Scaffold Health Checks

---
name: scaffold-health-checks
description: >-
  Scaffold FastAPI/gRPC liveness, readiness, and startup health checks, graceful
  shutdown, and optional Kubernetes probes. Use for "health endpoint",
  "readiness/liveness probe", or "k8s probes".
---

# Scaffold ArchiPy Health Checks

## Read first

Read these plugin rules in full before generating files (paths relative to this skill directory; Claude Code: `${CLAUDE_SKILL_DIR}/../../rules/`):

- `../../rules/using-archipy-services.mdc`

## Before writing files

1. Inspect package/config, current transports, app lifecycle, dependency adapters, DI wiring, deployment manifests, and
   existing health endpoints.
2. Infer package name, transport, ports, and readiness dependencies from the repository.
3. Ask only for unresolved choices: dependencies to include, heartbeat deadlock detection, or Kubernetes YAML.
4. Preserve existing health routes and manifests; merge compatible additions instead of overwriting.

## Prefer ArchiPy

Health checks are app code. ArchiPy does not ship stock HTTP routes or a stock gRPC `Health` servicer.

**Probe semantics** (liveness vs readiness vs startup, K8s notes, common mistakes, FastAPI sketches): keep
`../archipy-docs/reference/health-checks.md` § Health checks as the source of truth — do not invent alternate probe meanings or
duplicate endpoint sketches here. Resolve `../...` paths relative to this `SKILL.md`'s directory in the plugin
installation — not the app workspace.

```bash
uv add "archipy[fastapi]"   # HTTP probes
uv add "archipy[grpc]"      # gRPC server + grpcio-health-checking
```

Prefer existing app bootstrap:

```python
from archipy.helpers.utils.app_utils import AppUtils
from archipy.configs.base_config import BaseConfig

# FastAPI
app = AppUtils.create_fastapi_app()
app.include_router(create_health_v1_router(container))

# gRPC (sync)
server = AppUtils.create_grpc_app(BaseConfig.global_config())
# register domain servicers, then health:
register_health_servicer(server, container)

# gRPC (async)
server = AppUtils.create_async_grpc_app(BaseConfig.global_config())
```

Do not hand-roll bare `FastAPI()` / `grpc.server()` when AppUtils is in use. Do not mix sync and async gRPC servicer
styles on one server.

## Generate

Resolve files under `reference/` relative to this `SKILL.md` in the plugin installation
(`$CURSOR_PLUGIN_ROOT/skills/scaffold-health-checks/` or
`${CLAUDE_SKILL_DIR}/`). These are plugin templates, not app-relative paths. Copy
and adapt them into the app; never edit the plugin copies.

```text
<package>/services/health/v1/
├── health_checks.py       # shared readiness helpers (deps, warm-up, shutdown)
├── health_service.py      # FastAPI — when HTTP requested
└── health_grpc_service.py # gRPC HealthServicer wiring — when gRPC requested
deploy/
└── k8s-probes.yaml        # optional (httpGet and/or grpc probes)
```

Share readiness helpers across transports. Keep business rules out of transport files.

## FastAPI (`health_service.py`)

- Export a thin router for `GET /health/live` and `GET /health/ready`.
- Return `200` healthy, `503` not ready / unhealthy, with empty bodies: no dependency names, versions, or error text.
- Wire with `include_router` into `manage.py` / app factory.
- Liveness: process-only, no deps. Readiness: deps + warm-up + shutdown, timeouts; per-check detail goes to logs only.
- Probes live in `repositories/health_check/` (one adapter file per dependency raising `UnavailableError`); the logic never drives adapters or raw SQL.
- Optional heartbeat mode for deadlock detection only when user asks.
- Code sketches and payload shapes: `../archipy-docs/reference/health-checks.md` § Health checks → FastAPI endpoints.

## gRPC (`health_grpc_service.py`)

Use the standard gRPC Health Checking Protocol (`grpc.health.v1.Health`) via `grpcio-health-checking`.

Register at least `""` (overall), `"readiness"`, and `"liveness"`. Map ready/alive → `SERVING`, not ready →
`NOT_SERVING`. Full service-name table and update rules: `../archipy-docs/reference/health-checks.md` § Health checks → gRPC Health
protocol.

### Wire sketch

**`""` and `"readiness"` start `NOT_SERVING`** until warm-up + deps are healthy:

```python
from grpc_health.v1 import health, health_pb2, health_pb2_grpc


def register_health_servicer(server, container) -> health.HealthServicer:
    """Attach standard Health servicer; return handle for status updates."""
    health_servicer = health.HealthServicer()
    health_pb2_grpc.add_HealthServicer_to_server(health_servicer, server)

    health_servicer.set("liveness", health_pb2.HealthCheckResponse.SERVING)
    health_servicer.set("readiness", health_pb2.HealthCheckResponse.NOT_SERVING)
    health_servicer.set("", health_pb2.HealthCheckResponse.NOT_SERVING)
    return health_servicer
```

### Status update rules (summary)

- Warm-up complete + deps healthy → set `""` and `"readiness"` to `SERVING`.
- Dep failure → `""` / `"readiness"` to `NOT_SERVING`; never flip `"liveness"` for dep failures.
- Prefer background updater calling `set()` over slow checks inside every `Check`.
- On `SIGTERM`: set readiness/`""` to `NOT_SERVING`, then `health_servicer.enter_graceful_shutdown()`.
- Async gRPC: same protocol/names; register on `AppUtils.create_async_grpc_app`; keep updates task-safe.

## Startup probes

- HTTP: point startup at `/health/live`.
- gRPC: point startup at service `"liveness"` (prefer over `""`).

## Kubernetes probe YAML

When requested, emit `deploy/k8s-probes.yaml` matching the chosen transport (s).

**Copy templates from `reference/`, adapt ports to config:**

| Transport | Template                         |
|-----------|----------------------------------|
| HTTP      | `reference/k8s-probes-http.yaml` |
| gRPC      | `reference/k8s-probes-grpc.yaml` |

Use `config.GRPC.SERVE_PORT` / `config.FASTAPI.SERVE_PORT` — never hardcode ports in app code; YAML may show
placeholders matching config.

Rules: `readinessProbe.successThreshold: 2`, `failureThreshold: 3` default, `timeoutSeconds` ≥ slowest readiness check
timeout, `preStop` sleep for short drain window.

## Graceful shutdown

- On `SIGTERM`, fail readiness immediately (HTTP `503` / gRPC `NOT_SERVING`).
- Give Kubernetes a short window to stop routing, then exit after in-flight requests finish.
- Details: `../archipy-docs/reference/health-checks.md` § Health checks → Graceful shutdown.

## Common mistakes

See `../archipy-docs/reference/health-checks.md` § Health checks → Common mistakes. Also avoid:

- No warm-up or shutdown awareness in readiness helpers
- Mixing sync and async gRPC health / domain servicers on one server
- Not testing failure behavior by taking down dependencies

## Do not

- Double quotes, Google-style docstrings, `X | Y` typing
- Keep services thin; no business rules in health transport
- No secrets in code; list env keys separately when needed
- Prefer FastAPI `JSONResponse` for HTTP probes; prefer `grpcio-health-checking` for gRPC
- Suggest `/docs-health-checks` for explanation and `/docs-observability` for metrics / tracing follow-up
- Never hardcode ports in app code (YAML may show placeholders matching config).
- No warm-up/shutdown-blind readiness; no dependency checks in liveness; no custom gRPC health RPCs — use the
  standard protocol.
- No secrets in code; double quotes, Google-style docstrings, `X | Y` typing.

## Verify

1. Run formatter/linter, then Behave scenarios that call the health endpoints/RPCs through the BDD harness with the
   dependencies' `@needs-*` containers.
2. Cover healthy, dependency failure (stop or pause the container), timeout, warm-up, and shutdown states.
3. Validate generated Kubernetes YAML and confirm probe ports/paths/service names match app config.
4. Run the `archipy-reviewer` subagent on the changes and fix every **Must fix** finding it reports.
5. Report files, dependencies, and commands run.

## Beyond Kubernetes

Same pattern applies to ALB, Consul, Nginx, or gRPC load balancers: expose health (HTTP and/or `grpc.health.v1`), define
healthy clearly, and let infrastructure stop routing to unhealthy instances.