platform

package
v0.10.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Index

Constants

View Source
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.

View Source
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 Get

func Get[T any](a *App) T

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 Lookup

func Lookup[T any](a *App) (T, bool)

Lookup returns the value of type T and reports whether it is present.

func Provide

func Provide[T any](a *App, v T)

Provide stores a value in the container under its own type, replacing any previous one.

func Run

func Run(cfg Config, modules []Module, wire Wire) error

Run starts the modules and blocks until SIGINT or SIGTERM.

func RunContext

func RunContext(ctx context.Context, cfg Config, modules []Module, wire Wire) error

RunContext behaves like Run but stops when ctx is done. Tests use it.

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

func NewApp(log *slog.Logger) *App

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

func (a *App) AddHealthCheck(name string, check func(context.Context) error)

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

func (a *App) AliasMetric(name, alias string)

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

func (a *App) DeclareAlerts(kinds ...string)

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

func (a *App) Logger() *slog.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

func (a *App) OpenMetrics() bool

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.

func (*App) Role added in v0.2.2

func (a *App) Role() string

Role returns what this process does: all, api or worker.

func (*App) Serves added in v0.2.2

func (a *App) Serves(role string) bool

Serves reports whether this process takes the given role: a process in role all takes every role. A module that serves requests checks api, one that works jobs checks worker.

func (*App) Service

func (a *App) Service() string

Service returns the service name. Modules put it in page titles and messages.

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

type HealthChecker interface {
	Health(ctx context.Context) error
}

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

type PhasedStopper interface {
	Stopper
	StopPhases() []StopPhase
}

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

type Starter interface {
	Start(ctx context.Context) error
}

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.

type Stopper

type Stopper interface {
	Stop(ctx context.Context) error
}

Stopper releases resources. Modules are stopped in reverse order of initialisation, sharing one shutdown timeout.

type Wire

type Wire func(app *App) error

Wire builds the project domain: use cases, handlers, workers. It runs between Init and Start of every module, so queues and servers begin work with handlers in place.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL