@nifrajs/web 5.5.1 → 5.7.0

package/dist/live-redis.js

@@ -0,0 +1,212 @@
+/**
+ * KEYS[1] the stream, KEYS[2] the clock hash; ARGV[1] the event JSON, ARGV[2] the trim length.
+ * Lua numbers are doubles: a microsecond clock stays exact below 2^53 (the year 2255).
+ */
+export const APPEND_SCRIPT = `local t = redis.call('TIME')
+local now = tonumber(t[1]) * 1000000 + tonumber(t[2])
+local last = tonumber(redis.call('HGET', KEYS[2], 'seq') or '0')
+local seq = math.max(last + 1, now)
+local id = string.format('%.0f', seq)
+local n = redis.call('HINCRBY', KEYS[2], 'n', 1)
+redis.call('HSET', KEYS[2], 'seq', id)
+redis.call('XADD', KEYS[1], 'MAXLEN', '~', ARGV[2], id .. '-0', 'n', n, 'e', ARGV[1])
+return id`;
+const RETRY_MS = [100, 500, 1_000, 2_000, 5_000];
+const READ_GRACE_MS = 5_000;
+export function redisLiveBus(options) {
+    const key = options.key ?? "nifra:live";
+    const clock = `${key}:clock`;
+    const maxLength = String(options.maxLength ?? 100_000);
+    const blockMs = String(options.blockMs ?? 5_000);
+    const readTimeoutMs = options.readTimeoutMs ?? (options.blockMs ?? 5_000) + READ_GRACE_MS;
+    /** The clock's seq and running count, as the last append left them. */
+    const position = async () => {
+        const reply = await options.send("HMGET", [clock, "seq", "n"]);
+        const [seq, n] = Array.isArray(reply) ? reply : [];
+        return { seq: countOf(seq), n: countOf(n) };
+    };
+    return {
+        async append(input) {
+            const reply = await options.send("EVAL", [
+                APPEND_SCRIPT,
+                "2",
+                key,
+                clock,
+                JSON.stringify(input),
+                maxLength,
+            ]);
+            const seq = countOf(reply);
+            if (seq === 0)
+                throw new Error("[nifra/web] live-redis: the append script returned no seq");
+            return seq;
+        },
+        async subscribe(listener) {
+            const read = options.read;
+            if (read === undefined) {
+                throw new TypeError("[nifra/web] live-redis: subscribing needs `read`, a connection of its own; a bus without one only appends");
+            }
+            const start = await position();
+            let closed = false;
+            void follow(read, start.seq, start.n, listener, () => closed);
+            return {
+                head: start.seq,
+                close: () => {
+                    closed = true;
+                },
+            };
+        },
+    };
+    async function follow(read, head, count, listener, isClosed) {
+        let last = head;
+        // The id the next read starts after, verbatim: an id this bus did not write still moves it on.
+        let cursor = `${head}-0`;
+        let expected = count + 1;
+        let failures = 0;
+        // Told `down`: only a read that answers again ends the outage, never the clock alone.
+        let down = false;
+        while (!isClosed()) {
+            let entries;
+            let error;
+            try {
+                const reply = await within(read("XREAD", ["BLOCK", blockMs, "COUNT", "1000", "STREAMS", key, cursor]), readTimeoutMs);
+                entries = reply === null || reply === undefined ? [] : entriesOf(reply);
+                if (entries === undefined)
+                    error = new Error("[nifra/web] live-redis: XREAD replied in no known shape");
+            }
+            catch (failure) {
+                entries = undefined;
+                error = failure;
+            }
+            // Closed while the read was blocked: closing its connection next is the caller's shutdown.
+            if (isClosed())
+                return;
+            if (entries === undefined) {
+                // A reply of no known shape counts as a failed read, so it backs off instead of spinning.
+                failures++;
+                // One failed read may be a hiccup; a second in a row is an outage.
+                if (failures === 2) {
+                    down = true;
+                    listener.down(error);
+                }
+                await wait(RETRY_MS[Math.min(failures - 1, RETRY_MS.length - 1)] ?? 5_000);
+                continue;
+            }
+            failures = 0;
+            if (down) {
+                try {
+                    const now = await position();
+                    if (isClosed())
+                        return;
+                    // Whatever happened while the bus was unreachable is unknown: resume after the clock.
+                    listener.gap(now.seq);
+                    last = now.seq;
+                    cursor = `${now.seq}-0`;
+                    expected = now.n + 1;
+                    down = false;
+                }
+                catch {
+                    // The clock is out of reach: still down, and the next read tries again.
+                }
+                continue;
+            }
+            for (const entry of entries) {
+                if (isClosed())
+                    return;
+                cursor = entry.id;
+                if (entry.seq === 0) {
+                    listener.gap(last);
+                    continue;
+                }
+                if (entry.n !== expected) {
+                    // Entries between were trimmed before this reader got to them.
+                    listener.gap(entry.seq - 1);
+                }
+                expected = entry.n + 1;
+                last = entry.seq;
+                if (entry.event === undefined)
+                    listener.gap(entry.seq);
+                else
+                    listener.event(entry.event);
+            }
+        }
+    }
+}
+/**
+ * The entries of an `XREAD` reply for one stream - RESP2 `[[key, entries]]`, RESP3 `{ key: entries }`
+ * or a `Map` - each entry `[id, [field, value, ...]]`. Undefined when the reply has none of these shapes.
+ */
+function entriesOf(reply) {
+    let streams;
+    if (Array.isArray(reply))
+        streams = reply.map((stream) => (Array.isArray(stream) ? stream[1] : undefined));
+    else if (reply instanceof Map)
+        streams = [...reply.values()];
+    else if (isRecord(reply))
+        streams = Object.values(reply);
+    else
+        return undefined;
+    const out = [];
+    for (const entries of streams) {
+        if (!Array.isArray(entries))
+            return undefined;
+        for (const entry of entries) {
+            if (!Array.isArray(entry))
+                return undefined;
+            const [id, fields] = entry;
+            if (typeof id !== "string" || !Array.isArray(fields))
+                return undefined;
+            const [time, part] = id.split("-");
+            const seq = part === "0" ? countOf(time) : 0;
+            let n = 0;
+            let body;
+            for (let i = 0; i + 1 < fields.length; i += 2) {
+                if (fields[i] === "n")
+                    n = countOf(fields[i + 1]);
+                else if (fields[i] === "e")
+                    body = fields[i + 1];
+            }
+            out.push({ id, seq, n, event: seq === 0 ? undefined : eventOf(body, seq) });
+        }
+    }
+    return out;
+}
+function eventOf(body, seq) {
+    if (typeof body !== "string")
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value))
+        return undefined;
+    if (value.type === "change" && Array.isArray(value.keys)) {
+        const keys = value.keys.filter((name) => typeof name === "string");
+        return { type: "change", keys, seq };
+    }
+    const { sub, key } = value;
+    if (value.type === "revoke" &&
+        (sub === null || typeof sub === "string") &&
+        (key === null || typeof key === "string")) {
+        return { type: "revoke", sub, key, seq };
+    }
+    return undefined;
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A Redis integer reply or numeric string as a non-negative safe integer, else 0. */
+function countOf(value) {
+    const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+    return Number.isSafeInteger(n) && n > 0 ? n : 0;
+}
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** `pending`, or a rejection once `ms` pass without it settling. */
+function within(pending, ms) {
+    let timer;
+    const expiry = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("[nifra/web] live-redis: the read timed out")), ms);
+    });
+    return Promise.race([pending, expiry]).finally(() => clearTimeout(timer));
+}
+//# sourceMappingURL=live-redis.js.map

package/dist/live-redis.js.map

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

package/dist/live.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Live data refresh, server side. Loaders declare what their data depends on with `ctx.live(...keys)`;
+ * a live load returns an encrypted grant for those keys, and the client reloads through the same
+ * authorized path whenever one of them changes. Data never travels with a change notice.
+ *
+ * ```ts
+ * import { live } from "@nifrajs/web/live"
+ *
+ * const liveRuntime = live({ secret: process.env.LIVE_SECRET, subject: (ctx) => sessionUserId(ctx.request) })
+ * createWebApp({ ...options, live: liveRuntime })
+ * ```
+ *
+ * Every live load is a `POST` to the load endpoint that runs the target page as a `GET` through the
+ * whole app: every hook, middleware, gate and loader sees the target path, exactly as a navigation.
+ * Changes reach open pages over one WebSocket per tab, as opaque tags of the keys they watch.
+ */
+import { type Logger } from "@nifrajs/core/server";
+import { type LiveRuntimeHandle } from "./internal/live-contract.js";
+import { type LiveBus } from "./live/bus.js";
+import { type LiveHubNamespace } from "./live/hub-protocol.js";
+import type { LoaderContext } from "./manifest.js";
+export type { LiveBus, LiveBusEvent, LiveBusInput, LiveBusListener, LiveBusSubscription, LiveChange, LiveRevocation, } from "./live/bus.js";
+export { livePublisher, memoryBus, nextSeq } from "./live/bus.js";
+export interface LiveOptions {
+    /**
+     * The grant secret, or a rotation list with the newest first (at most 3, each at least 32 bytes).
+     * Required in production; development falls back to a random per-process secret.
+     */
+    readonly secret?: string | readonly string[] | undefined;
+    /**
+     * Who the viewer is: a stable id, or `null` for an anonymous viewer. Called once per live load,
+     * after middleware. A grant is only honored for the subject it was issued to.
+     */
+    readonly subject: (ctx: LoaderContext) => string | null | Promise<string | null>;
+    /** Separates this app's tags from another app's that shares a secret. Default `"nifra"`. */
+    readonly appId?: string;
+    /** Grant lifetime in seconds, at most 3600. Default 600. */
+    readonly grantTtl?: number;
+    /** The live load endpoint. Default `/_nifra/live/load`. */
+    readonly loadPath?: string;
+    /** The live socket. Default `/_nifra/live`. */
+    readonly path?: string;
+    /** Origins besides the app's own that may call the load endpoint and open the socket. */
+    readonly trustedOrigins?: readonly string[];
+    /** Live loads running at once in this process; past it the endpoint answers 503. Default 64. */
+    readonly maxConcurrentLoads?: number;
+    /** Live sockets in this process; past it a socket is closed with 1013. Default 10,000. */
+    readonly maxSockets?: number;
+    /** Refuse new sockets while the process's resident memory is above this many bytes. */
+    readonly maxRssBytes?: number;
+    /**
+     * The ordered log every process serving the app shares. Default: an in-process bus, right for one
+     * process only.
+     */
+    readonly bus?: LiveBus;
+    /**
+     * Cloudflare Workers: the Durable Object namespace of the app's live hub (`liveHub()` from
+     * `@nifrajs/web/live-hub`). The hub owns the log and holds the sockets; this isolate forwards the
+     * socket handshake to it, asks it for the seq and the revocations each load needs, and publishes
+     * through it. Exclusive with `bus`.
+     */
+    readonly hub?: LiveHubNamespace;
+    /** Processes serving the app, for spreading reloads. Default 1. */
+    readonly instances?: number;
+    /** Live loads per second the deployment absorbs after one change, for spreading reloads. Default 500. */
+    readonly reloadRate?: number;
+    /** The least time, in ms, clients spread their reloads over. Default 0. */
+    readonly spreadFloor?: number;
+    /**
+     * Re-check the keys of owners a load keeps without running their loaders. With it, `renew`
+     * re-signs a grant without loaders (every third renewal still runs them all, so a lost change is
+     * found within about 27 minutes); without it, `renew` runs a full load. `false` issues no grant.
+     */
+    readonly authorize?: (keys: readonly string[], ctx: LoaderContext) => boolean | Promise<boolean>;
+    /**
+     * Resolves once a committed write is readable by every loader, such as a read replica catching up.
+     * `publish` waits for it, so no client reloads before its data can show the change. Replica-backed
+     * reads need it; without it a publish goes out as soon as it is called.
+     */
+    readonly visible?: () => void | Promise<void>;
+    /**
+     * Let query hooks refetch on the keys a page's loaders grant (`useQuery(key, fn, { live })`). Each
+     * live load then carries a salted digest of every key it grants: page code can confirm a guess at
+     * one of them, so leave it off when key names hold anything the viewer should not see.
+     */
+    readonly queryKeys?: boolean;
+    /**
+     * Where the runtime reports what it cannot fix by itself: the bus stopping to answer and answering
+     * again, events lost to a trim, an event it could not apply, a publish it did not read back.
+     * Default `jsonLogger()`; `false` reports nothing. {@link Live.status} has the same state to poll.
+     */
+    readonly logger?: Logger | false;
+}
+/** What one process's live runtime is doing now; counters run from its start. */
+export interface LiveStatus {
+    /** The keyring is derived and the bus read: grants can be issued. */
+    readonly ready: boolean;
+    /**
+     * No grant is issued and no socket kept: the bus (or the Workers hub) is unreachable, or the
+     * runtime was closed. Open pages poll meanwhile.
+     */
+    readonly down: boolean;
+    /** Since when `down` has held, in epoch ms. */
+    readonly downSince: number | undefined;
+    /** Live sockets open in this process. On Workers the hub holds them, so this is 0. */
+    readonly sockets: number;
+    /** Live loads running in this process. */
+    readonly loads: number;
+    /** Bus events this process applied. */
+    readonly events: number;
+    /** `changed` frames this process sent, one per watching socket: each makes a page reload. */
+    readonly notified: number;
+    /**
+     * How long after its append the last event was applied here, in ms. The append time comes from the
+     * bus's clock, so skew between hosts shows in it.
+     */
+    readonly lagMs: number | undefined;
+}
+/** A live runtime: pass it to `createWebApp({ live })`. */
+export interface Live extends LiveRuntimeHandle {
+    /** Resolves once the secrets are derived and the bus is read; rejects on a duplicate secret id. */
+    readonly ready: Promise<void>;
+    /**
+     * `keys` changed: every open page watching one reloads it. Call it after the write is visible to
+     * loaders; resolves once this process has applied it, or 2 s after the bus took it if this process
+     * has not read it back by then.
+     */
+    publish(...keys: string[]): Promise<void>;
+    /** Refuse every grant issued to `subject` before now, and close its sockets. */
+    revoke(subject: string): Promise<void>;
+    /** Refuse every grant issued before now, and close every socket. */
+    revokeAll(): Promise<void>;
+    /**
+     * Access to `key` was removed (for everyone, or for one subject): every watcher gets one last change
+     * for it and stops watching it, and no grant issued before now keeps or re-signs it, so the next load
+     * runs that owner's loader, which decides again.
+     */
+    revokeKey(key: string, subject?: string): Promise<void>;
+    /** What this process's runtime is doing now: for a readiness check or metrics. */
+    status(): LiveStatus;
+    /**
+     * Stop reading the bus and close every live socket (1001); open pages poll until they reach another
+     * process. Call it before closing the bus's connections, so the reader does not count that as an
+     * outage. A publish after it throws. Idempotent.
+     */
+    close(): Promise<void>;
+}
+/** Create the live runtime for one app. */
+export declare function live(options: LiveOptions): Live;
+//# sourceMappingURL=live.d.ts.map

package/dist/live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../src/live.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAgC,KAAK,MAAM,EAAqB,MAAM,sBAAsB,CAAA;AAEnG,OAAO,EAOL,KAAK,iBAAiB,EACvB,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EACL,KAAK,OAAO,EAKb,MAAM,eAAe,CAAA;AAWtB,OAAO,EAOL,KAAK,gBAAgB,EAItB,MAAM,wBAAwB,CAAA;AAyB/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AASlD,YAAY,EACV,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAEjE,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAChF,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,yFAAyF;IACzF,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3C,gGAAgG;IAChG,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IACpC,0FAA0F;IAC1F,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,gBAAgB,CAAA;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,yGAAyG;IACzG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAChG;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;CACjC;AAED,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAED,2DAA2D;AAC3D,MAAM,WAAW,IAAK,SAAQ,iBAAiB;IAC7C,mGAAmG;IACnG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7B;;;;OAIG;IACH,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,gFAAgF;IAChF,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,oEAAoE;IACpE,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,kFAAkF;IAClF,MAAM,IAAI,UAAU,CAAA;IACpB;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAyED,2CAA2C;AAC3C,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAowB/C"}