@hile/micro 1.0.8 → 1.0.10

package/README.md

@@ -1,6 +1,6 @@
 # @hile/micro
 
-基于 `@hile/message-loader` 与 `@hile/message-ws` 的轻量级 **WebSocket 微服务框架**。提供服务注册与发现、心跳保活、熔断、请求超时、自动重试、调用链路追踪等功能。
+基于 `@hile/message-loader` 与 `@hile/message-ws` 的轻量级 **WebSocket 微服务框架**。提供服务注册与发现、心跳保活、熔断、请求超时、自动重试等功能。
 
 ## 架构分层
 
@@ -16,7 +16,7 @@ MessageLoader (路由) + MessageWs (请求/响应传输)
 | **Server** | WebSocket 监听、连接管理、消息路由。不关心注册中心 |
 | **Client** | 远端 Server 的代理，提供 `request()` / `push()` 通信接口 |
 | **Registry** | 注册中心。维护 namespace → 实例列表，心跳检测剔除死实例 |
-| **Application** | 应用服务。集成注册发现、熔断、重试、追踪等功能 |
+| **Application** | 应用服务。集成注册发现、熔断、重试等功能 |
 
 一个 `Application` 实例 **同时** 扮演 provider（`register` 暴露接口）和 consumer（`get` / `call` 调用其它服务）。
 
@@ -176,28 +176,6 @@ await app.call('svc', '/api', data, 5000, 0); // 超时 5s, 不重试
 
 重试策略：失败 → `recordFailure`（peer 被排除）→ 递归 `call(retries-1)` → `getActiveExcludes` 排除已失败的 peer → Registry `/‑/find` 返回其他 peer。
 
-### Correlation ID 链路追踪
-
-`call()` 自动为每次调用注入唯一 `_correlationId`：
-
-```typescript
-provider.register('/api', async ({ data }) => {
-  console.log(data._correlationId); // 自动注入的 UUID
-});
-```
-
-行为规则：
-
-| 入参 data | 结果 |
-|-----------|------|
-| `null / undefined` | 包装为 `{ _correlationId, data: null }` |
-| 字符串 / 数字 | 包装为 `{ _correlationId, data: '原始值' }` |
-| 数组 | 包装为 `{ _correlationId, data: [原始数组] }` |
-| `{ value: 1 }` (无 `_correlationId`) | 扩展为 `{ value: 1, _correlationId: 'uuid' }` |
-| `{ _correlationId: 'trace-1' }` | 保留已有 ID，**不覆盖** |
-
-> **注意：** 原 data 对象不会被修改（使用浅拷贝 `{ ...data, _correlationId }`）。
-
 ### 健康检查
 
 每个 `Application` 自动注册 `/-/health` 端点：
@@ -380,7 +358,7 @@ class Application extends Server {
   // 获取 namespace 对应的远端 Client（缓存 + 自动发现）
   get(namespace: string, exclude?: string[]): Promise<Client>;
 
-  // 一站式调用：get + request + response + 熔断 + 重试 + 追踪
+  // 一站式调用：get + request + response + 熔断 + 重试
   call<T = any>(
     namespace: string,
     url: string,

package/SKILL.md

@@ -30,7 +30,7 @@ description: Code generation and contribution rules for @hile/micro. Use when ed
 | `Server` | `server.ts` | WebSocketServer 生命周期, 出入站连接, Client Map | 不感知 Registry |
 | `Client` | `client.ts` | 远端 Server 的 WebSocket 会话代理 | `dispose()` 必须关闭底层 socket |
 | `Registry` | `registry.ts` | namespace → Set\<host:port\>, 心跳检测, /-/find 随机返回, 环境变量管理 | 自动创建 `~/.registry/` 工作目录 |
-| `Application` | `application.ts` | 注册发现 + 熔断 + 重试 + 追踪 + 心跳 + 远程环境变量读取 | `listen()` 后自动连 Registry |
+| `Application` | `application.ts` | 注册发现 + 熔断 + 重试 + 心跳 + 远程环境变量读取 | `listen()` 后自动连 Registry |
 
 ### 应用模型
 
@@ -142,7 +142,7 @@ export class Application extends Server {
   listen(port: number): Promise<() => Promise<void>>; // 自动连 Registry + 启心跳
 
   get(namespace: string, exclude?: string[]): Promise<Client>;
-  // call() = get + request + response + correlationId + 熔断 + 重试 + 超时
+  // call() = get + request + response + 熔断 + 重试 + 超时
   call<T = any>(
     namespace: string,
     url: string,
@@ -226,27 +226,7 @@ peer 首次失败
 
 **冷卻期:** `CB_COOLDOWN_MS = 30000` (30 秒)。到期后 `getActiveExcludes` 自动清除旧条目。
 
-### 3.3 Correlation ID
-
-`call()` 自动处理 `_correlationId`：
-
-```typescript
-// 非对象/假值/数组 → 包装
-!data || typeof data !== 'object' || Array.isArray(data)
-  → data = { _correlationId: randomUUID(), data }
-
-// 对象无 _correlationId → 浅拷贝注入
-else if (!data._correlationId)
-  → data = { ...data, _correlationId: randomUUID() }
-
-// 对象已有 _correlationId → 保留（透传）
-```
-
-- 使用 `import { randomUUID } from 'node:crypto'`（Node >= 14.17）
-- 永远不修改原始 data 对象（浅拷贝 `{ ...data }`）
-- retry 递归时 data 已包含 `_correlationId`，自动透传
-
-### 3.4 请求超时
+### 3.3 请求超时
 
 **配置链：**
 
@@ -547,8 +527,6 @@ pnpm --filter @hile/micro test     # 必须全部通过
 | call() 基本调用 | `circuit breaker > call() returns data on success` |
 | 熔断排除 | `circuit breaker > excludes a failing peer and selects a different one` |
 | 全排除重置 | `circuit breaker > resets breaker when all peers are excluded` |
-| Correlation ID 注入 | `correlation ID > injects _correlationId into call() data` |
-| Correlation ID 透传 | `correlation ID > preserves existing _correlationId` |
 | 健康检查 | `health endpoint > /-/health returns status and registry state` |
 | 超时 reject | `request timeout > rejects when request exceeds the timeout` |
 | 超时充足则成功 | `request timeout > succeeds when timeout is long enough` |
@@ -585,9 +563,8 @@ pnpm --filter @hile/micro test     # 必须全部通过
 3. **不要在 `Client.dispose()` 中删除 `socket.close()`**（会导致 WebSocketServer.close 长时间等待）
 4. **不要假设 `host:port` 可无损表达 IPv6** — 使用 `[IPv6]:port` 格式，`parseAddressKey` 按最后一个 `:` 切分
 5. **不要传错 Registry 端口** — 丢失 Registry 连接时依赖 `reconnectToRegistry`，不要在外部缓存 registry Client
-6. **不要在 call() 中修改原始 data 对象** — 必须使用浅拷贝 `{ ...data, _correlationId }`
-7. **不要在其他文件中重复 Registry 的 helper 函数** — `selectRandomRegistryAddress`、`parseAddressKey`、`getRegistryConfigsDir`、`namespaceToConfigFile`、`parseConfigFilename` 都在 `registry.ts` 中导出复用
-8. **不要给 call() 增加非可选参数** — `timeout` 和 `retries` 都在尾部且保持可选，不影响现有调用
+6. **不要在其他文件中重复 Registry 的 helper 函数** — `selectRandomRegistryAddress`、`parseAddressKey`、`getRegistryConfigsDir`、`namespaceToConfigFile`、`parseConfigFilename` 都在 `registry.ts` 中导出复用
+7. **不要给 call() 增加非可选参数** — `timeout` 和 `retries` 都在尾部且保持可选，不影响现有调用
 
 ---
 
@@ -617,7 +594,7 @@ pnpm --filter @hile/micro test     # 必须全部通过
 |------|------|
 | `packages/micro/src/registry.ts` | 注册中心（含配置管理、路径工具函数） |
 | `packages/micro/src/application.ts` | 应用服务（含 getEnvVariables） |
-| `packages/micro/src/index.test.ts` | 主测试文件（28 个用例） |
+| `packages/micro/src/index.test.ts` | 主测试文件（27 个用例） |
 | `packages/micro/src/env-config.test.ts` | 配置管理测试文件（13 个用例） |
 | `packages/cli/src/index.ts` | CLI 入口（含 registry configs 子命令组） |
 | `packages/cli/src/configs.ts` | CLI 配置管理 handler（list/get/set/del） |

package/dist/application.d.ts

@@ -34,16 +34,12 @@ export declare class Application extends Server {
     private readonly _registryLookupTimeoutMs;
     private readonly _requestTimeoutMs;
     private readonly namespaces;
-    private static readonly HEARTBEAT_INTERVAL;
-    private heartbeatTimer?;
     private static readonly CB_COOLDOWN_MS;
     private readonly circuitBreakers;
     constructor(props: ApplicationProps);
     listen(port?: number): Promise<() => Promise<void>>;
     private scheduleRegistryRetry;
     private reconnectToRegistry;
-    private startHeartbeat;
-    private stopHeartbeat;
     private recordSuccess;
     private recordFailure;
     private getActiveExcludes;

package/dist/application.js

@@ -1,4 +1,3 @@
-import { randomUUID } from 'node:crypto';
 import { Server } from './server.js';
 var RegistryLookupStatus;
 (function (RegistryLookupStatus) {
@@ -46,8 +45,6 @@ export class Application extends Server {
     _registryLookupTimeoutMs;
     _requestTimeoutMs;
     namespaces = new Map();
-    static HEARTBEAT_INTERVAL = 10000;
-    heartbeatTimer;
     static CB_COOLDOWN_MS = 30_000;
     circuitBreakers = new Map();
     constructor(props) {
@@ -69,7 +66,6 @@ export class Application extends Server {
         const callback = await super.listen(port);
         try {
             await this.reconnectToRegistry();
-            this.startHeartbeat();
         }
         catch (err) {
             try {
@@ -82,7 +78,6 @@ export class Application extends Server {
         }
         return async () => {
             this.stopped = true;
-            this.stopHeartbeat();
             if (this.reconnectTimeout) {
                 clearTimeout(this.reconnectTimeout);
                 this.reconnectTimeout = undefined;
@@ -134,25 +129,6 @@ export class Application extends Server {
         });
         return this.registryReconnectPromise;
     }
-    startHeartbeat() {
-        this.stopHeartbeat();
-        this.heartbeatTimer = setInterval(() => {
-            if (!this.registry)
-                return;
-            try {
-                this.registry.push('/-/heartbeat', {});
-            }
-            catch {
-                // registry connection may have dropped between null-check and push
-            }
-        }, Application.HEARTBEAT_INTERVAL);
-    }
-    stopHeartbeat() {
-        if (this.heartbeatTimer) {
-            clearInterval(this.heartbeatTimer);
-            this.heartbeatTimer = undefined;
-        }
-    }
     recordSuccess(ns, host, port) {
         const excludes = this.circuitBreakers.get(ns);
         if (excludes) {
@@ -263,13 +239,6 @@ export class Application extends Server {
         });
     }
     async call(namespace, url, data, timeout, retries = 1) {
-        // Inject or preserve correlation ID (no mutation of original data)
-        if (!data || typeof data !== 'object' || Array.isArray(data)) {
-            data = { _correlationId: randomUUID(), data };
-        }
-        else if (!data._correlationId) {
-            data = { ...data, _correlationId: randomUUID() };
-        }
         const exclude = this.getActiveExcludes(namespace);
         let client;
         try {

package/dist/client.d.ts

@@ -14,8 +14,12 @@ export declare class Client extends MessageWs {
     readonly host: string;
     readonly port: number;
     private _online;
+    private lastHeartbeat;
+    private heartbeatTimer?;
+    private checkTimer?;
     readonly events: EventEmitter<any>;
     constructor(props: ClientProps);
+    private startHeartbeat;
     protected exec(data: {
         url: string;
         data: any;

package/dist/client.js

@@ -7,6 +7,9 @@ export class Client extends MessageWs {
     host;
     port;
     _online = true;
+    lastHeartbeat = Date.now();
+    heartbeatTimer;
+    checkTimer;
     events = new EventEmitter();
     constructor(props) {
         const { server, ws, host, port } = props;
@@ -17,8 +20,32 @@ export class Client extends MessageWs {
         this.port = port;
         this.events.on('connect', () => this._online = true);
         this.events.on('disconnect', () => this._online = false);
+        this.lastHeartbeat = Date.now();
+        this.startHeartbeat();
+    }
+    startHeartbeat() {
+        const interval = Number(process.env.MICRO_HEARTBEAT_INTERVAL) || 10_000;
+        const timeout = Number(process.env.MICRO_HEARTBEAT_TIMEOUT) || 20_000;
+        const checkInterval = Number(process.env.MICRO_HEARTBEAT_CHECK_INTERVAL) || 5_000;
+        this.heartbeatTimer = setInterval(() => {
+            try {
+                this._push({ url: '/-/heartbeat', data: {} });
+            }
+            catch {
+                // connection closed — will be cleaned up by checkTimer or close event
+            }
+        }, interval);
+        this.checkTimer = setInterval(() => {
+            if (Date.now() - this.lastHeartbeat > timeout) {
+                this.dispose();
+            }
+        }, checkInterval);
     }
     async exec(data) {
+        if (data.url === '/-/heartbeat') {
+            this.lastHeartbeat = Date.now();
+            return;
+        }
         if (!this._online)
             throw new Error('Client is not online');
         return this.server.dispatch(data.url, data.data, {
@@ -36,6 +63,10 @@ export class Client extends MessageWs {
         return this._push({ url, data }, timeout);
     }
     dispose() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        if (this.checkTimer)
+            clearInterval(this.checkTimer);
         super.dispose();
         if (this.socket.readyState === WebSocket.OPEN || this.socket.readyState === WebSocket.CONNECTING) {
             this.socket.close();

package/dist/registry.d.ts

@@ -16,9 +16,6 @@ export declare function parseConfigFilename(filename: string): string | null;
 export declare class Registry extends Server {
     private readonly namespaces;
     private unregisterFind?;
-    private static readonly HEARTBEAT_INTERVAL;
-    private static readonly HEARTBEAT_TIMEOUT;
-    private readonly heartbeats;
     private readonly workspace;
     private readonly configFileSuffix;
     private readonly configs;

package/dist/registry.js

@@ -42,9 +42,6 @@ export function parseConfigFilename(filename) {
 export class Registry extends Server {
     namespaces = new Map();
     unregisterFind;
-    static HEARTBEAT_INTERVAL = 1000;
-    static HEARTBEAT_TIMEOUT = 20000;
-    heartbeats = new Map();
     workspace;
     configFileSuffix = '.config.yaml';
     configs = new Map();
@@ -57,7 +54,6 @@ export class Registry extends Server {
         this.workspace = workspace;
         this.events.on('connect', (client, extras) => {
             const key = client.host + ':' + client.port;
-            this.heartbeats.set(key, Date.now());
             const namespace = extras.join('/');
             if (!this.namespaces.has(namespace)) {
                 this.namespaces.set(namespace, new Set());
@@ -66,7 +62,6 @@ export class Registry extends Server {
         });
         this.events.on('disconnect', (client, extras) => {
             const key = client.host + ':' + client.port;
-            this.heartbeats.delete(key);
             const namespace = extras.join('/');
             if (this.namespaces.has(namespace)) {
                 const keys = this.namespaces.get(namespace);
@@ -80,12 +75,6 @@ export class Registry extends Server {
         });
         this.mountFindHandler();
         this.registerEnvVariables();
-        this.register('/-/heartbeat', async ({ client }) => {
-            if (!client)
-                return;
-            const key = client.host + ':' + client.port;
-            this.heartbeats.set(key, Date.now());
-        });
     }
     watchEnvFile() {
         const configFile = resolve(this.workspace, 'configs');
@@ -104,8 +93,14 @@ export class Registry extends Server {
         return watch(configFile, (_, filename) => {
             if (!filename?.endsWith(this.configFileSuffix))
                 return;
+            const fullPath = resolve(configFile, filename);
+            // 文件被删除（或重命名）：移除对应配置
+            if (!existsSync(fullPath)) {
+                this.configs.delete(parseConfigFilename(filename));
+                return;
+            }
             try {
-                const config = YAML.parse(readFileSync(resolve(configFile, filename), 'utf8'));
+                const config = YAML.parse(readFileSync(fullPath, 'utf8'));
                 if (typeof config !== 'object' || config === null)
                     return;
                 this.configs.set(parseConfigFilename(filename), config);
@@ -119,23 +114,10 @@ export class Registry extends Server {
         if (!_port || _port <= 0)
             throw new Error('Unable to resolve registry port: pass `port` in constructor options, or ensure process.env.REGISTRY_PORT is set.');
         const teardown = await super.listen(_port);
-        const timer = setInterval(() => {
-            const now = Date.now();
-            for (const [key, lastTime] of this.heartbeats) {
-                if (now - lastTime >= Registry.HEARTBEAT_TIMEOUT) {
-                    const client = this.clients.get(key);
-                    if (client) {
-                        this.heartbeats.delete(key);
-                        client.dispose();
-                    }
-                }
-            }
-        }, Registry.HEARTBEAT_INTERVAL);
         const watcher = this.watchEnvFile();
         return async () => {
             if (watcher)
                 watcher.close();
-            clearInterval(timer);
             await teardown();
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/micro",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -23,11 +23,11 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/message-loader": "^1.0.8",
+    "@hile/message-loader": "^1.0.9",
     "@hile/message-ws": "^1.0.6",
     "internal-ip": "^9.0.0",
     "ws": "^8.19.0",
     "yaml": "^2.9.0"
   },
-  "gitHead": "6c83f2e29de07a48e8467456b56351d304e45932"
+  "gitHead": "be31521d206109a1ed6e915ec231a849870b538c"
 }