Framework-agnostic health checks with integrations for the most popular ASGI frameworks: FastAPI / FastStream / Litestar to help you implement the Health Check API pattern
pip install fast-healthchecks (or poetry add / uv add). Backends and framework integrations are optional extras. See documentation → Installation for all options and extra names.
FastAPI
from fastapi import FastAPI
from fast_healthchecks import Probe
from fast_healthchecks.integrations.fastapi import HealthcheckRouter
app = FastAPI()
app.include_router(HealthcheckRouter(Probe(checks=[...])))FastStream / Litestar
from fast_healthchecks import Probe
from fast_healthchecks.integrations.faststream import health
# or: from fast_healthchecks.integrations.litestar import health
routes = health(Probe(checks=[...]))Usage depends on the framework (FastAPI: HealthcheckRouter; FastStream / Litestar: health() from the corresponding integration). Full examples, configuration, lifecycle and shutdown, URL/SSRF, and DSN formats are in the documentation. Example projects: FastAPI, FastStream, Litestar.
- Configuration, shutdown, probe options: documentation.
- Public API and
to_dict(): API Reference. - PostgreSQL TLS certificate rotation: DSN formats.
For fine-grained control over probe execution, use ProbeRunner as an async context manager:
from fast_healthchecks import Probe
from fast_healthchecks.execution import ProbeRunner, RunPolicy
probe = Probe(name="my-probe", checks=[...])
# Use context manager for automatic resource cleanup
async with ProbeRunner(
policy=RunPolicy(
mode="reporting",
execution="sequential",
probe_timeout_ms=5000, # 5 second timeout per probe
)
) as runner:
report = await runner.run(probe)
# Runner automatically closes probes on exitKey features:
- RunPolicy: Customize execution mode (
strict/reporting), timeout, and health evaluation - Automatic cleanup: Probes are closed when exiting the
async withblock - Reusable runner: Run multiple probes with the same policy
See documentation for details.
For the full list of recipes and their descriptions, run just or just --list (source of truth: justfile).
- Changelog: CHANGELOG.md in the repo; Changelog in the online docs.
- Architecture decisions: Decisions (ADR) in the online docs.
- Security: See SECURITY.md for how to report vulnerabilities.
git clone https://github.com/ZYLVEXT/fast-healthchecks.git
cd fast-healthchecks
uv sync --group=dev --group=docs --all-extrasjust lint- Import tests:
just tests-imports— verifies ImportError messages when optional deps are missing; runs with minimal install (uv sync --group=devonly, no extras). - Unit tests:
just tests-unit— runs pytest with-m unit. Expects dev deps and optional extras already installed (e.g. afteruv sync --group=dev --all-extrasor afterjust tests-integration). FastStream unit tests useTestKafkaBroker(connect_only=True)andTestAppso no real Kafka is required. - Integration tests:
just tests-integration— requires Docker anddocker compose; brings services up, runs integration tests, then brings them down. SetDOCKER_SERVICES_UP=1to skip compose up/down when services are already running. - Full suite:
just tests-all— runs import tests, then integration (compose up, pytest integration, compose down), then unit tests. Requires Docker.
Certificates in tests/certs/ are for tests only; see CONTRIBUTING § Test certificates.
CI runs pre-commit, import tests, and unit tests on push/PR; integration tests run only on manual workflow dispatch or schedule.
just serve-docsBump, rollback, workflows, secrets, pre-commit, and dependency updates: see CONTRIBUTING § CI and release and the workflows table there. Quick links: Bump version, Rollback release.
This project is licensed under the terms of the MIT license.