feat: use registrar

Author: vasco-santos

.aegir.js

@@ -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.
 
 ## Lead Maintainer
 
@@ -22,6 +22,7 @@ js-libp2p-pubsub
 
 - [Install](#install)
 - [Usage](#usage)
+- [API](#api)
 - [Contribute](#contribute)
 - [License](#license)
 
@@ -33,23 +34,27 @@ 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.
 
-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
 
 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 = {}) {
+    super('libp2p:pubsub', '/pubsub-implementation/1.0.0', peerInfo, registrar, options)
   }
 
-  _processConnection(idB58Str, conn, peer) {
+  _processMessages(idB58Str, conn, peer) {
     // Required to be implemented by the subclass
     // Process each message accordingly
   }
@@ -65,9 +70,114 @@ 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`.
+
+### Start
+
+Start the pubsub subsystem. The protocol will be registered to `libp2p`, which will notify about peers being connected and disconnected with the protocol.
+
+#### `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 established connections 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.
+
+#### `pubsub.getPeersSubscribed(topic)`
+
+##### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| topic | `string` | pubsub topic |
+
+##### Returns
+
+| Type | Description |
+|------|-------------|
+| `Array<string>` | Array of base-58 peer id's |
+
 ### Validate
 
 Validates the signature of a message.

README.md

@@ -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"
@@ -45,35 +42,26 @@
   },
   "homepage": "https://github.com/libp2p/js-libp2p-pubsub#readme",
   "devDependencies": {
-    "aegir": "^20.3.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.26.2",
-    "libp2p-secio": "~0.11.1",
-    "libp2p-spdy": "~0.13.3",
-    "libp2p-tcp": "~0.13.1",
-    "libp2p-websocket-star": "~0.10.2",
-    "libp2p-websocket-star-rendezvous": "~0.4.1",
-    "lodash": "^4.17.15",
+    "it-pair": "^1.0.0",
     "multiaddr": "^6.1.0",
-    "peer-id": "~0.12.2",
-    "peer-info": "~0.15.1"
+    "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": "^2.0.0",
-    "length-prefixed-stream": "^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.3",
-    "pull-pushable": "^2.2.0",
-    "pull-stream": "^3.6.14",
-    "sinon": "^7.5.0",
-    "time-cache": "~0.3.0"
+    "sinon": "^7.5.0"
   },
   "contributors": [
     "Cayman <[email protected]>",