tapline-host 1.6.2 → 1.7.0

package/dist/pidlock.js

@@ -0,0 +1,382 @@
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { closeSync, linkSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+function parseHolder(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+const runProgram = (file, args) => execFileSync(file, args, { encoding: "utf8", timeout: 5000, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+/**
+ * When a process started, as text that is the same each time it is asked for the same process; null when it can't be told. A lock
+ * keeps it beside the process id, so a process id that was reused by another program is not mistaken for the holder. Windows asks
+ * PowerShell (`Get-Process -Id N`, about half a second, asked only for a lock's own holder and when a lock is found), elsewhere `ps`.
+ */
+export function processStartTime(pid, platform = process.platform, run = runProgram) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        const out = platform === "win32"
+            ? run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().ToString('o')`])
+            : run("ps", ["-o", "lstart=", "-p", String(pid)]);
+        const text = out.trim();
+        return text === "" ? null : text;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a process runs (signal 0); a process we may not signal still runs. */
+export function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+let ownStart;
+/** The deps of this process for a lock of its own (this process's start time is asked once and kept). */
+export function ownLockDeps() {
+    return {
+        pid: process.pid,
+        alive: processAlive,
+        startOf: (pid) => {
+            if (pid !== process.pid)
+                return processStartTime(pid);
+            if (ownStart === undefined)
+                ownStart = processStartTime(pid);
+            return ownStart;
+        },
+    };
+}
+/** Whether the holder a lock names is provably gone: its process doesn't run, or the process that has that id started at another time. */
+function holderIsDead(deps, holder) {
+    if (typeof holder.pid !== "number" || !Number.isInteger(holder.pid))
+        return false;
+    if (!deps.alive(holder.pid))
+        return true;
+    if (typeof holder.started === "string" && deps.startOf !== undefined) {
+        const now = deps.startOf(holder.pid);
+        return now !== null && now !== holder.started;
+    }
+    return false;
+}
+/** A lock's text is a leftover only when it names a holder that is provably dead. Empty, cut-short or garbage text never is (no age rule). */
+function isLeftover(deps, text) {
+    const holder = parseHolder(text);
+    return typeof holder.pid === "number" && typeof holder.owner === "string" && holderIsDead(deps, holder);
+}
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+const codeOf = (error) => error.code;
+/** Errors that mean this file system can't hard-link (so the fallback is used), as opposed to "the name is taken". */
+const NO_LINK = new Set(["EPERM", "ENOSYS", "EXDEV", "ENOTSUP", "EOPNOTSUPP", "EMLINK", "EACCES"]);
+/**
+ * Creates `path` with `text`, whole, only if it doesn't exist: "published", or "exists" (someone's file stands there), or "error".
+ * The text is written to a unique temp file first and hard-linked into place, so `path` is never seen empty.
+ */
+export function publishNew(deps, path, text) {
+    const temp = `${path}.${randomBytes(6).toString("hex")}.pub`;
+    try {
+        writeFileSync(temp, text, { flag: "wx", mode: 0o600 });
+    }
+    catch {
+        return "error";
+    }
+    try {
+        deps.beforePublish?.(path);
+        try {
+            (deps.link ?? linkSync)(temp, path);
+            return "published";
+        }
+        catch (error) {
+            const code = codeOf(error);
+            if (code === "EEXIST")
+                return "exists";
+            if (code === undefined || !NO_LINK.has(code))
+                return "error";
+        }
+        // No hard links here: an exclusive create, then the content. Readers treat what can't be read as a holder as a writer in progress.
+        let fd;
+        try {
+            fd = openSync(path, "wx", 0o600);
+        }
+        catch (error) {
+            return codeOf(error) === "EEXIST" ? "exists" : "error";
+        }
+        try {
+            deps.afterCreate?.(path);
+            writeSync(fd, text);
+            return "published";
+        }
+        catch {
+            return "error";
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+/** A unique name for a file moved aside: only the one who moved it ever touches it. */
+function tombstone(path) {
+    return `${path}.${randomBytes(6).toString("hex")}.tomb`;
+}
+/**
+ * Removes the file at `path` only when it still holds `seen`: it is moved to a name of its own (one move, so only one remover gets
+ * it), and what was moved is checked; a file that changed hands in between is put back, never deleted.
+ */
+function removeIfUnchanged(deps, path, seen) {
+    const tomb = tombstone(path);
+    try {
+        renameSync(path, tomb);
+    }
+    catch {
+        return false;
+    }
+    try {
+        const moved = readFileSync(tomb, "utf8");
+        if (moved === seen)
+            return true;
+        publishNew(deps, path, moved);
+    }
+    catch {
+        // put back by someone else already, or unreadable: the next round decides
+    }
+    finally {
+        rmSync(tomb, { force: true });
+    }
+    return false;
+}
+/**
+ * Takes the lock at `path` (its folder must exist): the owner token, or null when a live holder has it. A live holder is never
+ * displaced, however long it takes. A leftover (holder provably dead) is taken over under `<path>.takeover`, published the same way:
+ * under it the lock is read again, and only if it is unchanged and its holder is still dead is it deleted and replaced by the taker's.
+ * A `.takeover` whose own process is dead is cleared the same way.
+ */
+export function takePidLock(deps, path) {
+    const takeoverPath = `${path}.takeover`;
+    const token = `${randomBytes(8).toString("hex")}-${deps.pid}`;
+    const mine = `${JSON.stringify({ owner: token, pid: deps.pid, started: deps.startOf?.(deps.pid) ?? null })}\n`;
+    for (let attempt = 0; attempt < 6; attempt++) {
+        // Acquisition honours `.takeover`: while a takeover or an unlock holds it (a live holder), nobody creates the lock.
+        const gate = readText(takeoverPath);
+        if (gate !== null && typeof parseHolder(gate).pid === "number" && !isLeftover(deps, gate))
+            return null;
+        const first = publishNew(deps, path, mine);
+        if (first === "published")
+            return token;
+        if (first === "error")
+            return null;
+        const seen = readText(path);
+        if (seen === null)
+            continue; // released between our create and our read: try to create again
+        if (!isLeftover(deps, seen))
+            return null;
+        deps.beforeReclaim?.();
+        // Under .takeover only one contender at a time looks at a leftover.
+        const claimed = publishNew(deps, takeoverPath, mine);
+        if (claimed === "error")
+            return null;
+        if (claimed === "exists") {
+            const other = readText(takeoverPath);
+            // Someone else is taking it over now (or was, and died): a dead taker's .takeover is cleared, a live one's is waited out.
+            if (other !== null && isLeftover(deps, other))
+                removeIfUnchanged(deps, takeoverPath, other);
+            continue;
+        }
+        try {
+            const now = readText(path);
+            if (now === seen && isLeftover(deps, now)) {
+                try {
+                    unlinkSync(path);
+                }
+                catch {
+                    continue;
+                }
+                if (publishNew(deps, path, mine) === "published")
+                    return token;
+                continue; // a run that came in first holds it now
+            }
+        }
+        finally {
+            // only our own .takeover is removed
+            const held = readText(takeoverPath);
+            if (held === mine)
+                removeIfUnchanged(deps, takeoverPath, mine);
+        }
+    }
+    return null;
+}
+/** Releases the lock only while its content is still the holder's own (`token`); another's lock is never removed. */
+export function dropPidLock(path, token) {
+    const text = readText(path);
+    if (text === null || parseHolder(text).owner !== token)
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // already gone
+    }
+}
+/** Whether the lock's holder is `token` right now (for a holder that wants to know it still has it). */
+export function holdsPidLock(path, token) {
+    const text = readText(path);
+    return text !== null && parseHolder(text).owner === token;
+}
+/** Judges the exact bytes of a lock file (a snapshot): the holder is looked at in THIS text, never in a later read of the file. */
+function judgeText(deps, text) {
+    if (text.trim() === "")
+        return { state: "stuck", why: "empty" };
+    const holder = parseHolder(text);
+    if (typeof holder.pid !== "number" || !Number.isInteger(holder.pid) || typeof holder.owner !== "string")
+        return { state: "stuck", why: "unreadable" };
+    return holderIsDead(deps, holder) ? { state: "stuck", why: "dead", pid: holder.pid } : { state: "live", pid: holder.pid };
+}
+function snapshotOf(path) {
+    try {
+        return { kind: "text", text: readFileSync(path, "utf8") };
+    }
+    catch (error) {
+        return codeOf(error) === "ENOENT" ? { kind: "absent" } : { kind: "unreadable" };
+    }
+}
+function judgeSnapshot(deps, snap) {
+    if (snap.kind === "absent")
+        return { state: "absent" };
+    return snap.kind === "unreadable" ? { state: "stuck", why: "unreadable" } : judgeText(deps, snap.text);
+}
+/** Looks at the lock at `path` without changing it. */
+export function inspectPidLock(deps, path) {
+    return judgeSnapshot(deps, snapshotOf(path));
+}
+/** The words for a stuck lock's cause. */
+export function stuckWords(state) {
+    if (state.why === "empty")
+        return "empty";
+    if (state.why === "unreadable")
+        return "unreadable";
+    return `held by a process that is gone (pid ${state.pid ?? "?"})`;
+}
+/**
+ * Removes the file at `path` that was judged stuck from `snap`, only if it still is what was judged: it is moved to a name of its
+ * own, and what was moved is compared with the snapshot (an unreadable snapshot is judged again on what was moved). A file that
+ * turns out to be another, live holder's is linked back and never deleted. Answers `removed`, `live` (with the pid of the holder
+ * put back) or `failed`.
+ */
+function removeJudged(deps, path, snap) {
+    if (snap.kind === "absent")
+        return "removed";
+    const tomb = tombstone(path);
+    try {
+        renameSync(path, tomb);
+    }
+    catch {
+        return "failed";
+    }
+    const moved = snapshotOf(tomb);
+    const same = snap.kind === "text" ? moved.kind === "text" && moved.text === snap.text : judgeSnapshot(deps, moved).state !== "live";
+    if (same) {
+        try {
+            rmSync(tomb, { force: true });
+            return "removed";
+        }
+        catch {
+            // can't be deleted (a folder, say): it is put back where it was
+        }
+    }
+    const state = judgeSnapshot(deps, moved);
+    const live = state.state === "live" ? { live: state.pid } : "failed";
+    if (moved.kind !== "text") {
+        try {
+            renameSync(tomb, path);
+        }
+        catch {
+            // the name was taken meanwhile: what was moved stays under its tombstone for a person to look at
+        }
+        return live;
+    }
+    // Link it back (published whole); a live holder is never unlinked. If the name was taken meanwhile, the tombstone stays for a person.
+    if (publishNew(deps, path, moved.text) === "published")
+        rmSync(tomb, { force: true });
+    return live;
+}
+/**
+ * Removes the lock at `path` and its `.takeover`, but only when no holder is proven alive: an empty or unreadable file, or one whose
+ * holder is dead (its process is gone, or has another start time). A live holder in either file refuses and removes nothing.
+ *
+ * It runs under the lock's own `.takeover` (published whole, as a takeover is), so it never overlaps a takeover, and acquisition
+ * honours `.takeover` too. Under it the exact bytes of the lock are read once, THAT snapshot's holder is judged, and the file is
+ * removed only if it still holds exactly those bytes (moved to a tombstone and compared; a different file is linked back).
+ * A `.takeover` that is itself stuck is cleared the same way first.
+ */
+export function unlockPidLock(deps, path) {
+    const takeoverPath = `${path}.takeover`;
+    const mine = `${JSON.stringify({ owner: `${randomBytes(8).toString("hex")}-${deps.pid}`, pid: deps.pid, started: deps.startOf?.(deps.pid) ?? null })}\n`;
+    const removed = [];
+    const failed = (file) => ({ status: "failed", removed, path: file });
+    let held = false;
+    for (let attempt = 0; attempt < 6 && !held; attempt++) {
+        const got = publishNew(deps, takeoverPath, mine);
+        if (got === "published") {
+            held = true;
+            break;
+        }
+        if (got === "error")
+            return failed(takeoverPath);
+        const snap = snapshotOf(takeoverPath);
+        const state = judgeSnapshot(deps, snap);
+        if (state.state === "live")
+            return { status: "live", pid: state.pid, removed, path: takeoverPath };
+        if (state.state === "absent")
+            continue;
+        deps.beforeRemove?.(takeoverPath);
+        const outcome = removeJudged(deps, takeoverPath, snap);
+        if (outcome === "removed")
+            removed.push({ path: takeoverPath, why: stuckWords(state) });
+        else if (outcome === "failed")
+            return failed(takeoverPath);
+        else
+            return { status: "live", pid: outcome.live, removed, path: takeoverPath };
+    }
+    if (!held)
+        return failed(takeoverPath);
+    try {
+        const snap = snapshotOf(path);
+        const state = judgeSnapshot(deps, snap);
+        if (state.state === "live")
+            return { status: "live", pid: state.pid, removed, path };
+        if (state.state === "absent")
+            return removed.length === 0 ? { status: "none", removed } : { status: "removed", removed };
+        deps.beforeRemove?.(path);
+        const outcome = removeJudged(deps, path, snap);
+        if (outcome === "removed")
+            removed.push({ path, why: stuckWords(state) });
+        else if (outcome === "failed")
+            return failed(path);
+        else
+            return { status: "live", pid: outcome.live, removed, path };
+        return { status: "removed", removed };
+    }
+    finally {
+        // only our own .takeover is released
+        if (readText(takeoverPath) === mine)
+            removeIfUnchanged(deps, takeoverPath, mine);
+    }
+}
+//# sourceMappingURL=pidlock.js.map

package/dist/pidlock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pidlock.js","sourceRoot":"","sources":["../src/pidlock.ts"],"names":[],"mappings":"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"}

package/dist/places.d.ts

@@ -114,6 +114,8 @@ export declare class AppMap {
     private known;
     private knownFor;
     private dirty;
+    /** Set by `discard`: this copy was dropped for a fresh read of the file and never writes again. */
+    private dead;
     private version;
     private timer;
     private saving;
@@ -188,6 +190,13 @@ export declare class AppMap {
     private schedule;
     /** Writes what changed now (the close, and tests). A failed write stays dirty and is tried again by the next flush. */
     flush(): Promise<void>;
+    /** How the file loaded: "ok", "new" (no file) or "unreadable". */
+    loadedStatus(): "ok" | "new" | "unreadable";
+    /**
+     * Drops this copy without writing it: what it learned and hadn't saved is let go, and it never saves again, so a file a person has
+     * edited can't be written over (or a deleted reflex brought back) by a stale copy. A save already under way is waited for.
+     */
+    discard(): Promise<void>;
     private write;
     /** The merged file is the map from now on: another tool's work, and a name a clash changed, come with it. */
     private adopt;
@@ -207,6 +216,8 @@ export declare class MapRegistry {
     /** The app's map; none for an app that has no id of its own. */
     forApp(app: MapApp): AppMap | undefined;
     flushAll(): Promise<void>;
+    /** Lets go of every map held in memory unsaved; the next `forApp` reads the file again. */
+    reload(): Promise<void>;
 }
 export interface PlaceSource {
     capabilities: string[];

package/dist/places.js

@@ -289,6 +289,8 @@ export class AppMap {
     known;
     knownFor;
     dirty = false;
+    /** Set by `discard`: this copy was dropped for a fresh read of the file and never writes again. */
+    dead = false;
     version = 0;
     timer;
     saving;
@@ -639,7 +641,7 @@ export class AppMap {
         this.schedule();
     }
     schedule() {
-        if (this.readOnly || this.timer !== undefined || this.saving !== undefined)
+        if (this.dead || this.readOnly || this.timer !== undefined || this.saving !== undefined)
             return;
         const wait = Math.max(0, this.lastWriteAt + this.gapMs - this.clock());
         this.timer = setTimeout(() => {
@@ -658,9 +660,27 @@ export class AppMap {
             return;
         while (this.saving !== undefined)
             await this.saving;
-        if (this.dirty)
+        if (this.dirty && !this.dead)
             await this.write();
     }
+    /** How the file loaded: "ok", "new" (no file) or "unreadable". */
+    loadedStatus() {
+        return this.loadStatus;
+    }
+    /**
+     * Drops this copy without writing it: what it learned and hadn't saved is let go, and it never saves again, so a file a person has
+     * edited can't be written over (or a deleted reflex brought back) by a stale copy. A save already under way is waited for.
+     */
+    async discard() {
+        this.dead = true;
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        while (this.saving !== undefined)
+            await this.saving;
+        this.dirty = false;
+    }
     write() {
         if (this.saving !== undefined)
             return this.saving;
@@ -767,6 +787,12 @@ export class MapRegistry {
     async flushAll() {
         await Promise.all([...this.maps.values()].map((map) => map.flush()));
     }
+    /** Lets go of every map held in memory unsaved; the next `forApp` reads the file again. */
+    async reload() {
+        const held = [...this.maps.values()];
+        this.maps.clear();
+        await Promise.all(held.map((map) => map.discard()));
+    }
 }
 /** Where the app was before a move: the host's latest `place` event when it names a route, else the last place seen. */
 export function placeBefore(source, map) {