@hile/message-modem 4.0.0 → 4.0.2

package/AI.md

@@ -130,6 +130,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
 
@@ -160,7 +161,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.
@@ -180,6 +185,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/deadline-scheduler.d.ts

@@ -0,0 +1,22 @@
+export interface DeadlineHandle {
+    deadline: number;
+    callback: () => void;
+    index: number;
+    active: boolean;
+}
+/** Maintains many logical deadlines with a single active Node.js timer. */
+export declare class DeadlineScheduler {
+    private readonly heap;
+    private timer?;
+    private armedDeadline?;
+    schedule(delay: number, callback: () => void): DeadlineHandle;
+    reschedule(handle: DeadlineHandle, delay: number): void;
+    cancel(handle: DeadlineHandle | undefined): void;
+    clear(): void;
+    private readonly flush;
+    private arm;
+    private removeAt;
+    private siftUp;
+    private siftDown;
+    private swap;
+}

package/dist/deadline-scheduler.js

@@ -0,0 +1,139 @@
+const MAX_TIMER_DELAY = 2_147_483_647;
+function normalizeDelay(delay) {
+    return Number.isFinite(delay) && delay >= 1 && delay <= MAX_TIMER_DELAY
+        ? delay
+        : 1;
+}
+/** Maintains many logical deadlines with a single active Node.js timer. */
+export class DeadlineScheduler {
+    heap = [];
+    timer;
+    armedDeadline;
+    schedule(delay, callback) {
+        const handle = {
+            deadline: Date.now() + normalizeDelay(delay),
+            callback,
+            index: this.heap.length,
+            active: true,
+        };
+        this.heap.push(handle);
+        this.siftUp(handle.index);
+        this.arm();
+        return handle;
+    }
+    reschedule(handle, delay) {
+        if (!handle.active)
+            return;
+        const previous = handle.deadline;
+        handle.deadline = Date.now() + normalizeDelay(delay);
+        if (handle.deadline < previous)
+            this.siftUp(handle.index);
+        else
+            this.siftDown(handle.index);
+        this.arm();
+    }
+    cancel(handle) {
+        if (!handle?.active)
+            return;
+        handle.active = false;
+        this.removeAt(handle.index);
+        this.arm();
+    }
+    clear() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.armedDeadline = undefined;
+        for (const handle of this.heap) {
+            handle.active = false;
+            handle.index = -1;
+        }
+        this.heap.length = 0;
+    }
+    flush = () => {
+        this.timer = undefined;
+        this.armedDeadline = undefined;
+        let now = Date.now();
+        while (this.heap[0]?.deadline <= now) {
+            const handle = this.removeAt(0);
+            handle.active = false;
+            try {
+                handle.callback();
+            }
+            catch (error) {
+                queueMicrotask(() => { throw error; });
+            }
+            now = Date.now();
+        }
+        this.arm();
+    };
+    arm() {
+        const next = this.heap[0];
+        if (!next) {
+            if (this.timer)
+                clearTimeout(this.timer);
+            this.timer = undefined;
+            this.armedDeadline = undefined;
+            return;
+        }
+        if (this.timer && this.armedDeadline === next.deadline)
+            return;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.armedDeadline = next.deadline;
+        this.timer = setTimeout(this.flush, Math.max(0, next.deadline - Date.now()));
+        this.timer.unref?.();
+    }
+    removeAt(index) {
+        const removed = this.heap[index];
+        const last = this.heap.pop();
+        removed.index = -1;
+        if (index < this.heap.length) {
+            this.heap[index] = last;
+            last.index = index;
+            const parent = index > 0 ? Math.floor((index - 1) / 2) : -1;
+            if (parent >= 0 && this.heap[index].deadline < this.heap[parent].deadline) {
+                this.siftUp(index);
+            }
+            else {
+                this.siftDown(index);
+            }
+        }
+        return removed;
+    }
+    siftUp(start) {
+        let index = start;
+        while (index > 0) {
+            const parent = Math.floor((index - 1) / 2);
+            if (this.heap[parent].deadline <= this.heap[index].deadline)
+                break;
+            this.swap(index, parent);
+            index = parent;
+        }
+    }
+    siftDown(start) {
+        let index = start;
+        while (true) {
+            const left = index * 2 + 1;
+            const right = left + 1;
+            let smallest = index;
+            if (left < this.heap.length && this.heap[left].deadline < this.heap[smallest].deadline) {
+                smallest = left;
+            }
+            if (right < this.heap.length && this.heap[right].deadline < this.heap[smallest].deadline) {
+                smallest = right;
+            }
+            if (smallest === index)
+                return;
+            this.swap(index, smallest);
+            index = smallest;
+        }
+    }
+    swap(left, right) {
+        const value = this.heap[left];
+        this.heap[left] = this.heap[right];
+        this.heap[right] = value;
+        this.heap[left].index = left;
+        this.heap[right].index = right;
+    }
+}

package/dist/index.d.ts

@@ -12,8 +12,18 @@ export interface MessageTransferFormat<T = any> {
     twoway: boolean;
     stream?: boolean;
     streamVersion?: 1;
+    streamWindow?: number;
     data?: T;
 }
+export interface MessageStreamOptions {
+    signal?: AbortSignal;
+    /** Maximum total stream lifetime in milliseconds. */
+    timeout?: number;
+    /** Maximum time between valid stream responses in milliseconds. */
+    idleTimeout?: number;
+    /** Maximum number of produced but not yet consumed chunks. */
+    window?: number;
+}
 export interface MessageReturnFormat<T = any> {
     status: string | number;
     data: T;
@@ -27,6 +37,7 @@ export interface MessageStreamChunk<T = any> {
 }
 export declare abstract class MessageModem {
     private id;
+    private readonly deadlines;
     private readonly aborts;
     private readonly stacks;
     private readonly streams;
@@ -78,9 +89,7 @@ export declare abstract class MessageModem {
         timeout?: number;
         signal?: AbortSignal;
     }): void;
-    protected _stream(data: any, options?: {
-        signal?: AbortSignal;
-    }): Readable;
+    protected _stream(data: any, options?: MessageStreamOptions): Readable;
     /**
      * 写入消息
      * @param data - 消息数据

package/dist/index.js

@@ -1,5 +1,6 @@
 import { AbortException, Exception, TimeoutException } from "./exception.js";
 import { Readable } from 'node:stream';
+import { DeadlineScheduler } from './deadline-scheduler.js';
 export * from './exception.js';
 export var MESSAGE_MODEM_TYPE;
 (function (MESSAGE_MODEM_TYPE) {
@@ -8,6 +9,30 @@ export var MESSAGE_MODEM_TYPE;
     MESSAGE_MODEM_TYPE[MESSAGE_MODEM_TYPE["ABORT"] = 2] = "ABORT";
     MESSAGE_MODEM_TYPE[MESSAGE_MODEM_TYPE["STREAM_CREDIT"] = 3] = "STREAM_CREDIT";
 })(MESSAGE_MODEM_TYPE || (MESSAGE_MODEM_TYPE = {}));
+const MAX_STREAM_WINDOW = 64;
+const MAX_TIMER_DELAY = 2_147_483_647;
+function streamLimit(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError(`${name} must be a positive safe integer`);
+    }
+    return value;
+}
+function streamWindow(value) {
+    const normalized = streamLimit(value, 'Stream window') ?? 1;
+    if (normalized > MAX_STREAM_WINDOW) {
+        throw new TypeError(`Stream window must not exceed ${MAX_STREAM_WINDOW}`);
+    }
+    return normalized;
+}
+function streamTimeout(value, name) {
+    const normalized = streamLimit(value, name);
+    if (normalized !== undefined && normalized > MAX_TIMER_DELAY) {
+        throw new TypeError(`${name} must not exceed ${MAX_TIMER_DELAY}`);
+    }
+    return normalized;
+}
 class CreditReadable extends Readable {
     onConsumed;
     constructor(onConsumed) {
@@ -26,6 +51,7 @@ class CreditReadable extends Readable {
 }
 export class MessageModem {
     id = 0;
+    deadlines = new DeadlineScheduler();
     aborts = new Map();
     stacks = new Map();
     streams = new Map();
@@ -47,6 +73,7 @@ export class MessageModem {
         this.stacks.clear();
         this.streams.clear();
         this.streamProducers.clear();
+        this.deadlines.clear();
     }
     /**
      * 创建自增 ID
@@ -105,28 +132,59 @@ export class MessageModem {
             signal: options?.signal,
         });
     }
-    _stream(data, options) {
+    _stream(data, options = {}) {
+        const window = streamWindow(options.window);
+        const timeout = streamTimeout(options.timeout, 'Stream timeout');
+        const idleTimeout = streamTimeout(options.idleTimeout, 'Stream idle timeout');
         const state = this.createPostData(MESSAGE_MODEM_TYPE.REQUEST, data, true, true);
         state.streamVersion = 1;
+        if (window > 1)
+            state.streamWindow = window;
         let consumer;
         const stream = new CreditReadable(() => {
-            if (!consumer.creditOwed || consumer.completed || consumer.cancelled)
+            if (consumer.creditsOwed === 0 || consumer.completed || consumer.cancelled)
                 return;
-            consumer.creditOwed = false;
+            consumer.creditsOwed--;
             try {
-                this.post(this.createPostData(MESSAGE_MODEM_TYPE.STREAM_CREDIT, { id: state.id, seq: consumer.nextSeq - 1 }, false));
+                this.post(this.createPostData(MESSAGE_MODEM_TYPE.STREAM_CREDIT, { id: state.id, seq: consumer.nextCreditSeq++ }, false));
             }
             catch (error) {
                 consumer.cancelled = true;
                 stream.destroy(error);
             }
         });
+        let totalTimer;
+        let idleTimer;
+        const clearTimers = () => {
+            this.deadlines.cancel(totalTimer);
+            this.deadlines.cancel(idleTimer);
+            totalTimer = undefined;
+            idleTimer = undefined;
+        };
+        const expire = (message) => {
+            if (consumer.completed || consumer.cancelled)
+                return;
+            sendAbort();
+            stream.destroy(new TimeoutException(message));
+        };
+        const touch = () => {
+            if (!idleTimeout || consumer.completed || consumer.cancelled)
+                return;
+            if (idleTimer)
+                this.deadlines.reschedule(idleTimer, idleTimeout);
+            else
+                idleTimer = this.deadlines.schedule(idleTimeout, () => expire('Stream idle timeout'));
+        };
         consumer = {
             stream,
             completed: false,
             cancelled: false,
-            creditOwed: false,
+            creditsOwed: 0,
+            maxCredits: window,
             nextSeq: 0,
+            nextCreditSeq: 0,
+            touch,
+            clearTimers,
         };
         const sendAbort = () => {
             if (consumer.completed || consumer.cancelled)
@@ -150,11 +208,14 @@ export class MessageModem {
         }
         this.streams.set(state.id, consumer);
         options?.signal?.addEventListener('abort', onAbort, { once: true });
+        if (timeout) {
+            totalTimer = this.deadlines.schedule(timeout, () => expire('Stream timeout'));
+        }
+        touch();
         stream.on('close', () => {
             sendAbort();
-            if (this.streams.has(state.id)) {
-                this.streams.delete(state.id);
-            }
+            clearTimers();
+            this.streams.delete(state.id);
             options?.signal?.removeEventListener('abort', onAbort);
         });
         try {
@@ -174,7 +235,7 @@ export class MessageModem {
      * @returns 消息响应
      */
     _write(data, options) {
-        const timeout = options?.timeout ?? 30000;
+        const timeout = streamTimeout(options?.timeout ?? 30000, 'Message timeout');
         const twoway = !!options?.twoway;
         const signal = options?.signal;
         // 创建请求消息数据
@@ -189,19 +250,17 @@ export class MessageModem {
             let timer;
             let posted = false;
             const clear = () => {
-                if (this.stacks.has(state.id)) {
-                    this.stacks.delete(state.id);
-                }
+                this.stacks.delete(state.id);
             };
             const clean = () => {
-                if (timer)
-                    clearTimeout(timer);
+                this.deadlines.cancel(timer);
+                timer = undefined;
                 signal?.removeEventListener('abort', onAbort);
                 clear();
             };
             const onAbort = () => {
-                if (timer)
-                    clearTimeout(timer);
+                this.deadlines.cancel(timer);
+                timer = undefined;
                 try {
                     if (posted)
                         this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
@@ -229,7 +288,7 @@ export class MessageModem {
                 resolve: _resolve,
                 reject: _reject,
             });
-            timer = setTimeout(() => _reject(new TimeoutException()), timeout).unref();
+            timer = this.deadlines.schedule(timeout, () => _reject(new TimeoutException()));
             signal?.addEventListener('abort', onAbort, { once: true });
             if (signal?.aborted) {
                 onAbort();
@@ -251,11 +310,6 @@ export class MessageModem {
     onRequest(msg) {
         const controller = new AbortController();
         this.aborts.set(msg.id, controller);
-        controller.signal.addEventListener('abort', () => {
-            if (this.aborts.has(msg.id)) {
-                this.aborts.delete(msg.id);
-            }
-        });
         this.exec(msg.data, controller.signal)
             .then(value => {
             if (controller.signal.aborted)
@@ -292,10 +346,7 @@ export class MessageModem {
             }
         })
             .finally(() => {
-            // 删除 Abort 处理函数
-            if (this.aborts.has(msg.id)) {
-                this.aborts.delete(msg.id);
-            }
+            this.aborts.delete(msg.id);
         });
     }
     /**
@@ -305,9 +356,10 @@ export class MessageModem {
     onResponse(msg) {
         const id = msg.id;
         const res = msg.data;
+        const stack = this.stacks.get(id);
         // 如果栈中存在该消息，则处理响应消息
-        if (this.stacks.has(id)) {
-            const { resolve, reject } = this.stacks.get(id);
+        if (stack) {
+            const { resolve, reject } = stack;
             // 如果响应状态码不是 200，则拒绝响应
             if (res?.status !== 200) {
                 reject(new Exception(res?.status, res?.message));
@@ -329,6 +381,26 @@ export class MessageModem {
             });
             return;
         }
+        let window;
+        try {
+            window = streamWindow(msg.streamWindow);
+        }
+        catch (error) {
+            this.post({
+                id: msg.id,
+                mode: MESSAGE_MODEM_TYPE.RESPONSE,
+                stream: true,
+                streamVersion: 1,
+                data: {
+                    status: 400,
+                    seq: 0,
+                    payload: error instanceof Error ? error.message : 'Invalid stream window',
+                    final: true,
+                },
+                twoway: false,
+            });
+            return;
+        }
         if (this.streamProducers.has(msg.id) || this.streamProducers.size >= 128) {
             this.post({
                 id: msg.id,
@@ -342,18 +414,13 @@ export class MessageModem {
         }
         const controller = new AbortController();
         const producer = {
-            credits: 1,
+            credits: window,
+            maxCredits: window,
             nextCreditSeq: 0,
         };
         let sequence = 0;
         this.aborts.set(msg.id, controller);
         this.streamProducers.set(msg.id, producer);
-        controller.signal.addEventListener('abort', () => {
-            producer.wake?.();
-            if (this.aborts.has(msg.id)) {
-                this.aborts.delete(msg.id);
-            }
-        });
         const takeCredit = async () => {
             while (producer.credits === 0 && !controller.signal.aborted) {
                 await new Promise((resolve) => {
@@ -432,19 +499,18 @@ export class MessageModem {
             }
             producer.wake?.();
             this.streamProducers.delete(msg.id);
-            if (this.aborts.has(msg.id)) {
-                this.aborts.delete(msg.id);
-            }
+            this.aborts.delete(msg.id);
         });
     }
     onStreamResponse(msg) {
         const id = msg.id;
         const res = msg.data;
+        const consumer = this.streams.get(id);
         // 如果栈中存在该消息，则处理响应消息
-        if (this.streams.has(id)) {
-            const consumer = this.streams.get(id);
+        if (consumer) {
             const stream = consumer.stream;
             if (res) {
+                consumer.touch();
                 if (!Number.isSafeInteger(res.seq) || res.seq !== consumer.nextSeq) {
                     stream.destroy(new Exception(409, `Invalid stream sequence: expected ${consumer.nextSeq}, received ${String(res.seq)}`));
                     return;
@@ -453,21 +519,28 @@ export class MessageModem {
                 if (res.status === 200) {
                     if (res.final) {
                         consumer.completed = true;
+                        consumer.clearTimers();
                         stream.push(null);
                     }
                     else {
-                        consumer.creditOwed = true;
+                        if (consumer.creditsOwed >= consumer.maxCredits) {
+                            stream.destroy(new Exception(429, 'Stream window exceeded'));
+                            return;
+                        }
+                        consumer.creditsOwed++;
                         stream.push(res.payload);
                     }
                 }
                 else {
                     consumer.completed = true;
+                    consumer.clearTimers();
                     const err = new Exception(res.status, res.payload);
                     setImmediate(() => stream.destroy(err));
                 }
             }
             else {
                 consumer.completed = true;
+                consumer.clearTimers();
                 const err = new Exception(404, 'Empty chunk data');
                 setImmediate(() => stream.destroy(err));
             }
@@ -499,15 +572,18 @@ export class MessageModem {
                 }
                 break;
             // 处理终止消息
-            case MESSAGE_MODEM_TYPE.ABORT:
+            case MESSAGE_MODEM_TYPE.ABORT: {
                 const id = msg.data;
-                if (this.aborts.has(id)) {
-                    const controller = this.aborts.get(id);
+                const controller = this.aborts.get(id);
+                if (controller) {
+                    this.aborts.delete(id);
+                    this.streamProducers.get(id)?.wake?.();
                     if (!controller.signal.aborted) {
                         controller.abort();
                     }
                 }
                 break;
+            }
             case MESSAGE_MODEM_TYPE.STREAM_CREDIT: {
                 const credit = msg.data;
                 if (!credit
@@ -517,8 +593,10 @@ export class MessageModem {
                     || credit.seq < 0)
                     break;
                 const producer = this.streamProducers.get(credit.id);
-                if (producer && producer.credits === 0 && credit.seq === producer.nextCreditSeq) {
-                    producer.credits = 1;
+                if (producer
+                    && producer.credits < producer.maxCredits
+                    && credit.seq === producer.nextCreditSeq) {
+                    producer.credits++;
                     producer.nextCreditSeq++;
                     producer.wake?.();
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/message-modem",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -22,5 +22,5 @@
     "fix-esm-import-path": "^1.10.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "b46cb7f3705a226f58e4d65a2ff985ea54b9a159"
+  "gitHead": "46d7bcfc78a914aa2af8cd96e41b08511f5af38e"
 }