Documentation
¶
Index ¶
- Constants
- func Degraded(err error) error
- func Get[T any](a *App) T
- func IsDegraded(err error) bool
- func Lookup[T any](a *App) (T, bool)
- func Provide[T any](a *App, v T)
- func Run(cfg Config, modules []Module, wire Wire) error
- func RunContext(ctx context.Context, cfg Config, modules []Module, wire Wire) error
- type App
- func (a *App) AddHealthCheck(name string, check func(context.Context) error)
- func (a *App) AliasMetric(name, alias string)
- func (a *App) DeclareAlerts(kinds ...string)
- func (a *App) Logger() *slog.Logger
- func (a *App) Metrics() *prometheus.Registry
- func (a *App) OpenMetrics() bool
- func (a *App) Role() string
- func (a *App) Serves(role string) bool
- func (a *App) Service() string
- type Config
- type HealthChecker
- type Module
- type PhasedStopper
- type Starter
- type StopPhase
- type Stopper
- type Wire
Constants ¶
const ( PhaseHTTP = 100 PhaseQueue = 200 PhaseGRPC = 300 )
Shutdown phases a module can place its steps in. With phased shutdown on (SHUTDOWN_PHASES), steps run in this order across all modules, as in taply: the HTTP servers stop taking requests first, the job queue drains next while gRPC clients are still served, and gRPC goes last. Any number in between orders a step of its own.
const ( RoleAll = "all" RoleAPI = "api" RoleWorker = "worker" )
Roles a process can run in. One binary serves them all: an API instance and a worker instance differ only in APP_ROLE.
Variables ¶
This section is empty.
Functions ¶
func Degraded ¶ added in v0.11.2
Degraded marks a health check failure of a part the instance can work without, such as optional storage: /health reports the check as "degraded: <error>" and the whole response as "degraded" with status 200, not 503, so a probe does not take the instance out or restart it. A nil error stays nil.
func Get ¶
Get returns the value of type T and panics when it is missing.
Panicking is right here: a missing dependency is a wiring mistake, and it shows up on the first run rather than in production under load.
func IsDegraded ¶ added in v0.11.2
IsDegraded reports whether err, or an error it wraps, came from Degraded.
func Provide ¶
Provide stores a value in the container under its own type, replacing any previous one.
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
App is the application container: logger, metrics, health checks and the values modules share with each other.
Modules find each other through the container instead of through edits in main.go, which is why adding or removing a module needs no manual changes in project code.
func NewApp ¶
NewApp creates a container without running modules. Tests and platform tooling use it when the full lifecycle is not needed. The logger may be nil.
func (*App) AddHealthCheck ¶
AddHealthCheck registers a check for /health. Modules need not call it: the platform adds a check for every module implementing HealthChecker.
func (*App) AliasMetric ¶ added in v0.9.0
AliasMetric serves the metric name under alias as well, with the same series and values, for as long as a service moves to the platform: the dashboards and alerts written for its old metric keep working while they are moved to the platform's name. Remove the alias once nothing reads the old name.
app.AliasMetric("api_deprecated_calls_total", "maas_deprecated_rpc_calls_total")
A metric may have several aliases. An alias is served only at /metrics and only while no real metric has the same name. A counter's alias ends in _total, like the counter.
func (*App) DeclareAlerts ¶ added in v0.5.7
DeclareAlerts starts the series of app_alerts_total at zero for the given kinds. increase() does not see the first sample of a new series, so without it the first alert of each kind after a restart would never fire. The project calls it with every kind it raises; a kind that is not declared is still counted.
func (*App) Logger ¶
Logger returns the application logger. Lines carrying logx.AlertKey are counted in app_alerts_total, whichever module or use case writes them.
func (*App) Metrics ¶
func (a *App) Metrics() *prometheus.Registry
Metrics returns the registry served at /metrics.
func (*App) OpenMetrics ¶ added in v0.9.0
OpenMetrics reports whether /metrics serves the OpenMetrics format (METRICS_OPENMETRICS), the one that carries exemplars. Modules attach trace ids as exemplars only then, so nothing changes for a service that has not asked for them.
type Config ¶
type Config struct {
Service string // service name in logs
Role string // what this process does: all, api or worker; all by default
OpsAddr string // ops server address, :9090 by default
ShutdownTimeout time.Duration // overall shutdown timeout, 20s by default
Logger *slog.Logger
// ShutdownPhases stops the modules by phase instead of in reverse order of
// initialisation: the HTTP servers, then the job queue, then gRPC, then every other
// module (see PhasedStopper). Off by default; SHUTDOWN_PHASES=true turns it on.
ShutdownPhases bool
// OpenMetrics serves /metrics in the OpenMetrics format to a scraper that asks for it,
// as Prometheus does; that format carries exemplars, the trace ids next to the call
// metrics of the api module. Off by default: the classic text format is served.
OpenMetrics bool
// OnStarted is called once every module and the ops server are up. Tests and local
// runs use it to learn the actual ops address.
OnStarted func(opsAddr string)
}
Config holds startup parameters. Empty fields fall back to defaults.
type HealthChecker ¶
HealthChecker adds the module to the /health response.
type Module ¶
type Module interface {
// Name identifies the module in logs, health output and errors.
Name() string
// Init prepares the module and puts whatever it shares into the container.
// Modules are initialised in the order they are listed.
Init(ctx context.Context, app *App) error
}
Module is an infrastructure part of the application: database, queues, API, admin UI.
Only Name and Init are required. Everything else is optional: the platform checks for Starter, Stopper and HealthChecker and calls them when implemented, so a module without background work stays a few lines long.
type PhasedStopper ¶ added in v0.9.0
PhasedStopper splits a module's shutdown into steps that phased shutdown interleaves with the steps of other modules. Its phases together must do what Stop does: without phased shutdown the platform calls Stop, with it only the phases.
Modules that are not PhasedStopper stop after every phase, in reverse order of initialisation, so the database outlives the servers and the queue that use it.
type Starter ¶
Starter runs background work: queue workers, servers, subscriptions. It is called after the domain is wired so that every handler is registered before traffic starts.
type StopPhase ¶ added in v0.9.0
type StopPhase struct {
Name string // shown in logs and errors: "http", "queue", "grpc"
Order int // PhaseHTTP, PhaseQueue, PhaseGRPC or a number between them
Stop func(ctx context.Context) error
}
StopPhase is one step of a module's shutdown.