scaffold-health-checks

Files (3)

• SKILL.md
• k8s-probes-grpc.yaml · reference/
• k8s-probes-http.yaml · reference/

SKILL.md (first lines)

# 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 `""`).

From SyntaxArc/archipy-plugin, MIT.

More from SyntaxArc/archipy-plugin