Fundamentals on Humus

The App lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Every humus application is a bedrock.App, and the root package’s humus.App is the lifecycle every humus service runs. It reads its settings, listens for signals, builds its telemetry and the user’s dependencies, runs one or more Services, drains and shuts them down within a grace period, releases what was built, shuts its telemetry down and turns the outcome into an exit status.

A service’s main is func main() { humus.Main(app.Init) }, where app.Init is the end user’s Init. humus.Main builds the humus.App from its defaults and that Init, applies the options it is given, and runs the App on the OS process. Options change the App’s fields, so everything this page says about humus.App is what Main runs. The runtime packages — REST, gRPC, jobs, queues — export Services for Init to return, not Apps, and one whose Services need a drain wraps Main with defaults of its own: see Runtime packages. An App that mixes runtimes, such as a REST API and a gRPC service in one process, needs nothing more.

Configuring a humus service

Mon, 01 Jan 0001 00:00:00 +0000

humus packages are configured with plain Go values. They read no environment variables for their settings, define no variable names and read no files on your behalf; the few variables humus does read are listed below. Every value is sourced in your own Init, with whatever names and formats your service already uses: an environment variable called READ_TIMEOUT or MYSVC_HTTP_READ_TIMEOUT, a duration written 5s, a file of PEM, a flag. The usual tool is bedrock’s config package, and this page uses it throughout.

Telemetry

Mon, 01 Jan 0001 00:00:00 +0000

A humus App builds its OpenTelemetry providers before Init, hands them to Init as one value, logs through them, and shuts them down last. The telemetry package builds them from a plain Settings value. humus.Main builds them from telemetry.DefaultSettings() unless the service passes a Builder of its own, which sources that value the same way Init sources any other package’s settings.

The design behind everything on this page is in Proposal: OpenTelemetry without globals, Revision 2. The lifecycle describes when the App builds its telemetry and shuts it down.

Health

Mon, 01 Jan 0001 00:00:00 +0000

A service reports its health as monitors it combines into two probes, liveness and readiness, and an App’s readiness is owned by a health Service it returns from Init like any other Service. All of it is in the health package, which depends on nothing but the standard library and serves no protocol. httphealth and grpc/grpchealth expose the probes to Kubernetes.

The design behind this page is in Proposal: health monitors and probes, Revision 2, and, for exposing the probes, in Proposal: exposing health probes.

Testing a humus App

Mon, 01 Jan 0001 00:00:00 +0000

A humus App runs whole inside a test. humustest makes that possible:

humustest.Start hands the end user’s Init to the App that humus.Main would run for it, with the same defaults, on a test Host in place of humus.OSHost() and on a new process from bedrocktest: its arguments, environment and stdin, which the test sets, its output, which the test reads, and its signals, which the test sends. It returns the process and a channel for the App’s exit status.
a Host, whose in-memory network the App listens on and the test dials, and whose filesystem is confined to the test’s own temp directory;
a certificate authority, NewCA, generated for each test;
Telemetry, a recorder of what an App emits, covered on the Telemetry page;
and TestService, the contract every Service must pass.

The network opens no real socket and starts no goroutines, so the App runs in a testing/synctest bubble. It needs no real environment, no real time and no file outside the test’s temp directory.