Skip to content

Health

rn_forge.web.health

Run and aggregate readiness checks.

Exceptions and timeouts become failed checks. A failed required check makes the service unavailable; optional failures only degrade the aggregate status.

LEGACY_LIVENESS_PATH = '/healthz' module-attribute

Deprecated alias of :data:LIVENESS_PATH, kept for hosts still probing it.

LIVENESS_PATH = '/livez' module-attribute

Default liveness path (kubernetes.io "Kubernetes API health endpoints").

READINESS_PATH = '/readyz' module-attribute

Default readiness path.

Check = Callable[[], CheckResult | bool | Awaitable[CheckResult | bool]]

A named check: a zero-argument callable, sync or async, returning a result or a bool.

CheckStatus = Literal['pass', 'warn', 'fail', 'skipped']

The four outcomes a single check may report.

CheckResult

Bases: WireModel

One dependency's verdict.

HealthReport

Bases: WireModel

The aggregate of one readiness run.

http_status is the transport status to serve; it is not part of the body.

as_body()

Return status and checks without the transport status.

liveness_body()

Return the liveness body: {"status": "pass"}, served with 200.

Liveness runs no checks: it answers whether the process can serve a request at all.

run_checks(checks, *, required=(), timeout=None) async

Run checks concurrently and aggregate them.

Parameters:

Name Type Description Default
checks Mapping[str, Check]

Name → check. Sync and async checks may be mixed freely.

required
required Collection[str]

Names whose failure makes the service unavailable (503). A name not present in checks is ignored.

()
timeout float | None

Seconds each check may run before it is reported as fail. None (the default) waits indefinitely.

None

Returns:

Type Description
HealthReport

The aggregate report, including the HTTP status to serve.

run_checks_sync(checks, *, required=(), timeout=None)

Run checks concurrently on a shared pool of at most 32 workers.

All checks share one deadline. A check that finds the pool full fails immediately with not run: health check capacity exhausted. A timed-out check keeps running and holding its slot until its callable returns.

Parameters:

Name Type Description Default
checks Mapping[str, Check]

Name → check. Every check must be synchronous.

required
required Collection[str]

Names whose failure makes the service unavailable (503).

()
timeout float | None

Seconds for the shared deadline, after which unfinished checks are reported as fail. None waits indefinitely.

None

Returns:

Type Description
HealthReport

The aggregate report, including the HTTP status to serve.

Raises:

Type Description
WebError

A check returned an awaitable. It is raised, not reported as a failing check.