chore: improve docs

README.md

@@ -32,7 +32,9 @@ js-libp2p-pubsub
 
 ## Usage
 
-Create your pubsub implementation extending the base protocol.
+A pubsub implementation **MUST** overwrite the `_processConnection`, `publish`, `subscribe` and `unsubscribe` functions. `add_peer` and `remove_peer` may be overwritten if the pubsub implementation needs to add custom logic when peers are added and remove. 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.
 
 ```JavaScript
 const Pubsub = require('libp2p-pubsub')
@@ -43,23 +45,30 @@ class PubsubImplementation extends Pubsub {
   }
 
   _processConnection(idB58Str, conn, peer) {
+    // Required to be implemented by the subclass
     // Process each message accordingly
   }
 
   publish() {
-
+    // Required to be implemented by the subclass
   }
 
   subscribe() {
-
+    // Required to be implemented by the subclass
   }
 
   unsubscribe() {
-
+    // Required to be implemented by the subclass
   }
 }
 ```
 
+## Implementations using this base protocol
+
+You can use the following implementations as examples for building your own pubsub implementation.
+
+- [libp2p/js-libp2p-floodsub](https://github.com/libp2p/js-libp2p-floodsub)
+
 ## Contribute
 
 Feel free to join in. All welcome. Open an [issue](https://github.com/libp2p/js-libp2p-pubsub/issues)!

package.json

@@ -57,6 +57,7 @@
     "dependencies": {
         "async": "^2.6.1",
         "debug": "^4.1.1",
+        "err-code": "^1.1.2",
         "length-prefixed-stream": "^1.6.0",
         "protons": "^1.0.1",
         "pull-pushable": "^2.2.0"

src/index.js

@@ -4,7 +4,9 @@ const EventEmitter = require('events')
 const pull = require('pull-stream/pull')
 const empty = require('pull-stream/sources/empty')
 const asyncEach = require('async/each')
+
 const debug = require('debug')
+const errcode = require('err-code')
 
 const Peer = require('./peer')
 const message = require('./message')
@@ -145,8 +147,17 @@ class PubsubBaseProtocol extends EventEmitter {
     })
   }
 
+  /**
+   * Process connections
+   * @abstract
+   * @param {string} idB58Str peer id string in base58
+   * @param {Connection} conn connection
+   * @param {PeerInfo} peer peer info
+   * @returns {undefined}
+   *
+   */
   _processConnection (idB58Str, conn, peer) {
-    throw new Error('_processConnection must be implemented by the subclass')
+    throw errcode('_processConnection must be implemented by the subclass', 'ERR_NOT_IMPLEMENTED')
   }
 
   _onConnectionEnd (idB58Str, peer, err) {
@@ -159,6 +170,38 @@ class PubsubBaseProtocol extends EventEmitter {
     this._removePeer(peer)
   }
 
+  /**
+   * Publish messages to the given topics.
+   * @abstract
+   * @param {Array<string>|string} topics
+   * @param {Array<any>|any} messages
+   * @returns {undefined}
+   *
+   */
+  publish (topics, messages) {
+    throw errcode('publish must be implemented by the subclass', 'ERR_NOT_IMPLEMENTED')
+  }
+
+  /**
+   * Subscribe to the given topic(s).
+   * @abstract
+   * @param {Array<string>|string} topics
+   * @returns {undefined}
+   */
+  subscribe (topics) {
+    throw errcode('subscribe must be implemented by the subclass', 'ERR_NOT_IMPLEMENTED')
+  }
+
+  /**
+   * Unsubscribe from the given topic(s).
+   * @abstract
+   * @param {Array<string>|string} topics
+   * @returns {undefined}
+   */
+  unsubscribe (topics) {
+    throw errcode('unsubscribe must be implemented by the subclass', 'ERR_NOT_IMPLEMENTED')
+  }
+
   /**
    * Mounts the pubsub protocol onto the libp2p node and sends our
    * subscriptions to every peer conneceted

test/pubsub.js

@@ -17,6 +17,18 @@ class PubsubImplementation extends PubsubBaseProtocol {
     super('libp2p:pubsub', 'libp2p:pubsub-implementation', libp2p)
   }
 
+  publish (topics, messages) {
+    // ...
+  }
+
+  subscribe (topics) {
+    // ...
+  }
+
+  unsubscribe (topics) {
+    // ...
+  }
+
   _processConnection (idB58Str, conn, peer) {
     // ...
   }