@hile/micro 4.0.0 → 4.0.2

package/AI.md

@@ -133,6 +133,7 @@ Use the message packages for request/response messaging over WebSocket, process
 - Do not use `stream()` for normal single-result calls.
 - Do not rely on message IDs for business idempotency. They are transport IDs.
 - Do not bypass `defineMessage()` for file-loaded handlers.
+- Do not pass zero, fractional, non-finite, or oversized message timeouts. Explicit timeout values must be safe integers from `1` through `2_147_483_647` milliseconds.
 
 ## Install
 
@@ -163,7 +164,11 @@ import { MessageWorkerThread } from '@hile/message-worker-thread'
 - `MessageLoader` maps `*.msg.*` files to routes using `@hile/loader`.
 - `MessageLoader.dispatch(path, data, extras?)` invokes the matched handler.
 - `MessageModem._send()` returns a `Promise`.
+- `MessageModem._send()` and `_push()` use a `30_000` ms timeout when none is provided. An explicit timeout must be a safe integer from `1` through `2_147_483_647`; invalid values throw `TypeError` before a message is sent.
 - `MessageModem._stream()` returns a Node `Readable` in object mode.
+- Stream `timeout` and `idleTimeout` values use the same `1` through `2_147_483_647` ms range. The stream `window` must be a safe integer from `1` through `64` and defaults to `1`.
+- Each modem schedules request, total-stream, and idle-stream deadlines through one internal deadline scheduler. This reduces active Node.js timers without changing timeout, cancellation, ordering, or error semantics.
+- `@hile/message-ws` keeps public `decodeMessageFrame()` payloads isolated from caller-owned input by default. Its owned WebSocket `RawData` path uses a zero-copy binary Flight payload view internally.
 - A stream request requires `exec()` to return an async iterable.
 - `Application.call(namespace, url, data, options?)` returns a promise.
 - `Application.stream(namespace, url, data, options?)` returns a readable stream.
@@ -183,6 +188,7 @@ import { MessageWorkerThread } from '@hile/message-worker-thread'
 - Message files default-export `defineMessage(...)`.
 - RPC callers use `await app.call(...)`.
 - Streaming handlers are async generators.
+- Custom modem timeout values use the documented safe-integer range.
 - Registry is started before application nodes need discovery.
 - Micro apps use stable namespaces and advertise reachable hosts.
 

package/README.md

@@ -69,6 +69,7 @@ const result = await app.call('example.service', '/ping', { hello: 'world' })
 - Do not use `stream()` for normal single-result calls.
 - Do not rely on message IDs for business idempotency. They are transport IDs.
 - Do not bypass `defineMessage()` for file-loaded handlers.
+- Do not pass zero, fractional, non-finite, or oversized message timeouts. Explicit timeout values must be safe integers from `1` through `2_147_483_647` milliseconds.
 
 - Appending a secondary response getter to `client.request('/x', data)`
 - Returning a plain object from a handler called through `stream()`.
@@ -80,6 +81,7 @@ const result = await app.call('example.service', '/ping', { hello: 'world' })
 - Message files default-export `defineMessage(...)`.
 - RPC callers use `await app.call(...)`.
 - Streaming handlers are async generators.
+- Custom modem timeout values use the documented safe-integer range.
 - Registry is started before application nodes need discovery.
 - Micro apps use stable namespaces and advertise reachable hosts.
 

package/dist/application.d.ts

@@ -1,6 +1,6 @@
-import { Client } from './client.js';
+import { Client, type ClientStreamOptions } from './client.js';
 import { Server, type MicroServerProps } from './server.js';
-import type { RegistryAddress, RegistryTopicSnapshot, RegistryTopicSummary } from './registry';
+import type { RegistryAddress, RegistryTopicSnapshot, RegistryTopicSnapshotsResult, RegistryTopicSummary } from './registry';
 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]: {
@@ -68,6 +68,7 @@ export declare class Application extends Server {
     private readonly publishedTopicDirty;
     private readonly publishedTopicVersions;
     private readonly publishedTopicSignatures;
+    private readonly pendingUnpublishes;
     private readonly topicSyncs;
     private readonly topicUpdateVersions;
     private publishIntentVersion;
@@ -112,18 +113,29 @@ export declare class Application extends Server {
         retries?: number;
         signal?: AbortSignal;
     }): Promise<T>;
-    stream(namespace: string, url: string, data: any, options?: {
-        signal?: AbortSignal;
+    stream(namespace: string, url: string, data: any, options?: ClientStreamOptions & {
         retries?: number;
     }): Promise<import('stream').Readable>;
+    /** Opens a stream against one exact service instance without registry selection. */
+    streamPeer(address: RegistryAddress, url: string, data: any, options?: ClientStreamOptions): Promise<import('stream').Readable>;
     publish<T = any>(topic: string, data: T): Promise<{
         update: (payload: T) => Promise</*elided*/ any>;
         unpublish: () => Promise</*elided*/ any>;
     }>;
+    /** Removes a publication intent and retries its Registry tombstone until acknowledged. */
+    unpublish(topic: string, expectedVersion?: number): Promise<void>;
     /** Reads Registry topic metadata without creating a pub/sub subscription. */
-    listRegistryTopics(prefix?: string): Promise<RegistryTopicSummary[]>;
+    listRegistryTopics(prefix?: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RegistryTopicSummary[]>;
+    /** Reads current topic payloads in one Registry round trip. */
+    listRegistryTopicSnapshots(prefix?: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RegistryTopicSnapshotsResult['topics']>;
     /** Reads one retained/current Registry topic payload without subscribing to it. */
-    getRegistryTopic<T = unknown>(topic: string): Promise<RegistryTopicSnapshot & {
+    getRegistryTopic<T = unknown>(topic: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RegistryTopicSnapshot & {
         payload: T;
     } | undefined>;
     /**

package/dist/application.js

@@ -113,6 +113,7 @@ export class Application extends Server {
     publishedTopicDirty = new Set();
     publishedTopicVersions = new Map();
     publishedTopicSignatures = new Map();
+    pendingUnpublishes = new Set();
     topicSyncs = new Map();
     topicUpdateVersions = new Map();
     publishIntentVersion = 0;
@@ -245,6 +246,7 @@ export class Application extends Server {
         return { timeout: this._registryLookupTimeoutMs };
     }
     recordPublishedTopic(topic, payload) {
+        this.pendingUnpublishes.delete(topic);
         const signature = stablePayloadSignature(payload);
         const previousSignature = this.publishedTopicSignatures.get(topic);
         const version = this.publishedTopics.has(topic) && previousSignature === signature
@@ -380,6 +382,11 @@ export class Application extends Server {
                 });
             });
             this.registry = registry;
+            for (const topic of [...this.pendingUnpublishes]) {
+                await this.syncUnpublishedTopic(topic, { propagateError: true });
+                if (!this.publishedTopics.has(topic))
+                    this.pendingUnpublishes.delete(topic);
+            }
             // 重新声明所有仍处于发布状态的 topic
             for (const topic of [...this.publishedTopics.keys()]) {
                 if (this.stopped || this.listenGeneration !== generation) {
@@ -784,7 +791,7 @@ export class Application extends Server {
         }
     }
     async stream(namespace, url, data, options) {
-        const { signal, retries = 1 } = options || {};
+        const { signal, retries = 1, timeout, idleTimeout, window } = options || {};
         let remainingRetries = retries;
         let retrySourceError;
         let hasRetrySourceError = false;
@@ -800,7 +807,7 @@ export class Application extends Server {
             }
             const { client, probe } = selected;
             try {
-                const readable = client.stream(url, data, { signal });
+                const readable = client.stream(url, data, { signal, timeout, idleTimeout, window });
                 return this.trackCircuitStream(namespace, client.host, client.port, probe, readable);
             }
             catch (err) {
@@ -816,6 +823,19 @@ export class Application extends Server {
             }
         }
     }
+    /** Opens a stream against one exact service instance without registry selection. */
+    async streamPeer(address, url, data, options) {
+        assertValidRegistrySocket('peer address', address.host, address.port);
+        if (options?.timeout !== undefined && (!Number.isSafeInteger(options.timeout) || options.timeout < 1 || options.timeout > 2_147_483_647)) {
+            throw new TypeError('Stream timeout must be a positive safe integer not exceeding 2147483647');
+        }
+        const startedAt = Date.now();
+        const client = await this.connect(address.host, address.port, options?.timeout, options?.signal);
+        const timeout = options?.timeout === undefined
+            ? undefined
+            : Math.max(1, options.timeout - (Date.now() - startedAt));
+        return client.stream(url, data, { ...options, timeout });
+    }
     async publish(topic, data) {
         this.assertCanUsePubSub();
         const snapshot = createPubSubPayloadSnapshot(topic, data);
@@ -834,32 +854,61 @@ export class Application extends Server {
                 return ref;
             },
             unpublish: async () => {
-                this.assertCanUsePubSub();
-                if (this.publishedTopicVersions.get(topic) !== refVersion)
-                    return ref;
-                this.publishedTopics.delete(topic);
-                this.publishedTopicRevisions.delete(topic);
-                this.publishedTopicDirty.delete(topic);
-                this.publishedTopicVersions.delete(topic);
-                this.publishedTopicSignatures.delete(topic);
-                await this.syncUnpublishedTopic(topic);
+                await this.unpublish(topic, refVersion);
                 return ref;
             }
         };
         return ref;
     }
+    /** Removes a publication intent and retries its Registry tombstone until acknowledged. */
+    async unpublish(topic, expectedVersion) {
+        const currentVersion = this.publishedTopicVersions.get(topic);
+        if (expectedVersion !== undefined && currentVersion !== expectedVersion && !this.pendingUnpublishes.has(topic))
+            return;
+        if (expectedVersion === undefined || currentVersion === expectedVersion) {
+            this.publishedTopics.delete(topic);
+            this.publishedTopicRevisions.delete(topic);
+            this.publishedTopicDirty.delete(topic);
+            this.publishedTopicVersions.delete(topic);
+            this.publishedTopicSignatures.delete(topic);
+            this.pendingUnpublishes.add(topic);
+        }
+        if (!this.canUsePubSub()) {
+            this.pendingUnpublishes.delete(topic);
+            return;
+        }
+        if (!this.registry) {
+            this.ensureRegistryReconnectScheduled();
+            return;
+        }
+        if (!this.pendingUnpublishes.has(topic))
+            return;
+        await this.syncUnpublishedTopic(topic, { propagateError: true });
+        if (!this.publishedTopics.has(topic))
+            this.pendingUnpublishes.delete(topic);
+    }
     /** Reads Registry topic metadata without creating a pub/sub subscription. */
-    async listRegistryTopics(prefix) {
+    async listRegistryTopics(prefix, options) {
+        const registry = this.registry;
+        if (!registry) {
+            this.ensureRegistryReconnectScheduled();
+            throw new Error('Registry is not connected');
+        }
+        const result = await registry.request('/-/topics', prefix === undefined ? {} : { prefix }, { ...this.registryRequestOptions(), signal: options?.signal });
+        return structuredClone(result.topics);
+    }
+    /** Reads current topic payloads in one Registry round trip. */
+    async listRegistryTopicSnapshots(prefix, options) {
         const registry = this.registry;
         if (!registry) {
             this.ensureRegistryReconnectScheduled();
             throw new Error('Registry is not connected');
         }
-        const result = await registry.request('/-/topics', prefix === undefined ? {} : { prefix }, this.registryRequestOptions());
+        const result = await registry.request('/-/topic/snapshots', prefix === undefined ? {} : { prefix }, { ...this.registryRequestOptions(), signal: options?.signal });
         return structuredClone(result.topics);
     }
     /** Reads one retained/current Registry topic payload without subscribing to it. */
-    async getRegistryTopic(topic) {
+    async getRegistryTopic(topic, options) {
         if (typeof topic !== 'string' || topic.length === 0) {
             throw new TypeError('Registry topic must not be empty');
         }
@@ -868,7 +917,7 @@ export class Application extends Server {
             this.ensureRegistryReconnectScheduled();
             throw new Error('Registry is not connected');
         }
-        const snapshot = await registry.request('/-/topic/get', { topic }, this.registryRequestOptions());
+        const snapshot = await registry.request('/-/topic/get', { topic }, { ...this.registryRequestOptions(), signal: options?.signal });
         return snapshot === undefined ? undefined : structuredClone(snapshot);
     }
     /**

package/dist/client.d.ts

@@ -9,6 +9,12 @@ export interface ClientProps {
     server: Server;
     ws: WebSocket;
 }
+export interface ClientStreamOptions {
+    signal?: AbortSignal;
+    timeout?: number;
+    idleTimeout?: number;
+    window?: number;
+}
 export type MicroMessageMetadata = {
     context?: ContextInput<ContextData>;
     [key: string]: unknown;
@@ -39,8 +45,6 @@ export declare class Client extends MessageWs {
         timeout?: number;
         signal?: AbortSignal;
     }): void;
-    stream(url: string, data: any, options?: {
-        signal?: AbortSignal;
-    }): import("node:stream").Readable;
+    stream(url: string, data: any, options?: ClientStreamOptions): import("node:stream").Readable;
     dispose(): void;
 }

package/dist/registry.d.ts

@@ -42,6 +42,11 @@ export interface RegistryTopicSummary {
 export interface RegistryTopicsResult {
     topics: RegistryTopicSummary[];
 }
+export interface RegistryTopicSnapshotsResult {
+    topics: Array<RegistryTopicSnapshot & {
+        publishers: RegistryAddress[];
+    }>;
+}
 export interface RegistryTopicGetData {
     topic: string;
 }
@@ -96,6 +101,7 @@ export declare class Registry extends Server {
     private createTopicSummary;
     private createTopicSnapshot;
     private listTopicSummaries;
+    private listTopicEntries;
     private registerReadApis;
     private cleanupTopicIfUnused;
     private clearTopicData;

package/dist/registry.js

@@ -182,11 +182,13 @@ export class Registry extends Server {
         };
     }
     listTopicSummaries(prefix) {
+        return this.listTopicEntries(prefix).map(([topic, entry]) => this.createTopicSummary(topic, entry));
+    }
+    listTopicEntries(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));
+            .sort(([a], [b]) => a.localeCompare(b));
     }
     registerReadApis() {
         this.fallbacks.add(this.register('/-/namespaces', async () => {
@@ -215,6 +217,12 @@ export class Registry extends Server {
         this.fallbacks.add(this.register('/-/topics', async ({ data }) => ({
             topics: this.listTopicSummaries(data?.prefix),
         })));
+        this.fallbacks.add(this.register('/-/topic/snapshots', async ({ data }) => ({
+            topics: this.listTopicEntries(data?.prefix).map(([topic, entry]) => ({
+                ...this.createTopicSnapshot(topic, entry),
+                publishers: registryAddressesFromKeys(entry.publishers),
+            })),
+        })));
         this.fallbacks.add(this.register('/-/topic/get', async ({ data }) => {
             if (typeof data?.topic !== 'string')
                 return;

package/dist/server.d.ts

@@ -23,13 +23,16 @@ export declare class Server extends MessageLoader {
     readonly logger: Logger | Console;
     readonly clients: Map<string, Client>;
     private readonly clientExtras;
+    private readonly pendingConnections;
     private readonly announceHost;
     readonly events: EventEmitter<any>;
     get host(): string;
     constructor(namespace: string, props?: MicroServerProps);
     private upstream;
     private createClient;
-    protected connect(host: string, port: number, timeout?: number): Promise<Client>;
+    protected connect(host: string, port: number, timeout?: number, signal?: AbortSignal): Promise<Client>;
+    private openConnection;
+    private waitForConnection;
     listen(port?: number): Promise<() => Promise<void>>;
     setPort(port: number): this;
     handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): this;

package/dist/server.js

@@ -12,6 +12,7 @@ export class Server extends MessageLoader {
     logger;
     clients = new Map();
     clientExtras = new Map();
+    pendingConnections = new Map();
     announceHost;
     events = new EventEmitter();
     get host() {
@@ -79,41 +80,83 @@ export class Server extends MessageLoader {
         this.events.emit('connect', client, extras);
         return client;
     }
-    async connect(host, port, timeout = DEFAULT_CONNECT_TIMEOUT) {
+    async connect(host, port, timeout = DEFAULT_CONNECT_TIMEOUT, signal) {
         const key = `${host}:${port}`;
         if (this.clients.has(key)) {
             return this.clients.get(key);
         }
         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) => {
+        let pending = this.pendingConnections.get(key);
+        if (!pending) {
+            const controller = new AbortController();
+            const promise = this.openConnection(host, port, controller.signal)
+                .then(ws => this.createClient(ws, host, port))
+                .finally(() => { this.pendingConnections.delete(key); });
+            promise.catch(() => undefined);
+            pending = { promise, controller, waiters: 0 };
+            this.pendingConnections.set(key, pending);
+        }
+        pending.waiters++;
+        try {
+            return await this.waitForConnection(pending.promise, timeout, signal);
+        }
+        finally {
+            pending.waiters--;
+            if (pending.waiters === 0 && this.pendingConnections.get(key) === pending)
+                pending.controller.abort();
+        }
+    }
+    openConnection(host, port, signal) {
+        return new Promise((resolve, reject) => {
             const ws = new WebSocket(`ws://${host}:${port}/${this.announceHost}/${this.port}/${this.namespace}`);
-            const timer = setTimeout(() => {
+            const clear = () => {
+                ws.off('open', onopen);
+                ws.off('error', onerror);
+                signal.removeEventListener('abort', onabort);
+            };
+            const terminate = () => {
                 clear();
                 ws.on('error', () => { });
                 try {
                     ws.terminate();
                 }
                 catch { }
-                reject(new Error('Connection timeout'));
-            }, timeout).unref();
-            const clear = () => {
-                clearTimeout(timer);
-                ws.off('open', onopen);
-                ws.off('error', onerror);
             };
             const onerror = (err) => {
                 clear();
                 reject(err);
             };
+            const onabort = () => {
+                reject(signal.reason ?? new Error('Connection aborted'));
+                terminate();
+            };
             const onopen = () => {
                 clear();
                 resolve(ws);
             };
             ws.on('open', onopen);
             ws.on('error', onerror);
+            signal.addEventListener('abort', onabort, { once: true });
+        });
+    }
+    waitForConnection(promise, timeout, signal) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason ?? new Error('Connection aborted'));
+        return new Promise((resolve, reject) => {
+            const timer = Number.isFinite(timeout) && timeout > 0
+                ? setTimeout(() => finish(reject, new Error('Connection timeout')), timeout).unref()
+                : undefined;
+            const onabort = () => finish(reject, signal?.reason ?? new Error('Connection aborted'));
+            const finish = (settle, value) => {
+                if (timer)
+                    clearTimeout(timer);
+                signal?.removeEventListener('abort', onabort);
+                settle(value);
+            };
+            signal?.addEventListener('abort', onabort, { once: true });
+            promise.then(client => finish(resolve, client), error => finish(reject, error));
         });
-        return this.createClient(ws, host, port);
     }
     async listen(port = 0) {
         if (port > 0) {
@@ -141,6 +184,10 @@ export class Server extends MessageLoader {
             this.wss = new WebSocketServer({ noServer: true });
         }
         return async () => {
+            for (const pending of this.pendingConnections.values())
+                pending.controller.abort();
+            await Promise.allSettled([...this.pendingConnections.values()].map(item => item.promise));
+            this.pendingConnections.clear();
             if (this.wss) {
                 // terminate 立即销毁 socket，不等待对端 close frame
                 // 避免 graceful close 时对端无响应导致 HTTP server 无法关闭

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/micro",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -24,13 +24,13 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/context": "^4.0.0",
+    "@hile/context": "^4.0.1",
     "@hile/logger": "^4.0.0",
-    "@hile/message-loader": "^4.0.0",
-    "@hile/message-ws": "^4.0.0",
+    "@hile/message-loader": "^4.0.2",
+    "@hile/message-ws": "^4.0.2",
     "internal-ip": "^9.0.0",
     "ws": "^8.21.0",
     "yaml": "^2.9.0"
   },
-  "gitHead": "b46cb7f3705a226f58e4d65a2ff985ea54b9a159"
+  "gitHead": "46d7bcfc78a914aa2af8cd96e41b08511f5af38e"
 }