@yefengr/pi-reach 0.0.4 → 0.0.6

package/dist/attachments/reservation.fixture.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/attachments/reservation.fixture.js

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+import { AttachmentStore, AttachmentStoreError } from "./store.js";
+// 仅由隔离测试的 IPC 子进程调用；不使用默认附件目录。
+const rootDir = process.argv[2];
+const available = BigInt(process.argv[3]);
+const allocationUnitBytes = Number(process.argv[4] ?? 1);
+const contents = "x".repeat(Number(process.argv[5] ?? 4));
+if (!rootDir || !process.send)
+    throw new Error("Isolated fixture requires root and IPC");
+const store = new AttachmentStore({
+    rootDir, runtimeId: `fixture-${process.pid}`, minFreeBytes: 2,
+    testHooks: { availableBytes: () => available, allocationUnitBytes },
+});
+const scope = { ownerId: "fixture-owner", sessionId: "session", uploadScope: store.scopeFor("session") };
+process.on("message", (message) => {
+    if (message !== "begin")
+        return;
+    void store.begin(scope, {
+        uploadId: "fixture-upload", fileName: "fixture.bin", mimeType: "application/octet-stream", byteLength: contents.length,
+        sha256: createHash("sha256").update(contents).digest("hex"),
+    }).then(() => process.send?.({ type: "result", accepted: true }), (error) => process.send?.({ type: "result", accepted: false,
+        code: error instanceof AttachmentStoreError ? error.code : "unexpected" }));
+});
+process.send({ type: "ready" });
+//# sourceMappingURL=reservation.fixture.js.map

package/dist/attachments/reservation.fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reservation.fixture.js","sourceRoot":"","sources":["../../src/attachments/reservation.fixture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEnE,+BAA+B;AAC/B,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAChC,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1C,MAAM,mBAAmB,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACzD,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC1D,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI;IAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;AACzF,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC;IAChC,OAAO,EAAE,SAAS,EAAE,WAAW,OAAO,CAAC,GAAG,EAAE,EAAE,YAAY,EAAE,CAAC;IAC7D,SAAS,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,mBAAmB,EAAE;CACpE,CAAC,CAAC;AACH,MAAM,KAAK,GAAG,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;AACzG,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAgB,EAAE,EAAE;IACzC,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO;IAChC,KAAK,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE;QACtB,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,0BAA0B,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM;QACtH,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;KAC5D,CAAC,CAAC,IAAI,CACL,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EACxD,CAAC,KAAc,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK;QAClE,IAAI,EAAE,KAAK,YAAY,oBAAoB,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAC7E,CAAC;AACJ,CAAC,CAAC,CAAC;AACH,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC"}

package/dist/attachments/reservations.d.ts

@@ -0,0 +1,21 @@
+import { type AttachmentStoreTestHooks } from "./types.js";
+export declare class DiskReservation {
+    private readonly root;
+    private readonly byteLength;
+    private readonly floor;
+    private readonly hooks;
+    private readonly directory;
+    private readonly path;
+    private readonly record;
+    private published;
+    private allocationUnit;
+    constructor(root: string, runtimeId: string, uploadId: string, byteLength: number, floor: bigint, hooks?: AttachmentStoreTestHooks);
+    publish(): Promise<void>;
+    private replace;
+    private assertOwned;
+    private totalRemaining;
+    check(): Promise<void>;
+    private available;
+    reduce(remainingBytes: number): Promise<void>;
+    remove(): Promise<void>;
+}

package/dist/attachments/reservations.js

@@ -0,0 +1,189 @@
+import { randomUUID } from "node:crypto";
+import { link, opendir, rename, statfs, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { ATTACHMENT_MAX_FILE_BYTES } from "../vendor/protocol/session/index.js";
+import { assertDirectories, assertRegularFile, createPrivateFile, ensurePrivateDirectory, readPrivateFile } from "./safe-files.js";
+import { AttachmentStoreError, nodeErrorHasCode } from "./types.js";
+const RECORD_MAX_BYTES = 4096;
+const RECORD_MAX_COUNT = 4096;
+const CHECK_ATTEMPTS = 3;
+const CHECK_RETRY_MS = 5;
+const UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const RECORD_NAME = new RegExp(`^${UUID}\\.json$`);
+const PENDING_NAME = new RegExp(`^${UUID}\\.pending$`);
+function roundAllocation(bytes, unit) {
+    const rounded = ((BigInt(bytes) + unit - 1n) / unit) * unit;
+    if (rounded > BigInt(Number.MAX_SAFE_INTEGER))
+        throw new AttachmentStoreError("io_error");
+    return Number(rounded);
+}
+function parseRecord(raw, unit) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw new AttachmentStoreError("io_error");
+    }
+    if (typeof data !== "object" || data === null)
+        throw new AttachmentStoreError("io_error");
+    const item = data;
+    if (Object.keys(item).sort().join(",") !== "pid,remainingBytes,runtimeId,uploadId" ||
+        !Number.isSafeInteger(item.pid) || (item.pid ?? 0) <= 0 ||
+        typeof item.runtimeId !== "string" || item.runtimeId.length < 1 || item.runtimeId.length > 256 ||
+        typeof item.uploadId !== "string" || item.uploadId.length < 1 || item.uploadId.length > 256 ||
+        !Number.isSafeInteger(item.remainingBytes) || (item.remainingBytes ?? -1) < 0 ||
+        (item.remainingBytes ?? Infinity) > roundAllocation(ATTACHMENT_MAX_FILE_BYTES, unit) ||
+        BigInt(item.remainingBytes ?? 0) % unit !== 0n) {
+        throw new AttachmentStoreError("io_error");
+    }
+    return item;
+}
+function provenDead(pid) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        return nodeErrorHasCode(error, "ESRCH");
+    }
+    // PID 复用和 EPERM 都保守占预算，不按年龄删除记录或原件。
+    return false;
+}
+export class DiskReservation {
+    root;
+    byteLength;
+    floor;
+    hooks;
+    directory;
+    path;
+    record;
+    published = false;
+    allocationUnit = 1n;
+    constructor(root, runtimeId, uploadId, byteLength, floor, hooks = {}) {
+        this.root = root;
+        this.byteLength = byteLength;
+        this.floor = floor;
+        this.hooks = hooks;
+        this.directory = join(root, ".reservations");
+        this.path = join(this.directory, `${randomUUID()}.json`);
+        this.record = { pid: process.pid, runtimeId, uploadId, remainingBytes: byteLength };
+    }
+    async publish() {
+        ensurePrivateDirectory(this.directory);
+        this.allocationUnit = this.hooks.availableBytes ? BigInt(this.hooks.allocationUnitBytes ?? 1) :
+            (await statfs(this.root, { bigint: true })).bsize;
+        if (this.allocationUnit <= 0n)
+            throw new AttachmentStoreError("io_error");
+        this.record.remainingBytes = roundAllocation(this.record.remainingBytes, this.allocationUnit);
+        await this.replace(this.record, true);
+        this.published = true;
+        try {
+            await this.check();
+        }
+        catch (error) {
+            await this.remove();
+            throw error;
+        }
+    }
+    async replace(record, initial) {
+        assertDirectories(this.directory);
+        const pending = join(this.directory, `${randomUUID()}.pending`);
+        const handle = await createPrivateFile(pending);
+        try {
+            await handle.writeFile(JSON.stringify(record));
+            await handle.sync();
+            await handle.close();
+            if (initial) {
+                // link 为独占发布；pending 从不计入 credits，也从不准许写原件。
+                await link(pending, this.path);
+            }
+            else {
+                await this.assertOwned();
+                await rename(pending, this.path);
+            }
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+            await unlink(pending).catch((error) => {
+                if (!nodeErrorHasCode(error, "ENOENT"))
+                    throw error;
+            });
+        }
+    }
+    async assertOwned() {
+        if (!this.published)
+            throw new AttachmentStoreError("invalid_upload");
+        assertDirectories(this.directory);
+        const current = parseRecord(await readPrivateFile(this.path, RECORD_MAX_BYTES), this.allocationUnit);
+        if (current.pid !== this.record.pid || current.runtimeId !== this.record.runtimeId ||
+            current.uploadId !== this.record.uploadId || current.remainingBytes !== this.record.remainingBytes) {
+            throw new AttachmentStoreError("invalid_upload");
+        }
+    }
+    async totalRemaining() {
+        let total = 0n;
+        let activeCount = 0;
+        // 流式枚举，不把历史死亡账本的总数当作活跃上传配额。
+        for await (const entry of await opendir(this.directory)) {
+            const name = entry.name;
+            const path = join(this.directory, name);
+            try {
+                assertRegularFile(path);
+                if (PENDING_NAME.test(name))
+                    continue;
+                if (!RECORD_NAME.test(name))
+                    throw new AttachmentStoreError("io_error");
+                const record = parseRecord(await readPrivateFile(path, RECORD_MAX_BYTES), this.allocationUnit);
+                if (provenDead(record.pid))
+                    continue;
+                if (++activeCount > RECORD_MAX_COUNT)
+                    throw new AttachmentStoreError("no_space", true);
+                total += BigInt(record.remainingBytes);
+            }
+            catch (error) {
+                // 删除只发生在该 reservation 已不再可能写入之后。
+                if (!nodeErrorHasCode(error, "ENOENT"))
+                    throw error;
+            }
+        }
+        return total;
+    }
+    async check() {
+        for (let attempt = 0; attempt < CHECK_ATTEMPTS; attempt++) {
+            await this.assertOwned();
+            const remaining = await this.totalRemaining();
+            // 必须先扫描 credits，再读取空间。旧 credits 与新空间只会高估需求。
+            const available = this.hooks.availableBytes ? await this.hooks.availableBytes() : await this.available();
+            if (remaining + this.floor <= available)
+                return;
+            if (attempt + 1 < CHECK_ATTEMPTS)
+                await new Promise((resolve) => setTimeout(resolve, CHECK_RETRY_MS));
+        }
+        throw new AttachmentStoreError("no_space", true);
+    }
+    async available() {
+        const stats = await statfs(this.root, { bigint: true });
+        return stats.bavail * stats.bsize;
+    }
+    async reduce(remainingBytes) {
+        if (!Number.isSafeInteger(remainingBytes) || remainingBytes < 0 || remainingBytes > this.byteLength) {
+            throw new AttachmentStoreError("invalid_upload");
+        }
+        // 已落盘的尾块可承载后续字节，不重复预留同一个分配单元。
+        const credits = roundAllocation(this.byteLength, this.allocationUnit) -
+            roundAllocation(this.byteLength - remainingBytes, this.allocationUnit);
+        if (credits > this.record.remainingBytes)
+            throw new AttachmentStoreError("invalid_upload");
+        const next = { ...this.record, remainingBytes: credits };
+        await this.replace(next, false);
+        this.record.remainingBytes = credits;
+    }
+    async remove() {
+        if (!this.published)
+            return;
+        await this.assertOwned();
+        await unlink(this.path);
+        this.published = false;
+    }
+}
+//# sourceMappingURL=reservations.js.map

package/dist/attachments/reservations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reservations.js","sourceRoot":"","sources":["../../src/attachments/reservations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnI,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAiC,MAAM,YAAY,CAAC;AAEnG,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAC9B,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAC9B,MAAM,cAAc,GAAG,CAAC,CAAC;AACzB,MAAM,cAAc,GAAG,CAAC,CAAC;AACzB,MAAM,IAAI,GAAG,8DAA8D,CAAC;AAC5E,MAAM,WAAW,GAAG,IAAI,MAAM,CAAC,IAAI,IAAI,UAAU,CAAC,CAAC;AACnD,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,IAAI,IAAI,aAAa,CAAC,CAAC;AASvD,SAAS,eAAe,CAAC,KAAa,EAAE,IAAY;IAClD,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC;QAAE,MAAM,IAAI,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAC1F,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,WAAW,CAAC,GAAW,EAAE,IAAY;IAC5C,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAAC,CAAC;IACrF,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QAAE,MAAM,IAAI,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAC1F,MAAM,IAAI,GAAG,IAAkC,CAAC;IAChD,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,uCAAuC;QAC9E,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC;QACvD,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,GAAG;QAC9F,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,GAAG;QAC3F,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;QAC7E,CAAC,IAAI,CAAC,cAAc,IAAI,QAAQ,CAAC,GAAG,eAAe,CAAC,yBAAyB,EAAE,IAAI,CAAC;QACpF,MAAM,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC,GAAG,IAAI,KAAK,EAAE,EAAE,CAAC;QACnD,MAAM,IAAI,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,IAAyB,CAAC;AACnC,CAAC;AAED,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,CAAC;QAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAAC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAAC,OAAO,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAAC,CAAC;IACxF,oCAAoC;IACpC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,OAAO,eAAe;IAQP;IAGA;IACA;IACA;IAZF,SAAS,CAAS;IAClB,IAAI,CAAS;IACb,MAAM,CAAoB;IACnC,SAAS,GAAG,KAAK,CAAC;IAClB,cAAc,GAAG,EAAE,CAAC;IAE5B,YACmB,IAAY,EAC7B,SAAiB,EACjB,QAAgB,EACC,UAAkB,EAClB,KAAa,EACb,QAAkC,EAAE;QALpC,SAAI,GAAJ,IAAI,CAAQ;QAGZ,eAAU,GAAV,UAAU,CAAQ;QAClB,UAAK,GAAL,KAAK,CAAQ;QACb,UAAK,GAAL,KAAK,CAA+B;QAErD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,UAAU,EAAE,OAAO,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC;IACtF,CAAC;IAED,KAAK,CAAC,OAAO;QACX,sBAAsB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,mBAAmB,IAAI,CAAC,CAAC,CAAC,CAAC;YAC7F,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QACpD,IAAI,IAAI,CAAC,cAAc,IAAI,EAAE;YAAE,MAAM,IAAI,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAC1E,IAAI,CAAC,MAAM,CAAC,cAAc,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QAC9F,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC;YAAC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QAAC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YAAC,MAAM,KAAK,CAAC;QAAC,CAAC;IACjF,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,MAAyB,EAAE,OAAgB;QAC/D,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAClC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,UAAU,EAAE,UAAU,CAAC,CAAC;QAChE,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAChD,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;YAC/C,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YACpB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,IAAI,OAAO,EAAE,CAAC;gBACZ,4CAA4C;gBAC5C,MAAM,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;gBACzB,MAAM,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC5C,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBAC7C,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC;oBAAE,MAAM,KAAK,CAAC;YACtD,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,WAAW;QACvB,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;QACtE,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAClC,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QACrG,IAAI,OAAO,CAAC,GAAG,KAAK,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,MAAM,CAAC,SAAS;YAC9E,OAAO,CAAC,QAAQ,KAAK,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,OAAO,CAAC,cAAc,KAAK,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;YACvG,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,cAAc;QAC1B,IAAI,KAAK,GAAG,EAAE,CAAC;QACf,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,4BAA4B;QAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;YACxB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YACxC,IAAI,CAAC;gBACH,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBACxB,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;oBAAE,SAAS;gBACtC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;oBAAE,MAAM,IAAI,oBAAoB,CAAC,UAAU,CAAC,CAAC;gBACxE,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,eAAe,CAAC,IAAI,EAAE,gBAAgB,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;gBAC/F,IAAI,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC;oBAAE,SAAS;gBACrC,IAAI,EAAE,WAAW,GAAG,gBAAgB;oBAAE,MAAM,IAAI,oBAAoB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;gBACvF,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;YACzC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,iCAAiC;gBACjC,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC;oBAAE,MAAM,KAAK,CAAC;YACtD,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,KAAK;QACT,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,cAAc,EAAE,OAAO,EAAE,EAAE,CAAC;YAC1D,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;YACzB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;YAC9C,4CAA4C;YAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;YACzG,IAAI,SAAS,GAAG,IAAI,CAAC,KAAK,IAAI,SAAS;gBAAE,OAAO;YAChD,IAAI,OAAO,GAAG,CAAC,GAAG,cAAc;gBAAE,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;QACxG,CAAC;QACD,MAAM,IAAI,oBAAoB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IACnD,CAAC;IAEO,KAAK,CAAC,SAAS;QACrB,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,OAAO,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,cAAsB;QACjC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC,IAAI,cAAc,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACpG,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;QACnD,CAAC;QACD,8BAA8B;QAC9B,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,cAAc,CAAC;YACnE,eAAe,CAAC,IAAI,CAAC,UAAU,GAAG,cAAc,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QACzE,IAAI,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc;YAAE,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;QAC3F,MAAM,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC;QACzD,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,MAAM,CAAC,cAAc,GAAG,OAAO,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAC5B,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;IACzB,CAAC;CACF"}

package/dist/attachments/safe-files.d.ts

@@ -0,0 +1,17 @@
+import { type Stats } from "node:fs";
+import { type FileHandle } from "node:fs/promises";
+export declare function assertDirectories(directory: string): void;
+export declare function ensurePrivateDirectory(directory: string): void;
+export interface OwnedDirectory {
+    path: string;
+    inode?: number;
+    device?: number;
+}
+/** mkdir 与 identity 获取同步相邻；既有目录绝不成为本次上传的资源。 */
+export declare function createOwnedDirectory(path: string, recordCreated: (directory: OwnedDirectory) => void): OwnedDirectory;
+export declare function assertOwnedDirectory(directory: OwnedDirectory): void;
+/** 只移除仍归本次上传所有的空目录，绝不递归删除或接管替换目录。 */
+export declare function removeOwnedDirectory(directory: OwnedDirectory): void;
+export declare function assertRegularFile(path: string): Stats;
+export declare function createPrivateFile(path: string): Promise<FileHandle>;
+export declare function readPrivateFile(path: string, maximumBytes: number): Promise<string>;

package/dist/attachments/safe-files.js

@@ -0,0 +1,108 @@
+import { constants, chmodSync, lstatSync, mkdirSync, rmdirSync } from "node:fs";
+import { open } from "node:fs/promises";
+import { dirname, parse, resolve, sep } from "node:path";
+import { AttachmentStoreError, nodeErrorHasCode } from "./types.js";
+export function assertDirectories(directory) {
+    const absolute = resolve(directory);
+    let current = parse(absolute).root;
+    for (const part of absolute.slice(current.length).split(sep).filter(Boolean)) {
+        current = resolve(current, part);
+        const stat = lstatSync(current);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new AttachmentStoreError("invalid_upload");
+    }
+}
+export function ensurePrivateDirectory(directory) {
+    const absolute = resolve(directory);
+    let current = parse(absolute).root;
+    for (const part of absolute.slice(current.length).split(sep).filter(Boolean)) {
+        current = resolve(current, part);
+        try {
+            mkdirSync(current, { mode: 0o700 });
+        }
+        catch (error) {
+            if (!nodeErrorHasCode(error, "EEXIST"))
+                throw error;
+        }
+        const stat = lstatSync(current);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new AttachmentStoreError("invalid_upload");
+    }
+    chmodSync(absolute, 0o700);
+}
+/** mkdir 与 identity 获取同步相邻；既有目录绝不成为本次上传的资源。 */
+export function createOwnedDirectory(path, recordCreated) {
+    assertDirectories(dirname(path));
+    try {
+        mkdirSync(path, { mode: 0o700 });
+    }
+    catch (error) {
+        if (nodeErrorHasCode(error, "EEXIST"))
+            throw new AttachmentStoreError("invalid_upload");
+        throw error;
+    }
+    // mkdir 成功即转移资源，identity 获取失败也不得让有界账本漏掉已创建目录。
+    const directory = { path };
+    recordCreated(directory);
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new AttachmentStoreError("invalid_upload");
+    directory.inode = stat.ino;
+    directory.device = stat.dev;
+    return directory;
+}
+export function assertOwnedDirectory(directory) {
+    // 缺失创建时证据不能靠后续 stat 补齐，也不能因路径消失就提交成功清理。
+    if (directory.inode === undefined || directory.device === undefined)
+        throw new AttachmentStoreError("invalid_upload");
+    assertDirectories(dirname(directory.path));
+    const stat = lstatSync(directory.path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.ino !== directory.inode || stat.dev !== directory.device) {
+        throw new AttachmentStoreError("invalid_upload");
+    }
+}
+/** 只移除仍归本次上传所有的空目录，绝不递归删除或接管替换目录。 */
+export function removeOwnedDirectory(directory) {
+    try {
+        assertOwnedDirectory(directory);
+        rmdirSync(directory.path);
+    }
+    catch (error) {
+        if (!nodeErrorHasCode(error, "ENOENT"))
+            throw error;
+    }
+}
+export function assertRegularFile(path) {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new AttachmentStoreError("invalid_upload");
+    return stat;
+}
+export async function createPrivateFile(path) {
+    return open(path, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+}
+export async function readPrivateFile(path, maximumBytes) {
+    assertRegularFile(path);
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > maximumBytes)
+            throw new AttachmentStoreError("io_error");
+        // 限长读取，不能在 stat 后使用无界 readFile。
+        const buffer = Buffer.alloc(maximumBytes + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const read = await handle.read(buffer, length, buffer.length - length, length);
+            if (read.bytesRead === 0)
+                break;
+            length += read.bytesRead;
+        }
+        if (length > maximumBytes)
+            throw new AttachmentStoreError("io_error");
+        return buffer.subarray(0, length).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+//# sourceMappingURL=safe-files.js.map

package/dist/attachments/safe-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-files.js","sourceRoot":"","sources":["../../src/attachments/safe-files.ts"],"names":[],"mappings":"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"}

package/dist/attachments/storage-path.d.ts

@@ -0,0 +1,4 @@
+export declare function localDateDirectory(date: Date): string;
+export declare function safeAttachmentFileName(original: string): string;
+/** attachmentId 只来自服务端 randomUUID，不接受客户端提供的目录组件。 */
+export declare function attachmentStoragePath(root: string, attachmentId: string, originalName: string, date: Date): string;

package/dist/attachments/storage-path.js

@@ -0,0 +1,47 @@
+import { join } from "node:path";
+// 为不同文件系统的单组件限制留余量；按 UTF-8 字节计算而非 JS 字符数。
+const MAX_FILE_NAME_BYTES = 240;
+const FALLBACK_FILE_NAME = "attachment";
+const WINDOWS_DEVICE_NAME = /^(?:CON|PRN|AUX|NUL|COM[1-9¹²³]|LPT[1-9¹²³]|CONIN\$|CONOUT\$)(?:\.|$)/iu;
+export function localDateDirectory(date) {
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+function truncateUtf8(value, maximumBytes) {
+    let bytes = 0;
+    let result = "";
+    for (const codepoint of value) {
+        const length = Buffer.byteLength(codepoint, "utf8");
+        if (bytes + length > maximumBytes)
+            break;
+        result += codepoint;
+        bytes += length;
+    }
+    return result;
+}
+function normalizeName(name) {
+    if (name === "" || name === "." || name === "..")
+        return FALLBACK_FILE_NAME;
+    const safe = name.replace(/[ .]+$/u, "_");
+    return WINDOWS_DEVICE_NAME.test(safe.trimStart()) ? `_${safe}` : safe;
+}
+export function safeAttachmentFileName(original) {
+    let name = normalizeName(original.replace(/[<>:"/\\|?*\p{Cc}\p{Cf}]/gu, "_"));
+    if (Buffer.byteLength(name, "utf8") <= MAX_FILE_NAME_BYTES)
+        return name;
+    const extensionStart = name.lastIndexOf(".");
+    if (extensionStart <= 0)
+        name = truncateUtf8(name, MAX_FILE_NAME_BYTES);
+    else {
+        // 至少给主名留一个完整 codepoint；异常超长扩展也必须受同一字节上限约束。
+        const extension = truncateUtf8(name.slice(extensionStart), MAX_FILE_NAME_BYTES - 4);
+        const stem = truncateUtf8(name.slice(0, extensionStart), MAX_FILE_NAME_BYTES - Buffer.byteLength(extension));
+        name = `${stem}${extension}`;
+    }
+    // 截断可能新产生设备名或尾部空格；重新归一化后仍须守住字节上限。
+    return truncateUtf8(normalizeName(name), MAX_FILE_NAME_BYTES).replace(/[ .]+$/u, "_");
+}
+/** attachmentId 只来自服务端 randomUUID，不接受客户端提供的目录组件。 */
+export function attachmentStoragePath(root, attachmentId, originalName, date) {
+    return join(root, localDateDirectory(date), attachmentId, safeAttachmentFileName(originalName));
+}
+//# sourceMappingURL=storage-path.js.map

package/dist/attachments/storage-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-path.js","sourceRoot":"","sources":["../../src/attachments/storage-path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,0CAA0C;AAC1C,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAChC,MAAM,kBAAkB,GAAG,YAAY,CAAC;AACxC,MAAM,mBAAmB,GAAG,yEAAyE,CAAC;AAEtG,MAAM,UAAU,kBAAkB,CAAC,IAAU;IAC3C,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AAC5H,CAAC;AAED,SAAS,YAAY,CAAC,KAAa,EAAE,YAAoB;IACvD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,SAAS,IAAI,KAAK,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACpD,IAAI,KAAK,GAAG,MAAM,GAAG,YAAY;YAAE,MAAM;QACzC,MAAM,IAAI,SAAS,CAAC;QACpB,KAAK,IAAI,MAAM,CAAC;IAClB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,kBAAkB,CAAC;IAC5E,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC1C,OAAO,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,IAAI,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,4BAA4B,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9E,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,mBAAmB;QAAE,OAAO,IAAI,CAAC;IAExE,MAAM,cAAc,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC7C,IAAI,cAAc,IAAI,CAAC;QAAE,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;SACnE,CAAC;QACJ,2CAA2C;QAC3C,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,mBAAmB,GAAG,CAAC,CAAC,CAAC;QACpF,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;QAC7G,IAAI,GAAG,GAAG,IAAI,GAAG,SAAS,EAAE,CAAC;IAC/B,CAAC;IACD,kCAAkC;IAClC,OAAO,YAAY,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;AACxF,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,YAAoB,EAAE,YAAoB,EAAE,IAAU;IACxG,OAAO,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,sBAAsB,CAAC,YAAY,CAAC,CAAC,CAAC;AAClG,CAAC"}

package/dist/attachments/store.d.ts

@@ -0,0 +1,55 @@
+import { type AttachmentDescriptor } from "../vendor/protocol/session/index.js";
+import { type AttachmentBeginInput, type AttachmentScope, type AttachmentStoreOptions, type AttachmentUploadState } from "./types.js";
+export { AttachmentStoreError } from "./types.js";
+export type { AttachmentBeginInput, AttachmentScope, AttachmentStoreOptions, AttachmentStoreTestHooks, AttachmentUploadState, } from "./types.js";
+export declare class AttachmentStore {
+    private readonly options;
+    private readonly root;
+    private readonly floor;
+    private uploads;
+    private byAttachment;
+    private readonly resources;
+    private readonly metadataLimit;
+    private readonly ownerPending;
+    private readonly cleanups;
+    private sessionId?;
+    private lease?;
+    private disposed;
+    private disposing?;
+    constructor(options: AttachmentStoreOptions);
+    scopeFor(sessionId: string): string;
+    resetScope(sessionId: string): void;
+    private validScope;
+    private checkScope;
+    private key;
+    private newUpload;
+    private checkMetadataBudget;
+    /** 仅测试观察数量，不包含路径、元信息或原始错误。 */
+    debugCounts(): {
+        records: number;
+        attachments: number;
+        resources: number;
+        cleanups: number;
+        pending: number;
+    };
+    private state;
+    private enqueue;
+    private get;
+    private assertFile;
+    private checkedState;
+    begin(scope: AttachmentScope, input: AttachmentBeginInput): Promise<AttachmentUploadState>;
+    write(scope: AttachmentScope, uploadId: string, offset: number, bytes: Uint8Array): Promise<AttachmentUploadState>;
+    private compareChunk;
+    finish(scope: AttachmentScope, uploadId: string): Promise<AttachmentUploadState>;
+    status(scope: AttachmentScope, uploadId: string): Promise<AttachmentUploadState>;
+    cancel(scope: AttachmentScope, uploadId: string): Promise<AttachmentUploadState>;
+    discard(scope: AttachmentScope, attachmentId: string): Promise<"cancelled" | "retained">;
+    resolve(scope: AttachmentScope, attachmentIds: readonly string[]): ReadonlyArray<{
+        descriptor: AttachmentDescriptor;
+        path: string;
+    }>;
+    retain(scope: AttachmentScope, attachmentIds: readonly string[]): void;
+    private cleanup;
+    private scheduleCleanup;
+    dispose(): Promise<void>;
+}