Skip to content
This repository was archived by the owner on Jun 26, 2023. It is now read-only.

Commit 8bee747

Browse files
vasco-santosjacobheun
vasco-santos
and
jacobheun
committed
feat: add topology interfaces (#7)
* feat: topology * feat: multicodec-topology * chore: address review Co-Authored-By: Jacob Heun <[email protected]> * chore: remove error from disconnect * docs: topology * chore: apply suggestions from code review Co-Authored-By: Jacob Heun <[email protected]>
1 parent b960f29 commit 8bee747

9 files changed

+492
-0
lines changed

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
- [Peer Discovery](./src/peer-discovery)
2020
- [Peer Routing](./src/peer-routing)
2121
- [Stream Muxer](./src/stream-muxer)
22+
- [Topology](./src/topology)
2223
- [Transport](./src/transport)
2324

2425
### Origin Repositories

‎src/topology/README.md

+141
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
interface-topology
2+
========================
3+
4+
> Implementation of the topology interface used by the `js-libp2p` registrar.
5+
6+
Topologies can be used in conjunction with `js-libp2p` to help shape its network and the overlays of its subsystems, such as pubsub and the DHT.
7+
8+
## Table of Contents
9+
10+
- [Implementations](#implementations)
11+
- [Install](#install)
12+
- [Modules using the interface](#modulesUsingTheInterface)
13+
- [Usage](#usage)
14+
- [Api](#api)
15+
16+
## Implementations
17+
18+
### Topology
19+
20+
A libp2p topology with a group of common peers.
21+
22+
### Multicodec Topology
23+
24+
A libp2p topology with a group of peers that support the same protocol.
25+
26+
## Install
27+
28+
```sh
29+
$ npm install libp2p-interfaces
30+
```
31+
32+
## Modules using the interface
33+
34+
TBA
35+
36+
## Usage
37+
38+
### Topology
39+
40+
```js
41+
const Topology = require('libp2p-interfaces/src/topology')
42+
43+
const toplogy = new Topology({
44+
min: 0,
45+
max: 50
46+
})
47+
```
48+
49+
### Multicodec Topology
50+
51+
```js
52+
const MulticodecTopology = require('libp2p-interfaces/src/topology/multicodec-topology')
53+
54+
const toplogy = new MulticodecTopology({
55+
min: 0,
56+
max: 50,
57+
multicodecs: ['/echo/1.0.0'],
58+
handlers: {
59+
onConnect: (peerInfo, conn) => {},
60+
onDisconnect: (peerInfo) => {}
61+
}
62+
})
63+
```
64+
65+
## API
66+
67+
The `MulticodecTopology` extends the `Topology`, which makes the `Topology` API a subset of the `MulticodecTopology` API.
68+
69+
### Topology
70+
71+
- `Topology`
72+
- `peers<Map<string, PeerInfo>>`: A Map of peers belonging to the topology.
73+
- `disconnect<function(PeerInfo)>`: Called when a peer has been disconnected
74+
75+
#### Constructor
76+
77+
```js
78+
const toplogy = new Topology({
79+
min: 0,
80+
max: 50,
81+
handlers: {
82+
onConnect: (peerInfo, conn) => {},
83+
onDisconnect: (peerInfo) => {}
84+
}
85+
})
86+
```
87+
88+
**Parameters**
89+
- `properties` is an `Object` containing the properties of the topology.
90+
- `min` is a `number` with the minimum needed connections (default: 0)
91+
- `max` is a `number` with the maximum needed connections (default: Infinity)
92+
- `handlers` is an optional `Object` containing the handler called when a peer is connected or disconnected.
93+
- `onConnect` is a `function` called everytime a peer is connected in the topology context.
94+
- `onDisconnect` is a `function` called everytime a peer is disconnected in the topology context.
95+
96+
#### Set a peer
97+
98+
- `topology.peers.set(id, peerInfo)`
99+
100+
Add a peer to the topology.
101+
102+
**Parameters**
103+
- `id` is the `string` that identifies the peer to add.
104+
- `peerInfo` is the [PeerInfo][peer-info] of the peer to add.
105+
106+
#### Notify about a peer disconnected event
107+
108+
- `topology.disconnect(peerInfo)`
109+
110+
**Parameters**
111+
- `peerInfo` is the [PeerInfo][peer-info] of the peer disconnected.
112+
113+
### Multicodec Topology
114+
115+
- `MulticodecTopology`
116+
- `registrar<Registrar>`: The `Registrar` of the topology. This is set by the `Registrar` during registration.
117+
- `peers<Map<string, PeerInfo>>`: The Map of peers that belong to the topology
118+
- `disconnect<function(PeerInfo)>`: Disconnects a peer from the topology.
119+
120+
#### Constructor
121+
122+
```js
123+
const toplogy = new MulticodecTopology({
124+
min: 0,
125+
max: 50,
126+
multicodecs: ['/echo/1.0.0'],
127+
handlers: {
128+
onConnect: (peerInfo, conn) => {},
129+
onDisconnect: (peerInfo) => {}
130+
}
131+
})
132+
```
133+
134+
**Parameters**
135+
- `properties` is an `Object` containing the properties of the topology.
136+
- `min` is a `number` with the minimum needed connections (default: 0)
137+
- `max` is a `number` with the maximum needed connections (default: Infinity)
138+
- `multicodecs` is a `Array<String>` with the multicodecs associated with the topology.
139+
- `handlers` is an optional `Object` containing the handler called when a peer is connected or disconnected.
140+
- `onConnect` is a `function` called everytime a peer is connected in the topology context.
141+
- `onDisconnect` is a `function` called everytime a peer is disconnected in the topology context.

‎src/topology/index.js

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
'use strict'
2+
3+
const noop = () => {}
4+
5+
class Topology {
6+
/**
7+
* @param {Object} props
8+
* @param {number} props.min minimum needed connections (default: 0)
9+
* @param {number} props.max maximum needed connections (default: Infinity)
10+
* @param {Object} [props.handlers]
11+
* @param {function} [props.handlers.onConnect] protocol "onConnect" handler
12+
* @param {function} [props.handlers.onDisconnect] protocol "onDisconnect" handler
13+
* @constructor
14+
*/
15+
constructor ({
16+
min = 0,
17+
max = Infinity,
18+
handlers = {}
19+
}) {
20+
this.min = min
21+
this.max = max
22+
23+
// Handlers
24+
this._onConnect = handlers.onConnect || noop
25+
this._onDisconnect = handlers.onDisconnect || noop
26+
27+
this.peers = new Map()
28+
}
29+
30+
set registrar (registrar) {
31+
this._registrar = registrar
32+
}
33+
34+
/**
35+
* Notify about peer disconnected event.
36+
* @param {PeerInfo} peerInfo
37+
* @returns {void}
38+
*/
39+
disconnect (peerInfo) {
40+
this._onDisconnect(peerInfo)
41+
}
42+
}
43+
44+
module.exports = Topology

‎src/topology/multicodec-topology.js

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
'use strict'
2+
3+
const assert = require('assert')
4+
const Topology = require('./index')
5+
6+
class MulticodecTopology extends Topology {
7+
/**
8+
* @param {Object} props
9+
* @param {number} props.min minimum needed connections (default: 0)
10+
* @param {number} props.max maximum needed connections (default: Infinity)
11+
* @param {Array<string>} props.multicodecs protocol multicodecs
12+
* @param {Object} props.handlers
13+
* @param {function} props.handlers.onConnect protocol "onConnect" handler
14+
* @param {function} props.handlers.onDisconnect protocol "onDisconnect" handler
15+
* @constructor
16+
*/
17+
constructor ({
18+
min,
19+
max,
20+
multicodecs,
21+
handlers
22+
}) {
23+
super({ min, max, handlers })
24+
25+
assert(multicodecs, 'one or more multicodec should be provided')
26+
assert(handlers, 'the handlers should be provided')
27+
assert(handlers.onConnect && typeof handlers.onConnect === 'function',
28+
'the \'onConnect\' handler must be provided')
29+
assert(handlers.onDisconnect && typeof handlers.onDisconnect === 'function',
30+
'the \'onDisconnect\' handler must be provided')
31+
32+
this.multicodecs = Array.isArray(multicodecs) ? multicodecs : [multicodecs]
33+
this._registrar = undefined
34+
35+
this._onProtocolChange = this._onProtocolChange.bind(this)
36+
}
37+
38+
set registrar (registrar) {
39+
this._registrar = registrar
40+
this._registrar.peerStore.on('change:protocols', this._onProtocolChange)
41+
42+
// Update topology peers
43+
this._updatePeers(this._registrar.peerStore.peers.values())
44+
}
45+
46+
/**
47+
* Update topology.
48+
* @param {Array<PeerInfo>} peerInfoIterable
49+
* @returns {void}
50+
*/
51+
_updatePeers (peerInfoIterable) {
52+
for (const peerInfo of peerInfoIterable) {
53+
if (this.multicodecs.filter(multicodec => peerInfo.protocols.has(multicodec))) {
54+
// Add the peer regardless of whether or not there is currently a connection
55+
this.peers.set(peerInfo.id.toB58String(), peerInfo)
56+
// If there is a connection, call _onConnect
57+
const connection = this._registrar.getConnection(peerInfo)
58+
connection && this._onConnect(peerInfo, connection)
59+
} else {
60+
// Remove any peers we might be tracking that are no longer of value to us
61+
this.peers.delete(peerInfo.id.toB58String())
62+
}
63+
}
64+
}
65+
66+
/**
67+
* Check if a new peer support the multicodecs for this topology.
68+
* @param {Object} props
69+
* @param {PeerInfo} props.peerInfo
70+
* @param {Array<string>} props.protocols
71+
*/
72+
_onProtocolChange ({ peerInfo, protocols }) {
73+
const existingPeer = this.peers.get(peerInfo.id.toB58String())
74+
const hasProtocol = protocols.filter(protocol => this.multicodecs.includes(protocol))
75+
76+
// Not supporting the protocol anymore?
77+
if (existingPeer && hasProtocol.length === 0) {
78+
this._onDisconnect({
79+
peerInfo
80+
})
81+
}
82+
83+
// New to protocol support
84+
for (const protocol of protocols) {
85+
if (this.multicodecs.includes(protocol)) {
86+
this._updatePeers([peerInfo])
87+
return
88+
}
89+
}
90+
}
91+
}
92+
93+
module.exports = MulticodecTopology

‎src/topology/tests/multicodec-topology.js

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
/* eslint-env mocha */
2+
3+
'use strict'
4+
5+
const chai = require('chai')
6+
const expect = chai.expect
7+
chai.use(require('dirty-chai'))
8+
const sinon = require('sinon')
9+
10+
const PeerId = require('peer-id')
11+
const PeerInfo = require('peer-info')
12+
const peers = require('../../utils/peers')
13+
14+
module.exports = (test) => {
15+
describe('multicodec topology', () => {
16+
let topology, peer
17+
18+
beforeEach(async () => {
19+
topology = await test.setup()
20+
if (!topology) throw new Error('missing multicodec topology')
21+
22+
const id = await PeerId.createFromJSON(peers[0])
23+
peer = await PeerInfo.create(id)
24+
})
25+
26+
afterEach(async () => {
27+
sinon.restore()
28+
await test.teardown()
29+
})
30+
31+
it('should have properties set', () => {
32+
expect(topology.multicodecs).to.exist()
33+
expect(topology._onConnect).to.exist()
34+
expect(topology._onDisconnect).to.exist()
35+
expect(topology.peers).to.exist()
36+
expect(topology._registrar).to.exist()
37+
})
38+
39+
it('should trigger "onDisconnect" on peer disconnected', () => {
40+
sinon.spy(topology, '_onDisconnect')
41+
topology.disconnect(peer)
42+
43+
expect(topology._onDisconnect.callCount).to.equal(1)
44+
})
45+
46+
it('should update peers on protocol change', async () => {
47+
sinon.spy(topology, '_updatePeers')
48+
expect(topology.peers.size).to.eql(0)
49+
50+
const id2 = await PeerId.createFromJSON(peers[1])
51+
const peer2 = await PeerInfo.create(id2)
52+
53+
const peerStore = topology._registrar.peerStore
54+
peerStore.emit('change:protocols', {
55+
peerInfo: peer2,
56+
protocols: Array.from(topology.multicodecs)
57+
})
58+
59+
expect(topology._updatePeers.callCount).to.equal(1)
60+
expect(topology.peers.size).to.eql(1)
61+
})
62+
63+
it('should disconnect if peer no longer supports a protocol', async () => {
64+
sinon.spy(topology, '_onDisconnect')
65+
expect(topology.peers.size).to.eql(0)
66+
67+
const id2 = await PeerId.createFromJSON(peers[1])
68+
const peer2 = await PeerInfo.create(id2)
69+
const peerStore = topology._registrar.peerStore
70+
71+
// Peer with the protocol
72+
peerStore.emit('change:protocols', {
73+
peerInfo: peer2,
74+
protocols: Array.from(topology.multicodecs)
75+
})
76+
77+
expect(topology.peers.size).to.eql(1)
78+
79+
// Peer does not support the protocol anymore
80+
peerStore.emit('change:protocols', {
81+
peerInfo: peer2,
82+
protocols: []
83+
})
84+
85+
expect(topology.peers.size).to.eql(1)
86+
expect(topology._onDisconnect.callCount).to.equal(1)
87+
})
88+
})
89+
}

0 commit comments

Comments
 (0)