@botlearn-course/daemon 0.0.20-beta.8 → 0.0.20

package/dist/workspace-restore.js

@@ -1,347 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statfsSync, unlinkSync, writeFileSync, } from "node:fs";
-import path from "node:path";
-import { validateWorkspaceEntrySet, } from "./workspace-entry-set.js";
-import { WORKSPACE_MATERIALIZATION_SCHEMA, writeWorkspaceMaterializationMarker, } from "./workspace-materialization.js";
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-const SHA256 = /^[0-9a-f]{64}$/;
-const RESTORE_JOURNAL_SCHEMA = "agent-workspace-restore-journal/1";
-const COPY_CHUNK_BYTES = 64 * 1024;
-export class WorkspaceRestoreError extends Error {
-    code;
-    retryable;
-    constructor(code, retryable = false) {
-        super(code);
-        this.code = code;
-        this.retryable = retryable;
-        this.name = "WorkspaceRestoreError";
-    }
-}
-function fail(code) {
-    throw new WorkspaceRestoreError(code, code === "workspace_restore_unavailable" ||
-        code === "workspace_restore_disk_pressure" ||
-        code === "workspace_restore_inode_pressure");
-}
-function assertUuid(value, label) {
-    if (!UUID.test(value))
-        fail(`workspace_restore_${label}_invalid`);
-}
-function hasExactKeys(value, expected) {
-    const actual = Object.keys(value).sort();
-    const sortedExpected = [...expected].sort();
-    return actual.length === sortedExpected.length &&
-        actual.every((key, index) => key === sortedExpected[index]);
-}
-function containsPath(parent, candidate) {
-    const relative = path.relative(parent, candidate);
-    return relative === "" || (!relative.startsWith(".." + path.sep) && relative !== "..");
-}
-function validJournalSwapName(value, prefix) {
-    return typeof value === "string" && value.startsWith(prefix) &&
-        UUID.test(value.slice(prefix.length));
-}
-function assertControlPath(workspaceDirectory, controlDirectory) {
-    if (containsPath(path.resolve(workspaceDirectory), path.resolve(controlDirectory))) {
-        fail("workspace_restore_control_path_invalid");
-    }
-}
-function assertDescriptor(descriptor) {
-    assertUuid(descriptor.sandboxId, "sandbox_id");
-    assertUuid(descriptor.runtimeSessionId, "session_id");
-    if (!Number.isSafeInteger(descriptor.sandboxGeneration) ||
-        descriptor.sandboxGeneration < 1 ||
-        !Number.isSafeInteger(descriptor.revision) ||
-        descriptor.revision < 0 ||
-        !Number.isSafeInteger(descriptor.expectedFileCount) ||
-        descriptor.expectedFileCount < 0 ||
-        !Number.isSafeInteger(descriptor.expectedEntryCount) ||
-        descriptor.expectedEntryCount < 0 ||
-        !Number.isSafeInteger(descriptor.expectedTotalBytes) ||
-        descriptor.expectedTotalBytes < 0 ||
-        (descriptor.continuityState !== "healthy" && descriptor.continuityState !== "degraded") ||
-        (descriptor.continuityState === "degraded" && !descriptor.continuityErrorCode) ||
-        (descriptor.continuityState === "healthy" && descriptor.continuityErrorCode !== null))
-        fail("workspace_restore_descriptor_invalid");
-    const revisionZero = descriptor.revision === 0;
-    if (revisionZero !== (descriptor.snapshotId === null) ||
-        revisionZero !== (descriptor.contentSha256 === null) ||
-        (!revisionZero &&
-            (!UUID.test(descriptor.snapshotId) || !SHA256.test(descriptor.contentSha256))) ||
-        (revisionZero &&
-            (descriptor.expectedFileCount !== 0 || descriptor.expectedEntryCount !== 0 ||
-                descriptor.expectedTotalBytes !== 0)))
-        fail("workspace_restore_descriptor_invalid");
-}
-export function workspaceRestoreJournalPath(controlDirectory, runtimeSessionId) {
-    assertUuid(runtimeSessionId, "session_id");
-    return path.join(controlDirectory, "workspace-restore-journals", `${runtimeSessionId}.json`);
-}
-function writeJournal(file, journal) {
-    const directory = path.dirname(file);
-    mkdirSync(directory, { recursive: true, mode: 0o700 });
-    chmodSync(directory, 0o700);
-    const staging = `${file}.tmp-${process.pid}-${randomUUID()}`;
-    try {
-        writeFileSync(staging, JSON.stringify(journal), { encoding: "utf8", mode: 0o600 });
-        const handle = openSync(staging, constants.O_RDONLY | constants.O_NOFOLLOW);
-        try {
-            fsyncSync(handle);
-        }
-        finally {
-            closeSync(handle);
-        }
-        renameSync(staging, file);
-        fsyncDirectory(directory);
-    }
-    catch (error) {
-        try {
-            unlinkSync(staging);
-        }
-        catch {
-            // The atomic staging file may not have been created.
-        }
-        throw error;
-    }
-}
-function parseJournal(raw, descriptor) {
-    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-        fail("workspace_restore_journal_invalid");
-    }
-    const value = raw;
-    if (!hasExactKeys(value, [
-        "schemaVersion",
-        "sandboxId",
-        "sandboxGeneration",
-        "runtimeSessionId",
-        "stagingName",
-        "backupName",
-        "hadWorkspace",
-        "phase",
-        "marker",
-    ]))
-        fail("workspace_restore_journal_invalid");
-    const namePrefix = `.botlearn-restore-${descriptor.runtimeSessionId}-`;
-    const backupPrefix = `.botlearn-backup-${descriptor.runtimeSessionId}-`;
-    if (value.schemaVersion !== RESTORE_JOURNAL_SCHEMA ||
-        value.sandboxId !== descriptor.sandboxId ||
-        value.sandboxGeneration !== descriptor.sandboxGeneration ||
-        value.runtimeSessionId !== descriptor.runtimeSessionId ||
-        !validJournalSwapName(value.stagingName, namePrefix) ||
-        !validJournalSwapName(value.backupName, backupPrefix) ||
-        typeof value.hadWorkspace !== "boolean" ||
-        !["prepared", "old_moved", "new_moved"].includes(String(value.phase)))
-        fail("workspace_restore_journal_invalid");
-    const marker = value.marker;
-    if (!marker || marker.schemaVersion !== WORKSPACE_MATERIALIZATION_SCHEMA ||
-        marker.sandboxId !== descriptor.sandboxId ||
-        marker.sandboxGeneration !== descriptor.sandboxGeneration ||
-        marker.runtimeSessionId !== descriptor.runtimeSessionId ||
-        marker.workspaceContinuityState !== descriptor.continuityState ||
-        marker.snapshotId !== descriptor.snapshotId || marker.revision !== descriptor.revision ||
-        marker.contentSha256 !== descriptor.contentSha256)
-        fail("workspace_restore_journal_invalid");
-    return value;
-}
-function fsyncDirectory(directory) {
-    const handle = openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
-    try {
-        fsyncSync(handle);
-    }
-    finally {
-        closeSync(handle);
-    }
-}
-function verifyDownloadedFile(file, expected) {
-    const handle = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
-    try {
-        const stats = fstatSync(handle, { bigint: true });
-        if (!stats.isFile() || stats.nlink !== 1n || stats.size !== BigInt(expected.expectedSize)) {
-            fail("workspace_restore_integrity_failed");
-        }
-        const hash = createHash("sha256");
-        const buffer = Buffer.allocUnsafe(COPY_CHUNK_BYTES);
-        let total = 0;
-        while (true) {
-            const bytesRead = readSync(handle, buffer, 0, buffer.length, null);
-            if (bytesRead === 0)
-                break;
-            total += bytesRead;
-            hash.update(buffer.subarray(0, bytesRead));
-        }
-        if (total !== expected.expectedSize || hash.digest("hex") !== expected.expectedSha256) {
-            fail("workspace_restore_integrity_failed");
-        }
-        fsyncSync(handle);
-    }
-    finally {
-        closeSync(handle);
-    }
-}
-function markerFromDescriptor(descriptor) {
-    return {
-        schemaVersion: WORKSPACE_MATERIALIZATION_SCHEMA,
-        sandboxId: descriptor.sandboxId,
-        sandboxGeneration: descriptor.sandboxGeneration,
-        runtimeSessionId: descriptor.runtimeSessionId,
-        workspaceContinuityState: descriptor.continuityState,
-        snapshotId: descriptor.snapshotId,
-        revision: descriptor.revision,
-        contentSha256: descriptor.contentSha256,
-        writtenAt: new Date().toISOString(),
-    };
-}
-export function recoverWorkspaceRestoreSwap(options) {
-    assertDescriptor(options.descriptor);
-    assertControlPath(options.workspaceDirectory, options.controlDirectory);
-    const journalFile = workspaceRestoreJournalPath(options.controlDirectory, options.descriptor.runtimeSessionId);
-    if (!existsSync(journalFile))
-        return false;
-    const journal = parseJournal(JSON.parse(readFileSync(journalFile, "utf8")), options.descriptor);
-    const parent = path.dirname(options.workspaceDirectory);
-    const staging = path.join(parent, journal.stagingName);
-    const backup = path.join(parent, journal.backupName);
-    const workspaceExists = existsSync(options.workspaceDirectory);
-    const stagingExists = existsSync(staging);
-    const backupExists = existsSync(backup);
-    if (journal.phase === "new_moved" ||
-        (journal.phase === "old_moved" && workspaceExists && !stagingExists)) {
-        if (!workspaceExists)
-            fail("workspace_restore_journal_invalid");
-        writeWorkspaceMaterializationMarker(journal.marker);
-        if (backupExists)
-            rmSync(backup, { recursive: true, force: true });
-        unlinkSync(journalFile);
-        fsyncDirectory(path.dirname(journalFile));
-        fsyncDirectory(parent);
-        return true;
-    }
-    if (!stagingExists)
-        fail("workspace_restore_journal_invalid");
-    if (!workspaceExists && backupExists)
-        renameSync(backup, options.workspaceDirectory);
-    else if (!workspaceExists && journal.hadWorkspace)
-        fail("workspace_restore_journal_invalid");
-    else if (workspaceExists && backupExists)
-        fail("workspace_restore_journal_invalid");
-    rmSync(staging, { recursive: true, force: true });
-    unlinkSync(journalFile);
-    fsyncDirectory(path.dirname(journalFile));
-    fsyncDirectory(parent);
-    return true;
-}
-export async function restoreWorkspaceSnapshot(options) {
-    const descriptor = options.descriptor;
-    assertDescriptor(descriptor);
-    assertControlPath(options.workspaceDirectory, options.controlDirectory);
-    assertWorkspaceRestoreCapacity(options);
-    recoverWorkspaceRestoreSwap({
-        workspaceDirectory: options.workspaceDirectory,
-        controlDirectory: options.controlDirectory,
-        descriptor,
-    });
-    const canonical = validateWorkspaceEntrySet(options.entrySet, options.limits);
-    if (canonical.entries.length !== descriptor.expectedEntryCount ||
-        canonical.fileCount !== descriptor.expectedFileCount ||
-        canonical.totalBytes !== descriptor.expectedTotalBytes ||
-        (descriptor.revision > 0 && canonical.contentSha256 !== descriptor.contentSha256))
-        fail("workspace_restore_integrity_failed");
-    const parent = path.dirname(options.workspaceDirectory);
-    const nonce = randomUUID();
-    const stagingName = `.botlearn-restore-${descriptor.runtimeSessionId}-${nonce}`;
-    const backupName = `.botlearn-backup-${descriptor.runtimeSessionId}-${nonce}`;
-    const staging = path.join(parent, stagingName);
-    const backup = path.join(parent, backupName);
-    mkdirSync(staging, { mode: 0o700 });
-    chmodSync(staging, 0o700);
-    let journalWritten = false;
-    try {
-        for (const entry of canonical.entries) {
-            const destination = path.join(staging, ...entry.path.split("/"));
-            if (entry.type === "directory") {
-                mkdirSync(destination, { recursive: true, mode: 0o700 });
-                chmodSync(destination, 0o700);
-                continue;
-            }
-            mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
-            const part = `${destination}.part`;
-            await options.downloadFile(entry, part);
-            verifyDownloadedFile(part, {
-                expectedSize: entry.sizeBytes,
-                expectedSha256: entry.sha256,
-            });
-            chmodSync(part, entry.mode === "0700" ? 0o700 : 0o600);
-            renameSync(part, destination);
-        }
-        const directories = new Set([staging]);
-        for (const entry of canonical.entries) {
-            let directory = entry.type === "directory"
-                ? path.join(staging, ...entry.path.split("/"))
-                : path.dirname(path.join(staging, ...entry.path.split("/")));
-            while (directory.startsWith(staging)) {
-                directories.add(directory);
-                if (directory === staging)
-                    break;
-                directory = path.dirname(directory);
-            }
-        }
-        for (const directory of [...directories].sort((a, b) => b.length - a.length)) {
-            fsyncDirectory(directory);
-        }
-        const journalFile = workspaceRestoreJournalPath(options.controlDirectory, descriptor.runtimeSessionId);
-        const journal = {
-            schemaVersion: RESTORE_JOURNAL_SCHEMA,
-            sandboxId: descriptor.sandboxId,
-            sandboxGeneration: descriptor.sandboxGeneration,
-            runtimeSessionId: descriptor.runtimeSessionId,
-            stagingName,
-            backupName,
-            hadWorkspace: existsSync(options.workspaceDirectory),
-            phase: "prepared",
-            marker: markerFromDescriptor(descriptor),
-        };
-        writeJournal(journalFile, journal);
-        journalWritten = true;
-        if (journal.hadWorkspace)
-            renameSync(options.workspaceDirectory, backup);
-        journal.phase = "old_moved";
-        writeJournal(journalFile, journal);
-        renameSync(staging, options.workspaceDirectory);
-        fsyncDirectory(parent);
-        journal.phase = "new_moved";
-        writeJournal(journalFile, journal);
-        writeWorkspaceMaterializationMarker(journal.marker);
-        if (journal.hadWorkspace)
-            rmSync(backup, { recursive: true, force: true });
-        unlinkSync(journalFile);
-        fsyncDirectory(path.dirname(journalFile));
-        fsyncDirectory(parent);
-    }
-    catch (error) {
-        if (!journalWritten)
-            rmSync(staging, { recursive: true, force: true });
-        throw error;
-    }
-}
-export function assertWorkspaceRestoreCapacity(options) {
-    const { descriptor } = options;
-    assertDescriptor(descriptor);
-    if (!Number.isSafeInteger(options.requiredFreeBytes) ||
-        options.requiredFreeBytes < descriptor.expectedTotalBytes)
-        fail("workspace_restore_reservation_invalid");
-    const parent = path.dirname(options.workspaceDirectory);
-    mkdirSync(parent, { recursive: true, mode: 0o700 });
-    if (existsSync(options.workspaceDirectory)) {
-        const current = lstatSync(options.workspaceDirectory, { bigint: true });
-        if (!current.isDirectory() || current.isSymbolicLink()) {
-            fail("workspace_restore_existing_workspace_invalid");
-        }
-    }
-    const filesystem = statfsSync(parent, { bigint: true });
-    if (filesystem.bavail * filesystem.bsize < BigInt(options.requiredFreeBytes)) {
-        fail("workspace_restore_disk_pressure");
-    }
-    const entryCopies = options.entryCopies ?? 1;
-    if (filesystem.ffree < BigInt(descriptor.expectedEntryCount * entryCopies + 16)) {
-        fail("workspace_restore_inode_pressure");
-    }
-}