@synapse-sdk/client 0.3.0 → 0.3.4

package/dist/node.js

@@ -1,14 +1,14 @@
 // The node (SDK §2, WP §10): the permanent thing. It owns this node's intents (the handle registries
-// live on the handles' modules), its declared target, and ONE lifecycle cell (`Link`) that says where
+// live on the handles' modules), its declared target, and ONE lifecycle `Cell` (`Link`) that says where
 // the node stands and, when connected, names the session. It holds no fact the broker told us: those
 // are the current `Session`'s. One loop (`run`) is the only driver: it dials, attaches, waits, tears
-// down, and answers `close()` and `setTarget()` by reply. Handles are told about sessions as a
-// message in their own mailbox (`monitor`), never by watching a cell. Nothing on the wire is
+// down, and answers `close()` and every target change (`declare`) by reply. Handles are told about sessions as a
+// message in their own mailbox (`monitor`), never by watching a `Cell`. Nothing on the wire is
 // resumable: a new session means a fresh `req` track, fresh announces, fresh subscriptions, which
 // the handles replay when told.
 import { ClockSync, SynapseError, calibrateMonotonicClock, defaultDomId, isValidClientName, mintName, mintUserId, nowUs } from "@synapse-sdk/core";
 import { closeOnSignals, forgetOnSignals } from "./signals.js";
-import { Session, closeError, defaultMaxDatagram, discoverBrokerCertSha256, openSession } from "./session.js";
+import { Session, closeError, defaultMaxDatagram, discoverBrokerCertSha256, makeDial, openSession, urlOrEndpoint } from "./session.js";
 import { startOn } from "./calls.js";
 import { AsyncQueue, Cell, deferred } from "./util.js";
 // ------------------------------------------------------------------------------------- policy
@@ -27,6 +27,7 @@ export function withMaxAttempts(p, maxAttempts) {
 export const defaultReconnectPolicy = exponentialPolicy(100, 10_000);
 export function stateOf(l) {
     switch (l.status) {
+        case "idle": return { status: "idle" };
         case "connected": return { status: "connected", url: l.session.url, sinceMs: l.session.startedMs };
         case "connecting": return { status: "connecting", attempt: l.attempt };
         case "reconnecting": return { status: "reconnecting", attempt: l.attempt, reason: l.reason, error: l.error, nextRetryAtMs: l.nextRetryAtMs };
@@ -35,7 +36,14 @@ export function stateOf(l) {
         case "failed": return { status: "failed", error: l.error };
     }
 }
-/** The rules (SDK §2, WP §10.4) for the delay before attempt `attempt`. */
+/** How long the first pursuit of a declared target (`connect()`) keeps trying a retryable failure before `failed` (SDK §2: a hard bound; the same value in every SDK). */
+export const FIRST_CONNECT_GIVE_UP_MS = 30_000;
+/**
+ * The rules (SDK §2, WP §10.4) for the delay before attempt `attempt`. `unauthorized` gives up in every pursuit. The first
+ * connect retries only retryable errors and only until its deadline (the loop cuts the pause and the attempt at it; the
+ * delay is not cut here); with no policy it uses the default. Giving up is `failed` in every pursuit: the node rests
+ * until a new target.
+ */
 export function decide(pursuit, policy, err, attempt, nowMs) {
     if (err.code === "unauthorized")
         return { kind: "failed" };
@@ -43,43 +51,56 @@ export function decide(pursuit, policy, err, attempt, nowMs) {
     if (pursuit.kind === "first") {
         if (!err.retryable || nowMs >= pursuit.deadlineMs)
             return { kind: "failed" };
-        const d = (policy ?? defaultReconnectPolicy).nextRetryDelayMs({ attempt });
-        delay = d === null ? null : Math.min(d, pursuit.deadlineMs - nowMs);
+        delay = (policy ?? defaultReconnectPolicy).nextRetryDelayMs({ attempt });
     }
     else
         delay = policy ? policy.nextRetryDelayMs({ attempt }) : null;
     if (delay !== null)
         return { kind: "retry", delayMs: delay };
-    return pursuit.kind === "reconnect" ? { kind: "closed" } : { kind: "failed" };
+    return { kind: "failed" };
+}
+/** The first connect's give-up when its bound cut an attempt: `last`, the previous attempt's error (when there was one), is its cause. */
+function gaveUp(boundMs, last) {
+    return new SynapseError(last?.code ?? "connection_lost", { message: `the first connect gave up after ${boundMs} ms${last ? ` (last attempt: ${last.message})` : ""}`, ...(last ? { cause: last } : {}) });
 }
 // ---------------------------------------------------------------------------------------- node
 export class Node {
-    link = new Cell({ status: "connecting", attempt: 1 });
+    link = new Cell({ status: "idle" });
     target;
+    /** The node's time domain; final once `prepared` resolved (the loop dials, and publishers describe themselves, only after). */
     dom;
+    /** Resolves once the time domain is final (the host's monotonic clock read, its domain id derived). */
+    prepared;
     knobs;
     policy;
+    /** Bun/Node: close on SIGINT/SIGTERM once a target is declared (not at construction: constructing opens nothing). */
+    signals;
     /** Broker notices addressed to this node, across its sessions (fed by the loop from the current session's). */
     notices = new Set();
     projectNotices = new Set();
-    /** Resolves once the node has ended for good (`close()`, the first connect failing, the policy giving up). */
+    /** Resolves once the node has ended for good: `close()`, and nothing else. */
     ended = deferred();
     #endedFlag = false;
-    /** The loop's mailbox: unbounded, so no `close()` or `setTarget()` is ever dropped. */
+    /** The loop's mailbox: unbounded, so no `close()` or target change is ever dropped. */
     #commands = new AsyncQueue(Infinity);
     #monitors = new Set();
     epochs = 0;
     reconnects = 0;
     callsSent = 0;
     callsAnswered = 0;
-    constructor(target, dom, knobs, policy) {
+    /** `finalDom`: the time domain once known, when `dom` is only provisional (see `createNode`). */
+    constructor(target, dom, knobs, policy, opts = {}) {
         this.target = new Cell(target);
         this.dom = dom;
         this.knobs = knobs;
         this.policy = policy;
+        this.signals = opts.signals ?? false;
+        this.prepared = opts.finalDom ? opts.finalDom.then(d => { this.dom = d; }) : Promise.resolve();
     }
     get isEnded() { return this.#endedFlag; }
     get isConnected() { return this.link.get().status === "connected"; }
+    /** Whether the node rests `failed` on target `generation` (a `failed` of an older target, not yet replaced by the loop, is not this target's). */
+    failedOn(generation) { const l = this.link.get(); return l.status === "failed" && l.generation === generation; }
     currentSession() { const l = this.link.get(); return l.status === "connected" ? l.session : undefined; }
     state() { return stateOf(this.link.get()); }
     /** The loop's one write. A write that names a session or withdraws one tells every monitoring handle, in the same step. */
@@ -119,9 +140,10 @@ export class Node {
         forgetOnSignals(this.#closable);
     }
     #closable = { close: () => this.close() };
-    /** Builds the freshly opened session completely (its epoch, its tasks running), then names it. */
-    attach(session) {
+    /** Builds the freshly opened session completely (its epoch, the target generation it was opened for, its tasks running), then names it. */
+    attach(session, generation) {
         session.epoch = ++this.epochs;
+        session.generation = generation;
         const sync = new ClockSync(this.dom.id, session.hello.dom, nowUs());
         session.clock.set(sync.info());
         session.onNotice = (n) => {
@@ -141,30 +163,130 @@ export class Node {
         this.#commands.push({ kind: "close" });
         await this.ended.promise;
     }
-    /** `setTarget()`: declares the target under the cell's write, posts the command with its reply, and awaits it. */
-    setTarget(dial) {
+    /**
+     * The one path of every target change (`connect()`, `disconnect()`): declares `dial` (`undefined`: no target) under the
+     * `target` `Cell`'s write, posts the command with its reply, and awaits it (the loop answers once the target is reached, given up
+     * on, applied as none, or superseded by a newer one: quietly). The target already declared declares nothing (except
+     * from `failed` on it, where it is dialed again) and settles with the node's state (`settled`); no target again is done at
+     * once. `giveUpAfterMs`: the bound of the dial's first pursuit.
+     */
+    declare(dial, giveUpAfterMs = FIRST_CONNECT_GIVE_UP_MS) {
         if (this.#endedFlag)
-            return Promise.reject(new SynapseError("not_connected", "node closed"));
+            return Promise.reject(notConnected());
         const t = this.target.get();
-        if (sameDial(t.dial, dial))
-            return Promise.resolve();
+        if (sameDial(t.dial, dial) && !this.failedOn(t.generation))
+            return dial ? this.settled(t.generation) : this.idle(t.generation);
+        if (dial && this.signals)
+            closeOnSignals(this.#closable);
         const next = { generation: t.generation + 1, dial, identity: dial ? dial.identity : t.identity };
         this.target.set(next);
         const reply = deferred();
-        this.#commands.push({ kind: "setTarget", target: next, reply });
+        this.#commands.push({ kind: "declare", target: next, reply, giveUpAfterMs });
         return reply.promise;
     }
-    /** Starts the loop. `first` is the `connect()` call's reply. `signals`: close on SIGINT/SIGTERM (Bun/Node). */
+    /**
+     * Settles with target `generation` by reading the node's state: resolves once connected on a session opened for it (a
+     * session of an earlier target still connected does not count) or once a newer target superseded it (quietly, as the
+     * loop answers a superseded call); rejects once `failed` on it (its error; a `failed` of an older target keeps it waiting) or ended (`not_connected`).
+     */
+    settled(generation) {
+        return new Promise((resolve, reject) => {
+            const check = () => {
+                const l = this.link.get();
+                if ((l.status === "connected" && l.session.generation === generation) || this.target.get().generation !== generation) {
+                    resolve();
+                    return true;
+                }
+                if (l.status === "failed" && l.generation === generation) {
+                    reject(l.error);
+                    return true;
+                }
+                if (l.status === "closed") {
+                    reject(notConnected());
+                    return true;
+                }
+                return false;
+            };
+            if (check())
+                return;
+            const unLink = this.link.subscribe(() => { if (check()) {
+                unLink();
+                unTarget();
+            } });
+            const unTarget = this.target.subscribe(() => { if (check()) {
+                unLink();
+                unTarget();
+            } });
+        });
+    }
+    /** `disconnect()` again while the first is still being acted on: resolves once the node rests `idle` (or a newer target superseded it); `not_connected` once it ended. */
+    idle(generation) {
+        return new Promise((resolve, reject) => {
+            const check = () => {
+                const l = this.link.get();
+                if (l.status === "idle" || this.target.get().generation !== generation) {
+                    resolve();
+                    return true;
+                }
+                if (l.status === "closed") {
+                    reject(notConnected());
+                    return true;
+                }
+                return false;
+            };
+            if (check())
+                return;
+            const unLink = this.link.subscribe(() => { if (check()) {
+                unLink();
+                unTarget();
+            } });
+            const unTarget = this.target.subscribe(() => { if (check()) {
+                unLink();
+                unTarget();
+            } });
+        });
+    }
+    /** Resolves once a session other than `asked` is connected; rejects with the error once the node rests `failed`, `not_connected` once it ended or rests `idle` (disconnected meanwhile: no session will follow). */
+    switchedFrom(asked) {
+        return new Promise((resolve, reject) => {
+            const check = () => {
+                const l = this.link.get();
+                if (l.status === "connected" && l.session !== asked) {
+                    resolve();
+                    return true;
+                }
+                if (l.status === "failed") {
+                    reject(l.error);
+                    return true;
+                }
+                if (l.status === "closed") {
+                    reject(notConnected());
+                    return true;
+                }
+                // A `disconnect()` during the switch: no session will follow.
+                if (l.status === "idle") {
+                    reject(new SynapseError("not_connected", "disconnected before the promoted session was up"));
+                    return true;
+                }
+                return false;
+            };
+            if (check())
+                return;
+            const un = this.link.subscribe(() => { if (check())
+                un(); });
+        });
+    }
+    /** Starts the loop (once the time domain is final). `first` is a `connect()` call's reply. `signals`: close on SIGINT/SIGTERM (Bun/Node). */
     run(stand, first, signals) {
         if (signals)
             closeOnSignals(this.#closable);
-        void runLoop(this, this.#commands, stand, first);
+        void this.prepared.then(() => runLoop(this, this.#commands, stand, first));
     }
 }
 function sameDial(a, b) {
     if (!a || !b)
         return a === b;
-    return a.url === b.url && a.cert === b.cert && a.identity.type === b.identity.type && a.identity.name === b.identity.name && a.identity.user_id === b.identity.user_id && a.identity.credential === b.identity.credential;
+    return a.url === b.url && a.cert === b.cert && a.token === b.token && a.identity.type === b.identity.type && a.identity.name === b.identity.name && a.identity.user_id === b.identity.user_id && a.identity.credential === b.identity.credential;
 }
 const notConnected = () => new SynapseError("not_connected", "node closed");
 /**
@@ -174,7 +296,7 @@ const notConnected = () => new SynapseError("not_connected", "node closed");
  */
 async function runLoop(node, commands, stand, first) {
     let target = node.target.get();
-    /** The `setTarget`/`connect` calls waiting for the current target. */
+    /** The `connect`/`disconnect` calls waiting for the current target. */
     let waiting = first ? [first] : [];
     const replyAll = (r) => { for (const w of waiting)
         r ? w.reject(r) : w.resolve(); waiting = []; };
@@ -198,7 +320,7 @@ async function runLoop(node, commands, stand, first) {
                 stand = { kind: "resting" };
                 continue;
             }
-            const { delayMs } = stand;
+            const { delayMs, pursuit } = stand;
             const ac = new AbortController();
             const opened = (async () => {
                 if (delayMs > 0)
@@ -214,9 +336,18 @@ async function runLoop(node, commands, stand, first) {
                     return { kind: "opened", result: e instanceof SynapseError ? e : new SynapseError("connection_lost", { message: String(e), cause: e }) };
                 }
             })();
-            wake = await Promise.race([nextCommand(), opened]);
-            // The dial is abandoned: its pause ends now; a session it still opens is closed when it arrives.
-            if (wake.kind === "command") {
+            // The first connect's bound cuts the pause and the attempt at its deadline: its give-up, with the previous
+            // attempt's error (attempt 1 has none) as the cause.
+            let cutTimer;
+            const racers = [nextCommand(), opened];
+            if (pursuit.kind === "first") {
+                const cut = { kind: "cut", error: gaveUp(pursuit.boundMs, stand.attempt > 1 ? stand.error : undefined) };
+                racers.push(new Promise(r => { cutTimer = setTimeout(() => r(cut), Math.max(0, pursuit.deadlineMs - performance.now())); }));
+            }
+            wake = await Promise.race(racers);
+            clearTimeout(cutTimer);
+            // The dial is abandoned (a command, or the bound): its pause ends now; a session it still opens is closed when it arrives.
+            if (wake.kind === "command" || wake.kind === "cut") {
                 ac.abort();
                 void opened.then(w => { if (w.kind === "opened" && w.result instanceof Session)
                     w.result.close(); });
@@ -243,7 +374,7 @@ async function runLoop(node, commands, stand, first) {
         const close = queued.some(c => c.kind === "close");
         let newest;
         for (const c of queued) {
-            if (c.kind !== "setTarget")
+            if (c.kind !== "declare")
                 continue;
             if (close) {
                 waiting.push(c.reply);
@@ -252,7 +383,7 @@ async function runLoop(node, commands, stand, first) {
             if (!newest || c.target.generation > newest.target.generation) {
                 if (newest)
                     newest.reply.resolve();
-                newest = { target: c.target, reply: c.reply };
+                newest = { target: c.target, reply: c.reply, giveUpAfterMs: c.giveUpAfterMs };
             }
             else
                 c.reply.resolve(); // superseded: quietly done
@@ -272,11 +403,13 @@ async function runLoop(node, commands, stand, first) {
             target = newest.target;
             attempts = 0;
             if (target.dial) {
+                // Every dial is first pursued within its bound.
+                const pursuit = { kind: "first", deadlineMs: performance.now() + newest.giveUpAfterMs, boundMs: newest.giveUpAfterMs };
                 node.setLink({ status: "connecting", attempt: 1 });
-                stand = { kind: "dialing", pursuit: { kind: "target" }, attempt: 1, delayMs: 0, reason: "client", error: new SynapseError("connection_lost", "target changed") };
+                stand = { kind: "dialing", pursuit, attempt: 1, delayMs: 0, reason: "client", error: new SynapseError("connection_lost", "target changed") };
             }
             else {
-                node.setLink({ status: "closed", reason: "client" });
+                node.setLink({ status: "idle" });
                 replyAll(undefined);
                 stand = { kind: "resting" };
             }
@@ -302,18 +435,24 @@ async function runLoop(node, commands, stand, first) {
                 stand = { kind: "dialing", pursuit: { kind: "reconnect" }, attempt: attempts, delayMs: delay, reason, error: err };
             }
             else {
-                await teardown(node, s, { status: "closing" });
-                node.end({ status: "closed", reason });
-                replyAll(notConnected());
-                return;
+                // The policy declined: the node rests `failed` with the drop's error until a new target (or `close()`).
+                await teardown(node, s, { status: "failed", error: err, generation: target.generation });
+                stand = { kind: "resting" };
             }
             continue;
         }
-        // opened
         if (stand.kind !== "dialing")
             continue;
+        // the first connect's bound cut the attempt: given up
+        if (wake.kind === "cut") {
+            node.setLink({ status: "failed", error: wake.error, generation: target.generation });
+            replyAll(wake.error);
+            stand = { kind: "resting" };
+            continue;
+        }
+        // opened
         if (wake.result instanceof Session) {
-            node.attach(wake.result);
+            node.attach(wake.result, target.generation);
             replyAll(undefined); // the target is reached
             stand = { kind: "live", session: wake.result };
             continue;
@@ -329,21 +468,12 @@ async function runLoop(node, commands, stand, first) {
             stand.error = e;
             node.setLink(pursuit.kind === "first" ? { status: "connecting", attempt: stand.attempt } : { status: "reconnecting", attempt: stand.attempt, reason: stand.reason, error: e, nextRetryAtMs: performance.now() + next.delayMs });
         }
-        else if (next.kind === "failed" && pursuit.kind === "target") {
-            node.setLink({ status: "failed", error: e });
+        else {
+            // Given up (any pursuit): `failed` is a resting state; a later `connect()` dials again.
+            node.setLink({ status: "failed", error: e, generation: target.generation });
             replyAll(e);
             stand = { kind: "resting" };
         }
-        else if (next.kind === "failed") {
-            node.end({ status: "failed", error: e });
-            replyAll(e);
-            return;
-        }
-        else {
-            node.end({ status: "closed", reason: stand.reason });
-            replyAll(notConnected());
-            return;
-        }
     }
 }
 /** Ends session `s`: the node stops naming it (handles are told, the status is true from that instant), then the session is torn down (calls failed, tasks awaited, close sent). */
@@ -367,12 +497,7 @@ export function resolveIdentity(o) {
 }
 /** Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). */
 export function resolveTarget(node, t) {
-    try {
-        new URL(t.url);
-    }
-    catch (e) {
-        throw new SynapseError("invalid_input", { message: `broker url ${JSON.stringify(t.url)}: ${e instanceof Error ? e.message : String(e)}` });
-    }
+    checkUrl(t.url);
     const cur = node.target.get().identity;
     if (t.name !== undefined && !isValidClientName(t.name))
         throw new SynapseError("invalid_input", `name ${JSON.stringify(t.name)} is not [a-z0-9_-]{1,64}`);
@@ -384,24 +509,39 @@ export function resolveTarget(node, t) {
     const cred = t.credential ?? cur.credential;
     if (cred)
         identity.credential = cred;
-    return { url: t.url, identity, cert: t.brokerCertSha256 };
+    return makeDial(t.url, identity, t.brokerCertSha256, t.token);
+}
+/** A given broker url that is not a URL is the caller's mistake: `invalid_input`. */
+export function checkUrl(url) {
+    try {
+        new URL(url);
+    }
+    catch (e) {
+        throw new SynapseError("invalid_input", { message: `broker url ${JSON.stringify(url)}: ${e instanceof Error ? e.message : String(e)}` });
+    }
 }
 /**
- * Builds the node and starts its loop in the first pursuit. Resolves as soon as the loop runs, with
- * the node (so a `close()` can reach it during the first dial) and `connected`: the loop's reply to
- * the first connect, a session established or why there is none (`not_connected` after a `close()`).
+ * Builds the node, synchronously, with no target (`idle`), and starts its loop resting; nothing is
+ * dialed until `connect()` declares a target. Throws `invalid_input` for options that can never work
+ * (a bad name). The time domain is read in the background; the loop starts once it is final.
  */
-export async function startNode(opts, giveUpAfterMs) {
+export function createNode(opts) {
     const identity = resolveIdentity(opts);
     // In the host's domain (Bun/Node) `nowUs()` must be the kernel's monotonic clock, like every other process on the host (WP §7.3).
-    if (!opts.domId)
+    const provisional = { id: opts.domId ?? identity.name };
+    const finalDom = opts.domId ? undefined : (async () => {
         await calibrateMonotonicClock();
-    const domId = opts.domId ?? (await defaultDomId()) ?? identity.name;
+        return { id: (await defaultDomId()) ?? identity.name };
+    })();
     const knobs = { transport: opts.transport ?? "auto", connectTimeoutMs: opts.connectTimeoutMs ?? 10_000, maxDatagram: opts.maxDatagram ?? defaultMaxDatagram(), project: opts.project };
     const policy = opts.reconnect === undefined ? defaultReconnectPolicy : opts.reconnect;
-    const dial = { url: opts.url, identity, cert: opts.brokerCertSha256 };
-    const node = new Node({ generation: 0, dial, identity }, { id: domId }, knobs, policy);
-    const first = deferred();
-    node.run({ kind: "dialing", pursuit: { kind: "first", deadlineMs: performance.now() + giveUpAfterMs }, attempt: 1, delayMs: 0, reason: "", error: new SynapseError("connection_lost") }, first, opts.signals ?? true);
-    return { node, connected: first.promise };
+    const node = new Node({ generation: 0, dial: undefined, identity }, provisional, knobs, policy, { signals: opts.signals ?? true, finalDom });
+    node.run({ kind: "resting" }, undefined, false);
+    return node;
+}
+/** The dial `connect()` with no target declares when none is declared: `SYNAPSE_ENDPOINT` (Bun/Node; unset, or a browser: `invalid_input`) with the node's current identity. */
+export function endpointDial(node) {
+    const url = urlOrEndpoint(undefined);
+    checkUrl(url);
+    return makeDial(url, node.target.get().identity, undefined, undefined);
 }