@wovin/core 0.2.2 → 0.3.2

package/dist/ipns.js

@@ -1,3 +1,46 @@
+// src/ipns/gateway-resolver.ts
+import { CID } from "multiformats/cid";
+import { Logger } from "besonders-logger";
+var { WARN, LOG, DEBUG } = Logger.setup(Logger.INFO);
+async function resolveIPNSViaGateway(ipns, gateways) {
+  if (!ipns.startsWith("k51")) return null;
+  if (!gateways?.length) return null;
+  for (const rawGateway of gateways) {
+    const gateway = rawGateway.replace(/\/+$/, "");
+    const url = `${gateway}/ipns/${ipns}/`;
+    try {
+      DEBUG(`[resolveIPNSViaGateway] HEAD ${url}`);
+      const response = await fetch(url, { method: "HEAD" });
+      if (!response.ok) {
+        DEBUG(`[resolveIPNSViaGateway] ${gateway} returned ${response.status}`);
+        continue;
+      }
+      const roots = response.headers.get("x-ipfs-roots") ?? response.headers.get("X-Ipfs-Roots");
+      if (roots) {
+        const first = roots.split(/[\s,]+/)[0]?.trim();
+        if (first) {
+          const cid = CID.parse(first);
+          DEBUG(`[resolveIPNSViaGateway] resolved via ${gateway} x-ipfs-roots:`, cid.toString());
+          return cid;
+        }
+      }
+      const etag = response.headers.get("etag");
+      if (etag) {
+        const m = etag.match(/^"?([a-z0-9]+)/i);
+        if (m) {
+          const cid = CID.parse(m[1]);
+          DEBUG(`[resolveIPNSViaGateway] resolved via ${gateway} etag:`, cid.toString());
+          return cid;
+        }
+      }
+      WARN(`[resolveIPNSViaGateway] ${gateway} returned 200 but no usable CID header`);
+    } catch (err) {
+      WARN(`[resolveIPNSViaGateway] ${gateway} failed:`, err);
+    }
+  }
+  return null;
+}
+
 // src/ipns/ipns-record.ts
 import { createIPNSRecord, marshalIPNSRecord, unmarshalIPNSRecord } from "ipns";
 import { privateKeyFromRaw } from "@libp2p/crypto/keys";
@@ -36,29 +79,563 @@ async function resolveIPNSSequence(nameServiceUrl, ipnsName) {
   }
   return 0n;
 }
-async function publishIPNSRecord(privateKey, cid, targets, sequenceServiceUrl = "https://name.web3.storage") {
+var SEQ_CONFLICT_RE = /existing IPNS record has sequence (\d+) >= new record sequence (\d+)/;
+async function publishIPNSRecord(privateKey, cid, targets, options) {
   const ipnsName = ipnsNameFromPrivateKey(privateKey);
-  const currentSeq = await resolveIPNSSequence(sequenceServiceUrl, ipnsName);
-  const sequence = currentSeq != null ? currentSeq + 1n : 0n;
-  const signed = await createSignedIPNSRecord(privateKey, cid, sequence);
-  const results = await Promise.allSettled(
-    targets.map((t) => t.publish(ipnsName, signed.recordBytes))
+  const maxBumps = options?.maxSequenceBumps ?? 3;
+  const publishTargets = targets.filter((t) => typeof t.publish === "function");
+  if (publishTargets.length === 0) {
+    throw new Error("No publish-capable targets supplied to publishIPNSRecord");
+  }
+  let sequence;
+  let bumpFloor;
+  for (let attempt = 0; ; attempt++) {
+    if (sequence === void 0) {
+      sequence = await pickNextSequence(ipnsName, targets);
+    }
+    if (bumpFloor !== void 0) {
+      if (bumpFloor > sequence) sequence = bumpFloor;
+      bumpFloor = void 0;
+    }
+    const signed = await createSignedIPNSRecord(privateKey, cid, sequence);
+    const results = await Promise.allSettled(
+      publishTargets.map((t) => t.publish(ipnsName, signed.recordBytes))
+    );
+    const failures = results.map((r, i) => ({ r, name: publishTargets[i].name })).filter(({ r }) => r.status === "rejected");
+    if (failures.length === 0) {
+      return signed;
+    }
+    const conflictReasons = failures.filter(
+      ({ r }) => SEQ_CONFLICT_RE.test(typeof r.reason === "string" ? r.reason : String(r.reason))
+    );
+    if (conflictReasons.length > 0 && attempt < maxBumps) {
+      let bump = sequence;
+      for (const { r } of conflictReasons) {
+        const msg = typeof r.reason === "string" ? r.reason : String(r.reason);
+        const m = msg.match(SEQ_CONFLICT_RE);
+        if (m) {
+          const existing = BigInt(m[1]);
+          if (existing >= bump) bump = existing + 1n;
+        }
+      }
+      if (bump > sequence) {
+        console.warn(
+          `[publishIPNSRecord] Sequence conflict: server seq ${bump - 1n} >= current ${sequence}, bumping to ${bump} (attempt ${attempt + 1}/${maxBumps})`
+        );
+        sequence = bump;
+        continue;
+      }
+    }
+    if (failures.length < publishTargets.length) {
+      for (const { r, name } of failures) {
+        console.warn(`[publishIPNSRecord] target '${name}' failed:`, r.reason);
+      }
+      return signed;
+    }
+    if (conflictReasons.length > 0) {
+      throw new Error(
+        `IPNS sequence conflict not resolved after ${Math.min(attempt + 1, maxBumps)} bumps. All publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join("; ")}`
+      );
+    }
+    throw new Error(
+      `All IPNS publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join("; ")}`
+    );
+  }
+}
+async function pickNextSequence(ipnsName, targets) {
+  const capable = targets.filter((t) => typeof t.resolveSequence === "function");
+  if (capable.length === 0) {
+    return 0n;
+  }
+  for (const target of capable) {
+    try {
+      const current = await target.resolveSequence(ipnsName);
+      return current == null ? 0n : current + 1n;
+    } catch (err) {
+      console.warn(`[publishIPNSRecord] target '${target.name}' sequence resolve failed:`, err);
+    }
+  }
+  console.warn(`[publishIPNSRecord] no target could resolve sequence for ${ipnsName} \u2014 starting at 0n`);
+  return 0n;
+}
+
+// src/ipns/ipns-w3name.ts
+import { Logger as Logger2 } from "besonders-logger";
+import { base64pad as base64pad2 } from "multiformats/bases/base64";
+import * as W3Name from "w3name";
+var { WARN: WARN2, LOG: LOG2, DEBUG: DEBUG2, ERROR } = Logger2.setup(Logger2.INFO);
+async function tryResolveIPNS(ipns) {
+  const url = `https://name.web3.storage/name/${ipns.toString()}`;
+  let response;
+  try {
+    response = await fetch(url, { signal: AbortSignal.timeout(3e4) });
+  } catch (err) {
+    throw ERROR("[w3name] Network error resolving IPNS:", err);
+  }
+  if (response.status === 404) {
+    DEBUG2("[w3name] IPNS record not found (never published):", ipns.toString());
+    return null;
+  }
+  if (!response.ok) {
+    throw ERROR(`[w3name] HTTP ${response.status} resolving IPNS:`, response.statusText);
+  }
+  const existing = await W3Name.resolve(ipns);
+  return existing;
+}
+async function publishIPNS(ipnsPrivateKey, cid) {
+  const TIMEOUT_MS = 3e4;
+  const timeout = new Promise(
+    (_, reject) => setTimeout(() => reject(new Error(`publishIPNS timed out after ${TIMEOUT_MS}ms`)), TIMEOUT_MS)
   );
-  const failures = results.map((r, i) => ({ r, name: targets[i].name })).filter(({ r }) => r.status === "rejected");
-  if (failures.length > 0 && failures.length < targets.length) {
-    for (const { r, name } of failures) {
-      console.warn(`[publishIPNSRecord] target '${name}' failed:`, r.reason);
+  return Promise.race([_publishIPNSImpl(ipnsPrivateKey, cid), timeout]);
+}
+async function _publishIPNSImpl(ipnsPrivateKey, cid) {
+  const value = `/ipfs/${cid}`;
+  const ipns = await W3Name.from(ipnsPrivateKey);
+  let revision;
+  const existing = await tryResolveIPNS(ipns);
+  if (existing) {
+    revision = await W3Name.increment(existing, value);
+    DEBUG2("[w3name] incrementing revision for", ipns.toString());
+  } else {
+    revision = await W3Name.v0(ipns, value);
+    DEBUG2("[w3name] creating initial revision for", ipns.toString());
+  }
+  await W3Name.publish(revision, ipns.key);
+  DEBUG2("[w3name] published", cid.toString(), "to", ipns.toString());
+  return revision;
+}
+async function resolveZtaxSequence(baseUrl, ipnsName) {
+  const url = `${baseUrl.replace(/\/+$/, "")}/${ipnsName}`;
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (err) {
+    throw new Error(`Network error resolving sequence from ${baseUrl}: ${err}`);
+  }
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} resolving sequence from ${baseUrl}: ${response.statusText}`);
+  }
+  const body = await response.json();
+  if (typeof body.seq === "number") {
+    return BigInt(body.seq);
+  }
+  if (typeof body.record === "string") {
+    try {
+      const bytes = base64pad2.baseDecode(body.record);
+      const entry = unmarshalIPNSRecord(bytes);
+      return entry.sequence;
+    } catch {
+      WARN2("[resolveZtaxSequence] failed to unmarshal record for", ipnsName);
+      return null;
+    }
+  }
+  return null;
+}
+function ztaxTarget(baseUrl = "https://ipfs.zt.ax") {
+  const cleanBase = baseUrl.replace(/\/+$/, "");
+  return {
+    name: "zt.ax",
+    async publish(ipnsName, recordBytes) {
+      const url = `${cleanBase}/${ipnsName}`;
+      DEBUG2(`[ztaxTarget] POST ${url}`);
+      const res = await fetch(url, {
+        method: "POST",
+        body: base64pad2.baseEncode(recordBytes)
+      });
+      if (!res.ok) {
+        let detail = "";
+        try {
+          const body = await res.json();
+          detail = body.message ? ` \u2014 ${body.message}` : "";
+        } catch {
+          detail = res.statusText ? ` \u2014 ${res.statusText}` : "";
+        }
+        throw new Error(`zt.ax HTTP ${res.status}${detail}`);
+      }
+    },
+    async resolveSequence(ipnsName) {
+      return resolveZtaxSequence(cleanBase, ipnsName);
+    }
+  };
+}
+function w3nameTarget(serviceUrl = "https://name.web3.storage") {
+  return {
+    name: "w3name",
+    // No publish() — w3name is read-only; publishing goes through ztaxTarget
+    async resolveSequence(ipnsName) {
+      return resolveIPNSSequence(serviceUrl, ipnsName);
+    }
+  };
+}
+async function generateIpnsKey() {
+  return W3Name.create();
+}
+async function getW3NamePublic(pk) {
+  const ipns = await W3Name.from(pk);
+  return ipns.toString();
+}
+
+// src/ipns/ipns-watcher.ts
+import { Logger as Logger3 } from "besonders-logger";
+import { CID as CID2 } from "multiformats/cid";
+import ReconnectingWebSocket from "partysocket/ws";
+var { WARN: WARN3, LOG: LOG3, DEBUG: DEBUG3, ERROR: ERROR2 } = Logger3.setup(Logger3.INFO);
+function buildWsUrl(nameBaseUrl, name) {
+  const base = nameBaseUrl.replace(/\/+$/, "").replace(/^http/, "ws");
+  return `${base}/${name}/watch`;
+}
+function buildHttpUrl(nameBaseUrl, name) {
+  const base = nameBaseUrl.replace(/\/+$/, "");
+  return `${base}/${name}`;
+}
+function requireNameBaseUrl(nameBaseUrl, fn) {
+  if (!nameBaseUrl) {
+    throw new Error(
+      `[${fn}] nameBaseUrl is required. The legacy default https://name.web3.storage is shut down. Pass the base URL of a naming service that supports WebSocket subscriptions to /name/<ipns>/watch and HTTP GET on /name/<ipns>.`
+    );
+  }
+  return nameBaseUrl;
+}
+function parseCidFromIpnsValue(value) {
+  try {
+    const cidStr = value.startsWith("/ipfs/") ? value.slice(6) : value;
+    return CID2.parse(cidStr);
+  } catch {
+    DEBUG3("[parseCidFromIpnsValue] failed to parse:", value);
+    return null;
+  }
+}
+function watchNameRaw(nameBaseUrl, name, options) {
+  const resolvedBase = requireNameBaseUrl(nameBaseUrl, "watchNameRaw");
+  const url = buildWsUrl(resolvedBase, name);
+  DEBUG3("[watchNameRaw] connecting to", url);
+  const ws = new WebSocket(url);
+  ws.onopen = () => {
+    LOG3("[watchNameRaw] connected to", name);
+    options.onOpen?.();
+  };
+  ws.onmessage = (event) => {
+    try {
+      const record = JSON.parse(event.data);
+      DEBUG3("[watchNameRaw] received update for", name, record);
+      options.onUpdate(record);
+    } catch (err) {
+      WARN3("[watchNameRaw] failed to parse message:", event.data, err);
+      options.onError?.(err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+  ws.onerror = (event) => {
+    const errorMsg = event instanceof ErrorEvent ? event.message : "WebSocket error";
+    WARN3("[watchNameRaw] error for", name, ":", errorMsg);
+    options.onError?.(new Error(errorMsg));
+  };
+  ws.onclose = (event) => {
+    DEBUG3("[watchNameRaw] closed for", name, "code:", event.code);
+    options.onClose?.(event);
+  };
+  return {
+    close: () => {
+      DEBUG3("[watchNameRaw] closing connection for", name);
+      ws.close();
+    },
+    ws
+  };
+}
+var DEFAULT_LIVENESS_INTERVAL = 36e5;
+var IpnsWatcher = class {
+  name;
+  nameBaseUrl;
+  ws;
+  lastKnownValue = null;
+  options;
+  isFirstConnect = true;
+  livenessTimer = null;
+  connectedAt = null;
+  lastMessageAt = null;
+  constructor(nameBaseUrl, name, options) {
+    this.nameBaseUrl = requireNameBaseUrl(nameBaseUrl, "IpnsWatcher");
+    this.name = name;
+    this.options = options;
+    const url = buildWsUrl(this.nameBaseUrl, name);
+    DEBUG3("[IpnsWatcher] creating for", name);
+    this.ws = new ReconnectingWebSocket(url, [], {
+      maxReconnectionDelay: 9e5,
+      // 15min
+      minReconnectionDelay: 5e3,
+      reconnectionDelayGrowFactor: 2,
+      maxRetries: Infinity,
+      ...options.wsOptions
+    });
+    this.ws.onopen = () => {
+      LOG3("[IpnsWatcher] connected to", name);
+      this.connectedAt = /* @__PURE__ */ new Date();
+      options.onConnected?.();
+      if (this.isFirstConnect && (options.fetchInitialState ?? false)) {
+        this.checkForMissedUpdates();
+      } else if (!this.isFirstConnect && (options.catchUpOnReconnect ?? true)) {
+        this.checkForMissedUpdates();
+      }
+      this.isFirstConnect = false;
+      if (options.livenessCheck !== false) {
+        this.startLivenessCheck();
+      }
+    };
+    this.ws.onmessage = (event) => {
+      this.lastMessageAt = /* @__PURE__ */ new Date();
+      try {
+        const record = JSON.parse(event.data);
+        DEBUG3("[IpnsWatcher] received update for", name, record);
+        const lastValue = this.lastKnownValue;
+        const isNew = record.value !== lastValue;
+        const cid = parseCidFromIpnsValue(record.value);
+        if (!isNew && !options.includeUnchanged) {
+          DEBUG3("[IpnsWatcher] skipping unchanged value for", name);
+          return;
+        }
+        this.lastKnownValue = record.value;
+        const update = {
+          value: record.value,
+          cid,
+          lastValue,
+          isNew,
+          record
+        };
+        void options.onUpdate(update);
+      } catch (err) {
+        WARN3("[IpnsWatcher] failed to parse message:", event.data, err);
+        options.onError?.(err instanceof Error ? err : new Error(String(err)));
+      }
+    };
+    this.ws.onerror = (event) => {
+      const errorMsg = event instanceof ErrorEvent ? event.message : "WebSocket error";
+      if (errorMsg === "Unexpected EOF") {
+        LOG3("[IpnsWatcher] error for", name, ":", errorMsg, "(auto-reconnect enabled)");
+      } else {
+        WARN3("[IpnsWatcher] error for", name, ":", errorMsg);
+      }
+      if (errorMsg !== "Unexpected EOF") {
+        options.onError?.(new Error(errorMsg));
+      }
+    };
+    this.ws.onclose = () => {
+      DEBUG3("[IpnsWatcher] disconnected from", name);
+      this.stopLivenessCheck();
+      this.connectedAt = null;
+      this.lastMessageAt = null;
+      options.onDisconnected?.();
+    };
+  }
+  /**
+   * Resolve current IPNS value via HTTP API to catch missed updates
+   */
+  async checkForMissedUpdates() {
+    try {
+      DEBUG3("[IpnsWatcher] checking for missed updates for", this.name);
+      const response = await fetch(buildHttpUrl(this.nameBaseUrl, this.name));
+      if (!response.ok) {
+        if (response.status === 404) {
+          DEBUG3("[IpnsWatcher] IPNS not yet published:", this.name);
+          return;
+        }
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      const record = await response.json();
+      const lastValue = this.lastKnownValue;
+      const isNew = record.value !== lastValue;
+      const cid = parseCidFromIpnsValue(record.value);
+      if (!isNew && !this.options.includeUnchanged) {
+        DEBUG3("[IpnsWatcher] no new updates for", this.name);
+        return;
+      }
+      const logMsg = lastValue === null ? "[IpnsWatcher] fetched initial state for" : "[IpnsWatcher] caught missed update for";
+      LOG3(logMsg, this.name, {
+        previous: lastValue,
+        current: record.value
+      });
+      this.lastKnownValue = record.value;
+      const update = {
+        value: record.value,
+        cid,
+        lastValue,
+        isNew,
+        record
+      };
+      void this.options.onUpdate(update);
+    } catch (err) {
+      WARN3("[IpnsWatcher] failed to check for missed updates:", this.name, err);
+      this.options.onError?.(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+  /**
+   * Start periodic liveness checks to detect zombie connections.
+   */
+  startLivenessCheck() {
+    this.stopLivenessCheck();
+    const interval = this.options.livenessCheckInterval ?? DEFAULT_LIVENESS_INTERVAL;
+    DEBUG3("[IpnsWatcher] starting liveness check for", this.name, "interval:", interval);
+    this.livenessTimer = setInterval(() => {
+      void this.performLivenessCheck();
+    }, interval);
+  }
+  /**
+   * Stop periodic liveness checks.
+   */
+  stopLivenessCheck() {
+    if (this.livenessTimer !== null) {
+      DEBUG3("[IpnsWatcher] stopping liveness check for", this.name);
+      clearInterval(this.livenessTimer);
+      this.livenessTimer = null;
+    }
+  }
+  /**
+   * Perform a single liveness check via HTTP.
+   * If the HTTP value differs from lastKnownValue, the connection is stale.
+   */
+  async performLivenessCheck() {
+    try {
+      DEBUG3("[IpnsWatcher] performing liveness check for", this.name);
+      const response = await fetch(buildHttpUrl(this.nameBaseUrl, this.name));
+      if (!response.ok) {
+        if (response.status === 404) {
+          if (this.lastKnownValue === null) {
+            DEBUG3("[IpnsWatcher] liveness check OK (both null) for", this.name);
+            return;
+          }
+          WARN3("[IpnsWatcher] liveness check inconsistent (we have value, HTTP 404) for", this.name);
+          return;
+        }
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      const record = await response.json();
+      if (record.value === this.lastKnownValue) {
+        DEBUG3("[IpnsWatcher] liveness check OK for", this.name);
+        return;
+      }
+      const now = /* @__PURE__ */ new Date();
+      const silenceDuration = this.lastMessageAt ? now.getTime() - this.lastMessageAt.getTime() : this.connectedAt ? now.getTime() - this.connectedAt.getTime() : 0;
+      const staleInfo = {
+        connectedAt: this.connectedAt ?? now,
+        lastMessageAt: this.lastMessageAt,
+        silenceDuration,
+        staleValue: this.lastKnownValue,
+        currentValue: record.value
+      };
+      WARN3("[IpnsWatcher] stale connection detected for", this.name, {
+        connectedAt: staleInfo.connectedAt.toISOString(),
+        lastMessageAt: staleInfo.lastMessageAt?.toISOString() ?? "never",
+        silenceDuration: `${Math.round(silenceDuration / 1e3)}s`,
+        staleValue: staleInfo.staleValue,
+        currentValue: staleInfo.currentValue
+      });
+      this.options.onStaleConnection?.(staleInfo);
+      const lastValue = this.lastKnownValue;
+      const cid = parseCidFromIpnsValue(record.value);
+      this.lastKnownValue = record.value;
+      const update = {
+        value: record.value,
+        cid,
+        lastValue,
+        isNew: true,
+        record
+      };
+      void this.options.onUpdate(update);
+      LOG3("[IpnsWatcher] forcing reconnect due to stale connection for", this.name);
+      this.ws.reconnect();
+    } catch (err) {
+      WARN3("[IpnsWatcher] liveness check failed for", this.name, err);
+    }
+  }
+  /**
+   * Manually start/reconnect the WebSocket.
+   * Only needed if you used `wsOptions: { startClosed: true }`.
+   */
+  start() {
+    LOG3("[IpnsWatcher] starting watcher for", this.name);
+    this.ws.reconnect();
+  }
+  /**
+   * Alias for close() - for backward compatibility
+   */
+  stop() {
+    this.close();
+  }
+  /**
+   * Close the WebSocket connection and stop watching
+   */
+  close() {
+    LOG3("[IpnsWatcher] closing watcher for", this.name);
+    this.stopLivenessCheck();
+    this.ws.close();
+  }
+  /**
+   * Get the last known IPNS value
+   */
+  get lastValue() {
+    return this.lastKnownValue;
+  }
+  /**
+   * Get the WebSocket ready state
+   */
+  get readyState() {
+    return this.ws.readyState;
+  }
+};
+function watchName(nameBaseUrl, name, options) {
+  return new IpnsWatcher(nameBaseUrl, name, options);
+}
+async function* watchNameIterator(nameBaseUrl, name, signal) {
+  const queue = [];
+  let resolve2 = null;
+  let error = null;
+  const watcher = new IpnsWatcher(nameBaseUrl, name, {
+    onUpdate: (update) => {
+      queue.push(update);
+      resolve2?.();
+    },
+    onError: (err) => {
+      error = err instanceof Error ? err : new Error("WebSocket error");
+      resolve2?.();
+    }
+  });
+  signal?.addEventListener("abort", () => {
+    watcher.close();
+  });
+  try {
+    while (!signal?.aborted) {
+      if (queue.length > 0) {
+        yield queue.shift();
+      } else if (error) {
+        WARN3("[watchNameIterator] error occurred, continuing:", error);
+        error = null;
+      } else {
+        await new Promise((r) => {
+          resolve2 = r;
+        });
+        resolve2 = null;
+      }
     }
-  } else if (failures.length === targets.length) {
-    throw new Error(`All IPNS publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join("; ")}`);
+  } finally {
+    watcher.close();
   }
-  return signed;
 }
 export {
+  IpnsWatcher,
   createSignedIPNSRecord,
+  generateIpnsKey,
+  getW3NamePublic,
   ipnsNameFromPrivateKey,
+  publishIPNS,
   publishIPNSRecord,
   resolveIPNSSequence,
-  unmarshalIPNSRecord
+  resolveIPNSViaGateway,
+  resolveZtaxSequence,
+  unmarshalIPNSRecord,
+  w3nameTarget,
+  watchName,
+  watchNameIterator,
+  watchNameRaw,
+  ztaxTarget
 };
 //# sourceMappingURL=ipns.js.map