深入解析 `@truffle/dashboard-message-bus`:Truffle Dashboard 消息总线架构与使用指南
深入解析 @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) └──────────────────────────────────────┘
具体流程拆解如下:
- 发布者(publisher)连接
publishServer,发送请求消息; - 消息总线将请求广播给当前所有已连接的订阅者;
- 订阅者处理请求后,向消息总线发送一条带对应请求 ID 的响应消息;
- 多个订阅者可以同时收到同一个请求,但只有第一个到达的响应会被返回给发布者;
- 当新的订阅者接入时,所有尚未被满足(unfulfilled)的请求会被重新发送给它;
- 生命周期规则:只要还存在至少一个发布者或订阅者在线,消息总线就持续运行;当最后一个连接断开时,消息总线自动关闭。
源码佐证:请求处理主流程
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 给出的扩展路径非常明确(这也是「添加新消息类型」的标准步骤):
- 在
@truffle/dashboard-message-bus-common的lib/messages.ts中定义新消息类型的接口(并按其惯例补充对应的type常量与类型守卫函数); - 由于消息格式由该公共包定义并导出,任何消费方(如
@truffle/dashboard)都可以直接导入; - 在所有消费该消息格式的包(如
@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):跟踪已发布消息的responsePromise,并提供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 通信体系的关键一环,其设计可以提炼为以下要点:
- 双服务器模型:publish 与 subscribe 两个独立 WebSocket 服务器解耦了「请求入口」与「请求出口」;
- 广播 + 首响应胜出:请求发给所有订阅者,但只有第一个响应回传给发布者,配合
"invalidate"消息避免重复响应; - 未完成请求重放:新订阅者接入时自动补发 backlog,保证请求不因订阅者晚到而丢失;
- 自管理生命周期:只要有任一连接就存活,最后一个连接断开即自动
terminate(); - base64 消息约定:所有消息经
jsonToBase64/base64ToJson编码,按id匹配请求与响应; - 类型可扩展:消息类型集中在
@truffle/dashboard-message-bus-common的 messages.ts,新增类型只需在该文件定义接口,并在消费方(如@truffle/dashboard)补充支持。
对绝大多数 Truffle 用户而言,这个包完全透明——它被 @truffle/dashboard 在底层自动启动与关闭;只有当你准备开发与 Dashboard 对接的新包、需要复用其消息约定或扩展消息类型时,才需要直接依赖它。届时,本文所梳理的架构、API 与源码路径将是你快速入门的完整地图。