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

refactor: async #26

Merged
merged 6 commits into from
Nov 14, 2019
Merged

refactor: async #26

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9df6594
refactor: async
vasco-santos Aug 30, 2019
f60da79
feat: use registrar
vasco-santos Oct 15, 2019
5b4f41b
chore: apply suggestions from code review
vasco-santos Oct 28, 2019
56ac766
chore: address review
vasco-santos Nov 5, 2019
4f94cd2
chore: add topology interface
vasco-santos Nov 7, 2019
f3cd195
chore: tests for getPeersSubscribed
vasco-santos Nov 14, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 0 additions & 71 deletions .aegir.js
View file
Open in desktop

This file was deleted.

140 changes: 130 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ js-libp2p-pubsub
[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
[![](https://img.shields.io/badge/pm-waffle-yellow.svg?style=flat-square)](https://waffle.io/libp2p/js-libp2p-pubsub)

> libp2p-pubsub consits on the base protocol for libp2p pubsub implementation. This module is responsible for all the logic regarding peer connections.
> libp2p-pubsub consists on the base protocol for libp2p pubsub implementations. This module is responsible for registering the protocol in libp2p, as well as all the logic regarding pubsub connections with other peers.
vasco-santos marked this conversation as resolved.
Show resolved Hide resolved
vasco-santos marked this conversation as resolved.
Show resolved Hide resolved

## Lead Maintainer

Expand All @@ -22,6 +22,7 @@ js-libp2p-pubsub

- [Install](#install)
- [Usage](#usage)
- [API](#api)
- [Contribute](#contribute)
- [License](#license)

Expand All @@ -33,23 +34,34 @@ js-libp2p-pubsub

## Usage

A pubsub implementation **MUST** override the `_processConnection`, `publish`, `subscribe` and `unsubscribe` functions.
`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 algortithm, instead of also needing to create the setup for it.
vasco-santos marked this conversation as resolved.
Show resolved Hide resolved

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
A pubsub implementation **MUST** override the `_processMessages`, `publish`, `subscribe`, `unsubscribe` and `getTopics` functions.

Other functions, such as `_onPeerConnected`, `_onPeerDisconnected`, `_addPeer`, `_removePeer`, `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 registering the pubsub protocol onto the libp2p node, while the `stop` function is responsible for unregistering the pubsub protocol and shutting down every connection
vasco-santos marked this conversation as resolved.
Show resolved Hide resolved
vasco-santos marked this conversation as resolved.
Show resolved Hide resolved

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

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

TODO: add explanation for registrar!

```JavaScript
const Pubsub = require('libp2p-pubsub')

class PubsubImplementation extends Pubsub {
constructor(libp2p) {
super('libp2p:pubsub', '/pubsub-implementation/1.0.0', libp2p)
constructor(peerInfo, registrar, options = {}) {
vasco-santos marked this conversation as resolved.
Show resolved Hide resolved
super({
debugName: 'libp2p:pubsub',
multicodecs: '/pubsub-implementation/1.0.0',
peerInfo: peerInfo,
registrar: registrar,
signMessages: options.signMessages,
strictSigning: options.strictSigning
})
}

_processConnection(idB58Str, conn, peer) {
_processMessages(idB58Str, conn, peer) {
// Required to be implemented by the subclass
// Process each message accordingly
}
Expand All @@ -65,21 +77,131 @@ class PubsubImplementation extends Pubsub {
unsubscribe() {
// Required to be implemented by the subclass
}

getTopics() {
// Required to be implemented by the subclass
}
}
```

## API

The following specified API should be the base API for a pubsub implementation on top of `libp2p`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't quite follow this statement, is it necessary? How does this API related to https://github.com/ipfs/interface-js-ipfs-core/blob/master/SPEC/PUBSUB.md ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is not necessary. But, taking into account that we want to remove the pubsub function mapping from js-libp2p, and just keep it's instance there, all the implementations should provide the same API.

Regarding the ipfs spec one, I don't think the ls and peers API is understandable, and we already updated those in libp2p-daemon/libp2p-daemon-client. They will have to get that updated

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right now libp2p points to that API for docs, https://github.com/libp2p/js-libp2p#libp2ppubsub. We should either get the ipfs api corrected, or if we're looking to have a different API for libp2p, make sure we have appropriate doc references.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Being worked on libp2p/js-libp2p#467 and will also be pointed in this repo afterward


### Start

Start the pubsub subsystem. The protocol will be registered to `libp2p`, which will notify about peers being connected and disconnected with the protocol.
vasco-santos marked this conversation as resolved.
Show resolved Hide resolved

#### `pubsub.start()`

##### Returns

| Type | Description |
|------|-------------|
| `Promise<void>` | resolves once pubsub starts |

### Stop

Stop the pubsub subsystem. The protocol will be unregistered to `libp2p`, which will remove all listeners for the protocol and the streams with other peers will be closed.

#### `pubsub.stop()`

##### Returns

| Type | Description |
|------|-------------|
| `Promise<void>` | resolves once pubsub stops |

### Publish

Publish data messages to pubsub topics.

#### `pubsub.publish(topics, messages)`

##### Parameters

| Name | Type | Description |
|------|------|-------------|
| topics | `Array<string>|string` | set of pubsub topics |
| messages | `Array<any>|any` | set of messages to publish |

##### Returns

| Type | Description |
|------|-------------|
| `Promise<void>` | resolves once messages are published to the network |

### Subscribe

Subscribe to the given topic(s).

#### `pubsub.subscribe(topics)`

##### Parameters

| Name | Type | Description |
|------|------|-------------|
| topics | `Array<string>|string` | set of pubsub topics |

### Unsubscribe

Unsubscribe from the given topic(s).

#### `pubsub.unsubscribe(topics)`

##### Parameters

| Name | Type | Description |
|------|------|-------------|
| topics | `Array<string>|string` | set of pubsub topics |

### Get Topics

Get the list of topics which the peer is subscribed to.

#### `pubsub.getTopics()`

##### Returns

| Type | Description |
|------|-------------|
| `Array<String>` | Array of subscribed topics |

### Get Peers Subscribed to a topic

Get a list of the peer-ids that are subscribed to one topic.
vasco-santos marked this conversation as resolved.
Show resolved Hide resolved

#### `pubsub.getPeersSubscribed(topic)`

##### Parameters

| Name | Type | Description |
|------|------|-------------|
| topic | `string` | pubsub topic |

##### Returns

| Type | Description |
|------|-------------|
| `Array<string>` | Array of base-58 peer id's |
vasco-santos marked this conversation as resolved.
Show resolved Hide resolved

### Validate

Validates the signature of a message.

#### `pubsub.validate(message, callback)`
#### `pubsub.validate(message)`

##### Parameters

| Name | Type | Description |
|------|------|-------------|
| message | `Message` | a pubsub message |
| callback | `function(Error, Boolean)` | calls back with true if the message is valid |

#### Returns

| Type | Description |
|------|-------------|
| `Promise<Boolean>` | resolves to true if the message is valid |

## Implementations using this base protocol

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

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

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

## License

Copyright (c) Protocol Labs, Inc. under the **MIT License**. See [LICENSE file](./LICENSE) for details.
34 changes: 11 additions & 23 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,6 @@
"coverage": "aegir coverage",
"coverage-publish": "aegir coverage --provider coveralls"
},
"browser": {
"test/utils/nodejs-bundle": "./test/utils/browser-bundle.js"
},
"files": [
"src",
"dist"
Expand All @@ -45,35 +42,26 @@
},
"homepage": "https://github.com/libp2p/js-libp2p-pubsub#readme",
"devDependencies": {
"aegir": "^18.2.1",
"aegir": "^20.4.1",
"benchmark": "^2.1.4",
"chai": "^4.2.0",
"chai-spies": "^1.0.0",
"dirty-chai": "^2.0.1",
"libp2p": "~0.24.4",
"libp2p-secio": "~0.11.1",
"libp2p-spdy": "~0.13.3",
"libp2p-tcp": "~0.13.0",
"libp2p-websocket-star": "~0.10.2",
"libp2p-websocket-star-rendezvous": "~0.3.0",
"lodash": "^4.17.11",
"multiaddr": "^6.0.6",
"peer-id": "~0.12.5",
"peer-info": "~0.15.1"
"it-pair": "^1.0.0",
"multiaddr": "^6.1.0",
"peer-id": "~0.13.3",
"peer-info": "~0.17.0"
},
"dependencies": {
"async": "^2.6.2",
"bs58": "^4.0.1",
"debug": "^4.1.1",
"err-code": "^1.1.2",
"length-prefixed-stream": "^2.0.0",
"libp2p-crypto": "~0.16.1",
"err-code": "^2.0.0",
"it-length-prefixed": "^2.0.0",
"it-pipe": "^1.0.1",
"it-pushable": "^1.3.2",
"libp2p-crypto": "~0.17.0",
"protons": "^1.0.1",
"pull-length-prefixed": "^1.3.1",
"pull-pushable": "^2.2.0",
"pull-stream": "^3.6.9",
"sinon": "^7.3.2",
"time-cache": "~0.3.0"
"sinon": "^7.5.0"
},
"contributors": [
"Cayman <caymannava@gmail.com>",
Expand Down
Loading