@synapse-sdk/client 0.3.3 → 0.3.6

package/dist/store.js

@@ -6,13 +6,14 @@
 // here. A refusal is asked again, paced, with a warning (R6); a transient reply paced, silently; an
 // incarnation that ends (writer gone, project switch, the owner restarted) replays the intent;
 // `destroyed` ends the handle. Writes name the epoch the mirror holds; the runtime checks ownership
-// (`not_owner`). Between incarnations (a session change, a replay) nothing is known: `store_gone`.
+// (`not_owner`). Between incarnations (a session change, a replay) nothing is known: a write then is
+// parked by the task and sent once the handle binds again (`store_gone` if it ends first).
 import * as Moq from "@moq/net";
 import { FLAGS, STORE_TRACK, SynapseError, decode as decodeBody, decodeHeader, moqPriority, storeBasePath, storeRobotScoped, } from "@synapse-sdk/core";
 import { startOn } from "./calls.js";
 import { REFOLLOW_PACE_MS, holderOf, isTransient, refusalPaceMs } from "./channel.js";
 import { latestSubscription, waitActive } from "./session.js";
-import { AsyncQueue, TIMEOUT, deferred, withTimeout } from "./util.js";
+import { AsyncQueue, StatusCell, TIMEOUT, deferred, withTimeout } from "./util.js";
 export const ENDED_DESTROYED = "destroyed";
 export const ENDED_CONNECTION_LOST = "connection_lost";
 export const ENDED_CLIENT = "client";
@@ -20,7 +21,7 @@ const ENDED_STORE_GONE = "store_gone";
 /** A watcher this many batches behind is ended, never grown. */
 export const STORE_FEED_CAP = 256;
 /** How long an incarnation the open's reply named has to show up on the announcement cursor (no "live" marker in @moq/net's JS cursor). */
-const ANNOUNCE_WITHIN_MS = 1000;
+export const ANNOUNCE_WITHIN_MS = 1000;
 const isFinal = (reason) => reason === ENDED_DESTROYED;
 const gone = (name, why) => new SynapseError("store_gone", `store ${JSON.stringify(name)}: ${why}`);
 // ------------------------------------------------------------------------------------- state
@@ -38,7 +39,8 @@ export class State {
     onDeath;
     absent = false;
     loaded = false;
-    gap = false;
+    /** A diff skipped a version (not applied; the track is read again from its snapshot): the highest version seen then. Cleared once the copy is back at it (PLAN v0.34 §2.2). */
+    gap;
     pending = 0;
     ended;
     #listeners = new Set();
@@ -91,13 +93,22 @@ export class State {
         this.onDeath = s.on_death;
         this.absent = false;
         this.loaded = true;
-        this.gap = false;
+        this.#heal();
         this.#emit(records);
     }
+    /** A gap is over once the copy is back at the highest version seen when it opened. */
+    #heal() { if (this.gap !== undefined && this.version >= this.gap)
+        this.gap = undefined; }
+    /**
+     * One diff, applied when it is the next version. Otherwise it is not applied (`false`): a gap, `synced` false until the
+     * copy is back at the version seen; the reader reads the track again from its snapshot (PLAN v0.34 §2.2).
+     */
     applyDiff(d, warn) {
         if (d.version !== this.version + 1) {
-            warn(`store: diff out of sequence (have ${this.version}, got ${d.version}); not synced until the next snapshot`);
-            this.gap = true;
+            warn(`store: diff out of sequence (have ${this.version}, got ${d.version}): not applied; reading the track again from its snapshot`);
+            this.gap = Math.max(this.gap ?? d.version, d.version);
+            this.#notify();
+            return false;
         }
         const records = [];
         const flat = new Map(this.flat);
@@ -118,7 +129,9 @@ export class State {
         }
         this.flat = flat;
         this.version = d.version;
+        this.#heal();
         this.#emit(records);
+        return true;
     }
     #clear() {
         const records = [...this.rows].map(([key, r]) => ({ kind: "delete", key, previousValue: r.v, by: undefined }));
@@ -134,7 +147,7 @@ export class State {
         this.epoch = undefined;
         this.version = 0;
         this.loaded = false;
-        this.gap = false;
+        this.gap = undefined;
         this.mode = undefined;
         this.owner = undefined;
         this.mine = false;
@@ -150,7 +163,7 @@ export class State {
         this.epoch = undefined;
         this.version = 0;
         this.loaded = false;
-        this.gap = false;
+        this.gap = undefined;
         this.mode = a?.mode;
         this.owner = a?.owner ?? undefined;
         this.mine = a?.mine ?? false;
@@ -176,7 +189,7 @@ export class State {
     status(nodeConnected, closed = false) {
         const ended = closed ? ENDED_CLIENT : this.ended;
         const connected = ended === undefined && nodeConnected;
-        return { synced: connected && this.pending === 0 && !this.gap && (this.loaded || this.absent), connected, pending: this.pending, mode: this.mode, owner: this.owner, mine: this.mine, minRole: this.minRole, onDeath: this.onDeath, absent: this.absent, version: this.version, epoch: this.epoch, ended };
+        return { synced: connected && this.pending === 0 && this.gap === undefined && (this.loaded || this.absent), connected, pending: this.pending, mode: this.mode, owner: this.owner, mine: this.mine, minRole: this.minRole, onDeath: this.onDeath, absent: this.absent, version: this.version, epoch: this.epoch, ended };
     }
 }
 function sameValue(a, b) {
@@ -206,6 +219,7 @@ export class Namespace {
     mailbox = new AsyncQueue(Infinity);
     exited = deferred();
     handles = 0;
+    nextHandle = 0;
     constructor(name, opts, node, warn) {
         this.name = name;
         this.opts = opts;
@@ -239,6 +253,9 @@ async function run(ns, registry) {
     let unwatchProject;
     const joining = [];
     let versionWaiters = [];
+    /** Writes that came while no incarnation was bound (a replay, or no session yet), in arrival order: sent once the handle binds again, refused `store_gone` if it ends first. Each counts in `pending`. */
+    let parked = [];
+    const ABSENT = "the namespace is absent: open it with an access mode to create it";
     const leaveIncarnation = () => { for (const w of versionWaiters.splice(0))
         w.reply.reject(gone(name, `the handle left the incarnation before version ${w.version}`)); };
     const stopPhase = () => {
@@ -358,9 +375,12 @@ async function run(ns, registry) {
             const done = follow(ns, s, announced, access?.epoch, stop.signal);
             phase = { kind: "following", attempt, stop, done };
             void done.then(reason => post({ kind: "followEnded", attempt, reason }));
-            if (!access)
+            // Absent: honestly in (nothing to load), and nothing to write to (the parked writes are refused).
+            if (!access) {
                 for (const j of joining.splice(0))
                     j.resolve();
+                refuseParked(ABSENT);
+            }
             return;
         }
         announced.close();
@@ -389,6 +409,9 @@ async function run(ns, registry) {
         if (state.loaded && state.epoch === epoch && state.version >= wanted)
             for (const j of joining.splice(0))
                 j.resolve();
+        // The handle is bound again (the reader applied the snapshot that names the epoch): the writes parked meanwhile go out, in order, naming it.
+        if (state.ended === undefined && state.epoch !== undefined)
+            sendParked();
     };
     const join = (reply) => {
         if (phase.kind === "waitingProject") {
@@ -426,14 +449,53 @@ async function run(ns, registry) {
                 again(REFOLLOW_PACE_MS);
         }
     };
-    const write = (op, args, reply) => {
+    /**
+     * A write. Ended or absent: `store_gone`. Between incarnations (a replay, or no session yet) it is parked: a write is
+     * intent, sent once the handle binds again (the runtime decides it then), refused `store_gone` if the handle ends first;
+     * it has no deadline of its own. Bound: sent after any parked before it, naming the mirror's epoch (and claim).
+     */
+    const write = (handle, op, args, reply) => {
         if (state.ended !== undefined) {
             reply.reject(gone(name, `the handle ended (${state.ended})`));
             return;
         }
+        if (state.epoch === undefined) {
+            if (state.absent) {
+                reply.reject(gone(name, ABSENT));
+                return;
+            }
+            parked.push({ handle, op, args, reply });
+            state.setPending(state.pending + 1);
+            return;
+        }
+        sendParked();
+        send(op, args, reply);
+    };
+    /** The parked writes go out, in arrival order (the handle is bound). */
+    const sendParked = () => {
+        if (!parked.length)
+            return;
+        const ws = parked;
+        parked = [];
+        state.setPending(state.pending - ws.length);
+        for (const w of ws)
+            send(w.op, w.args, w.reply);
+    };
+    /** The parked writes are refused `store_gone` (`why`): all of them (the handle ended, or the namespace is absent), or those of handle `of` (that handle was closed, others stay open). */
+    const refuseParked = (why, of) => {
+        const ws = parked.filter(w => of === undefined || w.handle === of);
+        if (!ws.length)
+            return;
+        parked = parked.filter(w => !ws.includes(w));
+        state.setPending(state.pending - ws.length);
+        for (const w of ws)
+            w.reply.reject(gone(name, why));
+    };
+    /** One write on the wire, naming the bound epoch (and claim); answered by the broker (`writeDone`). */
+    const send = (op, args, reply) => {
         const epoch = state.epoch;
         if (epoch === undefined) {
-            reply.reject(state.absent ? gone(name, "the namespace is absent: open it with an access mode to create it") : gone(name, "no incarnation is bound: the intent is being replayed"));
+            reply.reject(gone(name, "no incarnation is bound"));
             return;
         }
         if (!session) {
@@ -534,7 +596,10 @@ async function run(ns, registry) {
                     waitVersion(ev.epoch, ev.version, ev.reply);
                     break;
                 case "write":
-                    write(ev.op, ev.args, ev.reply);
+                    write(ev.handle, ev.op, ev.args, ev.reply);
+                    break;
+                case "leave":
+                    refuseParked(`the handle ended (${ENDED_CLIENT})`, ev.handle);
                     break;
                 case "writeDone":
                     if (writeDone(ev.op, ev.result, ev.reply)) {
@@ -567,6 +632,7 @@ async function run(ns, registry) {
         for (const j of joining.splice(0))
             j.reject(e);
         leaveIncarnation();
+        refuseParked(`the handle ended (${state.ended ?? reason ?? ENDED_CLIENT})`);
         {
             const p = ph();
             if (p.kind === "following" || p.kind === "paced")
@@ -580,7 +646,7 @@ async function run(ns, registry) {
             if (ev.kind === "writeDone")
                 writeDone(ev.op, ev.result, ev.reply);
             else if (ev.kind === "write")
-                write(ev.op, ev.args, ev.reply);
+                write(ev.handle, ev.op, ev.args, ev.reply);
             else if (ev.kind === "opened") {
                 const p = ph();
                 if (p.kind === "opening" && p.o.attempt === ev.attempt) {
@@ -632,7 +698,8 @@ function announcedEpoch(base, prefix) {
 /**
  * Reads the incarnation the open bound (`want`; `undefined`: absent, the first one announced), writing
  * the mirror and telling the task of each frame applied; returns how the track ended (`undefined`:
- * no final frame — the session, or the broker, went; the task replays).
+ * no final frame — the session, or the broker, went; the task replays). A diff out of sequence is not applied: the
+ * subscription is let go and the track subscribed again, which delivers the open group from its snapshot (PLAN v0.34 §2.2).
  */
 async function follow(ns, session, announced, want, signal) {
     const { state, warn, name } = ns;
@@ -685,74 +752,86 @@ async function follow(ns, session, announced, want, signal) {
             return undefined;
         }
         announced.close();
-        sub = bc.track(STORE_TRACK).subscribe(latestSubscription(moqPriority(1)));
-        const s = sub;
+        const track = bc.track(STORE_TRACK);
         // Closing the subscriber ends `recvGroup`, not a read on the group it already handed us: that group is closed too.
         let g;
-        signal.addEventListener("abort", () => { s.close(); g?.close(); }, { once: true });
-        // The first group read is the open one, from its start: a snapshot, then the diffs.
-        for (;;) {
-            g = await s.recvGroup();
-            if (!g)
-                break;
+        signal.addEventListener("abort", () => { sub?.close(); g?.close(); }, { once: true });
+        // A gap: this subscription is let go and the track subscribed again, which delivers the open group from its
+        // snapshot (PLAN v0.34 §2.2; no counter, no timer).
+        subscribe: for (;;) {
+            if (signal.aborted)
+                return undefined;
+            try {
+                sub?.close();
+            }
+            catch { /* closed */ }
+            const s = sub = track.subscribe(latestSubscription(moqPriority(1)));
+            // The first group read is the open one, from its start: a snapshot, then the diffs.
             for (;;) {
-                let f;
-                try {
-                    f = await g.readFrame();
-                }
-                catch {
-                    break;
-                }
-                if (!f)
+                g = await s.recvGroup();
+                if (!g)
                     break;
-                let header, hlen;
-                try {
-                    ({ header, hlen } = decodeHeader(f.payload));
-                }
-                catch {
-                    warn(`store ${name}: frame not decodable`);
-                    continue;
-                }
-                let body;
-                try {
-                    body = decodeBody(f.payload.subarray(hlen));
-                }
-                catch {
-                    warn(`store ${name}: frame body not decodable`);
-                    continue;
-                }
-                if (header.flags & FLAGS.END) {
-                    const fin = body;
-                    return fin && typeof fin.reason === "string" ? fin.reason : ENDED_STORE_GONE;
-                }
-                // A stopped reader no longer writes the mirror: it belongs to the next incarnation (or to none).
-                if (header.flags & FLAGS.KEY) {
-                    const snap = body;
-                    if (!snap || snap.epoch !== epoch) {
-                        warn(`store ${name}: snapshot of another epoch dropped`);
-                        continue;
+                for (;;) {
+                    let f;
+                    try {
+                        f = await g.readFrame();
                     }
-                    if (signal.aborted)
-                        continue;
-                    if (state.ended === undefined)
-                        state.applySnapshot(snap);
-                    ns.post({ kind: "applied", epoch, version: snap.version });
-                }
-                else if (header.flags & FLAGS.DELTA) {
-                    const diff = body;
-                    if (!diff || typeof diff.version !== "number") {
-                        warn(`store ${name}: diff not decodable`);
+                    catch {
+                        break;
+                    }
+                    if (!f)
+                        break;
+                    let header, hlen;
+                    try {
+                        ({ header, hlen } = decodeHeader(f.payload));
+                    }
+                    catch {
+                        warn(`store ${name}: frame not decodable`);
                         continue;
                     }
-                    if (signal.aborted)
+                    let body;
+                    try {
+                        body = decodeBody(f.payload.subarray(hlen));
+                    }
+                    catch {
+                        warn(`store ${name}: frame body not decodable`);
                         continue;
-                    if (state.ended === undefined && state.loaded)
-                        state.applyDiff(diff, warn);
-                    ns.post({ kind: "applied", epoch, version: diff.version });
+                    }
+                    if (header.flags & FLAGS.END) {
+                        const fin = body;
+                        return fin && typeof fin.reason === "string" ? fin.reason : ENDED_STORE_GONE;
+                    }
+                    // A stopped reader no longer writes the mirror: it belongs to the next incarnation (or to none).
+                    if (header.flags & FLAGS.KEY) {
+                        const snap = body;
+                        if (!snap || snap.epoch !== epoch) {
+                            warn(`store ${name}: snapshot of another epoch dropped`);
+                            continue;
+                        }
+                        if (signal.aborted)
+                            continue;
+                        if (state.ended === undefined)
+                            state.applySnapshot(snap);
+                        ns.post({ kind: "applied", epoch, version: snap.version });
+                    }
+                    else if (header.flags & FLAGS.DELTA) {
+                        const diff = body;
+                        if (!diff || typeof diff.version !== "number") {
+                            warn(`store ${name}: diff not decodable`);
+                            continue;
+                        }
+                        if (signal.aborted)
+                            continue;
+                        if (state.ended === undefined && state.loaded && !state.applyDiff(diff, warn)) {
+                            g.close();
+                            continue subscribe;
+                        }
+                        ns.post({ kind: "applied", epoch, version: diff.version });
+                    }
                 }
             }
+            return undefined; // the track ended with no final frame: the session (or the broker) went
         }
-        return undefined; // the track ended with no final frame: the session (or the broker) went
     }
     catch {
         return undefined;
@@ -771,31 +850,39 @@ async function follow(ns, session, announced, want, signal) {
 export class StoreHandleImpl {
     ns;
     #closed = false;
+    /** This handle's id in its namespace: its parked writes are refused when it closes. */
+    #id;
     /** Resolved when this handle closes: its version waits end. */
     #left = deferred();
     /** This handle's change feeds: closed with it. */
     #feeds = new Set();
     #valueObj;
     #valueOf;
+    /** Told when this handle closes (its status says `ended: client` from then on, whatever the namespace does). */
+    #onClose = new Set();
+    /** The handle's own state, a state value: `get()` (the same object while unchanged), `onChange`, `changed()`, `watch()`. */
+    status;
+    #status;
     constructor(ns) {
         this.ns = ns;
         ns.handles++;
+        this.#id = ns.nextHandle++;
+        this.status = this.#status = new StatusCell(() => this.ns.state.status(this.ns.node.isConnected, this.#closed), l => { const un = this.ns.state.subscribe(l); this.#onClose.add(l); return () => { un(); this.#onClose.delete(l); }; }, () => this.#closed || this.ns.state.ended !== undefined);
     }
     #ended() { return gone(this.ns.name, `the handle ended (${ENDED_CLIENT})`); }
     get name() { return this.ns.name; }
-    /** The whole value, what the runtime has; the same object while nothing changed (reference-stable for React). */
-    get value() {
+    get(key) {
         const flat = this.ns.state.flat;
+        if (key !== undefined)
+            return flat.get(key);
         if (this.#valueOf !== flat) {
             this.#valueOf = flat;
             this.#valueObj = Object.fromEntries(flat);
         }
         return this.#valueObj;
     }
-    get(key) { return this.ns.state.flat.get(key); }
-    get synced() { return this.status.synced; }
-    get status() { return this.ns.state.status(this.ns.node.isConnected, this.#closed); }
-    /** `set(key, value)` or `set({ ...several keys })` (one atomic write); resolves once `value` shows it. */
+    get synced() { return this.status.get().synced; }
+    /** `set(key, value)` or `set({ ...several keys })` (one atomic write); resolves once `get()` shows it. */
     async set(keyOrValues, value) {
         const v = typeof keyOrValues === "string" ? await this.#write("put", { key: keyOrValues, value }) : await this.#write("put_many", { values: keyOrValues });
         await this.#reached(v);
@@ -803,11 +890,11 @@ export class StoreHandleImpl {
     async delete(key) { await this.#reached(await this.#write("delete", { key })); }
     async clear() { await this.#reached(await this.#write("clear", {})); }
     async destroy() { await this.#write("destroy", {}); }
-    /** The wire half of a write: the runtime's answer, the version it assigned. */
+    /** The wire half of a write: the runtime's answer, the version it assigned (between incarnations the task holds it until the handle binds again). */
     async #write(op, args) {
         if (this.#closed)
             throw this.#ended();
-        const r = await this.ns.request(reply => ({ kind: "write", op, args, reply }));
+        const r = await this.ns.request(reply => ({ kind: "write", handle: this.#id, op, args, reply }));
         const v = r?.version;
         return typeof v === "number" ? v : typeof v === "bigint" ? Number(v) : 0;
     }
@@ -830,7 +917,7 @@ export class StoreHandleImpl {
         try {
             for await (const batch of q) {
                 if (key === undefined)
-                    yield this.value;
+                    yield this.get();
                 else if (batch.some(c => c.key === key))
                     yield this.ns.state.flat.get(key);
             }
@@ -840,12 +927,30 @@ export class StoreHandleImpl {
             this.ns.state.unwatch(q);
         }
     }
-    /** The framework bridge (React's `useStore`): called on every change of the value or the status. */
-    subscribe(listener) { return this.ns.state.subscribe(listener); }
-    /** Waits for the namespace to be in (the first snapshot applied, or absent). */
-    join() { return this.ns.request(reply => ({ kind: "join", reply })); }
-    /** `join()` under the SDK's word (Publisher and Registration have `ready()` too). */
-    ready() { return this.join(); }
+    changed(key) {
+        if (this.#closed)
+            return Promise.reject(this.#ended());
+        if (key !== undefined) {
+            // the first step of `watch(key)`, started now (its feed opens at the first `next()`), then left
+            const it = this.watch(key)[Symbol.asyncIterator]();
+            return it.next().then(r => { void it.return(undefined); if (r.done)
+                throw this.#ended(); return r.value; });
+        }
+        const from = this.get();
+        const d = deferred();
+        const un = this.ns.state.subscribe(() => { const v = this.get(); if (v !== from) {
+            un();
+            this.#onClose.delete(gone);
+            d.resolve(v);
+        } });
+        const gone = () => { un(); this.#onClose.delete(gone); d.reject(this.#ended()); };
+        this.#onClose.add(gone);
+        return d.promise;
+    }
+    /** `cb` with the whole value on every change of the value or the status (the framework bridge, React's `useStore`); returns the remover. */
+    onChange(cb) { return this.ns.state.subscribe(() => cb(this.get())); }
+    /** Waits for the namespace to be in: the value current as of the open (the version the runtime answered applied), or the namespace absent. */
+    ready() { return this.ns.request(reply => ({ kind: "join", reply })); }
     close() {
         if (this.#closed)
             return;
@@ -854,18 +959,29 @@ export class StoreHandleImpl {
         for (const q of this.#feeds)
             this.ns.state.unwatch(q);
         this.#feeds.clear();
+        for (const l of [...this.#onClose]) {
+            try {
+                l();
+            }
+            catch (e) {
+                queueMicrotask(() => { throw e; });
+            }
+        }
+        this.#onClose.clear();
+        this.#status.dispose();
         if (--this.ns.handles === 0)
             this.ns.post({ kind: "close" });
+        else
+            this.ns.post({ kind: "leave", handle: this.#id });
     }
     async [Symbol.asyncDispose]() { this.close(); }
 }
 /**
  * `store(name, opts)`: one task per namespace per node; a second `store` with the same options joins
- * it (no open written), with other options `invalid_input`; one exiting is waited out.
+ * it (no open written), with other options `invalid_input`; one exiting is waited out. Without a session
+ * (before the first, between two) the task waits for the next one, like after a drop; it resolves once in.
  */
 export async function openStore(node, registry, name, opts, warn) {
-    if (!node.currentSession())
-        throw new SynapseError("not_connected");
     for (;;) {
         const live = registry.get(name);
         if (live) {
@@ -877,7 +993,7 @@ export async function openStore(node, registry, name, opts, warn) {
                 throw new SynapseError("invalid_input", `store ${JSON.stringify(name)}: this node already has it open with other options`);
             const h = new StoreHandleImpl(live);
             try {
-                await h.join();
+                await h.ready();
             }
             catch (e) {
                 h.close();
@@ -890,7 +1006,7 @@ export async function openStore(node, registry, name, opts, warn) {
         const h = new StoreHandleImpl(ns);
         startNamespace(ns, registry);
         try {
-            await h.join();
+            await h.ready();
         }
         catch (e) {
             h.close();