@setu-ts/kernel 0.0.0-stage → 0.9.0

package/src/registry/service-registry.ts

@@ -0,0 +1,267 @@
+/**
+ * Capability-token service registry — the framework's primary service
+ * resolution mechanism (ARCHITECTURE.md §6).
+ *
+ * @module
+ */
+import type {
+  CapabilityToken,
+  IServiceRegistry,
+  RegisterOptions,
+  ServiceFactory,
+} from '@setu-ts/common';
+
+interface Registration {
+  instance?: object;
+  factory?: ServiceFactory<object>;
+}
+
+/**
+ * A successful registry mutation reported to the diagnostics collector, using
+ * token metadata alone. Duplicate-registration REFUSALS never produce an
+ * event: they throw before any mutation happens, and a refused registration
+ * is not a successful one.
+ *
+ * @since 0.8.0
+ */
+export type RegistryDiagnosticEvent = {
+  readonly kind: 'register-single' | 'register-multi' | 'unregister';
+  readonly token: CapabilityToken;
+};
+
+/**
+ * The collector-facing sink for successful registry mutations. Distinct from
+ * the startup logging observer, which keeps its own shape and behavior.
+ *
+ * @since 0.8.0
+ */
+export type RegistryDiagnosticsSink = (event: RegistryDiagnosticEvent) => void;
+
+function resolveRegistration(registration: Registration): object {
+  if (registration.instance === undefined) {
+    // Lazy factory: instantiate on first lookup, cache for subsequent ones.
+    registration.instance = registration.factory!();
+  }
+  return registration.instance;
+}
+
+/**
+ * Default {@linkcode IServiceRegistry} implementation. Request scopes are
+ * modeled as child registries that fall back to their parent for lookups
+ * while keeping their own registrations isolated.
+ */
+export class ServiceRegistry implements IServiceRegistry {
+  readonly #single = new Map<CapabilityToken, Registration>();
+  readonly #multi = new Map<CapabilityToken, Registration[]>();
+  readonly #parent: ServiceRegistry | undefined;
+  #sealed = false;
+  #observer: ((kind: 'override' | 'unregister', token: CapabilityToken) => void) | undefined;
+  #diagnosticsSink: RegistryDiagnosticsSink | undefined;
+  #missExplanation: ((token: CapabilityToken) => string | undefined) | undefined;
+
+  constructor(parent?: ServiceRegistry) {
+    this.#parent = parent;
+  }
+
+  /** Creates a request-scoped child registry that falls back to this one. */
+  createChild(): ServiceRegistry {
+    return new ServiceRegistry(this);
+  }
+
+  /** Prevents future application-scoped registrations. */
+  seal(): void {
+    this.#sealed = true;
+  }
+
+  /**
+   * Installs the diagnostics sink that receives successful registration and
+   * removal events. Pass `undefined` to detach (teardown).
+   *
+   * @param sink - The collector-facing sink, or `undefined`
+   * @since 0.8.0
+   */
+  setDiagnosticsSink(sink: RegistryDiagnosticsSink | undefined): void {
+    this.#diagnosticsSink = sink;
+  }
+
+  /**
+   * Installs the explanation {@linkcode ServiceRegistry.get} gives for a token
+   * it cannot find. The application knows what the registry cannot: whether
+   * its plugins have registered yet, and which plugin provides a token. When
+   * the function returns a string, it replaces the generic advice in the
+   * error; `undefined` keeps that advice.
+   *
+   * @param explain - Explains a missing token, or answers `undefined`
+   */
+  setMissExplanation(explain: (token: CapabilityToken) => string | undefined): void {
+    this.#missExplanation = explain;
+  }
+
+  /**
+   * Returns the ALREADY-RESOLVED instance for a token without ever executing
+   * a factory, using the same single-registration lookup precedence as
+   * {@linkcode ServiceRegistry.get} — own single registration, then own first
+   * multi-provider, then the parent. An unresolved LOCAL registration answers
+   * `undefined` and does NOT fall past to the parent: the answer "present but
+   * never constructed" must not turn into a foreign instance. Multi-providers
+   * are never enumerated, nothing is constructed, and the method is absent
+   * from {@linkcode IServiceRegistry} by design — it exists so kernel
+   * diagnostics can read an optional capability (telemetry identifiers) on the
+   * execution path without forcing a lazy service into existence, and it is
+   * not part of the public barrel.
+   *
+   * @typeParam T - The service's interface type
+   * @param token - The capability token to peek
+   * @returns The cached instance, or `undefined` when absent or unresolved
+   * @since 0.8.0
+   */
+  peekResolved<T extends object>(token: CapabilityToken): T | undefined {
+    const own = this.#single.get(token) ?? this.#multi.get(token)?.[0];
+    if (own !== undefined) {
+      return own.instance === undefined ? undefined : (own.instance as T);
+    }
+    if (this.#parent === undefined) {
+      return undefined;
+    }
+    return this.#parent.peekResolved<T>(token);
+  }
+
+  /**
+   * Reports whether `instance` is the CURRENT provider a resolving
+   * {@linkcode ServiceRegistry.get} would select for `token` — WITHOUT ever
+   * executing a factory.
+   *
+   * The lookup precedence is IDENTICAL to `get`'s: own single registration,
+   * then own first multi-provider, then the parent. The comparison is an
+   * identity check against the registration's already-resolved instance. A
+   * registration whose instance has not been constructed yet (a lazy factory
+   * that has not run) answers `false` — it does NOT fall past to the parent,
+   * because the answer "present but never constructed" must not be mistaken
+   * for a foreign instance. Nothing is constructed, no multi-provider list is
+   * enumerated, and the current value is never returned.
+   *
+   * This is the non-resolving identity predicate of
+   * {@linkcode IServiceRegistry.isCurrent}: a consumer can verify it still
+   * owns a known provider without forcing a lazy replacement into existence.
+   *
+   * @typeParam T - The service's interface type
+   * @param token - The capability token to check
+   * @param instance - The instance to compare against the current registration
+   * @returns `true` only when `instance` IS the registration `get` would select
+   * @since 0.8.0
+   */
+  isCurrent<T extends object>(token: CapabilityToken, instance: T): boolean {
+    const own = this.#single.get(token) ?? this.#multi.get(token)?.[0];
+    if (own !== undefined) {
+      return own.instance === instance;
+    }
+    if (this.#parent === undefined) {
+      return false;
+    }
+    return this.#parent.isCurrent(token, instance);
+  }
+
+  /** Installs the application-owned callback for startup-time mutations. */
+  setObserver(
+    observer: (kind: 'override' | 'unregister', token: CapabilityToken) => void,
+  ): void {
+    this.#observer = observer;
+  }
+
+  register<T extends object>(
+    token: CapabilityToken,
+    service: T,
+    options?: RegisterOptions,
+  ): void {
+    this.#store(token, { instance: service }, options);
+  }
+
+  registerFactory<T extends object>(
+    token: CapabilityToken,
+    factory: ServiceFactory<T>,
+    options?: RegisterOptions,
+  ): void {
+    this.#store(token, { factory }, options);
+  }
+
+  get<T extends object>(token: CapabilityToken): T {
+    const registration = this.#lookup(token);
+    if (registration === undefined) {
+      const advice = this.#missExplanation?.(token) ??
+        'Register a plugin that provides it, or check the token spelling against CAPABILITIES.';
+      throw new Error(`No service registered for capability '${token}'. ${advice}`);
+    }
+    return resolveRegistration(registration) as T;
+  }
+
+  getAll<T extends object>(token: CapabilityToken): readonly T[] {
+    const own = this.#multi.get(token) ?? [];
+    const inherited = this.#parent?.getAll<T>(token) ?? [];
+    const single = this.#single.get(token);
+    return [
+      ...inherited,
+      ...(single ? [resolveRegistration(single) as T] : []),
+      ...own.map((registration) => resolveRegistration(registration) as T),
+    ];
+  }
+
+  has(token: CapabilityToken): boolean {
+    return this.#single.has(token) || this.#multi.has(token) || (this.#parent?.has(token) ?? false);
+  }
+
+  unregister(token: CapabilityToken): boolean {
+    this.#assertMutable(token, 'unregister');
+    const hadSingle = this.#single.delete(token);
+    const hadMulti = this.#multi.delete(token);
+    const removed = hadSingle || hadMulti;
+    if (removed) {
+      this.#observer?.('unregister', token);
+      this.#diagnosticsSink?.({ kind: 'unregister', token });
+    }
+    return removed;
+  }
+
+  #lookup(token: CapabilityToken): Registration | undefined {
+    const own = this.#single.get(token) ?? this.#multi.get(token)?.[0];
+    if (own !== undefined) {
+      return own;
+    }
+    if (this.#parent === undefined) {
+      return undefined;
+    }
+    return this.#parent.#lookup(token);
+  }
+
+  #store(token: CapabilityToken, registration: Registration, options?: RegisterOptions): void {
+    this.#assertMutable(token, 'register');
+    if (options?.multi) {
+      const providers = this.#multi.get(token) ?? [];
+      providers.push(registration);
+      this.#multi.set(token, providers);
+      this.#diagnosticsSink?.({ kind: 'register-multi', token });
+      return;
+    }
+    // Conflicts are checked against this registry only: a request-scoped
+    // child may deliberately shadow an application-scoped service.
+    if (this.#single.has(token) && !options?.override) {
+      throw new Error(
+        `Capability '${token}' is already registered. Use { override: true } to replace it.`,
+      );
+    }
+    if (this.#single.has(token) && options?.override) {
+      this.#observer?.('override', token);
+    }
+    this.#single.set(token, registration);
+    this.#diagnosticsSink?.({ kind: 'register-single', token });
+  }
+
+  #assertMutable(token: CapabilityToken, operation: 'register' | 'unregister'): void {
+    if (this.#sealed) {
+      throw new Error(
+        `Cannot ${operation} capability '${token}' after runBootstrap() has completed. ` +
+          `Register during a plugin's register(), onInit, or onBootstrap hook, or use ` +
+          `request-scoped ctx.services inside middleware.`,
+      );
+    }
+  }
+}

package/src/router/route-matcher.ts

@@ -0,0 +1,131 @@
+/**
+ * Route matcher utilities — path decoding guard and pattern-parsing helpers
+ * for the kernel router.
+ *
+ * As of Milestone 22, route *matching* is delegated to Hono inside the
+ * [`Router`](./router.ts).  This module exports:
+ *
+ * - {@linkcode isPathDecodable} — used by the application to reject malformed
+ *   percent-escapes with a 400 **before** routing.
+ * - {@linkcode Segment}, {@linkcode parsePattern}, {@linkcode staticSegmentCount},
+ *   {@linkcode wildcardSegmentCount} — parsing primitives shared with the Router's
+ *   tie-break logic.
+ *
+ * @module
+ */
+
+interface StaticSegment {
+  type: 'static';
+  value: string;
+}
+
+interface ParamSegment {
+  type: 'param';
+  name: string;
+}
+
+interface WildcardSegment {
+  type: 'wildcard';
+}
+
+/**
+ * A parsed route segment — a static path component, a `:name` parameter
+ * placeholder, or the `*` wildcard.
+ *
+ * The wildcard arm was added in M70g. Before it, `*` parsed as a STATIC segment,
+ * so `/*` scored the same specificity as `/openapi.json` and the tie was decided
+ * by registration order alone — which silently removed every single-segment
+ * plugin route registered after an application catch-all.
+ *
+ * @since 0.1.0
+ */
+export type Segment = StaticSegment | ParamSegment | WildcardSegment;
+
+/**
+ * Parses a route pattern like `/users/:id` into segments.
+ *
+ * @param pattern - The route pattern to parse
+ * @returns An array of `Segment` objects
+ * @internal Used only at registration time for tie-break statics counting.
+ */
+export function parsePattern(pattern: string): readonly Segment[] {
+  const normalized = pattern === '/' ? '/' : pattern.replace(/\/+$/, '');
+  if (normalized === '/') {
+    return [{ type: 'static', value: '' }];
+  }
+  return normalized.slice(1).split('/').map((part) => {
+    if (part.startsWith(':')) {
+      return { type: 'param', name: part.slice(1) };
+    }
+    // Exactly `*`, never a segment merely CONTAINING one: `/a*` is not a pattern
+    // any first-party plugin registers, and treating it as a wildcard would lower
+    // the specificity of a path that matches literally.
+    if (part === '*') {
+      return { type: 'wildcard' };
+    }
+    return { type: 'static', value: part };
+  });
+}
+
+/**
+ * Counts the literal path components in a pattern.
+ *
+ * Neither a `:param` nor a `*` wildcard counts: both match text the pattern does
+ * not name, so neither makes the route more specific.
+ *
+ * @param segments - The parsed segments array
+ * @returns The count of static segments
+ * @internal Used only at registration time for tie-break specificity.
+ */
+export function staticSegmentCount(segments: readonly Segment[]): number {
+  let count = 0;
+  for (const segment of segments) {
+    if (segment.type === 'static') {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Counts the `*` wildcard segments in a pattern.
+ *
+ * The router's second tie-break key, read ASCENDING: between two routes with the
+ * same number of literal components, the one matching less arbitrary text is the
+ * more specific. That is what puts `/a/:id` ahead of `/a/*`, which before M70g
+ * lost in both registration orders because `*` was counted as a literal.
+ *
+ * @param segments - The parsed segments array
+ * @returns The count of wildcard segments
+ * @internal Used only at registration time for tie-break specificity.
+ */
+export function wildcardSegmentCount(segments: readonly Segment[]): number {
+  let count = 0;
+  for (const segment of segments) {
+    if (segment.type === 'wildcard') {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Reports whether a path can be percent-decoded without error.
+ *
+ * A malformed percent-escape (e.g. `%zz`, a truncated `%2`, or a bare `%`)
+ * makes {@linkcode decodeURIComponent} throw. The application uses this to
+ * reject a malformed request path as a `400` before it reaches routing,
+ * where an unguarded decode would otherwise surface as a `500`.
+ *
+ * @param path - The raw (still percent-encoded) request path
+ * @returns `true` when the path decodes cleanly, `false` when it is malformed
+ * @since 0.1.0
+ */
+export function isPathDecodable(path: string): boolean {
+  try {
+    decodeURIComponent(path);
+    return true;
+  } catch {
+    return false;
+  }
+}