{"bugs":{"url":"https://github.com/libp2p/js-libp2p/issues"},"dist":{"shasum":"fc3197cc4be9050191959141f57aecd7ec794a4b","tarball":"https://registry.npmjs.org/@libp2p/interface-pubsub/-/interface-pubsub-4.0.1-ab0e3980.tgz","fileCount":9,"integrity":"sha512-MblMC1pi71QuE8xXB70FCLAstmyo5y87pQ8iS3K5qppPdurHHMbdDIDzNjiqm77VVqYWFAxRlU187UuCjWTKBQ==","signatures":[{"sig":"MEUCIQDuiL9ptDzl5u05N+QaqlK3XMUQjhFaPzuRdop5YSPN3gIgYAcxl2qipoPAnC09kdoVmbp5BchIwFxb5nHXpibFrOE=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":34405},"name":"@libp2p/interface-pubsub","type":"module","types":"./dist/src/index.d.ts","readme":"# @libp2p/interface-pubsub <!-- omit in toc -->\n\n[![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)\n[![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)\n[![codecov](https://img.shields.io/codecov/c/github/libp2p/js-libp2p.svg?style=flat-square)](https://codecov.io/gh/libp2p/js-libp2p)\n[![CI](https://img.shields.io/github/actions/workflow/status/libp2p/js-libp2p/main.yml?branch=master\\&style=flat-square)](https://github.com/libp2p/js-libp2p/actions/workflows/main.yml?query=branch%3Amaster)\n\n> PubSub interface for libp2p\n\n## Table of contents <!-- omit in toc -->\n\n- - [Install](#install)\n- [Table of Contents <!-- omit in toc -->](#table-of-contents----omit-in-toc---)\n  - [Implementations using this interface](#implementations-using-this-interface)\n  - [Interface usage](#interface-usage)\n    - [Extend interface](#extend-interface)\n    - [Example](#example)\n  - [API](#api)\n    - [Constructor](#constructor)\n      - [`new Pubsub({options})`](#new-pubsuboptions)\n        - [Parameters](#parameters)\n    - [Start](#start)\n      - [`pubsub.start()`](#pubsubstart)\n    - [Stop](#stop)\n      - [`pubsub.stop()`](#pubsubstop)\n    - [Publish](#publish)\n      - [`pubsub.publish(topic, message)`](#pubsubpublishtopic-message)\n        - [Parameters](#parameters-1)\n        - [Returns](#returns)\n    - [Subscribe](#subscribe)\n      - [`pubsub.subscribe(topic)`](#pubsubsubscribetopic)\n        - [Parameters](#parameters-2)\n    - [Unsubscribe](#unsubscribe)\n      - [`pubsub.unsubscribe(topic)`](#pubsubunsubscribetopic)\n        - [Parameters](#parameters-3)\n    - [Get Topics](#get-topics)\n      - [`pubsub.getTopics()`](#pubsubgettopics)\n        - [Returns](#returns-1)\n    - [Get Peers Subscribed to a topic](#get-peers-subscribed-to-a-topic)\n      - [`pubsub.getSubscribers(topic)`](#pubsubgetsubscriberstopic)\n        - [Parameters](#parameters-4)\n        - [Returns](#returns-2)\n    - [Validate](#validate)\n      - [`pubsub.validate(message)`](#pubsubvalidatemessage)\n        - [Parameters](#parameters-5)\n      - [Returns](#returns-3)\n  - [Test suite usage](#test-suite-usage)\n  - [API Docs](#api-docs)\n  - [License](#license)\n  - [Contribution](#contribution)\n\n## Install\n\n```console\n$ npm i @libp2p/interface-pubsub\n```\n\nThe `interface-pubsub` contains the base implementation for a libp2p pubsub router implementation. This interface should be used to implement a pubsub router compatible with libp2p. It includes a test suite that pubsub routers should run, in order to ensure compatibility with libp2p.\n\n# Table of Contents <!-- omit in toc -->\n\n- [Implementations using this interface](#implementations-using-this-interface)\n- [Interface usage](#interface-usage)\n  - [Extend interface](#extend-interface)\n  - [Example](#example)\n- [API](#api)\n  - [Constructor](#constructor)\n    - [`new Pubsub({options})`](#new-pubsuboptions)\n      - [Parameters](#parameters)\n  - [Start](#start)\n    - [`pubsub.start()`](#pubsubstart)\n  - [Stop](#stop)\n    - [`pubsub.stop()`](#pubsubstop)\n  - [Publish](#publish)\n    - [`pubsub.publish(topic, message)`](#pubsubpublishtopic-message)\n      - [Parameters](#parameters-1)\n      - [Returns](#returns)\n  - [Subscribe](#subscribe)\n    - [`pubsub.subscribe(topic)`](#pubsubsubscribetopic)\n      - [Parameters](#parameters-2)\n  - [Unsubscribe](#unsubscribe)\n    - [`pubsub.unsubscribe(topic)`](#pubsubunsubscribetopic)\n      - [Parameters](#parameters-3)\n  - [Get Topics](#get-topics)\n    - [`pubsub.getTopics()`](#pubsubgettopics)\n      - [Returns](#returns-1)\n  - [Get Peers Subscribed to a topic](#get-peers-subscribed-to-a-topic)\n    - [`pubsub.getSubscribers(topic)`](#pubsubgetsubscriberstopic)\n      - [Parameters](#parameters-4)\n      - [Returns](#returns-2)\n  - [Validate](#validate)\n    - [`pubsub.validate(message)`](#pubsubvalidatemessage)\n      - [Parameters](#parameters-5)\n    - [Returns](#returns-3)\n- [Test suite usage](#test-suite-usage)\n- [License](#license)\n  - [Contribution](#contribution)\n\n## Implementations using this interface\n\nYou can check the following implementations as examples for building your own pubsub router.\n\n- [libp2p/js-libp2p-floodsub](https://github.com/libp2p/js-libp2p-floodsub)\n- [ChainSafe/js-libp2p-gossipsub](https://github.com/ChainSafe/js-libp2p-gossipsub)\n\n## Interface usage\n\n`interface-pubsub` abstracts the implementation protocol registration within `libp2p` and takes care of all the protocol connections and streams, as well as the subscription management and the features describe in the libp2p [pubsub specs](https://github.com/libp2p/specs/tree/master/pubsub). This way, a pubsub implementation can focus on its message routing algorithm, instead of also needing to create the setup for it.\n\n### Extend interface\n\nA pubsub router implementation should start by extending the `interface-pubsub` class and **MUST** override the `_publish` function, according to the router algorithms. This function is responsible for forwarding publish messages to other peers, as well as forwarding received messages if the router provides the `canRelayMessage` option to the base implementation.\n\nOther functions, such as `start`, `stop`, `subscribe`, `unsubscribe`, `_encodeRpc`, `_decodeRpc`, `_processRpcMessage`, `_addPeer` and `_removePeer` may be overwritten if the pubsub implementation needs to customize their logic. Implementations overriding these functions **MUST** call `super`.\n\nThe `start` and `stop` functions are responsible for the registration of the pubsub protocol with libp2p. The `stop` function also guarantees that the open streams in the protocol are properly closed.\n\nThe `subscribe` and `unsubscribe` functions take care of the subscription management and its inherent message propagation.\n\nWhen using a custom protobuf definition for message marshalling, you should override `_encodeRpc` and `_decodeRpc` to use the new protobuf instead of the default one.\n\n`_processRpcMessage` is responsible for handling messages received from other peers. This should be extended if further operations/validations are needed by the router.\n\nThe `_addPeer` and `_removePeer` functions are called when new peers running the pubsub router protocol establish a connection with the peer. They are used for tracking the open streams between the peers.\n\nAll the remaining functions **MUST NOT** be overwritten.\n\n### Example\n\nThe following example aims to show how to create your pubsub implementation extending this base protocol. The pubsub implementation will handle the subscriptions logic.\n\n```JavaScript\nconst Pubsub = require('libp2p-interfaces/src/pubsub')\n\nclass PubsubImplementation extends Pubsub {\n  constructor({ libp2p, options })\n    super({\n      debugName: 'libp2p:pubsub',\n      multicodecs: '/pubsub-implementation/1.0.0',\n      libp2p,\n      globalSigningPolicy: options.globalSigningPolicy\n    })\n  }\n\n  _publish (message) {\n    // Required to be implemented by the subclass\n    // Routing logic for the message\n  }\n}\n```\n\n## API\n\nThe interface aims to specify a common interface that all pubsub router implementation should follow. A pubsub router implementation should extend the [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter). When peers receive pubsub messages, these messages will be emitted by the event emitter where the `eventName` will be the `topic` associated with the message.\n\n### Constructor\n\nThe base class constructor configures the pubsub instance for use with a libp2p instance. It includes settings for logging, signature policies, etc.\n\n#### `new Pubsub({options})`\n\n##### Parameters\n\n| Name                          | Type                             | Description                                     | Default              |\n| ----------------------------- | -------------------------------- | ----------------------------------------------- | -------------------- |\n| options.libp2p                | `Libp2p`                         | libp2p instance                                 | required, no default |\n| options.debugName             | `string`                         | log namespace                                   | required, no default |\n| options.multicodecs           | `string \\| Array<string>`        | protocol identifier(s)                          | required, no default |\n| options.globalSignaturePolicy | `'StrictSign' \\| 'StrictNoSign'` | signature policy to be globally applied         | `'StrictSign'`       |\n| options.canRelayMessage       | `boolean`                        | if can relay messages if not subscribed         | `false`              |\n| options.emitSelf              | `boolean`                        | if `publish` should emit to self, if subscribed | `false`              |\n\n### Start\n\nStarts 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`.\n\n#### `pubsub.start()`\n\n### Stop\n\nStops 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.\n\n#### `pubsub.stop()`\n\n### Publish\n\nPublish data message to pubsub topics.\n\n#### `pubsub.publish(topic, message)`\n\n##### Parameters\n\n| Name    | Type         | Description        |\n| ------- | ------------ | ------------------ |\n| topic   | `string`     | pubsub topic       |\n| message | `Uint8Array` | message to publish |\n\n##### Returns\n\n| Type            | Description                                           |\n| --------------- | ----------------------------------------------------- |\n| `Promise<void>` | resolves once the message is published to the network |\n\n### Subscribe\n\nSubscribe to the given topic.\n\n#### `pubsub.subscribe(topic)`\n\n##### Parameters\n\n| Name  | Type     | Description  |\n| ----- | -------- | ------------ |\n| topic | `string` | pubsub topic |\n\n### Unsubscribe\n\nUnsubscribe from the given topic.\n\n#### `pubsub.unsubscribe(topic)`\n\n##### Parameters\n\n| Name  | Type     | Description  |\n| ----- | -------- | ------------ |\n| topic | `string` | pubsub topic |\n\n### Get Topics\n\nGet the list of topics which the peer is subscribed to.\n\n#### `pubsub.getTopics()`\n\n##### Returns\n\n| Type            | Description                |\n| --------------- | -------------------------- |\n| `Array<String>` | Array of subscribed topics |\n\n### Get Peers Subscribed to a topic\n\nGet a list of the [PeerId](https://github.com/libp2p/js-peer-id) strings that are subscribed to one topic.\n\n#### `pubsub.getSubscribers(topic)`\n\n##### Parameters\n\n| Name  | Type     | Description  |\n| ----- | -------- | ------------ |\n| topic | `string` | pubsub topic |\n\n##### Returns\n\n| Type            | Description               |\n| --------------- | ------------------------- |\n| `Array<string>` | Array of base-58 PeerId's |\n\n### Validate\n\nValidates a message according to the signature policy and topic-specific validation function.\n\n#### `pubsub.validate(message)`\n\n##### Parameters\n\n| Name    | Type      | Description      |\n| ------- | --------- | ---------------- |\n| message | `Message` | a pubsub message |\n\n#### Returns\n\n| Type            | Description                      |\n| --------------- | -------------------------------- |\n| `Promise<void>` | resolves if the message is valid |\n\n## Test suite usage\n\n```js\n'use strict'\n\nconst tests = require('libp2p-interfaces-compliance-tests/pubsub')\nconst YourPubsubRouter = require('../src')\n\ndescribe('compliance', () => {\n  let peers\n  let pubsubNodes = []\n\n  tests({\n    async setup (number = 1, options = {}) {\n      // Create number pubsub nodes with libp2p\n      peers = await createPeers({ number })\n\n      peers.forEach((peer) => {\n        const ps = new YourPubsubRouter(peer, options)\n\n        pubsubNodes.push(ps)\n      })\n\n      return pubsubNodes\n    },\n    async teardown () {\n      // Clean up any resources created by setup()\n      await Promise.all(pubsubNodes.map(ps => ps.stop()))\n      peers.length && await Promise.all(peers.map(peer => peer.stop()))\n    }\n  })\n})\n```\n\n## API Docs\n\n- <https://libp2p.github.io/js-libp2p/modules/_libp2p_interface_pubsub.html>\n\n## License\n\nLicensed under either of\n\n- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)\n- MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)\n\n## Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.\n","exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"}},"gitHead":"ab0e3980160dcbacf00825cfc4c6ba1d0c07a20c","license":"Apache-2.0 OR MIT","scripts":{"lint":"aegir lint","build":"aegir build","clean":"aegir clean","dep-check":"aegir dep-check"},"typedoc":{"entryPoint":"./src/index.ts"},"_npmUser":{"name":"npm-service-account-libp2p","email":"npm-service-account+libp2p@protocol.ai"},"homepage":"https://github.com/libp2p/js-libp2p/tree/master/packages/interface-pubsub#readme","keywords":["interface","libp2p"],"repository":{"url":"git+https://github.com/libp2p/js-libp2p.git","type":"git"},"_npmVersion":"8.19.4","description":"PubSub interface for libp2p","directories":{},"maintainers":[{"name":"jacobheun","email":"jacobheun@gmail.com"},{"name":"npm-service-account-libp2p","email":"npm-service-account+libp2p@protocol.ai"},{"name":"alanshaw","email":"alan138@gmail.com"},{"name":"vascosantos","email":"santos.vasco10@gmail.com"},{"name":"achingbrain","email":"alex@achingbrain.net"},{"name":"daviddias","email":"mail@daviddias.me"}],"_nodeVersion":"18.16.0","dependencies":{"it-pushable":"^3.1.3","uint8arraylist":"^2.4.3","@libp2p/interfaces":"3.3.2-ab0e3980","@libp2p/interface-peer-id":"2.0.2-ab0e3980","@libp2p/interface-connection":"5.1.1-ab0e3980"},"eslintConfig":{"extends":"ipfs","parserOptions":{"sourceType":"module"}},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"aegir":"^39.0.10"},"_npmOperationalInternal":{"tmp":"tmp/interface-pubsub_4.0.1-ab0e3980_1687168990678_0.6877783442622956","host":"s3://npm-registry-packages"},"_id":"@libp2p/interface-pubsub@4.0.1-ab0e3980","version":"4.0.1-ab0e3980"}