@fased/fased 0.1.62 → 0.1.64

package/dist/infra/local-source-paired-update.js

@@ -0,0 +1,538 @@
+import { resolveStateDir } from "../config/paths.js";
+import { runCommandWithTimeout } from "../process/exec.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import * as tar from "tar";
+
+//#region src/infra/local-source-paired-update.ts
+const JOURNAL_SCHEMA_VERSION = 1;
+const PHASES = new Set([
+	"prepared",
+	"app-active",
+	"signer-active",
+	"gateway-verified",
+	"committing",
+	"rolling-back"
+]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SHA_PATTERN = /^[a-f0-9]{40}$/;
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/;
+function resolveContext(env = process.env) {
+	const stateDir = path.resolve(resolveStateDir(env));
+	const updateRoot = path.join(stateDir, "source-paired-update");
+	return {
+		stateDir,
+		updateRoot,
+		transactionsDir: path.join(updateRoot, "transactions"),
+		journalPath: path.join(updateRoot, "transaction.json")
+	};
+}
+function pathIsInside(parent, candidate) {
+	const relative = path.relative(path.resolve(parent), path.resolve(candidate));
+	return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+async function fsyncPath(target) {
+	const handle = await fs.open(target, "r");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+async function sha256File(filePath) {
+	const bytes = await fs.readFile(filePath);
+	return createHash("sha256").update(bytes).digest("hex");
+}
+function validateRelease(value, label) {
+	const release = value;
+	if (!release || !SHA_PATTERN.test(release.sha ?? "") || !VERSION_PATTERN.test(release.version ?? "")) {
+		throw new Error(`Local source paired update has an invalid ${label} release identity`);
+	}
+	return {
+		sha: release.sha,
+		version: release.version
+	};
+}
+function validateJournal(context, value) {
+	const journal = value;
+	if (!journal || journal.schemaVersion !== JOURNAL_SCHEMA_VERSION || journal.kind !== "source-checkout" || !UUID_PATTERN.test(journal.transactionId ?? "") || !PHASES.has(journal.phase) || typeof journal.sourceRoot !== "string" || !path.isAbsolute(journal.sourceRoot) || typeof journal.transactionDir !== "string" || path.resolve(journal.transactionDir) !== path.join(context.transactionsDir, journal.transactionId ?? "") || !pathIsInside(context.updateRoot, journal.transactionDir) || path.resolve(journal.controllerPath ?? "") !== path.join(journal.transactionDir, "controller", "fased-managed-updater.mjs") || typeof journal.previous?.branch !== "string" && journal.previous?.branch !== null || typeof journal.previous?.branch === "string" && (!journal.previous.branch || journal.previous.branch.includes("..") || !/^[0-9A-Za-z._/-]+$/.test(journal.previous.branch)) || typeof journal.distSnapshot?.path !== "string" || path.resolve(journal.distSnapshot.path) !== path.join(journal.transactionDir, "dist.tar.gz") || !/^[a-f0-9]{64}$/.test(journal.distSnapshot?.sha256 ?? "") || !Number.isSafeInteger(journal.distSnapshot?.size) || (journal.distSnapshot?.size ?? -1) <= 0) {
+		throw new Error("Local source paired update journal is invalid");
+	}
+	const previous = validateRelease(journal.previous, "previous");
+	const needsTarget = new Set([
+		"app-active",
+		"signer-active",
+		"gateway-verified",
+		"committing"
+	]).has(journal.phase);
+	const target = journal.target === null ? null : validateRelease(journal.target, "target");
+	if (needsTarget && target === null) {
+		throw new Error("Local source paired update journal is missing its target release identity");
+	}
+	return {
+		...journal,
+		sourceRoot: path.resolve(journal.sourceRoot),
+		previous: {
+			...previous,
+			branch: journal.previous.branch
+		},
+		target
+	};
+}
+async function writeJournal(context, journal, phase = journal.phase, exclusive = false) {
+	const next = validateJournal(context, {
+		...journal,
+		phase,
+		updatedAt: new Date().toISOString()
+	});
+	await fs.mkdir(context.updateRoot, {
+		recursive: true,
+		mode: 448
+	});
+	if (exclusive) {
+		const handle = await fs.open(context.journalPath, "wx", 384);
+		try {
+			await handle.writeFile(`${JSON.stringify(next, null, 2)}\n`);
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+	} else {
+		const temporary = `${context.journalPath}.tmp-${process.pid}-${Date.now()}`;
+		const handle = await fs.open(temporary, "wx", 384);
+		try {
+			await handle.writeFile(`${JSON.stringify(next, null, 2)}\n`);
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		await fs.rename(temporary, context.journalPath);
+	}
+	await fsyncPath(context.updateRoot);
+	return next;
+}
+async function readLocalSourcePairedUpdateJournal(env = process.env) {
+	const context = resolveContext(env);
+	try {
+		return validateJournal(context, JSON.parse(await fs.readFile(context.journalPath, "utf8")));
+	} catch (error) {
+		if (error.code === "ENOENT") {
+			return null;
+		}
+		throw error;
+	}
+}
+async function runExact(argv, options) {
+	const result = await runCommandWithTimeout(argv, {
+		cwd: options.cwd,
+		timeoutMs: options.timeoutMs,
+		env: options.env
+	});
+	if (result.code !== 0) {
+		const detail = (result.stderr || result.stdout).trim().split("\n").slice(-5).join("\n");
+		throw new Error(`${options.label} failed${detail ? `: ${detail}` : ""}`);
+	}
+	return result.stdout.trim();
+}
+async function readGitHead(sourceRoot, timeoutMs, env) {
+	const sha = await runExact([
+		"git",
+		"-C",
+		sourceRoot,
+		"rev-parse",
+		"HEAD"
+	], {
+		cwd: sourceRoot,
+		timeoutMs,
+		env,
+		label: "git HEAD verification"
+	});
+	if (!SHA_PATTERN.test(sha)) {
+		throw new Error("Source checkout did not report an exact Git commit");
+	}
+	return sha;
+}
+async function readPackageVersion(sourceRoot) {
+	const parsed = JSON.parse(await fs.readFile(path.join(sourceRoot, "package.json"), "utf8"));
+	const version = typeof parsed.version === "string" ? parsed.version.trim() : "";
+	if (!VERSION_PATTERN.test(version)) {
+		throw new Error("Source checkout package.json has no exact release version");
+	}
+	return version;
+}
+async function copyController(sourceRoot, transactionDir) {
+	const controllerDir = path.join(transactionDir, "controller");
+	await fs.mkdir(controllerDir, {
+		recursive: true,
+		mode: 448
+	});
+	for (const name of ["fased-managed-updater.mjs", "managed-runtime-layout.mjs"]) {
+		const source = path.join(sourceRoot, "scripts", name);
+		const stat = await fs.lstat(source);
+		if (!stat.isFile() || stat.isSymbolicLink()) {
+			throw new Error(`Source checkout is missing a safe signer transaction controller: ${source}`);
+		}
+		const destination = path.join(controllerDir, name);
+		await fs.copyFile(source, destination);
+		await fs.chmod(destination, name.endsWith("updater.mjs") ? 448 : 384);
+		await fsyncPath(destination);
+	}
+	await fsyncPath(controllerDir);
+	return path.join(controllerDir, "fased-managed-updater.mjs");
+}
+async function isLocalSourceSignerConfigured(env = process.env) {
+	const stateDir = resolveContext(env).stateDir;
+	for (const candidate of [path.join(stateDir, "bin", "fased-signerd"), path.join(stateDir, "wallet", "signerd-v2.db")]) {
+		const found = await fs.lstat(candidate).then((stat) => stat.isFile() && !stat.isSymbolicLink()).catch(() => false);
+		if (found) {
+			return true;
+		}
+	}
+	try {
+		const registry = JSON.parse(await fs.readFile(path.join(stateDir, "wallet", "provider-registry.v1.json"), "utf8"));
+		return (registry.wallets ?? []).some((wallet) => wallet?.providerId === "local-socket-signer");
+	} catch {
+		return false;
+	}
+}
+async function prepareLocalSourcePairedUpdate(params) {
+	const env = params.env ?? process.env;
+	const context = resolveContext(env);
+	if (await readLocalSourcePairedUpdateJournal(env)) {
+		throw new Error("An unfinished Local source app/signer transaction must be recovered first");
+	}
+	const sourceRoot = path.resolve(params.sourceRoot);
+	const previousSha = await readGitHead(sourceRoot, params.timeoutMs, env);
+	const previousVersion = await readPackageVersion(sourceRoot);
+	const branchResult = await runCommandWithTimeout([
+		"git",
+		"-C",
+		sourceRoot,
+		"symbolic-ref",
+		"--quiet",
+		"--short",
+		"HEAD"
+	], {
+		cwd: sourceRoot,
+		timeoutMs: params.timeoutMs,
+		env
+	});
+	const branch = branchResult.code === 0 && branchResult.stdout.trim() ? branchResult.stdout.trim() : null;
+	if (branch !== null && (branch.includes("..") || !/^[0-9A-Za-z._/-]+$/.test(branch))) {
+		throw new Error("Source checkout branch name is unsafe for transactional rollback");
+	}
+	const transactionId = randomUUID();
+	const transactionDir = path.join(context.transactionsDir, transactionId);
+	await fs.mkdir(transactionDir, {
+		recursive: true,
+		mode: 448
+	});
+	try {
+		const distRoot = path.join(sourceRoot, "dist");
+		const distStat = await fs.lstat(distRoot);
+		if (!distStat.isDirectory() || distStat.isSymbolicLink()) {
+			throw new Error("Source checkout has no safe built dist directory to snapshot");
+		}
+		const distSnapshotPath = path.join(transactionDir, "dist.tar.gz");
+		await tar.c({
+			cwd: sourceRoot,
+			file: distSnapshotPath,
+			gzip: true,
+			portable: true,
+			noMtime: true
+		}, ["dist"]);
+		await fs.chmod(distSnapshotPath, 384);
+		await fsyncPath(distSnapshotPath);
+		const distSnapshotStat = await fs.lstat(distSnapshotPath);
+		const controllerPath = await copyController(sourceRoot, transactionDir);
+		const now = new Date().toISOString();
+		const journal = {
+			schemaVersion: 1,
+			kind: "source-checkout",
+			transactionId,
+			transactionDir,
+			sourceRoot,
+			controllerPath,
+			phase: "prepared",
+			previous: {
+				sha: previousSha,
+				version: previousVersion,
+				branch
+			},
+			target: null,
+			distSnapshot: {
+				path: distSnapshotPath,
+				sha256: await sha256File(distSnapshotPath),
+				size: distSnapshotStat.size
+			},
+			createdAt: now,
+			updatedAt: now
+		};
+		await fsyncPath(transactionDir);
+		return await writeJournal(context, journal, "prepared", true);
+	} catch (error) {
+		await fs.rm(transactionDir, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+}
+async function markLocalSourceAppActive(params) {
+	if (params.journal.phase !== "prepared") {
+		throw new Error(`Cannot activate source app from phase ${params.journal.phase}`);
+	}
+	const context = resolveContext(params.env ?? process.env);
+	const target = validateRelease({
+		sha: params.targetSha,
+		version: params.targetVersion
+	}, "target");
+	return await writeJournal(context, {
+		...params.journal,
+		target
+	}, "app-active");
+}
+async function runSignerController(params) {
+	const args = [
+		params.journal.controllerPath,
+		"local-signer",
+		params.action
+	];
+	if (params.action === "verify") {
+		if (!params.journal.target) {
+			throw new Error("Cannot verify a Local signer without a target release");
+		}
+		args.push("--version", params.journal.target.version, "--expected-commit", params.journal.target.sha, "--timeout", String(Math.ceil(params.timeoutMs / 1e3)));
+	}
+	await runExact([process.execPath, ...args], {
+		cwd: path.dirname(params.journal.controllerPath),
+		timeoutMs: params.timeoutMs,
+		env: params.env,
+		label: `Local signer ${params.action}`
+	});
+}
+async function activateLocalSourceSigner(params) {
+	if (params.journal.phase !== "app-active" || !params.journal.target) {
+		throw new Error(`Cannot activate Local signer from phase ${params.journal.phase}`);
+	}
+	const env = params.env ?? process.env;
+	const installer = path.join(params.journal.sourceRoot, "scripts", "install-fased-signerd.sh");
+	const stat = await fs.lstat(installer);
+	if (!stat.isFile() || stat.isSymbolicLink()) {
+		throw new Error("Updated source checkout is missing its safe Local signer installer");
+	}
+	await runExact([
+		"bash",
+		installer,
+		"--version",
+		params.journal.target.version,
+		"--expected-commit",
+		params.journal.target.sha,
+		"--defer-commit"
+	], {
+		cwd: params.journal.sourceRoot,
+		timeoutMs: params.timeoutMs,
+		env,
+		label: "Local signer prepare and activation"
+	});
+	return await writeJournal(resolveContext(env), params.journal, "signer-active");
+}
+async function verifyLocalSourceSigner(params) {
+	if (!new Set(["signer-active", "gateway-verified"]).has(params.journal.phase)) {
+		throw new Error(`Cannot verify Local signer from phase ${params.journal.phase}`);
+	}
+	await runSignerController({
+		journal: params.journal,
+		action: "verify",
+		timeoutMs: params.timeoutMs,
+		env: params.env ?? process.env
+	});
+}
+async function markLocalSourceGatewayVerified(journal, env = process.env) {
+	if (journal.phase !== "signer-active") {
+		throw new Error(`Cannot record Gateway verification from phase ${journal.phase}`);
+	}
+	return await writeJournal(resolveContext(env), journal, "gateway-verified");
+}
+async function removeTransaction(journal, env) {
+	const context = resolveContext(env);
+	await fs.rm(context.journalPath, { force: true });
+	await fsyncPath(context.updateRoot);
+	await fs.rm(journal.transactionDir, {
+		recursive: true,
+		force: true
+	});
+	await fsyncPath(context.transactionsDir);
+}
+async function commitLocalSourcePairedUpdate(params) {
+	const env = params.env ?? process.env;
+	let journal = params.journal;
+	if (journal.phase !== "gateway-verified" && journal.phase !== "committing") {
+		throw new Error(`Cannot commit Local source pair from phase ${journal.phase}`);
+	}
+	if (journal.phase !== "committing") {
+		journal = await writeJournal(resolveContext(env), journal, "committing");
+	}
+	await runSignerController({
+		journal,
+		action: "commit",
+		timeoutMs: params.timeoutMs,
+		env
+	});
+	await removeTransaction(journal, env);
+}
+async function restoreSourceApplication(params) {
+	const { journal, timeoutMs, env } = params;
+	const snapshotStat = await fs.lstat(journal.distSnapshot.path);
+	if (!snapshotStat.isFile() || snapshotStat.isSymbolicLink() || snapshotStat.size !== journal.distSnapshot.size || await sha256File(journal.distSnapshot.path) !== journal.distSnapshot.sha256) {
+		throw new Error("Local source rollback dist snapshot failed integrity verification");
+	}
+	if (journal.previous.branch) {
+		await runExact([
+			"git",
+			"-C",
+			journal.sourceRoot,
+			"checkout",
+			journal.previous.branch
+		], {
+			cwd: journal.sourceRoot,
+			timeoutMs,
+			env,
+			label: "source rollback branch checkout"
+		});
+		await runExact([
+			"git",
+			"-C",
+			journal.sourceRoot,
+			"reset",
+			"--hard",
+			journal.previous.sha
+		], {
+			cwd: journal.sourceRoot,
+			timeoutMs,
+			env,
+			label: "source rollback commit restore"
+		});
+	} else {
+		await runExact([
+			"git",
+			"-C",
+			journal.sourceRoot,
+			"checkout",
+			"--detach",
+			journal.previous.sha
+		], {
+			cwd: journal.sourceRoot,
+			timeoutMs,
+			env,
+			label: "source rollback detached commit restore"
+		});
+	}
+	await runExact([
+		"pnpm",
+		"install",
+		"--offline",
+		"--frozen-lockfile"
+	], {
+		cwd: journal.sourceRoot,
+		timeoutMs,
+		env,
+		label: "offline source dependency rollback"
+	});
+	await fs.rm(path.join(journal.sourceRoot, "dist"), {
+		recursive: true,
+		force: true
+	});
+	await tar.x({
+		cwd: journal.sourceRoot,
+		file: journal.distSnapshot.path,
+		strict: true,
+		filter: (entryPath) => entryPath === "dist" || entryPath.startsWith("dist/")
+	});
+	if (await readGitHead(journal.sourceRoot, timeoutMs, env) !== journal.previous.sha) {
+		throw new Error("Local source rollback restored the wrong Git commit");
+	}
+	if (await readPackageVersion(journal.sourceRoot) !== journal.previous.version) {
+		throw new Error("Local source rollback restored the wrong package version");
+	}
+}
+async function rollbackLocalSourcePairedUpdate(params) {
+	const env = params.env ?? process.env;
+	let journal = params.journal;
+	if (journal.phase !== "rolling-back") {
+		journal = await writeJournal(resolveContext(env), journal, "rolling-back");
+	}
+	const failures = [];
+	try {
+		await runSignerController({
+			journal,
+			action: "rollback",
+			timeoutMs: params.timeoutMs,
+			env
+		});
+	} catch (error) {
+		failures.push(`signer: ${String(error)}`);
+	}
+	if (failures.length === 0) {
+		try {
+			await restoreSourceApplication({
+				journal,
+				timeoutMs: params.timeoutMs,
+				env
+			});
+		} catch (error) {
+			failures.push(`application: ${String(error)}`);
+		}
+	}
+	if (failures.length > 0) {
+		throw new Error(`Local source paired rollback is incomplete (${failures.join("; ")}). Re-run fased update after correcting the failure.`);
+	}
+	await removeTransaction(journal, env);
+}
+async function recoverLocalSourcePairedUpdate(params) {
+	const env = params.env ?? process.env;
+	const journal = await readLocalSourcePairedUpdateJournal(env);
+	if (!journal) {
+		return "none";
+	}
+	if (journal.phase === "gateway-verified" || journal.phase === "committing") {
+		await commitLocalSourcePairedUpdate({
+			journal,
+			timeoutMs: params.timeoutMs,
+			env
+		});
+		return "committed";
+	}
+	await rollbackLocalSourcePairedUpdate({
+		journal,
+		timeoutMs: params.timeoutMs,
+		env
+	});
+	return "rolled-back";
+}
+async function assertLocalSourcePairedGatewayStartAllowed(params) {
+	const env = params.env ?? process.env;
+	const journal = await readLocalSourcePairedUpdateJournal(env);
+	if (!journal) {
+		return;
+	}
+	if (journal.phase !== "signer-active" && journal.phase !== "gateway-verified" && journal.phase !== "committing") {
+		throw new Error(`Gateway startup is blocked by an unfinished Local source app/signer update (${journal.phase}). Run fased update to recover it.`);
+	}
+	if (!journal.target || path.resolve(params.runtimeRoot) !== journal.sourceRoot) {
+		throw new Error("Gateway startup is blocked because the source update target root does not match");
+	}
+	const timeoutMs = params.timeoutMs ?? 5e3;
+	const [sha, version] = await Promise.all([readGitHead(journal.sourceRoot, timeoutMs, env), readPackageVersion(journal.sourceRoot)]);
+	if (sha !== journal.target.sha || version !== journal.target.version) {
+		throw new Error("Gateway startup is blocked because the source update target identity changed");
+	}
+}
+const __testing = {
+	resolveContext,
+	validateJournal
+};
+
+//#endregion
+export { activateLocalSourceSigner, assertLocalSourcePairedGatewayStartAllowed, commitLocalSourcePairedUpdate, isLocalSourceSignerConfigured, markLocalSourceAppActive, markLocalSourceGatewayVerified, prepareLocalSourcePairedUpdate, readLocalSourcePairedUpdateJournal, recoverLocalSourcePairedUpdate, rollbackLocalSourcePairedUpdate, verifyLocalSourceSigner };

package/dist/infra/restart.js

@@ -151,44 +151,75 @@ function deferGatewayRestartUntilIdle(opts) {
 	const pollMs = Math.max(10, Math.floor(pollMsRaw));
 	const maxWaitMsRaw = opts.maxWaitMs ?? DEFAULT_DEFERRAL_MAX_WAIT_MS;
 	const maxWaitMs = Math.max(pollMs, Math.floor(maxWaitMsRaw));
-	let pending;
+	let pendingPoll = null;
+	let pending = false;
+	const handle = {
+		cancel: () => {
+			if (!pending || !pendingPoll) {
+				return false;
+			}
+			clearInterval(pendingPoll);
+			pendingPoll = null;
+			pending = false;
+			return true;
+		},
+		isPending: () => pending
+	};
+	let pendingCount;
 	try {
-		pending = opts.getPendingCount();
+		pendingCount = opts.getPendingCount();
 	} catch (err) {
 		opts.hooks?.onCheckError?.(err);
 		emitGatewayRestart();
-		return;
+		return handle;
 	}
-	if (pending <= 0) {
+	if (pendingCount <= 0) {
 		opts.hooks?.onReady?.();
 		emitGatewayRestart();
-		return;
+		return handle;
 	}
-	opts.hooks?.onDeferring?.(pending);
+	opts.hooks?.onDeferring?.(pendingCount);
 	const startedAt = Date.now();
-	const poll = setInterval(() => {
+	pending = true;
+	pendingPoll = setInterval(() => {
 		let current;
 		try {
 			current = opts.getPendingCount();
 		} catch (err) {
-			clearInterval(poll);
+			if (!pending) {
+				return;
+			}
+			pending = false;
+			if (pendingPoll) {
+				clearInterval(pendingPoll);
+				pendingPoll = null;
+			}
 			opts.hooks?.onCheckError?.(err);
 			emitGatewayRestart();
 			return;
 		}
 		if (current <= 0) {
-			clearInterval(poll);
+			pending = false;
+			if (pendingPoll) {
+				clearInterval(pendingPoll);
+				pendingPoll = null;
+			}
 			opts.hooks?.onReady?.();
 			emitGatewayRestart();
 			return;
 		}
 		const elapsedMs = Date.now() - startedAt;
 		if (elapsedMs >= maxWaitMs) {
-			clearInterval(poll);
+			pending = false;
+			if (pendingPoll) {
+				clearInterval(pendingPoll);
+				pendingPoll = null;
+			}
 			opts.hooks?.onTimeout?.(current, elapsedMs);
 			emitGatewayRestart();
 		}
 	}, pollMs);
+	return handle;
 }
 function formatSpawnDetail(result) {
 	const clean = (value) => {