@hile/micro 1.0.3 → 1.0.4

package/README.md

@@ -2,6 +2,14 @@
 
 基于 `@hile/message-loader` 与 `@hile/message-ws` 的轻量级 **WebSocket 服务注册与发现**：用固定格式的连接 URL 标识对端，`Registry` 按逻辑 namespace 记录实例，`Application` 从注册中心拉取地址并缓存到远端服务的会话。
 
+## 概念分层
+
+1. **`Server`**：实现「服务」的 **底层协议与运行时**——基于 `ws` 监听、按路径解析对端身份，对内用 `MessageLoader` 做 `{ url, data }` 路由；不关心注册中心，只负责连接语义与消息派发。
+2. **`Registry`**：**注册中心**，维护「逻辑 namespace → 一组实例地址」，`/-/find` 随机返回其一。
+3. **`Application`**：**基于 `Server` 的具体应用侧实现**——继承 `Server`，在 `listen` 后自动连上 `Registry`，用 `get(namespace)` 发现其它服务并缓存 `Client`。
+
+同一进程里通常只建一个 `Application`，它 **同时** 扮演 **provider**（`register` 暴露接口）与 **consumer**（`get` + `request`/`push` 调用其它 namespace）；文档里把「提供方 / 调用方」拆开示例，是为了说明两种用法，而不是两类不同的类。
+
 ## 安装
 
 ```bash
@@ -16,16 +24,18 @@ pnpm add @hile/micro
 
 | 组件 | 作用 |
 |------|------|
-| `Server` | 监听 WebSocket；解析路径中的调用方地址与可选分段；对内用 `register`/`dispatch` 处理 `{ url, data }` |
+| `Server` | **底层协议**：监听 WebSocket；解析路径中的调用方地址与可选分段；对内用 `register`/`dispatch` 处理 `{ url, data }` |
 | `Client` | 连到远端 `Server`，`request`/`push` 走 `MessageModem`，`dispose()` 会关闭底层连接 |
-| `Registry` | 固定 namespace `'registry'`；实例上线/下线更新 namespace→地址集合；`/-/find` **随机** 返回其中一个地址 |
-| `Application` | 启动后连接 Registry；`get(ns)` 查询并 **缓存** 到目标服务的 `Client`，断连后清空缓存 |
+| `Registry` | **注册中心**：固定 namespace `'registry'`；实例上线/下线更新 namespace→地址集合；`/-/find` **随机** 返回其中一个地址 |
+| `Application` | **基于 `Server` 的应用实现**：启动后连接 Registry；`register` 侧即 provider、`get` 侧即 consumer；`get(ns)` 查询并 **缓存** 到目标服务的 `Client`，断连后清空缓存 |
 
 连接串格式（出站）：
 
-`ws://目标主机:端口/{本机广告IPv4}/{本机监听端口}/{本机namespace}`
+`ws://目标主机:端口/{宣告地址}/{本机监听端口}/{本机namespace}`
+
+宣告地址：构造 `Server` / `Application` / `Registry` 时可通过 **`advertiseHost`** 显式传入；未传则使用 `getLocalIPv4()`。若二者皆无（例如无可用 IPv4），**构造阶段即抛错**。容器、多网卡或 CI 环境建议设置 `advertiseHost`（如 `127.0.0.1` 或 Pod IP）。
 
-其中广告 IPv4 由 `getLocalIPv4()` 取第一个非回环网卡地址；多网卡或容器环境可能需要后续版本支持显式 `advertiseHost`（当前未暴露）。
+`Application` 还支持 **`registryLookupTimeoutMs`**（默认 `10000`），限制对 Registry `/-/find` 的响应等待时间。
 
 出站 `connect` 默认 **5 秒**握手超时，超时报错 `Connection timeout`。
 
@@ -38,7 +48,7 @@ pnpm add @hile/micro
 ```typescript
 import { Registry } from '@hile/micro';
 
-const registry = new Registry();
+const registry = new Registry({ advertiseHost: '127.0.0.1' });
 await registry.listen(9000);
 ```
 
@@ -50,6 +60,7 @@ import { Application } from '@hile/micro';
 const provider = new Application({
   namespace: 'payments',
   registry: { host: '127.0.0.1', port: 9000 },
+  advertiseHost: '127.0.0.1',
 });
 
 await provider.listen(9100);
@@ -67,6 +78,7 @@ import { Application } from '@hile/micro';
 const consumer = new Application({
   namespace: 'checkout',
   registry: { host: '127.0.0.1', port: 9000 },
+  advertiseHost: '127.0.0.1',
 });
 
 await consumer.listen(9200);

package/SKILL.md

@@ -11,20 +11,22 @@ description: Code generation and contribution rules for @hile/micro. Use when ed
 
 ## 1. 架构总览
 
-`@hile/micro` 在 `@hile/message-loader` + `@hile/message-ws` 之上提供 **轻量级进程间服务发现与会话**：
+`@hile/micro` 在 `@hile/message-loader` + `@hile/message-ws` 之上提供 **轻量级进程间服务发现与会话**。分层理解：
 
-- **`Server`**：基于 `ws` 的 `WebSocketServer`，用 **URL 路径** 携带对端身份与命名空间；对内用 `MessageLoader.register` / `dispatch` 处理消息路由。
+- **`Server`**：实现服务的 **底层协议与运行时**——`WebSocketServer` + 路径约定；对内 `MessageLoader.register` / `dispatch` 完成 `{ url, data }` 路由。不包含注册中心逻辑。
+- **`Registry`**：**注册中心**，固定 `namespace` 为 `'registry'`，维护「逻辑 namespace → 一组 `host:port`」；`/-/find` 在集合中 **随机** 返回一条地址（见 `selectRandomRegistryAddress`）。
+- **`Application`**：**基于 `Server` 的应用侧实现**（`extends Server`）；`listen(port)` 后自动 `connect` 到注册中心；`get(targetNamespace)` 向注册中心查询并 **缓存** 到目标服务的 `Client`，目标断连后删除缓存以便下次重新发现。
 - **`Client`**：连接到远端 `Server`，`request(url, data)` / `push(url, data)` 将负载交给本端 `Server.dispatch`；`dispose()` 会移除监听并 **关闭底层 WebSocket**，避免 `listen` 关闭阶段挂住。
-- **`Registry`**：固定 `namespace` 为 `'registry'`，维护「逻辑 namespace → 一组 `host:port`」；`/-/find` 在集合中 **随机** 返回一条地址（见 `selectRandomRegistryAddress`）。
-- **`Application`**：`Server` 的子类；`listen(port)` 后自动 `connect` 到注册中心；`get(targetNamespace)` 向注册中心查询并 **缓存** 到目标服务的 `Client`，目标断连后删除缓存以便下次重新发现。
+
+**应用模型**：`Application = provider + consumer`——同一实例既可 `register(...)`（对外提供能力），也可 `get(ns)` 再 `request`/`push`（消费其它 namespace）。文档示例常拆成两个进程分别演示 provider / consumer，API 层面仍是同一个类。
 
 依赖链：
 
 ```
 MessageLoader (路由) + MessageWs (请求/响应传输)
-  └── Server / Client
-        ├── Registry
-        └── Application
+  └── Server（底层协议）+ Client
+        ├── Registry（注册中心，一种特殊的 Server 用法）
+        └── Application（基于 Server，叠加上注册发现）
 ```
 
 ---
@@ -62,27 +64,28 @@ ws://{host}:{port}/${this.ipv4}/${this.port}/${this.namespace}
 ## 3. 类型与关键 API（生成代码须一致）
 
 ```typescript
-// registry.ts
-export interface RegistryFindData {
-  namespace: string;
-}
+// server.ts
+export type MicroServerProps = MessageLoaderProps & {
+  /** 出站 URL 宣告段；缺省 getLocalIPv4()，皆无则构造抛错 */
+  advertiseHost?: string;
+};
 
-export interface RegistryAddress {
-  host: string;
-  port: number;
-}
+// registry.ts
+export function parseAddressKey(key: string): RegistryAddress | undefined;
 
 export function selectRandomRegistryAddress(
   keys: Iterable<string>,
 ): RegistryAddress | undefined;
 
-export class Registry extends Server { /* ... */ }
+export class Registry extends Server { /* constructor(props?: MicroServerProps); onFind() 幂等 */ }
 
 // application.ts
 export type ApplicationProps = {
   namespace: string;
   registry: RegistryAddress;
-} & MessageLoaderProps;
+  /** 默认 10000；对 `/-/find` 的 response 等待上限 */
+  registryLookupTimeoutMs?: number;
+} & MicroServerProps;
 
 export class Application extends Server {
   listen(port: number): Promise<() => Promise<void>>;
@@ -109,7 +112,7 @@ export class Client extends MessageWs {
 ### 4.1 Registry 服务端
 
 ```typescript
-const registry = new Registry();
+const registry = new Registry({ advertiseHost: '127.0.0.1' });
 const dispose = await registry.listen(registryPort);
 // shutdown: await dispose();
 ```
@@ -120,6 +123,7 @@ const dispose = await registry.listen(registryPort);
 const app = new Application({
   namespace: 'my-service',
   registry: { host: '127.0.0.1', port: registryPort },
+  advertiseHost: '127.0.0.1',
 });
 const dispose = await app.listen(appPort);
 
@@ -147,7 +151,7 @@ const result = await response();
 - 修改 WebSocket URL 三段式约定却不同时更新 **`Server.onConnected`** 与 **`Server.connect`** 的拼接格式。
 - 在 `Registry` 中按 `Set` **迭代顺序** 固定返回「第一个」实例（破坏负载分散）；除非你明确改需求并改写测试。
 - `Client`/`Server` **`dispose`** 后不关闭 **`ws`**（会导致 **`WebSocketServer.close`** 长时间等待）；本包已在 `Client.dispose` 内关闭socket，不要随意删除。
-- 假设 `host:port` 串可无损表达 **IPv6**（当前实现按 **首个 `:` 分割**，仅适合 IPv4 或不含冒号的 host）。
+- 假设 `host:port` 串可无损表达 **IPv6**：注册表 Set 的键应使用 **`[IPv6]:port`**；`selectRandomRegistryAddress` / `parseAddressKey` 按 **最后一个 `:`** 切分 host 与 port。
 - `Application.props.registry` **不要传错端口**；丢失与注册中心的连接时依赖 `reconnectToRegistry`，不要在外部缓存 `registry` Client 绕过重连语义。
 
 ---

package/dist/application.d.ts

@@ -1,18 +1,24 @@
 import { Client } from './client.js';
-import { Server } from './server.js';
-import { MessageLoaderProps } from '@hile/message-loader';
+import { Server, type MicroServerProps } from './server.js';
 import { RegistryAddress } from './registry.js';
 export type ApplicationProps = {
     namespace: string;
     registry: RegistryAddress;
-} & MessageLoaderProps;
+    /** `/-/find` 等待响应的上限（毫秒），默认 `10000` */
+    registryLookupTimeoutMs?: number;
+} & MicroServerProps;
 export declare class Application extends Server {
     private registry?;
     private reconnectTimeout?;
+    private registryReconnectPromise;
+    /** 为 true 时不再向 Registry 重连（listen 返回的 teardown 已触发） */
+    private stopped;
     private readonly _registry_address;
+    private readonly _registryLookupTimeoutMs;
     private readonly namespaces;
     constructor(props: ApplicationProps);
     listen(port?: number): Promise<() => Promise<void>>;
+    private scheduleRegistryRetry;
     private reconnectToRegistry;
     private findFromRegistry;
     get(namespace: string): Promise<Client>;

package/dist/application.js

@@ -5,43 +5,126 @@ var RegistryLookupStatus;
     RegistryLookupStatus[RegistryLookupStatus["PENDING"] = 1] = "PENDING";
     RegistryLookupStatus[RegistryLookupStatus["READY"] = 2] = "READY";
 })(RegistryLookupStatus || (RegistryLookupStatus = {}));
+function assertValidRegistrySocket(meta, host, port) {
+    if (typeof host !== 'string' || !host || host.length > 253) {
+        throw new Error(`Invalid ${meta}: empty or oversized host`);
+    }
+    if (/[\s\r\n\0]/.test(host))
+        throw new Error(`Invalid ${meta}: host contains whitespace`);
+    if (!Number.isFinite(port) || port !== Math.trunc(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid ${meta}: port must be integer 1..65535`);
+    }
+    if (host.includes(':') && !host.startsWith('[')) {
+        throw new Error(`Invalid ${meta}: IPv6 host must be bracketed (e.g. [::1])`);
+    }
+    if (host.includes('/') || host.includes('?')) {
+        throw new Error(`Invalid ${meta}: illegal host characters`);
+    }
+}
+function withTimeout(promise, ms, label) {
+    if (!Number.isFinite(ms) || ms <= 0)
+        return promise;
+    let timer;
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+        }),
+    ]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
 export class Application extends Server {
     registry;
     reconnectTimeout;
+    registryReconnectPromise;
+    /** 为 true 时不再向 Registry 重连（listen 返回的 teardown 已触发） */
+    stopped = false;
     _registry_address;
+    _registryLookupTimeoutMs;
     namespaces = new Map();
     constructor(props) {
-        const { namespace, registry, ...loaderProps } = props;
-        super(namespace, loaderProps);
+        const { namespace, registry, registryLookupTimeoutMs = 10_000, ...microAndLoader } = props;
+        super(namespace, microAndLoader);
+        assertValidRegistrySocket('registry address', registry.host, registry.port);
         this._registry_address = registry;
+        this._registryLookupTimeoutMs = registryLookupTimeoutMs;
     }
     async listen(port = 0) {
+        this.stopped = false;
         const callback = await super.listen(port);
-        await this.reconnectToRegistry();
+        try {
+            await this.reconnectToRegistry();
+        }
+        catch (err) {
+            try {
+                await callback();
+            }
+            catch {
+                // ignore secondary errors from teardown
+            }
+            throw err;
+        }
         return async () => {
-            if (this.reconnectTimeout)
+            this.stopped = true;
+            if (this.reconnectTimeout) {
                 clearTimeout(this.reconnectTimeout);
+                this.reconnectTimeout = undefined;
+            }
+            this.registry = undefined;
             await callback();
         };
     }
+    scheduleRegistryRetry() {
+        if (this.stopped)
+            return;
+        if (this.reconnectTimeout)
+            clearTimeout(this.reconnectTimeout);
+        this.reconnectTimeout = setTimeout(() => {
+            this.reconnectTimeout = undefined;
+            void this.reconnectToRegistry().catch(() => {
+                if (this.stopped)
+                    return;
+                this.scheduleRegistryRetry();
+            });
+        }, 3000);
+    }
     async reconnectToRegistry() {
-        const registry = await this.connect(this._registry_address.host, this._registry_address.port);
-        registry.events.on('disconnect', () => {
-            this.registry = undefined;
-            const reconnect = () => {
-                this.reconnectToRegistry().catch(e => {
-                    this.reconnectTimeout = setTimeout(reconnect, 3000);
+        if (this.stopped)
+            return;
+        if (this.registryReconnectPromise)
+            return this.registryReconnectPromise;
+        this.registryReconnectPromise = (async () => {
+            const registry = await this.connect(this._registry_address.host, this._registry_address.port);
+            if (this.stopped) {
+                registry.dispose();
+                return;
+            }
+            registry.events.once('disconnect', () => {
+                if (this.registry !== registry)
+                    return;
+                this.registry = undefined;
+                if (this.stopped)
+                    return;
+                void this.reconnectToRegistry().catch(() => {
+                    if (this.stopped)
+                        return;
+                    this.scheduleRegistryRetry();
                 });
-            };
-            reconnect();
+            });
+            this.registry = registry;
+        })().finally(() => {
+            this.registryReconnectPromise = undefined;
         });
-        this.registry = registry;
+        return this.registryReconnectPromise;
     }
     async findFromRegistry(namespace) {
         if (!this.registry)
             throw new Error('Registry not found');
         const { response } = this.registry.request('/-/find', { namespace });
-        return await response();
+        const p = response();
+        return await withTimeout(p, this._registryLookupTimeoutMs, 'Registry /-/find');
     }
     get(namespace) {
         if (!this.namespaces.has(namespace)) {
@@ -53,6 +136,12 @@ export class Application extends Server {
             });
         }
         const stack = this.namespaces.get(namespace);
+        if (stack.status === RegistryLookupStatus.READY &&
+            !this.clients.has(`${stack.host}:${stack.port}`)) {
+            stack.status = RegistryLookupStatus.IDLE;
+            stack.host = '';
+            stack.port = 0;
+        }
         const key = `${stack.host}:${stack.port}`;
         if (stack.status === RegistryLookupStatus.READY && this.clients.has(key)) {
             return Promise.resolve(this.clients.get(key));
@@ -64,6 +153,7 @@ export class Application extends Server {
                 this.findFromRegistry(namespace).then(data => {
                     if (!data)
                         return Promise.reject(new Error('Namespace not found'));
+                    assertValidRegistrySocket('peer address from registry', data.host, data.port);
                     return this.connect(data.host, data.port).then(client => {
                         stack.host = data.host;
                         stack.port = data.port;

package/dist/registry.d.ts

@@ -1,5 +1,4 @@
-import { MessageLoaderProps } from '@hile/message-loader';
-import { Server } from './server.js';
+import { Server, type MicroServerProps } from './server.js';
 export interface RegistryFindData {
     namespace: string;
 }
@@ -7,9 +6,14 @@ export interface RegistryAddress {
     host: string;
     port: number;
 }
+/** 将 `host:port` 或 `[ipv6]:port` 形式的 key 解析为地址（端口取最后一个 `:` 之后） */
+export declare function parseAddressKey(key: string): RegistryAddress | undefined;
 export declare function selectRandomRegistryAddress(keys: Iterable<string>): RegistryAddress | undefined;
 export declare class Registry extends Server {
     private readonly namespaces;
-    constructor(props?: MessageLoaderProps);
+    private unregisterFind?;
+    constructor(props?: MicroServerProps);
+    /** 幂等：重复调用会先注销上一条 `/-/find` 再注册，避免叠多条路由 */
     onFind(): void;
+    private mountFindHandler;
 }

package/dist/registry.js

@@ -1,9 +1,24 @@
 import { Server } from './server.js';
+/** 将 `host:port` 或 `[ipv6]:port` 形式的 key 解析为地址（端口取最后一个 `:` 之后） */
+export function parseAddressKey(key) {
+    const i = key.lastIndexOf(':');
+    if (i <= 0 || i >= key.length - 1)
+        return undefined;
+    const host = key.slice(0, i);
+    const port = Number(key.slice(i + 1));
+    if (!host ||
+        !Number.isFinite(port) ||
+        port !== Math.trunc(port) ||
+        port < 1 ||
+        port > 65535) {
+        return undefined;
+    }
+    return { host, port };
+}
 export function selectRandomRegistryAddress(keys) {
-    const addresses = Array.from(keys).map((key) => {
-        const [host, port] = key.split(':');
-        return { host, port: Number(port) };
-    });
+    const addresses = Array.from(keys)
+        .map(parseAddressKey)
+        .filter((a) => a !== undefined);
     if (addresses.length === 0)
         return;
     const index = Math.floor(Math.random() * addresses.length);
@@ -11,8 +26,9 @@ export function selectRandomRegistryAddress(keys) {
 }
 export class Registry extends Server {
     namespaces = new Map();
+    unregisterFind;
     constructor(props) {
-        super('registry', props);
+        super('registry', props ?? {});
         this.events.on('connect', (client, extras) => {
             const key = client.host + ':' + client.port;
             const namespace = extras.join('/');
@@ -34,10 +50,18 @@ export class Registry extends Server {
                 }
             }
         });
-        this.onFind();
+        this.mountFindHandler();
     }
+    /** 幂等：重复调用会先注销上一条 `/-/find` 再注册，避免叠多条路由 */
     onFind() {
-        this.register('/-/find', async ({ data }) => {
+        this.mountFindHandler();
+    }
+    mountFindHandler() {
+        if (this.unregisterFind) {
+            this.unregisterFind();
+            this.unregisterFind = undefined;
+        }
+        this.unregisterFind = this.register('/-/find', async ({ data }) => {
             const namespace = data.namespace;
             const keys = this.namespaces.get(namespace);
             if (!keys)

package/dist/server.d.ts

@@ -3,14 +3,22 @@ import { Client } from './client.js';
 import { IncomingMessage } from 'http';
 import { EventEmitter } from 'node:events';
 import type { Duplex } from "node:stream";
+/** {@link MessageLoaderProps} 加上出站 WebSocket 宣告地址 */
+export type MicroServerProps = MessageLoaderProps & {
+    /**
+     * 出站连接 URL 中 `ws://{host}:{port}/{本段}/...` 的「本段」宣告地址。
+     * 缺省使用 `getLocalIPv4()`；若仍为 `undefined`（无可用 IPv4）则构造 {@link Server} 时抛错。
+     */
+    advertiseHost?: string;
+};
 export declare class Server extends MessageLoader {
     private readonly namespace;
     private wss?;
     port?: number;
     protected readonly clients: Map<string, Client>;
-    private readonly ipv4;
+    private readonly announceHost;
     readonly events: EventEmitter<any>;
-    constructor(namespace: string, props?: MessageLoaderProps);
+    constructor(namespace: string, props?: MicroServerProps);
     private upstream;
     private createClient;
     protected connect(host: string, port: number, timeout?: number): Promise<Client>;

package/dist/server.js

@@ -10,11 +10,17 @@ export class Server extends MessageLoader {
     wss;
     port;
     clients = new Map();
-    ipv4 = getLocalIPv4();
+    announceHost;
     events = new EventEmitter();
     constructor(namespace, props = {}) {
-        super(props);
+        const { advertiseHost, ...loaderProps } = props;
+        super(loaderProps);
         this.namespace = namespace;
+        const resolved = advertiseHost?.trim() || getLocalIPv4();
+        if (!resolved) {
+            throw new Error('Unable to resolve advertise host for @hile/micro Server: pass `advertiseHost` (e.g. "127.0.0.1") in constructor options, or ensure getLocalIPv4() returns an address.');
+        }
+        this.announceHost = resolved;
         this.events.on('connect', (client, extras) => {
             client.events.emit('connect', extras);
         });
@@ -34,13 +40,25 @@ export class Server extends MessageLoader {
         const [host, port, ...extras] = sp;
         if (!host || !port)
             return ws.close();
-        this.createClient(ws, host, Number(port), extras);
+        const portNum = Number(port);
+        if (!Number.isFinite(portNum) ||
+            portNum !== Math.trunc(portNum) ||
+            portNum < 1 ||
+            portNum > 65535) {
+            return ws.close();
+        }
+        this.createClient(ws, host, portNum, extras);
     }
     createClient(ws, host, port, extras = []) {
         const key = `${host}:${port}`;
+        const previous = this.clients.get(key);
+        if (previous) {
+            this.clients.delete(key);
+            previous.dispose();
+        }
         const client = new Client({ server: this, ws, host, port });
         ws.on('close', () => {
-            if (this.clients.has(key)) {
+            if (this.clients.get(key) === client) {
                 this.clients.delete(key);
             }
             client.dispose();
@@ -58,7 +76,7 @@ export class Server extends MessageLoader {
         if (!this.port)
             throw new Error('You can not connect to a server without a local port, please use `.setPort(port)` for local port.');
         const ws = await new Promise((resolve, reject) => {
-            const ws = new WebSocket(`ws://${host}:${port}/${this.ipv4}/${this.port}/${this.namespace}`);
+            const ws = new WebSocket(`ws://${host}:${port}/${this.announceHost}/${this.port}/${this.namespace}`);
             const timer = setTimeout(() => {
                 clear();
                 ws.on('error', () => { });
@@ -112,7 +130,8 @@ export class Server extends MessageLoader {
             this.wss = new WebSocketServer({ noServer: true });
         }
         return async () => {
-            for (const client of this.clients.values()) {
+            const toDispose = [...this.clients.values()];
+            for (const client of toDispose) {
                 client.dispose();
             }
             this.clients.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/micro",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -28,5 +28,5 @@
     "internal-ip": "^9.0.0",
     "ws": "^8.19.0"
   },
-  "gitHead": "fc98c3e1ecf57f6cb4aded9caef28da0a35b7f30"
+  "gitHead": "46d4b998c1fd2fd725bf484ca634f25b61f19cd5"
 }