dsh-shared-kb 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,251 @@
1
+ /**
2
+ * 跨机器租约(lease)。
3
+ *
4
+ * 问题:知识库放在共享盘上,多台机器、多个进程、多个会话同时改同一个库。
5
+ * 需要一种「在共享盘上也能正确工作」的互斥原语。
6
+ *
7
+ * 为什么不用文件锁(flock/LockFileEx):SMB 上的文件锁语义各实现不一,
8
+ * 有的静默降级成无锁,出问题时表现为「两个进程都以为自己拿到了锁」,
9
+ * 数据损坏且无迹可查。
10
+ *
11
+ * 采用的做法:**目录原子创建 + owner 心跳**。
12
+ * - mkdir 在所有主流文件系统(含 SMB/NFS)上是原子的:
13
+ * 恰好一个调用方成功,其余 EEXIST。
14
+ * - 锁目录里写 owner.json(machine / pid / 心跳时间 / 随机 token)。
15
+ * - 持有者定期刷新 owner.json 的 heartbeatAt(不是 mtime,mtime 在
16
+ * SMB 上可能因为时钟偏移或缓存而失真)。
17
+ * - 回收判据:心跳超过 staleMs 未更新 **且** 能证明持有者已不在
18
+ * (同机则查 PID,异机则只看心跳超时)。
19
+ * - 释放:删除锁目录。为了防「删掉别人刚抢到的锁」,释放前比对 token。
20
+ *
21
+ * 这不是一个「绝对正确」的分布式锁(共享盘上不存在这种东西),
22
+ * 而是一个**失败可见、可自愈、竞争窗口极小**的方案:
23
+ * 真正的写入正确性由 revision CAS 兜底 —— 即使锁失效导致并发写,
24
+ * CAS 也会让后来的写入失败而不是静默覆盖。
25
+ */
26
+ import { randomBytes } from "node:crypto";
27
+ import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
28
+ import { join } from "node:path";
29
+ import { HubError } from "../core/errors.js";
30
+ import { machineId } from "../core/hubconfig.js";
31
+ import { locksDir } from "../core/paths.js";
32
+
33
+ const OWNER_FILE = "owner.json";
34
+ /** 心跳间隔:持有者每隔这么久刷新一次。 */
35
+ export const LEASE_HEARTBEAT_MS = 5_000;
36
+ /** 心跳超过这么久没更新 = 持有者失联,可回收。 */
37
+ export const LEASE_STALE_MS = 30_000;
38
+ const DEFAULT_TIMEOUT_MS = 20_000;
39
+ const POLL_MS = 120;
40
+
41
+ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
42
+
43
+ function isPidAlive(pid) {
44
+ if (!Number.isInteger(pid) || pid <= 0) return false;
45
+ try {
46
+ process.kill(pid, 0);
47
+ return true;
48
+ } catch (error) {
49
+ // EPERM = 进程存在但信号不通;ESRCH = 真的没了
50
+ return error?.code === "EPERM";
51
+ }
52
+ }
53
+
54
+ async function readOwner(lockDir) {
55
+ try {
56
+ const raw = JSON.parse(await readFile(join(lockDir, OWNER_FILE), "utf8"));
57
+ if (typeof raw?.token !== "string") return null;
58
+ return raw;
59
+ } catch {
60
+ return null;
61
+ }
62
+ }
63
+
64
+ /** 刚创建的锁有一个极短保护期:防止「mkdir 成功、owner.json 还没写完」被误判成僵尸。 */
65
+ const MIN_RECLAIM_AGE_MS = 300;
66
+
67
+ /**
68
+ * 判断一个已有锁是否可回收。
69
+ *
70
+ * 判据分两类,不能混用:
71
+ * 同机 —— PID 是硬证据。进程不在了,锁一定是死的,可以立即回收(只需越过
72
+ * 300ms 的最小保护期,避开写 owner.json 的窗口)。指望等心跳超时
73
+ * 是错的:进程崩溃后没人刷新心跳,但那把锁本来就已经无效了。
74
+ * 异机 —— 只能靠心跳。共享盘上拿不到别的机器的进程表,心跳停了超过
75
+ * staleMs 才认为失联(staleMs 由调用方传入,不是全局常量)。
76
+ *
77
+ * @param {object|null} owner
78
+ * @param {number} now
79
+ * @param {number} staleMs
80
+ */
81
+ function reclaimable(owner, now, staleMs) {
82
+ if (!owner) return { ok: false, reason: "no-owner" };
83
+ const beat = Number(owner.heartbeatAt) || 0;
84
+ const age = now - beat;
85
+ const sameMachine = owner.machine === machineId();
86
+
87
+ if (sameMachine) {
88
+ const alive = isPidAlive(Number(owner.pid));
89
+ if (!alive) {
90
+ if (age >= MIN_RECLAIM_AGE_MS) return { ok: true, reason: "same-machine-dead-pid", ageMs: age };
91
+ return { ok: false, reason: "too-young", ageMs: age };
92
+ }
93
+ // PID 还活着但心跳停了很久:可能是调试断点 / 长时间 GC / 磁盘卡住。
94
+ // 给一个远宽于 staleMs 的窗口,宁可多等也不误抢活进程的锁。
95
+ return { ok: age > staleMs * 4, reason: "same-machine-stalled", ageMs: age };
96
+ }
97
+
98
+ if (age > staleMs) return { ok: true, reason: "remote-heartbeat-timeout", ageMs: age };
99
+ return { ok: false, reason: "fresh", ageMs: age };
100
+ }
101
+
102
+ /** 锁目录路径:按 scope 分文件,不同 scope 互不阻塞(例如 doc:<id> 与 kb)。 */
103
+ function lockPath(dir, scope) {
104
+ const safe = String(scope ?? "kb").replace(/[^A-Za-z0-9_.:-]/g, "_");
105
+ return join(locksDir(dir), `${safe}.lease`);
106
+ }
107
+
108
+ /**
109
+ * 在租约保护下执行 fn。
110
+ *
111
+ * @param {string} dir 知识库目录(库级)或任意需要互斥的目录
112
+ * @param {string} scope 锁作用域:`kb`(整库)/ `doc:<docId>`(单文档)/ `idx`(索引)
113
+ * @param {(ctx: {token: string, beat: () => Promise<void>}) => Promise<any>} fn
114
+ * @param {{timeoutMs?: number, staleMs?: number, onWait?: (info: object) => void}} [options]
115
+ */
116
+ export async function withLease(dir, scope, fn, options = {}) {
117
+ const timeoutMs = Number(options.timeoutMs) > 0 ? Number(options.timeoutMs) : DEFAULT_TIMEOUT_MS;
118
+ const staleMs = Number(options.staleMs) > 0 ? Number(options.staleMs) : LEASE_STALE_MS;
119
+ const path = lockPath(dir, scope);
120
+ await mkdir(locksDir(dir), { recursive: true });
121
+
122
+ const token = randomBytes(8).toString("hex");
123
+ const owner = {
124
+ token,
125
+ scope: String(scope ?? "kb"),
126
+ machine: machineId(),
127
+ pid: process.pid,
128
+ acquiredAt: Date.now(),
129
+ heartbeatAt: Date.now(),
130
+ };
131
+
132
+ const started = Date.now();
133
+ let acquired = false;
134
+ for (;;) {
135
+ try {
136
+ await mkdir(path);
137
+ acquired = true;
138
+ break;
139
+ } catch (error) {
140
+ if (error?.code !== "EEXIST") throw error;
141
+ const holder = await readOwner(path);
142
+ const verdict = reclaimable(holder, Date.now(), staleMs);
143
+ if (verdict.ok) {
144
+ // 回收:先改名再删,避免「删到别人刚建的锁」。
145
+ const grave = `${path}.stale.${randomBytes(4).toString("hex")}`;
146
+ try {
147
+ await rename(path, grave);
148
+ await rm(grave, { recursive: true, force: true });
149
+ } catch {
150
+ /* 别人先回收了,继续重试 */
151
+ }
152
+ continue;
153
+ }
154
+ if (Date.now() - started > timeoutMs) {
155
+ throw new HubError(
156
+ "LEASE_TIMEOUT",
157
+ holder
158
+ ? `该库正被 ${holder.machine} 上的进程 ${holder.pid} 占用(作用域 ${holder.scope}),请稍后重试`
159
+ : "该库正在被另一个任务修改,请稍后重试",
160
+ {
161
+ status: 409,
162
+ details: holder ? { holder: { ...holder, heartbeatAt: undefined } } : { scope },
163
+ retryAfterMs: Math.max(250, staleMs - (Date.now() - (Number(holder?.heartbeatAt) || 0))),
164
+ }
165
+ );
166
+ }
167
+ options.onWait?.(holder ?? null);
168
+ await sleep(POLL_MS + Math.floor(Math.random() * 80));
169
+ }
170
+ }
171
+
172
+ try {
173
+ await writeFile(join(path, OWNER_FILE), JSON.stringify(owner), "utf8");
174
+ } catch {
175
+ /* owner 写失败不阻断:回收退化为只看目录存在 */
176
+ }
177
+
178
+ let stopped = false;
179
+ const timer = setInterval(() => {
180
+ if (stopped) return;
181
+ owner.heartbeatAt = Date.now();
182
+ writeFile(join(path, OWNER_FILE), JSON.stringify(owner), "utf8").catch(() => {});
183
+ }, Math.min(LEASE_HEARTBEAT_MS, Math.floor(staleMs / 4)));
184
+ if (typeof timer.unref === "function") timer.unref();
185
+
186
+ const beat = async () => {
187
+ owner.heartbeatAt = Date.now();
188
+ await writeFile(join(path, OWNER_FILE), JSON.stringify(owner), "utf8").catch(() => {});
189
+ };
190
+
191
+ try {
192
+ return await fn({ token, beat });
193
+ } finally {
194
+ stopped = true;
195
+ clearInterval(timer);
196
+ // 只删自己那把:token 对不上说明已被回收并被别人重新持有。
197
+ const current = await readOwner(path);
198
+ if (!current || current.token === token) {
199
+ await rm(path, { recursive: true, force: true }).catch(() => {});
200
+ }
201
+ }
202
+ }
203
+
204
+ /** 查看当前锁状态(诊断用,不加锁、不修改)。 */
205
+ export async function inspectLeases(dir) {
206
+ const root = locksDir(dir);
207
+ let names = [];
208
+ try {
209
+ names = await readdir(root);
210
+ } catch {
211
+ return [];
212
+ }
213
+ const now = Date.now();
214
+ const out = [];
215
+ for (const name of names) {
216
+ if (!name.endsWith(".lease")) continue;
217
+ const full = join(root, name);
218
+ const owner = await readOwner(full);
219
+ out.push({
220
+ scope: owner?.scope ?? name.replace(/\.lease$/, ""),
221
+ machine: owner?.machine ?? null,
222
+ pid: owner?.pid ?? null,
223
+ holderLabel: owner ? `${owner.machine}:${owner.pid}` : "unknown",
224
+ ageMs: owner ? now - (Number(owner.heartbeatAt) || 0) : null,
225
+ stale: owner ? now - (Number(owner.heartbeatAt) || 0) > LEASE_STALE_MS : true,
226
+ });
227
+ }
228
+ return out;
229
+ }
230
+
231
+ /** 强制清理超时锁(管理动作,需显式调用;返回被清掉的 scope)。 */
232
+ export async function pruneStaleLeases(dir) {
233
+ const root = locksDir(dir);
234
+ let names = [];
235
+ try {
236
+ names = await readdir(root);
237
+ } catch {
238
+ return [];
239
+ }
240
+ const cleaned = [];
241
+ for (const name of names) {
242
+ if (!name.endsWith(".lease")) continue;
243
+ const full = join(root, name);
244
+ const owner = await readOwner(full);
245
+ const verdict = reclaimable(owner, Date.now(), LEASE_STALE_MS);
246
+ if (!verdict.ok) continue;
247
+ await rm(full, { recursive: true, force: true }).catch(() => {});
248
+ cleaned.push({ scope: owner?.scope ?? name, reason: verdict.reason, ageMs: verdict.ageMs });
249
+ }
250
+ return cleaned;
251
+ }
@@ -0,0 +1,263 @@
1
+ /**
2
+ * 知识库清单(manifest.json)—— 多人共用的唯一真相。
3
+ *
4
+ * 设计要点:
5
+ *
6
+ * 1. **revision 单调递增**。每次成功写入 rev+1(不是时间戳,时间戳在多机
7
+ * 时钟偏移下会倒退,无法比较先后)。
8
+ *
9
+ * 2. **CAS(compare-and-swap)**。写入前必须声明「我基于哪一版改」:
10
+ * - 显式传 expectedRev:调用方已经读过这一版,改动依赖它;
11
+ * - 不传:读-改-写在同一把租约内完成,视为自动取最新。
12
+ * 两者都不允许「后写覆盖先写」:rev 对不上就抛 REV_CONFLICT,
13
+ * 并回传当前 rev 与冲突的文档,让上层决定重试还是合并。
14
+ *
15
+ * 3. **原子落盘**。临时文件 + rename。共享盘上 rename 在同一目录内是原子的。
16
+ *
17
+ * 4. **写前留版本**。每篇文档保留最近 N 版正文快照,别人覆盖了还能找回来。
18
+ *
19
+ * 5. **事件日志**。所有写操作追加到 events.jsonl(只增不改),
20
+ * 这是「谁在什么时候改了什么」的唯一凭据,多人协作时比 manifest 更重要。
21
+ */
22
+ import { appendFile, mkdir, readFile, stat } from "node:fs/promises";
23
+ import { writeFileAtomic } from "../core/atomic.js";
24
+ import { join } from "node:path";
25
+ import { conflict, HubError } from "../core/errors.js";
26
+ import { machineId } from "../core/hubconfig.js";
27
+ import { kbMetaPath, locksDir } from "../core/paths.js";
28
+ import { withLease } from "./lease.js";
29
+
30
+ export const MANIFEST_SCHEMA = 3;
31
+ const MANIFEST_FILE = "manifest.json";
32
+ const EVENTS_FILE = "events.jsonl";
33
+ /** 每篇文档保留多少个历史正文版本。 */
34
+ export const DEFAULT_HISTORY_KEEP = 10;
35
+ /** 事件日志超过这个行数时提示归档(不自动删,删日志要人确认)。 */
36
+ export const EVENTS_ROTATE_HINT = 50_000;
37
+
38
+ function manifestPath(dir) {
39
+ return join(dir, MANIFEST_FILE);
40
+ }
41
+
42
+ export function emptyManifest(name) {
43
+ return {
44
+ schemaVersion: MANIFEST_SCHEMA,
45
+ name,
46
+ rev: 0,
47
+ createdAt: new Date().toISOString(),
48
+ updatedAt: new Date().toISOString(),
49
+ updatedBy: null,
50
+ schemaDoc: "",
51
+ docs: [],
52
+ stats: { docs: 0, chars: 0 },
53
+ };
54
+ }
55
+
56
+ /**
57
+ * 迁移旧清单。
58
+ * 只做「补齐缺省字段」,不做语义改写 —— 迁移必须幂等且可在别人的机器上重复跑。
59
+ */
60
+ export function migrateManifest(raw, name) {
61
+ const base = emptyManifest(name);
62
+ if (!raw || typeof raw !== "object") return base;
63
+ const schema = Number(raw.schemaVersion) || 1;
64
+ const docs = Array.isArray(raw.docs)
65
+ ? raw.docs.map((doc) => normalizeDoc(doc)).filter(Boolean)
66
+ : [];
67
+ const out = {
68
+ ...base,
69
+ ...raw,
70
+ schemaVersion: MANIFEST_SCHEMA,
71
+ rev: Number.isInteger(raw.rev) && raw.rev >= 0 ? raw.rev : 0,
72
+ docs,
73
+ name: raw.name ?? name,
74
+ };
75
+ if (schema < MANIFEST_SCHEMA) {
76
+ out.migratedFrom = schema;
77
+ out.migratedAt = new Date().toISOString();
78
+ }
79
+ out.stats = recomputeStats(docs);
80
+ return out;
81
+ }
82
+
83
+ /** 文档条目规范化:保留未知字段(前向兼容,别人新版本写的字段不能被我抹掉)。 */
84
+ function normalizeDoc(doc) {
85
+ if (!doc || typeof doc !== "object" || typeof doc.id !== "string") return null;
86
+ return {
87
+ ...doc,
88
+ version: Number.isInteger(doc.version) ? doc.version : 1,
89
+ status: typeof doc.status === "string" ? doc.status : "ready",
90
+ tags: Array.isArray(doc.tags) ? doc.tags : [],
91
+ };
92
+ }
93
+
94
+ export function recomputeStats(docs) {
95
+ const live = docs.filter((doc) => !doc.deletedAt && doc.status === "ready");
96
+ return {
97
+ docs: live.length,
98
+ chars: live.reduce((sum, doc) => sum + (Number(doc.chars) || 0), 0),
99
+ all: docs.length,
100
+ };
101
+ }
102
+
103
+ /** 读清单;文件不存在返回空清单(不抛异常,新建库路径也要能走通)。 */
104
+ export async function readManifest(dir, name = "default") {
105
+ try {
106
+ const raw = JSON.parse(await readFile(manifestPath(dir), "utf8"));
107
+ return migrateManifest(raw, name);
108
+ } catch (error) {
109
+ if (error?.code === "ENOENT") return emptyManifest(name);
110
+ // JSON 坏了不能静默当空库:那会让下一次写入把整库清单覆盖成只有一条。
111
+ throw new HubError("MANIFEST_CORRUPT", `清单文件损坏,请从备份恢复:${manifestPath(dir)}`, {
112
+ status: 500,
113
+ details: { path: manifestPath(dir), cause: String(error?.message ?? error) },
114
+ });
115
+ }
116
+ }
117
+
118
+ /** 只读探测:文件在不在、多大、多久没动(用于「别人刚改过」判定)。 */
119
+ export async function manifestStat(dir) {
120
+ try {
121
+ const s = await stat(manifestPath(dir));
122
+ return { exists: true, size: s.size, mtimeMs: s.mtimeMs };
123
+ } catch {
124
+ return { exists: false, size: 0, mtimeMs: 0 };
125
+ }
126
+ }
127
+
128
+ async function writeManifestAtomic(dir, manifest) {
129
+ await mkdir(dir, { recursive: true });
130
+ // 必须走带重试的原子写:清单是所有人共用的唯一真相,
131
+ // 在 Windows 共享盘上裸 rename 覆盖会间歇 EPERM,表现为「随机丢条目」。
132
+ await writeFileAtomic(manifestPath(dir), JSON.stringify(manifest, null, 2), { encoding: "utf8" });
133
+ }
134
+
135
+ function touch(manifest, by) {
136
+ manifest.updatedAt = new Date().toISOString();
137
+ manifest.updatedBy = by ?? { machine: machineId(), pid: process.pid };
138
+ manifest.stats = recomputeStats(manifest.docs ?? []);
139
+ }
140
+
141
+ /**
142
+ * 在租约 + CAS 保护下修改清单。
143
+ *
144
+ * @param {string} dir 知识库目录
145
+ * @param {string} name 库名
146
+ * @param {(manifest: object, ctx: {now: string, by: object}) => any} mutate
147
+ * 直接改传入的 manifest;返回值原样传回调用方。
148
+ * @param {{expectedRev?: number, by?: object, scope?: string, timeoutMs?: number}} [options]
149
+ * @returns {Promise<{rev: number, result: any, manifest: object}>}
150
+ */
151
+ export async function withManifest(dir, name, mutate, options = {}) {
152
+ const scope = options.scope ?? "kb";
153
+ return withLease(
154
+ dir,
155
+ scope,
156
+ async () => {
157
+ const manifest = await readManifest(dir, name);
158
+ const expected = options.expectedRev;
159
+ if (expected !== undefined && Number(expected) !== manifest.rev) {
160
+ throw conflict(
161
+ `清单已被其他人更新(当前 rev ${manifest.rev},你基于 rev ${expected}),请重新读取后再提交`,
162
+ { currentRev: manifest.rev, expectedRev: Number(expected), updatedAt: manifest.updatedAt, updatedBy: manifest.updatedBy }
163
+ );
164
+ }
165
+ const by = options.by ?? { machine: machineId(), pid: process.pid };
166
+ const now = new Date().toISOString();
167
+ const result = await mutate(manifest, { now, by });
168
+ manifest.rev = manifest.rev + 1;
169
+ touch(manifest, by);
170
+ await writeManifestAtomic(dir, manifest);
171
+ return { rev: manifest.rev, result, manifest };
172
+ },
173
+ { timeoutMs: options.timeoutMs }
174
+ );
175
+ }
176
+
177
+ /** 只读访问:不加锁,也不改任何东西。 */
178
+ export async function withManifestRead(dir, name, fn) {
179
+ const manifest = await readManifest(dir, name);
180
+ return fn(manifest);
181
+ }
182
+
183
+ /** 失败重试版:CAS 冲突时重读并重跑 mutate(只用于可安全重放的变更)。 */
184
+ export async function withManifestRetry(dir, name, mutate, options = {}) {
185
+ const attempts = Math.max(1, Number(options.attempts) || 4);
186
+ let lastError = null;
187
+ for (let i = 0; i < attempts; i += 1) {
188
+ try {
189
+ return await withManifest(dir, name, mutate, { ...options, expectedRev: undefined });
190
+ } catch (error) {
191
+ lastError = error;
192
+ if (error?.code !== "REV_CONFLICT" && error?.code !== "LEASE_TIMEOUT") throw error;
193
+ await new Promise((r) => setTimeout(r, 120 * (i + 1) + Math.floor(Math.random() * 90)));
194
+ }
195
+ }
196
+ throw lastError;
197
+ }
198
+
199
+ /** 追加一条事件(只增不改;失败不影响主流程,审计不该阻断业务)。 */
200
+ export async function appendEvent(dir, event) {
201
+ const record = {
202
+ at: new Date().toISOString(),
203
+ machine: machineId(),
204
+ pid: process.pid,
205
+ ...event,
206
+ };
207
+ try {
208
+ await mkdir(dir, { recursive: true });
209
+ await appendFile(join(dir, EVENTS_FILE), JSON.stringify(record) + "\n", "utf8");
210
+ } catch {
211
+ /* 事件日志写不进去(只读盘 / 权限)不影响本次操作 */
212
+ }
213
+ return record;
214
+ }
215
+
216
+ /** 读最近 N 条事件(倒序)。大文件只读尾部,避免一次读几百 MB。 */
217
+ export async function readEvents(dir, { limit = 100, docId = null } = {}) {
218
+ const path = join(dir, EVENTS_FILE);
219
+ let text = "";
220
+ try {
221
+ const s = await stat(path);
222
+ const tailBytes = Math.min(s.size, 1024 * 1024 * 4);
223
+ const handle = await readFile(path);
224
+ text = handle.subarray(Math.max(0, handle.length - tailBytes)).toString("utf8");
225
+ } catch {
226
+ return [];
227
+ }
228
+ const lines = text.split("\n").filter((line) => line.trim() !== "");
229
+ // 首行可能被截断(我们从中间开始读),丢掉它
230
+ if (lines.length > 1) lines.shift();
231
+ const out = [];
232
+ for (let i = lines.length - 1; i >= 0 && out.length < limit; i -= 1) {
233
+ try {
234
+ const record = JSON.parse(lines[i]);
235
+ if (docId && record.docId !== docId) continue;
236
+ out.push(record);
237
+ } catch {
238
+ /* 跳过坏行 */
239
+ }
240
+ }
241
+ return out;
242
+ }
243
+
244
+ /** 库级元数据(kb.json):描述、默认检索配置、schema 版本。 */
245
+ export async function readKbMeta(dir) {
246
+ try {
247
+ return JSON.parse(await readFile(kbMetaPath(dir), "utf8"));
248
+ } catch {
249
+ return null;
250
+ }
251
+ }
252
+
253
+ export async function writeKbMeta(dir, meta) {
254
+ await mkdir(dir, { recursive: true });
255
+ await writeFileAtomic(kbMetaPath(dir), JSON.stringify({ ...meta, updatedAt: new Date().toISOString() }, null, 2), {
256
+ encoding: "utf8",
257
+ });
258
+ }
259
+
260
+ /** 确保 .locks 目录存在(租约前置条件)。 */
261
+ export async function ensureLocksDir(dir) {
262
+ await mkdir(locksDir(dir), { recursive: true });
263
+ }