@hile/message-modem 2.0.3 → 3.0.0

package/AI.md

@@ -0,0 +1,295 @@
+# AI Guide For @hile/message-modem
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Implement request/response, push, abort, and stream protocol behavior independent of transport.
+
+
+
+Use this file when an AI agent installs the npm package and needs package-local examples, package selection rules, boundaries, and verification steps.
+
+
+
+## Package Selection
+
+
+
+Use `@hile/message-modem` for: Implement request/response, push, abort, and stream protocol behavior independent of transport.
+
+
+
+# Messaging And Microservices
+
+Packages: `@hile/message-modem`, `@hile/message-ws`, `@hile/message-ipc`, `@hile/message-worker-thread`, `@hile/message-loader`, `@hile/micro`, `@hile/micro-dynamic-configs`.
+
+## Copy-Paste Example
+
+Message handler file:
+
+```ts
+// src/messages/ping.msg.ts
+import { defineMessage } from '@hile/message-loader'
+
+export default defineMessage(async ({ data, params }) => {
+  return {
+    type: 'pong',
+    data,
+    params,
+    timestamp: Date.now(),
+  }
+})
+```
+
+Microservice boot file:
+
+```ts
+// src/services/app.boot.ts
+import { defineService } from '@hile/core'
+import { Application } from '@hile/micro'
+
+export default defineService('micro.app', async (shutdown) => {
+  const app = new Application({
+    namespace: process.env.MICRO_NAMESPACE ?? 'example.service',
+    registry: {
+      host: process.env.REGISTRY_HOST ?? '127.0.0.1',
+      port: Number(process.env.REGISTRY_PORT ?? 9876),
+    },
+    advertiseHost: process.env.HILE_ADVERTISE_HOST ?? '127.0.0.1',
+  })
+
+  await app.load(new URL('../messages', import.meta.url).pathname)
+  const stop = await app.listen(Number(process.env.MICRO_PORT ?? 0))
+  shutdown(stop)
+  return app
+})
+```
+
+Caller:
+
+```ts
+const result = await app.call('example.service', '/ping', { hello: 'world' })
+```
+
+## More Examples
+
+Streaming handler:
+
+```ts
+// src/messages/events.msg.ts
+import { defineMessage } from '@hile/message-loader'
+
+export default defineMessage(async function* () {
+  for (let i = 0; i < 3; i++) {
+    yield { seq: i }
+  }
+})
+```
+
+Streaming caller:
+
+```ts
+const stream = await app.stream('example.service', '/events', {})
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+```
+
+Custom WebSocket modem:
+
+```ts
+import { MessageWs } from '@hile/message-ws'
+import type WebSocket from 'ws'
+
+class RpcWs extends MessageWs {
+  constructor(ws: WebSocket, private readonly dispatch: (url: string, data: unknown) => Promise<unknown>) {
+    super(ws)
+  }
+
+  protected exec(data: { url: string; data: unknown }) {
+    return this.dispatch(data.url, data.data)
+  }
+
+  request<T>(url: string, data: unknown, timeout = 30_000) {
+    return this._send<T>({ url, data }, { timeout })
+  }
+}
+```
+
+Notice that `request()` returns a `Promise<T>`. Await it directly.
+
+## Use When
+
+Use the message packages for request/response messaging over WebSocket, process IPC, worker threads, file-system message handlers, service discovery, streaming RPC, and registry-backed pub/sub.
+
+## Do Not Use When
+
+- 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.
+
+## Install
+
+```bash
+pnpm add @hile/micro @hile/message-loader @hile/message-ws
+```
+
+Use transport-specific packages only when you need to build custom IPC or worker-thread bridges.
+
+## Imports
+
+```ts
+import { defineMessage, MessageLoader } from '@hile/message-loader'
+import { Application, Registry, Server } from '@hile/micro'
+import { MessageWs } from '@hile/message-ws'
+import { MessageIpc } from '@hile/message-ipc'
+import { MessageWorkerThread } from '@hile/message-worker-thread'
+```
+
+## Compose With
+
+- `@hile/context` propagates context in micro message metadata.
+- `@hile/redis-idempotency` protects retryable side effects in message handlers.
+- `@hile/redis-stream-queue` is better for durable background jobs.
+
+## Runtime And Lifecycle Notes
+
+- `MessageLoader` maps `*.msg.*` files to routes using `@hile/loader`.
+- `MessageLoader.dispatch(path, data, extras?)` invokes the matched handler.
+- `MessageModem._send()` returns a `Promise`.
+- `MessageModem._stream()` returns a Node `Readable` in object mode.
+- 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.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`.
+
+## Anti-Patterns
+
+- Appending a secondary response getter to `client.request('/x', data)`
+- Returning a plain object from a handler called through `stream()`.
+- Using pub/sub as a durable queue.
+- Forgetting to register `shutdown(await app.listen(...))`.
+
+## Verification Checklist
+
+- Message files default-export `defineMessage(...)`.
+- RPC callers use `await app.call(...)`.
+- Streaming handlers are async generators.
+- Registry is started before application nodes need discovery.
+- Micro apps use stable namespaces and advertise reachable hosts.
+
+
+
+# Related Recipes
+
+
+
+# Micro RPC With Message Loader
+
+## Complete Example
+
+Provider handler:
+
+```ts
+// src/messages/charge.msg.ts
+import { defineMessage } from '@hile/message-loader'
+
+export default defineMessage(async ({ data }) => {
+  return { charged: true, input: data }
+})
+```
+
+Provider boot:
+
+```ts
+// src/services/app.boot.ts
+import { defineService } from '@hile/core'
+import { Application } from '@hile/micro'
+
+export default defineService('billing.micro', async (shutdown) => {
+  const app = new Application({
+    namespace: 'billing',
+    registry: { host: '127.0.0.1', port: 9876 },
+    advertiseHost: '127.0.0.1',
+  })
+
+  await app.load(new URL('../messages', import.meta.url).pathname)
+  const stop = await app.listen(9101)
+  shutdown(stop)
+  return app
+})
+```
+
+Consumer:
+
+```ts
+const result = await app.call('billing', '/charge', {
+  tenantId: 't1',
+  amount: 100,
+})
+```
+
+## File Layout
+
+```text
+provider/
+  src/messages/charge.msg.ts
+  src/services/app.boot.ts
+consumer/
+  src/models/payments/pay.model.ts
+```
+
+## User Intent
+
+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/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)`.
+5. Use `app.stream()` only for async-generator handlers.
+
+## Failure And Cleanup Behavior
+
+- `Application.call()` may retry; side-effecting handlers need idempotency.
+- Registry disconnect triggers reconnect; apps re-declare topics and subscriptions.
+- Circuit breaker excludes failing nodes for cooldown.
+
+## Verification Checklist
+
+- Registry is reachable.
+- Provider namespace matches consumer call.
+- Handlers default-export `defineMessage()`.
+- Consumer code awaits `app.call(...)` directly.
+
+
+
+# Global Guardrails
+
+
+
+## Never Generate These Patterns
+
+- Do not call `loadService()` at module top level; it starts resources during import.
+- Do not default-export plain functions from `*.boot.*` files; `hile start` expects a Hile service.
+- Do not set `ctx.body` and also return a controller value.
+- Do not assume `@hile/http` Zod validation mutates or coerces `ctx.query`, `ctx.params`, or `ctx.request.body`.
+- Do not put reusable business logic only in controllers, pages, queue workers, or message handlers.
+- Do not use old message examples that append a secondary response getter; current request APIs return promises directly.
+- Do not claim exactly-once delivery or execution from Redis locks, queues, idempotency, or rate limits.
+- Do not use queue `jobId` as the only side-effect idempotency boundary.
+- Do not log the entire async context by default.

package/README.md

@@ -1,215 +1,90 @@
 # @hile/message-modem
 
-传输无关的请求/响应消息通信抽象层。将底层传输机制（WebSocket、postMessage、IPC 等）与业务逻辑解耦，提供统一的 _send/receive 语义。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 安装
+Implement request/response, push, abort, and stream protocol behavior independent of transport.
 
-```bash
-pnpm add @hile/message-modem
-```
-
-## 核心特性
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-- **传输无关** — 子类只需实现 `post`（如何发送）和 `exec`（如何处理），即可运行于任何通信通道
-- **双向请求/响应** — `_send` 发送请求并等待对端响应（`twoway: true`）
-- **单向推送** — `_push` 发送消息无需对端响应（`twoway: false`）
-- **流式传输** — `_stream` 发送流式请求，对端返回 async generator 时分块回传，发送方获得 `Readable` stream
-- **请求/响应配对** — 自增 ID + Promise 栈，自动配对请求与响应
-- **超时控制** — 默认 30 秒，可按请求自定义
-- **主动中止** — 发送方可 abort 等待，接收方可取消正在执行的任务
-- **错误传播** — `Exception` 携带 status 码透传；普通 Error 映射为 500
+## When To Use
 
-## 快速开始
-
-### 第一步：继承并实现抽象方法
-
-```typescript
-import { MessageModem, type MessageTransferFormat } from '@hile/message-modem';
-
-class WebSocketModem extends MessageModem {
-  constructor(private ws: WebSocket) {
-    super();
-    ws.addEventListener('message', (e) => {
-      this.receive(JSON.parse(e.data));
-    });
-  }
-
-  protected post<T>(data: MessageTransferFormat<T>): void {
-    this.ws.send(JSON.stringify(data));
-  }
-
-  protected async exec(data: any): Promise<any> {
-    // 处理远端请求
-    return handleRequest(data);
-  }
-
-  // 暴露发送方法
-  public request<T>(data: T, timeout?: number) {
-    return this._send(data, timeout);
-  }
-}
-```
+Use the message packages for request/response messaging over WebSocket, process IPC, worker threads, file-system message handlers, service discovery, streaming RPC, and registry-backed pub/sub.
 
-### 第二步：发送请求
+## Install
 
-```typescript
-const modem = new WebSocketModem(ws);
-
-const { abort, response } = modem.request({ action: 'getUser', id: 1 });
-
-// 等待响应
-const user = await response();
-console.log(user);
-
-// 或中止请求
-abort();
+```bash
+pnpm add @hile/message-modem
 ```
 
-### 第三步：处理超时与异常
+## Copy-Paste Example
 
-所有异常类均从主入口导出，无需单独引入：
+Message handler file:
 
-```typescript
-import { AbortException, Exception } from '@hile/message-modem';
+```ts
+// src/messages/ping.msg.ts
+import { defineMessage } from '@hile/message-loader'
 
-try {
-  // 5 秒超时
-  const result = await modem.request(data, 5000).response();
-} catch (e) {
-  if (e instanceof AbortException) {
-    console.log('请求超时或被中止');
-  } else if (e instanceof Exception) {
-    console.log(`远端错误 [${e.status}]: ${e.message}`);
+export default defineMessage(async ({ data, params }) => {
+  return {
+    type: 'pong',
+    data,
+    params,
+    timestamp: Date.now(),
   }
-}
-```
-
-## API
-
-### `MessageModem`（抽象类）
-
-| 方法 | 可见性 | 说明 |
-|------|--------|------|
-| `post(data)` | `protected abstract` | 子类实现：如何将消息发送到远端 |
-| `exec(data)` | `protected abstract` | 子类实现：如何处理收到的请求，返回 Promise |
-| `_send(data, opts?)` | `protected` | 发送双向请求（`twoway: true`），返回 `{ abort, response }` |
-| `_push(data, opts?)` | `protected` | 发送单向推送（`twoway: false`），无返回值，接收方不回复 RESPONSE |
-| `_stream(data, opts?)` | `protected` | 发送流式请求，返回 `Readable` stream。对端 `exec()` 须返回 async generator |
-| `receive(msg)` | `public` | 接收消息入口，根据 mode 分发处理 |
-
-### `_send` 返回值
-
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `abort` | `() => void` | 中止本次请求 |
-| `response` | `<U>() => Promise<U>` | 等待远端响应 |
-
-### 消息类型
-
-| 枚举值 | 说明 |
-|--------|------|
-| `MESSAGE_MODEM_TYPE.REQUEST` | 请求消息 |
-| `MESSAGE_MODEM_TYPE.RESPONSE` | 响应消息 |
-| `MESSAGE_MODEM_TYPE.ABORT` | 中止消息 |
-
-### 异常类
-
-| 类 | status | 默认 message | 说明 |
-|------|--------|------|------|
-| `Exception` | 自定义 | 自定义 | 基础异常，携带 status |
-| `TimeoutException` | `ETIMEDOUT` | `Timeout` | 超时异常 |
-| `AbortException` | `ECONNABORTED` | `Abort` | 中止异常 |
-
-### 消息格式
-
-```typescript
-// 传输格式
-interface MessageTransferFormat<T = any> {
-  id: number;
-  mode: MESSAGE_MODEM_TYPE;
-  twoway: boolean;
-  stream?: boolean;      // true → 流式模式
-  data?: T;
-}
-
-// 响应数据格式
-interface MessageReturnFormat<T = any> {
-  status: string | number;
-  data: T;
-  message: string;
-}
-
-// 流式分块格式（stream=true 时 RESPONSE 携带）
-interface MessageStreamChunk<T = any> {
-  status: string | number;
-  seq: number;           // 块序号，从 0 递增
-  payload: T;            // 块数据
-  final: boolean;        // true → 最后一块
-}
+})
 ```
 
-## 消息流转
-
-### 双向模式（`_send`）
-
-```
-发送方                        接收方
-  │                             │
-  │  _send(data)                │
-  │──── REQUEST (twoway) ──────►│
-  │                             │ exec(data)
-  │                             │
-  │◄──── RESPONSE ──────────────│
-  │  resolve(data)              │
-  │                             │
-  │  abort()                    │
-  │──── ABORT ─────────────────►│
-  │                             │ 取消 exec
+Microservice boot file:
+
+```ts
+// src/services/app.boot.ts
+import { defineService } from '@hile/core'
+import { Application } from '@hile/micro'
+
+export default defineService('micro.app', async (shutdown) => {
+  const app = new Application({
+    namespace: process.env.MICRO_NAMESPACE ?? 'example.service',
+    registry: {
+      host: process.env.REGISTRY_HOST ?? '127.0.0.1',
+      port: Number(process.env.REGISTRY_PORT ?? 9876),
+    },
+    advertiseHost: process.env.HILE_ADVERTISE_HOST ?? '127.0.0.1',
+  })
+
+  await app.load(new URL('../messages', import.meta.url).pathname)
+  const stop = await app.listen(Number(process.env.MICRO_PORT ?? 0))
+  shutdown(stop)
+  return app
+})
 ```
 
-### 单向模式（`_push`）
+Caller:
 
-```
-发送方                        接收方
-  │                             │
-  │  _push(data)                │
-  │──── REQUEST (!twoway) ─────►│
-  │                             │ exec(data)
-  │                             │ （不回复 RESPONSE）
+```ts
+const result = await app.call('example.service', '/ping', { hello: 'world' })
 ```
 
-### 流式模式（`_stream`）
-
-```
-发送方                        接收方
-  │                             │
-  │  _stream(data)              │
-  │──── REQUEST (stream) ──────►│
-  │                             │ exec(data) → async generator
-  │                             │
-  │◄─── RESPONSE (seq:0) ───────│ for await (chunk of gen)
-  │◄─── RESPONSE (seq:1) ───────│
-  │◄─── RESPONSE (seq:2) ───────│
-  │  ...                        │
-  │◄─── RESPONSE (final) ───────│ 迭代结束
-  │                             │
-  │  abort()                    │
-  │──── ABORT ─────────────────►│ 取消迭代
-```
+## Boundaries
 
-对端 `exec()` 返回 `AsyncIterable` 时，`MessageModem` 自动检测并进入分块传输模式。发送方通过 `for await` 消费 `Readable` stream。
+- 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.
 
-**何时用**：大数据集、实时事件流、LLM token 输出、进度上报等需要持续推送的场景。
-**何时不用**：单次请求/响应 —— 用 `_send()` 即可，无需 `_stream()`。
+- Appending a secondary response getter to `client.request('/x', data)`
+- Returning a plain object from a handler called through `stream()`.
+- Using pub/sub as a durable queue.
+- Forgetting to register `shutdown(await app.listen(...))`.
 
-## 适用场景
+## Verify
 
-- **iframe 通信** — 父子页面 postMessage
-- **WebSocket** — 客户端与服务端双向通信
-- **Web Worker** — 主线程与 Worker 通信
-- **Electron IPC** — 主进程与渲染进程通信
-- **Node.js child_process** — 父子进程通信
+- Message files default-export `defineMessage(...)`.
+- RPC callers use `await app.call(...)`.
+- Streaming handlers are async generators.
+- Registry is started before application nodes need discovery.
+- Micro apps use stable namespaces and advertise reachable hosts.
 
-## License
+## More Context
 
-MIT
+- `AI.md` in this package: full package-local AI guide.
+- Root `llms-full.txt`: full monorepo AI context.
+- Root `references/`: source files copied from `docs/ai`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/message-modem",
-  "version": "2.0.3",
+  "version": "3.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -11,7 +11,7 @@
   "files": [
     "dist",
     "README.md",
-    "SKILL.md"
+    "AI.md"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -21,5 +21,5 @@
     "fix-esm-import-path": "^1.10.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "a7615000fcb87e6bc0e573af760c814ec935bab2"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }