@hile/micro 3.0.1 → 3.0.3

package/AI.md

@@ -186,6 +186,20 @@ import { MessageWorkerThread } from '@hile/message-worker-thread'
 - Registry is started before application nodes need discovery.
 - Micro apps use stable namespaces and advertise reachable hosts.
 
+## Registry Read APIs
+
+`Registry` exposes read-only routes for diagnostics and admin tooling. These routes return
+snapshots of current registry state; they do not change service discovery, topic declarations,
+subscriptions, or retained config data.
+
+- `/-/namespaces` returns all registered namespaces with peer counts and addresses.
+- `/-/namespace/peers` accepts `{ namespace, exclude? }` and returns every peer for one namespace.
+- `/-/registry/status` returns registry uptime and counts for clients, namespaces, topics, and config namespaces.
+- `/-/topics` accepts `{ prefix? }` and returns topic summaries with publisher/subscriber counts and retained/data flags.
+- `/-/topic/get` accepts `{ topic }` and returns the current topic payload snapshot when the topic exists.
+- `/-/configs` returns loaded config namespaces and keys.
+- `/-/config/get` accepts `{ namespace, key? }` and returns either a config snapshot or one config value.
+
 
 
 # Related Recipes
@@ -349,6 +363,122 @@ Use this recipe when config changes should persist to Redis and be pushed throug
 - Change handlers use `change:key`.
 - Cleanup from `initialize()` is registered.
 
+# Stable Runtime Reload
+
+## Complete Example
+
+```ts
+import { defineService, loadService } from '@hile/core'
+import { Application } from '@hile/micro'
+import { Http } from '@hile/http'
+import { createConfigAggregator, createRuntimeReloader } from '@hile/reloader'
+import appService from './micro.app.boot'
+import httpService from './http.boot'
+
+type RuntimeConfig = {
+  mysql: { host: string; port: number }
+  redis: { host: string; port: number }
+  flags: Record<string, boolean>
+}
+
+export default defineService('runtime.reload', async (shutdown) => {
+  const app = await loadService<Application>(appService)
+  const http = await loadService<Http>(httpService)
+
+  const reloader = createRuntimeReloader<RuntimeConfig, AppRuntime>({
+    debounceMs: 100,
+    normalize: config => ({
+      mysql: config.mysql,
+      redis: config.redis,
+      flags: config.flags,
+    }),
+    create: config => createAppRuntime(config),
+    dispose: runtime => runtime.close(),
+    onError: (error, context) => {
+      logger.error({ error, stage: context.stage }, 'runtime reload failed')
+    },
+  })
+
+  const configs = createConfigAggregator<RuntimeConfig>({
+    required: ['mysql', 'redis'],
+    defaults: { flags: {} },
+    debounceMs: 100,
+    onError: (error) => {
+      logger.error({ error }, 'runtime config emit failed')
+    },
+  })
+
+  configs.onChange(config => reloader.update(config))
+
+  const cleanupMysql = await app.subscribe('config:mysql', value => configs.set('mysql', value))
+  const cleanupRedis = await app.subscribe('config:redis', value => configs.set('redis', value))
+  const cleanupFlags = await app.subscribe('config:flags', value => configs.set('flags', value))
+
+  http.use(async (ctx, next) => {
+    const runtime = reloader.current()
+    if (!runtime) {
+      ctx.status = 503
+      ctx.body = { error: 'runtime is not ready' }
+      return
+    }
+    await runtime.handle(ctx, next)
+  })
+
+  shutdown(async () => {
+    await cleanupMysql()
+    await cleanupRedis()
+    await cleanupFlags()
+    configs.dispose()
+    await reloader.stop()
+  })
+
+  return reloader
+})
+```
+
+## File Layout
+
+```text
+src/services/runtime.reload.boot.ts
+src/services/micro.app.boot.ts
+src/services/http.boot.ts
+```
+
+## User Intent
+
+Use this recipe when `app.subscribe()` receives config updates that should rebuild business runtime state without thrashing services or rebinding ports.
+
+## Packages To Use
+
+- `@hile/reloader`
+- `@hile/micro`
+- `@hile/http`
+- `@hile/core`
+
+## Implementation Steps
+
+1. Keep the HTTP listener outside the reloader.
+2. Create `RuntimeReloader` for the runtime object that can be safely swapped.
+3. Create `ConfigAggregator` for all required subscribe topics.
+4. Feed each `app.subscribe()` callback into `configs.set(key, value)`.
+5. Use `configs.onChange(config => reloader.update(config))`.
+6. Register subscribe cleanup, `configs.dispose()`, and `reloader.stop()` with shutdown.
+
+## Failure And Cleanup Behavior
+
+- Config bursts collapse through aggregator debounce and reloader debounce.
+- Reloads never run concurrently.
+- If `create()` fails, the previous runtime stays active.
+- Old runtime disposal happens after the new runtime becomes current.
+- Same-port HTTP services are not restarted.
+
+## Verification Checklist
+
+- Required config keys are received before the first runtime is created.
+- Repeated equivalent configs do not reload.
+- A failed create logs an error and leaves old traffic handling intact.
+- The HTTP server is started once and reads `reloader.current()` per request.
+
 
 
 # Global Guardrails

package/dist/registry.d.ts

@@ -7,6 +7,75 @@ export interface RegistryAddress {
     host: string;
     port: number;
 }
+export interface RegistryNamespaceSnapshot {
+    namespace: string;
+    peerCount: number;
+    peers: RegistryAddress[];
+}
+export interface RegistryNamespacesResult {
+    namespaces: RegistryNamespaceSnapshot[];
+}
+export type RegistryNamespacePeersData = RegistryFindData;
+export interface RegistryNamespacePeersResult {
+    namespace: string;
+    peers: RegistryAddress[];
+}
+export interface RegistryStatusSnapshot {
+    status: 'ok';
+    startedAt: number;
+    uptime: number;
+    clientCount: number;
+    namespaceCount: number;
+    topicCount: number;
+    configNamespaceCount: number;
+}
+export interface RegistryTopicsData {
+    prefix?: string;
+}
+export interface RegistryTopicSummary {
+    topic: string;
+    publisherCount: number;
+    subscriberCount: number;
+    hasData: boolean;
+    retained: boolean;
+}
+export interface RegistryTopicsResult {
+    topics: RegistryTopicSummary[];
+}
+export interface RegistryTopicGetData {
+    topic: string;
+}
+export interface RegistryTopicSnapshot extends RegistryTopicSummary {
+    payload: any;
+}
+export interface RegistryConfigSummary {
+    namespace: string;
+    keys: string[];
+}
+export interface RegistryConfigsResult {
+    configs: RegistryConfigSummary[];
+}
+export interface RegistryConfigGetData {
+    namespace: string;
+    key?: string;
+}
+export type RegistryConfigGetResult = {
+    namespace: string;
+    hasConfig: true;
+    config: any;
+} | {
+    namespace: string;
+    hasConfig: false;
+} | {
+    namespace: string;
+    key: string;
+    hasValue: true;
+    value: any;
+} | {
+    namespace: string;
+    key: string;
+    hasValue: false;
+};
 /** 将 `host:port` 或 `[ipv6]:port` 形式的 key 解析为地址（端口取最后一个 `:` 之后） */
 export declare function parseAddressKey(key: string): RegistryAddress | undefined;
 export declare function selectRandomRegistryAddress(keys: Iterable<string>): RegistryAddress | undefined;
@@ -21,7 +90,13 @@ export declare class Registry extends Server {
     private readonly fallbacks;
     private readonly topics;
     private topicRevision;
+    private readonly startedAt;
     constructor(props?: MicroServerProps);
+    private createNamespaceSnapshot;
+    private createTopicSummary;
+    private createTopicSnapshot;
+    private listTopicSummaries;
+    private registerReadApis;
     private cleanupTopicIfUnused;
     private clearTopicData;
     private rememberPublisherPayload;

package/dist/registry.js

@@ -28,6 +28,28 @@ export function selectRandomRegistryAddress(keys) {
     const index = Math.floor(Math.random() * addresses.length);
     return addresses[index];
 }
+function compareRegistryAddress(a, b) {
+    const byHost = a.host.localeCompare(b.host);
+    if (byHost !== 0)
+        return byHost;
+    return a.port - b.port;
+}
+function registryAddressesFromKeys(keys, exclude) {
+    const excludeSet = exclude?.length ? new Set(exclude) : undefined;
+    return Array.from(keys)
+        .filter(key => !excludeSet?.has(key))
+        .map(parseAddressKey)
+        .filter((address) => address !== undefined)
+        .sort(compareRegistryAddress);
+}
+function cloneRegistryValue(value) {
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        return value;
+    }
+}
 export function getRegistryConfigsDir() {
     return resolve(homedir(), '.registry', 'configs');
 }
@@ -81,6 +103,7 @@ export class Registry extends Server {
     fallbacks = new Set();
     topics = new Map();
     topicRevision = 0;
+    startedAt = Date.now();
     constructor(props = {}) {
         const workspace = resolve(homedir(), '.registry');
         if (!existsSync(workspace)) {
@@ -133,6 +156,112 @@ export class Registry extends Server {
         this.registerSubscribe();
         this.registerUnsubscribe();
         this.registerReceiveTopicUpdate();
+        this.registerReadApis();
+    }
+    createNamespaceSnapshot(namespace, keys) {
+        const peers = registryAddressesFromKeys(keys);
+        return {
+            namespace,
+            peerCount: peers.length,
+            peers,
+        };
+    }
+    createTopicSummary(topic, entry) {
+        return {
+            topic,
+            publisherCount: entry.publishers.size,
+            subscriberCount: entry.subscribers.size,
+            hasData: entry.hasData,
+            retained: entry.retained,
+        };
+    }
+    createTopicSnapshot(topic, entry) {
+        return {
+            ...this.createTopicSummary(topic, entry),
+            payload: cloneRegistryValue(entry.data),
+        };
+    }
+    listTopicSummaries(prefix) {
+        const hasPrefix = typeof prefix === 'string' && prefix.length > 0;
+        return [...this.topics.entries()]
+            .filter(([topic]) => !hasPrefix || topic.startsWith(prefix))
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([topic, entry]) => this.createTopicSummary(topic, entry));
+    }
+    registerReadApis() {
+        this.fallbacks.add(this.register('/-/namespaces', async () => {
+            const namespaces = [...this.namespaces.entries()]
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([namespace, keys]) => this.createNamespaceSnapshot(namespace, keys));
+            return { namespaces };
+        }));
+        this.fallbacks.add(this.register('/-/namespace/peers', async ({ data }) => {
+            const namespace = typeof data?.namespace === 'string' ? data.namespace : '';
+            const keys = this.namespaces.get(namespace);
+            return {
+                namespace,
+                peers: keys ? registryAddressesFromKeys(keys, data.exclude) : [],
+            };
+        }));
+        this.fallbacks.add(this.register('/-/registry/status', async () => ({
+            status: 'ok',
+            startedAt: this.startedAt,
+            uptime: Date.now() - this.startedAt,
+            clientCount: this.clients.size,
+            namespaceCount: this.namespaces.size,
+            topicCount: this.topics.size,
+            configNamespaceCount: this.configs.size,
+        })));
+        this.fallbacks.add(this.register('/-/topics', async ({ data }) => ({
+            topics: this.listTopicSummaries(data?.prefix),
+        })));
+        this.fallbacks.add(this.register('/-/topic/get', async ({ data }) => {
+            if (typeof data?.topic !== 'string')
+                return;
+            const entry = this.topics.get(data.topic);
+            if (!entry)
+                return;
+            return this.createTopicSnapshot(data.topic, entry);
+        }));
+        this.fallbacks.add(this.register('/-/configs', async () => {
+            const configs = [...this.configs.entries()]
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([namespace, config]) => ({
+                namespace,
+                keys: Object.keys(config).sort(),
+            }));
+            return { configs };
+        }));
+        this.fallbacks.add(this.register('/-/config/get', async ({ data }) => {
+            const namespace = typeof data?.namespace === 'string' ? data.namespace : '';
+            const config = this.configs.get(namespace);
+            if (typeof data?.key === 'string') {
+                if (config && Object.prototype.hasOwnProperty.call(config, data.key)) {
+                    return {
+                        namespace,
+                        key: data.key,
+                        hasValue: true,
+                        value: cloneRegistryValue(config[data.key]),
+                    };
+                }
+                return {
+                    namespace,
+                    key: data.key,
+                    hasValue: false,
+                };
+            }
+            if (!config) {
+                return {
+                    namespace,
+                    hasConfig: false,
+                };
+            }
+            return {
+                namespace,
+                hasConfig: true,
+                config: cloneRegistryValue(config),
+            };
+        }));
     }
     cleanupTopicIfUnused(topic, entry = this.topics.get(topic)) {
         if (!entry)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/micro",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -31,5 +31,5 @@
     "ws": "^8.21.0",
     "yaml": "^2.9.0"
   },
-  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
+  "gitHead": "eac3a74c71ec2c514b920015f1c0d3415d3b8057"
 }