@streamotter/gateway 0.1.0-rc.1

package/dist/transport/socketio.js

@@ -0,0 +1,80 @@
+import { Server } from "socket.io";
+import { EVENTS, HELLO_TIMEOUT_MS } from "@streamotter/contracts";
+const KNOWN_EVENTS = new Set([EVENTS.subscribe, EVENTS.unsubscribe, EVENTS.resync, EVENTS.receipt]);
+class SocketIoConnection {
+    #socket;
+    constructor(socket) {
+        this.#socket = socket;
+    }
+    sendHello(hello) {
+        this.#socket.emit("so:hello", hello);
+    }
+    sendState(frame) {
+        this.#socket.emit("so:state", frame);
+    }
+    sendData(frame) {
+        this.#socket.emit("so:data", frame);
+    }
+    sendError(frame) {
+        this.#socket.emit("so:error", frame);
+    }
+    close() {
+        this.#socket.disconnect(true);
+    }
+}
+/**
+ * Socket.IO adapter: namespace "/", WebSocket-only transport, connection-state
+ * recovery disabled (V1 owns resynchronization), control frames bounded by
+ * maxControlFrameBytes. Authentication runs in handshake middleware so failures
+ * reach the SDK as structured connect errors.
+ */
+export function attachSocketIo(httpServer, options) {
+    const io = new Server(httpServer, {
+        path: options.path,
+        serveClient: false,
+        transports: ["websocket"],
+        allowUpgrades: false,
+        maxHttpBufferSize: options.maxControlFrameBytes,
+        connectTimeout: HELLO_TIMEOUT_MS,
+        pingInterval: 25_000,
+        pingTimeout: 20_000
+    });
+    io.use((socket, next) => {
+        const origin = socket.handshake.headers.origin;
+        options.callbacks.authenticate({ auth: socket.handshake.auth, origin }).then(result => {
+            if (!result.ok) {
+                const error = new Error(result.error.message);
+                error.data = result.error;
+                next(error);
+                return;
+            }
+            socket.data.handshake = result.value;
+            next();
+        }, () => {
+            const error = new Error("An unexpected error occurred.");
+            error.data = { code: "INTERNAL", message: "An unexpected error occurred.", retryable: true, requestId: "" };
+            next(error);
+        });
+    });
+    io.on("connection", socket => {
+        const handshake = socket.data.handshake;
+        if (handshake === undefined) {
+            socket.disconnect(true);
+            return;
+        }
+        const session = options.callbacks.openSession(handshake, new SocketIoConnection(socket));
+        const untyped = socket;
+        untyped.on(EVENTS.subscribe, (payload, reply) => session.handleSubscribe(payload, reply));
+        untyped.on(EVENTS.unsubscribe, (payload, reply) => session.handleUnsubscribe(payload, reply));
+        untyped.on(EVENTS.resync, (payload, reply) => session.handleResync(payload, reply));
+        untyped.on(EVENTS.receipt, (payload) => session.handleReceipt(payload));
+        untyped.onAny((event, ...args) => {
+            if (typeof event !== "string" || !KNOWN_EVENTS.has(event))
+                session.handleUnknown(String(event), args);
+        });
+        socket.on("disconnect", () => session.handleTransportClosed());
+        session.open();
+    });
+    return io;
+}
+//# sourceMappingURL=socketio.js.map

package/dist/transport/socketio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socketio.js","sourceRoot":"","sources":["../../src/transport/socketio.ts"],"names":[],"mappings":"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"}

package/dist/transport/types.d.ts

@@ -0,0 +1,10 @@
+import type { DataFrame, ErrorFrame, Hello, SubscriptionFrame } from "@streamotter/contracts";
+/** Server-side view of one client transport connection. Transport specifics stay in the adapter. */
+export interface ConnectionTransport {
+    sendHello(hello: Hello): void;
+    sendState(frame: SubscriptionFrame): void;
+    sendData(frame: DataFrame): void;
+    sendError(frame: ErrorFrame): void;
+    close(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/transport/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transport/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE9F,oGAAoG;AACpG,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC9B,SAAS,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACjC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/transport/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/transport/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/transport/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@streamotter/gateway",
+  "version": "0.1.0-rc.1",
+  "description": "StreamOtter Node.js gateway: Kafka and fixture sources, application-owned access handlers, snapshot synchronization, and bounded Socket.IO delivery.",
+  "keywords": [
+    "streamotter",
+    "kafka",
+    "kafkajs",
+    "socket.io",
+    "websocket",
+    "realtime",
+    "live-data",
+    "state-sync",
+    "gateway",
+    "typescript"
+  ],
+  "homepage": "https://github.com/jfricano/StreamOtter/tree/main/packages/gateway#readme",
+  "bugs": {
+    "url": "https://github.com/jfricano/StreamOtter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jfricano/StreamOtter.git",
+    "directory": "packages/gateway"
+  },
+  "license": "MIT",
+  "author": "Orca Solutions",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./management": {
+      "types": "./dist/management/index.d.ts",
+      "default": "./dist/management/index.js"
+    },
+    "./internals": {
+      "types": "./dist/internals.d.ts",
+      "default": "./dist/internals.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "kafkajs": "2.2.4",
+    "socket.io": "4.8.3",
+    "@streamotter/contracts": "0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.6"
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+import { assertValidProjectConfig, type ChannelMap, type Gateway, type GatewayOptions, type ProjectConfig } from "@streamotter/contracts";
+import { createGatewayRuntime } from "./runtime/gateway.ts";
+
+export type * from "@streamotter/contracts";
+export { StreamOtterError, validateProjectConfig } from "@streamotter/contracts";
+export { consoleLogger, silentLogger } from "./runtime/util.ts";
+
+/**
+ * Validates configuration structure and references synchronously. Secret
+ * resolution and connectivity belong to gateway startup. Throws CONFIG_INVALID.
+ */
+export function defineProject<C extends ChannelMap>(config: ProjectConfig<C>): ProjectConfig<C> {
+  assertValidProjectConfig(config);
+  return config;
+}
+
+/** Constructs a gateway without opening connections; call start() to listen and consume. */
+export function createGateway<C extends ChannelMap>(options: GatewayOptions<C>): Gateway {
+  return createGatewayRuntime(options).gateway;
+}

package/src/internals.ts

@@ -0,0 +1,5 @@
+/**
+ * Internal access shared by StreamOtter's own CLI, management server, and tests.
+ * Not a stable public API; applications should use createGateway().
+ */
+export { createGatewayRuntime, getGatewayInternals, type GatewayInternals, type InternalGatewayOptions } from "./runtime/gateway.ts";

package/src/management/index.ts

@@ -0,0 +1,371 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { extname, join, resolve as resolvePath, sep } from "node:path";
+import {
+  canonicalJsonPretty, CAPABILITIES, DEFAULT_MANAGEMENT_PORT, isPlainObject, streamError, StreamOtterError,
+  validateProjectConfig, type ErrorCode, type Gateway, type Json, type Result, type StreamError, type Trace
+} from "@streamotter/contracts";
+import { getGatewayInternals, type GatewayInternals } from "../runtime/gateway.ts";
+import { newId, sha256Hex, TokenBucket } from "../runtime/util.ts";
+
+export interface ManagementServerOptions {
+  gateway: Gateway;
+  /** Loopback by default. */
+  host?: string;
+  port?: number;
+  /** Per-run bearer token; generated when omitted. */
+  token?: string;
+  /** Built workbench assets to serve from the same origin; null disables the UI. */
+  workbenchDir?: string | null;
+}
+
+export interface ManagementServer {
+  readonly origin: string;
+  readonly token: string;
+  close(): Promise<void>;
+}
+
+const MAX_BODY_BYTES = 1_048_576;
+
+const STATUS_BY_CODE: Partial<Record<ErrorCode, number>> = {
+  INVALID_REQUEST: 400, INVALID_PARAMS: 400, CONFIG_INVALID: 400, UNSUPPORTED_CAPABILITY: 400,
+  UNAUTHENTICATED: 401, FORBIDDEN: 403, CHANNEL_NOT_FOUND: 404, TRACE_CURSOR_EXPIRED: 410,
+  OVERLOADED: 429, SOURCE_UNAVAILABLE: 503, TIMEOUT: 504
+};
+
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8"
+};
+
+class HttpError extends Error {
+  readonly status: number;
+  readonly error: StreamError;
+
+  constructor(status: number, code: ErrorCode, message?: string, details?: Readonly<Record<string, Json>>) {
+    super(message ?? code);
+    this.status = status;
+    const options: { message?: string; details?: Readonly<Record<string, Json>> } = {};
+    if (message !== undefined) options.message = message;
+    if (details !== undefined) options.details = details;
+    this.error = streamError(code, options);
+  }
+}
+
+function tokensEqual(expected: string, provided: string): boolean {
+  const a = Buffer.from(expected);
+  const b = Buffer.from(provided);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+async function readJsonBody(request: IncomingMessage): Promise<unknown> {
+  const declared = Number(request.headers["content-length"] ?? "0");
+  if (declared > MAX_BODY_BYTES) throw new HttpError(413, "INVALID_REQUEST", "The request body exceeds 1 MiB.");
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += (chunk as Buffer).length;
+    if (size > MAX_BODY_BYTES) throw new HttpError(413, "INVALID_REQUEST", "The request body exceeds 1 MiB.");
+    chunks.push(chunk as Buffer);
+  }
+  if (size === 0) throw new HttpError(400, "INVALID_REQUEST", "A JSON body is required.");
+  const type = request.headers["content-type"] ?? "";
+  if (!/^application\/json\b/i.test(type)) throw new HttpError(400, "INVALID_REQUEST", "Content-Type must be application/json.");
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    throw new HttpError(400, "INVALID_REQUEST", "The body is not valid JSON.");
+  }
+}
+
+/** Requires an object with exactly the listed keys (optional keys may be absent). */
+function shape(value: unknown, required: readonly string[], optional: readonly string[] = []): Record<string, unknown> {
+  if (!isPlainObject(value)) throw new HttpError(400, "INVALID_REQUEST", "The body must be a JSON object.");
+  for (const key of Object.keys(value)) {
+    if (!required.includes(key) && !optional.includes(key)) throw new HttpError(400, "INVALID_REQUEST", `Unknown field "${key.slice(0, 64)}".`);
+  }
+  for (const key of required) {
+    if (!Object.hasOwn(value, key)) throw new HttpError(400, "INVALID_REQUEST", `"${key}" is required.`);
+  }
+  return value;
+}
+
+function requireString(value: unknown, name: string): string {
+  if (typeof value !== "string" || value.length === 0 || value.length > 256) throw new HttpError(400, "INVALID_REQUEST", `${name} must be a non-empty string.`);
+  return value;
+}
+
+function mapError(error: unknown): { status: number; error: StreamError } {
+  if (error instanceof HttpError) return { status: error.status, error: error.error };
+  if (error instanceof StreamOtterError) {
+    const status = typeof error.details?.["status"] === "number" ? error.details["status"] : STATUS_BY_CODE[error.code] ?? 500;
+    const { status: _omit, ...details } = (error.details ?? {}) as Record<string, Json>;
+    const options: { message: string; retryable: boolean; details?: Readonly<Record<string, Json>> } = { message: error.message, retryable: error.retryable };
+    if (Object.keys(details).length > 0) options.details = details;
+    return { status, error: streamError(error.code, options) };
+  }
+  return { status: 500, error: streamError("INTERNAL") };
+}
+
+/**
+ * Local development management API and workbench host. Every /management/v1
+ * operation requires the per-run bearer token. Browser requests must carry the
+ * exact workbench Origin (or, for same-origin GETs, a same-origin Referer). No
+ * CORS is ever granted. Refuses to start for production gateways.
+ */
+export async function startManagementServer(options: ManagementServerOptions): Promise<ManagementServer> {
+  const internals = getGatewayInternals(options.gateway);
+  if (internals.mode !== "development") {
+    throw new StreamOtterError("FORBIDDEN", { message: "The management API is only available in development mode." });
+  }
+  const token = options.token ?? randomBytes(24).toString("base64url");
+  const host = options.host ?? "127.0.0.1";
+  const workbenchDir = options.workbenchDir === undefined || options.workbenchDir === null ? null : await realpath(options.workbenchDir).catch(() => null);
+  const bucket = new TokenBucket(100, 200);
+  let origin = "";
+
+  const server = createServer((request, response) => {
+    const requestId = newId();
+    response.setHeader("X-Request-Id", requestId);
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("X-Content-Type-Options", "nosniff");
+    response.setHeader("Referrer-Policy", "same-origin");
+    response.setHeader("X-Frame-Options", "DENY");
+    handle(request, response, requestId).catch(error => {
+      const mapped = mapError(error);
+      if (mapped.status === 500) internals.logger.error("Management request failed", { requestId, error: String((error as Error)?.name ?? "Error") });
+      send(response, mapped.status, { ok: false, requestId, error: { ...mapped.error, requestId } });
+    });
+  });
+
+  function send(response: ServerResponse, status: number, body: Result<unknown>): void {
+    if (response.headersSent) {
+      response.end();
+      return;
+    }
+    response.statusCode = status;
+    response.setHeader("Content-Type", "application/json; charset=utf-8");
+    response.end(JSON.stringify(body));
+  }
+
+  function checkBrowserOrigin(request: IncomingMessage): void {
+    const requestOrigin = request.headers.origin;
+    if (requestOrigin !== undefined) {
+      if (requestOrigin !== origin) throw new HttpError(403, "FORBIDDEN", "Cross-origin management requests are not allowed.");
+      return;
+    }
+    const referer = request.headers.referer;
+    if (referer !== undefined) {
+      if (request.method !== "GET" || !(referer === origin || referer.startsWith(`${origin}/`))) {
+        throw new HttpError(403, "FORBIDDEN", "Cross-origin management requests are not allowed.");
+      }
+    }
+  }
+
+  function query(url: URL, allowed: readonly string[]): Record<string, string> {
+    const values: Record<string, string> = {};
+    for (const [key, value] of url.searchParams) {
+      if (!allowed.includes(key)) throw new HttpError(400, "INVALID_REQUEST", `Unknown query parameter "${key.slice(0, 64)}".`);
+      if (Object.hasOwn(values, key)) throw new HttpError(400, "INVALID_REQUEST", `Duplicate query parameter "${key.slice(0, 64)}".`);
+      values[key] = value;
+    }
+    return values;
+  }
+
+  async function handle(request: IncomingMessage, response: ServerResponse, requestId: string): Promise<void> {
+    const url = new URL(request.url ?? "/", "http://management.invalid");
+    if (!url.pathname.startsWith("/management/")) {
+      await serveStatic(request, response, url.pathname);
+      return;
+    }
+    checkBrowserOrigin(request);
+    const authorization = request.headers.authorization ?? "";
+    const provided = /^Bearer (.+)$/.exec(authorization)?.[1] ?? "";
+    if (!tokensEqual(token, provided)) throw new HttpError(401, "UNAUTHENTICATED", "A valid management bearer token is required.");
+    if (!bucket.take()) throw new HttpError(429, "OVERLOADED", "Too many management requests.");
+    const route = `${request.method ?? "GET"} ${url.pathname}`;
+    const ok = (data: unknown) => send(response, 200, { ok: true, requestId, data });
+    const noQuery = () => query(url, []);
+
+    switch (route) {
+      case "GET /management/v1/capabilities":
+        noQuery();
+        return ok(CAPABILITIES);
+      case "GET /management/v1/health":
+        noQuery();
+        return ok(internals.health());
+      case "GET /management/v1/sources":
+        noQuery();
+        return ok({ items: internals.sources() });
+      case "GET /management/v1/channels":
+        noQuery();
+        return ok({ items: internals.channels() });
+      case "GET /management/v1/config":
+        noQuery();
+        return ok({ config: internals.config, fingerprint: internals.fingerprint });
+      case "GET /management/v1/traces": {
+        const q = query(url, ["limit", "cursor", "sourceId", "channel", "outcome"]);
+        let limit = 100;
+        if (q["limit"] !== undefined) {
+          if (!/^\d{1,3}$/.test(q["limit"])) throw new HttpError(400, "INVALID_REQUEST", "limit must be an integer from 1 to 500.");
+          limit = Number(q["limit"]);
+          if (limit < 1 || limit > 500) throw new HttpError(400, "INVALID_REQUEST", "limit must be an integer from 1 to 500.");
+        }
+        const outcome = q["outcome"];
+        if (outcome !== undefined && !["ok", "filtered", "rejected", "failed"].includes(outcome)) {
+          throw new HttpError(400, "INVALID_REQUEST", "outcome must be ok, filtered, rejected, or failed.");
+        }
+        const page = internals.traces({
+          limit,
+          ...(q["cursor"] === undefined ? {} : { cursor: q["cursor"] }),
+          ...(q["sourceId"] === undefined ? {} : { sourceId: q["sourceId"] }),
+          ...(q["channel"] === undefined ? {} : { channel: q["channel"] }),
+          ...(outcome === undefined ? {} : { outcome: outcome as Trace["outcome"] })
+        });
+        return ok(page);
+      }
+      case "GET /management/v1/dev/principals":
+        noQuery();
+        return ok({ items: internals.developmentPrincipals() });
+      default:
+        break;
+    }
+
+    if (request.method !== "POST") throw new HttpError(404, "INVALID_REQUEST", "Unknown management route.");
+    noQuery();
+    const body = await readJsonBody(request);
+    switch (route) {
+      case "POST /management/v1/source-checks": {
+        const sourceId = requireString(shape(body, ["sourceId"])["sourceId"], "sourceId");
+        return ok({ steps: await internals.checkSource(sourceId) });
+      }
+      case "POST /management/v1/config/validate": {
+        const { config } = shape(body, ["config"]);
+        return ok(validateProjectConfig(config));
+      }
+      case "POST /management/v1/config/export": {
+        const { config } = shape(body, ["config"]);
+        const validation = validateProjectConfig(config);
+        if (!validation.valid) {
+          throw new HttpError(400, "CONFIG_INVALID", "The configuration is invalid and was not exported.", {
+            issues: validation.issues.map(issue => ({ path: issue.path, code: issue.code, message: issue.message }))
+          });
+        }
+        return ok({ filename: "streamotter.json", content: canonicalJsonPretty(config), fingerprint: sha256Hex(config) });
+      }
+      case "POST /management/v1/sources/resume": {
+        const sourceId = requireString(shape(body, ["sourceId"])["sourceId"], "sourceId");
+        return ok(await internals.resumeSource(sourceId));
+      }
+      case "POST /management/v1/preview-sessions": {
+        const ref = requireString(shape(body, ["fixturePrincipalRef"])["fixturePrincipalRef"], "fixturePrincipalRef");
+        return ok(internals.createPreviewSession(ref));
+      }
+      case "POST /management/v1/dev/fixtures/advance": {
+        const fields = shape(body, ["sourceId", "count"]);
+        const sourceId = requireString(fields["sourceId"], "sourceId");
+        const count = fields["count"];
+        if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 1 || count > 100) {
+          throw new HttpError(400, "INVALID_REQUEST", "count must be an integer from 1 to 100.");
+        }
+        return ok({ advanced: await internals.advanceFixture(sourceId, count) });
+      }
+      case "POST /management/v1/dev/disconnect": {
+        const previewSessionId = requireString(shape(body, ["previewSessionId"])["previewSessionId"], "previewSessionId");
+        internals.disconnectPreviewSession(previewSessionId);
+        return ok(null);
+      }
+      default:
+        throw new HttpError(404, "INVALID_REQUEST", "Unknown management route.");
+    }
+  }
+
+  async function serveStatic(request: IncomingMessage, response: ServerResponse, pathname: string): Promise<void> {
+    if (workbenchDir === null || (request.method !== "GET" && request.method !== "HEAD")) {
+      response.statusCode = 404;
+      response.end();
+      return;
+    }
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(pathname);
+    } catch {
+      response.statusCode = 400;
+      response.end();
+      return;
+    }
+    const relative = decoded === "/" ? "index.html" : decoded.replace(/^\/+/, "");
+    const file = resolvePath(workbenchDir, relative);
+    if (!file.startsWith(workbenchDir + sep) || relative.includes("\0")) {
+      response.statusCode = 404;
+      response.end();
+      return;
+    }
+    let target = file;
+    try {
+      const info = await stat(target);
+      if (info.isDirectory()) target = join(target, "index.html");
+      const real = await realpath(target);
+      if (!real.startsWith(workbenchDir + sep)) throw new Error("outside");
+      let content: Buffer | string = await readFile(real);
+      if (extname(real) === ".html") {
+        // Tell the workbench where the gateway listens (not secret; the token is never embedded).
+        const address = internals.address();
+        const escape = (value: string) => value.replace(/[&"<>]/g, character => `&#${character.charCodeAt(0)};`);
+        const meta = address === null ? "" :
+          `<meta name="streamotter-gateway-origin" content="${escape(address.origin)}"><meta name="streamotter-gateway-path" content="${escape(address.path)}">`;
+        content = content.toString("utf8").replace("</head>", `${meta}</head>`);
+      }
+      response.statusCode = 200;
+      response.setHeader("Content-Type", CONTENT_TYPES[extname(real)] ?? "application/octet-stream");
+      const gatewayOrigin = internals.address()?.origin ?? "";
+      const socketOrigin = gatewayOrigin.replace(/^http/, "ws");
+      response.setHeader("Content-Security-Policy", [
+        "default-src 'self'",
+        `connect-src 'self' ${gatewayOrigin} ${socketOrigin}`.trim(),
+        "img-src 'self' data:",
+        "style-src 'self'",
+        "script-src 'self'",
+        "frame-ancestors 'none'",
+        "base-uri 'none'",
+        "form-action 'none'"
+      ].join("; "));
+      response.end(request.method === "HEAD" ? undefined : content);
+    } catch {
+      response.statusCode = 404;
+      response.end();
+    }
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port ?? DEFAULT_MANAGEMENT_PORT, host, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const address = server.address() as AddressInfo;
+  origin = `http://${host.includes(":") ? `[${host}]` : host}:${address.port}`;
+  internals.allowDevelopmentOrigin(origin);
+
+  let closing: Promise<void> | null = null;
+  const close = () => {
+    closing ??= new Promise<void>(resolve => {
+      server.close(() => resolve());
+      server.closeAllConnections();
+    });
+    return closing;
+  };
+  internals.onStop(close);
+  return { origin, token, close };
+}
+
+export type { GatewayInternals };

package/src/runtime/budget.ts

@@ -0,0 +1,60 @@
+/**
+ * Hierarchical byte budget: subscription → connection → gateway. A reservation
+ * succeeds only if every level has room, and is applied to every level.
+ */
+export class ByteBudget {
+  readonly limit: number;
+  readonly parent: ByteBudget | null;
+  #used = 0;
+
+  constructor(limit: number, parent: ByteBudget | null = null) {
+    this.limit = limit;
+    this.parent = parent;
+  }
+
+  get used(): number {
+    return this.#used;
+  }
+
+  tryReserve(bytes: number): boolean {
+    for (let node: ByteBudget | null = this; node !== null; node = node.parent) {
+      if (node.#used + bytes > node.limit) return false;
+    }
+    for (let node: ByteBudget | null = this; node !== null; node = node.parent) node.#used += bytes;
+    return true;
+  }
+
+  release(bytes: number): void {
+    for (let node: ByteBudget | null = this; node !== null; node = node.parent) {
+      node.#used = Math.max(0, node.#used - bytes);
+    }
+  }
+}
+
+/** Per-subscription budget: a frame count plus a byte budget chained to its connection. */
+export class SubscriptionBudget {
+  readonly bytes: ByteBudget;
+  readonly maxFrames: number;
+  #frames = 0;
+
+  constructor(maxFrames: number, maxBytes: number, parent: ByteBudget) {
+    this.maxFrames = maxFrames;
+    this.bytes = new ByteBudget(maxBytes, parent);
+  }
+
+  get frames(): number {
+    return this.#frames;
+  }
+
+  tryReserve(bytes: number): boolean {
+    if (this.#frames + 1 > this.maxFrames) return false;
+    if (!this.bytes.tryReserve(bytes)) return false;
+    this.#frames++;
+    return true;
+  }
+
+  release(bytes: number): void {
+    this.#frames = Math.max(0, this.#frames - 1);
+    this.bytes.release(bytes);
+  }
+}