@libp2p/interface-compliance-tests 0.0.0 → 1.0.2

package/src/connection/README.md

@@ -0,0 +1,256 @@
+interface-connection
+==================
+
+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.
+
+## Usage
+
+### 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.
+- **[multiaddr connection](https://github.com/libp2p/interface-transport#multiaddrconnection)**: an abstraction over the socket to allow it to work with multiaddr addresses. It is a duplex connection that transports create to wrap the socket before passing to an upgrader that turns it into a standard connection (see below).
+- **connection**: a connection between two _peers_ that has built in multiplexing and info about the connected peer. It is created from a [multiaddr connection](https://github.com/libp2p/interface-transport#multiaddrconnection) by an upgrader. The upgrader uses multistream-select to add secio and multiplexing and returns this object.
+- **stream**: a muxed 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 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
+const tests = require('libp2p-interfaces-compliance-tests/connection')
+describe('your connection', () => {
+  tests({
+    // Options should be passed to your connection
+    async setup (options) {
+      return YourConnection
+    },
+    async teardown () {
+      // cleanup resources created by setup()
+    }
+  })
+})
+```
+
+## API
+
+### Connection
+
+A valid connection (one that follows this abstraction), must implement the following API:
+
+- type: `Connection`
+```js
+new Connection({
+  localAddr,
+  remoteAddr,
+  localPeer,
+  remotePeer,
+  newStream,
+  close,
+  getStreams,
+  stat: {
+    direction,
+    timeline: {
+      open,
+      upgraded
+    },
+    multiplexer,
+    encryption
+  }
+})
+```
+  - `<Multiaddr> conn.localAddr`
+  - `<Multiaddr> conn.remoteAddr`
+  - `<PeerId> conn.localPeer`
+  - `<PeerId> conn.remotePeer`
+  - `<Object> conn.stat`
+  - `<Map> conn.registry`
+  - `Array<Stream> conn.streams`
+  - `Promise<object> conn.newStream(Array<protocols>)`
+  - `<void> conn.removeStream(id)`
+  - `<Stream> conn.addStream(stream, protocol, metadata)`
+  - `Promise<> conn.close()`
+
+It can be obtained as follows:
+
+```js
+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
+
+- `JavaScript` - `const conn = new Connection({localAddr, remoteAddr, localPeer, remotePeer, newStream, close, getStreams, direction, multiplexer, encryption})`
+
+Creates a new Connection instance.
+
+`localAddr` is the optional [multiaddr](https://github.com/multiformats/multiaddr) address used by the local peer to reach the remote.
+`remoteAddr` is the optional [multiaddr](https://github.com/multiformats/multiaddr) address used to communicate with the remote peer.
+`localPeer` is the [PeerId](https://github.com/libp2p/js-peer-id) of the local peer.
+`remotePeer` is the [PeerId](https://github.com/libp2p/js-peer-id) 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:
+- `direction` is a `string` indicating whether the connection is `inbound` or `outbound`.
+- `timeline` is an `object` with the relevant events timestamps of the connection (`open`, `upgraded` and `closed`; the `closed` will be added when the connection is closed).
+- `multiplexer` is a `string` with the connection multiplexing codec (optional).
+- `encryption` is a `string` with the connection encryption method identifier (optional).
+- `status` is a `string` indicating the overall status of the connection. It is one of [`'open'`, `'closing'`, `'closed'`]
+
+#### Create a new stream
+
+- `JavaScript` - `conn.newStream(protocols)`
+
+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:
+
+```js
+{
+  stream,
+  protocol
+}
+```
+
+The stream property contains the muxed stream, while the protocol contains the protocol codec used by the stream.
+
+#### Add stream metadata
+
+- `JavaScript` - `conn.addStream(stream, { protocol, ...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
+
+- `JavaScript` - `conn.removeStream(id)`
+
+Removes the stream with the given id from the connection registry.
+
+`id` is the unique id of the stream for this connection.
+
+
+#### Close connection
+
+- `JavaScript` - `conn.close()`
+
+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
+
+- `JavaScript` - `conn.id`
+
+This property contains the identifier of the connection.
+
+#### Connection streams registry
+
+- `JavaScript` - `conn.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
+
+- `JavaScript` - `conn.remotePeer`
+
+This property contains the remote `peer-id` of this connection.
+
+#### Local peer
+
+- `JavaScript` - `conn.localPeer`
+
+This property contains the local `peer-id` of this connection.
+
+#### Get the connection Streams
+
+- `JavaScript` - `conn.streams`
+
+This getter returns all the muxed streams within the connection.
+
+It returns an `Array`.
+
+#### Remote address
+
+- `JavaScript` - `conn.remoteAddr`
+
+This getter returns the `remote` [multiaddr](https://github.com/multiformats/multiaddr) address.
+
+#### Local address
+
+- `JavaScript` - `conn.localAddr`
+
+This getter returns the `local` [multiaddr](https://github.com/multiformats/multiaddr) address.
+
+#### Stat
+
+- `JavaScript` - `conn.stat`
+
+This getter returns an `Object` with the metadata of the connection, as follows:
+
+- `status`:
+
+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`. These values can also be directly referenced by importing the `status` file:
+
+```js
+const {
+  OPEN, CLOSING, CLOSED
+} = require('libp2p-interfaces/src/connection/status')
+
+if (connection.stat.status === OPEN) {
+  // ...
+}
+```
+
+- `timeline`:
+
+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.
+
+- `direction`:
+
+This property contains the direction of the peer in the connection. It can be `inbound` or `outbound`.
+
+- `multiplexer`:
+
+This property contains the `multiplexing` codec being used in the connection.
+
+- `encryption`:
+
+This property contains the encryption method being used in the connection. It is `undefined` if the connection is not encrypted.
+
+#### Tags
+
+- `JavaScript` - `conn.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.

package/src/connection/connection.ts

@@ -0,0 +1,178 @@
+import { expect } from 'aegir/utils/chai.js'
+import sinon from 'sinon'
+import type { TestSetup } from '../index.js'
+import type { Connection } from '@libp2p/interfaces/connection'
+
+export default (test: TestSetup<Connection>) => {
+  describe('connection', () => {
+    describe('open connection', () => {
+      let connection: Connection
+
+      beforeEach(async () => {
+        connection = await test.setup()
+      })
+
+      afterEach(async () => {
+        await connection.close()
+        await test.teardown()
+      })
+
+      it('should have properties set', () => {
+        expect(connection.id).to.exist()
+        expect(connection.localPeer).to.exist()
+        expect(connection.remotePeer).to.exist()
+        expect(connection.localAddr).to.exist()
+        expect(connection.remoteAddr).to.exist()
+        expect(connection.stat.status).to.equal('OPEN')
+        expect(connection.stat.timeline.open).to.exist()
+        expect(connection.stat.timeline.upgraded).to.exist()
+        expect(connection.stat.timeline.close).to.not.exist()
+        expect(connection.stat.direction).to.exist()
+        expect(connection.streams).to.eql([])
+        expect(connection.tags).to.eql([])
+      })
+
+      it('should get the metadata of an open connection', () => {
+        const stat = connection.stat
+
+        expect(stat.status).to.equal('OPEN')
+        expect(stat.direction).to.exist()
+        expect(stat.timeline.open).to.exist()
+        expect(stat.timeline.upgraded).to.exist()
+        expect(stat.timeline.close).to.not.exist()
+      })
+
+      it('should return an empty array of streams', () => {
+        const streams = connection.streams
+
+        expect(streams).to.eql([])
+      })
+
+      it('should be able to create a new stream', async () => {
+        const protocolToUse = '/echo/0.0.1'
+        const { stream, protocol } = await connection.newStream([protocolToUse])
+
+        expect(protocol).to.equal(protocolToUse)
+
+        const connStreams = await connection.streams
+
+        expect(stream).to.exist()
+        expect(connStreams).to.exist()
+        expect(connStreams).to.have.lengthOf(1)
+        expect(connStreams[0]).to.equal(stream)
+      })
+    })
+
+    describe('close connection', () => {
+      let connection: Connection
+      let timelineProxy
+      const proxyHandler = {
+        set () {
+          // @ts-expect-error - TS fails to infer here
+          return Reflect.set(...arguments)
+        }
+      }
+
+      beforeEach(async () => {
+        timelineProxy = new Proxy({
+          open: Date.now() - 10,
+          upgraded: Date.now()
+        }, proxyHandler)
+
+        connection = await test.setup({
+          stat: {
+            timeline: timelineProxy,
+            direction: 'outbound',
+            encryption: '/crypto/1.0.0',
+            multiplexer: '/muxer/1.0.0'
+          }
+        })
+      })
+
+      afterEach(async () => {
+        await test.teardown()
+      })
+
+      it('should be able to close the connection after being created', async () => {
+        expect(connection.stat.timeline.close).to.not.exist()
+        await connection.close()
+
+        expect(connection.stat.timeline.close).to.exist()
+        expect(connection.stat.status).to.equal('CLOSED')
+      })
+
+      it('should be able to close the connection after opening a stream', async () => {
+        // Open stream
+        const protocol = '/echo/0.0.1'
+        await connection.newStream([protocol])
+
+        // Close connection
+        expect(connection.stat.timeline.close).to.not.exist()
+        await connection.close()
+
+        expect(connection.stat.timeline.close).to.exist()
+        expect(connection.stat.status).to.equal('CLOSED')
+      })
+
+      it('should properly track streams', async () => {
+        // Open stream
+        const protocol = '/echo/0.0.1'
+        const { stream } = await connection.newStream([protocol])
+        const trackedStream = connection.registry.get(stream.id)
+        expect(trackedStream).to.have.property('protocol', protocol)
+
+        // Close stream
+        await stream.close()
+
+        expect(connection.registry.get(stream.id)).to.not.exist()
+      })
+
+      it('should support a proxy on the timeline', async () => {
+        sinon.spy(proxyHandler, 'set')
+        expect(connection.stat.timeline.close).to.not.exist()
+
+        await connection.close()
+        // @ts-expect-error - fails to infer callCount
+        expect(proxyHandler.set.callCount).to.equal(1)
+        // @ts-expect-error - fails to infer getCall
+        const [obj, key, value] = proxyHandler.set.getCall(0).args
+        expect(obj).to.eql(connection.stat.timeline)
+        expect(key).to.equal('close')
+        expect(value).to.be.a('number').that.equals(connection.stat.timeline.close)
+      })
+
+      it('should fail to create a new stream if the connection is closing', async () => {
+        expect(connection.stat.timeline.close).to.not.exist()
+        const p = connection.close()
+
+        try {
+          const protocol = '/echo/0.0.1'
+          await connection.newStream([protocol])
+        } catch (err: any) {
+          expect(err).to.exist()
+          return
+        } finally {
+          await p
+        }
+
+        throw new Error('should fail to create a new stream if the connection is closing')
+      })
+
+      it('should fail to create a new stream if the connection is closed', async () => {
+        expect(connection.stat.timeline.close).to.not.exist()
+        await connection.close()
+
+        try {
+          const protocol = '/echo/0.0.1'
+          await connection.newStream([protocol])
+        } catch (err: any) {
+          expect(err).to.exist()
+          expect(err.code).to.equal('ERR_CONNECTION_CLOSED')
+          return
+        }
+
+        throw new Error('should fail to create a new stream if the connection is closing')
+      })
+    })
+  })
+}

package/src/connection/index.ts

@@ -0,0 +1,7 @@
+import connectionSuite from './connection.js'
+import type { TestSetup } from '../index.js'
+import type { Connection } from '@libp2p/interfaces/connection'
+
+export default (test: TestSetup<Connection>) => {
+  connectionSuite(test)
+}

package/src/crypto/index.ts

@@ -0,0 +1,104 @@
+import { expect } from 'aegir/utils/chai.js'
+// @ts-expect-error no types
+import duplexPair from 'it-pair/duplex.js'
+import { pipe } from 'it-pipe'
+import * as PeerIdFactory from '@libp2p/peer-id-factory'
+import { collect } from 'streaming-iterables'
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+import peers from '../utils/peers.js'
+import { UnexpectedPeerError } from '@libp2p/interfaces/crypto/errors'
+import type { TestSetup } from '../index.js'
+import type { Crypto } from '@libp2p/interfaces/crypto'
+import type { PeerId } from '@libp2p/interfaces/peer-id'
+
+export default (common: TestSetup<Crypto>) => {
+  describe('interface-crypto compliance tests', () => {
+    let crypto: Crypto
+    let localPeer: PeerId
+    let remotePeer: PeerId
+    let mitmPeer: PeerId
+
+    before(async () => {
+      [
+        crypto,
+        localPeer,
+        remotePeer,
+        mitmPeer
+      ] = await Promise.all([
+        common.setup(),
+        PeerIdFactory.createFromJSON(peers[0]),
+        PeerIdFactory.createFromJSON(peers[1]),
+        PeerIdFactory.createFromJSON(peers[2])
+      ])
+    })
+
+    after(async () => {
+      await common.teardown()
+    })
+
+    it('has a protocol string', () => {
+      expect(crypto.protocol).to.exist()
+      expect(crypto.protocol).to.be.a('string')
+    })
+
+    it('it wraps the provided duplex connection', async () => {
+      const [localConn, remoteConn] = duplexPair()
+
+      const [
+        inboundResult,
+        outboundResult
+      ] = await Promise.all([
+        crypto.secureInbound(remotePeer, localConn),
+        crypto.secureOutbound(localPeer, remoteConn, remotePeer)
+      ])
+
+      // Echo server
+      pipe(inboundResult.conn, inboundResult.conn)
+
+      // Send some data and collect the result
+      const input = uint8ArrayFromString('data to encrypt')
+      const result = await pipe(
+        [input],
+        outboundResult.conn,
+        // Convert BufferList to Buffer via slice
+        (source: AsyncIterable<Uint8Array>) => (async function * toBuffer () {
+          for await (const chunk of source) {
+            yield chunk.slice()
+          }
+        })(),
+        collect
+      )
+
+      expect(result).to.eql([input])
+    })
+
+    it('should return the remote peer id', async () => {
+      const [localConn, remoteConn] = duplexPair()
+
+      const [
+        inboundResult,
+        outboundResult
+      ] = await Promise.all([
+        crypto.secureInbound(remotePeer, localConn),
+        crypto.secureOutbound(localPeer, remoteConn, remotePeer)
+      ])
+
+      // Inbound should return the initiator (local) peer
+      expect(inboundResult.remotePeer.toBytes()).to.equalBytes(localPeer.toBytes())
+      // Outbound should return the receiver (remote) peer
+      expect(outboundResult.remotePeer.toBytes()).to.equalBytes(remotePeer.toBytes())
+    })
+
+    it('inbound connections should verify peer integrity if known', async () => {
+      const [localConn, remoteConn] = duplexPair()
+
+      await Promise.all([
+        crypto.secureInbound(remotePeer, localConn, mitmPeer),
+        crypto.secureOutbound(localPeer, remoteConn, remotePeer)
+      ]).then(() => expect.fail(), (err) => {
+        expect(err).to.exist()
+        expect(err).to.have.property('code', UnexpectedPeerError.code)
+      })
+    })
+  })
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+
+export interface TestSetup<T, SetupArgs = {}> {
+  setup: (args?: SetupArgs) => Promise<T>
+  teardown: () => Promise<void>
+}

package/src/peer-discovery/index.ts

@@ -0,0 +1,87 @@
+import { expect } from 'aegir/utils/chai.js'
+import { Multiaddr } from '@multiformats/multiaddr'
+import delay from 'delay'
+import pDefer from 'p-defer'
+import type { TestSetup } from '../index.js'
+import type { PeerDiscovery } from '@libp2p/interfaces/peer-discovery'
+import type { Startable } from '@libp2p/interfaces'
+
+export default (common: TestSetup<PeerDiscovery & Startable>) => {
+  describe('interface-peer-discovery compliance tests', () => {
+    let discovery: PeerDiscovery & Startable
+
+    beforeEach(async () => {
+      discovery = await common.setup()
+    })
+
+    afterEach('ensure discovery was stopped', async () => {
+      await discovery.stop()
+
+      discovery.removeAllListeners()
+
+      await common.teardown()
+    })
+
+    it('can start the service', async () => {
+      await discovery.start()
+    })
+
+    it('can start and stop the service', async () => {
+      await discovery.start()
+      await discovery.stop()
+    })
+
+    it('should not fail to stop the service if it was not started', async () => {
+      await discovery.stop()
+    })
+
+    it('should not fail to start the service if it is already started', async () => {
+      await discovery.start()
+      await discovery.start()
+    })
+
+    it('should emit a peer event after start', async () => {
+      const defer = pDefer()
+      await discovery.start()
+
+      discovery.on('peer', ({ id, multiaddrs }) => {
+        expect(id).to.exist()
+        expect(id).to.have.property('type').that.is.oneOf(['RSA', 'Ed25519', 'secp256k1'])
+        expect(multiaddrs).to.exist()
+
+        multiaddrs.forEach((m) => expect(Multiaddr.isMultiaddr(m)).to.eql(true))
+
+        defer.resolve()
+      })
+
+      await defer.promise
+    })
+
+    it('should not receive a peer event before start', async () => {
+      discovery.on('peer', () => {
+        throw new Error('should not receive a peer event before start')
+      })
+
+      await delay(2000)
+    })
+
+    it('should not receive a peer event after stop', async () => {
+      const deferStart = pDefer()
+
+      await discovery.start()
+
+      discovery.on('peer', () => {
+        deferStart.resolve()
+      })
+
+      await deferStart.promise
+      await discovery.stop()
+
+      discovery.on('peer', () => {
+        throw new Error('should not receive a peer event after stop')
+      })
+
+      await delay(2000)
+    })
+  })
+}