@cg-devcenter/rtc-fpnn-webjs-sdk 1.0.0-cg.11 → 1.0.0-cg.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -73,6 +73,8 @@ TypeScript 中,省略协议或选择 FPNN 并设置 `legacy-rtm`,会得到 `
73
73
 
74
74
  `close()`、`startAutoReconnect()`、`destroy()` 是客户端生命周期控制,不映射为 TLV 业务 route。`startAutoReconnect()` 由 facade 直接转发给底层客户端;共享模式下由 SharedWorker 客户端转发给 Worker 中的 RTMClient。它不会因 TLV 兼容层缺少业务 route 而被拒绝。
75
75
 
76
+ TLV + `legacy-rtm` 直连模式下,`destroy()` 会关闭连接并释放实例,销毁产生的 `SessionClosed(0)` 不会通知业务。需要观察会话关闭时,调用 `close()` 并等待原有的 `SessionClosed` 通知。
77
+
76
78
  `getUnreadMessage` 保留 `withLogout` 布尔参数,`removeSession` 保留 `localOnly` 布尔参数;两者也兼容旧式的第二位 `timeout` 调用。传入布尔选项后,`timeout` 顺延一位。Callback 和 Promise 入口都遵循该参数顺序。
77
79
 
78
80
  ### 消息发送
@@ -20,9 +20,9 @@ const client = rtm.createClient({
20
20
  });
21
21
  ```
22
22
 
23
- 若业务必须保持每个页面独立连接,可改用 `rtm.createClient({ sharing: false, pid, endpoint: fpnnEndpoint })`;浏览器缺少 SharedWorker 时,`createClient()` 也会自动使用独立连接。若希望新项目显式使用 TLV v1,则设置 `protocol: 'tlv-v1'` 并提供完整 `tlvEndpoint`。
23
+ 若业务必须保持每个页面独立连接,可改用 `rtm.createClient({ sharing: false, pid, endpoint: fpnnEndpoint })`;浏览器缺少 SharedWorker 时,`createClient()` 也会自动使用独立连接。若希望新项目显式使用 TLV v1,则设置 `protocol: 'tlv-v1'` 并提供 `tlvEndpoint`;无路径或仅 `/` 时 SDK 自动补齐 `/service/websocket`,已有路径原样保留。
24
24
 
25
- 迁移到 TLV v1 时,将连接地址换成部署方提供的完整 WebSocket URL,并在创建时选择 TLV:
25
+ 迁移到 TLV v1 时,将连接地址换成部署方提供的 `ws://` 或 `wss://` URL(无路径或仅 `/` 时 SDK 自动补齐 `/service/websocket`,已有路径保持不变),并在创建时选择 TLV:
26
26
 
27
27
  ```js
28
28
  const client = new rtm.RTMClient({
@@ -179,7 +179,7 @@ const independentClient = rtm.createClient({
179
179
 
180
180
  ## 选择 TLV v1 是另一项迁移
181
181
 
182
- 继续使用 FPNN 时不需要更换消息事件名称。改用 TLV v1 时,创建客户端需显式设置 `protocol: 'tlv-v1'` 并提供部署方给出的完整 WebSocket URL。TLV Push 使用 `event.direct`、`event.group`、`event.room`、`event.broadcast` 等名称,字段结构也不同;应使用 `RTMConfig.TLV_SERVER_PUSH` 常量和对应契约处理。
182
+ 继续使用 FPNN 时不需要更换消息事件名称。改用 TLV v1 时,创建客户端需显式设置 `protocol: 'tlv-v1'` 并提供部署方给出的 `ws://` 或 `wss://` URL;无路径或仅 `/` 时 SDK 自动补齐 `/service/websocket`,已有路径原样保留。TLV Push 使用 `event.direct`、`event.group`、`event.room`、`event.broadcast` 等名称,字段结构也不同;应使用 `RTMConfig.TLV_SERVER_PUSH` 常量和对应契约处理。
183
183
 
184
184
  TLV v1 仅支持[支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵)中标出的 API。未支持的 FPNN API 不会自动回退到 FPNN。FPNN 与 TLV 的业务 API、wire method、URI 和字段对照见[协议迁移对照](PROTOCOL_MIGRATION.md)及[TLV 契约](TLV_CONTRACT.md)。
185
185
 
package/docs/TLV.md CHANGED
@@ -8,11 +8,13 @@ TLV v1 使用 MessagePack over WebSocket。公开方法见 [SDK API](USAGE.md)
8
8
  | 项目 | 规则 |
9
9
  | --- | --- |
10
10
  | 协议模式 | `protocol: 'tlv-v1'` |
11
- | 端点 | `tlvEndpoint` 为完整 `ws://` 或 `wss://` URL |
11
+ | 端点 | `tlvEndpoint` 为 `ws://` 或 `wss://` URL;无路径或仅 `/` 时 SDK 自动补齐 `/service/websocket`,已有路径保留且不重复拼接 |
12
12
  | WebSocket | 每个 binary message 恰好一个完整 TLV frame |
13
13
  | 非浏览器运行时 | 提供 `webSocketFactory(url)`;旧 `fpnn` 不可用 |
14
14
  | 鉴权 | `login(uid, credential, callback, timeout)`;仅 `accepted === true` 进入登录态 |
15
15
 
16
+ TLV 地址兼容 `tlv_endpoint`、WebSocket URL 形式的 `endpoint` / `ssl_endpoint`;优先级为 `tlvEndpoint`、`tlv_endpoint`、`endpoint`、`ssl_endpoint`。SDK 选取有效地址并补齐默认路径后,内部只保留 `tlvEndpoint`,避免等价地址别名造成共享 Worker 初始化冲突。调用方传入的配置对象不会被修改;其他连接选项仍须一致。
17
+
16
18
  ## Frame 接口
17
19
 
18
20
  | 字段 | 规则 |
@@ -58,5 +60,5 @@ TLV v1 使用 MessagePack over WebSocket。公开方法见 [SDK API](USAGE.md)
58
60
  | `event.kicked` | `TLV_SERVER_PUSH.kickOut` | 不发送 |
59
61
  | `event.room_removed` | `TLV_SERVER_PUSH.kickOutRoom` | 不发送 |
60
62
 
61
- 可靠 Push 以 `message_ref` 去重;每次重传仍发送 ACK。协议错误、心跳失败或连接关闭会失败当前
62
- pending 请求;SDK 不重放结果未知的修改请求。
63
+ 可靠 Push 以 `message_ref` 去重;每次重传仍发送 ACK。协议错误或心跳失败时,SDK 先报告错误,再发起
64
+ WebSocket 关闭。收到关闭事件,或等待约 2 秒仍无回调时,SDK 结束旧连接上的待处理请求,启用自动重连的 RTM 客户端随后尝试重登。迟到的旧连接关闭事件不会影响新连接。SDK 不重放结果未知的修改请求。
package/docs/USAGE.md CHANGED
@@ -64,7 +64,7 @@ const peerUid = '10002';
64
64
  const client = rtm.createClient({
65
65
  protocol: 'tlv-v1',
66
66
  pid: 12345,
67
- tlvEndpoint: 'wss://<gate-host>/service/websocket',
67
+ tlvEndpoint: 'wss://<gate-host>', // SDK 自动补齐 /service/websocket
68
68
  autoReconnect: true,
69
69
  });
70
70
 
@@ -266,7 +266,7 @@ SharedWorker 仍要求 Worker 与页面同源;仅配置跨域 CORS 不会满
266
266
  | `protocol` | `'tlv-v1' \| 'fpnn'` | 默认 `'fpnn'` | 新接入请显式设为 `'tlv-v1'`。 |
267
267
  | `endpoint` | `string` | FPNN 必填 | FPNN Gate 主机及可选端口(`host[:port]`),使用 `ws://`。 |
268
268
  | `ssl_endpoint` | `string` | FPNN 可选 | FPNN Gate 主机及可选端口(`host[:port]`),使用 `wss://`;提供时优先于 `endpoint`。 |
269
- | `tlvEndpoint` | `string` | TLV 必填 | Gate 提供的完整 `ws://` 或 `wss://` URL,含部署要求的路径,通常以 `/service/websocket` 结尾。 |
269
+ | `tlvEndpoint` | `string` | TLV 必填 | Gate 的 `ws://` 或 `wss://` URL;无路径或仅 `/` 时 SDK 自动补齐 `/service/websocket`。已有 `/service/websocket` 不重复拼接,自定义路径原样保留;查询参数保持不变。 |
270
270
  | `autoReconnect` | `boolean` | `true` | 自动重连开关。终止性鉴权错误不会无限重试。 |
271
271
  | `connectionTimeout` | `number` | `30000` | 建立 WebSocket 连接的超时。 |
272
272
  | `requestTimeout` | `number` | `20000` | 请求默认超时;方法级 `timeout > 0` 时覆盖此值。 |
@@ -319,7 +319,7 @@ SharedWorker 是 SDK 实例和登录状态的共享底座:负责端口、同 U
319
319
 
320
320
  | API / 选项 | 参数与结果 |
321
321
  | --- | --- |
322
- | `new RTMSharedWorkerClient(options)` | `clientOptions` 必填;`clientOptions.protocol` 省略时默认 FPNN,提供 `pid` 及 `endpoint` 或 `ssl_endpoint`(`host[:port]`,不含 URL scheme 和路径)。选择 TLV v1 时显式设置 `protocol: 'tlv-v1'`,并提供完整 `tlvEndpoint`。`workerUrl` 可选,同源 Worker 脚本 URL;普通浏览器脚本省略时 SDK 推导加载 SDK 的脚本同目录下的 `rtm.shared-worker.js`,现代 ESM 入口自动解析包内 Worker 资源。提供 `uid` 且省略 `workerName` 时,SDK 根据协议、`clientOptions.pid`、`uid`、实际 Gate endpoint 和 `workerNamespace` 生成稳定名称;若需要自行构造名称,可调用 `createSharedWorkerName({protocol, pid, uid, endpoint, namespace})`。若 `uid` 和 `workerName` 都省略,会使用通用默认名称;多账号应用应传其中一个,避免不同 UID 页面加入同一个 Worker。`readyTimeout` 默认 10000 毫秒;`idleShutdownTimeout` 默认 5000 毫秒,最后一个页面 detach 后等待这段时间再关闭共享连接,设为 `0` 表示立即关闭;同一 Worker 的所有页面必须使用相同值。`conversation` 可选,默认 `null` 接收全部会话 Push。 |
322
+ | `new RTMSharedWorkerClient(options)` | `clientOptions` 必填;`clientOptions.protocol` 省略时默认 FPNN,提供 `pid` 及 `endpoint` 或 `ssl_endpoint`(`host[:port]`,不含 URL scheme 和路径)。选择 TLV v1 时显式设置 `protocol: 'tlv-v1'`,并提供 `tlvEndpoint`;无路径或仅 `/` 时 SDK 自动补齐 `/service/websocket`。`workerUrl` 可选,同源 Worker 脚本 URL;普通浏览器脚本省略时 SDK 推导加载 SDK 的脚本同目录下的 `rtm.shared-worker.js`,现代 ESM 入口自动解析包内 Worker 资源。提供 `uid` 且省略 `workerName` 时,SDK 根据协议、`clientOptions.pid`、`uid`、实际 Gate endpoint 和 `workerNamespace` 生成稳定名称;若需要自行构造名称,可调用 `createSharedWorkerName({protocol, pid, uid, endpoint, namespace})`。若 `uid` 和 `workerName` 都省略,会使用通用默认名称;多账号应用应传其中一个,避免不同 UID 页面加入同一个 Worker。`readyTimeout` 默认 10000 毫秒;`idleShutdownTimeout` 默认 5000 毫秒,最后一个页面 detach 后等待这段时间再关闭共享连接,设为 `0` 表示立即关闭;同一 Worker 的所有页面必须使用相同值。`conversation` 可选,默认 `null` 接收全部会话 Push。 |
323
323
  | `whenReady()` | 等 Worker 首次初始化并返回 `{status, uid}` 初始快照;再次调用不会刷新快照,当前状态用 `getSharedSession()`。初始化失败时 Promise reject,SDK 会自动 detach 并关闭当前页面的端口。 |
324
324
  | `getSharedSession()` | 同步返回本页面最近观察到的 `{status, uid}`。 |
325
325
  | `loginIfNeeded(uid, credential?, timeout?)` | 同 UID 会话已登录则复用;登录中则加入该登录;会话空闲时须提供服务端签发的 credential。resolve `{accepted, errorCode, reused, uid}`。 |
@@ -431,7 +431,7 @@ await shared.promises.sendChat(peerUid, 'hello', '{}');
431
431
  // 页面离开时 SDK 自动 detach;也可显式 shared.destroy()。
432
432
  ```
433
433
 
434
- FPNN 的 `endpoint` / `ssl_endpoint` 接收 `host[:port]`,SDK 补上 `ws://` / `wss://` 和 `/service/websocket`;它与 TLV 的完整 URL 配置不同。自动 Worker identity 包含协议,因此同 UID 的 FPNN / TLV 页面不会共享一条连接。若显式指定相同 `workerName` 却传入不同协议或配置,后加入页面初始化失败,不会覆盖已有会话。
434
+ FPNN 的 `endpoint` / `ssl_endpoint` 接收 `host[:port]`,SDK 补上 `ws://` / `wss://` 和 `/service/websocket`。TLV 的 `tlvEndpoint` 仍须带 `ws://` 或 `wss://`,无路径或仅 `/` 时同样由 SDK 补齐 `/service/websocket`;已有路径保持不变。自动 Worker identity 包含协议,因此同 UID 的 FPNN / TLV 页面不会共享一条连接。若显式指定相同 `workerName` 却传入不同协议或配置,后加入页面初始化失败,不会覆盖已有会话。
435
435
 
436
436
  FPNN Push 保留 `SERVER_PUSH` 事件和 `from / gid / rid / mid / msg` 等字段;TLV 保留 `TLV_SERVER_PUSH` 事件及其字段。Worker 原样分发所有 SDK 事件;ACK、去重、协议校验和业务请求都由底层 `RTMClient` 处理。页面适配器只在应用显式设置 `conversation` 时进行本地筛选。FPNN 的 `fileToken`、`sendFile`、`sendGroupFile`、`sendRoomFile` 都可通过共享调用使用,File 对象经结构化克隆交给 Worker,上传继续由 SDK 的文件代理连接完成。TLV 文件调用由底层协议契约返回 `200020`,共享层不维护业务 API 禁用名单。传统参数与 Push 细节见 [协议迁移对照](PROTOCOL_MIGRATION.md) 和 [事件处理说明](EventProcess.md)。
437
437
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cg-devcenter/rtc-fpnn-webjs-sdk",
3
- "version": "1.0.0-cg.11",
3
+ "version": "1.0.0-cg.13",
4
4
  "description": "Browser RTM SDK with FPNN and TLV v1 MessagePack WebSocket transports",
5
5
  "main": "./dist/rtm.min.js",
6
6
  "browser": "./dist/rtm.min.js",
@@ -71,6 +71,8 @@
71
71
  "test:unit": "node test/tlv/run.js && node test/tlv/documentation.js && node test/migration-compatibility.js && node test/legacy-rtm-compatibility.js && node test/demo-workflows.js && node test/vue-demo-state.js && node test/sdk-capabilities.mjs",
72
72
  "test:package": "npm run build && npm run capabilities:check && node test/package-files.js && node test/package-tarball.js && node test/package-smoke.js && node test/package-esm-smoke.mjs && node test/package-webpack4.js && npm run test:types",
73
73
  "test:types": "tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2020 test/package-types/esm.mts test/package-types/cjs.cts",
74
+ "demo:alipay-build": "node examples/alipay-mini-program-demo/scripts/build-sdk.mjs",
75
+ "demo:alipay-prefill-credential": "node examples/alipay-mini-program-demo/scripts/prefill-credential.mjs",
74
76
  "demo:tlv-basic": "node examples/tlv-basic-demo/server.js",
75
77
  "demo:shared-worker": "node examples/shared-worker-demo/server.js",
76
78
  "prepack": "npm run build"