feat: emit standardized routing events (#981)

Emit events with routing information for find providers operation.

Author: achingbrain

packages/bitswap/src/network.ts

@@ -15,7 +15,7 @@ import type { WantOptions } from './bitswap.ts'
 import type { MultihashHasherLoader } from './index.ts'
 import type { Block } from './pb/message.ts'
 import type { QueuedBitswapMessage } from './utils/bitswap-message.ts'
-import type { Provider, Routing } from '@helia/interface/routing'
+import type { Provider, Routing, RoutingFindProvidersProgressEvents } from '@helia/interface/routing'
 import type { Libp2p, AbortOptions, Connection, PeerId, Topology, ComponentLogger, IdentifyResult, Counter, Metrics, Stream } from '@libp2p/interface'
 import type { Logger } from '@libp2p/logger'
 import type { PeerQueueJobOptions } from '@libp2p/utils'
@@ -54,7 +54,8 @@ export type BitswapNetworkWantProgressEvents =
   ProgressEvent<'bitswap:send-wantlist:error', { peer: PeerId, error: Error }> |
   ProgressEvent<'bitswap:find-providers', CID> |
   ProgressEvent<'bitswap:found-provider', BitswapProvider> |
-  BitswapNetworkProgressEvents
+  BitswapNetworkProgressEvents |
+  RoutingFindProvidersProgressEvents
 
 export type BitswapNetworkNotifyProgressEvents =
   BitswapNetworkProgressEvents |

packages/block-brokers/src/trustless-gateway/index.ts

@@ -1,6 +1,6 @@
 import { TrustlessGatewayBlockBroker } from './broker.ts'
 import type { TransformRequestInit } from './trustless-gateway.ts'
-import type { Routing, BlockBroker } from '@helia/interface'
+import type { Routing, BlockBroker, RoutingFindProvidersProgressEvents } from '@helia/interface'
 import type { ComponentLogger } from '@libp2p/interface'
 import type { CID } from 'multiformats'
 import type { ProgressEvent } from 'progress-events'
@@ -38,7 +38,8 @@ export interface TrustlessGatewayProvider {
 
 export type TrustlessGatewayGetBlockProgressEvents =
   ProgressEvent<'trustless-gateway:get-block:fetch', URL> |
-  ProgressEvent<'trustless-gateway:found-provider', TrustlessGatewayProvider>
+  ProgressEvent<'trustless-gateway:found-provider', TrustlessGatewayProvider> |
+  RoutingFindProvidersProgressEvents
 
 export interface TrustlessGatewayBlockBrokerInit {
   /**

packages/interface/src/blocks.ts

@@ -1,3 +1,4 @@
+import type { RoutingFindProvidersProgressEvents } from './routing.ts'
 import type { PeerId } from '@libp2p/interface'
 import type { Multiaddr } from '@multiformats/multiaddr'
 import type { Blockstore } from 'interface-blockstore'
@@ -37,7 +38,8 @@ export type PutManyBlocksProgressEvents =
 export type GetBlockProgressEvents =
   ProgressEvent<'blocks:get:providers:want', CID> |
   ProgressEvent<'blocks:get:blockstore:get', CID> |
-  ProgressEvent<'blocks:get:blockstore:put', CID>
+  ProgressEvent<'blocks:get:blockstore:put', CID> |
+  RoutingFindProvidersProgressEvents
 
 export type GetManyBlocksProgressEvents =
   ProgressEvent<'blocks:get-many:blockstore:get-many'> |

packages/interface/src/routing.ts

@@ -1,14 +1,14 @@
 import type { AbortOptions, PeerId, PeerInfo, TraceOptions } from '@libp2p/interface'
 import type { CID } from 'multiformats/cid'
-import type { ProgressOptions } from 'progress-events'
+import type { ProgressEvent, ProgressOptions } from 'progress-events'
 
 /**
  * When a routing operation involves reading values, these options allow
  * controlling where the values are read from. Some implementations support a
  * local cache that may be used in preference over network calls, for example
  * when a record has a TTL.
  */
-export interface RoutingOptions extends AbortOptions, ProgressOptions, TraceOptions {
+export interface RoutingOptions<Event extends ProgressEvent = any> extends AbortOptions, ProgressOptions<Event>, TraceOptions {
   /**
    * Pass `false` to not use the network
    *
@@ -55,7 +55,140 @@ export interface Provider extends PeerInfo {
   routing: string
 }
 
+export interface RoutingFindProvidersStartEvent {
+  routing: string
+  cid: CID
+}
+
+export interface RoutingFindProvidersEndEvent {
+  routing: string
+  cid: CID
+  found: number
+}
+
+export interface RoutingFindProvidersHttpGatewayProvider {
+  routing: 'http-gateway-router'
+  cid: CID
+  provider: PeerInfo & {
+    protocols: ['transport-ipfs-gateway-http']
+  }
+}
+
+export interface RoutingFindProvidersDelegatedHttpRoutingProvider {
+  routing: 'delegated-http-router'
+  cid: CID
+  provider: PeerInfo & {
+    routing: 'delegated-http-routing'
+    protocols: string[]
+  }
+}
+
+export interface RoutingFindProvidersLibp2pProvider {
+  routing: 'libp2p-router'
+  cid: CID
+  provider: PeerInfo
+}
+
+export type RoutingFindProvidersProviderEvent = RoutingFindProvidersHttpGatewayProvider | RoutingFindProvidersDelegatedHttpRoutingProvider | RoutingFindProvidersLibp2pProvider
+
+export type RoutingFindProvidersProgressEvents =
+  ProgressEvent<'helia:routing:find-providers:start', RoutingFindProvidersStartEvent> |
+  ProgressEvent<'helia:routing:find-providers:provider', RoutingFindProvidersProviderEvent> |
+  ProgressEvent<'helia:routing:find-providers:end', RoutingFindProvidersEndEvent> |
+  RoutingFindPeerProgressEvents
+
+export interface RoutingProvideStartEvent {
+  routing: string
+  cid: CID
+}
+
+export interface RoutingProvideEndEvent {
+  routing: string
+  cid: CID
+}
+
+export type RoutingProvideProgressEvents =
+  ProgressEvent<'helia:routing:provide:start', RoutingProvideStartEvent> |
+  ProgressEvent<'helia:routing:provide:end', RoutingProvideEndEvent>
+
+export interface RoutingCancelReprovideStartEvent {
+  routing: string
+  cid: CID
+}
+
+export interface RoutingCancelReprovideEndEvent {
+  routing: string
+  cid: CID
+}
+
+export type RoutingCancelReprovideProgressEvents =
+  ProgressEvent<'helia:routing:cancel-reprovide:start', RoutingCancelReprovideStartEvent> |
+  ProgressEvent<'helia:routing:cancel-reprovide:end', RoutingCancelReprovideEndEvent>
+
+export interface RoutingPutStartEvent {
+  routing: string
+  key: Uint8Array
+  value: Uint8Array
+}
+
+export interface RoutingPutEndEvent {
+  routing: string
+  key: Uint8Array
+  value: Uint8Array
+}
+
+export type RoutingPutProgressEvents =
+  ProgressEvent<'helia:routing:put:start', RoutingPutStartEvent> |
+  ProgressEvent<'helia:routing:put:end', RoutingPutEndEvent>
+
+export interface RoutingGetStartEvent {
+  routing: string
+  key: Uint8Array
+}
+
+export interface RoutingGetEndEvent {
+  routing: string
+  key: Uint8Array
+}
+
+export type RoutingGetProgressEvents =
+  ProgressEvent<'helia:routing:get:start', RoutingGetStartEvent> |
+  ProgressEvent<'helia:routing:get:end', RoutingGetEndEvent>
+
+export interface RoutingFindPeerStartEvent {
+  routing: string
+  peerId: PeerId
+}
+
+export interface RoutingFindPeerEndEvent {
+  routing: string
+  peerId: PeerId
+}
+
+export type RoutingFindPeerProgressEvents =
+  ProgressEvent<'helia:routing:find-peer:start', RoutingFindPeerStartEvent> |
+  ProgressEvent<'helia:routing:find-peer:end', RoutingFindPeerEndEvent>
+
+export interface RoutingGetClosestPeersStartEvent {
+  routing: string
+  key: Uint8Array
+}
+
+export interface RoutingGetClosestPeersEndEvent {
+  routing: string
+  key: Uint8Array
+}
+
+export type RoutingGetClosestPeersProgressEvents =
+  ProgressEvent<'helia:routing:get-closest-peers:start', RoutingGetClosestPeersStartEvent> |
+  ProgressEvent<'helia:routing:get-closest-peers:end', RoutingGetClosestPeersEndEvent>
+
 export interface Routing {
+  /**
+   * The name of this routing implementation
+   */
+  name: string
+
   /**
    * The implementation of this method should ensure that network peers know the
    * caller can provide content that corresponds to the passed CID.
@@ -67,7 +200,7 @@ export interface Routing {
    * await contentRouting.provide(cid)
    * ```
    */
-  provide(cid: CID, options?: RoutingOptions): Promise<void>
+  provide(cid: CID, options?: RoutingOptions<RoutingProvideProgressEvents>): Promise<void>
 
   /**
    * Helia will periodically re-provide every previously provided CID. Use this
@@ -94,7 +227,7 @@ export interface Routing {
    * }
    * ```
    */
-  findProviders(cid: CID, options?: RoutingOptions): 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
@@ -110,7 +243,7 @@ export interface Routing {
    * await contentRouting.put(key, value)
    * ```
    */
-  put(key: Uint8Array, value: Uint8Array, options?: RoutingOptions): Promise<void>
+  put(key: Uint8Array, value: Uint8Array, options?: RoutingOptions<RoutingPutProgressEvents>): Promise<void>
 
   /**
    * Retrieves a value from the network corresponding to the passed key.
@@ -124,7 +257,7 @@ export interface Routing {
    * const value = await contentRouting.get(key)
    * ```
    */
-  get(key: Uint8Array, options?: RoutingOptions): Promise<Uint8Array>
+  get(key: Uint8Array, options?: RoutingOptions<RoutingGetProgressEvents>): Promise<Uint8Array>
 
   /**
    * Searches the network for peer info corresponding to the passed peer id.
@@ -136,7 +269,7 @@ export interface Routing {
    * const peer = await peerRouting.findPeer(peerId, options)
    * ```
    */
-  findPeer(peerId: PeerId, options?: RoutingOptions): Promise<PeerInfo>
+  findPeer(peerId: PeerId, options?: RoutingOptions<RoutingFindPeerProgressEvents>): Promise<PeerInfo>
 
   /**
    * Search the network for peers that are closer to the passed key. Peer
@@ -151,5 +284,5 @@ export interface Routing {
    * }
    * ```
    */
-  getClosestPeers(key: Uint8Array, options?: RoutingOptions): AsyncIterable<PeerInfo>
+  getClosestPeers(key: Uint8Array, options?: RoutingOptions<RoutingGetClosestPeersProgressEvents>): AsyncIterable<PeerInfo>
 }

packages/interop/package.json

@@ -52,10 +52,10 @@
   },
   "dependencies": {
     "@helia/block-brokers": "^5.1.4",
-    "@helia/dnslink": "^1.1.4",
     "@helia/car": "^5.3.10",
     "@helia/dag-cbor": "^5.0.7",
     "@helia/dag-json": "^5.0.7",
+    "@helia/dnslink": "^1.1.4",
     "@helia/http": "^3.0.22",
     "@helia/interface": "^6.1.1",
     "@helia/ipns": "^9.1.9",

packages/mfs/test/touch.spec.ts

@@ -134,6 +134,7 @@ describe('touch', () => {
     await fs.cp(shardedDirCid, shardedDirPath)
 
     await delay(2000)
+
     await fs.touch(shardedDirPath, {
       recursive: true
     })

packages/routers/src/delegated-http-routing.ts

@@ -19,6 +19,7 @@ function isIPNSKey (key: Uint8Array): boolean {
 }
 
 class DelegatedHTTPRouter implements Routing {
+  public readonly name = 'delegated-http-router'
   private readonly client: DelegatedRoutingV1HttpApiClient
 
   constructor (components: DelegatedRoutingV1HttpApiClientComponents, init: DelegatedRoutingV1HttpApiClientInit) {

packages/routers/src/http-gateway-routing.ts

@@ -45,6 +45,7 @@ function toUrl (info: PeerInfo): URL {
 }
 
 class HTTPGatewayRouter implements Partial<Routing> {
+  public readonly name = 'http-gateway-router'
   private readonly gateways: PeerInfo[]
   private readonly shuffle: boolean
 

packages/routers/src/libp2p-routing.ts

@@ -3,6 +3,7 @@ import type { Libp2p, PeerId, PeerInfo } from '@libp2p/interface'
 import type { CID } from 'multiformats'
 
 class Libp2pRouter implements Routing {
+  public readonly name = 'libp2p-router'
   private readonly libp2p: Libp2p
 
   constructor (libp2p: Libp2p) {

packages/utils/src/abstract-session.ts

@@ -406,7 +406,7 @@ export abstract class AbstractSession<Provider, RetrieveBlockProgressEvents exte
   /**
    * This method should search for new providers and yield them.
    */
-  abstract findNewProviders (cid: CID, options: AbortOptions): AsyncGenerator<Provider>
+  abstract findNewProviders (cid: CID, options: BlockRetrievalOptions<RetrieveBlockProgressEvents>): AsyncGenerator<Provider>
 
   /**
    * The subclass should contact the provider and request the block from it.