mirror of
https://github.com/vacp2p/specs.git
synced 2026-01-08 23:08:09 -05:00
140 lines
5.9 KiB
Markdown
140 lines
5.9 KiB
Markdown
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](https://github.com/diasdavid/abstract-transport) interface.
|
|
- `sw.addUpgrade(connUpgrade, [options])` - A connection upgrade must be able to receive and return something that implements the [abstract-connection](https://github.com/diasdavid/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
|
|
|
|
1. the _client interface_, for clients (e.g. higher layers of IPFS)
|
|
2. 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.
|
|
|
|
```go
|
|
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)
|
|
|
|
|