Libp2p Switch

libp2p-switch.md

Libp2p Switch

Assumptions:

• Multistream1.0 is still used.

1. Overview
   1. Creation
2. Dialing
   1. Establishing Connection
   2. Privatize Connection
   3. Setup Multistream
   4. Encrypt Connection
   5. Add Stream Muxer
   6. Application Protocol
3. Listening

Overview

1. Create a switch with orderer lists of: Crypto and Muxers.
2. Use .handle exclusively for application protocols. /dht/, /pubsub/, /ipfs/, etc.?
   • All protocols, including crypto and muxers, must be registered with multistream

Dialing

Pseudo Code

connection = getConnection(peer)
connection = privatize(connection)
connection = addMultistream(connection)
theirSupportedProtocols = connection.ls()
connection = encrypt(connection, theirSupportedProtocols, ourCryptoProtocols)
connection = addStreamMuxers(connection, theirSupportedProtocols, ourStreaMuxerProtocols)
if (applicationProtocol) stream = createStream(connection, applicationProtocol, theirSupportedProtocols)

Establishing Connection

Get Basic Connection

Privatize Connection

If configured, must immediately attempt to privatize the new connection

Setup Multistream

Note: js-libp2p-switch currently does not perform an ls. It will add it in a future update, but may need to be changed to support an ls at this stage of the dial.

1. Immediately register the connection with a Multistream.Dialer instance
2. Perform a multistreamDialer.ls on the connection to determine supported protocols of peer

Considerations

If an [#application-protocol](Application Protocol) is provided for the dial, and that protocol is not present in multistreamDialer.ls, it may warrant closing the connection immediately. If a dial is performed with no protocol, this may likely be a proactive connect for a multipurpose connection. If the protocol is provided, it may likely be for a specific purpose and the lack of support for that protocol may warrant immediate closure of the connection.

Encrypt Connection

1. Select the best available encryption protocol
2. Perform a multistreamDialer.select for that protocol
3. On failure, try any other available protocols
4. If all protocols fail, end the connection immediately
   • Future iterations may wish to perform some type of backoff blacklisting for the peer
5. If successful, continue on.

Add Stream Muxer

1. Given the available protocols from Setup Multistream, select the best stream muxer
2. Perform a multistreamDialer.select for that muxer
3. On failure, try any other available stream muxer protocols
4. If all stream muxer protocols fail, end the connection immediately
5. If all protocols fail, degrade to an unmuxed connection.
   • Multiple streams cannot be opened on this connection.
6. If successful, continue on.

Application Protocol

An application protocol is a custom protocol used to register handlers in a given codebase that will be executed when a connection receives a stream prepended with that protocol. Considered another way, this can be considered Endpoints within an application. For example, if a dial is performed with the protocol /ipfs/kad/1.0.0,

1. If no application protocol is known, take no action
2. If an application protocol is known:
   1. Check the protocol list for the peer to determine if the protocol is supported.
   2. If not supported, error the request. The connection should not be closed, as other protocol requests may still be supported.
   3. If supported, perform a multistreamDialer.select for that protocol.
3. If a new stream is created via multistreamDialer.select, return the stream, otherwise error.