@hile/micro 2.0.7 → 2.0.15

package/README.md

@@ -108,20 +108,50 @@ const result = await response();
 
 ### 熔断器 (Circuit Breaker)
 
-`call()` 自动跟踪每个 namespace 下各 peer 的调用失败。失败的 peer 被临时排除，**30 秒冷卻期**后自动恢复。
+`call()` 和 `stream()` 自动跟踪每个 namespace 下各 peer 的调用结果。熔断状态保存在调用方 `Application` 的本地内存中，不依赖 Redis、数据库或 Registry 共享状态。
 
 | 场景 | 行为 |
 |------|------|
-| 调用 peer A 失败 | A 加入排除列表（30s cooldown） |
-| 再次调用该 namespace | Registry `/‑/find` 带上 `exclude`，返回其他 peer |
-| 所有 peer 都被排除 | 重置排除列表，重新从所有 peer 中选择 |
-| 调用成功 | 该 peer 从排除列表中移除 |
+| `closed` 状态调用失败 | 累计连续失败次数 |
+| 连续失败达到阈值 | peer 进入 `open`，选路时通过 Registry `exclude` 临时排除 |
+| 冷却时间到期 | peer 进入 `half-open`，只放行少量探测请求 |
+| `half-open` 探测成功 | 累计成功次数，达到阈值后恢复 `closed` |
+| `half-open` 探测失败 | 重新进入 `open`，冷却时间指数退避 |
+| 所有 `open` peer 都被排除 | 重置该 namespace 的本地熔断状态，重新选择 peer；若 Registry 不可用但已选中的缓存 Client 仍连接，则沿用缓存发起探测，避免完全饿死 |
 
-排除列表：
-- 键：`${host}:${port}`
-- 存储：`Map<namespace, Map<peerKey, openedAt>>`
-- 冷卻期：`CB_COOLDOWN_MS = 30_000`（30 秒）
-- 过期检查：`getActiveExcludes()` 在每次 `call()` 调用时执行
+如果 peer 正处于 `half-open` 且探测名额已满，本次调用不会占用额外探测名额；有其他 peer 时改选其他 peer，没有可用 peer 时需要在已有探测完成后再尝试。
+
+默认策略：
+
+| 配置 | 默认值 | 说明 |
+|------|--------|------|
+| `failureThreshold` | `3` | 连续失败 3 次后打开熔断 |
+| `failureWindowMs` | `60000` | 连续失败统计窗口 |
+| `successThreshold` | `2` | half-open 连续成功 2 次后恢复 |
+| `cooldownMs` | `10000` | 首次打开后的冷却时间 |
+| `maxCooldownMs` | `120000` | 指数退避冷却上限 |
+| `halfOpenMaxProbes` | `1` | half-open 同时放行的探测数 |
+
+可以在构造 `Application` 时覆盖：
+
+```typescript
+const app = new Application({
+  namespace: 'checkout',
+  registry: { host, port },
+  circuitBreaker: {
+    failureThreshold: 3,
+    failureWindowMs: 60_000,
+    successThreshold: 2,
+    cooldownMs: 10_000,
+    maxCooldownMs: 120_000,
+    halfOpenMaxProbes: 1,
+    shouldRecordFailure: (err) => true,
+    shouldRetry: (err) => true,
+  },
+});
+```
+
+`shouldRecordFailure` 返回 `false` 的错误不会计入熔断；`shouldRetry` 返回 `false` 的错误不会自动重试。可用它们区分业务错误和连接、超时等基础设施错误。
 
 ### 请求超时
 
@@ -136,8 +166,8 @@ const app = new Application({
 });
 
 // 单次调用覆盖
-await app.call('svc', '/api', data, 5_000);   // 5s 超时
-await app.call('svc', '/api', data, 1_000, 0); // 1s 超时, 不重试
+await app.call('svc', '/api', data, { timeout: 5_000 });          // 5s 超时, 默认重试 1 次
+await app.call('svc', '/api', data, { timeout: 1_000, retries: 0 }); // 1s 超时, 不重试
 ```
 
 超时触发时，底层 MessageModem 会向对端发送 **ABORT** 消息取消远程执行。
@@ -169,12 +199,51 @@ try {
 `call()` 默认 retries=1，失败后自动换 peer 重试：
 
 ```typescript
-await app.call('svc', '/api', data);        // 默认重试 1 次
-await app.call('svc', '/api', data, 5000, 3); // 超时 5s, 重试 3 次
-await app.call('svc', '/api', data, 5000, 0); // 超时 5s, 不重试
+await app.call('svc', '/api', data);                          // 默认重试 1 次
+await app.call('svc', '/api', data, { timeout: 5000, retries: 3 }); // 超时 5s, 重试 3 次
+await app.call('svc', '/api', data, { timeout: 5000, retries: 0 }); // 超时 5s, 不重试
 ```
 
-重试策略：失败 → `recordFailure`（peer 被排除）→ 递归 `call(retries-1)` → `getActiveExcludes` 排除已失败的 peer → Registry `/‑/find` 返回其他 peer。
+重试策略：失败 → 按 `shouldRecordFailure` 更新本地熔断状态 → 按 `shouldRetry` 判断是否继续下一次尝试 → 下次发现服务时用 `getActiveExcludes()` 排除 `open` 或探测名额已满的 `half-open` peer → Registry `/‑/find` 返回其他 peer。
+
+### 流式调用 (Stream)
+
+`stream()` 用于**需要持续推送数据**的场景：大数据集、实时事件、LLM token 流、进度上报等。不需要流式传输时优先用 `call()`。
+
+**Provider 侧**：消息处理器必须返回 async generator（`async function*`）。
+
+```typescript
+// 通过 register() 注册
+app.register('/events', async function* () {
+  for (let i = 0; i < 100; i++) {
+    yield { seq: i, time: Date.now() }
+    await new Promise(r => setTimeout(r, 100))
+  }
+})
+
+// 或通过 .msg 文件定义（推荐）
+// src/messages/events.msg.ts
+import { defineMessage } from '@hile/message-loader'
+export default defineMessage(async function* ({ data }) {
+  for (const item of await fetchItems(data.query)) {
+    yield item
+  }
+})
+```
+
+**Consumer 侧**：`app.stream()` 返回 `Readable` stream，可用 `for await` 逐 chunk 消费。
+
+```typescript
+const stream = await app.stream('data-svc', '/events', { query: 'recent' })
+for await (const chunk of stream) {
+  console.log(chunk)  // { seq: 0, time: 1718000000000 }
+}
+```
+
+**注意事项**：
+- 普通 handler（返回非 async iterable）被 `stream()` 调用时会报错 `"Invalid async iterable"`
+- 不需要流式传输时用 `call()`，不要用 `stream()` 取单次返回值
+- `stream()` 享有与 `call()` 相同的选路与熔断；同步建流失败可按 `retries` 重试，流已返回后的异步错误会计入熔断但不会自动重放流
 
 ### 健康检查
 
@@ -197,7 +266,7 @@ const health = await app.dispatch('/-/health', {});
 
 ### 缓存降级
 
-当 Registry 不可用但本地仍有已缓存的 Client 连接时，`get()` 自动降级使用缓存：
+当 Registry 不可用但本地仍有已缓存的 Client 连接时，`get()` 自动降级使用缓存。熔断器在“所有 `open` peer 都被排除”并触发本地 reset 时，也会保留已经选中的可用缓存 Client，不会因为 Registry 短暂不可用而丢弃仍可通信的连接。
 
 | 场景 | 行为 |
 |------|------|
@@ -363,10 +432,25 @@ class Application extends Server {
     namespace: string,
     url: string,
     data: any,
-    timeout?: number,     // 请求超时（ms），默认 requestTimeoutMs
-    retries?: number,     // 失败重试次数，默认 1
+    options?: {
+      timeout?: number,     // 请求超时（ms），默认 requestTimeoutMs
+      retries?: number,     // 失败重试次数，默认 1
+      signal?: AbortSignal, // 手动取消
+    },
   ): Promise<T>;
 
+  // 流式调用：get + stream + 熔断；同步建流失败可重试
+  // provider handler 必须返回 async generator，consumer 获得 Readable stream
+  stream(
+    namespace: string,
+    url: string,
+    data: any,
+    options?: {
+      signal?: AbortSignal,
+      retries?: number,     // 失败重试次数，默认 1
+    },
+  ): Promise<import('stream').Readable>;
+
   // 注册路由（provider 侧）
   register<T = any>(url: string, handler: (ctx) => Promise<T>): () => void;
 
@@ -410,6 +494,7 @@ class Server extends MessageLoader {
 class Client extends MessageWs {
   request(url: string, data: any, timeout?: number): { abort(): void; response<T>(): Promise<T> };
   push(url: string, data: any, timeout?: number): void;
+  stream(url: string, data: any, options?: { signal?: AbortSignal }): Readable;
   dispose(): void;
 }
 ```

package/dist/application.d.ts

@@ -15,6 +15,28 @@ type EnvRequestResult<T extends Record<string, Record<string, any>>, R> = R exte
 } ? {
     [K in N]: EnvFieldsForRequest<T, N, F>;
 } : never;
+export type CircuitBreakerStatus = 'closed' | 'open' | 'half-open';
+export type CircuitBreakerOptions = {
+    /** 连续失败达到阈值后打开熔断器，默认 3 */
+    failureThreshold?: number;
+    /** 连续失败统计窗口（毫秒），默认 60000 */
+    failureWindowMs?: number;
+    /** half-open 探测连续成功达到阈值后恢复，默认 2 */
+    successThreshold?: number;
+    /** 首次打开后的冷却时间（毫秒），默认 10000 */
+    cooldownMs?: number;
+    /** 指数退避冷却时间上限（毫秒），默认 120000 */
+    maxCooldownMs?: number;
+    /** half-open 状态下同时放行的探测请求数，默认 1 */
+    halfOpenMaxProbes?: number;
+    /** 返回 false 的错误不会计入熔断，默认全部计入 */
+    shouldRecordFailure?: (err: unknown) => boolean;
+    /** 返回 false 的错误不会自动重试，默认全部允许重试 */
+    shouldRetry?: (err: unknown) => boolean;
+};
+type RegistryLookupOptions = {
+    allowExcludedCachedFallback?: boolean;
+};
 export type GetEnvVariablesResult<T extends Record<string, Record<string, any>>, Requests extends readonly EnvRequest<T>[]> = UnionToIntersection<EnvRequestResult<T, Requests[number]>>;
 export type ApplicationProps = {
     namespace: string;
@@ -23,30 +45,68 @@ export type ApplicationProps = {
     registryLookupTimeoutMs?: number;
     /** 单次 request() 等待响应的上限（毫秒），默认 `30000` */
     requestTimeoutMs?: number;
+    /** 本地内存熔断策略配置 */
+    circuitBreaker?: CircuitBreakerOptions;
 } & MicroServerProps;
 export declare class Application extends Server {
     private registry?;
     private reconnectTimeout?;
     private registryReconnectPromise;
+    private registryReconnectGeneration;
     /** 为 true 时不再向 Registry 重连（listen 返回的 teardown 已触发） */
     private stopped;
+    private listenGeneration;
     private readonly _registry_address;
     private readonly _registryLookupTimeoutMs;
     private readonly _requestTimeoutMs;
+    private readonly _circuitBreaker;
     private readonly namespaces;
-    private static readonly CB_COOLDOWN_MS;
     private readonly circuitBreakers;
-    private readonly fallbacks;
     private readonly topics;
+    private readonly publishedTopics;
+    private readonly publishedTopicRevisions;
+    private readonly publishedTopicDirty;
+    private readonly publishedTopicVersions;
+    private readonly publishedTopicSignatures;
+    private readonly topicSyncs;
+    private readonly topicUpdateVersions;
+    private publishIntentVersion;
     constructor(props: ApplicationProps);
+    private dispatchTopicUpdate;
     listen(port?: number): Promise<() => Promise<void>>;
     private scheduleRegistryRetry;
+    private canUsePubSub;
+    private assertCanUsePubSub;
+    private ensureRegistryReconnectScheduled;
+    private handleRegistrySyncFailure;
+    private registryRequestOptions;
+    private recordPublishedTopic;
+    private enqueueTopicSync;
+    private syncPublishedTopic;
+    private syncUnpublishedTopic;
+    private syncUnsubscribedTopic;
+    private syncRestoredSubscription;
+    private restoreSubscription;
+    private rollbackLocalSubscription;
     private reconnectToRegistry;
+    private peerKey;
+    private getPeerStates;
+    private getOrCreatePeerState;
+    private deletePeerState;
+    private openCircuit;
+    private acquireCircuitProbe;
+    private shouldRecordCircuitFailure;
+    private shouldRetryCircuitFailure;
     private recordSuccess;
     private recordFailure;
+    private getActiveCircuitExcludes;
     private getActiveExcludes;
+    private trackCircuitStream;
+    private selectCircuitClient;
+    private selectCircuitProbe;
     private findFromRegistry;
     get(namespace: string, exclude?: string[]): Promise<Client>;
+    protected resolveClient(namespace: string, exclude?: string[], options?: RegistryLookupOptions): Promise<Client>;
     call<T = any>(namespace: string, url: string, data: any, options?: {
         timeout?: number;
         retries?: number;
@@ -60,7 +120,10 @@ export declare class Application extends Server {
         update: (payload: T) => Promise</*elided*/ any>;
         unpublish: () => Promise</*elided*/ any>;
     }>;
-    /** 对同一 topic 重复 subscribe 是幂等的：第二次调用只返回 unsubscribe 函数，不会注册第二个 callback */
+    /**
+     * 对同一 topic 可多次 subscribe，各自独立回调。
+     * 传入同一个 callback 引用第二次调用时幂等返回 unsubscribe，不重复注册。
+     */
     subscribe<T = any>(topic: string, callback: (data: T) => any, isReconnect?: boolean): Promise<() => Promise<void>>;
 }
 export {};