@lovrozagar/honey 0.7.3 → 1.0.0-rc.1

package/dist/realtime/server.js

@@ -1,255 +1,232 @@
-import { invokeUser } from "../invoke-user.js";
+import { CLOSE_INTERNAL, CLOSE_NORMAL, CLOSE_POLICY, CLOSE_TOO_BIG, CLOSE_TRY_AGAIN, exceedsPayload, } from "../ws/shared.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";
+import { createEventQueue, invokeUser, reportUserError } from "./invoke-user.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) {
+export function createRealtimePublisher(bus, namespace) {
     const forNs = (ns) => ({
-        publish(topic, data) {
-            bus.publish(topicKey(ns, String(topic)), data);
-        },
+        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);
-        },
-    };
+    return { namespace: (name) => forNs(String(name)), publish: forNs(namespace).publish };
 }
-/**
- * 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)
+class Session {
+    #config;
+    #ctx;
+    #log;
+    #id = crypto.randomUUID();
+    #fields;
+    #lane = createEventQueue();
+    #conn;
+    /* inbound frames in arrival order, including those that beat the open or the message handler */
+    #inbox = [];
+    #onMessage = null;
+    #onClose = null;
+    #socket = null;
+    #closed = false;
+    #closeQueued = false;
+    #drainScheduled = false;
+    #options;
+    constructor(options) {
+        this.#config = options.config;
+        this.#ctx = options.ctx;
+        this.#log = options.log;
+        this.#fields = { connId: this.#id, namespace: options.config.namespace, route: options.config.path };
+        this.#conn = this.#connContext(options.userId);
+        const { onError } = options.config;
+        const report = onError ? (error) => onError(error, this.#conn) : null;
+        const invokeAs = (phase) => ({
+            fields: this.#fields,
+            log: this.#log,
+            onError: report,
+            phase: `realtime ${phase}`,
+        });
+        this.#options = { close: invokeAs("close"), handler: invokeAs("handler"), message: invokeAs("message") };
+    }
+    attach(ws) {
+        if (this.#socket !== null || this.#closed)
             return;
-        tornDown = true;
-        closed = true;
-        bus.unsubscribeAll(connId);
-        bus.removeHandler(connId);
-    };
-    const closeSocket = (code, reason) => {
-        const ws = socket;
-        teardown();
-        if (ws === null)
+        this.#socket = ws;
+        this.#config.bus.onMessage(this.#id, this.#sendFrame);
+        void this.#lane.push(async () => {
+            const ok = await this.#invoke("handler", () => this.#config.handler(this.#ctx, this.#conn));
+            if (!ok)
+                this.#closeSocket(ws, CLOSE_INTERNAL, "internal error");
+        });
+        /* frames that beat the open run after the handler, ahead of later ones */
+        if (this.#inbox.length > 0)
+            this.#scheduleDrain();
+    }
+    close(reason) {
+        this.#teardown();
+        /* frames still waiting for a message handler are dropped: none can come for a closed connection */
+        if (this.#onMessage === null)
+            this.#inbox.length = 0;
+        if (this.#closeQueued)
+            return;
+        this.#closeQueued = true;
+        /* after every frame queued before it */
+        void this.#lane.push(async () => {
+            const fn = this.#onClose;
+            if (fn !== null)
+                await this.#invoke("close", () => fn(reason || "normal"));
+        });
+    }
+    error(error) {
+        reportUserError(error, { fields: this.#fields, log: this.#log, phase: "realtime socket error" });
+    }
+    message(data) {
+        /* the wire format is JSON text; binary frames are not part of it */
+        if (this.#closed || typeof data !== "string")
             return;
+        const { limits } = this.#config;
+        /* before the open there is no socket to close yet: a frame over a limit is dropped */
+        const ws = this.#socket;
+        if (exceedsPayload(data, limits.maxFrameBytes)) {
+            if (ws !== null)
+                this.#closeSocket(ws, CLOSE_TOO_BIG, "frame too large");
+            return;
+        }
+        let payload;
         try {
-            ws.close(code, truncateUtf8(reason, MAX_CLOSE_REASON));
+            payload = JSON.parse(data);
         }
-        catch (e) {
-            log?.warn?.({ connId, err: e }, "realtime close failed");
+        catch {
+            /* not JSON: not a frame of this protocol */
+            return;
         }
-    };
-    const sendFrame = (frame) => {
-        const ws = socket;
-        if (closed || ws === null)
+        if (this.#inbox.length >= limits.maxPendingFrames) {
+            if (ws !== null)
+                this.#closeSocket(ws, CLOSE_POLICY, "too many pending frames");
+            return;
+        }
+        this.#inbox.push(payload);
+        if (ws !== null)
+            this.#scheduleDrain();
+    }
+    #invoke(phase, fn) {
+        return invokeUser(fn, this.#options[phase]);
+    }
+    /** A transport failure is not the route's error: it is logged, never handed to onError. */
+    #transportFailed(phase, error) {
+        reportUserError(error, { fields: this.#fields, log: this.#log, phase: `realtime ${phase}` });
+    }
+    /* one drain at a time: a running drain takes every frame that arrives while it runs */
+    #scheduleDrain() {
+        if (this.#drainScheduled)
+            return;
+        this.#drainScheduled = true;
+        void this.#lane.push(this.#drain);
+    }
+    /** Drop the connection from the bus; runs once, before any close handler. */
+    #teardown() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#config.bus.unsubscribeAll(this.#id);
+        this.#config.bus.removeHandler(this.#id);
+    }
+    #closeSocket(ws, code, reason) {
+        this.#teardown();
+        try {
+            ws.close(code, reason);
+        }
+        catch (error) {
+            this.#transportFailed("close", error);
+        }
+    }
+    /* the bus's sink for this connection */
+    #sendFrame = (frame) => {
+        const ws = this.#socket;
+        if (this.#closed || ws === null)
             return;
-        if (bufferedAmountOf(ws.raw) > limits.maxBufferedBytes) {
-            if (limits.slowConsumer === "drop")
-                return;
-            closeSocket(CLOSE_TRY_AGAIN, "slow consumer");
+        const { limits } = this.#config;
+        if ((ws.bufferedAmount ?? 0) > limits.maxBufferedBytes) {
+            if (limits.slowConsumer === "close")
+                this.#closeSocket(ws, 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");
+        catch (error) {
+            this.#transportFailed("send", error);
         }
     };
-    /* 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;
+    /* frames wait until a message handler exists */
+    #drain = async () => {
+        try {
+            while (this.#inbox.length > 0) {
+                const fn = this.#onMessage;
+                if (fn === null)
+                    return;
+                const payload = this.#inbox.shift();
+                await this.#invoke("message", () => fn(payload));
             }
-            const payload = inbox.shift();
-            await invoke("message", () => fn(payload));
+        }
+        finally {
+            this.#drainScheduled = false;
         }
     };
-    const accept = (payload) => {
-        if (inbox.length >= limits.maxPendingFrames) {
-            closeSocket(CLOSE_POLICY, "too many pending frames");
+    #on(event, fn) {
+        if (typeof fn !== "function")
+            throw new TypeError("conn.on: handler must be a function");
+        if (event === "message") {
+            this.#onMessage = fn;
+            if (this.#inbox.length > 0)
+                this.#scheduleDrain();
+        }
+        else if (event === "close") {
+            this.#onClose = fn;
+        }
+        else {
+            throw new TypeError(`conn.on: unknown event "${event}"`);
+        }
+    }
+    #topic(topic) {
+        return topicKey(this.#config.namespace, String(topic));
+    }
+    #join(topic) {
+        if (this.#closed)
             return;
+        const { bus, limits } = this.#config;
+        const key = this.#topic(topic);
+        if (bus.topicCount(this.#id) >= limits.maxTopics && !bus.isSubscribed(this.#id, key)) {
+            throw new RangeError(`realtime: a connection may join at most ${limits.maxTopics} topics`);
         }
-        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));
+        bus.subscribe(this.#id, key);
+    }
+    #connContext(userId) {
+        const { bus } = this.#config;
+        const conn = {
+            close: (reason) => {
+                /* a conn exists only once its handler ran, after the socket attached */
+                const text = reason === undefined ? "" : String(reason);
+                if (!this.#closed)
+                    this.#closeSocket(this.#socket, CLOSE_NORMAL, text);
             },
-        },
-        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)));
+            closed: false,
+            id: this.#id,
+            join: (topic) => this.#join(topic),
+            leave: (topic) => {
+                if (!this.#closed)
+                    bus.unsubscribe(this.#id, this.#topic(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 };
+            on: ((event, fn) => this.#on(event, fn)),
+            /* publishing after close is allowed: a close handler announcing a departure is the common case */
+            publish: (topic, payload) => bus.publish(this.#topic(topic), payload),
+            send: (payload) => this.#sendFrame(encodeRealtimeFrame(payload)),
+            state: {},
+            transport: "ws",
+            userId,
+        };
+        Object.defineProperty(conn, "closed", { enumerable: true, get: () => this.#closed });
+        return Object.freeze(conn);
+    }
+}
+/** One realtime connection over the route's bus; the realtime route's ws callbacks feed it. */
+export function createRealtimeSession(options) {
+    return new Session(options);
 }
-//# sourceMappingURL=server.js.map

package/dist/response/binary.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The bytes `ctx.res.binary()` answers: what it takes, the media type it answers them as, and the
+ * header map it starts from. Bytes are a type contract (F8): never parsed, never validated.
+ */
+import type { ResponseOptions } from "./response.ts";
+/** The bytes a binary answer carries. */
+export type BinaryBody = ArrayBuffer | Uint8Array<ArrayBuffer>;
+/** `ctx.res.binary()`'s options: the media type (`application/octet-stream` by default) beside the usual ones. */
+export type BinaryOptions<CT extends string = string> = ResponseOptions & {
+    contentType?: CT;
+};
+export declare const BINARY_HEADERS: Readonly<{
+    "content-type": "application/octet-stream";
+}>;
+/** `body` as a Uint8Array: the same one, or a view over an ArrayBuffer, never a copy. */
+export declare function binaryBytes(body: BinaryBody): Uint8Array<ArrayBuffer>;
+/** The header map an answer of `contentType` starts from. */
+export declare function binaryHeaders(contentType: string | undefined): Readonly<Record<string, string>>;

package/dist/response/binary.js

@@ -0,0 +1,10 @@
+/* frozen: the Node path hands the map to the bag as its header map */
+export const BINARY_HEADERS = /* @__PURE__ */ Object.freeze({ "content-type": "application/octet-stream" });
+/** `body` as a Uint8Array: the same one, or a view over an ArrayBuffer, never a copy. */
+export function binaryBytes(body) {
+    return body instanceof Uint8Array ? body : new Uint8Array(body);
+}
+/** The header map an answer of `contentType` starts from. */
+export function binaryHeaders(contentType) {
+    return contentType === undefined ? BINARY_HEADERS : { "content-type": contentType };
+}

package/dist/response/builder.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Response construction. `HoneyResponse` is a Response-shaped bag for Node: it keeps a buffered
+ * body and a plain header map so the adapter can `res.end` it without `new Response()`, and builds
+ * a Fetch body stream only when something reads one. The raw-body side table lets every reader
+ * (raw(), HEAD, compress, output validation) find a native response's buffered body (H18.1).
+ */
+import { type HeaderMap, HoneyOutHeaders } from "./out-headers.ts";
+/** The Node adapter sets this on a request so `HoneyRes` can skip `new Response()`. */
+export declare const NODE_OUTBOUND: unique symbol;
+declare const HONEY_RESPONSE: unique symbol;
+export type RawBody = string | Uint8Array;
+export declare function isNodeOutbound(req: Request): boolean;
+export declare function isHoneyResponse(value: unknown): value is HoneyResponse;
+/**
+ * Record the buffered body a native response was built from. Only for a response honey constructed:
+ * a recorded body also tells withHeaders the headers are mutable.
+ */
+export declare function withRawBody(response: Response, body: RawBody): Response;
+/** The buffered body a response was built from, or `null` for a streamed or foreign one. */
+export declare function rawBodyOf(response: Response): RawBody | null;
+/** Record that `response` streams a body honey produced (sse, stream, generate). */
+export declare function withProducedBody(response: Response): Response;
+/** Whether `response` streams a body honey produced: one never to be buffered, as it may not end. */
+export declare function isProducedStream(response: Response): boolean;
+type HoneyResponseInit = {
+    headers: HeaderMap;
+    raw?: RawBody | null;
+    status: number;
+    statusText?: string;
+    stream?: ReadableStream<Uint8Array> | null;
+};
+type DeriveInit = {
+    headers?: HeaderMap | Headers | HoneyOutHeaders;
+    raw?: RawBody | null;
+    status?: number;
+    stream?: ReadableStream<Uint8Array> | null;
+};
+export declare class HoneyResponse {
+    #private;
+    readonly [HONEY_RESPONSE] = true;
+    readonly ok: boolean;
+    readonly redirected = false;
+    readonly status: number;
+    readonly statusText: string;
+    readonly type: ResponseType;
+    readonly url = "";
+    constructor(init: HoneyResponseInit);
+    get headers(): HoneyOutHeaders;
+    get body(): ReadableStream<Uint8Array> | null;
+    get bodyUsed(): boolean;
+    /** Plain header map for `res.writeHead`. */
+    get plainHeaders(): HeaderMap;
+    /** Known-size body for `res.end`. */
+    get rawBody(): RawBody | null;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    blob(): Promise<Blob>;
+    bytes(): Promise<Uint8Array>;
+    clone(): Response;
+    formData(): Promise<FormData>;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+    /** Copy this bag with new headers/status/body — keeps the Node `res.end` path. */
+    derive(init: DeriveInit): HoneyResponse;
+}
+export declare function createHoneyResponse(init: HoneyResponseInit): Response;
+type ReplaceInit = {
+    body?: BodyInit | null;
+    headers?: Headers | HoneyOutHeaders | HeaderMap;
+    status?: number;
+};
+/** Rebuild a response without dropping a HoneyResponse back to `new Response()`. */
+export declare function replaceResponse(response: Response, init: ReplaceInit): Response;
+export {};