@xfey/tutti 0.1.60 → 0.1.62

package/dist/server-shell/local-console/package-update-lock.js

@@ -0,0 +1,223 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, closeSync, constants, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+const DEFAULT_STALE_MS = 30_000;
+export function packageUpdateLockPath(tuttiHome) {
+    return join(tuttiHome, "runtime", "package-update.lock");
+}
+function isPositiveInteger(value) {
+    return Number.isInteger(value) && value > 0;
+}
+function parseRecord(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (Object.keys(value).sort().join("\n") !==
+            ["acquired_at", "owner_id", "pid", "schema_version", "updated_at"].join("\n") ||
+            value.schema_version !== 1 ||
+            !isPositiveInteger(value.pid) ||
+            typeof value.owner_id !== "string" ||
+            value.owner_id === "" ||
+            typeof value.acquired_at !== "string" ||
+            typeof value.updated_at !== "string" ||
+            !Number.isFinite(Date.parse(value.acquired_at)) ||
+            !Number.isFinite(Date.parse(value.updated_at))) {
+            return null;
+        }
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "EPERM");
+    }
+}
+function fileAge(path, now) {
+    try {
+        return Math.max(0, now() - statSync(path).mtimeMs);
+    }
+    catch {
+        return null;
+    }
+}
+export function inspectPackageUpdateLock(options) {
+    const path = packageUpdateLockPath(options.tuttiHome);
+    const age = fileAge(path, options.now ?? Date.now);
+    if (age === null) {
+        return { status: "unlocked" };
+    }
+    const record = parseRecord(path);
+    if (record === null) {
+        return { status: "recovery_required" };
+    }
+    if ((options.processAlive ?? defaultProcessAlive)(record.pid)) {
+        return { status: "active" };
+    }
+    return age < (options.staleMs ?? DEFAULT_STALE_MS)
+        ? { status: "active" }
+        : { status: "recovery_required" };
+}
+function ensurePrivateRuntimeDirectory(path) {
+    const directory = dirname(path);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    chmodSync(directory, 0o700);
+}
+function writeRecord(path, record) {
+    const temporaryPath = `${path}.${record.owner_id}.tmp`;
+    try {
+        writeFileSync(temporaryPath, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+        chmodSync(temporaryPath, 0o600);
+        renameSync(temporaryPath, path);
+        chmodSync(path, 0o600);
+    }
+    finally {
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch {
+            // Atomic rename normally removes the temporary path.
+        }
+    }
+}
+export function tryAcquirePackageUpdateLock(options) {
+    const path = packageUpdateLockPath(options.tuttiHome);
+    const now = options.now ?? Date.now;
+    ensurePrivateRuntimeDirectory(path);
+    const ownerId = randomBytes(16).toString("base64url");
+    const timestamp = new Date(now()).toISOString();
+    const record = {
+        schema_version: 1,
+        pid: options.pid ?? process.pid,
+        owner_id: ownerId,
+        acquired_at: timestamp,
+        updated_at: timestamp,
+    };
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "EEXIST") {
+            const inspection = inspectPackageUpdateLock(options);
+            return inspection.status === "unlocked" ? { status: "active" } : inspection;
+        }
+        throw error;
+    }
+    try {
+        writeFileSync(descriptor, `${JSON.stringify(record)}\n`, "utf8");
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    chmodSync(path, 0o600);
+    let released = false;
+    return {
+        status: "acquired",
+        lease: {
+            path,
+            transferTo: (pid) => {
+                if (released || !isPositiveInteger(pid)) {
+                    throw new Error("Package update lock transfer is invalid.");
+                }
+                const current = parseRecord(path);
+                if (current?.owner_id !== ownerId) {
+                    throw new Error("Package update lock ownership changed before transfer.");
+                }
+                writeRecord(path, {
+                    ...current,
+                    pid,
+                    updated_at: new Date(now()).toISOString(),
+                });
+            },
+            release: () => {
+                if (released) {
+                    return;
+                }
+                released = true;
+                if (parseRecord(path)?.owner_id !== ownerId) {
+                    return;
+                }
+                try {
+                    unlinkSync(path);
+                }
+                catch (error) {
+                    if (typeof error !== "object" ||
+                        error === null ||
+                        !("code" in error) ||
+                        error.code !== "ENOENT") {
+                        throw error;
+                    }
+                }
+            },
+        },
+    };
+}
+export function removeRecoverablePackageUpdateLock(options) {
+    if (inspectPackageUpdateLock(options).status !== "recovery_required") {
+        return false;
+    }
+    try {
+        unlinkSync(packageUpdateLockPath(options.tuttiHome));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function transferPackageUpdateLockFromCurrentProcess(options) {
+    if (!isPositiveInteger(options.nextPid)) {
+        return false;
+    }
+    const path = packageUpdateLockPath(options.tuttiHome);
+    const record = parseRecord(path);
+    if (record === null || record.pid !== process.pid) {
+        return false;
+    }
+    writeRecord(path, {
+        ...record,
+        pid: options.nextPid,
+        updated_at: new Date((options.now ?? Date.now)()).toISOString(),
+    });
+    return true;
+}
+export function releasePackageUpdateLockForCurrentProcess(tuttiHome) {
+    const path = packageUpdateLockPath(tuttiHome);
+    const record = parseRecord(path);
+    if (record === null || record.pid !== process.pid) {
+        return false;
+    }
+    try {
+        unlinkSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function releasePackageUpdateLockForExpectedPid(tuttiHome, expectedPid) {
+    const path = packageUpdateLockPath(tuttiHome);
+    const record = parseRecord(path);
+    if (record === null || record.pid !== expectedPid) {
+        return false;
+    }
+    try {
+        unlinkSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=package-update-lock.js.map

package/dist/server-shell/local-console/package-update-log.d.ts

@@ -0,0 +1,20 @@
+export declare function packageUpdateLogPath(tuttiHome: string): string;
+export declare function withPackageUpdateLogDescriptor<T>(tuttiHome: string, run: (descriptor: number) => T): T;
+export declare function redactPackageUpdateOutput(value: string, privatePaths: readonly string[]): string;
+export declare class PackageUpdateLogger {
+    #private;
+    constructor(options: {
+        tuttiHome: string;
+        privatePaths?: readonly string[];
+        now?: () => Date;
+    });
+    append(options: {
+        level: "info" | "warn" | "error";
+        message: string;
+        phase?: string;
+        reasonCode?: string;
+        stdout?: string;
+        stderr?: string;
+    }): void;
+}
+//# sourceMappingURL=package-update-log.d.ts.map

package/dist/server-shell/local-console/package-update-log.js

@@ -0,0 +1,75 @@
+import { appendFileSync, chmodSync, closeSync, existsSync, mkdirSync, openSync, renameSync, statSync, unlinkSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { redactAndTruncateText, serializeRuntimeLogLine } from "@tutti/shared/utils";
+const PACKAGE_UPDATE_LOG_MAX_BYTES = 2 * 1024 * 1024;
+const PACKAGE_UPDATE_OUTPUT_MAX_CHARS = 16 * 1024;
+export function packageUpdateLogPath(tuttiHome) {
+    return join(tuttiHome, "logs", "package-update.log");
+}
+function preparePackageUpdateLog(tuttiHome) {
+    const path = packageUpdateLogPath(tuttiHome);
+    const directory = dirname(path);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    chmodSync(directory, 0o700);
+    if (existsSync(path) && statSync(path).size >= PACKAGE_UPDATE_LOG_MAX_BYTES) {
+        const previous = `${path}.1`;
+        if (existsSync(previous)) {
+            unlinkSync(previous);
+        }
+        renameSync(path, previous);
+    }
+    return path;
+}
+export function withPackageUpdateLogDescriptor(tuttiHome, run) {
+    const path = preparePackageUpdateLog(tuttiHome);
+    const descriptor = openSync(path, "a", 0o600);
+    chmodSync(path, 0o600);
+    try {
+        return run(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+export function redactPackageUpdateOutput(value, privatePaths) {
+    let redacted = redactAndTruncateText(value, PACKAGE_UPDATE_OUTPUT_MAX_CHARS);
+    for (const path of [...privatePaths, tmpdir()].filter((entry) => entry !== "")) {
+        redacted = redacted.replaceAll(path, "[REDACTED:local_path]");
+    }
+    return redacted.replace(/(^|[\s"'`=:(])(?:\/tmp\/|\/private\/tmp\/)[^\s"',)]+/gu, "$1[REDACTED:local_path]");
+}
+export class PackageUpdateLogger {
+    #tuttiHome;
+    #privatePaths;
+    #now;
+    constructor(options) {
+        this.#tuttiHome = options.tuttiHome;
+        this.#privatePaths = options.privatePaths ?? [];
+        this.#now = options.now ?? (() => new Date());
+    }
+    append(options) {
+        const path = preparePackageUpdateLog(this.#tuttiHome);
+        const fields = {
+            ...(options.phase === undefined ? {} : { phase: options.phase }),
+            ...(options.reasonCode === undefined ? {} : { reason_code: options.reasonCode }),
+            ...(options.stdout === undefined
+                ? {}
+                : { stdout: redactPackageUpdateOutput(options.stdout, this.#privatePaths) }),
+            ...(options.stderr === undefined
+                ? {}
+                : { stderr: redactPackageUpdateOutput(options.stderr, this.#privatePaths) }),
+        };
+        const line = serializeRuntimeLogLine({
+            level: options.level,
+            service: "tutti-package-update",
+            component: "worker",
+            message: options.message,
+            fields,
+            now: this.#now,
+        });
+        appendFileSync(path, `${line}\n`, { encoding: "utf8", mode: 0o600 });
+        chmodSync(path, 0o600);
+    }
+}
+//# sourceMappingURL=package-update-log.js.map

package/dist/server-shell/local-console/package-update-process.d.ts

@@ -0,0 +1,22 @@
+import type { PackageUpdatePreparationLease } from "./package-update-service.js";
+import { type PackageUpdateWorkerInput } from "./package-update-worker.js";
+export type HiddenPackageUpdateProcessPlan = {
+    executable: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    shell: false;
+};
+export declare function buildHiddenPackageUpdateProcessPlan(options: {
+    input: PackageUpdateWorkerInput;
+    role: "worker" | "completion";
+}): HiddenPackageUpdateProcessPlan;
+export declare function spawnPackageUpdateWorkerProcess(options: {
+    input: PackageUpdateWorkerInput;
+    lease: PackageUpdatePreparationLease;
+}): Promise<{
+    pid: number;
+}>;
+export declare function runPackageUpdateWorkerProtocol(): Promise<void>;
+export declare function runPackageUpdateCompletionProtocol(): Promise<void>;
+//# sourceMappingURL=package-update-process.d.ts.map

package/dist/server-shell/local-console/package-update-process.js

@@ -0,0 +1,252 @@
+import { spawn } from "node:child_process";
+import { releasePackageUpdateLockForCurrentProcess, releasePackageUpdateLockForExpectedPid, transferPackageUpdateLockFromCurrentProcess, } from "./package-update-lock.js";
+import { PackageUpdateLogger, withPackageUpdateLogDescriptor } from "./package-update-log.js";
+import { updatePackageUpdateRuntimeRecord, } from "./package-update-record.js";
+import { parsePackageUpdateWorkerInput, runPackageUpdateWorker, } from "./package-update-worker.js";
+import { runPackageUpdateCompletion } from "./package-update-completion.js";
+const HANDSHAKE_TIMEOUT_MS = 10_000;
+export function buildHiddenPackageUpdateProcessPlan(options) {
+    return {
+        executable: options.input.installation.nodeExecutable,
+        args: [
+            options.input.cli_entrypoint,
+            "internal",
+            options.role === "worker" ? "package-update-worker" : "package-update-complete",
+        ],
+        cwd: options.input.tutti_home,
+        env: {
+            ...options.input.completion_environment,
+            TUTTI_HOME: options.input.tutti_home,
+        },
+        shell: false,
+    };
+}
+function sendProcessMessage(message) {
+    return new Promise((resolveSend, rejectSend) => {
+        if (process.send === undefined) {
+            rejectSend(new Error("Package update process IPC is unavailable."));
+            return;
+        }
+        process.send(message, (error) => {
+            if (error === null) {
+                resolveSend();
+            }
+            else {
+                rejectSend(error);
+            }
+        });
+    });
+}
+function sendChildMessage(child, message) {
+    return new Promise((resolveSend, rejectSend) => {
+        if (!child.connected || child.send === undefined) {
+            rejectSend(new Error("Package update child IPC is unavailable."));
+            return;
+        }
+        child.send(message, (error) => {
+            if (error === null) {
+                resolveSend();
+            }
+            else {
+                rejectSend(error);
+            }
+        });
+    });
+}
+function waitForChildMessage(child) {
+    return new Promise((resolveMessage, rejectMessage) => {
+        const timeout = setTimeout(() => {
+            cleanup();
+            rejectMessage(new Error("Package update child handshake timed out."));
+        }, HANDSHAKE_TIMEOUT_MS);
+        const onMessage = (message) => {
+            cleanup();
+            resolveMessage(message);
+        };
+        const onError = (error) => {
+            cleanup();
+            rejectMessage(error);
+        };
+        const onExit = () => {
+            cleanup();
+            rejectMessage(new Error("Package update child exited during handshake."));
+        };
+        const cleanup = () => {
+            clearTimeout(timeout);
+            child.off("message", onMessage);
+            child.off("error", onError);
+            child.off("exit", onExit);
+        };
+        child.once("message", onMessage);
+        child.once("error", onError);
+        child.once("exit", onExit);
+    });
+}
+function waitForProcessMessage() {
+    return new Promise((resolveMessage, rejectMessage) => {
+        const timeout = setTimeout(() => {
+            cleanup();
+            rejectMessage(new Error("Package update parent handshake timed out."));
+        }, HANDSHAKE_TIMEOUT_MS);
+        const onMessage = (message) => {
+            cleanup();
+            resolveMessage(message);
+        };
+        const onDisconnect = () => {
+            cleanup();
+            rejectMessage(new Error("Package update parent disconnected during handshake."));
+        };
+        const cleanup = () => {
+            clearTimeout(timeout);
+            process.off("message", onMessage);
+            process.off("disconnect", onDisconnect);
+        };
+        process.once("message", onMessage);
+        process.once("disconnect", onDisconnect);
+    });
+}
+function spawnHiddenPackageUpdateProcess(options) {
+    const plan = buildHiddenPackageUpdateProcessPlan(options);
+    return withPackageUpdateLogDescriptor(options.input.tutti_home, (descriptor) => spawn(plan.executable, plan.args, {
+        cwd: plan.cwd,
+        detached: true,
+        env: plan.env,
+        shell: plan.shell,
+        stdio: ["ignore", descriptor, descriptor, "ipc"],
+    }));
+}
+function disconnectAndUnref(child) {
+    child.unref();
+    child.channel?.unref();
+    if (child.connected) {
+        child.disconnect();
+    }
+}
+export async function spawnPackageUpdateWorkerProcess(options) {
+    const child = spawnHiddenPackageUpdateProcess({ input: options.input, role: "worker" });
+    let handedOff = false;
+    try {
+        const ready = await waitForChildMessage(child);
+        if (ready.kind !== "ready" || ready.role !== "worker") {
+            throw new Error("Package update worker returned an invalid readiness message.");
+        }
+        await sendChildMessage(child, { kind: "input", input: options.input });
+        const accepted = await waitForChildMessage(child);
+        if (accepted.kind !== "accepted" || accepted.role !== "worker") {
+            throw new Error("Package update worker rejected its internal input.");
+        }
+        if (child.pid === undefined) {
+            throw new Error("Package update worker did not expose a process id.");
+        }
+        options.lease.handoffTo(child.pid);
+        handedOff = true;
+        await sendChildMessage(child, { kind: "start" });
+        options.lease.release();
+        disconnectAndUnref(child);
+        return { pid: child.pid };
+    }
+    catch (error) {
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // The worker already exited.
+        }
+        if (handedOff) {
+            options.lease.cancel();
+        }
+        else {
+            options.lease.release();
+        }
+        throw error;
+    }
+}
+async function startInstalledCompletion(input, record) {
+    const child = spawnHiddenPackageUpdateProcess({ input, role: "completion" });
+    let transferred = false;
+    try {
+        const ready = await waitForChildMessage(child);
+        if (ready.kind !== "ready" || ready.role !== "completion" || child.pid === undefined) {
+            throw new Error("Installed package completion did not become ready.");
+        }
+        updatePackageUpdateRuntimeRecord({
+            tuttiHome: input.tutti_home,
+            current: record,
+            phase: "restarting",
+            updaterPid: child.pid,
+        });
+        if (!transferPackageUpdateLockFromCurrentProcess({
+            tuttiHome: input.tutti_home,
+            nextPid: child.pid,
+        })) {
+            throw new Error("Package update lock could not be handed to completion.");
+        }
+        transferred = true;
+        await sendChildMessage(child, { kind: "start" });
+        disconnectAndUnref(child);
+    }
+    catch (error) {
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // The completion process already exited.
+        }
+        if (transferred && child.pid !== undefined) {
+            releasePackageUpdateLockForExpectedPid(input.tutti_home, child.pid);
+        }
+        throw error;
+    }
+}
+export async function runPackageUpdateWorkerProtocol() {
+    await sendProcessMessage({ kind: "ready", role: "worker" });
+    let input = null;
+    try {
+        const message = await waitForProcessMessage();
+        input = message.kind === "input" ? parsePackageUpdateWorkerInput(message.input) : null;
+        if (input === null) {
+            await sendProcessMessage({ kind: "rejected", role: "worker" });
+            return;
+        }
+        await sendProcessMessage({ kind: "accepted", role: "worker" });
+        const start = await waitForProcessMessage();
+        if (start.kind !== "start") {
+            throw new Error("Package update worker did not receive its start signal.");
+        }
+        await runPackageUpdateWorker(input, {
+            startCompletion: startInstalledCompletion,
+        });
+    }
+    catch (error) {
+        if (input !== null) {
+            new PackageUpdateLogger({
+                tuttiHome: input.tutti_home,
+                privatePaths: [input.tutti_home, input.installation.packageRoot],
+            }).append({
+                level: "error",
+                message: "Package update worker crashed.",
+                reasonCode: "worker_crashed",
+            });
+            releasePackageUpdateLockForCurrentProcess(input.tutti_home);
+        }
+        throw error;
+    }
+}
+export async function runPackageUpdateCompletionProtocol() {
+    await sendProcessMessage({ kind: "ready", role: "completion" });
+    const start = await waitForProcessMessage();
+    if (start.kind !== "start") {
+        throw new Error("Package update completion did not receive its start signal.");
+    }
+    const tuttiHome = process.env.TUTTI_HOME;
+    const cliEntrypoint = process.argv[1];
+    if (tuttiHome === undefined || cliEntrypoint === undefined) {
+        throw new Error("Package update completion environment is unavailable.");
+    }
+    await runPackageUpdateCompletion({
+        tuttiHome,
+        cliEntrypoint,
+        env: process.env,
+    });
+}
+//# sourceMappingURL=package-update-process.js.map

package/dist/server-shell/local-console/package-update-record.d.ts

@@ -0,0 +1,53 @@
+import { type ProjectId } from "@tutti/shared/ids";
+export type PackageUpdateRuntimePhase = "preparing" | "stopping_hosts" | "installing" | "restarting" | "failed";
+export type PackageUpdateRuntimeRecord = {
+    schema_version: 1;
+    source_version: string;
+    target_version: string;
+    phase: PackageUpdateRuntimePhase;
+    restore_project_ids: ProjectId[];
+    updater_pid: number;
+    started_at: string;
+    updated_at: string;
+    failure_reason_code?: string;
+    restart_failure_count?: number;
+};
+export type PackageUpdateRuntimeRecordRead = {
+    status: "missing";
+} | {
+    status: "valid";
+    record: PackageUpdateRuntimeRecord;
+} | {
+    status: "invalid";
+};
+export type PackageUpdateCompletionResult = {
+    source_version: string;
+    target_version: string;
+    restart_failure_count: number;
+};
+export declare function packageUpdateRuntimeRecordPath(tuttiHome: string): string;
+export declare function readPackageUpdateRuntimeRecord(options: {
+    tuttiHome: string;
+    now?: () => number;
+    maxAgeMs?: number;
+}): PackageUpdateRuntimeRecordRead;
+export declare function writePackageUpdateRuntimeRecord(tuttiHome: string, record: PackageUpdateRuntimeRecord): void;
+export declare function deletePackageUpdateRuntimeRecord(options: {
+    tuttiHome: string;
+    expectedTargetVersion?: string;
+    expectedUpdaterPid?: number;
+}): boolean;
+export declare function updatePackageUpdateRuntimeRecord(options: {
+    tuttiHome: string;
+    current: PackageUpdateRuntimeRecord;
+    phase: PackageUpdateRuntimePhase;
+    now?: () => Date;
+    updaterPid?: number;
+    failureReasonCode?: string;
+    restartFailureCount?: number;
+}): PackageUpdateRuntimeRecord;
+export declare function consumePackageUpdateCompletion(options: {
+    tuttiHome: string;
+    currentVersion: string;
+}): PackageUpdateCompletionResult | undefined;
+//# sourceMappingURL=package-update-record.d.ts.map