@hile/micro 3.0.1 → 3.0.2

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

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.2",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -31,5 +31,5 @@
     "ws": "^8.21.0",
     "yaml": "^2.9.0"
   },
-  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
+  "gitHead": "5d6a724ac4e99d493d42efe337e3ad17db40c3f7"
 }