libp2p-message-handler

A message handler for Libp2p. This package makes it easy to create a protocol on Libp2p by converting the streams into a discrete messaging system.

Table of Contents

• Install
• Usage
• API
  • createMessageHandler
  • MessageHandler
    • start
    • stop
    • isStarted
    • send
    • broadcast
    • handle
    • unhandle
• Logging
• Tests
• To-Do

Install

npm i @organicdesign/libp2p-message-handler

Usage

import { createMessageHandler } from "@organicdesign/libp2p-message-handler";

const handler = createMessageHandler(options)(libp2p);

await handler.start();

handler.handle((message, peer) => {
	// Handler an incomming message.
});

// Send a message to a peer (will throw if not connected).
await handler.send(message, peer);

// Stop the synchronizer.
await handler.stop();

API

createMessageHandler

createMessageHandler([options])(libp2p);

• options <Object> An optional object with the following properties:
  • protocol <String> A string which specifies the name of the protocol. Default: "/message-handler/0.0.1".
• libp2p <Libp2p> The libp2p instance.
• Returns: <MessageHandler> The message handler instance.

Creates a Libp2p message handler.

MessageHandler

new MessageHandler(libp2p, [options]);

• options <Object> An optional object with the following properties:
  • protocol <String> A string which specifies the name of the protocol. Default: "/message-handler/0.0.1".
• libp2p <Libp2p> The libp2p instance.

The MessageHandler class. It is not recommended to instanciate it directly but rather use the createMessageHandler function.

start

messageHandler.start();

• Returns: <Promise>

Start the message handler, resolves when it has finished starting.

stop

messageHandler.stop();

• Returns: <Promise>

Stop the message handler, resolves when it has finished stopping.

isStarted

messageHandler.isStarted();

• Returns: <boolean>

Check if the message handler is started.

send

messageHandler.send(message, peer);

• message <Uint8Array> The message to send.
• peer <PeerId> The peer ID of the peer to send the message to.
• Returns: <Promise>

Send a message to a connected peer. Resolves when the message is sent. Rejects if it fails to send the message.

broadcast

messageHandler.broadcast(message);

• message <Uint8Array> The message to send.
• Returns: <Promise> Resolves to a list of <PromiseSettledResult>s.

Send a message to all connected peers. Resolves when the message has been sent or has failed to be sent to all pairs. This method only sends the message to connected pairs, if you are wanting to send a message to the entire network you should use a pubsub module instead.

handle

messageHandler.handle(handlerFunc);

• handlerFunc <(Uint8Array, PeerId) => void> The handler function to call with the received message and the sender's peer ID.

Handle incomming messages from other peers.

unhandle

messageHandler.unhandle(handlerFunc);

• handlerFunc <(Uint8Array, PeerId) => void> The handler function which was previously handled.

Stop handling messages with this handler function.

Logging

The logger has the following namespaces:

• libp2p:message-handler - Logs general actions like starting, stopping and opening streams.
• libp2p:message-handler:messages - Logs when it sends or receives messages.

To enable logging in nodejs add the following environment variable (by prefixing the start command):

DEBUG=libp2p:message-handler*

Or in the browser:

localStorage.setItem("debug", "libp2p:message-handler*");

Tests

To run the test suite:

npm run test

To-Do

• [x] Add tests.
• [x] Add logging.