Home

Awesome

⛔️ DEPRECATED: interface-connection is now included in libp2p-interfaces

interface-connection

Discourse posts Dependency Status js-standard-style

This is a test suite and interface you can use to implement a connection. The connection interface contains all the metadata associated with it, as well as an array of the streams opened through this connection. In the same way as the connection, a stream contains properties with its metadata, plus an iterable duplex object that offers a mechanism for writing and reading data, with back pressure. This module and test suite were heavily inspired by abstract-blob-store and interface-stream-muxer.

The primary goal of this module is to enable developers to pick, swap or upgrade their connection without losing the same API expectations and mechanisms such as back pressure and the ability to half close a connection.

Publishing a test suite as a module lets multiple modules ensure compatibility since they use the same test suite.

Lead Maintainer

Jacob Heun

Usage

Connection

Before creating a connection from a transport compatible with libp2p it is important to understand some concepts:

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 layer that sits on top of the raw socket.

This helps ensuring that the transport is responsible for socket management, while also allowing the application layer to handle the connection management.

Test suite

JS

describe('your connection', () => {
  require('interface-connection/src/tests')({
    async setup () {
      return YourConnection
    },
    async teardown () {
      // cleanup resources created by setup()
    }
  })
})

Go

WIP

API

Connection

A valid connection (one that follows this abstraction), must implement the following API:

new Connection({
  localAddr,
  remoteAddr,
  localPeer,
  remotePeer,
  newStream,
  close,
  getStreams,
  stat: {
    direction,
    timeline: {
      open,
      upgraded
    },
    multiplexer,
    encryption
  }
})

It can be obtained as follows:

const { Connection } = require('interface-connection')

const conn = new Connection({
  localAddr: maConn.localAddr,
  remoteAddr: maConn.remoteAddr,
  localPeer: this._peerId,
  remotePeer,
  newStream,
  close: err => maConn.close(err),
  getStreams,
  stats: {
    direction: 'outbound',
    timeline: {
      open: maConn.timeline.open,
      upgraded: Date.now()
    },
    multiplexer,
    encryption
  }
})

Creating a connection instance

Creates a new Connection instance.

localAddr is the multiaddr address used by the local peer to reach the remote. remoteAddr is the multiaddr address used to communicate with the remote peer. localPeer is the PeerId of the local peer. remotePeer is the PeerId of the remote peer. newStream is the function responsible for getting a new muxed+multistream-selected stream. close is the function responsible for closing the raw connection. getStreams is the function responsible for getting the streams muxed within the connection. stats is an object with the metadata of the connection. It contains:

Create a new stream

Create a new stream within the connection.

protocols is an array of the intended protocol to use (by order of preference). Example: [/echo/1.0.0]

It returns a Promise with an object with the following properties:

{
  stream,
  protocol
}

The stream property contains the muxed stream, while the protocol contains the protocol codec used by the stream.

Add stream metadata

Add a new stream to the connection registry.

stream is a muxed stream. protocol is the string codec for the protocol used by the stream. Example: /echo/1.0.0 metadata is an object containing any additional, optional, stream metadata that you wish to track (such as its tags).

Remove a from the registry

Removes the stream with the given id from the connection registry.

id is the unique id of the stream for this connection.

Close connection

This method closes the connection to the remote peer, as well as all the streams muxed within the connection.

It returns a Promise.

Connection identifier

This property contains the identifier of the connection.

Connection streams registry

This property contains a map with the muxed streams indexed by their id. This registry contains the protocol used by the stream, as well as its metadata.

Remote peer

This property contains the remote peer-id of this connection.

Local peer

This property contains the local peer-id of this connection.

Get the connection Streams

This getter returns all the muxed streams within the connection.

It returns an Array.

Remote address

This getter returns the remote multiaddr address.

Local address

This getter returns the local multiaddr address.

Stat

This getter returns an Object with the metadata of the connection, as follows:

This property contains the status of the connection. It can be either open, closing or closed. 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.

This property contains an object with the open, upgraded and close timestamps of the connection. Note that, the close timestamp is undefined until the connection is closed.

This property contains the direction of the peer in the connection. It can be inbound or outbound.

This property contains the multiplexing codec being used in the connection.

This property contains the encryption method being used in the connection. It is undefined if the connection is not encrypted.

Tags

This property contains an array of tags associated with the connection. New tags can be pushed to this array during the connection's lifetime.