@hile/message-ipc 2.1.1 → 3.0.0

package/AI.md

@@ -0,0 +1,295 @@
+# AI Guide For @hile/message-ipc
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Use MessageModem over child_process IPC.
+
+
+
+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-ipc` for: Use MessageModem over child_process IPC.
+
+
+
+# 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,129 +1,90 @@
 # @hile/message-ipc
 
-基于 `@hile/message-modem` 的 Node.js IPC 通信抽象实现。让父子进程间的请求/响应通信像调用函数一样简单。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 安装
+Use MessageModem over child_process IPC.
 
-```bash
-pnpm add @hile/message-ipc
-```
-
-## 核心特性
-
-- **双端支持** — 父进程端传入 `ChildProcess`，子进程端零配置
-- **继承模式** — 继承 `MessageIpc` 并实现 `exec` 方法定义请求处理逻辑
-- **请求/响应** — 继承 `MessageModem` 的全部能力
-- **超时控制** — 默认 30 秒，可按请求自定义
-- **主动中止** — `abort()` 取消等待并通知对端
-- **错误传播** — `Exception` 带 status 透传，普通 Error 映射为 500
-- **资源清理** — `dispose()` 移除监听，避免内存泄漏
-
-## 快速开始
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-### 第一步：定义子类
+## When To Use
 
-`MessageIpc` 是抽象类，需继承并实现 `exec` 方法：
+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.
 
-```typescript
-import { MessageIpc } from '@hile/message-ipc';
-import { Exception } from '@hile/message-modem';
+## Install
 
-class WorkerIpc extends MessageIpc {
-  protected async exec(data: any): Promise<any> {
-    switch (data?.action) {
-      case 'compute':
-        return data.value * 2;
-      case 'restricted':
-        throw new Exception(403, 'not allowed');
-      default:
-        return data; // echo
-    }
-  }
-
-  public request<T = any>(data: T, timeout?: number) {
-    return this._send(data, timeout);
-  }
-}
+```bash
+pnpm add @hile/message-ipc
 ```
 
-### 第二步：父进程
+## Copy-Paste Example
 
-```typescript
-import { fork } from 'node:child_process';
+Message handler file:
 
-class ParentIpc extends MessageIpc {
-  protected async exec(data: any): Promise<any> {
-    return { reply: 'from parent', query: data };
-  }
+```ts
+// src/messages/ping.msg.ts
+import { defineMessage } from '@hile/message-loader'
 
-  public request<T = any>(data: T, timeout?: number) {
-    return this._send(data, timeout);
+export default defineMessage(async ({ data, params }) => {
+  return {
+    type: 'pong',
+    data,
+    params,
+    timestamp: Date.now(),
   }
-}
-
-const child = fork('./worker.js');
-const ipc = new ParentIpc(child);
-
-const result = await ipc.request({ action: 'compute', value: 42 }).response();
-console.log(result); // 84
-
-ipc.dispose();
-child.kill();
+})
 ```
 
-### 第三步：子进程（worker.js）
-
-```typescript
-const ipc = new WorkerIpc(); // 无参数 → 自动使用 process
+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
+})
 ```
 
-## API
-
-### `MessageIpc`（抽象类）
-
-| 方法 | 签名 | 说明 |
-|------|------|------|
-| `constructor` | `new SubClass(channel?: ChildProcess)` | 父进程传 `fork()` 返回值；子进程不传参数 |
-| `exec` | `protected abstract exec(data: any): Promise<any>` | 子类实现：处理对端请求的业务逻辑 |
-| `_send` | `protected _send<T>(data: T, timeout?: number)` | 发送双向请求（`twoway: true`），返回 `{ abort, response }`。子类自行暴露为 public |
-| `_push` | `protected _push<T>(data: T, timeout?: number)` | 发送单向推送（`twoway: false`），接收方不回复 RESPONSE |
-| `dispose` | `dispose(): void` | 移除消息监听，释放资源 |
+Caller:
 
-### `_send` 返回值
-
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `abort` | `() => void` | 中止请求 |
-| `response` | `<U>() => Promise<U>` | 等待对端响应 |
-
-## 超时与中止
+```ts
+const result = await app.call('example.service', '/ping', { hello: 'world' })
+```
 
-```typescript
-import { AbortException, Exception } from '@hile/message-modem';
+## Boundaries
 
-// 5 秒超时
-const result = await ipc.request(data, 5000).response();
+- 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.
 
-// 主动中止
-const req = ipc.request(data);
-setTimeout(() => req.abort(), 3000);
-try {
-  await req.response();
-} catch (e) {
-  if (e instanceof AbortException) {
-    console.log('请求被中止或超时');
-  } else if (e instanceof Exception) {
-    console.log(`远端错误 [${e.status}]: ${e.message}`);
-  }
-}
-```
+- 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
 
-- `MessageIpc` 是 **抽象类**，不能直接实例化，必须继承并实现 `exec`
-- 子进程必须通过 `fork()` 启动，`spawn()` 没有 IPC 通道
-- 使用完毕后务必调用 `dispose()` + `child.kill()` 清理资源
+- 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-ipc",
-  "version": "2.1.1",
+  "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": {
@@ -22,7 +22,7 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/message-modem": "^2.1.1"
+    "@hile/message-modem": "^3.0.0"
   },
-  "gitHead": "7903ae989bd001d1ed1437cb90c9e828a1909061"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }