深入解析 `@truffle/dashboard-message-bus`:Truffle Dashboard 消息总线架构与使用指南

原创2026-09-21 21:23:271,402 阅读
文章标签:区块链开发工具Web3

深入解析 @truffle/dashboard-message-bus:Truffle Dashboard 消息总线架构与使用指南

导读

@truffle/dashboard-message-bus 是 Truffle 生态中连接 Truffle Dashboard 与其余 Truffle 组件的中间件包,通过一对专门的代理 WebSocket 服务器,实现发布者(publisher)与订阅者(subscriber,即 Dashboard)之间的请求—响应通信。本文以该包的官方 README 为主线,结合仓库内 DashboardMessageBus.ts、utils.ts 等源码与端到端测试,完整讲解其安装方式、核心 API、双服务器架构、消息编解码、连接生命周期、消息类型扩展机制,以及它如何被 @truffle/dashboard 自动启动并投入使用。读完本文,你将理解 Dashboard 与 Truffle 各组件(如注入式 web3 provider)之间的通信原理,并掌握为 Dashboard 开发集成时所需要的最小依赖与调用方式。

注意:这是一个中间件(middleware)包。文档明确警告:它只应在为 Truffle Dashboard 开发集成时使用,终端用户不应也不需要直接安装它——它在底层被其他包自动使用。全文以此为前提展开。

包定位:它是谁,为谁服务

@truffle/dashboard-message-bus 管理 Truffle Dashboard 与任何其他 Truffle 组件之间的通信,其载体是一个专用的代理 RPC 服务器实例(specialized proxy RPC server instance)。

在 Truffle 的多包(monorepo)结构中,它位于整个 Dashboard 通信链路的中枢位置:

  • 上游:@truffle/dashboard-message-bus-common 提供所有共享的消息类型定义与编解码工具(Message、Response、jsonToBase64、base64ToJson 等),本包直接依赖它(见 package.json 中 dependencies 的 @truffle/dashboard-message-bus-common: ^0.1.7)。
  • 下游:@truffle/dashboard(DashboardServer.ts)负责启动 Dashboard 的同时自动启动消息总线;@truffle/dashboard-message-bus-client 则提供连接消息总线、发布消息与订阅消息的客户端封装。
  • 检验:@truffle/dashboard-message-bus-e2e-test 中的 DashboardMessageBus.test.ts 以真实端口跑通了完整的「发布—订阅—响应」链路。

用一句话概括:本包是 Dashboard 通信的服务器端枢纽,客户端侧与类型定义则分别由 dashboard-message-bus-client 与 dashboard-message-bus-common 承担。

安装

由于它通常被其他包在底层依赖,README 明确建议:只有当你正在构建一个需要与 Dashboard 或消息总线交互的包时,才需要安装它。

# npm
npm install @truffle/dashboard-message-bus

# 或 yarn
yarn add @truffle/dashboard-message-bus

从 package.json 可以看到它的运行环境约束与关键依赖:

  • Node.js 版本要求:"node": "^16.20 || ^18.16 || >=20";
  • 核心依赖:isomorphic-ws(跨环境 WebSocket)、ws、promise.any(用于「取第一个响应」的竞速逻辑)、delay、@truffle/dashboard-message-bus-common;
  • "browser": { "ws": false }:表明该包面向 Node 环境为主,浏览器构建时禁用 ws。

快速使用:启动一个消息总线

README 给出的核心用法非常简洁:实例化 DashboardMessageBus,然后调用其 start() 方法。

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

const messageBus = new DashboardMessageBus(
  publishPort,    // 发布者(publisher)连接的 WebSocket 端口
  subscribePort,  // 订阅者(subscriber)连接的 WebSocket 端口
  "localhost"     // host,可选,默认 localhost
);

await messageBus.start();

构造函数签名(见 DashboardMessageBus.ts):

constructor(
  public publishPort: number,
  public subscribePort: number,
  public host: string = "localhost"
)

README 特别强调:直接启动消息总线几乎总是与启动新 Dashboard 绑定在一起,因此你通常不需要手动做这件事。正确做法是启动 Dashboard,它会自动启动对应的消息总线——这一点在后文「与 Dashboard 的集成」一节中会看到源码证据。

除 start() 外,DashboardMessageBus 还暴露两个生命周期相关成员:

  • ready:一个 Promise,当消息总线准备好处理请求(即至少有一个订阅者在线)时 resolve;
  • terminate():关闭两个 WebSocket 服务器,并触发 "terminate" 事件。

该实例还继承了 EventEmitter,外部可以通过监听 "terminate" 事件感知消息总线的退出(DashboardServer 正是利用这一点联动关闭整个服务)。

架构:两个 WebSocket 服务器,一进一出

消息总线的工作机制(README「Architecture」一节)可以用一句话概括:运行两个相互独立的 WebSocket 服务器——一个给发布者连接并发请求,另一个给订阅者(Dashboard)连接并接收请求。

                    ┌──────────────────────────────────────┐
                    │          DashboardMessageBus          │
  publishers ─────► │  publishServer(publishPort)         │
  (truffle组件等)    │       接收请求,转发给订阅者           │
                    │                                      │
                    │  subscribeServer(subscribePort)    │
  subscribers ◄──── │       下发请求、收集响应               │
  (dashboard)       └──────────────────────────────────────┘

具体流程拆解如下:

  1. 发布者(publisher)连接 publishServer,发送请求消息;
  2. 消息总线将请求广播给当前所有已连接的订阅者;
  3. 订阅者处理请求后,向消息总线发送一条带对应请求 ID 的响应消息;
  4. 多个订阅者可以同时收到同一个请求,但只有第一个到达的响应会被返回给发布者;
  5. 当新的订阅者接入时,所有尚未被满足(unfulfilled)的请求会被重新发送给它;
  6. 生命周期规则:只要还存在至少一个发布者或订阅者在线,消息总线就持续运行;当最后一个连接断开时,消息总线自动关闭。

源码佐证:请求处理主流程

processRequest(DashboardMessageBus.ts)是实现上述第 2~4 步的核心私有方法:

private async processRequest(publisher, data, subscribers) {
  // 统一为字符串,WebSocket.Data 可能是 Buffer 等其他形式
  if (typeof data !== "string") data = data.toString();

  await this.ready;  // 至少一个订阅者才继续

  this.unfulfilledRequests.set(data, { publisher, data });
  const message = base64ToJson(data);

  try {
    // 广播给所有订阅者,并等待第一个响应
    const response = await broadcastAndAwaitFirst(subscribers, message);

    // 将响应以 base64 编码发回发布者
    const encodedResponse = jsonToBase64(response);
    publisher.send(encodedResponse);
    this.unfulfilledRequests.delete(data);

    this.invalidateMessage(message.id);  // 通知其余订阅者:请求已满足,勿再响应
  } catch (error) {
    // 记录错误日志(log 消息)
  }
}

其中「等待第一个响应」的实现位于 utils.ts,它借助 promise.any 对所有订阅者连接同时发起 sendAndAwait 并竞速:

export const broadcastAndAwaitFirst = async (sockets, message) => {
  const promises = sockets.map(socket => sendAndAwait(socket, message));
  const result = await Promise.any(promises);
  return result;
};

而 sendAndAwait(同文件 utils.ts)的关键是按消息 ID 匹配响应——只有 response.id === message.id 的响应才会 resolve,同时监听 error 与 close 事件以便失败时 reject。这正是 README 所说「订阅者通过发送带请求 ID 的响应来应答」的代码级印证。

源码佐证:未完成请求的重放

addSubscriber(DashboardMessageBus.ts)实现了 README 中的第 5 步——新订阅者接入时补发 backlog:

private addSubscriber(newSubscriber: WebSocket) {
  // 把所有未满足的请求单独转发给这个新订阅者
  this.unfulfilledRequests.forEach(({ publisher, data }) =>
    this.processRequest(publisher, data, [newSubscriber])
  );
  this.subscribers.push(newSubscriber);
  if (this.subscribers.length == 1) this.resolveReadyPromise();
}

同时注意 start() 中的细节:订阅者必须先发送一条消息("ready")才会被正式加入订阅者列表(newSubscriber.once("message", () => this.addSubscriber(newSubscriber))),这保证了 ready Promise 只有在真实可用的订阅者上线后才 resolve。

源码佐证:自动关闭

removeSubscriber 与 removePublisher 都会调用 terminateIfNoConnections()(DashboardMessageBus.ts):

private terminateIfNoConnections() {
  if (this.publishers.length === 0 && this.subscribers.length === 0) {
    this.terminate();
  }
}

这正是 README 第 6 步「最后一个连接断开即关闭」的实现。此外,当发布者断开时,其名下所有未满足请求也会被一并清理(clearRequestsForPublisher)。

消息编解码:base64 传输约定

消息总线中所有经过 WebSocket 传输的消息都以 base64 字符串编码,这一约定由 @truffle/dashboard-message-bus-common 提供(utils.ts):

// JSON 对象 → base64 字符串
export const jsonToBase64 = (json: any) => {
  const stringifiedJson = JSON.stringify(json);
  return Buffer.from(stringifiedJson).toString("base64");
};

// base64 字符串 → JSON 对象(jsonToBase64 的逆操作)
export const base64ToJson = (base64: string) => {
  const buffer = Buffer.from(base64, "base64");
  return JSON.parse(buffer.toString("utf8"));
};

创建消息则统一使用 createMessage(同包 utils.ts),它会自动为消息分配随机 ID:

export const createMessage = <M extends Message>(type: M["type"], payload: M["payload"]): Message => {
  const id = Math.random();
  return { id, type, payload };
};

消息与响应的基础结构定义在 messages.ts:

export interface Message {
  id: number;
  type?: string;
  payload: any;
}

export interface Response {
  id: number;
  payload: any;
}

注意一个不对称设计:请求消息带有 type 字段,而响应消息只有 id 与 payload,不含 type。e2e 测试对此有显式断言(DashboardMessageBus.test.ts)。

消息类型:provider、invalidate、log 与更多

README 指出,目前消息类型很少,最重要的是三种:

类型 方向 作用
"provider" 发布者 → Dashboard 将 RPC 请求发送给 @truffle/dashboard,由你的钱包(如 MetaMask)注入的 web3 provider 处理
"invalidate" 消息总线 → 订阅者 使此前某条消息失效(携带被失效消息的 ID)
"log" 消息总线 → 各端 在网络上传输日志消息(内部类型,不供发布者/订阅者直接使用)

这些消息类型均以 TypeScript 接口的形式定义在 @truffle/dashboard-message-bus-common 的 messages.ts 中,并配有类型守卫函数。例如:

// RPC 请求消息:payload 即完整的 JSON-RPC 2.0 请求
export interface DashboardProviderMessage extends Message {
  type: "provider";
  payload: {
    jsonrpc: "2.0";
    method: string;
    params: any[];
    id: number;
  };
}

// 失效消息:payload 是被失效消息的 ID
export interface InvalidateMessage extends Message {
  type: "invalidate";
  payload: number;
}

// 日志消息:payload 携带 debug 命名空间与消息本体
export interface LogMessage extends Message {
  type: "log";
  payload: {
    namespace: string;
    message: any;
  };
}

除上述三种外,同文件中还定义了 "cli-event"(Truffle CLI 事件数据通知)与 "debug"(在 Dashboard 浏览器控制台打印日志)两种类型,以及相应的 isCliEventMessage、isDashboardProviderMessage、isLogMessage、isDebugMessage、isInvalidateMessage 守卫函数。

消息总线的内部消息使用

DashboardMessageBus 内部就大量使用 "log" 与 "invalidate" 消息:

  • logTo(DashboardMessageBus.ts)构造 { namespace: "dashboard-message-bus[:子命名空间]", message } 的 "log" 消息并广播,用于向各端汇报「Subscriber connected」「Sending message to N subscribers」「An error occurred」等运行时事件;
  • invalidateMessage(DashboardMessageBus.ts)在请求被满足后,向所有订阅者广播 "invalidate" 消息,防止它们对已完成的请求重复响应。

如何添加新的消息类型

README 给出的扩展路径非常明确(这也是「添加新消息类型」的标准步骤):

  1. 在 @truffle/dashboard-message-bus-common 的 lib/messages.ts 中定义新消息类型的接口(并按其惯例补充对应的 type 常量与类型守卫函数);
  2. 由于消息格式由该公共包定义并导出,任何消费方(如 @truffle/dashboard)都可以直接导入;
  3. 在所有消费该消息格式的包(如 @truffle/dashboard 本身)中添加对新类型的支持。

详细说明可参考 @truffle/dashboard-message-bus-common README(原文档中给出的外部链接已转换为仓库内相对路径)。

客户端视角:谁在发布,谁在订阅

虽然 @truffle/dashboard-message-bus 只提供服务器端 DashboardMessageBus,但 README 也提到「它导出了一批用于连接与通信的实用工具」。这些工具即 utils.ts 中的 startWebSocketServer、broadcastAndDisregard、broadcastAndAwaitFirst、sendAndAwait。不过更完整的客户端抽象在兄弟包 @truffle/dashboard-message-bus-client 中(client.ts):

const client = new DashboardMessageBusClient({
  host: "localhost",
  subscribePort,  // 订阅连接端口
  publishPort     // 发布连接端口
});

await client.ready();

// 作为发布者发消息
const lifecycle = await client.publish({ type: "provider", payload: rpcRequest });
const response = await lifecycle.response;

// 作为订阅者收消息
const subscription = client.subscribe({ type: "provider" });
subscription.on("message", lifecycle => { /* 处理请求 */ });

客户端默认配置(client.ts)为 host: "localhost"、port: 24012、maxRetries: 1、retryDelayMsec: 100。当未显式指定 subscribePort/publishPort 时,连接层会通过 HTTP 请求 http://<host>:<port>/ports 从 Dashboard 服务器动态获取两个端口(见 connection/index.ts)。

与消息总线的服务器端逻辑一一对应,客户端侧还实现了:

  • PublishMessageLifecycle(publish.ts):跟踪已发布消息的 response Promise,并提供 invalidate()(通知其他订阅者不要再响应)与 abandon()(放弃等待响应但不失效)两个方法;
  • ReceivedMessageLifecycle:订阅者收到的每条消息,可调用其 respond() 返回响应——e2e 测试正是通过它完成应答闭环的。

端到端测试 DashboardMessageBus.test.ts 展示了完整的发布—订阅—响应流程:publisher 发布 { type: "test", payload: "request" },订阅者收到后 respond({ payload: "response" }),发布者侧 publishLifecycle.response 最终拿到 { id, payload: "response" }(且响应不含 type)。该文件同时以 it.todo 标记了待补充的用例:广播到多订阅者、向新订阅者重放未完成请求、发布者断开时清理其未完成请求。

与 Dashboard 的集成:何时自动启动

README 反复强调「启动 Dashboard 时消息总线会被自动启动」。这一说法在 DashboardServer.ts 中有明确的源码证据:

private async startMessageBus() {
  const subscribePort = this.configSubscribePort ?? (await getPort({ host: this.host }));
  const publishPort = this.configPublishPort ?? (await getPort({ host: this.host }));

  const messageBus = new DashboardMessageBus(publishPort, subscribePort, this.host);
  await messageBus.start();
  messageBus.on("terminate", this.boundTerminateListener);  // 消息总线退出 → 关闭 Dashboard
  return messageBus;
}

DashboardServer.start() 首先调用 startMessageBus(),随后再启动 Express 服务;其 HTTP 端点 /ports 对外暴露 { dashboardPort, subscribePort, publishPort }(DashboardServer.ts),供客户端动态发现消息总线端口。

而 postRpc 端点(DashboardServer.ts)则展示了 "provider" 消息类型的真实落地:浏览器端发来的 JSON-RPC 请求被封装为 dashboardProviderMessageType 消息发布到消息总线,等待生命周期响应后原样返回——这正是「RPC 请求经消息总线转发给钱包注入的 web3 provider」这一机制在服务端的接线。

测试策略

README 明确指出:

  • 该包设计上服务于 @truffle/dashboard 包,因此手动测试大多通过 dashboard 包进行;
  • test/ 目录已定义了一些自动化测试,但仍需扩充。

仓库现状与此描述一致:本包目录(packages/dashboard-message-bus)下暂无独立的 test/ 目录,真正的自动化测试位于 e2e 包 DashboardMessageBus.test.ts,它同时实例化 DashboardMessageBus 与 DashboardMessageBusClient 跑真实端口通信,并在 afterEach 中执行 client.close() 与 messageBus.terminate() 做清理。若你想在本地验证,可进入 e2e 包目录按该包 package.json 中定义的脚本运行 Jest 测试。

总结

@truffle/dashboard-message-bus 是理解 Truffle Dashboard 通信体系的关键一环,其设计可以提炼为以下要点:

  1. 双服务器模型:publish 与 subscribe 两个独立 WebSocket 服务器解耦了「请求入口」与「请求出口」;
  2. 广播 + 首响应胜出:请求发给所有订阅者,但只有第一个响应回传给发布者,配合 "invalidate" 消息避免重复响应;
  3. 未完成请求重放:新订阅者接入时自动补发 backlog,保证请求不因订阅者晚到而丢失;
  4. 自管理生命周期:只要有任一连接就存活,最后一个连接断开即自动 terminate();
  5. base64 消息约定:所有消息经 jsonToBase64/base64ToJson 编码,按 id 匹配请求与响应;
  6. 类型可扩展:消息类型集中在 @truffle/dashboard-message-bus-common 的 messages.ts,新增类型只需在该文件定义接口,并在消费方(如 @truffle/dashboard)补充支持。

对绝大多数 Truffle 用户而言,这个包完全透明——它被 @truffle/dashboard 在底层自动启动与关闭;只有当你准备开发与 Dashboard 对接的新包、需要复用其消息约定或扩展消息类型时,才需要直接依赖它。届时,本文所梳理的架构、API 与源码路径将是你快速入门的完整地图。

登录后查看全文
truffle