chore: add socket concept

Author: vasco-santos

README.md

@@ -35,9 +35,50 @@ Include this badge in your readme if you make a module that is compatible with t
 
 ![](https://raw.githubusercontent.com/diasdavid/interface-connection/master/img/badge.png)
 
-# How to use the battery of tests
+# Usage
 
-## JS
+## Connection
+
+Before creating a connection from a transport compatible with `libp2p` it is important to understand some concepts:
+
+- **socket**: the underlying raw duplex connection between two nodes. It is created by the transports during a dial/listen.
+- **connection**: the abstract libp2p duplex connection between two nodes. The transport must pipe the `socket` through the connection.
+- **stream**: a single duplex channel of the `connection`. Each connection may have many streams.
+
+A connection stands for the libp2p communication duplex layer between two nodes. It is **not** the underlying raw transport duplex layer (socket), such as a TCP socket, but an abstracted duplex layer that sits on top of the raw socket.
+
+When a libp2p transport creates its socket, a new `connection` instance should be created and the transport should **pipe** both input and output of the socket through this `connection`, i.e. `pipe(socket, connection, socket)`.
+
+The transport must handle the translation of cleanup from the socket to the connection. That is, the errors, resets or closes on the socket **must** be passed to the connection. In the same way, the transport **must** map these actions from the `connection` to the socket. This helps ensuring that the transport is responsible for socket management, while also allowing the application layer to handle the connection management.
+
+```js
+const pipe = require('it-pipe')
+const { Connection } = require('interface-connection')
+
+class Transport {
+  async dial () {
+    // ...
+
+    // create the raw socket and the connection
+    const socket = await this._connect()
+    const conn = new Connection(remotePeerInfo, remoteMa)
+
+    // pipe the socket through the connection (if necessary include a conversion to iterable duplex streams)
+    pipe(socket, conn, socket)
+
+    // bind the necessary handlers to update state changes (error, close, reset, ...)
+    // ...
+
+    return conn
+  }
+
+  _connect () {}
+}
+```
+
+## Test suite
+
+### JS
 
 ```js
 describe('your connection', () => {
@@ -52,7 +93,7 @@ describe('your connection', () => {
 })
 ```
 
-## Go
+### Go
 
 > WIP
 
@@ -147,7 +188,7 @@ This property contains the remote peer info of this connection.
 
 - `JavaScript` - `conn.status`
 
-This property contains the status of the connection. It can be either `OPEN`, `CLOSED` or `CLOSING`. Once the creating is created it is in an `OPEN` status. When a `conn.close()` happens, the status will change to `CLOSING` and finally, after all the connection streams are properly closed, the status will be `CLOSED`.
+This property contains the status of the connection. It can be either `OPEN`, `CLOSED` or `CLOSING`. Once the connection is created it is in an `OPEN` status. When a `conn.close()` happens, the status will change to `CLOSING` and finally, after all the connection streams are properly closed, the status will be `CLOSED`.
 
 ### Endpoints multiaddr
 

src/connection.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { Duplex } = require('stream')
+
 const PeerInfo = require('peer-info')
 const multiaddr = require('multiaddr')
 const multistream = require('multistream-select')
@@ -16,15 +18,19 @@ const defaultMaxNumberOfAttemptsForHasMultiplexer = 5
 
 /**
  * An implementation of the js-libp2p connection.
+ * This is an abstract duplex connection between two nodes and
+ * each transport must pipe its socket through this.
  */
-class Connection {
+class Connection extends Duplex {
   /**
    * Creates an instance of Connection.
    * @param {PeerInfo} peerInfo remote peer PeerInfo
    * @param {multiaddr} remoteMa remote peer multiaddr
    * @param {boolean} [isInitiator=true] peer initiated the connection
    */
   constructor (peerInfo, remoteMa, isInitiator = true) {
+    super()
+
     assert(PeerInfo.isPeerInfo(peerInfo), 'peerInfo must be an instance of PeerInfo')
     assert(multiaddr.isMultiaddr(remoteMa), 'remoteMa must be an instance of multiaddr')
     assert(typeof isInitiator === 'boolean', 'isInitiator must be a boolean')
@@ -190,16 +196,26 @@ class Connection {
       return
     }
 
-    if (this.status !== STATUS.CLOSING) {
-      this.status = STATUS.CLOSING
-      this.timeline.close = Date.now()
+    if (this._closing) {
+      return this._closing
     }
 
+    this.status = STATUS.CLOSING
+
     // Close all streams
-    await Promise.all(this._streams.map((stream) => stream.close()))
+    this._closing = await this._closeStreams()
 
+    this.timeline.close = Date.now()
     this.status = STATUS.CLOSED
   }
+
+  /**
+   * Close all the streams associated with this connection.
+   * @return {Promise}
+   */
+  _closeStreams () {
+    return Promise.all(this._streams.map((stream) => stream.close()))
+  }
 }
 
 module.exports = withIs(Connection, { className: 'Connection', symbolName: '@libp2p/interface-connection/connection' })