feat: refresh ipns record

packages/ipns/README.md

@@ -193,18 +193,12 @@ const delegatedClient = delegatedRoutingV1HttpApiClient({
 })
 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

@@ -34,7 +34,11 @@
  * value.
  *
  * ```TypeScript
- * import { createHelia } from 'helia'
+ * import { createHelia } from 'helia'export interface IPNSRecordMetadata {
+  keyName: string
+  lifetime: number
+  upkeep: Upkeep
+}
  * import { ipns } from '@helia/ipns'
  * import { unixfs } from '@helia/unixfs'
  * import { generateKeyPair } from '@libp2p/crypto/keys'
@@ -164,18 +168,12 @@
  * })
  * 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 the latest existing record to routing
+ * // use `options.force` if the record is already published
+ * const { record: latestRecord } = await name.republish(parsedCid, { record })
  *
- * // publish record to routing
- * await Promise.all(
- *   name.routers.map(async r => {
- *     await r.put(routingKey, marshaledRecord)
- *   })
- * )
+ * // stop republishing a key
+ * await name.unpublish(parsedCid)
  * ```
  */
 
@@ -206,6 +204,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'> |
@@ -219,7 +222,7 @@ export interface PublishOptions extends AbortOptions, ProgressOptions<PublishPro
   lifetime?: number
 
   /**
-   * Only publish to a local datastore (default: false)
+   * Initially only publish to a local datastore (default: false)
    */
   offline?: boolean
 
@@ -233,11 +236,15 @@ export interface PublishOptions extends AbortOptions, ProgressOptions<PublishPro
    * The TTL of the record in ms (default: 5 minutes)
    */
   ttl?: number
-}
 
-export interface IPNSRecordMetadata {
-  keyName: string
-  lifetime: number
+  /**
+   * Automated record upkeep policy. (default: "republish")
+   *
+   * - `republish`: create a new record with a refreshed TTL
+   * - `refresh`: publish the existing record until it expires
+   * - `none`: disable automated publishing
+   */
+  upkeep?: 'republish' | 'refresh' | 'none'
 }
 
 export interface ResolveOptions extends AbortOptions, ProgressOptions<ResolveProgressEvents | IPNSRoutingProgressEvents> {
@@ -256,6 +263,42 @@ 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
+
+  /**
+   * Initially only republish to a local datastore (default: false)
+   */
+  offline?: boolean
+
+  /**
+   * Skip resolution of latest record before republishing (default: false)
+   *
+   * It's important to resolve the latest record before republishing to routers
+   * Resolution should only be skipped when confident the latest record is already known
+   */
+  skipResolution?: boolean
+
+  /**
+   * Force the record to be republished even when already resolvable (default: false)
+   *
+   * It's important for republishing to be handled by a single machine
+   * Republishing should only be forced when confident the record is not being republished by other clients
+   */
+  force?: boolean
+
+  /**
+   * Automated record upkeep policy. (default: "refresh")
+   *
+   * - `refresh`: republish the existing record until it expires
+   * - `none`: disable automated publishing
+   */
+  upkeep?: 'refresh' | 'none'
+}
+
 export interface ResolveResult {
   /**
    * The CID that was resolved
@@ -287,6 +330,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
@@ -352,7 +402,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,8 @@ 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 { Upkeep } from '../pb/metadata.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'
@@ -57,13 +59,14 @@ export class IPNSPublisher {
       const record = await createIPNSRecord(privKey, value, sequenceNumber, lifetime, { ...options, ttlNs })
       const marshaledRecord = marshalIPNSRecord(record)
 
+      const metadata = { keyName, lifetime, upkeep: Upkeep[options.upkeep ?? 'republish'] }
       if (options.offline === true) {
         // only store record locally
-        await this.localStore.put(routingKey, marshaledRecord, { ...options, metadata: { keyName, lifetime } })
+        await this.localStore.put(routingKey, marshaledRecord, { ...options, metadata })
       } else {
         // publish record to routing (including the local store)
         await Promise.all(this.routers.map(async r => {
-          await r.put(routingKey, marshaledRecord, { ...options, metadata: { keyName, lifetime } })
+          await r.put(routingKey, marshaledRecord, { ...options, metadata })
         }))
       }
 
@@ -88,10 +91,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)
   }
 }