@helia/interface 6.2.1 → 7.0.0

package/src/blocks.ts

@@ -1,6 +1,6 @@
 import type { RoutingFindProvidersProgressEvents } from './routing.ts'
-import type { PeerId, AbortOptions } from '@libp2p/interface'
 import type { Multiaddr } from '@multiformats/multiaddr'
+import type { AbortOptions } from 'abort-error'
 import type { Blockstore } from 'interface-blockstore'
 import type { CID } from 'multiformats/cid'
 import type { ProgressEvent, ProgressOptions } from 'progress-events'
@@ -16,7 +16,7 @@ export interface ProviderOptions {
    * child blocks, a `findProviders` routing query will be run to find peers
    * that can supply the blocks.
    */
-  providers?: Array<PeerId | Multiaddr | Multiaddr[]>
+  providers?: Array<CID | Multiaddr | Multiaddr[]>
 }
 
 /**
@@ -25,7 +25,7 @@ export interface ProviderOptions {
 export interface BlockBrokerConnectProgressEvent {
   broker: string
   type: 'connect'
-  provider: PeerId
+  provider: CID
   cid: CID
 }
 
@@ -35,7 +35,7 @@ export interface BlockBrokerConnectProgressEvent {
 export interface BlockBrokerConnectedProgressEvent {
   broker: string
   type: 'connected'
-  provider: PeerId
+  provider: CID
   address: Multiaddr
   cid: CID
 }
@@ -46,7 +46,7 @@ export interface BlockBrokerConnectedProgressEvent {
 export interface BlockBrokerRequestBlockProgressEvent {
   broker: string
   type: 'request-block'
-  provider: PeerId
+  provider: CID
   cid: CID
 }
 
@@ -56,7 +56,7 @@ export interface BlockBrokerRequestBlockProgressEvent {
 export interface BlockBrokerReceiveBlockProgressEvent {
   broker: string
   type: 'receive-block'
-  provider: PeerId
+  provider: CID
   cid: CID
 }
 
@@ -150,7 +150,7 @@ ProgressOptions<DeleteBlockProgressEvents>, ProgressOptions<DeleteManyBlocksProg
    * Adds a new peer to the session if they are supported and are either
    * not already in the session and have not been evicted previously.
    */
-  addPeer (peer: PeerId | Multiaddr | Multiaddr[], options?: AbortOptions): Promise<void>
+  addPeer (peer: CID | Multiaddr | Multiaddr[], options?: AbortOptions): Promise<void>
 }
 
 export interface BlockRetrievalOptions <ProgressEvents extends ProgressEvent<any, any> = ProgressEvent<any, any>> extends AbortOptions, ProgressOptions<ProgressEvents>, ProviderOptions {
@@ -232,7 +232,7 @@ export interface SessionBlockBroker<RetrieveProgressEvents extends ProgressEvent
    * Adds a new peer to the session if they are supported and are either
    * not already in the session and have not been evicted previously.
    */
-  addPeer (peer: PeerId | Multiaddr | Multiaddr[], options?: AbortOptions): Promise<void>
+  addPeer (peer: CID | Multiaddr | Multiaddr[], options?: AbortOptions): Promise<void>
 }
 
 export const DEFAULT_SESSION_MIN_PROVIDERS = 1

package/src/errors.ts

@@ -42,3 +42,8 @@ export class InvalidCodecError extends Error {
     this.name = 'InvalidCodecError'
   }
 }
+
+export class UnknownCryptoError extends Error {
+  static name = 'UnknownCryptoError'
+  name = 'UnknownCryptoError'
+}

package/src/graph-walker.ts

@@ -0,0 +1,38 @@
+import type { CodecLoader } from './index.js'
+import type { AbortOptions } from '@libp2p/interface'
+import type { Blockstore } from 'interface-blockstore'
+import type { BlockView, CID, Version } from 'multiformats'
+
+export interface GraphWalkerComponents {
+  blockstore: Blockstore
+  getCodec: CodecLoader
+}
+
+export interface GraphWalkerInit {}
+
+export interface GraphNode<
+  T = unknown,
+  C extends number = number,
+  A extends number = number,
+  V extends Version = 0 | 1
+> {
+  block: BlockView<T, C, A, V>
+  depth: number
+  path: CID[]
+}
+
+export interface WalkOptions<T> extends AbortOptions {
+  /**
+   * Stop traversal once `node.depth` reaches this value. The root is
+   * depth 0. Default: Infinity (walk the entire DAG).
+   */
+  depth?: number
+
+  includeChild?(child: CID, parent: BlockView<T, number, number, 0 | 1>): boolean
+}
+
+export interface GraphWalker {
+  walk<T = any>(cid: CID, options?: WalkOptions<T>): AsyncGenerator<GraphNode<T>>
+}
+
+export type GraphWalkerFactory = (components: GraphWalkerComponents) => GraphWalker

package/src/index.ts

@@ -14,35 +14,51 @@
  * ```
  */
 
-import type { Blocks } from './blocks.ts'
+import type { BlockBroker, Blocks } from './blocks.ts'
 import type { Pins } from './pins.ts'
-import type { Routing } from './routing.ts'
-import type { AbortOptions, ComponentLogger, Libp2p, Metrics, TypedEventEmitter } from '@libp2p/interface'
+import type { Router, Routing } from './routing.ts'
+import type { CryptoLoader, Keychain } from '@ipshipyard/keychain'
+import type { Metrics } from '@libp2p/interface'
 import type { DNS } from '@multiformats/dns'
+import type { AbortOptions } from 'abort-error'
+import type { ComponentLogger } from 'birnam'
 import type { Datastore } from 'interface-datastore'
-import type { Await } from 'interface-store'
+import type { TypedEventEmitter } from 'main-event'
 import type { BlockCodec, MultihashHasher } from 'multiformats'
 import type { CID } from 'multiformats/cid'
 import type { ProgressEvent, ProgressOptions } from 'progress-events'
 
-export type { Await, AwaitIterable } from 'interface-store'
-
 export interface CodecLoader {
-  <T = any, Code extends number = any>(code: Code): Await<BlockCodec<Code, T>>
+  <T = any, Code extends number = any>(code: Code, options?: AbortOptions): BlockCodec<Code, T> | Promise<BlockCodec<Code, T>>
 }
 
 export interface HasherLoader {
-  (code: number): Await<MultihashHasher>
+  (code: number, options?: AbortOptions): MultihashHasher | Promise<MultihashHasher>
+}
+
+export type { CryptoLoader, Keychain } from '@ipshipyard/keychain'
+export type { Crypto, PrivateKey, PublicKey } from '@ipshipyard/crypto'
+export { isPrivateKey, isPublicKey } from '@ipshipyard/crypto'
+
+export interface NodeInfo {
+  name: string
+  version: string
+}
+
+export interface HeliaMixin<Start extends Helia = Helia, Stop = Start> {
+  name: string
+  start?(helia: Start): Promise<void> | void
+  stop?(helia: Stop): Promise<void> | void
 }
 
 /**
  * The API presented by a Helia node
  */
-export interface Helia<T extends Libp2p = Libp2p> {
+export interface Helia {
   /**
-   * The libp2p instance
+   * Runtime information about the node
    */
-  libp2p: T
+  info: NodeInfo
 
   /**
    * Where the blocks are stored
@@ -57,7 +73,12 @@ export interface Helia<T extends Libp2p = Libp2p> {
   /**
    * Event emitter for Helia start and stop events
    */
-  events: TypedEventEmitter<HeliaEvents<T>>
+  events: TypedEventEmitter<HeliaEvents<this>>
+
+  /**
+   * Secure storage for private keys
+   */
+  keychain: Keychain
 
   /**
    * Pinning operations for blocks in the blockstore
@@ -87,15 +108,20 @@ export interface Helia<T extends Libp2p = Libp2p> {
    */
   metrics?: Metrics
 
+  /**
+   * The current status of the Helia node
+   */
+  status: 'starting' | 'started' | 'stopping' | 'stopped'
+
   /**
    * Starts the Helia node
    */
-  start(): Promise<void>
+  start(options?: AbortOptions): Promise<this>
 
   /**
    * Stops the Helia node
    */
-  stop(): Promise<void>
+  stop(options?: AbortOptions): Promise<this>
 
   /**
    * Remove any unpinned blocks from the blockstore
@@ -114,6 +140,36 @@ export interface Helia<T extends Libp2p = Libp2p> {
    * the hasher is being fetched from the network.
    */
   getHasher: HasherLoader
+
+  /**
+   * Cryptography implementations securely sign and verify data
+   */
+  getCrypto: CryptoLoader
+
+  /**
+   * Returns `true` if a router with the passed name has been configured
+   */
+  hasRouter (name: string): boolean
+
+  /**
+   * Add a router
+   */
+  addRouter(router: Router): void
+
+  /**
+   * Returns `true` if a block broker with the passed name has been configured
+   */
+  hasBlockBroker (name: string): boolean
+
+  /**
+   * Add a block broker
+   */
+  addBlockBroker(blockBroker: BlockBroker): void
+
+  /**
+   * Add a mixin to extend runtime functionality
+   */
+  addMixin<T extends Helia = Helia & Record<string, any>>(mixin: HeliaMixin<T>): void
 }
 
 export type GcEvents =
@@ -124,7 +180,7 @@ export interface GCOptions extends AbortOptions, ProgressOptions<GcEvents> {
 
 }
 
-export interface HeliaEvents<T extends Libp2p = Libp2p> {
+export interface HeliaEvents<H extends Helia = Helia> {
   /**
    * This event notifies listeners that the node has started
    *
@@ -134,7 +190,7 @@ export interface HeliaEvents<T extends Libp2p = Libp2p> {
    * })
    * ```
    */
-  start: CustomEvent<Helia<T>>
+  start: CustomEvent<H>
 
   /**
    * This event notifies listeners that the node has stopped
@@ -145,10 +201,11 @@ export interface HeliaEvents<T extends Libp2p = Libp2p> {
    * })
    * ```
    */
-  stop: CustomEvent<Helia<T>>
+  stop: CustomEvent<H>
 }
 
 export * from './blocks.ts'
 export * from './errors.ts'
+export * from './graph-walker.ts'
 export * from './pins.ts'
 export * from './routing.ts'

package/src/pins.ts

@@ -1,5 +1,6 @@
 import type { GetBlockProgressEvents } from './blocks.ts'
-import type { AbortOptions } from '@libp2p/interface'
+import type { GraphWalkerFactory } from './graph-walker.ts'
+import type { AbortOptions } from 'abort-error'
 import type { CID } from 'multiformats/cid'
 import type { ProgressEvent, ProgressOptions } from 'progress-events'
 
@@ -20,6 +21,11 @@ export interface AddOptions extends AbortOptions, ProgressOptions<AddPinEvents |
    */
   depth?: number
 
+  /**
+   * Walker factory used to traverse the DAG. Default: `depthFirstWalker()`.
+   */
+  walker?: GraphWalkerFactory
+
   /**
    * Optional user-defined metadata to store with the pin
    */
@@ -27,7 +33,10 @@ export interface AddOptions extends AbortOptions, ProgressOptions<AddPinEvents |
 }
 
 export interface RmOptions extends AbortOptions {
-
+  /**
+   * Walker factory used to traverse the DAG. Default: `depthFirstWalker()`.
+   */
+  walker?: GraphWalkerFactory
 }
 
 export interface LsOptions extends AbortOptions {

package/src/routing.ts

@@ -1,4 +1,5 @@
-import type { AbortOptions, PeerId, PeerInfo, TraceOptions } from '@libp2p/interface'
+import type { Multiaddr } from '@multiformats/multiaddr'
+import type { AbortOptions } from 'abort-error'
 import type { CID } from 'multiformats/cid'
 import type { ProgressEvent, ProgressOptions } from 'progress-events'
 
@@ -8,7 +9,7 @@ import type { ProgressEvent, ProgressOptions } from 'progress-events'
  * local cache that may be used in preference over network calls, for example
  * when a record has a TTL.
  */
-export interface RoutingOptions<Event extends ProgressEvent = any> extends AbortOptions, ProgressOptions<Event>, TraceOptions {
+export interface RoutingOptions<Event extends ProgressEvent = any> extends AbortOptions, ProgressOptions<Event> {
   /**
    * Pass `false` to not use the network
    *
@@ -29,12 +30,42 @@ export interface RoutingOptions<Event extends ProgressEvent = any> extends Abort
    * @default true
    */
   validate?: boolean
+
+  /**
+   * Where tracing is used, this value carries tracing context
+   */
+  trace?: any
+}
+
+/**
+ * A Peer is another node on the network
+ */
+export interface Peer {
+  /**
+   * The identifier of the remote peer
+   */
+  id: CID
+
+  /**
+   * The multiaddrs a peer is listening on
+   */
+  multiaddrs: Multiaddr[]
 }
 
 /**
  * A provider can supply the content for a CID
  */
-export interface Provider extends PeerInfo {
+export interface Provider {
+  /**
+   * The identifier of the remote peer, a CID
+   */
+  id: CID
+
+  /**
+   * The multiaddrs a peer is listening on
+   */
+  multiaddrs: Multiaddr[]
+
   /**
    * If present these are the methods that the peer can supply the content via.
    *
@@ -69,7 +100,7 @@ export interface RoutingFindProvidersEndEvent {
 export interface RoutingFindProvidersHttpGatewayProvider {
   routing: 'http-gateway-router'
   cid: CID
-  provider: PeerInfo & {
+  provider: Peer & {
     protocols: ['transport-ipfs-gateway-http']
   }
 }
@@ -77,7 +108,7 @@ export interface RoutingFindProvidersHttpGatewayProvider {
 export interface RoutingFindProvidersDelegatedHttpRoutingProvider {
   routing: 'delegated-http-router'
   cid: CID
-  provider: PeerInfo & {
+  provider: Peer & {
     routing: 'delegated-http-routing'
     protocols: string[]
   }
@@ -86,7 +117,7 @@ export interface RoutingFindProvidersDelegatedHttpRoutingProvider {
 export interface RoutingFindProvidersLibp2pProvider {
   routing: 'libp2p-router'
   cid: CID
-  provider: PeerInfo
+  provider: Peer
 }
 
 export type RoutingFindProvidersProviderEvent = RoutingFindProvidersHttpGatewayProvider | RoutingFindProvidersDelegatedHttpRoutingProvider | RoutingFindProvidersLibp2pProvider
@@ -157,12 +188,12 @@ export type RoutingGetProgressEvents =
 
 export interface RoutingFindPeerStartEvent {
   routing: string
-  peerId: PeerId
+  peerId: CID
 }
 
 export interface RoutingFindPeerEndEvent {
   routing: string
-  peerId: PeerId
+  peerId: CID
 }
 
 export type RoutingFindPeerProgressEvents =
@@ -183,7 +214,7 @@ export type RoutingGetClosestPeersProgressEvents =
   ProgressEvent<'helia:routing:get-closest-peers:start', RoutingGetClosestPeersStartEvent> |
   ProgressEvent<'helia:routing:get-closest-peers:end', RoutingGetClosestPeersEndEvent>
 
-export interface Routing {
+export interface Router {
   /**
    * The name of this routing implementation
    */
@@ -197,10 +228,12 @@ export interface Routing {
    *
    * ```js
    * // ...
-   * await contentRouting.provide(cid)
+   * await contentRouting.provide(cid, {
+   *   signal: AbortSignal.timeout(5_000)
+   * })
    * ```
    */
-  provide(cid: CID, options?: RoutingOptions<RoutingProvideProgressEvents>): Promise<void>
+  provide?(cid: CID, options?: RoutingOptions<RoutingProvideProgressEvents>): Promise<void>
 
   /**
    * Helia will periodically re-provide every previously provided CID. Use this
@@ -210,10 +243,12 @@ export interface Routing {
    *
    * ```js
    * // ...
-   * await contentRouting.cancelReprovide(cid)
+   * await contentRouting.cancelReprovide(cid, {
+   *   signal: AbortSignal.timeout(5_000)
+   * })
    * ```
    */
-  cancelReprovide(key: CID, options?: AbortOptions): Promise<void>
+  cancelReprovide?(key: CID, options?: AbortOptions): Promise<void>
 
   /**
    * Find the providers of the passed CID.
@@ -222,12 +257,14 @@ export interface Routing {
    *
    * ```js
    * // Iterate over the providers found for the given cid
-   * for await (const provider of contentRouting.findProviders(cid)) {
+   * for await (const provider of contentRouting.findProviders(cid, {
+   *   signal: AbortSignal.timeout(5_000)
+   * })) {
    *  console.log(provider.id, provider.multiaddrs)
    * }
    * ```
    */
-  findProviders(cid: CID, options?: RoutingOptions<RoutingFindProvidersProgressEvents>): AsyncIterable<Provider>
+  findProviders?(cid: CID, options?: RoutingOptions<RoutingFindProvidersProgressEvents>): AsyncIterable<Provider>
 
   /**
    * Puts a value corresponding to the passed key in a way that can later be
@@ -237,13 +274,15 @@ export interface Routing {
    *
    * ```js
    * // ...
-   * const key = '/key'
+   * const key = uint8ArrayFromString('/key')
    * const value = uint8ArrayFromString('oh hello there')
    *
-   * await contentRouting.put(key, value)
+   * await contentRouting.put(key, value, {
+   *   signal: AbortSignal.timeout(5_000)
+   * })
    * ```
    */
-  put(key: Uint8Array, value: Uint8Array, options?: RoutingOptions<RoutingPutProgressEvents>): Promise<void>
+  put?(key: Uint8Array, value: Uint8Array, options?: RoutingOptions<RoutingPutProgressEvents>): Promise<void>
 
   /**
    * Retrieves a value from the network corresponding to the passed key.
@@ -253,11 +292,13 @@ export interface Routing {
    * ```js
    * // ...
    *
-   * const key = '/key'
-   * const value = await contentRouting.get(key)
+   * const key = uint8ArrayFromString('/key')
+   * const value = await contentRouting.get(key, {
+   *   signal: AbortSignal.timeout(5_000)
+   * })
    * ```
    */
-  get(key: Uint8Array, options?: RoutingOptions<RoutingGetProgressEvents>): Promise<Uint8Array>
+  get?(key: Uint8Array, options?: RoutingOptions<RoutingGetProgressEvents>): Promise<Uint8Array>
 
   /**
    * Searches the network for peer info corresponding to the passed peer id.
@@ -266,10 +307,12 @@ export interface Routing {
    *
    * ```js
    * // ...
-   * const peer = await peerRouting.findPeer(peerId, options)
+   * const peer = await peerRouting.findPeer(peerId, {
+   *   signal: AbortSignal.timeout(5_000)
+   * })
    * ```
    */
-  findPeer(peerId: PeerId, options?: RoutingOptions<RoutingFindPeerProgressEvents>): Promise<PeerInfo>
+  findPeer?(peer: CID, options?: RoutingOptions<RoutingFindPeerProgressEvents>): Promise<Peer>
 
   /**
    * Search the network for peers that are closer to the passed key. Peer
@@ -279,10 +322,14 @@ export interface Routing {
    *
    * ```js
    * // Iterate over the closest peers found for the given key
-   * for await (const peer of peerRouting.getClosestPeers(key)) {
+   * for await (const peer of peerRouting.getClosestPeers(key, {
+   *   signal: AbortSignal.timeout(5_000)
+   * })) {
    *   console.log(peer.id, peer.multiaddrs)
    * }
    * ```
    */
-  getClosestPeers(key: Uint8Array, options?: RoutingOptions<RoutingGetClosestPeersProgressEvents>): AsyncIterable<PeerInfo>
+  getClosestPeers?(key: Uint8Array, options?: RoutingOptions<RoutingGetClosestPeersProgressEvents>): AsyncIterable<Peer>
 }
+
+export type Routing = Required<Omit<Router, 'name'>>