@fishenv/http 0.0.2 → 0.0.4

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;

package/dist/ws/lifecycle.js

@@ -0,0 +1,97 @@
+/**
+ * Turns a route's `handle(fn)` into the per-socket `SocketHandlers` that core
+ * dispatches to. One lifecycle object is created per accepted handshake.
+ */
+import { HttpError, } from "../core/index.js";
+import { runCallback, WsConnection } from "./connection.js";
+import { TokenBucket } from "./limits.js";
+import { WsMessage } from "./message.js";
+import { closeFrameFor, DEFAULT_MAX_QUEUED_MESSAGES, WsCloseCode, WsCloseError, } from "./types.js";
+/**
+ * - 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 function createLifecycle(req, protocol, setup, options = {}) {
+    const logger = options.logger ?? console;
+    const maxQueued = options.maxQueuedMessages ?? DEFAULT_MAX_QUEUED_MESSAGES;
+    const limiter = options.rateLimit
+        ? new TokenBucket(options.rateLimit.messages, options.rateLimit.perMs)
+        : null;
+    let socket;
+    let ready = false;
+    const queue = [];
+    const fail = (err) => {
+        if (!(err instanceof WsCloseError || err instanceof HttpError)) {
+            logger.error("[fishenv.ws] handler failed:", err);
+        }
+        const frame = closeFrameFor(err, options.development);
+        socket?.close(frame.code, frame.reason);
+    };
+    const flush = () => {
+        ready = true;
+        while (socket != null && !socket.closed && queue.length > 0) {
+            socket._deliver(queue.shift());
+        }
+        queue.length = 0;
+    };
+    return {
+        open(ws) {
+            const conn = new WsConnection(ws, req, protocol, fail);
+            socket = conn;
+            let result;
+            try {
+                options.onOpen?.(conn);
+                result = setup(conn);
+            }
+            catch (err) {
+                fail(err);
+                return;
+            }
+            const settle = (cleanup) => {
+                if (typeof cleanup === "function")
+                    conn.onClose(cleanup);
+                flush();
+            };
+            if (result instanceof Promise)
+                result.then(settle, fail);
+            else
+                settle(result);
+        },
+        message(_ws, raw) {
+            if (socket == null || socket.closed)
+                return;
+            const message = new WsMessage(raw);
+            if (options.maxMessageSize != null &&
+                message.size > options.maxMessageSize) {
+                socket.close(WsCloseCode.MessageTooBig, "Message too big");
+                return;
+            }
+            if (limiter != null && !limiter.take()) {
+                if (options.rateLimit?.onExceed === "drop")
+                    return;
+                socket.close(WsCloseCode.PolicyViolation, "Rate limit exceeded");
+                return;
+            }
+            if (!ready) {
+                if (queue.length >= maxQueued) {
+                    socket.close(WsCloseCode.PolicyViolation, "Too many queued messages");
+                    return;
+                }
+                queue.push(message);
+                return;
+            }
+            socket._deliver(message);
+        },
+        close(_ws, code, reason) {
+            queue.length = 0;
+            socket?._closed(code, reason);
+        },
+        drain() {
+            if (socket != null)
+                runCallback(() => socket?._drained(), fail);
+        },
+    };
+}

package/dist/ws/limits.d.ts

@@ -0,0 +1,32 @@
+/** Per-connection rate limiting and per-route connection counting. */
+/**
+ * Classic token bucket: `capacity` tokens, refilled continuously at
+ * `capacity / perMs`. Allows short bursts up to `capacity`.
+ */
+export declare class TokenBucket {
+    #private;
+    constructor(capacity: number, perMs: number, now?: () => number);
+    /** Consume one token; `false` if the bucket is empty. */
+    take(): boolean;
+}
+export interface WsConnectionLimit<A> {
+    /** Max open sockets on this route. Rejected with `503`. */
+    total?: number;
+    /** Max open sockets per key (e.g. user id). Rejected with `429`. */
+    perKey?: {
+        key: (args: A) => string;
+        max: number;
+    };
+}
+/**
+ * Open-socket counters for one route. Checked before the upgrade (cheap
+ * rejection) and re-checked on open, because concurrent handshakes can both
+ * pass the first check — counting only real opens means nothing can leak.
+ */
+export declare class ConnectionCounter {
+    #private;
+    get total(): number;
+    count(key: string): number;
+    /** Register an open socket; returns the release fn (idempotent). */
+    acquire(key: string | null): () => void;
+}

package/dist/ws/limits.js

@@ -0,0 +1,67 @@
+/** Per-connection rate limiting and per-route connection counting. */
+/**
+ * Classic token bucket: `capacity` tokens, refilled continuously at
+ * `capacity / perMs`. Allows short bursts up to `capacity`.
+ */
+export class TokenBucket {
+    #capacity;
+    #ratePerMs;
+    #now;
+    #tokens;
+    #last;
+    constructor(capacity, perMs, now = () => performance.now()) {
+        if (!(capacity > 0) || !(perMs > 0)) {
+            throw new Error("rateLimit: messages and perMs must be positive");
+        }
+        this.#capacity = capacity;
+        this.#ratePerMs = capacity / perMs;
+        this.#now = now;
+        this.#tokens = capacity;
+        this.#last = now();
+    }
+    /** Consume one token; `false` if the bucket is empty. */
+    take() {
+        const now = this.#now();
+        this.#tokens = Math.min(this.#capacity, this.#tokens + (now - this.#last) * this.#ratePerMs);
+        this.#last = now;
+        if (this.#tokens < 1)
+            return false;
+        this.#tokens -= 1;
+        return true;
+    }
+}
+/**
+ * Open-socket counters for one route. Checked before the upgrade (cheap
+ * rejection) and re-checked on open, because concurrent handshakes can both
+ * pass the first check — counting only real opens means nothing can leak.
+ */
+export class ConnectionCounter {
+    #total = 0;
+    #byKey = new Map();
+    get total() {
+        return this.#total;
+    }
+    count(key) {
+        return this.#byKey.get(key) ?? 0;
+    }
+    /** Register an open socket; returns the release fn (idempotent). */
+    acquire(key) {
+        this.#total++;
+        if (key != null)
+            this.#byKey.set(key, this.count(key) + 1);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.#total--;
+            if (key == null)
+                return;
+            const next = this.count(key) - 1;
+            if (next <= 0)
+                this.#byKey.delete(key);
+            else
+                this.#byKey.set(key, next);
+        };
+    }
+}

package/dist/ws/message.d.ts

@@ -0,0 +1,19 @@
+/** A lazily decoded inbound WebSocket message. */
+/**
+ * Bun delivers text frames as `string` and binary frames as `Buffer`; this
+ * wraps both without forcing a decode until the handler asks for one.
+ */
+export declare class WsMessage {
+    #private;
+    constructor(raw: string | Uint8Array);
+    get isBinary(): boolean;
+    /** Size in bytes (UTF-8 for text frames). */
+    get size(): number;
+    /** The original value Bun delivered. */
+    get raw(): string | Uint8Array;
+    /** Text content. Binary frames must hold valid UTF-8. */
+    text(): string;
+    bytes(): Uint8Array;
+    /** Parse as JSON; malformed input throws a {@link WsProtocolError} (→ `1008`). */
+    json<T = unknown>(): T;
+}

package/dist/ws/message.js

@@ -0,0 +1,58 @@
+/** A lazily decoded inbound WebSocket message. */
+import { WsProtocolError } from "./types.js";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+/**
+ * Bun delivers text frames as `string` and binary frames as `Buffer`; this
+ * wraps both without forcing a decode until the handler asks for one.
+ */
+export class WsMessage {
+    #raw;
+    #size;
+    constructor(raw) {
+        this.#raw = raw;
+    }
+    get isBinary() {
+        return typeof this.#raw !== "string";
+    }
+    /** Size in bytes (UTF-8 for text frames). */
+    get size() {
+        if (this.#size == null) {
+            this.#size =
+                typeof this.#raw === "string"
+                    ? Buffer.byteLength(this.#raw, "utf8")
+                    : this.#raw.byteLength;
+        }
+        return this.#size;
+    }
+    /** The original value Bun delivered. */
+    get raw() {
+        return this.#raw;
+    }
+    /** Text content. Binary frames must hold valid UTF-8. */
+    text() {
+        if (typeof this.#raw === "string")
+            return this.#raw;
+        try {
+            return decoder.decode(this.#raw);
+        }
+        catch {
+            throw new WsProtocolError("Invalid UTF-8");
+        }
+    }
+    bytes() {
+        return typeof this.#raw === "string"
+            ? encoder.encode(this.#raw)
+            : this.#raw;
+    }
+    /** Parse as JSON; malformed input throws a {@link WsProtocolError} (→ `1008`). */
+    json() {
+        const text = this.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new WsProtocolError("Invalid JSON");
+        }
+    }
+}

package/dist/ws/origin.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Cross-Site WebSocket Hijacking (CSWSH) protection.
+ *
+ * Browsers attach cookies to cross-origin WebSocket handshakes and CORS does
+ * not apply to them, so the `Origin` header is the only thing stopping a
+ * hostile page from opening an authenticated socket. Requests *without* an
+ * `Origin` (curl, native apps, servers) can't carry ambient browser
+ * credentials and are allowed.
+ */
+import type { CorsOptions } from "../core/index.ts";
+export type OriginPredicate = (origin: string, req: Request) => boolean | Promise<boolean>;
+export type OriginSource = 
+/** `Origin` host equals the `Host` header. */
+"same-origin"
+/** Disable the check. Logged once at build. */
+ | "any"
+/** Exact origin (`"https://app.example.com"`) or a leftmost wildcard (`"https://*.example.com"`). */
+ | string
+/** Tested against the normalized origin; anchored automatically. */
+ | RegExp | OriginPredicate;
+export interface OriginPolicy {
+    /** `true` if the handshake may proceed. */
+    check(req: Request): boolean | Promise<boolean>;
+    /** Whether the policy is `"any"` (no protection). */
+    readonly allowsAny: boolean;
+}
+/**
+ * Compile origin sources into a policy. An empty list means `"same-origin"`.
+ * Throws on malformed sources so mistakes surface at startup.
+ */
+export declare function createOriginPolicy(sources: readonly OriginSource[]): OriginPolicy;
+/**
+ * Origin sources inherited from a root `cors()` config. `"*"` is *not*
+ * inherited — a wildcard would disable CSWSH protection on cookie-authenticated
+ * sockets — and is reported via `wildcard` so the caller can warn.
+ */
+export declare function originSourcesFromCors(cors: CorsOptions | null): {
+    sources: OriginSource[];
+    wildcard: boolean;
+};

package/dist/ws/origin.js

@@ -0,0 +1,152 @@
+/**
+ * Cross-Site WebSocket Hijacking (CSWSH) protection.
+ *
+ * Browsers attach cookies to cross-origin WebSocket handshakes and CORS does
+ * not apply to them, so the `Origin` header is the only thing stopping a
+ * hostile page from opening an authenticated socket. Requests *without* an
+ * `Origin` (curl, native apps, servers) can't carry ambient browser
+ * credentials and are allowed.
+ */
+const DEFAULT_PORTS = {
+    "http:": "80",
+    "https:": "443",
+    "ws:": "80",
+    "wss:": "443",
+};
+/** `scheme://host[:port]`, lowercased, default ports dropped. */
+function normalize(url) {
+    return `${url.protocol}//${url.host}`.toLowerCase();
+}
+function parseOrigin(raw) {
+    if (raw === "null")
+        return null;
+    try {
+        const url = new URL(raw);
+        // A real Origin header never has a path, query, fragment or userinfo.
+        if (url.username || url.password)
+            return null;
+        return url;
+    }
+    catch {
+        return null;
+    }
+}
+/** Host header → `host[:port]` with any default port removed. */
+function normalizeHost(host) {
+    const lower = host.toLowerCase().replace(/\.$/, "");
+    const match = /^(.*?)(?::(\d+))?$/.exec(lower);
+    if (match == null)
+        return lower;
+    const [, name, port] = match;
+    if (port === "80" || port === "443" || port == null)
+        return name ?? lower;
+    return `${name}:${port}`;
+}
+function sameOrigin(origin, _raw, req) {
+    if (origin == null)
+        return false;
+    if (origin.protocol !== "http:" && origin.protocol !== "https:")
+        return false;
+    const host = req.headers.get("host");
+    if (host == null)
+        return false;
+    return normalizeHost(origin.host) === normalizeHost(host);
+}
+function compileString(source) {
+    const wildcard = /^([a-z][a-z0-9+.-]*):\/\/\*\.([^/:*]+)(?::(\d+))?$/i.exec(source);
+    if (wildcard) {
+        const [, scheme, domain, port] = wildcard;
+        const protocol = `${scheme.toLowerCase()}:`;
+        const suffix = `.${domain.toLowerCase()}`;
+        const wantPort = port ?? DEFAULT_PORTS[protocol] ?? "";
+        return (origin) => {
+            if (origin == null || origin.protocol !== protocol)
+                return false;
+            const gotPort = origin.port || DEFAULT_PORTS[origin.protocol] || "";
+            if (gotPort !== wantPort)
+                return false;
+            const host = origin.hostname.toLowerCase();
+            // Require at least one label before the suffix: "*.example.com"
+            // matches "a.example.com" but not "example.com" or "evilexample.com".
+            return host.endsWith(suffix) && host.length > suffix.length;
+        };
+    }
+    if (source.includes("*")) {
+        throw new Error(`Invalid origin "${source}": only a leftmost "*." wildcard is supported`);
+    }
+    if (source === "null") {
+        return (_origin, raw) => raw === "null";
+    }
+    const parsed = parseOrigin(source);
+    if (parsed == null ||
+        parsed.pathname !== "/" ||
+        parsed.search ||
+        parsed.hash) {
+        throw new Error(`Invalid origin "${source}": expected "scheme://host[:port]"`);
+    }
+    const expected = normalize(parsed);
+    return (origin) => origin != null && normalize(origin) === expected;
+}
+function compileRegExp(source) {
+    const body = source.source;
+    const anchored = new RegExp(`^(?:${body})$`, source.flags.replace(/[gy]/g, ""));
+    return (origin, raw) => anchored.test(origin == null ? raw : normalize(origin));
+}
+/**
+ * Compile origin sources into a policy. An empty list means `"same-origin"`.
+ * Throws on malformed sources so mistakes surface at startup.
+ */
+export function createOriginPolicy(sources) {
+    if (sources.includes("any")) {
+        return { check: () => true, allowsAny: true };
+    }
+    const matchers = (sources.length ? sources : ["same-origin"]).map((source) => {
+        if (source === "same-origin")
+            return sameOrigin;
+        if (typeof source === "string")
+            return compileString(source);
+        if (source instanceof RegExp)
+            return compileRegExp(source);
+        return (_origin, raw, req) => source(raw, req);
+    });
+    return {
+        allowsAny: false,
+        check(req) {
+            const raw = req.headers.get("origin");
+            if (raw == null)
+                return true; // non-browser client
+            const origin = parseOrigin(raw);
+            const pending = [];
+            for (const matcher of matchers) {
+                const result = matcher(origin, raw, req);
+                if (result === true)
+                    return true;
+                if (result instanceof Promise)
+                    pending.push(result);
+            }
+            if (pending.length === 0)
+                return false;
+            return Promise.all(pending).then((results) => results.includes(true));
+        },
+    };
+}
+/**
+ * Origin sources inherited from a root `cors()` config. `"*"` is *not*
+ * inherited — a wildcard would disable CSWSH protection on cookie-authenticated
+ * sockets — and is reported via `wildcard` so the caller can warn.
+ */
+export function originSourcesFromCors(cors) {
+    if (cors == null)
+        return { sources: [], wildcard: false };
+    const { origin } = cors;
+    if (origin === "*")
+        return { sources: [], wildcard: true };
+    if (typeof origin === "function") {
+        return { sources: [(o) => origin(o) != null], wildcard: false };
+    }
+    const list = Array.isArray(origin) ? origin : [origin];
+    return {
+        sources: list.filter((o) => o !== "*"),
+        wildcard: list.includes("*"),
+    };
+}

package/dist/ws/presence.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+import type { WsConnection } from "./connection.ts";
+import type { WsHub } from "./hub.ts";
+export interface PresenceEntry<M = unknown> {
+    /** Connection id. */
+    ref: string;
+    meta: M;
+}
+/** Entries grouped by key — the wire format of state and diffs. */
+export type PresenceState<M = unknown> = Record<string, PresenceEntry<M>[]>;
+export interface PresenceDiff<M = unknown> {
+    joins: PresenceState<M>;
+    leaves: PresenceState<M>;
+}
+export interface PresenceOptions {
+    /** Client-facing diff coalescing window. Default 50 ms. */
+    batchMs?: number;
+    /** Heartbeat interval on a transport. Default 5 s. */
+    heartbeatMs?: number;
+    /** A node silent for longer is considered dead. Default 15 s. */
+    peerTimeoutMs?: number;
+    /** Max entries per topic on this node (protects memory). Default 10 000. */
+    maxEntriesPerTopic?: number;
+    /** Injectable clock/timers for tests. */
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    setInterval?: (fn: () => void, ms: number) => unknown;
+    clearInterval?: (handle: unknown) => void;
+}
+type DiffListener = (topic: string, diff: PresenceDiff) => void;
+export declare class PresenceLimitError extends Error {
+    constructor(topic: string);
+}
+/**
+ * Per-hub presence state. Get it via `hub.presence(topic)` — you rarely
+ * construct this directly.
+ */
+export declare class PresenceRegistry {
+    #private;
+    constructor(hub: WsHub, replicated: boolean, options?: PresenceOptions);
+    /**
+     * Track `socket` in `topic` under `key`. Re-tracking replaces the meta.
+     * Untracked automatically when the socket closes.
+     */
+    track(topic: string, socket: WsConnection, key: string, meta: unknown): void;
+    /** Replace the meta of an already tracked socket. No-op if untracked. */
+    update(topic: string, socket: WsConnection, meta: unknown): boolean;
+    untrack(topic: string, socket: WsConnection): void;
+    list(topic: string): PresenceState;
+    has(topic: string, key: string): boolean;
+    keys(topic: string): string[];
+    /** Tracked meta of a local socket. */
+    metaOf(topic: string, socket: WsConnection): unknown;
+    /** Topics with at least one entry anywhere. */
+    topics(): string[];
+    /** Coalesced diffs for every topic (local and remote changes). */
+    onDiff(fn: DiffListener): () => void;
+    /** Stop timers and drop remote state (e.g. on shutdown). */
+    close(): void;
+    /** Emit pending diffs now. Called automatically after `batchMs`. */
+    flush(): void;
+}
+/** A read/write view of one topic, from `hub.presence(topic)`. */
+export declare class PresenceTopic<M = unknown> {
+    #private;
+    readonly topic: string;
+    /** @internal */
+    constructor(registry: PresenceRegistry, topic: string);
+    track(socket: WsConnection, key: string, meta: M): void;
+    update(socket: WsConnection, meta: M): boolean;
+    untrack(socket: WsConnection): void;
+    /** Cluster-wide: `{ [key]: { ref, meta }[] }`. */
+    list(): PresenceState<M>;
+    has(key: string): boolean;
+    keys(): string[];
+    /** Number of distinct keys (users), cluster-wide. */
+    count(): number;
+    /** Coalesced diffs of this topic. */
+    onDiff(fn: (diff: PresenceDiff<M>) => void): () => void;
+}
+export {};