clinkx 1.3.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (123) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/README.md +13 -6
  3. package/clinkx-workflows/dist/child-env.d.ts +3 -0
  4. package/clinkx-workflows/dist/child-env.js +11 -0
  5. package/clinkx-workflows/dist/child-env.js.map +1 -1
  6. package/clinkx-workflows/dist/dashboard/api-routes.d.ts +21 -0
  7. package/clinkx-workflows/dist/dashboard/api-routes.js +27 -0
  8. package/clinkx-workflows/dist/dashboard/api-routes.js.map +1 -1
  9. package/clinkx-workflows/dist/dashboard/auth/challenge-store.d.ts +13 -0
  10. package/clinkx-workflows/dist/dashboard/auth/challenge-store.js.map +1 -1
  11. package/clinkx-workflows/dist/dashboard/auth/controller.d.ts +27 -0
  12. package/clinkx-workflows/dist/dashboard/auth/controller.js +262 -23
  13. package/clinkx-workflows/dist/dashboard/auth/controller.js.map +1 -1
  14. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.d.ts +62 -0
  15. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js +70 -0
  16. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js.map +1 -0
  17. package/clinkx-workflows/dist/dashboard/request-admission.d.ts +6 -0
  18. package/clinkx-workflows/dist/dashboard/request-admission.js +9 -0
  19. package/clinkx-workflows/dist/dashboard/request-admission.js.map +1 -1
  20. package/clinkx-workflows/dist/dashboard/server-factory.js +15 -1
  21. package/clinkx-workflows/dist/dashboard/server-factory.js.map +1 -1
  22. package/clinkx-workflows/dist/dashboard/settings-contract.d.ts +1806 -0
  23. package/clinkx-workflows/dist/dashboard/settings-contract.js +630 -0
  24. package/clinkx-workflows/dist/dashboard/settings-contract.js.map +1 -0
  25. package/clinkx-workflows/dist/dashboard/settings-process-reader.d.ts +48 -0
  26. package/clinkx-workflows/dist/dashboard/settings-process-reader.js +195 -0
  27. package/clinkx-workflows/dist/dashboard/settings-process-reader.js.map +1 -0
  28. package/clinkx-workflows/dist/dashboard/settings-routes.d.ts +87 -0
  29. package/clinkx-workflows/dist/dashboard/settings-routes.js +690 -0
  30. package/clinkx-workflows/dist/dashboard/settings-routes.js.map +1 -0
  31. package/clinkx-workflows/dist/dashboard-ui/assets/index-DSOtuS0p.js +122 -0
  32. package/clinkx-workflows/dist/dashboard-ui/assets/style-C5guUjwN.css +1 -0
  33. package/clinkx-workflows/dist/dashboard-ui/index.html +2 -2
  34. package/clinkx-workflows/dist/durable-file-core.d.ts +76 -0
  35. package/clinkx-workflows/dist/durable-file-core.js +146 -0
  36. package/clinkx-workflows/dist/durable-file-core.js.map +1 -0
  37. package/clinkx-workflows/dist/durable-file.d.ts +8 -64
  38. package/clinkx-workflows/dist/durable-file.js +14 -137
  39. package/clinkx-workflows/dist/durable-file.js.map +1 -1
  40. package/clinkx-workflows/dist/index.js +68 -2
  41. package/clinkx-workflows/dist/index.js.map +1 -1
  42. package/clinkx-workflows/dist/settings/audit.d.ts +101 -0
  43. package/clinkx-workflows/dist/settings/audit.js +318 -0
  44. package/clinkx-workflows/dist/settings/audit.js.map +1 -0
  45. package/clinkx-workflows/dist/settings/bootstrap.d.ts +35 -0
  46. package/clinkx-workflows/dist/settings/bootstrap.js +52 -0
  47. package/clinkx-workflows/dist/settings/bootstrap.js.map +1 -0
  48. package/clinkx-workflows/dist/settings/codec.d.ts +51 -0
  49. package/clinkx-workflows/dist/settings/codec.js +410 -0
  50. package/clinkx-workflows/dist/settings/codec.js.map +1 -0
  51. package/clinkx-workflows/dist/settings/durable-write.d.ts +48 -0
  52. package/clinkx-workflows/dist/settings/durable-write.js +31 -0
  53. package/clinkx-workflows/dist/settings/durable-write.js.map +1 -0
  54. package/clinkx-workflows/dist/settings/index.d.ts +20 -0
  55. package/clinkx-workflows/dist/settings/index.js +23 -0
  56. package/clinkx-workflows/dist/settings/index.js.map +1 -0
  57. package/clinkx-workflows/dist/settings/loader.d.ts +80 -0
  58. package/clinkx-workflows/dist/settings/loader.js +577 -0
  59. package/clinkx-workflows/dist/settings/loader.js.map +1 -0
  60. package/clinkx-workflows/dist/settings/lock.d.ts +108 -0
  61. package/clinkx-workflows/dist/settings/lock.js +344 -0
  62. package/clinkx-workflows/dist/settings/lock.js.map +1 -0
  63. package/clinkx-workflows/dist/settings/paths.d.ts +65 -0
  64. package/clinkx-workflows/dist/settings/paths.js +173 -0
  65. package/clinkx-workflows/dist/settings/paths.js.map +1 -0
  66. package/clinkx-workflows/dist/settings/process-heartbeat.d.ts +47 -0
  67. package/clinkx-workflows/dist/settings/process-heartbeat.js +305 -0
  68. package/clinkx-workflows/dist/settings/process-heartbeat.js.map +1 -0
  69. package/clinkx-workflows/dist/settings/registry.d.ts +178 -0
  70. package/clinkx-workflows/dist/settings/registry.js +1285 -0
  71. package/clinkx-workflows/dist/settings/registry.js.map +1 -0
  72. package/clinkx-workflows/dist/settings/schema.d.ts +404 -0
  73. package/clinkx-workflows/dist/settings/schema.js +415 -0
  74. package/clinkx-workflows/dist/settings/schema.js.map +1 -0
  75. package/clinkx-workflows/dist/settings/store.d.ts +157 -0
  76. package/clinkx-workflows/dist/settings/store.js +842 -0
  77. package/clinkx-workflows/dist/settings/store.js.map +1 -0
  78. package/clinkx-workflows/dist/stdio-entry.d.ts +2 -0
  79. package/clinkx-workflows/dist/stdio-entry.js +52 -0
  80. package/clinkx-workflows/dist/stdio-entry.js.map +1 -0
  81. package/dist/dashboard-cli.js +50 -1
  82. package/dist/dashboard-cli.js.map +1 -1
  83. package/dist/dashboard-companion/protocol.js +17 -0
  84. package/dist/dashboard-companion/protocol.js.map +1 -1
  85. package/dist/dashboard-gateway/control-plane/contracts.d.ts +38 -38
  86. package/dist/dashboard-gateway/tunnel-http.js +20 -0
  87. package/dist/dashboard-gateway/tunnel-http.js.map +1 -1
  88. package/dist/elaris/config.d.ts +10 -0
  89. package/dist/elaris/config.js +27 -1
  90. package/dist/elaris/config.js.map +1 -1
  91. package/dist/elaris/tools.js +4 -1
  92. package/dist/elaris/tools.js.map +1 -1
  93. package/dist/index.d.ts +0 -31
  94. package/dist/index.js +41 -404
  95. package/dist/index.js.map +1 -1
  96. package/dist/lib.d.ts +17 -0
  97. package/dist/lib.js +17 -0
  98. package/dist/lib.js.map +1 -0
  99. package/dist/progress-report/lock.d.ts +17 -59
  100. package/dist/progress-report/lock.js +25 -329
  101. package/dist/progress-report/lock.js.map +1 -1
  102. package/dist/server.js +75 -4
  103. package/dist/server.js.map +1 -1
  104. package/dist/settings-cli/clients.d.ts +137 -0
  105. package/dist/settings-cli/clients.js +1124 -0
  106. package/dist/settings-cli/clients.js.map +1 -0
  107. package/dist/settings-cli/commands.d.ts +67 -0
  108. package/dist/settings-cli/commands.js +726 -0
  109. package/dist/settings-cli/commands.js.map +1 -0
  110. package/dist/settings-cli/format.d.ts +34 -0
  111. package/dist/settings-cli/format.js +40 -0
  112. package/dist/settings-cli/format.js.map +1 -0
  113. package/dist/settings-cli/main.d.ts +18 -0
  114. package/dist/settings-cli/main.js +256 -0
  115. package/dist/settings-cli/main.js.map +1 -0
  116. package/dist/stdio-main.d.ts +73 -0
  117. package/dist/stdio-main.js +455 -0
  118. package/dist/stdio-main.js.map +1 -0
  119. package/docs/configuration.md +340 -39
  120. package/docs/security.md +150 -6
  121. package/package.json +2 -2
  122. package/clinkx-workflows/dist/dashboard-ui/assets/index-DRId2DVA.js +0 -119
  123. package/clinkx-workflows/dist/dashboard-ui/assets/style-CHAw57y5.css +0 -1
@@ -0,0 +1,108 @@
1
+ export declare const LOCK_FILENAME = ".lock";
2
+ /** Give up rather than block a settings save forever on a contended document. */
3
+ export declare const LOCK_ACQUIRE_TIMEOUT_MS = 10000;
4
+ /**
5
+ * Errors from this module are their own class, not the root `ExecutionError`:
6
+ * this package must never import from the root `src/`, and the store maps this
7
+ * onto a 409/503 response itself.
8
+ */
9
+ export declare class SettingsLockError extends Error {
10
+ constructor(message: string);
11
+ }
12
+ export interface SettingsLockFileHandle {
13
+ writeFile(data: string): Promise<void>;
14
+ /** fsync: makes the body durable before it is published under `.lock`. */
15
+ sync(): Promise<void>;
16
+ close(): Promise<void>;
17
+ }
18
+ /** Filesystem operations the lock uses; injectable for race/fault tests. */
19
+ export interface SettingsLockFsOps {
20
+ open(path: string, flags: "wx", mode?: number): Promise<SettingsLockFileHandle>;
21
+ /**
22
+ * Hard-link `from` to `to`. `EEXIST` when `to` already exists, which is how
23
+ * acquisition detects contention without ever creating a partial lock.
24
+ */
25
+ link(from: string, to: string): Promise<void>;
26
+ readFile(path: string): Promise<string>;
27
+ unlink(path: string): Promise<void>;
28
+ }
29
+ /** `process.kill(pid, 0)` shape: throws ESRCH for a dead pid, EPERM for a live other-user pid. */
30
+ export type SettingsLockKillProbe = (pid: number, signal?: number) => void;
31
+ export interface SettingsLockDeps {
32
+ readonly fs?: SettingsLockFsOps | undefined;
33
+ readonly kill?: SettingsLockKillProbe | undefined;
34
+ readonly hostname?: (() => string) | undefined;
35
+ readonly now?: (() => number) | undefined;
36
+ /**
37
+ * Diagnostics sink for noteworthy lock events (reclaims, stolen locks).
38
+ * Deliberately not the logger: the settings bootstrap forbids logger
39
+ * imports in this family, and the store wires its own sink.
40
+ */
41
+ readonly warn?: ((fields: Record<string, unknown>, message: string) => void) | undefined;
42
+ }
43
+ export interface SettingsLockOptions extends SettingsLockDeps {
44
+ readonly acquireTimeoutMs?: number | undefined;
45
+ }
46
+ /**
47
+ * A holder's live claim on the critical section.
48
+ *
49
+ * `assertHeld` is not decoration. Reclamation is racy in principle — see the
50
+ * residuals on `withSettingsLock` — so any caller that is about to make a
51
+ * durable change must re-establish ownership immediately beforehand, which
52
+ * collapses the window in which a stolen-from holder can still commit down to
53
+ * the syscall that follows.
54
+ */
55
+ export interface SettingsLockGuard {
56
+ assertHeld(): Promise<void>;
57
+ }
58
+ /**
59
+ * Run `fn` while holding an exclusive cross-process lock on the settings
60
+ * directory `dir` (the directory holding `settings.json`).
61
+ *
62
+ * THE EXCLUSION PRIMITIVE. The lock is created by writing the full body to a
63
+ * throwaway `.lock.<token>.tmp` (opened `O_CREAT|O_EXCL`, fsynced) and
64
+ * publishing it with `link(2)`. The kernel arbitrates `link` atomically against
65
+ * every other creator on the same filesystem — including a second ClinkX server
66
+ * process, which is the real case here (a `clinkx` and a `clinkx-test` server,
67
+ * or the dashboard, routinely touch one settings directory at once) — and,
68
+ * because the body is complete before the link, NO CONTENDER EVER OBSERVES AN
69
+ * EMPTY `.lock`. A revision compare-and-swap alone is NOT a substitute:
70
+ * read -> compare -> replace has a window between the compare and the rename,
71
+ * so the CAS detects a lost update while this is what prevents one.
72
+ *
73
+ * RECLAMATION REQUIRES PROOF, NOT AGE — AND ONLY EVER ON THIS HOST. `link`
74
+ * arbitrates creation only, so an unconditional unlink of a lock merely judged
75
+ * old is unsafe: two contenders can both judge the same abandoned lock, the
76
+ * first can unlink-recreate-and-enter, and the second's already-justified
77
+ * unlink then deletes the FIRST's live lock and lets it enter too. So a lock
78
+ * is reclaimed only on positive evidence of death: a dead PID on this host,
79
+ * verified by a probe nothing else can fake. A lock held from ANOTHER host (a
80
+ * container bind-mount dashboard) records a hostname no local probe can
81
+ * check, and staleness cannot distinguish a dead foreign holder from a
82
+ * suspended one, so it is NEVER reclaimed automatically: the acquire deadline
83
+ * expires and the error names the lock path and the manual `rm` (R1). Evidence
84
+ * alone is still not enough to make two simultaneous reclaimers safe, so the
85
+ * unlink itself is serialized behind a second `O_EXCL` file (`.lock.steal`)
86
+ * with a full body re-observation under it before the unlink
87
+ * (`reclaimAbandonedLock`).
88
+ *
89
+ * Release is ownership-checked: the holder re-reads the lock body and unlinks
90
+ * only if the token is still its own, so a holder that was stolen from does not
91
+ * normally delete the new owner's lock. Node exposes no atomic
92
+ * compare-and-unlink, so that check is read-then-unlink and a steal landing
93
+ * inside that window is still possible; the guarantee is "will not", not
94
+ * "cannot".
95
+ *
96
+ * Honest residuals, all accepted under a single-user local-filesystem model:
97
+ * `O_EXCL`/`link` are not reliable on some network filesystems (NFSv2/v3); a
98
+ * PID can be recycled, so a probe can report a live process that is not the
99
+ * original holder; and a foreign-host lock whose holder died without releasing
100
+ * strands saves until an operator removes the file — the timeout error tells
101
+ * them exactly that. The steal lock adds one of its own: a process that dies
102
+ * while holding `.lock.steal` leaves it behind, which disables AUTOMATIC
103
+ * RECLAMATION for this settings document — normal acquisition and release are
104
+ * unaffected — until an operator removes the file. That is strictly the better
105
+ * failure mode: a save that needs a manual unwedge, rather than two writers in
106
+ * the critical section.
107
+ */
108
+ export declare function withSettingsLock<T>(dir: string, fn: (guard: SettingsLockGuard) => Promise<T>, options?: SettingsLockOptions): Promise<T>;
@@ -0,0 +1,344 @@
1
+ import { randomBytes } from "node:crypto";
2
+ import { hostname as nodeHostname } from "node:os";
3
+ import { join } from "node:path";
4
+ import { open as nodeOpen, link as nodeLink, readFile as nodeReadFile, unlink as nodeUnlink } from "node:fs/promises";
5
+ export const LOCK_FILENAME = ".lock";
6
+ /** Give up rather than block a settings save forever on a contended document. */
7
+ export const LOCK_ACQUIRE_TIMEOUT_MS = 10_000;
8
+ const RETRY_BASE_MS = 15;
9
+ const RETRY_JITTER_MS = 20;
10
+ /**
11
+ * Errors from this module are their own class, not the root `ExecutionError`:
12
+ * this package must never import from the root `src/`, and the store maps this
13
+ * onto a 409/503 response itself.
14
+ */
15
+ export class SettingsLockError extends Error {
16
+ constructor(message) {
17
+ super(message);
18
+ this.name = "SettingsLockError";
19
+ }
20
+ }
21
+ const nodeFs = {
22
+ open: async (path, flags, mode) => await nodeOpen(path, flags, mode),
23
+ link: async (from, to) => await nodeLink(from, to),
24
+ readFile: async (path) => await nodeReadFile(path, "utf8"),
25
+ unlink: async (path) => await nodeUnlink(path),
26
+ };
27
+ /** Serializes the one destructive step in this module. See `reclaimAbandonedLock`. */
28
+ const STEAL_LOCK_SUFFIX = ".steal";
29
+ function stealPathFor(lockPath) {
30
+ return `${lockPath}${STEAL_LOCK_SUFFIX}`;
31
+ }
32
+ function sleep(ms) {
33
+ return new Promise((resolve) => {
34
+ setTimeout(resolve, ms);
35
+ });
36
+ }
37
+ function errnoCode(error) {
38
+ return typeof error === "object" && error !== null && "code" in error
39
+ ? String(error.code)
40
+ : undefined;
41
+ }
42
+ async function readLockBody(fs, lockPath) {
43
+ try {
44
+ const raw = await fs.readFile(lockPath);
45
+ const parsed = JSON.parse(raw);
46
+ if (typeof parsed !== "object" || parsed === null)
47
+ return null;
48
+ const record = parsed;
49
+ const token = record["token"];
50
+ const pid = record["pid"];
51
+ const host = record["hostname"];
52
+ if (typeof token !== "string" || token === "")
53
+ return null;
54
+ return {
55
+ token,
56
+ pid: typeof pid === "number" && Number.isInteger(pid) && pid > 0 ? pid : 0,
57
+ hostname: typeof host === "string" ? host : "",
58
+ startedAt: typeof record["startedAt"] === "string" ? record["startedAt"] : "",
59
+ };
60
+ }
61
+ catch {
62
+ // Absent, unreadable, or unparseable: never provably ours, never provably dead.
63
+ return null;
64
+ }
65
+ }
66
+ async function readLockToken(fs, lockPath) {
67
+ return (await readLockBody(fs, lockPath))?.token ?? null;
68
+ }
69
+ /** Alive unless the OS positively says the process is gone. */
70
+ function sameHostProcessIsDead(pid, kill) {
71
+ if (pid <= 0)
72
+ return false;
73
+ try {
74
+ kill(pid, 0);
75
+ return false;
76
+ }
77
+ catch (err) {
78
+ // EPERM means it exists and belongs to someone else — alive, not dead.
79
+ return errnoCode(err) === "ESRCH";
80
+ }
81
+ }
82
+ /**
83
+ * Decide whether the lock on disk may be reclaimed. Reclamation requires
84
+ * POSITIVE EVIDENCE OF DEATH, and the only admissible evidence is a dead PID
85
+ * on THIS host: we can never probe a process on another host, and no
86
+ * staleness heuristic can distinguish a dead foreign holder from a suspended
87
+ * one, so a foreign-host lock (or one recording no host at all) is never
88
+ * reclaimed automatically — an operator removes it (R1).
89
+ */
90
+ function classifyLockBody(body, deps) {
91
+ if (body.hostname !== "" && body.hostname === deps.hostname()) {
92
+ return sameHostProcessIsDead(body.pid, deps.kill)
93
+ ? { kind: "abandoned", token: body.token, why: `owner pid ${String(body.pid)} is gone` }
94
+ : { kind: "live" };
95
+ }
96
+ if (body.hostname === "") {
97
+ return {
98
+ kind: "foreign",
99
+ why: `the lock body records no hostname (pid ${String(body.pid)}); a lock without a host can never be proven dead, so it is never reclaimed automatically`,
100
+ };
101
+ }
102
+ return {
103
+ kind: "foreign",
104
+ why: `the lock is held on another host ("${body.hostname}", pid ${String(body.pid)}); a lock from another host is never reclaimed automatically`,
105
+ };
106
+ }
107
+ /**
108
+ * Delete an abandoned lock, but only ever one contender at a time.
109
+ *
110
+ * Reclamation is the one destructive step here, so it gets its own `O_EXCL`
111
+ * file. Without it two contenders can both observe the SAME dead lock and both
112
+ * authorize an unlink; the first unlinks, recreates and enters, and the second's
113
+ * already-authorized unlink then lands on the winner's LIVE lock and lets it
114
+ * enter too. Both would read the same settings revision, both pass the CAS, and
115
+ * one update would be silently lost. Holding the steal lock across the
116
+ * re-observation makes the check-and-delete indivisible with respect to other
117
+ * reclaimers.
118
+ *
119
+ * Reports the REAL outcome, which is also the caller's "progress was made"
120
+ * signal. Reporting success on an unlink that did not happen would be worse
121
+ * than useless: the caller skips its backoff and immediately re-observes the
122
+ * same undeletable lock, spinning for the whole deadline at full CPU.
123
+ */
124
+ async function reclaimAbandonedLock(lockPath, observedToken, deps) {
125
+ const stealPath = stealPathFor(lockPath);
126
+ let handle;
127
+ try {
128
+ handle = await deps.fs.open(stealPath, "wx", 0o600);
129
+ }
130
+ catch (err) {
131
+ // Another contender is already reclaiming (or the steal lock is stranded);
132
+ // either way this contender waits rather than racing it. The errno is
133
+ // carried out because EEXIST (a real contender) and EACCES/EROFS/ENOSPC
134
+ // (the steal lock could not even be created) need different operator
135
+ // advice, and only the former makes "remove that file" sound guidance.
136
+ return { kind: "steal_lock_unavailable", code: errnoCode(err) ?? "unknown" };
137
+ }
138
+ try {
139
+ // Re-observe the FULL body UNDER the steal lock: if the winner already
140
+ // replaced the dead lock, this is a different acquisition and we must not
141
+ // touch it. A body that can no longer be read proves nothing either.
142
+ const current = await readLockBody(deps.fs, lockPath);
143
+ if (current === null || current.token !== observedToken)
144
+ return { kind: "superseded" };
145
+ try {
146
+ await deps.fs.unlink(lockPath);
147
+ return { kind: "reclaimed" };
148
+ }
149
+ catch (err) {
150
+ // ENOENT means somebody else already removed it, which IS progress.
151
+ // Anything else (an immutable flag, EPERM, a read-only mount) is a
152
+ // failure and must not be dressed up as a reclamation.
153
+ const code = errnoCode(err);
154
+ return code === "ENOENT"
155
+ ? { kind: "reclaimed" }
156
+ : { kind: "unlink_failed", code: code ?? "unknown" };
157
+ }
158
+ }
159
+ finally {
160
+ // A close() that rejects (EIO, ENOSPC) must not skip the unlink: stranding
161
+ // our OWN steal lock would trigger by accident the exact residual this
162
+ // design documents as its worst failure mode.
163
+ await handle.close().catch(() => undefined);
164
+ await deps.fs.unlink(stealPath).catch((err) => {
165
+ // Stranding this file disables automatic reclamation for this settings
166
+ // document until an operator removes it. That residual is documented,
167
+ // but swallowing it silently means it only ever surfaces to a LATER
168
+ // contender's timeout.
169
+ deps.warn({ stealPath, err: err instanceof Error ? err.message : String(err) }, "settings lock: could not remove the reclaim lock; automatic reclamation is disabled for this settings document until it is deleted");
170
+ });
171
+ }
172
+ }
173
+ /** The holder identity as the timeout error reports it. */
174
+ function describeHolder(body) {
175
+ if (body === null) {
176
+ return "holder unknown (the lock body is absent, unreadable, or malformed)";
177
+ }
178
+ const host = body.hostname === "" ? "no recorded host" : `host "${body.hostname}"`;
179
+ return `holder ${host}, pid ${String(body.pid)}`;
180
+ }
181
+ function manualRecoveryStep(lockPath, body) {
182
+ const host = body !== null && body.hostname !== "" ? body.hostname : "the host that wrote it";
183
+ return `confirm no writer runs on ${host}, then rm '${lockPath}'`;
184
+ }
185
+ /**
186
+ * Run `fn` while holding an exclusive cross-process lock on the settings
187
+ * directory `dir` (the directory holding `settings.json`).
188
+ *
189
+ * THE EXCLUSION PRIMITIVE. The lock is created by writing the full body to a
190
+ * throwaway `.lock.<token>.tmp` (opened `O_CREAT|O_EXCL`, fsynced) and
191
+ * publishing it with `link(2)`. The kernel arbitrates `link` atomically against
192
+ * every other creator on the same filesystem — including a second ClinkX server
193
+ * process, which is the real case here (a `clinkx` and a `clinkx-test` server,
194
+ * or the dashboard, routinely touch one settings directory at once) — and,
195
+ * because the body is complete before the link, NO CONTENDER EVER OBSERVES AN
196
+ * EMPTY `.lock`. A revision compare-and-swap alone is NOT a substitute:
197
+ * read -> compare -> replace has a window between the compare and the rename,
198
+ * so the CAS detects a lost update while this is what prevents one.
199
+ *
200
+ * RECLAMATION REQUIRES PROOF, NOT AGE — AND ONLY EVER ON THIS HOST. `link`
201
+ * arbitrates creation only, so an unconditional unlink of a lock merely judged
202
+ * old is unsafe: two contenders can both judge the same abandoned lock, the
203
+ * first can unlink-recreate-and-enter, and the second's already-justified
204
+ * unlink then deletes the FIRST's live lock and lets it enter too. So a lock
205
+ * is reclaimed only on positive evidence of death: a dead PID on this host,
206
+ * verified by a probe nothing else can fake. A lock held from ANOTHER host (a
207
+ * container bind-mount dashboard) records a hostname no local probe can
208
+ * check, and staleness cannot distinguish a dead foreign holder from a
209
+ * suspended one, so it is NEVER reclaimed automatically: the acquire deadline
210
+ * expires and the error names the lock path and the manual `rm` (R1). Evidence
211
+ * alone is still not enough to make two simultaneous reclaimers safe, so the
212
+ * unlink itself is serialized behind a second `O_EXCL` file (`.lock.steal`)
213
+ * with a full body re-observation under it before the unlink
214
+ * (`reclaimAbandonedLock`).
215
+ *
216
+ * Release is ownership-checked: the holder re-reads the lock body and unlinks
217
+ * only if the token is still its own, so a holder that was stolen from does not
218
+ * normally delete the new owner's lock. Node exposes no atomic
219
+ * compare-and-unlink, so that check is read-then-unlink and a steal landing
220
+ * inside that window is still possible; the guarantee is "will not", not
221
+ * "cannot".
222
+ *
223
+ * Honest residuals, all accepted under a single-user local-filesystem model:
224
+ * `O_EXCL`/`link` are not reliable on some network filesystems (NFSv2/v3); a
225
+ * PID can be recycled, so a probe can report a live process that is not the
226
+ * original holder; and a foreign-host lock whose holder died without releasing
227
+ * strands saves until an operator removes the file — the timeout error tells
228
+ * them exactly that. The steal lock adds one of its own: a process that dies
229
+ * while holding `.lock.steal` leaves it behind, which disables AUTOMATIC
230
+ * RECLAMATION for this settings document — normal acquisition and release are
231
+ * unaffected — until an operator removes the file. That is strictly the better
232
+ * failure mode: a save that needs a manual unwedge, rather than two writers in
233
+ * the critical section.
234
+ */
235
+ export async function withSettingsLock(dir, fn, options = {}) {
236
+ const fs = options.fs ?? nodeFs;
237
+ const kill = options.kill ?? ((pid, signal) => process.kill(pid, signal));
238
+ const hostnameFn = options.hostname ?? (() => nodeHostname());
239
+ const now = options.now ?? (() => Date.now());
240
+ const warn = options.warn ?? (() => undefined);
241
+ const lockPath = join(dir, LOCK_FILENAME);
242
+ const token = randomBytes(16).toString("hex");
243
+ const acquireTimeoutMs = options.acquireTimeoutMs ?? LOCK_ACQUIRE_TIMEOUT_MS;
244
+ const deadline = now() + acquireTimeoutMs;
245
+ // Carried into the timeout message. Without it every failure reads "locked by
246
+ // another writer", including the one case where there provably is no other
247
+ // writer — a stranded `.lock.steal` blocking the reclamation of a dead
248
+ // holder's lock — which points the operator at the wrong file for the single
249
+ // failure mode this design introduces.
250
+ let lastObservation = "the lock was not observed before the deadline";
251
+ // The last body seen while contending, so the timeout can name the holder
252
+ // (host and pid) and give the manual recovery step for a foreign lock.
253
+ let lastBody = null;
254
+ for (;;) {
255
+ if (now() >= deadline) {
256
+ throw new SettingsLockError(`settings document is locked by another writer and did not release within ${String(acquireTimeoutMs)}ms; lock file ${lockPath}; ${describeHolder(lastBody)}; ${lastObservation}; ${manualRecoveryStep(lockPath, lastBody)}`);
257
+ }
258
+ // Publish the body under a throwaway name first, then link it into place.
259
+ // `.lock` therefore never exists with a partial body: a contender that
260
+ // reads it mid-acquire sees either no lock or a complete one, so an
261
+ // empty lock can never wedge every future save (P2).
262
+ const tmpPath = `${lockPath}.${token}.tmp`;
263
+ try {
264
+ const handle = await fs.open(tmpPath, "wx", 0o600);
265
+ try {
266
+ const body = {
267
+ token,
268
+ pid: process.pid,
269
+ hostname: hostnameFn(),
270
+ startedAt: new Date(now()).toISOString(),
271
+ };
272
+ await handle.writeFile(JSON.stringify(body));
273
+ await handle.sync();
274
+ }
275
+ finally {
276
+ await handle.close();
277
+ }
278
+ await fs.link(tmpPath, lockPath);
279
+ break;
280
+ }
281
+ catch (err) {
282
+ const code = errnoCode(err);
283
+ if (code !== "EEXIST") {
284
+ // The failure touched only our throwaway file; `.lock` was never
285
+ // created, so nothing has to be cleaned up behind us.
286
+ throw err;
287
+ }
288
+ const body = await readLockBody(fs, lockPath);
289
+ lastBody = body;
290
+ const observation = body === null
291
+ ? { kind: "unknown", why: "lock body is absent, unreadable, or malformed" }
292
+ : classifyLockBody(body, { hostname: hostnameFn, kill });
293
+ if (observation.kind === "abandoned") {
294
+ const outcome = await reclaimAbandonedLock(lockPath, observation.token, { fs, warn });
295
+ if (outcome.kind === "reclaimed") {
296
+ lastObservation = `the lock was abandoned (${observation.why}) and was reclaimed`;
297
+ warn({ lockPath, reason: observation.why }, "settings lock: reclaiming abandoned settings lock");
298
+ // Real progress was made, so retry immediately rather than sleeping.
299
+ continue;
300
+ }
301
+ // Reclamation was declined or lost: fall through to the backoff, so a
302
+ // repeatedly-failing reclaim waits out the deadline instead of spinning.
303
+ lastObservation =
304
+ outcome.kind === "steal_lock_unavailable"
305
+ ? outcome.code === "EEXIST"
306
+ ? `the lock looks abandoned (${observation.why}) but reclamation was declined because the reclaim lock ${stealPathFor(lockPath)} already exists — if no writer is running, remove that file`
307
+ : `the lock looks abandoned (${observation.why}) but the reclaim lock ${stealPathFor(lockPath)} could not be created (${outcome.code})`
308
+ : outcome.kind === "superseded"
309
+ ? `the lock looked abandoned (${observation.why}) but another writer replaced it first`
310
+ : `the lock looks abandoned (${observation.why}) but it could not be deleted (${outcome.code})`;
311
+ }
312
+ else {
313
+ lastObservation =
314
+ observation.kind === "live"
315
+ ? "the lock is held by a writer that still looks alive"
316
+ : observation.kind === "foreign"
317
+ ? `the lock will not be reclaimed: ${observation.why}`
318
+ : `the lock could not be judged abandoned: ${observation.why}`;
319
+ }
320
+ await sleep(RETRY_BASE_MS + Math.floor(Math.random() * RETRY_JITTER_MS));
321
+ }
322
+ finally {
323
+ // On success the link consumed the temporary; on contention or failure
324
+ // it must not linger (ENOENT is the expected, ignored outcome).
325
+ await fs.unlink(tmpPath).catch(() => undefined);
326
+ }
327
+ }
328
+ const guard = {
329
+ async assertHeld() {
330
+ if ((await readLockToken(fs, lockPath)) !== token) {
331
+ throw new SettingsLockError("settings lock was reclaimed by another writer mid-update; nothing was written — re-read the settings document and retry");
332
+ }
333
+ },
334
+ };
335
+ try {
336
+ return await fn(guard);
337
+ }
338
+ finally {
339
+ if ((await readLockToken(fs, lockPath)) === token) {
340
+ await fs.unlink(lockPath).catch(() => undefined);
341
+ }
342
+ }
343
+ }
344
+ //# sourceMappingURL=lock.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/settings/lock.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,65 @@
1
+ /** Default directory segments under `$HOME` (XDG_CONFIG_HOME is ignored). */
2
+ export declare const DEFAULT_SETTINGS_DIR = ".config/clinkx/settings";
3
+ /** Name of the settings document inside the settings directory. */
4
+ export declare const SETTINGS_FILE_NAME = "settings.json";
5
+ /** Name of the 0600 secrets document inside the settings directory. */
6
+ export declare const SECRETS_FILE_NAME = "secrets.json";
7
+ /** Per-process heartbeat files live in this subdirectory. */
8
+ export declare const PROCESSES_DIR_NAME = "processes";
9
+ export interface SettingsDirEnv {
10
+ /** Environment record consulted for the override, HOME and CLINKX_HOME. */
11
+ readonly env: Readonly<Record<string, string | undefined>>;
12
+ }
13
+ export type SettingsDirOrigin = "override" | "default" | "invalid" | "unresolvable";
14
+ export interface SettingsDirResolution {
15
+ /** Resolved settings directory; "" when invalid/unresolvable. */
16
+ readonly dir: string;
17
+ readonly origin: SettingsDirOrigin;
18
+ /** Present exactly when origin is "invalid" or "unresolvable". */
19
+ readonly warning?: string;
20
+ }
21
+ /**
22
+ * Validate a `$CLINKX_SETTINGS_DIR` override. Returns a rejection reason or
23
+ * undefined when the override is acceptable. `clinkxHome` is the EFFECTIVE
24
+ * ClinkX home the directory must not live under (`CLINKX_HOME` when set,
25
+ * else `$HOME/.clinkx` — computed by the caller so both the override and the
26
+ * default candidate are held to the same rule, S6).
27
+ */
28
+ export declare function validateSettingsDirOverride(dir: string, home: string | undefined, clinkxHome: string | undefined): string | undefined;
29
+ /** The default settings directory under `home` (XDG is deliberately ignored). */
30
+ export declare function defaultSettingsDirFor(home: string): string;
31
+ /**
32
+ * Resolve the settings directory from an env record. Never touches the
33
+ * filesystem and never throws; a rejected override yields
34
+ * `{ dir: "", origin: "invalid" }` plus a warning for the loader to surface.
35
+ * An empty/whitespace override is treated as unset (some clients export
36
+ * empty strings for unset variables).
37
+ */
38
+ export declare function resolveSettingsDir(input: SettingsDirEnv): SettingsDirResolution;
39
+ /** `<dir>/settings.json` */
40
+ export declare function settingsFilePath(dir: string): string;
41
+ /** `<dir>/secrets.json` */
42
+ export declare function secretsFilePath(dir: string): string;
43
+ /** `<dir>/processes` */
44
+ export declare function processesDirPath(dir: string): string;
45
+ /** `<hostname>-<pid>-<bootNonce>.json` (hostname may itself contain dashes). */
46
+ export declare function processHeartbeatFileName(hostname: string, pid: number, bootNonce: string): string;
47
+ /** `<dir>/processes/<hostname>-<pid>-<bootNonce>.json` */
48
+ export declare function processHeartbeatFilePath(dir: string, hostname: string, pid: number, bootNonce: string): string;
49
+ export interface ProcessHeartbeatFileNameParts {
50
+ readonly hostname: string;
51
+ readonly pid: number;
52
+ readonly bootNonce: string;
53
+ }
54
+ /**
55
+ * Parse a heartbeat file name back into its parts, or undefined when the
56
+ * name does not match the `<host>-<pid>-<32-hex>.json` grammar. Used by the
57
+ * writer's dead-pid prune (and later by the dashboard reader).
58
+ */
59
+ export declare function parseProcessHeartbeatFileName(name: string): ProcessHeartbeatFileNameParts | undefined;
60
+ /**
61
+ * Parse the durable writer's temp name for a heartbeat
62
+ * (`.<heartbeat name>.<pid>.<16-hex>.tmp`), or undefined for any other name.
63
+ * The parts identify the heartbeat, and so the process that wrote the temp.
64
+ */
65
+ export declare function parseProcessHeartbeatTempFileName(name: string): ProcessHeartbeatFileNameParts | undefined;