@hile/micro-dynamic-configs 1.0.3 → 2.0.0

package/README.md

@@ -0,0 +1,85 @@
+# @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.
+
+## Usage
+
+```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 });
+```
+
+## Topic Convention
+
+Each schema field publishes to a separate topic:
+
+```
+{namespace}:{field}
+```
+
+For example, with namespace `config-svc` and schema fields `name`, `port`, `debug`:
+
+- `config-svc:name`
+- `config-svc:port`
+- `config-svc:debug`
+
+## Subscribing
+
+Use `app.subscribe()` directly on any micro Application:
+
+```ts
+const values: Record<string, any> = {};
+const unsub = await app.subscribe('config-svc:name', (v) => values.name = v);
+```
+
+## Local Events
+
+The server emits `change:{field}` events locally:
+
+```ts
+configs.on('change:name', (newValue, oldValue) => {
+  console.log(`name changed from ${oldValue} to ${newValue}`);
+});
+```
+
+## Persistence
+
+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.
+
+## Teardown
+
+```ts
+const teardown = await configs.initialize();
+// Later:
+await teardown(); // unpublishes all topics and cleans up listeners
+```

package/SKILL.md

@@ -11,24 +11,24 @@ description: Code generation and contribution rules for @hile/micro-dynamic-conf
 
 ## 1. 架构总览
 
-三个角色，通过 `@hile/micro` 的 WebSocket 通信：
+通过 `@hile/micro` 的 pub/sub 机制推送配置变更，每个 schema 字段一个独立 topic。
 
 ```
-APP_3 (Publisher)          APP_1 (Config Server)         APP_2 (Subscriber)
-    │                            │                              │
-    │    save({ key: val })      │                              │
-    ├──────────────────────────► │                              │
-    │                            │   push /-/dynamic-configs/   │
-    │                            │   change { key, newValue }   │
-    │                            ├─────────────────────────────►│
-    │                            │                              │
-    │                            │◄── subscribe(fields) ───────┤
-    │                            │───── initial values ────────►│
+Publisher                    Config Server                       Subscriber
+    │                             │                                  │
+    │   save({ key: val })        │                                  │
+    ├──────────────────────────►  │                                  │
+    │                             │  publisher.update(newValue)      │
+    │                             │  ──────────────────────────────► │
+    │                             │  (通过 Registry 广播 topic)       │
+    │                             │                                  │
+    │                             │  app.subscribe('ns:key', cb)     │
+    │                             │  ◄────────────────────────────── │
 ```
 
-- **Config Server** (`MicroDynamicConfigsServer`) — 持有配置数据，管理订阅者列表，推送变更
-- **Subscriber** (`MicroDynamicConfigClients`) — 订阅某个 namespace 的配置字段，接收实时推送
-- **Publisher** — 调用 `server.save()` 修改配置，数据流向是：validate → Redis 持久化 → 内存更新 → 推送通知
+- **Config Server** (`MicroDynamicConfigsServer`) — 持有配置数据，校验、持久化，通过 `app.publish` 注册 publisher
+- **Subscriber** — 直接用 `app.subscribe(topic, callback)` 接收推送，无需客户端层
+- **Publisher** — 调用 `server.save()` 修改配置，数据流：validate → Redis 持久化 → 内存更新 → `publisher.update()` → `change:key` 事件
 
 ---
 
@@ -49,8 +49,8 @@ constructor(options: {
   redis_key: string // Redis 存储键名
 })
 
-// 从 Redis 加载持久化数据，返回 teardown 函数
-initialize(): Promise<() => void>
+// 从 Redis 加载持久化数据，为每个 schema 字段注册 publisher，返回 teardown 函数
+initialize(): Promise<() => Promise<void>>
 
 // 持久化并推送变更
 save(value: Partial<z.infer<Z>>): Promise<number>
@@ -59,56 +59,35 @@ save(value: Partial<z.infer<Z>>): Promise<number>
 get value(): z.infer<Z>
 ```
 
-### MicroDynamicConfigClients
+### 事件
 
-```typescript
-class MicroDynamicConfigClients
-
-constructor(app: Application)
-
-subscribe<T extends Record<string, any>>(
-  namespace: string,
-  fields: (keyof T)[]
-): Promise<T>
-
-close(): Promise<void>
-```
-
-### DynamicConfigClient (通常不直接使用)
-
-```typescript
-class DynamicConfigClient<T extends Record<string, any>>
-
-getValue(): Promise<T>
-close(): Promise<void>
-setValue<K extends keyof T>(k: K, v: T[K]): this  // 由 push handler 调用
-```
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| `change:{field}` | `(newValue, oldValue)` | 字段变更时触发，每个字段独立事件名 |
 
 ---
 
-## 3. 通信协议
+## 3. Topic 约定
 
-### 路由端点
+每个 schema 字段一个 topic，格式为：
 
-| 方向 | 路径 | 数据 | 返回 |
-|------|------|------|------|
-| Subscriber → Server | `/-/dynamic-configs/subscribe` | `string[]` (字段名) | `Record<string, any>` (字段值) |
-| Subscriber → Server | `/-/dynamic-configs/unsubscribe` | `string[]` (字段名) | `number` (timestamp) |
-| Server → Subscriber | `/-/dynamic-configs/change` (push) | `{ key, newValue, oldValue, namespace }` | — |
+```
+{namespace}:{field}
+```
 
-### 订阅流程
+例如 namespace `config-svc`、字段 `name`、`port`、`debug`：
 
-1. 客户端通过 Registry 发现目标 namespace 的 `host:port`
-2. 建立 WebSocket 连接
-3. 发送 subscribe 请求，服务端注册并返回初始值
-4. 服务端数据变更时，遍历 `stacks` 中该字段的订阅者，逐个 push
-5. 客户端收到 push 后更新本地缓存
+- `config-svc:name`
+- `config-svc:port`
+- `config-svc:debug`
 
-### 退订与断连
+### 订阅
 
-- 显式退订：调用 `close()` → 发送 unsubscribe 请求
-- 被动断连：WebSocket close → 服务端 `onClientDisconnect` 清理所有 `stacks`
-- 客户端断连后 `_status = 0`，下次 `getValue()` 重新走完整订阅流程
+```typescript
+const values: Record<string, any> = {};
+const unsub = await app.subscribe('config-svc:name', (v) => values.name = v);
+// unsub() 取消订阅
+```
 
 ---
 
@@ -124,10 +103,10 @@ for (const key of keys) {
   const parsed = schema.parse(value[key]);
   if (!deepEqual(old, parsed)) entries.push({ key, parsed });
 }
-// Pass 2: persist → memory → emit
+// Pass 2: persist → memory → publish + emit
 await redis.set(key, JSON.stringify(next));
 update memory;
-emit events;
+emit 'change:{key}' events;
 
 // ✗ 禁止：validate 和 mutate 混在一轮
 for (const key of keys) {
@@ -135,87 +114,47 @@ for (const key of keys) {
 }
 ```
 
-### 4.2 客户端状态机
+### 4.2 initialize() 中注册 publisher
 
-```
-_status: 0 (uninit) ──getValue()──→ 1 (loading)
-    ↑                                    │
-    │                           subscribe()
-    │                              │
-    │                         ┌────┴────┐
-    │                    fail │         │ success
-    │                    ┌────┘         └────┐
-    │                    ↓                   ↓
-    │                    0 (retry)           2 (ready)
-    │                                        │
-    │                            disconnect  │
-    │                              ────────→ 0
-    │                              close()
-    └────────────────────────────────── closed
-```
+```typescript
+// ✓ 正确：initialize 时调用 app.publish 注册所有字段
+const publisher = await this.app.publish(`${namespace}:${key}`, initialValue);
+this.publishers.set(key, publisher);
 
-- `close()` 设 `_closed = true`，pending subscribe 完成时检测标记并 dispose 连接
-- `close()` 后 `getValue()` 直接 reject
+// save 时通过 publisher.update 推送
+await this.publishers.get(key)!.update(newValue);
 
-### 4.3 生命周期
+// teardown 时 unpublish
+await publisher.unpublish();
 
-```typescript
-// 服务端初始化
-const teardown = await server.initialize();
-// ... 运行 ...
-teardown(); // 清理所有监听器和订阅
-
-// 客户端创建
-const configs = new MicroDynamicConfigClients(app);
-const value = await configs.subscribe("ns", ["key1"]);
-// ... 使用 ...
-await configs.close(); // 清理所有订阅连接
+// ✗ 禁止：save 中每次调用 app.publish（应复用 initialize 时注册的 publisher）
 ```
 
----
-
-## 5. 反模式（禁止）
-
-### 5.1 save() 中字段校验失败后保留脏状态
+### 4.3 teardown 必须清理所有资源
 
 ```typescript
-// ✗
-for (const key of keys) {
-  this._value[key] = parsed;  // 后续失败 → 脏数据
-}
-await redis.set(...);
-
-// ✓ 先全部校验，再统一写入
+// ✓ 正确：teardown 需 unpublish + clear + removeAllListeners
+return async () => {
+  for (const publisher of this.publishers.values()) {
+    await publisher.unpublish();
+  }
+  this.publishers.clear();
+  this.removeAllListeners();
+};
 ```
 
-### 5.2 close() 前不检查 pending subscribe
+### 4.4 deep diff 避免无效推送
 
 ```typescript
-// ✗ close() 不设标记，pending subscribe 完成导致 client 复活
-async close() {
-  await this.unsubscribe();
-  this._client = undefined;
-}
-
-// ✓ close() 先设 _closed 标记
-async close() {
-  this._closed = true;
-  await this.unsubscribe();
-  this._client = undefined;
+// ✓ 正确：值未变化时跳过 publish
+if (isDeepStrictEqual(oldValue, parsed)) {
+  continue;  // 不写入 entries，不触发 publish 和事件
 }
 ```
 
-### 5.3 多个 MicroDynamicConfigClients 实例共享同一 app
-
-rou3 `dispatch()` 只执行第一个匹配的 handler，第二个实例的 `/-/dynamic-configs/change` 不会触发。一个 app 只应创建一个 `MicroDynamicConfigClients` 实例。
-
-### 5.4 在 push handler 中做耗时的同步操作
-
-push handler 在 message 调度线程中执行，不应包含耗时操作。`setValue()` 仅是内存写入，保持轻量。
-
 ---
 
-## 6. 边界条件清单
+## 5. 边界条件清单
 
 - [ ] `save()` 传入空对象 `{}` — 返回 0，无操作
 - [ ] `save()` 传入 schema 中不存在的字段 — 跳过，不报错
@@ -223,10 +162,13 @@ push handler 在 message 调度线程中执行，不应包含耗时操作。`set
 - [ ] `save()` 中所有字段值与当前一致 — 返回 0，不写 Redis 不推送
 - [ ] `save()` Redis 写入失败 — throw，`_value` 不变
 - [ ] `initialize()` 时 Redis 无数据 — 使用 schema 默认值
-- [ ] `close()` 在 subscribe 完成前调用 — `_closed` 标记防止复活，新连接被 dispose
-- [ ] `close()` 后调用 `getValue()` — 直接 reject
-- [ ] 订阅不存在的字段 — 服务器静默跳过，不返回该字段
-- [ ] 同一 namespace 重复 subscribe — 复用已有 client，`fields` 不会合并
-- [ ] 断连后重新 subscribe — `_status = 0` → 全量重新拉取
-- [ ] 服务端推送时订阅者已断连 — `has(client)` 检查跳过，等待 `onClientDisconnect` 清理
-- [ ] 多个字段同时变更 — 一轮 `save()` 中多次 `change:key` 事件，订阅者逐个收到
+- [ ] 多个字段同时变更 — 一轮 `save()` 中逐个 `publisher.update()` + `change:key` 事件
+- [ ] Deep diff 检测嵌套对象变化 — 嵌套字段内容不变时跳过 publish
+
+---
+
+## 6. 依赖
+
+- `@hile/micro` — 提供 `Application`、`app.publish`/`app.subscribe`
+- `ioredis` — Redis 持久化
+- `zod` — Schema 定义与校验

package/dist/index.d.ts

@@ -1,2 +1 @@
 export * from './server.js';
-export * from './client.js';

package/dist/index.js

@@ -1,2 +1 @@
 export * from './server.js';
-export * from './client.js';

package/dist/server.d.ts

@@ -4,21 +4,18 @@ import { Redis } from "ioredis";
 import { EventEmitter } from 'node:events';
 export declare class MicroDynamicConfigsServer<T extends Application, Z extends ZodObject<ZodRawShape>> extends EventEmitter {
     private _value;
-    private readonly stacks;
     private readonly app;
     private readonly schema;
     private readonly redis;
     private readonly redis_key;
+    private readonly publishers;
     constructor(options: {
         app: T;
         redis: Redis;
         schema: Z;
         redis_key: string;
     });
-    private onClientDisconnect;
     get value(): z.core.output<Z>;
     initialize(): Promise<() => Promise<void>>;
-    private registerSubscribe;
-    private registerUnsubscribe;
     save(value: Partial<z.infer<Z>>): Promise<number>;
 }

package/dist/server.js

@@ -2,11 +2,11 @@ import { isDeepStrictEqual } from "node:util";
 import { EventEmitter } from 'node:events';
 export class MicroDynamicConfigsServer extends EventEmitter {
     _value;
-    stacks = new Map();
     app;
     schema;
     redis;
     redis_key;
+    publishers = new Map();
     constructor(options) {
         super();
         this.app = options.app;
@@ -14,32 +14,7 @@ export class MicroDynamicConfigsServer extends EventEmitter {
         this.redis = options.redis;
         this.redis_key = options.redis_key;
         this._value = this.schema.parse({});
-        for (const key of Object.keys(this.schema.shape)) {
-            this.stacks.set(key, new Set());
-            this.on('change:' + key, (newValue, oldValue) => {
-                if (this.stacks.has(key)) {
-                    const pool = this.stacks.get(key);
-                    for (const client of pool) {
-                        if (this.app.clients.has(client)) {
-                            this.app.clients.get(client).push('/-/dynamic-configs/change', {
-                                key, newValue, oldValue,
-                                namespace: this.app.namespace,
-                            });
-                        }
-                    }
-                }
-            });
-        }
-        this.registerSubscribe();
-        this.registerUnsubscribe();
-        this.app.events.on('disconnect', this.onClientDisconnect);
     }
-    onClientDisconnect = (client) => {
-        const key = client.host + ':' + client.port;
-        for (const [, pool] of this.stacks) {
-            pool.delete(key);
-        }
-    };
     get value() {
         return this._value;
     }
@@ -50,38 +25,19 @@ export class MicroDynamicConfigsServer extends EventEmitter {
                 this._value = this.schema.parse(JSON.parse(value));
             }
         }
+        const keys = Object.keys(this.schema.shape);
+        for (const key of keys) {
+            const publisher = await this.app.publish(`${this.app.namespace}:${key}`, this._value[key]);
+            this.publishers.set(key, publisher);
+        }
         return async () => {
+            for (const publisher of this.publishers.values()) {
+                await publisher.unpublish();
+            }
+            this.publishers.clear();
             this.removeAllListeners();
-            this.app.events.off('disconnect', this.onClientDisconnect);
-            this.stacks.clear();
         };
     }
-    registerSubscribe() {
-        this.app.register('/-/dynamic-configs/subscribe', async ({ data, client }) => {
-            const out = {};
-            for (const key of data) {
-                if (this.stacks.has(key)) {
-                    this.stacks.get(key).add(client.host + ':' + client.port);
-                    out[key] = this._value[key];
-                }
-            }
-            return out;
-        });
-    }
-    registerUnsubscribe() {
-        this.app.register('/-/dynamic-configs/unsubscribe', async ({ data, client }) => {
-            for (const key of data) {
-                if (this.stacks.has(key)) {
-                    const pool = this.stacks.get(key);
-                    const _key = client.host + ':' + client.port;
-                    if (pool.has(_key)) {
-                        pool.delete(_key);
-                    }
-                }
-            }
-            return Date.now();
-        });
-    }
     async save(value) {
         const keys = Object.keys(value);
         if (!keys.length)
@@ -112,6 +68,9 @@ export class MicroDynamicConfigsServer extends EventEmitter {
             this._value[key] = parsed;
         }
         for (const { key, parsed: newValue, oldValue } of entries) {
+            if (this.publishers.has(key)) {
+                await this.publishers.get(key).update(newValue);
+            }
             this.emit('change:' + key, newValue, oldValue);
         }
         return entries.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/micro-dynamic-configs",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -23,9 +23,9 @@
   },
   "dependencies": {
     "@hile/ioredis": "^1.1.2",
-    "@hile/micro": "^1.0.10",
+    "@hile/micro": "^2.0.0",
     "ioredis": "^5.10.0",
     "zod": "^4.4.3"
   },
-  "gitHead": "be31521d206109a1ed6e915ec231a849870b538c"
+  "gitHead": "d28b20bc22ee08c45cbf4596672705cb96e8e461"
 }