@fishenv/http 0.0.0-stage → 0.0.3

package/dist/ws/channels/handler.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `channels()` — the opt-in protocol handler. A per-socket state machine
+ * that multiplexes authorized channels over one socket.
+ *
+ * Guarantees:
+ * - frames of one socket are processed **sequentially** (join → event →
+ *   leave order holds); different sockets run concurrently
+ * - nothing reaches a handler before the channel is joined and the payload
+ *   validated against the contract
+ * - repeated protocol violations close the socket with `1008`
+ */
+import { WsHub } from "../hub.ts";
+import type { WsProtocolHandler } from "../route-builder.ts";
+import type { AnyChannelImpl } from "./channel.ts";
+export interface ChannelsOptions {
+    /** Default 32. Exceeding it fails the join with `429 too_many_channels`. */
+    maxChannelsPerSocket?: number;
+    /** Protocol violations tolerated before closing with `1008`. Default 10. */
+    maxViolations?: number;
+    /** Frames queued behind a slow handler before closing with `1013`. Default 64. */
+    maxPendingFrames?: number;
+    /**
+     * Hub that backs channel membership — pass an instance or a DI token to
+     * reach channels from server code via `hub.channel(name)`. A private hub is
+     * used otherwise.
+     */
+    hub?: WsHub | (abstract new (...args: any[]) => WsHub);
+}
+/**
+ * Build the protocol handler. Prefer `.channels([...])` on a ws route,
+ * which also type-checks completeness; this form plugs into `.handleWith()`.
+ */
+export declare function channels(impls: readonly AnyChannelImpl[], options?: ChannelsOptions): WsProtocolHandler<Record<string, unknown>, Record<string, unknown>>;

package/dist/ws/channels/handler.js

@@ -0,0 +1,486 @@
+/**
+ * `channels()` — the opt-in protocol handler. A per-socket state machine
+ * that multiplexes authorized channels over one socket.
+ *
+ * Guarantees:
+ * - frames of one socket are processed **sequentially** (join → event →
+ *   leave order holds); different sockets run concurrently
+ * - nothing reaches a handler before the channel is joined and the payload
+ *   validated against the contract
+ * - repeated protocol violations close the socket with `1008`
+ */
+import * as v from "valibot";
+import { HttpError, ValidationError, validatePathParams, } from "../../core/index.js";
+import { WsHub } from "../hub.js";
+import { TokenBucket } from "../limits.js";
+import { checkOutbound } from "../typed.js";
+import { WsCloseCode, WsCloseError } from "../types.js";
+import { CHANNELS_PROTOCOL, encodeFrame, eventFrame, FrameError, parseClientFrame, } from "./protocol.js";
+import { channelRoom } from "./target.js";
+const DEFAULTS = {
+    maxChannelsPerSocket: 32,
+    maxViolations: 10,
+    maxPendingFrames: 64,
+};
+/** Errors for rejected frames, mapped onto the HTTP error vocabulary. */
+class ChannelError extends HttpError {
+    #code;
+    /** Counts towards `maxViolations`. */
+    violation;
+    constructor(status, code, message, violation = true) {
+        super(status, message);
+        this.#code = code;
+        this.violation = violation;
+    }
+    get code() {
+        return this.#code;
+    }
+}
+/**
+ * Build the protocol handler. Prefer `.channels([...])` on a ws route,
+ * which also type-checks completeness; this form plugs into `.handleWith()`.
+ */
+export function channels(impls, options = {}) {
+    const defs = impls.map((impl) => impl._definition);
+    const opts = { ...DEFAULTS, ...options };
+    const env = { development: false, logger: console };
+    let privateHub;
+    const resolveHub = (container) => {
+        const hub = options.hub;
+        if (hub instanceof WsHub)
+            return hub;
+        if (hub != null)
+            return container.get(hub);
+        privateHub ??= new WsHub({
+            name: `fishenv.channels.${crypto.randomUUID()}`,
+        });
+        return privateHub;
+    };
+    return {
+        protocols: [CHANNELS_PROTOCOL],
+        onBuild(buildEnv, route) {
+            env.development = buildEnv.development;
+            env.logger = buildEnv.logger;
+            validateImpls(defs, route);
+        },
+        setup(args) {
+            const session = new ChannelSession(args, defs, resolveHub(args.container), opts, env);
+            args.socket.onMessage((message) => session.enqueue(message.raw));
+            args.socket.onClose(() => session.disconnect());
+        },
+    };
+}
+/** Startup checks — the runtime twin of the compile-time completeness types. */
+function validateImpls(defs, route) {
+    const where = `[fishenv.ws] ${route.path}`;
+    const names = new Set();
+    for (const def of defs) {
+        const name = def.contract.name;
+        if (names.has(name))
+            throw new Error(`${where}: channel "${name}" is implemented twice`);
+        names.add(name);
+        if (def.join == null && !def.isPublic) {
+            throw new Error(`${where}: channel "${name}" has no join authorizer; add .join(fn) or .public()`);
+        }
+        for (const event of def.contract._definition.clientEvents.keys()) {
+            if (!def.events.has(event) && def.any == null) {
+                throw new Error(`${where}: channel "${name}" is missing .on("${event}")`);
+            }
+        }
+    }
+    const contract = route.contract;
+    if (contract == null)
+        return;
+    if (contract.kind !== "channels") {
+        throw new Error(`${where}: .channels() requires a c.ws().channels() contract`);
+    }
+    for (const expected of contract.channels) {
+        const def = defs.find((d) => d.contract.name === expected.name);
+        if (def == null) {
+            throw new Error(`${where}: contract channel "${expected.name}" is not implemented`);
+        }
+        if (def.contract !== expected) {
+            throw new Error(`${where}: channel "${expected.name}" implements a different contract object than the socket contract lists`);
+        }
+    }
+    for (const def of defs) {
+        if (!contract.channels.some((c) => c.name === def.contract.name)) {
+            throw new Error(`${where}: channel "${def.contract.name}" is not part of the socket contract`);
+        }
+    }
+}
+class ChannelSession {
+    #args;
+    #socket;
+    #defs;
+    #hub;
+    #opts;
+    #env;
+    #joined = new Map();
+    #presenceBuckets = new Map();
+    #chain = Promise.resolve();
+    #pending = 0;
+    #violations = 0;
+    #disconnected = false;
+    constructor(args, defs, hub, opts, env) {
+        this.#args = args;
+        this.#socket = args.socket;
+        this.#defs = defs;
+        this.#hub = hub;
+        this.#opts = opts;
+        this.#env = env;
+    }
+    // ── Scheduling ──────────────────────────────────────────────────────
+    enqueue(raw) {
+        if (this.#pending >= this.#opts.maxPendingFrames) {
+            this.#socket.close(WsCloseCode.TryAgainLater, "Too many pending frames");
+            return;
+        }
+        this.#schedule(() => this.#process(raw));
+    }
+    #schedule(task) {
+        this.#pending++;
+        this.#chain = this.#chain
+            .then(task)
+            .catch((err) => this.#env.logger.error("[fishenv.ws] channel task failed:", err))
+            .finally(() => {
+            this.#pending--;
+        });
+    }
+    // ── Frame processing ────────────────────────────────────────────────
+    async #process(raw) {
+        if (this.#socket.closed)
+            return;
+        let frame;
+        try {
+            if (typeof raw !== "string")
+                throw new FrameError("Binary frames are not supported");
+            let value;
+            try {
+                value = JSON.parse(raw);
+            }
+            catch {
+                throw new FrameError("Invalid JSON");
+            }
+            frame = parseClientFrame(value);
+        }
+        catch (err) {
+            if (!(err instanceof FrameError))
+                throw err;
+            this.#fail(err.ref, err.ch, new ChannelError(400, "bad_request", err.message));
+            return;
+        }
+        try {
+            switch (frame.t) {
+                case "join":
+                    return await this.#join(frame);
+                case "event":
+                    return await this.#event(frame);
+                case "leave":
+                    return await this.#leave(frame);
+                case "presence_update":
+                    return await this.#presenceUpdate(frame);
+            }
+        }
+        catch (err) {
+            this.#fail(frame.ref, frame.ch, err);
+        }
+    }
+    async #join(frame) {
+        if (this.#joined.has(frame.ch)) {
+            throw new ChannelError(409, "already_joined", "Channel already joined");
+        }
+        const match = this.#match(frame.ch);
+        if (match == null)
+            throw new ChannelError(404, "unknown_channel", "Unknown channel");
+        if (this.#joined.size >= this.#opts.maxChannelsPerSocket) {
+            throw new ChannelError(429, "too_many_channels", "Too many channels joined");
+        }
+        const { def, raw } = match;
+        const contract = def.contract._definition;
+        const path = validatePathParams(raw, contract.paramSchemas);
+        const data = parsePayload(contract.join.payload, frame.d);
+        const context = this.#context(def, frame.ch);
+        const args = { ...this.#base(path), data, channel: context };
+        const reply = def.join ? await def.join(args) : undefined;
+        checkOutbound(contract.join.reply, reply, this.#env.development, `join reply of "${frame.ch}"`);
+        // Resolve presence before committing, so a failing tracker aborts the join.
+        const presence = contract.presence;
+        const tracked = presence != null && def.presence != null
+            ? (await def.presence(args))
+            : null;
+        if (tracked != null) {
+            checkOutbound(presence?.meta, tracked.meta, this.#env.development, `presence meta of "${frame.ch}"`);
+        }
+        if (this.#socket.closed)
+            return;
+        const room = channelRoom(frame.ch);
+        this.#hub.join(this.#socket, room);
+        this.#hub._onLeave(this.#socket, room, (reason) => this.#schedule(() => this.#serverLeave(frame.ch, "kicked", reason)));
+        this.#joined.set(frame.ch, { impl: def, name: frame.ch, path, context });
+        this.#reply(frame.ref, reply);
+        if (presence != null) {
+            const registry = presenceFor(this.#hub);
+            if (tracked != null) {
+                registry.track(room, this.#socket, tracked.key, tracked.meta);
+            }
+            this.#send(encodeFrame({
+                t: "presence_state",
+                ch: frame.ch,
+                d: registry.list(room),
+            }));
+        }
+    }
+    async #presenceUpdate(frame) {
+        const joined = this.#joined.get(frame.ch);
+        if (joined == null)
+            throw new ChannelError(403, "not_joined", "Channel not joined");
+        const presence = joined.impl.contract._definition.presence;
+        if (presence == null || !presence.clientUpdates) {
+            throw new ChannelError(403, "forbidden", "Presence updates are not allowed on this channel");
+        }
+        const room = channelRoom(frame.ch);
+        const registry = presenceFor(this.#hub);
+        if (registry.metaOf(room, this.#socket) === undefined) {
+            throw new ChannelError(409, "not_tracked", "This socket is not tracked in presence", false);
+        }
+        const meta = parsePayload(presence.meta, frame.d);
+        let bucket = this.#presenceBuckets.get(frame.ch);
+        if (bucket == null) {
+            bucket = new TokenBucket(1, PRESENCE_UPDATE_INTERVAL_MS);
+            this.#presenceBuckets.set(frame.ch, bucket);
+        }
+        if (!bucket.take()) {
+            throw new ChannelError(429, "rate_limited", "Presence updates are rate limited", false);
+        }
+        registry.update(room, this.#socket, meta);
+        this.#reply(frame.ref, undefined);
+    }
+    async #event(frame) {
+        const joined = this.#joined.get(frame.ch);
+        if (joined == null)
+            throw new ChannelError(403, "not_joined", "Channel not joined");
+        const { impl } = joined;
+        const declared = impl.contract._definition.clientEvents.get(frame.ev);
+        const handler = impl.events.get(frame.ev);
+        let result;
+        if (declared != null && handler != null) {
+            const data = parsePayload(declared.payload, frame.d);
+            result = await handler({
+                ...this.#base(joined.path),
+                data,
+                channel: joined.context,
+            });
+            checkOutbound(declared.reply, result, this.#env.development, `reply to "${frame.ev}" on "${frame.ch}"`);
+        }
+        else if (impl.any != null) {
+            result = await impl.any({
+                ...this.#base(joined.path),
+                event: frame.ev,
+                data: frame.d,
+                channel: joined.context,
+            });
+        }
+        else {
+            throw new ChannelError(404, "unknown_event", "Unknown event");
+        }
+        this.#reply(frame.ref, result);
+    }
+    async #leave(frame) {
+        const joined = this.#joined.get(frame.ch);
+        if (joined == null)
+            throw new ChannelError(403, "not_joined", "Channel not joined");
+        this.#forget(joined);
+        await this.#runLeave(joined, "client");
+        this.#reply(frame.ref, undefined);
+    }
+    /** Kick or `channel.leave()`: tell the client, then run the leave handler. */
+    async #serverLeave(name, reason, message) {
+        const joined = this.#joined.get(name);
+        if (joined == null)
+            return;
+        this.#forget(joined);
+        this.#send(encodeFrame({ t: "close", ch: name, reason: message }));
+        await this.#runLeave(joined, reason);
+    }
+    /** Socket closed: run every leave handler once. Hub rooms clean up themselves. */
+    disconnect() {
+        if (this.#disconnected)
+            return;
+        this.#disconnected = true;
+        this.#schedule(async () => {
+            for (const joined of [...this.#joined.values()]) {
+                this.#joined.delete(joined.name);
+                await this.#runLeave(joined, "disconnect");
+            }
+        });
+    }
+    // ── Helpers ─────────────────────────────────────────────────────────
+    #forget(joined) {
+        this.#joined.delete(joined.name);
+        this.#presenceBuckets.delete(joined.name);
+        const room = channelRoom(joined.name);
+        this.#hub.leave(this.#socket, room);
+        if (joined.impl.contract._definition.presence != null) {
+            presenceFor(this.#hub).untrack(room, this.#socket);
+        }
+    }
+    async #runLeave(joined, reason) {
+        if (joined.impl.leave == null)
+            return;
+        try {
+            await joined.impl.leave({ ...this.#base(joined.path), reason });
+        }
+        catch (err) {
+            this.#env.logger.error(`[fishenv.ws] leave handler of "${joined.name}" failed:`, err);
+        }
+    }
+    #match(name) {
+        for (const def of this.#defs) {
+            const match = def.pattern.exec(`/${name}`);
+            if (match == null)
+                continue;
+            const raw = {};
+            def.paramNames.forEach((param, i) => {
+                const value = match[i + 1];
+                if (value !== undefined)
+                    raw[param] = value;
+            });
+            return { def, raw };
+        }
+        return null;
+    }
+    #base(path) {
+        const { ctx, req, container } = this.#args;
+        return { ctx, path, req, container, socket: this.#socket };
+    }
+    #context(def, name) {
+        const serverEvents = def.contract._definition.serverEvents;
+        const check = (event, payload) => {
+            if (!this.#env.development || serverEvents.size === 0)
+                return;
+            const schema = serverEvents.get(event);
+            if (schema == null) {
+                throw new Error(`"${event}" is not a server event of channel "${def.contract.name}"`);
+            }
+            checkOutbound(schema, payload, true, `serverEvent "${event}"`);
+        };
+        const target = () => this.#hub.channel(name);
+        const presenceDef = def.contract._definition.presence;
+        const room = channelRoom(name);
+        const presence = presenceDef == null
+            ? undefined
+            : {
+                update: (meta) => {
+                    checkOutbound(presenceDef.meta, meta, this.#env.development, `presence meta of "${name}"`);
+                    return presenceFor(this.#hub).update(room, this.#socket, meta);
+                },
+                list: () => presenceFor(this.#hub).list(room),
+                has: (key) => presenceFor(this.#hub).has(room, key),
+                keys: () => presenceFor(this.#hub).keys(room),
+            };
+        return {
+            name,
+            presence,
+            broadcast: (event, payload) => {
+                check(event, payload);
+                return target().send(event, payload);
+            },
+            broadcastFrom: (event, payload) => {
+                check(event, payload);
+                return target().except(this.#socket).send(event, payload);
+            },
+            push: (event, payload) => {
+                check(event, payload);
+                return this.#socket.send(eventFrame(name, event, payload));
+            },
+            leave: (reason = "") => {
+                this.#schedule(() => this.#serverLeave(name, "server", reason));
+            },
+        };
+    }
+    #reply(ref, d) {
+        if (ref === undefined)
+            return;
+        this.#send(encodeFrame(d === undefined
+            ? { t: "reply", ref, ok: true }
+            : { t: "reply", ref, ok: true, d }));
+    }
+    #fail(ref, ch, err) {
+        const wire = this.#toWire(err);
+        if (ref !== undefined) {
+            this.#send(encodeFrame({ t: "reply", ref, ok: false, err: wire }));
+        }
+        else {
+            this.#send(encodeFrame(ch ? { t: "error", ch, err: wire } : { t: "error", err: wire }));
+        }
+        const violation = (err instanceof ChannelError && err.violation) ||
+            err instanceof ValidationError;
+        if (violation && ++this.#violations >= this.#opts.maxViolations) {
+            this.#socket.close(WsCloseCode.PolicyViolation, "Too many protocol violations");
+        }
+    }
+    #toWire(err) {
+        if (err instanceof WsCloseError) {
+            // A handler asked for the whole socket to go away.
+            this.#socket.close(err.code, err.message);
+        }
+        if (err instanceof HttpError)
+            return err.toJSON(this.#env.development);
+        this.#env.logger.error("[fishenv.ws] channel handler failed:", err);
+        const wire = {
+            status: 500,
+            code: "internal",
+            message: "Internal Server Error",
+        };
+        if (this.#env.development && err instanceof Error) {
+            wire.message = err.message;
+            wire.stack = err.stack;
+        }
+        return wire;
+    }
+    #send(frame) {
+        this.#socket.send(frame);
+    }
+}
+/** Client presence updates allowed per channel per socket: one per second. */
+const PRESENCE_UPDATE_INTERVAL_MS = 1_000;
+const CHANNEL_ROOM_PREFIX = channelRoom("");
+const fanOutInstalled = new WeakSet();
+const LOCAL_ONLY = {
+    exceptIds: new Set(),
+    exceptKeys: new Set(),
+    onlyKeys: null,
+};
+/**
+ * The hub's presence registry, with presence diffs of channel topics fanned
+ * out to the channel's *local* members — every node derives the same diffs
+ * from replicated state, so nothing is re-published over the transport.
+ */
+function presenceFor(hub) {
+    const registry = hub._presenceRegistry();
+    if (!fanOutInstalled.has(hub)) {
+        fanOutInstalled.add(hub);
+        registry.onDiff((topic, diff) => {
+            if (!topic.startsWith(CHANNEL_ROOM_PREFIX))
+                return;
+            const ch = topic.slice(CHANNEL_ROOM_PREFIX.length);
+            hub._sendRoom(topic, encodeFrame({
+                t: "presence_diff",
+                ch,
+                joins: diff.joins,
+                leaves: diff.leaves,
+            }), LOCAL_ONLY, false);
+        });
+    }
+    return registry;
+}
+/** Validate a client payload; no schema means the payload is ignored. */
+function parsePayload(schema, value) {
+    if (schema == null)
+        return undefined;
+    const result = v.safeParse(schema, value);
+    if (!result.success)
+        throw new ValidationError("body", result.issues);
+    return result.output;
+}

package/dist/ws/channels/protocol.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Wire protocol `fishenv.channels.v1` — JSON text frames.
+ *
+ * Client → server:
+ *   { t: "join",  ref?, ch, d? }
+ *   { t: "event", ref?, ch, ev, d? }
+ *   { t: "leave", ref?, ch }
+ *   { t: "presence_update", ref?, ch, d }
+ *
+ * Server → client:
+ *   { t: "reply", ref, ok: true, d? } | { t: "reply", ref, ok: false, err }
+ *   { t: "event", ch, ev, d }            — `seq` is reserved for replay
+ *   { t: "close", ch, reason }           — server-initiated leave
+ *   { t: "error", ch?, err }             — failure of a frame without `ref`
+ *   { t: "presence_state", ch, d }
+ *   { t: "presence_diff", ch, joins, leaves }
+ *
+ * Parsing reads only known keys and never merges client objects into
+ * server state, so `__proto__` & co. are inert.
+ */
+import type { HttpErrorJSON } from "../../core/index.ts";
+export { CHANNELS_PROTOCOL } from "../../contract/index.ts";
+export declare const MAX_CHANNEL_NAME_LENGTH = 256;
+export declare const MAX_EVENT_NAME_LENGTH = 128;
+export declare const MAX_REF: number;
+export type ClientFrame = {
+    t: "join";
+    ref?: number;
+    ch: string;
+    d?: unknown;
+} | {
+    t: "event";
+    ref?: number;
+    ch: string;
+    ev: string;
+    d?: unknown;
+} | {
+    t: "leave";
+    ref?: number;
+    ch: string;
+} | {
+    t: "presence_update";
+    ref?: number;
+    ch: string;
+    d?: unknown;
+};
+/** Public error payload; same shape as `HttpError.toJSON()` minus nothing. */
+export type WireError = Pick<HttpErrorJSON, "status" | "code" | "message"> & Partial<Pick<HttpErrorJSON, "details" | "stack">>;
+export type PresenceEntries = Record<string, {
+    ref: string;
+    meta: unknown;
+}[]>;
+export type ServerFrame = {
+    t: "reply";
+    ref: number;
+    ok: true;
+    d?: unknown;
+} | {
+    t: "reply";
+    ref: number;
+    ok: false;
+    err: WireError;
+} | {
+    t: "event";
+    ch: string;
+    ev: string;
+    d: unknown;
+    seq?: number;
+} | {
+    t: "close";
+    ch: string;
+    reason: string;
+} | {
+    t: "error";
+    ch?: string;
+    err: WireError;
+} | {
+    t: "presence_state";
+    ch: string;
+    d: PresenceEntries;
+} | {
+    t: "presence_diff";
+    ch: string;
+    joins: PresenceEntries;
+    leaves: PresenceEntries;
+};
+/** Why a frame was rejected; `ref` is recovered when possible for the reply. */
+export declare class FrameError extends Error {
+    readonly ref?: number;
+    readonly ch?: string;
+    constructor(message: string, ref?: number, ch?: string);
+}
+/** Validate an already-JSON-parsed client frame. Throws {@link FrameError}. */
+export declare function parseClientFrame(value: unknown): ClientFrame;
+export declare function encodeFrame(frame: ServerFrame): string;
+export declare function eventFrame(ch: string, ev: string, d: unknown): string;