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

package/src/application/inject-body.ts

@@ -0,0 +1,131 @@
+/**
+ * Per-shape coercion of an {@linkcode InjectRequest} body (M95c §3.9).
+ *
+ * `inject()` used to JSON-stringify every non-string body, so a
+ * `Uint8Array` arrived as `{"0":97,…}` and an `ArrayBuffer`, a `Blob` and a
+ * `URLSearchParams` each arrived as the two bytes `{}` — destroying the input
+ * while reporting status 200. The coercion is now explicit per shape, and any
+ * shape OUTSIDE the union is refused by name rather than silently stringified,
+ * because `InjectRequest.body` is reachable from JavaScript and from an
+ * `unknown`-typed caller, where the type alone would not hold.
+ *
+ * Internal to the kernel — deliberately NOT exported from the barrel. The
+ * union itself has ONE home, the published `InjectRequest.body`; this module
+ * derives its alias from it so the two cannot drift.
+ *
+ * @module
+ */
+import type { InjectRequest } from './application.ts';
+
+/**
+ * The body shapes {@linkcode InjectRequest} carries — derived from the
+ * published interface, which owns the literal union.
+ *
+ * @since 0.7.0
+ */
+export type InjectBody = NonNullable<InjectRequest['body']>;
+
+/** What {@linkcode coerceInjectBody} resolves with. */
+export interface CoercedInjectBody {
+  /** The body's bytes; `undefined` when the caller sent no body. */
+  readonly bytes: Uint8Array | undefined;
+  /**
+   * The content type to default to when the caller supplied none:
+   * `application/x-www-form-urlencoded` for a `URLSearchParams`,
+   * `application/json` for a string or a plain object, a `Blob`'s own `type`
+   * when that string is non-empty (matching the platform, whose
+   * `new Request(url, { body: blob })` sets the header from it and omits it
+   * when the blob has none), and NONE for a `Uint8Array` or an `ArrayBuffer`
+   * — those bytes carry no declared type, and guessing would make the form
+   * parse refuse them.
+   */
+  readonly defaultContentType: string | undefined;
+}
+
+/**
+ * Coerces an injected body to the bytes the synthetic request carries.
+ *
+ * Bytes pass through with their exact contents — copied, never aliased to the
+ * caller's `Uint8Array` or `ArrayBuffer`, since `bytes()` hands the result
+ * straight to the handler — a `Blob` is awaited to bytes, a `URLSearchParams`
+ * is serialised with its own `toString()`, and only a plain object reaches
+ * `JSON.stringify`. An array, a `Date`, a class instance or any other shape
+ * rejects with a `TypeError` naming the received type.
+ *
+ * @param body - The caller-supplied body, if any
+ * @returns The coerced bytes and the content-type default for the shape
+ * @throws {TypeError} When the body is outside the {@linkcode InjectBody} union
+ * @since 0.7.0
+ */
+export async function coerceInjectBody(
+  body: InjectBody | undefined,
+): Promise<CoercedInjectBody> {
+  if (body === undefined) {
+    return { bytes: undefined, defaultContentType: undefined };
+  }
+  if (typeof body === 'string') {
+    return { bytes: new TextEncoder().encode(body), defaultContentType: 'application/json' };
+  }
+  if (body instanceof URLSearchParams) {
+    return {
+      bytes: new TextEncoder().encode(body.toString()),
+      defaultContentType: 'application/x-www-form-urlencoded',
+    };
+  }
+  if (body instanceof Uint8Array) {
+    // A COPY, not the caller's array. `bytes()` hands this straight to the
+    // handler, so aliasing would let a handler that mutates the body it read
+    // corrupt the fixture the test passed in — and a fixture reused across two
+    // injected requests would carry the first request's mutation into the
+    // second. `slice()` also guarantees a plain ArrayBuffer-backed view, which
+    // `BodyInit` requires and a SharedArrayBuffer-backed argument would not be.
+    return { bytes: body.slice(), defaultContentType: undefined };
+  }
+  if (body instanceof ArrayBuffer) {
+    // `new Uint8Array(buffer)` is a VIEW over the caller's buffer, not a copy —
+    // same aliasing hazard as above, one indirection further out.
+    return { bytes: new Uint8Array(body.slice(0)), defaultContentType: undefined };
+  }
+  if (body instanceof Blob) {
+    // A Blob DECLARES its type in `.type`, so it contributes that as the
+    // content-type default — exactly what the platform does for
+    // `new Request(url, { body: blob })`, header omitted when the type is
+    // empty. The bare byte shapes stay default-free: bytes alone say nothing
+    // about their encoding, which is why an injected multipart Blob used to
+    // answer 500 (`UnsupportedFormEncodingError`) where the same Blob through
+    // `fetch()` answered 200.
+    return {
+      bytes: new Uint8Array(await body.arrayBuffer()),
+      defaultContentType: body.type.length > 0 ? body.type : undefined,
+    };
+  }
+  if (typeof body === 'object' && body !== null && isPlainObject(body)) {
+    return {
+      bytes: new TextEncoder().encode(JSON.stringify(body)),
+      defaultContentType: 'application/json',
+    };
+  }
+  throw new TypeError(refusalMessage(body));
+}
+
+/** A plain object: `Object.prototype` (or `null`) is its prototype. */
+function isPlainObject(value: object): boolean {
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/** Names the received value in the refusal, so the caller sees what was wrong. */
+function refusalMessage(value: unknown): string {
+  const received = value === null
+    ? 'null'
+    : typeof value === 'object'
+    ? (Object.getPrototypeOf(value) as { constructor?: { name?: string } } | null)?.constructor
+      ?.name ?? 'object'
+    : typeof value;
+  return (
+    `inject() body must be a string, Uint8Array, ArrayBuffer, Blob, URLSearchParams, or a ` +
+    `plain object; received ${received}. The previous behaviour silently JSON-stringified ` +
+    `every other shape, which destroyed the value — pass bytes for a binary or multipart ` +
+    `body, or a plain object for JSON.`
+  );
+}

package/src/context/request-context.ts

@@ -0,0 +1,169 @@
+/**
+ * Request context factory — creates a fresh per-request context whose cold
+ * members (identity, child registry, state, query, signal) are resolved on
+ * first read rather than eagerly.
+ *
+ * @module
+ */
+import { sealRequestIdentity } from '@setu-ts/common';
+import type { IRequest, IRequestContext, IServiceRegistry } from '@setu-ts/common';
+import type { IRuntimeServices } from '@setu-ts/common';
+
+import type { ServiceRegistry } from '../registry/service-registry.ts';
+import { ResponseBuilder } from './response.ts';
+
+/**
+ * Internal result of {@linkcode createRequestContext}: the immutable
+ * {@linkcode IRequestContext} plus a `setParams` mutator the kernel uses
+ * to install matched route parameters after routing. This shape is NOT
+ * exported from the package public API — only the kernel dispatch path
+ * uses `setParams`.
+ */
+export interface RequestContextHandle {
+  /** The per-request context. */
+  readonly ctx: IRequestContext;
+  /** Replaces the params exposed by `ctx.params` (used after route match). */
+  setParams(params: Record<string, string>): void;
+}
+
+/** Shared empty params — replaced by `setParams` once a route matches. */
+const EMPTY_PARAMS: Readonly<Record<string, string>> = Object.freeze({});
+
+/**
+ * The per-request context, as a class so that every accessor lives on ONE
+ * shared prototype.
+ *
+ * The class is load-bearing rather than stylistic. An earlier attempt at the
+ * same laziness using own-property getters on a fresh object literal per
+ * request measured **13% slower** than eager construction, because each
+ * request got its own hidden class. Declared once on a prototype, the same
+ * getters are monomorphic.
+ *
+ * Cold members are resolved on first read. The eager versions each cost every
+ * request in the application to serve the minority that reads them: a child
+ * registry allocation, a `crypto`-backed UUID, a `Map`, a `URL` parse for the
+ * query string (the second in the request's life — the adapter already parsed
+ * one), and — on Node — an `AbortController`, because
+ * `@hono/node-server`'s lightweight Request creates one on first `signal` read.
+ */
+class RequestContext implements IRequestContext {
+  readonly request: IRequest;
+  readonly response: ResponseBuilder;
+  readonly startTime: number;
+
+  readonly #registry: ServiceRegistry;
+  readonly #runtime: IRuntimeServices;
+  #params: Readonly<Record<string, string>> = EMPTY_PARAMS;
+  #id: string | undefined;
+  #services: IServiceRegistry | undefined;
+  #state: Map<string, unknown> | undefined;
+  #query: Readonly<Record<string, string>> | undefined;
+  #signal: AbortSignal | undefined;
+
+  constructor(request: IRequest, registry: ServiceRegistry, runtime: IRuntimeServices) {
+    this.request = request;
+    this.#registry = registry;
+    this.#runtime = runtime;
+    this.response = new ResponseBuilder();
+    // Monotonic, and read eagerly on purpose: it is the request's start, so a
+    // lazy read would time the first access rather than the request.
+    this.startTime = runtime.hrtime();
+    // `raw` is OMITTED, not set to undefined, when the adapter supplied none:
+    // `IRequestContext.raw` is optional and the workspace compiles under
+    // `exactOptionalPropertyTypes`, so a getter returning `undefined` is not
+    // assignable. This reproduces the pre-M87 conditional-spread behaviour.
+    if (request.raw !== undefined) {
+      (this as unknown as { raw: Request }).raw = request.raw;
+    }
+  }
+
+  /** Unique request ID. */
+  get id(): string {
+    this.#id ??= this.#runtime.uuid();
+    return this.#id;
+  }
+
+  /** The request-scoped child service registry. */
+  get services(): IServiceRegistry {
+    this.#services ??= this.#registry.createChild();
+    return this.#services;
+  }
+
+  /** Matched route parameters — empty until the kernel calls `setParams`. */
+  get params(): Readonly<Record<string, string>> {
+    return this.#params;
+  }
+
+  /** Parsed query-string parameters. */
+  get query(): Readonly<Record<string, string>> {
+    if (this.#query === undefined) {
+      const url = new URL(this.request.url);
+      const query: Record<string, string> = {};
+      for (const [key, value] of url.searchParams.entries()) {
+        query[key] = value;
+      }
+      this.#query = query;
+    }
+    return this.#query;
+  }
+
+  /** Per-request scratch state. */
+  get state(): Map<string, unknown> {
+    this.#state ??= new Map();
+    return this.#state;
+  }
+
+  /**
+   * An abort signal that is live for the life of the request.
+   *
+   * Falls back to a never-aborting sentinel when the incoming request carries
+   * no signal (an injected or test-constructed request), so handlers always
+   * have something to listen on.
+   *
+   * The sentinel is constructed **per request**, never once at module scope:
+   * Cloudflare Workers refuses `new AbortController()` in global scope
+   * ("Disallowed operation called within global scope"), because an
+   * AbortController is bound to an I/O context. A module-scope one made every
+   * application fail to boot on workerd. Caching a single instance lazily is
+   * not a fix either — workerd would then refuse to use a controller created
+   * for one request on behalf of another.
+   */
+  get signal(): AbortSignal {
+    this.#signal ??= this.request.signal ?? new AbortController().signal;
+    return this.#signal;
+  }
+
+  /** Installs matched route parameters after routing. */
+  setParams(params: Record<string, string>): void {
+    this.#params = params;
+  }
+}
+
+/**
+ * Creates a per-request {@linkcode IRequestContext}.
+ *
+ * The returned `ctx.params` is a readonly getter over an internal slot;
+ * use {@linkcode RequestContextHandle.setParams} on the returned handle
+ * to update it after routing (the kernel does this in its dispatch
+ * terminal). This avoids mutating a `readonly` field via a cast.
+ *
+ * @param request - The incoming request
+ * @param registry - The application-scoped service registry (a child is created
+ *   on first `ctx.services` read)
+ * @param runtime - Runtime services for uuid and hrtime
+ * @returns The request context handle
+ */
+export function createRequestContext(
+  request: IRequest,
+  registry: ServiceRegistry,
+  runtime: IRuntimeServices,
+): RequestContextHandle {
+  sealRequestIdentity(request);
+  const ctx = new RequestContext(request, registry, runtime);
+  return {
+    ctx,
+    setParams(next: Record<string, string>): void {
+      ctx.setParams(next);
+    },
+  };
+}

package/src/context/response.ts

@@ -0,0 +1,254 @@
+/**
+ * Response builder — chainable configuration + terminal methods that produce
+ * the opaque {@linkcode HandlerResult} brand only the kernel creates.
+ *
+ * @module
+ */
+import type {
+  HandlerResult,
+  IResponse,
+  ResponseSnapshot,
+  ResponseSnapshotInit,
+} from '@setu-ts/common';
+
+/** Opaque brand — only the kernel constructs values of this type. */
+const HANDLER_RESULT: HandlerResult = { __handlerResult: true };
+
+/** Internal immutable header sources for the common terminal response shapes. */
+const JSON_INIT = responseInit({ 'content-type': 'application/json; charset=utf-8' });
+const TEXT_INIT = responseInit({ 'content-type': 'text/plain; charset=utf-8' });
+const HTML_INIT = responseInit({ 'content-type': 'text/html; charset=utf-8' });
+const BINARY_INIT = responseInit({ 'content-type': 'application/octet-stream' });
+
+/**
+ * Default implementation of {@linkcode IResponse}. Configuration methods
+ * chain; terminal methods mark the builder as ended and return the brand.
+ */
+export class ResponseBuilder implements IResponse {
+  #status = 200;
+  #headers: Headers | undefined;
+  #responseInit: TerminalResponseInit | undefined;
+  #initHeaderName: string | undefined;
+  #body: Uint8Array | string | ReadableStream<Uint8Array> | null = null;
+  #streaming = false;
+  #ended = false;
+
+  status(code: number): IResponse {
+    this.#status = code;
+    return this;
+  }
+
+  header(name: string, value: string): IResponse {
+    this.#materializeHeaders().set(name, value);
+    return this;
+  }
+
+  appendHeader(name: string, value: string): IResponse {
+    this.#materializeHeaders().append(name, value);
+    return this;
+  }
+
+  json<T>(body: T): HandlerResult {
+    this.#body = JSON.stringify(body);
+    this.#setBuiltInHeader('content-type', 'application/json; charset=utf-8', JSON_INIT);
+    this.#ended = true;
+    return HANDLER_RESULT;
+  }
+
+  text(body: string): HandlerResult {
+    this.#body = body;
+    this.#setBuiltInHeader('content-type', 'text/plain; charset=utf-8', TEXT_INIT);
+    this.#ended = true;
+    return HANDLER_RESULT;
+  }
+
+  /**
+   * Sends an HTML response with the `text/html; charset=utf-8` media type.
+   *
+   * @param body - The HTML document text
+   * @returns The handler result
+   */
+  html(body: string): HandlerResult {
+    this.#body = body;
+    this.#setBuiltInHeader('content-type', 'text/html; charset=utf-8', HTML_INIT);
+    this.#ended = true;
+    return HANDLER_RESULT;
+  }
+
+  send(body?: Uint8Array): HandlerResult {
+    this.#body = body ?? null;
+    if (body !== undefined && !this.#hasHeader('content-type')) {
+      this.#setBuiltInHeader('content-type', 'application/octet-stream', BINARY_INIT);
+    }
+    this.#ended = true;
+    return HANDLER_RESULT;
+  }
+
+  redirect(url: string, status: number = 302): HandlerResult {
+    this.#status = status;
+    this.#setBuiltInHeader('location', url, responseInit({ location: url }));
+    this.#body = null;
+    this.#ended = true;
+    return HANDLER_RESULT;
+  }
+
+  /**
+   * Sends a streaming response body.
+   *
+   * Accepts a web-standard {@linkcode ReadableStream} so that a handler can flush
+   * bytes progressively over a long-lived connection instead of buffering a
+   * whole body before send.
+   *
+   * @param body - A `ReadableStream` of `Uint8Array` chunks
+   * @returns The handler result
+   */
+  stream(body: ReadableStream<Uint8Array>): HandlerResult {
+    this.#body = body;
+    this.#streaming = true;
+    this.#ended = true;
+    return HANDLER_RESULT;
+  }
+
+  /**
+   * Returns a snapshot of the current response state.
+   *
+   * @returns The discriminated snapshot (status, headers, and either a buffered
+   *   body or a live stream, keyed on `streaming`)
+   */
+  snapshot(): ResponseSnapshot {
+    if (this.#streaming) {
+      return new StreamingResponseSnapshot(
+        this,
+        this.#status,
+        this.#body as ReadableStream<Uint8Array>,
+      );
+    }
+    return new BufferedResponseSnapshot(
+      this,
+      this.#status,
+      this.#body as Uint8Array | string | null,
+    );
+  }
+
+  /** Whether a terminal method has been called (used to detect short-circuits). */
+  get ended(): boolean {
+    return this.#ended;
+  }
+
+  /**
+   * The response status as currently set, defaulted to 200 — the value a
+   * completed request's diagnostics record reports. Read-only by design:
+   * status is set through {@linkcode ResponseBuilder.status}.
+   * @since 0.8.0
+   */
+  get statusCode(): number {
+    return this.#status;
+  }
+
+  /** Returns the native Headers object, creating it only for mutable access. */
+  #materializeHeaders(): Headers {
+    if (this.#headers === undefined) {
+      this.#headers = new Headers(this.#responseInit?.headers);
+      this.#responseInit = undefined;
+      this.#initHeaderName = undefined;
+    }
+    return this.#headers;
+  }
+
+  /** Supplies the documented live headers view to an internal snapshot. */
+  headersForSnapshot(): Headers {
+    return this.#materializeHeaders();
+  }
+
+  /** Supplies the current fast-path init to an internal snapshot. */
+  responseInitForSnapshot(): ResponseSnapshotInit | undefined {
+    const init = this.#responseInit;
+    if (init === undefined) return undefined;
+
+    // Native HTTP servers are allowed to add derived headers (for example,
+    // Content-Length) to their response initializer. Keep the shared internal
+    // source immutable, but give each snapshot consumer a mutable copy.
+    return { headers: { ...init.headers } };
+  }
+
+  /** Writes one built-in header without materializing native Headers where possible. */
+  #setBuiltInHeader(name: string, value: string, init: TerminalResponseInit): void {
+    if (this.#headers !== undefined) {
+      this.#headers.set(name, value);
+      return;
+    }
+    if (this.#responseInit === undefined || this.#initHeaderName === name) {
+      this.#responseInit = init;
+      this.#initHeaderName = name;
+      return;
+    }
+    this.#materializeHeaders().set(name, value);
+  }
+
+  /** Returns whether the current response already holds a named header. */
+  #hasHeader(name: string): boolean {
+    return this.#headers?.has(name) ?? this.#initHeaderName === name;
+  }
+}
+
+/** Snapshot object for buffered responses, with prototype-backed accessors. */
+class BufferedResponseSnapshot implements Extract<ResponseSnapshot, { readonly streaming: false }> {
+  readonly streaming = false;
+  readonly #response: ResponseBuilder;
+  readonly status: number;
+  readonly body: Uint8Array | string | null;
+
+  constructor(
+    response: ResponseBuilder,
+    status: number,
+    body: Uint8Array | string | null,
+  ) {
+    this.#response = response;
+    this.status = status;
+    this.body = body;
+  }
+
+  get responseInit(): ResponseSnapshotInit | undefined {
+    return this.#response.responseInitForSnapshot();
+  }
+
+  get headers(): Headers {
+    return this.#response.headersForSnapshot();
+  }
+}
+
+/** Snapshot object for streaming responses, with prototype-backed accessors. */
+class StreamingResponseSnapshot implements Extract<ResponseSnapshot, { readonly streaming: true }> {
+  readonly streaming = true;
+  readonly #response: ResponseBuilder;
+  readonly status: number;
+  readonly body: ReadableStream<Uint8Array>;
+
+  constructor(
+    response: ResponseBuilder,
+    status: number,
+    body: ReadableStream<Uint8Array>,
+  ) {
+    this.#response = response;
+    this.status = status;
+    this.body = body;
+  }
+
+  get responseInit(): ResponseSnapshotInit | undefined {
+    return this.#response.responseInitForSnapshot();
+  }
+
+  get headers(): Headers {
+    return this.#response.headersForSnapshot();
+  }
+}
+
+/** Internal shared source for a terminal response's fast-path header init. */
+type TerminalResponseInit = {
+  readonly headers: Readonly<Record<string, string>>;
+};
+
+/** Freezes a terminal response's internal header source before it is copied to a snapshot. */
+function responseInit(headers: Record<string, string>): TerminalResponseInit {
+  return Object.freeze({ headers: Object.freeze(headers) });
+}