@hile/message-modem 3.0.0 → 4.0.1

package/dist/index.d.ts

@@ -3,15 +3,27 @@ export * from './exception.js';
 export declare enum MESSAGE_MODEM_TYPE {
     REQUEST = 0,
     RESPONSE = 1,
-    ABORT = 2
+    ABORT = 2,
+    STREAM_CREDIT = 3
 }
 export interface MessageTransferFormat<T = any> {
     id: number;
     mode: MESSAGE_MODEM_TYPE;
     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;
@@ -28,6 +40,7 @@ export declare abstract class MessageModem {
     private readonly aborts;
     private readonly stacks;
     private readonly streams;
+    private readonly streamProducers;
     protected _dispose(): void;
     /**
      * 创建自增 ID
@@ -75,9 +88,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

@@ -6,12 +6,54 @@ export var MESSAGE_MODEM_TYPE;
     MESSAGE_MODEM_TYPE[MESSAGE_MODEM_TYPE["REQUEST"] = 0] = "REQUEST";
     MESSAGE_MODEM_TYPE[MESSAGE_MODEM_TYPE["RESPONSE"] = 1] = "RESPONSE";
     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) {
+        super({ objectMode: true });
+        this.onConsumed = onConsumed;
+    }
+    _read() {
+        // Credits are tied to actual read() results, not Node's eager buffer filling.
+    }
+    read(size) {
+        const chunk = super.read(size);
+        if (chunk !== null)
+            this.onConsumed();
+        return chunk;
+    }
+}
 export class MessageModem {
     id = 0;
     aborts = new Map();
     stacks = new Map();
     streams = new Map();
+    streamProducers = new Map();
     _dispose() {
         for (const { reject } of this.stacks.values()) {
             reject(new AbortException());
@@ -19,12 +61,16 @@ export class MessageModem {
         for (const controller of this.aborts.values()) {
             controller.abort();
         }
-        for (const stream of this.streams.values()) {
+        for (const { stream } of this.streams.values()) {
             stream.destroy(new AbortException());
         }
+        for (const producer of this.streamProducers.values()) {
+            producer.wake?.();
+        }
         this.aborts.clear();
         this.stacks.clear();
         this.streams.clear();
+        this.streamProducers.clear();
     }
     /**
      * 创建自增 ID
@@ -83,25 +129,105 @@ 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);
-        const stream = new Readable({ objectMode: true, read() { } });
-        this.streams.set(state.id, stream);
-        this.post(state);
+        state.streamVersion = 1;
+        if (window > 1)
+            state.streamWindow = window;
+        let consumer;
+        const stream = new CreditReadable(() => {
+            if (consumer.creditsOwed === 0 || consumer.completed || consumer.cancelled)
+                return;
+            consumer.creditsOwed--;
+            try {
+                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 = () => {
+            if (totalTimer)
+                clearTimeout(totalTimer);
+            if (idleTimer)
+                clearTimeout(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)
+                clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => expire('Stream idle timeout'), idleTimeout);
+            idleTimer.unref?.();
+        };
+        consumer = {
+            stream,
+            completed: false,
+            cancelled: false,
+            creditsOwed: 0,
+            maxCredits: window,
+            nextSeq: 0,
+            nextCreditSeq: 0,
+            touch,
+            clearTimers,
+        };
+        const sendAbort = () => {
+            if (consumer.completed || consumer.cancelled)
+                return;
+            consumer.cancelled = true;
+            try {
+                this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
+            }
+            catch {
+                // The transport may already be closed.
+            }
+        };
         const onAbort = () => {
-            this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
+            sendAbort();
             stream.destroy(new AbortException());
-            this.streams.delete(state.id);
         };
-        if (options?.signal) {
-            options.signal.addEventListener('abort', onAbort);
+        if (options?.signal?.aborted) {
+            consumer.cancelled = true;
+            queueMicrotask(() => stream.destroy(new AbortException()));
+            return stream;
+        }
+        this.streams.set(state.id, consumer);
+        options?.signal?.addEventListener('abort', onAbort, { once: true });
+        if (timeout) {
+            totalTimer = setTimeout(() => expire('Stream timeout'), timeout);
+            totalTimer.unref?.();
         }
+        touch();
         stream.on('close', () => {
+            sendAbort();
+            clearTimers();
             if (this.streams.has(state.id)) {
                 this.streams.delete(state.id);
             }
             options?.signal?.removeEventListener('abort', onAbort);
         });
+        try {
+            this.post(state);
+        }
+        catch (error) {
+            consumer.cancelled = true;
+            this.streams.delete(state.id);
+            queueMicrotask(() => stream.destroy(error));
+        }
         return stream;
     }
     /**
@@ -116,26 +242,32 @@ export class MessageModem {
         const signal = options?.signal;
         // 创建请求消息数据
         const state = this.createPostData(MESSAGE_MODEM_TYPE.REQUEST, data, twoway);
-        // 发送消息
-        this.post(state);
         // 如果消息是单向的，则直接返回
-        if (!twoway)
+        if (!twoway) {
+            if (!signal?.aborted)
+                this.post(state);
             return;
+        }
         return new Promise((resolve, reject) => {
+            let timer;
+            let posted = false;
             const clear = () => {
                 if (this.stacks.has(state.id)) {
                     this.stacks.delete(state.id);
                 }
             };
             const clean = () => {
-                clearTimeout(timer);
+                if (timer)
+                    clearTimeout(timer);
                 signal?.removeEventListener('abort', onAbort);
                 clear();
             };
             const onAbort = () => {
-                clearTimeout(timer);
+                if (timer)
+                    clearTimeout(timer);
                 try {
-                    this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
+                    if (posted)
+                        this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
                 }
                 catch {
                     /* 例如 WebSocket 已关闭时 send 可能抛错 */
@@ -156,12 +288,23 @@ export class MessageModem {
                 clean();
                 reject(e);
             };
-            const timer = setTimeout(() => _reject(new TimeoutException()), timeout).unref();
-            signal?.addEventListener('abort', onAbort);
             this.stacks.set(state.id, {
                 resolve: _resolve,
                 reject: _reject,
             });
+            timer = setTimeout(() => _reject(new TimeoutException()), timeout).unref();
+            signal?.addEventListener('abort', onAbort, { once: true });
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            try {
+                posted = true;
+                this.post(state);
+            }
+            catch (error) {
+                _reject(error);
+            }
         });
     }
     /**
@@ -238,30 +381,97 @@ export class MessageModem {
         }
     }
     onStreamRequest(msg) {
+        if (msg.streamVersion !== 1) {
+            this.post({
+                id: msg.id,
+                mode: MESSAGE_MODEM_TYPE.RESPONSE,
+                stream: true,
+                streamVersion: 1,
+                data: { status: 400, seq: 0, payload: 'Unsupported stream protocol', final: true },
+                twoway: false,
+            });
+            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,
+                mode: MESSAGE_MODEM_TYPE.RESPONSE,
+                stream: true,
+                streamVersion: 1,
+                data: { status: 429, seq: 0, payload: 'Stream capacity exceeded', final: true },
+                twoway: false,
+            });
+            return;
+        }
         const controller = new AbortController();
+        const producer = {
+            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) => {
+                    producer.wake = resolve;
+                });
+                producer.wake = undefined;
+            }
+            if (controller.signal.aborted)
+                throw new AbortException();
+            producer.credits--;
+        };
         this.exec(msg.data, controller.signal)
             .then(async (value) => {
             if (!isAsyncIterable(value)) {
                 throw new Exception(500, 'Invalid async iterable');
             }
-            let i = 0;
-            for await (const chunk of value) {
+            const iterator = value[Symbol.asyncIterator]();
+            producer.iterator = iterator;
+            while (!controller.signal.aborted) {
+                await takeCredit();
+                const next = await iterator.next();
                 if (controller.signal.aborted)
                     return;
+                if (next.done)
+                    break;
                 this.post({
                     id: msg.id,
                     mode: MESSAGE_MODEM_TYPE.RESPONSE,
                     stream: true,
+                    streamVersion: msg.streamVersion,
                     data: {
                         status: 200,
-                        seq: i++,
-                        payload: chunk,
+                        seq: sequence++,
+                        payload: next.value,
                         final: false,
                     },
                     twoway: false,
@@ -273,9 +483,10 @@ export class MessageModem {
                 id: msg.id,
                 mode: MESSAGE_MODEM_TYPE.RESPONSE,
                 stream: true,
+                streamVersion: msg.streamVersion,
                 data: {
                     status: 200,
-                    seq: i++,
+                    seq: sequence++,
                     payload: undefined,
                     final: true,
                 },
@@ -289,16 +500,22 @@ export class MessageModem {
                 id: msg.id,
                 mode: MESSAGE_MODEM_TYPE.RESPONSE,
                 stream: true,
+                streamVersion: msg.streamVersion,
                 data: {
                     status: e instanceof Exception ? e.status : 500,
-                    seq: 0,
-                    payload: e instanceof Exception ? e.message : 'Unknown error',
+                    seq: sequence,
+                    payload: e instanceof Error ? e.message : 'Unknown error',
                     final: true,
                 },
                 twoway: false,
             });
         })
             .finally(() => {
+            if (controller.signal.aborted && producer.iterator?.return) {
+                void Promise.resolve(producer.iterator.return()).catch(() => { });
+            }
+            producer.wake?.();
+            this.streamProducers.delete(msg.id);
             if (this.aborts.has(msg.id)) {
                 this.aborts.delete(msg.id);
             }
@@ -309,22 +526,40 @@ export class MessageModem {
         const res = msg.data;
         // 如果栈中存在该消息，则处理响应消息
         if (this.streams.has(id)) {
-            const stream = this.streams.get(id);
+            const consumer = this.streams.get(id);
+            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;
+                }
+                consumer.nextSeq++;
                 if (res.status === 200) {
                     if (res.final) {
+                        consumer.completed = true;
+                        consumer.clearTimers();
                         stream.push(null);
                     }
                     else {
+                        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));
             }
@@ -365,6 +600,24 @@ export class MessageModem {
                     }
                 }
                 break;
+            case MESSAGE_MODEM_TYPE.STREAM_CREDIT: {
+                const credit = msg.data;
+                if (!credit
+                    || !Number.isSafeInteger(credit.id)
+                    || credit.id < 0
+                    || !Number.isSafeInteger(credit.seq)
+                    || credit.seq < 0)
+                    break;
+                const producer = this.streamProducers.get(credit.id);
+                if (producer
+                    && producer.credits < producer.maxCredits
+                    && credit.seq === producer.nextCreditSeq) {
+                    producer.credits++;
+                    producer.nextCreditSeq++;
+                    producer.wake?.();
+                }
+                break;
+            }
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/message-modem",
-  "version": "3.0.0",
+  "version": "4.0.1",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -18,8 +18,9 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/node": "^26.2.0",
     "fix-esm-import-path": "^1.10.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
+  "gitHead": "fe98c6f8cca2860ccbb213c575cfda44588cbd06"
 }