A test suite and interface you can use to implement a transport interface.
JavaScript
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
img rename, following libp2p/js-libp2p-switch#8 (comment) Sep 17, 2015
src feat(connection): migrate to pull-streams Sep 5, 2016
test feat(connection): migrate to pull-streams Sep 5, 2016
.gitignore feat: async crypto + sauce labs + aegir 9 Nov 1, 2016
.npmignore add required methods by the consumers of the conn obj, to the conn in… Jun 16, 2016
.travis.yml feat: async crypto + sauce labs + aegir 9 Nov 1, 2016
LICENSE
README.md Grammar fixes (#25) Jun 25, 2018
circle.yml
package.json chore: add engine Mar 21, 2017

README.md

interface-connection

This is a test suite and interface you can use to implement a connection. A connection is understood as something that offers mechanism for writing and reading data, back pressure, half and full duplex streams. 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 all ensure compatibility since they use the same test suite.

The API is presented with both Node.js and Go primitives, however, there is no actual limitations for it to be extended to any other language, pushing forward the cross compatibility and interop through diferent stacks.

Modules that implement the interface

Badge

Include this badge in your readme if you make a module that is compatible with the interface-connection API. You can validate this by running the tests.

How to use the battery of tests

Node.js

var tape = require('tape')
var tests = require('interface-connection/tests')
var YourConnectionHandler = require('../src')

var common = {
  setup: function (t, cb) {
    cb(null, YourConnectionHandler)
  },
  teardown: function (t, cb) {
    cb()
  }
}

tests(tape, common)

Go

WIP

API

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

Table of contents:

  • type: Connection
    • conn.getObservedAddrs(callback)
    • conn.getPeerInfo(callback)
    • conn.setPeerInfo(peerInfo)
    • ...

Get the Observed Addresses of the peer in the other end

  • JavaScript - conn.getObservedAddrs(callback)

This method retrieves the observed addresses we get from the underlying transport, if any.

callback should follow the follow function (err, multiaddrs) {}, where multiaddrs is an array of multiaddr.

Get the PeerInfo

  • JavaScript - conn.getPeerInfo(callback)

This method retrieves the a Peer Info object that contains information about the peer that this conn connects to.

callback should follow the function (err, peerInfo) {} signature, where peerInfo is a object of type Peer Info

Set the PeerInfo

  • JavaScript - conn.setPeerInfo(peerInfo) j This method stores a reference to the peerInfo Object that contains information about the peer that this conn connects to.

peerInfo is a object of type Peer Info


notes:

  • should follow the remaining Duplex stream operations
  • should have backpressure into account
  • should enable half duplex streams (close from one side, but still open for the other)
  • should support full duplex
  • tests should be performed by passing two streams