@le-space/aleph-bootstrap 0.9.4 → 0.9.6

package/README.md

@@ -13,6 +13,7 @@ It is designed for two complementary jobs:
 - `discoverAlephBootstrapMultiaddrs(options)`
 - `createLibp2pAlephBootstrap(options)`
 - `filterRelayBootstrapPostsByProfile(posts, profile?)`
+- `unsupportedRelayBootstrapReason(post)`
 - `filterRelayBootstrapPostsByRegistration(posts, registrationId?)`
 - `filterPublicMultiaddrs(addrs, options?)`
 - `createRelayBootstrapPost(options)`
@@ -71,6 +72,12 @@ downstream, a browser probe wave against an unscoped list spent its outbound
 stream budget on dead addresses and wrote off the one healthy relay along with
 them.
 
+A record this package cannot use — a legacy v1 post, or a type it did not ask
+for — is **skipped, not fatal**. One such record on a public, append-only
+channel would otherwise blind discovery for every consumer, permanently, and
+nobody can FORGET somebody else's post. Pass `onUnsupportedPost` to see what
+was skipped and why.
+
 Use `registrationId` for anything that bakes addresses into a build or dials
 them on start. Omit both to see the whole channel, which is what a dashboard
 wants.

package/index.d.ts

@@ -112,6 +112,15 @@ interface DiscoverAlephBootstrapOptions {
      * start; omit it to see the whole channel.
      */
     registrationId?: string | readonly string[];
+    /**
+     * Called for each record discovery had to skip. Optional, and the default of
+     * doing nothing is deliberate — a skipped record is not an error for the
+     * consumer — but a consumer whose relay went missing wants to see this.
+     */
+    onUnsupportedPost?: (skipped: {
+        hash: string | null | undefined;
+        reason: string;
+    }) => void;
     fetch?: typeof fetch;
 }
 interface FilterPublicMultiaddrsOptions {
@@ -220,7 +229,24 @@ declare function verifyRelayBootstrapDualKeyContent(content: RelayBootstrapConte
     now?: number;
 }): Promise<RelayBootstrapVerificationResult>;
 declare function fetchAlephBootstrapPosts(options?: DiscoverAlephBootstrapOptions): Promise<RelayBootstrapPostRecord[]>;
-declare function selectCurrentRelayBootstrapPosts(posts: readonly RelayBootstrapPostRecord[], options?: Pick<DiscoverAlephBootstrapOptions, "maxAgeMs"> & {
+/**
+ * Why this post cannot be used, or `null` if it can.
+ *
+ * This used to throw, and one record of the wrong type took the whole page
+ * with it. The channel is public and append-only: anybody with an ETH key can
+ * publish into it, nobody can FORGET somebody else's post, and every consumer
+ * polls the same page. So a single legacy record — not ours, not removable —
+ * would blind discovery for everyone, permanently.
+ *
+ * The Rust client learned this the same way and changed the same shape: after
+ * a production incident on 2026-08-30, `get_messages_iterator` was page-strict
+ * and one message the validator rejected failed every poll, leaving the
+ * scheduler unable to see new v-programs at all (aleph-im/aleph-rs#386). The
+ * answer there was to yield per message and carry on; the answer here is to
+ * skip the record and say which one it was.
+ */
+declare function unsupportedRelayBootstrapReason(post: RelayBootstrapPostRecord): string | null;
+declare function selectCurrentRelayBootstrapPosts(posts: readonly RelayBootstrapPostRecord[], options?: Pick<DiscoverAlephBootstrapOptions, "maxAgeMs" | "onUnsupportedPost"> & {
     now?: number;
 }): RelayBootstrapPostRecord[];
 /**
@@ -254,4 +280,4 @@ declare function createLibp2pAlephBootstrap(options?: DiscoverAlephBootstrapOpti
     tagName?: string;
 }): Promise<ReturnType<typeof bootstrap>>;
 
-export { type CreateRelayBootstrapPostOptions, DEFAULT_ALEPH_API_HOST, DEFAULT_ALEPH_BOOTSTRAP_CHANNEL, DEFAULT_ALEPH_BOOTSTRAP_POST_TYPE, DEFAULT_ALEPH_BOOTSTRAP_REF, DEFAULT_BOOTSTRAP_COMPACT_MULTIADDR_LIMIT, DEFAULT_BOOTSTRAP_MAX_AGE_MS, DEFAULT_BOOTSTRAP_MAX_PAGES, DEFAULT_BOOTSTRAP_PAGINATION, type DiscoverAlephBootstrapOptions, type FilterPublicMultiaddrsOptions, RELAY_BOOTSTRAP_SIGNATURE_SCHEME, type RelayBootstrapAuthorizationPayload, type RelayBootstrapAuthorizationRecord, type RelayBootstrapContent, type RelayBootstrapPostContent, type RelayBootstrapPostRecord, type RelayBootstrapProofPayload, type RelayBootstrapProofRecord, type RelayBootstrapProofSigner, type RelayBootstrapTrustMode, type RelayBootstrapVerificationResult, buildRelayBootstrapPostContent, createLibp2pAlephBootstrap, createRelayBootstrapPost, dedupeMultiaddrs, discoverAlephBootstrapMultiaddrs, fetchAlephBootstrapPosts, filterPublicMultiaddrs, filterRelayBootstrapPostsByProfile, filterRelayBootstrapPostsByRegistration, isBrowserDialableMultiaddr, isPublicMultiaddr, relayBootstrapMultiaddrsHash, relayBootstrapTrustMode, selectCompactRelayBootstrapMultiaddrs, selectCurrentRelayBootstrapPosts, signRelayBootstrapAuthorization, signRelayBootstrapProof, verifyRelayBootstrapAuthorization, verifyRelayBootstrapDualKeyContent, verifyRelayBootstrapProof };
+export { type CreateRelayBootstrapPostOptions, DEFAULT_ALEPH_API_HOST, DEFAULT_ALEPH_BOOTSTRAP_CHANNEL, DEFAULT_ALEPH_BOOTSTRAP_POST_TYPE, DEFAULT_ALEPH_BOOTSTRAP_REF, DEFAULT_BOOTSTRAP_COMPACT_MULTIADDR_LIMIT, DEFAULT_BOOTSTRAP_MAX_AGE_MS, DEFAULT_BOOTSTRAP_MAX_PAGES, DEFAULT_BOOTSTRAP_PAGINATION, type DiscoverAlephBootstrapOptions, type FilterPublicMultiaddrsOptions, RELAY_BOOTSTRAP_SIGNATURE_SCHEME, type RelayBootstrapAuthorizationPayload, type RelayBootstrapAuthorizationRecord, type RelayBootstrapContent, type RelayBootstrapPostContent, type RelayBootstrapPostRecord, type RelayBootstrapProofPayload, type RelayBootstrapProofRecord, type RelayBootstrapProofSigner, type RelayBootstrapTrustMode, type RelayBootstrapVerificationResult, buildRelayBootstrapPostContent, createLibp2pAlephBootstrap, createRelayBootstrapPost, dedupeMultiaddrs, discoverAlephBootstrapMultiaddrs, fetchAlephBootstrapPosts, filterPublicMultiaddrs, filterRelayBootstrapPostsByProfile, filterRelayBootstrapPostsByRegistration, isBrowserDialableMultiaddr, isPublicMultiaddr, relayBootstrapMultiaddrsHash, relayBootstrapTrustMode, selectCompactRelayBootstrapMultiaddrs, selectCurrentRelayBootstrapPosts, signRelayBootstrapAuthorization, signRelayBootstrapProof, unsupportedRelayBootstrapReason, verifyRelayBootstrapAuthorization, verifyRelayBootstrapDualKeyContent, verifyRelayBootstrapProof };

package/index.js

@@ -595,20 +595,24 @@ async function fetchAlephBootstrapPosts(options = {}) {
   }
   const payload = await response.json();
   const posts = (payload.posts ?? []).map((entry) => normalizeRelayBootstrapPostRecord(entry)).filter((entry) => entry != null).sort((left, right) => compareRelayBootstrapPostRecency(right, left));
-  posts.forEach(assertSupportedRelayBootstrapPost);
-  return posts;
+  return usableRelayBootstrapPosts(posts, options.onUnsupportedPost);
 }
-function assertSupportedRelayBootstrapPost(post) {
+function unsupportedRelayBootstrapReason(post) {
   if (post.type === "relay-bootstrap") {
-    throw new Error(
-      "Legacy relay-bootstrap record encountered. Only relay-bootstrap-v2 is supported."
-    );
+    return "legacy relay-bootstrap record; only relay-bootstrap-v2 is supported";
   }
   if (post.type && post.type !== DEFAULT_ALEPH_BOOTSTRAP_POST_TYPE) {
-    throw new Error(
-      `Unsupported relay bootstrap post type: ${post.type}. Expected ${DEFAULT_ALEPH_BOOTSTRAP_POST_TYPE}.`
-    );
+    return `unsupported post type ${post.type}; expected ${DEFAULT_ALEPH_BOOTSTRAP_POST_TYPE}`;
   }
+  return null;
+}
+function usableRelayBootstrapPosts(posts, onUnsupportedPost) {
+  return posts.filter((post) => {
+    const reason = unsupportedRelayBootstrapReason(post);
+    if (!reason) return true;
+    onUnsupportedPost?.({ hash: post.itemHash ?? post.hash, reason });
+    return false;
+  });
 }
 function compareRelayBootstrapPostRecency(left, right) {
   const leftUpdatedAt = left.content?.updatedAt ?? 0;
@@ -629,8 +633,7 @@ function selectCurrentRelayBootstrapPosts(posts, options = {}) {
   const maxAgeMs = options.maxAgeMs ?? DEFAULT_BOOTSTRAP_MAX_AGE_MS;
   const now = options.now ?? Date.now();
   const selected = /* @__PURE__ */ new Map();
-  for (const post of posts) {
-    assertSupportedRelayBootstrapPost(post);
+  for (const post of usableRelayBootstrapPosts(posts, options.onUnsupportedPost)) {
     const content = post.content;
     if (!content) continue;
     if (now - content.updatedAt > maxAgeMs) continue;
@@ -777,6 +780,7 @@ export {
   selectCurrentRelayBootstrapPosts,
   signRelayBootstrapAuthorization,
   signRelayBootstrapProof,
+  unsupportedRelayBootstrapReason,
   verifyRelayBootstrapAuthorization,
   verifyRelayBootstrapDualKeyContent,
   verifyRelayBootstrapProof

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/aleph-bootstrap",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Aleph-backed libp2p bootstrap discovery and relay registration helpers.",
   "license": "MIT",
   "type": "module",