@setu-ts/kernel 0.0.0-stage → 0.10.0

package/src/diagnostics/projection.ts

@@ -0,0 +1,322 @@
+/**
+ * Diagnostics projection — the pure half of kernel diagnostics: label
+ * allowlist compilation and bounded primitive projection.
+ *
+ * Every string that can leave the process through a diagnostics snapshot or
+ * event batch passes through the allowlists compiled here, at the capture
+ * boundary and never again. An allowlist is an EXACT set of registration
+ * strings — no globs, no regular expressions — because approving a label is a
+ * disclosure decision the developer makes per name, not a pattern match to be
+ * widened.
+ *
+ * @module
+ */
+import { hasForbiddenAliasCharacter } from '@setu-ts/common';
+import type {
+  DiagnosticsEdge,
+  DiagnosticsNode,
+  DiagnosticsSnapshot,
+  HttpMethod,
+} from '@setu-ts/common';
+
+/**
+ * Explicit label allowlists for the four projected name families. A name
+ * leaves the process only when it exactly matches an entry here; unknown names
+ * authorize no output.
+ *
+ * @since 0.8.0
+ */
+export interface KernelDiagnosticsLabelOptions {
+  /** Exact plugin `name` values that may appear as node labels. */
+  readonly plugins?: readonly string[];
+  /** Exact capability-token strings that may appear as node labels. */
+  readonly capabilities?: readonly string[];
+  /** Exact registered route patterns (including group prefix) that may appear as labels. */
+  readonly routes?: readonly string[];
+  /** Exact declared middleware names that may appear as labels. */
+  readonly middleware?: readonly string[];
+}
+
+/**
+ * Options enabling kernel diagnostics, supplied as
+ * `createApplication({ diagnostics })`. The presence of the option IS the
+ * activation: an omitted option creates no collector, metadata mirror, ring
+ * buffer, or timer anywhere in the kernel.
+ *
+ * @since 0.8.0
+ */
+export interface KernelDiagnosticsOptions {
+  /**
+   * Explicit label allowlists. Omitted entirely, every projected node carries
+   * only its opaque identifier — no name, template, or version ever leaves the
+   * process.
+   */
+  readonly labels?: KernelDiagnosticsLabelOptions;
+}
+
+/** Maximum entries accepted in one label allowlist. */
+export const MAX_LABEL_LIST_ENTRIES = 256;
+
+/** Maximum UTF-8 byte length of one allowlist entry. */
+export const MAX_LABEL_BYTES = 160;
+
+/** A compiled allowlist set per label family. */
+export interface DiagnosticsLabelAllowlists {
+  readonly plugins: ReadonlySet<string>;
+  readonly capabilities: ReadonlySet<string>;
+  readonly routes: ReadonlySet<string>;
+  readonly middleware: ReadonlySet<string>;
+}
+
+/**
+ * Compiles one allowlist, refusing malformed input with VALUE-FREE errors: an
+ * error must state the constraint it enforces, never echo the offending value,
+ * because a construction-time diagnostic failure is an attacker-reachable path
+ * for whatever the list contains.
+ *
+ * @param entries - The raw allowlist, or `undefined` for an empty set
+ * @param listName - Family name used in the error text only
+ * @returns The compiled exact-match set
+ * @throws {RangeError} When the list exceeds 256 entries, an entry exceeds 160
+ * UTF-8 bytes, or an entry contains a control character — without naming any entry
+ * @since 0.8.0
+ */
+export function compileLabelAllowlist(
+  entries: readonly string[] | undefined,
+  listName: string,
+): ReadonlySet<string> {
+  if (entries === undefined) {
+    return new Set<string>();
+  }
+  if (entries.length > MAX_LABEL_LIST_ENTRIES) {
+    throw new RangeError(
+      `Invalid diagnostics labels.${listName}: more than ${MAX_LABEL_LIST_ENTRIES} entries.`,
+    );
+  }
+  const compiled = new Set<string>();
+  for (const entry of entries) {
+    const bytes = new TextEncoder().encode(entry).length;
+    if (bytes > MAX_LABEL_BYTES) {
+      throw new RangeError(
+        `Invalid diagnostics labels.${listName}: an entry exceeds the ${MAX_LABEL_BYTES}-byte bound.`,
+      );
+    }
+    if (hasForbiddenAliasCharacter(entry)) {
+      throw new RangeError(
+        `Invalid diagnostics labels.${listName}: an entry contains a control, format or line-separator character.`,
+      );
+    }
+    compiled.add(entry);
+  }
+  return compiled;
+}
+
+/**
+ * Compiles every label family of a {@linkcode KernelDiagnosticsOptions}.
+ *
+ * @param options - The diagnostics options, or `undefined` for all-empty lists
+ * @returns The compiled allowlists
+ * @throws {RangeError} When any list is malformed (see {@linkcode compileLabelAllowlist})
+ * @since 0.8.0
+ */
+export function compileLabelAllowlists(
+  options: KernelDiagnosticsOptions | undefined,
+): DiagnosticsLabelAllowlists {
+  const labels = options?.labels;
+  return {
+    plugins: compileLabelAllowlist(labels?.plugins, 'plugins'),
+    capabilities: compileLabelAllowlist(labels?.capabilities, 'capabilities'),
+    routes: compileLabelAllowlist(labels?.routes, 'routes'),
+    middleware: compileLabelAllowlist(labels?.middleware, 'middleware'),
+  };
+}
+
+/**
+ * Projects a candidate registration string through an allowlist.
+ *
+ * Exact membership, never a truncation: a name either IS an approved label or
+ * it is omitted — truncating a 200-byte route pattern into an approved-looking
+ * prefix would mint a new name that was never disclosed on purpose.
+ *
+ * @param allowlist - The compiled exact-match set for this family
+ * @param candidate - The raw registration string
+ * @returns The candidate itself when approved, `undefined` otherwise
+ * @since 0.8.0
+ */
+export function approvedLabel(
+  allowlist: ReadonlySet<string>,
+  candidate: string,
+): string | undefined {
+  return allowlist.has(candidate) ? candidate : undefined;
+}
+
+const HTTP_METHODS: ReadonlySet<string> = new Set([
+  'GET',
+  'HEAD',
+  'POST',
+  'PUT',
+  'PATCH',
+  'DELETE',
+  'OPTIONS',
+]);
+
+/**
+ * Projects a method string onto the {@linkcode HttpMethod} vocabulary.
+ * Unsupported input is omitted, never widened into a new name.
+ *
+ * @param method - The raw method string from a registration
+ * @returns The known verb, or `undefined` when outside the vocabulary
+ * @since 0.8.0
+ */
+export function projectHttpMethod(method: string): HttpMethod | undefined {
+  return HTTP_METHODS.has(method) ? (method as HttpMethod) : undefined;
+}
+
+/**
+ * Bounded plugin-version grammar. A version is emitted only when it is a plain
+ * `major.minor.patch` semver (optionally with prerelease/build suffixes) within
+ * 64 characters — anything else (a git sha, a sentence, a hostile string) is
+ * omitted rather than projected.
+ *
+ * @param version - The raw plugin `version` string
+ * @returns The version when it passes the bounded grammar, `undefined` otherwise
+ * @since 0.8.0
+ */
+export function boundedPluginVersion(version: string): string | undefined {
+  if (version.length === 0 || version.length > 64) {
+    return undefined;
+  }
+  const bounded = /^\d{1,5}\.\d{1,5}\.\d{1,5}(?:-[0-9A-Za-z.-]{1,64})?(?:\+[0-9A-Za-z.-]{1,64})?$/;
+  return bounded.test(version) ? version : undefined;
+}
+
+/**
+ * Inclusive monotonic elapsed time for one observed boundary.
+ *
+ * @param clock - The injected monotonic clock
+ * @param startedAtMs - The boundary's recorded start offset, or `null`
+ * @returns Elapsed ms, or `null` when either reading was unavailable
+ * @since 0.8.0
+ */
+export function monotonicElapsed(
+  clock: () => number | null,
+  startedAtMs: number | null,
+): number | null {
+  if (startedAtMs === null) {
+    return null;
+  }
+  const finishedAtMs = clock();
+  return finishedAtMs === null ? null : finishedAtMs - startedAtMs;
+}
+
+/**
+ * Advances a monotonic counter with saturation at `Number.MAX_SAFE_INTEGER`.
+ * Returns `null` at saturation, which callers treat as "stop collection": a
+ * coarse failure state long before any identifier could wrap into a
+ * misleading value.
+ *
+ * @param current - The current counter value
+ * @returns The next value, or `null` when the counter is saturated
+ * @since 0.8.0
+ */
+export function saturatingNext(current: number): number | null {
+  return current >= Number.MAX_SAFE_INTEGER ? null : current + 1;
+}
+
+/** Fixed v1 limits: composition nodes retained by the collector. */
+export const MAX_NODES = 1024;
+
+/** Fixed v1 limits: composition edges retained by the collector. */
+export const MAX_EDGES = 4096;
+
+/** Fixed v1 limits: snapshot budget as the exact UTF-8 byte length of the compact JSON. */
+export const MAX_SNAPSHOT_BYTES = 262_144;
+
+/**
+ * Applies the fixed 256 KiB snapshot budget to the final DTO: the exact UTF-8
+ * byte length of the compact JSON encoding of the RETURNED object is the
+ * number the wire consumer measures, so trimming runs on the final shape —
+ * omitting later entries (with their edges) and setting `truncated` until it
+ * fits.
+ *
+ * Extracted as a pure seam because the retained-field bounds make the budget
+ * unreachable through real captures (1,024 bounded nodes stay well under the
+ * cap); the defense still carries the bar, so the decidable trim is tested
+ * here directly rather than left behind an uncoverable branch.
+ *
+ * @param scalar - The snapshot's scalar members (instanceId, state, failureCode, droppedEvents)
+ * @param nodes - The projected nodes, oldest first
+ * @param edges - The projected edges, oldest first
+ * @param truncated - The topology truncation flag
+ * @returns The bounded snapshot DTO
+ * @since 0.8.0
+ */
+export function applySnapshotBudget(
+  scalar: {
+    readonly instanceId: string | null;
+    readonly state: DiagnosticsSnapshot['state'];
+    readonly failureCode: DiagnosticsSnapshot['failureCode'];
+    readonly droppedEvents: number;
+  },
+  nodes: readonly DiagnosticsNode[],
+  edges: readonly DiagnosticsEdge[],
+  truncated: boolean,
+): DiagnosticsSnapshot {
+  const encoder = new TextEncoder();
+  const build = (
+    keptNodes: readonly DiagnosticsNode[],
+    keptEdges: readonly DiagnosticsEdge[],
+    isTruncated: boolean,
+  ): DiagnosticsSnapshot => ({
+    version: 1,
+    instanceId: scalar.instanceId,
+    state: scalar.state,
+    failureCode: scalar.failureCode,
+    nodes: keptNodes,
+    edges: keptEdges,
+    truncated: isTruncated,
+    droppedEvents: scalar.droppedEvents,
+  });
+  const measure = (candidate: DiagnosticsSnapshot): number =>
+    encoder.encode(JSON.stringify(candidate)).length;
+
+  // Fast path: nothing to trim. Returning the inputs untouched also keeps the
+  // untrimmed shape EXACTLY as it was — an edge whose endpoint is somehow
+  // absent from `nodes` survives here, as it always did, rather than being
+  // silently dropped by the retained-id filter below.
+  const whole = build(nodes, edges, truncated);
+  if (measure(whole) <= MAX_SNAPSHOT_BYTES) {
+    return whole;
+  }
+
+  // Trimming keeps a PREFIX of the nodes, and dropping a suffix entry can only
+  // shrink the encoding — so the encoded length is monotone in the retained
+  // count and the largest fitting prefix is found by bisection. Dropping one
+  // node per measurement instead is quadratic: 4,000 nodes cost ~2,700 full
+  // `JSON.stringify` + encode passes (measured at ~1,000 ms) where bisection
+  // costs ~12 (~4 ms). The measurement itself is unchanged — every candidate
+  // is the exact compact UTF-8 length of the snapshot that would be returned.
+  const at = (count: number): DiagnosticsSnapshot => {
+    const keptNodes = nodes.slice(0, count);
+    const keptIds = new Set(keptNodes.map((node) => node.id));
+    // Equivalent to the cumulative per-drop filter: an edge survives exactly
+    // when neither endpoint was dropped.
+    const keptEdges = edges.filter((edge) => keptIds.has(edge.from) && keptIds.has(edge.to));
+    return build(keptNodes, keptEdges, true);
+  };
+
+  let low = 0;
+  let high = nodes.length - 1;
+  let best = at(0);
+  while (low <= high) {
+    const mid = (low + high) >> 1;
+    const candidate = at(mid);
+    if (measure(candidate) <= MAX_SNAPSHOT_BYTES) {
+      best = candidate;
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+  return best;
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @module
+ *
+ * Plugin kernel: plugin registry, service registry, middleware pipeline, router,
+ * and application lifecycle.
+ *
+ * Every export here is public API and documented in PUBLIC_API.md
+ * (AI_GUIDELINES §10).
+ */
+
+export type {
+  ApplicationOptions,
+  IKernelApplication,
+  InjectRequest,
+  InjectResponse,
+  KernelDiagnosticsLabelOptions,
+  KernelDiagnosticsOptions,
+} from './application/application.ts';
+
+export { createApplication } from './application/application.ts';

package/src/lifecycle/lifecycle-manager.ts

@@ -0,0 +1,282 @@
+/**
+ * Lifecycle manager — registers and executes lifecycle hooks in the correct
+ * ordering. Shutdown hooks run in reverse (LIFO) for proper cleanup.
+ *
+ * @module
+ */
+import type { IRequestContext } from '@setu-ts/common';
+import type { ILifecycleApi } from '@setu-ts/common';
+
+import { monotonicElapsed } from '../diagnostics/projection.ts';
+
+type VoidHook = () => void | Promise<void>;
+type RequestHook = (ctx: IRequestContext) => void | Promise<void>;
+type ErrorHook = (error: Error, ctx: IRequestContext) => void | Promise<void>;
+
+/**
+ * The lifecycle phases the manager itself drains, named exactly as the
+ * diagnostics stage vocabulary spells them. The request-scoped hooks
+ * (`onRequest`/`onResponse`/`onError`) are invoked by the application and
+ * observed there.
+ *
+ * @since 0.8.0
+ */
+export type LifecycleHookPhase =
+  'register-hook' | 'init' | 'bootstrap' | 'stopping' | 'shutdown' | 'close';
+
+/**
+ * One hook invocation observed with its fixed phase plus execution ordinal —
+ * ownership is NEVER inferred, because the manager does not record it.
+ *
+ * @since 0.8.0
+ */
+export interface LifecycleHookObservation {
+  /** The lifecycle phase being drained. */
+  readonly phase: LifecycleHookPhase;
+  /** 1-based EXECUTION order within the phase (LIFO phases count downward). */
+  readonly ordinal: number;
+  /** Whether the hook threw (the error itself is never retained). */
+  readonly failed: boolean;
+  /** Monotonic start offset, or `null` when no runtime clock is available. */
+  readonly startedAtMs: number | null;
+  /** Inclusive monotonic elapsed ms, or `null`. */
+  readonly durationMs: number | null;
+}
+
+/**
+ * The diagnostics observer the application passes to instrument hook
+ * execution. Observation never changes hook ordering, aggregation, or
+ * propagation semantics.
+ *
+ * @since 0.8.0
+ */
+export interface LifecycleObserver {
+  /** Monotonic clock; returns `null` when no runtime clock is available. */
+  readonly clock: () => number | null;
+  /** Called once per executed hook, in execution order. */
+  readonly onHook: (observation: LifecycleHookObservation) => void;
+}
+
+/**
+ * Default implementation of {@linkcode ILifecycleApi}. Stores hook arrays
+ * and exposes execution methods for each lifecycle phase.
+ */
+export class LifecycleManager implements ILifecycleApi {
+  readonly #register: VoidHook[] = [];
+  /** Count of onRegister hooks already drained by {@linkcode runRegister}. */
+  #registerCursor = 0;
+  readonly #init: VoidHook[] = [];
+  readonly #bootstrap: VoidHook[] = [];
+  readonly #request: RequestHook[] = [];
+  readonly #response: RequestHook[] = [];
+  readonly #error: ErrorHook[] = [];
+  readonly #stopping: VoidHook[] = [];
+  readonly #shutdown: VoidHook[] = [];
+  readonly #close: VoidHook[] = [];
+  #observer: LifecycleObserver | undefined;
+
+  /**
+   * Installs the diagnostics observer for hook invocations. Pass `undefined`
+   * to detach (teardown).
+   *
+   * @param observer - The observer, or `undefined`
+   * @since 0.8.0
+   */
+  setLifecycleObserver(observer: LifecycleObserver | undefined): void {
+    this.#observer = observer;
+  }
+
+  onRegister(fn: () => void | Promise<void>): void {
+    this.#register.push(fn);
+  }
+
+  onInit(fn: () => void | Promise<void>): void {
+    this.#init.push(fn);
+  }
+
+  onBootstrap(fn: () => void | Promise<void>): void {
+    this.#bootstrap.push(fn);
+  }
+
+  onRequest(fn: (ctx: IRequestContext) => void | Promise<void>): void {
+    this.#request.push(fn);
+  }
+
+  onResponse(fn: (ctx: IRequestContext) => void | Promise<void>): void {
+    this.#response.push(fn);
+  }
+
+  onError(fn: (error: Error, ctx: IRequestContext) => void | Promise<void>): void {
+    this.#error.push(fn);
+  }
+
+  onStopping(fn: () => void | Promise<void>): void {
+    this.#stopping.push(fn);
+  }
+
+  onShutdown(fn: () => void | Promise<void>): void {
+    this.#shutdown.push(fn);
+  }
+
+  onClose(fn: () => void | Promise<void>): void {
+    this.#close.push(fn);
+  }
+
+  /**
+   * Runs onRegister hooks added since the previous call, in registration
+   * order. The kernel invokes this immediately after each plugin's
+   * `register()` returns, so a plugin's onRegister hooks run "during the
+   * owning plugin's registration" (per {@linkcode ILifecycleApi.onRegister})
+   * — after that plugin and before the next one. A cursor tracks how many
+   * hooks have already run so each plugin only fires the hooks it added; a
+   * hook that registers a further onRegister hook drains it in the same pass.
+   */
+  async runRegister(): Promise<void> {
+    while (this.#registerCursor < this.#register.length) {
+      const fn = this.#register[this.#registerCursor]!;
+      this.#registerCursor++;
+      await this.#runObserved('register-hook', this.#registerCursor, fn);
+    }
+  }
+
+  /** Runs all onInit hooks in registration order. */
+  async runInit(): Promise<void> {
+    let ordinal = 0;
+    for (const fn of this.#init) {
+      ordinal++;
+      await this.#runObserved('init', ordinal, fn);
+    }
+  }
+
+  /** Runs all onBootstrap hooks in registration order. */
+  async runBootstrap(): Promise<void> {
+    let ordinal = 0;
+    for (const fn of this.#bootstrap) {
+      ordinal++;
+      await this.#runObserved('bootstrap', ordinal, fn);
+    }
+  }
+
+  /**
+   * Whether any onStopping hook is registered.
+   *
+   * `Application` checks this rather than awaiting unconditionally: awaiting
+   * an already-resolved promise still defers the rest of `stop()` by a
+   * microtask, which would move when `#stopping` flips and change the answer a
+   * request arriving in that same tick gets. Branching keeps the new phase
+   * genuinely zero-width for an application that registers no hook.
+   */
+  hasStopping(): boolean {
+    return this.#stopping.length > 0;
+  }
+
+  /**
+   * Runs stopping hooks in reverse registration order (LIFO), before the
+   * application starts refusing requests.
+   */
+  async runStopping(): Promise<void> {
+    for (let i = this.#stopping.length - 1; i >= 0; i--) {
+      await this.#runObserved('stopping', this.#stopping.length - i, this.#stopping[i]!);
+    }
+  }
+
+  /** Runs shutdown hooks in reverse registration order (LIFO cleanup). */
+  async runShutdown(): Promise<void> {
+    for (let i = this.#shutdown.length - 1; i >= 0; i--) {
+      await this.#runObserved('shutdown', this.#shutdown.length - i, this.#shutdown[i]!);
+    }
+  }
+
+  /**
+   * Runs close hooks in registration order (after shutdown completes).
+   *
+   * EVERY hook runs, even when an earlier one rejects: a close hook releases
+   * one plugin's resources, and letting the first failure abort the loop meant
+   * one plugin that could not disconnect kept every later plugin from
+   * releasing anything — the M50 `onStopping` defect in a second place. The
+   * caller still learns about the failures, from an `AggregateError` raised
+   * once the whole list has run; a single failure is rethrown as itself, so an
+   * existing `instanceof` check on the hook's own error still matches.
+   *
+   * @throws {AggregateError} When more than one hook rejected
+   */
+  async runClose(): Promise<void> {
+    const errors: unknown[] = [];
+    let ordinal = 0;
+    for (const fn of this.#close) {
+      ordinal++;
+      try {
+        await this.#runObserved('close', ordinal, fn);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length === 1) {
+      throw errors[0];
+    }
+    if (errors.length > 1) {
+      throw new AggregateError(errors, 'One or more close hooks failed.');
+    }
+  }
+
+  /**
+   * Returns the request hooks list for the application to invoke during
+   * request processing.
+   */
+  getRequestHooks(): readonly RequestHook[] {
+    return this.#request;
+  }
+
+  /**
+   * Returns the response hooks list for the application to invoke after
+   * the response is produced.
+   */
+  getResponseHooks(): readonly RequestHook[] {
+    return this.#response;
+  }
+
+  /**
+   * Returns the error hooks list for the application to invoke when an
+   * error escapes middleware or a handler.
+   */
+  getErrorHooks(): readonly ErrorHook[] {
+    return this.#error;
+  }
+
+  /**
+   * Runs one hook, observing its completion when an observer is installed.
+   * With no observer this is a bare `await fn()` — zero added work. A
+   * throwing hook is recorded as `failed` (never with the error itself) and
+   * re-thrown with its identity intact, so ordering, aggregation, and
+   * propagation semantics are unchanged.
+   */
+  async #runObserved(phase: LifecycleHookPhase, ordinal: number, fn: VoidHook): Promise<void> {
+    const observer = this.#observer;
+    if (observer === undefined) {
+      await fn();
+      return;
+    }
+    const startedAtMs = observer.clock();
+    let failed = false;
+    try {
+      await fn();
+    } catch (error) {
+      failed = true;
+      observer.onHook({
+        phase,
+        ordinal,
+        failed,
+        startedAtMs,
+        durationMs: monotonicElapsed(observer.clock, startedAtMs),
+      });
+      throw error;
+    }
+    observer.onHook({
+      phase,
+      ordinal,
+      failed,
+      startedAtMs,
+      durationMs: monotonicElapsed(observer.clock, startedAtMs),
+    });
+  }
+}