copper

README

Note

Under active development

Documentation

Overview

Package copper encapsulates everything you need to build apps quickly

Index

• Variables
• type App
  • func InitApp() (*App, error)
  • func NewApp(lifecycle *Lifecycle, config cconfig.Config, logger clogger.Logger) *App
  • func (a *App) Run(fns ...Runner)
  • func (a *App) Start(fns ...Runner)
• type Flags
  • func NewFlags() *Flags
• type Lifecycle
  • func NewLifecycle(logger clogger.Logger) *Lifecycle
  • func (lc *Lifecycle) OnStop(fn func(ctx context.Context) error)
  • func (lc *Lifecycle) Stop()
• type Runner

Variables

var WireModule = wire.NewSet(wire.FieldsOf(new(*App), "Lifecycle", "Config", "Logger"))

WireModule can be used as part of google/wire setup to include the app's lifecycle, config, and logger.

Types

type App

type App struct {
	Lifecycle *Lifecycle
	Config    cconfig.Config
	Logger    clogger.Logger
}

App defines a Copper app container that can run provided code in its managed lifecycle. It provides functionality to read config in multiple environments as defined by command-line flags.

func InitApp

func InitApp() (*App, error)

InitApp creates a new Copper app along with its dependencies.

func NewApp

func NewApp(lifecycle *Lifecycle, config cconfig.Config, logger clogger.Logger) *App

NewApp creates a new Copper app and returns it along with the app's lifecycle manager, config, and the logger.

func (*App) Run

func (a *App) Run(fns ...Runner)

Run runs the provided funcs. Once all of the functions complete their run, the lifecycle's stop funcs are also called. If any of the fns return an error, the app exits with an exit code 1. Run should be used when none of the fn are blocking. For blocking funcs like a long running server, use Start.

func (*App) Start

func (a *App) Start(fns ...Runner)

Start runs the provided fns where the last provided fn be blocking like a long running server. The app listens on the OS's INT and TERM signals from the user to exit. Once the signal is received, the lifecycle's stop funcs are called. If any of the fns fail to run and returns an error, the app exits with exit code 1. If none of the fns are blocking, use Run instead.

type Flags

type Flags struct {
	Env        cconfig.Env
	ConfigDir  cconfig.Dir
	ProjectDir cconfig.ProjectDir
}

Flags holds flag values passed in via command line. These can be used to configure the app environment and override the config directory.

func NewFlags

func NewFlags() *Flags

NewFlags reads the command line flags and returns Flags with the values set.

type Lifecycle

type Lifecycle struct {
	// contains filtered or unexported fields
}

Lifecycle represents the lifecycle of an app. Most importantly, it allows various parts of the app to register stop funcs that are run before the app exits. Packages such as chttp use Lifecycle to gracefully stop the HTTP server before the app exits.

func NewLifecycle

func NewLifecycle(logger clogger.Logger) *Lifecycle

NewLifecycle instantiates and returns a new Lifecycle that can be used with New to create a Copper app.

func (*Lifecycle) OnStop

func (lc *Lifecycle) OnStop(fn func(ctx context.Context) error)

OnStop registers the provided fn to run before the app exits. The fn is given a context with a deadline. Once the deadline expires, the app may exit forcefully.

func (*Lifecycle) Stop

func (lc *Lifecycle) Stop()

Stop runs all of the registered stop funcs in order along with a context with a configured timeout.

type Runner

type Runner interface {
	Run() error
}

Runner provides an interface that can be run by a Copper app using the Run or Start funcs. This interface is implemented by various packages within Copper including chttp.Server.