@truffle/dashboard-message-bus-client

@truffle/dashboard-message-bus-client

This library is used for connecting with the message bus that powers the Truffle dashboard.

Usage

Connecting to the message bus and producing a message

import { DashboardMessageBusClient } from "@truffle/dashboard-message-bus-client";

const client = new DashboardMessageBusClient({ port, host });

const message = {
  type: "helloWorld",
  id: new DateTime().getTime(),
  payload: {
    hello: "world"
  }
};

const messageLifecycle = await client.publish(message);

The lifecycle of published messages

Publishing a message creates a lifecycle for that message. The lifecycle is tracked by the publisher as an object of type PublishedMessageLifecycle<MessageType, ResponseType>.

Publish message lifecycles terminate in one of three ways:

1. Receipt of a corresponding response message
2. Invalidation of the message
3. Abandonment of the message

Waiting for a response to a message

To enable request/response messaging (e.g. proxied JSON-RPC messages), publish lifecycles contain a promise that resolves when a response to the originally published message is received.

const response = await publishLifecycle.response;

Abandoning messages

To allow for fire-and-forget messages (e.g. event data), simply call the abandon method on the lifecycle object.

Important: If the abandon method of the publish lifecycle is not called, the process will hang forever on exit, as it will forever be waiting for a response that will never arive.

await messageLifecycle.abandon();

Invalidating messages (aka message cancellation)

The consumer of a published message often will need to perform some longer running operation as a result of that message. To cancel that work, or to communicate to the consumer that the message is no longer valid, simply call cancel on the publish lifecycle.

await messageLifecycle.invalidate();

Consuming and responding to messages

Messages can be consumed by calling the subscribe method of the client. The subscribe method returns a DashboardMessageSubscription object. This object emits message events whenever messages are received that match the subscription's filter.

Received messages are wrapped up in a lifecycle object similar to the one used for publishing messages, however there's only a single respond method.

import { DashboardMessageBusClient } from "@truffle/dashboard-message-bus-client";

const client = new DashboardMessageBusClient({ port, host });

// omitting the type string in the options object will return a subscription
// for all messages
const subscription = client.subscribe({
  type: "helloWorld"
});

subscription.on("message", receivedMessageLifecycle => {
  const helloTarget = receivedMessageLifecycle.message.payload.hello;

  if (helloTarget.toLowerCase() === "world") {
    // respond by passing your response payload directly to the response
    await receivedMessageLifecycle.respond({
      someArbitraryResponse:
        "Why hello there. Pleased to make your acquaintance"
    });
  } else {
    await receivedMessageLifecycle.respond({
      error: `I'm sorry, you have the wrong number. This is world, not "${helloTarget}"`
    });
  }
});