@helia/ipns 4.0.0 → 5.0.0

package/src/index.ts

@@ -3,20 +3,64 @@
  *
  * IPNS operations using a Helia node
  *
- * @example Using libp2p and pubsub routers
+ * @example Getting started
  *
  * With {@link IPNSRouting} routers:
  *
  * ```typescript
  * import { createHelia } from 'helia'
  * import { ipns } from '@helia/ipns'
- * import { libp2p, pubsub } from '@helia/ipns/routing'
  * import { unixfs } from '@helia/unixfs'
  *
  * const helia = await createHelia()
+ * const name = ipns(helia)
+ *
+ * // create a public key to publish as an IPNS name
+ * const keyInfo = await helia.libp2p.services.keychain.createKey('my-key')
+ * const peerId = await helia.libp2p.services.keychain.exportPeerId(keyInfo.name)
+ *
+ * // store some data to publish
+ * const fs = unixfs(helia)
+ * const cid = await fs.add(Uint8Array.from([0, 1, 2, 3, 4]))
+ *
+ * // publish the name
+ * await name.publish(peerId, cid)
+ *
+ * // resolve the name
+ * const cid = name.resolve(peerId)
+ * ```
+ *
+ * @example Using custom PubSub router
+ *
+ * Additional IPNS routers can be configured - these enable alternative means to
+ * publish and resolve IPNS names.
+ *
+ * One example is the PubSub router - this requires an instance of Helia with
+ * libp2p PubSub configured.
+ *
+ * It works by subscribing to a pubsub topic for each IPNS name that we try to
+ * resolve. Updated IPNS records are shared on these topics so an update must
+ * occur before the name is resolvable.
+ *
+ * This router is only suitable for networks where IPNS updates are frequent
+ * and multiple peers are listening on the topic(s), otherwise update messages
+ * may fail to be published with "Insufficient peers" errors.
+ *
+ * ```typescript
+ * import { createHelia, libp2pDefaults } from 'helia'
+ * import { ipns } from '@helia/ipns'
+ * import { pubsub } from '@helia/ipns/routing'
+ * import { unixfs } from '@helia/unixfs'
+ * import { gossipsub } from '@chainsafe/libp2p-gossipsub'
+ *
+ * const libp2pOptions = libp2pDefaults()
+ * libp2pOptions.services.pubsub = gossipsub()
+ *
+ * const helia = await createHelia({
+ *   libp2p: libp2pOptions
+ * })
  * const name = ipns(helia, {
  *  routers: [
- *    libp2p(helia),
  *    pubsub(helia)
  *  ]
  * })
@@ -121,9 +165,11 @@ import { ipnsValidator } from 'ipns/validator'
 import { CID } from 'multiformats/cid'
 import { CustomProgressEvent } from 'progress-events'
 import { defaultResolver } from './dns-resolvers/default.js'
+import { helia } from './routing/helia.js'
 import { localStore, type LocalStore } from './routing/local-store.js'
 import type { IPNSRouting, IPNSRoutingEvents } from './routing/index.js'
 import type { DNSResponse } from './utils/dns.js'
+import type { Routing } from '@helia/interface'
 import type { AbortOptions, PeerId } from '@libp2p/interface'
 import type { Datastore } from 'interface-datastore'
 import type { IPNSRecord } from 'ipns'
@@ -249,6 +295,7 @@ export type { IPNSRouting } from './routing/index.js'
 
 export interface IPNSComponents {
   datastore: Datastore
+  routing: Routing
 }
 
 class DefaultIPNS implements IPNS {
@@ -258,7 +305,10 @@ class DefaultIPNS implements IPNS {
   private readonly defaultResolvers: DNSResolver[]
 
   constructor (components: IPNSComponents, routers: IPNSRouting[] = [], resolvers: DNSResolver[] = []) {
-    this.routers = routers
+    this.routers = [
+      helia(components.routing),
+      ...routers
+    ]
     this.localStore = localStore(components.datastore)
     this.defaultResolvers = resolvers.length > 0 ? resolvers : [defaultResolver()]
   }
@@ -376,21 +426,44 @@ class DefaultIPNS implements IPNS {
     }
 
     const records: Uint8Array[] = []
+    let foundInvalid = 0
 
     await Promise.all(
       routers.map(async (router) => {
+        let record: Uint8Array
+
+        try {
+          record = await router.get(routingKey, {
+            ...options,
+            validate: false
+          })
+        } catch (err: any) {
+          if (router === this.localStore && err.code === 'ERR_NOT_FOUND') {
+            log('did not have record locally')
+          } else {
+            log.error('error finding IPNS record', err)
+          }
+
+          return
+        }
+
         try {
-          const record = await router.get(routingKey, options)
           await ipnsValidator(routingKey, record)
 
           records.push(record)
         } catch (err) {
+          // we found a record, but the validator rejected it
+          foundInvalid++
           log.error('error finding IPNS record', err)
         }
       })
     )
 
     if (records.length === 0) {
+      if (foundInvalid > 0) {
+        throw new CodeError(`${foundInvalid > 1 ? `${foundInvalid} records` : 'Record'} found for routing key ${foundInvalid > 1 ? 'were' : 'was'} invalid`, 'ERR_RECORDS_FAILED_VALIDATION')
+      }
+
       throw new CodeError('Could not find record for routing key', 'ERR_NOT_FOUND')
     }
 
@@ -407,7 +480,7 @@ export interface IPNSOptions {
   resolvers?: DNSResolver[]
 }
 
-export function ipns (components: IPNSComponents, { routers = [], resolvers = [] }: IPNSOptions): IPNS {
+export function ipns (components: IPNSComponents, { routers = [], resolvers = [] }: IPNSOptions = {}): IPNS {
   return new DefaultIPNS(components, routers, resolvers)
 }
 

package/src/routing/helia.ts

@@ -0,0 +1,45 @@
+import { CustomProgressEvent, type ProgressEvent } from 'progress-events'
+import type { GetOptions, PutOptions } from './index.js'
+import type { IPNSRouting } from '../index.js'
+import type { Routing } from '@helia/interface'
+
+export interface HeliaRoutingComponents {
+  routing: Routing
+}
+
+export type HeliaRoutingProgressEvents =
+  ProgressEvent<'ipns:routing:helia:error', Error>
+
+export class HeliaRouting implements IPNSRouting {
+  private readonly routing: Routing
+
+  constructor (routing: Routing) {
+    this.routing = routing
+  }
+
+  async put (routingKey: Uint8Array, marshaledRecord: Uint8Array, options: PutOptions = {}): Promise<void> {
+    try {
+      await this.routing.put(routingKey, marshaledRecord, options)
+    } catch (err: any) {
+      options.onProgress?.(new CustomProgressEvent<Error>('ipns:routing:helia:error', err))
+    }
+  }
+
+  async get (routingKey: Uint8Array, options: GetOptions = {}): Promise<Uint8Array> {
+    try {
+      return await this.routing.get(routingKey, options)
+    } catch (err: any) {
+      options.onProgress?.(new CustomProgressEvent<Error>('ipns:routing:helia:error', err))
+    }
+
+    throw new Error('Not found')
+  }
+}
+
+/**
+ * The helia routing uses any available Routers configured on the passed Helia
+ * node. This could be libp2p, HTTP API Delegated Routing, etc.
+ */
+export function helia (routing: Routing): IPNSRouting {
+  return new HeliaRouting(routing)
+}

package/src/routing/index.ts

@@ -1,4 +1,4 @@
-import type { Libp2pContentRoutingProgressEvents } from './libp2p.js'
+import type { HeliaRoutingProgressEvents } from './helia.js'
 import type { DatastoreProgressEvents } from './local-store.js'
 import type { PubSubProgressEvents } from './pubsub.js'
 import type { AbortOptions } from '@libp2p/interface'
@@ -9,7 +9,12 @@ export interface PutOptions extends AbortOptions, ProgressOptions {
 }
 
 export interface GetOptions extends AbortOptions, ProgressOptions {
-
+  /**
+   * Pass false to not perform validation actions
+   *
+   * @default true
+   */
+  validate?: boolean
 }
 
 export interface IPNSRouting {
@@ -19,8 +24,8 @@ export interface IPNSRouting {
 
 export type IPNSRoutingEvents =
   DatastoreProgressEvents |
-  Libp2pContentRoutingProgressEvents |
+  HeliaRoutingProgressEvents |
   PubSubProgressEvents
 
-export { libp2p } from './libp2p.js'
+export { helia } from './helia.js'
 export { pubsub } from './pubsub.js'

package/dist/src/routing/libp2p.d.ts

@@ -1,22 +0,0 @@
-import { type ProgressEvent } from 'progress-events';
-import type { GetOptions, PutOptions } from './index.js';
-import type { IPNSRouting } from '../index.js';
-import type { ContentRouting } from '@libp2p/interface';
-export interface Libp2pContentRoutingComponents {
-    libp2p: {
-        contentRouting: ContentRouting;
-    };
-}
-export type Libp2pContentRoutingProgressEvents = ProgressEvent<'ipns:routing:libp2p:error', Error>;
-export declare class Libp2pContentRouting implements IPNSRouting {
-    private readonly contentRouting;
-    constructor(components: Libp2pContentRoutingComponents);
-    put(routingKey: Uint8Array, marshaledRecord: Uint8Array, options?: PutOptions): Promise<void>;
-    get(routingKey: Uint8Array, options?: GetOptions): Promise<Uint8Array>;
-}
-/**
- * The libp2p routing uses any available Content Routers configured on the
- * passed libp2p node. This could be KadDHT, HTTP API Delegated Routing, etc.
- */
-export declare function libp2p(components: Libp2pContentRoutingComponents): IPNSRouting;
-//# sourceMappingURL=libp2p.d.ts.map

package/dist/src/routing/libp2p.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"libp2p.d.ts","sourceRoot":"","sources":["../../../src/routing/libp2p.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE;QACN,cAAc,EAAE,cAAc,CAAA;KAC/B,CAAA;CACF;AAED,MAAM,MAAM,kCAAkC,GAC5C,aAAa,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAA;AAEnD,qBAAa,oBAAqB,YAAW,WAAW;IACtD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;gBAElC,UAAU,EAAE,8BAA8B;IAIjD,GAAG,CAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlG,GAAG,CAAE,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,UAAU,CAAC;CASlF;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAE,UAAU,EAAE,8BAA8B,GAAG,WAAW,CAE/E"}

package/dist/src/routing/libp2p.js

@@ -1,32 +0,0 @@
-import { CustomProgressEvent } from 'progress-events';
-export class Libp2pContentRouting {
-    contentRouting;
-    constructor(components) {
-        this.contentRouting = components.libp2p.contentRouting;
-    }
-    async put(routingKey, marshaledRecord, options = {}) {
-        try {
-            await this.contentRouting.put(routingKey, marshaledRecord, options);
-        }
-        catch (err) {
-            options.onProgress?.(new CustomProgressEvent('ipns:routing:libp2p:error', err));
-        }
-    }
-    async get(routingKey, options = {}) {
-        try {
-            return await this.contentRouting.get(routingKey, options);
-        }
-        catch (err) {
-            options.onProgress?.(new CustomProgressEvent('ipns:routing:libp2p:error', err));
-        }
-        throw new Error('Not found');
-    }
-}
-/**
- * The libp2p routing uses any available Content Routers configured on the
- * passed libp2p node. This could be KadDHT, HTTP API Delegated Routing, etc.
- */
-export function libp2p(components) {
-    return new Libp2pContentRouting(components);
-}
-//# sourceMappingURL=libp2p.js.map

package/dist/src/routing/libp2p.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"libp2p.js","sourceRoot":"","sources":["../../../src/routing/libp2p.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAsB,MAAM,iBAAiB,CAAA;AAczE,MAAM,OAAO,oBAAoB;IACd,cAAc,CAAgB;IAE/C,YAAa,UAA0C;QACrD,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC,cAAc,CAAA;IACxD,CAAC;IAED,KAAK,CAAC,GAAG,CAAE,UAAsB,EAAE,eAA2B,EAAE,UAAsB,EAAE;QACtF,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,CAAC,CAAA;QACrE,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,mBAAmB,CAAQ,2BAA2B,EAAE,GAAG,CAAC,CAAC,CAAA;QACxF,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAE,UAAsB,EAAE,UAAsB,EAAE;QACzD,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;QAC3D,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,mBAAmB,CAAQ,2BAA2B,EAAE,GAAG,CAAC,CAAC,CAAA;QACxF,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,WAAW,CAAC,CAAA;IAC9B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAE,UAA0C;IAChE,OAAO,IAAI,oBAAoB,CAAC,UAAU,CAAC,CAAA;AAC7C,CAAC"}

package/src/routing/libp2p.ts

@@ -1,47 +0,0 @@
-import { CustomProgressEvent, type ProgressEvent } from 'progress-events'
-import type { GetOptions, PutOptions } from './index.js'
-import type { IPNSRouting } from '../index.js'
-import type { ContentRouting } from '@libp2p/interface'
-
-export interface Libp2pContentRoutingComponents {
-  libp2p: {
-    contentRouting: ContentRouting
-  }
-}
-
-export type Libp2pContentRoutingProgressEvents =
-  ProgressEvent<'ipns:routing:libp2p:error', Error>
-
-export class Libp2pContentRouting implements IPNSRouting {
-  private readonly contentRouting: ContentRouting
-
-  constructor (components: Libp2pContentRoutingComponents) {
-    this.contentRouting = components.libp2p.contentRouting
-  }
-
-  async put (routingKey: Uint8Array, marshaledRecord: Uint8Array, options: PutOptions = {}): Promise<void> {
-    try {
-      await this.contentRouting.put(routingKey, marshaledRecord, options)
-    } catch (err: any) {
-      options.onProgress?.(new CustomProgressEvent<Error>('ipns:routing:libp2p:error', err))
-    }
-  }
-
-  async get (routingKey: Uint8Array, options: GetOptions = {}): Promise<Uint8Array> {
-    try {
-      return await this.contentRouting.get(routingKey, options)
-    } catch (err: any) {
-      options.onProgress?.(new CustomProgressEvent<Error>('ipns:routing:libp2p:error', err))
-    }
-
-    throw new Error('Not found')
-  }
-}
-
-/**
- * The libp2p routing uses any available Content Routers configured on the
- * passed libp2p node. This could be KadDHT, HTTP API Delegated Routing, etc.
- */
-export function libp2p (components: Libp2pContentRoutingComponents): IPNSRouting {
-  return new Libp2pContentRouting(components)
-}