libp2p events

[achingbrain]

The libp2p object returned from createLibp2p is an EventTarget that emits a few different events.

These events are really useful for observing the inner workings of libp2p without having to tie your code to the internal structure of libp2p.

They also open the door to real-time monitoring of libp2p with better observability and debugging possibilities.

The event list should be expanded to encompass more events. Some (non-exhausive) suggestions:

• peer:dial - when we dial a peer, the event should hold the peer id and which multiaddrs are being dialled
• peer:dial:success - the event should hold the peer id and the multiaddr that succeeded
• peer:dial:error - the event should hold the peer id and the multiaddr that failed and an Error object
• identify:success - the identify protocol competed for a peer - the event should hold the peer id
• identify:error - the identify protocol failed for a peer - the event should hold the peer id and an Error object
• identify:push:success - the identify push protocol competed for a peer - the event should hold the peer id
• identify:push:error - the identify push protocol failed for a peer - the event should hold the peer id and an Error object
• connection:prune - we pruned a connection, the event should have the peer id of the connection that was closed
• connection:upgrade - a connection was upgraded, the event should have the connection that was upgraded
• ...other things?

It would be good to establish a naming convention for events, the above hasn't had a whole lot of thought applied to it.

[maschad]

Great idea @achingbrain this would be very helpful, I would also add the following to this list:

• peer:dial:pending when a dial is pending, the event the event should hold the peer id and which multiaddrs are being dialled
• connection:${status} when a peer's status has changed, the event should have the peer id and the multiaddr and the status.

@wemeetagain can you think of other events that might be useful?

[achingbrain]

We may not need a peer:dial:pending event - it is pending after the peer:dial event and before the peer:dial:success/peer:dial:error events.

[wemeetagain]

More events would definitely be nice. Would be nice for the success events to include as much relevant data as possible. Eg: have identify:success also emit the Identify object.

As far as being a substitute to access to the underlying implementation, I disagree that it works for all cases.

For example, Lodestar currently inspects the dialer to avoid redialing peers with pending dials. This ensures we dial enough peers with the right properties and don't underdial.

We could track the libp2p dial/dial:success/dial:error events and build our own map of pending dials.
Or we could just use the existing map in the dialer and not do the extra work, maintain the extra code, etc.

For us, the tradeoffs pretty clearly point to us doing something like this:

function isPending(libp2p: Libp2p, peerIdStr: string): boolean {
  return (libp2p as unknown as {dialer: DefaultDialer}).dialer.pendingDials.has(peerIdStr);
}

rather than something like this:

class PendingDialTracker {
  public pendingDials = new Set<string>()
  libp2p: Libp2p
  constructor(libp2p: Libp2p) {
    this.libp2p = libp2p
    this.libp2p.addEventListener('peer:dial', this.onPeerDial)
    this.libp2p.addEventListener('peer:dial:success', this.onPeerDialFinish)
    this.libp2p.addEventListener('peer:dial:error', this.onPeerDialFinish)
  }
  close() {
    this.libp2p.removeEventListener('peer:dial', this.onPeerDial)
    this.libp2p.removeEventListener('peer:dial:success', this.onPeerDialFinish)
    this.libp2p.removeEventListener('peer:dial:error', this.onPeerDialFinish)
  }
  onPeerDial = (peerId: PeerId) => {
    this.pendingDials.add(peerId.toString())
  }
  onPeerDialFinish = (peerId: PeerId) => {
    this.pendingDials.delete(peerId.toString())
  }
}

[maschad]

As discussed with @achingbrain we could structure these events as Progress Events which would allow us to create union types that represent a variety of custom events that are emitted from a particular Libp2p process at various stages in it's progress.

We can begin working on this once ipfs/helia-ipns#1 is merged and we see how performant this is.