Skip to content

Commit c690b29

Browse files
vasco-santosvasco-santos
authored
refactor: async (#26)
BREAKING CHANGE: Switch to using async/await and async iterators.
1 parent 8669709 commit c690b29

16 files changed

+794
-895
lines changed

‎.aegir.js

Lines changed: 0 additions & 71 deletions
This file was deleted.

‎README.md

Lines changed: 130 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ js-libp2p-pubsub
1212
[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
1313
[![](https://img.shields.io/badge/pm-waffle-yellow.svg?style=flat-square)](https://waffle.io/libp2p/js-libp2p-pubsub)
1414

15-
> libp2p-pubsub consits on the base protocol for libp2p pubsub implementation. This module is responsible for all the logic regarding peer connections.
15+
> libp2p-pubsub is the base protocol for libp2p pubsub implementations. This module is responsible for registering the protocol with libp2p, as well as managing the logic regarding pubsub connections with other peers.
1616
1717
## Lead Maintainer
1818

@@ -22,6 +22,7 @@ js-libp2p-pubsub
2222

2323
- [Install](#install)
2424
- [Usage](#usage)
25+
- [API](#api)
2526
- [Contribute](#contribute)
2627
- [License](#license)
2728

@@ -33,23 +34,34 @@ js-libp2p-pubsub
3334

3435
## Usage
3536

36-
A pubsub implementation **MUST** override the `_processConnection`, `publish`, `subscribe` and `unsubscribe` functions.
37+
`libp2p-pubsub` abstracts the implementation protocol registration within `libp2p` and takes care of all the protocol connections. This way, a pubsub implementation can focus on its routing algorithm, instead of also needing to create the setup for it.
3738

38-
Other functions, such as `_addPeer`, `_removePeer`, `_onDial`, `start` and `stop` may be overwritten if the pubsub implementation needs to add custom logic on them. It is important pointing out that `start` and `stop` **must** call `super`. The `start` function is responsible for mounting the pubsub protocol onto the libp2p node and sending its' subscriptions to every peer connected, while the `stop` function is responsible for unmounting the pubsub protocol and shutting down every connection
39+
A pubsub implementation **MUST** override the `_processMessages`, `publish`, `subscribe`, `unsubscribe` and `getTopics` functions.
40+
41+
Other functions, such as `_onPeerConnected`, `_onPeerDisconnected`, `_addPeer`, `_removePeer`, `start` and `stop` may be overwritten if the pubsub implementation needs to customize their logic. Implementations overriding `start` and `stop` **MUST** call `super`. The `start` function is responsible for registering the pubsub protocol with libp2p, while the `stop` function is responsible for unregistering the pubsub protocol and closing pubsub connections.
3942

4043
All the remaining functions **MUST NOT** be overwritten.
4144

4245
The following example aims to show how to create your pubsub implementation extending this base protocol. The pubsub implementation will handle the subscriptions logic.
4346

47+
TODO: add explanation for registrar!
48+
4449
```JavaScript
4550
const Pubsub = require('libp2p-pubsub')
4651

4752
class PubsubImplementation extends Pubsub {
48-
constructor(libp2p) {
49-
super('libp2p:pubsub', '/pubsub-implementation/1.0.0', libp2p)
53+
constructor({ peerInfo, registrar, ...options })
54+
super({
55+
debugName: 'libp2p:pubsub',
56+
multicodecs: '/pubsub-implementation/1.0.0',
57+
peerInfo: peerInfo,
58+
registrar: registrar,
59+
signMessages: options.signMessages,
60+
strictSigning: options.strictSigning
61+
})
5062
}
5163

52-
_processConnection(idB58Str, conn, peer) {
64+
_processMessages(idB58Str, conn, peer) {
5365
// Required to be implemented by the subclass
5466
// Process each message accordingly
5567
}
@@ -65,21 +77,131 @@ class PubsubImplementation extends Pubsub {
6577
unsubscribe() {
6678
// Required to be implemented by the subclass
6779
}
80+
81+
getTopics() {
82+
// Required to be implemented by the subclass
83+
}
6884
}
6985
```
7086

87+
## API
88+
89+
The following specified API should be the base API for a pubsub implementation on top of `libp2p`.
90+
91+
### Start
92+
93+
Starts the pubsub subsystem. The protocol will be registered to `libp2p`, which will result in pubsub being notified when peers who support the protocol connect/disconnect to `libp2p`.
94+
95+
#### `pubsub.start()`
96+
97+
##### Returns
98+
99+
| Type | Description |
100+
|------|-------------|
101+
| `Promise<void>` | resolves once pubsub starts |
102+
103+
### Stop
104+
105+
Stops the pubsub subsystem. The protocol will be unregistered from `libp2p`, which will remove all listeners for the protocol and the established connections will be closed.
106+
107+
#### `pubsub.stop()`
108+
109+
##### Returns
110+
111+
| Type | Description |
112+
|------|-------------|
113+
| `Promise<void>` | resolves once pubsub stops |
114+
115+
### Publish
116+
117+
Publish data messages to pubsub topics.
118+
119+
#### `pubsub.publish(topics, messages)`
120+
121+
##### Parameters
122+
123+
| Name | Type | Description |
124+
|------|------|-------------|
125+
| topics | `Array<string>|string` | set of pubsub topics |
126+
| messages | `Array<any>|any` | set of messages to publish |
127+
128+
##### Returns
129+
130+
| Type | Description |
131+
|------|-------------|
132+
| `Promise<void>` | resolves once messages are published to the network |
133+
134+
### Subscribe
135+
136+
Subscribe to the given topic(s).
137+
138+
#### `pubsub.subscribe(topics)`
139+
140+
##### Parameters
141+
142+
| Name | Type | Description |
143+
|------|------|-------------|
144+
| topics | `Array<string>|string` | set of pubsub topics |
145+
146+
### Unsubscribe
147+
148+
Unsubscribe from the given topic(s).
149+
150+
#### `pubsub.unsubscribe(topics)`
151+
152+
##### Parameters
153+
154+
| Name | Type | Description |
155+
|------|------|-------------|
156+
| topics | `Array<string>|string` | set of pubsub topics |
157+
158+
### Get Topics
159+
160+
Get the list of topics which the peer is subscribed to.
161+
162+
#### `pubsub.getTopics()`
163+
164+
##### Returns
165+
166+
| Type | Description |
167+
|------|-------------|
168+
| `Array<String>` | Array of subscribed topics |
169+
170+
### Get Peers Subscribed to a topic
171+
172+
Get a list of the [PeerId](https://github.com/libp2p/js-peer-id) strings that are subscribed to one topic.
173+
174+
#### `pubsub.getPeersSubscribed(topic)`
175+
176+
##### Parameters
177+
178+
| Name | Type | Description |
179+
|------|------|-------------|
180+
| topic | `string` | pubsub topic |
181+
182+
##### Returns
183+
184+
| Type | Description |
185+
|------|-------------|
186+
| `Array<string>` | Array of base-58 PeerId's |
187+
71188
### Validate
72189

73190
Validates the signature of a message.
74191

75-
#### `pubsub.validate(message, callback)`
192+
#### `pubsub.validate(message)`
76193

77194
##### Parameters
78195

79196
| Name | Type | Description |
80197
|------|------|-------------|
81198
| message | `Message` | a pubsub message |
82-
| callback | `function(Error, Boolean)` | calls back with true if the message is valid |
199+
200+
#### Returns
201+
202+
| Type | Description |
203+
|------|-------------|
204+
| `Promise<Boolean>` | resolves to true if the message is valid |
83205

84206
## Implementations using this base protocol
85207

@@ -94,8 +216,6 @@ Feel free to join in. All welcome. Open an [issue](https://github.com/libp2p/js-
94216

95217
This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
96218

97-
[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/contributing.md)
98-
99219
## License
100220

101221
Copyright (c) Protocol Labs, Inc. under the **MIT License**. See [LICENSE file](./LICENSE) for details.

‎package.json

Lines changed: 12 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,6 @@
1717
"coverage": "aegir coverage",
1818
"coverage-publish": "aegir coverage --provider coveralls"
1919
},
20-
"browser": {
21-
"test/utils/nodejs-bundle": "./test/utils/browser-bundle.js"
22-
},
2320
"files": [
2421
"src",
2522
"dist"
@@ -45,35 +42,27 @@
4542
},
4643
"homepage": "https://github.com/libp2p/js-libp2p-pubsub#readme",
4744
"devDependencies": {
48-
"aegir": "^18.2.1",
45+
"aegir": "^20.4.1",
4946
"benchmark": "^2.1.4",
5047
"chai": "^4.2.0",
5148
"chai-spies": "^1.0.0",
5249
"dirty-chai": "^2.0.1",
53-
"libp2p": "~0.24.4",
54-
"libp2p-secio": "~0.11.1",
55-
"libp2p-spdy": "~0.13.3",
56-
"libp2p-tcp": "~0.13.0",
57-
"libp2p-websocket-star": "~0.10.2",
58-
"libp2p-websocket-star-rendezvous": "~0.3.0",
59-
"lodash": "^4.17.11",
60-
"multiaddr": "^6.0.6",
61-
"peer-id": "~0.12.5",
62-
"peer-info": "~0.15.1"
50+
"it-pair": "^1.0.0",
51+
"multiaddr": "^6.1.0",
52+
"peer-id": "~0.13.3",
53+
"peer-info": "~0.17.0"
6354
},
6455
"dependencies": {
65-
"async": "^2.6.2",
6656
"bs58": "^4.0.1",
6757
"debug": "^4.1.1",
68-
"err-code": "^1.1.2",
69-
"length-prefixed-stream": "^2.0.0",
70-
"libp2p-crypto": "~0.16.1",
58+
"err-code": "^2.0.0",
59+
"it-length-prefixed": "^2.0.0",
60+
"it-pipe": "^1.0.1",
61+
"it-pushable": "^1.3.2",
62+
"libp2p-crypto": "~0.17.0",
63+
"libp2p-interfaces": "~0.1.4",
7164
"protons": "^1.0.1",
72-
"pull-length-prefixed": "^1.3.1",
73-
"pull-pushable": "^2.2.0",
74-
"pull-stream": "^3.6.9",
75-
"sinon": "^7.3.2",
76-
"time-cache": "~0.3.0"
65+
"sinon": "^7.5.0"
7766
},
7867
"contributors": [
7968
"Cayman <caymannava@gmail.com>",

0 commit comments

Comments
 (0)