@beignet/core 0.0.49 → 0.0.51

package/src/server/instrumentation.ts

@@ -16,7 +16,12 @@ import {
   type TraceContext,
   type TracingPort,
 } from "../tracing/index.js";
-import type { HttpRequestLike, HttpResponseLike, ServerHook } from "./http.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  HttpResponseLike,
+  ServerHook,
+} from "./http.js";
 import {
   clearActiveRequestContext,
   enterActiveRequestContext,
@@ -205,17 +210,20 @@ function requestHeadersToRecord(headers: Headers): Record<string, string> {
 }
 
 function getResponseHeader(
-  headers: Record<string, string> | undefined,
+  headers: HttpResponseHeaders | undefined,
   name: string,
 ): string | undefined {
   if (!headers) return undefined;
   const direct = headers[name];
-  if (direct !== undefined) return direct;
+  if (direct !== undefined) {
+    return typeof direct === "string" ? direct : direct[0];
+  }
   const normalized = name.toLowerCase();
   const entry = Object.entries(headers).find(
     ([key]) => key.toLowerCase() === normalized,
   );
-  return entry?.[1];
+  const value = entry?.[1];
+  return typeof value === "string" ? value : value?.[0];
 }
 
 function getResponseOwner(

package/src/server/request-executor.ts

@@ -82,6 +82,7 @@ import {
   PathDecodeError,
 } from "./route-matching.js";
 import type { TrustedRequestInfo } from "./trusted-proxy.js";
+import { InvalidRequestUrlError } from "./trusted-proxy-internal.js";
 
 function withoutHeadResponseBody(
   response: HttpResponse,
@@ -281,6 +282,19 @@ export function createRequestExecutor<
         };
       }
 
+      if (currentError instanceof InvalidRequestUrlError) {
+        return {
+          ctx,
+          response: errorResponse(
+            400,
+            "INVALID_REQUEST_URL",
+            "Malformed request URL",
+          ),
+          error: currentError,
+          owner: "framework",
+        };
+      }
+
       if (isAppError(currentError)) {
         return {
           ctx,

package/src/server/request-preparation.ts

@@ -41,6 +41,17 @@ type RequestValidationLocation = "query" | "path" | "headers" | "body";
 
 const DEFAULT_REQUEST_BODY_MAX_BYTES = 1024 * 1024;
 
+function cancelRequestBody(
+  source: { cancel(reason?: unknown): Promise<void> },
+  reason: unknown,
+): void {
+  try {
+    void source.cancel(reason).catch(() => {});
+  } catch {
+    // Cancellation is best-effort and must not replace the 413 response.
+  }
+}
+
 class RequestBodyTooLargeError extends Error {
   readonly maxBytes: number;
   readonly actualBytes?: number;
@@ -208,9 +219,16 @@ async function readLimitedRequestText(
   req: HttpRequestLike,
   maxBytes: number,
 ): Promise<string> {
-  assertContentLengthWithinLimit(req.headers, maxBytes);
-
   const body = req.raw?.body;
+  try {
+    assertContentLengthWithinLimit(req.headers, maxBytes);
+  } catch (error) {
+    if (body) {
+      cancelRequestBody(body, error);
+    }
+    throw error;
+  }
+
   if (!body) {
     const text = await req.text();
     const actualBytes = new TextEncoder().encode(text).byteLength;
@@ -231,7 +249,9 @@ async function readLimitedRequestText(
       if (result.done) break;
       received += result.value.byteLength;
       if (received > maxBytes) {
-        throw new RequestBodyTooLargeError(maxBytes, received);
+        const error = new RequestBodyTooLargeError(maxBytes, received);
+        cancelRequestBody(reader, error);
+        throw error;
       }
       text += decoder.decode(result.value, { stream: true });
     }

package/src/server/response-finalization.ts

@@ -9,7 +9,11 @@ import {
   isErrorResponseBody,
 } from "../errors/index.js";
 import { getRequestIdFromContext } from "./hooks/utils.js";
-import type { HttpResponse, HttpResponseLike } from "./http.js";
+import type {
+  HttpResponse,
+  HttpResponseHeaders,
+  HttpResponseLike,
+} from "./http.js";
 import type { ResponseFinalizerResponseOwner } from "./internal-hooks.js";
 import {
   parseStandardSchema,
@@ -76,7 +80,7 @@ export function withFrameworkErrorOwnerHeader(
 }
 
 function setRecordHeader(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   name: string,
   value: string,
 ): void {
@@ -89,6 +93,34 @@ function setRecordHeader(
   headers[name] = value;
 }
 
+function headerValues(value: string | readonly string[]): readonly string[] {
+  return typeof value === "string" ? [value] : value;
+}
+
+function sameHeaderValue(
+  left: string | readonly string[] | undefined,
+  right: string | readonly string[],
+): boolean {
+  if (left === undefined) return false;
+  const leftValues = headerValues(left);
+  const rightValues = headerValues(right);
+  return (
+    leftValues.length === rightValues.length &&
+    leftValues.every((value, index) => value === rightValues[index])
+  );
+}
+
+function appendHeaderValues(
+  headers: Headers,
+  name: string,
+  value: string | readonly string[],
+): void {
+  headers.delete(name);
+  for (const item of headerValues(value)) {
+    headers.append(name, item);
+  }
+}
+
 /** Apply contract-owned deprecation headers to any response representation. */
 export function withContractLifecycleHeaders(
   res: HttpResponse,
@@ -113,17 +145,18 @@ export function withContractLifecycleHeaders(
     });
   }
 
-  const headers = { ...(res.headers ?? {}) };
+  const headers: HttpResponseHeaders = { ...(res.headers ?? {}) };
   for (const [name, value] of Object.entries(lifecycleHeaders)) {
     if (name.toLowerCase() === "link") {
       const existingName = Object.keys(headers).find(
         (key) => key.toLowerCase() === "link",
       );
       const existing = existingName ? headers[existingName] : undefined;
+      const existingValue = existing ? headerValues(existing).join(", ") : "";
       setRecordHeader(
         headers,
         name,
-        existing ? `${existing}, ${value}` : value,
+        existingValue ? `${existingValue}, ${value}` : value,
       );
     } else {
       setRecordHeader(headers, name, value);
@@ -140,11 +173,18 @@ export function responseOwnerFor(
   return owner ?? "route";
 }
 
-function headersToRecord(headers: Headers): Record<string, string> {
-  const record: Record<string, string> = {};
+function headersToRecord(headers: Headers): HttpResponseHeaders {
+  const record: HttpResponseHeaders = {};
   headers.forEach((value, key) => {
     record[key] = value;
   });
+  const setCookies =
+    (headers as Headers & { getSetCookie?: () => string[] }).getSetCookie?.call(
+      headers,
+    ) ?? [];
+  if (setCookies.length > 0) {
+    record["set-cookie"] = setCookies;
+  }
   return record;
 }
 
@@ -169,10 +209,10 @@ export function responseForHooks(res: HttpResponse): HttpResponseLike {
  */
 export function mergeNativeResponseHeaders(
   nativeResponse: Response,
-  originalHeaders: Record<string, string>,
-  finalHeaders: Record<string, string>,
+  originalHeaders: HttpResponseHeaders,
+  finalHeaders: HttpResponseHeaders,
 ): Response {
-  const originalByLowerKey = new Map<string, string>();
+  const originalByLowerKey = new Map<string, string | readonly string[]>();
   for (const [key, value] of Object.entries(originalHeaders)) {
     originalByLowerKey.set(key.toLowerCase(), value);
   }
@@ -181,13 +221,9 @@ export function mergeNativeResponseHeaders(
   const merged = new Headers(nativeResponse.headers);
   for (const [key, value] of Object.entries(finalHeaders)) {
     const lowerKey = key.toLowerCase();
-    if (originalByLowerKey.get(lowerKey) === value) continue;
+    if (sameHeaderValue(originalByLowerKey.get(lowerKey), value)) continue;
     changed = true;
-    if (lowerKey === "set-cookie") {
-      merged.append(lowerKey, value);
-    } else {
-      merged.set(key, value);
-    }
+    appendHeaderValues(merged, key, value);
   }
 
   if (!changed) {

package/src/server/route-matching.ts

@@ -15,12 +15,35 @@ export class PathDecodeError extends Error {
   }
 }
 
+function encodeStaticSegment(value: string): string {
+  return encodeURI(value).replace(
+    /[?#]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+function matchPercentEncodingCase(value: string): string {
+  return value.replace(/%([0-9A-F]{2})/g, (_match, encoded: string) => {
+    const digits = [...encoded]
+      .map((digit) =>
+        /[A-F]/.test(digit) ? `[${digit}${digit.toLowerCase()}]` : digit,
+      )
+      .join("");
+    return `%${digits}`;
+  });
+}
+
 export function compilePath(path: string): CompiledPath {
   const parsed = parsePathTemplate(path);
   const regexParts = parsed.segments.map((segment) =>
     segment.kind === "dynamic"
       ? "([^/]+)"
-      : segment.value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+      : matchPercentEncodingCase(
+          encodeStaticSegment(segment.value).replace(
+            /[.*+?^${}()|[\]\\]/g,
+            "\\$&",
+          ),
+        ),
   );
   const pattern = new RegExp(`^/${regexParts.join("/")}$`);
   return { ...parsed, pattern };

package/src/server/server-sent-events.ts

@@ -0,0 +1,415 @@
+const DEFAULT_HEARTBEAT_MS = 25_000;
+const DEFAULT_MAX_BUFFERED_BYTES = 1_048_576;
+const MAX_BUFFERED_BYTES = 2_147_483_647;
+const MAX_TIMER_MS = 2_147_483_647;
+
+/**
+ * One JSON-encoded Server-Sent Event.
+ */
+export interface ServerSentEventMessage<TData = unknown> {
+  /** JSON-serializable event payload. */
+  data: TData;
+  /** Optional event type consumed by `EventSource.addEventListener(...)`. */
+  event?: string;
+  /** Optional event identifier used by browsers for `Last-Event-ID`. */
+  id?: string;
+  /** Optional browser reconnection delay in milliseconds. */
+  retry?: number;
+}
+
+/**
+ * Controls exposed while an SSE response is active.
+ */
+export interface ServerSentEventStream {
+  /**
+   * Aborts whenever this stream closes, including response cancellation.
+   * Async setup should pass it to cancellable subscription APIs.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Send a JSON-encoded event.
+   *
+   * Returns `false` after the stream closes, when encoding fails, or when the
+   * unread byte limit would be exceeded.
+   */
+  send<TData>(message: ServerSentEventMessage<TData>): boolean;
+  /**
+   * Send an SSE comment. Comments are useful as connection heartbeats.
+   *
+   * Returns `false` when the stream is no longer writable or its unread byte
+   * limit would be exceeded.
+   */
+  comment(value?: string): boolean;
+  /** Close the stream and run its cleanup exactly once. */
+  close(): void;
+}
+
+/** Closeable subscription returned by an SSE stream's `start` callback. */
+export interface ServerSentEventSubscription {
+  /** Close the associated subscription. */
+  close(): Promise<void> | void;
+}
+
+/** Cleanup returned by an SSE stream's `start` callback. */
+export type ServerSentEventCleanup =
+  | (() => Promise<void> | void)
+  | ServerSentEventSubscription;
+
+/** Options for `createServerSentEventResponse(...)`. */
+export interface ServerSentEventResponseOptions {
+  /**
+   * Begin producing events. Return a cleanup callback or closeable
+   * subscription for resources associated with this connection. Pending
+   * asynchronous setup does not block response cancellation; honor the stream
+   * signal and return cleanup when setup settles.
+   */
+  start(
+    stream: ServerSentEventStream,
+  ):
+    | Promise<ServerSentEventCleanup | undefined>
+    | ServerSentEventCleanup
+    | undefined;
+  /**
+   * Abort the stream with the surrounding request or application lifecycle.
+   */
+  signal?: AbortSignal;
+  /**
+   * Interval for SSE heartbeat comments. Defaults to 25 seconds. Set to
+   * `false` to disable heartbeats.
+   */
+  heartbeatMs?: number | false;
+  /**
+   * Close the connection after this duration so clients can reconnect and
+   * reconcile. Disabled by default.
+   */
+  maxLifetimeMs?: number | false;
+  /**
+   * Maximum bytes of unread event data held by the response stream. Defaults
+   * to 1 MiB. The connection closes when one frame or the accumulated queue
+   * would exceed this limit.
+   */
+  maxBufferedBytes?: number;
+  /** Additional response headers such as CORS or `Vary`. */
+  headers?: HeadersInit;
+  /**
+   * Observe producer, serialization, buffer, stream, or cleanup failures.
+   * Expected `AbortError` rejections caused by stream closure are ignored.
+   */
+  onError?(error: unknown): Promise<void> | void;
+}
+
+function assertTimerOption(
+  name: "heartbeatMs" | "maxLifetimeMs",
+  value: number | false | undefined,
+): void {
+  if (
+    value === false ||
+    value === undefined ||
+    (Number.isInteger(value) && value >= 1 && value <= MAX_TIMER_MS)
+  ) {
+    return;
+  }
+
+  throw new RangeError(
+    `${name} must be false or an integer between 1 and ${MAX_TIMER_MS} milliseconds.`,
+  );
+}
+
+function assertMaxBufferedBytes(value: number): void {
+  if (Number.isInteger(value) && value >= 1 && value <= MAX_BUFFERED_BYTES) {
+    return;
+  }
+
+  throw new RangeError(
+    `maxBufferedBytes must be an integer between 1 and ${MAX_BUFFERED_BYTES} bytes.`,
+  );
+}
+
+function assertSingleLine(name: "event" | "id", value: string): void {
+  if (value.includes("\r") || value.includes("\n")) {
+    throw new TypeError(`SSE ${name} must not contain line breaks.`);
+  }
+  if (name === "id" && value.includes("\0")) {
+    throw new TypeError("SSE id must not contain null characters.");
+  }
+}
+
+function isPromiseLike<T>(value: T | PromiseLike<T>): value is PromiseLike<T> {
+  return (
+    value !== null &&
+    (typeof value === "object" || typeof value === "function") &&
+    "then" in value &&
+    typeof value.then === "function"
+  );
+}
+
+function isAbortError(error: unknown): boolean {
+  try {
+    return (
+      typeof error === "object" &&
+      error !== null &&
+      "name" in error &&
+      error.name === "AbortError"
+    );
+  } catch {
+    return false;
+  }
+}
+
+function encodeMessage<TData>(message: ServerSentEventMessage<TData>): string {
+  if (message.event !== undefined) {
+    assertSingleLine("event", message.event);
+  }
+  if (message.id !== undefined) {
+    assertSingleLine("id", message.id);
+  }
+  if (
+    message.retry !== undefined &&
+    (!Number.isInteger(message.retry) ||
+      message.retry < 0 ||
+      message.retry > MAX_TIMER_MS)
+  ) {
+    throw new RangeError(
+      `SSE retry must be an integer between 0 and ${MAX_TIMER_MS} milliseconds.`,
+    );
+  }
+
+  const data = JSON.stringify(message.data);
+  if (data === undefined) {
+    throw new TypeError("SSE data must be JSON-serializable.");
+  }
+
+  const fields: string[] = [];
+  if (message.event !== undefined) fields.push(`event: ${message.event}`);
+  if (message.id !== undefined) fields.push(`id: ${message.id}`);
+  if (message.retry !== undefined) fields.push(`retry: ${message.retry}`);
+  fields.push(`data: ${data}`);
+  return `${fields.join("\n")}\n\n`;
+}
+
+function encodeComment(value: string): string {
+  return `${value
+    .split(/\r\n|\r|\n/)
+    .map((line) => `: ${line}`)
+    .join("\n")}\n\n`;
+}
+
+function createResponseHeaders(init: HeadersInit | undefined): Headers {
+  const headers = new Headers(init);
+  headers.set("Content-Type", "text/event-stream; charset=utf-8");
+  headers.set("Cache-Control", "no-store, no-transform");
+  headers.set("X-Accel-Buffering", "no");
+  headers.delete("Connection");
+  headers.delete("Content-Length");
+  headers.delete("Transfer-Encoding");
+  return headers;
+}
+
+/**
+ * Create a portable Fetch `Response` that safely manages a Server-Sent Events
+ * stream.
+ *
+ * The helper owns SSE framing, JSON encoding, heartbeats, abort handling,
+ * bounded unread buffering, maximum lifetime, and cleanup. Authentication,
+ * replay, authorization, connection limits, and application reconciliation
+ * remain the caller's responsibility.
+ */
+export function createServerSentEventResponse(
+  options: ServerSentEventResponseOptions,
+): Response {
+  const heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+  const maxBufferedBytes =
+    options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+  assertTimerOption("heartbeatMs", heartbeatMs);
+  assertTimerOption("maxLifetimeMs", options.maxLifetimeMs);
+  assertMaxBufferedBytes(maxBufferedBytes);
+  const headers = createResponseHeaders(options.headers);
+
+  const encoder = new TextEncoder();
+  const lifecycleController = new AbortController();
+  let cleanup: ServerSentEventCleanup | undefined;
+  let cleanupPromise: Promise<void> | undefined;
+  let closed = false;
+  let heartbeatTimer: ReturnType<typeof setInterval> | undefined;
+  let lifetimeTimer: ReturnType<typeof setTimeout> | undefined;
+  let abortListener: (() => void) | undefined;
+  let closeStream: (() => void) | undefined;
+
+  const reportError = (error: unknown): void => {
+    if (!options.onError) return;
+    void Promise.resolve()
+      .then(() => options.onError?.(error))
+      .catch(() => undefined);
+  };
+
+  const runCleanup = (): Promise<void> => {
+    if (cleanupPromise) return cleanupPromise;
+    if (!cleanup) return Promise.resolve();
+    const activeCleanup = cleanup;
+    cleanupPromise = Promise.resolve()
+      .then(() =>
+        typeof activeCleanup === "function"
+          ? activeCleanup()
+          : activeCleanup.close(),
+      )
+      .catch(reportError);
+    return cleanupPromise;
+  };
+
+  const stream = new ReadableStream<Uint8Array>(
+    {
+      start(controller) {
+        const clearLifecycle = () => {
+          if (heartbeatTimer !== undefined) clearInterval(heartbeatTimer);
+          if (lifetimeTimer !== undefined) clearTimeout(lifetimeTimer);
+          if (abortListener) {
+            options.signal?.removeEventListener("abort", abortListener);
+          }
+        };
+
+        const close = () => {
+          if (closed) return;
+          closed = true;
+          clearLifecycle();
+          lifecycleController.abort();
+          void runCleanup();
+          try {
+            controller.close();
+          } catch {
+            // Cancellation may already have detached the stream controller.
+          }
+        };
+        closeStream = close;
+
+        const enqueue = (value: string): boolean => {
+          if (closed) return false;
+          try {
+            const chunk = encoder.encode(value);
+            const availableBytes = controller.desiredSize;
+            if (availableBytes === null || chunk.byteLength > availableBytes) {
+              reportError(
+                new RangeError(
+                  `SSE buffer limit of ${maxBufferedBytes} bytes exceeded.`,
+                ),
+              );
+              close();
+              return false;
+            }
+            controller.enqueue(chunk);
+            return true;
+          } catch (error) {
+            reportError(error);
+            close();
+            return false;
+          }
+        };
+
+        const controls: ServerSentEventStream = {
+          signal: lifecycleController.signal,
+          send(message) {
+            if (closed) return false;
+            try {
+              return enqueue(encodeMessage(message));
+            } catch (error) {
+              reportError(error);
+              close();
+              return false;
+            }
+          },
+          comment(value = "") {
+            if (closed) return false;
+            try {
+              return enqueue(encodeComment(value));
+            } catch (error) {
+              reportError(error);
+              close();
+              return false;
+            }
+          },
+          close,
+        };
+
+        if (options.signal?.aborted) {
+          close();
+          return;
+        }
+
+        abortListener = close;
+        options.signal?.addEventListener("abort", abortListener, {
+          once: true,
+        });
+
+        if (heartbeatMs !== false) {
+          heartbeatTimer = setInterval(() => {
+            controls.comment("heartbeat");
+          }, heartbeatMs);
+        }
+        if (
+          options.maxLifetimeMs !== undefined &&
+          options.maxLifetimeMs !== false
+        ) {
+          lifetimeTimer = setTimeout(close, options.maxLifetimeMs);
+        }
+
+        const registerCleanup = (
+          resolvedCleanup: ServerSentEventCleanup | undefined,
+        ): void => {
+          try {
+            if (
+              typeof resolvedCleanup === "function" ||
+              (typeof resolvedCleanup === "object" &&
+                resolvedCleanup !== null &&
+                "close" in resolvedCleanup &&
+                typeof resolvedCleanup.close === "function")
+            ) {
+              cleanup = resolvedCleanup;
+              if (closed) void runCleanup();
+            } else if (resolvedCleanup !== undefined) {
+              reportError(
+                new TypeError(
+                  "SSE start must return a cleanup function, a closeable subscription, or nothing.",
+                ),
+              );
+              close();
+            }
+          } catch (error) {
+            reportError(error);
+            close();
+          }
+        };
+
+        const handleStartError = (error: unknown): void => {
+          if (!(closed && isAbortError(error))) reportError(error);
+          close();
+        };
+
+        try {
+          const result = options.start(controls);
+          if (isPromiseLike<ServerSentEventCleanup | undefined>(result)) {
+            void Promise.resolve(result).then(
+              registerCleanup,
+              handleStartError,
+            );
+          } else {
+            registerCleanup(result);
+          }
+        } catch (error) {
+          handleStartError(error);
+        }
+      },
+      cancel() {
+        closeStream?.();
+        return runCleanup();
+      },
+    },
+    {
+      highWaterMark: maxBufferedBytes,
+      size: (chunk) => chunk?.byteLength ?? 0,
+    },
+  );
+
+  return new Response(stream, {
+    status: 200,
+    headers,
+  });
+}