Skip to content

feat: add estate-standard /health endpoint - #174

Merged
vreshch merged 1 commit into
masterfrom
feature/health-endpoint
Aug 9, 2026
Merged

feat: add estate-standard /health endpoint#174
vreshch merged 1 commit into
masterfrom
feature/health-endpoint

Conversation

@vreshch

@vreshch vreshch commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Summary

Adds the estate-standard /health contract (/home/vreshch/vaults/agentage/specs/health-endpoints.md) to vreshch.com. Today https://vreshch.com/health 404s; without it, admin.agentage.io can only show "No probe" for this service.

  • Bumped @agentage/observability ^0.6.1 -> ^0.8.0 (already a dependency for OTEL tracing via /next; this adds the /health subpath, which is dependency-free - no OpenTelemetry pulled into the route).
  • src/app/health/route.ts - export const dynamic = 'force-dynamic' + healthResponse(), per the Next.js profile in the spec (SSR shell, no downstream dependency checks).
  • Dockerfile - runner stage now redeclares ARG COMMIT_SHA/BUILD_TIME and promotes them to ENV, since ARGs don't cross stage boundaries and the envelope reads build provenance from runtime env vars. Without this it would report 0.0.0-dev/dev forever.
  • docker-compose.yml - Swarm healthcheck now spiders /health instead of / (see judgement call below).

Judgement calls

  1. No explicit service param. The route calls healthResponse() with no override. .github/workflows/deploy.yml writes OTEL_SERVICE_NAME=vreshch-web into the runtime .env (consumed via docker-compose.yml's env_file: .env), and the kit's resolveServiceName defaults to OTEL_SERVICE_NAME. Confirmed this end-to-end with a local container run: -e OTEL_SERVICE_NAME=vreshch-web produces "service": "vreshch-web"; without it, "service": "unknown" (loud on purpose, per the kit's docstring). This is deliberate: it keeps the health service and the OTEL service.name equal by construction instead of by two hand-typed strings drifting apart, which is the exact defect (H hand-typed mismatch) the spec calls out in 9 of 10 services today. Trade-off: a container run outside this deploy pipeline (e.g. local docker run without the prod .env) will report service: "unknown" rather than vreshch-web - acceptable since this repo has no preview environment (direct-to-prod).
  2. docker-compose.yml healthcheck moved from / to /health. Recommended and made the change: / renders the full homepage (blog list, images) so a content-only regression or a slow render can flap the Swarm health state for reasons unrelated to "is the process alive"; /health is the minimal, stable, estate-standard surface built for exactly this and won't shift when the homepage changes. Also lines up the container's own healthcheck with what admin.agentage.io will be probing externally.
  3. No dependency checks added - per the spec's Next.js profile, an SSR shell must not probe downstream services, and vreshch.com has none server-side anyway.

Verification

  • npm run verify (type-check + lint + build + test) - green, /health builds as ƒ (dynamic).
  • npm run format:check - green (separate CI step, not part of verify in this repo).
  • Built the container with --build-arg COMMIT_SHA=testsha1234567890 --build-arg BRANCH=feature/health-endpoint --build-arg BUILD_TIME=2026-08-09T12:00:00Z, ran it, and curled /health:
    {
      "success": true,
      "data": {
        "status": "ok",
        "service": "unknown",
        "version": "testsha1234567890",
        "commit": "testsha",
        "buildTime": "2026-08-09T12:00:00Z",
        "startedAt": "2026-08-09T14:34:12.819Z",
        "uptimeSeconds": 7
      }
    }
    commit is 7 chars, version is the full sha, buildTime round-trips - confirms the Dockerfile ARG-to-ENV promotion works. service reads unknown here because this ad-hoc docker run didn't set OTEL_SERVICE_NAME (not baked into the image, only written to the server's .env by the deploy job). Re-ran with -e OTEL_SERVICE_NAME=vreshch-web and got "service": "vreshch-web", matching what prod will report.
  • Added src/app/health/route.test.ts (Vitest) asserting 200, success: true, data.service === 'vreshch-web', data.status === 'ok' (stubs OTEL_SERVICE_NAME to mirror the prod runtime env).

Test plan

  • CI green (pr-validation.yml including the separate Format check step)
  • After merge + deploy, curl https://vreshch.com/health returns the envelope with service: "vreshch-web" and real commit/buildTime
  • admin.agentage.io Services page picks up a probe for vreshch-web instead of "No probe"

Adopt @agentage/observability/health so admin.agentage.io can probe
this service; promote COMMIT_SHA/BUILD_TIME to runtime ENV in the
Dockerfile runner stage and point the Swarm healthcheck at /health.
@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown

🎉 PR Validation ✅ PASSED

Commit: 79f69723f9d6a37916dbd13cacf08b414744ac36
Branch: feature/health-endpoint

Checks:

  • ✅ Dependencies installed
  • ✅ Linting passed
  • ✅ Format check passed
  • ✅ Build successful
  • ✅ Docker build
  • ✅ E2E tests

Visual Changes: 8 of 8 screenshots changed

📸 contacts desktop — 100% changed
📸 contacts mobile — 100% changed
📸 home desktop — 100% changed
📸 home mobile — 100% changed
📸 interests desktop — 100% changed
📸 interests mobile — 100% changed
📸 projects desktop — 100% changed
📸 projects mobile — 100% changed

Ready to merge!


🔗 View workflow run
⏰ Generated at: 2026-08-09T14:39:21.214Z

@vreshch
vreshch marked this pull request as ready for review August 9, 2026 14:40
@vreshch
vreshch merged commit 8f581c5 into master Aug 9, 2026
1 check passed
@vreshch
vreshch deleted the feature/health-endpoint branch August 9, 2026 20:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant