goforarun

README

GoForARun

Simple package to help bootstrapping projects.

Features

• Run a service easily, just need to have an Init(), Run(), and Shutdown() methods.
• Configuration via config.yaml file to configure your service.
• Build info with version, commit, and date. (GoReleaser friendly)
• Observability with OpenTelemetry.
• Provided with HTTP and GRPC servers. (see /examples)

Getting started

Run to create a project:

$ go run github.com/davfer/goforarun/cmd/create@v0.0.6 <project_name>
$ cd <project_name>
$ go mod init <project_name>
$ go get github.com/davfer/goforarun
$ go run .

Use the package directly:

go get github.com/davfer/goforarun

Usage

Your application will need to implement the App interface, like:

// config.go
type ExampleConfig struct {
    FrameworkConfig *app.BaseAppConfig `yaml:"framework"` 
    // Extend your config here
}

func (c *ExampleConfig) Framework() *app.BaseAppConfig {
    return c.FrameworkConfig
}

// service.go
type ExampleService struct {
	cfg *ExampleConfig
	// Add your dependencies here
}

func (e *ExampleService) Init(cfg *ExampleConfig) ([]app.RunnableServer, error) {
	e.cfg = cfg
	// Add your servers and also initialize your dependencies here
	return []app.RunnableServer{}, nil
}

func (e *ExampleService) Run(ctx context.Context) error {
	// Run your application here if needed
	fmt.Printf("Hello, %s!\n", e.cfg.Framework().ServiceName)

	return nil
}

func (e *ExampleService) Shutdown(ctx context.Context) error {
	// Shutdown your application here if needed, no need to shut down your servers
	return nil
}

Then, create a main.go file like:

// main.go
var (
	version = "dev"
	commit  = "none"
	date    = "unknown"
)

func main() {
	build := &app.BuildInfo{Version: version, Commit: commit, Date: date}
	if svc, err := app.NewService[*ExampleService, *ExampleConfig](&ExampleService{}, build); err != nil {
		panic(err)
	} else {
		svc.Run(context.Background())
	}
}

Documentation

Index

• Constants
• Variables
• func NewConfig[K any](configPath string) (K, error)
• type App
• type BaseAppConfig
  • func (c *BaseAppConfig) ServiceVersionedName() string
• type BaseService
• type BuildInfo
• type Config
• type InfoServer
• type LoggingConfig
• type RunnableServer
• type Service
  • func NewService[K App[V], V Config](app K, buildInfo *BuildInfo) (*Service[K, V], error)
  • func (s *Service[K, V]) Run(ctx context.Context)

Constants

const AppLoggerName = "gofar"

Variables

var ErrGracefulShutdown = errors.New("graceful shutdown")

Functions

func NewConfig

func NewConfig[K any](configPath string) (K, error)

NewConfig creates a new configuration from a file path

Types

type App

type App[V any] interface {
	Init(cfg V) ([]RunnableServer, error)
	Run(ctx context.Context) error
	Shutdown(ctx context.Context) error
}

type BaseAppConfig

type BaseAppConfig struct {
	// ServiceName is the identifier of the service
	ServiceName string `yaml:"service_name"`
	// LoggingConfig is the configuration of the logs
	LoggingConfig LoggingConfig `yaml:"logs"`
	// BuildInfo is the information of the build. Useful to identify running process for observability.
	BuildInfo *BuildInfo
}

BaseAppConfig is the base configuration for the service, it needs a name, a log level, a log format, and an observability mode.

func (*BaseAppConfig) ServiceVersionedName

func (c *BaseAppConfig) ServiceVersionedName() string

ServiceVersionedName returns the service name with the version if it exists, useful to group equal running services

type BaseService

type BaseService[V any] struct {
	Cfg V
}

type BuildInfo

type BuildInfo struct {
	Version string
	Commit  string
	Date    string
}

BuildInfo is the information of the build, it contains the version, the commit and the date.

type Config

type Config interface {
	Framework() *BaseAppConfig
}

type InfoServer

type InfoServer struct {
	Net  string
	Host string
	Port string
	Name string
}

InfoServer contains the information of a server to be started.

type LoggingConfig

type LoggingConfig struct {
	// Level is the log level (debug, info, warn, error, fatal, panic)
	Level string `yaml:"level"`
	// Format is the log format (text, json)
	Format string `yaml:"format"`
	// Output is the log output (stdout, stderr, file)
	Output string `yaml:"output"`
	// FilteredChannels is the list of channels to filter [channel: level]
	FilteredChannels map[string]string `yaml:"filtered_channels"`
}

type RunnableServer

type RunnableServer interface {
	Info() *InfoServer // TODO: Probably not needed
	Run(context.Context) error
	Shutdown(context.Context) error
}

type Service

type Service[K App[V], V Config] struct {
	BaseService[V]
	// contains filtered or unexported fields
}

func NewService

func NewService[K App[V], V Config](app K, buildInfo *BuildInfo) (*Service[K, V], error)

NewService creates a new service with the given app and config. This is the main and only entry point for the GoForARun framework.

func (*Service[K, V]) Run

func (s *Service[K, V]) Run(ctx context.Context)

Run starts the service and blocks until it receives a SIGINT or the app crashes. If the app Run method returns an error, the service will log it and exit.