@synapse-sdk/client 0.3.0 → 0.3.4

package/dist/calls.d.ts

@@ -1,4 +1,4 @@
-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";
@@ -33,5 +33,11 @@ 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>;
+/**
+ * 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>;
 /** `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>;

package/dist/calls.js

@@ -178,6 +178,25 @@ export function startOn(node, session, svc, args, opts, contract) {
     run.start();
     return run;
 }
+/**
+ * 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),
+        nextUpdate: async () => undefined,
+        updates: async function* () { },
+        cancel: async () => { },
+        [Symbol.asyncDispose]: async () => { },
+    };
+}
 /** `callStream`: the updates and the result as one ordered stream; `break` cancels. */
 export async function* callStream(run) {
     try {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ 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";
 export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport } from "./session.ts";

package/dist/index.js

@@ -3,6 +3,7 @@ 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";
 export { replaceEqualDeep, shallowEqual } from "./util.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 {};