@fishenv/http 0.0.2 → 0.0.4

package/dist/ws/presence.js

@@ -0,0 +1,420 @@
+/**
+ * Presence — *who* is in a topic (a channel, or any app-defined topic like
+ * `"online-users"`), keyed by identity rather than by socket, replicated
+ * across nodes.
+ *
+ * Model: an entry is `(key, ref, meta)` — `key` is the identity (user id),
+ * `ref` the connection id, `meta` app data. Three tabs = one key, three refs;
+ * closing one tab is not a "leave" of the user.
+ *
+ * Replication is single-writer: every entry is owned by the node holding its
+ * socket and only that node writes it, so state is conflict-free without a
+ * merge CRDT. Each node stamps its messages with a per-node clock; a gap or
+ * an unknown node triggers a full `sync` from the owner. Nodes heartbeat;
+ * a silent node is declared dead and its entries are dropped.
+ */
+export class PresenceLimitError extends Error {
+    constructor(topic) {
+        super(`Presence topic "${topic}" is full`);
+        this.name = "PresenceLimitError";
+    }
+}
+/**
+ * Per-hub presence state. Get it via `hub.presence(topic)` — you rarely
+ * construct this directly.
+ */
+export class PresenceRegistry {
+    #hub;
+    #opts;
+    #now;
+    #setTimer;
+    #clearTimer;
+    #setInterval;
+    #clearInterval;
+    #local = new Map();
+    #sockets = new Map();
+    #peers = new Map();
+    #listeners = new Set();
+    #pending = new Map();
+    #flushTimer;
+    #clock = 0;
+    #intervals = [];
+    #replicated;
+    constructor(hub, replicated, options = {}) {
+        this.#hub = hub;
+        this.#replicated = replicated;
+        this.#opts = {
+            batchMs: options.batchMs ?? 50,
+            heartbeatMs: options.heartbeatMs ?? 5_000,
+            peerTimeoutMs: options.peerTimeoutMs ?? 15_000,
+            maxEntriesPerTopic: options.maxEntriesPerTopic ?? 10_000,
+        };
+        this.#now = options.now ?? Date.now;
+        this.#setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.#clearTimer = options.clearTimer ?? ((h) => clearTimeout(h));
+        this.#setInterval =
+            options.setInterval ??
+                ((fn, ms) => {
+                    const handle = setInterval(fn, ms);
+                    handle.unref?.();
+                    return handle;
+                });
+        this.#clearInterval =
+            options.clearInterval ?? ((h) => clearInterval(h));
+        if (replicated) {
+            hub._registerExtension("presence", (body) => this.#onRemote(body));
+            this.#intervals.push(this.#setInterval(() => this.#heartbeat(), this.#opts.heartbeatMs), this.#setInterval(() => this.#sweep(), this.#opts.heartbeatMs));
+            // Ask everyone for their current entries.
+            this.#publish({
+                op: "sync_request",
+                node: this.#hub.nodeId,
+                target: "*",
+            });
+        }
+    }
+    // ── Local writes ────────────────────────────────────────────────────
+    /**
+     * Track `socket` in `topic` under `key`. Re-tracking replaces the meta.
+     * Untracked automatically when the socket closes.
+     */
+    track(topic, socket, key, meta) {
+        if (socket.closed)
+            return;
+        let entries = this.#local.get(topic);
+        if (entries == null) {
+            entries = new Map();
+            this.#local.set(topic, entries);
+        }
+        const previous = entries.get(socket.id);
+        if (previous == null && entries.size >= this.#opts.maxEntriesPerTopic) {
+            throw new PresenceLimitError(topic);
+        }
+        const stored = { key, meta };
+        entries.set(socket.id, stored);
+        if (!this.#sockets.has(socket.id)) {
+            this.#sockets.set(socket.id, socket);
+            socket.onClose(() => this.#untrackSocket(socket));
+        }
+        const leaves = previous ? { [socket.id]: previous } : {};
+        this.#queue(topic, { [socket.id]: stored }, leaves);
+        this.#publishDiff(topic, { [socket.id]: stored }, previous ? [socket.id] : []);
+    }
+    /** Replace the meta of an already tracked socket. No-op if untracked. */
+    update(topic, socket, meta) {
+        const current = this.#local.get(topic)?.get(socket.id);
+        if (current == null)
+            return false;
+        this.track(topic, socket, current.key, meta);
+        return true;
+    }
+    untrack(topic, socket) {
+        const entries = this.#local.get(topic);
+        const previous = entries?.get(socket.id);
+        if (entries == null || previous == null)
+            return;
+        entries.delete(socket.id);
+        if (entries.size === 0)
+            this.#local.delete(topic);
+        this.#queue(topic, {}, { [socket.id]: previous });
+        this.#publishDiff(topic, {}, [socket.id]);
+    }
+    // ── Reads (cluster-wide) ────────────────────────────────────────────
+    list(topic) {
+        const state = {};
+        const add = (entries) => {
+            for (const [ref, { key, meta }] of entries ?? []) {
+                addEntry(state, key, ref, meta);
+            }
+        };
+        add(this.#local.get(topic));
+        for (const peer of this.#peers.values())
+            add(peer.topics.get(topic));
+        return state;
+    }
+    has(topic, key) {
+        return this.list(topic)[key] != null;
+    }
+    keys(topic) {
+        return Object.keys(this.list(topic));
+    }
+    /** Tracked meta of a local socket. */
+    metaOf(topic, socket) {
+        return this.#local.get(topic)?.get(socket.id)?.meta;
+    }
+    /** Topics with at least one entry anywhere. */
+    topics() {
+        const all = new Set(this.#local.keys());
+        for (const peer of this.#peers.values()) {
+            for (const topic of peer.topics.keys())
+                all.add(topic);
+        }
+        return [...all];
+    }
+    /** Coalesced diffs for every topic (local and remote changes). */
+    onDiff(fn) {
+        this.#listeners.add(fn);
+        return () => this.#listeners.delete(fn);
+    }
+    /** Stop timers and drop remote state (e.g. on shutdown). */
+    close() {
+        for (const handle of this.#intervals)
+            this.#clearInterval(handle);
+        this.#intervals = [];
+        if (this.#flushTimer != null)
+            this.#clearTimer(this.#flushTimer);
+        this.#flushTimer = undefined;
+        this.#replicated = false;
+    }
+    // ── Batching ────────────────────────────────────────────────────────
+    #queue(topic, joins, leaves) {
+        let pending = this.#pending.get(topic);
+        if (pending == null) {
+            pending = { joins: new Map(), leaves: new Map() };
+            this.#pending.set(topic, pending);
+        }
+        for (const [ref, entry] of Object.entries(leaves)) {
+            if (pending.joins.has(ref)) {
+                // Joined within this window, so clients never saw that version. If
+                // they saw an older one, its leave is already queued.
+                pending.joins.delete(ref);
+                continue;
+            }
+            if (!pending.leaves.has(ref))
+                pending.leaves.set(ref, entry);
+        }
+        for (const [ref, entry] of Object.entries(joins))
+            pending.joins.set(ref, entry);
+        this.#flushTimer ??= this.#setTimer(() => this.flush(), this.#opts.batchMs);
+    }
+    /** Emit pending diffs now. Called automatically after `batchMs`. */
+    flush() {
+        if (this.#flushTimer != null)
+            this.#clearTimer(this.#flushTimer);
+        this.#flushTimer = undefined;
+        const pending = [...this.#pending];
+        this.#pending.clear();
+        for (const [topic, { joins, leaves }] of pending) {
+            if (joins.size === 0 && leaves.size === 0)
+                continue;
+            const diff = { joins: group(joins), leaves: group(leaves) };
+            for (const fn of [...this.#listeners]) {
+                try {
+                    fn(topic, diff);
+                }
+                catch (err) {
+                    console.error("[fishenv.ws] presence listener failed:", err);
+                }
+            }
+        }
+    }
+    // ── Replication ─────────────────────────────────────────────────────
+    #publish(message) {
+        if (this.#replicated)
+            this.#hub._publishExtension("presence", message);
+    }
+    #tick() {
+        return ++this.#clock;
+    }
+    #publishDiff(topic, joins, leaves) {
+        if (!this.#replicated)
+            return;
+        this.#publish({
+            op: "diff",
+            node: this.#hub.nodeId,
+            clock: this.#tick(),
+            topic,
+            joins,
+            leaves,
+        });
+    }
+    #heartbeat() {
+        this.#publish({
+            op: "heartbeat",
+            node: this.#hub.nodeId,
+            clock: this.#tick(),
+        });
+    }
+    /** Drop peers that stopped heart-beating (crashed or partitioned nodes). */
+    #sweep() {
+        const deadline = this.#now() - this.#opts.peerTimeoutMs;
+        for (const [node, peer] of [...this.#peers]) {
+            if (peer.lastSeen >= deadline)
+                continue;
+            this.#peers.delete(node);
+            for (const [topic, entries] of peer.topics) {
+                this.#queue(topic, {}, Object.fromEntries(entries));
+            }
+        }
+    }
+    #onRemote(message) {
+        if (message == null || typeof message !== "object")
+            return;
+        if (message.node === this.#hub.nodeId)
+            return;
+        if (message.op === "sync_request") {
+            if (message.target === "*" || message.target === this.#hub.nodeId) {
+                this.#sendSync(message.node);
+            }
+            return;
+        }
+        let peer = this.#peers.get(message.node);
+        const isNew = peer == null;
+        if (peer == null) {
+            peer = {
+                clock: 0,
+                lastSeen: this.#now(),
+                syncing: false,
+                topics: new Map(),
+            };
+            this.#peers.set(message.node, peer);
+        }
+        peer.lastSeen = this.#now();
+        if (message.op === "sync") {
+            if (message.to === this.#hub.nodeId)
+                this.#applySync(peer, message);
+            else if (!peer.syncing)
+                this.#advance(message.node, peer, message.clock, isNew);
+            return;
+        }
+        if (peer.syncing)
+            return; // the snapshot will contain it
+        if (!this.#advance(message.node, peer, message.clock, isNew))
+            return;
+        if (message.op === "diff")
+            this.#applyDiff(peer, message);
+    }
+    /** Check clock continuity; on a gap request a full sync. */
+    #advance(node, peer, clock, isNew) {
+        if (clock === peer.clock + 1 || (isNew && clock === 1)) {
+            peer.clock = clock;
+            return true;
+        }
+        if (clock <= peer.clock)
+            return false; // duplicate / reordered — ignore
+        peer.syncing = true;
+        this.#publish({ op: "sync_request", node: this.#hub.nodeId, target: node });
+        return false;
+    }
+    #applyDiff(peer, message) {
+        let entries = peer.topics.get(message.topic);
+        if (entries == null) {
+            entries = new Map();
+            peer.topics.set(message.topic, entries);
+        }
+        const leaves = {};
+        for (const ref of message.leaves) {
+            const previous = entries.get(ref);
+            if (previous == null)
+                continue;
+            entries.delete(ref);
+            leaves[ref] = previous;
+        }
+        for (const [ref, entry] of Object.entries(message.joins))
+            entries.set(ref, entry);
+        if (entries.size === 0)
+            peer.topics.delete(message.topic);
+        this.#queue(message.topic, message.joins, leaves);
+    }
+    #sendSync(to) {
+        const topics = {};
+        for (const [topic, entries] of this.#local)
+            topics[topic] = Object.fromEntries(entries);
+        this.#publish({
+            op: "sync",
+            node: this.#hub.nodeId,
+            clock: this.#tick(),
+            to,
+            topics,
+        });
+    }
+    /** Replace a peer's state with its snapshot and emit the difference. */
+    #applySync(peer, message) {
+        const previous = peer.topics;
+        const next = new Map();
+        for (const [topic, entries] of Object.entries(message.topics)) {
+            next.set(topic, new Map(Object.entries(entries)));
+        }
+        const allTopics = new Set([...previous.keys(), ...next.keys()]);
+        for (const topic of allTopics) {
+            const before = previous.get(topic) ?? new Map();
+            const after = next.get(topic) ?? new Map();
+            const joins = {};
+            const leaves = {};
+            for (const [ref, entry] of before) {
+                const now = after.get(ref);
+                if (now == null || !sameEntry(now, entry))
+                    leaves[ref] = entry;
+            }
+            for (const [ref, entry] of after) {
+                const was = before.get(ref);
+                if (was == null || !sameEntry(was, entry))
+                    joins[ref] = entry;
+            }
+            this.#queue(topic, joins, leaves);
+        }
+        peer.topics = next;
+        peer.clock = message.clock;
+        peer.syncing = false;
+    }
+    #untrackSocket(socket) {
+        this.#sockets.delete(socket.id);
+        for (const topic of [...this.#local.keys()])
+            this.untrack(topic, socket);
+    }
+}
+function addEntry(state, key, ref, meta) {
+    const list = state[key];
+    if (list == null)
+        state[key] = [{ ref, meta }];
+    else
+        list.push({ ref, meta });
+}
+function sameEntry(a, b) {
+    return a.key === b.key && JSON.stringify(a.meta) === JSON.stringify(b.meta);
+}
+function group(entries) {
+    const state = {};
+    for (const [ref, { key, meta }] of entries)
+        addEntry(state, key, ref, meta);
+    return state;
+}
+/** A read/write view of one topic, from `hub.presence(topic)`. */
+export class PresenceTopic {
+    topic;
+    #registry;
+    /** @internal */
+    constructor(registry, topic) {
+        this.#registry = registry;
+        this.topic = topic;
+    }
+    track(socket, key, meta) {
+        this.#registry.track(this.topic, socket, key, meta);
+    }
+    update(socket, meta) {
+        return this.#registry.update(this.topic, socket, meta);
+    }
+    untrack(socket) {
+        this.#registry.untrack(this.topic, socket);
+    }
+    /** Cluster-wide: `{ [key]: { ref, meta }[] }`. */
+    list() {
+        return this.#registry.list(this.topic);
+    }
+    has(key) {
+        return this.#registry.has(this.topic, key);
+    }
+    keys() {
+        return this.#registry.keys(this.topic);
+    }
+    /** Number of distinct keys (users), cluster-wide. */
+    count() {
+        return this.keys().length;
+    }
+    /** Coalesced diffs of this topic. */
+    onDiff(fn) {
+        return this.#registry.onDiff((topic, diff) => {
+            if (topic === this.topic)
+                fn(diff);
+        });
+    }
+}

package/dist/ws/route-builder.d.ts

@@ -0,0 +1,136 @@
+/** Fluent builder for WebSocket routes, layered on the core `RouteBuilder`. */
+import type { AnyChannelContract, WsContract, WsContractDefinition } from "../contract/index.ts";
+import { type AnySchema, type BuildEnv, type DIContainer, type FinishedRoute, type InputOptions, type MergeParam, type MiddlewareFn, type RouteBuilder, type RouteMeta } from "../core/index.ts";
+import { type ChannelFactory, type ChannelImplDefinition } from "./channels/channel.ts";
+import { type ChannelsOptions } from "./channels/handler.ts";
+import type { WsConnection } from "./connection.ts";
+import type { WsHub } from "./hub.ts";
+import { type WsConnectionLimit } from "./limits.ts";
+import { type OriginSource } from "./origin.ts";
+import { type WsCleanupFn, type WsRateLimit } from "./types.ts";
+export interface WsHandlerArgs<Ctx extends Record<string, unknown>, Params extends Record<string, unknown>, Socket = WsConnection> {
+    /** `TypedWsConnection` on `c.ws().messages()` contract routes. */
+    socket: Socket;
+    path: Params;
+    ctx: Ctx;
+    /** The upgrade request. */
+    req: Request;
+    container: DIContainer;
+}
+export type WsHandlerFn<Ctx extends Record<string, unknown>, Params extends Record<string, unknown>, Socket = WsConnection> = (args: WsHandlerArgs<Ctx, Params, Socket>) => void | WsCleanupFn | Promise<void | WsCleanupFn>;
+/** What a protocol handler learns about the route it is mounted on. */
+export interface WsRouteInfo {
+    /** Full path including router prefixes. */
+    path: string;
+    contract?: WsContractDefinition;
+}
+/**
+ * A reusable protocol implementation (channels, JSON-RPC, …) that plugs into
+ * `.handleWith()` exactly like the built-in `channels()` handler.
+ */
+export interface WsProtocolHandler<Ctx extends Record<string, unknown>, Params extends Record<string, unknown>> {
+    /** Subprotocols this handler speaks, in preference order. */
+    readonly protocols?: readonly string[];
+    readonly setup: WsHandlerFn<Ctx, Params>;
+    /** Startup validation hook (e.g. completeness checks). */
+    onBuild?(env: BuildEnv, route: WsRouteInfo): void;
+}
+/** Router-level defaults set via `withWs(router, options)`. */
+export interface WsRouterOptions {
+    /** Origin sources added to every ws route on this router. */
+    origins?: OriginSource[];
+}
+/** Mutable per-route configuration, copied when a builder is re-created. */
+export interface WsRouteOptions {
+    routerOrigins: OriginSource[];
+    origins: OriginSource[];
+    inheritOrigins: boolean;
+    protocols?: readonly string[];
+    maxMessageSize?: number;
+    rateLimit?: WsRateLimit;
+    maxQueuedMessages?: number;
+    maxConnections?: WsConnectionLimit<any>;
+    /** Set for routes created from a `c.ws()` contract. */
+    contract?: WsContractDefinition;
+}
+type Inner<RouterCtx extends Record<string, unknown>, RouteCtx extends Record<string, unknown>, Params extends Record<string, unknown>> = RouteBuilder<RouterCtx, RouteCtx, "none", InputOptions<"none">, Params, undefined>;
+/**
+ * A channel implementation that `.channels()` accepts for a given ctx.
+ * Only the phantom members are compared, so the check is exactly: "is it
+ * complete?" and "does the route's ctx satisfy what the handlers need?".
+ */
+export interface CompleteChannelImpl<Ctx> {
+    readonly _ctx?: (ctx: Ctx) => void;
+    readonly _status?: "complete";
+    readonly contract: AnyChannelContract;
+    readonly _definition: ChannelImplDefinition;
+}
+type ImplNames<Impls extends readonly unknown[]> = Impls[number] extends infer I ? I extends {
+    readonly contract: {
+        readonly name: infer N;
+    };
+} ? N : never : never;
+type ContractNames<K> = K extends WsContract<any, any, "channels", infer Cs, any, any> ? Cs extends readonly AnyChannelContract[] ? Cs[number]["name"] : never : never;
+/** `unknown` when the implementations match the socket contract; a named error otherwise. */
+export type ChannelCoverage<Impls extends readonly unknown[], K> = [K] extends [
+    undefined
+] ? unknown : [Exclude<ContractNames<K>, ImplNames<Impls>>] extends [never] ? [Exclude<ImplNames<Impls>, ContractNames<K>>] extends [never] ? unknown : {
+    __channelNotInContract: Exclude<ImplNames<Impls>, ContractNames<K>>;
+} : {
+    __missingChannel: Exclude<ContractNames<K>, ImplNames<Impls>>;
+};
+/**
+ * Delegates to the core `RouteBuilder`, so `.param()` / `.with()` carry
+ * exactly the same generics as HTTP and SSE routes.
+ *
+ * Handshake order: origin → upgrade headers (426) → subprotocol →
+ * middleware → path params → connection limits → upgrade.
+ */
+export declare class WsRouteBuilder<RouterCtx extends Record<string, unknown>, RouteCtx extends Record<string, unknown>, Params extends Record<string, unknown>, Socket = WsConnection, Contract = undefined> {
+    #private;
+    constructor(inner: Inner<RouterCtx, RouteCtx, Params>, options?: Partial<WsRouteOptions>);
+    meta(data: RouteMeta): this;
+    /**
+     * Add allowed origins on top of the inherited ones (root `cors()` and
+     * `withWs()` options). Pass `{ inherit: false }` to replace them instead.
+     */
+    origin(...args: [...OriginSource[], {
+        inherit?: boolean;
+    }] | OriginSource[]): this;
+    /** Supported subprotocols in preference order; others get `400`. */
+    protocols(list: readonly string[]): this;
+    /** Per-route inbound limit (closes with `1009`). Must be ≤ the server-wide limit. */
+    maxMessageSize(bytes: number): this;
+    /** Inbound token bucket per connection. Opt-in. */
+    rateLimit(limit: WsRateLimit): this;
+    /** Cap open sockets on this route (`503`) and/or per key (`429`). */
+    maxConnections(limit: WsConnectionLimit<Omit<WsHandlerArgs<RouterCtx & RouteCtx, Params, Socket>, "socket">>): this;
+    /** Not available on contract routes — the contract owns the params. */
+    param<Name extends string & keyof Params, S extends AnySchema>(name: Name, schema: S): WsRouteBuilder<RouterCtx, RouteCtx, MergeParam<Params, Name, S>, Socket, Contract>;
+    with<NewCtx extends Record<string, unknown>>(mw: MiddlewareFn<RouterCtx & RouteCtx, NewCtx>): WsRouteBuilder<RouterCtx, RouteCtx & NewCtx, Params, Socket, Contract>;
+    /**
+     * Terminal: serve the channel protocol. Every implementation must be
+     * complete (all client events handled, join authorized or `.public()`),
+     * and on contract routes the set must match the socket contract exactly.
+     *
+     * Pass a callback to get a `channel` factory typed with this route's ctx:
+     * `.channels((channel) => [channel(room).join(({ ctx }) => …)])`.
+     */
+    channels<const Impls extends readonly CompleteChannelImpl<RouterCtx & RouteCtx>[]>(impls: (Impls & ChannelCoverage<Impls, Contract>) | ((channel: ChannelFactory<RouterCtx & RouteCtx>) => Impls & ChannelCoverage<Impls, Contract>), options?: ChannelsOptions): FinishedRoute;
+    /** Terminal: plug in a reusable protocol handler (see `channels()`). */
+    handleWith(handler: WsProtocolHandler<RouterCtx & RouteCtx, Params>): FinishedRoute;
+    /**
+     * Terminal shorthand: resolve a hub from the container and register the
+     * socket under the key derived from the handshake (e.g. the user id).
+     */
+    subscribe<H extends WsHub>(token: abstract new (...args: any[]) => H, key: (args: WsHandlerArgs<RouterCtx & RouteCtx, Params, Socket>) => string): FinishedRoute;
+    /**
+     * Terminal. Runs once per socket, after the upgrade. The returned function
+     * (if any) runs when the socket closes.
+     *
+     * `.catch()` on the result only covers failures *before* the upgrade
+     * (origin, middleware, params) — after that, errors close the socket.
+     */
+    handle(fn: WsHandlerFn<RouterCtx & RouteCtx, Params, Socket>): FinishedRoute;
+}
+export {};