request-iframe 0.0.5 → 0.1.0

package/README.CN.md

@@ -160,12 +160,12 @@ request-iframe 在 `postMessage` 基础上实现了一套类 HTTP 的通信协
 | 类型 | 方向 | 说明 |
 |------|------|------|
 | `request` | Client → Server | 客户端发起请求 |
-| `ack` | Server → Client | 服务端确认收到请求 |
+| `ack` | Server → Client | 服务端确认收到请求（当请求 `requireAck` 开启时） |
 | `async` | Server → Client | 通知客户端这是异步任务（handler 返回 Promise 时发送） |
 | `response` | Server → Client | 返回响应数据 |
 | `error` | Server → Client | 返回错误信息 |
-| `received` | Client → Server | 客户端确认收到响应（可选，由 `requireAck` 控制） |
-| `ping` | Client → Server | 连接检测（`isConnect()` 方法） |
+| `received` | Client → Server | 客户端确认收到响应/错误（可选，由响应的 `requireAck` 控制） |
+| `ping` | Client → Server | 连接检测（`isConnect()`；可使用 `requireAck` 确认投递） |
 | `pong` | Server → Client | 连接检测响应 |
 
 ### 超时机制
@@ -176,7 +176,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 +219,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 +240,7 @@ client.send('/api/getData', data, {
 
 这使得：
 - 不同版本的库可以做兼容处理
-- 新版本 Server 可兼容旧版本 Client
+- 当前协议版本为 `2`；对于新的 stream pull/ack 流程，建议双方保持一致版本
 - 版本过低时会返回明确的错误信息
 - `timestamp` 便于调试消息延迟、分析通信性能
 
@@ -274,7 +279,7 @@ await client.send('/config', {
 });
 
 // 监听组件事件（通过反向通信）
-const server = requestIframeServer({ secretKey: 'widget-events' });
+const server = requestIframeServer({ secretKey: 'widget' });
 server.on('/event', (req, res) => {
   console.log('组件事件:', req.body);
   res.send({ received: true });
@@ -706,6 +711,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) {
@@ -755,18 +762,36 @@ if (isIframeFileReadableStream(fileResponse.stream)) {
 | `IframeReadableStream` | 客户端可读流，用于接收普通数据 |
 | `IframeFileReadableStream` | 客户端文件可读流（文件流） |
 
+> **注意**：文件流内部会进行 Base64 编/解码。Base64 会带来约 33% 的体积膨胀，并且在超大文件场景下可能会有较高的内存/CPU 开销。大文件建议使用 **分块** 文件流（`chunked: true`），并控制 chunk 大小（例如 256KB–1MB）。
+
 **流选项：**
 
 ```typescript
 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 }>;  // 数据生成函数
   metadata?: Record<string, any>;   // 自定义元数据
 }
 ```
 
+**流超时/保活：**
+- `streamTimeout`（请求参数）：读侧空闲超时（ms，可选）。消费 `response.stream` 时超过该时间未收到新的 chunk，会先做一次心跳确认，失败则认为流已断开并报错。
+- `streamTimeout`（流参数）：写侧空闲超时（ms，可选）。写侧在 pull/ack 协议下，若长时间未收到对端 `pull/ack`，会做心跳确认并失败（避免长时间无效占用）。
+- `expireTimeout`（流参数）：写侧有效期；过期后会发送 `stream_error`，读侧会收到明确的“已过期”错误。
+
+**pull/ack 协议（新增，默认启用）：**
+- 读侧会自动发送 `stream_pull` 请求更多 chunk，并对每个收到的 chunk 自动发送 `stream_ack`。
+- 写侧只会在收到 `stream_pull` 后才继续发送 `stream_data`，实现真正的背压（按需拉取）。
+
+**consume 默认行为（变更）：**
+- `for await (const chunk of stream)` 默认会 **消费并丢弃已迭代过的 chunk**（`consume: true`），避免长流场景内存无限增长。
+- 如果你希望后续还能 `read()/readAll()` 拿到历史数据，可在创建流时传 `consume: false`（或在业务上自行缓存）。
+
 ### 连接检测
 
 ```typescript
@@ -796,6 +821,8 @@ server.on('/api/important', async (req, res) => {
 });
 ```
 
+> **说明**：当响应/错误被客户端“接管”（即存在对应的 pending request）时，库会自动发送 `received`，无需业务侧手动发送。
+
 ### 追踪模式
 
 开启追踪模式可以在控制台查看详细的通信日志：
@@ -848,9 +875,14 @@ 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`
 
@@ -882,6 +914,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 +937,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 +990,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 +1013,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 +1168,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 +1541,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` | 请求过多（服务端并发限制） |
 
 ### 错误处理示例
 

package/README.md

@@ -165,7 +165,7 @@ await client.send('/config', {
 });
 
 // Listen to component events (via reverse communication)
-const server = requestIframeServer({ secretKey: 'widget-events' });
+const server = requestIframeServer({ secretKey: 'widget' });
 server.on('/event', (req, res) => {
   console.log('Component event:', req.body);
   res.send({ received: true });
@@ -229,7 +229,7 @@ request-iframe implements an HTTP-like communication protocol on top of `postMes
        │                                          │
        │  ──── REQUEST ────────────────────────>  │  Send request
        │                                          │
-       │  <──── ACK ───────────────────────────  │  Acknowledge receipt
+       │  <──── ACK (optional) ────────────────  │  Acknowledge receipt (controlled by request `requireAck`, default true)
        │                                          │
        │                                          │  Execute handler
        │                                          │
@@ -237,7 +237,7 @@ request-iframe implements an HTTP-like communication protocol on top of `postMes
        │                                          │
        │  <──── RESPONSE ──────────────────────  │  Return result
        │                                          │
-       │  ──── RECEIVED (optional) ────────────>  │  Acknowledge receipt of response
+       │  ──── RECEIVED (optional) ────────────>  │  Acknowledge receipt of response/error (controlled by response `requireAck`)
        │                                          │
 ```
 
@@ -246,13 +246,15 @@ request-iframe implements an HTTP-like communication protocol on top of `postMes
 | Type | Direction | Description |
 |------|-----------|-------------|
 | `request` | Client → Server | Client initiates request |
-| `ack` | Server → Client | Server acknowledges receipt of request |
+| `ack` | Server → Client | Server acknowledges receipt of request (when request `requireAck` is enabled) |
 | `async` | Server → Client | Notifies client this is an async task (sent when handler returns Promise) |
 | `response` | Server → Client | Returns response data |
 | `error` | Server → Client | Returns error information |
-| `received` | Client → Server | Client acknowledges receipt of response (optional, controlled by `requireAck`) |
-| `ping` | Client → Server | Connection detection (`isConnect()` method) |
+| `received` | Client → Server | Client acknowledges receipt of response/error (optional, controlled by response `requireAck`) |
+| `ping` | Client → Server | Connection detection (`isConnect()` method, may use `requireAck` to confirm delivery) |
 | `pong` | Server → Client | Connection detection response |
+| `stream_pull` | Receiver → Sender | Stream pull: receiver requests next chunks (pull/ack protocol) |
+| `stream_ack` | Receiver → Sender | Stream ack: receiver acknowledges a chunk (pull/ack protocol) |
 
 ### Timeout Mechanism
 
@@ -262,7 +264,8 @@ request-iframe uses a three-stage timeout strategy to intelligently adapt to dif
 client.send('/api/getData', data, {
   ackTimeout: 1000,       // Stage 1: ACK timeout (default 1000ms)
   timeout: 5000,          // Stage 2: Request timeout (default 5s)
-  asyncTimeout: 120000    // Stage 3: Async request timeout (default 120s)
+  asyncTimeout: 120000,   // Stage 3: Async request timeout (default 120s)
+  requireAck: true        // Whether to wait for server ACK before switching to stage 2 (default true)
 });
 ```
 
@@ -304,13 +307,17 @@ Send REQUEST
 | timeout | Medium (5s) | Suitable for simple synchronous processing, like reading data, parameter validation |
 | asyncTimeout | Long (120s) | Suitable for complex async operations, like file processing, batch operations, third-party API calls |
 
+**Notes:**
+- If you set `requireAck: false`, the request will **skip** the ACK stage and start `timeout` immediately.
+- Stream transfer has its own optional idle timeout: use `streamTimeout` (see [Streaming](#streaming)).
+
 ### Protocol Version
 
 Each message contains a `__requestIframe__` field identifying the protocol version, and a `timestamp` field recording message creation time:
 
 ```typescript
 {
-  __requestIframe__: 1,  // Protocol version number
+  __requestIframe__: 2,  // Protocol version number
   timestamp: 1704067200000,  // Message creation timestamp (milliseconds)
   type: 'request',
   requestId: 'req_xxx',
@@ -321,7 +328,7 @@ Each message contains a `__requestIframe__` field identifying the protocol versi
 
 This enables:
 - Different library versions can handle compatibility
-- New version Server can be compatible with old version Client
+- Current protocol version is `2`. For the new stream pull/ack flow, both sides should use the same version.
 - Clear error messages when version is too low
 - `timestamp` facilitates debugging message delays and analyzing communication performance
 
@@ -630,6 +637,11 @@ server.on('/api/stream', async (req, res) => {
   const stream = new IframeWritableStream({
     type: 'data',
     chunked: true,
+    mode: 'pull', // default: pull/ack protocol (backpressure)
+    // Optional: auto-expire stream to avoid leaking resources (default: asyncTimeout)
+    // expireTimeout: 120000,
+    // Optional: writer-side idle timeout while waiting for pull/ack
+    // streamTimeout: 10000,
     // Generate data using async iterator
     iterator: async function* () {
       for (let i = 0; i < 10; i++) {
@@ -643,14 +655,19 @@ server.on('/api/stream', async (req, res) => {
 });
 
 // Client side: Receive stream data
-const response = await client.send('/api/stream', {});
+const response = await client.send('/api/stream', {}, { streamTimeout: 10000 });
 
 // Check if it's a stream response
 if (isIframeReadableStream(response.stream)) {
+  // Sender stream mode (from stream_start)
+  console.log('Stream mode:', response.stream.mode); // 'pull' | 'push' | undefined
+
   // Method 1: Read all data at once
   const allData = await response.stream.read();
+  // If you want a consistent return type (always an array of chunks), use readAll()
+  const allChunks = await response.stream.readAll();
   
-  // Method 2: Read chunk by chunk using async iterator
+  // Method 2: Read chunk by chunk using async iterator (consume defaults to true)
   for await (const chunk of response.stream) {
     console.log('Received chunk:', chunk);
   }
@@ -728,6 +745,20 @@ server.on('/api/uploadStream', async (req, res) => {
 | `IframeReadableStream` | Client-side readable stream for receiving regular data |
 | `IframeFileReadableStream` | Client-side file readable stream, automatically handles base64 decoding |
 
+> **Note**: File streams are base64-encoded internally. Base64 introduces ~33% size overhead and can be memory/CPU heavy for very large files. For large files, prefer **chunked** file streams (`chunked: true`) and keep chunk sizes moderate (e.g. 256KB–1MB).
+
+**Stream timeouts:**
+- `options.streamTimeout` (request option): client-side stream idle timeout while consuming `response.stream` (data/file streams). When triggered, the client will attempt a heartbeat check and fail the stream if the connection is not alive.
+- `expireTimeout` (writable stream option): writer-side stream lifetime. When expired, the writer sends `stream_error` and the reader will fail the stream with `STREAM_EXPIRED`.
+- `streamTimeout` (writable stream option): writer-side idle timeout. If the writer does not receive `stream_pull/stream_ack` for a long time, it will heartbeat-check and fail to avoid wasting resources.
+
+**Pull/Ack protocol (default):**
+- Reader automatically sends `stream_pull` to request chunks and sends `stream_ack` for each received chunk.
+- Writer only sends `stream_data` when it has received `stream_pull`, enabling real backpressure.
+
+**consume default change:**
+- `for await (const chunk of response.stream)` defaults to **consume and drop** already iterated chunks (`consume: true`) to prevent unbounded memory growth for long streams.
+
 ### Connection Detection
 
 ```typescript
@@ -757,6 +788,8 @@ server.on('/api/important', async (req, res) => {
 });
 ```
 
+> **Note**: Client acknowledgment (`received`) is sent automatically by the library when the response/error is accepted by the client (i.e., there is a matching pending request). You don't need to manually send `received`.
+
 ### Trace Mode
 
 Enable trace mode to view detailed communication logs in console:
@@ -809,9 +842,14 @@ Create a Client instance.
 | `target` | `HTMLIFrameElement \| Window` | Target iframe element or window object |
 | `options.secretKey` | `string` | Message isolation identifier (optional) |
 | `options.trace` | `boolean` | Whether to enable trace mode (optional) |
+| `options.targetOrigin` | `string` | Override postMessage targetOrigin for sending (optional). If `target` is a `Window`, default is `*`. |
 | `options.ackTimeout` | `number` | Global default ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Global default request timeout (ms), default 5000 |
 | `options.asyncTimeout` | `number` | Global default async timeout (ms), default 120000 |
+| `options.requireAck` | `boolean` | Global default for request delivery ACK (default true). If false, requests skip the ACK stage and start `timeout` immediately |
+| `options.streamTimeout` | `number` | Global default stream idle timeout (ms) when consuming `response.stream` (optional) |
+| `options.allowedOrigins` | `string \| RegExp \| Array<string \| RegExp>` | Allowlist for incoming message origins (optional, recommended for production) |
+| `options.validateOrigin` | `(origin, data, context) => boolean` | Custom origin validator (optional, higher priority than `allowedOrigins`) |
 
 **Returns:** `RequestIframeClient`
 
@@ -826,6 +864,9 @@ Create a Server instance.
 | `options.secretKey` | `string` | Message isolation identifier (optional) |
 | `options.trace` | `boolean` | Whether to enable trace mode (optional) |
 | `options.ackTimeout` | `number` | Wait for client acknowledgment timeout (ms), default 1000 |
+| `options.maxConcurrentRequestsPerClient` | `number` | Max concurrent in-flight requests per client (per origin + creatorId). Default Infinity |
+| `options.allowedOrigins` | `string \| RegExp \| Array<string \| RegExp>` | Allowlist for incoming message origins (optional, recommended for production) |
+| `options.validateOrigin` | `(origin, data, context) => boolean` | Custom origin validator (optional, higher priority than `allowedOrigins`) |
 
 **Returns:** `RequestIframeServer`
 
@@ -844,6 +885,8 @@ Send a request. Automatically dispatches to `sendFile()` or `sendStream()` based
 | `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Request timeout (ms), default 5000 |
 | `options.asyncTimeout` | `number` | Async timeout (ms), default 120000 |
+| `options.requireAck` | `boolean` | Whether to require server delivery ACK (default true). If false, skips ACK stage |
+| `options.streamTimeout` | `number` | Stream idle timeout (ms) while consuming `response.stream` (optional) |
 | `options.headers` | `object` | Request headers (optional) |
 | `options.cookies` | `object` | Request cookies (optional, merged with internally stored cookies, passed-in takes priority) |
 | `options.requestId` | `string` | Custom request ID (optional) |
@@ -895,6 +938,8 @@ Send file as request body (via stream; server receives File/Blob when autoResolv
 | `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Request timeout (ms), default 5000 |
 | `options.asyncTimeout` | `number` | Async timeout (ms), default 120000 |
+| `options.requireAck` | `boolean` | Whether to require server delivery ACK (default true). If false, skips ACK stage |
+| `options.streamTimeout` | `number` | Stream idle timeout (ms) while consuming `response.stream` (optional) |
 | `options.headers` | `object` | Request headers (optional) |
 | `options.cookies` | `object` | Request cookies (optional) |
 | `options.requestId` | `string` | Custom request ID (optional) |
@@ -916,6 +961,8 @@ Send stream as request body (server receives readable stream).
 | `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Request timeout (ms), default 5000 |
 | `options.asyncTimeout` | `number` | Async timeout (ms), default 120000 |
+| `options.requireAck` | `boolean` | Whether to require server delivery ACK (default true). If false, skips ACK stage |
+| `options.streamTimeout` | `number` | Stream idle timeout (ms) while consuming `response.stream` (optional) |
 | `options.headers` | `object` | Request headers (optional) |
 | `options.cookies` | `object` | Request cookies (optional) |
 | `options.requestId` | `string` | Custom request ID (optional) |
@@ -1064,6 +1111,8 @@ Destroy Server instance, remove all listeners.
 
 request-iframe provides React hooks for easy integration in React applications. Import hooks from `request-iframe/react`:
 
+> Note: React is only required if you use `request-iframe/react`. Installing `request-iframe` alone does not require React.
+
 ```typescript
 import { useClient, useServer, useServerHandler, useServerHandlerMap } from 'request-iframe/react';
 ```
@@ -1328,8 +1377,12 @@ const IframeComponent = () => {
 | `PROTOCOL_UNSUPPORTED` | Protocol version not supported |
 | `IFRAME_NOT_READY` | iframe not ready |
 | `STREAM_ERROR` | Stream transfer error |
+| `STREAM_TIMEOUT` | Stream idle timeout |
+| `STREAM_EXPIRED` | Stream expired (writable stream lifetime exceeded) |
 | `STREAM_CANCELLED` | Stream cancelled |
 | `STREAM_NOT_BOUND` | Stream not bound to request context |
+| `STREAM_START_TIMEOUT` | Stream start timeout (request body stream_start not received in time) |
+| `TOO_MANY_REQUESTS` | Too many concurrent requests (server-side limit) |
 
 ### Error Handling Example
 

package/esm/api/client.js

@@ -0,0 +1,79 @@
+import { getIframeTargetOrigin, generateInstanceId } from '../utils';
+import { RequestIframeClientServer } from '../core/client-server';
+import { RequestIframeClientImpl } from '../core/client';
+import { setupClientDebugInterceptors } from '../utils/debug';
+import { Messages, ErrorCode } from '../constants';
+
+/**
+ * Create a client (for sending requests)
+ * 
+ * Note:
+ * - MessageChannel is cached at the window level by secretKey (ensures unique message listener)
+ * - Client instances are not cached, a new instance is created on each call
+ * - This allows different versions of the library to coexist
+ */
+export function requestIframeClient(target, options) {
+  var targetWindow = null;
+  var targetOrigin = '*';
+  if (target.tagName === 'IFRAME') {
+    var iframe = target;
+    targetWindow = iframe.contentWindow;
+    targetOrigin = getIframeTargetOrigin(iframe);
+    if (!targetWindow) {
+      throw {
+        message: Messages.IFRAME_NOT_READY,
+        code: ErrorCode.IFRAME_NOT_READY
+      };
+    }
+  } else {
+    targetWindow = target;
+    targetOrigin = '*';
+  }
+
+  // Allow user to override targetOrigin explicitly
+  if (options !== null && options !== void 0 && options.targetOrigin) {
+    targetOrigin = options.targetOrigin;
+  }
+
+  // Determine secretKey
+  var secretKey = options === null || options === void 0 ? void 0 : options.secretKey;
+
+  // Generate instance ID first (will be used by both client and server)
+  var instanceId = generateInstanceId();
+
+  // Create ClientServer (internally obtains or creates a shared MessageChannel)
+  var server = new RequestIframeClientServer({
+    secretKey,
+    ackTimeout: options === null || options === void 0 ? void 0 : options.ackTimeout,
+    autoOpen: options === null || options === void 0 ? void 0 : options.autoOpen
+  }, instanceId);
+
+  // Create client instance
+  var client = new RequestIframeClientImpl(targetWindow, targetOrigin, server, {
+    secretKey,
+    ackTimeout: options === null || options === void 0 ? void 0 : options.ackTimeout,
+    timeout: options === null || options === void 0 ? void 0 : options.timeout,
+    asyncTimeout: options === null || options === void 0 ? void 0 : options.asyncTimeout,
+    returnData: options === null || options === void 0 ? void 0 : options.returnData,
+    headers: options === null || options === void 0 ? void 0 : options.headers,
+    allowedOrigins: options === null || options === void 0 ? void 0 : options.allowedOrigins,
+    validateOrigin: options === null || options === void 0 ? void 0 : options.validateOrigin
+  }, instanceId);
+
+  // If trace mode is enabled, register debug interceptors
+  if (options !== null && options !== void 0 && options.trace) {
+    setupClientDebugInterceptors(client);
+  }
+  return client;
+}
+
+/**
+ * Clear MessageChannel cache (for testing or reset)
+ * Note: This clears the shared message channel for the specified secretKey
+ */
+export function clearRequestIframeClientCache(secretKey) {
+  // Now client is no longer cached, only need to clear MessageChannel cache
+  // MessageChannel cleanup is handled by clearMessageChannelCache in cache.ts
+  // Empty implementation kept here to maintain API compatibility
+  void secretKey;
+}

package/esm/api/server.js

@@ -0,0 +1,59 @@
+import { RequestIframeServerImpl } from '../core/server';
+import { setupServerDebugListeners } from '../utils/debug';
+import { getCachedServer, cacheServer, clearServerCache } from '../utils/cache';
+
+/**
+ * Create a server (for receiving and handling requests)
+ * 
+ * Note:
+ * - MessageChannel is cached at the window level by secretKey (ensures unique message listener)
+ * - If options.id is specified, the server will be cached and reused (singleton pattern)
+ * - If options.id is not specified, a new instance is created on each call
+ * - This allows different versions of the library to coexist
+ */
+export function requestIframeServer(options) {
+  // Determine secretKey and id
+  var secretKey = options === null || options === void 0 ? void 0 : options.secretKey;
+  var id = options === null || options === void 0 ? void 0 : options.id;
+
+  // If id is specified, check cache first
+  if (id) {
+    var cached = getCachedServer(secretKey, id);
+    if (cached) {
+      return cached;
+    }
+  }
+
+  // Create server (internally obtains or creates a shared MessageChannel)
+  var server = new RequestIframeServerImpl({
+    secretKey,
+    id,
+    ackTimeout: options === null || options === void 0 ? void 0 : options.ackTimeout,
+    autoOpen: options === null || options === void 0 ? void 0 : options.autoOpen,
+    allowedOrigins: options === null || options === void 0 ? void 0 : options.allowedOrigins,
+    validateOrigin: options === null || options === void 0 ? void 0 : options.validateOrigin,
+    maxConcurrentRequestsPerClient: options === null || options === void 0 ? void 0 : options.maxConcurrentRequestsPerClient
+  });
+
+  // If trace mode is enabled, register debug listeners
+  if (options !== null && options !== void 0 && options.trace) {
+    setupServerDebugListeners(server);
+  }
+
+  // Cache server if id is specified
+  if (id) {
+    cacheServer(server, secretKey, id);
+  }
+  return server;
+}
+
+/**
+ * Clear server cache (for testing or reset)
+ * Note: This clears the cached server instances
+ */
+export function clearRequestIframeServerCache(secretKey) {
+  // Clear server cache
+  clearServerCache();
+  // MessageChannel cleanup is handled by clearMessageChannelCache in cache.ts
+  void secretKey;
+}