@lovrozagar/honey 0.7.2 → 1.0.0-rc.1

package/dist/realtime/bus.d.ts

@@ -1,27 +1,24 @@
 /**
- * In-process topic bus behind `app.realtime()`. Topics are opaque keys here; the realtime server
- * namespaces them per route before they reach the bus. Each publish serializes its payload once and
- * hands every subscriber the same JSON text frame.
+ * The in-process topic bus behind `realtime()`. Topics are opaque keys here; the realtime server
+ * namespaces them per route before they reach the bus. A publish serializes its payload once and
+ * hands every subscriber the same JSON text frame. Pass one bus to several routes to share topics.
  */
-export interface RealtimeBus {
+export type RealtimeBus = {
     subscribe(connId: string, topic: string): void;
     unsubscribe(connId: string, topic: string): void;
     unsubscribeAll(connId: string): void;
-    /** Serialize `data` once and deliver the frame to every subscriber of `topic`. Throws when `data` is not JSON-serializable. */
+    /** Serialize `data` once and deliver the frame to every subscriber of `topic`; throws when `data` is not JSON. */
     publish(topic: string, data: unknown): void;
     /** Deliver an already-serialized frame to every subscriber of `topic`. */
     publishFrame(topic: string, frame: string): void;
-    onMessage(connId: string, handler: (frame: string) => void): void;
+    onMessage(connId: string, sink: (frame: string) => void): void;
     removeHandler(connId: string): void;
+    /** The connections on `topic`, as a snapshot. */
     presence(topic: string): string[];
-    /** Number of topics `connId` is subscribed to. */
+    /** How many topics `connId` is on. */
     topicCount(connId: string): number;
     isSubscribed(connId: string, topic: string): boolean;
-}
-/**
- * The wire format of the shipped bus: every frame, in both directions, is one JSON text.
- * Throws a `TypeError` for values JSON cannot represent (`undefined`, functions, symbols, BigInt, cycles).
- */
+};
+/** The wire format: every frame, both ways, is one JSON text. A value JSON cannot represent is a TypeError. */
 export declare function encodeRealtimeFrame(data: unknown): string;
 export declare function createBus(): RealtimeBus;
-//# sourceMappingURL=bus.d.ts.map

package/dist/realtime/bus.js

@@ -1,112 +1,67 @@
-/**
- * The wire format of the shipped bus: every frame, in both directions, is one JSON text.
- * Throws a `TypeError` for values JSON cannot represent (`undefined`, functions, symbols, BigInt, cycles).
- */
+/** The wire format: every frame, both ways, is one JSON text. A value JSON cannot represent is a TypeError. */
 export function encodeRealtimeFrame(data) {
     const frame = JSON.stringify(data);
-    if (frame === undefined) {
+    if (frame === undefined)
         throw new TypeError(`realtime payload is not JSON-serializable (got ${typeof data})`);
-    }
     return frame;
 }
+/** Remove `member` from the set under `key`, and the set once it is empty. */
+function removeFrom(map, key, member) {
+    const set = map.get(key);
+    if (set === undefined)
+        return;
+    set.delete(member);
+    if (set.size === 0)
+        map.delete(key);
+}
+function addTo(map, key, member) {
+    let set = map.get(key);
+    if (set === undefined) {
+        set = new Set();
+        map.set(key, set);
+    }
+    set.add(member);
+}
 export function createBus() {
-    /* topic -> set of connIds subscribed to it */
+    /* topic → connections on it, and connection → its topics (for unsubscribeAll) */
     const topicSubs = new Map();
-    /* connId -> set of topics it is subscribed to (reverse lookup for unsubscribeAll) */
     const connTopics = new Map();
-    /* connId -> frame sink */
-    const handlers = new Map();
-    function subscribe(connId, topic) {
-        let subs = topicSubs.get(topic);
-        if (!subs) {
-            subs = new Set();
-            topicSubs.set(topic, subs);
-        }
-        subs.add(connId);
-        let topics = connTopics.get(connId);
-        if (!topics) {
-            topics = new Set();
-            connTopics.set(connId, topics);
-        }
-        topics.add(topic);
-    }
-    function unsubscribe(connId, topic) {
-        const subs = topicSubs.get(topic);
-        if (subs) {
-            subs.delete(connId);
-            if (subs.size === 0)
-                topicSubs.delete(topic);
-        }
-        const topics = connTopics.get(connId);
-        if (topics) {
-            topics.delete(topic);
-            if (topics.size === 0)
-                connTopics.delete(connId);
-        }
-    }
-    function unsubscribeAll(connId) {
-        const topics = connTopics.get(connId);
-        if (!topics)
-            return;
-        for (const topic of topics) {
-            const subs = topicSubs.get(topic);
-            if (subs) {
-                subs.delete(connId);
-                if (subs.size === 0)
-                    topicSubs.delete(topic);
-            }
-        }
-        connTopics.delete(connId);
-    }
-    function publishFrame(topic, frame) {
+    const sinks = new Map();
+    const publishFrame = (topic, frame) => {
         const subs = topicSubs.get(topic);
-        if (!subs)
+        if (subs === undefined)
             return;
-        /* snapshot: a sink that closes its connection unsubscribes while we iterate */
-        for (const connId of Array.from(subs)) {
-            const handler = handlers.get(connId);
-            if (!handler)
-                continue;
+        /* a snapshot: a sink that closes its connection unsubscribes while this iterates */
+        const snapshot = [...subs];
+        for (const connId of snapshot) {
             try {
-                handler(frame);
+                sinks.get(connId)?.(frame);
             }
             catch {
-                /* sinks are internal and contain their own errors; one must never block the others */
+                /* sinks contain their own errors; one must never block the others */
             }
         }
-    }
-    function publish(topic, data) {
-        publishFrame(topic, encodeRealtimeFrame(data));
-    }
-    function onMessage(connId, handler) {
-        handlers.set(connId, handler);
-    }
-    function removeHandler(connId) {
-        handlers.delete(connId);
-    }
-    function presence(topic) {
-        const subs = topicSubs.get(topic);
-        if (!subs)
-            return [];
-        return [...subs];
-    }
-    function topicCount(connId) {
-        return connTopics.get(connId)?.size ?? 0;
-    }
-    function isSubscribed(connId, topic) {
-        return connTopics.get(connId)?.has(topic) ?? false;
-    }
+    };
     return {
-        isSubscribed,
-        onMessage,
-        presence,
-        publish,
+        isSubscribed: (connId, topic) => connTopics.get(connId)?.has(topic) ?? false,
+        onMessage: (connId, sink) => void sinks.set(connId, sink),
+        presence: (topic) => [...(topicSubs.get(topic) ?? [])],
+        publish: (topic, data) => publishFrame(topic, encodeRealtimeFrame(data)),
         publishFrame,
-        removeHandler,
-        subscribe,
-        topicCount,
-        unsubscribe,
-        unsubscribeAll,
+        removeHandler: (connId) => void sinks.delete(connId),
+        subscribe(connId, topic) {
+            addTo(topicSubs, topic, connId);
+            addTo(connTopics, connId, topic);
+        },
+        topicCount: (connId) => connTopics.get(connId)?.size ?? 0,
+        unsubscribe(connId, topic) {
+            removeFrom(topicSubs, topic, connId);
+            removeFrom(connTopics, connId, topic);
+        },
+        unsubscribeAll(connId) {
+            for (const topic of connTopics.get(connId) ?? [])
+                removeFrom(topicSubs, topic, connId);
+            connTopics.delete(connId);
+        },
     };
 }
-//# sourceMappingURL=bus.js.map

package/dist/realtime/invoke-user.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Containment for user callbacks the framework calls outside a request's middleware chain (ws and
+ * realtime events, adapter hooks). A sync throw or a rejection never escapes into the runtime,
+ * where it would be an uncaught exception or an unhandled rejection and, on Node, end the process.
+ * The failure goes to the callback's `onError`, else to the logger; until bit 07 wires the app
+ * logger, a failure with neither is contained and goes nowhere.
+ */
+/** The error side of a structured logger (`error(fields, msg)`). */
+export type InvokeLogger = {
+    error?: (fields: Record<string, unknown>, msg?: string) => void;
+};
+export type InvokeOptions = {
+    /** Where the callback's error goes. If it throws or rejects itself, that is logged and it is not called again. */
+    onError?: ((error: unknown) => unknown) | null;
+    log?: InvokeLogger | null;
+    /** A label for the log line (`"websocket open"`, …). */
+    phase: string;
+    /** Extra fields for the log line. */
+    fields?: Record<string, unknown>;
+};
+/** Report `error` through `onError`, or log it. Never throws, never rejects. */
+export declare function reportUserError(error: unknown, options: InvokeOptions): void;
+/**
+ * Call `fn`: `true` when it succeeded, `false` when it threw or rejected (reported). A callback that
+ * answers at once is answered at once; one that returns a promise is answered by a promise. Never
+ * throws, never rejects.
+ */
+export declare function invokeUser(fn: () => unknown, options: InvokeOptions): boolean | Promise<boolean>;
+/**
+ * One ordered lane: each task starts after the previous one settled; a failing task never stops the
+ * rest. A task pushed while nothing is waiting runs at once, so a callback that answers at once costs
+ * no turn of the queue; what it pushes while it runs waits until it settled.
+ */
+export declare function createEventQueue(): {
+    push(task: () => unknown): Promise<void>;
+};

package/dist/realtime/invoke-user.js

@@ -0,0 +1,103 @@
+/**
+ * Containment for user callbacks the framework calls outside a request's middleware chain (ws and
+ * realtime events, adapter hooks). A sync throw or a rejection never escapes into the runtime,
+ * where it would be an uncaught exception or an unhandled rejection and, on Node, end the process.
+ * The failure goes to the callback's `onError`, else to the logger; until bit 07 wires the app
+ * logger, a failure with neither is contained and goes nowhere.
+ */
+function logFailure(error, options, phase) {
+    try {
+        options.log?.error?.({ ...options.fields, err: error, phase }, "callback failed");
+    }
+    catch {
+        /* a broken logger must not become the thing that escapes */
+    }
+}
+function isThenable(value) {
+    return value !== null && typeof value === "object" && typeof value.then === "function";
+}
+/** Report `error` through `onError`, or log it. Never throws, never rejects. */
+export function reportUserError(error, options) {
+    const onError = options.onError;
+    if (!onError)
+        return logFailure(error, options, options.phase);
+    try {
+        const result = onError(error);
+        if (isThenable(result))
+            result.then(undefined, (failure) => logFailure(failure, options, "onError"));
+    }
+    catch (failure) {
+        logFailure(failure, options, "onError");
+    }
+}
+/**
+ * Call `fn`: `true` when it succeeded, `false` when it threw or rejected (reported). A callback that
+ * answers at once is answered at once; one that returns a promise is answered by a promise. Never
+ * throws, never rejects.
+ */
+export function invokeUser(fn, options) {
+    try {
+        const result = fn();
+        if (!isThenable(result))
+            return true;
+        return Promise.resolve(result).then(() => true, (error) => {
+            reportUserError(error, options);
+            return false;
+        });
+    }
+    catch (error) {
+        reportUserError(error, options);
+        return false;
+    }
+}
+const IDLE = /* @__PURE__ */ Promise.resolve();
+/**
+ * One ordered lane: each task starts after the previous one settled; a failing task never stops the
+ * rest. A task pushed while nothing is waiting runs at once, so a callback that answers at once costs
+ * no turn of the queue; what it pushes while it runs waits until it settled.
+ */
+export function createEventQueue() {
+    let tail = IDLE;
+    let waiting = 0;
+    let running = false;
+    /* opens the gate pushes made during a running task wait behind; null until one is made */
+    let open = null;
+    const settled = () => {
+        waiting--;
+    };
+    return {
+        push(task) {
+            if (running && open === null)
+                tail = new Promise((resolve) => (open = resolve));
+            if (waiting > 0) {
+                waiting++;
+                tail = tail.then(task).then(settled, settled);
+                return tail;
+            }
+            waiting++;
+            running = true;
+            let result;
+            try {
+                result = task();
+            }
+            catch {
+                /* lane tasks report their own failures (invokeUser); one that throws anyway must not stop the lane */
+                result = undefined;
+            }
+            running = false;
+            const gate = open;
+            open = null;
+            if (!isThenable(result)) {
+                waiting--;
+                gate?.();
+                return IDLE;
+            }
+            const done = Promise.resolve(result).then(settled, settled);
+            if (gate === null)
+                tail = done;
+            else
+                void done.then(gate);
+            return done;
+        },
+    };
+}

package/dist/realtime/realtime.d.ts

@@ -0,0 +1,7 @@
+import type { WSRouteBuilder, WSRouteCtx } from "../routing/ws-builder.ts";
+import { type AnyHoneyHandle, type WsRouteOf } from "../ws/route.ts";
+import { type RealtimeOptions } from "./route.ts";
+import { type RealtimePublisher } from "./server.ts";
+/** The ctx `ws(app, path)` hands its callbacks, which `identify` and `handler` receive. */
+export type RealtimeCtx<TApp, TPath extends string> = WsRouteOf<TApp, TPath> extends WSRouteBuilder<infer TCtx, infer TFull extends string, any> ? WSRouteCtx<TCtx, TFull> : never;
+export declare function realtime<TApp extends AnyHoneyHandle, const TPath extends string>(app: TApp, path: TPath, options: RealtimeOptions<RealtimeCtx<TApp, TPath>>): RealtimePublisher;

package/dist/realtime/realtime.js

@@ -0,0 +1,40 @@
+/**
+ * `realtime(app, path, opts)`: a realtime route, built on `ws(app, path)` through the public API
+ * alone. A plain function the app module imports (`@lovrozagar/honey/realtime`); nothing registers
+ * itself (H23), and an app that never calls it bundles none of it.
+ *
+ * It returns the publisher for the route's namespace: REST handlers publish through it. The bus is
+ * the isolation boundary: each call gets a fresh bus unless `opts.bus` is given, and routes share
+ * topics only through the same bus and the same namespace. The default namespace is the `path`
+ * given here, as written: a sub-app mounted twice runs one `realtime()` call, so both mounts share
+ * its bus and namespace; call `realtime()` per mount to keep them apart.
+ */
+import { REQUEST } from "../context/context.js";
+import { ws } from "../ws/route.js";
+import { resolveRealtimeConfig } from "./route.js";
+import { createRealtimePublisher, createRealtimeSession, } from "./server.js";
+export function realtime(app, path, options) {
+    const config = resolveRealtimeConfig(path, options);
+    const { identify } = config;
+    /* one session per upgrade request, keyed by its ctx: every ws callback receives that ctx */
+    const sessions = new WeakMap();
+    /* after the route's middleware, before the origin check and the upgrade; a throw rejects the upgrade */
+    const connect = async (ctx, next) => {
+        const userId = identify === null ? null : ((await identify(ctx)) ?? null);
+        sessions.set(ctx, createRealtimeSession({ config, ctx, log: ctx[REQUEST].logger, userId }));
+        return next();
+    };
+    let route = ws(app, path);
+    for (const mw of [...config.use, connect])
+        route = route.use(mw);
+    if (config.allowedOrigins !== null)
+        route = route.origins(config.allowedOrigins);
+    const session = (ctx) => sessions.get(ctx);
+    route.handler({
+        onClose: (ctx, _ws, _code, reason) => session(ctx).close(reason),
+        onError: (ctx, _ws, error) => session(ctx).error(error),
+        onMessage: (ctx, _ws, data) => session(ctx).message(data),
+        onOpen: (ctx, socket) => session(ctx).attach(socket),
+    });
+    return createRealtimePublisher(config.bus, config.namespace);
+}

package/dist/realtime/route.d.ts

@@ -1,7 +1,13 @@
-import { type WSOriginPolicy } from "../ws-origin.ts";
+/**
+ * A realtime route's options, and their validation into the config the session runs on. Options
+ * the shipped transport does not implement are rejected, never silently ignored.
+ */
+import type { MiddlewareFn } from "../middleware/middleware.ts";
+import { type WSOriginPolicy } from "../ws/origin.ts";
+import { type RealtimeBus } from "./bus.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).
+ * Every frame, in both directions, is one JSON text.
  */
 export type ConnContext = {
     readonly id: string;
@@ -20,8 +26,8 @@ export type ConnContext = {
     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 | Promise<void>): void;
-    on(event: "close", handler: (reason: string) => void | Promise<void>): void;
+    on(event: "message", handler: (payload: unknown) => Promise<void> | void): void;
+    on(event: "close", handler: (reason: string) => Promise<void> | void): void;
 };
 export type RealtimeLimits = {
     /** Topics one connection may join. Default 128. */
@@ -41,18 +47,21 @@ export type RealtimeLimits = {
     /** `"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>>;
+/** `C` is the request context the route's middleware leaves for `identify` and `handler`. */
+export type RealtimeOptions<C = unknown> = {
     /**
-     * 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.
+     * The topic bus. Default: a fresh bus for this route. Routes share topics only when they are
+     * given the same bus and name the same namespace.
      */
+    bus?: RealtimeBus;
+    /** Route-level middleware, after the app's chain and scopes, before `identify` and the upgrade. */
+    use?: readonly MiddlewareFn<any, any>[];
+    /** Topic namespace within the bus. Default: the path given to `realtime()`. */
     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>;
+    identify?: (ctx: C) => Promise<string | null | undefined> | string | null | undefined;
+    /** Receives every error thrown by `handler` and the `message`/`close` handlers. */
+    onError?: (error: unknown, conn: ConnContext) => Promise<void> | void;
     limits?: RealtimeLimits;
     /**
      * Browser origins allowed to connect: `"*"`, a list (`https://app.example.com`), or a
@@ -60,22 +69,19 @@ export type RealtimeRouteOpts<C = unknown> = {
      * or `Authorization` gets 403.
      */
     allowedOrigins?: WSOriginPolicy;
-    handler: (c: C, conn: ConnContext) => void | Promise<void>;
+    handler: (ctx: C, conn: ConnContext) => Promise<void> | void;
 };
 /** A realtime route after validation, with every default applied. */
 export type RealtimeConfig = {
-    allowedOrigins: WSOriginPolicy | null;
-    handler: RealtimeRouteOpts["handler"];
-    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;
+    readonly allowedOrigins: WSOriginPolicy | null;
+    readonly bus: RealtimeBus;
+    readonly handler: (ctx: unknown, conn: ConnContext) => Promise<void> | void;
+    readonly identify: ((ctx: unknown) => Promise<string | null | undefined> | string | null | undefined) | null;
+    readonly limits: Readonly<Required<RealtimeLimits>>;
+    readonly namespace: string;
+    readonly onError: ((error: unknown, conn: ConnContext) => Promise<void> | void) | null;
+    readonly path: string;
+    readonly use: readonly MiddlewareFn<any, any>[];
 };
-/** 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
+/** Validate `realtime()` options and apply every default. */
+export declare function resolveRealtimeConfig<C>(path: string, options: RealtimeOptions<C>): RealtimeConfig;

package/dist/realtime/route.js

@@ -1,4 +1,5 @@
-import { validateOriginPolicy } from "../ws-origin.js";
+import { validateOriginPolicy } from "../ws/origin.js";
+import { createBus } from "./bus.js";
 const DEFAULT_LIMITS = {
     maxBufferedBytes: 4 * 1024 * 1024,
     maxFrameBytes: 1024 * 1024,
@@ -14,59 +15,42 @@ function positiveInt(name, value, fallback) {
     }
     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`);
+function resolveLimits(limits) {
+    const { slowConsumer } = limits;
+    if (slowConsumer !== undefined && slowConsumer !== "close" && slowConsumer !== "drop") {
+        throw new TypeError(`realtime limits.slowConsumer must be "close" or "drop", got ${String(slowConsumer)}`);
     }
-    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.`);
+    return {
+        maxBufferedBytes: positiveInt("maxBufferedBytes", limits.maxBufferedBytes, DEFAULT_LIMITS.maxBufferedBytes),
+        maxFrameBytes: positiveInt("maxFrameBytes", limits.maxFrameBytes, DEFAULT_LIMITS.maxFrameBytes),
+        maxPendingFrames: positiveInt("maxPendingFrames", limits.maxPendingFrames, DEFAULT_LIMITS.maxPendingFrames),
+        maxTopics: positiveInt("maxTopics", limits.maxTopics, DEFAULT_LIMITS.maxTopics),
+        slowConsumer: slowConsumer ?? DEFAULT_LIMITS.slowConsumer,
+    };
+}
+/** Validate `realtime()` options and apply every default. */
+export function resolveRealtimeConfig(path, options) {
+    const opts = options;
+    if (typeof opts?.handler !== "function")
+        throw new TypeError(`realtime("${path}"): handler must be a function`);
+    if (opts.reconnectBuffer !== undefined) {
+        throw new TypeError(`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.transports !== undefined) {
+        throw new TypeError(`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"`);
+        throw new TypeError(`realtime("${path}"): namespace must be a non-empty string`);
     }
     return {
         allowedOrigins: opts.allowedOrigins === undefined ? null : validateOriginPolicy(opts.allowedOrigins),
+        bus: opts.bus ?? createBus(),
         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,
-        },
+        limits: Object.freeze(resolveLimits(opts.limits ?? {})),
         namespace: opts.namespace ?? path,
-        namespaceExplicit: opts.namespace !== undefined,
         onError: opts.onError ?? null,
         path,
+        use: opts.use ?? [],
     };
 }
-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/server.d.ts

@@ -1,43 +1,39 @@
-import type { WSContext, WSHandler } from "../ws/cloudflare.ts";
-import type { RealtimeBus } from "./bus.ts";
+/**
+ * The server side of one realtime connection, and the publisher `realtime()` returns. The session
+ * binds the socket to the route's bus and runs the route's callbacks on its own ordered lane:
+ * `handler`, then each inbound frame, then `close`, each awaited and contained. The ws route's
+ * lane only hands it events, so a slow handler holds this lane, never the socket's.
+ */
+import type { WSContext } from "../ws/contract.ts";
+import { type RealtimeBus } from "./bus.ts";
+import { type InvokeLogger } from "./invoke-user.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. */
+/** What `realtime()` returns: publish into its route's namespace, or another namespace on its bus. */
 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.
-     */
+    /** Send `data` as one JSON frame to every connection on `topic`. Throws when `data` is not JSON. */
     publish(topic: string, data: unknown): void;
-    /** The publisher for one namespace (a route's `namespace` option, or its full path pattern). */
+    /** The publisher for another namespace on the same bus. */
     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 declare function createRealtimePublisher(bus: RealtimeBus, namespace: string): RealtimePublisher;
+/** One connection's events, as the realtime route's ws callbacks hand them over. */
 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;
+    /** Attach the open socket and run the route's handler (once). */
+    attach(ws: WSContext): void;
+    close(reason: string): void;
+    error(error: unknown): void;
+    message(data: ArrayBuffer | string): 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;
+type SessionOptions = {
     config: RealtimeConfig;
     ctx: unknown;
-    log: Logger | undefined;
+    log: InvokeLogger | null;
     userId: string | null;
-}): RealtimeSession;
+};
+/** One realtime connection over the route's bus; the realtime route's ws callbacks feed it. */
+export declare function createRealtimeSession(options: SessionOptions): RealtimeSession;
 export {};
-//# sourceMappingURL=server.d.ts.map