zen-fs-config 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,129 @@
+# zen-fs-config
+
+基于 ZenFS 的分布式配置管理库。多个应用实例通过任意 ZenFS 后端共享配置，支持应用隔离、共享空间、节点本地配置和冲突安全。
+
+**GitHub**: https://github.com/weijia/zen-fs-config
+**NPM**: `zen-fs-config`
+**设计文档**: [DESIGN.md](./DESIGN.md)
+
+## 安装
+
+```bash
+npm install zen-fs-config @zenfs/core zen-fs-cache zen-fs-sync
+```
+
+## 快速开始
+
+```typescript
+import { createConfigRepo, registerBackend } from 'zen-fs-config';
+import { InMemory } from '@zenfs/core';
+
+// 1. 注册自定义后端（可选，InMemory 已内置）
+registerBackend('InMemory', async (options) => {
+  return InMemory.create({ maxSize: options.maxSize as number ?? 100 * 1024 * 1024 });
+});
+
+// 2. 创建配置仓库
+const repo = await createConfigRepo('my-app', {
+  primaryBackendId: 'local-memory',
+  backendInfo: {
+    type: 'InMemory',
+    options: { label: 'my-app-config' },
+  },
+  cache: { storeType: 'MemoryCacheStore', ttlMs: 60_000 },
+  bootstrap: {
+    backends: [
+      { id: 'local-memory', type: 'InMemory', options: { label: 'primary' } },
+    ],
+    syncRules: [
+      { prefix: '/my-app/', direction: 'one-way', conflictStrategy: 'source-wins', replicas: ['local-memory'] },
+      { prefix: '/shared/', direction: 'bi-directional', conflictStrategy: 'merge', replicas: ['local-memory'] },
+      { prefix: '/nodes/', direction: 'none' },
+    ],
+  },
+});
+
+// 3. 读写配置（同步 API，从内存缓存读取）
+repo.setConfig('/database', { host: 'localhost', port: 5432 });
+const db = repo.getConfig<{ host: string; port: number }>('/database');
+
+// 4. 节点本地配置（异步 API，不自动同步）
+await repo.setNodeConfig('node-1', '/debug', { level: 'verbose' });
+const debug = await repo.getNodeConfig('node-1', '/debug');
+
+// 5. 发布节点配置到同步后端（用于调试）
+await repo.publishNodeConfig('node-1');
+
+// 6. 清理
+await repo.dispose();
+```
+
+## 目录结构
+
+```
+/
+├── {appId}/           # 应用私有配置（单向同步，每个应用只能读写自己的）
+├── shared/            # 跨应用共享配置（双向同步，merge 冲突策略）
+├── nodes/{nodeId}/    # 节点本地配置（不同步，除非手动 publish）
+└── .meta/
+    ├── backends.json  # 后端拓扑（自描述，任意后端可引导）
+    ├── sync-rules.json
+    └── .conflicts/    # 冲突归档（双方内容都保存，永不丢失）
+```
+
+每个配置文件有 sidecar 版本文件：`db.json` → `.db.json.version`（版本号 + SHA-256 哈希）。
+
+## 核心 API
+
+| 方法 | 说明 |
+|---|---|
+| `getConfig<T>(path)` | 同步读取应用配置（从内存缓存） |
+| `setConfig(path, data)` | 同步写入应用配置（异步持久化 + 自动同步） |
+| `getNodeConfig<T>(nodeId, path)` | 异步读取节点本地配置 |
+| `setNodeConfig(nodeId, path, data)` | 异步写入节点本地配置（不同步） |
+| `publishNodeConfig(nodeId)` | 将节点配置一次性同步到所有后端 |
+| `peekNodeConfig<T>(nodeId, path)` | 只读查看其他节点的已发布配置 |
+| `flush()` | 手动触发所有同步 |
+| `listConflicts()` | 列出所有冲突归档 |
+| `resolveConflict(id, merged)` | 用合并内容解决冲突 |
+| `fs.promises.*` | 标准 fs API，chroot 隔离到 `/{appId}/` 和 `/shared/` |
+| `dispose()` | 停止同步、释放资源 |
+
+## 后端注册
+
+```typescript
+import { registerBackend } from 'zen-fs-config';
+
+// 注册 S3 后端
+registerBackend('S3Bucket', async (options) => {
+  const { S3Bucket } = await import('@zenfs/core');
+  return S3Bucket.create(options);
+});
+
+// 注册自定义后端
+registerBackend('my-custom', async (options) => {
+  return {
+    readFile: (path) => { /* ... */ },
+    writeFile: (path, data) => { /* ... */ },
+    readdir: (path) => { /* ... */ },
+    stat: (path) => { /* ... */ },
+    exists: (path) => { /* ... */ },
+    mkdir: (path) => { /* ... */ },
+    unlink: (path) => { /* ... */ },
+    rmdir: (path) => { /* ... */ },
+    rename: (old, newPath) => { /* ... */ },
+  };
+});
+```
+
+## 依赖
+
+| 包 | 说明 |
+|---|---|
+| `@zenfs/core >=2.3.0` | ZenFS 虚拟文件系统 |
+| `zen-fs-cache >=1.0.0` | ETag/TTL 缓存层 |
+| `zen-fs-sync >=0.1.0` | 跨后端同步引擎 |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import * as node_fs from 'node:fs';
-import { ConflictStrategy, SyncResult, SyncPairStatus } from 'zen-fs-sync';
+import { ConflictStrategy, SyncResult, SyncPairStatus, SyncableFS } from 'zen-fs-sync';
 export { SyncPairStatus, SyncResult } from 'zen-fs-sync';
+import * as node_fs from 'node:fs';
 
 /** A single backend in the topology. */
 interface BackendDescriptor {
@@ -143,15 +143,15 @@ interface IConfigRepo {
     /** Write a config value (auto-synced). */
     setConfig(path: string, data: unknown): void;
     /** Read node-local config. */
-    getNodeConfig<T = unknown>(nodeId: string, path: string): T;
+    getNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     /** Write node-local config (no auto-sync). */
-    setNodeConfig(nodeId: string, path: string, data: unknown): void;
+    setNodeConfig(nodeId: string, path: string, data: unknown): Promise<void>;
     /** Publish node-local config to sync backends (one-time, for debugging). */
     publishNodeConfig(nodeId: string, options?: {
         paths?: string[];
     }): Promise<SyncResult>;
     /** Peek at another node's published config (read-only). */
-    peekNodeConfig<T = unknown>(nodeId: string, path: string): T;
+    peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     /** Manually flush all pending sync operations. */
     flush(): Promise<SyncResult[]>;
     /** Get sync status for all registered sync pairs. */
@@ -164,4 +164,172 @@ interface IConfigRepo {
     dispose(): Promise<void>;
 }
 
-export type { BackendDescriptor, BackendsMeta, BootstrapData, CacheOptions, ConfigRepoOptions, ConfigSerializer, ConflictArchive, ConflictInfo, IConfigRepo, SyncRule, SyncRulesMeta, VersionMeta };
+/**
+ * zen-fs-config — Config Serializers
+ *
+ * Handles serialization/deserialization between JS values and file bytes.
+ * The default serializer handles .json, .txt, and unknown extensions.
+ * Users can provide a custom ConfigSerializer via ConfigRepoOptions.
+ */
+
+/**
+ * Extended serializer that also accepts an optional path hint for routing.
+ * The core ConfigSerializer interface only takes `data`, but internally
+ * we use the path to pick the right serializer.
+ */
+interface PathAwareSerializer extends ConfigSerializer {
+    serialize(data: unknown, path?: string): Uint8Array;
+    deserialize(raw: Uint8Array, path?: string): unknown;
+}
+/**
+ * Create a serializer chain from a user-provided serializer + defaults.
+ * The first serializer whose `canHandle()` returns true wins.
+ */
+declare function createSerializerChain(custom?: ConfigSerializer): PathAwareSerializer;
+
+/**
+ * Map a config key to a file path.
+ *
+ * - `/db/host` → `/db/host.json` (append .json if no extension)
+ * - `/readme.md` → `/readme.md` (preserve existing extension)
+ */
+declare function configKeyToFilePath(configPath: string): string;
+/**
+ * Extract the file extension (including the dot), or empty string.
+ */
+declare function getExtension(path: string): string;
+
+/**
+ * zen-fs-config — ConfigRepo Implementation
+ *
+ * Core implementation of IConfigRepo and the createConfigRepo factory.
+ */
+
+interface MinimalAsyncFS {
+    readFile(path: string, ...args: any[]): Promise<any>;
+    writeFile(path: string, data: any, options?: any): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<any>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: any): Promise<any>;
+    unlink(path: string): Promise<void>;
+    rmdir?(path: string): Promise<void>;
+    rename?(oldPath: string, newPath: string): Promise<void>;
+}
+declare class ConfigRepo implements IConfigRepo {
+    readonly appId: string;
+    readonly nodeId: string;
+    /** Chroot-isolated fs for app-facing API. Typed as `any` to match `typeof import('node:fs')` duck-typically. */
+    readonly fs: any;
+    private cachedFS;
+    private fullFS;
+    private serializer;
+    private syncEngine;
+    private replicaBackends;
+    private onConflictCallback?;
+    private disposed;
+    private configCache;
+    constructor(appId: string, nodeId: string, cachedFS: MinimalAsyncFS, serializer: PathAwareSerializer, onConflict?: (conflict: ConflictInfo) => Promise<unknown | null>);
+    load(rawConfig?: string): Promise<void>;
+    getConfig<T = unknown>(path: string): T;
+    setConfig(path: string, data: unknown): void;
+    getNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
+    setNodeConfig(nodeId: string, path: string, data: unknown): Promise<void>;
+    publishNodeConfig(nodeId: string, options?: {
+        paths?: string[];
+    }): Promise<SyncResult>;
+    peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
+    flush(): Promise<SyncResult[]>;
+    getSyncStatuses(): Map<string, SyncPairStatus>;
+    resolveConflict(conflictId: string, mergedContent: unknown): Promise<void>;
+    listConflicts(): Promise<ConflictArchive[]>;
+    dispose(): Promise<void>;
+    setupSync(rules: SyncRule[], backends: BackendDescriptor[], primaryBackendId: string): Promise<void>;
+    private persistConfig;
+    private reloadConfigCache;
+    private handleConflict;
+    private ensureDir;
+    private walkDir;
+    writeMetaFile(path: string, data: BackendsMeta | SyncRulesMeta): Promise<void>;
+    readMetaFile<T>(path: string): Promise<T | null>;
+    private tryParse;
+    private assertNotDisposed;
+}
+declare function createConfigRepo(appId: string, options: ConfigRepoOptions): Promise<IConfigRepo>;
+
+/**
+ * zen-fs-config — Backend Registry
+ *
+ * A pluggable registry that maps backend type names to factory functions.
+ * Built-in support for ZenFS backends (InMemory, IndexedDB, etc.)
+ * loaded from @zenfs/core.
+ *
+ * Users can register custom backends via `registerBackend()`.
+ */
+
+type BackendFactory = (options: Record<string, unknown>) => Promise<BackendInstance>;
+/**
+ * The minimal interface a backend instance must satisfy.
+ * Matches zen-fs-cache's CacheableFileSystem requirements.
+ */
+interface BackendInstance {
+    readFile(path: string, ...args: any[]): Promise<any>;
+    writeFile(path: string, data: string | Uint8Array | ArrayBuffer, options?: any): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string, ...args: any[]): Promise<any>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: any): Promise<any>;
+    unlink(path: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    rename?(oldPath: string, newPath: string): Promise<void>;
+    readFileMeta?(path: string, opts?: any): Promise<any>;
+    getRevision?(path: string): Promise<string | number | undefined>;
+}
+declare function registerBackend(type: string, factory: BackendFactory): void;
+declare function createBackend(descriptor: Pick<BackendDescriptor, 'type' | 'options'>): Promise<BackendInstance>;
+declare function hasBackend(type: string): boolean;
+declare function listBackends(): string[];
+
+/**
+ * zen-fs-config — Sidecar Version File Management
+ *
+ * Each config file has a companion .version file for version-based change
+ * detection and conflict resolution.
+ *
+ * Config file:  /app-a/db.json
+ * Version file: /app-a/.db.json.version
+ */
+
+/**
+ * Compute the sidecar version file path from a config file path.
+ *
+ * /app-a/db.json        → /app-a/.db.json.version
+ * /shared/flags.json    → /shared/.flags.json.version
+ * /nodes/s1/env.json    → /nodes/s1/.env.json.version
+ */
+declare function versionPathFor(configFilePath: string): string;
+/**
+ * Compute SHA-256 hash of a Uint8Array.
+ * Returns "sha256:" prefix + hex digest.
+ */
+declare function sha256(data: Uint8Array): Promise<string>;
+/**
+ * Read and parse a version file. Returns null if it doesn't exist or is invalid.
+ */
+declare function readVersion(fs: SyncableFS, versionFilePath: string): Promise<VersionMeta | null>;
+/**
+ * Write a version file.
+ */
+declare function writeVersion(fs: SyncableFS, versionFilePath: string, meta: VersionMeta): Promise<void>;
+/**
+ * Increment version for a config file write.
+ */
+declare function incrementVersion(fs: SyncableFS, configFilePath: string, newContent: Uint8Array, author: string): Promise<VersionMeta>;
+/**
+ * Verify that the version file's hash matches the actual file content.
+ * If mismatch, auto-increment version and return updated meta.
+ * If version file doesn't exist, return null.
+ */
+declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
+
+export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type BootstrapData, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type SyncRule, type SyncRulesMeta, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, verifyOrRepairVersion, versionPathFor, writeVersion };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import * as node_fs from 'node:fs';
-import { ConflictStrategy, SyncResult, SyncPairStatus } from 'zen-fs-sync';
+import { ConflictStrategy, SyncResult, SyncPairStatus, SyncableFS } from 'zen-fs-sync';
 export { SyncPairStatus, SyncResult } from 'zen-fs-sync';
+import * as node_fs from 'node:fs';
 
 /** A single backend in the topology. */
 interface BackendDescriptor {
@@ -143,15 +143,15 @@ interface IConfigRepo {
     /** Write a config value (auto-synced). */
     setConfig(path: string, data: unknown): void;
     /** Read node-local config. */
-    getNodeConfig<T = unknown>(nodeId: string, path: string): T;
+    getNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     /** Write node-local config (no auto-sync). */
-    setNodeConfig(nodeId: string, path: string, data: unknown): void;
+    setNodeConfig(nodeId: string, path: string, data: unknown): Promise<void>;
     /** Publish node-local config to sync backends (one-time, for debugging). */
     publishNodeConfig(nodeId: string, options?: {
         paths?: string[];
     }): Promise<SyncResult>;
     /** Peek at another node's published config (read-only). */
-    peekNodeConfig<T = unknown>(nodeId: string, path: string): T;
+    peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     /** Manually flush all pending sync operations. */
     flush(): Promise<SyncResult[]>;
     /** Get sync status for all registered sync pairs. */
@@ -164,4 +164,172 @@ interface IConfigRepo {
     dispose(): Promise<void>;
 }
 
-export type { BackendDescriptor, BackendsMeta, BootstrapData, CacheOptions, ConfigRepoOptions, ConfigSerializer, ConflictArchive, ConflictInfo, IConfigRepo, SyncRule, SyncRulesMeta, VersionMeta };
+/**
+ * zen-fs-config — Config Serializers
+ *
+ * Handles serialization/deserialization between JS values and file bytes.
+ * The default serializer handles .json, .txt, and unknown extensions.
+ * Users can provide a custom ConfigSerializer via ConfigRepoOptions.
+ */
+
+/**
+ * Extended serializer that also accepts an optional path hint for routing.
+ * The core ConfigSerializer interface only takes `data`, but internally
+ * we use the path to pick the right serializer.
+ */
+interface PathAwareSerializer extends ConfigSerializer {
+    serialize(data: unknown, path?: string): Uint8Array;
+    deserialize(raw: Uint8Array, path?: string): unknown;
+}
+/**
+ * Create a serializer chain from a user-provided serializer + defaults.
+ * The first serializer whose `canHandle()` returns true wins.
+ */
+declare function createSerializerChain(custom?: ConfigSerializer): PathAwareSerializer;
+
+/**
+ * Map a config key to a file path.
+ *
+ * - `/db/host` → `/db/host.json` (append .json if no extension)
+ * - `/readme.md` → `/readme.md` (preserve existing extension)
+ */
+declare function configKeyToFilePath(configPath: string): string;
+/**
+ * Extract the file extension (including the dot), or empty string.
+ */
+declare function getExtension(path: string): string;
+
+/**
+ * zen-fs-config — ConfigRepo Implementation
+ *
+ * Core implementation of IConfigRepo and the createConfigRepo factory.
+ */
+
+interface MinimalAsyncFS {
+    readFile(path: string, ...args: any[]): Promise<any>;
+    writeFile(path: string, data: any, options?: any): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<any>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: any): Promise<any>;
+    unlink(path: string): Promise<void>;
+    rmdir?(path: string): Promise<void>;
+    rename?(oldPath: string, newPath: string): Promise<void>;
+}
+declare class ConfigRepo implements IConfigRepo {
+    readonly appId: string;
+    readonly nodeId: string;
+    /** Chroot-isolated fs for app-facing API. Typed as `any` to match `typeof import('node:fs')` duck-typically. */
+    readonly fs: any;
+    private cachedFS;
+    private fullFS;
+    private serializer;
+    private syncEngine;
+    private replicaBackends;
+    private onConflictCallback?;
+    private disposed;
+    private configCache;
+    constructor(appId: string, nodeId: string, cachedFS: MinimalAsyncFS, serializer: PathAwareSerializer, onConflict?: (conflict: ConflictInfo) => Promise<unknown | null>);
+    load(rawConfig?: string): Promise<void>;
+    getConfig<T = unknown>(path: string): T;
+    setConfig(path: string, data: unknown): void;
+    getNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
+    setNodeConfig(nodeId: string, path: string, data: unknown): Promise<void>;
+    publishNodeConfig(nodeId: string, options?: {
+        paths?: string[];
+    }): Promise<SyncResult>;
+    peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
+    flush(): Promise<SyncResult[]>;
+    getSyncStatuses(): Map<string, SyncPairStatus>;
+    resolveConflict(conflictId: string, mergedContent: unknown): Promise<void>;
+    listConflicts(): Promise<ConflictArchive[]>;
+    dispose(): Promise<void>;
+    setupSync(rules: SyncRule[], backends: BackendDescriptor[], primaryBackendId: string): Promise<void>;
+    private persistConfig;
+    private reloadConfigCache;
+    private handleConflict;
+    private ensureDir;
+    private walkDir;
+    writeMetaFile(path: string, data: BackendsMeta | SyncRulesMeta): Promise<void>;
+    readMetaFile<T>(path: string): Promise<T | null>;
+    private tryParse;
+    private assertNotDisposed;
+}
+declare function createConfigRepo(appId: string, options: ConfigRepoOptions): Promise<IConfigRepo>;
+
+/**
+ * zen-fs-config — Backend Registry
+ *
+ * A pluggable registry that maps backend type names to factory functions.
+ * Built-in support for ZenFS backends (InMemory, IndexedDB, etc.)
+ * loaded from @zenfs/core.
+ *
+ * Users can register custom backends via `registerBackend()`.
+ */
+
+type BackendFactory = (options: Record<string, unknown>) => Promise<BackendInstance>;
+/**
+ * The minimal interface a backend instance must satisfy.
+ * Matches zen-fs-cache's CacheableFileSystem requirements.
+ */
+interface BackendInstance {
+    readFile(path: string, ...args: any[]): Promise<any>;
+    writeFile(path: string, data: string | Uint8Array | ArrayBuffer, options?: any): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string, ...args: any[]): Promise<any>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: any): Promise<any>;
+    unlink(path: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    rename?(oldPath: string, newPath: string): Promise<void>;
+    readFileMeta?(path: string, opts?: any): Promise<any>;
+    getRevision?(path: string): Promise<string | number | undefined>;
+}
+declare function registerBackend(type: string, factory: BackendFactory): void;
+declare function createBackend(descriptor: Pick<BackendDescriptor, 'type' | 'options'>): Promise<BackendInstance>;
+declare function hasBackend(type: string): boolean;
+declare function listBackends(): string[];
+
+/**
+ * zen-fs-config — Sidecar Version File Management
+ *
+ * Each config file has a companion .version file for version-based change
+ * detection and conflict resolution.
+ *
+ * Config file:  /app-a/db.json
+ * Version file: /app-a/.db.json.version
+ */
+
+/**
+ * Compute the sidecar version file path from a config file path.
+ *
+ * /app-a/db.json        → /app-a/.db.json.version
+ * /shared/flags.json    → /shared/.flags.json.version
+ * /nodes/s1/env.json    → /nodes/s1/.env.json.version
+ */
+declare function versionPathFor(configFilePath: string): string;
+/**
+ * Compute SHA-256 hash of a Uint8Array.
+ * Returns "sha256:" prefix + hex digest.
+ */
+declare function sha256(data: Uint8Array): Promise<string>;
+/**
+ * Read and parse a version file. Returns null if it doesn't exist or is invalid.
+ */
+declare function readVersion(fs: SyncableFS, versionFilePath: string): Promise<VersionMeta | null>;
+/**
+ * Write a version file.
+ */
+declare function writeVersion(fs: SyncableFS, versionFilePath: string, meta: VersionMeta): Promise<void>;
+/**
+ * Increment version for a config file write.
+ */
+declare function incrementVersion(fs: SyncableFS, configFilePath: string, newContent: Uint8Array, author: string): Promise<VersionMeta>;
+/**
+ * Verify that the version file's hash matches the actual file content.
+ * If mismatch, auto-increment version and return updated meta.
+ * If version file doesn't exist, return null.
+ */
+declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
+
+export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type BootstrapData, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type SyncRule, type SyncRulesMeta, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, verifyOrRepairVersion, versionPathFor, writeVersion };