@synapse-sdk/client 0.1.0 → 0.3.3

package/dist/node.js

@@ -0,0 +1,408 @@
+// 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
+// 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
+// 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, makeDial, openSession, urlOrEndpoint } from "./session.js";
+import { startOn } from "./calls.js";
+import { AsyncQueue, Cell, deferred } from "./util.js";
+// ------------------------------------------------------------------------------------- policy
+/** Uniform in [0, 1): jitter, not a secret. */
+const unitRandom = () => Math.random();
+/** `initial × 2^(attempt−1)` capped at `max`, times an equal jitter U(0.5, 1); never gives up. */
+export function exponentialPolicy(initialMs, maxMs) {
+    return { initialMs, nextRetryDelayMs: ({ attempt }) => Math.min(initialMs * 2 ** Math.min(attempt - 1, 31), maxMs) * (0.5 + 0.5 * unitRandom()) };
+}
+/** A fixed delay (tests). */
+export function fixedPolicy(ms) { return { initialMs: ms, nextRetryDelayMs: () => ms }; }
+/** Stops after `maxAttempts` attempts in one phase. */
+export function withMaxAttempts(p, maxAttempts) {
+    return { initialMs: p.initialMs, nextRetryDelayMs: ctx => (ctx.attempt > maxAttempts ? null : p.nextRetryDelayMs(ctx)) };
+}
+export const defaultReconnectPolicy = exponentialPolicy(100, 10_000);
+export function stateOf(l) {
+    switch (l.status) {
+        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 };
+        case "closing": return { status: "closing" };
+        case "closed": return { status: "closed", reason: l.reason };
+        case "failed": return { status: "failed", error: l.error };
+    }
+}
+/** The rules (SDK §2, WP §10.4) for the delay before attempt `attempt`. */
+export function decide(pursuit, policy, err, attempt, nowMs) {
+    if (err.code === "unauthorized")
+        return { kind: "failed" };
+    let delay;
+    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);
+    }
+    else
+        delay = policy ? policy.nextRetryDelayMs({ attempt }) : null;
+    if (delay !== null)
+        return { kind: "retry", delayMs: delay };
+    return pursuit.kind === "reconnect" ? { kind: "closed" } : { kind: "failed" };
+}
+// ---------------------------------------------------------------------------------------- node
+export class Node {
+    link = new Cell({ status: "connecting", attempt: 1 });
+    target;
+    dom;
+    knobs;
+    policy;
+    /** 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). */
+    ended = deferred();
+    #endedFlag = false;
+    /** The loop's mailbox: unbounded, so no `close()` or `setTarget()` is ever dropped. */
+    #commands = new AsyncQueue(Infinity);
+    #monitors = new Set();
+    epochs = 0;
+    reconnects = 0;
+    callsSent = 0;
+    callsAnswered = 0;
+    constructor(target, dom, knobs, policy) {
+        this.target = new Cell(target);
+        this.dom = dom;
+        this.knobs = knobs;
+        this.policy = policy;
+    }
+    get isEnded() { return this.#endedFlag; }
+    get isConnected() { return this.link.get().status === "connected"; }
+    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. */
+    setLink(next) {
+        const prev = this.link.get();
+        const event = next.status === "connected" ? { kind: "started", session: next.session } : prev.status === "connected" ? { kind: "ended" } : undefined;
+        this.link.set(next);
+        if (event)
+            this.#tell(event);
+    }
+    #tell(e) { for (const m of [...this.#monitors]) {
+        if (!m(e))
+            this.#monitors.delete(m);
+    } }
+    /**
+     * Registers a handle to be told about sessions (and the node's end) and returns the session the
+     * node has right now; the next event is its end. `deliver` returns `false` once the handle's
+     * mailbox is gone, which unregisters it; `unmonitor` unregisters it at once.
+     */
+    monitor(deliver) {
+        if (this.#endedFlag) {
+            deliver({ kind: "nodeEnded" });
+            return { session: undefined, unmonitor: () => { } };
+        }
+        this.#monitors.add(deliver);
+        return { session: this.currentSession(), unmonitor: () => { this.#monitors.delete(deliver); } };
+    }
+    /** The node ends for good in `link`: handles are told, feeds end. */
+    end(link) {
+        this.setLink(link);
+        this.#endedFlag = true;
+        const ms = [...this.#monitors];
+        this.#monitors.clear();
+        for (const m of ms)
+            m({ kind: "nodeEnded" });
+        this.ended.resolve();
+        forgetOnSignals(this.#closable);
+    }
+    #closable = { close: () => this.close() };
+    /** Builds the freshly opened session completely (its epoch, its tasks running), then names it. */
+    attach(session) {
+        session.epoch = ++this.epochs;
+        const sync = new ClockSync(this.dom.id, session.hello.dom, nowUs());
+        session.clock.set(sync.info());
+        session.onNotice = (n) => {
+            if (n.kind === "error")
+                for (const cb of this.notices)
+                    cb(n.body);
+            else
+                for (const cb of this.projectNotices)
+                    cb(n.notice);
+        };
+        session.start(sync, (svc, args) => startOn(this, session, svc, args, {}).result);
+        this.setLink({ status: "connected", session });
+        return session;
+    }
+    /** `close()`: posts the command; resolves once the node has ended. */
+    async close() {
+        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) {
+        if (this.#endedFlag)
+            return Promise.reject(new SynapseError("not_connected", "node closed"));
+        const t = this.target.get();
+        if (sameDial(t.dial, dial))
+            return Promise.resolve();
+        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 });
+        return reply.promise;
+    }
+    /** Starts the loop. `first` is the `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);
+    }
+}
+function sameDial(a, b) {
+    if (!a || !b)
+        return a === b;
+    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");
+/**
+ * The loop, the only driver of the node's sessions from the first connect on. One step: wait (the live
+ * session closed, or a command; the dial finished, or a command; a command) → take every queued command
+ * (`close` wins; the newest target wins, older waiting calls are superseded) → act.
+ */
+async function runLoop(node, commands, stand, first) {
+    let target = node.target.get();
+    /** The `setTarget`/`connect` 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 = []; };
+    /** Attempts in the current pursuit, kept across a session that died young (the policy's rule). */
+    let attempts = 0;
+    // The one wait for a command, kept across steps until it is taken. A wait that lost a race is not
+    // dropped: the command it receives is still this wait's, and the next race (where it is listed
+    // first) takes it. A fresh wait is made only after the previous one's command was taken.
+    let commandWait;
+    const nextCommand = () => (commandWait ??= commands.next().then(c => ({ kind: "command", command: c })));
+    for (;;) {
+        // ---- wait
+        let wake;
+        if (stand.kind === "live") {
+            const s = stand.session;
+            wake = await Promise.race([nextCommand(), s.closed.then(err => ({ kind: "dropped", err }))]);
+        }
+        else if (stand.kind === "dialing") {
+            const dial = target.dial;
+            if (!dial) {
+                stand = { kind: "resting" };
+                continue;
+            }
+            const { delayMs } = stand;
+            const ac = new AbortController();
+            const opened = (async () => {
+                if (delayMs > 0)
+                    await new Promise(r => { const t = setTimeout(r, delayMs); ac.signal.addEventListener("abort", () => { clearTimeout(t); r(); }, { once: true }); });
+                if (ac.signal.aborted)
+                    return { kind: "opened", result: new SynapseError("canceled", "superseded") };
+                try {
+                    // The pin: given, else discovered per attempt (a restarted dev broker has a fresh certificate), else unpinned.
+                    const cert = dial.cert ?? await discoverBrokerCertSha256(dial.url, { signal: ac.signal });
+                    return { kind: "opened", result: await openSession(node.knobs, { ...dial, cert }, node.dom.id, ac.signal) };
+                }
+                catch (e) {
+                    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") {
+                ac.abort();
+                void opened.then(w => { if (w.kind === "opened" && w.result instanceof Session)
+                    w.result.close(); });
+            }
+        }
+        else {
+            wake = await nextCommand();
+        }
+        // ---- commands first: everything queued; `close` wins; the newest target wins.
+        // Commands are taken only on a command wake. Otherwise the command wait is still out, and any
+        // command already queued arrived after the one that wait will receive: taking those now would
+        // act on newer commands before an older one. The next step's race takes the wait first.
+        const queued = [];
+        if (wake.kind === "command") {
+            commandWait = undefined;
+            queued.push(wake.command ?? { kind: "close" });
+            for (;;) {
+                const c = commands.tryNext();
+                if (!c)
+                    break;
+                queued.push(c);
+            }
+        }
+        const close = queued.some(c => c.kind === "close");
+        let newest;
+        for (const c of queued) {
+            if (c.kind !== "setTarget")
+                continue;
+            if (close) {
+                waiting.push(c.reply);
+                continue;
+            }
+            if (!newest || c.target.generation > newest.target.generation) {
+                if (newest)
+                    newest.reply.resolve();
+                newest = { target: c.target, reply: c.reply };
+            }
+            else
+                c.reply.resolve(); // superseded: quietly done
+        }
+        if (close) {
+            if (stand.kind === "live")
+                await teardown(node, stand.session, { status: "closing" });
+            node.end({ status: "closed", reason: "client" });
+            replyAll(notConnected());
+            return;
+        }
+        if (newest) {
+            if (stand.kind === "live")
+                await teardown(node, stand.session, { status: "closing" });
+            replyAll(undefined); // superseded: quietly done
+            waiting.push(newest.reply);
+            target = newest.target;
+            attempts = 0;
+            if (target.dial) {
+                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") };
+            }
+            else {
+                node.setLink({ status: "closed", reason: "client" });
+                replyAll(undefined);
+                stand = { kind: "resting" };
+            }
+            continue;
+        }
+        if (wake.kind === "command")
+            continue; // the command was handled above
+        // ---- what the wait brought
+        if (wake.kind === "dropped") {
+            if (stand.kind !== "live")
+                continue;
+            const s = stand.session;
+            const lived = performance.now() - s.startedMs;
+            const err = s.closingReason ? new SynapseError("connection_lost", { message: s.closingReason, source: "broker" }) : closeError(wake.err);
+            if (node.policy && lived >= node.policy.initialMs)
+                attempts = 0;
+            attempts += 1;
+            const reason = err.code;
+            const delay = node.policy ? node.policy.nextRetryDelayMs({ attempt: attempts }) : null;
+            if (delay !== null) {
+                node.reconnects++;
+                await teardown(node, s, { status: "reconnecting", attempt: attempts, reason, error: err, nextRetryAtMs: performance.now() + delay });
+                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;
+            }
+            continue;
+        }
+        // opened
+        if (stand.kind !== "dialing")
+            continue;
+        if (wake.result instanceof Session) {
+            node.attach(wake.result);
+            replyAll(undefined); // the target is reached
+            stand = { kind: "live", session: wake.result };
+            continue;
+        }
+        const e = wake.result;
+        const { pursuit } = stand;
+        stand.attempt += 1;
+        if (pursuit.kind === "reconnect")
+            attempts = stand.attempt;
+        const next = decide(pursuit, node.policy, e, stand.attempt, performance.now());
+        if (next.kind === "retry") {
+            stand.delayMs = next.delayMs;
+            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 });
+            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). */
+async function teardown(node, s, next) {
+    node.setLink(next);
+    await s.teardown();
+}
+// ------------------------------------------------------------------------------------ connect
+/** Resolves the identity a node declares (`resolve_identity`): a missing name is minted, a `web`/`hmi` node without a `user_id` mints one. */
+export function resolveIdentity(o) {
+    const name = o.name ?? mintName(o.type);
+    if (!isValidClientName(name))
+        throw new SynapseError("invalid_input", `name ${JSON.stringify(name)} is not [a-z0-9_-]{1,64}`);
+    const id = { type: o.type, name };
+    const userId = o.userId ?? ((o.type === "web" || o.type === "hmi") ? mintUserId() : undefined);
+    if (userId)
+        id.user_id = userId;
+    if (o.credential)
+        id.credential = o.credential;
+    return id;
+}
+/** 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)}` });
+    }
+    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}`);
+    const type = t.type ?? cur.type;
+    const identity = { type, name: t.name ?? cur.name };
+    const userId = t.userId ?? cur.user_id ?? ((type === "web" || type === "hmi") ? mintUserId() : undefined);
+    if (userId)
+        identity.user_id = userId;
+    const cred = t.credential ?? cur.credential;
+    if (cred)
+        identity.credential = cred;
+    return makeDial(t.url, identity, t.brokerCertSha256, t.token);
+}
+/**
+ * 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()`).
+ */
+export async function startNode(opts, giveUpAfterMs) {
+    const url = urlOrEndpoint(opts.url);
+    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)
+        await calibrateMonotonicClock();
+    const domId = opts.domId ?? (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 = makeDial(url, identity, opts.brokerCertSha256, opts.token);
+    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 };
+}