Documentation
¶
Overview ¶
Package health provides a small abstraction for dependency probes used by the /healthz handler in pkg/app. Each subsystem (DB, Redis, object storage, etc.) exposes a Prober that the handler aggregates into the JSON response.
The package exists so pkg/app stays free of direct dependencies on driver-specific libraries (e.g. github.com/redis/go-redis/v9), which the project firewall rules prefer to keep wrapped.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SupportsMailProbe ¶
SupportsMailProbe reports whether the given Sender implements the optional mail.HealthChecker contract.
Types ¶
type DBHealther ¶
DBHealther is the minimum surface a SQL-database handle must expose to be probed by NewDBProbe. *pkg/db.DB satisfies this interface natively.
type Prober ¶
type Prober interface {
// Name is the identifier surfaced in the /healthz response, e.g.
// "db:default" or "redis". Stable across releases — operators key
// alerts off these strings.
Name() string
// Probe runs the dependency check. Implementations should keep the
// operation cheap and non-destructive (PING, HEAD, LIST with limit 1).
Probe(ctx context.Context) error
}
Prober describes a single dependency that can be probed for health. Probe should return nil when the dependency is reachable and usable, or a non-nil error explaining the failure. Implementations must respect the deadline carried by ctx.
func FuncProbe ¶
FuncProbe adapts a bare health function into a Prober. It is the bridge for probes that are not framework-owned dependencies — e.g. the framework registers one per ServiceRegistration.Health under the name "service:<name>". The function must respect ctx's deadline.
func NewDBProbe ¶
func NewDBProbe(name string, h DBHealther) Prober
NewDBProbe wraps a database handle into a Prober. The probe surfaces the alias in the result name (e.g. "db:default"), so the handler can report per-alias status in multi-database deployments.
func NewMailProbe ¶
NewMailProbe builds a Prober that exercises a mail.Sender's optional health check. The sender must implement mail.HealthChecker; callers should type-assert before calling NewMailProbe, and skip registration if the assertion fails — there is intentionally no silent fallback so the /healthz response never includes a information-free "skipped" row.
SupportsMailProbe is exposed as a convenience wrapper around the type-assertion check so callers can keep the conditional outside this package.
func NewRedisProbe ¶
NewRedisProbe builds a Prober that PINGs a Redis server on Probe().
The URL is parsed eagerly; if it is empty or malformed, the returned Prober reports unhealthy on every Probe call instead of refusing to construct. This keeps the operator-facing failure mode uniform — the /healthz body always lists the probe and shows the reason — and avoids App.New having to decide between several silent failure paths at startup.
Each probe call lazily creates a short-lived client and closes it after PING. That matches the cadence of liveness probes (every 10–30 s in Kubernetes) and avoids holding a long-lived connection pool just for health checks.
func NewStorageProbe ¶
NewStorageProbe builds a Prober that exercises a storage.Store with a trivial, non-destructive List call. The probe asks for at most one object under a sentinel prefix so it never touches real tenant data nor pays per-request egress for content download.
The default sentinel prefix is `_nucleus_healthz/`. It is unlikely to collide with real keys; if a deployment does happen to use that prefix, the probe still works — List returns whatever exists or an empty result and either is treated as healthy by the underlying provider call succeeding.
type Result ¶
Result is the outcome of one probe run.
func Run ¶
Run executes every probe in probes with the given per-probe timeout budget and returns the results in the same order. Probes run concurrently; total wall time is bounded by the slowest probe rather than the sum.
A zero or negative timeout disables the per-probe deadline; callers remain responsible for parent-context cancellation.
Source Files