plugins/ops-guards/hooks/lock.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1// The heavy-work lock, as a command (job_1e4b82452fe0, mod 1).
2//
3// This is a port of acquireHeavyLock / releaseHeavyLock / waitForHeavyLock in capsid's
4// scripts/overnight-guard.mjs, so a tab and the nightly scheduler share one lock:
5//   file     ~/.capsid/overnight-heavy.lock
6//   create   openSync(path, "wx"), which fails if the file exists
7//   body     JSON { ns, pid, started } with `started` an ISO time
8//   stale    older than 9 hours, or unreadable, is removed and taken over
9//   release  only when the file's `ns` is ours
10// The scheduler reads `ns` and `started` and nothing else, so extra fields would be safe,
11// but none are added. test/ops-guards-lock.test.mjs pins this format.
12//
13// The hooks module cannot make an exclusive create itself ($.fs.write replaces in place),
14// and a hooks module may import only its own files, so the mod runs this file with
15// $.process.run. Run directly:
16//   node lock.mjs acquire <ns> [lockPath]
17//   node lock.mjs wait    <ns> <waitMs> [lockPath]
18//   node lock.mjs release <ns> [lockPath]
19// Output is one line of JSON. Exit 0 for any answer, 2 for a usage or I/O error.
20import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeSync } from 'node:fs';
21import { homedir } from 'node:os';
22import { dirname, join, resolve } from 'node:path';
23import { fileURLToPath } from 'node:url';
24
25export const DEFAULT_LOCK = join(homedir(), '.capsid', 'overnight-heavy.lock');
26export const STALE_MS = 9 * 3_600_000;
27
28export function readLock(path) {
29  try {
30    const parsed = JSON.parse(readFileSync(path, 'utf8'));
31    return parsed && typeof parsed.ns === 'string' && typeof parsed.started === 'string' ? parsed : null;
32  } catch {
33    return null;
34  }
35}
36
37export function acquire(path, info, { now = Date.now, staleMs = STALE_MS } = {}) {
38  mkdirSync(dirname(path), { recursive: true });
39  for (let attempt = 0; attempt < 2; attempt += 1) {
40    try {
41      const fd = openSync(path, 'wx');
42      try {
43        writeSync(fd, JSON.stringify(info));
44      } finally {
45        closeSync(fd);
46      }
47      return { ok: true };
48    } catch (err) {
49      if (!(err instanceof Error) || err.code !== 'EEXIST') throw err;
50    }
51    const holder = readLock(path);
52    const age = holder ? now() - Date.parse(holder.started) : Number.POSITIVE_INFINITY;
53    // An unreadable lock is as stale as one past its time: nothing can say who holds it.
54    if (age <= staleMs) return { ok: false, holder };
55    rmSync(path, { force: true });
56  }
57  return { ok: false, holder: readLock(path) };
58}
59
60export function release(path, ns) {
61  const holder = readLock(path);
62  if (holder && holder.ns === ns) {
63    rmSync(path, { force: true });
64    return { released: true };
65  }
66  return { released: false, holder };
67}
68
69export async function wait(path, info, waitMs, { pollMs = 5000, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now, staleMs } = {}) {
70  const deadline = now() + waitMs;
71  for (;;) {
72    const got = acquire(path, info, { now, ...(staleMs === undefined ? {} : { staleMs }) });
73    if (got.ok || now() >= deadline) return got;
74    await sleep(pollMs);
75  }
76}
77
78async function main(argv) {
79  const [cmd, ns, ...rest] = argv;
80  if (!cmd || !ns) {
81    console.error('usage: lock.mjs acquire <ns> [path] | wait <ns> <waitMs> [path] | release <ns> [path]');
82    return 2;
83  }
84  const info = { ns, pid: process.ppid, started: new Date().toISOString() };
85  if (cmd === 'acquire') {
86    console.log(JSON.stringify(acquire(rest[0] ?? DEFAULT_LOCK, info)));
87    return 0;
88  }
89  if (cmd === 'wait') {
90    const waitMs = Number(rest[0]);
91    if (!Number.isFinite(waitMs) || waitMs < 0) {
92      console.error(`waitMs "${rest[0]}" is not a number`);
93      return 2;
94    }
95    console.log(JSON.stringify(await wait(rest[1] ?? DEFAULT_LOCK, info, waitMs)));
96    return 0;
97  }
98  if (cmd === 'release') {
99    console.log(JSON.stringify(release(rest[0] ?? DEFAULT_LOCK, ns)));
100    return 0;
101  }
102  console.error(`unknown command "${cmd}"`);
103  return 2;
104}
105
106if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
107  main(process.argv.slice(2)).then(
108    (code) => {
109      process.exitCode = code;
110    },
111    (err) => {
112      console.error(err instanceof Error ? err.message : String(err));
113      process.exitCode = 2;
114    }
115  );
116}