@hile/micro 1.0.4 → 1.0.6

package/dist/application.d.ts

@@ -1,11 +1,28 @@
 import { Client } from './client.js';
 import { Server, type MicroServerProps } from './server.js';
 import { RegistryAddress } from './registry.js';
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type EnvRequest<T extends Record<string, Record<string, any>>> = {
+    [N in keyof T]: {
+        namespace: N;
+        fields?: readonly (keyof T[N])[];
+    };
+}[keyof T];
+type EnvFieldsForRequest<T extends Record<string, Record<string, any>>, N extends keyof T, F> = F extends readonly (infer K extends keyof T[N])[] ? Pick<T[N], K> : T[N];
+type EnvRequestResult<T extends Record<string, Record<string, any>>, R> = R extends {
+    namespace: infer N extends keyof T;
+    fields?: infer F;
+} ? {
+    [K in N]: EnvFieldsForRequest<T, N, F>;
+} : never;
+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;
     registry: RegistryAddress;
     /** `/-/find` 等待响应的上限（毫秒），默认 `10000` */
     registryLookupTimeoutMs?: number;
+    /** 单次 request() 等待响应的上限（毫秒），默认 `30000` */
+    requestTimeoutMs?: number;
 } & MicroServerProps;
 export declare class Application extends Server {
     private registry?;
@@ -15,11 +32,24 @@ export declare class Application extends Server {
     private stopped;
     private readonly _registry_address;
     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;
     private findFromRegistry;
-    get(namespace: string): Promise<Client>;
+    get(namespace: string, exclude?: string[]): Promise<Client>;
+    call<T = any>(namespace: string, url: string, data: any, timeout?: number, retries?: number): Promise<T>;
+    getEnvVariables<T extends Record<string, Record<string, any>>, const Requests extends readonly EnvRequest<T>[] = readonly EnvRequest<T>[]>(...data: Requests): Promise<GetEnvVariablesResult<T, Requests>>;
 }
+export {};

package/dist/application.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { Server } from './server.js';
 var RegistryLookupStatus;
 (function (RegistryLookupStatus) {
@@ -43,19 +44,32 @@ export class Application extends Server {
     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, registryLookupTimeoutMs = 10_000, ...microAndLoader } = props;
+        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);
         try {
             await this.reconnectToRegistry();
+            this.startHeartbeat();
         }
         catch (err) {
             try {
@@ -68,6 +82,7 @@ export class Application extends Server {
         }
         return async () => {
             this.stopped = true;
+            this.stopHeartbeat();
             if (this.reconnectTimeout) {
                 clearTimeout(this.reconnectTimeout);
                 this.reconnectTimeout = undefined;
@@ -119,14 +134,66 @@ export class Application extends Server {
         });
         return this.registryReconnectPromise;
     }
-    async findFromRegistry(namespace) {
+    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) {
+            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 });
-        const p = response();
-        return await withTimeout(p, this._registryLookupTimeoutMs, 'Registry /-/find');
+        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: '',
@@ -136,8 +203,12 @@ 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}`)) {
+            (!this.clients.has(`${stack.host}:${stack.port}`) ||
+                (exclude?.length && exclude.includes(`${stack.host}:${stack.port}`)))) {
             stack.status = RegistryLookupStatus.IDLE;
             stack.host = '';
             stack.port = 0;
@@ -150,7 +221,7 @@ 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);
@@ -170,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);
@@ -178,4 +262,46 @@ 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;
+        }
+    }
+    async getEnvVariables(...data) {
+        if (!this.registry)
+            throw new Error('Registry not found');
+        const { response } = this.registry.request('/-/env/variables', data);
+        const configs = await response();
+        const out = {};
+        for (const { namespace, value } of configs) {
+            out[namespace] = value;
+        }
+        return out;
+    }
 }

package/dist/registry.d.ts

@@ -1,6 +1,7 @@
 import { Server, type MicroServerProps } from './server.js';
 export interface RegistryFindData {
     namespace: string;
+    exclude?: string[];
 }
 export interface RegistryAddress {
     host: string;
@@ -9,11 +10,23 @@ export interface RegistryAddress {
 /** 将 `host:port` 或 `[ipv6]:port` 形式的 key 解析为地址（端口取最后一个 `:` 之后） */
 export declare function parseAddressKey(key: string): RegistryAddress | undefined;
 export declare function selectRandomRegistryAddress(keys: Iterable<string>): RegistryAddress | undefined;
+export declare function getRegistryConfigsDir(): string;
+export declare function namespaceToConfigFile(ns: string): string;
+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;
     constructor(props?: MicroServerProps);
+    watchEnvFile(): import("node:fs").FSWatcher | undefined;
+    listen(port?: number): Promise<() => Promise<void>>;
     /** 幂等：重复调用会先注销上一条 `/-/find` 再注册，避免叠多条路由 */
     onFind(): void;
     private mountFindHandler;
+    private registerEnvVariables;
 }

package/dist/registry.js

@@ -1,4 +1,8 @@
 import { Server } from './server.js';
+import { homedir } from 'node:os';
+import { resolve, join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, watch } from 'node:fs';
+import YAML from 'yaml';
 /** 将 `host:port` 或 `[ipv6]:port` 形式的 key 解析为地址（端口取最后一个 `:` 之后） */
 export function parseAddressKey(key) {
     const i = key.lastIndexOf(':');
@@ -24,13 +28,36 @@ export function selectRandomRegistryAddress(keys) {
     const index = Math.floor(Math.random() * addresses.length);
     return addresses[index];
 }
+export function getRegistryConfigsDir() {
+    return resolve(homedir(), '.registry', 'configs');
+}
+export function namespaceToConfigFile(ns) {
+    return join(getRegistryConfigsDir(), `${ns}.config.yaml`);
+}
+export function parseConfigFilename(filename) {
+    if (!filename.endsWith('.config.yaml'))
+        return null;
+    return filename.slice(0, -'.config.yaml'.length);
+}
 export class Registry extends Server {
     namespaces = new Map();
     unregisterFind;
-    constructor(props) {
-        super('registry', props ?? {});
+    static HEARTBEAT_INTERVAL = 1000;
+    static HEARTBEAT_TIMEOUT = 20000;
+    heartbeats = new Map();
+    workspace;
+    configFileSuffix = '.config.yaml';
+    configs = new Map();
+    constructor(props = {}) {
+        const workspace = resolve(homedir(), '.registry');
+        if (!existsSync(workspace)) {
+            mkdirSync(workspace, { recursive: true });
+        }
+        super('registry', props);
+        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());
@@ -39,6 +66,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);
@@ -51,6 +79,65 @@ 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');
+        if (!existsSync(configFile))
+            return;
+        const configFiles = readdirSync(configFile).filter(filename => filename.endsWith(this.configFileSuffix));
+        for (const filename of configFiles) {
+            try {
+                const config = YAML.parse(readFileSync(resolve(configFile, filename), 'utf8'));
+                if (typeof config !== 'object' || config === null)
+                    continue;
+                this.configs.set(parseConfigFilename(filename), config);
+            }
+            catch { }
+        }
+        return watch(configFile, (_, filename) => {
+            if (!filename?.endsWith(this.configFileSuffix))
+                return;
+            try {
+                const config = YAML.parse(readFileSync(resolve(configFile, filename), 'utf8'));
+                if (typeof config !== 'object' || config === null)
+                    return;
+                this.configs.set(parseConfigFilename(filename), config);
+            }
+            catch { /* vim 替换文件时的中间态读错误，忽略 */ }
+        });
+    }
+    async listen(port = 0) {
+        const registry_port = process.env.REGISTRY_PORT ? Number(process.env.REGISTRY_PORT) : 0;
+        const _port = port || registry_port;
+        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();
+        };
     }
     /** 幂等：重复调用会先注销上一条 `/-/find` 再注册，避免叠多条路由 */
     onFind() {
@@ -63,10 +150,34 @@ export class Registry extends Server {
         }
         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);
         });
     }
+    registerEnvVariables() {
+        this.register('/-/env/variables', async ({ data }) => {
+            return data.map(({ namespace, fields }) => {
+                if (!this.configs.has(namespace)) {
+                    return { namespace, value: null };
+                }
+                if (!fields?.length)
+                    return { namespace, value: this.configs.get(namespace) };
+                const config = this.configs.get(namespace);
+                const value = {};
+                for (const field of fields) {
+                    value[field] = config[field];
+                }
+                return { namespace, value };
+            });
+        });
+    }
 }

package/dist/server.d.ts

@@ -18,6 +18,7 @@ export declare class Server extends MessageLoader {
     protected readonly clients: Map<string, Client>;
     private readonly announceHost;
     readonly events: EventEmitter<any>;
+    get host(): string;
     constructor(namespace: string, props?: MicroServerProps);
     private upstream;
     private createClient;

package/dist/server.js

@@ -12,6 +12,9 @@ export class Server extends MessageLoader {
     clients = new Map();
     announceHost;
     events = new EventEmitter();
+    get host() {
+        return this.announceHost;
+    }
     constructor(namespace, props = {}) {
         const { advertiseHost, ...loaderProps } = props;
         super(loaderProps);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/micro",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -26,7 +26,8 @@
     "@hile/message-loader": "^1.0.8",
     "@hile/message-ws": "^1.0.6",
     "internal-ip": "^9.0.0",
-    "ws": "^8.19.0"
+    "ws": "^8.19.0",
+    "yaml": "^2.9.0"
   },
-  "gitHead": "46d4b998c1fd2fd725bf484ca634f25b61f19cd5"
+  "gitHead": "b2272b434848ff9d93a88796e25a66665afcaa0a"
 }