@hile/message-modem 4.0.1 → 4.0.3

package/AI.md

@@ -32,13 +32,14 @@ Message handler file:
 
 ```ts
 // src/messages/ping.msg.ts
-import { defineMessage } from '@hile/message-loader'
+import { defineMicroMessage } from '@hile/micro'
 
-export default defineMessage(async ({ data, params }) => {
+export default defineMicroMessage(async ({ data, params, invocation }) => {
   return {
     type: 'pong',
     data,
     params,
+    requestId: invocation.context.values.requestId,
     timestamp: Date.now(),
   }
 })
@@ -71,7 +72,11 @@ export default defineService('micro.app', async (shutdown) => {
 Caller:
 
 ```ts
-const result = await app.call('example.service', '/ping', { hello: 'world' })
+import { randomUUID } from 'node:crypto'
+import { createExecutionContext } from '@hile/context'
+
+const context = createExecutionContext({ requestId: randomUUID() })
+const result = await app.call('example.service', '/ping', { hello: 'world' }, { context })
 ```
 
 ## More Examples
@@ -80,11 +85,11 @@ Streaming handler:
 
 ```ts
 // src/messages/events.msg.ts
-import { defineMessage } from '@hile/message-loader'
+import { defineMicroMessage } from '@hile/micro'
 
-export default defineMessage(async function* () {
+export default defineMicroMessage(async function* ({ invocation }) {
   for (let i = 0; i < 3; i++) {
-    yield { seq: i }
+    yield { seq: i, requestId: invocation.context.values.requestId }
   }
 })
 ```
@@ -92,7 +97,7 @@ export default defineMessage(async function* () {
 Streaming caller:
 
 ```ts
-const stream = await app.stream('example.service', '/events', {})
+const stream = await app.stream('example.service', '/events', {}, { context })
 for await (const chunk of stream) {
   console.log(chunk)
 }
@@ -129,12 +134,13 @@ 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.
+- Use `defineMicroMessage()` for Micro business handlers; reserve generic `defineMessage()` for transport-neutral loaders.
+- 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
 
 ```bash
-pnpm add @hile/micro @hile/message-loader @hile/message-ws
+pnpm add @hile/context @hile/micro @hile/message-loader @hile/message-ws
 ```
 
 Use transport-specific packages only when you need to build custom IPC or worker-thread bridges.
@@ -143,7 +149,8 @@ Use transport-specific packages only when you need to build custom IPC or worker
 
 ```ts
 import { defineMessage, MessageLoader } from '@hile/message-loader'
-import { Application, Registry, Server } from '@hile/micro'
+import { createExecutionContext } from '@hile/context'
+import { Application, defineMicroMessage, Registry, Server } from '@hile/micro'
 import { MessageWs } from '@hile/message-ws'
 import { MessageIpc } from '@hile/message-ipc'
 import { MessageWorkerThread } from '@hile/message-worker-thread'
@@ -151,7 +158,7 @@ import { MessageWorkerThread } from '@hile/message-worker-thread'
 
 ## Compose With
 
-- `@hile/context` propagates context in micro message metadata.
+- Pass `ExecutionContext` explicitly in every business call or stream option; the receiver gets it in `invocation.context`.
 - `@hile/redis-idempotency` protects retryable side effects in message handlers.
 - `@hile/redis-stream-queue` is better for durable background jobs.
 
@@ -160,10 +167,14 @@ 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.
+- `Application.call(namespace, url, data, options)` requires `options.context` and returns a promise.
+- `Application.stream(namespace, url, data, options)` requires `options.context` and returns a readable stream.
 - `Application.publish(topic, payload)` returns an object with `update()` and `unpublish()`.
 - `Application.subscribe(topic, callback)` returns an unsubscribe function.
 - `Registry` stores service addresses and retained config/topic state under `~/.registry`.
@@ -177,9 +188,10 @@ import { MessageWorkerThread } from '@hile/message-worker-thread'
 
 ## Verification Checklist
 
-- Message files default-export `defineMessage(...)`.
-- RPC callers use `await app.call(...)`.
+- Micro message files default-export `defineMicroMessage(...)` and receive `invocation.context`.
+- RPC callers use `await app.call(..., { context })`.
 - 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.
 
@@ -197,10 +209,10 @@ Provider handler:
 
 ```ts
 // src/messages/charge.msg.ts
-import { defineMessage } from '@hile/message-loader'
+import { defineMicroMessage } from '@hile/micro'
 
-export default defineMessage(async ({ data }) => {
-  return { charged: true, input: data }
+export default defineMicroMessage(async ({ data, invocation }) => {
+  return { charged: true, input: data, requestId: invocation.context.values.requestId }
 })
 ```
 
@@ -228,10 +240,14 @@ export default defineService('billing.micro', async (shutdown) => {
 Consumer:
 
 ```ts
+import { randomUUID } from 'node:crypto'
+import { createExecutionContext } from '@hile/context'
+
+const context = createExecutionContext({ requestId: randomUUID(), tenantId: 't1' })
 const result = await app.call('billing', '/charge', {
   tenantId: 't1',
   amount: 100,
-})
+}, { context })
 ```
 
 ## File Layout
@@ -251,16 +267,15 @@ Use this recipe when services communicate over Hile registry-backed RPC.
 ## Packages To Use
 
 - `@hile/micro`
-- `@hile/message-loader`
-- `@hile/context` when context must cross service boundaries
+- `@hile/context` for the required explicit execution context carrier
 - `@hile/redis-idempotency` for retryable side effects
 
 ## Implementation Steps
 
 1. Start a Registry with `hile registry`.
 2. Start providers with stable namespaces.
-3. Load `*.msg.ts` handlers through `app.load()`.
-4. Call providers with `await app.call(namespace, url, data)`.
+3. Default-export `defineMicroMessage()` handlers and load them through `app.load()`.
+4. Create context at ingress and call providers with `await app.call(namespace, url, data, { context })`.
 5. Use `app.stream()` only for async-generator handlers.
 
 ## Failure And Cleanup Behavior
@@ -273,8 +288,8 @@ Use this recipe when services communicate over Hile registry-backed RPC.
 
 - Registry is reachable.
 - Provider namespace matches consumer call.
-- Handlers default-export `defineMessage()`.
-- Consumer code awaits `app.call(...)` directly.
+- Handlers default-export `defineMicroMessage()` and consume explicit invocation context when needed.
+- Consumer code awaits `app.call(..., { context })` directly.
 
 
 

package/README.md

@@ -22,13 +22,14 @@ Message handler file:
 
 ```ts
 // src/messages/ping.msg.ts
-import { defineMessage } from '@hile/message-loader'
+import { defineMicroMessage } from '@hile/micro'
 
-export default defineMessage(async ({ data, params }) => {
+export default defineMicroMessage(async ({ data, params, invocation }) => {
   return {
     type: 'pong',
     data,
     params,
+    requestId: invocation.context.values.requestId,
     timestamp: Date.now(),
   }
 })
@@ -61,14 +62,19 @@ export default defineService('micro.app', async (shutdown) => {
 Caller:
 
 ```ts
-const result = await app.call('example.service', '/ping', { hello: 'world' })
+import { randomUUID } from 'node:crypto'
+import { createExecutionContext } from '@hile/context'
+
+const context = createExecutionContext({ requestId: randomUUID() })
+const result = await app.call('example.service', '/ping', { hello: 'world' }, { context })
 ```
 
 ## Boundaries
 
 - 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.
+- Use `defineMicroMessage()` for Micro business handlers; reserve generic `defineMessage()` for transport-neutral loaders.
+- 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()`.
@@ -77,9 +83,10 @@ const result = await app.call('example.service', '/ping', { hello: 'world' })
 
 ## Verify
 
-- Message files default-export `defineMessage(...)`.
-- RPC callers use `await app.call(...)`.
+- Micro message files default-export `defineMicroMessage(...)` and receive `invocation.context`.
+- RPC callers use `await app.call(..., { context })`.
 - 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

@@ -37,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;

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) {
@@ -50,6 +51,7 @@ class CreditReadable extends Readable {
 }
 export class MessageModem {
     id = 0;
+    deadlines = new DeadlineScheduler();
     aborts = new Map();
     stacks = new Map();
     streams = new Map();
@@ -71,6 +73,7 @@ export class MessageModem {
         this.stacks.clear();
         this.streams.clear();
         this.streamProducers.clear();
+        this.deadlines.clear();
     }
     /**
      * 创建自增 ID
@@ -153,10 +156,8 @@ export class MessageModem {
         let totalTimer;
         let idleTimer;
         const clearTimers = () => {
-            if (totalTimer)
-                clearTimeout(totalTimer);
-            if (idleTimer)
-                clearTimeout(idleTimer);
+            this.deadlines.cancel(totalTimer);
+            this.deadlines.cancel(idleTimer);
             totalTimer = undefined;
             idleTimer = undefined;
         };
@@ -170,9 +171,9 @@ export class MessageModem {
             if (!idleTimeout || consumer.completed || consumer.cancelled)
                 return;
             if (idleTimer)
-                clearTimeout(idleTimer);
-            idleTimer = setTimeout(() => expire('Stream idle timeout'), idleTimeout);
-            idleTimer.unref?.();
+                this.deadlines.reschedule(idleTimer, idleTimeout);
+            else
+                idleTimer = this.deadlines.schedule(idleTimeout, () => expire('Stream idle timeout'));
         };
         consumer = {
             stream,
@@ -208,16 +209,13 @@ export class MessageModem {
         this.streams.set(state.id, consumer);
         options?.signal?.addEventListener('abort', onAbort, { once: true });
         if (timeout) {
-            totalTimer = setTimeout(() => expire('Stream timeout'), timeout);
-            totalTimer.unref?.();
+            totalTimer = this.deadlines.schedule(timeout, () => expire('Stream timeout'));
         }
         touch();
         stream.on('close', () => {
             sendAbort();
             clearTimers();
-            if (this.streams.has(state.id)) {
-                this.streams.delete(state.id);
-            }
+            this.streams.delete(state.id);
             options?.signal?.removeEventListener('abort', onAbort);
         });
         try {
@@ -237,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;
         // 创建请求消息数据
@@ -252,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));
@@ -292,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();
@@ -314,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)
@@ -355,10 +346,7 @@ export class MessageModem {
             }
         })
             .finally(() => {
-            // 删除 Abort 处理函数
-            if (this.aborts.has(msg.id)) {
-                this.aborts.delete(msg.id);
-            }
+            this.aborts.delete(msg.id);
         });
     }
     /**
@@ -368,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));
@@ -432,12 +421,6 @@ export class MessageModem {
         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) => {
@@ -516,17 +499,15 @@ 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();
@@ -591,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/message-modem",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -22,5 +22,5 @@
     "fix-esm-import-path": "^1.10.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "fe98c6f8cca2860ccbb213c575cfda44588cbd06"
+  "gitHead": "3ea69973f9373ddb1f7d5d37338966fd7d081d66"
 }