cross-tab-worker-databus 0.1.1 → 0.2.0

package/docs/transports.md

@@ -0,0 +1,144 @@
+# Transport Backends
+
+> [中文](./zh/transports.md) | English
+
+The core package (`cross-tab-worker-databus`) is transport-agnostic. It defines a
+`DataBusTransport` contract; the built-in Centrifuge backend is one implementation
+of that contract, exposed as the optional `./centrifuge` subpath. This document
+describes the contract and how to wire up a third-party backend (native WebSocket,
+socket.io, SSE, etc.).
+
+## The `DataBusTransport` contract
+
+Every backend implements five methods. `subscribe` / `unsubscribe` MUST be
+idempotent — the DataBus may call them repeatedly and replays them on reconnect.
+
+```ts
+interface DataBusTransport<TConfig = unknown, TData = unknown> {
+  start(config: TConfig, handlers: DataBusTransportHandlers<TData>): MaybePromise<void>;
+  subscribe(topic: string): MaybePromise<void>;
+  unsubscribe(topic: string): MaybePromise<void>;
+  publish(topic: string, data: unknown): MaybePromise<void>;
+  stop(): MaybePromise<void>;
+}
+
+interface DataBusTransportHandlers<TData = unknown> {
+  onMessage: (message: DataBusMessage<TData>) => void;
+  onStatus: (status: WorkerStatus) => void;   // 'connecting' | 'connected' | 'disconnected' | 'error'
+  onError: (error: unknown) => void;
+}
+```
+
+`start()` receives the user-supplied connection config (untyped `TConfig` — the
+backend owns its shape) and the three callbacks. Call `onStatus` whenever the
+connection state changes; call `onMessage` for each inbound publication; call
+`onError` for non-fatal errors (the DataBus applies a recovery cooldown so a
+flapping connection does not retry-loop).
+
+## Architectural layers
+
+```
+CrossTabDataBus  ──►  DataBusTransport (your backend)
+                          │
+                  ┌───────┴────────┐
+                  │ Worker protocol │   (your backend's main-thread ↔ worker messages)
+                  └───────┬────────┘
+                          │
+                     Session layer   (the actual client: WebSocket / centrifuge / …)
+                          │
+                        Server
+```
+
+The DataBus layer handles cross-tab coordination (BroadcastChannel control
+plane, localStorage routes, owner selection, failover, page lifecycle). Your
+transport only owns the I/O path: connect, subscribe, publish, disconnect.
+
+## Implementing a backend
+
+### 1. Define your Worker protocol
+
+Mirror the Centrifuge backend's `centrifuge-protocol.ts`: a discriminated union
+of messages the main thread sends to the Worker (`INIT` / `SUBSCRIBE` /
+`UNSUBSCRIBE` / `PUBLISH` / `STOP`) and a union the Worker posts back
+(`STATUS` / `MESSAGE` / `ERROR`). Keep it structured-cloneable (no functions,
+no class instances — `Error` must be serialised).
+
+### 2. Implement the session
+
+A session class owns one connection and lives inside the Worker (or, as a
+fallback, on the main thread). It receives protocol messages via a `handle()`
+method and posts outputs back through a sink. See
+[`centrifuge-session.ts`](../src/centrifuge-session.ts) for the reference shape:
+
+- `handle(message)` dispatches by `message.type`.
+- `subscribe(topic)` is idempotent — re-subscribing an existing topic is a no-op.
+- `unsubscribe(topic)` removes listeners before disconnecting, to avoid a late
+  event resurrecting a re-subscribed topic.
+- `stop()` disconnects, clears all subscriptions, and emits `disconnected`.
+
+### 3. Implement the transport
+
+The transport selects a backend (SharedWorker / Dedicated Worker / local),
+posts protocol messages to it, and routes Worker outputs back to the
+`DataBusTransportHandlers`. See [`centrifuge.ts`](../src/centrifuge.ts) for the
+reference shape, including:
+
+- **Backend selection**: reuse `selectWorkerBackend` from `worker-mode.ts` so
+  your backend degrades consistently with the rest of the SDK.
+- **Generation guard**: bump a monotonic counter when a backend is created;
+  error handlers check it so late errors from a superseded Worker cannot
+  corrupt the fresh session.
+- **SharedWorker heartbeat**: if you use a SharedWorker, send periodic PINGs
+  so a `PortReaper` can reclaim dead-tab sessions.
+
+### 4. Expose as a subpath
+
+Add `exports` entries in `package.json` (one per entry point — the main bundle,
+the dedicated worker, the shared worker):
+
+```json
+{
+  "exports": {
+    "./your-backend": {
+      "types": "./dist/your-backend.d.ts",
+      "import": "./dist/your-backend.js"
+    },
+    "./your-backend.worker": "./dist/your-backend.worker.js",
+    "./your-backend.shared.worker": "./dist/your-backend.shared.worker.js"
+  }
+}
+```
+
+This keeps the core package zero-dependency: users who do not import
+`./your-backend` never pull your client library into their bundle.
+
+### 5. Register the peer dependency
+
+Declare your client library as an optional peer dependency so consumers
+opt in:
+
+```json
+{
+  "peerDependencies": { "your-client-lib": "^x.y.z" },
+  "peerDependenciesMeta": { "your-client-lib": { "optional": true } }
+}
+```
+
+## Factory entry point
+
+Provide a `create<Backend>DataBus(options)` factory that wires the transport
+into a `CrossTabDataBus`, mirroring `createCentrifugeDataBus`. This is the
+surface most consumers use; it should accept the connection config, cluster
+key (defaulting to the connection URL), and forward trace / worker-mode
+options to the DataBus.
+
+## What the transport does NOT own
+
+- **Cross-tab routing**: the `WorkerClusterRuntime` decides which tab owns a
+  topic. Your transport just subscribes when told.
+- **Reconnect replay**: the DataBus replays the current owner's topics on
+  reconnect; your transport's `subscribe` must be safe to call again.
+- **Publication fan-out**: the owner broadcasts publications over
+  BroadcastChannel; your transport only receives and reports them.
+- **Page lifecycle**: the DataBus suspends/resumes the transport on
+  `pagehide` / `pageshow`; your transport's `stop()` must be clean.

package/docs/zh/architecture.md

@@ -10,23 +10,33 @@ graph TB
     subgraph TabA["Tab A"]
       AppA["业务模块"] --> BusA["CrossTabDataBus"]
       BusA --> RuntimeA["WorkerClusterRuntime"]
-      BusA --> WorkerA["Dedicated / Shared Worker A"]
+      BusA --> TransportA["CentrifugeWorkerTransport"]
+      TransportA --> WorkerA["Dedicated / Shared Worker A"]
     end
     subgraph TabB["Tab B"]
       AppB["业务模块"] --> BusB["CrossTabDataBus"]
       BusB --> RuntimeB["WorkerClusterRuntime"]
-      BusB --> WorkerB["Dedicated / Shared Worker B"]
+      BusB --> TransportB["CentrifugeWorkerTransport"]
+      TransportB --> WorkerB["Dedicated / Shared Worker B"]
     end
   end
 
   RuntimeA <--> Channel["BroadcastChannel 控制面"]
   RuntimeB <--> Channel
-  RuntimeA <--> Registry["localStorage Worker 注册表"]
-  RuntimeB <--> Registry
-  RuntimeA <--> Routes["localStorage Topic 路由表"]
-  RuntimeB <--> Routes
-  WorkerA --> Server["Centrifuge / 实时服务器"]
-  WorkerB --> Server
+  RuntimeA --> BatchA["BatchingStorageWriter"]
+  RuntimeB --> BatchB["BatchingStorageWriter"]
+  BatchA <--> Registry["localStorage Worker 注册表"]
+  BatchB <--> Registry
+  BatchA <--> Routes["localStorage Topic 路由表"]
+  BatchB <--> Routes
+  WorkerA --> SessionA["CentrifugeSession"]
+  WorkerB --> SessionB["CentrifugeSession"]
+  SessionA --> Server["Centrifuge / 实时服务器"]
+  SessionB --> Server
+  subgraph SW["SharedWorker 进程（backend = shared 时）"]
+    Reaper["PortReaper"] -.-> SessionA
+    Reaper -.-> SessionB
+  end
 ```
 
 默认 `workerMode: 'dedicated'` 时，每个 Tab 使用独立的 transport Worker。配置为 `shared` 或 `auto` 且浏览器支持 SharedWorker 时，同源 Tab 复用同一个 SharedWorker；SharedWorker 内每个连接 port 各自维护独立的 `CentrifugeSession`，一个 Tab 刷新或停止不会影响其他 Tab。`auto` 模式按 **SharedWorker → Dedicated Worker → 主线程 WebSocket** 降级，`dedicated` 模式按 **Dedicated Worker → SharedWorker → 主线程 WebSocket** 降级。`BroadcastChannel` 只负责控制消息和实时 publication 转发；localStorage 只负责最终一致的协调元数据。
@@ -377,6 +387,8 @@ sequenceDiagram
 4. owner 通过 BroadcastChannel 广播 `EVENT/DATABUS_PUBLICATION`；自身 Tab 也有本地订阅时直接分发一次。BroadcastChannel 从不把消息回传给发送者，因此不会重复分发。
 5. 其余每个 Tab 收到 `EVENT` 后，仅当自己持有该 Topic 的 `subscriber:{topicKey}:{tabId}` 记录时才调用本地 handler；没有本地订阅的 Tab 直接丢弃。
 
+在 transport 层，Centrifuge 客户端可能同时在 `client` 对象和对应 `Subscription` 对象上触发同一 publication。为避免把同一条服务器 publication 分发两次，CentrifugeSession 的 client 级 `publication` 监听只处理**没有客户端订阅**的 topic（即服务端订阅）；已有活跃订阅的 topic 仅由 subscription 级监听派发。
+
 ```mermaid
 sequenceDiagram
   participant Pub as 发布方 Tab A

package/docs/zh/configuration.md

@@ -132,6 +132,8 @@ const bus = createCentrifugeDataBus({
 - **会话超时**：`3 × heartbeatIntervalMs`（默认 `30000` ms）。超过超时未收到消息的端口会被回收：其会话停止，WebSocket 关闭。这与 Core 集群心跳（默认 `3000` ms，通过 localStorage 跟踪 worker 存活）相互独立——见下方说明。
 - **自适应频率**：回收器以所有活动端口中最小的心跳间隔运行，使短心跳端口的会话能被及时回收。当最后一个端口断开时，回收器定时器清除，避免长时间存在的 SharedWorker 在连接爆发间隙运行永久的空循环。
 - **先关闭端口再停止会话**：回收端口时，先关闭端口，再停止会话。关闭端口会丢弃会话的 `disconnected` 状态通知（使其不会到达可能仍在运行但缓慢的主线程），并保证已关闭的端口永远无法传递后续消息，从而在回收器追踪之外复活僵尸会话。
+- **失败隔离**：回收与 `dispose()` 都用 try-catch 包裹 `target.close()`/`target.stop()`，单个异常端口不会中断本轮回收，也不会让后续死 Tab 无人回收。
+- **关闭清理**：SharedWorker 关闭时，`PortReaper.dispose()` 停止定时器并关闭/停止**所有**仍被追踪的会话，确保没有任何 `CentrifugeSession` 或 WebSocket 比 reaper 活得更久。这补充了按端口回收——后者只覆盖 reaper 运行期间静默的端口。
 
 这是从崩溃（未发送 `STOP`）的 Tab 中恢复会话的机制。降低 `heartbeatIntervalMs` 可更快回收死会话，代价是端口上更频繁的 PING 消息。
 

package/docs/zh/transports.md

@@ -0,0 +1,132 @@
+# Transport 后端
+
+> 中文 | [English](../transports.md)
+
+核心包（`cross-tab-worker-databus`）与 transport 无关。它定义了一个
+`DataBusTransport` 契约；内置的 Centrifuge 后端是该契约的一个实现，作为可选的
+`./centrifuge` subpath 暴露。本文档描述该契约以及如何接入第三方后端（原生
+WebSocket、socket.io、SSE 等）。
+
+## `DataBusTransport` 契约
+
+每个后端实现 5 个方法。`subscribe` / `unsubscribe` 必须幂等——DataBus 可能重复
+调用，并在重连时回放。
+
+```ts
+interface DataBusTransport<TConfig = unknown, TData = unknown> {
+  start(config: TConfig, handlers: DataBusTransportHandlers<TData>): MaybePromise<void>;
+  subscribe(topic: string): MaybePromise<void>;
+  unsubscribe(topic: string): MaybePromise<void>;
+  publish(topic: string, data: unknown): MaybePromise<void>;
+  stop(): MaybePromise<void>;
+}
+
+interface DataBusTransportHandlers<TData = unknown> {
+  onMessage: (message: DataBusMessage<TData>) => void;
+  onStatus: (status: WorkerStatus) => void;   // 'connecting' | 'connected' | 'disconnected' | 'error'
+  onError: (error: unknown) => void;
+}
+```
+
+`start()` 接收用户提供的连接配置（无类型 `TConfig`——后端自行定义其形状）和
+三个回调。连接状态变化时调 `onStatus`；收到 publication 时调 `onMessage`；
+非致命错误调 `onError`（DataBus 有恢复冷却窗口，避免抖动连接死循环重试）。
+
+## 架构分层
+
+```
+CrossTabDataBus  ──►  DataBusTransport（你的后端）
+                          │
+                  ┌───────┴────────┐
+                  │ Worker 协议     │   （你的后端的主线程 ↔ worker 消息）
+                  └───────┬────────┘
+                          │
+                     Session 层    （真正的客户端：WebSocket / centrifuge / …）
+                          │
+                        服务端
+```
+
+DataBus 层负责跨 Tab 协调（BroadcastChannel 控制面、localStorage 路由、owner 选举、
+故障转移、页面生命周期）。你的 transport 只负责 I/O 路径：连接、订阅、发布、断开。
+
+## 实现一个后端
+
+### 1. 定义你的 Worker 协议
+
+参照 Centrifuge 后端的 `centrifuge-protocol.ts`：一个主线程发给 Worker 的
+判别联合（`INIT` / `SUBSCRIBE` / `UNSUBSCRIBE` / `PUBLISH` / `STOP`）和一个
+Worker 回传的联合（`STATUS` / `MESSAGE` / `ERROR`）。保持结构化克隆安全
+（无函数、无类实例——`Error` 必须序列化）。
+
+### 2. 实现 session
+
+一个 session 类持有一个连接，运行在 Worker 内（或作为降级运行在主线程）。
+它通过 `handle()` 方法接收协议消息，通过 sink 回传输出。参见
+[`centrifuge-session.ts`](../../src/centrifuge-session.ts) 的参考形状：
+
+- `handle(message)` 按 `message.type` 分派。
+- `subscribe(topic)` 幂等——对已存在 topic 重复订阅是 no-op。
+- `unsubscribe(topic)` 先移除监听器再断开，避免迟到事件复活已重订阅的 topic。
+- `stop()` 断开、清理所有订阅、emit `disconnected`。
+
+### 3. 实现 transport
+
+transport 选择后端（SharedWorker / Dedicated Worker / 本地），向它发送协议
+消息，并把 Worker 输出路由回 `DataBusTransportHandlers`。参见
+[`centrifuge.ts`](../../src/centrifuge.ts) 的参考形状，包括：
+
+- **后端选举**：复用 `worker-mode.ts` 的 `selectWorkerBackend`，使你的后端与
+  SDK 其余部分降级行为一致。
+- **generation 守卫**：创建后端时递增单调计数器；错误处理检查它，使被取代的
+  Worker 的迟到错误不会污染新 session。
+- **SharedWorker 心跳**：若用 SharedWorker，定期发 PING，让 `PortReaper` 能
+  回收死 tab 的 session。
+
+### 4. 作为 subpath 暴露
+
+在 `package.json` 加 `exports` 条目（每个入口一个——主 bundle、dedicated worker、
+shared worker）：
+
+```json
+{
+  "exports": {
+    "./your-backend": {
+      "types": "./dist/your-backend.d.ts",
+      "import": "./dist/your-backend.js"
+    },
+    "./your-backend.worker": "./dist/your-backend.worker.js",
+    "./your-backend.shared.worker": "./dist/your-backend.shared.worker.js"
+  }
+}
+```
+
+这保持核心包零依赖：不导入 `./your-backend` 的用户不会把你的客户端库打进 bundle。
+
+### 5. 声明 peer 依赖
+
+将你的客户端库声明为可选 peer 依赖，让消费者自行选择：
+
+```json
+{
+  "peerDependencies": { "your-client-lib": "^x.y.z" },
+  "peerDependenciesMeta": { "your-client-lib": { "optional": true } }
+}
+```
+
+## 工厂入口
+
+提供一个 `create<Backend>DataBus(options)` 工厂，把 transport 接入
+`CrossTabDataBus`，与 `createCentrifugeDataBus` 对称。这是大多数消费者使用的
+界面；它应接受连接配置、cluster key（默认为连接 URL），并把 trace /
+worker-mode 选项转发给 DataBus。
+
+## transport 不负责的事
+
+- **跨 Tab 路由**：`WorkerClusterRuntime` 决定哪个 tab 拥有 topic。你的 transport
+  只在被通知时订阅。
+- **重连回放**：DataBus 在重连时回放当前 owner 的 topic；你的 transport 的
+  `subscribe` 必须可安全重复调用。
+- **publication 扇出**：owner 通过 BroadcastChannel 广播 publication；你的
+  transport 只接收并上报。
+- **页面生命周期**：DataBus 在 `pagehide` / `pageshow` 时挂起/恢复 transport；
+  你的 transport 的 `stop()` 必须干净。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cross-tab-worker-databus",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Framework-agnostic cross-tab data bus with Dedicated/Shared Worker clustering and Centrifuge support.",
   "type": "module",
   "license": "MIT",
@@ -54,9 +54,14 @@
     "test:e2e": "pnpm build && playwright test",
     "typecheck": "tsc --noEmit"
   },
-  "dependencies": {
+  "peerDependencies": {
     "centrifuge": "^5.5.3"
   },
+  "peerDependenciesMeta": {
+    "centrifuge": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@playwright/test": "^1.62.1",
     "@types/node": "^24.0.0",