bazis 0.96.1

package/core/http/HttpContext/HttpContext.ts

@@ -0,0 +1,148 @@
+import type { ServiceScope } from "../../di";
+import { BadRequestError, PayloadTooLargeError } from "../Errors/HttpError";
+import { ResponseBuilder } from "./ResponseBuilder";
+import type { ModelValidator } from "../Binding/modelValidator";
+
+/** Route parameter values after constraint conversion (`:id(int)` -> number). */
+export type RouteParams = Readonly<Record<string, string | number | boolean>>;
+
+/**
+ * Per-request context flowing through the middleware pipeline and into
+ * actions. Wraps the native Bun `Request`, the matched route parameters and
+ * the request-scoped DI resolver.
+ */
+export class HttpContext {
+  /** Response produced by the pipeline (set by the terminal handler or middleware). */
+  response?: Response;
+
+  /** Response shaping for actions that return plain values (see ResponseBuilder). */
+  readonly res = new ResponseBuilder();
+
+  /** Free-form state for passing data between middleware (e.g. auth user). */
+  readonly state = new Map<string, unknown>();
+
+  private bodyPromise?: Promise<unknown>;
+  private bodyBytesPromise?: Promise<Uint8Array>;
+
+  constructor(
+    /** Native Bun request. */
+    readonly request: Request,
+    /** Parsed request URL (query via `url.searchParams`). */
+    readonly url: URL,
+    /** Route parameters, converted per template constraints. */
+    readonly params: RouteParams,
+    /**
+     * Request-scoped DI resolver: controllers and scoped services of this
+     * request are resolved from here. JS producers retain the scope until EOF,
+     * failure, cancellation or peer disconnect. Native file/materialized bodies
+     * release it after Bun takes ownership. The original Response is preserved.
+     */
+    readonly services: ServiceScope,
+    /** API version resolved for this request (if versioning is enabled). */
+    readonly apiVersion?: string,
+    /** Optional maximum request body size enforced while reading body streams. */
+    private readonly maxBodyBytes?: number,
+    /** Remote peer address reported by Bun (not a forwarded header). */
+    readonly clientIp?: string,
+    /** Validator captured by the owning HTTP server. */
+    readonly modelValidator?: ModelValidator,
+  ) {}
+
+  get method(): string {
+    return this.request.method;
+  }
+
+  get path(): string {
+    return this.url.pathname;
+  }
+
+  /** Query parameter shortcut. */
+  query(name: string): string | undefined {
+    return this.url.searchParams.get(name) ?? undefined;
+  }
+
+  /** Header shortcut (case-insensitive). */
+  header(name: string): string | undefined {
+    return this.request.headers.get(name) ?? undefined;
+  }
+
+  /**
+   * Request body parsed as JSON. Parsed once and cached — multiple bindings
+   * and middleware share the same promise. Malformed JSON becomes a 400.
+   */
+  json<T = unknown>(): Promise<T> {
+    this.bodyPromise ??= this.readBodyText().then((text) => {
+      try {
+        return JSON.parse(text) as T;
+      } catch {
+        throw new BadRequestError("Malformed JSON in request body");
+      }
+    });
+    return this.bodyPromise as Promise<T>;
+  }
+
+  /** Request body as text. Shares the same bounded body read as JSON/formData. */
+  text(): Promise<string> {
+    return this.readBodyText();
+  }
+
+  /** Request body as multipart/urlencoded form data (native parser). */
+  formData(): ReturnType<Request["formData"]> {
+    return this.readBodyBytes()
+      .then((bytes) => new Response(bytes as unknown as ConstructorParameters<typeof Response>[0], { headers: this.request.headers }).formData())
+      .catch((error) => {
+        if (error instanceof PayloadTooLargeError) {
+          throw error;
+        }
+        throw new BadRequestError("Malformed form data in request body");
+      }) as ReturnType<Request["formData"]>;
+  }
+
+  private readBodyText(): Promise<string> {
+    return this.readBodyBytes().then((bytes) => new TextDecoder().decode(bytes));
+  }
+
+  private readBodyBytes(): Promise<Uint8Array> {
+    this.bodyBytesPromise ??= readRequestBodyBytes(this.request, this.maxBodyBytes);
+    return this.bodyBytesPromise;
+  }
+}
+
+async function readRequestBodyBytes(request: Request, maxBytes: number | undefined): Promise<Uint8Array> {
+  if (request.body === null) {
+    return new Uint8Array();
+  }
+  if (maxBytes === undefined) {
+    return new Uint8Array(await request.arrayBuffer());
+  }
+
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const item = await reader.read();
+      if (item.done) {
+        break;
+      }
+      const chunk = item.value;
+      total += chunk.byteLength;
+      if (total > maxBytes) {
+        void reader.cancel("request body exceeds maxBodyBytes").catch(() => undefined);
+        throw new PayloadTooLargeError(maxBytes);
+      }
+      chunks.push(chunk);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (let index = 0; index < chunks.length; index += 1) {
+    const chunk = chunks[index] as Uint8Array;
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body;
+}

package/core/http/HttpContext/ResponseBuilder.ts

@@ -0,0 +1,37 @@
+/**
+ * Mutable response state an action (or middleware) can shape before the
+ * result is materialized into a `Response`. Available as `ctx.res` and via
+ * a typed ResponseBuilder action parameter.
+ *
+ * Explicitly returned `Response` instances and result helpers (`Ok(...)`)
+ * win over the builder's status; builder headers are merged in either way.
+ */
+export class ResponseBuilder {
+  private statusCode?: number;
+  private readonly headerList: [string, string][] = [];
+
+  /** Overrides the response status (weaker than `@HttpCode` and result helpers). */
+  status(code: number): this {
+    this.statusCode = code;
+    return this;
+  }
+
+  /** Adds a response header (appended to whatever the result produces). */
+  header(name: string, value: string): this {
+    this.headerList.push([name, value]);
+    return this;
+  }
+
+  /** Shortcut for the Content-Type header. */
+  contentType(value: string): this {
+    return this.header("content-type", value);
+  }
+
+  get statusOverride(): number | undefined {
+    return this.statusCode;
+  }
+
+  get headers(): readonly [string, string][] {
+    return this.headerList;
+  }
+}

package/core/http/HttpContext/inspectableRedirects.ts

@@ -0,0 +1,47 @@
+import { InspectableRedirectProtocol as protocol } from "../../../library/http-client";
+
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+/** Called after the normal middleware chain, before transferring the scope. */
+export function inspectableRedirectResponse(response: Response, request: Request): Response {
+  const negotiated = request.headers.get(protocol.header) === protocol.version;
+  const redirect = negotiated && REDIRECT_STATUSES.has(response.status) && response.headers.has("location");
+  const headers = new Headers(response.headers);
+  appendHeaderToken(headers, "vary", protocol.header);
+  // These names belong to this transport; application headers cannot forge
+  // a redirect status on an ordinary response.
+  headers.delete(protocol.header);
+  headers.delete(protocol.statusHeader);
+  if (negotiated) {
+    headers.set(protocol.header, protocol.version);
+    headers.set("cache-control", "no-store");
+    for (const name of [protocol.header, protocol.statusHeader, "location"]) {
+      appendHeaderToken(headers, "access-control-expose-headers", name);
+    }
+    if (redirect) headers.set(protocol.statusHeader, String(response.status));
+  }
+  if (!redirect) {
+    try {
+      // Preserve the actual Response/Bun.file body path, including Range.
+      for (const name of ["vary", protocol.header, protocol.statusHeader, "cache-control", "access-control-expose-headers"]) {
+        const value = headers.get(name);
+        if (value === null) response.headers.delete(name);
+        else response.headers.set(name, value);
+      }
+      return response;
+    } catch {
+      // Fetch responses may have immutable headers. Keep their original stream.
+    }
+  }
+  return new Response(response.body, {
+    status: redirect ? 200 : response.status,
+    statusText: redirect ? "OK" : response.statusText,
+    headers,
+  });
+}
+
+function appendHeaderToken(headers: Headers, name: string, token: string): void {
+  const current = headers.get(name)?.split(",").map(value => value.trim().toLowerCase()) ?? [];
+  if (current.includes(token.toLowerCase()) || (name === "vary" && current.includes("*"))) return;
+  headers.append(name, token);
+}

package/core/http/HttpContext/principal.ts

@@ -0,0 +1,24 @@
+/**
+ * Contract of the "current request subject" in `ctx.state`.
+ *
+ * This is the only meeting point between the authentication layer (an application
+ * `@Authorize` check puts the principal into `ctx.state`) and the kernel parts
+ * that need per-user personalization (for example the output cache with
+ * `varyByUser`/`varyByClaim`). The key and the shape are declared here, in the
+ * kernel, so application code depends on the kernel and not the other way round.
+ */
+
+/** The `ctx.state` key under which {@link RequestPrincipal} is stored. */
+export const PRINCIPAL_STATE_KEY = "auth:principal";
+
+/**
+ * The minimal principal shape the kernel relies on. The concrete implementation
+ * (token kind, claim set and so on) belongs to the application layer; these
+ * optional fields are enough for the kernel.
+ */
+export interface RequestPrincipal {
+  /** Subject identifier (`sub`); used by the output cache for `varyByUser`. */
+  readonly subject?: string;
+  /** Optional claim lookup by type; used for `varyByClaim`. */
+  findFirst?(claimType: string): string | undefined;
+}

package/core/http/HttpContext/responseLifetime.ts

@@ -0,0 +1,45 @@
+import { finished } from "node:stream";
+
+/**
+ * Observe the original body without locking, reading, cloning or replacing it.
+ * Bun can consequently retain its native file/range/sendfile handling.
+ * The returned promise settles after request-scope cleanup, for host shutdown.
+ */
+export function holdResponseScope(
+  response: Response,
+  signal: AbortSignal,
+  dispose: () => Promise<void>,
+): Promise<void> {
+  const body = response.body;
+  if (!body) return Promise.resolve().then(dispose);
+  if (response.bodyUsed || body.locked) throw new TypeError("Response body is already in use");
+
+  let complete!: () => void;
+  let reject!: (reason: unknown) => void;
+  const completion = new Promise<void>((resolve, fail) => { complete = resolve; reject = fail; });
+  let ended = false;
+  let cleanup = (): void => {};
+  let handoffCheck: ReturnType<typeof setImmediate> | undefined;
+
+  const finish = (): void => {
+    if (ended) return;
+    ended = true;
+    cleanup();
+    if (handoffCheck !== undefined) clearImmediate(handoffCheck);
+    // Before Bun takes ownership (including an already-aborted request), an
+    // unlocked producer still needs cancellation. Once locked, Bun owns it.
+    if (signal.aborted && !body.locked) void body.cancel(signal.reason).catch(() => undefined);
+    void Promise.resolve().then(dispose).then(complete, reject);
+  };
+  cleanup = finished(body, { signal }, finish);
+
+  // Qualified Bun 1.4 consumes native Blob/file bodies directly: bodyUsed is
+  // true, but no JS reader is acquired and its stream never emits finished.
+  // After the response handoff, release that scope as for a materialized
+  // result. A live JS producer remains locked and is observed until finished.
+  // This is a single handoff check, not a timer-based stream lifetime limit.
+  handoffCheck = setImmediate(() => {
+    if (response.bodyUsed && !body.locked) finish();
+  });
+  return completion;
+}