@beignet/core 0.0.48 → 0.0.50

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,
+  });
+}

package/src/server/server.ts

@@ -78,7 +78,10 @@ import {
   type TrustedProxyConfig,
   type TrustedRequestInfo,
 } from "./trusted-proxy.js";
-import { assertValidTrustedProxyConfig } from "./trusted-proxy-internal.js";
+import {
+  assertValidTrustedProxyConfig,
+  parseHttpRequestUrl,
+} from "./trusted-proxy-internal.js";
 import {
   createUseCaseRouteHandler,
   isUseCaseRouteDef,
@@ -539,7 +542,7 @@ export async function createServer<
   ): Promise<unknown> => {
     if (!serviceContextsAvailable) {
       throw new Error(
-        "Service contexts are unavailable until providers have started.",
+        "Service contexts are unavailable during provider setup and after provider shutdown.",
       );
     }
 
@@ -553,16 +556,20 @@ export async function createServer<
     if (stopped) return;
     stopped = true;
     const errors: unknown[] = [];
-    for (let i = providerResults.length - 1; i >= 0; i -= 1) {
-      const result = providerResults[i];
-      try {
-        await result?.stop?.({
-          ports: finalPorts,
-          createServiceContext: lifecycleCreateServiceContext,
-        });
-      } catch (err) {
-        errors.push(err);
+    try {
+      for (let i = providerResults.length - 1; i >= 0; i -= 1) {
+        const result = providerResults[i];
+        try {
+          await result?.stop?.({
+            ports: finalPorts,
+            createServiceContext: lifecycleCreateServiceContext,
+          });
+        } catch (err) {
+          errors.push(err);
+        }
       }
+    } finally {
+      serviceContextsAvailable = false;
     }
     if (errors.length) {
       throw new AggregateError(errors, "Provider shutdown errors");
@@ -744,16 +751,6 @@ export async function createServer<
       providerResults.push(result);
     }
 
-    for (const result of providerResults) {
-      if (!result.start) continue;
-      await result.start({
-        ports: finalPorts,
-        createServiceContext: lifecycleCreateServiceContext,
-      });
-    }
-
-    instrumentation.attachPorts(finalPorts);
-
     const onUnboundPorts = options.onUnboundPorts ?? "error";
     if (onUnboundPorts !== "ignore") {
       const unboundKeys = Object.keys(finalPorts).filter((key) =>
@@ -772,7 +769,20 @@ export async function createServer<
       }
     }
 
+    // Every provider has now contributed its ports and the unbound-port guard
+    // has passed. Start hooks may safely build service contexts while they
+    // activate consumers such as event listeners.
     serviceContextsAvailable = true;
+
+    for (const result of providerResults) {
+      if (!result.start) continue;
+      await result.start({
+        ports: finalPorts,
+        createServiceContext: lifecycleCreateServiceContext,
+      });
+    }
+
+    instrumentation.attachPorts(finalPorts);
   } catch (error) {
     try {
       await stop();
@@ -807,6 +817,7 @@ export async function createServer<
     path,
     pathParams: null,
     query: null,
+    queryTransport: null,
     body: null,
     responses: {},
     metadata: {},
@@ -821,8 +832,22 @@ export async function createServer<
       registryNeedsSort = false;
     }
 
-    const url = new URL(req.url);
     const method = req.method.toUpperCase();
+    let url: URL;
+    try {
+      url = parseHttpRequestUrl(req.url);
+    } catch (error) {
+      return await executeFallback(
+        {
+          contract: fallbackContract("invalidRequestUrl", method, "/"),
+          handler: async () => {
+            throw error;
+          },
+        },
+        req,
+        {},
+      );
+    }
 
     let pathMatchedMethods: Set<string> | undefined;
     let headCandidate: RegisteredRoute | undefined;
@@ -929,6 +954,7 @@ function rawRouteContract(init: RawRouteInit): HttpContractConfig {
     path: init.path,
     pathParams: null,
     query: null,
+    queryTransport: null,
     body: null,
     responses: {},
     metadata: init.metadata ?? {},

package/src/server/trusted-proxy-internal.ts

@@ -1,5 +1,25 @@
 import type { TrustedProxyConfig } from "./trusted-proxy.js";
 
+export class InvalidRequestUrlError extends Error {
+  constructor() {
+    super("req.url must be an absolute HTTP or HTTPS URL.");
+    this.name = "InvalidRequestUrlError";
+  }
+}
+
+export function parseHttpRequestUrl(value: string): URL {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new InvalidRequestUrlError();
+    }
+    return url;
+  } catch (error) {
+    if (error instanceof InvalidRequestUrlError) throw error;
+    throw new InvalidRequestUrlError();
+  }
+}
+
 export function requireTrustedProxyHeaderName(
   name: string,
   optionName: string,

package/src/server/trusted-proxy.ts

@@ -1,5 +1,8 @@
 import type { HttpRequestLike } from "./http.js";
-import { requireTrustedProxyHeaderName } from "./trusted-proxy-internal.js";
+import {
+  parseHttpRequestUrl,
+  requireTrustedProxyHeaderName,
+} from "./trusted-proxy-internal.js";
 
 /**
  * Header source used to resolve a client IP after an app has explicitly opted
@@ -141,17 +144,13 @@ function normalizeHost(
 }
 
 function baseRequestUrl(req: HttpRequestLike): URL {
-  try {
-    return new URL(req.url);
-  } catch {
-    throw new Error("req.url must be an absolute URL.");
-  }
+  return parseHttpRequestUrl(req.url);
 }
 
 function normalizedBaseProtocol(url: URL): "http" | "https" {
   const protocol = normalizeProtocol(url.protocol);
   if (protocol) return protocol;
-  throw new Error("req.url must use http or https.");
+  throw new Error("Resolved request URL must use HTTP or HTTPS.");
 }
 
 /**