@nvae/llmswitch 0.2.0 → 0.5.0

package/dist/bridge/state.js

@@ -1,29 +1,70 @@
-import { existsSync, readFileSync } from "node:fs";
+import { chmodSync, existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
+import { randomBytes, timingSafeEqual } from "node:crypto";
 import { atomicWriteFile, ensureDir } from "../utils/fs.js";
 import { getAppConfigRoot } from "../utils/paths.js";
 import { DEFAULT_BRIDGE_HOST, DEFAULT_BRIDGE_PORT, emptyUpstreams, } from "./types.js";
+const STATE_VERSION = 2;
+const MAX_PID = 2_147_483_647;
+const LOCK_STALE_MS = 120_000;
+const LOCK_DEFAULT_TIMEOUT_MS = 5_000;
+export class BridgeStateConflictError extends Error {
+    constructor(expected, actual) {
+        super(`Bridge 状态版本冲突：期望 revision ${expected}，实际 ${actual}`);
+        this.name = "BridgeStateConflictError";
+    }
+}
+export class BridgeLockTimeoutError extends Error {
+    constructor(message = "获取 bridge 锁超时") {
+        super(message);
+        this.name = "BridgeLockTimeoutError";
+    }
+}
 export function getBridgeDir() {
     return join(getAppConfigRoot(), "bridge");
 }
 export function getBridgeStatePath() {
     return join(getBridgeDir(), "state.json");
 }
+/** @deprecated v1 single-object upstream file; read once for migration only. */
 export function getBridgeUpstreamPath() {
     return join(getBridgeDir(), "upstream.json");
 }
+/** @deprecated PID is diagnostic only; identity lives in state.instance. */
 export function getBridgePidPath() {
     return join(getBridgeDir(), "bridge.pid");
 }
+export function getBridgeLockPath() {
+    return join(getBridgeDir(), "state.lock");
+}
+export function getTransactionsDir() {
+    return join(getAppConfigRoot(), "transactions");
+}
+// --- tokens -----------------------------------------------------------------
+/** 32 random bytes as unpadded base64url. */
+export function generateBridgeToken() {
+    return randomBytes(32).toString("base64url");
+}
+export function isValidBridgeToken(token) {
+    return typeof token === "string" && /^[A-Za-z0-9_-]{43}$/.test(token);
+}
+/** Constant-time token comparison; length mismatch is a fast, safe reject. */
+export function constantTimeTokenEqual(a, b) {
+    if (typeof a !== "string" || typeof b !== "string")
+        return false;
+    const bufA = Buffer.from(a, "utf8");
+    const bufB = Buffer.from(b, "utf8");
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+// --- upstream normalization -------------------------------------------------
 function isLegacyUpstream(raw) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return false;
     const row = raw;
     return typeof row.baseUrl === "string" && !("codex" in row) && !("claude" in row);
 }
-/**
- * Normalize disk/runtime upstream payloads (legacy single object → per-tool map).
- */
 export function normalizeBridgeUpstreams(raw) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
         return emptyUpstreams();
@@ -37,89 +78,324 @@ export function normalizeBridgeUpstreams(raw) {
         claude: row.claude ?? null,
     };
 }
-export function readBridgeUpstreams() {
-    const path = getBridgeUpstreamPath();
-    if (!existsSync(path))
-        return emptyUpstreams();
-    try {
-        return normalizeBridgeUpstreams(JSON.parse(readFileSync(path, "utf8")));
-    }
-    catch {
-        return emptyUpstreams();
-    }
+/** Legacy upstreams cannot authenticate until reapplied. */
+function markUpstreamMigrationRequired(upstream) {
+    if (!upstream)
+        return null;
+    return { ...upstream, clientToken: null, migrationRequired: true };
 }
-export function writeBridgeUpstreams(upstreams) {
-    ensureDir(getBridgeDir());
-    atomicWriteFile(getBridgeUpstreamPath(), JSON.stringify({
-        codex: upstreams.codex,
-        claude: upstreams.claude,
-    }, null, 2) + "\n");
+// --- persistence ------------------------------------------------------------
+function isValidPid(pid) {
+    return (typeof pid === "number" &&
+        Number.isInteger(pid) &&
+        pid >= 1 &&
+        pid <= MAX_PID);
 }
-export function readBridgeUpstream(tool = "codex") {
-    return readBridgeUpstreams()[tool];
+function defaultListener() {
+    return {
+        bindHost: process.env.LLM_SWITCH_BRIDGE_HOST || DEFAULT_BRIDGE_HOST,
+        advertiseHost: process.env.LLM_SWITCH_BRIDGE_HOST || DEFAULT_BRIDGE_HOST,
+        port: Number(process.env.LLM_SWITCH_BRIDGE_PORT) || DEFAULT_BRIDGE_PORT,
+        allowRemote: false,
+    };
 }
-export function writeBridgeUpstream(tool, upstream) {
-    const current = readBridgeUpstreams();
-    current[tool] = upstream;
-    writeBridgeUpstreams(current);
-    const state = readBridgeStateRaw();
-    writeBridgeState({
+function withFlatAliases(state) {
+    return {
         ...state,
-        upstreams: current,
-    });
+        port: state.listener.port,
+        pid: state.instance?.pid ?? null,
+        host: state.listener.bindHost,
+    };
 }
-function readBridgeStateRaw() {
-    const path = getBridgeStatePath();
-    const defaults = {
-        port: Number(process.env.LLM_SWITCH_BRIDGE_PORT) || DEFAULT_BRIDGE_PORT,
-        host: process.env.LLM_SWITCH_BRIDGE_HOST || DEFAULT_BRIDGE_HOST,
-        pid: null,
-        upstreams: readBridgeUpstreams(),
+function parseInstance(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const row = raw;
+    if (typeof row.id !== "string" ||
+        !isValidBridgeToken(row.controlToken) ||
+        !isValidPid(row.pid)) {
+        return null;
+    }
+    return {
+        id: row.id,
+        controlToken: row.controlToken,
+        pid: row.pid,
+        startedAt: typeof row.startedAt === "string" ? row.startedAt : "",
+    };
+}
+function parseListener(raw) {
+    const fallback = defaultListener();
+    if (!raw || typeof raw !== "object")
+        return fallback;
+    const row = raw;
+    return {
+        bindHost: typeof row.bindHost === "string" ? row.bindHost : fallback.bindHost,
+        advertiseHost: typeof row.advertiseHost === "string"
+            ? row.advertiseHost
+            : fallback.advertiseHost,
+        port: typeof row.port === "number" ? row.port : fallback.port,
+        allowRemote: row.allowRemote === true,
     };
-    if (!existsSync(path))
-        return defaults;
+}
+/**
+ * Read the one-time v1 migration state: legacy upstream.json, flagged so it can
+ * be inspected but never authenticate a client until reapplied.
+ */
+function readLegacyMigrationState() {
+    const legacyPath = getBridgeUpstreamPath();
+    if (!existsSync(legacyPath))
+        return null;
     try {
-        const raw = JSON.parse(readFileSync(path, "utf8"));
-        const upstreams = raw.upstreams
-            ? normalizeBridgeUpstreams(raw.upstreams)
-            : raw.upstream
-                ? normalizeBridgeUpstreams(raw.upstream)
-                : readBridgeUpstreams();
-        return {
-            port: raw.port || defaults.port,
-            host: raw.host || defaults.host,
-            pid: raw.pid ?? null,
-            upstreams,
-        };
+        const upstreams = normalizeBridgeUpstreams(JSON.parse(readFileSync(legacyPath, "utf8")));
+        return withFlatAliases({
+            version: STATE_VERSION,
+            revision: 0,
+            listener: defaultListener(),
+            instance: null,
+            upstreams: {
+                codex: markUpstreamMigrationRequired(upstreams.codex),
+                claude: markUpstreamMigrationRequired(upstreams.claude),
+            },
+            pending: null,
+        });
     }
     catch {
-        return defaults;
+        return null;
     }
 }
 export function readBridgeState() {
-    return readBridgeStateRaw();
+    const path = getBridgeStatePath();
+    if (!existsSync(path)) {
+        const legacy = readLegacyMigrationState();
+        if (legacy)
+            return legacy;
+        return withFlatAliases({
+            version: STATE_VERSION,
+            revision: 0,
+            listener: defaultListener(),
+            instance: null,
+            upstreams: emptyUpstreams(),
+            pending: null,
+        });
+    }
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const pending = raw.pending && typeof raw.pending === "object"
+            ? {
+                revision: Number(raw.pending.revision) || 0,
+                upstreams: normalizeBridgeUpstreams(raw.pending.upstreams),
+                transactionId: raw.pending
+                    .transactionId,
+            }
+            : null;
+        return withFlatAliases({
+            version: STATE_VERSION,
+            revision: typeof raw.revision === "number" ? raw.revision : 0,
+            listener: parseListener(raw.listener),
+            instance: parseInstance(raw.instance),
+            upstreams: normalizeBridgeUpstreams(raw.upstreams),
+            pending: pending,
+        });
+    }
+    catch {
+        return withFlatAliases({
+            version: STATE_VERSION,
+            revision: 0,
+            listener: defaultListener(),
+            instance: null,
+            upstreams: emptyUpstreams(),
+            pending: null,
+        });
+    }
 }
-export function writeBridgeState(state) {
+function persistState(next) {
     ensureDir(getBridgeDir());
-    const upstreams = normalizeBridgeUpstreams(state.upstreams);
-    atomicWriteFile(getBridgeStatePath(), JSON.stringify({
-        port: state.port,
-        host: state.host,
-        pid: state.pid,
-        upstreams,
-    }, null, 2) + "\n");
-    writeBridgeUpstreams(upstreams);
-    if (state.pid != null) {
-        atomicWriteFile(getBridgePidPath(), String(state.pid) + "\n");
-    }
-}
-/** Codex-facing base URL (includes /v1). */
+    try {
+        chmodSync(getBridgeDir(), 0o700);
+    }
+    catch {
+        // best effort; Windows relies on user-dir ACLs
+    }
+    const payload = {
+        version: STATE_VERSION,
+        revision: next.revision,
+        listener: next.listener,
+        instance: next.instance,
+        upstreams: {
+            codex: next.upstreams.codex,
+            claude: next.upstreams.claude,
+        },
+        pending: next.pending,
+    };
+    atomicWriteFile(getBridgeStatePath(), JSON.stringify(payload, null, 2) + "\n");
+}
+/**
+ * Persist state with an incremented revision. Rejects stale writes: the input
+ * revision must equal the on-disk revision (compare-and-set).
+ */
+export function writeBridgeState(state) {
+    const current = readBridgeState();
+    if (existsSync(getBridgeStatePath()) && state.revision !== current.revision) {
+        throw new BridgeStateConflictError(current.revision, state.revision);
+    }
+    const next = withFlatAliases({
+        version: STATE_VERSION,
+        revision: current.revision + 1,
+        listener: state.listener,
+        instance: state.instance,
+        upstreams: normalizeBridgeUpstreams(state.upstreams),
+        pending: state.pending,
+    });
+    persistState(next);
+    return next;
+}
+/**
+ * Atomically mutate state under compare-and-set. `expectedRevision` defaults to
+ * the current on-disk revision.
+ */
+export function updateBridgeState(mutate, expectedRevision) {
+    const current = readBridgeState();
+    if (expectedRevision !== undefined && expectedRevision !== current.revision) {
+        throw new BridgeStateConflictError(current.revision, expectedRevision);
+    }
+    const mutated = mutate(current);
+    const next = withFlatAliases({
+        version: STATE_VERSION,
+        revision: current.revision + 1,
+        listener: mutated.listener,
+        instance: mutated.instance,
+        upstreams: normalizeBridgeUpstreams(mutated.upstreams),
+        pending: mutated.pending,
+    });
+    persistState(next);
+    return next;
+}
+// --- upstream facade (compat) ----------------------------------------------
+export function readBridgeUpstreams() {
+    return readBridgeState().upstreams;
+}
+export function readBridgeUpstream(tool = "codex") {
+    return readBridgeUpstreams()[tool];
+}
+export function writeBridgeUpstream(tool, upstream) {
+    return updateBridgeState((current) => ({
+        ...current,
+        upstreams: { ...current.upstreams, [tool]: upstream },
+    }));
+}
+export function writeBridgeUpstreams(upstreams) {
+    return updateBridgeState((current) => ({ ...current, upstreams }));
+}
+// --- URLs -------------------------------------------------------------------
+function hostForUrl(host) {
+    return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+/** Codex-facing base URL (includes /v1), using the connectable advertise host. */
 export function bridgeBaseUrl(state) {
     const s = state || readBridgeState();
-    return `http://${s.host}:${s.port}/v1`;
+    return `http://${hostForUrl(s.listener.advertiseHost)}:${s.listener.port}/v1`;
 }
 /** Claude-facing root URL (no /v1; client appends /v1/messages). */
 export function bridgeRootUrl(state) {
     const s = state || readBridgeState();
-    return `http://${s.host}:${s.port}`;
+    return `http://${hostForUrl(s.listener.advertiseHost)}:${s.listener.port}`;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function hasPendingJournal(transactionId) {
+    if (!transactionId)
+        return false;
+    return existsSync(join(getTransactionsDir(), `${transactionId}.json`));
+}
+function readLockRecord(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Acquire the exclusive bridge lock (global lock in the design's lock order).
+ * Reclaims a stale lock when: (a) the owner PID is dead and an associated
+ * transaction journal exists (immediate journal recovery), or (b) the owner PID
+ * is dead and the lock is older than two minutes. Never steals a live lock.
+ */
+export function acquireBridgeLock(options = {}) {
+    ensureDir(getBridgeDir());
+    const lockPath = getBridgeLockPath();
+    const deadline = Date.now() + (options.timeoutMs ?? LOCK_DEFAULT_TIMEOUT_MS);
+    const lockId = randomBytes(8).toString("hex");
+    const record = {
+        lockId,
+        pid: process.pid,
+        instanceId: options.instanceId ?? null,
+        transactionId: options.transactionId ?? null,
+        createdAt: new Date().toISOString(),
+    };
+    const serialized = JSON.stringify(record) + "\n";
+    for (;;) {
+        try {
+            writeFileSync(lockPath, serialized, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            return makeLock(lockPath, lockId);
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        const existing = readLockRecord(lockPath);
+        if (existing && reclaimable(existing, lockPath)) {
+            // Atomically take over by replacing via temp rename.
+            const tmp = `${lockPath}.${lockId}.tmp`;
+            writeFileSync(tmp, serialized, { encoding: "utf8", mode: 0o600 });
+            renameSync(tmp, lockPath);
+            const confirmed = readLockRecord(lockPath);
+            if (confirmed?.lockId === lockId)
+                return makeLock(lockPath, lockId);
+        }
+        if (Date.now() >= deadline) {
+            throw new BridgeLockTimeoutError();
+        }
+        sleepSync(25);
+    }
+}
+function reclaimable(record, lockPath) {
+    if (isValidPid(record.pid) && pidAlive(record.pid))
+        return false;
+    // Dead owner with a pending journal: recover immediately.
+    if (hasPendingJournal(record.transactionId))
+        return true;
+    // Orphan lock without a journal: only after the stale age.
+    let age = Number.POSITIVE_INFINITY;
+    try {
+        age = Date.now() - statSync(lockPath).mtimeMs;
+    }
+    catch {
+        age = Number.POSITIVE_INFINITY;
+    }
+    const recordedAge = record.createdAt
+        ? Date.now() - Date.parse(record.createdAt)
+        : Number.POSITIVE_INFINITY;
+    return Math.max(age, recordedAge) > LOCK_STALE_MS;
+}
+function makeLock(lockPath, lockId) {
+    return {
+        release() {
+            const current = readLockRecord(lockPath);
+            if (current?.lockId === lockId) {
+                rmSync(lockPath, { force: true });
+            }
+        },
+    };
+}
+function sleepSync(ms) {
+    const shared = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(shared, 0, 0, ms);
 }