Truffle Dashboard 消息总线通用类型包 @truffle/dashboard-message-bus-common 详解
Truffle Dashboard 消息总线通用类型包 @truffle/dashboard-message-bus-common 详解
导读
@truffle/dashboard-message-bus-common 是 Truffle Dashboard 消息总线体系中的通用类型与工具包,它本身不包含任何网络逻辑,而是为 @truffle/dashboard-message-bus(消息总线服务端)与 @truffle/dashboard-message-bus-client(消息总线客户端)之间提供共享的消息类型定义、类型守卫函数和序列化工具。如果你正在为 Truffle Dashboard 开发集成(例如自定义的 RPC 代理、事件订阅或日志转发),本文将从安装、消息类型体系、底层实现原理到如何新增消息类型,为你提供一份完整的实战指南。读完本文,你将掌握 Dashboard 消息总线上所有内建消息的字段结构与语义,并能够在此基础上定义自己的消息类型。
注意:这是一个中间件包,官方明确标注"只应在为 Truffle Dashboard 开发集成时使用",普通终端用户无需直接安装它,因为它总是被其他包(如
@truffle/dashboard)间接依赖。
包的角色定位:消息总线的"通用契约层"
在 Truffle Dashboard 的通信架构中,消息总线由两个 WebSocket 服务器构成:一个供**发布者(publisher)连接并发送请求,另一个供订阅者(subscriber,即 Dashboard)**连接并接收请求。发布者的请求会被广播给所有订阅者,但只有第一个响应会回传给发布者;当新订阅者接入时,所有"未完成(unfulfilled)"的请求也会补发给它(见 DashboardMessageBus.ts)。
在这个架构里,@truffle/dashboard-message-bus-common 扮演的是契约层角色:消息在总线上传输时统一采用 base64 编码的 JSON 文本,而所有消息的结构定义、类型常量和判断函数都集中在这一个包中,供服务端与客户端两侧共同引用,避免两处各自定义导致的不一致。其职责清晰体现在 lib/index.ts 的导出结构中:
export * from "./messages";
export * from "./utils";
export interface PortsConfig {
dashboardPort: number;
subscribePort: number;
publishPort: number;
}
PortsConfig 是包内唯一直接定义的接口,它描述了 Dashboard 实例的三个关键端口(Dashboard 本身、订阅服务器、发布服务器),该结构被 DashboardServer.ts 中的 /ports 接口原样返回,客户端拿到后即可据此连接消息总线。
安装
如果你在构建一个需要与 Dashboard 或消息总线交互的包,可以从 NPM 安装此包:
npm install @truffle/dashboard-message-bus-common
或使用 Yarn:
yarn add @truffle/dashboard-message-bus-common
从 package.json 可以看到该包发布为 main: "dist/index.js"、types: "dist/index.d.ts",仅发布 dist 目录,构建脚本为 tsc(yarn build)。它的 Node 引擎要求为 ^16.20 || ^18.16 || >=20,TypeScript 编译目标为 es2016、模块系统为 commonjs(见 tsconfig.json),并开启 declaration: true 以便生成 .d.ts 类型声明,供 TypeScript 消费者直接获得完整的类型提示。
核心消息类型体系
该包定义了两套基础接口,是所有消息的"根类型":
// lib/messages.ts
export interface Message {
id: number; // 消息唯一标识,用于关联请求与响应
type?: string; // 消息类型字符串,可选(用于未分类消息)
payload: any; // 消息携带的数据
}
export interface Response {
id: number; // 对应原始请求的 id
payload: any; // 响应数据
}
在此基础上,包内定义了四种内建消息类型,每种类型都有类型常量(TypeScript 字面量类型 + 运行时字符串值)和对应的类型守卫函数。消息类型常量采用"双声明"模式:export type LogMessageType = "log" 供编译期使用,export const logMessageType = "log" 供运行期比较,二者结合既保证了类型安全又避免了魔法字符串散落各处。
1. provider —— Dashboard Provider 的 RPC 转发消息
这是消息总线中最重要的消息类型,用于向 Dashboard 实例的注入式 provider 发送 RPC 请求(例如转发给 MetaMask 等钱包处理):
export interface DashboardProviderMessage extends Message {
type: DashboardProviderMessageType; // "provider"
payload: {
jsonrpc: "2.0"; // 固定为 JSON-RPC 2.0 版本号
method: string; // 要调用的 RPC 方法名
params: any[]; // 方法参数数组
id: number; // RPC 请求 ID
};
}
在 DashboardServer.ts 的 postRpc 方法中可以看到它的实际消费方式:Dashboard 的 HTTP /rpc 端点将收到的请求体直接作为 payload 发布为 dashboardProviderMessageType 消息,然后等待生命周期中的 response 并把响应体回传:
this.client
.publish({ type: dashboardProviderMessageType, payload: req.body })
.then(lifecycle => lifecycle.response)
.then(response => res.json(response?.payload))
.catch(next);
2. invalidate —— 使较早消息失效
invalidate 消息用于通知接收方某条较早发布的消息已经失效,其 payload 就是要失效消息的 id:
export interface InvalidateMessage extends Message {
type: InvalidateMessageType; // "invalidate"
payload: number; // 被失效消息的 ID
}
这是一个内部消息类型,不面向普通发布者/订阅者使用。从 DashboardMessageBus.ts 的 invalidateMessage 方法可以看到,消息总线在把第一个响应回传给发布者后,会自动构造一条 invalidate 消息广播给所有订阅者(broadcastAndDisregard,即不等待响应),让订阅者知道该请求已经完成、可以释放对应资源。
3. log —— 跨线路的日志消息
log 消息用于在消息总线两端传递日志,其 payload 包含 debug 命名空间与消息内容。这同样属于内部消息类型:
export interface LogMessage extends Message {
type: LogMessageType; // "log"
payload: {
namespace: string; // debug 命名空间,如 "dashboard-message-bus:requests"
message: any; // 任意日志内容
};
}
总线在 DashboardMessageBus.ts 的 logTo 方法中统一以 "dashboard-message-bus" 为根命名空间,可附加 :requests、:responses、:connections、:errors 等子命名空间,构造 log 消息并广播给指定接收方。Dashboard 侧则在 setupVerboseLogging 中订阅 logMessageType 消息,将其交给 debug 模块输出(见 DashboardServer.ts)。
4. debug 与 cli-event —— 另两种扩展消息
除 README 提到的三种外,源码还额外定义了两种消息(这也是"从源码结构看"该包不断演进的证据,见 lib/messages.ts):
debug:DebugMessage,payload 为{ message: string },注释标明用于在 Dashboard 浏览器控制台输出日志;cli-event:CliEventMessage<T>,payload 为{ label: string; data: T },用于向订阅者广播 Truffle CLI 事件数据,label用于标识事件数据类型。
类型守卫函数
为了在运行时安全地区分消息类型,包内为每种消息提供了一组类型谓词函数,例如:
export const isDashboardProviderMessage = (
message: Message
): message is DashboardProviderMessage => {
return message.type === dashboardProviderMessageType;
};
isCliEventMessage、isLogMessage、isDebugMessage、isInvalidateMessage 同理。这些函数配合 TypeScript 的 is 谓词语法,可以在 if 分支内自动收窄消息类型,让订阅端代码既安全又简洁。
消息的序列化工具与创建工具
消息在 WebSocket 线路上传输时并非原始 JSON,而是统一编码为 base64 字符串。该包在 lib/utils.ts 中提供了对应的转换工具:
// 将任意 JS 对象/值转为 base64 表示的 JSON 字符串
export const jsonToBase64 = (json: any) => {
const stringifiedJson = JSON.stringify(json);
const buffer = Buffer.from(stringifiedJson);
return buffer.toString("base64");
};
// 将 base64 表示的 JSON 字符串还原为 JS 对象
// 注意:这是 jsonToBase64 的逆向操作,不保证兼容其他 base64 格式
export const base64ToJson = (base64: string) => {
const buffer = Buffer.from(base64, "base64");
const stringifiedJson = buffer.toString("utf8");
return JSON.parse(stringifiedJson);
};
在消息总线的实际处理流程中(见 DashboardMessageBus.ts 的 processRequest),发布者发来的原始数据会先转为字符串,再经 base64ToJson 还原为消息对象广播给订阅者;收到第一个响应后,再用 jsonToBase64 编码回发给发布者。同时 unfulfilledRequests 缓存中保存的也是 base64 字符串,这与客户端发布时调用的编码方式严格一致。
此外,包内还提供了 createMessage 工厂函数,用于生成带随机 id 的消息:
export const createMessage = <M extends Message>(
type: M["type"],
payload: M["payload"]
): Message => {
const id = Math.random();
return { id, type, payload };
};
id 采用 Math.random() 生成的随机浮点数,其唯一性由总线与客户端两侧共同维护——总线靠它关联请求与响应、客户端靠它匹配 Response.id 与原始请求。
客户端如何使用这些类型
消息总线的消费者通常在 @truffle/dashboard-message-bus-client 中工作,而本包的 Message 类型正是客户端的公共接口基础(client/lib/types.ts 中直接 import { Message } from "@truffle/dashboard-message-bus-common")。
发布一条消息并获取其生命周期:
import { DashboardMessageBusClient } from "@truffle/dashboard-message-bus-client";
const client = new DashboardMessageBusClient({ port, host });
const message = {
type: "helloWorld",
id: new Date().getTime(),
payload: { hello: "world" }
};
const messageLifecycle = await client.publish(message);
publish 返回的 PublishedMessageLifecycle 有三种终止方式:
- 收到对应响应:
await messageLifecycle.response会一直等待与发布消息 id 匹配的Response(这是实现请求/响应式 JSON-RPC 代理的基础); - 使消息失效:调用
await messageLifecycle.invalidate(),向消费方传达"消息不再有效"; - 放弃消息:调用
await messageLifecycle.abandon()。注意:对于 fire-and-forget 类消息(如事件数据),如果不调用abandon(),进程会永远挂起等待永远不会到来的响应,导致无法正常退出。
消费消息则通过 subscribe:
const subscription = client.subscribe({ type: "helloWorld" });
subscription.on("message", async receivedMessageLifecycle => {
// 读取消息 payload 并作出响应
await receivedMessageLifecycle.respond({
someArbitraryResponse: "Why hello there."
});
});
不传 type 时订阅所有消息;收到消息后通过 respond 回传与请求 id 对应的响应。
如何新增消息类型
当前内建消息类型很少,绝大多数集成场景只需 provider 类型。如果需要扩展,官方给出的步骤十分明确:
- 在
lib/messages.ts中定义新消息的接口。建议同时遵循包内既有模式:- 定义字面量类型与常量,如
export type MyMessageType = "my-message"; export const myMessageType = "my-message"; - 让新接口继承
Message,并将type收窄为对应的字面量类型; - 定义清晰的
payload结构(最好带 JSDoc 注释说明消息语义); - 添加对应的类型守卫函数,例如
export const isMyMessage = (message: Message): message is MyMessage => message.type === myMessageType;
- 定义字面量类型与常量,如
- 在
lib/index.ts中导出新类型(export * from "./messages"已覆盖,若新增独立文件需在此补充导出)。 - 在使用方包中同步加入支持:例如
@truffle/dashboard(消息总线的启动方兼主要订阅方)与@truffle/dashboard-message-bus-client需要相应处理新消息的发布与消费逻辑。正如 dashboard-message-bus/README.md 所指出的,新增消息类型需要各消费包协同支持,本包只是"契约的登记处"。
完成定义后,通过 yarn build(即 tsc)编译,新消息类型就会随 dist 目录发布,供所有消费者以类型安全的方式使用。
总结
@truffle/dashboard-message-bus-common 是理解 Truffle Dashboard 通信机制的关键入口:它以极小的代码量(messages.ts + utils.ts + index.ts 三个文件)定义了总线上的全部消息契约、base64 编解码工具与消息创建工厂。无论是排查 Dashboard RPC 代理链路、实现自定义消息协议,还是为 Dashboard 开发新的集成包,都建议从这个包的源码开始——它是连接消息总线服务端与客户端两侧的最短路径,也是整个 Dashboard 生态中最稳定的公共接口。