ReviewOS

also looking at this

stacks/bench-review

Adopt the hq-apps app conventions

#76
Merged glennmichael123 wants to merge chore/hq-apps-conventions into main
31 files +1656 -395
app/Support/health.tsadded+90-0
Changes to app/Support/health.ts
@@ -0,0 +1,90 @@
1import type { ApplicationHealthResult } from '@stacksjs/router'
2import { 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 */
11export const APP = 'bench-review'
12
13export 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 */
63export 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}