@calimero-network/mero-js 27.4.0 → 27.5.0

package/dist/index.cjs

@@ -40,8 +40,10 @@ __export(index_exports, {
   ConfirmRequired: () => ConfirmRequired,
   ConsentStale: () => ConsentStale,
   DEFAULT_COLLATERAL_MIRROR: () => DEFAULT_COLLATERAL_MIRROR,
+  DEFAULT_DIRECTORY: () => DEFAULT_DIRECTORY,
   DEFAULT_ORG_CAPABILITIES: () => DEFAULT_ORG_CAPABILITIES,
   DEFAULT_RELEASE_MIRROR: () => DEFAULT_RELEASE_MIRROR,
+  DirectoryError: () => DirectoryError,
   GITHUB_RELEASES: () => GITHUB_RELEASES,
   HANDSHAKE_PATH: () => HANDSHAKE_PATH,
   IdempotencyMismatch: () => IdempotencyMismatch,
@@ -1357,6 +1359,85 @@ async function fetchAttestedKey(baseUrl, policy, fetchImpl = (input, init) => fe
   return transportKey;
 }
 
+// src/cloud-v2/directory.ts
+var DEFAULT_DIRECTORY = "https://manager.cloud.calimero.network/api/v2/directory";
+var DEFAULT_REFRESH_SECONDS = 60;
+var DirectoryError = class 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";
+  }
+};
+function directoryUrl(directory, cluster) {
+  return `${directory.replace(/\/+$/, "")}/${encodeURIComponent(cluster)}`;
+}
+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)}`, void 0, 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 = /* @__PURE__ */ 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 void 0;
+  const { url: url2, zone, weight } = entry;
+  if (typeof url2 !== "string" || typeof weight !== "number" || !Number.isInteger(weight) || weight < 1) return void 0;
+  let parsed;
+  try {
+    parsed = new URL(url2);
+  } catch {
+    return void 0;
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return void 0;
+  return { url: url2.replace(/\/+$/, ""), zone: typeof zone === "string" ? zone : void 0, weight };
+}
+function orderNodes(nodes, zone, random) {
+  const near = zone === void 0 ? [] : nodes.filter((node) => node.zone === zone);
+  const far = zone === void 0 ? 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;
+}
+
 // src/cloud-v2/errors.ts
 var CalimeroError = class extends Error {
   constructor(status, code, message, details = {}) {
@@ -1743,7 +1824,7 @@ function retryDelayMs(retry, options) {
 function ceremony(path) {
   return path === "auth/refresh" || path.startsWith("auth/passkey/");
 }
-var CalimeroClient = class {
+var CalimeroClient = class _CalimeroClient {
   constructor(options) {
     /** The one in use: an index into {@link nodeUrls}. */
     this.at = 0;
@@ -1766,10 +1847,40 @@ var CalimeroClient = class {
     };
     this.raw = raw;
   }
-  /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` moved the client on. */
+  /**
+   * 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 * 1e3
+    };
+    return client;
+  }
+  /** 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(url2) {
     let sealed = this.channels.get(url2);
@@ -1790,9 +1901,46 @@ var CalimeroClient = class {
    */
   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((url2) => url2 !== current)];
+      this.at = 0;
+      source.due = Date.now() + listing.refreshAfterSeconds * 1e3;
+    }).catch(() => void 0).finally(() => {
+      source.reading = void 0;
+    });
+  }
   /** Authenticate every request with an API key. */
   useApiKey(key) {
     this.auth = key;
@@ -1820,6 +1968,7 @@ var CalimeroClient = class {
       headers["content-type"] = "application/json";
       payload = JSON.stringify(body);
     }
+    if (this.source && Date.now() >= this.source.due) this.reread();
     const url2 = this.nodeUrl;
     try {
       return await this.channel(url2)(`${url2}/${path}`, { method, headers, body: payload, signal });
@@ -1851,7 +2000,7 @@ var CalimeroClient = class {
     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;
       const error = await refusal(response);
@@ -1887,25 +2036,40 @@ var CalimeroClient = class {
    * {@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 = /* @__PURE__ */ 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}`, {}, void 0, error);
-        } else throw error;
+      let node = this.nodeUrl;
+      for (let attempt = 0; ; attempt++) {
+        node = this.nodeUrl;
+        tried.add(node);
+        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}`, {}, void 0, 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) * 1e3)));
       }
-      if (attempt >= retries) throw unavailable;
-      const backoff = retryDelayMs(attempt, this.retry);
-      await new Promise((resolve) => setTimeout(resolve, Math.max(backoff, (unavailable.retryAfter ?? 0) * 1e3)));
+      if (once || !this.failOver(node, tried)) throw unavailable;
     }
   }
   post(path, body = {}) {
@@ -2200,7 +2364,7 @@ var CalimeroClient = class {
       path,
       { method, args, idempotencyKey: key },
       passkey,
-      (body) => this.retried("POST", path, body, body.confirm === void 0 ? this.retry.retries : 0)
+      (body) => this.retried("POST", path, body, body.confirm !== void 0)
     );
   }
   /** Run a read-only method: strong by default, or stale from any replica. */