How do approaches to registering custom protocols compare (handle/dial vs

[2color]

I came across two ways of implementing custom protocols in js-libp2p and I'm curious how they compare and when would you chose one over the other.

dialProtocol and handle

peer1.handle(protocolId, ({ stream }) =>  {
    pipe(stream, stream)
})

const pstream = await peer2.dialProtocol(maddr, protocolId, {
    signal,
  })

Creating a topology with the registrar

Using the registrar, you can also register custom protocols, essentially creating a topology, for example:

https://github.com/libp2p/js-libp2p/blob/main/doc/SERVICES.md?plain=1#L302-L315

[achingbrain]

These all do slightly different things:

node.handle

This registers a handler for incoming protocol streams.

It causes the protocol name to be added to the list of protocols supported by the current node.

The list of supported protocols is exchanged with peers via Identify and Identify/Push, if configured.

node.dialProtocol

This is for initiating a protocol stream over a connection to a remote peer.

The remote peer has to have called node.handle already.

You can also call node.dial to get a Connection, then call conn.newStream with the protocol name(s) to accomplish the same thing.

The dialing node does not need to have called node.handle with the protocol name, this is only required to accept incoming streams, not to create outgoing ones.

node.register

This registers a (passive) topology listener rather than a(n active) protocol handler.

The topology is notified after Identify has run on any newly opened connection, or updated data arrives via Identify/Push on an existing connection.

It does not cause the protocol name to be added to the list of protocols supported by the current node, so if a remote node attempts to open a protocol stream on the current node for the protocol that the topology is registered for, but no handler has been set (via node.handle), the attempt to open the stream will fail.

The onConnect topology callback is invoked when a remote peer that supports that protocol connects, not when a protocol stream is opened on that connection.

Hopefully this makes the distinction clearer?

[2color]

That makes sense. Are there any good examples of a topology being used by any of the core js-libp2p modules?

[achingbrain]

Sure, circuit relay uses a toplogy to discover relays, KAD-DHT uses one to add peers to buckets, and also gossipsub uses one to discover other protocol peers.

[achingbrain]

Closing as I think this has been answered.