@hile/message-ws 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/codec.d.ts

@@ -8,4 +8,6 @@ export declare class MessageFrameError extends Error {
     constructor(code: MessageFrameErrorCode, message: string);
 }
 export declare function encodeMessageFrame(message: MessageTransferFormat): string | Buffer;
-export declare function decodeMessageFrame(raw: Buffer | ArrayBuffer | Buffer[] | Uint8Array | string, isBinary: boolean): MessageTransferFormat;
+export declare function decodeMessageFrame(raw: Buffer | ArrayBuffer | Buffer[] | Uint8Array | string, isBinary: boolean, options?: {
+    copyBinaryPayload?: boolean;
+}): MessageTransferFormat;

package/dist/codec.js

@@ -91,7 +91,7 @@ export function encodeMessageFrame(message) {
     payload.copy(frame, HILE_MESSAGE_FRAME_HEADER_SIZE + header.length);
     return frame;
 }
-export function decodeMessageFrame(raw, isBinary) {
+export function decodeMessageFrame(raw, isBinary, options = {}) {
     const bytes = toBuffer(raw);
     if (!isBinary) {
         return parseJson(bytes.toString('utf8'));
@@ -115,11 +115,12 @@ export function decodeMessageFrame(raw, isBinary) {
     const headerEnd = HILE_MESSAGE_FRAME_HEADER_SIZE + headerLength;
     const envelope = parseJson(bytes.subarray(HILE_MESSAGE_FRAME_HEADER_SIZE, headerEnd).toString('utf8'));
     validateBinaryEnvelope(envelope);
+    const payload = bytes.subarray(headerEnd);
     return {
         ...envelope,
         data: {
             ...envelope.data,
-            payload: Buffer.from(bytes.subarray(headerEnd)),
+            payload: options.copyBinaryPayload === false ? payload : Buffer.from(payload),
         },
     };
 }

package/dist/index.js

@@ -30,7 +30,9 @@ export class MessageWs extends MessageModem {
         this.ws = ws;
         this.listener = (raw, isBinary) => {
             try {
-                const msg = decodeMessageFrame(raw, isBinary);
+                // ws owns RawData for the lifetime of the emitted message and does not
+                // mutate it afterwards, so Flight payloads can safely remain views.
+                const msg = decodeMessageFrame(raw, isBinary, { copyBinaryPayload: false });
                 this.receive(msg);
             }
             catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/message-ws",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -24,8 +24,8 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/message-modem": "^4.0.1",
+    "@hile/message-modem": "^4.0.3",
     "ws": "^8.21.0"
   },
-  "gitHead": "fe98c6f8cca2860ccbb213c575cfda44588cbd06"
+  "gitHead": "3ea69973f9373ddb1f7d5d37338966fd7d081d66"
 }