@okay-e9g/hono-config 0.0.13 → 0.0.14

package/package.json

@@ -48,5 +48,5 @@
 		"prepublishOnly": "bun run typecheck && bun test",
 		"typecheck": "tsc --noEmit"
 	},
-	"version": "0.0.13"
+	"version": "0.0.14"
 }

package/src/index.ts

@@ -4,4 +4,5 @@
 
 export * from './helpers';
 export * from './middlewares';
+export * from './routes';
 export * from './schemas';

package/src/routes/health.ts

@@ -0,0 +1,228 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { Context } from 'hono';
+import type { Env } from 'hono/types';
+
+/**
+ * Response returned by `createHealthRoute`.
+ */
+export type HealthResponse = {
+	checks: Record<
+		string,
+		| {
+				critical: boolean;
+				durationMs: number;
+				status: 'healthy';
+		  }
+		| {
+				critical: boolean;
+				durationMs: number;
+				message: string;
+				reason: 'failed' | 'timeout';
+				status: 'unhealthy';
+		  }
+	>;
+	release: string | null;
+	status: 'degraded' | 'healthy' | 'unhealthy';
+};
+
+/**
+ * Options used to create a health route.
+ *
+ * A direct check is critical and uses the route-wide timeout, which defaults
+ * to 10 seconds. Use the descriptor form to mark a check as non-critical or
+ * override its timeout. Checks pass by returning normally and fail by throwing
+ * or rejecting.
+ *
+ * @typeParam T - Hono environment type available to health checks.
+ */
+export type HealthRouteOpts<T extends Env = Env> = {
+	checks?: Readonly<
+		Record<
+			string,
+			| ((c: Context<T>, signal: AbortSignal) => Promise<void> | void)
+			| {
+					check: (c: Context<T>, signal: AbortSignal) => Promise<void> | void;
+					critical?: boolean;
+					timeoutMs?: number;
+			  }
+		>
+	>;
+	release?: ((c: Context<T>) => string | null) | null | string;
+	timeoutMs?: number;
+};
+
+const runCheck = async <T extends Env>(
+	c: Context<T>,
+	{
+		check,
+		critical,
+		name,
+		timeoutMs,
+	}: {
+		check: (c: Context<T>, signal: AbortSignal) => Promise<void> | void;
+		critical: boolean;
+		name: string;
+		timeoutMs: number;
+	},
+): Promise<[string, HealthResponse['checks'][string]]> => {
+	const controller = new AbortController();
+	const requestSignal = c.req.raw.signal;
+	const timeoutError = new Error(`Health check timed out after ${timeoutMs}ms`);
+	const start = performance.now();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let onRequestAbort: (() => void) | undefined;
+
+	try {
+		await Promise.race([
+			Promise.resolve().then(() => check(c, controller.signal)),
+			new Promise<never>((_, reject) => {
+				const abort = (reason: unknown) => {
+					reject(reason);
+					controller.abort(reason);
+				};
+
+				timer = setTimeout(() => abort(timeoutError), timeoutMs);
+				onRequestAbort = () => {
+					abort(requestSignal.reason ?? new Error('Health check request was aborted'));
+				};
+
+				if (requestSignal.aborted) {
+					onRequestAbort();
+					return;
+				}
+
+				requestSignal.addEventListener('abort', onRequestAbort, { once: true });
+			}),
+		]);
+
+		return [
+			name,
+			{
+				critical,
+				durationMs: performance.now() - start,
+				status: 'healthy',
+			},
+		];
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+
+		return [
+			name,
+			{
+				critical,
+				durationMs: performance.now() - start,
+				message: message === '' ? 'Health check failed' : message,
+				reason: error === timeoutError ? 'timeout' : 'failed',
+				status: 'unhealthy',
+			},
+		];
+	} finally {
+		if (timer !== undefined) {
+			clearTimeout(timer);
+		}
+
+		if (onRequestAbort !== undefined) {
+			requestSignal.removeEventListener('abort', onRequestAbort);
+		}
+	}
+};
+
+/**
+ * Creates a reusable Hono route for liveness and readiness checks.
+ *
+ * Checks run concurrently. A failure in a critical check produces an
+ * `unhealthy` response with HTTP 503, while failures limited to non-critical
+ * checks produce a `degraded` response with HTTP 200. With no checks, the
+ * route produces a healthy liveness response.
+ *
+ * Thrown check messages are included in the response. Protect detailed health
+ * routes with appropriate authentication or network restrictions when those
+ * messages may contain sensitive information.
+ *
+ * @typeParam T - Hono environment type available to health checks.
+ * @param opts - Checks, release metadata, and timeout configuration.
+ * @returns A terminal Hono route handler.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from 'hono';
+ * import { createHealthRoute } from '@okay-e9g/hono-config';
+ *
+ * type AppEnv = {
+ *   Bindings: {
+ *     CACHE: KVNamespace;
+ *     DB: D1Database;
+ *   };
+ * };
+ *
+ * const app = new Hono<AppEnv>();
+ *
+ * app.get('/-/health', createHealthRoute<AppEnv>({
+ *   checks: {
+ *     database: async (c) => {
+ *       await c.env.DB.prepare('SELECT 1').first();
+ *     },
+ *     cache: {
+ *       check: async (c) => {
+ *         await c.env.CACHE.get('__healthcheck__');
+ *       },
+ *       critical: false,
+ *       timeoutMs: 2_000,
+ *     },
+ *   },
+ * }));
+ * ```
+ */
+export const createHealthRoute = <T extends Env = Env>({
+	checks = {},
+	release = null,
+	timeoutMs = 10_000,
+}: HealthRouteOpts<T> = {}) => {
+	const preparedChecks = Object.entries(checks).map(([name, definition]) => {
+		if (typeof definition === 'function') {
+			return {
+				check: definition,
+				critical: true,
+				name,
+				timeoutMs,
+			};
+		}
+
+		if (definition === null || typeof definition.check !== 'function') {
+			throw new TypeError(`Health check "${name}" must be a function or check descriptor.`);
+		}
+
+		return {
+			check: definition.check,
+			critical: definition.critical ?? true,
+			name,
+			timeoutMs: definition.timeoutMs ?? timeoutMs,
+		};
+	});
+
+	return async (c: Context<T>) => {
+		const checksByName = Object.fromEntries(
+			await Promise.all(preparedChecks.map((check) => runCheck(c, check))),
+		) as HealthResponse['checks'];
+		const failedChecks = Object.values(checksByName).filter(({ status }) => status === 'unhealthy');
+		const status: HealthResponse['status'] = failedChecks.some(({ critical }) => critical)
+			? 'unhealthy'
+			: failedChecks.length
+				? 'degraded'
+				: 'healthy';
+
+		c.header('Cache-Control', 'no-store');
+
+		return c.json(
+			{
+				checks: checksByName,
+				release: typeof release === 'function' ? release(c) : release,
+				status,
+			} satisfies HealthResponse,
+			status === 'unhealthy' ? 503 : 200,
+		);
+	};
+};

package/src/routes/index.ts

@@ -0,0 +1,5 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './health';