request-iframe 0.0.6 → 0.1.1

package/README.CN.md

@@ -1,6 +1,6 @@
 # request-iframe
 
-像发送 HTTP 请求一样与 iframe 通信！基于 `postMessage` 实现的 iframe 跨域通信库。
+像发送 HTTP 请求一样与 iframe / Window 通信！基于 `postMessage` 实现的浏览器跨页面通信库。
 
 > 🌐 **Languages**: [English](./README.md) | [中文](./README.CN.md)
 
@@ -8,7 +8,7 @@
   <img src="https://img.shields.io/badge/TypeScript-Ready-blue" alt="TypeScript Ready">
   <img src="https://img.shields.io/badge/API-Express%20Like-green" alt="Express Like API">
   <img src="https://img.shields.io/badge/License-MIT-yellow" alt="MIT License">
-  <img src="https://img.shields.io/badge/Test%20Coverage-76%25-brightgreen" alt="Test Coverage">
+  <img src="https://coveralls.io/repos/github/gxlmyacc/request-iframe/badge.svg?branch=main" alt="Coverage Status">
 </p>
 
 ## 📑 目录
@@ -48,7 +48,7 @@
 
 ## 为什么选择 request-iframe？
 
-在微前端、iframe 嵌套等场景下，父子页面通信是常见需求。传统的 `postMessage` 通信存在以下痛点：
+在微前端、iframe 嵌套、弹窗（window.open）等场景下，跨页面通信是常见需求。传统的 `postMessage` 通信存在以下痛点：
 
 | 痛点 | 传统方式 | request-iframe |
 |------|----------|----------------|
@@ -74,7 +74,7 @@
 - ⏱️ **智能超时** - 三阶段超时（连接/同步/异步），自动识别长任务
 - 📦 **TypeScript** - 完整的类型定义和智能提示
 - 🔒 **消息隔离** - secretKey 机制避免多实例消息串线
-- 📁 **文件传输** - 支持文件通过流方式传输（Client→Server）
+- 📁 **文件传输** - 支持文件通过流方式传输（Client↔Server）
 - 🌊 **流式传输** - 支持大文件分块传输，支持异步迭代器
 - 🌍 **多语言** - 错误消息可自定义，便于国际化
 - ✅ **协议版本** - 内置版本控制，便于升级兼容
@@ -151,7 +151,7 @@ request-iframe 在 `postMessage` 基础上实现了一套类 HTTP 的通信协
        │                                            │
        │  <──── RESPONSE ────────────────────────  │  返回结果
        │                                            │
-       │  ──── RECEIVED (可选) ──────────────────>  │  确认收到响应
+       │  ──── ACK (可选) ───────────────────────>  │  确认收到响应
        │                                            │
 ```
 
@@ -160,12 +160,11 @@ request-iframe 在 `postMessage` 基础上实现了一套类 HTTP 的通信协
 | 类型 | 方向 | 说明 |
 |------|------|------|
 | `request` | Client → Server | 客户端发起请求 |
-| `ack` | Server → Client | 服务端确认收到请求 |
+| `ack` | 接收方 → 发送方 | 回执确认（当消息 `requireAck: true` 且被接管/处理时发送；ACK-only） |
 | `async` | Server → Client | 通知客户端这是异步任务（handler 返回 Promise 时发送） |
 | `response` | Server → Client | 返回响应数据 |
 | `error` | Server → Client | 返回错误信息 |
-| `received` | Client → Server | 客户端确认收到响应（可选，由 `requireAck` 控制） |
-| `ping` | Client → Server | 连接检测（`isConnect()` 方法） |
+| `ping` | Client → Server | 连接检测（`isConnect()`；可使用 `requireAck` 确认投递） |
 | `pong` | Server → Client | 连接检测响应 |
 
 ### 超时机制
@@ -176,7 +175,8 @@ request-iframe 采用三阶段超时策略，智能适应不同场景：
 client.send('/api/getData', data, {
   ackTimeout: 1000,       // 阶段1：等待 ACK 的超时时间（默认 1000ms）
   timeout: 5000,          // 阶段2：请求超时时间（默认 5s）
-  asyncTimeout: 120000    // 阶段3：异步请求超时时间（默认 120s）
+  asyncTimeout: 120000,   // 阶段3：异步请求超时时间（默认 120s）
+  requireAck: true        // 是否需要服务端 ACK（默认 true；为 false 则跳过 ACK 阶段，直接进入 timeout）
 });
 ```
 
@@ -218,13 +218,17 @@ client.send('/api/getData', data, {
 | timeout | 中等（5s） | 适用于简单的同步处理，如读取数据、参数校验等 |
 | asyncTimeout | 较长（120s） | 适用于复杂异步操作，如文件处理、批量操作、第三方 API 调用等 |
 
+**补充说明：**
+- `requireAck: false` 会跳过 ACK 阶段，直接以 `timeout` 作为第一阶段计时。
+- 流（Stream）有独立的可选空闲超时：`streamTimeout`（见「流式传输（Stream）」）。
+
 ### 协议版本
 
 每条消息都包含 `__requestIframe__` 字段标识协议版本，以及 `timestamp` 字段记录消息创建时间：
 
 ```typescript
 {
-  __requestIframe__: 1,  // 协议版本号
+  __requestIframe__: 2,  // 协议版本号
   timestamp: 1704067200000,  // 消息创建时间戳（毫秒）
   type: 'request',
   requestId: 'req_xxx',
@@ -235,7 +239,7 @@ client.send('/api/getData', data, {
 
 这使得：
 - 不同版本的库可以做兼容处理
-- 新版本 Server 可兼容旧版本 Client
+- 当前协议版本为 `2`；对于新的 stream pull/ack 流程，建议双方保持一致版本
 - 版本过低时会返回明确的错误信息
 - `timestamp` 便于调试消息延迟、分析通信性能
 
@@ -281,6 +285,29 @@ server.on('/event', (req, res) => {
 });
 ```
 
+### 弹窗 / 新标签页（Window 通信）
+
+`request-iframe` 不仅可以与 iframe 通信，也可以把 `target` 直接传 `Window`（例如弹窗/新标签页）。
+
+**重要前提**：你必须拿到对方页面的 `Window` 引用（例如 `window.open()` 的返回值，或通过 `window.opener` / `MessageEvent.source` 获取）。**无法**通过 URL 给“任意标签页”发消息。
+
+```typescript
+// 父页面：打开新标签页/弹窗
+const child = window.open('https://child.example.com/page.html', '_blank');
+if (!child) throw new Error('弹窗被拦截');
+
+// 父 -> 子
+const client = requestIframeClient(child, {
+  secretKey: 'popup-demo',
+  targetOrigin: 'https://child.example.com' // 强烈建议不要用 '*'
+});
+await client.send('/api/ping', { from: 'parent' });
+
+// 子页面：创建 server
+const server = requestIframeServer({ secretKey: 'popup-demo' });
+server.on('/api/ping', (req, res) => res.send({ ok: true, echo: req.body }));
+```
+
 ### 跨域数据获取
 
 当 iframe 与父页面不同域时，使用 request-iframe 安全地获取数据：
@@ -578,6 +605,8 @@ server.on('/api/data', (req, res) => {
 
 ### 文件传输
 
+> 说明：文件传输（无论 Client→Server 还是 Server→Client）底层都会通过 stream 协议承载；你只需要使用 `client.sendFile()` / `res.sendFile()` 这一层 API 即可。
+
 ```typescript
 // Server 端发送文件
 server.on('/api/download', async (req, res) => {
@@ -610,7 +639,7 @@ if (response.data instanceof File || response.data instanceof Blob) {
 
 #### Client → Server（Client 向 Server 发送文件）
 
-Client 端发送文件**仅走流式**。使用 `sendFile()`（或直接 `send(path, file)`）；Server 端在 `autoResolve: true`（默认）时会把文件自动解析成 `File/Blob` 放到 `req.body`，当 `autoResolve: false` 时则通过 `req.stream` / `req.body` 暴露为 `IframeFileReadableStream`。
+Client 端发送文件使用 `sendFile()`（或直接 `send(path, file)`）；Server 端在 `autoResolve: true`（默认）时会把文件自动解析成 `File/Blob` 放到 `req.body`，当 `autoResolve: false` 时则通过 `req.stream` / `req.body` 暴露为 `IframeFileReadableStream`。
 
 ```typescript
 // Client 端：发送文件（stream，autoResolve 默认 true）
@@ -634,14 +663,74 @@ server.on('/api/upload', async (req, res) => {
 });
 ```
 
-**提示**：当 `client.send()` 的 `body` 是 `File/Blob` 时，会自动分发到 `client.sendFile()`（走流式）。`autoResolve` 为 true（默认）时 Server 拿到 `req.body`（File/Blob），为 false 时拿到 `req.stream` / `req.body`（`IframeFileReadableStream`）。
+**提示**：当 `client.send()` 的 `body` 是 `File/Blob` 时，会自动分发到 `client.sendFile()`。`autoResolve` 为 true（默认）时 Server 拿到 `req.body`（File/Blob），为 false 时拿到 `req.stream` / `req.body`（`IframeFileReadableStream`）。
 
 ### 流式传输（Stream）
 
-对于大文件或需要分块传输的场景，可以使用流式传输：
+Stream 除了用于大文件/分块传输，也可以用于“长连接 / 订阅式交互”（类似 SSE / WebSocket，但基于 `postMessage`）。常见用法有两类：
+
+- **长连接/订阅**：Client 发起一次请求拿到 `response.stream`，然后用 `for await` 持续消费事件；需要结束时调用 `stream.cancel()`。
+- **分块/文件流**：按 chunk 传输数据或文件（下方示例）。
+
+> 长连接注意事项：
+> - `IframeWritableStream` 默认会使用 `asyncTimeout` 作为 `expireTimeout`（避免泄露）。如果你的订阅需要更久，请显式设置更大的 `expireTimeout`，或设置 `expireTimeout: 0` 关闭自动过期（建议配合业务侧取消/重连，避免泄露）。
+> - Server 端的 `res.sendStream(stream)` 会一直等待到流结束；如果你需要在后续主动 `write()` 推送数据，请不要直接 `await` 它，可以用 `void res.sendStream(stream)` 或保存返回的 Promise。
+> - 如果启用了 `maxConcurrentRequestsPerClient`，一个长连接 stream 会占用一个并发槽，需要按业务场景调整。
+> - **事件订阅**：stream 支持 `stream.on(event, listener)`（返回取消订阅函数），可用于埋点/进度/调试（如监听 `start/data/read/write/cancel/end/error/timeout/expired`）。主消费仍建议使用 `for await`。
+
+#### 长连接 / 订阅式交互（push 模式示例）
 
 ```typescript
-import { 
+/**
+ * Server 端：订阅（长连接）
+ * - mode: 'push'：由写侧主动 write()
+ * - expireTimeout: 0：关闭自动过期（谨慎使用，建议结合业务取消/重连）
+ */
+server.on('/api/subscribe', (req, res) => {
+  const stream = new IframeWritableStream({
+    type: 'data',
+    chunked: true,
+    mode: 'push',
+    expireTimeout: 0,
+    /** 可选：写侧空闲检测（等待 pull/ack 太久会做心跳并失败） */
+    streamTimeout: 15000
+  });
+
+  /** 注意：不要 await，否则会一直等到流结束 */
+  void res.sendStream(stream);
+
+  const timer = setInterval(() => {
+    try {
+      stream.write({ type: 'tick', ts: Date.now() });
+    } catch {
+      clearInterval(timer);
+    }
+  }, 1000);
+});
+
+/**
+ * Client 端：持续读取（长连接建议用 for await，而不是 readAll()）
+ */
+const resp = await client.send('/api/subscribe', {});
+if (isIframeReadableStream(resp.stream)) {
+  /** 事件订阅示例（可选） */
+  const off = resp.stream.on(StreamEvent.ERROR, ({ error }) => {
+    console.error('stream error:', error);
+  });
+
+  for await (const evt of resp.stream) {
+    console.log('event:', evt);
+  }
+
+  off();
+}
+```
+
+#### 分块 / 文件流示例
+
+```typescript
+import {
+  StreamEvent,
   IframeWritableStream, 
   IframeFileWritableStream,
   isIframeReadableStream,
@@ -706,6 +795,8 @@ const response = await client.send('/api/stream', {});
 if (isIframeReadableStream(response.stream)) {
   // 方式1：一次性读取所有数据
   const allData = await response.stream.read();
+  // 如果希望返回类型稳定（始终是 chunk 数组），可使用 readAll()
+  const allChunks = await response.stream.readAll();
   
   // 方式2：使用异步迭代器逐块读取
   for await (const chunk of response.stream) {
@@ -750,10 +841,12 @@ if (isIframeFileReadableStream(fileResponse.stream)) {
 
 | 类型 | 说明 |
 |------|------|
-| `IframeWritableStream` | 服务端可写流，用于发送普通数据 |
-| `IframeFileWritableStream` | 服务端文件可写流（文件流） |
-| `IframeReadableStream` | 客户端可读流，用于接收普通数据 |
-| `IframeFileReadableStream` | 客户端文件可读流（文件流） |
+| `IframeWritableStream` | 写侧（生产者）流：**谁要发送 stream，谁就创建它**；可用于 Server→Client 的响应流，也可用于 Client→Server 的请求流 |
+| `IframeFileWritableStream` | 文件写侧（生产者）流：用于发送文件（底层会做 Base64 编码） |
+| `IframeReadableStream` | 读侧（消费者）流：用于接收普通数据（无论来自 Server 还是 Client） |
+| `IframeFileReadableStream` | 文件读侧（消费者）流：用于接收文件（底层会做 Base64 解码） |
+
+> **注意**：文件流内部会进行 Base64 编/解码。Base64 会带来约 33% 的体积膨胀，并且在超大文件场景下可能会有较高的内存/CPU 开销。大文件建议使用 **分块** 文件流（`chunked: true`），并控制 chunk 大小（例如 256KB–1MB）。
 
 **流选项：**
 
@@ -761,12 +854,32 @@ if (isIframeFileReadableStream(fileResponse.stream)) {
 interface WritableStreamOptions {
   type?: 'data' | 'file';    // 流类型
   chunked?: boolean;          // 是否分块传输（默认 true）
+  mode?: 'pull' | 'push';     // 流模式：pull(默认，按需拉取) / push(主动写入)
+  expireTimeout?: number;     // 流过期时间（ms，可选；默认约等于 asyncTimeout）
+  streamTimeout?: number;     // 写侧空闲超时（ms，可选）：长时间未收到对端 pull/ack 时会做心跳确认并失败
   iterator?: () => AsyncGenerator;  // 数据生成迭代器
   next?: () => Promise<{ data: any; done: boolean }>;  // 数据生成函数
+  maxPendingChunks?: number;  // 写侧待发送缓冲上限（可选；push/长连接场景建议配置，避免 pendingQueue 无限增长）
+  maxPendingBytes?: number;   // 写侧待发送字节上限（可选；避免单次 write 超大 chunk 导致内存暴涨）
   metadata?: Record<string, any>;   // 自定义元数据
 }
 ```
 
+**流超时/保活：**
+- `streamTimeout`（请求参数）：读侧空闲超时（ms，可选）。消费 `response.stream` 时超过该时间未收到新的 chunk，会先做一次心跳确认（默认使用 `client.isConnect()`），失败则认为流已断开并报错。
+- `streamTimeout`（流参数）：写侧空闲超时（ms，可选）。写侧在 pull 协议下，若长时间未收到对端 `pull`，会做心跳确认并失败（避免长时间无效占用）。
+- `expireTimeout`（流参数）：写侧有效期；过期后会发送 `stream_error`，读侧会收到明确的“已过期”错误。
+- `maxPendingChunks`（流参数）：写侧待发送缓冲上限（可选）。对 `push` / 长连接场景很重要：当对端停止 pull 时，继续 `write()` 会在写侧积压，建议设置上限防止内存无限增长。
+- `maxPendingBytes`（流参数）：写侧待发送字节上限（可选）。用于防止单次写入超大 chunk（例如大字符串/大 Blob 包装）导致内存占用过高。
+
+**pull/ack 协议（新增，默认启用）：**
+- 读侧会自动发送 `stream_pull` 请求更多 chunk；写侧只会在收到 `stream_pull` 后才继续发送 `stream_data`，实现真正的背压（按需拉取）。
+  - 断连检测不依赖 `stream_ack`，而是通过 `streamTimeout + 心跳(isConnect)` 来实现。
+
+**consume 默认行为（变更）：**
+- `for await (const chunk of stream)` 默认会 **消费并丢弃已迭代过的 chunk**（`consume: true`），避免长流场景内存无限增长。
+- 如果你希望后续还能 `read()/readAll()` 拿到历史数据，可在创建流时传 `consume: false`（或在业务上自行缓存）。
+
 ### 连接检测
 
 ```typescript
@@ -786,9 +899,9 @@ Server 可以要求 Client 确认收到响应：
 ```typescript
 server.on('/api/important', async (req, res) => {
   // requireAck: true 表示需要客户端确认
-  const received = await res.send(data, { requireAck: true });
+  const acked = await res.send(data, { requireAck: true });
   
-  if (received) {
+  if (acked) {
     console.log('客户端已确认收到');
   } else {
     console.log('客户端未确认（超时）');
@@ -796,6 +909,8 @@ server.on('/api/important', async (req, res) => {
 });
 ```
 
+> **说明**：当响应/错误被客户端“接管”（即存在对应的 pending request）时，库会自动发送 `ack`，无需业务侧手动发送。
+
 ### 追踪模式
 
 开启追踪模式可以在控制台查看详细的通信日志：
@@ -848,12 +963,81 @@ setMessages({
 | `target` | `HTMLIFrameElement \| Window` | 目标 iframe 元素或 window 对象 |
 | `options.secretKey` | `string` | 消息隔离标识（可选） |
 | `options.trace` | `boolean` | 是否开启追踪模式（可选） |
+| `options.targetOrigin` | `string` | 覆盖 postMessage 的 targetOrigin（可选）。当 `target` 是 `Window` 时默认 `*`；当 `target` 是 iframe 时默认取 `iframe.src` 的 origin。 |
 | `options.ackTimeout` | `number` | 全局默认 ACK 确认超时（ms），默认 1000 |
 | `options.timeout` | `number` | 全局默认请求超时（ms），默认 5000 |
 | `options.asyncTimeout` | `number` | 全局默认异步超时（ms），默认 120000 |
+| `options.requireAck` | `boolean` | 全局默认请求投递 ACK（默认 true）。为 false 时请求跳过 ACK 阶段，直接进入 timeout |
+| `options.streamTimeout` | `number` | 全局默认流空闲超时（ms，可选），用于消费 `response.stream` |
+| `options.allowedOrigins` | `string \| RegExp \| Array<string \| RegExp>` | 接收消息的 origin 白名单（可选，生产环境强烈建议配置） |
+| `options.validateOrigin` | `(origin, data, context) => boolean` | 自定义 origin 校验函数（可选，优先级高于 `allowedOrigins`） |
 
 **返回值：** `RequestIframeClient`
 
+**关于 `target: Window` 的说明：**
+- **必须持有对方页面的 `Window` 引用**（例如 `window.open()` 返回值、`window.opener`、或 `MessageEvent.source`）。
+- **无法**通过 URL 给“任意标签页”发消息。
+- 安全起见，建议显式设置 `targetOrigin`，并配置 `allowedOrigins` / `validateOrigin`。
+
+**生产环境推荐配置（模板）：**
+
+```typescript
+import { requestIframeClient, requestIframeServer } from 'request-iframe';
+
+/**
+ * 建议：明确限定 3 件事
+ * - secretKey：隔离不同业务/不同实例，避免消息串线
+ * - targetOrigin：发送时的 targetOrigin（Window 场景强烈建议不要用 '*'）
+ * - allowedOrigins / validateOrigin：接收时的 origin 白名单校验
+ */
+const secretKey = 'my-app';
+const targetOrigin = 'https://child.example.com';
+const allowedOrigins = [targetOrigin];
+
+// Client（父页）
+const client = requestIframeClient(window.open(targetOrigin)!, {
+  secretKey,
+  targetOrigin,
+  allowedOrigins
+});
+
+// Server（子页/iframe 内）
+const server = requestIframeServer({
+  secretKey,
+  allowedOrigins,
+  // 防止异常/攻击导致消息爆炸（按需设置）
+  maxConcurrentRequestsPerClient: 50
+});
+```
+
+**生产环境推荐配置（iframe 场景模板）：**
+
+```typescript
+import { requestIframeClient, requestIframeServer } from 'request-iframe';
+
+/**
+ * iframe 场景通常可以从 iframe.src 推导 targetOrigin，并用它作为 allowedOrigins 白名单。
+ */
+const iframe = document.querySelector('iframe')!;
+const targetOrigin = new URL(iframe.src).origin;
+const secretKey = 'my-app';
+
+// Client（父页）
+const client = requestIframeClient(iframe, {
+  secretKey,
+  // 可显式写出来（即使库内部也会默认推导），便于审计/避免误用 '*'
+  targetOrigin,
+  allowedOrigins: [targetOrigin]
+});
+
+// Server（iframe 内）
+const server = requestIframeServer({
+  secretKey,
+  allowedOrigins: [targetOrigin],
+  maxConcurrentRequestsPerClient: 50
+});
+```
+
 **示例：**
 
 ```typescript
@@ -882,6 +1066,9 @@ await client.send('/api/longTask', {}, {
 | `options.secretKey` | `string` | 消息隔离标识（可选） |
 | `options.trace` | `boolean` | 是否开启追踪模式（可选） |
 | `options.ackTimeout` | `number` | 等待客户端确认超时（ms），默认 1000 |
+| `options.maxConcurrentRequestsPerClient` | `number` | 每个客户端的最大并发 in-flight 请求数（按 origin + creatorId 维度），默认 Infinity |
+| `options.allowedOrigins` | `string \| RegExp \| Array<string \| RegExp>` | 接收消息的 origin 白名单（可选，生产环境强烈建议配置） |
+| `options.validateOrigin` | `(origin, data, context) => boolean` | 自定义 origin 校验函数（可选，优先级高于 `allowedOrigins`） |
 
 **返回值：** `RequestIframeServer`
 
@@ -902,6 +1089,8 @@ await client.send('/api/longTask', {}, {
 | `options.ackTimeout` | `number` | ACK 确认超时（ms），默认 1000 |
 | `options.timeout` | `number` | 请求超时（ms），默认 5000 |
 | `options.asyncTimeout` | `number` | 异步超时（ms），默认 120000 |
+| `options.requireAck` | `boolean` | 是否需要服务端 ACK（默认 true）。为 false 时跳过 ACK 阶段 |
+| `options.streamTimeout` | `number` | 流空闲超时（ms，可选），用于消费 `response.stream` |
 | `options.headers` | `object` | 请求 headers（可选） |
 | `options.cookies` | `object` | 请求 cookies（可选，会与内部存储的 cookies 合并，传入的优先级更高） |
 | `options.requestId` | `string` | 自定义请求 ID（可选） |
@@ -953,6 +1142,8 @@ await client.send('/api/uploadStream', stream);
 | `options.ackTimeout` | `number` | ACK 确认超时（ms），默认 1000 |
 | `options.timeout` | `number` | 请求超时（ms），默认 5000 |
 | `options.asyncTimeout` | `number` | 异步超时（ms），默认 120000 |
+| `options.requireAck` | `boolean` | 是否需要服务端 ACK（默认 true）。为 false 时跳过 ACK 阶段 |
+| `options.streamTimeout` | `number` | 流空闲超时（ms，可选），用于消费 `response.stream` |
 | `options.headers` | `object` | 请求 headers（可选） |
 | `options.cookies` | `object` | 请求 cookies（可选） |
 | `options.requestId` | `string` | 自定义请求 ID（可选） |
@@ -974,6 +1165,8 @@ await client.send('/api/uploadStream', stream);
 | `options.ackTimeout` | `number` | ACK 确认超时（ms），默认 1000 |
 | `options.timeout` | `number` | 请求超时（ms），默认 5000 |
 | `options.asyncTimeout` | `number` | 异步超时（ms），默认 120000 |
+| `options.requireAck` | `boolean` | 是否需要服务端 ACK（默认 true）。为 false 时跳过 ACK 阶段 |
+| `options.streamTimeout` | `number` | 流空闲超时（ms，可选），用于消费 `response.stream` |
 | `options.headers` | `object` | 请求 headers（可选） |
 | `options.cookies` | `object` | 请求 cookies（可选） |
 | `options.requestId` | `string` | 自定义请求 ID（可选） |
@@ -1127,6 +1320,8 @@ server.use(['/a', '/b'], (req, res, next) => { ... });
 
 request-iframe 提供了 React hooks，方便在 React 应用中使用。从 `request-iframe/react` 导入 hooks：
 
+> 注意：只有在使用 `request-iframe/react` 时才需要安装 React；单独安装 `request-iframe` 不依赖 React。
+
 ```typescript
 import { useClient, useServer, useServerHandler, useServerHandlerMap } from 'request-iframe/react';
 ```
@@ -1498,8 +1693,12 @@ import {
 | `PROTOCOL_UNSUPPORTED` | 协议版本不支持 |
 | `IFRAME_NOT_READY` | iframe 未就绪 |
 | `STREAM_ERROR` | 流传输错误 |
+| `STREAM_TIMEOUT` | 流空闲超时 |
+| `STREAM_EXPIRED` | 流已过期（可写流超过有效期） |
 | `STREAM_CANCELLED` | 流被取消 |
 | `STREAM_NOT_BOUND` | 流未绑定到请求上下文 |
+| `STREAM_START_TIMEOUT` | 流启动超时（请求体 stream_start 未按时到达） |
+| `TOO_MANY_REQUESTS` | 请求过多（服务端并发限制） |
 
 ### 错误处理示例