@cg-devcenter/rtc-fpnn-webjs-sdk 1.0.0-cg.10 → 1.0.0-cg.12
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.
- package/README.md +1 -1
- package/dist/rtm.d.ts +4 -3
- package/dist/rtm.min.js +3 -3
- package/dist/rtm.mjs +2 -2
- package/dist/rtm.shared-worker.js +3 -3
- package/docs/CAPABILITIES.md +1 -1
- package/docs/PROTOCOL_MIGRATION.md +2 -2
- package/docs/RTM_MIGRATION.md +2 -1
- package/docs/TLV.md +3 -1
- package/docs/USAGE.md +7 -7
- package/package.json +1 -1
package/docs/CAPABILITIES.md
CHANGED
|
@@ -80,7 +80,7 @@ TLV v1 使用 MessagePack 二进制 WebSocket frame。SDK 提供以下基础模
|
|
|
80
80
|
const result = await client.promises.sendChat(peerUid, 'hello', '{}', 0, 12000);
|
|
81
81
|
```
|
|
82
82
|
|
|
83
|
-
`client.promises.login(uid, credential, timeout?)` 成功时 resolve `{ accepted: true, errorCode }`,鉴权失败时 reject 一个带 `code` 的 Error。TLV Gate 返回 `control.error` 时保留服务端错误码;若只返回 `accepted: false`,SDK 使用 `200027`。`client.promises.bye(timeout?)`
|
|
83
|
+
`client.promises.login(uid, credential, timeout?)` 成功时 resolve `{ accepted: true, errorCode }`,鉴权失败时 reject 一个带 `code` 的 Error。TLV Gate 返回 `control.error` 时保留服务端错误码;若只返回 `accepted: false`,SDK 使用 `200027`。`client.promises.bye(timeout?)` 在收到 Gate 应答时 resolve 应答数据;FPNN Gate 关闭连接完成 `bye` 时 resolve `{ closed: true }`。超时或其他错误仍会 reject,TLV 请求失败时 SDK 主动关闭连接。`RTMSharedWorkerClient.loginIfNeeded()` 保持自己的结果约定:RTC 鉴权结果 resolve 为 `{ accepted, errorCode, reused, uid }`;Worker 初始化错误及缺少首次登录 credential 会 reject。其他生命周期方法和事件仍通过 client 本身调用。
|
|
84
84
|
|
|
85
85
|
### 一对一聊天
|
|
86
86
|
|
|
@@ -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'`
|
|
23
|
+
若业务必须保持每个页面独立连接,可改用 `rtm.createClient({ sharing: false, pid, endpoint: fpnnEndpoint })`;浏览器缺少 SharedWorker 时,`createClient()` 也会自动使用独立连接。若希望新项目显式使用 TLV v1,则设置 `protocol: 'tlv-v1'` 并提供 `tlvEndpoint`;无路径或仅 `/` 时 SDK 自动补齐 `/service/websocket`,已有路径原样保留。
|
|
24
24
|
|
|
25
|
-
迁移到 TLV v1
|
|
25
|
+
迁移到 TLV v1 时,将连接地址换成部署方提供的 `ws://` 或 `wss://` URL(无路径或仅 `/` 时 SDK 自动补齐 `/service/websocket`,已有路径保持不变),并在创建时选择 TLV:
|
|
26
26
|
|
|
27
27
|
```js
|
|
28
28
|
const client = new rtm.RTMClient({
|
package/docs/RTM_MIGRATION.md
CHANGED
|
@@ -80,6 +80,7 @@ client.login(uid, credential, (accepted, errorCode) => {
|
|
|
80
80
|
- 默认 `autoReconnect: true` 与上游一致。当前版没有为了 FPNN 迁移改变这一默认值。
|
|
81
81
|
- `login(uid, token, callback, timeout)`、FPNN Push 名称及普通 API 参数顺序沿用上游;当前版另外提供 Promise facade 和一批新增 API,见下表。
|
|
82
82
|
- `getUnreadMessage` 新增可选 `withLogout`,`removeSession` 新增可选 `localOnly`,`bye` 新增可选超时和 callback。旧 JavaScript 调用形式仍可用;当前类型声明也保留旧调用重载,只有需要新语义时才传新增参数。
|
|
83
|
+
- FPNN `bye` 保留上游的无参调用方式。上游内部忽略关闭时的 transport 错误;当前版把 Gate 按关闭流程断开连接视为成功,callback / Promise 返回 `{closed: true}`。超时和其他请求错误仍报告为失败;TLV 仍以 Gate 的 `connection.close` Answer 作为成功应答。
|
|
83
84
|
- `createClient()` 即使默认协议为 FPNN,也会在 SharedWorker 可用时优先共享;浏览器没有 SharedWorker API 时自动使用独立连接。需要始终独立时,应使用 `RTMClient` 或显式设置 `sharing: false`;只设置 `protocol: 'fpnn'` 不会关闭可用时的共享。
|
|
84
85
|
|
|
85
86
|
共享模式下,当前 `createClient()` 通过 SharedWorker 按 PID、协议、UID 和 Gate 地址复用连接;首次登录的页面提供 credential,同身份的其他页面复用会话。
|
|
@@ -178,7 +179,7 @@ const independentClient = rtm.createClient({
|
|
|
178
179
|
|
|
179
180
|
## 选择 TLV v1 是另一项迁移
|
|
180
181
|
|
|
181
|
-
继续使用 FPNN 时不需要更换消息事件名称。改用 TLV v1 时,创建客户端需显式设置 `protocol: 'tlv-v1'`
|
|
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` 常量和对应契约处理。
|
|
182
183
|
|
|
183
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)。
|
|
184
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`
|
|
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
|
| 字段 | 规则 |
|
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
|
|
67
|
+
tlvEndpoint: 'wss://<gate-host>', // SDK 自动补齐 /service/websocket
|
|
68
68
|
autoReconnect: true,
|
|
69
69
|
});
|
|
70
70
|
|
|
@@ -248,7 +248,7 @@ SharedWorker 仍要求 Worker 与页面同源;仅配置跨域 CORS 不会满
|
|
|
248
248
|
| `new RTMClient(options)` | 创建客户端;`pid` 必填,必须显式设 `protocol: 'tlv-v1'` 才使用 TLV。构造参数见下表。 |
|
|
249
249
|
| `login(uid, credential, callback, timeout?)` | `callback(accepted, errorCode)`。仅 `accepted === true` 表示进入登录态。`timeout` 限制 auth 请求;WebSocket 握手由 `connectionTimeout` 限制。 |
|
|
250
250
|
| `promises.login(uid, credential, timeout?)` | 登录成功 resolve `{accepted: true, errorCode}`;登录拒绝或失败 reject,错误对象带 `code`。 |
|
|
251
|
-
| `bye(timeout?, callback?)` |
|
|
251
|
+
| `bye(timeout?, callback?)` | 发协议级关闭请求。FPNN Gate 关闭连接时 callback 为 `(null, {closed: true})`;收到Gate应答时返回该应答。TLV按 `connection.close` 应答完成;TLV失败或超时会关闭底层连接。其他请求错误通过 callback / Promise 返回。 |
|
|
252
252
|
| `close()` | 立即关闭当前连接,不等待协议级关闭应答。 |
|
|
253
253
|
| `startAutoReconnect()` | 关闭当前连接并允许 SDK 按配置重连。`createClient()` 的 `legacy-rtm` 模式下也会作为本地生命周期方法直接转发,不经过 TLV 业务 API 映射。 |
|
|
254
254
|
| `destroy()` | 立即关闭连接并释放客户端资源;正在等待的请求会以错误结束。 |
|
|
@@ -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
|
|
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` 时覆盖此值。 |
|
|
@@ -295,7 +295,7 @@ SharedWorker 仍要求 Worker 与页面同源;仅配置跨域 CORS 不会满
|
|
|
295
295
|
|
|
296
296
|
`ErrorRecorder(error)` 用于连接、协议、自动重连和登录错误,不会代替普通业务请求的 callback 或 Promise rejection。业务失败应检查各自调用结果。请求超时与连接中断会结束挂起调用;连接中断时写入结果可能未知,SDK 不自动重放,业务应按幂等规则决定是否重试。
|
|
297
297
|
|
|
298
|
-
`bye()`
|
|
298
|
+
`bye()` 与普通业务调用不同,是异步的协议关闭握手。FPNN Gate 可能通过关闭连接完成 `bye`,不返回 Answer;SDK 会把该预期断连作为成功处理,Promise resolve `{closed: true}`。收到 Gate Answer 时 Promise resolve 应答数据;TLV 超时或拒绝仍会 reject 并关闭连接。结束整个会话时,使用有超时的 Promise,并在 `finally` 中 `close()` 后 `destroy()`;不必等待 `SessionClosed` 才能清理:
|
|
299
299
|
|
|
300
300
|
```js
|
|
301
301
|
try {
|
|
@@ -307,7 +307,7 @@ try {
|
|
|
307
307
|
}
|
|
308
308
|
```
|
|
309
309
|
|
|
310
|
-
Promise 成功表示 Gate
|
|
310
|
+
Promise 成功表示 Gate 已应答关闭请求,或 FPNN 会话已按关闭流程断开。直接结束整个会话可调用 `close()`,这可能中止尚未完成的 `bye()`。共享模式下只关闭当前页面或卸载组件时仅调用 `destroy()`,不要调用 `bye()` / `close()`,其他页面会继续使用共享会话。独立 `RTMClient.destroy()` 则会关闭其自身连接。
|
|
311
311
|
|
|
312
312
|
常用事件:`ErrorRecorder(error)`、`ReloginCompleted(successful, retryAgain, errorCode, retriedCount)`、`SessionClosed(errorCode)`。TLV 可靠 Push 由 SDK 自动 ACK,并按 `message_ref` 去重;这不等于离线补拉或业务存储。
|
|
313
313
|
|
|
@@ -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'
|
|
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
|
|
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