knodin 0.7.5 → 0.8.2

package/dist/src/diagnostics-write-helper.js

@@ -0,0 +1,473 @@
+import fs from "node:fs";
+import path from "node:path";
+const VERSION = 1;
+const [expectedDevRaw, expectedInoRaw, relativeTarget, mode, maxBytesRaw, bytesRaw, nonce, maxAgeRaw = "0", testFixtures = "", componentSwapPath = "", deleteSwapPath = "",] = process.argv.slice(2);
+const expectedDev = Number(expectedDevRaw);
+const expectedIno = Number(expectedInoRaw);
+const maxBytes = Number(maxBytesRaw);
+const bytes = Number(bytesRaw);
+const maxAgeMs = Number(maxAgeRaw);
+function emitPipe(value) {
+    const message = Buffer.from(`${JSON.stringify(value)}\n`);
+    let offset = 0;
+    while (offset < message.byteLength) {
+        try {
+            offset += fs.writeSync(1, message, offset, message.byteLength - offset);
+        }
+        catch (error) {
+            if (error.code !== "EAGAIN")
+                throw error;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2);
+        }
+    }
+}
+function cwdIdentity(requiredDev = expectedDev, requiredIno = expectedIno) {
+    const descriptor = fs.openSync(".", fs.constants.O_RDONLY);
+    let observed;
+    try {
+        observed = fs.fstatSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    if (observed.dev !== requiredDev || observed.ino !== requiredIno)
+        throw new Error("destination parent identity mismatch");
+    return observed;
+}
+try {
+    if (!Number.isSafeInteger(expectedDev) ||
+        !Number.isSafeInteger(expectedIno) ||
+        !Number.isSafeInteger(maxBytes) ||
+        !Number.isSafeInteger(bytes) ||
+        !Number.isSafeInteger(maxAgeMs) ||
+        maxAgeMs < 0 ||
+        bytes < 0 ||
+        bytes > maxBytes ||
+        !(mode === "create" ||
+            mode === "replace" ||
+            mode === "append" ||
+            mode === "delete" ||
+            mode === "read") ||
+        !relativeTarget ||
+        path.isAbsolute(relativeTarget) ||
+        relativeTarget
+            .split(/[\\/]/)
+            .some((segment) => !segment || segment === "." || segment === "..") ||
+        !nonce ||
+        !/^[a-f0-9]{32}$/.test(nonce))
+        throw new Error("invalid helper arguments");
+    const allowFaultFixtures = testFixtures === "enabled";
+    if (allowFaultFixtures && process.env.KNODIN_DIAGNOSTICS_TEST_SWAP_TO) {
+        const boundPath = process.cwd();
+        const displaced = `${boundPath}-displaced`;
+        fs.renameSync(boundPath, displaced);
+        fs.symlinkSync(process.env.KNODIN_DIAGNOSTICS_TEST_SWAP_TO, boundPath);
+    }
+    if (allowFaultFixtures && process.env.KNODIN_DIAGNOSTICS_TEST_HELPER_FAULT === "crash")
+        process.exit(91);
+    const rootIdentity = cwdIdentity();
+    const rootPath = fs.realpathSync(".");
+    const segments = relativeTarget.split(/[\\/]/);
+    const basename = segments.pop();
+    if (!basename)
+        throw new Error("invalid helper target");
+    let boundIdentity = rootIdentity;
+    for (const segment of segments) {
+        cwdIdentity(boundIdentity.dev, boundIdentity.ino);
+        let created = false;
+        try {
+            fs.mkdirSync(segment, { mode: 0o700 });
+            created = true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        if (created && allowFaultFixtures && componentSwapPath) {
+            fs.renameSync(segment, `${segment}-displaced`);
+            fs.symlinkSync(componentSwapPath, segment);
+        }
+        const child = fs.lstatSync(segment);
+        if (child.isSymbolicLink() || !child.isDirectory())
+            throw new Error("destination component is not a private directory");
+        process.chdir(segment);
+        const bound = fs.statSync(".");
+        if (bound.dev !== child.dev || bound.ino !== child.ino)
+            throw new Error("destination component identity mismatch");
+        boundIdentity = bound;
+        const resolved = fs.realpathSync(".");
+        if (resolved !== rootPath && !resolved.startsWith(`${rootPath}${path.sep}`))
+            throw new Error("destination ancestry escaped repository root");
+    }
+    const identity = cwdIdentity(boundIdentity.dev, boundIdentity.ino);
+    const boundParentPath = fs.realpathSync(".");
+    if (allowFaultFixtures && process.env.KNODIN_DIAGNOSTICS_TEST_HELPER_FAULT === "protocol") {
+        emitPipe({ version: 999, type: "READY", nonce });
+        process.exit(92);
+    }
+    const readyMessage = {
+        version: VERSION,
+        type: "READY",
+        rootDev: rootIdentity.dev,
+        rootIno: rootIdentity.ino,
+        dev: identity.dev,
+        ino: identity.ino,
+        nonce,
+    };
+    emitPipe(readyMessage);
+    if (mode !== "append" &&
+        allowFaultFixtures &&
+        process.env.KNODIN_DIAGNOSTICS_TEST_POST_READY_ROOT_SWAP_TO) {
+        fs.renameSync(rootPath, `${rootPath}-displaced`);
+        fs.symlinkSync(process.env.KNODIN_DIAGNOSTICS_TEST_POST_READY_ROOT_SWAP_TO, rootPath);
+        const forgedParent = path.join(rootPath, ...relativeTarget.split(/[\\/]/).slice(0, -1));
+        fs.mkdirSync(forgedParent, { recursive: true });
+        fs.writeFileSync(path.join(forgedParent, `.knodin-write-${nonce}.receipt`), "forged\n");
+    }
+    if (mode !== "append" &&
+        allowFaultFixtures &&
+        process.env.KNODIN_DIAGNOSTICS_TEST_POST_READY_PARENT_SWAP_TO) {
+        const boundPath = process.cwd();
+        fs.renameSync(boundPath, `${boundPath}-displaced`);
+        fs.symlinkSync(process.env.KNODIN_DIAGNOSTICS_TEST_POST_READY_PARENT_SWAP_TO, boundPath);
+        fs.writeFileSync(path.join(boundPath, `.knodin-write-${nonce}.receipt`), `${JSON.stringify({ version: VERSION, type: "RECEIPT", dev: identity.dev, ino: identity.ino, nonce, bytes, targetDev: identity.dev, targetIno: identity.ino, data: "" })}\n`);
+    }
+    const commit = (payload, sequence) => {
+        if (mode === "append" &&
+            sequence === 2 &&
+            allowFaultFixtures &&
+            process.env.KNODIN_DIAGNOSTICS_TEST_APPEND_PARENT_SWAP_TO) {
+            const boundPath = process.cwd();
+            fs.renameSync(boundPath, `${boundPath}-displaced`);
+            fs.symlinkSync(process.env.KNODIN_DIAGNOSTICS_TEST_APPEND_PARENT_SWAP_TO, boundPath);
+            fs.writeFileSync(path.join(boundPath, `.knodin-write-${nonce}.${sequence}.receipt`), `${JSON.stringify({ version: VERSION, type: "RECEIPT", dev: identity.dev, ino: identity.ino, nonce, sequence, bytes: payload.byteLength })}\n`);
+        }
+        cwdIdentity(identity.dev, identity.ino);
+        const writeParent = fs.realpathSync(".");
+        if (writeParent !== boundParentPath)
+            throw new Error("destination parent path changed before write");
+        if (mode === "read") {
+            const descriptor = fs.openSync(basename, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+            try {
+                const opened = fs.fstatSync(descriptor);
+                if (!opened.isFile() || opened.nlink !== 1 || opened.size > maxBytes) {
+                    const limit = maxBytes >= 1024 * 1024 ? `${maxBytes / (1024 * 1024)} MiB` : `${maxBytes} byte`;
+                    throw new Error(`read target exceeds its ${limit} safety limit`);
+                }
+                const content = fs.readFileSync(descriptor);
+                const final = fs.fstatSync(descriptor);
+                const current = fs.lstatSync(basename);
+                if (final.nlink !== 1 ||
+                    current.isSymbolicLink() ||
+                    current.nlink !== 1 ||
+                    current.dev !== final.dev ||
+                    current.ino !== final.ino)
+                    throw new Error("read target identity changed during use");
+                cwdIdentity(identity.dev, identity.ino);
+                if (fs.realpathSync(".") !== boundParentPath)
+                    throw new Error("destination parent path changed during read");
+                emitPipe({
+                    version: VERSION,
+                    type: "RECEIPT",
+                    dev: identity.dev,
+                    ino: identity.ino,
+                    nonce,
+                    bytes: content.byteLength,
+                    targetDev: final.dev,
+                    targetIno: final.ino,
+                    data: content.toString("base64"),
+                });
+            }
+            finally {
+                fs.closeSync(descriptor);
+            }
+            return;
+        }
+        if (mode === "delete") {
+            const expected = JSON.parse(payload.toString("utf8"));
+            if (!Number.isSafeInteger(expected.dev) || !Number.isSafeInteger(expected.ino))
+                throw new Error("invalid delete identity");
+            if (allowFaultFixtures && deleteSwapPath) {
+                const boundPath = process.cwd();
+                fs.renameSync(boundPath, `${boundPath}-displaced`);
+                fs.symlinkSync(deleteSwapPath, boundPath);
+            }
+            cwdIdentity(identity.dev, identity.ino);
+            const deleteParent = fs.realpathSync(".");
+            if (deleteParent !== rootPath && !deleteParent.startsWith(`${rootPath}${path.sep}`))
+                throw new Error("delete parent escaped repository root");
+            if (allowFaultFixtures &&
+                typeof expected.token === "string" &&
+                process.env.KNODIN_DIAGNOSTICS_TEST_LOCK_SUCCESSOR === "1") {
+                fs.renameSync(basename, `${basename}.fixture-original`);
+                const successor = `${JSON.stringify({ token: "f".repeat(32), acquiredAt: new Date().toISOString() })}\n`;
+                if (expected.kind === "directory") {
+                    fs.mkdirSync(basename, { mode: 0o700 });
+                    fs.writeFileSync(path.join(basename, "owner.json"), successor, {
+                        flag: "wx",
+                        mode: 0o600,
+                    });
+                }
+                else
+                    fs.writeFileSync(basename, successor, { flag: "wx", mode: 0o600 });
+            }
+            const tombstone = `.${basename}.${process.pid}.${nonce}.delete`;
+            fs.renameSync(basename, tombstone);
+            const restoreWithoutClobber = () => {
+                if (expected.kind === "directory") {
+                    try {
+                        fs.mkdirSync(basename, { mode: 0o700 });
+                    }
+                    catch (error) {
+                        if (error.code !== "EEXIST")
+                            throw error;
+                    }
+                    return;
+                }
+                try {
+                    fs.linkSync(tombstone, basename);
+                    fs.unlinkSync(tombstone);
+                }
+                catch (error) {
+                    if (error.code !== "EEXIST")
+                        throw error;
+                }
+            };
+            const directoryTarget = expected.kind === "directory";
+            const descriptor = fs.openSync(tombstone, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+            let opened;
+            let content = "";
+            try {
+                opened = fs.fstatSync(descriptor);
+                if ((directoryTarget ? !opened.isDirectory() : !opened.isFile() || opened.nlink !== 1) ||
+                    opened.dev !== expected.dev ||
+                    opened.ino !== expected.ino) {
+                    restoreWithoutClobber();
+                    throw new Error("delete target identity mismatch");
+                }
+                if (typeof expected.token === "string" && !directoryTarget)
+                    content = fs.readFileSync(descriptor, "utf8");
+            }
+            finally {
+                fs.closeSync(descriptor);
+            }
+            if (typeof expected.token === "string") {
+                if (directoryTarget) {
+                    const ownerDescriptor = fs.openSync(path.join(tombstone, "owner.json"), fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+                    try {
+                        const ownerStats = fs.fstatSync(ownerDescriptor);
+                        if (!ownerStats.isFile() || ownerStats.nlink !== 1)
+                            throw new Error("legacy lock owner is unsafe");
+                        content = fs.readFileSync(ownerDescriptor, "utf8");
+                    }
+                    finally {
+                        fs.closeSync(ownerDescriptor);
+                    }
+                }
+                const owner = JSON.parse(content);
+                if (owner.token !== expected.token) {
+                    restoreWithoutClobber();
+                    throw new Error("delete owner token mismatch");
+                }
+            }
+            const current = fs.lstatSync(tombstone);
+            if (current.dev !== opened.dev ||
+                current.ino !== opened.ino ||
+                (!directoryTarget && current.nlink !== 1))
+                throw new Error("delete target changed before unlink");
+            if (directoryTarget) {
+                fs.unlinkSync(path.join(tombstone, "owner.json"));
+                fs.rmdirSync(tombstone);
+            }
+            else
+                fs.unlinkSync(tombstone);
+            const directory = fs.openSync(".", fs.constants.O_RDONLY);
+            try {
+                fs.fsyncSync(directory);
+            }
+            finally {
+                fs.closeSync(directory);
+            }
+            emitPipe({
+                version: VERSION,
+                type: "RECEIPT",
+                dev: identity.dev,
+                ino: identity.ino,
+                nonce,
+                bytes: payload.byteLength,
+                deletedBytes: opened.size,
+            });
+            return;
+        }
+        const temporary = `.${basename}.${process.pid}.${nonce}.tmp`;
+        let target = basename;
+        if (mode === "replace")
+            target = temporary;
+        let existing = Buffer.alloc(0);
+        let rotate = false;
+        if (mode === "append") {
+            try {
+                const current = fs.lstatSync(basename);
+                if (current.isSymbolicLink() || !current.isFile() || current.nlink !== 1)
+                    throw new Error("append target is not a regular file");
+                rotate =
+                    current.size + payload.byteLength > maxBytes ||
+                        (maxAgeMs > 0 && Date.now() - current.mtimeMs > maxAgeMs);
+                const source = fs.openSync(basename, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+                try {
+                    const opened = fs.fstatSync(source);
+                    if (!opened.isFile() ||
+                        opened.nlink !== 1 ||
+                        opened.dev !== current.dev ||
+                        opened.ino !== current.ino)
+                        throw new Error("append target identity changed before read");
+                    existing = fs.readFileSync(source);
+                    if (fs.fstatSync(source).nlink !== 1)
+                        throw new Error("append target acquired an external link");
+                }
+                finally {
+                    fs.closeSync(source);
+                }
+                if (sequence === 2 &&
+                    allowFaultFixtures &&
+                    process.env.KNODIN_DIAGNOSTICS_TEST_APPEND_HARDLINK_TO)
+                    fs.linkSync(basename, process.env.KNODIN_DIAGNOSTICS_TEST_APPEND_HARDLINK_TO);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        if (mode === "append")
+            target = temporary;
+        let written;
+        const descriptor = fs.openSync(target, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW, 0o600);
+        try {
+            const opened = fs.fstatSync(descriptor);
+            written = opened;
+            if (!opened.isFile() || opened.nlink !== 1)
+                throw new Error("opened target is not a private regular file");
+            if (mode === "append" && !rotate)
+                fs.writeFileSync(descriptor, existing);
+            fs.writeFileSync(descriptor, payload);
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        try {
+            cwdIdentity(identity.dev, identity.ino);
+            if (fs.realpathSync(".") !== boundParentPath)
+                throw new Error("destination parent path changed before publish");
+            if (mode === "replace" || mode === "append") {
+                if (mode === "append" && rotate) {
+                    const previousTemporary = `.${basename}.1.${process.pid}.${nonce}.tmp`;
+                    fs.writeFileSync(previousTemporary, existing, { flag: "wx", mode: 0o600 });
+                    fs.renameSync(previousTemporary, `${basename}.1`);
+                }
+                fs.renameSync(temporary, basename);
+            }
+            if (allowFaultFixtures && process.env.KNODIN_DIAGNOSTICS_TEST_POST_PUBLISH_TARGET_SWAP_TO) {
+                fs.renameSync(basename, `${basename}.fixture-published`);
+                fs.symlinkSync(process.env.KNODIN_DIAGNOSTICS_TEST_POST_PUBLISH_TARGET_SWAP_TO, basename);
+            }
+            const current = fs.lstatSync(basename);
+            if (!written ||
+                current.isSymbolicLink() ||
+                !current.isFile() ||
+                current.nlink !== 1 ||
+                current.dev !== written.dev ||
+                current.ino !== written.ino ||
+                (mode !== "append" && current.size !== payload.byteLength))
+                throw new Error("write receipt mismatch");
+            const directory = fs.openSync(".", fs.constants.O_RDONLY);
+            try {
+                fs.fsyncSync(directory);
+            }
+            finally {
+                fs.closeSync(directory);
+            }
+            const message = {
+                version: VERSION,
+                type: "RECEIPT",
+                dev: identity.dev,
+                ino: identity.ino,
+                nonce,
+                bytes: payload.byteLength,
+                targetDev: current.dev,
+                targetIno: current.ino,
+                sequence,
+            };
+            emitPipe(message);
+        }
+        catch (error) {
+            try {
+                if (mode === "replace" || mode === "append")
+                    fs.unlinkSync(temporary);
+                else if (mode === "create")
+                    fs.unlinkSync(basename);
+            }
+            catch { }
+            throw error;
+        }
+    };
+    if (mode === "append") {
+        let pending = Buffer.alloc(0);
+        let idle;
+        await new Promise((resolve, reject) => {
+            const armIdle = () => {
+                if (idle)
+                    clearTimeout(idle);
+                idle = setTimeout(resolve, 500);
+            };
+            process.stdin.on("data", (chunk) => {
+                try {
+                    pending = Buffer.concat([pending, chunk]);
+                    while (pending.byteLength >= 8) {
+                        const sequence = pending.readUInt32BE(0);
+                        const length = pending.readUInt32BE(4);
+                        if (length > maxBytes)
+                            throw new Error("payload exceeds declared bound");
+                        if (pending.byteLength < 8 + length)
+                            break;
+                        commit(pending.subarray(8, 8 + length), sequence);
+                        pending = pending.subarray(8 + length);
+                    }
+                    armIdle();
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            process.stdin.once("end", resolve);
+            armIdle();
+        });
+    }
+    else {
+        const chunks = [];
+        let total = 0;
+        while (total < bytes) {
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, Math.max(1, bytes - total)));
+            const count = fs.readSync(0, chunk, 0, chunk.length, null);
+            if (count === 0)
+                throw new Error("payload ended early");
+            total += count;
+            if (total > bytes || total > maxBytes)
+                throw new Error("payload exceeds declared bound");
+            chunks.push(chunk.subarray(0, count));
+        }
+        commit(Buffer.concat(chunks, total));
+    }
+}
+catch (error) {
+    try {
+        fs.writeSync(1, `${JSON.stringify({
+            version: VERSION,
+            type: "ERROR",
+            nonce,
+            message: error instanceof Error ? error.message : "helper failed",
+        })}\n`);
+    }
+    catch { }
+    process.exitCode = 1;
+}