Add database readiness and native container health checks #58

Merged

erik merged 1 commit from feat/task-5e994039-readiness-healthchecks into main

2026-10-25 20:36:25 -05:00

erik commented

2026-10-25 20:32:44 -05:00

Owner

Summary

Add the current template's runtime health improvements while retaining slugkit.com's reference API and recent security/federation changes.

Add site-local /ready: HTTP 200/ready only when an existing database connection contains every packaged migration marker; otherwise HTTP 503/not_ready. Responses are generic JSON with no-store caching.
Keep /health and /api/1.1.0/health database-independent and unchanged.
Readiness observes an existing connection only: no lazy storage creation, migrations, schema/data writes, auth state changes or external-service calls. Startup behavior is unchanged.
Copy the native Node scripts/healthcheck.mjs into the runtime image and add the template's Docker HEALTHCHECK (30s interval, 5s timeout, 10s start period, 3 retries). Probe fetch has a 3s abort timeout, rejects redirects, honors existing binding precedence and succeeds only for HTTP 200/ready JSON.
Document semantics, limits and the separate Kubernetes rollout boundary in docs/health-checks.md.

Task: task-5e994039

Verification

./scripts/pre-pr.sh PASS: formatting, typecheck, build/reproducible CSS and 550 tests across 56 files.

New regressions cover closed/uninitialized/unmigrated/read-only connections; missing/extra migration markers and recovery; no probe writes/schema creation/storage initialization/network calls; unchanged liveness and security headers; native probe address precedence, failures/JSON/redirects/timeout configuration; runtime Dockerfile script/HEALTHCHECK wiring; and real native Node subprocess success/failure/recovery against isolated loopback HTTP fixtures.

Pure mocked/configuration tests remain deterministic CI tests. Actual HTTP/subprocess verification is in container-healthcheck.integration.test.ts, excluded from CI by the existing test:ci policy. No Docker/container/browser/federation integration provisioning or execution was added to CI/release workflows.

Verification limit: the local Docker daemon is unavailable. No image build or actual container smoke test was performed. Static Docker configuration and native process/HTTP checks passed; those are not claimed as image-level verification.

Boundaries

No dependencies, migration SQL, production data/storage, application binding/version configuration, reference API/schema/archive, browser security/federation identity, branding or release workflow behavior changed. No image/tag publication, production deployment or homelab mutation was performed.

Docker image health metadata does not configure Kubernetes probes. Any Kubernetes readiness/liveness/startup manifest changes must be reviewed separately in homelab through Flux/GitOps, with startup migrations and rollout timings considered. Publishing/deployment remain separately approved operations.

## Summary Add the current template's runtime health improvements while retaining slugkit.com's reference API and recent security/federation changes. - Add site-local `/ready`: HTTP 200/ready only when an existing database connection contains every packaged migration marker; otherwise HTTP 503/not_ready. Responses are generic JSON with no-store caching. - Keep `/health` and `/api/1.1.0/health` database-independent and unchanged. - Readiness observes an existing connection only: no lazy storage creation, migrations, schema/data writes, auth state changes or external-service calls. Startup behavior is unchanged. - Copy the native Node `scripts/healthcheck.mjs` into the runtime image and add the template's Docker HEALTHCHECK (30s interval, 5s timeout, 10s start period, 3 retries). Probe fetch has a 3s abort timeout, rejects redirects, honors existing binding precedence and succeeds only for HTTP 200/ready JSON. - Document semantics, limits and the separate Kubernetes rollout boundary in `docs/health-checks.md`. Task: task-5e994039 ## Verification `./scripts/pre-pr.sh` PASS: formatting, typecheck, build/reproducible CSS and **550 tests across 56 files**. New regressions cover closed/uninitialized/unmigrated/read-only connections; missing/extra migration markers and recovery; no probe writes/schema creation/storage initialization/network calls; unchanged liveness and security headers; native probe address precedence, failures/JSON/redirects/timeout configuration; runtime Dockerfile script/HEALTHCHECK wiring; and real native Node subprocess success/failure/recovery against isolated loopback HTTP fixtures. Pure mocked/configuration tests remain deterministic CI tests. Actual HTTP/subprocess verification is in `container-healthcheck.integration.test.ts`, excluded from CI by the existing test:ci policy. No Docker/container/browser/federation integration provisioning or execution was added to CI/release workflows. **Verification limit:** the local Docker daemon is unavailable. No image build or actual container smoke test was performed. Static Docker configuration and native process/HTTP checks passed; those are not claimed as image-level verification. ## Boundaries No dependencies, migration SQL, production data/storage, application binding/version configuration, reference API/schema/archive, browser security/federation identity, branding or release workflow behavior changed. No image/tag publication, production deployment or homelab mutation was performed. Docker image health metadata does not configure Kubernetes probes. Any Kubernetes readiness/liveness/startup manifest changes must be reviewed separately in homelab through Flux/GitOps, with startup migrations and rollout timings considered. Publishing/deployment remain separately approved operations.

erik added 1 commit

2026-10-25 20:32:44 -05:00

feat: add database readiness and native container probe

CI / verify (pull_request) Successful in 45s

Details

46eefd54b7

Task: #task-5e994039

erik commented

2026-10-25 20:36:25 -05:00

Author

Owner

Independent review — `46eefd54b7`

A separate fresh-context Pi reviewer inspected the full diff and relevant startup/application/database/configuration/test code with read/grep/find/ls only. Result: No actionable defects found.

Review confirmed existing-connection/SELECT-only readiness with fail-closed 200/503 responses and no-store caching; unchanged startup and database-independent liveness; correct packaged migration paths/runtime copying; probe binding/port precedence, timeout/redirect/response/exit handling; CI exclusion of real process/HTTP integration tests; and preservation of API/schema archives, security/federation, packages, migration SQL and workflows.

Optional suggestion: add a local-only delayed-header or stalled-body fixture for the actual three-second abort behavior. Deferred as non-blocking follow-up. Current unit tests verify configured timeout/error handling; actual native-process HTTP tests exercise success/failure/recovery and redirect rejection, not real stalled-body timing.

Verification limits: independent review was static/read-only and did not rerun checks. Implementation-session scripts/pre-pr.sh passed (550 tests in 56 files, formatting/types/build/reproducible CSS), and Forgejo PR CI run #57 passed for this exact commit. CI was checked via fj actions tasks due to the known fj pr status parser issue.

The Docker daemon is unavailable: no image build or container smoke test was performed. Static Docker configuration and native-process/loopback HTTP verification are not claimed as image-level or production verification. No image/tag publication, production deployment, homelab mutation or Kubernetes probe application was performed or authorized.

## Independent review — 46eefd54b78e2697485fc3520418e804a970468f A separate fresh-context Pi reviewer inspected the full diff and relevant startup/application/database/configuration/test code with read/grep/find/ls only. Result: **No actionable defects found.** Review confirmed existing-connection/SELECT-only readiness with fail-closed 200/503 responses and no-store caching; unchanged startup and database-independent liveness; correct packaged migration paths/runtime copying; probe binding/port precedence, timeout/redirect/response/exit handling; CI exclusion of real process/HTTP integration tests; and preservation of API/schema archives, security/federation, packages, migration SQL and workflows. Optional suggestion: add a local-only delayed-header or stalled-body fixture for the actual three-second abort behavior. Deferred as non-blocking follow-up. Current unit tests verify configured timeout/error handling; actual native-process HTTP tests exercise success/failure/recovery and redirect rejection, not real stalled-body timing. Verification limits: independent review was static/read-only and did not rerun checks. Implementation-session scripts/pre-pr.sh passed (550 tests in 56 files, formatting/types/build/reproducible CSS), and Forgejo PR CI run #57 passed for this exact commit. CI was checked via fj actions tasks due to the known fj pr status parser issue. The Docker daemon is unavailable: no image build or container smoke test was performed. Static Docker configuration and native-process/loopback HTTP verification are not claimed as image-level or production verification. No image/tag publication, production deployment, homelab mutation or Kubernetes probe application was performed or authorized.

erik merged commit 8129181773 into main

2026-10-25 20:36:25 -05:00

erik deleted branch feat/task-5e994039-readiness-healthchecks

2026-10-25 20:36:25 -05:00

erik referenced this pull request from a commit

2026-10-25 20:36:26 -05:00

Merge pull request 'Add database readiness and native container health checks' (#58) from feat/task-5e994039-readiness-healthchecks into main