yrby-client 0.4.3 → 0.6.0

package/dist/document_session.js

@@ -0,0 +1,296 @@
+// Holds a document for the application, independently of editors and page
+// navigation.
+//
+// A session remains open while an editor is attached or the server has not yet
+// acknowledged some of its edits, and it closes itself when neither is true.
+// When the server rejects the subscription, the session tries the descriptor's
+// refresh URL once if it has one. If there is no URL, the refresh fails, or the
+// server rejects the new grant, the session blocks. Blocking releases its
+// editors and keeps its queued work in memory until the application calls
+// retry() or discard().
+import * as Y from "yjs";
+import { uuidv4 } from "lib0/random";
+import { ActionCableProvider } from "./actioncable_provider.js";
+// Each phase sets the state apps see, whether a new lease connects right away,
+// and which transitions are allowed. A new lease does not connect while the
+// session is blocked or waiting for a refreshed grant. Transitions that aren't
+// listed are ignored.
+const PHASES = {
+    open: { state: "open", connects: true, on: { refresh: "refreshing", block: "blocked", close: "closed" } },
+    refreshing: { state: "open", connects: false, on: { renew: "renewed", block: "blocked", close: "closed" } },
+    renewed: { state: "open", connects: true, on: { accept: "open", block: "blocked", close: "closed" } },
+    blocked: { state: "blocked", connects: false, on: { retry: "open", close: "closed" } },
+    closed: { state: "closed", connects: false, on: {} },
+};
+// Without a limit, a refresh request that never returns would leave the
+// session offline and stuck with its editors attached. After this long, the
+// session blocks.
+const REFRESH_TIMEOUT_MS = 15_000;
+const DEFAULT_CHANNEL = "Y::DocumentChannel";
+const stores = new WeakMap();
+/** The identity of the document a descriptor names. Matching keys share a session. */
+export function documentKey(descriptor) {
+    return JSON.stringify([descriptor.channel || DEFAULT_CHANNEL, descriptor.grant, descriptor.name]);
+}
+// Only the factory may create a store for a consumer.
+const storeToken = Symbol("storeToken");
+// Not exported, so only the store can acquire leases.
+const attachLease = Symbol("attachLease");
+// Not exported, so only a session can publish store changes.
+const notifyStoreChange = Symbol("notifyStoreChange");
+/** Holds one consumer's sessions and emits "change" with the session in `detail`. */
+export class DocumentSessionStore extends EventTarget {
+    consumer;
+    static for(consumer) {
+        let store = stores.get(consumer);
+        if (!store)
+            stores.set(consumer, store = new DocumentSessionStore(consumer, storeToken));
+        return store;
+    }
+    #sessions = new Map();
+    constructor(consumer, token) {
+        super();
+        this.consumer = consumer;
+        if (token !== storeToken)
+            throw new Error("Use DocumentSessionStore.for(consumer)");
+    }
+    get sessions() { return [...this.#sessions.values()]; }
+    /** Acquire a lease on this document session, creating it on first use. */
+    acquire(input) {
+        if (!input.grant || !input.name)
+            throw new Error("A document requires a grant and name");
+        // The refresh URL is not part of the identity. Matching tuples share a
+        // session, which renews with the URL from the first acquisition.
+        const descriptor = Object.freeze({
+            channel: input.channel || DEFAULT_CHANNEL,
+            grant: input.grant,
+            name: input.name,
+            ...(input.refresh ? { refresh: input.refresh } : {}),
+        });
+        const key = documentKey(descriptor);
+        let session = this.#sessions.get(key);
+        if (!session) {
+            session = new DocumentSession(this, descriptor, () => { this.#sessions.delete(key); });
+            this.#sessions.set(key, session);
+        }
+        return session[attachLease]();
+    }
+    [notifyStoreChange](session) {
+        this.dispatchEvent(new CustomEvent("change", { detail: session }));
+    }
+}
+/** A caller's hold on a session. Release it when you're done with the session. */
+export class DocumentLease {
+    session;
+    #controller = new AbortController();
+    #onRelease;
+    constructor(session, onRelease) {
+        this.session = session;
+        this.#onRelease = onRelease;
+    }
+    /** Aborts when the lease ends, including when the session blocks or is discarded. */
+    get signal() { return this.#controller.signal; }
+    setPresence(state) {
+        if (!this.signal.aborted)
+            this.session.provider.awareness.setLocalState(state);
+    }
+    /** Runs editor cleanup synchronously, before the final check for pending work. */
+    release() {
+        if (this.signal.aborted)
+            return;
+        this.#controller.abort();
+        this.#onRelease();
+    }
+}
+// Application commands (acquire, retry, discard) take effect immediately.
+// Provider callbacks and lease releases record what happened and request a
+// settle, which runs after the current call stack finishes. Settle releases a
+// blocked session's leases, closes a session nobody needs, and notifies store
+// observers once.
+export class DocumentSession {
+    store;
+    descriptor;
+    remove;
+    doc = new Y.Doc();
+    provider;
+    #lifecycle = { phase: "open" };
+    #leases = new Set();
+    // Leases held when the session blocked. Settle releases these and keeps any
+    // lease acquired while blocked for retry().
+    #retiring;
+    #error;
+    #dirty = false; // true until store observers are notified of the latest change
+    #settleQueued = false;
+    /** Create and hold sessions through DocumentSessionStore.acquire. */
+    constructor(store, descriptor, remove) {
+        this.store = store;
+        this.descriptor = descriptor;
+        this.remove = remove;
+        // The session uses one provider for its whole life. The provider queues
+        // edits while offline, so blocking and retrying only need to disconnect and
+        // connect.
+        this.provider = new ActionCableProvider(this.doc, store.consumer, descriptor.channel, {
+            grant: descriptor.grant,
+            name: descriptor.name,
+            // Ack sequence numbers are per session, not per record.
+            session_id: uuidv4(),
+        }, {
+            onError: (error, context) => {
+                if (context === "rejected")
+                    this.#rejected(error);
+                else if (this.state !== "closed") {
+                    this.#error = error;
+                    this.#changed();
+                }
+            },
+        });
+        this.provider.awareness.setLocalState(null); // no cursor until an editor sets one
+        this.provider.onStatusChange(({ status }) => {
+            if (this.state !== "open")
+                return;
+            // The server accepted the subscription, so a renewed grant is valid.
+            if (status === "connected" || status === "synced")
+                this.#transition("accept");
+            this.#changed();
+        });
+    }
+    get error() { return this.#error; }
+    get hasPending() { return this.provider.hasPending; }
+    get whenSynced() { return this.provider.whenSynced; }
+    get state() { return PHASES[this.#lifecycle.phase].state; }
+    [attachLease]() {
+        if (this.state === "closed")
+            throw new Error("Cannot acquire a closed document session");
+        const lease = new DocumentLease(this, () => this.#release(lease));
+        this.#leases.add(lease);
+        this.#changed();
+        if (PHASES[this.#lifecycle.phase].connects)
+            this.#connect();
+        return lease;
+    }
+    #release(lease) {
+        if (!this.#leases.delete(lease))
+            return;
+        this.#changed();
+        if (!this.#leases.size)
+            this.provider.awareness.setLocalState(null);
+    }
+    /** Reconnects with this session's current grant, which is the original one or the last one a refresh returned. */
+    retry() {
+        if (this.#transition("retry"))
+            this.#connect();
+    }
+    /** Closes the session and drops pending work. The application calls this explicitly, because an ordinary detach keeps pending work. */
+    discard() { this.#close(); }
+    #changed() {
+        this.#dirty = true;
+        if (this.#settleQueued)
+            return;
+        this.#settleQueued = true;
+        queueMicrotask(() => this.#settle());
+    }
+    #settle() {
+        this.#settleQueued = false;
+        // If editor cleanup retries or blocks during #enforce, #changed queues
+        // another settle to handle it.
+        this.#enforce();
+        if (!this.#dirty)
+            return;
+        this.#dirty = false;
+        this.store[notifyStoreChange](this);
+    }
+    #enforce() {
+        if (this.state === "closed")
+            return;
+        if (this.state === "blocked") {
+            const retiring = this.#retiring;
+            this.#retiring = undefined;
+            // Leave the queue alone until retry() or discard().
+            for (const lease of retiring ?? [])
+                lease.release();
+            return;
+        }
+        if (!this.#needed())
+            this.#close();
+    }
+    // Connect with the current grant, or resubscribe with a renewed one. The
+    // provider defers its own callbacks, so a failure here only blocks.
+    #connect(grant) {
+        try {
+            if (grant === undefined)
+                this.provider.connect();
+            else
+                this.provider.renew({ grant });
+        }
+        catch (error) {
+            this.#transition("block", error);
+        }
+    }
+    #needed() { return this.#leases.size > 0 || this.provider.hasPending; }
+    // The only method that changes the phase. It doesn't call out to other code,
+    // and #settle acts on the result.
+    #transition(event, error) {
+        const phase = PHASES[this.#lifecycle.phase].on[event];
+        if (!phase)
+            return false;
+        this.#lifecycle = { phase };
+        this.#retiring = phase === "blocked" ? [...this.#leases] : undefined;
+        if (event === "retry")
+            this.#error = undefined;
+        else if (event === "block")
+            this.#error = error;
+        this.#changed();
+        return true;
+    }
+    #close() {
+        if (!this.#transition("close"))
+            return;
+        // Leave the store first so editor cleanup below can acquire a new session.
+        this.remove();
+        for (const lease of [...this.#leases])
+            lease.release();
+        this.provider.destroy();
+        this.doc.destroy();
+    }
+    // Try the refresh URL once per rejection. Block if the server rejects again
+    // while refreshing or rejects the renewed grant.
+    #rejected(error) {
+        const url = this.descriptor.refresh;
+        if (url && this.#transition("refresh"))
+            void this.#refresh(url, this.#lifecycle);
+        else
+            this.#transition("block", error);
+    }
+    async #refresh(url, attempt) {
+        let grant;
+        try {
+            grant = await fetchGrant(url);
+        }
+        catch (error) {
+            if (this.#lifecycle === attempt)
+                this.#transition("block", error);
+            return;
+        }
+        // A retry, discard, or block during the request takes precedence over it.
+        if (this.#lifecycle !== attempt)
+            return;
+        if (this.#transition("renew"))
+            this.#connect(grant);
+    }
+}
+/** Ask the application for a new grant. Resolves to the grant or throws. */
+async function fetchGrant(url) {
+    const response = await fetch(url, {
+        credentials: "same-origin",
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS),
+    });
+    if (!response.ok)
+        throw new Error(`grant refresh failed: ${response.status}`);
+    const body = await response.json();
+    const grant = body?.grant;
+    if (typeof grant !== "string" || !grant)
+        throw new Error("grant refresh returned no grant");
+    return grant;
+}
+//# sourceMappingURL=document_session.js.map

package/dist/document_session.js.map

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

package/dist/index.d.ts

@@ -5,4 +5,6 @@ export type { YProtocolSessionOptions } from "./y_protocol_session.js";
 export { ActionCableProvider } from "./actioncable_provider.js";
 export type { ActionCableProviderOptions, ProviderStatus, StatusEvent, CableConsumer, CableSubscription, } from "./actioncable_provider.js";
 export { toBase64, fromBase64 } from "./base64.js";
+export { DocumentSessionStore } from "./document_session.js";
+export type { DocumentSession, DocumentLease, DocumentDescriptor, DocumentSessionState } from "./document_session.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAI3E,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACxE,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAIvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,YAAY,EACV,0BAA0B,EAC1B,cAAc,EACd,WAAW,EACX,aAAa,EACb,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAI3E,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACxE,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAIvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,YAAY,EACV,0BAA0B,EAC1B,cAAc,EACd,WAAW,EACX,aAAa,EACb,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -8,4 +8,6 @@ export { YProtocolSession, MessageType } from "./y_protocol_session.js";
 export { ActionCableProvider } from "./actioncable_provider.js";
 // Optional base64 helpers for transports that carry frames as strings.
 export { toBase64, fromBase64 } from "./base64.js";
+// Document sessions, leased by editors or held by headless workflows.
+export { DocumentSessionStore } from "./document_session.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,6DAA6D;AAC7D,6CAA6C;AAC7C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAGxE,6DAA6D;AAC7D,iEAAiE;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAShE,uEAAuE;AACvE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,6DAA6D;AAC7D,6CAA6C;AAC7C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAGxE,6DAA6D;AAC7D,iEAAiE;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAShE,uEAAuE;AACvE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEnD,sEAAsE;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/reliable_sync.d.ts

@@ -14,46 +14,33 @@ export interface ReliableSyncOptions {
     setInterval?: (handler: () => void, ms: number) => TimerHandle;
     clearInterval?: (handle: TimerHandle) => void;
 }
-interface Pending {
-    seq: number;
-    update: Uint8Array;
+/** One queued update and the sequence number an ack must reach to remove it. */
+export interface Pending {
+    readonly seq: number;
+    readonly update: Uint8Array;
 }
 export declare class ReliableSync {
     #private;
-    /** Unacked local updates, in order. */
-    pending: Pending[];
     constructor(opts: ReliableSyncOptions);
+    /** A snapshot of unacknowledged local updates, oldest first. Editing it does not change the queue. */
+    get pending(): readonly Pending[];
     /** True while there are unacknowledged local updates. */
     get hasPending(): boolean;
-    /**
-     * Record a local document update. It is queued and the unacked tail is
-     * flushed; the update remains retained until the server acknowledges it.
-     */
+    /** Queue a local update and, while connected, send the tail. Ignored after destroy(). */
     enqueue(update: Uint8Array): void;
     /**
-     * Send the whole unacked tail as one merged delta. The id is the highest seq
-     * in the batch, so a single { ack } cumulatively confirms everything up to it.
-     * No-op while disconnected (the tail is replayed on the next onConnect).
-     */
-    flush(): void;
-    /**
-     * Confirm delivery up to `id`: prune every queued update with seq <= id.
-     * Acks arrive over the wire, so validate before pruning. A malformed value
-     * (NaN/string/negative) or an impossible future id must not silently drop the
-     * queue; invalid acks are ignored.
-     */
-    onAck(id: number): void;
-    /** Transport (re)connected: replay the unacked tail and resume retransmits. */
-    onConnect(): void;
-    /** Transport dropped: keep the queue (for reconnect replay), pause the timer. */
-    onDisconnect(): void;
-    /**
-     * One retransmit tick. Exposed for deterministic testing; normally driven by
-     * the internal timer.
+     * Confirm delivery through `id`, removing every queued update with
+     * seq <= id. Acks come off the wire, so ignore a malformed value or an id
+     * beyond anything sent.
      */
-    onTick(): void;
-    /** Stop timers and drop references. Call when the provider is destroyed. */
+    acknowledge(id: number): void;
+    /** Call when the transport is up. Replays the tail and keeps retransmitting until it is acknowledged. */
+    resume(): void;
+    /** Call when the transport is down. Keeps the queue and stops retransmitting. */
+    pause(): void;
+    /** Send the tail again if anything is unacknowledged. The internal timer calls this, and a host with its own scheduler can too. */
+    retransmit(): void;
+    /** Stop the timer and drop the queue. Later enqueues are ignored. */
     destroy(): void;
 }
-export {};
 //# sourceMappingURL=reliable_sync.d.ts.map

package/dist/reliable_sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reliable_sync.d.ts","sourceRoot":"","sources":["../src/reliable_sync.ts"],"names":[],"mappings":"AAgBA,oEAAoE;AACpE,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC;AAElC,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C,gFAAgF;IAChF,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,CAAC;IAC7C,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,WAAW,CAAC;IAC/D,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CAC/C;AAID,UAAU,OAAO;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,qBAAa,YAAY;;IACvB,uCAAuC;IACvC,OAAO,EAAE,OAAO,EAAE,CAAM;gBAeZ,IAAI,EAAE,mBAAmB;IAiBrC,yDAAyD;IACzD,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAOjC;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAKb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQvB,+EAA+E;IAC/E,SAAS,IAAI,IAAI;IAMjB,iFAAiF;IACjF,YAAY,IAAI,IAAI;IAKpB;;;OAGG;IACH,MAAM,IAAI,IAAI;IAKd,4EAA4E;IAC5E,OAAO,IAAI,IAAI;CA2BhB"}
+{"version":3,"file":"reliable_sync.d.ts","sourceRoot":"","sources":["../src/reliable_sync.ts"],"names":[],"mappings":"AAmBA,oEAAoE;AACpE,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC;AAElC,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C,gFAAgF;IAChF,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,CAAC;IAC7C,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,WAAW,CAAC;IAC/D,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CAC/C;AAED,gFAAgF;AAChF,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AASD,qBAAa,YAAY;;gBAkBX,IAAI,EAAE,mBAAmB;IAgBrC,sGAAsG;IACtG,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED,yDAAyD;IACzD,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,yFAAyF;IACzF,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAOjC;;;;OAIG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQ7B,yGAAyG;IACzG,MAAM,IAAI,IAAI;IAQd,iFAAiF;IACjF,KAAK,IAAI,IAAI;IAOb,mIAAmI;IACnI,UAAU,IAAI,IAAI;IAIlB,qEAAqE;IACrE,OAAO,IAAI,IAAI;CAwDhB"}