goboot

README

goboot

WARNING: This repo not intended for public use and has no versioning applied. So be warned: things can break between commits. This project will have long periods of non-activity with short bursts of high activity based on my schedule. Meaning: don't count on my support.

goboot instantiates an application environment for web services. Its main purpose is to create an opinionated base for REST and gRPC apps.

Goals:

• Easy and consistent service bootstrapping of common services (databases, queues, etc).
• Panic if bootstrapping a service failed. We don't want to start a broken server.
• Good logging and error reporting while bootstrapping. Debugging broken boot procedures on infra can be a pain...
• Avoid framework-like dependencies in goboot such as web frameworks or routers.

Non-goals:

• The services in this package are not an abstraction of underlying libraries but only aid in bootstrapping or simplify using them.
• No need for flexibility of underlying drivers. Being tied to one specific version of a lib and/or datastore is OK.

Given these goals & non-goals you'll find this codebase is strongly tied to:

• Viper for configuration management;
• Zerolog for logging;
• all packages (elasticsearch, postgres, pubsub, redis) have third-party dependencies and may only work for a specific version of db/protocol.

It's quite likely the set of chosen libraries here would not fit your project's needs or personal preferences.

Development

This codebase contains integration tests that depend on real databases.

Ensure databases are running:

$ docker compose up

And in a different tab:

$ make test

# or if you have richgo installed run:
$ make humantest

This requires richgo to be installed.

See the project's Makefile for other (more standard) commands.

Documentation

Index

• func LoadConfig(log zerolog.Logger, dir string, env string) (*viper.Viper, error)
• func SetGlobalLogLevel(level string)
• type AppEnv
  • func NewAppEnv(confDir string, env string) *AppEnv
  • func (ctx *AppEnv) AddService(service AppService)
  • func (ctx *AppEnv) Close()
  • func (ctx *AppEnv) Configure()
  • func (ctx *AppEnv) Init()
• type AppService

Functions

func LoadConfig

func LoadConfig(log zerolog.Logger, dir string, env string) (*viper.Viper, error)

LoadConfig reads in configuration files and environment variables in the following order of priority:

1. environment variables (optional) 2. {path}/config.{env}.yaml (optional, but logs a warning if missing) 3. {path}/config.yaml (mandatory)

An config variable "var.sub_2: value" can be overwritten with an environment variable VAR_SUB_2.

func SetGlobalLogLevel

func SetGlobalLogLevel(level string)

SetGlobalLogLevel updates the log level, panics if log level is unknown.

Types

type AppEnv

type AppEnv struct {
	Config   *viper.Viper
	Log      zerolog.Logger
	ConfDir  string
	Services []AppService
}

AppEnv contains all application-scoped variables.

func NewAppEnv

func NewAppEnv(confDir string, env string) *AppEnv

NewAppEnv creates an AppEnv by loading configuration settings.

Panics if configuration failed to load.

func (*AppEnv) AddService

func (ctx *AppEnv) AddService(service AppService)

func (*AppEnv) Close

func (ctx *AppEnv) Close()

Close cleans up any resources held by any app services.

func (*AppEnv) Configure

func (ctx *AppEnv) Configure()

Configure sets up service settings.

func (*AppEnv) Init

func (ctx *AppEnv) Init()

Init runs all app service initialization.

type AppService

type AppService interface {
	// Configure is run when a new app context is created. Use this to load
	// configuration settings.
	//
	// Any error will cause a panic. The app waits for all services to be
	// configured before calling Init.
	Configure(env *AppEnv) error

	// Init is run after all services have been configured. Use this to run
	// setup that is dependent on other services.
	//
	// Any error will cause a panic. The app starts after all initializations
	// are finished.
	Init() error

	// Close is run right before shutdown. The app waits until close resolves.
	//
	// Any returned error is logged but will not cause a panic or exit.
	Close() error

	// Name returns the name of the service used for logging purposes.
	Name() string
}

AppService instantiates a singleton application service that is created on application boot and shutdown gracefully on application termination.