@le-space/aleph-bootstrap 0.9.3 → 0.9.5

package/README.md

@@ -12,6 +12,9 @@ It is designed for two complementary jobs:
 
 - `discoverAlephBootstrapMultiaddrs(options)`
 - `createLibp2pAlephBootstrap(options)`
+- `filterRelayBootstrapPostsByProfile(posts, profile?)`
+- `unsupportedRelayBootstrapReason(post)`
+- `filterRelayBootstrapPostsByRegistration(posts, registrationId?)`
 - `filterPublicMultiaddrs(addrs, options?)`
 - `createRelayBootstrapPost(options)`
 - `signRelayBootstrapAuthorization(args)`
@@ -45,6 +48,40 @@ By default, discovery will:
 - verify dual-key records when they are present
 - ignore malformed or invalid dual-key records
 
+## Scoping discovery
+
+The channel is shared. Several relay implementations register in it, and so
+does every throwaway relay an E2E run starts — under the same profile as the
+production one, with a registration that outlives the machine it describes,
+because guests self-publish with generated keys and no remaining key can
+FORGET the post.
+
+Two scopes, and most consumers want both:
+
+```ts
+const list = await discoverAlephBootstrapMultiaddrs({
+  profile: 'orbitdb-relay',                          // not uc-go-peer's relays
+  registrationId: 'relay:orbitdb-relay:orbitdb-relay' // and not the E2E ones
+})
+```
+
+`profile` keeps out relays a consumer cannot use at all — an orbitdb app that
+dials a `uc-go-peer` relay never gets a shared circuit and sits at
+`candidates: 0`. `registrationId` keeps out its own corpses: measured
+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.
+
 If a consumer wants to require the stronger model:
 
 ```ts

package/index.d.ts

@@ -103,6 +103,24 @@ interface DiscoverAlephBootstrapOptions {
      * When omitted, posts of every profile are returned (previous behaviour).
      */
     profile?: string | readonly string[];
+    /**
+     * Restrict discovery further, to the registrations published under this id
+     * (e.g. `"relay:orbitdb-relay:orbitdb-relay"`). Profile is not fine enough:
+     * an E2E run's throwaway relays register under the same profile as the
+     * production one, and a registration outlives the machine it describes. Use
+     * this for anything that bakes addresses into a build or dials them on
+     * 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 {
@@ -211,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[];
 /**
@@ -219,10 +254,30 @@ declare function selectCurrentRelayBootstrapPosts(posts: readonly RelayBootstrap
  * A missing/empty filter is a no-op so existing callers are unaffected.
  */
 declare function filterRelayBootstrapPostsByProfile(posts: readonly RelayBootstrapPostRecord[], profile?: string | readonly string[]): RelayBootstrapPostRecord[];
+/**
+ * Keep only the registrations a consumer published for itself.
+ *
+ * Profile is not fine enough. Every ephemeral relay an E2E run starts
+ * registers under the same profile as the production one - as
+ * `relay:<profile>:<name>-e2e-*` - and a registration outlives the machine it
+ * describes, because guests self-publish with generated keys and no remaining
+ * key can FORGET the post. So the channel accumulates registrations that are
+ * indistinguishable from the real one by profile alone, and were alive when
+ * they were written.
+ *
+ * Measured downstream: a browser probe wave against that list exhausted its
+ * outbound stream budget on dead addresses and wrote off the one healthy relay
+ * along with the corpses, leaving both browsers with nothing to dial.
+ *
+ * Omitting the scope returns every registration, which is the previous
+ * behaviour and the right default for a consumer that wants to see the channel
+ * rather than its own corner of it.
+ */
+declare function filterRelayBootstrapPostsByRegistration(posts: readonly RelayBootstrapPostRecord[], registrationId?: string | readonly string[]): RelayBootstrapPostRecord[];
 declare function discoverAlephBootstrapMultiaddrs(options?: DiscoverAlephBootstrapOptions): Promise<string[]>;
 declare function createLibp2pAlephBootstrap(options?: DiscoverAlephBootstrapOptions & {
     timeout?: number;
     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, 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;
@@ -653,6 +656,14 @@ function filterRelayBootstrapPostsByProfile(posts, profile) {
     (post) => post.content != null && allowed.has(String(post.content.profile))
   );
 }
+function filterRelayBootstrapPostsByRegistration(posts, registrationId) {
+  const wanted = (typeof registrationId === "string" ? [registrationId] : registrationId ?? []).map((entry) => entry.trim()).filter(Boolean);
+  if (wanted.length === 0) return [...posts];
+  const allowed = new Set(wanted);
+  return posts.filter(
+    (post) => post.content != null && allowed.has(String(post.content.registrationId))
+  );
+}
 async function filterTrustedRelayBootstrapPosts(posts, options = {}) {
   const requireDualKeyAttestation = options.requireDualKeyAttestation ?? false;
   const verifyDualKeyAttestation = options.verifyDualKeyAttestation ?? true;
@@ -692,11 +703,14 @@ async function discoverAlephBootstrapMultiaddrs(options = {}) {
       pagination
     });
     collectedPosts.push(...pagePosts);
-    const selectedPosts = filterRelayBootstrapPostsByProfile(
-      selectCurrentRelayBootstrapPosts(collectedPosts, {
-        maxAgeMs: options.maxAgeMs
-      }),
-      options.profile
+    const selectedPosts = filterRelayBootstrapPostsByRegistration(
+      filterRelayBootstrapPostsByProfile(
+        selectCurrentRelayBootstrapPosts(collectedPosts, {
+          maxAgeMs: options.maxAgeMs
+        }),
+        options.profile
+      ),
+      options.registrationId
     );
     const trustedPosts = await filterTrustedRelayBootstrapPosts(selectedPosts, {
       requireDualKeyAttestation: options.requireDualKeyAttestation,
@@ -757,6 +771,7 @@ export {
   fetchAlephBootstrapPosts,
   filterPublicMultiaddrs,
   filterRelayBootstrapPostsByProfile,
+  filterRelayBootstrapPostsByRegistration,
   isBrowserDialableMultiaddr,
   isPublicMultiaddr,
   relayBootstrapMultiaddrsHash,
@@ -765,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.3",
+  "version": "0.9.5",
   "description": "Aleph-backed libp2p bootstrap discovery and relay registration helpers.",
   "license": "MIT",
   "type": "module",