feat: refresh ipns record

packages/ipns/README.md

@@ -188,18 +188,12 @@ const parsedCid: CID<unknown, 114, 0 | 18, 1> = CID.parse(ipnsName)
 const delegatedClient = createDelegatedRoutingV1HttpApiClient('https://delegated-ipfs.dev')
 const record = await delegatedClient.getIPNS(parsedCid)
 
-const routingKey = multihashToIPNSRoutingKey(parsedCid.multihash)
-const marshaledRecord = marshalIPNSRecord(record)
-
-// validate that they key corresponds to the record
-await ipnsValidator(routingKey, marshaledRecord)
-
-// publish record to routing
-await Promise.all(
-  name.routers.map(async r => {
-    await r.put(routingKey, marshaledRecord)
-  })
-)
+// publish the latest existing record to routing
+// use `options.force` if the record is already published
+const { record: latestRecord } = await name.republish(parsedCid, { record })
+
+// stop republishing a key
+await name.unpublish(parsedCid)
 ```
 
 # Install

packages/ipns/src/index.ts

@@ -159,18 +159,12 @@
  * const delegatedClient = createDelegatedRoutingV1HttpApiClient('https://delegated-ipfs.dev')
  * const record = await delegatedClient.getIPNS(parsedCid)
  *
- * const routingKey = multihashToIPNSRoutingKey(parsedCid.multihash)
- * const marshaledRecord = marshalIPNSRecord(record)
- *
- * // validate that they key corresponds to the record
- * await ipnsValidator(routingKey, marshaledRecord)
- *
- * // publish record to routing
- * await Promise.all(
- *   name.routers.map(async r => {
- *     await r.put(routingKey, marshaledRecord)
- *   })
- * )
+ * // publish the latest existing record to routing
+ * // use `options.force` if the record is already published
+ * const { record: latestRecord } = await name.republish(parsedCid, { record })
+ *
+ * // stop republishing a key
+ * await name.unpublish(parsedCid)
  * ```
  */
 
@@ -201,6 +195,11 @@ export type ResolveProgressEvents =
   ProgressEvent<'ipns:resolve:success', IPNSRecord> |
   ProgressEvent<'ipns:resolve:error', Error>
 
+export type RepublishProgressEvents =
+  ProgressEvent<'ipns:republish:start'> |
+  ProgressEvent<'ipns:republish:success', IPNSRecord> |
+  ProgressEvent<'ipns:republish:error', Error>
+
 export type DatastoreProgressEvents =
   ProgressEvent<'ipns:routing:datastore:put'> |
   ProgressEvent<'ipns:routing:datastore:get'> |
@@ -251,6 +250,27 @@ export interface ResolveOptions extends AbortOptions, ProgressOptions<ResolvePro
   nocache?: boolean
 }
 
+export interface RepublishOptions extends AbortOptions, ProgressOptions<RepublishProgressEvents | IPNSRoutingProgressEvents> {
+  /**
+   * A candidate IPNS record to use if no newer records are found
+   */
+  record?: IPNSRecord
+
+  /**
+   * Force the record to be published immediately even if it's already resolvable
+   *
+   * @default false
+   */
+  force?: boolean
+
+  /**
+   * Republish the latest existing record for the key on a regularly basis
+   *
+   * @default true
+   */
+  repeat?: boolean
+}
+
 export interface ResolveResult {
   /**
    * The CID that was resolved
@@ -282,6 +302,13 @@ export interface IPNSPublishResult {
   publicKey: PublicKey
 }
 
+export interface IPNSRepublishResult {
+  /**
+   * The published record
+   */
+  record: IPNSRecord
+}
+
 export interface IPNSResolver {
   /**
    * Accepts a libp2p public key, a CID with the libp2p-key codec and either the
@@ -347,7 +374,16 @@ export interface IPNS {
    * Note that the record may still be resolved by other peers until it expires
    * or is no longer valid.
    */
-  unpublish(keyName: string, options?: AbortOptions): Promise<void>
+  unpublish(keyName: string | CID<unknown, 0x72, 0x00 | 0x12, 1> | PublicKey | MultihashDigest<0x00 | 0x12> | PeerId, options?: AbortOptions): Promise<void>
+
+  /**
+   * Republish the latest known existing record to all routers
+   *
+   * This will automatically be done regularly unless `options.repeat` is false
+   *
+   * Use `unpublish` to stop republishing a key
+   */
+  republish(key: CID<unknown, 0x72, 0x00 | 0x12, 1> | PublicKey | MultihashDigest<0x00 | 0x12> | PeerId, options?: RepublishOptions): Promise<IPNSRepublishResult>
 }
 
 export type { IPNSRouting } from './routing/index.js'

packages/ipns/src/ipns.ts

@@ -5,7 +5,7 @@ import { IPNSResolver } from './ipns/resolver.ts'
 import { localStore } from './local-store.js'
 import { helia } from './routing/helia.js'
 import { localStoreRouting } from './routing/local-store.ts'
-import type { IPNSComponents, IPNS as IPNSInterface, IPNSOptions, IPNSPublishResult, IPNSResolveResult, PublishOptions, ResolveOptions } from './index.js'
+import type { IPNSComponents, IPNS as IPNSInterface, IPNSOptions, IPNSPublishResult, IPNSRepublishResult, IPNSResolveResult, PublishOptions, RepublishOptions, ResolveOptions } from './index.js'
 import type { LocalStore } from './local-store.js'
 import type { IPNSRouting } from './routing/index.js'
 import type { AbortOptions, PeerId, PublicKey, Startable } from '@libp2p/interface'
@@ -34,13 +34,14 @@ export class IPNS implements IPNSInterface, Startable {
       routers: this.routers,
       localStore: this.localStore
     })
-    this.republisher = new IPNSRepublisher(components, {
+    this.resolver = new IPNSResolver(components, {
       ...init,
       routers: this.routers,
       localStore: this.localStore
     })
-    this.resolver = new IPNSResolver(components, {
+    this.republisher = new IPNSRepublisher(components, {
       ...init,
+      resolver: this.resolver,
       routers: this.routers,
       localStore: this.localStore
     })
@@ -81,7 +82,11 @@ export class IPNS implements IPNSInterface, Startable {
     return this.resolver.resolve(key, options)
   }
 
-  async unpublish (keyName: string, options?: AbortOptions): Promise<void> {
+  async unpublish (keyName: string | CID<unknown, 0x72, 0x00 | 0x12, 1> | PublicKey | MultihashDigest<0x00 | 0x12> | PeerId, options?: AbortOptions): Promise<void> {
     return this.publisher.unpublish(keyName, options)
   }
+
+  async republish (key: CID<unknown, 0x72, 0x00 | 0x12, 1> | PublicKey | MultihashDigest<0x00 | 0x12> | PeerId, options: RepublishOptions = {}): Promise<IPNSRepublishResult> {
+    return this.republisher.republish(key, options)
+  }
 }

packages/ipns/src/ipns/publisher.ts

@@ -4,6 +4,7 @@ import { createIPNSRecord, marshalIPNSRecord, multihashToIPNSRoutingKey, unmarsh
 import { CID } from 'multiformats/cid'
 import { CustomProgressEvent } from 'progress-events'
 import { DEFAULT_LIFETIME_MS, DEFAULT_TTL_NS } from '../constants.ts'
+import { keyToMultihash } from '../utils.ts'
 import type { IPNSPublishResult, PublishOptions } from '../index.js'
 import type { LocalStore } from '../local-store.js'
 import type { IPNSRouting } from '../routing/index.js'
@@ -88,10 +89,13 @@ export class IPNSPublisher {
     }
   }
 
-  async unpublish (keyName: string, options?: AbortOptions): Promise<void> {
-    const { publicKey } = await this.keychain.exportKey(keyName)
-    const digest = publicKey.toMultihash()
-    const routingKey = multihashToIPNSRoutingKey(digest)
+  async unpublish (keyName: string | CID<unknown, 0x72, 0x00 | 0x12, 1> | PublicKey | MultihashDigest<0x00 | 0x12> | PeerId, options?: AbortOptions): Promise<void> {
+    if (typeof keyName === 'string') {
+      const { publicKey } = await this.keychain.exportKey(keyName)
+      keyName = publicKey.toMultihash()
+    }
+
+    const routingKey = multihashToIPNSRoutingKey(keyToMultihash(keyName))
     await this.localStore.delete(routingKey, options)
   }
 }

packages/ipns/src/ipns/republisher.ts

@@ -1,13 +1,21 @@
+import { NotFoundError } from '@libp2p/interface'
 import { Queue, repeatingTask } from '@libp2p/utils'
-import { createIPNSRecord, marshalIPNSRecord, unmarshalIPNSRecord } from 'ipns'
+import { createIPNSRecord, marshalIPNSRecord, multihashFromIPNSRoutingKey, multihashToIPNSRoutingKey, unmarshalIPNSRecord } from 'ipns'
+import { ipnsValidator } from 'ipns/validator'
+import { CustomProgressEvent } from 'progress-events'
+import { equals as uint8ArrayEquals } from 'uint8arrays/equals'
 import { DEFAULT_REPUBLISH_CONCURRENCY, DEFAULT_REPUBLISH_INTERVAL_MS, DEFAULT_TTL_NS } from '../constants.ts'
-import { shouldRepublish } from '../utils.js'
+import { ipnsSelector } from '../index.ts'
+import { keyToMultihash, shouldRefresh, shouldRepublish } from '../utils.js'
+import type { IPNSRepublishResult, RepublishOptions } from '../index.ts'
 import type { LocalStore } from '../local-store.js'
+import type { IPNSResolver } from './resolver.ts'
 import type { IPNSRouting } from '../routing/index.js'
-import type { AbortOptions, ComponentLogger, Libp2p, Logger, PrivateKey } from '@libp2p/interface'
+import type { AbortOptions, ComponentLogger, Libp2p, Logger, PeerId, PrivateKey, PublicKey } from '@libp2p/interface'
 import type { Keychain } from '@libp2p/keychain'
 import type { RepeatingTask } from '@libp2p/utils'
 import type { IPNSRecord } from 'ipns'
+import type { CID, MultihashDigest } from 'multiformats/cid'
 
 export interface IPNSRepublisherComponents {
   logger: ComponentLogger
@@ -17,13 +25,15 @@ export interface IPNSRepublisherComponents {
 export interface IPNSRepublisherInit {
   republishConcurrency?: number
   republishInterval?: number
+  resolver: IPNSResolver
   routers: IPNSRouting[]
   localStore: LocalStore
 }
 
 export class IPNSRepublisher {
   public readonly routers: IPNSRouting[]
   private readonly localStore: LocalStore
+  private readonly resolver: IPNSResolver
   private readonly republishTask: RepeatingTask
   private readonly log: Logger
   private readonly keychain: Keychain
@@ -33,6 +43,7 @@ export class IPNSRepublisher {
   constructor (components: IPNSRepublisherComponents, init: IPNSRepublisherInit) {
     this.log = components.logger.forComponent('helia:ipns')
     this.localStore = init.localStore
+    this.resolver = init.resolver
     this.keychain = components.libp2p.services.keychain
     this.republishConcurrency = init.republishConcurrency || DEFAULT_REPUBLISH_CONCURRENCY
     this.started = components.libp2p.status === 'started'
@@ -78,6 +89,7 @@ export class IPNSRepublisher {
 
     try {
       const recordsToRepublish: Array<{ routingKey: Uint8Array, record: IPNSRecord }> = []
+      const keysToRepublish: Array<Uint8Array> = []
 
       // Find all records using the localStore.list method
       for await (const { routingKey, record, metadata, created } of this.localStore.list(options)) {
@@ -87,6 +99,16 @@ export class IPNSRepublisher {
           this.log(`no metadata found for record ${routingKey.toString()}, skipping`)
           continue
         }
+
+        if (metadata.refresh) {
+          if (!shouldRefresh(created)) {
+            this.log.trace(`skipping record ${routingKey.toString()} within republish threshold`)
+            continue
+          }
+          keysToRepublish.push(routingKey)
+          continue
+        }
+
         let ipnsRecord: IPNSRecord
         try {
           ipnsRecord = unmarshalIPNSRecord(record)
@@ -135,10 +157,93 @@ export class IPNSRepublisher {
           }
         }, options)
       }
+      for (const routingKey of keysToRepublish) {
+        // resolve the latest record
+        let latestRecord: IPNSRecord
+        try {
+          const { record } = await this.resolver.resolve(multihashFromIPNSRoutingKey(routingKey))
+          latestRecord = record
+        } catch (err: any) {
+          this.log.error('unable to find existing record to republish - %e', err)
+          continue
+        }
+
+        // Add job to queue to republish the existing record to all routers
+        queue.add(async () => {
+          try {
+            await Promise.all(
+              this.routers.map(r => r.put(routingKey, marshalIPNSRecord(latestRecord), { ...options, overwrite: true }))
+            )
+          } catch (err: any) {
+            this.log.error('error republishing existing record - %e', err)
+          }
+        }, options)
+      }
     } catch (err: any) {
       this.log.error('error during republish - %e', err)
     }
 
     await queue.onIdle(options) // Wait for all jobs to complete
   }
+
+  async republish (key: CID<unknown, 0x72, 0x00 | 0x12, 1> | PublicKey | MultihashDigest<0x00 | 0x12> | PeerId, options: RepublishOptions = {}): Promise<IPNSRepublishResult> {
+    const records: IPNSRecord[] = []
+    let publishedRecord: IPNSRecord | null = null
+    const digest = keyToMultihash(key)
+    const routingKey = multihashToIPNSRoutingKey(digest)
+
+    try {
+      // collect records for key
+      if (options.record != null) {
+        // user supplied record
+        await ipnsValidator(routingKey, marshalIPNSRecord(options.record))
+        records.push(options.record)
+      }
+      try {
+        // local record
+        const { record } = await this.resolver.resolve(key, { offline: true })
+        records.push(record)
+      } catch (err: any) {
+        if (err.name !== 'NotFoundError') {
+          throw err
+        }
+      }
+      try {
+        // published record
+        const { record } = await this.resolver.resolve(key, { nocache: true })
+        publishedRecord = record
+        records.push(record)
+      } catch (err: any) {
+        if (err.name !== 'NotFoundError') {
+          throw err
+        }
+      }
+      if (records.length === 0) {
+        throw new NotFoundError('Found no existing records to republish')
+      }
+
+      // check if record is already published
+      const selectedRecord = records[ipnsSelector(routingKey, records.map(marshalIPNSRecord))]
+      const marshaledRecord = marshalIPNSRecord(selectedRecord)
+      if (options.force !== true && publishedRecord != null && uint8ArrayEquals(marshaledRecord, marshalIPNSRecord(publishedRecord))) {
+        throw new Error('Record already published')
+      }
+
+      // publish record to routers
+      const putOptions = {
+        ...options,
+        metadata: options.repeat !== false ? { refresh: true } : undefined,
+        // overwrite so Record.created is reset for #republish
+        overwrite: true
+      }
+      await Promise.all(
+        this.routers.map(r => r.put(routingKey, marshaledRecord, putOptions))
+      )
+
+      return { record: selectedRecord }
+    } catch (err: any) {
+      options.onProgress?.(new CustomProgressEvent<Error>('ipns:republish:error', err))
+      throw err
+    }
+  }
 }

packages/ipns/src/ipns/resolver.ts

@@ -8,6 +8,7 @@ import { CID } from 'multiformats/cid'
 import * as Digest from 'multiformats/hashes/digest'
 import { DEFAULT_TTL_NS } from '../constants.ts'
 import { InvalidValueError, RecordsFailedValidationError, UnsupportedMultibasePrefixError, UnsupportedMultihashCodecError } from '../errors.js'
+import { LocalStoreRouting } from '../routing/local-store.ts'
 import { isCodec, IDENTITY_CODEC, SHA2_256_CODEC, isLibp2pCID } from '../utils.js'
 import type { IPNSResolveResult, ResolveOptions, ResolveResult } from '../index.js'
 import type { LocalStore } from '../local-store.js'
@@ -177,6 +178,11 @@ export class IPNSResolver {
       this.routers.map(async (router) => {
         let record: Uint8Array
 
+        // skip checking cache when nocache is true
+        if (router instanceof LocalStoreRouting && options.nocache === true) {
+          return
+        }
+
         try {
           record = await router.get(routingKey, {
             ...options,