@fishenv/http 0.0.0-stage → 0.0.3

package/dist/ws/hub.js

@@ -0,0 +1,489 @@
+/**
+ * Keyed registry of live sockets plus server-side rooms — the seam for
+ * targeted (non-broadcast) sends from anywhere in the application.
+ */
+import { createTransportBridge, } from "../core/index.js";
+import { WsChannelTarget } from "./channels/target.js";
+import { PresenceRegistry, PresenceTopic, } from "./presence.js";
+import { WsCloseCode } from "./types.js";
+const NO_FILTER = {
+    exceptIds: new Set(),
+    exceptKeys: new Set(),
+    onlyKeys: null,
+};
+function isUnfiltered(filter) {
+    return (filter.exceptIds.size === 0 &&
+        filter.exceptKeys.size === 0 &&
+        filter.onlyKeys == null);
+}
+function toWireFilter(filter) {
+    if (isUnfiltered(filter))
+        return undefined;
+    return {
+        exceptIds: filter.exceptIds.size ? [...filter.exceptIds] : undefined,
+        exceptKeys: filter.exceptKeys.size ? [...filter.exceptKeys] : undefined,
+        onlyKeys: filter.onlyKeys ? [...filter.onlyKeys] : undefined,
+    };
+}
+function fromWireFilter(wire) {
+    if (wire == null)
+        return NO_FILTER;
+    return {
+        exceptIds: new Set(wire.exceptIds ?? []),
+        exceptKeys: new Set(wire.exceptKeys ?? []),
+        onlyKeys: wire.onlyKeys ? new Set(wire.onlyKeys) : null,
+    };
+}
+/** A fan-out target: a room, optionally narrowed to/away from sockets or keys. */
+export class WsRoomTarget {
+    #hub;
+    #room;
+    #filter;
+    /** @internal Use `hub.to(room)`. */
+    constructor(hub, room, filter = NO_FILTER) {
+        this.#hub = hub;
+        this.#room = room;
+        this.#filter = filter;
+    }
+    /** Exclude a socket (e.g. the sender) or every socket of a key. */
+    except(...targets) {
+        const exceptIds = new Set(this.#filter.exceptIds);
+        const exceptKeys = new Set(this.#filter.exceptKeys);
+        for (const t of targets) {
+            if (typeof t === "string")
+                exceptKeys.add(t);
+            else
+                exceptIds.add(t.id);
+        }
+        return new WsRoomTarget(this.#hub, this.#room, {
+            ...this.#filter,
+            exceptIds,
+            exceptKeys,
+        });
+    }
+    /** Only members registered under one of `keys`. */
+    only(...keys) {
+        const onlyKeys = new Set(keys);
+        if (this.#filter.onlyKeys != null) {
+            for (const k of [...onlyKeys]) {
+                if (!this.#filter.onlyKeys.has(k))
+                    onlyKeys.delete(k);
+            }
+        }
+        return new WsRoomTarget(this.#hub, this.#room, {
+            ...this.#filter,
+            onlyKeys,
+        });
+    }
+    /** Deliver to matching members on every node. Returns the local delivery count. */
+    send(data) {
+        return this.#hub._sendRoom(this.#room, encodeFrame(data), this.#filter, true);
+    }
+    /**
+     * Remove matching members from the room on every node, running any leave
+     * hook registered for them (channels use this to notify the client).
+     */
+    kick(reason = "") {
+        return this.#hub._kick(this.#room, this.#filter, reason, true);
+    }
+    /** Local matching member count. */
+    count() {
+        return this.sockets().length;
+    }
+    /** Local matching members. */
+    sockets() {
+        return this.#hub._members(this.#room, this.#filter);
+    }
+}
+/**
+ * Sockets keyed by an application identity (user id, tenant id, device…),
+ * plus server-side **rooms** — groupings the server assigns; clients can't
+ * ask to join one. One key maps to many sockets (tabs); one socket has at
+ * most one key and any number of rooms.
+ *
+ * Subclass it to get a DI token:
+ * ```ts
+ * class ChatSockets extends WsHub {}
+ * ```
+ */
+export class WsHub {
+    name;
+    #byKey = new Map();
+    #keyOf = new Map();
+    #rooms = new Map();
+    #roomsOf = new Map();
+    #tracked = new Set();
+    #leaveHooks = new Map();
+    #extensions = new Map();
+    #bridge;
+    #replicated;
+    #presenceOptions;
+    #presence;
+    constructor(options = {}) {
+        this.name = options.name ?? this.constructor.name;
+        this.#replicated = options.transport != null;
+        this.#presenceOptions = options.presence;
+        this.#bridge = createTransportBridge(options.transport, (message) => {
+            if (message.hub === this.name)
+                this.#onRemote(message);
+        }, { label: "[fishenv.ws]" });
+    }
+    /** Random id of this hub instance on the transport. */
+    get nodeId() {
+        return this.#bridge.nodeId;
+    }
+    // ── Registration ────────────────────────────────────────────────────
+    /**
+     * Register a socket under `key`. Returns an unregister fn; also
+     * auto-removes (keys and rooms) on close. Re-adding moves the socket.
+     */
+    add(key, socket) {
+        if (socket.closed)
+            return () => { };
+        this.#removeKey(socket);
+        let set = this.#byKey.get(key);
+        if (set == null) {
+            set = new Set();
+            this.#byKey.set(key, set);
+        }
+        set.add(socket);
+        this.#keyOf.set(socket, key);
+        this.#track(socket);
+        return () => {
+            if (this.#keyOf.get(socket) === key)
+                this.#removeKey(socket);
+        };
+    }
+    /** The key a socket was registered under, if any. */
+    keyOf(socket) {
+        return this.#keyOf.get(socket);
+    }
+    // ── Rooms ───────────────────────────────────────────────────────────
+    /** Put a socket in a room (idempotent). Server-side only. */
+    join(socket, room) {
+        if (socket.closed)
+            return;
+        let members = this.#rooms.get(room);
+        if (members == null) {
+            members = new Set();
+            this.#rooms.set(room, members);
+        }
+        if (members.has(socket))
+            return;
+        members.add(socket);
+        let rooms = this.#roomsOf.get(socket);
+        if (rooms == null) {
+            rooms = new Set();
+            this.#roomsOf.set(socket, rooms);
+        }
+        rooms.add(room);
+        if (serverOf(socket) != null)
+            socket.raw.subscribe(this.#topic(room));
+        this.#track(socket);
+    }
+    /** Remove a socket from a room. Does *not* run leave hooks. */
+    leave(socket, room) {
+        this.#leaveHooks.get(socket)?.delete(room);
+        const members = this.#rooms.get(room);
+        if (members == null || !members.delete(socket))
+            return;
+        if (members.size === 0)
+            this.#rooms.delete(room);
+        const rooms = this.#roomsOf.get(socket);
+        rooms?.delete(room);
+        if (rooms?.size === 0)
+            this.#roomsOf.delete(socket);
+        if (!socket.closed && serverOf(socket) != null) {
+            socket.raw.unsubscribe(this.#topic(room));
+        }
+    }
+    /** Rooms a socket is in. */
+    rooms(socket) {
+        return [...(this.#roomsOf.get(socket) ?? [])];
+    }
+    /** Every room with at least one local member. */
+    roomNames() {
+        return [...this.#rooms.keys()];
+    }
+    to(room) {
+        return new WsRoomTarget(this, room);
+    }
+    channel(a, b) {
+        return new WsChannelTarget(this, typeof a === "string" ? a : (b ?? ""));
+    }
+    // ── Sending ─────────────────────────────────────────────────────────
+    /** Send to every socket of `key` on every node. Returns local delivery count. */
+    send(key, data) {
+        const frame = encodeFrame(data);
+        this.#bridge.publish({
+            hub: this.name,
+            kind: "send",
+            key,
+            payload: toWire(frame),
+        });
+        return this.#deliverKey(key, frame);
+    }
+    sendMany(keys, data) {
+        let delivered = 0;
+        for (const key of keys)
+            delivered += this.send(key, data);
+        return delivered;
+    }
+    /** Send to every keyed socket in this hub, on every node. */
+    broadcast(data) {
+        const frame = encodeFrame(data);
+        this.#bridge.publish({
+            hub: this.name,
+            kind: "send",
+            key: null,
+            payload: toWire(frame),
+        });
+        return this.#deliverAll(frame);
+    }
+    /**
+     * Close every socket of `key` on every node — e.g. on logout or when
+     * permissions are revoked. Returns the local count.
+     */
+    close(key, code = WsCloseCode.Normal, reason = "") {
+        this.#bridge.publish({ hub: this.name, kind: "close", key, code, reason });
+        return this.#closeKey(key, code, reason);
+    }
+    /** Close every local socket and detach from the transport. */
+    closeAll(code = WsCloseCode.GoingAway, reason = "") {
+        for (const socket of [...this.#tracked])
+            socket.close(code, reason);
+        this.#presence?.close();
+        this.#bridge.close();
+    }
+    // ── Presence ────────────────────────────────────────────────────────
+    /**
+     * Presence for a topic — who is "in" it, by key, across every node.
+     * Channels with contract presence use `hub.channel(name).presence`.
+     */
+    presence(topic) {
+        return new PresenceTopic(this._presenceRegistry(), topic);
+    }
+    /** @internal The hub's presence registry (created on first use). */
+    _presenceRegistry() {
+        this.#presence ??= new PresenceRegistry(this, this.#replicated, this.#presenceOptions);
+        return this.#presence;
+    }
+    // ── Introspection ───────────────────────────────────────────────────
+    has(key) {
+        return (this.#byKey.get(key)?.size ?? 0) > 0;
+    }
+    /** Socket count for `key`, or every keyed socket when omitted. */
+    count(key) {
+        if (key != null)
+            return this.#byKey.get(key)?.size ?? 0;
+        return this.#keyOf.size;
+    }
+    keys() {
+        return [...this.#byKey.keys()];
+    }
+    connections(key) {
+        return [...(this.#byKey.get(key) ?? [])];
+    }
+    // ── Extension points (channels, presence) ───────────────────────────
+    /**
+     * @internal Run `hook` when `socket` is kicked from `room` (locally or by
+     * another node). The hook is responsible for calling `leave()`.
+     */
+    _onLeave(socket, room, hook) {
+        let hooks = this.#leaveHooks.get(socket);
+        if (hooks == null) {
+            hooks = new Map();
+            this.#leaveHooks.set(socket, hooks);
+        }
+        hooks.set(room, hook);
+    }
+    /** @internal Receive transport messages of an extension (e.g. presence). */
+    _registerExtension(kind, onRemote) {
+        this.#extensions.set(kind, onRemote);
+    }
+    /** @internal Publish an extension message to other nodes. */
+    _publishExtension(kind, body) {
+        this.#bridge.publish({ hub: this.name, kind, body });
+    }
+    /** @internal */
+    _members(room, filter = NO_FILTER) {
+        return [...(this.#rooms.get(room) ?? [])].filter((s) => this.#matches(s, filter));
+    }
+    /** @internal */
+    _sendRoom(room, frame, filter, publish) {
+        if (publish) {
+            this.#bridge.publish({
+                hub: this.name,
+                kind: "room",
+                room,
+                payload: toWire(frame),
+                filter: toWireFilter(filter),
+            });
+        }
+        const members = this.#rooms.get(room);
+        if (members == null)
+            return 0;
+        // Fast path: no filter → one native publish per server.
+        if (isUnfiltered(filter)) {
+            const servers = new Set();
+            let delivered = 0;
+            for (const socket of members) {
+                if (socket.closed)
+                    continue;
+                const server = serverOf(socket);
+                if (server == null) {
+                    if (isDelivered(socket.send(frame)))
+                        delivered++;
+                }
+                else {
+                    servers.add(server);
+                    delivered++;
+                }
+            }
+            for (const server of servers)
+                server.publish(this.#topic(room), frame);
+            return delivered;
+        }
+        let delivered = 0;
+        for (const socket of [...members]) {
+            if (!this.#matches(socket, filter))
+                continue;
+            if (isDelivered(socket.send(frame)))
+                delivered++;
+        }
+        return delivered;
+    }
+    /** @internal */
+    _kick(room, filter, reason, publish) {
+        if (publish) {
+            this.#bridge.publish({
+                hub: this.name,
+                kind: "kick",
+                room,
+                filter: toWireFilter(filter),
+                reason,
+            });
+        }
+        const targets = this._members(room, filter);
+        for (const socket of targets) {
+            const hook = this.#leaveHooks.get(socket)?.get(room);
+            if (hook != null)
+                hook(reason);
+            else
+                this.leave(socket, room);
+        }
+        return targets.length;
+    }
+    // ── Internals ───────────────────────────────────────────────────────
+    #matches(socket, filter) {
+        if (filter.exceptIds.has(socket.id))
+            return false;
+        const key = this.#keyOf.get(socket);
+        if (key != null && filter.exceptKeys.has(key))
+            return false;
+        if (filter.onlyKeys != null && (key == null || !filter.onlyKeys.has(key))) {
+            return false;
+        }
+        return true;
+    }
+    #topic(room) {
+        return `fx:${this.name}:r:${room}`;
+    }
+    #deliverKey(key, frame) {
+        let delivered = 0;
+        for (const socket of [...(this.#byKey.get(key) ?? [])]) {
+            if (isDelivered(socket.send(frame)))
+                delivered++;
+        }
+        return delivered;
+    }
+    #deliverAll(frame) {
+        let delivered = 0;
+        for (const socket of [...this.#keyOf.keys()]) {
+            if (isDelivered(socket.send(frame)))
+                delivered++;
+        }
+        return delivered;
+    }
+    #closeKey(key, code, reason) {
+        const sockets = [...(this.#byKey.get(key) ?? [])];
+        for (const socket of sockets)
+            socket.close(code, reason);
+        return sockets.length;
+    }
+    #onRemote(message) {
+        switch (message.kind) {
+            case "send": {
+                const frame = fromWire(message.payload);
+                if (message.key == null)
+                    this.#deliverAll(frame);
+                else
+                    this.#deliverKey(message.key, frame);
+                return;
+            }
+            case "room":
+                this._sendRoom(message.room, fromWire(message.payload), fromWireFilter(message.filter), false);
+                return;
+            case "close":
+                this.#closeKey(message.key, message.code, message.reason);
+                return;
+            case "kick":
+                this._kick(message.room, fromWireFilter(message.filter), message.reason, false);
+                return;
+            case "presence":
+                this.#extensions.get("presence")?.(message.body);
+                return;
+        }
+    }
+    #track(socket) {
+        if (this.#tracked.has(socket))
+            return;
+        this.#tracked.add(socket);
+        socket.onClose(() => {
+            this.#tracked.delete(socket);
+            this.#removeKey(socket);
+            for (const room of this.rooms(socket))
+                this.leave(socket, room);
+            this.#leaveHooks.delete(socket);
+        });
+    }
+    #removeKey(socket) {
+        const key = this.#keyOf.get(socket);
+        if (key == null)
+            return;
+        this.#keyOf.delete(socket);
+        const set = this.#byKey.get(key);
+        set?.delete(socket);
+        if (set?.size === 0)
+            this.#byKey.delete(key);
+    }
+}
+function serverOf(socket) {
+    return socket.raw.data?.server;
+}
+function isDelivered(result) {
+    return result === "sent" || result === "backpressure";
+}
+/** Text and binary frames go out as-is; everything else as JSON. */
+export function encodeFrame(data) {
+    if (typeof data === "string")
+        return data;
+    if (data instanceof Uint8Array)
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data)) {
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    }
+    return JSON.stringify(data);
+}
+function toWire(frame) {
+    return typeof frame === "string"
+        ? { text: frame }
+        : { base64: Buffer.from(frame).toString("base64") };
+}
+function fromWire(payload) {
+    if (payload.text != null)
+        return payload.text;
+    return new Uint8Array(Buffer.from(payload.base64 ?? "", "base64"));
+}

package/dist/ws/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * WebSockets for `@fishenv/http`.
+ *
+ * A ws route is an ordinary `GET` route: origin checks, middleware (auth),
+ * path-param validation and connection limits all run *before* the upgrade,
+ * so a rejected handshake is a normal HTTP error and no socket is opened.
+ *
+ * ```ts
+ * const api = withWs(r({ prefix: "/api" }).use(auth));
+ *
+ * api.ws("/echo/:room")
+ *   .maxMessageSize(16 * 1024)
+ *   .rateLimit({ messages: 20, perMs: 1000 })
+ *   .handle(({ socket, path }) => {
+ *     socket.onMessage((msg) => socket.send(`[${path.room}] ${msg.text()}`));
+ *   });
+ * ```
+ *
+ * Module layout:
+ * - `types.ts`         — shared types, close codes, error → close mapping
+ * - `message.ts`       — `WsMessage`, a lazily decoded inbound message
+ * - `connection.ts`    — `WsConnection`, a single live socket
+ * - `lifecycle.ts`     — per-socket buffering, limits and error handling
+ * - `origin.ts`        — CSWSH origin policy
+ * - `limits.ts`        — rate limiting and connection counting
+ * - `helpers.ts`       — handshake helpers
+ * - `hub.ts`           — `WsHub`, keyed registry + server-side rooms
+ * - `presence.ts`      — replicated presence (`hub.presence(topic)`)
+ * - `tickets.ts`       — `WsTickets`, single-use handshake tickets
+ * - `typed.ts`         — `TypedWsConnection` for `c.ws().messages()` contracts
+ * - `route-builder.ts` — `WsRouteBuilder`
+ * - `channels/`        — the opt-in channel protocol: `channel()`, `channels()`,
+ *                        wire format, `hub.channel(name)` targets
+ * - `router.ts`        — `withWs()` mixin
+ */
+export type { AnyChannelImpl, AnyEventFn, ChannelContext, ChannelFactory, ChannelHandlerArgs, ChannelImplDefinition, ChannelPresence, ClientEventName, EventFn, JoinFn, LeaveFn, LeaveReason, PresenceFn, ServerEventName, ServerEventPayload, } from "./channels/channel.ts";
+export { ChannelImpl, channel } from "./channels/channel.ts";
+export type { ChannelsOptions } from "./channels/handler.ts";
+export { channels } from "./channels/handler.ts";
+export type { ClientFrame, PresenceEntries, ServerFrame, WireError, } from "./channels/protocol.ts";
+export { CHANNELS_PROTOCOL, FrameError, parseClientFrame, } from "./channels/protocol.ts";
+export { channelRoom, WsChannelTarget } from "./channels/target.ts";
+export type { WsCloseListener, WsMessageListener } from "./connection.ts";
+export { WsConnection } from "./connection.ts";
+export { isWebSocketUpgrade, negotiateProtocol, requestedProtocols, UpgradeRequiredError, } from "./helpers.ts";
+export type { RoomFilter, WireFilter, WirePayload, WsHubOptions, WsHubPayload, WsTransportMessage, } from "./hub.ts";
+export { encodeFrame, WsHub, WsRoomTarget } from "./hub.ts";
+export type { LifecycleOptions, WsSetupFn } from "./lifecycle.ts";
+export { createLifecycle } from "./lifecycle.ts";
+export type { WsConnectionLimit } from "./limits.ts";
+export { ConnectionCounter, TokenBucket } from "./limits.ts";
+export { WsMessage } from "./message.ts";
+export type { OriginPolicy, OriginPredicate, OriginSource } from "./origin.ts";
+export { createOriginPolicy, originSourcesFromCors } from "./origin.ts";
+export type { PresenceDiff, PresenceEntry, PresenceOptions, PresenceState, } from "./presence.ts";
+export { PresenceLimitError, PresenceRegistry, PresenceTopic, } from "./presence.ts";
+export type { ChannelCoverage, CompleteChannelImpl, WsHandlerArgs, WsHandlerFn, WsProtocolHandler, WsRouteInfo, WsRouteOptions, WsRouterOptions, } from "./route-builder.ts";
+export { WsRouteBuilder } from "./route-builder.ts";
+export type { SocketOf, WsRouter } from "./router.ts";
+export { withWs } from "./router.ts";
+export type { TicketStore, WsTicketsOptions } from "./tickets.ts";
+export { bearerFromProtocol, MemoryTicketStore, WsTickets } from "./tickets.ts";
+export { ContractViolationError, checkOutbound, parseInbound, TypedWsConnection, } from "./typed.ts";
+export type { WsCleanupFn, WsConnectionOptions, WsRateLimit, WsSendable, WsSendResult, } from "./types.ts";
+export { closeFrameFor, MAX_CLOSE_REASON_BYTES, truncateReason, WsCloseCode, WsCloseError, WsProtocolError, } from "./types.ts";

package/dist/ws/index.js

@@ -0,0 +1,66 @@
+/**
+ * WebSockets for `@fishenv/http`.
+ *
+ * A ws route is an ordinary `GET` route: origin checks, middleware (auth),
+ * path-param validation and connection limits all run *before* the upgrade,
+ * so a rejected handshake is a normal HTTP error and no socket is opened.
+ *
+ * ```ts
+ * const api = withWs(r({ prefix: "/api" }).use(auth));
+ *
+ * api.ws("/echo/:room")
+ *   .maxMessageSize(16 * 1024)
+ *   .rateLimit({ messages: 20, perMs: 1000 })
+ *   .handle(({ socket, path }) => {
+ *     socket.onMessage((msg) => socket.send(`[${path.room}] ${msg.text()}`));
+ *   });
+ * ```
+ *
+ * Module layout:
+ * - `types.ts`         — shared types, close codes, error → close mapping
+ * - `message.ts`       — `WsMessage`, a lazily decoded inbound message
+ * - `connection.ts`    — `WsConnection`, a single live socket
+ * - `lifecycle.ts`     — per-socket buffering, limits and error handling
+ * - `origin.ts`        — CSWSH origin policy
+ * - `limits.ts`        — rate limiting and connection counting
+ * - `helpers.ts`       — handshake helpers
+ * - `hub.ts`           — `WsHub`, keyed registry + server-side rooms
+ * - `presence.ts`      — replicated presence (`hub.presence(topic)`)
+ * - `tickets.ts`       — `WsTickets`, single-use handshake tickets
+ * - `typed.ts`         — `TypedWsConnection` for `c.ws().messages()` contracts
+ * - `route-builder.ts` — `WsRouteBuilder`
+ * - `channels/`        — the opt-in channel protocol: `channel()`, `channels()`,
+ *                        wire format, `hub.channel(name)` targets
+ * - `router.ts`        — `withWs()` mixin
+ */
+// Channels (Layer 3)
+export { ChannelImpl, channel } from "./channels/channel.js";
+export { channels } from "./channels/handler.js";
+export { CHANNELS_PROTOCOL, FrameError, parseClientFrame, } from "./channels/protocol.js";
+export { channelRoom, WsChannelTarget } from "./channels/target.js";
+// Connection
+export { WsConnection } from "./connection.js";
+// Handshake helpers
+export { isWebSocketUpgrade, negotiateProtocol, requestedProtocols, UpgradeRequiredError, } from "./helpers.js";
+// Hub
+export { encodeFrame, WsHub, WsRoomTarget } from "./hub.js";
+// Lifecycle (for custom routes built on core's requestUpgrade)
+export { createLifecycle } from "./lifecycle.js";
+// Limits
+export { ConnectionCounter, TokenBucket } from "./limits.js";
+// Messages
+export { WsMessage } from "./message.js";
+// Origin policy
+export { createOriginPolicy, originSourcesFromCors } from "./origin.js";
+// Presence
+export { PresenceLimitError, PresenceRegistry, PresenceTopic, } from "./presence.js";
+// Route builder
+export { WsRouteBuilder } from "./route-builder.js";
+// Router mixin
+export { withWs } from "./router.js";
+// Tickets
+export { bearerFromProtocol, MemoryTicketStore, WsTickets } from "./tickets.js";
+// Contract-typed sockets
+export { ContractViolationError, checkOutbound, parseInbound, TypedWsConnection, } from "./typed.js";
+// Types & close codes
+export { closeFrameFor, MAX_CLOSE_REASON_BYTES, truncateReason, WsCloseCode, WsCloseError, WsProtocolError, } from "./types.js";

package/dist/ws/lifecycle.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Turns a route's `handle(fn)` into the per-socket `SocketHandlers` that core
+ * dispatches to. One lifecycle object is created per accepted handshake.
+ */
+import { type Logger, type SocketHandlers } from "../core/index.ts";
+import { WsConnection } from "./connection.ts";
+import { type WsCleanupFn, type WsConnectionOptions } from "./types.ts";
+export type WsSetupFn = (socket: WsConnection) => void | WsCleanupFn | Promise<void | WsCleanupFn>;
+export interface LifecycleOptions extends WsConnectionOptions {
+    logger?: Pick<Logger, "error">;
+    /** Called after the socket opened and before setup runs; throw to reject. */
+    onOpen?: (socket: WsConnection) => void;
+}
+/**
+ * - Messages arriving while an async setup is still running are buffered
+ *   (bounded) and replayed in order once it settles — Bun does not hold
+ *   `message` back while `open` awaits.
+ * - Size and rate limits are enforced before anything reaches user code.
+ * - Any throw/rejection closes the socket via {@link closeFrameFor}.
+ */
+export declare function createLifecycle(req: Request, protocol: string | null, setup: WsSetupFn, options?: LifecycleOptions): SocketHandlers;