@lovrozagar/honey 0.6.5 → 0.7.0

package/dist/realtime/register.js

@@ -0,0 +1,10 @@
+/**
+ * `import "@lovrozagar/honey/realtime"` makes `app.realtime()` available. The core never
+ * imports the realtime server, so an app without realtime routes does not bundle it.
+ */
+import { registerFeature } from "../feature-slots.js";
+import { createBus } from "./bus.js";
+import { resolveRealtimeConfig } from "./route.js";
+import { createRealtimePublisher, createRealtimeSession } from "./server.js";
+registerFeature("realtime", { createBus, createRealtimePublisher, createRealtimeSession, resolveRealtimeConfig });
+//# sourceMappingURL=register.js.map

package/dist/realtime/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/realtime/register.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAE5E,eAAe,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,CAAC,CAAA"}

package/dist/realtime/route.d.ts

@@ -1,42 +1,81 @@
+import { type WSOriginPolicy } from "../ws-origin.ts";
+/**
+ * One realtime connection as the route handler sees it. Only the WebSocket transport ships.
+ * Every frame, in both directions, is one JSON text (see the README's realtime wire format).
+ */
 export type ConnContext = {
     readonly id: string;
+    /** What the route's `identify(ctx)` returned, else `null`. */
     readonly userId: string | null;
-    readonly transport: "ws" | "sse" | "longpoll";
+    readonly transport: "ws";
+    /** `true` once the connection closed (or `close()` was called). `join` and `send` are then no-ops. */
+    readonly closed: boolean;
     readonly state: Record<string, unknown>;
+    /** Subscribe to `topic` in this route's namespace. Throws past `limits.maxTopics`. */
     join(topic: string): void;
     leave(topic: string): void;
+    /** Send one JSON frame to this connection. Throws when `payload` is not JSON-serializable. */
     send(payload: unknown): void;
+    /** Send one JSON frame to every connection on `topic` in this route's namespace (this one included). */
     publish(topic: string, payload: unknown): void;
+    /** Close with code 1000. A reason longer than 123 UTF-8 bytes is truncated. */
     close(reason?: string): void;
-    on(event: "message", handler: (payload: unknown) => void): void;
-    on(event: "close", handler: (reason: string) => void): void;
-    readonly _handlers: {
-        message: ((payload: unknown) => void) | null;
-        close: ((reason: string) => void) | null;
-    };
+    on(event: "message", handler: (payload: unknown) => void | Promise<void>): void;
+    on(event: "close", handler: (reason: string) => void | Promise<void>): void;
 };
-export type RealtimeRouteOpts = {
+export type RealtimeLimits = {
+    /** Topics one connection may join. Default 128. */
+    maxTopics?: number;
+    /** Largest inbound text frame in UTF-8 bytes; larger frames close the connection with 1009. Default 1 MiB. */
+    maxFrameBytes?: number;
+    /**
+     * Inbound frames waiting for a handler (a slow async `message` handler, or none attached yet).
+     * Past this the connection closes with 1008. Default 64.
+     */
+    maxPendingFrames?: number;
+    /**
+     * Outbound bytes the runtime may hold for a client that is not reading, where the runtime reports
+     * it (`bufferedAmount`). Past this `slowConsumer` applies. Default 4 MiB.
+     */
+    maxBufferedBytes?: number;
+    /** `"close"` (default) closes a slow consumer with 1013; `"drop"` drops frames until it catches up. */
+    slowConsumer?: "close" | "drop";
+};
+/** `C` is the request context of the handle `realtime()` is called on. */
+export type RealtimeRouteOpts<C = unknown> = {
     use?: Array<(ctx: unknown, next: () => Promise<Response>) => Promise<Response>>;
-    reconnectBuffer?: number;
-    handler: (c: unknown, conn: ConnContext) => void | Promise<void>;
+    /**
+     * Topic namespace. Connections only see topics of their own namespace. Defaults to the route's
+     * full path pattern, so two realtime routes never share topics unless they name the same namespace.
+     */
+    namespace?: string;
+    /** Runs after the route's middleware, before the upgrade. Its result becomes `conn.userId`; a throw rejects the upgrade. */
+    identify?: (ctx: C) => string | null | undefined | Promise<string | null | undefined>;
+    /** Receives every error thrown by `handler` and the `message`/`close` handlers. Defaults to the app logger. */
+    onError?: (error: unknown, conn: ConnContext) => void | Promise<void>;
+    limits?: RealtimeLimits;
+    /**
+     * Browser origins allowed to connect: `"*"`, a list (`https://app.example.com`), or a
+     * predicate. Same-origin always passes. Unset, a cross-origin upgrade that carries `Cookie`
+     * or `Authorization` gets 403.
+     */
+    allowedOrigins?: WSOriginPolicy;
+    handler: (c: C, conn: ConnContext) => void | Promise<void>;
 };
-export type RealtimeRouteHandler = {
+/** A realtime route after validation, with every default applied. */
+export type RealtimeConfig = {
+    allowedOrigins: WSOriginPolicy | null;
     handler: RealtimeRouteOpts["handler"];
-    middlewares: RealtimeRouteOpts["use"];
-    reconnectBuffer: number;
+    identify: NonNullable<RealtimeRouteOpts["identify"]> | null;
+    limits: Required<RealtimeLimits>;
+    namespace: string;
+    /** false when `namespace` is the default (the route's path), which follows the route when mounted */
+    namespaceExplicit: boolean;
+    onError: NonNullable<RealtimeRouteOpts["onError"]> | null;
     path: string;
 };
-export declare function createConnContext(opts: {
-    id: string;
-    userId: string | null;
-    transport: "ws" | "sse" | "longpoll";
-    bus: {
-        subscribe(connId: string, topic: string): void;
-        unsubscribe(connId: string, topic: string): void;
-        unsubscribeAll(connId: string): void;
-        publish(topic: string, data: unknown): void;
-    };
-    sendFn: (payload: unknown) => void;
-    closeFn: (reason?: string) => void;
-}): ConnContext;
+/** Validate `app.realtime()` options. Options the shipped bus does not implement are rejected, not ignored. */
+export declare function resolveRealtimeConfig<C>(path: string, routeOpts: RealtimeRouteOpts<C>): RealtimeConfig;
+/** Cut `reason` to at most `max` UTF-8 bytes without splitting a code point. */
+export declare function truncateUtf8(reason: string, max: number): string;
 //# sourceMappingURL=route.d.ts.map

package/dist/realtime/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/realtime/route.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,KAAK,GAAG,UAAU,CAAA;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACvC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAC5B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAC9C,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAA;IAC/D,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAA;IAC3D,QAAQ,CAAC,SAAS,EAAE;QAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;KAAE,CAAA;CAC9G,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC/B,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChE,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IAClC,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAA;IACrC,WAAW,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAA;IACrC,eAAe,EAAE,MAAM,CAAA;IACvB,IAAI,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACvC,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,SAAS,EAAE,IAAI,GAAG,KAAK,GAAG,UAAU,CAAA;IACpC,GAAG,EAAE;QACJ,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;QAC9C,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;QAChD,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;QACpC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;KAC3C,CAAA;IACD,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAClC,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAClC,GAAG,WAAW,CA+Dd"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/realtime/route.ts"],"names":[],"mappings":"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"}

package/dist/realtime/route.js

@@ -0,0 +1,72 @@
+import { validateOriginPolicy } from "../ws-origin.js";
+const DEFAULT_LIMITS = {
+    maxBufferedBytes: 4 * 1024 * 1024,
+    maxFrameBytes: 1024 * 1024,
+    maxPendingFrames: 64,
+    maxTopics: 128,
+    slowConsumer: "close",
+};
+function positiveInt(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError(`realtime limits.${name} must be a positive integer, got ${String(value)}`);
+    }
+    return value;
+}
+/** Validate `app.realtime()` options. Options the shipped bus does not implement are rejected, not ignored. */
+export function resolveRealtimeConfig(path, routeOpts) {
+    const opts = routeOpts;
+    if (typeof opts?.handler !== "function") {
+        throw new TypeError(`app.realtime("${path}"): handler must be a function`);
+    }
+    const legacy = opts;
+    if (legacy.reconnectBuffer !== undefined) {
+        throw new TypeError(`app.realtime("${path}"): reconnectBuffer is not supported. Realtime ships the WebSocket transport without resume; remove the option.`);
+    }
+    if (legacy.transports !== undefined) {
+        throw new TypeError(`app.realtime("${path}"): only the WebSocket transport ships; remove transports.`);
+    }
+    if (opts.namespace !== undefined && (typeof opts.namespace !== "string" || opts.namespace === "")) {
+        throw new TypeError(`app.realtime("${path}"): namespace must be a non-empty string`);
+    }
+    const l = opts.limits ?? {};
+    if (l.slowConsumer !== undefined && l.slowConsumer !== "close" && l.slowConsumer !== "drop") {
+        throw new TypeError(`realtime limits.slowConsumer must be "close" or "drop"`);
+    }
+    return {
+        allowedOrigins: opts.allowedOrigins === undefined ? null : validateOriginPolicy(opts.allowedOrigins),
+        handler: opts.handler,
+        identify: opts.identify ?? null,
+        limits: {
+            maxBufferedBytes: positiveInt("maxBufferedBytes", l.maxBufferedBytes, DEFAULT_LIMITS.maxBufferedBytes),
+            maxFrameBytes: positiveInt("maxFrameBytes", l.maxFrameBytes, DEFAULT_LIMITS.maxFrameBytes),
+            maxPendingFrames: positiveInt("maxPendingFrames", l.maxPendingFrames, DEFAULT_LIMITS.maxPendingFrames),
+            maxTopics: positiveInt("maxTopics", l.maxTopics, DEFAULT_LIMITS.maxTopics),
+            slowConsumer: l.slowConsumer ?? DEFAULT_LIMITS.slowConsumer,
+        },
+        namespace: opts.namespace ?? path,
+        namespaceExplicit: opts.namespace !== undefined,
+        onError: opts.onError ?? null,
+        path,
+    };
+}
+const encoder = new TextEncoder();
+/** Cut `reason` to at most `max` UTF-8 bytes without splitting a code point. */
+export function truncateUtf8(reason, max) {
+    if (reason.length * 3 <= max)
+        return reason;
+    if (encoder.encode(reason).byteLength <= max)
+        return reason;
+    let bytes = 0;
+    let out = "";
+    for (const ch of reason) {
+        const n = encoder.encode(ch).byteLength;
+        if (bytes + n > max)
+            break;
+        bytes += n;
+        out += ch;
+    }
+    return out;
+}
+//# sourceMappingURL=route.js.map

package/dist/realtime/route.js.map

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

package/dist/realtime/server.d.ts

@@ -0,0 +1,43 @@
+import type { WSContext, WSHandler } from "../ws/cloudflare.ts";
+import type { RealtimeBus } from "./bus.ts";
+import type { RealtimeConfig } from "./route.ts";
+type Logger = {
+    error?: (obj: Record<string, unknown>, msg?: string) => void;
+    warn?: (obj: Record<string, unknown>, msg?: string) => void;
+};
+/** `ctx.realtime` — publish into a realtime namespace from any request. */
+export type RealtimePublisher = {
+    /**
+     * Publish to `topic` in the app's only realtime namespace. Throws when the app has several
+     * namespaces; use `namespace(name).publish()` then.
+     */
+    publish(topic: string, data: unknown): void;
+    /** The publisher for one namespace (a route's `namespace` option, or its full path pattern). */
+    namespace(name: string): {
+        publish(topic: string, data: unknown): void;
+    };
+};
+/** The bus key of `topic` in namespace `ns`. Namespaces never see each other's topics. */
+export declare function topicKey(ns: string, topic: string): string;
+export declare function createRealtimePublisher(bus: RealtimeBus, namespaces: () => Iterable<string>): RealtimePublisher;
+export type RealtimeSession = {
+    /** The handler to pass to the runtime's WebSocket adapter. */
+    handler: WSHandler<unknown>;
+    /** Attach the socket and start the connection (idempotent). Adapters that return an open socket from `upgrade()` call this right away; others get it from `onOpen`. */
+    attach(ws: WSContext<unknown>): void;
+};
+/**
+ * One realtime connection: binds the socket to the bus and runs the route's callbacks on one ordered
+ * queue — `handler`, then each inbound frame, then `close` — each awaited. Every callback is
+ * contained: a throw or rejection goes to the route's `onError` (or the app logger) and never escapes
+ * into the runtime, so it can neither crash the process nor poison the queue.
+ */
+export declare function createRealtimeSession(opts: {
+    bus: RealtimeBus;
+    config: RealtimeConfig;
+    ctx: unknown;
+    log: Logger | undefined;
+    userId: string | null;
+}): RealtimeSession;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/realtime/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/realtime/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAE/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAY3C,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,YAAY,CAAA;AAE7D,KAAK,MAAM,GAAG;IACb,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5D,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC3D,CAAA;AAED,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG;IAC/B;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IAC3C,gGAAgG;IAChG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAA;CACxE,CAAA;AAID,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC,MAAM,CAAC,GAAG,iBAAiB,CAsB/G;AAED,MAAM,MAAM,eAAe,GAAG;IAC7B,8DAA8D;IAC9D,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC3B,uKAAuK;IACvK,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;CACpC,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,WAAW,CAAA;IAChB,MAAM,EAAE,cAAc,CAAA;IACtB,GAAG,EAAE,OAAO,CAAA;IACZ,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB,GAAG,eAAe,CAsNlB"}

package/dist/realtime/server.js

@@ -0,0 +1,255 @@
+import { invokeUser } from "../invoke-user.js";
+import { encodeRealtimeFrame } from "./bus.js";
+import { bufferedAmountOf, CLOSE_INTERNAL, CLOSE_NORMAL, CLOSE_POLICY, CLOSE_TOO_BIG, CLOSE_TRY_AGAIN, exceedsPayload, MAX_CLOSE_REASON, } from "../ws/shared.js";
+import { truncateUtf8 } from "./route.js";
+const SEP = "\u0000";
+/** The bus key of `topic` in namespace `ns`. Namespaces never see each other's topics. */
+export function topicKey(ns, topic) {
+    return ns + SEP + topic;
+}
+export function createRealtimePublisher(bus, namespaces) {
+    const forNs = (ns) => ({
+        publish(topic, data) {
+            bus.publish(topicKey(ns, String(topic)), data);
+        },
+    });
+    return {
+        namespace(name) {
+            return forNs(String(name));
+        },
+        publish(topic, data) {
+            const all = new Set(namespaces());
+            if (all.size !== 1) {
+                throw new Error(all.size === 0
+                    ? "ctx.realtime.publish: the app has no realtime routes"
+                    : `ctx.realtime.publish: the app has ${all.size} realtime namespaces (${[...all].join(", ")}); use ctx.realtime.namespace(name).publish(topic, data)`);
+            }
+            forNs(all.values().next().value).publish(topic, data);
+        },
+    };
+}
+/**
+ * One realtime connection: binds the socket to the bus and runs the route's callbacks on one ordered
+ * queue — `handler`, then each inbound frame, then `close` — each awaited. Every callback is
+ * contained: a throw or rejection goes to the route's `onError` (or the app logger) and never escapes
+ * into the runtime, so it can neither crash the process nor poison the queue.
+ */
+export function createRealtimeSession(opts) {
+    const { bus, config, ctx, log, userId } = opts;
+    const { limits, namespace } = config;
+    const connId = crypto.randomUUID();
+    const state = {};
+    let socket = null;
+    let closed = false;
+    let tornDown = false;
+    let closeRan = false;
+    let onMessageFn = null;
+    let onCloseFn = null;
+    /* ordered queue: open → messages → close. Every inbound frame waits in `inbox` in arrival
+     * order, including frames that beat the open or the `message` handler; a drain task delivers
+     * them, so a frame never overtakes one that arrived before it. */
+    let queue = Promise.resolve();
+    const inbox = [];
+    /* the same containment as WebSocket callbacks: onError gets the error, an onError that
+     * throws is logged and never invoked again for its own error, nothing reaches the runtime */
+    const invoke = (phase, fn) => invokeUser(fn, {
+        fields: { connId, namespace, route: config.path },
+        log,
+        onError: config.onError ? (err) => config.onError?.(err, conn) : null,
+        phase,
+    });
+    const enqueue = (task) => {
+        queue = queue.then(task).then(() => undefined, () => undefined);
+    };
+    /** Drop the connection from the bus. Runs exactly once, before any user close handler. */
+    const teardown = () => {
+        if (tornDown)
+            return;
+        tornDown = true;
+        closed = true;
+        bus.unsubscribeAll(connId);
+        bus.removeHandler(connId);
+    };
+    const closeSocket = (code, reason) => {
+        const ws = socket;
+        teardown();
+        if (ws === null)
+            return;
+        try {
+            ws.close(code, truncateUtf8(reason, MAX_CLOSE_REASON));
+        }
+        catch (e) {
+            log?.warn?.({ connId, err: e }, "realtime close failed");
+        }
+    };
+    const sendFrame = (frame) => {
+        const ws = socket;
+        if (closed || ws === null)
+            return;
+        if (bufferedAmountOf(ws.raw) > limits.maxBufferedBytes) {
+            if (limits.slowConsumer === "drop")
+                return;
+            closeSocket(CLOSE_TRY_AGAIN, "slow consumer");
+            return;
+        }
+        try {
+            ws.send(frame);
+        }
+        catch (e) {
+            /* the socket went away between the readyState check and the write */
+            log?.warn?.({ connId, err: e }, "realtime send failed");
+        }
+    };
+    /* frames that arrived before the close still run; the close handler is queued after them.
+     * Without a handler the frames stay in the inbox until one is attached, or are dropped on close. */
+    const drain = async () => {
+        while (inbox.length > 0) {
+            const fn = onMessageFn;
+            if (fn === null) {
+                if (closed)
+                    inbox.length = 0;
+                return;
+            }
+            const payload = inbox.shift();
+            await invoke("message", () => fn(payload));
+        }
+    };
+    const accept = (payload) => {
+        if (inbox.length >= limits.maxPendingFrames) {
+            closeSocket(CLOSE_POLICY, "too many pending frames");
+            return;
+        }
+        inbox.push(payload);
+        enqueue(drain);
+    };
+    const conn = Object.create(null);
+    Object.defineProperties(conn, {
+        close: {
+            enumerable: true,
+            value(reason) {
+                if (closed)
+                    return;
+                closeSocket(CLOSE_NORMAL, reason === undefined ? "" : String(reason));
+            },
+        },
+        closed: { enumerable: true, get: () => closed },
+        id: { enumerable: true, value: connId },
+        join: {
+            enumerable: true,
+            value(topic) {
+                if (closed)
+                    return;
+                const key = topicKey(namespace, String(topic));
+                if (bus.topicCount(connId) >= limits.maxTopics && !bus.isSubscribed(connId, key)) {
+                    throw new RangeError(`realtime: a connection may join at most ${limits.maxTopics} topics`);
+                }
+                bus.subscribe(connId, key);
+            },
+        },
+        leave: {
+            enumerable: true,
+            value(topic) {
+                if (closed)
+                    return;
+                bus.unsubscribe(connId, topicKey(namespace, String(topic)));
+            },
+        },
+        on: {
+            enumerable: true,
+            value(event, fn) {
+                if (typeof fn !== "function")
+                    throw new TypeError("conn.on: handler must be a function");
+                if (event === "message") {
+                    onMessageFn = fn;
+                    /* frames that waited for a handler run next, in arrival order */
+                    if (inbox.length > 0)
+                        enqueue(drain);
+                }
+                else if (event === "close") {
+                    onCloseFn = fn;
+                }
+                else {
+                    throw new TypeError(`conn.on: unknown event "${String(event)}"`);
+                }
+            },
+        },
+        /* publishing after close is allowed: a close handler announcing a departure is the common case */
+        publish: {
+            enumerable: true,
+            value(topic, payload) {
+                bus.publish(topicKey(namespace, String(topic)), payload);
+            },
+        },
+        send: {
+            enumerable: true,
+            value(payload) {
+                const frame = encodeRealtimeFrame(payload);
+                sendFrame(frame);
+            },
+        },
+        state: { enumerable: true, get: () => state },
+        transport: { enumerable: true, value: "ws" },
+        userId: { enumerable: true, value: userId },
+    });
+    const attach = (ws) => {
+        if (socket !== null || tornDown)
+            return;
+        socket = ws;
+        bus.onMessage(connId, sendFrame);
+        enqueue(async () => {
+            const ok = await invoke("handler", () => config.handler(ctx, conn));
+            if (!ok)
+                closeSocket(CLOSE_INTERNAL, "internal error");
+        });
+    };
+    const onSocketClose = (reason) => {
+        teardown();
+        if (closeRan)
+            return;
+        closeRan = true;
+        enqueue(() => {
+            const fn = onCloseFn;
+            return fn === null ? Promise.resolve() : invoke("close", () => fn(reason));
+        });
+    };
+    const handler = {
+        onClose: (_ctx, _ws, _code, reason) => {
+            onSocketClose(reason || "normal");
+        },
+        onError: (_ctx, _ws, error) => {
+            log?.warn?.({ connId, err: error }, "realtime socket error");
+        },
+        onMessage: (_ctx, _ws, data) => {
+            if (closed)
+                return;
+            /* the wire format is JSON text; binary frames are not part of it */
+            if (typeof data !== "string")
+                return;
+            if (exceedsPayload(data, limits.maxFrameBytes)) {
+                closeSocket(CLOSE_TOO_BIG, "frame too large");
+                return;
+            }
+            let payload;
+            try {
+                payload = JSON.parse(data);
+            }
+            catch {
+                /* not JSON: not a frame of this protocol */
+                return;
+            }
+            if (socket === null) {
+                /* a frame before open (runtime quirk): it waits in the inbox, ahead of later frames */
+                if (inbox.length >= limits.maxPendingFrames)
+                    return;
+                inbox.push(payload);
+                return;
+            }
+            accept(payload);
+        },
+        onOpen: (_ctx, ws) => {
+            attach(ws);
+        },
+    };
+    return { attach, handler };
+}
+//# sourceMappingURL=server.js.map

package/dist/realtime/server.js.map

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

package/dist/request-id.d.ts

@@ -2,6 +2,13 @@ import type { MiddlewareFn } from "./middleware.ts";
 type RequestIdOptions = {
     generator?: () => string;
     header?: string;
+    /**
+     * Decides whether an inbound id is reused. Default: 1–128 characters of
+     * `A-Z a-z 0-9 . _ : + / = -` (UUIDs, ULIDs, base64, W3C trace ids).
+     * Anything else is replaced with a generated id, so a client cannot put
+     * arbitrary text into logs or response headers.
+     */
+    validate?: (id: string) => boolean;
 };
 export declare function requestId(options?: RequestIdOptions): MiddlewareFn<{
     req: Request;

package/dist/request-id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-id.d.ts","sourceRoot":"","sources":["../src/request-id.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD,KAAK,gBAAgB,GAAG;IACvB,SAAS,CAAC,EAAE,MAAM,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAa3G"}
+{"version":3,"file":"request-id.d.ts","sourceRoot":"","sources":["../src/request-id.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGnD,KAAK,gBAAgB,GAAG;IACvB,SAAS,CAAC,EAAE,MAAM,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAA;CAClC,CAAA;AAID,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAa3G"}

package/dist/request-id.js

@@ -0,0 +1,16 @@
+import { namedMiddleware } from "./middleware.js";
+import { withHeaders } from "./with-headers.js";
+const SAFE_ID_RE = /^[\w.:+/=-]{1,128}$/;
+export function requestId(options) {
+    const headerName = options?.header ?? "x-request-id";
+    const generate = options?.generator ?? (() => crypto.randomUUID());
+    const validate = options?.validate ?? ((id) => SAFE_ID_RE.test(id));
+    const mw = async (ctx, next) => {
+        const existing = ctx.req.headers.get(headerName);
+        const id = existing !== null && validate(existing) ? existing : generate();
+        const response = await next({ requestId: id });
+        return withHeaders(response, (headers) => headers.set(headerName, id));
+    };
+    return namedMiddleware("requestId", mw);
+}
+//# sourceMappingURL=request-id.js.map

package/dist/request-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.js","sourceRoot":"","sources":["../src/request-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAc/C,MAAM,UAAU,GAAG,qBAAqB,CAAA;AAExC,MAAM,UAAU,SAAS,CAAC,OAA0B;IACnD,MAAM,UAAU,GAAG,OAAO,EAAE,MAAM,IAAI,cAAc,CAAA;IACpD,MAAM,QAAQ,GAAG,OAAO,EAAE,SAAS,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAA;IAClE,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;IAE3E,MAAM,EAAE,GAA0D,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACrF,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;QAChD,MAAM,EAAE,GAAG,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;QAC1E,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAA;QAC9C,OAAO,WAAW,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAA;IACvE,CAAC,CAAA;IAED,OAAO,eAAe,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;AACxC,CAAC"}

package/dist/request-limits.d.ts

@@ -0,0 +1,3 @@
+/** Bun's default request body cap; honey's Node adapter applies the same one. */
+export declare const DEFAULT_MAX_REQUEST_BODY: number;
+//# sourceMappingURL=request-limits.d.ts.map

package/dist/request-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-limits.d.ts","sourceRoot":"","sources":["../src/request-limits.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,QAAoB,CAAA"}

package/dist/request-limits.js

@@ -0,0 +1,3 @@
+/** Bun's default request body cap; honey's Node adapter applies the same one. */
+export const DEFAULT_MAX_REQUEST_BODY = 128 * 1024 * 1024;
+//# sourceMappingURL=request-limits.js.map

package/dist/request-limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-limits.js","sourceRoot":"","sources":["../src/request-limits.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA"}

package/dist/request-path.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The request path the router, scopes, `ctx.path`, `proxy()` and `staticFiles()` all see.
+ *
+ * Policy, applied the same way on every runtime:
+ * - empty segments collapse: `//admin///users` is `/admin/users`
+ * - dot segments resolve: `.` is dropped and `..` removes the segment before it, never past
+ *   the root; `%2e` counts as a dot, as it does for WHATWG URL parsing
+ * - a trailing slash is kept (the router and `trailingSlash()` decide what it means)
+ * - a backslash is a `/`, and characters a URL path cannot hold raw (space, controls, `"`, `<`,
+ *   `>`, `` ` ``, `{`, `}`, non-ASCII) are percent-encoded as UTF-8 — what WHATWG URL parsing
+ *   does, so a runtime that hands the app the raw target (Deno) and one that parses it first
+ *   (Bun, Node) route the same bytes the same way
+ * - an encoded `/` or `\` (`%2F`, `%5C`) is rejected unless `encodedSlashes` is `"allow"`: a
+ *   segment that decodes to a path separator means one thing to this router and another to
+ *   whatever the path is forwarded to (a proxy upstream, a file system). Allowed, it stays
+ *   encoded in the path and decodes into a param value.
+ * - everything else stays percent-encoded; params are decoded when they are extracted
+ *
+ * Returns `null` for a rejected path; the app answers 400.
+ */
+export declare function normalizePath(raw: string, encodedSlashes?: "allow" | "reject"): string | null;
+/**
+ * One path segment as a normalized request path holds it: characters a URL path cannot hold
+ * raw become UTF-8 percent escapes, everything else (existing escapes included) is kept.
+ * Route patterns encode their static segments with this too, so `app.get("/é")` matches the
+ * `/%C3%A9` every runtime hands the app.
+ */
+export declare function encodeSegment(seg: string): string;
+/** The path of a request URL without `new URL()`: everything from the first `/` after the authority, up to `?` or `#`. */
+export declare function pathOfUrl(rawUrl: string): string;
+/** `?query` of a request URL (with the `?`), or `""`. Never includes a fragment. */
+export declare function searchOfUrl(rawUrl: string): string;
+//# sourceMappingURL=request-path.d.ts.map

package/dist/request-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-path.d.ts","sourceRoot":"","sources":["../src/request-path.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,GAAE,OAAO,GAAG,QAAmB,GAAG,MAAM,GAAG,IAAI,CAgDvG;AAqBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAwBjD;AAWD,0HAA0H;AAC1H,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAShD;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQlD"}