also looking at this
Adopt the hq-apps app conventions
#76
31 files
+1656
-395
| @@ -0,0 +1,90 @@ | ||
| 1 | import type { ApplicationHealthResult } from '@stacksjs/router' | |
| 2 | import { checkApplicationHealth } from '@stacksjs/router' | |
| 3 | ||
| 4 | /** | |
| 5 | * The name this app answers to in its own health body. | |
| 6 | * | |
| 7 | * Matches `package.json` → `name`, which is also the key | |
| 8 | * `scripts/smoke-deployment.ts` and `scripts/validate-release.ts` resolve | |
| 9 | * their contracts by. Keep the three in step. | |
| 10 | */ | |
| 11 | export const APP = 'bench-review' | |
| 12 | ||
| 13 | export interface HealthOptions { | |
| 14 | /** | |
| 15 | * The probe runner. Defaults to the framework's, which checks the database | |
| 16 | * (`SELECT 1`) and the cache (set, then delete) with a 1.5s timeout each. | |
| 17 | * Injectable so the failure path can be tested without taking a real | |
| 18 | * dependency down. | |
| 19 | */ | |
| 20 | check?: () => Promise<ApplicationHealthResult> | |
| 21 | /** App-specific facts merged into the body. */ | |
| 22 | extra?: Record<string, unknown> | |
| 23 | } | |
| 24 | ||
| 25 | /** | |
| 26 | * The health endpoint an uptime monitor can actually trust. | |
| 27 | * | |
| 28 | * ## Why this is registered by hand | |
| 29 | * | |
| 30 | * The framework already ships this as `route.health()` from | |
| 31 | * `storage/framework/defaults/routes/dashboard.ts`, but reaching it depends on | |
| 32 | * conditions that have nothing to do with health: | |
| 33 | * | |
| 34 | * - `config/dashboard.ts` → `enabled`. Turning off the admin UI also removes | |
| 35 | * `/api/health`. bench-review has no `config/dashboard.ts` at all, so there | |
| 36 | * is nothing guaranteeing that call site runs. | |
| 37 | * - the vendored `storage/framework/` tree reaching the box. bench's | |
| 38 | * production artifact is a pre-rendered `dist/` plus the API process; the | |
| 39 | * framework defaults are not something the deploy contract promises. | |
| 40 | * | |
| 41 | * Registering it here makes the endpoint a property of this app rather than of | |
| 42 | * a UI flag and a build artifact. User routes load before the framework's, so | |
| 43 | * this also wins wherever the default one is present. | |
| 44 | * | |
| 45 | * ## Why not a static 200 | |
| 46 | * | |
| 47 | * A literal `{ status: 'ok' }` cannot fail: it returns 200 with the database | |
| 48 | * down, the cache gone, and every page 500ing. Pointing a monitor at it would | |
| 49 | * produce a green dashboard straight through an outage — worse than having no | |
| 50 | * monitor at all, because one is a known gap and the other is a false | |
| 51 | * assurance. | |
| 52 | * | |
| 53 | * Answering 503 on a failed probe is what makes this readable by a plain HTTP | |
| 54 | * check, so no monitor has to understand the body to get the right answer. | |
| 55 | * | |
| 56 | * ## Route registration | |
| 57 | * | |
| 58 | * `routes/api.ts` auto-prefixes every path with `/api` (stacksjs/stacks#1835), | |
| 59 | * so the declaration there is a bare `/health` and the served path is | |
| 60 | * `/api/health`. Do not declare `/api/health` in that file — it becomes | |
| 61 | * `/api/api/health`. | |
| 62 | */ | |
| 63 | export async function healthResponse(options: HealthOptions = {}): Promise<Response> { | |
| 64 | const check = options.check ?? checkApplicationHealth | |
| 65 | ||
| 66 | let health: ApplicationHealthResult | |
| 67 | try { | |
| 68 | health = await check() | |
| 69 | } | |
| 70 | catch (err) { | |
| 71 | // A probe runner that throws is itself a failure, and reporting it as one | |
| 72 | // beats a 500 from an unhandled rejection: the monitor gets a body it can | |
| 73 | // read rather than an opaque error page. | |
| 74 | health = { | |
| 75 | status: 'degraded', | |
| 76 | checks: { probe: { ok: false, ms: 0, message: err instanceof Error ? err.message : String(err) } }, | |
| 77 | timestamp: Date.now(), | |
| 78 | } | |
| 79 | } | |
| 80 | ||
| 81 | return new Response(JSON.stringify({ app: APP, ...health, ...(options.extra ?? {}) }), { | |
| 82 | status: health.status === 'healthy' ? 200 : 503, | |
| 83 | headers: { | |
| 84 | 'Content-Type': 'application/json', | |
| 85 | // A cached health check reports the past. Nothing between us and the | |
| 86 | // monitor may answer this from a store. | |
| 87 | 'Cache-Control': 'no-store', | |
| 88 | }, | |
| 89 | }) | |
| 90 | } | |