@lovrozagar/honey 0.7.3 → 1.0.0-rc.1

package/dist/ws/node.js

@@ -1,173 +1,125 @@
-export { WSContextImpl, } from "./cloudflare.js";
-import { fireHandler, WSContextImpl } from "./cloudflare.js";
-import { resolveWSOptions, selectProtocol, toArrayBuffer, } from "./shared.js";
-const WS_MISSING = 'WebSocket routes on Node need the "ws" package, which is an optional peer dependency of honey. Install it: npm install ws';
 /**
- * Node.js WebSocket adapter, on the `ws` package (an optional peer dependency). It reads
- * `env.__nodeUpgrade`, which honey's `serve()` puts there for an upgrade request.
+ * The Node WebSocket adapter, on the `ws` package (an optional peer dependency, loaded on the first
+ * upgrade). The Node bridge's `'upgrade'` listener puts the raw socket on the request view under
+ * `NODE_UPGRADE`; the adapter hands it to `ws`, which writes the 101 itself, so the handshake
+ * never goes through the Fetch body writer. Keepalive pings and the idle timeout run here.
  */
-export function nodeWebSocket(opts) {
-    const options = resolveWSOptions(opts);
-    const keepalive = opts?.keepalive;
+import { optionalPeer } from "../runtime/optional-peer.js";
+import { fireHandler, switchingProtocols, WSContextImpl } from "./contract.js";
+import { resolveWSOptions, selectProtocol } from "./shared.js";
+export const NODE_UPGRADE = /* @__PURE__ */ Symbol("honey.nodeUpgrade");
+/** Ping a quiet peer and end one that stays quiet: the keepalive and the idle timeout. */
+function watch(ws, options, keepalive) {
+    let lastSeen = Date.now();
+    let pongDue;
+    const timers = [];
+    const seen = () => {
+        lastSeen = Date.now();
+    };
+    ws.on("pong", () => {
+        seen();
+        clearTimeout(pongDue);
+        pongDue = undefined;
+    });
+    ws.on("ping", seen);
+    ws.on("message", seen);
+    if (keepalive !== undefined) {
+        timers.push(setInterval(() => {
+            /* one pong outstanding at a time: a slow pong never stacks timers */
+            if (ws.readyState !== 1 || pongDue !== undefined)
+                return;
+            ws.ping();
+            pongDue = setTimeout(() => ws.terminate(), keepalive.timeout);
+        }, keepalive.interval));
+    }
+    const idle = options.idleTimeout;
+    if (idle > 0) {
+        const tick = Math.max(Math.floor(idle / 2), 1);
+        timers.push(setInterval(() => {
+            const quiet = Date.now() - lastSeen;
+            if (quiet >= idle)
+                ws.terminate();
+            else if (quiet >= tick)
+                ws.ping();
+        }, tick));
+    }
+    ws.on("close", () => {
+        for (const timer of timers)
+            clearInterval(timer);
+        clearTimeout(pongDue);
+    });
+}
+/** Wire one accepted socket to `handler`. Text frames arrive as strings, binary as exactly their bytes. */
+function wire(ws, socket, handler, open) {
+    ws.on("message", (data, isBinary) => {
+        const message = isBinary ? data : Buffer.from(data).toString("utf8");
+        fireHandler("message", () => handler.onMessage?.(undefined, socket, message));
+    });
+    ws.on("close", (code, reason) => {
+        open.delete(ws);
+        fireHandler("close", () => handler.onClose?.(undefined, socket, code, reason.toString()));
+    });
+    ws.on("error", (error) => {
+        fireHandler("error", () => handler.onError?.(undefined, socket, error));
+    });
+}
+export function nodeWebSocket(options) {
+    const resolved = resolveWSOptions(options);
+    const keepalive = options?.keepalive;
     if (keepalive !== undefined && !(keepalive.interval > 0 && keepalive.timeout > 0)) {
         throw new TypeError("nodeWebSocket: keepalive.interval and keepalive.timeout must be positive");
     }
-    let wss = null;
-    let wssReady = null;
+    const loadWs = optionalPeer("ws", "WebSocket routes on Node", () => import("ws"));
     const open = new Set();
-    /* the Request being upgraded, for the protocol callback (ws hands it the IncomingMessage) */
+    let server = null;
+    /* the request being upgraded, for the protocol choice: ws asks synchronously within handleUpgrade */
     let upgrading = null;
-    const ensureWss = () => {
-        if (wss)
-            return Promise.resolve(wss);
-        if (!wssReady) {
-            wssReady = import("ws").then((mod) => {
-                const wsModule = mod;
-                wss = new wsModule.WebSocketServer({
-                    handleProtocols: (protocols) => {
-                        if (protocols.size === 0 || upgrading === null)
-                            return false;
-                        return selectProtocol(upgrading, options) ?? false;
-                    },
-                    maxPayload: options.maxPayload,
-                    noServer: true,
-                    perMessageDeflate: false,
-                });
-                return wss;
-            }, (err) => {
-                /* not cached: installing ws later works without a restart */
-                wssReady = null;
-                throw new Error(WS_MISSING, { cause: err });
-            });
-        }
-        return wssReady;
-    };
-    const watch = (ws) => {
-        let pingTimer;
-        let pongTimeout;
-        let idleTimer;
-        let lastSeen = Date.now();
-        const seen = () => {
-            lastSeen = Date.now();
-        };
-        ws.on("pong", () => {
-            seen();
-            if (pongTimeout !== undefined) {
-                clearTimeout(pongTimeout);
-                pongTimeout = undefined;
-            }
+    const serverOf = async () => {
+        /* ws's ESM entry, or its CommonJS one under default: what Node resolves a retry to once ws was installed */
+        const ws = (await loadWs());
+        const { WebSocketServer } = "WebSocketServer" in ws ? ws : ws.default;
+        server ??= new WebSocketServer({
+            /* asked only within handleUpgrade, so the request is the one being upgraded */
+            handleProtocols: () => selectProtocol(upgrading, resolved) ?? false,
+            maxPayload: resolved.maxPayload,
+            noServer: true,
+            perMessageDeflate: false,
         });
-        ws.on("ping", seen);
-        if (keepalive) {
-            pingTimer = setInterval(() => {
-                if (ws.readyState !== 1)
-                    return;
-                /* one pong outstanding at a time: a slow pong must not stack timers */
-                if (pongTimeout !== undefined)
-                    return;
-                ws.ping();
-                pongTimeout = setTimeout(() => ws.terminate(), keepalive.timeout);
-            }, keepalive.interval);
-        }
-        const idle = options.idleTimeout;
-        if (idle > 0) {
-            const tick = Math.max(Math.floor(idle / 2), 1);
-            idleTimer = setInterval(() => {
-                if (ws.readyState !== 1)
-                    return;
-                const quiet = Date.now() - lastSeen;
-                if (quiet >= idle)
-                    ws.terminate();
-                else if (quiet >= tick)
-                    ws.ping();
-            }, tick);
-        }
-        const stop = () => {
-            if (pingTimer !== undefined)
-                clearInterval(pingTimer);
-            if (pongTimeout !== undefined)
-                clearTimeout(pongTimeout);
-            if (idleTimer !== undefined)
-                clearInterval(idleTimer);
-            pingTimer = pongTimeout = idleTimer = undefined;
-        };
-        ws.on("close", stop);
-        ws.on("error", stop);
+        return server;
     };
     return {
         closeAll(code, reason) {
-            for (const ws of open) {
-                try {
-                    ws.close(code, reason);
-                }
-                catch {
-                    ws.terminate();
-                }
-            }
+            for (const ws of open)
+                ws.close(code, reason);
         },
-        options,
-        async upgrade(req, env, handler) {
-            const server = await ensureWss();
-            const upgrade = env.__nodeUpgrade;
-            if (upgrade === undefined) {
-                throw new Error("nodeWebSocket: no upgrade socket; serve the app with honey's serve() on Node");
-            }
+        options: resolved,
+        runtime: "node",
+        async upgrade(req, _env, handler) {
+            const upgrade = req[NODE_UPGRADE];
+            if (upgrade === undefined)
+                throw new Error("nodeWebSocket needs the upgrade socket: serve the app with serve(app) on Node");
+            const wss = await serverOf();
             return new Promise((resolve, reject) => {
                 /* ws answers a malformed handshake itself and never calls back: fail instead of hanging */
-                const sock = upgrade.socket;
-                sock.once?.("close", () => {
+                ;
+                upgrade.socket.once("close", () => {
                     if (!upgrade.upgraded)
                         reject(new Error("WebSocket handshake failed"));
                 });
                 upgrading = req;
-                try {
-                    server.handleUpgrade(upgrade.req, upgrade.socket, upgrade.head, (ws) => {
-                        upgrade.upgraded = true;
-                        ws.binaryType = "arraybuffer";
-                        open.add(ws);
-                        const socket = new WSContextImpl(ws, options);
-                        ws.on("message", (data, isBinary) => {
-                            let payload;
-                            if (!isBinary) {
-                                /* text frame: a string, as on every other runtime */
-                                payload = Buffer.isBuffer(data)
-                                    ? data.toString("utf-8")
-                                    : data instanceof ArrayBuffer
-                                        ? Buffer.from(data).toString("utf-8")
-                                        : Buffer.concat(data).toString("utf-8");
-                            }
-                            else if (data instanceof ArrayBuffer) {
-                                payload = data;
-                            }
-                            else {
-                                payload = toArrayBuffer(Array.isArray(data) ? Buffer.concat(data) : data);
-                            }
-                            fireHandler("message", () => handler.onMessage?.(undefined, socket, payload));
-                        });
-                        watch(ws);
-                        ws.on("close", (code, reason) => {
-                            open.delete(ws);
-                            fireHandler("close", () => handler.onClose?.(undefined, socket, code, reason.toString()));
-                        });
-                        ws.on("error", (err) => {
-                            fireHandler("error", () => handler.onError?.(undefined, socket, err));
-                        });
-                        fireHandler("open", () => handler.onOpen?.(undefined, socket));
-                        /* Node's Response rejects status 101 (Fetch spec: 200-599 only).
-                           Create a valid Response and override status for the sentinel check. */
-                        const resp = new Response(null);
-                        Object.defineProperty(resp, "status", { value: 101 });
-                        resolve({ response: resp, socket });
-                    });
-                }
-                catch (err) {
-                    reject(err);
-                }
-                finally {
-                    upgrading = null;
-                }
+                wss.handleUpgrade(upgrade.req, upgrade.socket, upgrade.head, (ws) => {
+                    /* from here the socket is the WebSocket's: the bridge must never write HTTP on it */
+                    upgrade.upgraded = true;
+                    ws.binaryType = "arraybuffer";
+                    open.add(ws);
+                    const socket = new WSContextImpl(ws, resolved);
+                    wire(ws, socket, handler, open);
+                    watch(ws, resolved, keepalive);
+                    fireHandler("open", () => handler.onOpen?.(undefined, socket));
+                    resolve({ response: switchingProtocols({ upgrade: "websocket" }), socket });
+                });
+                upgrading = null;
             });
         },
     };
 }
-//# sourceMappingURL=node.js.map

package/dist/ws/origin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Which browser origins may open a WebSocket. A browser lets any page open a socket to any host
+ * and sends that host's cookies with it, so a cookie-authenticated socket is open to cross-site
+ * hijacking unless the server checks `Origin`.
+ *
+ * - `"*"`: every origin.
+ * - a list: those exact origins (scheme, host and port), plus same-origin.
+ * - a function: called with the `Origin` value; same-origin always passes.
+ * - unset (the default): same-origin passes; a cross-origin upgrade carrying credentials (`Cookie`
+ *   or `Authorization`, what hijacking needs) is rejected. A request without `Origin` (not a
+ *   browser) passes.
+ *
+ * Same-origin is the full origin (H18.12): an `http://` page is not same-origin to an `https`
+ * server. Behind a TLS terminator the server sees plain http, so the shortcut fails closed there:
+ * such an app lists its origins.
+ */
+export type WSOriginPolicy = "*" | readonly string[] | ((origin: string) => boolean);
+export declare function validateOriginPolicy(policy: unknown): WSOriginPolicy;
+/**
+ * Whether an upgrade from `origin` (the `Origin` header, `null` when absent) may proceed against a
+ * server whose own origin is `serverOrigin` (`new URL(req.url).origin`).
+ */
+export declare function originAllowed(policy: WSOriginPolicy | null, origin: string | null, serverOrigin: string, hasCredentials: boolean): boolean;

package/dist/ws/origin.js

@@ -0,0 +1,48 @@
+/** `URL.parse` without it: Node 20 lacks it. */
+function parseUrl(text) {
+    try {
+        return new URL(text);
+    }
+    catch {
+        /* not a URL: an Origin no policy can match, which the caller refuses */
+        return null;
+    }
+}
+/** An origin's canonical spelling (lowercase, default port dropped), or `null` for `"null"` or a non-URL. */
+function canonicalOrigin(text) {
+    const origin = parseUrl(text)?.origin;
+    return origin === undefined || origin === "null" ? null : origin;
+}
+/** A list entry: exactly an origin, normalized. A path, query or fragment means it is not one. */
+function listedOrigin(entry) {
+    const url = parseUrl(entry);
+    const origin = url === null || url.origin === "null" ? null : url.origin;
+    if (origin === null || url?.pathname !== "/" || url.search !== "" || url.hash !== "") {
+        throw new TypeError(`allowedOrigins: "${entry}" is not an origin like https://example.com`);
+    }
+    return origin;
+}
+export function validateOriginPolicy(policy) {
+    if (policy === "*" || typeof policy === "function")
+        return policy;
+    if (Array.isArray(policy) && policy.every((entry) => typeof entry === "string")) {
+        return Object.freeze(policy.map(listedOrigin));
+    }
+    throw new TypeError('allowedOrigins must be "*", a list of origins, or a function');
+}
+/**
+ * Whether an upgrade from `origin` (the `Origin` header, `null` when absent) may proceed against a
+ * server whose own origin is `serverOrigin` (`new URL(req.url).origin`).
+ */
+export function originAllowed(policy, origin, serverOrigin, hasCredentials) {
+    if (policy === "*" || origin === null)
+        return true;
+    const canonical = canonicalOrigin(origin);
+    if (canonical === serverOrigin)
+        return true;
+    if (policy === null)
+        return !hasCredentials;
+    if (typeof policy === "function")
+        return policy(origin) === true;
+    return canonical !== null && policy.includes(canonical);
+}

package/dist/ws/route.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `ws(app, path)`: a WebSocket route on `app`'s handle, `.handler({ onOpen, onMessage, onClose, … })`
+ * registers it. A plain function the app module imports (`@lovrozagar/honey/ws`), not a `Honey`
+ * method, so an app that never opens a socket bundles none of the route builder (H23).
+ */
+import type { Honey } from "../routing/app.ts";
+import type { ApplyScoped, ScopedMwEntry } from "../routing/app-types.ts";
+import type { MergePath } from "../routing/types.ts";
+import { type WSRouteBuilder } from "../routing/ws-builder.ts";
+/** Any app handle: a `honey()` app or a handle its `use()`, `basePath()`, `context()` or `meta()` returned. */
+export type AnyHoneyHandle = Honey<any, any, any, any, any, any, any, any, any>;
+/** The builder `ws(app, path)` returns: the handle's ctx with the scopes over the route, at the joined path. */
+export type WsRouteOf<TApp, TPath extends string> = TApp extends Honey<any, infer TCtx, any, any, any, any, infer TBase, any, infer TScoped extends readonly ScopedMwEntry[]> ? WSRouteBuilder<TCtx & ApplyScoped<TScoped, MergePath<TBase, TPath>>, MergePath<TBase, TPath>, TApp> : never;
+export declare function ws<TApp extends AnyHoneyHandle, const TPath extends string>(app: TApp, path: TPath): WsRouteOf<TApp, TPath>;

package/dist/ws/route.js

@@ -0,0 +1,5 @@
+import { GRAPH, VIEW } from "../routing/register.js";
+import { startWsRoute } from "../routing/ws-builder.js";
+export function ws(app, path) {
+    return startWsRoute(app[GRAPH], app[VIEW], app, path);
+}

package/dist/ws/session.d.ts

@@ -1,11 +1,20 @@
-import { type InvokeLogger } from "../invoke-user.ts";
-import type { WSHandler } from "./cloudflare.ts";
-/** `callbacks` are the route's own; each receives the route's request context `ctx` first. */
-export declare function createWsSession(opts: {
+/**
+ * The server side of one ws route connection: the route's callbacks run on one ordered lane (open,
+ * then messages, then close), each contained, with a cap on messages waiting for the handler.
+ * A plain module: importing it registers nothing (H23).
+ */
+import { type InvokeLogger } from "../realtime/invoke-user.ts";
+import type { WSHandler } from "./contract.ts";
+/** Messages one connection may have waiting for its handler; more close it with 1008. */
+export declare const WS_PENDING_MAX = 1024;
+export type WsSessionOptions = {
+    /** The route's own callbacks; each receives the route's request context first. */
     callbacks: WSHandler<unknown>;
     ctx: unknown;
     log: InvokeLogger | null;
+    /** The client's `reconnect_token`: `onReconnect` runs in place of `onOpen` when both exist. */
     reconnectToken: string | null;
     route: string;
-}): WSHandler<unknown>;
-//# sourceMappingURL=session.d.ts.map
+};
+/** The adapter-facing handler for one connection. */
+export declare function createWsSession(options: WsSessionOptions): WSHandler<unknown>;

package/dist/ws/session.js

@@ -1,24 +1,25 @@
 /**
- * The server side of one websocket route connection: the user's callbacks run on one ordered
- * queue (open, then messages, then close), each contained, with a cap on waiting messages.
- * Every honey adapter imports this module, which registers it, so the core never bundles it
- * for an app without websockets.
+ * The server side of one ws route connection: the route's callbacks run on one ordered lane (open,
+ * then messages, then close), each contained, with a cap on messages waiting for the handler.
+ * A plain module: importing it registers nothing (H23).
  */
-import { registerFeature } from "../feature-slots.js";
-import { createEventQueue, invokeUser } from "../invoke-user.js";
-import { originAllowed } from "../ws-origin.js";
-/** Messages one websocket connection may have waiting for its handler; more close it with 1008. */
-const WS_PENDING_MAX = 1024;
-/** `callbacks` are the route's own; each receives the route's request context `ctx` first. */
-export function createWsSession(opts) {
-    const { callbacks, ctx, log, reconnectToken, route } = opts;
+import { createEventQueue, invokeUser } from "../realtime/invoke-user.js";
+import { CLOSE_POLICY } from "./shared.js";
+/** Messages one connection may have waiting for its handler; more close it with 1008. */
+export const WS_PENDING_MAX = 1024;
+/** The adapter-facing handler for one connection. */
+export function createWsSession(options) {
+    const { callbacks, ctx, log, reconnectToken, route } = options;
     const { onClose, onError, onMessage, onOpen, onReconnect } = callbacks;
     const queue = createEventQueue();
     let pending = 0;
+    const handled = () => {
+        pending--;
+    };
     const run = (phase, ws, fn) => invokeUser(fn, {
         fields: { route },
         log,
-        onError: onError ? (err) => onError(ctx, ws, err) : null,
+        onError: onError ? (error) => onError(ctx, ws, error) : null,
         phase: `websocket ${phase}`,
     });
     return {
@@ -26,7 +27,7 @@ export function createWsSession(opts) {
             if (onClose)
                 void queue.push(() => run("close", ws, () => onClose(ctx, ws, code, reason)));
         },
-        /* a transport error: tell onError once; if onError throws, that is logged */
+        /* a transport error: onError hears it once; without one, it is logged */
         onError: (_ctx, ws, error) => {
             void queue.push(() => invokeUser(() => (onError ? onError(ctx, ws, error) : Promise.reject(error)), {
                 fields: { route },
@@ -37,16 +38,16 @@ export function createWsSession(opts) {
         onMessage: (_ctx, ws, data) => {
             if (!onMessage)
                 return;
-            if (pending >= WS_PENDING_MAX) {
-                ws.close(1008, "too many pending messages");
-                return;
-            }
+            if (pending >= WS_PENDING_MAX)
+                return ws.close(CLOSE_POLICY, "too many pending messages");
             pending++;
-            void queue.push(() => run("message", ws, () => onMessage(ctx, ws, data)).finally(() => {
-                pending--;
-            }));
+            void queue.push(() => {
+                const ran = run("message", ws, () => onMessage(ctx, ws, data));
+                return typeof ran === "boolean" ? handled() : ran.then(handled);
+            });
         },
         onOpen: (_ctx, ws) => {
+            /* an empty token is no token */
             if (reconnectToken && onReconnect) {
                 void queue.push(() => run("open", ws, () => onReconnect(ctx, ws, reconnectToken)));
             }
@@ -56,5 +57,3 @@ export function createWsSession(opts) {
         },
     };
 }
-registerFeature("ws", { createWsSession, originAllowed });
-//# sourceMappingURL=session.js.map

package/dist/ws/shared.d.ts

@@ -1,65 +1,55 @@
 /**
- * Options every WebSocket adapter takes, with the same meaning and defaults on Node, Bun, Deno
- * and Workers. Each adapter enforces what its runtime does not.
+ * What every WebSocket adapter shares: the options with one meaning and one default on Node, Bun
+ * and Workers, subprotocol choice, payload and close-frame rules, and close-reason truncation.
  */
 export type WSAdapterOptions = {
     /**
-     * Largest inbound message in bytes. A bigger one closes the connection with 1009.
-     * Default 1 MiB.
+     * Largest inbound message in bytes; a bigger one closes the connection with 1009 (on Bun, 1006:
+     * Bun enforces the limit itself and force-closes without a close frame). Default 1 MiB.
      */
     maxPayload?: number;
-    /**
-     * Outbound bytes a socket may hold unsent before `backpressurePolicy` applies to the next
-     * `send()`. Default 8 MiB.
-     */
+    /** Outbound bytes a socket may hold unsent before `backpressurePolicy` applies to the next `send()`. Default 8 MiB. */
     backpressureLimit?: number;
-    /**
-     * Over `backpressureLimit`: `"close"` closes the connection with 1013 (try again later),
-     * `"drop"` discards the message. Default `"close"`.
-     */
+    /** Over `backpressureLimit`: `"close"` closes with 1013 (try again later), `"drop"` discards the message. Default `"close"`. */
     backpressurePolicy?: "close" | "drop";
     /**
-     * Close a connection that has received nothing (no message, no pong) for this many
-     * milliseconds. Idle peers are pinged first where the runtime allows it. `0` disables.
-     * Default 120 000 (Bun's default). Deno and Bun take whole seconds.
+     * Close a connection that received nothing (no message, no pong) for this many ms. Idle peers
+     * are pinged first where the runtime allows it. `0` disables. Default 120 000; Bun takes whole seconds.
      */
     idleTimeout?: number;
-    /**
-     * Choose the subprotocol from the ones the client offered (`Sec-WebSocket-Protocol`).
-     * Return `null` or `undefined` for none. Default: the first one offered.
-     */
+    /** Choose the subprotocol from the ones the client offered; `null` or `undefined` for none. Default: the first offered. */
     protocol?: (offered: string[], req: Request) => string | null | undefined;
 };
 export type ResolvedWSOptions = {
-    backpressureLimit: number;
-    backpressurePolicy: "close" | "drop";
-    idleTimeout: number;
-    maxPayload: number;
-    protocol: (offered: string[], req: Request) => string | null | undefined;
+    readonly backpressureLimit: number;
+    readonly backpressurePolicy: "close" | "drop";
+    readonly idleTimeout: number;
+    readonly maxPayload: number;
+    readonly protocol: (offered: string[], req: Request) => string | null | undefined;
 };
 export declare const DEFAULT_MAX_PAYLOAD: number;
 export declare const DEFAULT_BACKPRESSURE_LIMIT: number;
 export declare const DEFAULT_IDLE_TIMEOUT = 120000;
-/** Close codes the adapters and the realtime server use. */
 export declare const CLOSE_NORMAL = 1000;
 export declare const CLOSE_GOING_AWAY = 1001;
 export declare const CLOSE_POLICY = 1008;
 export declare const CLOSE_TOO_BIG = 1009;
 export declare const CLOSE_INTERNAL = 1011;
 export declare const CLOSE_TRY_AGAIN = 1013;
-/** Longest close reason a frame can carry (125-byte control payload minus the 2-byte code). */
+/** Longest close reason a frame carries: a 125-byte control payload minus the 2-byte code. */
 export declare const MAX_CLOSE_REASON = 123;
-export declare function resolveWSOptions(opts: WSAdapterOptions | undefined): ResolvedWSOptions;
+export declare function resolveWSOptions(options: WSAdapterOptions | undefined): ResolvedWSOptions;
 /** The subprotocols the client offered, in order. */
 export declare function offeredProtocols(req: Request): string[];
-/** The subprotocol to answer with, or `null`. A choice the client did not offer is ignored. */
-export declare function selectProtocol(req: Request, opts: ResolvedWSOptions): string | null;
-/** Outbound bytes the runtime holds for this socket, when it reports them. */
+/** The subprotocol to answer with, or `null`; a choice the client did not offer is ignored. */
+export declare function selectProtocol(req: Request, options: ResolvedWSOptions): string | null;
+/** Outbound bytes the runtime holds for this socket, when it reports them (Bun's method, the DOM property). */
 export declare function bufferedAmountOf(raw: unknown): number;
 /** Whether an inbound message is larger than `limit` bytes. */
 export declare function exceedsPayload(data: ArrayBuffer | ArrayBufferView | Blob | string, limit: number): boolean;
-/** `data` as an `ArrayBuffer` holding exactly its bytes (a pooled Buffer's backing store is larger). */
+/** `data` as an ArrayBuffer holding exactly its bytes (a pooled Buffer's backing store is larger). */
 export declare function toArrayBuffer(data: ArrayBuffer | ArrayBufferView): ArrayBuffer;
-/** A close code a server may send: 1000, 1001-1014 except the reserved ones, or 3000-4999. */
+/** A close code a server may send (RFC 6455 §7.4): 1000, 1001–1014 but the reserved ones, or 3000–4999; else 1000. */
 export declare function sendableCloseCode(code: number | undefined): number;
-//# sourceMappingURL=shared.d.ts.map
+/** `reason` cut to at most `max` UTF-8 bytes without splitting a code point. */
+export declare function truncateUtf8(reason: string, max: number): string;