@setu-ts/kernel 0.0.0-bootstrap.0 → 0.9.0

package/src/pipeline/execute-chain.ts

@@ -0,0 +1,164 @@
+/**
+ * Shared middleware-chain executor — classic next()-chaining with a
+ * double-`next` guard and defense-in-depth against a stage that responds
+ * AND calls `next()`.
+ *
+ * Both the global pipeline ({@linkcode MiddlewarePipeline}) and the
+ * per-route middleware chain (dispatched from the application) delegate to
+ * this helper so the chaining semantics are defined in exactly one place
+ * (AI_GUIDELINES §11.1 — DRY).
+ *
+ * @module
+ */
+import type { DiagnosticsEventOutcome, IRequestContext, MiddlewareFunction } from '@setu-ts/common';
+
+import type { ResponseBuilder } from '../context/response.ts';
+import { monotonicElapsed } from '../diagnostics/projection.ts';
+
+/**
+ * One executed stage's completion record, reported in actual completion order.
+ * Skipped stages (the defense-in-depth early returns) emit no record.
+ *
+ * @since 0.8.0
+ */
+export interface ChainStageObservation {
+  /** 0-based index of the stage in the chain it was registered in. */
+  readonly position: number;
+  /** How the stage completed. */
+  readonly outcome: Extract<
+    DiagnosticsEventOutcome,
+    'ok' | 'error' | 'short-circuit' | 'downstream-skipped'
+  >;
+  /** Monotonic start offset, or `null` when no runtime clock is available. */
+  readonly startedAtMs: number | null;
+  /** Inclusive monotonic elapsed ms (including downstream `next()` work). */
+  readonly durationMs: number | null;
+}
+
+/**
+ * The diagnostics observer the application passes to instrument a chain. The
+ * clock is injected because observation must not read ambient time.
+ *
+ * @since 0.8.0
+ */
+export interface ChainObserver {
+  /** Monotonic clock; returns `null` when no runtime clock is available. */
+  readonly clock: () => number | null;
+  /** Called once per EXECUTED stage, in completion order. */
+  readonly onStage: (observation: ChainStageObservation) => void;
+}
+
+/**
+ * Executes a chain of middleware with classic `next()`-chaining semantics.
+ *
+ * Each middleware receives a `next` function that advances to the next
+ * stage. A stage that returns without calling `next()` short-circuits the
+ * chain — subsequent stages and the terminal are not invoked. As
+ * defense-in-depth, before invoking the next stage (and before the
+ * terminal) the executor also checks `ResponseBuilder.ended` on
+ * `ctx.response`: if a stage has already produced a terminal response
+ * (e.g. called `json()`), downstream stages are skipped even if that
+ * stage incorrectly called `next()`.
+ *
+ * @param chain - The ordered middleware functions to execute
+ * @param ctx - The request context (its `response` is a {@linkcode ResponseBuilder})
+ * @param terminal - Called when every middleware has called `next()`
+ * @param names - Optional diagnostic names, positionally matching `chain`, used
+ * to identify the offending stage in the double-`next()` error. The global
+ * pipeline supplies the names registered through `MiddlewareOptions.name`;
+ * route-level chains have none and fall back to the function's own name.
+ * @param observer - Optional diagnostics observer. When absent the executor
+ * performs no additional work beyond the original path; when present, each
+ * stage's completion is observed inline without changing dispatch semantics —
+ * a throw is recorded and re-thrown with its identity intact, and the
+ * `downstream-skipped` outcome records a stage that called `next()` after the
+ * response had already ended.
+ * @throws {Error} If `next()` is called multiple times within a single middleware
+ * @since 0.1.0
+ */
+export async function executeChain(
+  chain: readonly MiddlewareFunction[],
+  ctx: IRequestContext,
+  terminal: () => Promise<void>,
+  names?: readonly string[],
+  observer?: ChainObserver,
+): Promise<void> {
+  let index = 0;
+
+  // Defense in depth: stop once a prior stage has ended the response. The
+  // check is guarded so callers passing a minimal context (e.g. the
+  // pipeline unit tests with an empty object) don't crash on a missing
+  // `response` — only a real ResponseBuilder exposes `ended`.
+  const responseEnded = (): boolean => {
+    const response = ctx.response as Partial<ResponseBuilder> | undefined;
+    return typeof response?.ended === 'boolean' ? response.ended : false;
+  };
+
+  const elapsed = (startedAtMs: number | null): number | null =>
+    observer === undefined ? null : monotonicElapsed(observer.clock, startedAtMs);
+
+  const run = async (): Promise<void> => {
+    if (index >= chain.length) {
+      // Defense in depth: do not run the terminal if a prior stage
+      // already ended the response.
+      if (responseEnded()) {
+        return;
+      }
+      await terminal();
+      return;
+    }
+    // Defense in depth: a prior stage ended the response — stop.
+    if (responseEnded()) {
+      return;
+    }
+    const fn = chain[index]!;
+    const position = index;
+    index++;
+    let nextCalled = false;
+    let downstreamSkipped = false;
+    const next: () => Promise<void> = () => {
+      if (nextCalled) {
+        // Prefer the name registered via `MiddlewareOptions.name`, then the
+        // function's own name. `fn.name` is ALWAYS a string — `''` for an
+        // anonymous function — so `??` never fell back and the message read
+        // "…in middleware " with a blank name. `||` is the correct operator.
+        const label = names?.[position] || fn.name || '<anonymous>';
+        throw new Error(
+          `next() called multiple times in middleware ${label}`,
+        );
+      }
+      nextCalled = true;
+      if (observer !== undefined && responseEnded()) {
+        // The stage called next() after ending the response; run()'s own
+        // ended check below will skip the downstream. Recorded for the
+        // caller's completion record — the outcome, not a new behavior.
+        downstreamSkipped = true;
+      }
+      return run();
+    };
+    const startedAtMs = observer === undefined ? null : observer.clock();
+    try {
+      await fn(ctx, next);
+    } catch (error) {
+      if (observer !== undefined) {
+        observer.onStage({
+          position,
+          outcome: 'error',
+          startedAtMs,
+          durationMs: elapsed(startedAtMs),
+        });
+      }
+      throw error;
+    }
+    if (observer !== undefined) {
+      observer.onStage({
+        position,
+        outcome: !nextCalled ? 'short-circuit' : downstreamSkipped ? 'downstream-skipped' : 'ok',
+        startedAtMs,
+        durationMs: elapsed(startedAtMs),
+      });
+    }
+  };
+
+  await run();
+}

package/src/pipeline/middleware-pipeline.ts

@@ -0,0 +1,131 @@
+/**
+ * Middleware pipeline — ASP.NET Core-style ordered execution with priority
+ * bands, short-circuiting, and double-next protection.
+ *
+ * @module
+ */
+import type {
+  IMiddlewareApi,
+  IRequestContext,
+  MiddlewareFunction,
+  MiddlewareOptions,
+} from '@setu-ts/common';
+
+import { executeChain } from './execute-chain.ts';
+import type { ChainObserver } from './execute-chain.ts';
+
+interface MiddlewareEntry {
+  fn: MiddlewareFunction;
+  priority: number;
+  name: string;
+  index: number;
+}
+
+const DEFAULT_PRIORITY = 500;
+
+/**
+ * One compiled global middleware stage, projected for diagnostics: the
+ * declared name, its priority, and its execution position in the stable
+ * priority sort.
+ *
+ * @since 0.8.0
+ */
+export interface MiddlewareStageDescriptor {
+  /** The name passed through `MiddlewareOptions`, or the generated placeholder. */
+  readonly name: string;
+  /** The stage's execution priority. */
+  readonly priority: number;
+  /** 1-based execution position in the compiled chain. */
+  readonly position: number;
+}
+
+/**
+ * Middleware pipeline: collect middleware with priorities, compile into a
+ * sorted chain, then execute with classic next()-chaining semantics.
+ */
+export class MiddlewarePipeline implements IMiddlewareApi {
+  readonly #entries: MiddlewareEntry[] = [];
+  #compiled: MiddlewareFunction[] | null = null;
+  /** Diagnostic names, positionally matching {@linkcode MiddlewarePipeline.compile}'s output. */
+  #compiledNames: string[] | null = null;
+  /** Compiled stage descriptors, positionally matching the chain (diagnostics seam). */
+  #compiledDescriptors: MiddlewareStageDescriptor[] | null = null;
+
+  add(middleware: MiddlewareFunction, options?: MiddlewareOptions): void {
+    if (this.#compiled !== null) {
+      throw new Error('Cannot add middleware after the pipeline has been compiled.');
+    }
+    this.#entries.push({
+      fn: middleware,
+      priority: options?.priority ?? DEFAULT_PRIORITY,
+      name: options?.name ?? `<anonymous-${this.#entries.length}>`,
+      index: this.#entries.length,
+    });
+  }
+
+  /**
+   * Sorts middleware stably by (priority, insertion order) and freezes the
+   * chain. After calling, no further middleware may be added.
+   */
+  compile(): readonly MiddlewareFunction[] {
+    if (this.#compiled !== null) {
+      return this.#compiled;
+    }
+    const sorted = [...this.#entries].sort(
+      (a, b) => a.priority - b.priority || a.index - b.index,
+    );
+    this.#compiled = sorted.map((entry) => entry.fn);
+    this.#compiledNames = sorted.map((entry) => entry.name);
+    this.#compiledDescriptors = sorted.map((entry, position) => ({
+      name: entry.name,
+      priority: entry.priority,
+      position: position + 1,
+    }));
+    return this.#compiled;
+  }
+
+  /**
+   * Diagnostic names of the compiled chain, in execution order.
+   *
+   * Each entry is the `name` passed through {@linkcode MiddlewareOptions}, or a
+   * generated `<anonymous-N>` placeholder. Returns an empty array before
+   * {@linkcode MiddlewarePipeline.compile} runs.
+   *
+   * @returns The compiled stage names, positionally matching the compiled chain
+   * @internal Diagnostics seam — the kernel passes these to `executeChain` so a
+   * double-`next()` error can name the offending stage.
+   */
+  compiledNames(): readonly string[] {
+    return this.#compiledNames ?? [];
+  }
+
+  /**
+   * The compiled stages projected as bounded descriptors, in execution order.
+   *
+   * @returns Empty before {@linkcode MiddlewarePipeline.compile} runs
+   * @internal Diagnostics seam — the collector captures these once, at
+   * compile, so middleware nodes and stage records carry the same identity.
+   * @since 0.8.0
+   */
+  compiledDescriptors(): readonly MiddlewareStageDescriptor[] {
+    return this.#compiledDescriptors ?? [];
+  }
+
+  /**
+   * Executes the compiled pipeline using classic next()-chaining.
+   *
+   * @param ctx - The request context
+   * @param terminal - Called when all middleware have completed
+   * @param observer - Optional diagnostics observer, forwarded to the shared
+   * chain executor; absent performs no additional work
+   * @throws {Error} If next() is called multiple times in a single middleware
+   */
+  async execute(
+    ctx: IRequestContext,
+    terminal: () => Promise<void>,
+    observer?: ChainObserver,
+  ): Promise<void> {
+    const chain = this.#compiled ?? this.compile();
+    await executeChain(chain, ctx, terminal, this.compiledNames(), observer);
+  }
+}

package/src/registry/plugin-resolver.ts

@@ -0,0 +1,185 @@
+/**
+ * Plugin dependency resolution: topological sort with cycle detection,
+ * priority ordering, and the mandatory-runtime-first rule
+ * (ARCHITECTURE.md §5, §7).
+ *
+ * @module
+ */
+import { CAPABILITIES } from '@setu-ts/common';
+import type { CapabilityToken, IPlugin } from '@setu-ts/common';
+
+/**
+ * Resolves plugin registration order.
+ *
+ * Order is determined by: dependency edges first (a plugin's dependencies
+ * register before it), then declared priority (lower first), then original
+ * registration order. The plugin providing the `runtime` capability always
+ * registers first, regardless of priority.
+ */
+export function resolvePluginOrder(plugins: readonly IPlugin[]): readonly IPlugin[] {
+  assertUniqueNames(plugins);
+  const providers = buildProviderIndex(plugins);
+
+  const runtimeProvider = providers.get(CAPABILITIES.RUNTIME);
+  if (runtimeProvider === undefined) {
+    throw new Error(
+      `No plugin provides the mandatory '${CAPABILITIES.RUNTIME}' capability. ` +
+        `Register a runtime plugin (e.g. RuntimePlugin from @setu-ts/runtime).`,
+    );
+  }
+
+  const dependenciesOf = (plugin: IPlugin): IPlugin[] => {
+    const edges: IPlugin[] = [];
+    // Every plugin implicitly depends on the runtime provider so it can rely
+    // on ctx.runtime during registration.
+    if (plugin !== runtimeProvider) {
+      edges.push(runtimeProvider);
+    }
+    for (const token of plugin.dependencies ?? []) {
+      const provider = providers.get(token);
+      if (provider === undefined) {
+        throw new Error(
+          `Plugin '${plugin.name}' depends on capability '${token}', but no registered plugin provides it.`,
+        );
+      }
+      if (provider !== plugin) {
+        edges.push(provider);
+      }
+    }
+    for (const token of plugin.optionalDependencies ?? []) {
+      const provider = providers.get(token);
+      if (provider !== undefined && provider !== plugin) {
+        edges.push(provider);
+      }
+    }
+    return edges;
+  };
+
+  return topologicalSort(plugins, dependenciesOf);
+}
+
+/**
+ * One plugin's declared `consumes` capability for which no provider exists.
+ * Used to build a soft startup diagnostic in the application.
+ *
+ * Unlike a missing {@linkcode IPlugin.dependencies} entry (which throws in
+ * {@linkcode resolvePluginOrder}), an unsatisfied `consumes` is not a
+ * resolve-time error: the plugin resolves the capability lazily at request
+ * time, so the failure would otherwise surface only later, as a runtime throw
+ * from `services.get`. Reporting it at startup names the consumer up front.
+ */
+export interface UnsatisfiedConsumer {
+  /** Name of the plugin that declares the consumed capability. */
+  readonly plugin: string;
+  /** The consumed capability token that no registered plugin provides. */
+  readonly capability: CapabilityToken;
+}
+
+/**
+ * Finds every `consumes` capability, across all plugins, that `isProvided`
+ * reports as absent.
+ *
+ * Pure by design: the caller supplies the provider check — in the kernel, the
+ * live service registry's `has` after all plugins have registered, so
+ * capabilities registered imperatively (not declared in `provides`) still
+ * count as satisfied and never produce a false warning.
+ *
+ * @param plugins - All registered plugins
+ * @param isProvided - Predicate: does a provider exist for this capability?
+ * @returns One entry per unsatisfied (plugin, capability) pair, in plugin then
+ * declaration order
+ */
+export function findUnsatisfiedConsumers(
+  plugins: readonly IPlugin[],
+  isProvided: (token: CapabilityToken) => boolean,
+): readonly UnsatisfiedConsumer[] {
+  const unsatisfied: UnsatisfiedConsumer[] = [];
+  for (const plugin of plugins) {
+    for (const capability of plugin.consumes ?? []) {
+      if (!isProvided(capability)) {
+        unsatisfied.push({ plugin: plugin.name, capability });
+      }
+    }
+  }
+  return unsatisfied;
+}
+
+function assertUniqueNames(plugins: readonly IPlugin[]): void {
+  const seen = new Set<string>();
+  for (const plugin of plugins) {
+    if (seen.has(plugin.name)) {
+      throw new Error(
+        `Duplicate plugin name '${plugin.name}'. To replace a plugin, register the ` +
+          `replacement's services with { override: true } instead of reusing the name.`,
+      );
+    }
+    seen.add(plugin.name);
+  }
+}
+
+/**
+ * Indexes which plugin provides each capability token. A plugin implicitly
+ * provides its own name, so `dependencies: ['logger-plugin']` also works.
+ */
+function buildProviderIndex(plugins: readonly IPlugin[]): Map<CapabilityToken, IPlugin> {
+  const providers = new Map<CapabilityToken, IPlugin>();
+  for (const plugin of plugins) {
+    for (const token of [plugin.name, ...(plugin.provides ?? [])]) {
+      const existing = providers.get(token);
+      if (existing !== undefined && existing !== plugin) {
+        throw new Error(
+          `Capability '${token}' is provided by both '${existing.name}' and '${plugin.name}'. ` +
+            `Multi-provider capabilities must be registered with { multi: true } at the service level.`,
+        );
+      }
+      providers.set(token, plugin);
+    }
+  }
+  return providers;
+}
+
+/**
+ * Depth-first topological sort. Within the same dependency level, plugins
+ * are visited by (priority, registration order), which the DFS preserves in
+ * the output.
+ */
+function topologicalSort(
+  plugins: readonly IPlugin[],
+  dependenciesOf: (plugin: IPlugin) => IPlugin[],
+): readonly IPlugin[] {
+  const DEFAULT_PRIORITY = 500;
+  const seeds = plugins
+    .map((plugin, index) => ({ plugin, index }))
+    .sort(
+      (a, b) =>
+        (a.plugin.priority ?? DEFAULT_PRIORITY) - (b.plugin.priority ?? DEFAULT_PRIORITY) ||
+        a.index - b.index,
+    )
+    .map(({ plugin }) => plugin);
+
+  const ordered: IPlugin[] = [];
+  const done = new Set<IPlugin>();
+  const inProgress = new Set<IPlugin>();
+
+  const visit = (plugin: IPlugin, chain: readonly string[]): void => {
+    if (done.has(plugin)) {
+      return;
+    }
+    if (inProgress.has(plugin)) {
+      const cycle = [...chain.slice(chain.indexOf(plugin.name)), plugin.name].join(' -> ');
+      throw new Error(`Circular plugin dependency detected: ${cycle}`);
+    }
+    inProgress.add(plugin);
+    for (const dependency of dependenciesOf(plugin)) {
+      visit(dependency, [...chain, plugin.name]);
+    }
+    inProgress.delete(plugin);
+    done.add(plugin);
+    ordered.push(plugin);
+  };
+
+  for (const plugin of seeds) {
+    visit(plugin, []);
+  }
+  return ordered;
+}