@zmdb/web 1.0.0-beta.1

package/src/integrations/index.ts

@@ -0,0 +1,50 @@
+// Framework-agnostic endpoint adapter — see ./SPEC.md.
+
+import { claimsValidationIssues, ValidationError, validationIssuesOf } from '@zmdb/validator';
+
+export interface Handler<In, Out> {
+  validate: (raw: unknown) => In;
+  handle: (input: In) => Promise<Out>;
+  serialize?: (out: Out) => string;
+}
+
+export interface EndpointResult {
+  status: number;
+  body: string;
+}
+
+export function makeEndpoint<In, Out>(h: Handler<In, Out>): (raw: unknown) => Promise<EndpointResult> {
+  const serialize = h.serialize ?? ((o: Out) => JSON.stringify(o));
+  return async (raw: unknown) => {
+    let input: In;
+    try {
+      input = h.validate(raw);
+    } catch (err) {
+      const error = err instanceof Error ? err.message : 'invalid input';
+      const issues = validationIssuesOf(err);
+      return { status: 400, body: JSON.stringify(issues ? { error, issues } : { error }) };
+    }
+    try {
+      const out = await h.handle(input);
+      return { status: 200, body: serialize(out) };
+    } catch (err) {
+      // A validation error from the *handler* is still the caller's fault — a write that
+      // failed its own schema check on the way to the driver — so it is a 400 and not a 500.
+      // Anything else is rethrown untouched: this adapter has no business deciding what an
+      // unexpected exception means.
+      if (err instanceof ValidationError || claimsValidationIssues(err)) {
+        const error = err instanceof Error ? err.message : 'invalid input';
+        const issues = validationIssuesOf(err);
+        return { status: 400, body: JSON.stringify(issues ? { error, issues } : { error }) };
+      }
+      throw err;
+    }
+  };
+}
+
+// --- Thin per-framework adapters (optional; no hard deps) ---
+// Hono:    app.post('/x', async (c) => { const r = await ep(await c.req.json()); return c.body(r.body, r.status); })
+// Express: app.post('/x', async (req,res) => { const r = await ep(req.body); res.status(r.status).send(r.body); })
+// tRPC:    procedure.input(z.unknown()).mutation(({input}) => ep(input))
+// NestJS:  @Post() async create(@Body() b){ return ep(b); }
+// Each is a 1–2 line wrapper over makeEndpoint — see docs/framework-integrations.

package/src/middleware/errors.ts

@@ -0,0 +1,17 @@
+/** An error carrying an HTTP status, thrown when a middleware chain short-circuits. */
+export class ChainError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = 'ChainError';
+    this.status = status;
+  }
+}
+
+/**
+ * Internal boundary error whose status is already the framework's decision.
+ *
+ * Ordinary user-thrown pipe errors still become ChainError(400). Built-in
+ * boundary parsers use this subclass when 400 and 413 have distinct meanings.
+ */
+export class BoundaryStatusError extends ChainError {}

package/src/middleware/index.ts

@@ -0,0 +1,108 @@
+// @zmdb/web — guards, pipes, interceptors & exception filters (epic #287, spec
+// ./SPEC.md). A Chain composes middleware around a handler in deterministic
+// order. Static composition, no reflection, no `as` on the consumer surface.
+
+import type { Ctx, QueryValues } from '../context/index.js';
+import type { WebResponse } from '../pipeline/index.js';
+import { BoundaryStatusError, ChainError } from './errors.js';
+
+export { ChainError } from './errors.js';
+
+export type AnyCtx = Ctx<Record<string, string>, unknown, QueryValues>;
+
+/** Authorization gate: a `false` short-circuits the request (403). */
+export interface Guard {
+  canActivate(ctx: AnyCtx): boolean | Promise<boolean>;
+}
+
+/** A guard that declares the OpenAPI security scheme and scopes it enforces. */
+export interface SecurityAwareGuard extends Guard {
+  readonly enforces: { readonly scheme: string; readonly scopes: readonly string[] };
+}
+
+/** Transform/validate a value; ordinary throws yield 400. */
+export interface Pipe<In = unknown, Out = unknown> {
+  transform(value: In, ctx: AnyCtx): Out | Promise<Out>;
+}
+
+/** Wrap the rest of the chain (handler) with pre/post behavior. */
+export interface Interceptor {
+  intercept(ctx: AnyCtx, next: () => Promise<unknown>): Promise<unknown>;
+}
+
+/** Map a thrown error to a response. */
+export interface ExceptionFilter {
+  catch(error: unknown, ctx: AnyCtx): WebResponse | undefined;
+}
+
+/** A composed middleware chain for a route. */
+export interface Chain {
+  readonly guards: readonly Guard[];
+  readonly pipes: readonly Pipe[];
+  readonly interceptors: readonly Interceptor[];
+  readonly filters: readonly ExceptionFilter[];
+}
+
+/** A handler invoked with the (piped) ctx. */
+export type ChainHandler = (ctx: AnyCtx) => unknown;
+
+/**
+ * Run a middleware chain around `handler` for `ctx`. Order: guards → pipes (fold
+ * the body) → interceptors (nested) → handler. A guard returning false throws
+ * ChainError(403); an ordinary throwing pipe throws ChainError(400), while a
+ * built-in boundary pipe can preserve its framework-selected status; a thrown
+ * handler is offered to the exception filters — a matching filter's response is
+ * returned, otherwise the error rethrows for the pipeline to serialize.
+ */
+export async function runChain(chain: Chain, ctx: AnyCtx, handler: ChainHandler): Promise<unknown> {
+  // 1) guards
+  for (const guard of chain.guards) {
+    const allowed = await guard.canActivate(ctx);
+    if (!allowed) {
+      throw new ChainError(403, 'forbidden');
+    }
+  }
+
+  // 2) pipes — fold over the body, producing a new ctx the handler sees.
+  let body = ctx.body;
+  for (const pipe of chain.pipes) {
+    try {
+      body = await pipe.transform(body, ctx);
+    } catch (error) {
+      if (error instanceof BoundaryStatusError) {
+        throw error;
+      }
+      throw new ChainError(400, messageOf(error));
+    }
+  }
+  const pipedCtx: AnyCtx = { ...ctx, body };
+
+  // 3) interceptors — nest right-to-left so the first listed runs outermost.
+  const invokeHandler = (): Promise<unknown> => Promise.resolve(handler(pipedCtx));
+  let next = invokeHandler;
+  for (let i = chain.interceptors.length - 1; i >= 0; i -= 1) {
+    const interceptor = chain.interceptors[i];
+    if (interceptor === undefined) {
+      continue;
+    }
+    const downstream = next;
+    next = (): Promise<unknown> => interceptor.intercept(pipedCtx, downstream);
+  }
+
+  // 4) handler (via the interceptor chain); 5) exception filters on throw.
+  try {
+    return await next();
+  } catch (error) {
+    for (const filter of chain.filters) {
+      const response = filter.catch(error, pipedCtx);
+      if (response !== undefined) {
+        return response;
+      }
+    }
+    throw error;
+  }
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}