fast-healthchecks 1.0.0

Fast Healthchecks

Fast Healthchecks

Framework-agnostic health checks with integrations for the most popular ASGI frameworks: FastAPI / FastStream / Litestar to help you implement the Health Check API pattern

---

---

Installation

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.

Quick Start

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.

Probe Runner (Advanced)

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 exit

Key features:

• RunPolicy: Customize execution mode (strict/reporting), timeout, and health evaluation
• Automatic cleanup: Probes are closed when exiting the async with block
• Reusable runner: Run multiple probes with the same policy

See documentation for details.

Development

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.

Setup environment

git clone https://github.com/ZYLVEXT/fast-healthchecks.git
cd fast-healthchecks
uv sync --group=dev --group=docs --all-extras

Run linters

just lint

Running tests

• Import tests: just tests-imports — verifies ImportError messages when optional deps are missing; runs with minimal install (uv sync --group=dev only, no extras).
• Unit tests: just tests-unit — runs pytest with -m unit. Expects dev deps and optional extras already installed (e.g. after uv sync --group=dev --all-extras or after just tests-integration). FastStream unit tests use TestKafkaBroker(connect_only=True) and TestApp so no real Kafka is required.
• Integration tests: just tests-integration — requires Docker and docker compose; brings services up, runs integration tests, then brings them down. Set DOCKER_SERVICES_UP=1 to 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.

Serve documentation

just serve-docs

Release and CI (maintainers)

Bump, rollback, workflows, secrets, pre-commit, and dependency updates: see CONTRIBUTING § CI and release and the workflows table there. Quick links: Bump version, Rollback release.

Known alternatives

• FastAPI Health
• FastAPI Health Monitor
• fastapi_healthz
• fastapi_healthcheck

License

This project is licensed under the terms of the MIT license.