Truffle Dashboard 消息总线通用类型包 @truffle/dashboard-message-bus-common 详解

原创2026-09-21 16:44:001,326 阅读
文章标签:区块链开发工具Web3

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 有三种终止方式:

  1. 收到对应响应:await messageLifecycle.response 会一直等待与发布消息 id 匹配的 Response(这是实现请求/响应式 JSON-RPC 代理的基础);
  2. 使消息失效:调用 await messageLifecycle.invalidate(),向消费方传达"消息不再有效";
  3. 放弃消息:调用 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 类型。如果需要扩展,官方给出的步骤十分明确:

  1. 在 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;
  2. 在 lib/index.ts 中导出新类型(export * from "./messages" 已覆盖,若新增独立文件需在此补充导出)。
  3. 在使用方包中同步加入支持:例如 @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 生态中最稳定的公共接口。

登录后查看全文
truffle