@nifrajs/web 5.5.1 → 5.7.0

package/dist/live/hub.d.ts

@@ -0,0 +1,185 @@
+/**
+ * The live socket endpoint and its fan-out. A socket subscribes to the tags of the keys its installed
+ * grants hold; each change goes out as one identical `changed` frame per tag topic, so Bun can send it
+ * with one native publish. Frames carry tags only: never data, key text, subjects or seqs.
+ *
+ * Installing a watch and applying a bus event each run as one synchronous step (subscribe, then scan
+ * history, then `ready`; record in history, then publish), so every event is either reported in
+ * `ready.stale` or delivered after the subscription, and `ready` precedes every later frame.
+ */
+import { type NifraWebSocket, type WebSocketData } from "@nifrajs/core/server";
+import type { LiveRevocation } from "./bus.js";
+import type { History } from "./history.js";
+import { type Keyring } from "./keyring.js";
+import type { Revocations } from "./revocations.js";
+export declare const CLOSE_BAD_GRANT = 4401;
+export declare const CLOSE_REVOKED = 4403;
+export declare const CLOSE_SCOPE = 4409;
+export declare const CLOSE_CAPACITY = 1013;
+export declare const CLOSE_PROTOCOL = 1008;
+/** The runtime closed: reconnect, most likely to another process. */
+export declare const CLOSE_GOING_AWAY = 1001;
+/** Nothing to watch: a tab with no tag to hear about reconnects only once it has one. */
+export declare const CLOSE_UNWATCHED = 1000;
+export declare const MAX_FRAME_BYTES = 32768;
+export declare const MAX_WATCH_GRANTS = 3;
+export declare const MAX_WATCHES_PER_MINUTE = 20;
+/** Every inbound frame, heartbeats included: a client heartbeats twice a minute. */
+export declare const MAX_FRAMES_PER_MINUTE = 60;
+export declare const MAX_OUTBOUND_BYTES = 65536;
+export declare const MAX_TOPICS = 200000;
+export declare const IDLE_MS = 150000;
+/**
+ * How long a socket may hold no tag: from its open, or from the watch or revocation that left it
+ * none. A tab watches right after its first live load, so only a socket nobody listens on runs out.
+ */
+export declare const FIRST_WATCH_MS = 60000;
+export declare const SWEEP_MS = 10000;
+export declare const COALESCE_MS = 25;
+/** How long after closing many sockets at once their reconnects are told to spread their reloads. */
+export declare const RECONNECT_WINDOW_MS = 30000;
+export interface HubOptions {
+    readonly appId: string;
+    readonly trusted: ReadonlySet<string>;
+    readonly maxSockets: number;
+    readonly maxRssBytes: number | undefined;
+    readonly reloadRate: number;
+    readonly instances: number;
+    readonly spreadFloor: number;
+    readonly hash: (key: string) => number;
+    /** Distinct tags this process holds subscriptions for. Default {@link MAX_TOPICS}. */
+    readonly maxTopics?: number;
+    /** Where key tags come from; the runtime shares one cache between its loads and this hub. */
+    readonly tags?: TagOf;
+    /**
+     * Socket-tag subscriptions this process holds in all; past it a watch is refused with 1013. For a
+     * host whose memory is capped below what its sockets could ask for. Default: no budget.
+     */
+    readonly maxMemberships?: number;
+    /**
+     * Where a hub that outlives its memory keeps socket state (a hibernating Durable Object): told of
+     * every installed watch and every socket that leaves. Its sweep runs on the host's alarm instead
+     * of a timer, which would keep the host awake.
+     */
+    readonly store?: HubStore;
+}
+/** What a socket's membership is, kept so a hub can {@link LiveHub.restore} it after its memory is gone. */
+export interface StoredSocket {
+    readonly sub: string | null;
+    readonly exp: number;
+    readonly tags: readonly string[];
+}
+export interface HubStore {
+    saved(ws: NifraWebSocket<LiveSocket>, socket: StoredSocket): void;
+    removed(ws: NifraWebSocket<LiveSocket>): void;
+    /** The last time the host answered this socket's heartbeat without waking the hub. */
+    lastBeat(ws: NifraWebSocket<LiveSocket>): number;
+}
+/** Per-connection state, held in `ws.data`. */
+export interface LiveSocket {
+    sid: string;
+    /** The subject of the first accepted grant; `undefined` until then. */
+    sub: string | null | undefined;
+    /** The highest `gen` received; a lower or equal one is ignored. */
+    received: number;
+    tags: Set<string>;
+    /** Earliest installed grant expiry, ms. */
+    exp: number;
+    /** Since when it has held no tag; `undefined` while it holds one. See {@link FIRST_WATCH_MS}. */
+    unwatchedSince: number | undefined;
+    window: number;
+    frames: number;
+    watches: number;
+    lastSeen: number;
+}
+export declare class LiveHub {
+    private readonly ring;
+    private readonly history;
+    private readonly revocations;
+    private readonly options;
+    /** Where `changed` frames go: each attached app's `publish`. */
+    private readonly publishers;
+    /** Bus unreachable: no watch is accepted and no socket kept. */
+    down: boolean;
+    /** `changed` frames sent, one per subscribed socket: each makes a page reload. */
+    notified: number;
+    private readonly sockets;
+    /** Local subscribers per tag: the intern table, and the input to `spread`. */
+    private readonly members;
+    /** Socket-tag subscriptions held, the sum of `members`. */
+    private memberships;
+    private readonly tagOf;
+    private readonly coalescing;
+    /** The last time many sockets were closed at once, and how many. */
+    private burstAt;
+    private burstSize;
+    private coalesceTimer;
+    private sweepTimer;
+    constructor(ring: Keyring, history: History, revocations: Revocations, options: HubOptions, 
+    /** Where `changed` frames go: each attached app's `publish`. */
+    publishers: ReadonlySet<(topic: string, frame: string) => void>);
+    get size(): number;
+    /** The tag of `key` under each listed secret, newest first. */
+    tagsOf(key: string): Promise<string[]>;
+    /** The handshake: a missing, `null` or untrusted Origin is refused. */
+    upgrade(req: Request): LiveSocket | Response;
+    open(ws: NifraWebSocket<LiveSocket>): void;
+    /** The runtime has dropped the closed socket's topics; only the counts are left to settle. */
+    close(ws: NifraWebSocket<LiveSocket>): void;
+    /** A change, already in history: publish one frame per tag, at most once per key per window. */
+    change(keys: readonly string[], tags: readonly (readonly string[])[]): void;
+    /** A revocation, already stored. `tags` are the key's tags for a `revokeKey`. */
+    revoke(event: LiveRevocation, tags: readonly string[]): void;
+    /** Close every socket: history or revocations before now are unknown, or the bus is gone. */
+    closeAll(code: number, reason: string): void;
+    /**
+     * `count` sockets just closed together and will reconnect together. Each must reload under its new
+     * socket id, so for a while `welcome` tells them to spread those reloads as a change would.
+     */
+    burst(count: number): void;
+    /** Resolves once a watch is installed or refused. */
+    message(ws: NifraWebSocket<LiveSocket>, data: WebSocketData): Promise<void> | undefined;
+    private install;
+    /**
+     * A socket whose hub lost its memory but not its connection: its membership comes back as stored.
+     * Every revocation since was applied to what is stored, so nothing here is checked again.
+     */
+    restore(ws: NifraWebSocket<LiveSocket>, stored: StoredSocket | undefined): void;
+    private flush;
+    private publishTags;
+    /**
+     * How long clients spread their reloads, from this process's subscriber count, rounded up to a few
+     * steps so the frame shows no more than its order of magnitude.
+     */
+    private spread;
+    private join;
+    private leave;
+    /** Leave every topic before closing: nothing published after this reaches the socket. */
+    private drop;
+    private forget;
+    private send;
+    private topic;
+    /** Read on every open, never cached: a burst of opens must not all pass on one stale reading. */
+    private overRss;
+    private startSweep;
+    private stopSweep;
+    /**
+     * Drop the socket when its earliest grant has expired. A host whose sweep can run late (an alarm)
+     * asks before every frame it sends.
+     */
+    expired(ws: NifraWebSocket<LiveSocket>, now: number): boolean;
+    /**
+     * Expired grants, silent peers, sockets with nothing to watch and slow readers. Returns the earliest
+     * deadline left: a grant expiry, the silence limit, or the end of {@link FIRST_WATCH_MS}; infinite
+     * with no socket.
+     */
+    sweep(): number;
+}
+/** The pub/sub topic of one tag. */
+export declare const topicOf: (appId: string, tag: string) => string;
+/** The wire tag of a key under one listed secret. */
+export type TagOf = (key: string, secret: number) => Promise<string>;
+/** {@link Keyring.tag}, kept: a key's tag changes only with the secrets. Oldest entry out first. */
+export declare function tagCache(ring: Keyring, size?: number): TagOf;
+export declare function unref<T>(timer: T): T;
+//# sourceMappingURL=hub.d.ts.map

package/dist/live/hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.d.ts","sourceRoot":"","sources":["../../src/live/hub.ts"],"names":[],"mappings":"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"}