@zmdb/web 1.0.0-beta.1

package/src/dto-pipes/index.ts

@@ -0,0 +1,93 @@
+// @zmdb/web — DTO validation & serialization pipes (epic #297, spec ./SPEC.md).
+// Bind routes to schema-derived DTO validation (a Pipe) and entity serialization
+// (an Interceptor), built on the middleware chain. Zero runtime parser (consumer
+// supplies the AOT assert); no `as` on the consumer surface.
+
+import type { Chain, Pipe, Interceptor } from '../middleware/index.js';
+import { parseMultipart, type Multipart, type UploadLimits } from '../upload/index.js';
+
+/**
+ * A validation pipe: runs `validator` (e.g. `assert<CreateDTO<S>>`) on the body,
+ * yielding the typed value. A throw becomes the chain's 400. The framework
+ * embeds no parser — validation is the consumer's AOT `assert`.
+ */
+export function validationPipe<T>(validator: (raw: unknown) => T): Pipe<unknown, T> {
+  return {
+    transform(value: unknown): T {
+      return validator(value);
+    },
+  };
+}
+
+/**
+ * A pipe that only converts: the wire→app decode at the boundary (plan D3).
+ *
+ * Separate from `validationPipe` because the two do different jobs and the order matters.
+ * `wireDecoder(Schema)` turns the ISO string JSON carries into the `Date` a `CreateDTO`
+ * asks for; the validator then checks the app type. Decoding after validation would mean
+ * validating the wrong layer, and doing both in one function is how a validator ends up
+ * accepting `Date | string` and checking neither.
+ */
+export function decodePipe<In = unknown, Out = unknown>(decode: (value: In) => Out): Pipe<In, Out> {
+  return {
+    transform(value: In): Out {
+      return decode(value);
+    },
+  };
+}
+
+/**
+ * Parse the exact request bytes as multipart at the ordinary pipe boundary.
+ *
+ * The returned `Multipart` remains available to later validation pipes, so form
+ * fields use the same validation path as JSON bodies.
+ */
+export function multipartPipe(limits: Partial<UploadLimits> = {}): Pipe<unknown, Multipart> {
+  const configured = { ...limits };
+  return {
+    transform(value, ctx): Multipart {
+      return parseMultipart(value, ctx.headers['content-type'] ?? '', configured);
+    },
+  };
+}
+
+/**
+ * A serialization interceptor: transforms the handler's result via `serialize`
+ * (default: identity — the pipeline JSON-encodes downstream). Pass an entity
+ * serializer to shape the response from `Entity<S>`.
+ */
+export function serializationInterceptor(serialize: (result: unknown) => unknown = r => r): Interceptor {
+  return {
+    async intercept(_ctx, next): Promise<unknown> {
+      const result = await next();
+      return serialize(result);
+    },
+  };
+}
+
+/** Options for `dtoChain`. */
+export interface DtoChainOptions<T> {
+  /** The wire→app decode, e.g. `wireDecoder(Schema, 'create')`. Runs before `validate`. */
+  readonly decode?: (raw: unknown) => unknown;
+  readonly validate: (raw: unknown) => T;
+  readonly serialize?: (result: unknown) => unknown;
+}
+
+/**
+ * Compose a Chain with the validation pipe (+ optional decode pipe and
+ * serialization interceptor), so a route adopts DTO validation/serialization in
+ * one call.
+ */
+export function dtoChain<T>(options: DtoChainOptions<T>): Chain {
+  return {
+    guards: [],
+    // Decode first, then validate: the validator checks the app type, which is only what
+    // the body holds once the two types JSON cannot carry have been converted.
+    pipes:
+      options.decode === undefined
+        ? [validationPipe(options.validate)]
+        : [decodePipe(options.decode), validationPipe(options.validate)],
+    interceptors: options.serialize === undefined ? [] : [serializationInterceptor(options.serialize)],
+    filters: [],
+  };
+}

package/src/gateways/index.ts

@@ -0,0 +1,180 @@
+// @zmdb/web — WebSocket & SSE gateways (epic #307, spec ./SPEC.md). @Gateway/
+// @Subscribe store handlers in context.metadata; a dispatcher routes events with
+// a typed message ctx; sseStream frames an async iterable as SSE. No ws
+// dependency, no reflection, no `as` on the consumer surface.
+
+import '@zmdb/app';
+
+/** The context a subscribed handler receives. */
+export interface MessageCtx<T = unknown> {
+  readonly event: string;
+  readonly data: T;
+}
+
+/** A recorded event subscription. */
+export interface Subscription {
+  readonly event: string;
+  readonly handlerName: string;
+}
+
+const NAMESPACE = Symbol('zmdb.web.gateway.namespace');
+const SUBSCRIPTIONS = Symbol('zmdb.web.gateway.subscriptions');
+
+interface GatewayMetadata {
+  [NAMESPACE]?: string;
+  [SUBSCRIPTIONS]?: Subscription[];
+}
+
+// boundary: our @Gateway/@Subscribe decorators are the only writers of these
+// slots, so viewing the record through GatewayMetadata is sound (§2.1).
+function gatewayView(metadata: DecoratorMetadata): GatewayMetadata {
+  return metadata;
+}
+
+/** Stage-3 class decorator: mark a gateway with an optional namespace. */
+export function Gateway(namespace = '') {
+  return function <T extends abstract new (...args: never[]) => unknown>(
+    _target: T,
+    context: ClassDecoratorContext<T>,
+  ): void {
+    gatewayView(context.metadata)[NAMESPACE] = namespace;
+  };
+}
+
+/** Stage-3 method decorator: subscribe the method to an event. */
+export function Subscribe(event: string) {
+  return function (_target: (...args: never[]) => unknown, context: ClassMethodDecoratorContext): void {
+    const handlerName = typeof context.name === 'string' ? context.name : context.name.toString();
+    const view = gatewayView(context.metadata);
+    const existing = view[SUBSCRIPTIONS];
+    if (existing === undefined) {
+      view[SUBSCRIPTIONS] = [{ event, handlerName }];
+    } else {
+      existing.push({ event, handlerName });
+    }
+  };
+}
+
+/** Read a gateway class's subscriptions (declaration order). No reflection. */
+export function getSubscriptions(gateway: abstract new (...args: never[]) => unknown): readonly Subscription[] {
+  const metadata = gateway[Symbol.metadata];
+  if (metadata === undefined || metadata === null) {
+    return [];
+  }
+  return gatewayView(metadata)[SUBSCRIPTIONS] ?? [];
+}
+
+type MessageHandler = (ctx: MessageCtx) => unknown;
+
+/** A dispatcher routing an event+message to the gateway's matching handler. */
+export interface GatewayDispatcher {
+  dispatch(event: string, data: unknown): Promise<unknown>;
+}
+
+/** Build a dispatcher for a gateway instance. */
+export function createGatewayDispatcher(gateway: object): GatewayDispatcher {
+  const ctor = gateway.constructor;
+  const subs = typeof ctor === 'function' ? getSubscriptions(gatewayClass(ctor)) : [];
+  const byEvent = new Map<string, string>();
+  for (const sub of subs) {
+    byEvent.set(sub.event, sub.handlerName);
+  }
+  return {
+    async dispatch(event: string, data: unknown): Promise<unknown> {
+      const handlerName = byEvent.get(event);
+      if (handlerName === undefined) {
+        return undefined;
+      }
+      const handler = readMessageHandler(gateway, handlerName);
+      if (handler === undefined) {
+        return undefined;
+      }
+      return handler({ event, data });
+    },
+  };
+}
+
+type GatewayClass = abstract new (...args: never[]) => unknown;
+
+// boundary: an instance's `.constructor` carries the gateway metadata; narrowing
+// it for getSubscriptions is sound (§2.1).
+function gatewayClass(ctor: Function): GatewayClass {
+  return ctor as GatewayClass;
+}
+
+// boundary: @Subscribe only records names of the gateway's own methods; reading
+// one by name and calling it as a MessageHandler is sound (§2.1).
+function readMessageHandler(gateway: object, name: string): MessageHandler | undefined {
+  const value = Reflect.get(gateway, name);
+  if (typeof value !== 'function') {
+    return undefined;
+  }
+  const bound = value.bind(gateway);
+  return bound as MessageHandler;
+}
+
+/** A Server-Sent-Events frame. */
+export interface SseFrame<T = unknown> {
+  readonly event?: string;
+  readonly data: T;
+}
+
+/** Turn an async iterable of frames into an SSE-framed byte stream. */
+export function sseStream(source: AsyncIterable<SseFrame>): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  const iterator = source[Symbol.asyncIterator]();
+  let state: 'open' | 'cancelling' | 'closed' = 'open';
+  let cancellation: Promise<void> | undefined;
+
+  const cancel = (reason: unknown): Promise<void> => {
+    if (state === 'closed') {
+      return Promise.resolve();
+    }
+    if (cancellation !== undefined) {
+      return cancellation;
+    }
+    state = 'cancelling';
+    cancellation = (async () => {
+      try {
+        await iterator.return?.(reason);
+      } catch {
+        // A client disconnect is normal teardown. This helper has no error
+        // reporter, so a cleanup rejection must not become a server failure;
+        // sources that need reporting own it inside return/finally.
+      } finally {
+        state = 'closed';
+      }
+    })();
+    return cancellation;
+  };
+
+  return new ReadableStream<Uint8Array>({
+    async pull(controller): Promise<void> {
+      if (state !== 'open') {
+        return;
+      }
+      let next: IteratorResult<SseFrame>;
+      try {
+        next = await iterator.next();
+      } catch (error) {
+        if (state !== 'open') {
+          return;
+        }
+        state = 'closed';
+        throw error;
+      }
+      if (state !== 'open') {
+        return;
+      }
+      const { value, done } = next;
+      if (done) {
+        state = 'closed';
+        controller.close();
+        return;
+      }
+      const prefix = value.event === undefined ? '' : `event: ${value.event}\n`;
+      controller.enqueue(encoder.encode(`${prefix}data: ${JSON.stringify(value.data)}\n\n`));
+    },
+    cancel,
+  });
+}

package/src/health/index.ts

@@ -0,0 +1,198 @@
+// @zmdb/web — HTTP liveness and readiness routes (#581, epic #578).
+// Liveness is synchronous by type. Readiness is concurrent, bounded, success-cached,
+// and coalesced while a probe invocation is still waiting.
+
+import type { CheckResult, DetailedCheck, HealthChecks, LivenessCheck, ReadinessCheck } from '@zmdb/app/health';
+
+import { json, type WebResponse } from '../pipeline/index.js';
+
+const DEFAULT_CACHE_MS = 1000;
+const DEADLINE_GRACE_MS = 50;
+
+export interface HealthProbes {
+  readonly live: () => WebResponse;
+  readonly ready: () => Promise<WebResponse>;
+}
+
+export interface DetailedBody {
+  readonly status: 'ok' | 'error';
+  readonly checks: readonly DetailedCheck[];
+}
+
+interface CachedSuccess {
+  readonly expiresAt: number;
+  readonly result: DetailedCheck;
+}
+
+interface CheckState {
+  cached?: CachedSuccess;
+  inFlight?: Promise<DetailedCheck>;
+}
+
+interface ReadinessRunner {
+  run(): Promise<readonly DetailedCheck[]>;
+}
+
+function createCheckState(): CheckState {
+  return {};
+}
+
+function publicResponse(ok: boolean): WebResponse {
+  return json({ status: ok ? 'ok' : 'error' }, ok ? {} : { status: 503 });
+}
+
+function runLiveness(checks: readonly LivenessCheck[]): boolean {
+  for (const check of checks) {
+    try {
+      if (!check.run()) {
+        return false;
+      }
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+function createReadinessRunner(checks: readonly ReadinessCheck[]): ReadinessRunner {
+  const entries = checks.map(check => ({ check, state: createCheckState() }));
+
+  return {
+    run: () => {
+      if (entries.length === 0) {
+        return Promise.resolve([]);
+      }
+
+      const completed: (DetailedCheck | undefined)[] = entries.map(() => undefined);
+      const running = entries.map(({ check, state }, index) =>
+        runReadinessCheck(check, state).then(result => {
+          completed[index] = result;
+          return result;
+        }),
+      );
+      const aggregateDeadline = Math.max(...entries.map(({ check }) => check.timeoutMs)) + DEADLINE_GRACE_MS;
+      const startedAt = Date.now();
+
+      return new Promise(resolve => {
+        let settled = false;
+        const finish = (results: readonly DetailedCheck[]): void => {
+          if (settled) {
+            return;
+          }
+          settled = true;
+          clearTimeout(timer);
+          resolve(results);
+        };
+        const timer = setTimeout(() => {
+          finish(
+            entries.map(
+              ({ check }, index): DetailedCheck =>
+                completed[index] ?? {
+                  name: check.name,
+                  ok: false,
+                  detail: 'timeout',
+                  durationMs: Math.max(0, Date.now() - startedAt),
+                },
+            ),
+          );
+        }, aggregateDeadline);
+
+        void Promise.all(running).then(finish);
+      });
+    },
+  };
+}
+
+function runReadinessCheck(check: ReadinessCheck, state: CheckState): Promise<DetailedCheck> {
+  const now = Date.now();
+  if (state.cached !== undefined) {
+    if (now < state.cached.expiresAt) {
+      return Promise.resolve(state.cached.result);
+    }
+    delete state.cached;
+  }
+  if (state.inFlight !== undefined) {
+    return state.inFlight;
+  }
+
+  const startedAt = now;
+  const controller = new AbortController();
+  const pending = new Promise<DetailedCheck>(resolve => {
+    let settled = false;
+    let timedOut = false;
+    const finish = (result: CheckResult): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(abortTimer);
+      clearTimeout(deadlineTimer);
+      const detailed = {
+        name: check.name,
+        ok: result.ok,
+        ...(result.detail === undefined ? {} : { detail: result.detail }),
+        durationMs: Math.max(0, Date.now() - startedAt),
+      };
+      if (result.ok) {
+        state.cached = {
+          expiresAt: Date.now() + (check.cacheMs ?? DEFAULT_CACHE_MS),
+          result: detailed,
+        };
+      }
+      resolve(detailed);
+    };
+
+    const abortTimer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, check.timeoutMs);
+    const deadlineTimer = setTimeout(() => {
+      finish({ ok: false, detail: 'timeout' });
+    }, check.timeoutMs + DEADLINE_GRACE_MS);
+
+    try {
+      void check.run(controller.signal).then(
+        result => finish(timedOut ? { ok: false, detail: 'timeout' } : result),
+        () => finish(timedOut ? { ok: false, detail: 'timeout' } : { ok: false }),
+      );
+    } catch {
+      finish({ ok: false });
+    }
+  });
+
+  state.inFlight = pending;
+  void pending.finally(() => {
+    if (state.inFlight === pending) {
+      delete state.inFlight;
+    }
+  });
+  return pending;
+}
+
+/** Build the public liveness and readiness handlers from this application's explicit checks. */
+export function healthRoutes(checks: HealthChecks): HealthProbes {
+  const liveness = checks.liveness ?? [];
+  const readiness = createReadinessRunner(checks.readiness ?? []);
+  return {
+    live: () => publicResponse(runLiveness(liveness)),
+    ready: async () => {
+      const results = await readiness.run();
+      return publicResponse(results.every(result => result.ok));
+    },
+  };
+}
+
+/**
+ * Build the opt-in detailed readiness handler.
+ *
+ * Mount this separate handler through the application's normal RouteOptions.guards composition.
+ * The public handlers returned by healthRoutes never expose names, details, or timings.
+ */
+export function detailedReadyRoute(checks: HealthChecks): () => Promise<WebResponse> {
+  const readiness = createReadinessRunner(checks.readiness ?? []);
+  return async () => {
+    const results = await readiness.run();
+    const ok = results.every(result => result.ok);
+    return json({ status: ok ? 'ok' : 'error', checks: results }, ok ? {} : { status: 503 });
+  };
+}

package/src/http-token.ts

@@ -0,0 +1,22 @@
+export function isHttpTokenCode(code: number): boolean {
+  return (
+    (code >= 48 && code <= 57) ||
+    (code >= 65 && code <= 90) ||
+    (code >= 97 && code <= 122) ||
+    code === 33 ||
+    code === 35 ||
+    code === 36 ||
+    code === 37 ||
+    code === 38 ||
+    code === 39 ||
+    code === 42 ||
+    code === 43 ||
+    code === 45 ||
+    code === 46 ||
+    code === 94 ||
+    code === 95 ||
+    code === 96 ||
+    code === 124 ||
+    code === 126
+  );
+}

package/src/index.ts

@@ -0,0 +1,167 @@
+// @zmdb/web — the HTTP adapter for the zmdb application kernel.
+//
+// Stage-3 metadata, DI, modules and lifecycle are installed and owned by
+// @zmdb/app. Importing the web root activates that one metadata baseline before
+// any HTTP decorator is evaluated.
+import '@zmdb/app';
+
+// Controllers & routing (Stage-3 decorators → context.metadata). See ./routing.
+export {
+  Controller,
+  Get,
+  Post,
+  Put,
+  Patch,
+  Delete,
+  Public,
+  getRoutes,
+  isPublic,
+  type RouteDefinition,
+  type ResolvedRoute,
+} from './routing/index.js';
+
+// Inert HTTP declarations and serialisable operation IR. The compiler-backed
+// collector is intentionally available only from `@zmdb/web/contract/compiler`.
+export {
+  defineHttpContract,
+  httpOperation,
+  type AuthorizationCodeFlow,
+  type ClientCredentialsFlow,
+  type CompiledHttpContract,
+  type CompiledHttpOperation,
+  type HttpBodyDeclaration,
+  type HttpBodyIR,
+  type HttpBodyKind,
+  type HttpContractDeclaration,
+  type HttpContractIR,
+  type HttpController,
+  type HttpMethod,
+  type HttpOperationDeclaration,
+  type HttpOperationIR,
+  type HttpOperationTypes,
+  type HttpParameterDeclaration,
+  type HttpParameterIR,
+  type HttpRequestBodyDeclaration,
+  type HttpRequestBodyIR,
+  type HttpResponseDeclaration,
+  type HttpResponseHeaderDeclaration,
+  type HttpResponseHeaderIR,
+  type HttpResponseIR,
+  type HttpTypeIR,
+  type HttpVersionDeclaration,
+  type HttpVersionIR,
+  type ImplicitFlow,
+  type JsonValue,
+  type OAuthFlow,
+  type OAuthFlows,
+  type PasswordFlow,
+  type SecurityRequirement,
+  type SecurityScheme,
+} from './contract/index.js';
+
+// API version declarations and strategy types. See ./versioning.
+export { Version, VersionNeutral, versionsOf, type VersionStrategy } from './versioning/index.js';
+
+// Typed request context + compile-time path-param derivation. See ./context.
+export {
+  extractParams,
+  compilePattern,
+  countSegments,
+  matchCompiled,
+  type CompiledPattern,
+  type PathParams,
+  type QueryValues,
+  type Ctx,
+  type HandlerFor,
+} from './context/index.js';
+
+// Request pipeline & runtime adapters. See ./pipeline.
+export {
+  createRouter,
+  toNodeHandler,
+  toFetchHandler,
+  json,
+  text,
+  respond,
+  bytes,
+  stream,
+  file,
+  bodyText,
+  type Router,
+  type WebRequest,
+  type WebResponse,
+  type ResponseBody,
+  type RouteOptions,
+  type GuardRegistry,
+  type RouterOptions,
+  type ResponseOptions,
+  type StreamOptions,
+  type FileResponseOptions,
+  type AdapterOptions,
+} from './pipeline/index.js';
+
+// Confined static files with validators and single-range streaming. See ./static.
+export { createStaticHandler, type StaticHandler, type StaticOptions } from './static/index.js';
+
+// Incremental, cross-runtime gzip/deflate middleware. See ./compression.
+export { compress, compressionInterceptor, type CompressionOptions, type ContentCoding } from './compression/index.js';
+
+// HTTP router construction over app-owned observability ports.
+export { createTracedRouter } from './traced-router.js';
+
+// HTTP validation and wire conversion. Repository DI tokens are app-owned.
+export { validateWith } from './data/index.js';
+
+// Guards, pipes, interceptors & exception filters. See ./middleware.
+export {
+  runChain,
+  ChainError,
+  type AnyCtx,
+  type Guard,
+  type SecurityAwareGuard,
+  type Pipe,
+  type Interceptor,
+  type ExceptionFilter,
+  type Chain,
+  type ChainHandler,
+} from './middleware/index.js';
+
+// HTTP application bootstrap over one app-owned graph. See ./app.
+export { createApp, type WebApplication, type WebApplicationOptions } from './app/index.js';
+
+// DTO validation & serialization pipes. See ./dto-pipes.
+export {
+  validationPipe,
+  multipartPipe,
+  serializationInterceptor,
+  dtoChain,
+  type DtoChainOptions,
+} from './dto-pipes/index.js';
+
+// Bounded multipart/form-data parsing. See ./upload.
+export { parseMultipart, UPLOAD_DEFAULTS, type Multipart, type UploadLimits, type UploadPart } from './upload/index.js';
+
+// Stateless, session-bound CSRF protection. See ./csrf.
+export { createCsrf, type Csrf, type CsrfOptions } from './csrf/index.js';
+
+// OpenAPI 3.1 projection from the shared HTTP contract IR. See ./openapi.
+export {
+  toOpenApi,
+  serveOpenApi,
+  type JsonSchema,
+  type OpenApiDocument,
+  type OpenApiRenderOptions,
+} from './openapi/index.js';
+
+// WebSocket & SSE gateways. See ./gateways.
+export {
+  Gateway,
+  Subscribe,
+  getSubscriptions,
+  createGatewayDispatcher,
+  sseStream,
+  type MessageCtx,
+  type Subscription,
+  type GatewayDispatcher,
+  type SseFrame,
+} from './gateways/index.js';