@hile/message-ws 2.1.1 → 3.0.0

package/AI.md

@@ -0,0 +1,295 @@
+# AI Guide For @hile/message-ws
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Use MessageModem over WebSocket connections.
+
+
+
+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-ws` for: Use MessageModem over WebSocket connections.
+
+
+
+# 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,128 +1,90 @@
 # @hile/message-ws
 
-基于 `@hile/message-modem` 和 `ws` 模块的 WebSocket 通信抽象实现。让客户端与服务端之间的请求/响应通信像调用函数一样简单。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 安装
+Use MessageModem over WebSocket connections.
 
-```bash
-pnpm add @hile/message-ws
-```
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-## 核心特性
-
-- **双端支持** — 客户端和服务端各自包装 `WebSocket` 实例即可
-- **继承模式** — 继承 `MessageWs` 并实现 `exec` 方法
-- **JSON 传输** — 消息自动 JSON 序列化/反序列化
-- **请求/响应** — 继承 `MessageModem` 全部能力
-- **超时控制** — 默认 30 秒，可按请求自定义
-- **主动中止** — `abort()` 取消等待并通知对端
-- **错误传播** — `Exception` 带 status 透传，普通 Error 映射为 500
-- **连接状态检查** — 发送前检查 `readyState`
-- **资源清理** — `dispose()` 移除监听
-
-## 快速开始
-
-### 第一步：定义子类
-
-```typescript
-import { MessageWs } from '@hile/message-ws';
-import { Exception } from '@hile/message-modem';
-
-class AppWs extends MessageWs {
-  protected async exec(data: any): Promise<any> {
-    switch (data?.action) {
-      case 'getUser':
-        return { id: data.id, name: 'Alice' };
-      case 'restricted':
-        throw new Exception(403, 'not allowed');
-      default:
-        return data;
-    }
-  }
+## When To Use
 
-  public request<T = any>(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.
 
-```typescript
-import { WebSocketServer } from 'ws';
+## Install
 
-const wss = new WebSocketServer({ port: 8080 });
-wss.on('connection', (ws) => {
-  const modem = new AppWs(ws);
-  // 自动处理客户端请求
-});
+```bash
+pnpm add @hile/message-ws
 ```
 
-### 第三步：客户端
+## Copy-Paste Example
 
-```typescript
-import WebSocket from 'ws';
+Message handler file:
 
-const ws = new WebSocket('ws://localhost:8080');
-ws.on('open', () => {
-  const modem = new AppWs(ws);
+```ts
+// src/messages/ping.msg.ts
+import { defineMessage } from '@hile/message-loader'
 
-  const user = await modem.request({ action: 'getUser', id: 1 }).response();
-  console.log(user); // { id: 1, name: 'Alice' }
-
-  modem.dispose();
-  ws.close();
-});
+export default defineMessage(async ({ data, params }) => {
+  return {
+    type: 'pong',
+    data,
+    params,
+    timestamp: Date.now(),
+  }
+})
 ```
 
-## API
-
-### `MessageWs`（抽象类）
-
-| 方法 | 签名 | 说明 |
-|------|------|------|
-| `constructor` | `new SubClass(ws: WebSocket)` | 传入已连接的 WebSocket 实例 |
-| `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` | 移除消息监听，释放资源 |
-
-### `_send` 返回值
+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
+})
+```
 
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `abort` | `() => void` | 中止请求 |
-| `response` | `<U>() => Promise<U>` | 等待对端响应 |
+Caller:
 
-## 超时与中止
+```ts
+const result = await app.call('example.service', '/ping', { hello: 'world' })
+```
 
-```typescript
-import { AbortException, Exception } from '@hile/message-modem';
+## Boundaries
 
-// 5 秒超时
-const result = await modem.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 = modem.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
 
-- `MessageWs` 是 **抽象类**，不能直接实例化
-- 必须在 WebSocket 连接建立（`open` 事件）后再创建实例或发送请求
-- 消息通过 JSON 序列化传输，不支持 Buffer/Map/Set 等非 JSON 类型
-- 使用完毕后调用 `dispose()` + `ws.close()`
+- 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/dist/index.d.ts

@@ -15,9 +15,10 @@ import type WebSocket from 'ws';
  * }
  *
  * const ws = new WebSocket('ws://localhost:8080');
- * ws.on('open', () => {
+ * ws.on('open', async () => {
  *   const modem = new MyWs(ws);
- *   modem.request('hello').response().then(console.log);
+ *   const result = await modem.request('hello');
+ *   console.log(result);
  * });
  */
 export declare abstract class MessageWs extends MessageModem {

package/dist/index.js

@@ -14,9 +14,10 @@ import { MessageModem } from '@hile/message-modem';
  * }
  *
  * const ws = new WebSocket('ws://localhost:8080');
- * ws.on('open', () => {
+ * ws.on('open', async () => {
  *   const modem = new MyWs(ws);
- *   modem.request('hello').response().then(console.log);
+ *   const result = await modem.request('hello');
+ *   console.log(result);
  * });
  */
 export class MessageWs extends MessageModem {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/message-ws",
-  "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": {
@@ -23,8 +23,8 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/message-modem": "^2.1.1",
+    "@hile/message-modem": "^3.0.0",
     "ws": "^8.21.0"
   },
-  "gitHead": "7903ae989bd001d1ed1437cb90c9e828a1909061"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }