6 Interfaces

6.1 libp2p

6.2 Peer Routing

6.3 Swarm

~~The network is abstracted through the swarm which presents a simplified interface for the remaining layers to have access to the network. This interface should look like:~~

sw.addTransport(transport, [options, dialOptions, listenOptions]) - Add a transport to be supported by this swarm instance. Swarm expects it to implement the abstract-transport interface.
sw.addUpgrade(connUpgrade, [options]) - A connection upgrade must be able to receive and return something that implements the abstract-connection interface.
sw.addStreamMuxer(streamMuxer, [options]) - Upgrading a connection to use a stream muxer is still considered an upgrade, but a special case since once this connection is applied, the returned obj will implement the abstract-stream-muxer interface.
sw.dial(PeerInfo, options, protocol, callback) - PeerInfo should contain the ID of the peer and its respective multiaddrs known.
sw.handleProtocol(protocol, handlerFunction) - enable a protocol to be registered, so that another peer can open a stream to talk with us to that specific protocol

The following figure represents how the network level pieces, are tied together:

┌ ─ ─ ─ ─ ┌ ─ ─ ─ ─ ┌ ─ ─ ─ ─ ┌───────────┐
 mounted │ mounted │ mounted ││Identify   │
│protocol │protocol │protocol │(mounted   │
 1       │ 2       │ ...     ││ protocol) │
└ ─ ─ ─ ─ └ ─ ─ ─ ─ └ ─ ─ ─ ─ └───────────┘
┌─────────────────────────────────────────┐
│             swarm                       │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│            connection                   │
└─────────────────────────────────────────┘
┌───────────────┐┌───────────┐┌───────────┐
│Transport      ││multistream││ stream    │
│(TCP, UDP, etc)││           ││ muxer     │
└───────────────┘└───────────┘│┌ ─ ─ ─ ─ ┐│
                              │  spdy     │
                              │└ ─ ─ ─ ─ ┘│
                              │┌ ─ ─ ─ ─ ┐│
                              │ multiplex │
                              │└ ─ ─ ─ ─ ┘│
                              │┌ ─ ─ ─ ─ ┐│
                              │ QUIC      │
                              │└ ─ ─ ─ ─ ┘│
                              │┌ ─ ─ ─ ─ ┐│
                              │ others    │
                              │└ ─ ─ ─ ─ ┘│
                              └───────────┘

6.4 Distributed Record Store

OLD The network protocol's interface has two parts:A

the client interface, for clients (e.g. higher layers of IPFS)
the service interface, for remote peers (e.g. other IPFS nodes)

4.1 Client Interface

The Client Interface is exposed to the higher layers of IPFS. It is the entry point for other parts to open + handle streams.

This type system represents the interface exposed to clients. Actual implementations will likely be more complicated, but they should aim to cover this.

type PrivateKey interface {
  PublicKey() PublicKey

  Sign(data []byte) Signature
  Decrypt(ciphertext []byte) (plaintext []byte)
}

type PublicKey interface {
  PeerID() PeerID

  Verify(Signature) (ok bool)
  Encrypt(plaintext []byte) (ciphertext []byte)
}

// PeerID is a hash of a PublicKey, encoded in multihash
// It represents the identity of a node.
type PeerID Multihash

// Node is a peer in the network. It is both a client and server.
// Users may open streams to remote peers, or set handlers for protocols.
type Node interface {
  // ID returns the PeerID of this Node
  ID() PeerID

  // NewStream creates a new stream to given peerID.
  // It may have to establish a new connection to given peer.
  // (This includes finding the addresses of a peer, and NAT Traversal.)
  NewStream(Protocol, PeerID) (Stream, error)

  // SetStreamHandler sets a callback for remote-opened streams for a protocol
  // Thus clients register "protocol handlers", much like URL route handlers
  SetStreamHandler(Protocol, StreamHandler)

  // Raw connections are not exported to the user, only streams.
}

type StreamHandler func (Stream)

TODO: incorporate unreliable message / packet streams.

4.2 Protocol Interface

The network protocol consists of:

Any secure, reliable, stream transport:
- a reliable transport protocol (TCP, QUIC, SCTP, UDT, UTP, ...)
- a secure PKI based transport protocol (SSH, TLS, ...)
- a stream transport (with flow control, etc) (HTTP2, SSH, QUIC)
Protocol stream framing, to multiplex services
Auxiliary protocols for connectivity:
- Identify - exchange node information
- NAT - NAT Traversal (ICE)
- Relay - for when NAT Traversal fails

Both the transport and stream muxer are pluggable. Unless constraints dictate otherwise, implementations SHOULD implement TCP and HTTP/2 for interoperability. These are the default

any reliable transport protocol
a secure channel encryption
a stream multiplexor with flow control (e.g. HTTP/2, SPDY, QUIC, SSH)
every stream protocol header

(TODO: unreliable transport)

5.9 KiB Raw Blame History