@helia/ipns 7.0.0-ecf5394 → 7.1.0-1561e4a

package/src/index.ts

@@ -241,7 +241,7 @@ import { localStore, type LocalStore } from './routing/local-store.js'
 import type { IPNSRouting, IPNSRoutingEvents } from './routing/index.js'
 import type { Routing } from '@helia/interface'
 import type { AbortOptions, ComponentLogger, Logger, PeerId } from '@libp2p/interface'
-import type { DNS, ResolveDnsProgressEvents } from '@multiformats/dns'
+import type { Answer, DNS, ResolveDnsProgressEvents } from '@multiformats/dns'
 import type { Datastore } from 'interface-datastore'
 import type { IPNSRecord } from 'ipns'
 import type { ProgressEvent, ProgressOptions } from 'progress-events'
@@ -254,6 +254,8 @@ const HOUR = 60 * MINUTE
 const DEFAULT_LIFETIME_MS = 24 * HOUR
 const DEFAULT_REPUBLISH_INTERVAL_MS = 23 * HOUR
 
+const DEFAULT_TTL_NS = BigInt(HOUR) * 1_000_000n
+
 export type PublishProgressEvents =
   ProgressEvent<'ipns:publish:start'> |
   ProgressEvent<'ipns:publish:success', IPNSRecord> |
@@ -294,9 +296,18 @@ export interface PublishOptions extends AbortOptions, ProgressOptions<PublishPro
 
 export interface ResolveOptions extends AbortOptions, ProgressOptions<ResolveProgressEvents | IPNSRoutingEvents> {
   /**
-   * Do not query the network for the IPNS record (default: false)
+   * Do not query the network for the IPNS record
+   *
+   * @default false
    */
   offline?: boolean
+
+  /**
+   * Do not use cached IPNS Record entries
+   *
+   * @default false
+   */
+  nocache?: boolean
 }
 
 export interface ResolveDNSLinkOptions extends AbortOptions, ProgressOptions<ResolveDNSLinkProgressEvents> {
@@ -331,10 +342,33 @@ export interface RepublishOptions extends AbortOptions, ProgressOptions<Republis
 }
 
 export interface ResolveResult {
+  /**
+   * The CID that was resolved
+   */
   cid: CID
+
+  /**
+   * Any path component that was part of the resolved record
+   *
+   * @default ""
+   */
   path: string
 }
 
+export interface IPNSResolveResult extends ResolveResult {
+  /**
+   * The resolved record
+   */
+  record: IPNSRecord
+}
+
+export interface DNSLinkResolveResult extends ResolveResult {
+  /**
+   * The resolved record
+   */
+  answer: Answer
+}
+
 export interface IPNS {
   /**
    * Creates an IPNS record signed by the passed PeerId that will resolve to the passed value
@@ -347,12 +381,12 @@ export interface IPNS {
    * Accepts a public key formatted as a libp2p PeerID and resolves the IPNS record
    * corresponding to that public key until a value is found
    */
-  resolve(key: PeerId, options?: ResolveOptions): Promise<ResolveResult>
+  resolve(key: PeerId, options?: ResolveOptions): Promise<IPNSResolveResult>
 
   /**
    * Resolve a CID from a dns-link style IPNS record
    */
-  resolveDNSLink(domain: string, options?: ResolveDNSLinkOptions): Promise<ResolveResult>
+  resolveDNSLink(domain: string, options?: ResolveDNSLinkOptions): Promise<DNSLinkResolveResult>
 
   /**
    * Periodically republish all IPNS records found in the datastore
@@ -393,8 +427,8 @@ class DefaultIPNS implements IPNS {
 
       if (await this.localStore.has(routingKey, options)) {
         // if we have published under this key before, increment the sequence number
-        const buf = await this.localStore.get(routingKey, options)
-        const existingRecord = unmarshal(buf)
+        const { record } = await this.localStore.get(routingKey, options)
+        const existingRecord = unmarshal(record)
         sequenceNumber = existingRecord.sequence + 1n
       }
 
@@ -416,17 +450,23 @@ class DefaultIPNS implements IPNS {
     }
   }
 
-  async resolve (key: PeerId, options: ResolveOptions = {}): Promise<ResolveResult> {
+  async resolve (key: PeerId, options: ResolveOptions = {}): Promise<IPNSResolveResult> {
     const routingKey = peerIdToRoutingKey(key)
     const record = await this.#findIpnsRecord(routingKey, options)
 
-    return this.#resolve(record.value, options)
+    return {
+      ...(await this.#resolve(record.value, options)),
+      record
+    }
   }
 
-  async resolveDNSLink (domain: string, options: ResolveDNSLinkOptions = {}): Promise<ResolveResult> {
+  async resolveDNSLink (domain: string, options: ResolveDNSLinkOptions = {}): Promise<DNSLinkResolveResult> {
     const dnslink = await resolveDNSLink(domain, this.dns, this.log, options)
 
-    return this.#resolve(dnslink, options)
+    return {
+      ...(await this.#resolve(dnslink.value, options)),
+      answer: dnslink.answer
+    }
   }
 
   republish (options: RepublishOptions = {}): void {
@@ -465,7 +505,7 @@ class DefaultIPNS implements IPNS {
     }, options.interval ?? DEFAULT_REPUBLISH_INTERVAL_MS)
   }
 
-  async #resolve (ipfsPath: string, options: ResolveOptions = {}): Promise<ResolveResult> {
+  async #resolve (ipfsPath: string, options: ResolveOptions = {}): Promise<{ cid: CID, path: string }> {
     const parts = ipfsPath.split('/')
     try {
       const scheme = parts[1]
@@ -494,22 +534,69 @@ class DefaultIPNS implements IPNS {
   }
 
   async #findIpnsRecord (routingKey: Uint8Array, options: ResolveOptions = {}): Promise<IPNSRecord> {
-    let routers = [
-      this.localStore,
-      ...this.routers
-    ]
+    const records: Uint8Array[] = []
+    const cached = await this.localStore.has(routingKey, options)
+
+    if (cached) {
+      log('record is present in the cache')
+
+      if (options.nocache !== true) {
+        try {
+          // check the local cache first
+          const { record, created } = await this.localStore.get(routingKey, options)
+
+          this.log('record retrieved from cache')
+
+          // validate the record
+          await ipnsValidator(routingKey, record)
+
+          this.log('record was valid')
+
+          // check the TTL
+          const ipnsRecord = unmarshal(record)
+
+          // IPNS TTL is in nanoseconds, convert to milliseconds, default to one
+          // hour
+          const ttlMs = Number((ipnsRecord.ttl ?? DEFAULT_TTL_NS) / 1_000_000n)
+          const ttlExpires = created.getTime() + ttlMs
+
+          if (ttlExpires > Date.now()) {
+            // the TTL has not yet expired, return the cached record
+            this.log('record TTL was valid')
+            return ipnsRecord
+          }
+
+          if (options.offline === true) {
+            // the TTL has expired but we are skipping the routing search
+            this.log('record TTL has been reached but we are resolving offline-only, returning record')
+            return ipnsRecord
+          }
+
+          this.log('record TTL has been reached, searching routing for updates')
+
+          // add the local record to our list of resolved record, and also
+          // search the routing for updates - the most up to date record will be
+          // returned
+          records.push(record)
+        } catch (err) {
+          this.log('cached record was invalid', err)
+          await this.localStore.delete(routingKey, options)
+        }
+      } else {
+        log('ignoring local cache due to nocache=true option')
+      }
+    }
 
     if (options.offline === true) {
-      routers = [
-        this.localStore
-      ]
+      throw new CodeError('Record was not present in the cache or has expired', 'ERR_NOT_FOUND')
     }
 
-    const records: Uint8Array[] = []
+    log('did not have record locally')
+
     let foundInvalid = 0
 
     await Promise.all(
-      routers.map(async (router) => {
+      this.routers.map(async (router) => {
         let record: Uint8Array
 
         try {
@@ -518,11 +605,7 @@ class DefaultIPNS implements IPNS {
             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)
-          }
+          log.error('error finding IPNS record', err)
 
           return
         }

package/src/routing/local-store.ts

@@ -1,8 +1,9 @@
 import { Record } from '@libp2p/kad-dht'
 import { type Datastore, Key } from 'interface-datastore'
 import { CustomProgressEvent, type ProgressEvent } from 'progress-events'
+import { equals as uint8ArrayEquals } from 'uint8arrays/equals'
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
-import type { GetOptions, IPNSRouting, PutOptions } from '../routing'
+import type { GetOptions, PutOptions } from '../routing'
 import type { AbortOptions } from '@libp2p/interface'
 
 function dhtRoutingKey (key: Uint8Array): Key {
@@ -14,8 +15,16 @@ export type DatastoreProgressEvents =
   ProgressEvent<'ipns:routing:datastore:get'> |
   ProgressEvent<'ipns:routing:datastore:error', Error>
 
-export interface LocalStore extends IPNSRouting {
+export interface GetResult {
+  record: Uint8Array
+  created: Date
+}
+
+export interface LocalStore {
+  put(routingKey: Uint8Array, marshaledRecord: Uint8Array, options?: PutOptions): Promise<void>
+  get(routingKey: Uint8Array, options?: GetOptions): Promise<GetResult>
   has(routingKey: Uint8Array, options?: AbortOptions): Promise<boolean>
+  delete(routingKey: Uint8Array, options?: AbortOptions): Promise<void>
 }
 
 /**
@@ -29,6 +38,21 @@ export function localStore (datastore: Datastore): LocalStore {
       try {
         const key = dhtRoutingKey(routingKey)
 
+        // don't overwrite existing, identical records as this will affect the
+        // TTL
+        try {
+          const existingBuf = await datastore.get(key)
+          const existingRecord = Record.deserialize(existingBuf)
+
+          if (uint8ArrayEquals(existingRecord.value, marshalledRecord)) {
+            return
+          }
+        } catch (err: any) {
+          if (err.code !== 'ERR_NOT_FOUND') {
+            throw err
+          }
+        }
+
         // Marshal to libp2p record as the DHT does
         const record = new Record(routingKey, marshalledRecord, new Date())
 
@@ -39,7 +63,7 @@ export function localStore (datastore: Datastore): LocalStore {
         throw err
       }
     },
-    async get (routingKey: Uint8Array, options: GetOptions = {}): Promise<Uint8Array> {
+    async get (routingKey: Uint8Array, options: GetOptions = {}): Promise<GetResult> {
       try {
         const key = dhtRoutingKey(routingKey)
 
@@ -49,7 +73,10 @@ export function localStore (datastore: Datastore): LocalStore {
         // Unmarshal libp2p record as the DHT does
         const record = Record.deserialize(buf)
 
-        return record.value
+        return {
+          record: record.value,
+          created: record.timeReceived
+        }
       } catch (err: any) {
         options.onProgress?.(new CustomProgressEvent<Error>('ipns:routing:datastore:error', err))
         throw err
@@ -58,6 +85,10 @@ export function localStore (datastore: Datastore): LocalStore {
     async has (routingKey: Uint8Array, options: AbortOptions = {}): Promise<boolean> {
       const key = dhtRoutingKey(routingKey)
       return datastore.has(key, options)
+    },
+    async delete (routingKey, options): Promise<void> {
+      const key = dhtRoutingKey(routingKey)
+      return datastore.delete(key, options)
     }
   }
 }

package/src/routing/pubsub.ts

@@ -72,7 +72,7 @@ class PubSubRouting implements IPNSRouting {
     await ipnsValidator(routingKey, message.data)
 
     if (await this.localStore.has(routingKey)) {
-      const currentRecord = await this.localStore.get(routingKey)
+      const { record: currentRecord } = await this.localStore.get(routingKey)
 
       if (uint8ArrayEquals(currentRecord, message.data)) {
         log('not storing record as we already have it')
@@ -128,7 +128,9 @@ class PubSubRouting implements IPNSRouting {
       }
 
       // chain through to local store
-      return await this.localStore.get(routingKey, options)
+      const { record } = await this.localStore.get(routingKey, options)
+
+      return record
     } catch (err: any) {
       options.onProgress?.(new CustomProgressEvent<Error>('ipns:pubsub:error', err))
       throw err