@cosmicdrift/kumiko-framework 0.1.0

package/src/api/route-registrars.ts

@@ -0,0 +1,195 @@
+// Route-level wiring that buildServer used to inline. Extracted so
+// server.ts stays a composition-of-named-steps rather than 500 lines of
+// branches. Every registrar takes the Hono app + whatever state it
+// actually reads — no monolithic `options` parameter, because these
+// helpers exist to make each step's dependencies visible at the call-site.
+
+import type { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import type { DbConnection } from "../db/connection";
+import type { Lifecycle } from "../lifecycle";
+import type { Meter, PrometheusMeter } from "../observability";
+import { serializeOpenMetrics } from "../observability";
+import type { EventConsumer } from "../pipeline/event-dispatcher";
+import { Routes } from "./api-constants";
+import {
+  createReadinessProbe,
+  dbPingCheck,
+  dispatcherLagCheck,
+  type ReadinessCheck,
+  redisPingCheck,
+} from "./readiness";
+
+// --- Body size limit ------------------------------------------------------
+
+const BODY_LIMIT_PATHS = [
+  `/api${Routes.write}`,
+  `/api${Routes.batch}`,
+  `/api${Routes.query}`,
+  `/api${Routes.command}`,
+  `/api${Routes.auth}/*`,
+] as const;
+
+export const DEFAULT_MAX_REQUEST_BYTES = 1_048_576;
+
+// Cap JSON bodies on /api/write + /api/batch + /api/query + /api/command
+// + /api/auth/*. File uploads keep their own per-field maxSize. `0`
+// disables the limit entirely — only useful when a reverse-proxy caps
+// upstream or tests want raw passthrough.
+export function registerBodyLimit(app: Hono, maxBytes: number): void {
+  // skip: opt-out path — caller passed `maxBytes: 0`, so no middleware
+  // is attached (upstream cap via reverse-proxy is expected). Not a bug
+  // suppression, an intentional disable.
+  if (maxBytes <= 0) return;
+  const limit = bodyLimit({ maxSize: maxBytes });
+  for (const path of BODY_LIMIT_PATHS) app.use(path, limit);
+}
+
+// --- /metrics (Prometheus scrape) -----------------------------------------
+
+export type MetricsRouteOptions = {
+  readonly token?: string;
+  readonly path?: string;
+};
+
+// Timing-safe string compare — equal-length strings compare every byte
+// regardless of where they diverge; different lengths return false without
+// iterating. Prevents side-channel leaks on the Bearer-token check.
+function constantTimeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+// Type-guard: duck-types the meter on `snapshot()`. An alternative
+// Prometheus-compatible meter (future OTLP bridge) works without an
+// explicit union — if it exposes `snapshot()` it's serialisable.
+function isPrometheusMeter(m: Meter): m is PrometheusMeter {
+  return typeof (m as { snapshot?: unknown }).snapshot === "function";
+}
+
+// Mount `/metrics` (or the caller-supplied path). Takes just the Meter —
+// not the whole ObservabilityProvider — because that's the only field
+// this route reads. Bearer-token optional — without one, scraping is
+// open, fine for a private cluster.
+export function registerMetricsRoute(app: Hono, meter: Meter, options: MetricsRouteOptions): void {
+  const metricsPath = options.path ?? "/metrics";
+  const expectedToken = options.token;
+  app.get(metricsPath, async (c) => {
+    if (expectedToken !== undefined) {
+      const header = c.req.header("authorization") ?? "";
+      const prefix = "Bearer ";
+      if (!header.startsWith(prefix)) return c.text("unauthorized", 401);
+      const provided = header.slice(prefix.length);
+      if (!constantTimeEqual(provided, expectedToken)) return c.text("unauthorized", 401);
+    }
+    if (!isPrometheusMeter(meter)) {
+      return c.text(
+        "metrics endpoint requires a PrometheusMeter — wrap the observability provider around createPrometheusMeter()",
+        503,
+      );
+    }
+    const body = serializeOpenMetrics(meter);
+    c.header("Content-Type", "application/openmetrics-text; version=1.0.0; charset=utf-8");
+    return c.body(body);
+  });
+}
+
+// --- /version ---------------------------------------------------------------
+
+// Anonymous endpoint that returns build-identity. Used by ops-tooling
+// (prod-version.sh) und Telegram-deploy-Notification damit man nicht
+// kubectl + crictl auf den Master braucht um die deployed-Version zu
+// sehen.
+//
+// BUILD_VERSION + BUILD_TIME werden vom Dockerfile (ARG → ENV)
+// durchgereicht — fallen zurück auf "dev" / "unknown" wenn lokal ohne
+// Build-args gebaut.
+export function registerVersionRoute(app: Hono): void {
+  const version = process.env["BUILD_VERSION"] ?? "dev";
+  const buildTime = process.env["BUILD_TIME"] ?? "unknown";
+  app.get(Routes.version, (c) =>
+    c.json({
+      version,
+      buildTime,
+      node: process.env["NODE_ENV"] ?? "development",
+    }),
+  );
+}
+
+// --- /health + /health/ready ----------------------------------------------
+
+// Readiness is one concept — what to check (db/redis/consumers) AND how
+// to run the probe (timeout, lag-threshold). Keep the pair grouped so
+// callers see "this is my readiness setup" as a single struct, not as
+// four half-related top-level fields.
+export type HealthRoutesOptions = {
+  readonly lifecycle?: Lifecycle;
+  readonly readiness?: {
+    readonly db?: DbConnection;
+    readonly redis?: import("ioredis").default;
+    readonly consumers?: readonly EventConsumer[];
+    readonly timeoutMs?: number;
+    // Opt-in dispatcher-lag gate. Off by default — a default threshold
+    // would false-503 small deployments that legitimately lag during
+    // bursts. Requires `db` + `consumers` to be set too; otherwise silently
+    // skipped (nothing to diff against).
+    readonly maxDispatcherLag?: bigint;
+  };
+};
+
+// Mount both health probes:
+//   /health — always, trivial 200 with `{status:"ok"}` (liveness)
+//   /health/ready — only when a lifecycle is wired. Short-circuits to
+//                   503 during drain; otherwise runs dependency checks
+//                   (DB/Redis/Dispatcher-lag) in parallel with a per-check
+//                   timeout.
+export function registerHealthRoutes(app: Hono, options: HealthRoutesOptions): void {
+  app.get(Routes.health, (c) => c.json({ status: "ok" }));
+
+  // skip: no lifecycle wired → /health/ready stays absent by design.
+  // Without lifecycle we'd have no way to flip the probe to 503 on
+  // drain — `/health` alone is enough for a test/dev process.
+  if (!options.lifecycle) return;
+  const lifecycle = options.lifecycle;
+  const readiness = options.readiness;
+
+  const readinessChecks: ReadinessCheck[] = [];
+  if (readiness?.db) readinessChecks.push(dbPingCheck(readiness.db));
+  if (readiness?.redis) readinessChecks.push(redisPingCheck(readiness.redis));
+  if (
+    readiness?.maxDispatcherLag !== undefined &&
+    readiness.db &&
+    readiness.consumers &&
+    readiness.consumers.length > 0
+  ) {
+    readinessChecks.push(
+      dispatcherLagCheck(
+        readiness.db,
+        readiness.consumers.map((c) => c.name),
+        readiness.maxDispatcherLag,
+      ),
+    );
+  }
+  const probe = createReadinessProbe(readinessChecks, { timeoutMs: readiness?.timeoutMs });
+
+  app.get(Routes.healthReady, async (c) => {
+    const state = lifecycle.state();
+    if (state !== "ready") {
+      return c.json({ status: "not_ready", state, uptimeSec: lifecycle.uptimeSec() }, 503);
+    }
+    const result = await probe();
+    return c.json(
+      {
+        status: result.ok ? "ready" : "not_ready",
+        state,
+        uptimeSec: lifecycle.uptimeSec(),
+        checks: result.checks,
+      },
+      result.ok ? 200 : 503,
+    );
+  });
+}

package/src/api/routes.ts

@@ -0,0 +1,135 @@
+import { type Context, Hono } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import {
+  InternalError,
+  isKumikoError,
+  type KumikoError,
+  reraiseAsKumikoError,
+  serializeError,
+  ValidationError,
+} from "../errors";
+import type { Dispatcher } from "../pipeline/dispatcher";
+import { Routes } from "./api-constants";
+import { getUser } from "./auth-middleware";
+import { requestContext } from "./request-context";
+
+export function createApiRoutes(dispatcher: Dispatcher) {
+  const api = new Hono();
+
+  api.post(Routes.write, async (c) => {
+    const user = getUser(c);
+    const body = await c.req.json<{ type: string; payload: unknown; requestId?: string }>();
+
+    try {
+      const result = await dispatcher.write(body.type, body.payload, user, body.requestId);
+      if (!result.isSuccess) {
+        return writeErrorResponse(c, reraiseAsKumikoError(result.error));
+      }
+      return c.json(result);
+    } catch (e) {
+      return writeErrorResponse(c, toKumiko(e));
+    }
+  });
+
+  api.post(Routes.batch, async (c) => {
+    const user = getUser(c);
+    const body = await c.req.json<{
+      commands: Array<{ type: string; payload: unknown }>;
+      requestId?: string;
+    }>();
+
+    if (!Array.isArray(body.commands)) {
+      // Client-shape violation → ValidationError (400, code=validation_error)
+      // matches what a Zod-level schema failure would produce if /batch had
+      // one. Client SDKs can key off the uniform validation contract.
+      return writeErrorResponse(
+        c,
+        new ValidationError({
+          fields: [
+            {
+              path: "commands",
+              code: "invalid_type",
+              i18nKey: "errors.validation.invalid_type",
+              params: { expected: "array", received: typeof body.commands },
+            },
+          ],
+        }),
+      );
+    }
+
+    try {
+      const result = await dispatcher.batch(body.commands, user, body.requestId);
+      if (!result.isSuccess) {
+        const err = reraiseAsKumikoError(result.error);
+        const requestId = requestContext.get()?.requestId;
+        const { error } = serializeError(err, requestId);
+        // Keep failedIndex + results alongside the error envelope so callers
+        // can tell which command in the batch failed and inspect the partial
+        // results from the successful commands before the rollback.
+        return c.json(
+          {
+            isSuccess: false,
+            error,
+            failedIndex: result.failedIndex,
+            results: result.results,
+          },
+          err.httpStatus as ContentfulStatusCode,
+        );
+      }
+      return c.json(result);
+    } catch (e) {
+      return writeErrorResponse(c, toKumiko(e));
+    }
+  });
+
+  api.post(Routes.query, async (c) => {
+    const user = getUser(c);
+    const body = await c.req.json<{ type: string; payload: unknown }>();
+
+    try {
+      const result = await dispatcher.query(body.type, body.payload, user);
+      return c.json({ data: result });
+    } catch (e) {
+      return queryErrorResponse(c, toKumiko(e));
+    }
+  });
+
+  api.post(Routes.command, async (c) => {
+    const user = getUser(c);
+    const body = await c.req.json<{ type: string; payload: unknown }>();
+
+    try {
+      await dispatcher.command(body.type, body.payload, user);
+      return c.json({ ok: true }, 202);
+    } catch (e) {
+      return queryErrorResponse(c, toKumiko(e));
+    }
+  });
+
+  return api;
+}
+
+function toKumiko(e: unknown): KumikoError {
+  if (isKumikoError(e)) return e;
+  if (e instanceof Error) return new InternalError({ cause: e });
+  return new InternalError({ message: String(e) });
+}
+
+// For /write + /batch: keep the isSuccess flag so clients can flip on a single
+// boolean (mirrors the success shape). The actual error body is the
+// error-contract payload nested under .error.
+function writeErrorResponse(c: Context, err: KumikoError, statusOverride?: number) {
+  const requestId = requestContext.get()?.requestId;
+  const { error } = serializeError(err, requestId);
+  const status = (statusOverride ?? err.httpStatus) as ContentfulStatusCode;
+  return c.json({ isSuccess: false, error }, status);
+}
+
+// For /query + /command: no isSuccess on success (just { data } / {ok}), so we
+// keep the same lean shape on failure — only the `error` key.
+function queryErrorResponse(c: Context, err: KumikoError, statusOverride?: number) {
+  const requestId = requestContext.get()?.requestId;
+  const body = serializeError(err, requestId);
+  const status = (statusOverride ?? err.httpStatus) as ContentfulStatusCode;
+  return c.json(body, status);
+}