@calimero-network/mero-js 27.4.0 → 27.5.0

package/README.md

@@ -31,8 +31,9 @@ quotes and is loaded on first use.
 ```ts
 import { CalimeroClient, browserPasskey } from '@calimero-network/mero-js';
 
-const client = new CalimeroClient({
-  baseUrl: 'https://eu1.cloud.calimero.network',
+// Reach a Calimero Cloud cluster by name.
+const client = await CalimeroClient.connect({
+  cluster: 'eu-shared-1',
   // Trust the signed mero-tee release the node names, from this one up.
   policy: { release: { minReleaseVersion: '2.3.109' } },
 });
@@ -52,6 +53,34 @@ A development cluster (`merod local`, `merod run --dev`) sends mock quotes,
 which pass only with `policy: { allowMock: true }`. Nothing is read from the
 environment.
 
+## Connecting to a cluster
+
+`CalimeroClient.connect({ cluster, policy })` is the recommended way to reach a
+Calimero Cloud cluster. It reads the cluster's nodes from the public node
+directory (`DEFAULT_DIRECTORY`, `https://manager.cloud.calimero.network/api/v2/directory`;
+`directory` names another), puts those in `zone` first when you give one, and
+orders each group at random, weighted by the directory's weight. A cluster the
+directory does not know, or one with no usable node, throws `DirectoryError`.
+
+The directory only picks which nodes to try, and in what order. It is not
+trusted: every node is attested under **your** `policy` before anything is
+sent to it, so a wrong or tampered list can only make connecting fail.
+
+Any node of a cluster serves any request. While the node in use answers `503`
+or cannot be reached, a call or a view is retried there (`retry`); when those
+retries run out it fails over to the next node and starts them again there,
+with the **same** idempotency key, which the app's replicated log answers once
+cluster-wide. Each node is tried once per request; when all have failed, the
+last `UnavailableError` reaches you. After a failover, and once the directory's
+`refreshAfterSeconds` has passed (checked at the next request), the client
+reads the directory again in the background: the node in use stays first,
+nodes no longer listed are dropped. `client.nodeUrl` is the node in use,
+`client.nodes` the list.
+
+For a fixed list of nodes or a cluster you run yourself, construct the client
+directly: `new CalimeroClient({ baseUrl, nodes, policy })`. It fails over
+between `baseUrl` and `nodes` the same way, and never reads a directory.
+
 ## What the client checks
 
 Before it sends anything to a node, as core's Rust client does (`Measurements::Release`):
@@ -71,7 +100,7 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 - **Credentials**: `signUp`, `signIn`, `refresh`, `signOut`, `signOutEverywhere`, `useSession`, `useApiKey`, `me`, `usage`, `addPasskey`, `labelPasskey`, `removePasskey`, `createApiKey`, `listApiKeys`, `revokeApiKey`.
 - **Packages**: `installPackage`, `uploadPackage`, `packages`, `package`, `uninstallPackage`; `uploadBundle` (raw WASM, development clusters only).
 - **Apps**: `createApp`, `listApps`, `getApp`, `deleteApp`, `setAccess`, `setAppMetadata`, `appStorage`, `appAbi`, `upgradeApp`, `transferApp`.
-- **Calls**: `call`, `callConfirmed`, `view`, `events`. A call always carries an idempotency key, and is sent again with it while the node answers `503`.
+- **Calls**: `call`, `callConfirmed`, `view`, `events`. A call always carries an idempotency key, and is sent again with it while the node answers `503`, then to the next node.
 - **Blobs and presence**: `uploadBlob`, `downloadBlob`, `listBlobs`, `blobInfo`, `deleteBlob`; `publishPresence`, `presence`, `presenceStream`.
 - **Organizations**: `createOrg`, `getOrg`, `deleteOrg`, `setOrgMetadata`, `setMember`, `removeMember`, `setMemberMetadata`, `setCapabilities` (`ORG_CAPABILITIES`), teams, `invite`, `redeemInvite`.
 - **Owner decisions** (passkey approval, never from an app's frontend): `upgradeOrg`, `upgradeRun`, `retryUpgradeRun`, `approveRelease`, `approveOutbound`, `bindPublisher`, `upgradePublished`.

package/dist/cloud-v2/client.d.ts

@@ -160,9 +160,10 @@ export interface CalimeroClientOptions {
     baseUrl: string;
     /**
      * Other nodes of the same cluster, in the order to move to them when a node
-     * answers `421 WRONG_NODE` (its release may not serve this account). Each is
-     * attested under the same `policy` before anything is sent to it. Without
-     * them a `421` reaches the caller as {@link WrongNode}.
+     * answers `421 WRONG_NODE` (its release may not serve this account), or stays
+     * unavailable to a call or a view through all its retries. Each is attested
+     * under the same `policy` before anything is sent to it. Without them a `421`
+     * reaches the caller as {@link WrongNode}.
      */
     nodes?: string[];
     policy: CloudPolicy;
@@ -171,9 +172,26 @@ export interface CalimeroClientOptions {
     /** How calls and views retry a 503 or a failed connection. */
     retry?: CloudRetryOptions;
 }
+/** How {@link CalimeroClient.connect} reaches a Calimero Cloud cluster by name. */
+export interface CalimeroConnectOptions {
+    /** The cluster's name, e.g. `eu-shared-1`. */
+    cluster: string;
+    /** What every node must attest to before anything is sent to it. */
+    policy: CloudPolicy;
+    /** The node directory to ask. Default {@link DEFAULT_DIRECTORY}. */
+    directory?: string;
+    /** Try the nodes in this zone (e.g. `europe-west4-a`) first. */
+    zone?: string;
+    /** Fetch for the directory, attestation and envelopes. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** How calls and views retry a 503 or a failed connection. */
+    retry?: CloudRetryOptions;
+    /** Randomness for the weighted node order, in [0, 1). Defaults to `Math.random`. */
+    random?: () => number;
+}
 export declare class CalimeroClient {
-    /** Every node this client may use, `baseUrl` first. */
-    private readonly nodeUrls;
+    /** Every node this client may use, `baseUrl` first (or as the directory last ordered them). */
+    private nodeUrls;
     /** The one in use: an index into {@link nodeUrls}. */
     private at;
     /** A sealed fetch per node, each attesting its own node on first use. */
@@ -188,9 +206,24 @@ export declare class CalimeroClient {
     private readonly retry;
     /** Rejections of the underlying `fetch` itself: the node could not be reached or dropped the connection. */
     private readonly networkFailures;
+    /** The directory the node list came from, for a client made by {@link connect}. */
+    private source;
+    /**
+     * A client for the Calimero Cloud cluster named `cluster`: its node list read
+     * from the public node directory, those in `zone` first, each group in
+     * weighted-random order. The directory only picks which nodes to try: each is
+     * attested under `policy` before anything is sent to it. Throws
+     * {@link DirectoryError} when the directory names no usable node.
+     *
+     * The list is read again in the background after a failover, and at the
+     * first request once the directory's `refreshAfterSeconds` has passed.
+     */
+    static connect(options: CalimeroConnectOptions): Promise<CalimeroClient>;
     constructor(options: CalimeroClientOptions);
-    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` moved the client on. */
+    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` or a failover moved the client on. */
     get nodeUrl(): string;
+    /** Every node this client may use, in the order it moves through them. */
+    get nodes(): string[];
     /** The sealed channel to `url`, attested under the client's policy before its first request. */
     private channel;
     /**
@@ -199,6 +232,19 @@ export declare class CalimeroClient {
      * refuse after another request moved on already does not move again.
      */
     private moveOn;
+    /**
+     * Fail over from node `from`, where a request's retries ran out, to the next
+     * node it has not `tried`. False when it has tried them all. A request whose
+     * node another request moved away from already goes to that node, if untried.
+     */
+    private failOver;
+    /**
+     * Read the node list again from the directory, in the background, for a
+     * client made by {@link connect}: the node in use stays first, then the
+     * directory's order; a node no longer listed is dropped. A failed read is
+     * ignored. One read at a time.
+     */
+    private reread;
     /** Authenticate every request with an API key. */
     useApiKey(key: string): void;
     useSession(session: CalimeroSession): void;
@@ -241,10 +287,17 @@ export declare class CalimeroClient {
      * {@link json} for a call or a view (D70): while the node answers 503 or
      * cannot be reached, the same request, with the same idempotency key, is sent
      * again after {@link retryDelayMs} (or the pause the node asked for, if
-     * longer), at most `retries` times. Every other answer is final. The last
+     * longer), at most `retries` times. Every other answer is final.
+     *
+     * When a node's retries run out, the request fails over to the next node the
+     * client knows and its retries start again there, with the same key: the
+     * key is kept in the app's replicated log, so the cluster answers it once
+     * whichever node it reaches. Each node is tried once per request. The last
      * failure surfaces as {@link UnavailableError}: the node's 503, or reason
      * `network` for a connection that failed, whose `committed` is `'unknown'`.
-     * `retries` 0 sends the request exactly once.
+     *
+     * `once` sends the request exactly once, to the node in use (the confirmed
+     * attempt of {@link callConfirmed}, whose challenge is single-use).
      */
     private retried;
     post<T = Record<string, unknown>>(path: string, body?: unknown): Promise<T>;

package/dist/cloud-v2/client.js

@@ -11,6 +11,7 @@
  */
 import { SealedTransportError, createSealedFetch } from '../sealed/sealed.js';
 import { fetchAttestedKey } from './attestation.js';
+import { DEFAULT_DIRECTORY, orderNodes, readDirectory } from './directory.js';
 import { CalimeroError, ConfirmCancelled, ConfirmRequired, LoginRequired, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 import { b64url, fromB64url } from './passkey.js';
 import { confirmationCode, pageQuery, pendingApprovalsFrom, } from './approvals.js';
@@ -114,6 +115,32 @@ function ceremony(path) {
     return path === 'auth/refresh' || path.startsWith('auth/passkey/');
 }
 export class CalimeroClient {
+    /**
+     * A client for the Calimero Cloud cluster named `cluster`: its node list read
+     * from the public node directory, those in `zone` first, each group in
+     * weighted-random order. The directory only picks which nodes to try: each is
+     * attested under `policy` before anything is sent to it. Throws
+     * {@link DirectoryError} when the directory names no usable node.
+     *
+     * The list is read again in the background after a failover, and at the
+     * first request once the directory's `refreshAfterSeconds` has passed.
+     */
+    static async connect(options) {
+        const directory = options.directory ?? DEFAULT_DIRECTORY;
+        const random = options.random ?? Math.random;
+        const fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+        const listing = await readDirectory(directory, options.cluster, fetcher);
+        const [baseUrl, ...nodes] = orderNodes(listing.nodes, options.zone, random);
+        const client = new CalimeroClient({ baseUrl, nodes, policy: options.policy, fetch: options.fetch, retry: options.retry });
+        client.source = {
+            directory,
+            cluster: options.cluster,
+            zone: options.zone,
+            random,
+            due: Date.now() + listing.refreshAfterSeconds * 1000,
+        };
+        return client;
+    }
     constructor(options) {
         /** The one in use: an index into {@link nodeUrls}. */
         this.at = 0;
@@ -142,10 +169,14 @@ export class CalimeroClient {
         };
         this.raw = raw;
     }
-    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` moved the client on. */
+    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` or a failover moved the client on. */
     get nodeUrl() {
         return this.nodeUrls[this.at];
     }
+    /** Every node this client may use, in the order it moves through them. */
+    get nodes() {
+        return [...this.nodeUrls];
+    }
     /** The sealed channel to `url`, attested under the client's policy before its first request. */
     channel(url) {
         let sealed = this.channels.get(url);
@@ -167,10 +198,52 @@ export class CalimeroClient {
     moveOn(from) {
         if (this.nodeUrls.length < 2)
             return false;
-        if (this.at === from)
-            this.at = (from + 1) % this.nodeUrls.length;
+        if (this.nodeUrl === from)
+            this.at = (this.at + 1) % this.nodeUrls.length;
         return true;
     }
+    /**
+     * Fail over from node `from`, where a request's retries ran out, to the next
+     * node it has not `tried`. False when it has tried them all. A request whose
+     * node another request moved away from already goes to that node, if untried.
+     */
+    failOver(from, tried) {
+        if (this.nodeUrl !== from && !tried.has(this.nodeUrl))
+            return true;
+        const count = this.nodeUrls.length;
+        for (let step = 1; step < count; step++) {
+            const next = (this.at + step) % count;
+            if (!tried.has(this.nodeUrls[next])) {
+                this.at = next;
+                this.reread();
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Read the node list again from the directory, in the background, for a
+     * client made by {@link connect}: the node in use stays first, then the
+     * directory's order; a node no longer listed is dropped. A failed read is
+     * ignored. One read at a time.
+     */
+    reread() {
+        const source = this.source;
+        if (!source || source.reading)
+            return;
+        source.reading = readDirectory(source.directory, source.cluster, this.raw)
+            .then((listing) => {
+            const current = this.nodeUrl;
+            const listed = orderNodes(listing.nodes, source.zone, source.random);
+            this.nodeUrls = [current, ...listed.filter((url) => url !== current)];
+            this.at = 0;
+            source.due = Date.now() + listing.refreshAfterSeconds * 1000;
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            source.reading = undefined;
+        });
+    }
     /** Authenticate every request with an API key. */
     useApiKey(key) {
         this.auth = key;
@@ -200,6 +273,8 @@ export class CalimeroClient {
             headers['content-type'] = 'application/json';
             payload = JSON.stringify(body);
         }
+        if (this.source && Date.now() >= this.source.due)
+            this.reread();
         const url = this.nodeUrl;
         try {
             return await this.channel(url)(`${url}/${path}`, { method, headers, body: payload, signal });
@@ -232,7 +307,7 @@ export class CalimeroClient {
         let refreshed = false;
         let moved = false;
         for (;;) {
-            const [token, at] = [this.auth, this.at];
+            const [token, at] = [this.auth, this.nodeUrl];
             const response = await this.request(method, path, body, raw, contentType, signal);
             if (response.ok)
                 return response;
@@ -272,30 +347,46 @@ export class CalimeroClient {
      * {@link json} for a call or a view (D70): while the node answers 503 or
      * cannot be reached, the same request, with the same idempotency key, is sent
      * again after {@link retryDelayMs} (or the pause the node asked for, if
-     * longer), at most `retries` times. Every other answer is final. The last
+     * longer), at most `retries` times. Every other answer is final.
+     *
+     * When a node's retries run out, the request fails over to the next node the
+     * client knows and its retries start again there, with the same key: the
+     * key is kept in the app's replicated log, so the cluster answers it once
+     * whichever node it reaches. Each node is tried once per request. The last
      * failure surfaces as {@link UnavailableError}: the node's 503, or reason
      * `network` for a connection that failed, whose `committed` is `'unknown'`.
-     * `retries` 0 sends the request exactly once.
+     *
+     * `once` sends the request exactly once, to the node in use (the confirmed
+     * attempt of {@link callConfirmed}, whose challenge is single-use).
      */
-    async retried(method, path, body, retries = this.retry.retries) {
-        for (let attempt = 0;; attempt++) {
+    async retried(method, path, body, once = false) {
+        const retries = once ? 0 : this.retry.retries;
+        const tried = new Set();
+        for (;;) {
             let unavailable;
-            try {
-                return await this.json(method, path, body);
-            }
-            catch (error) {
-                if (error instanceof UnavailableError)
-                    unavailable = error;
-                else if (error instanceof TypeError && this.networkFailures.has(error)) {
-                    unavailable = new UnavailableError('NETWORK', `the node could not be reached: ${error.message}`, {}, undefined, error);
+            let node = this.nodeUrl;
+            for (let attempt = 0;; attempt++) {
+                node = this.nodeUrl;
+                tried.add(node);
+                try {
+                    return await this.json(method, path, body);
                 }
-                else
-                    throw error;
+                catch (error) {
+                    if (error instanceof UnavailableError)
+                        unavailable = error;
+                    else if (error instanceof TypeError && this.networkFailures.has(error)) {
+                        unavailable = new UnavailableError('NETWORK', `the node could not be reached: ${error.message}`, {}, undefined, error);
+                    }
+                    else
+                        throw error;
+                }
+                if (attempt >= retries)
+                    break;
+                const backoff = retryDelayMs(attempt, this.retry);
+                await new Promise((resolve) => setTimeout(resolve, Math.max(backoff, (unavailable.retryAfter ?? 0) * 1000)));
             }
-            if (attempt >= retries)
+            if (once || !this.failOver(node, tried))
                 throw unavailable;
-            const backoff = retryDelayMs(attempt, this.retry);
-            await new Promise((resolve) => setTimeout(resolve, Math.max(backoff, (unavailable.retryAfter ?? 0) * 1000)));
         }
     }
     post(path, body = {}) {
@@ -600,7 +691,7 @@ export class CalimeroClient {
         const key = idempotencyKey ?? newIdempotencyKey();
         // The confirmed attempt goes out exactly once: its challenge is single-use,
         // so a resend would be refused on the challenge, not answered from the key.
-        return this.confirmed('POST', path, { method, args, idempotencyKey: key }, passkey, (body) => this.retried('POST', path, body, body.confirm === undefined ? this.retry.retries : 0));
+        return this.confirmed('POST', path, { method, args, idempotencyKey: key }, passkey, (body) => this.retried('POST', path, body, body.confirm !== undefined));
     }
     /** Run a read-only method: strong by default, or stale from any replica. */
     view(app, method, args = {}, options = {}) {

package/dist/cloud-v2/directory.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The Calimero Cloud node directory: which nodes of a cluster take traffic now,
+ * and in what order this client tries them.
+ *
+ * `GET {directory}/{cluster}` (no auth) answers
+ * `{ cluster, nodes: [{ id, url, zone, weight }], refreshAfterSeconds }`. The
+ * directory is not trusted for security: it only picks which nodes to try.
+ * Every node is attested under the caller's own policy before anything is sent
+ * to it, so a bad list can only make connecting fail.
+ */
+/** The Calimero Cloud control plane's public node directory. */
+export declare const DEFAULT_DIRECTORY = "https://manager.cloud.calimero.network/api/v2/directory";
+/** Why {@link DirectoryError} was thrown. */
+export type DirectoryFailure = 'unreachable' | 'not-found' | 'bad-response' | 'empty';
+/**
+ * The directory could not name a node to try: it could not be reached or
+ * answered an error (`unreachable`), does not know the cluster (`not-found`,
+ * a 404), answered something that is not a listing (`bad-response`), or listed
+ * no usable node (`empty`).
+ */
+export declare class DirectoryError extends Error {
+    readonly cluster: string;
+    readonly reason: DirectoryFailure;
+    readonly status?: number;
+    readonly cause?: unknown;
+    constructor(cluster: string, reason: DirectoryFailure, message: string, status?: number, cause?: unknown);
+}
+/** One usable node of a listing. */
+export interface DirectoryNode {
+    url: string;
+    zone?: string;
+    weight: number;
+}
+export interface DirectoryListing {
+    nodes: DirectoryNode[];
+    refreshAfterSeconds: number;
+}
+/** The URL of `cluster`'s listing in `directory`. */
+export declare function directoryUrl(directory: string, cluster: string): string;
+/**
+ * Read `cluster`'s listing, keeping only the entries with an http(s) URL and a
+ * positive integer weight (the first of a repeated URL).
+ */
+export declare function readDirectory(directory: string, cluster: string, fetcher: typeof fetch): Promise<DirectoryListing>;
+/**
+ * The order to try `nodes` in: those in `zone` first (when given), each group
+ * in weighted-random order, a node's weight its relative chance to come next.
+ * `random` answers in [0, 1), as `Math.random` does.
+ */
+export declare function orderNodes(nodes: DirectoryNode[], zone: string | undefined, random: () => number): string[];

package/dist/cloud-v2/directory.js

@@ -0,0 +1,115 @@
+/**
+ * The Calimero Cloud node directory: which nodes of a cluster take traffic now,
+ * and in what order this client tries them.
+ *
+ * `GET {directory}/{cluster}` (no auth) answers
+ * `{ cluster, nodes: [{ id, url, zone, weight }], refreshAfterSeconds }`. The
+ * directory is not trusted for security: it only picks which nodes to try.
+ * Every node is attested under the caller's own policy before anything is sent
+ * to it, so a bad list can only make connecting fail.
+ */
+/** The Calimero Cloud control plane's public node directory. */
+export const DEFAULT_DIRECTORY = 'https://manager.cloud.calimero.network/api/v2/directory';
+/** How long a listing stands when the directory does not say. */
+const DEFAULT_REFRESH_SECONDS = 60;
+/**
+ * The directory could not name a node to try: it could not be reached or
+ * answered an error (`unreachable`), does not know the cluster (`not-found`,
+ * a 404), answered something that is not a listing (`bad-response`), or listed
+ * no usable node (`empty`).
+ */
+export class DirectoryError extends Error {
+    constructor(cluster, reason, message, status, cause) {
+        super(`directory for cluster ${cluster}: ${message}`);
+        this.cluster = cluster;
+        this.reason = reason;
+        this.status = status;
+        this.cause = cause;
+        this.name = 'DirectoryError';
+    }
+}
+/** The URL of `cluster`'s listing in `directory`. */
+export function directoryUrl(directory, cluster) {
+    return `${directory.replace(/\/+$/, '')}/${encodeURIComponent(cluster)}`;
+}
+/**
+ * Read `cluster`'s listing, keeping only the entries with an http(s) URL and a
+ * positive integer weight (the first of a repeated URL).
+ */
+export async function readDirectory(directory, cluster, fetcher) {
+    let response;
+    try {
+        response = await fetcher(directoryUrl(directory, cluster), { method: 'GET', headers: { accept: 'application/json' } });
+    }
+    catch (error) {
+        throw new DirectoryError(cluster, 'unreachable', `could not be reached: ${String(error)}`, undefined, error);
+    }
+    if (response.status === 404)
+        throw new DirectoryError(cluster, 'not-found', 'unknown cluster', 404);
+    if (!response.ok)
+        throw new DirectoryError(cluster, 'unreachable', `answered ${response.status}`, response.status);
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        throw new DirectoryError(cluster, 'bad-response', 'answered something other than JSON', response.status, error);
+    }
+    const listing = body;
+    if (!listing || typeof listing !== 'object' || !Array.isArray(listing.nodes)) {
+        throw new DirectoryError(cluster, 'bad-response', 'answered no node list', response.status);
+    }
+    const nodes = [];
+    const seen = new Set();
+    for (const entry of listing.nodes) {
+        const node = usable(entry);
+        if (node && !seen.has(node.url)) {
+            seen.add(node.url);
+            nodes.push(node);
+        }
+    }
+    if (nodes.length === 0)
+        throw new DirectoryError(cluster, 'empty', 'lists no usable node', response.status);
+    const after = listing.refreshAfterSeconds;
+    const refreshAfterSeconds = typeof after === 'number' && Number.isFinite(after) && after >= 1 ? after : DEFAULT_REFRESH_SECONDS;
+    return { nodes, refreshAfterSeconds };
+}
+function usable(entry) {
+    if (!entry || typeof entry !== 'object')
+        return undefined;
+    const { url, zone, weight } = entry;
+    if (typeof url !== 'string' || typeof weight !== 'number' || !Number.isInteger(weight) || weight < 1)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+        return undefined;
+    return { url: url.replace(/\/+$/, ''), zone: typeof zone === 'string' ? zone : undefined, weight };
+}
+/**
+ * The order to try `nodes` in: those in `zone` first (when given), each group
+ * in weighted-random order, a node's weight its relative chance to come next.
+ * `random` answers in [0, 1), as `Math.random` does.
+ */
+export function orderNodes(nodes, zone, random) {
+    const near = zone === undefined ? [] : nodes.filter((node) => node.zone === zone);
+    const far = zone === undefined ? nodes : nodes.filter((node) => node.zone !== zone);
+    return [...weightedOrder(near, random), ...weightedOrder(far, random)];
+}
+function weightedOrder(nodes, random) {
+    const left = [...nodes];
+    const order = [];
+    while (left.length > 0) {
+        let roll = random() * left.reduce((sum, node) => sum + node.weight, 0);
+        let pick = 0;
+        while (pick < left.length - 1 && roll >= left[pick].weight)
+            roll -= left[pick++].weight;
+        order.push(left.splice(pick, 1)[0].url);
+    }
+    return order;
+}

package/dist/cloud-v2/index.d.ts

@@ -1,7 +1,9 @@
 export { CalimeroClient } from './client.js';
+export { DEFAULT_DIRECTORY, DirectoryError } from './directory.js';
+export type { DirectoryFailure } from './directory.js';
 export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 export type { Committed } from './errors.js';
-export type { AppInfo, BlobInfo, CallResult, CalimeroClientOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.js';
+export type { AppInfo, BlobInfo, CallResult, CalimeroClientOptions, CalimeroConnectOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.js';
 export { claimedRelease, fetchAttestedKey, freshCollateral, MOCK_QUOTE_HEADER } from './attestation.js';
 export type { AttestationDoc, CloudPolicy, CloudReleasePolicy } from './attestation.js';
 export { browserPasskey, b64url, fromB64url } from './passkey.js';

package/dist/cloud-v2/index.js

@@ -1,4 +1,5 @@
 export { CalimeroClient } from './client.js';
+export { DEFAULT_DIRECTORY, DirectoryError } from './directory.js';
 export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 export { claimedRelease, fetchAttestedKey, freshCollateral, MOCK_QUOTE_HEADER } from './attestation.js';
 export { browserPasskey, b64url, fromB64url } from './passkey.js';