goarc

README

Idiomatic Go Applications Framework

The goarc is an idiomatic Go applications framework that focuses on application Life-Cycle.

Installation

Simply add the following import to your code, and then go [build|run|test] will automatically fetch the necessary dependencies:

import "github.com/lnashier/goarc"

Examples

Examples

Toy HTTP Example

package main

import (
	"github.com/lnashier/goarc"
	goarchttp "github.com/lnashier/goarc/http"
	xhttp "github.com/lnashier/goarc/x/http"
	"net/http"
	"time"
)

func main() {
	goarc.Up(goarchttp.NewService(
		goarchttp.ServiceName("toy"),
		goarchttp.ServicePort(8080),
		goarchttp.ServiceShutdownGracetime(2*time.Second),
		goarchttp.App(func(srv *goarchttp.Service) error {

			// BYO http.Handler
			srv.Register("/toys/byo", http.MethodGet, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
				w.WriteHeader(http.StatusOK)
				w.Write([]byte("Hello World!"))
			}))

			// Use pre-assembled http.Handler to work with JSON response type
			srv.Register("/toys/json", http.MethodGet, xhttp.JSONHandler(func(r *http.Request) (any, error) {
				return []string{"Hello World!"}, nil
			}))

			// Use pre-assembled http.Handler to work with TEXT response type
			srv.Register("/toys/text", http.MethodGet, xhttp.TextHandler(func(r *http.Request) (string, error) {
				return "Hello World!", nil
			}))

			return nil
		}),
	))
}

Toy CLI Example

package main

import (
	"context"
	"errors"
	"fmt"
	"github.com/lnashier/goarc"
	goarccli "github.com/lnashier/goarc/cli"
	xtime "github.com/lnashier/goarc/x/time"
	"time"
)

func main() {
	goarc.Up(goarccli.NewService(
		goarccli.ServiceName("mockcli"),
		goarccli.App(
			func(svc *goarccli.Service) error {
				svc.Register("echo", func(ctx context.Context, args []string) error {
					xtime.SleepWithContext(ctx, time.Duration(10)*time.Second)

					if len(args) > 0 {
						fmt.Println(args[0])
						return nil
					}

					return errors.New("nothing to echo")
				})

				return nil
			},
		),
	))
}

Documentation

Index

• func Up(s Service, opt ...BootOpt)
• type BootOpt
  • func Context(ctx context.Context) BootOpt
  • func OnStart(f func(error)) BootOpt
  • func OnStop(f func(error)) BootOpt
• type Service
• type ServiceFunc
  • func (s ServiceFunc) Start() error
  • func (s ServiceFunc) Stop() error

Functions

func Up

func Up(s Service, opt ...BootOpt)

Up manages the lifecycle of a service. It blocks until the service shuts down or the service.Start() method returns. It listens to specific signals and gracefully shut down the service when any of these signals are received:

syscall.SIGINT
syscall.SIGTERM
syscall.SIGQUIT
syscall.SIGABRT

It exits with a non-zero status code if an error occurs during either the startup or shutdown process.

Types

type BootOpt

type BootOpt func(*bootOpts)

func Context

func Context(ctx context.Context) BootOpt

func OnStart

func OnStart(f func(error)) BootOpt

func OnStop

func OnStop(f func(error)) BootOpt

type Service

type Service interface {
	// Start should initiate the startup of the service.
	// It returns an error if the startup process encounters any issues.
	Start() error

	// Stop should initiate the shutdown of the service.
	// It returns an error if the shutdown process encounters any issues.
	Stop() error
}

Service represents a generic service that goarc framework can Start and Stop.

type ServiceFunc

type ServiceFunc func(bool) error

ServiceFunc serves as an adapter, enabling the utilization of regular functions as goarc services. If f is a function with the correct signature, ServiceFunc(f) creates a Service that invokes f. The function f receives a boolean parameter indicating whether it's invoked as Start (true) or Stop (false).

func (ServiceFunc) Start

func (s ServiceFunc) Start() error

Start calls f(true).

func (ServiceFunc) Stop

func (s ServiceFunc) Stop() error

Stop calls f(false).