@hile/micro-dynamic-configs 3.0.0 → 3.0.2

package/AI.md

@@ -0,0 +1,280 @@
+# AI Guide For @hile/micro-dynamic-configs
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Persist runtime config in Redis and publish typed changes through @hile/micro.
+
+
+
+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
+
+
+
+| User asks for | Use | Also read |
+|---|---|---|
+| Push runtime config without restarts | `@hile/micro-dynamic-configs` | `packages/messaging-micro.md`, `recipes/runtime-config.md` |
+
+
+
+# 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
+
+
+
+# Runtime Dynamic Config
+
+## Complete Example
+
+```ts
+import { z } from 'zod'
+import { MicroDynamicConfigsServer } from '@hile/micro-dynamic-configs'
+
+const schema = z.object({
+  featureCheckout: z.boolean().default(false),
+  maxRetries: z.number().int().min(1).max(10).default(3),
+})
+
+const configs = new MicroDynamicConfigsServer({
+  app,
+  redis,
+  schema,
+  redis_key: 'configs:checkout',
+})
+
+const cleanup = await configs.initialize()
+shutdown(cleanup)
+
+configs.on('change:featureCheckout', (next, previous) => {
+  logger.info({ previous, next }, 'featureCheckout changed')
+})
+
+await configs.save({ featureCheckout: true })
+```
+
+## File Layout
+
+```text
+src/services/configs.boot.ts
+src/services/app.boot.ts
+```
+
+## User Intent
+
+Use this recipe when config changes should persist to Redis and be pushed through the micro registry without restarting services.
+
+## Packages To Use
+
+- `@hile/micro-dynamic-configs`
+- `@hile/micro`
+- `@hile/ioredis`
+- `zod`
+
+## Implementation Steps
+
+1. Define a Zod object schema with defaults.
+2. Create `MicroDynamicConfigsServer`.
+3. Call `initialize()` after `app` and `redis` are ready.
+4. Register cleanup with `shutdown()`.
+5. Use `.save(partial)` for changes.
+
+## Failure And Cleanup Behavior
+
+- `save()` validates fields before mutating memory.
+- Redis is written before memory and event emission update.
+- `initialize()` publishes every config field as a topic.
+- Cleanup unpublishes topics and removes listeners.
+
+## Verification Checklist
+
+- Schema defaults parse `{}`.
+- `redis_key` is app-specific.
+- Change handlers use `change:key`.
+- Cleanup from `initialize()` is registered.
+
+
+
+# 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,85 +1,90 @@
 # @hile/micro-dynamic-configs
 
-Dynamic configuration server for @hile/micro. Stores config in Redis, validates with Zod, and pushes changes to subscribers via micro's built-in pub/sub.
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## Usage
+Persist runtime config in Redis and publish typed changes through @hile/micro.
 
-```ts
-import { Application } from '@hile/micro';
-import { MicroDynamicConfigsServer } from '@hile/micro-dynamic-configs';
-import Redis from 'ioredis';
-import { z } from 'zod';
-
-const schema = z.object({
-  name: z.string().default(''),
-  port: z.number().default(8080),
-  debug: z.boolean().default(false),
-});
-
-const app = new Application({
-  namespace: 'config-svc',
-  registry: { host: '127.0.0.1', port: 6379 },
-});
-
-const redis = new Redis({ host: '127.0.0.1', port: 6379 });
-
-const configs = new MicroDynamicConfigsServer({
-  app,
-  redis,
-  schema,
-  redis_key: 'my-app:config',
-});
-
-await configs.initialize();
-
-// Read current value
-console.log(configs.value); // { name: '', port: 8080, debug: false }
-
-// Update and persist — subscribers receive push
-await configs.save({ name: 'production', port: 9090 });
-```
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-## Topic Convention
+## When To Use
 
-Each schema field publishes to a separate topic:
+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.
 
-```
-{namespace}:{field}
+## Install
+
+```bash
+pnpm add @hile/micro-dynamic-configs
 ```
 
-For example, with namespace `config-svc` and schema fields `name`, `port`, `debug`:
+## Copy-Paste Example
 
-- `config-svc:name`
-- `config-svc:port`
-- `config-svc:debug`
+Message handler file:
 
-## Subscribing
+```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(),
+  }
+})
+```
 
-Use `app.subscribe()` directly on any micro Application:
+Microservice boot file:
 
 ```ts
-const values: Record<string, any> = {};
-const unsub = await app.subscribe('config-svc:name', (v) => values.name = v);
+// 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
+})
 ```
 
-## Local Events
-
-The server emits `change:{field}` events locally:
+Caller:
 
 ```ts
-configs.on('change:name', (newValue, oldValue) => {
-  console.log(`name changed from ${oldValue} to ${newValue}`);
-});
+const result = await app.call('example.service', '/ping', { hello: 'world' })
 ```
 
-## Persistence
+## Boundaries
 
-Config is persisted to Redis on every `save()`. On `initialize()`, the server loads the last saved state from Redis. Schema defaults apply when no value exists.
+- 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.
 
-## Teardown
+- 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(...))`.
 
-```ts
-const teardown = await configs.initialize();
-// Later:
-await teardown(); // unpublishes all topics and cleans up listeners
-```
+## Verify
+
+- 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.
+
+## More Context
+
+- `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/micro-dynamic-configs",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -11,7 +11,7 @@
   "files": [
     "dist",
     "README.md",
-    "SKILL.md"
+    "AI.md"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -22,10 +22,10 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/ioredis": "^2.1.1",
-    "@hile/micro": "^3.0.0",
+    "@hile/ioredis": "^3.0.0",
+    "@hile/micro": "^3.0.2",
     "ioredis": "^5.11.0",
     "zod": "^4.4.3"
   },
-  "gitHead": "14b55afba0e9af80a782eaa84f6f48c1e66861a1"
+  "gitHead": "5d6a724ac4e99d493d42efe337e3ad17db40c3f7"
 }