feat: refresh ipns record

packages/ipns/README.md

@@ -173,12 +173,15 @@ It is sometimes useful to be able to republish an existing IPNS record
 without needing the private key. This allows you to extend the availability
 of a record that was created elsewhere.
 
+There should be only one republisher per IPNS key. Multiple machines
+republishing the same key will conflict on sequence numbers and flood the
+DHT with redundant writes.
+
 ```TypeScript
 import { createHelia } from 'helia'
-import { ipns, ipnsValidator } from '@helia/ipns'
+import { ipns } from '@helia/ipns'
 import { delegatedRoutingV1HttpApiClient } from '@helia/delegated-routing-v1-http-api-client'
 import { CID } from 'multiformats/cid'
-import { multihashToIPNSRoutingKey, marshalIPNSRecord } from 'ipns'
 import { defaultLogger } from '@libp2p/logger'
 
 const helia = await createHelia()
@@ -193,18 +196,13 @@ 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)
+// republish to routing; throws RecordAlreadyPublishedError if a newer record
+// is already resolvable — pass `force: true` only if you know no one else is
+// republishing this key
+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)
 ```
 
 # Install

packages/ipns/src/errors.ts

@@ -1,3 +1,5 @@
+import type { IPNSRecord } from 'ipns'
+
 export class RecordsFailedValidationError extends Error {
   static name = 'RecordsFailedValidationError'
 
@@ -47,3 +49,12 @@ export class RecordNotFoundError extends Error {
   static name = 'RecordNotFoundError'
   name = 'RecordNotFoundError'
 }
+
+export class RecordAlreadyPublishedError extends Error {
+  static name = 'RecordAlreadyPublishedError'
+  name = 'RecordAlreadyPublishedError'
+
+  constructor (message: string, public readonly record: IPNSRecord) {
+    super(message)
+  }
+}

packages/ipns/src/index.ts

@@ -144,12 +144,15 @@
  * without needing the private key. This allows you to extend the availability
  * of a record that was created elsewhere.
  *
+ * There should be only one republisher per IPNS key. Multiple machines
+ * republishing the same key will conflict on sequence numbers and flood the
+ * DHT with redundant writes.
+ *
  * ```TypeScript
  * import { createHelia } from 'helia'
- * import { ipns, ipnsValidator } from '@helia/ipns'
+ * import { ipns } from '@helia/ipns'
  * import { delegatedRoutingV1HttpApiClient } from '@helia/delegated-routing-v1-http-api-client'
  * import { CID } from 'multiformats/cid'
- * import { multihashToIPNSRoutingKey, marshalIPNSRecord } from 'ipns'
  * import { defaultLogger } from '@libp2p/logger'
  *
  * const helia = await createHelia()
@@ -164,18 +167,13 @@
  * })
  * 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)
+ * // republish to routing; throws RecordAlreadyPublishedError if a newer record
+ * // is already resolvable — pass `force: true` only if you know no one else is
+ * // republishing this key
+ * 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)
+   * Only publish to the local datastore, skipping the routers (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,45 @@ 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
+
+  /**
+   * Only republish to the local datastore, skipping the routers (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")
+   *
+   * Defaults to `refresh` since `republish()` cannot sign new records without
+   * the private key.
+   *
+   * - `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 +333,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
@@ -346,13 +399,26 @@ export interface IPNS {
   /**
    * Stop republishing of an IPNS record
    *
-   * This will delete the last signed IPNS record from the datastore, but the
-   * key will remain in the keychain.
+   * This will delete the last signed IPNS record from the datastore. If a key
+   * name is passed, the key will remain in the keychain.
    *
    * 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
+   *
+   * Updates the record's upkeep policy to `options.upkeep` (default: 'refresh').
+   * The background republisher will then keep the record alive accordingly.
+   *
+   * Use `unpublish` to stop republishing a key.
+   *
+   * @throws {NotFoundError} when no existing records can be found
+   * @throws {RecordAlreadyPublishedError} when a record is already published; pass `force: true` to bypass
+   */
+  republish(key: CID<unknown, 0x72, 0x00 | 0x12, 1> | PublicKey | MultihashDigest<0x00 | 0x12> | PeerId, options?: RepublishOptions): Promise<IPNSRepublishResult>
 }
 
 export type { IPNSRouting } from './routing/index.ts'

packages/ipns/src/ipns.ts

@@ -5,7 +5,7 @@ import { IPNSResolver } from './ipns/resolver.ts'
 import { localStore } from './local-store.ts'
 import { helia } from './routing/helia.ts'
 import { localStoreRouting } from './routing/local-store.ts'
-import type { IPNSComponents, IPNS as IPNSInterface, IPNSOptions, IPNSPublishResult, IPNSResolveResult, PublishOptions, ResolveOptions } from './index.ts'
+import type { IPNSComponents, IPNS as IPNSInterface, IPNSOptions, IPNSPublishResult, IPNSRepublishResult, IPNSResolveResult, PublishOptions, RepublishOptions, ResolveOptions } from './index.ts'
 import type { LocalStore } from './local-store.ts'
 import type { IPNSRouting } from './routing/index.ts'
 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.ts'
 import type { LocalStore } from '../local-store.ts'
 import type { IPNSRouting } from '../routing/index.ts'
@@ -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)
   }
 }