@hile/micro 1.0.3 → 1.0.5

package/dist/application.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { Server } from './server.js';
 var RegistryLookupStatus;
 (function (RegistryLookupStatus) {
@@ -5,45 +6,194 @@ 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;
+    _requestTimeoutMs;
     namespaces = new Map();
+    static HEARTBEAT_INTERVAL = 10000;
+    heartbeatTimer;
+    static CB_COOLDOWN_MS = 30_000;
+    circuitBreakers = new Map();
     constructor(props) {
-        const { namespace, registry, ...loaderProps } = props;
-        super(namespace, loaderProps);
+        const { namespace, registry, registryLookupTimeoutMs = 10_000, requestTimeoutMs = 30_000, ...microAndLoader } = props;
+        super(namespace, microAndLoader);
+        assertValidRegistrySocket('registry address', registry.host, registry.port);
         this._registry_address = registry;
+        this._registryLookupTimeoutMs = registryLookupTimeoutMs;
+        this._requestTimeoutMs = requestTimeoutMs;
+        this.register('/-/health', async () => ({
+            status: 'ok',
+            registry: !!this.registry,
+            uptime: process.uptime(),
+            namespaces: [...this.namespaces.keys()],
+        }));
     }
     async listen(port = 0) {
+        this.stopped = false;
         const callback = await super.listen(port);
-        await this.reconnectToRegistry();
+        try {
+            await this.reconnectToRegistry();
+            this.startHeartbeat();
+        }
+        catch (err) {
+            try {
+                await callback();
+            }
+            catch {
+                // ignore secondary errors from teardown
+            }
+            throw err;
+        }
         return async () => {
-            if (this.reconnectTimeout)
+            this.stopped = true;
+            this.stopHeartbeat();
+            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;
+    }
+    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;
+        }
     }
-    async findFromRegistry(namespace) {
+    recordSuccess(ns, host, port) {
+        const excludes = this.circuitBreakers.get(ns);
+        if (excludes) {
+            excludes.delete(`${host}:${port}`);
+            if (excludes.size === 0)
+                this.circuitBreakers.delete(ns);
+        }
+    }
+    recordFailure(ns, host, port) {
+        let excludes = this.circuitBreakers.get(ns);
+        if (!excludes) {
+            excludes = new Map();
+            this.circuitBreakers.set(ns, excludes);
+        }
+        excludes.set(`${host}:${port}`, Date.now());
+    }
+    getActiveExcludes(ns) {
+        const excludes = this.circuitBreakers.get(ns);
+        if (!excludes)
+            return [];
+        const now = Date.now();
+        const active = [];
+        for (const [key, openedAt] of excludes) {
+            if (now - openedAt >= Application.CB_COOLDOWN_MS) {
+                excludes.delete(key);
+            }
+            else {
+                active.push(key);
+            }
+        }
+        if (excludes.size === 0)
+            this.circuitBreakers.delete(ns);
+        return active;
+    }
+    async findFromRegistry(namespace, exclude) {
         if (!this.registry)
             throw new Error('Registry not found');
-        const { response } = this.registry.request('/-/find', { namespace });
-        return await response();
+        const { response } = this.registry.request('/-/find', { namespace, exclude });
+        return await withTimeout(response(), this._registryLookupTimeoutMs, 'Registry /-/find');
     }
-    get(namespace) {
+    get(namespace, exclude) {
         if (!this.namespaces.has(namespace)) {
             this.namespaces.set(namespace, {
                 host: '',
@@ -53,6 +203,16 @@ export class Application extends Server {
             });
         }
         const stack = this.namespaces.get(namespace);
+        // Save old cache info before potential invalidation (used for cache degradation)
+        const cachedHost = stack.host;
+        const cachedPort = stack.port;
+        if (stack.status === RegistryLookupStatus.READY &&
+            (!this.clients.has(`${stack.host}:${stack.port}`) ||
+                (exclude?.length && exclude.includes(`${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));
@@ -61,9 +221,10 @@ export class Application extends Server {
             stack.handlers.add([resolve, reject]);
             if (stack.status === RegistryLookupStatus.IDLE) {
                 stack.status = RegistryLookupStatus.PENDING;
-                this.findFromRegistry(namespace).then(data => {
+                this.findFromRegistry(namespace, exclude).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;
@@ -80,6 +241,19 @@ export class Application extends Server {
                         }
                     });
                 }).catch(e => {
+                    // Registry unavailable but previously cached client still valid -> degrade
+                    const cachedKey = `${cachedHost}:${cachedPort}`;
+                    if (cachedHost && this.clients.has(cachedKey)) {
+                        const client = this.clients.get(cachedKey);
+                        // Restore cache so subsequent calls hit the fast path
+                        stack.host = cachedHost;
+                        stack.port = cachedPort;
+                        stack.status = RegistryLookupStatus.READY;
+                        for (const [resolve] of stack.handlers.values()) {
+                            resolve(client);
+                        }
+                        return;
+                    }
                     this.namespaces.delete(namespace);
                     for (const [_, reject] of stack.handlers.values()) {
                         reject(e);
@@ -88,4 +262,35 @@ 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 {
+            client = await this.get(namespace, exclude);
+        }
+        catch {
+            this.circuitBreakers.delete(namespace);
+            client = await this.get(namespace);
+        }
+        try {
+            const { response } = client.request(url, data, timeout ?? this._requestTimeoutMs);
+            const result = await response();
+            this.recordSuccess(namespace, client.host, client.port);
+            return result;
+        }
+        catch (err) {
+            this.recordFailure(namespace, client.host, client.port);
+            if (retries > 0) {
+                return this.call(namespace, url, data, timeout, retries - 1);
+            }
+            throw err;
+        }
+    }
 }

package/dist/registry.d.ts

@@ -1,15 +1,24 @@
-import { MessageLoaderProps } from '@hile/message-loader';
-import { Server } from './server.js';
+import { Server, type MicroServerProps } from './server.js';
 export interface RegistryFindData {
     namespace: string;
+    exclude?: string[];
 }
 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?;
+    private static readonly HEARTBEAT_INTERVAL;
+    private static readonly HEARTBEAT_TIMEOUT;
+    private readonly heartbeats;
+    constructor(props?: MicroServerProps);
+    listen(port?: number): Promise<() => Promise<void>>;
+    /** 幂等：重复调用会先注销上一条 `/-/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,10 +26,15 @@ export function selectRandomRegistryAddress(keys) {
 }
 export class Registry extends Server {
     namespaces = new Map();
+    unregisterFind;
+    static HEARTBEAT_INTERVAL = 1000;
+    static HEARTBEAT_TIMEOUT = 20000;
+    heartbeats = new Map();
     constructor(props) {
-        super('registry', props);
+        super('registry', props ?? {});
         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());
@@ -23,6 +43,7 @@ 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);
@@ -34,14 +55,54 @@ export class Registry extends Server {
                 }
             }
         });
-        this.onFind();
+        this.mountFindHandler();
+        this.register('/-/heartbeat', async ({ client }) => {
+            if (!client)
+                return;
+            const key = client.host + ':' + client.port;
+            this.heartbeats.set(key, Date.now());
+        });
     }
+    async listen(port = 0) {
+        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);
+        return async () => {
+            clearInterval(timer);
+            await teardown();
+        };
+    }
+    /** 幂等：重复调用会先注销上一条 `/-/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);
+            let keys = this.namespaces.get(namespace);
             if (!keys)
                 return;
+            if (data.exclude?.length) {
+                const excludeSet = new Set(data.exclude);
+                const filtered = [...keys].filter(k => !excludeSet.has(k));
+                if (filtered.length === 0)
+                    return;
+                keys = new Set(filtered);
+            }
             return selectRandomRegistryAddress(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.5",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -28,5 +28,5 @@
     "internal-ip": "^9.0.0",
     "ws": "^8.19.0"
   },
-  "gitHead": "fc98c3e1ecf57f6cb4aded9caef28da0a35b7f30"
+  "gitHead": "ddc82850295d26358cbffbb695e642cdb748339d"
 }