libp2p - [WIP] Update the Interfaces chapter

libp2p/6-interfaces.md

@@ -1,139 +1,48 @@
 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
-
-
+`libp2p` is a conglomerate of several protocols working together to offer a common solid interface with talking with any other network addressable process. This is made possible by shimming current exist protocols and implementations through a set of explicit interfaces, from Peer Routing, Discovery, Stream Muxing, Transports, Connections and so on.
 
+## 6.1 libp2p
 
+libp2p, the top module that interfaces all the other modules that make a libp2p instance, must offer an interface for dialing to a peer and plugging in all of the modules (e.g. which transports) we want to support.
 
 
 
+## 6.2 Peer Routing
 
-----------------------------
-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
+![](https://raw.githubusercontent.com/diasdavid/abstract-peer-routing/master/img/badge.png)
 
-  Sign(data []byte) Signature
-  Decrypt(ciphertext []byte) (plaintext []byte)
-}
+A Peer Routing service offers a way for libp2p Node to find the PeerInfo of another Node, so that it can dial to that node. In it is most pure form, a Peer Routing module should have a interface that given a 'key', a set of PeerInfos are returned.
+See https://github.com/diasdavid/abstract-peer-routing for the interface and tests.
 
-type PublicKey interface {
-  PeerID() PeerID
+## 6.3 Swarm
 
-  Verify(Signature) (ok bool)
-  Encrypt(plaintext []byte) (ciphertext []byte)
-}
+Current interface available and updated at:
 
-// PeerID is a hash of a PublicKey, encoded in multihash
-// It represents the identity of a node.
-type PeerID Multihash
+https://github.com/diasdavid/js-libp2p-swarm#usage
 
-// 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
+### 6.3.1 Transport
 
-  // 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)
+![](https://raw.githubusercontent.com/diasdavid/abstract-transport/master/img/badge.png)
 
-  // SetStreamHandler sets a callback for remote-opened streams for a protocol
-  // Thus clients register "protocol handlers", much like URL route handlers
-  SetStreamHandler(Protocol, StreamHandler)
+https://github.com/diasdavid/abstract-transport
 
-  // Raw connections are not exported to the user, only streams.
-}
+### 6.3.2 Connection
 
-type StreamHandler func (Stream)
-```
+![](https://raw.githubusercontent.com/diasdavid/abstract-connection/master/img/badge.png)
 
-TODO: incorporate unreliable message / packet streams.
+https://github.com/diasdavid/abstract-connection
 
-### 4.2 Protocol Interface
+### 6.3.3 Stream Muxing
 
-The network protocol consists of:
+![](https://github.com/diasdavid/abstract-stream-muxer/raw/master/img/badge.png)
 
-- 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
+https://github.com/diasdavid/abstract-stream-muxer
 
-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
+## 6.4 Distributed Record Store
 
-- 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)
+## 6.5 Peer Discovery