@astralyn/sash 0.1.0

package/dist/state-lock.js

@@ -0,0 +1,331 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { errnoCode, errorMessage } from "./error-utils.js";
+import { isPlainObject } from "./json-shape.js";
+import { isProcessAlive } from "./process.js";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_POLL_MS = 50;
+const syncWaitCell = new Int32Array(new SharedArrayBuffer(4));
+function ownerDescription(owner) {
+    const pid = owner?.pid ?? "unknown";
+    const purpose = owner?.purpose === undefined ? "unknown" : JSON.stringify(owner.purpose);
+    return `owner PID ${pid}, purpose ${purpose}`;
+}
+function lockError(file, message, owner) {
+    return new Error(`State lock ${message}: ${file} (${ownerDescription(owner)})`);
+}
+function normalizeOptions(file, options) {
+    if (typeof options !== "object" ||
+        options === null ||
+        typeof options.purpose !== "string" ||
+        !options.purpose.trim()) {
+        throw lockError(file, "requires a non-empty purpose");
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 0) {
+        throw lockError(file, "requires timeoutMs to be a non-negative integer");
+    }
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    if (!Number.isInteger(pollMs) || pollMs <= 0) {
+        throw lockError(file, "requires pollMs to be a positive integer");
+    }
+    return {
+        purpose: options.purpose.trim(),
+        timeoutMs,
+        pollMs,
+    };
+}
+function partialOwner(value) {
+    if (!isPlainObject(value))
+        return undefined;
+    const pid = typeof value.pid === "number" && Number.isInteger(value.pid) && value.pid > 0
+        ? value.pid
+        : undefined;
+    const purpose = typeof value.purpose === "string" && value.purpose ? value.purpose : undefined;
+    return pid === undefined && purpose === undefined ? undefined : { pid, purpose };
+}
+function parseLockRecord(value) {
+    if (!isPlainObject(value))
+        return undefined;
+    if (value.version !== 1)
+        return undefined;
+    if (typeof value.pid !== "number" || !Number.isInteger(value.pid) || value.pid <= 0) {
+        return undefined;
+    }
+    if (typeof value.token !== "string" || !value.token)
+        return undefined;
+    if (typeof value.purpose !== "string" || !value.purpose)
+        return undefined;
+    if (typeof value.acquiredAt !== "string" || !value.acquiredAt)
+        return undefined;
+    return {
+        version: 1,
+        pid: value.pid,
+        token: value.token,
+        purpose: value.purpose,
+        acquiredAt: value.acquiredAt,
+    };
+}
+function readExistingStateLock(file) {
+    try {
+        if (!fs.lstatSync(file).isFile()) {
+            return { kind: "corrupt", reason: "lock path is not a regular file" };
+        }
+        let text;
+        try {
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch (err) {
+            if (errnoCode(err) === "ENOENT")
+                return { kind: "missing" };
+            return { kind: "corrupt", reason: `lock record is not valid JSON (${errorMessage(err)})` };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (err) {
+            return { kind: "corrupt", reason: `lock record is not valid JSON (${errorMessage(err)})` };
+        }
+        const record = parseLockRecord(parsed);
+        return record
+            ? { kind: "valid", record }
+            : {
+                kind: "corrupt",
+                reason: "lock record has an invalid shape",
+                owner: partialOwner(parsed),
+            };
+    }
+    catch (err) {
+        if (errnoCode(err) === "ENOENT")
+            return { kind: "missing" };
+        return { kind: "corrupt", reason: `lock record cannot be read (${errorMessage(err)})` };
+    }
+}
+function removeMatchingStateLock(file, token) {
+    const existing = readExistingStateLock(file);
+    if (existing.kind !== "valid" || existing.record.token !== token)
+        return;
+    try {
+        fs.unlinkSync(file);
+    }
+    catch (err) {
+        if (errnoCode(err) !== "ENOENT") {
+            throw lockError(file, `could not be released (${errorMessage(err)})`, existing.record);
+        }
+    }
+}
+function createLease(file, record) {
+    return {
+        file,
+        record,
+        release: () => {
+            removeMatchingStateLock(file, record.token);
+        },
+    };
+}
+function tryCreateStateLock(file, options) {
+    const record = {
+        version: 1,
+        pid: process.pid,
+        token: crypto.randomBytes(24).toString("hex"),
+        purpose: options.purpose,
+        acquiredAt: new Date().toISOString(),
+    };
+    const temp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${record.token}.tmp`);
+    let fd;
+    try {
+        fd = fs.openSync(temp, "wx", 0o600);
+        fs.writeFileSync(fd, `${JSON.stringify(record)}\n`, "utf8");
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fd = undefined;
+        fs.linkSync(temp, file);
+        return createLease(file, record);
+    }
+    catch (err) {
+        if (errnoCode(err) === "EEXIST" && fs.existsSync(file))
+            return undefined;
+        throw lockError(file, `could not create (${errorMessage(err)})`, record);
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+            }
+        }
+        try {
+            fs.unlinkSync(temp);
+        }
+        catch {
+        }
+    }
+}
+function staleLockFile(file) {
+    return path.join(path.dirname(file), `.${path.basename(file)}.stale.${process.pid}.${crypto.randomBytes(8).toString("hex")}`);
+}
+function reclaimDeadStateLock(file, owner) {
+    const current = readExistingStateLock(file);
+    if (current.kind === "missing")
+        return;
+    if (current.kind !== "valid" ||
+        current.record.token !== owner.token ||
+        current.record.pid !== owner.pid) {
+        return;
+    }
+    if (isProcessAlive(current.record.pid))
+        return;
+    const stale = staleLockFile(file);
+    try {
+        fs.renameSync(file, stale);
+    }
+    catch (err) {
+        if (errnoCode(err) === "ENOENT")
+            return;
+        throw lockError(file, `could not move dead owner aside (${errorMessage(err)})`, owner);
+    }
+    const moved = readExistingStateLock(stale);
+    if (moved.kind !== "valid" ||
+        moved.record.token !== owner.token ||
+        moved.record.pid !== owner.pid) {
+        try {
+            fs.renameSync(stale, file);
+        }
+        catch {
+        }
+        throw lockError(file, "changed while reclaiming a dead owner; refusing to delete it", owner);
+    }
+    try {
+        fs.unlinkSync(stale);
+    }
+    catch (err) {
+        if (errnoCode(err) !== "ENOENT") {
+            throw lockError(file, `could not remove stale record (${errorMessage(err)})`, owner);
+        }
+    }
+}
+function inspectExistingLock(file) {
+    const existing = readExistingStateLock(file);
+    if (existing.kind !== "valid" || isProcessAlive(existing.record.pid))
+        return existing;
+    reclaimDeadStateLock(file, existing.record);
+    return { kind: "missing" };
+}
+function ensureParentDirectory(file) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+    }
+    catch (err) {
+        throw lockError(file, `could not create parent directory (${errorMessage(err)})`);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function sleepSync(ms) {
+    Atomics.wait(syncWaitCell, 0, 0, ms);
+}
+function busyError(file, owner) {
+    return lockError(file, "is busy", owner);
+}
+export function readStateLockRecord(file) {
+    const existing = readExistingStateLock(file);
+    if (existing.kind === "missing")
+        return undefined;
+    if (existing.kind === "corrupt") {
+        throw lockError(file, `is corrupt and cannot be trusted (${existing.reason})`, existing.owner);
+    }
+    return existing.record;
+}
+function createStateLockAcquisition(file, options) {
+    const normalized = normalizeOptions(file, options);
+    ensureParentDirectory(file);
+    const deadline = Date.now() + normalized.timeoutMs;
+    let sawCorruptRecord = false;
+    return () => {
+        const lease = tryCreateStateLock(file, normalized);
+        if (lease)
+            return { kind: "acquired", lease };
+        const existing = inspectExistingLock(file);
+        if (existing.kind === "missing") {
+            sawCorruptRecord = false;
+            return { kind: "retry" };
+        }
+        const remaining = deadline - Date.now();
+        if (existing.kind === "corrupt") {
+            if (sawCorruptRecord || remaining <= 0) {
+                throw lockError(file, `is corrupt and cannot be reclaimed (${existing.reason})`, existing.owner);
+            }
+            sawCorruptRecord = true;
+            return { kind: "wait", delayMs: Math.min(normalized.pollMs, remaining) };
+        }
+        sawCorruptRecord = false;
+        if (remaining <= 0)
+            throw busyError(file, existing.record);
+        return { kind: "wait", delayMs: Math.min(normalized.pollMs, remaining) };
+    };
+}
+export async function acquireStateLock(file, options) {
+    const next = createStateLockAcquisition(file, options);
+    for (;;) {
+        const step = next();
+        if (step.kind === "acquired")
+            return step.lease;
+        if (step.kind === "wait")
+            await sleep(step.delayMs);
+    }
+}
+export function acquireStateLockSync(file, options) {
+    const next = createStateLockAcquisition(file, options);
+    for (;;) {
+        const step = next();
+        if (step.kind === "acquired")
+            return step.lease;
+        if (step.kind === "wait")
+            sleepSync(step.delayMs);
+    }
+}
+export async function withStateLock(file, options, action) {
+    const lease = await acquireStateLock(file, options);
+    let outcome;
+    try {
+        outcome = { ok: true, value: await action(lease) };
+    }
+    catch (err) {
+        outcome = { ok: false, error: err };
+    }
+    let releaseError;
+    try {
+        lease.release();
+    }
+    catch (err) {
+        releaseError = err;
+    }
+    if (!outcome.ok) {
+        if (releaseError) {
+            throw new Error(`${errorMessage(outcome.error)}; state lock release failed: ${errorMessage(releaseError)}`);
+        }
+        throw outcome.error;
+    }
+    if (releaseError)
+        throw releaseError;
+    return outcome.value;
+}
+export class StateMutationQueue {
+    file;
+    timeoutMs;
+    operationQueue = Promise.resolve();
+    constructor(file, timeoutMs = 30_000) {
+        this.file = file;
+        this.timeoutMs = timeoutMs;
+    }
+    run(purpose, action) {
+        const operation = () => withStateLock(this.file, { purpose, timeoutMs: this.timeoutMs }, () => action());
+        const next = this.operationQueue.then(operation, operation);
+        this.operationQueue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+}

package/dist/status.js

@@ -0,0 +1,279 @@
+import { currentCoreVersion } from "./core.js";
+import { SashDaemonClient } from "./daemon-client.js";
+import { evaluateDaemon, } from "./daemon-lifecycle.js";
+import { ProfileService } from "./profile-service.js";
+import { SystemProxyManager } from "./system-proxy-manager.js";
+import { uiInstalled } from "./webui.js";
+export const CLI_STATUS_SCHEMA_VERSION = 1;
+function errorText(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return (message
+        .replace(/[\r\n\t]+/g, " ")
+        .trim()
+        .slice(0, 300) || "unknown error");
+}
+function addError(errors, message) {
+    if (!errors.includes(message))
+        errors.push(message);
+}
+function observedSystemProxy(state) {
+    if (!state) {
+        return { supported: null, enabled: null, server: null, details: null };
+    }
+    return {
+        supported: typeof state.supported === "boolean" ? state.supported : null,
+        enabled: typeof state.enabled === "boolean" ? state.enabled : null,
+        server: typeof state.server === "string" && state.server ? state.server : null,
+        details: typeof state.details === "string" && state.details ? state.details : null,
+    };
+}
+function daemonObservation(state, daemonState) {
+    const resolvedState = daemonState ?? state.kind;
+    return {
+        state: resolvedState,
+        running: state.running,
+        healthy: resolvedState === "healthy",
+        pid: typeof state.pid === "number" ? state.pid : null,
+        port: state.kind === "stopped" ? 0 : (state.port ?? 0),
+    };
+}
+export function resolveObservedSystemProxy(source, fallbackDaemonApplied, inspection, inspectionError) {
+    const errors = [];
+    let daemonApplied = fallbackDaemonApplied;
+    let osObserved;
+    if (source) {
+        daemonApplied = source.appliedKnown ? source.applied : null;
+        if (daemonApplied === null)
+            addError(errors, "Daemon-applied proxy state is unavailable");
+        if (source.queryError)
+            addError(errors, `System proxy query failed: ${source.queryError}`);
+        if (source.stateKnown && source.state) {
+            osObserved = observedSystemProxy(source.state);
+        }
+    }
+    if (!osObserved && inspection) {
+        if (inspection.queryError) {
+            addError(errors, `System proxy query failed: ${inspection.queryError}`);
+        }
+        if (inspection.stateKnown) {
+            osObserved = observedSystemProxy(inspection.state);
+        }
+    }
+    if (inspectionError)
+        addError(errors, inspectionError);
+    osObserved ??= observedSystemProxy(undefined);
+    if (osObserved.supported === null || osObserved.enabled === null) {
+        addError(errors, "OS proxy state is unavailable");
+    }
+    return { daemonApplied, osObserved, errors };
+}
+export async function observeSystemProxy(context, dependencies, source, fallbackDaemonApplied) {
+    let inspection;
+    let inspectionError;
+    if (!source?.stateKnown || !source.state) {
+        try {
+            inspection = dependencies.inspectSystemProxy
+                ? await dependencies.inspectSystemProxy(context)
+                : await new SystemProxyManager({ layout: context.layout }).inspect();
+        }
+        catch (err) {
+            inspectionError = `OS proxy query failed: ${errorText(err)}`;
+        }
+    }
+    return resolveObservedSystemProxy(source, fallbackDaemonApplied, inspection, inspectionError);
+}
+async function evaluate(context, dependencies) {
+    return dependencies.evaluateDaemon
+        ? dependencies.evaluateDaemon(context)
+        : evaluateDaemon(context.layout, context.settings);
+}
+async function queryStatus(context, dependencies, daemon) {
+    if (dependencies.queryDaemonStatus) {
+        return dependencies.queryDaemonStatus(context, daemon);
+    }
+    return new SashDaemonClient(daemon.port, context.settings.daemonSecret).status();
+}
+function addObservationErrors(errors, observation) {
+    for (const error of observation.errors)
+        addError(errors, error);
+}
+export async function collectRuntimeStatus(context, dependencies = {}) {
+    const errors = [];
+    const daemonState = await evaluate(context, dependencies);
+    let daemon = daemonObservation(daemonState);
+    const installedVersion = dependencies.installedCoreVersion
+        ? dependencies.installedCoreVersion(context)
+        : currentCoreVersion(context.layout);
+    const profile = dependencies.activeProfile
+        ? dependencies.activeProfile(context)
+        : new ProfileService({
+            layout: context.layout,
+            settings: () => context.settings,
+        }).active();
+    let coreRunning = daemonState.running ? null : false;
+    let coreHealthy = daemonState.running ? null : false;
+    let corePid = null;
+    let coreVersion = null;
+    let tunActive = daemonState.running ? null : false;
+    let desiredProxy = context.settings.systemProxy;
+    let proxySource;
+    let queriedDaemon = false;
+    if (daemonState.kind === "healthy") {
+        try {
+            const status = await queryStatus(context, dependencies, daemonState);
+            queriedDaemon = true;
+            daemon = daemonObservation(daemonState, "healthy");
+            desiredProxy = status.systemProxy.desired;
+            proxySource = {
+                applied: status.systemProxy.applied,
+                appliedKnown: status.systemProxy.appliedKnown,
+                stateKnown: status.systemProxy.stateKnown,
+                ...(status.systemProxy.actual ? { state: status.systemProxy.actual } : {}),
+                ...(status.systemProxy.queryError ? { queryError: status.systemProxy.queryError } : {}),
+            };
+            if (typeof status.core.running !== "boolean") {
+                addError(errors, "Core running state is unavailable");
+            }
+            else if (!status.core.running) {
+                coreRunning = false;
+                coreHealthy = false;
+                tunActive = false;
+            }
+            else {
+                coreRunning = true;
+                coreHealthy = typeof status.core.healthy === "boolean" ? status.core.healthy : null;
+                corePid = typeof status.core.pid === "number" ? status.core.pid : null;
+                coreVersion =
+                    typeof status.core.version === "string" && status.core.version
+                        ? status.core.version
+                        : null;
+                tunActive = typeof status.core.tunActive === "boolean" ? status.core.tunActive : null;
+                if (coreHealthy === null)
+                    addError(errors, "Core health is unavailable");
+                else if (!coreHealthy)
+                    addError(errors, "Core controller health probe failed");
+                if (corePid === null)
+                    addError(errors, "Core PID is unavailable");
+                if (coreVersion === null)
+                    addError(errors, "Core runtime version is unavailable");
+                if (tunActive === null)
+                    addError(errors, "Core TUN state is unavailable");
+            }
+        }
+        catch (err) {
+            daemon = daemonObservation(daemonState, "unhealthy");
+            addError(errors, `Daemon status query failed: ${errorText(err)}`);
+        }
+    }
+    else if (daemonState.running) {
+        addError(errors, "sashd control API is unavailable");
+    }
+    const proxyObservation = await observeSystemProxy(context, dependencies, proxySource, daemonState.running ? null : false);
+    addObservationErrors(errors, proxyObservation);
+    const healthy = !daemonState.running
+        ? false
+        : queriedDaemon
+            ? coreRunning === false
+                ? false
+                : coreHealthy
+            : null;
+    const activeProfile = profile ? { id: profile.id, name: profile.name, url: profile.url } : null;
+    const daemonPort = daemon.port || context.settings.daemonPort;
+    return {
+        schemaVersion: CLI_STATUS_SCHEMA_VERSION,
+        complete: errors.length === 0,
+        healthy,
+        queryError: errors.length > 0 ? errors.join("; ") : null,
+        daemon: { ...daemon, port: daemonPort },
+        core: {
+            running: coreRunning,
+            healthy: coreHealthy,
+            pid: corePid,
+            version: coreVersion,
+            installedVersion: installedVersion || null,
+        },
+        systemProxy: {
+            desired: desiredProxy,
+            daemonApplied: proxyObservation.daemonApplied,
+            osObserved: proxyObservation.osObserved,
+        },
+        uiInstalled: dependencies.hasUi ? dependencies.hasUi(context) : uiInstalled(context.layout),
+        endpoints: {
+            mixedProxy: `127.0.0.1:${context.settings.mixedPort}`,
+            controller: context.settings.controller,
+            daemonApi: `http://127.0.0.1:${daemonPort}`,
+            dashboard: `http://127.0.0.1:${daemonPort}/ui/`,
+        },
+        activeProfile,
+        tun: {
+            desired: context.settings.tun,
+            active: tunActive,
+        },
+        paths: {
+            root: context.layout.root,
+            config: context.layout.configFile,
+        },
+    };
+}
+export function runtimeStatusHeadline(status) {
+    if (status.daemon.state === "stopped")
+        return { level: "info", text: "sash is not running" };
+    if (status.daemon.state === "unhealthy" || status.core.running === null) {
+        const owner = status.daemon.pid === null ? "" : ` (PID=${status.daemon.pid})`;
+        return {
+            level: "warn",
+            text: `sashd is running${owner}, but runtime status is unavailable`,
+        };
+    }
+    if (status.core.running) {
+        const pid = status.core.pid === null ? "unknown" : String(status.core.pid);
+        const version = status.core.version ? `, ${status.core.version}` : "";
+        return status.core.healthy
+            ? {
+                level: "ok",
+                text: `sashd running (PID=${status.daemon.pid}), core running (PID=${pid}${version})`,
+            }
+            : {
+                level: "warn",
+                text: `sashd running (PID=${status.daemon.pid}), core unhealthy (PID=${pid}${version})`,
+            };
+    }
+    return {
+        level: "ok",
+        text: `sashd running (PID=${status.daemon.pid}), core stopped`,
+    };
+}
+export function formatTunObservation(status) {
+    if (!status.tun.desired) {
+        if (status.tun.active === true)
+            return "off (runtime active)";
+        return status.tun.active === null && status.core.running !== false
+            ? "off (runtime unknown)"
+            : "off";
+    }
+    if (status.core.running === false)
+        return "on (core stopped)";
+    if (status.core.running === null)
+        return "on (runtime unknown)";
+    if (status.tun.active === true)
+        return "on (active)";
+    if (status.tun.active === false)
+        return "on (inactive)";
+    return "on (unverified)";
+}
+export function shouldShowTunGuidance(status) {
+    return (status.tun.desired &&
+        status.core.running === true &&
+        status.core.healthy === true &&
+        status.tun.active !== true);
+}
+export function formatObservedProxy(state) {
+    if (state.enabled === null)
+        return "unknown";
+    return state.enabled ? `on (${state.server || "unknown server"})` : "off";
+}
+export function markIncompleteObservation(complete) {
+    if (!complete && (process.exitCode === undefined || process.exitCode === 0)) {
+        process.exitCode = 2;
+    }
+}