Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var BootPrintln = func(v ...any) {}
BootPrintln can be replaced with log.Println for printing debug information.
var EnvMap = map[Environment][]string{ EnvProduction: []string{"production"}, EnvStaging: []string{"staging"}, EnvDevelopment: []string{"development"}, EnvTest: []string{"test"}, }
EnvMap gives mappings of strings to specific environments.
var EnvVarName = "NAGA_ENV"
EnvVarName is the name of environment variable which contains the app environment. Defaults to NAGA_ENV.
Functions ¶
Types ¶
type Command ¶
type Command struct {
Keyword string
Run func(*CommandContext)
ShortUsage string
Usage string
Flags []*Flag
}
Command represents a command-line keyword for the app. This is then typically invoked as follows:
./myapp <keyword>
type CommandContext ¶
type CommandContext struct {
Args []string
Flags map[string]*Flag
// contains filtered or unexported fields
}
CommandContext is passed to the command when it is run, containing an array of parsed arguments.
func (*CommandContext) Fatal ¶
func (c *CommandContext) Fatal(format string, args ...any)
func (*CommandContext) RequireAtLeastNArgs ¶
func (c *CommandContext) RequireAtLeastNArgs(n int)
RequireAtLeastNArgs is a helper function to ensure we have at least n args.
func (*CommandContext) RequireExactlyNArgs ¶
func (c *CommandContext) RequireExactlyNArgs(n int)
RequireExactlyNArgs is a helper function to ensure we have at exactly n args.
func (*CommandContext) UsageExit ¶
func (c *CommandContext) UsageExit()
UsageExit prints the usage for the executed command and exits.
type Config ¶
type Config struct {
// Setup is called regardless of the command, after initialization
// and before the command (e.g., before Start).
// Setup is executed in topological order sequentially (leaves first).
Setup func() error
// SetupTest is called after Setup and before Start (or command).
// Always called in tests.
SetupTest func()
// Start is invoked when the app is run with '<myapp> start', i.e.
// the start command. Start is run in goroutines, and is launched
// sequentially in topological order.
Start func()
// Stop is invoked when a ctrl-c signal is received. May not execute,
// e.g. if the app is kill-9ed. A maximum of 30 seconds is given
// for all Stop functions to finish. Stop is invoked sequentially
// in reverse topological order (parents first).
Stop func()
// contains filtered or unexported fields
}
Config contains functions for handling a Module's lifecycle. Each Module is responsible for setting up its Config object when its Init method is called (which can happen in any order). When a command is run, Setup is always called. If the command is the start command, Config.Start is also invoked.
func (*Config) AddCommand ¶
AddCommand adds a command to the service via its Config.
func (*Config) SetDefaultCommand ¶
SetDefaultCommand sets the given command to be the default when the app is started without a command.
type Environment ¶
type Environment int
Environment can be configured with the NAGA_ENV environment variable. This defaults to EnvUnknown if not otherwise set.s
const ( EnvProduction Environment = iota EnvStaging EnvDevelopment EnvTest EnvUnknown )
Environment constants
func GetEnvironment ¶
func GetEnvironment() Environment
GetEnvironment returns the app environment parsed from the environment variable.
func (Environment) IsDevelopment ¶
func (e Environment) IsDevelopment() bool
IsDevelopment returns true iff env is development.
func (Environment) IsHosted ¶
func (e Environment) IsHosted() bool
IsHosted returns true if env if prod or staging
func (Environment) IsProduction ¶
func (e Environment) IsProduction() bool
IsProduction returns true iff env is production.
func (Environment) String ¶
func (e Environment) String() string
type Module ¶
type Module interface {
Init(*Config)
}
A Module registers lifecycle hooks via the Config parameter of the Init method it must implement. A Module may depend on other Modules by declaring them as fields (pointers to other Modules). See Config for more information about the lifecycle hooks and the order in which they are executed. Within a Service, Modules are singletons.
type Service ¶
type Service[App Module] struct { Env Environment // contains filtered or unexported fields }
A Service wraps a Module (and its dependencies). It manages the lifecycle and allows the Module to be started and stopped. It maintains a topologically sorted list of the Modules, along with a map of the Modules' Configs and a map of registered commands.
func NewApp ¶
NewApp creates a new app with Module m as the entry point. Unlike New, `start` is not automatically registered.
func (*Service[M]) Run ¶
func (s *Service[M]) Run()
Run parses arguments from the command line and passes them to RunCommand.
func (*Service[M]) RunCommand ¶
RunCommand executes the given command, or returns an error if not found. module setup (and setupTest) will be called recursively before executing the command via cmd.Run. Meant for tests.
func (*Service[App]) Start ¶
Start is a convenience method equivalent to `service.Load(m).Run()` and starting the app with `./<myapp> start`. Prefer using `Run()` as it is more flexible.
func (*Service[App]) StartForTest ¶
func (s *Service[App]) StartForTest() (App, func())
StartForTest starts the app with the environment set to test. Returns the started module and stop function as a convenience.
Source Files