health

Package health serves liveness and readiness endpoints.

Liveness (/livez) only reports that the process is serving requests; it never checks dependencies, so a database outage doesn't restart every instance. Readiness (/readyz) runs registered checks and fails while the application is shutting down, so load balancers stop routing to it (ADR-0017).

Stability: pre-1.0 (ADR-0015).

Constants#

const DefaultTimeout#

const DefaultTimeout = 2 * time.Second

DefaultTimeout applies to checks with no timeout.

Types#

type Check#

type Check struct {
	Name    string
	Timeout time.Duration
	Func    func(ctx context.Context) error
}

A Check verifies one dependency. Func must respect ctx.

type CheckStatus#

type CheckStatus struct {
	Status     string `json:"status"`
	DurationMS int64  `json:"duration_ms"`
}

CheckStatus is one check's result. Error details are logged, not returned, so dependency hostnames and messages don't leak.

type Checker#

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

Checker holds readiness checks and shutdown state. It is safe for concurrent use.

func New#

func New(logger *slog.Logger, checks ...Check) *Checker

New returns a Checker. A nil logger discards check failures.

func (*Checker) Add#

func (c *Checker) Add(check Check)

Add registers a readiness check.

func (*Checker) Check#

func (c *Checker) Check(ctx context.Context) (Status, bool)

Check runs every check and reports whether all passed.

func (*Checker) Liveness#

func (c *Checker) Liveness() http.Handler

Liveness serves 200 {"status":"ok"} while the process can handle requests.

func (*Checker) Readiness#

func (c *Checker) Readiness() http.Handler

Readiness runs every check concurrently and serves 200 when all pass, 503 otherwise, or 503 {"status":"shutting_down"} after Checker.SetShuttingDown.

func (*Checker) SetShuttingDown#

func (c *Checker) SetShuttingDown()

SetShuttingDown makes readiness fail from now on. Pass it to app.OnShutdown.

type Status#

type Status struct {
	Status string                 `json:"status"`
	Checks map[string]CheckStatus `json:"checks,omitempty"`
}

Status is the readiness response body.