Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

fix(config): never write config.yaml without the lock; break stale locks

KageBinary604f47869fef
diff --git a/ix-cli/src/cli/__tests__/config-file-mode.test.ts b/ix-cli/src/cli/__tests__/config-file-mode.test.ts
index dafb2a89..c83537a8 100644
--- a/ix-cli/src/cli/__tests__/config-file-mode.test.ts
+++ b/ix-cli/src/cli/__tests__/config-file-mode.test.ts
@@ -51,7 +51,7 @@ describe("saveConfig persistence", () => {
saveConfig({ endpoint: "http://localhost:8090", format: "json" });
expect(readConfig()).toMatchObject({ endpoint: "http://localhost:8090", format: "json" });
- expect(fs.readdirSync(cfgDir())).toEqual(["config.yaml"]);
+ expect(fs.readdirSync(cfgDir()).filter((n) => n !== "locks")).toEqual(["config.yaml"]); // the lock directory stays
});
it.skipIf(!posix)("creates the config directory 0700", () => {
@@ -84,7 +84,7 @@ describe("saveConfig persistence", () => {
const currentInode = fs.statSync(cfgPath()).ino;
if (previousInode !== 0 && currentInode !== 0) expect(currentInode).not.toBe(previousInode);
- expect(fs.readdirSync(cfgDir())).toEqual(["config.yaml"]);
+ expect(fs.readdirSync(cfgDir()).filter((n) => n !== "locks")).toEqual(["config.yaml"]); // the lock directory stays
expect(readConfig()).toMatchObject({ endpoint: "http://new.example", format: "json" });
});
@@ -132,6 +132,6 @@ describe("saveConfig with an unparseable config", () => {
expect(() => saveConfig({ endpoint: "http://localhost:8090", format: "text" })).toThrow(/not valid YAML/);
expect(fs.readFileSync(cfgPath(), "utf8")).toBe(broken);
- expect(fs.readdirSync(cfgDir())).toEqual(["config.yaml"]);
+ expect(fs.readdirSync(cfgDir()).filter((n) => n !== "locks")).toEqual(["config.yaml"]); // the lock directory stays
});
});
diff --git a/ix-cli/src/cli/__tests__/config-integrity.test.ts b/ix-cli/src/cli/__tests__/config-integrity.test.ts
index 0f97e521..ff6ab9cd 100644
--- a/ix-cli/src/cli/__tests__/config-integrity.test.ts
+++ b/ix-cli/src/cli/__tests__/config-integrity.test.ts
@@ -1,10 +1,12 @@
// Copyright 2026 Ix Infrastructure Inc.
import { execFile } from "node:child_process";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
import { promisify } from "node:util";
import { Command } from "commander";
@@ -20,7 +22,11 @@ import { parse } from "yaml";
const execFileAsync = promisify(execFile);
const CLI_ROOT = resolve(fileURLToPath(new URL("../../..", import.meta.url)));
-const TSX = join(CLI_ROOT, "node_modules", ".bin", "tsx");
+// tsx's own entry, run by this node: node_modules/.bin/tsx is a .cmd shim on
+// Windows, which execFile cannot start (ENOENT).
+const TSX_CLI = join(CLI_ROOT, "node_modules", "tsx", "dist", "cli.mjs");
+const tsx = (args: string[], options: Parameters<typeof execFileAsync>[2]) =>
+ execFileAsync(process.execPath, [TSX_CLI, ...args], options);
const BOOTSTRAP = join(CLI_ROOT, "src", "cli", "bootstrap.ts");
let home: string;
@@ -43,9 +49,11 @@ afterEach(() => {
const configPath = () => join(home, "config.yaml");
describe("parallel registrations", () => {
- it.skipIf(process.platform === "win32")("8 processes registering 8 repositories at once keep all 8", async () => {
+ // Generous: each process is a cold tsx start, and a slow macOS or Windows
+ // runner takes seconds per start. The lock itself waits up to 30 s.
+ it("8 processes registering 8 repositories at once keep all 8", async () => {
const script = join(home, "register.mts");
- writeFileSync(script, `import { ensureWorkspaceRegistered } from ${JSON.stringify(BOOTSTRAP)};\nensureWorkspaceRegistered(process.argv[2]);\n`);
+ writeFileSync(script, `import { ensureWorkspaceRegistered } from ${JSON.stringify(pathToFileURL(BOOTSTRAP).href)};\nensureWorkspaceRegistered(process.argv[2]);\n`);
for (let trial = 0; trial < 2; trial++) {
rmSync(configPath(), { force: true });
const dirs = Array.from({ length: 8 }, (_, i) => {
@@ -53,12 +61,98 @@ describe("parallel registrations", () => {
mkdirSync(d, { recursive: true });
return d;
});
- await Promise.all(dirs.map((d) =>
- execFileAsync(TSX, [script, d], { env: { ...process.env, IX_HOME: home, IX_LOCK_DIR: join(home, "locks") } })));
+ const env: NodeJS.ProcessEnv = { ...process.env, IX_HOME: home, IX_LOCK_DIR: join(home, "locks") };
+ delete env.FORCE_COLOR;
+ await Promise.all(dirs.map((d) => tsx([script, d], { env })));
const registered = (parse(readFileSync(configPath(), "utf8")).workspaces ?? []).map((w: { root_path: string }) => w.root_path);
- expect(registered.sort()).toEqual(dirs.sort());
+ // Registration stores the canonical path (macOS: /private/var/..., not
+ // tmpdir's /var/...; Windows: the long name, not RUNNER~1).
+ expect(registered.sort()).toEqual(dirs.map((d) => realpathSync.native(d)).sort());
}
- }, 60_000);
+ }, 180_000);
+});
+
+describe("the config lock", () => {
+ const lockDir = () => join(home, "locks");
+ beforeEach(() => { process.env.IX_LOCK_DIR = lockDir(); });
+ afterEach(() => {
+ delete process.env.IX_LOCK_DIR;
+ delete process.env.IX_CONFIG_LOCK_WAIT_MS;
+ });
+
+ async function lockFile(): Promise<string> {
+ const { namedLockPath } = await import("../single-flight.js");
+ return namedLockPath("config", configPath());
+ }
+
+ /** A pid that was alive a moment ago and is not now. */
+ function deadPid(): number {
+ const out = execFileSync(process.execPath, ["-e", "process.stdout.write(String(process.pid))"], { encoding: "utf8" });
+ return Number(out);
+ }
+
+ function plant(path: string, pid: number): void {
+ mkdirSync(lockDir(), { recursive: true });
+ writeFileSync(path, JSON.stringify({ pid, host: hostname(), token: "planted", startedAt: Date.now(), label: "test" }));
+ }
+
+ it("breaks a lock left by a dead process, and the write goes through", async () => {
+ const path = await lockFile();
+ plant(path, deadPid()); // fresh mtime: only the dead pid makes it stale
+ const { updateConfig, loadConfig } = await import("../config.js");
+ const started = Date.now();
+ updateConfig((c) => ({ save: { ...c, format: "json" }, result: undefined }));
+ expect(Date.now() - started).toBeLessThan(5_000);
+ expect(loadConfig().format).toBe("json");
+ expect(existsSync(path)).toBe(false);
+ });
+
+ it("breaks a lock older than the bound even when its pid is alive", async () => {
+ const path = await lockFile();
+ plant(path, process.pid);
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(path, old, old);
+ const { saveConfig, loadConfig } = await import("../config.js");
+ saveConfig({ ...loadConfig(), format: "llm" });
+ expect(loadConfig().format).toBe("llm");
+ });
+
+ it("fails loudly, writing nothing, while a live holder keeps it", async () => {
+ writeFileSync(configPath(), "endpoint: http://localhost:8090\nformat: text\n");
+ const before = readFileSync(configPath(), "utf8");
+ const path = await lockFile();
+ plant(path, process.pid);
+ process.env.IX_CONFIG_LOCK_WAIT_MS = "300";
+ const { updateConfig, saveConfig, loadConfig, ConfigLockError } = await import("../config.js");
+ expect(() => updateConfig((c) => ({ save: { ...c, format: "json" }, result: undefined }))).toThrow(ConfigLockError);
+ expect(() => saveConfig({ ...loadConfig(), format: "json" })).toThrow(/Nothing was written/);
+ expect(readFileSync(configPath(), "utf8")).toBe(before);
+ expect(existsSync(path)).toBe(true); // a live holder's lock is not taken
+
+ const { renderCliError } = await import("../errors.js");
+ const lines: string[] = [];
+ vi.spyOn(console, "error").mockImplementation((...a: unknown[]) => { lines.push(a.join(" ")); });
+ vi.spyOn(console, "log").mockImplementation((...a: unknown[]) => { lines.push(a.join(" ")); });
+ vi.spyOn(process.stderr, "write").mockImplementation((s: string | Uint8Array) => { lines.push(String(s)); return true; });
+ vi.spyOn(process, "exit").mockImplementation(((code?: number) => { throw new Error(`exit ${code}`); }) as never);
+ let err: unknown;
+ try { updateConfig(() => ({ result: undefined })); } catch (e) { err = e; }
+ expect(() => renderCliError(err)).toThrow("exit 1");
+ const text = lines.join("\n");
+ expect(text).toContain(path);
+ expect(text).not.toMatch(/\n\s+at /); // no stack trace
+ });
+
+ it("is re-entrant: saveConfig inside updateConfig does not wait on itself", async () => {
+ process.env.IX_CONFIG_LOCK_WAIT_MS = "300";
+ const { updateConfig, saveConfig, loadConfig } = await import("../config.js");
+ updateConfig((c) => {
+ saveConfig({ ...c, format: "json" });
+ return { save: { ...loadConfig(), endpoint: "http://127.0.0.1:8190" }, result: undefined };
+ });
+ expect(loadConfig()).toMatchObject({ format: "json", endpoint: "http://127.0.0.1:8190" });
+ expect(existsSync(await lockFile())).toBe(false);
+ });
});
describe("a config that does not parse", () => {
@@ -101,7 +195,7 @@ describe("a config that does not parse", () => {
const env: NodeJS.ProcessEnv = { ...process.env, IX_HOME: home, IX_ENDPOINT: "http://127.0.0.1:1" };
delete env.FORCE_COLOR;
for (const format of ["json", "llm"]) {
- const out = await execFileAsync(TSX, [main, "map", "--format", format], { cwd: repo, env })
+ const out = await tsx([main, "map", "--format", format], { cwd: repo, env })
.then(() => { throw new Error("ix map exited 0 on a broken config"); },
(e: { code?: number; stdout?: string }) => e);
expect(out.code).toBe(1);
diff --git a/ix-cli/src/cli/bootstrap.ts b/ix-cli/src/cli/bootstrap.ts
index 68df0b96..71f07a14 100644
--- a/ix-cli/src/cli/bootstrap.ts
+++ b/ix-cli/src/cli/bootstrap.ts
@@ -7,7 +7,7 @@ import { execFileSync } from "node:child_process";
import chalk from "chalk";
import { createClient } from "../client/factory.js";
import { renderBanner } from "./banner.js";
-import { canonicalWorkspacePath, getEndpoint, gitRootFor, loadConfig, loadWorkspaces, findWorkspaceForCwd, updateConfig, type IxConfig, type WorkspaceConfig } from "./config.js";
+import { canonicalWorkspacePath, getEndpoint, gitRootFor, loadConfig, loadWorkspaces, findWorkspaceForCwd, updateConfig, withConfigWriteLock, type IxConfig, type WorkspaceConfig } from "./config.js";
import { WorkspaceNotMappedError, workspaceNotMappedHint } from "./errors.js";
import { ixHome } from "./ix-home.js";
import { stderr } from "./stderr.js";
@@ -30,16 +30,21 @@ export function ensureLocalConfig(): boolean {
const configDir = ixHome();
const configPath = join(configDir, "config.yaml");
mkdirSync(configDir, { recursive: true });
- try {
- // 'wx' creates the file atomically and throws EEXIST if it already exists,
- // avoiding the existsSync-then-write TOCTOU (CodeQL js/file-system-race).
- writeFileSync(configPath, `endpoint: ${getEndpoint()}\nformat: text\n`, { flag: "wx" });
- noteRelocatedConfig(configPath);
- return true;
- } catch (err: any) {
- if (err?.code === "EEXIST") return false;
- throw err;
- }
+ // Under the config lock like every other write, so a registration that has
+ // just read "no file" is not overtaken by this one.
+ const created = withConfigWriteLock(() => {
+ try {
+ // 'wx' creates the file atomically and throws EEXIST if it already exists,
+ // avoiding the existsSync-then-write TOCTOU (CodeQL js/file-system-race).
+ writeFileSync(configPath, `endpoint: ${getEndpoint()}\nformat: text\n`, { flag: "wx" });
+ return true;
+ } catch (err: any) {
+ if (err?.code === "EEXIST") return false;
+ throw err;
+ }
+ });
+ if (created) noteRelocatedConfig(configPath);
+ return created;
}
/**
diff --git a/ix-cli/src/cli/config-lock.ts b/ix-cli/src/cli/config-lock.ts
new file mode 100644
index 00000000..3aea0411
--- /dev/null
+++ b/ix-cli/src/cli/config-lock.ts
@@ -0,0 +1,266 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+import { hostname } from "node:os";
+import { randomBytes } from "node:crypto";
+import { namedLockPath } from "./single-flight.js";
+
+/**
+ * The lock every write of config.yaml holds.
+ *
+ * A write is a read-modify-write: read the file, change it, rename a new copy
+ * over it. Two processes doing that at once each rename their own copy over the
+ * other's, and one of the two changes is gone -- eight parallel `ix map` runs
+ * registering eight repositories kept one or two of them. So nothing writes the
+ * file without this lock, ever: a writer that cannot get it waits, breaks it if
+ * its holder is gone, and otherwise fails with {@link ConfigLockError}. There is
+ * no "go ahead unlocked after a while"; that fallback is the race it exists to
+ * prevent, and on a slow machine it was taken.
+ *
+ * The critical section is synchronous and a few milliseconds long, so a holder
+ * cannot be interrupted part-way by anything short of the process dying, and a
+ * dead holder is recognised by its pid. A lock older than the bound is stale
+ * too, which covers a pid on another host, a reused pid, and a holder that was
+ * stopped and never resumed.
+ *
+ * Re-entrant within a process: `saveConfig` takes the lock itself, and
+ * `updateConfig` calls it while already holding it.
+ */
+
+/** config.yaml could not be locked for a write, and nothing was written. */
+export class ConfigLockError extends Error {
+ constructor(readonly configPath: string, readonly lockPath: string, readonly detail: string) {
+ super(`Could not lock ${configPath} to write it: ${detail}`);
+ this.name = "ConfigLockError";
+ }
+}
+
+interface LockMeta {
+ pid: number;
+ host: string;
+ /** Absent in a lock an older Ix wrote. */
+ token?: string;
+ startedAt: number;
+ label: string;
+}
+
+const DEFAULT_WAIT_MS = 30_000;
+const DEFAULT_STALE_MS = 30_000;
+/** A lock file with no readable meta yet is being written; give it this long. */
+const UNREADABLE_GRACE_MS = 5_000;
+
+/** A positive whole number of ms from the environment, or the default. Digits only: "30s" is not 30 ms. */
+function envMs(name: string, fallback: number): number {
+ const raw = process.env[name];
+ if (!raw || !/^\d+$/.test(raw)) return fallback;
+ const n = Number.parseInt(raw, 10);
+ return n > 0 ? n : fallback;
+}
+
+/** How long a writer waits for the lock before failing. */
+function waitMs(): number { return envMs("IX_CONFIG_LOCK_WAIT_MS", DEFAULT_WAIT_MS); }
+/** A lock untouched for this long is presumed abandoned. */
+function staleMs(): number { return envMs("IX_CONFIG_LOCK_STALE_MS", DEFAULT_STALE_MS); }
+
+const pause = new Int32Array(new SharedArrayBuffer(4));
+/** A synchronous sleep: config writes run inside synchronous callers. */
+function sleepSync(ms: number): void {
+ Atomics.wait(pause, 0, 0, Math.max(1, Math.floor(ms)));
+}
+
+/** Windows reports a file that is open elsewhere, or pending deletion, as these. Transient there. */
+function isTransientWindowsError(err: unknown): boolean {
+ if (process.platform !== "win32") return false;
+ const code = (err as NodeJS.ErrnoException | undefined)?.code;
+ return code === "EPERM" || code === "EACCES" || code === "EBUSY";
+}
+
+function pidAlive(pid: number): boolean {
+ if (!Number.isInteger(pid) || pid <= 0) return false;
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch (err) {
+ // EPERM: it exists, under another user.
+ return (err as NodeJS.ErrnoException | undefined)?.code === "EPERM";
+ }
+}
+
+interface Observed {
+ meta: LockMeta | null;
+ /** Identity of the file observed, so a breaker removes only what it judged. */
+ id: string;
+ mtimeMs: number;
+}
+
+function observe(path: string): Observed | null {
+ let st;
+ try { st = statSync(path); } catch { return null; }
+ let meta: LockMeta | null = null;
+ try {
+ const parsed = JSON.parse(readFileSync(path, "utf-8"));
+ // An older Ix wrote this lock without a token; its pid still tells.
+ if (parsed && typeof parsed === "object" && typeof parsed.pid === "number") meta = parsed as LockMeta;
+ } catch { /* being written, or not ours */ }
+ return { meta, id: `${meta?.token ?? ""}:${st.ino}:${st.mtimeMs}:${st.size}`, mtimeMs: st.mtimeMs };
+}
+
+/** Why the observed holder is gone, or undefined while it may still be working. */
+function staleReason(o: Observed): string | undefined {
+ const age = Date.now() - o.mtimeMs;
+ if (!o.meta) return age > Math.min(UNREADABLE_GRACE_MS, staleMs()) ? "an unreadable lock file" : undefined;
+ if (o.meta.host === hostname() && !pidAlive(o.meta.pid)) return `its holder, pid ${o.meta.pid}, is gone`;
+ if (age > staleMs()) return `it is ${Math.round(age / 1000)}s old`;
+ return undefined;
+}
+
+/**
+ * Create `path` exclusively with `meta` in it. True when created, false when it
+ * already exists (or, on Windows, is still being deleted); anything else throws.
+ */
+function createExclusive(path: string, meta: LockMeta): boolean {
+ let fd: number;
+ try {
+ fd = openSync(path, "wx", 0o600);
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException | undefined)?.code === "EEXIST" || isTransientWindowsError(err)) return false;
+ throw err;
+ }
+ try { writeSync(fd, JSON.stringify(meta)); } finally { closeSync(fd); }
+ return true;
+}
+
+function removeIfSame(path: string, id: string): void {
+ const now = observe(path);
+ if (now && now.id === id) rmSync(path, { force: true });
+}
+
+/**
+ * Remove the lock at `path` if it is still the one judged stale. Serialised by
+ * a second, short-lived lock, so that two waiters that both judged the same
+ * dead holder cannot have one of them delete the lock the other just took.
+ */
+function breakStale(path: string, judged: Observed, meta: LockMeta): void {
+ const breaker = `${path}.break`;
+ if (!createExclusive(breaker, meta)) {
+ // Another waiter is breaking it. Its own breaker is abandoned only if that
+ // waiter died in the few syscalls it holds it for.
+ const b = observe(breaker);
+ if (b && staleReason(b)) {
+ try { removeIfSame(breaker, b.id); } catch { /* next round */ }
+ }
+ return;
+ }
+ try {
+ removeIfSame(path, judged.id);
+ } catch { /* retried by the caller's loop */ } finally {
+ try { rmSync(breaker, { force: true }); } catch { /* broken as stale later */ }
+ }
+}
+
+function release(path: string, token: string): void {
+ for (let attempt = 0; ; attempt++) {
+ try {
+ const o = observe(path);
+ if (o?.meta?.token !== undefined && o.meta.token === token) rmSync(path, { force: true });
+ return;
+ } catch (err) {
+ // Left behind, it is broken as soon as this process exits.
+ if (!isTransientWindowsError(err) || attempt >= 20) return;
+ sleepSync(10 + attempt * 10);
+ }
+ }
+}
+
+function acquire(configPath: string, label: string): () => void {
+ const path = namedLockPath("config", configPath);
+ try {
+ // 0700, like saveConfig's: this can be what creates ~/.ix itself.
+ mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+ } catch (err) {
+ throw new ConfigLockError(configPath, path, `the lock directory ${dirname(path)} cannot be created (${(err as Error).message})`);
+ }
+ const token = randomBytes(12).toString("hex");
+ const meta: LockMeta = {
+ pid: process.pid,
+ host: hostname(),
+ token,
+ startedAt: Date.now(),
+ label,
+ };
+ const deadline = Date.now() + waitMs();
+ let delay = 5;
+ let last: Observed | null = null;
+ for (;;) {
+ let created: boolean;
+ try {
+ created = createExclusive(path, meta);
+ } catch (err) {
+ throw new ConfigLockError(configPath, path, `the lock file ${path} cannot be created (${(err as Error).message})`);
+ }
+ if (created) return () => release(path, token);
+
+ const held = observe(path);
+ if (held) {
+ last = held;
+ if (staleReason(held)) {
+ breakStale(path, held, meta);
+ continue;
+ }
+ }
+ if (Date.now() >= deadline) {
+ const holder = last?.meta
+ ? `pid ${last.meta.pid} on ${last.meta.host}${last.meta.label ? ` (${last.meta.label})` : ""}`
+ : "another process";
+ throw new ConfigLockError(
+ configPath, path,
+ `${holder} has held its lock for more than ${Math.round(waitMs() / 1000)}s. Nothing was written. ` +
+ `If no other ix command is running, delete ${path} and run the command again.`,
+ );
+ }
+ sleepSync(Math.min(delay + Math.random() * delay, Math.max(1, deadline - Date.now())));
+ delay = Math.min(delay * 1.5, 250);
+ }
+}
+
+let depth = 0;
+
+/**
+ * Run `fn` holding the config lock. Synchronous only: the lock is released
+ * when `fn` returns, so a promise it returned would run unlocked.
+ */
+export function withConfigLock<T>(configPath: string, label: string, fn: () => T): T {
+ if (depth > 0) {
+ depth++;
+ try { return fn(); } finally { depth--; }
+ }
+ const releaseLock = acquire(configPath, label);
+ depth = 1;
+ try {
+ return fn();
+ } finally {
+ depth = 0;
+ releaseLock();
+ }
+}
+
+/**
+ * Rename `from` over `to`, retrying the errors Windows gives while another
+ * process has `to` open (a reader, an indexer, an antivirus scan). Elsewhere a
+ * rename either works or fails for good.
+ */
+export function renameWithRetry(from: string, to: string): void {
+ const deadline = Date.now() + 5_000;
+ let delay = 10;
+ for (;;) {
+ try {
+ renameSync(from, to);
+ return;
+ } catch (err) {
+ if (!isTransientWindowsError(err) || Date.now() >= deadline) throw err;
+ sleepSync(delay);
+ delay = Math.min(delay * 2, 200);
+ }
+ }
+}
diff --git a/ix-cli/src/cli/config.ts b/ix-cli/src/cli/config.ts
index d2c9c53a..ea3976e3 100644
--- a/ix-cli/src/cli/config.ts
+++ b/ix-cli/src/cli/config.ts
@@ -1,6 +1,6 @@
// Copyright 2026 Ix Infrastructure Inc.
-import { readFileSync, writeFileSync, existsSync, rmSync, chmodSync, renameSync, realpathSync, mkdirSync, statSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, rmSync, chmodSync, realpathSync, mkdirSync, statSync } from "node:fs";
import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
import { createHash, randomBytes } from "node:crypto";
import { execFileSync } from "node:child_process";
@@ -8,7 +8,9 @@ import { parse, stringify } from "yaml";
import { IxClient } from "../client/api.js";
import { ixHome } from "./ix-home.js";
import { isLocalEndpoint } from "./backend-version.js";
-import { acquireLockAt, namedLockPath } from "./single-flight.js";
+import { renameWithRetry, withConfigLock } from "./config-lock.js";
+
+export { ConfigLockError } from "./config-lock.js";
/**
* The key of a project root's per-root state files. Canonical first: `ix
@@ -249,9 +251,6 @@ export function resetConfigMemo(): void {
configMemo = undefined;
}
-/** How long a config write waits for another process's before going ahead anyway. */
-const CONFIG_LOCK_WAIT_MS = 5_000;
-
/**
* Read config.yaml, apply `mutate`, and write it back, with no other Ix
* process writing it in between.
@@ -260,36 +259,30 @@ const CONFIG_LOCK_WAIT_MS = 5_000;
* runs registering eight new repositories each read the file, each appended
* its own workspace, and each renamed its copy over the others' -- leaving one
* or two of the eight. Under the lock each one reads what the previous one
- * wrote. The lock is the single-flight link lock, so a crashed holder is
- * detected by its dead pid; past {@link CONFIG_LOCK_WAIT_MS} the write goes
- * ahead unlocked rather than hang a command.
+ * wrote. A writer that cannot get the lock waits, breaks it if its holder is
+ * gone, and otherwise fails with `ConfigLockError`; it never writes unlocked
+ * (see config-lock.ts).
*
* `mutate` gets a fresh read, never the memoised one, and returns the config
- * to save, or undefined to leave the file as it is.
+ * to save, or undefined to leave the file as it is. It must be synchronous.
*/
export function updateConfig<T>(mutate: (config: IxConfig) => { save?: IxConfig; result: T }): T {
const configPath = join(ixHome(), "config.yaml");
- const lock = waitForLock(namedLockPath("config", configPath), `config write ${configPath}`);
- try {
+ return withConfigLock(configPath, `config write ${configPath}`, () => {
configMemo = undefined;
const { save, result } = mutate(loadConfig());
if (save) saveConfig(save);
return result;
- } finally {
- lock?.release();
- }
+ });
}
-function waitForLock(path: string, label: string): { release(): void } | null {
- const deadline = Date.now() + CONFIG_LOCK_WAIT_MS;
- const pause = new Int32Array(new SharedArrayBuffer(4));
- for (;;) {
- const handle = acquireLockAt(path, label);
- if (handle) return handle;
- if (Date.now() >= deadline) return null;
- // A synchronous wait: registration runs inside synchronous callers.
- Atomics.wait(pause, 0, 0, 5 + Math.floor(Math.random() * 20));
- }
+/**
+ * Run `fn` holding the config lock, for a write that is not a plain
+ * `updateConfig` -- creating the file, say. Synchronous only.
+ */
+export function withConfigWriteLock<T>(fn: () => T): T {
+ const configPath = join(ixHome(), "config.yaml");
+ return withConfigLock(configPath, `config write ${configPath}`, fn);
}
// Keys the OSS schema owns. For these, the in-memory `config` argument is
@@ -308,9 +301,18 @@ const OSS_OWNED_KEYS = new Set<keyof IxConfig>([
"auth",
]);
+/**
+ * Write `config` over config.yaml, keeping the keys OSS does not own. Takes the
+ * config lock (re-entrantly, so `updateConfig` can call it), and re-reads the
+ * file under it, so the keys it preserves are the current ones.
+ */
export function saveConfig(config: IxConfig): void {
const configDir = ixHome();
const configPath = join(configDir, "config.yaml");
+ withConfigLock(configPath, `config write ${configPath}`, () => writeConfigLocked(config, configDir, configPath));
+}
+
+function writeConfigLocked(config: IxConfig, configDir: string, configPath: string): void {
// 0700, to match the 0600 the config itself is written with below: the file
// holds credentials (Pro's instances carry a tunnel JWT and a long-lived IdP
// refresh token), and a directory created at the default umask (typically
@@ -351,10 +353,14 @@ export function saveConfig(config: IxConfig): void {
// js/file-system-race). Same-dir keeps the rename atomic; rename replaces on
// POSIX and Windows alike, and inherits the temp's 0600 mode (tightening any
// pre-existing group/world-readable config).
- const tmpPath = `${configPath}.${process.pid}.tmp`;
+ //
+ // On Windows the rename is MoveFileEx with REPLACE_EXISTING, which fails with
+ // EPERM/EBUSY while another process has the target open -- an unlocked
+ // reader, an indexer, antivirus -- so it is retried for a few seconds.
+ const tmpPath = `${configPath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
writeFileSync(tmpPath, stringify(merged), { mode: 0o600 });
try {
- renameSync(tmpPath, configPath);
+ renameWithRetry(tmpPath, configPath);
} catch (err) {
try { rmSync(tmpPath, { force: true }); } catch { /* best effort */ }
throw err;
diff --git a/ix-cli/src/cli/errors.ts b/ix-cli/src/cli/errors.ts
index 894d61c7..d170fd5a 100644
--- a/ix-cli/src/cli/errors.ts
+++ b/ix-cli/src/cli/errors.ts
@@ -337,6 +337,19 @@ export function configParseError(path: string, detail: string): StructuredError
};
}
+/**
+ * config.yaml could not be locked for a write. Nothing was written: Ix never
+ * writes the file unlocked, because that is how parallel registrations lost
+ * each other's workspaces.
+ */
+export function configLockError(detail: string): StructuredError {
+ return {
+ error: "config_lock_timeout",
+ message: `Ix could not lock its config to write it: ${detail}`,
+ next: "Wait for the other ix command to finish and run this one again.",
+ };
+}
+
/**
* The backend answered 401 `local_token_required`: it was started with
* IX_LOCAL_TOKEN and this CLI sent no token, or a different one.
@@ -393,6 +406,13 @@ export function renderCliError(err: unknown, debug = false, endpoint?: string):
process.exit(1);
}
+ if (e?.name === "ConfigLockError") {
+ const locked = configLockError(e.detail);
+ if (!emitLlmError(locked.error, locked.message, locked.next)) renderStructuredError(locked);
+ if (debug) writeDebugDetail(err);
+ process.exit(1);
+ }
+
if (e?.name === "LocalTokenRequiredError") {
const refused = localTokenRequiredError(endpoint);
if (!emitLlmError(refused.error, refused.message, refused.next)) {