@synapse-sdk/client 0.3.3 → 0.3.6

package/dist/calls.d.ts

@@ -1,7 +1,7 @@
-import { type CallId, type ServiceContract } from "@synapse-sdk/core";
+import { SynapseError, type CallId, type ServiceContract } from "@synapse-sdk/core";
 import type { Node } from "./node.ts";
 import { type RespFrame, type Session } from "./session.ts";
-import type { CallEvent, CallOptions, Run, RunStatus } from "./types.ts";
+import type { CallOptions, Run, RunStatus } from "./types.ts";
 /** A fresh call id (WP §8.2): 16 random bytes. */
 export declare function newCallId(): CallId;
 export declare class RunImpl<U, R> implements Run<U, R> {
@@ -17,12 +17,14 @@ export declare class RunImpl<U, R> implements Run<U, R> {
     get status(): RunStatus;
     get result(): Promise<R>;
     then<A = R, B = never>(onFulfilled?: ((v: R) => A | PromiseLike<A>) | null, onRejected?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+    catch<B = never>(onRejected?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<R | B>;
+    finally(onFinally?: (() => void) | null): Promise<R>;
     /** The session's demux hands frames here; `null` = the session ended with the call pending. */
     deliver(f: RespFrame | null): void;
     /** Starts the per-frame reader once the request is written (frames can arrive before `writeCall` returns). */
     start(): void;
-    nextUpdate(): Promise<U | undefined>;
-    updates(): AsyncIterable<U>;
+    next(): Promise<U | undefined>;
+    [Symbol.asyncIterator](): AsyncIterator<U>;
     /** Cooperative cancel (WP §8.4): tells the broker, then waits for its `canceled` terminal frame. `connection_lost` without sending once the session ended. */
     cancel(reason?: string): Promise<void>;
     /** Dropped with the call in flight: the runtime is told (best effort). */
@@ -33,5 +35,9 @@ export declare class RunImpl<U, R> implements Run<U, R> {
  * go on the session the attempt is for (`channel.ts`). `connection_lost` once it ended.
  */
 export declare function startOn<U, R>(node: Node, session: Session, svc: string, args: unknown, opts: CallOptions<U>, contract?: ServiceContract<unknown, unknown, U, R>): RunImpl<U, R>;
-/** `callStream`: the updates and the result as one ordered stream; `break` cancels. */
-export declare function callStream<U, R>(run: Run<U, R>): AsyncGenerator<CallEvent<U, R>, void, undefined>;
+/**
+ * A call that was never sent (no session): a `Run` already `failed` with `error`. Its result is the
+ * error; it has no updates; `cancel()` has nothing to do. Like every Run, an unread result is no
+ * unhandled rejection.
+ */
+export declare function failedRun<U, R>(error: SynapseError): Run<U, R>;

package/dist/calls.js

@@ -4,7 +4,7 @@
 // a frame on a later session (WP §8.4: ownership is checked, never inferred).
 import { FLAGS, SynapseError, TYPES, decode as decodeBody, encode as encodeBody, nowUs, toHex, validateSync } from "@synapse-sdk/core";
 import { outcomeUnknown } from "./session.js";
-import { AsyncQueue, deferred } from "./util.js";
+import { AsyncQueue, deferred, rethrowLater } from "./util.js";
 /** A fresh call id (WP §8.2): 16 random bytes. */
 export function newCallId() { const b = new Uint8Array(16); crypto.getRandomValues(b); return b; }
 export class RunImpl {
@@ -42,6 +42,8 @@ export class RunImpl {
     get status() { return this.#status; }
     get result() { return this.#result.promise; }
     then(onFulfilled, onRejected) { return this.#result.promise.then(onFulfilled, onRejected); }
+    catch(onRejected) { return this.then(undefined, onRejected); }
+    finally(onFinally) { return this.#result.promise.finally(onFinally); }
     /** The session's demux hands frames here; `null` = the session ended with the call pending. */
     deliver(f) { this.#frames.push(f); }
     /** Starts the per-frame reader once the request is written (frames can arrive before `writeCall` returns). */
@@ -93,11 +95,17 @@ export class RunImpl {
                     continue;
                 u = r.value;
             }
-            this.#updates.push(u);
-            try {
-                this.opts.onUpdate?.(u);
+            // The callback form takes the stream (as `subscribe(topic, cb)`): a throwing `onUpdate` is rethrown later and the reading goes on.
+            if (this.opts.onUpdate) {
+                try {
+                    this.opts.onUpdate(u);
+                }
+                catch (e) {
+                    rethrowLater(e);
+                }
             }
-            catch { /* the caller's */ }
+            else
+                this.#updates.push(u);
         }
     }
     #updates = new AsyncQueue(4096);
@@ -129,8 +137,8 @@ export class RunImpl {
             this.#result.resolve(r.value);
         }
     }
-    async nextUpdate() { return this.#updates.next(); }
-    updates() { return this.#updates; }
+    next() { return this.#updates.next(); }
+    [Symbol.asyncIterator]() { return this.#updates[Symbol.asyncIterator](); }
     #sendCancel(reason) {
         if (!this.session.isLive)
             return;
@@ -178,15 +186,24 @@ export function startOn(node, session, svc, args, opts, contract) {
     run.start();
     return run;
 }
-/** `callStream`: the updates and the result as one ordered stream; `break` cancels. */
-export async function* callStream(run) {
-    try {
-        for await (const u of run.updates())
-            yield { type: "update", data: u };
-        yield { type: "result", data: await run.result };
-    }
-    finally {
-        if (run.status === "pending" || run.status === "running")
-            run.cancel("caller").catch(() => { });
-    }
+/**
+ * A call that was never sent (no session): a `Run` already `failed` with `error`. Its result is the
+ * error; it has no updates; `cancel()` has nothing to do. Like every Run, an unread result is no
+ * unhandled rejection.
+ */
+export function failedRun(error) {
+    const result = Promise.reject(error);
+    result.catch(() => { });
+    return {
+        id: "",
+        status: "failed",
+        result,
+        then: (onFulfilled, onRejected) => result.then(onFulfilled, onRejected),
+        catch: onRejected => result.catch(onRejected),
+        finally: onFinally => result.finally(onFinally),
+        next: async () => undefined,
+        [Symbol.asyncIterator]: async function* () { },
+        cancel: async () => { },
+        [Symbol.asyncDispose]: async () => { },
+    };
 }

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 export * from "@synapse-sdk/core";
 export { Synapse, FIRST_CONNECT_GIVE_UP_MS } from "./synapse.ts";
 export { defaultReconnectPolicy, exponentialPolicy, fixedPolicy, withMaxAttempts } from "./node.ts";
-export { callStream } from "./calls.ts";
 export { isTasksRefusal } from "./tasks.ts";
 export { setMoqDebug } from "./moq_log.ts";
 export type * from "./types.ts";

package/dist/index.js

@@ -2,7 +2,6 @@
 export * from "@synapse-sdk/core";
 export { Synapse, FIRST_CONNECT_GIVE_UP_MS } from "./synapse.js";
 export { defaultReconnectPolicy, exponentialPolicy, fixedPolicy, withMaxAttempts } from "./node.js";
-export { callStream } from "./calls.js";
 export { isTasksRefusal } from "./tasks.js";
 export { setMoqDebug } from "./moq_log.js";
 export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport } from "./session.js";

package/dist/node.d.ts

@@ -9,14 +9,16 @@ export declare function fixedPolicy(ms: number): ReconnectPolicy;
 /** Stops after `maxAttempts` attempts in one phase. */
 export declare function withMaxAttempts(p: ReconnectPolicy, maxAttempts: number): ReconnectPolicy;
 export declare const defaultReconnectPolicy: ReconnectPolicy;
-/** The node's declared target: bumped `generation` per change; `dial` undefined = deliberately disconnected. */
+/** The node's declared target: bumped `generation` per change; `dial` undefined = no target (the node is `idle`). */
 export interface Target {
     generation: number;
     dial: Dial | undefined;
     identity: Identity;
 }
-/** The one lifecycle cell: `ConnectionState` with the session on `connected`. State, not history. */
+/** The one lifecycle value (held in a `Cell`): `ConnectionState` with the session on `connected`. State, not history. */
 export type Link = {
+    status: "idle";
+} | {
     status: "connecting";
     attempt: number;
 } | {
@@ -36,6 +38,7 @@ export type Link = {
 } | {
     status: "failed";
     error: SynapseError;
+    generation: number;
 };
 export declare function stateOf(l: Link): ConnectionState;
 /** What a handle task is told about the node's session, in its own mailbox, in order with its other events. */
@@ -47,16 +50,20 @@ export type SessionEvent = {
 } | {
     kind: "nodeEnded";
 };
-/** Where the loop replies to a `connect`/`setTarget` call waiting for a target generation. */
+/** 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 declare const FIRST_CONNECT_GIVE_UP_MS = 30000;
+/** Where the loop replies to a `connect`/`disconnect` call waiting for a target generation. */
 type Reply = Deferred<void>;
-/** Why the loop is dialing. */
+/**
+ * Why the loop is dialing: the first pursuit of a declared target (`connect()`), every attempt (its pause included) cut
+ * at `deadlineMs` (`boundMs` after the first attempt), or a dropped session (paced by the policy).
+ */
 type Pursuit = {
     kind: "first";
     deadlineMs: number;
+    boundMs: number;
 } | {
     kind: "reconnect";
-} | {
-    kind: "target";
 };
 type Stand = {
     kind: "live";
@@ -76,30 +83,44 @@ type Next = {
     delayMs: number;
 } | {
     kind: "failed";
-} | {
-    kind: "closed";
 };
-/** The rules (SDK §2, WP §10.4) for the delay before attempt `attempt`. */
+/**
+ * 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 declare function decide(pursuit: Pursuit, policy: ReconnectPolicy | null, err: SynapseError, attempt: number, nowMs: number): Next;
 export declare class Node {
     #private;
     readonly link: Cell<Link>;
     readonly target: Cell<Target>;
-    readonly dom: TimeDomain;
+    /** The node's time domain; final once `prepared` resolved (the loop dials, and publishers describe themselves, only after). */
+    dom: TimeDomain;
+    /** Resolves once the time domain is final (the host's monotonic clock read, its domain id derived). */
+    readonly prepared: Promise<void>;
     readonly knobs: SessionKnobs;
     readonly policy: ReconnectPolicy | null;
+    /** Bun/Node: close on SIGINT/SIGTERM once a target is declared (not at construction: constructing opens nothing). */
+    readonly signals: boolean;
     /** Broker notices addressed to this node, across its sessions (fed by the loop from the current session's). */
     readonly notices: Set<(n: ErrorBody) => void>;
     readonly projectNotices: Set<(n: Notice) => void>;
-    /** 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. */
     readonly ended: Deferred<void>;
     epochs: number;
     reconnects: number;
     callsSent: number;
     callsAnswered: number;
-    constructor(target: Target, dom: TimeDomain, knobs: SessionKnobs, policy: ReconnectPolicy | null);
+    /** `finalDom`: the time domain once known, when `dom` is only provisional (see `createNode`). */
+    constructor(target: Target, dom: TimeDomain, knobs: SessionKnobs, policy: ReconnectPolicy | null, opts?: {
+        signals?: boolean;
+        finalDom?: Promise<TimeDomain>;
+    });
     get isEnded(): boolean;
     get isConnected(): boolean;
+    /** 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: number): boolean;
     currentSession(): Session | undefined;
     state(): ConnectionState;
     /** The loop's one write. A write that names a session or withdraws one tells every monitoring handle, in the same step. */
@@ -115,13 +136,29 @@ export declare class Node {
     };
     /** The node ends for good in `link`: handles are told, feeds end. */
     end(link: Link): void;
-    /** Builds the freshly opened session completely (its epoch, its tasks running), then names it. */
-    attach(session: Session): Session;
+    /** Builds the freshly opened session completely (its epoch, the target generation it was opened for, its tasks running), then names it. */
+    attach(session: Session, generation: number): Session;
     /** `close()`: posts the command; resolves once the node has ended. */
     close(): Promise<void>;
-    /** `setTarget()`: declares the target under the cell's write, posts the command with its reply, and awaits it. */
-    setTarget(dial: Dial | undefined): Promise<void>;
-    /** Starts the loop. `first` is the `connect()` call's reply. `signals`: close on SIGINT/SIGTERM (Bun/Node). */
+    /**
+     * 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: Dial | undefined, giveUpAfterMs?: number): Promise<void>;
+    /**
+     * 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: number): Promise<void>;
+    /** `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: number): Promise<void>;
+    /** 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: Session): Promise<void>;
+    /** 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: Stand, first: Reply | undefined, signals: boolean): void;
 }
 /** Resolves the identity a node declares (`resolve_identity`): a missing name is minted, a `web`/`hmi` node without a `user_id` mints one. */
@@ -133,13 +170,14 @@ export declare function resolveIdentity(o: {
 }): Identity;
 /** Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). */
 export declare function resolveTarget(node: Node, t: ConnectTarget): Dial;
+/** A given broker url that is not a URL is the caller's mistake: `invalid_input`. */
+export declare function checkUrl(url: string): void;
 /**
- * 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 declare function startNode(opts: ConnectOptions, giveUpAfterMs: number): Promise<{
-    node: Node;
-    connected: Promise<void>;
-}>;
+export declare function createNode(opts: ConnectOptions): 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 declare function endpointDial(node: Node): Dial;
 export {};