@mzzsfy/dsh-common-tools
v0.5.1
Published
全家桶公共依赖库:按插件空间隔离的 WebSocket 双向订阅/推送与 toast;host setupCommonTools 借消费插件生命周期激活,client 复用页面单连接;普通 npm 依赖而非 dsh 插件
Readme
@mzzsfy/dsh-common-tools
公共依赖库,提供插件独立消息通道与 toast。普通 npm 包,不是 DSH 插件。host 与 client 都通过当前插件的 ctx 建立通道,插件名自动来自 loader 的 ctx.fiber.entry.options.name,使用完整 npm 包名。共享模块的 require 不携带调用者身份,必须在 apply(ctx) 中初始化。
双接口
两端 API 相同,消息就是业务 payload:
const bus = setupCommonTools(ctx)
const stop = bus.subscribe(message => handleMessage(message))
bus.publish({ type: 'refresh' })host:
import { setupCommonTools } from '@mzzsfy/dsh-common-tools/host'
export const inject = ['webServer']
export function apply(ctx) {
const bus = setupCommonTools(ctx)
bus.subscribe(message => handleCommand(message))
bus.publish({ changed: true })
}client:
window.__ModuleLoader__.load({
id: '@mzzsfy/example', // 与 host 的包名一致
factory(require) {
const { setupCommonTools, createSnapshotRefresh, toast } = require('@mzzsfy/dsh-common-tools/client')
return {
apply(ctx) {
const bus = setupCommonTools(ctx)
const controller = new AbortController()
const snapshot = createSnapshotRefresh(async () => {
const res = await fetch('/api/example/snapshot', { signal: controller.signal })
const data = await res.json()
if (!controller.signal.aborted) console.log(data)
})
bus.subscribe(snapshot.refresh, { onReset: snapshot.refresh })
ctx.effect(() => () => { snapshot.dispose(); controller.abort() })
ctx.effect(() => {
const button = document.createElement('button')
button.textContent = '刷新'
button.onclick = () => {
try { bus.publish({ type: 'refresh' }) }
catch (error) { toast.show(error.message, { kind: 'error' }) }
}
document.body.appendChild(button)
return () => button.remove()
})
},
}
},
})示例中的快照路由与 host 命令处理由消费插件实现;示例按钮展示发送与卸载接线,实际插件可换成已注册面板。消费方仍需声明依赖与 external,见下文装载说明。
| 方法 | 行为 |
|---|---|
| subscribe(listener) | 接收对端本插件消息,listener(payload),返回幂等退订函数 |
| publish(payload = null) | 向对端本插件发送 JSON 消息,上行不自动广播回来 |
| client subscribe(listener, { onReset }) | 可选恢复回调,接收订阅确认后对账,首连/重连均触发 |
| host onPresence(listener) | 接收本插件的浏览器连接数;注册立即回调,变化时回调,返回退订函数 |
插件本身就是通道,没有 topic 和消息版本。不同插件不能通过本门面指定别人的空间;同插件多实例共享空间。业务需要区分消息时直接使用 payload 中的业务字段。回调同步抛错或异步拒绝均告警隔离。
生命周期
client 初始化取得插件实例的连接使用权;纯发送插件不需要制造接收订阅。组件提前退订仅停止接收,不影响发送。插件卸载自动清理自己的全部订阅和使用权,最后一个实例卸载才关闭页面共享 WS、取消重连。host 同样按实例清理,最后一个 host 使用方退出删除路由、连接和心跳。
presence 只统计有接收订阅的连接,纯发送实例不计在场。对已就绪空间新增订阅时,onReset 在 subscribe 返回前同步执行。尚未确认的订阅不接收业务消息,遗漏由随后的快照对账恢复。
连接与边界
页面全部插件共享 WS /api/bus/ws;HTTPS 自动使用 WSS,不占 HTTP/1.1 普通请求连接池。首连/重连完成接收确认后调用 onReset 拉业务快照,不做事件重放。总线逐条交付 payload,不合并业务消息。五个快照消费方在宿主合并失效广播、在客户端单飞刷新,持续变更下同一刷新器的起始间隔至少一秒;首次立即,窗口内变更在末尾补拉。cron 的偏好与看板共用 status 请求。
断开后指数退避加抖动重连,上限 30 秒,握手确认超时 10 秒。服务端每 30 秒 ping,未回复的连接终止。单帧及发送积压上限 1 MiB,按完整 JSON 协议消息 UTF-8 字节计算;非法 JSON payload 或超界发送同步拒绝,慢接收方积压超界断开。publish 交给本地 WS 即返回,不表示业务处理完成;断线不排队、不自动重发。
快照消费方可独立使用 host 导出的 createChangeNotifier(() => bus.publish()) 与 client 导出的 createSnapshotRefresh(loadSnapshot)。两者返回 { refresh, dispose },与实例生命周期一起释放。前者仅合并失效通知;后者保证单飞及末尾补拉,失败不会自行形成重试循环,调用方仍负责请求超时和迟到响应检查。调度采用正常系统时钟下的一秒窗口,空闲时无定时轮询。
内部协议
| 方向 | 帧 |
|---|---|
| client → host | { "type": "hello", "protocol": 1, "version": "<包版本>" } |
| host → client | { "type": "hello", "protocol": 1, "protocols": [1], "version": "<包版本>" } |
| client → host | { "type": "subscribe", "plugins": ["@mzzsfy/dsh-tunnel"], "revision": 1 } |
| host → client | { "type": "ready", "plugins": ["@mzzsfy/dsh-tunnel"], "revision": 1 } |
| client → host | { "type": "publish", "plugin": "@mzzsfy/dsh-tunnel", "payload": {} } |
| host → client | { "type": "message", "plugin": "@mzzsfy/dsh-tunnel", "payload": {} } |
订阅帧替换接收空间清单,与发送资格无关。revision 仅协调接收确认,不是业务消息版本。非法帧或二进制上行关闭连接;明确跨源上行写入被拒绝,身份认证及可达性由宿主承担,不设插件认证层。
host 的 WS 实现多实体以进程级注册表共享传输,同版不重复安装,较新版本接管传输并保留监听;已有 WS 门面动态转发。upgrade 不经宿主 /api prefix 闸门(responder 只按 exact pathname 分发),交付 socket 前自行回问一次 connection.requestRejection,非空即写状态码并断 socket;connection 服务缺失时放行,与插件 HTTP 路由同口径。缺少 registerUpgrade 时告警并停用总线,不注册资源。loader 上下文缺少包名时明确拒绝,不猜测身份。0.2.0 移除旧 SSE、topic、forPlugin 和 version 接口,无兼容路径。升级须统一更新消费方与依赖,完整重启宿主并刷新旧页面;旧代际 SSE(包 0.1)与 WS 代际(注册版本:0.2-0.3 写死 1.0,0.4.0 起与包版本同锁)同进程混装会发生注册表冲突,不支持跨该代际热接管。
兼容窗口与版本协商
当前窗口 0.5.x:帧集合、导出形状与 setupCommonTools 门面语义在 0.5.x 内保持向后兼容,只允许发 patch。0.6.0 视为破坏性版本(0.x 语义里 minor 即破坏),必须与十个消费方的依赖范围抬升同批发布——npm 的 ^0.5.0 只约束安装,装载行按包名取 profile 顶层那份,单独发 0.6.0 会被 hoist 给仍在 ^0.5.0 的旧插件。窗口与红线见 DEVELOPMENT/client-dependency.md。
0.4.x → 0.5.0 的实际增量:client 新增导出 Tooltip 与 tipPlacement(见「悬浮提示」),host 侧 WS upgrade 补一次宿主闸门回问;既有帧集合、门面与 toast 语义未变。
版本协商:client 连接首帧上报 { type: 'hello', protocol: 1, version },host 回 { type: 'hello', protocol, protocols: [1], version }。协议无交集时 client 打印一条告警并关闭连接、不再重连(页级总线停用);旧 host(0.3.x 及以前)把未知帧当非法帧直接关连接,client 在 hello 宽限窗内被关即判定为老帧模式,降级为不报版本重连一次,连接从未 open 就断开不触发降级。帧协议改动即递增 PROTOCOL;host 侧 PKG_VERSION 与包版本同锁(仓库测试守)。
装载与 Toast
client 模块由每个消费插件自带的装载行进入宿主:消费方在自己的 cordis.patch.yml 里加一行 id: <本包前缀>-dsh-common-tools、name: '@mzzsfy/dsh-common-tools'。宿主按包名把多行合并成一份 client 模块(entriesByName + compose),bundle 只拼一次、模块只注册一次,多行在宿主侧是多个空 apply() 条目;本包不 host 别人的行,也不依赖别人 host 自己的行——装任一消费插件即可独立运行。消费方声明 dependencies(范围 ^0.5.0)与 external @mzzsfy/dsh-common-tools/client,factory 内 require 后经命名空间使用;该包须能从 profile 根解析,生产 profile 为 pnpm nodeLinker: hoisted。装载规约见 DEVELOPMENT/client-dependency.md。toast 不要求建立 bus:
const { toast } = require('@mzzsfy/dsh-common-tools/client')
toast.show('已归档', { kind: 'ok' })
toast.show('任务完成\n耗时 12 秒', { appearance: 'panel', holdMs: 6000 })自 0.3.0 起,appearance 支持 toast(默认,宿主 toast-bg/toast-label 色对)与 panel(宿主 bg-layer-1/label-primary 色对)。两种样式随宿主亮暗主题更新,成功/错误只强调边框,不覆盖底色或文案颜色;多行文本保留换行。未知值使用 toast,设置仅作用于本条通知。kind 支持 info/ok/error,sticky: true 常驻并显示“知道了”,onClick 点击直达,holdMs 指定自动消失时间(默认 4 秒)。
悬浮提示
client 侧通用悬浮提示(0.5.0 起),消费方只给锚点与内容:
const { Tooltip } = require('@mzzsfy/dsh-common-tools/client')
h(Tooltip, { anchor }, content)anchor两种形态:指针{ kind: 'point', x, y }(悬停时给,组件在mousemove上跟随)与元素矩形{ left, top, width, height }(快照,页面滚动后自动收起)。panelSelector可选:给定时以该面板矩形为夹取边界,提示不飘出弹窗;缺省用视口。- 定位:上下越界换侧,两侧都放不下取空间大的一侧再夹取进边界;元素锚点画箭头,指针锚点不画。
- 渲染:portal 到
body,样式类dct-tip*随 toast 样式表注入(首次使用前经 layout effect 注入,不依赖是否发过 toast);宿主模块表缺 react-dom 主入口时降级就地渲染,提示仍可见。 tipPlacement一并导出(纯函数:(anchor, tipSize, bounds, options)→{ left, top, side, arrowX }),供消费方在不挂组件时复用同一套定位规则。
测试
在本包目录执行:
npm install --omit=peer
node --test "test/*.test.mjs"覆盖范围见兼容性测试。
