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.
- package/CHANGELOG.md +28 -0
- package/README.md +13 -6
- package/clinkx-workflows/dist/child-env.d.ts +3 -0
- package/clinkx-workflows/dist/child-env.js +11 -0
- package/clinkx-workflows/dist/child-env.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/api-routes.d.ts +21 -0
- package/clinkx-workflows/dist/dashboard/api-routes.js +27 -0
- package/clinkx-workflows/dist/dashboard/api-routes.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/auth/challenge-store.d.ts +13 -0
- package/clinkx-workflows/dist/dashboard/auth/challenge-store.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/auth/controller.d.ts +27 -0
- package/clinkx-workflows/dist/dashboard/auth/controller.js +262 -23
- package/clinkx-workflows/dist/dashboard/auth/controller.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/auth/settings-step-up.d.ts +62 -0
- package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js +70 -0
- package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js.map +1 -0
- package/clinkx-workflows/dist/dashboard/request-admission.d.ts +6 -0
- package/clinkx-workflows/dist/dashboard/request-admission.js +9 -0
- package/clinkx-workflows/dist/dashboard/request-admission.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/server-factory.js +15 -1
- package/clinkx-workflows/dist/dashboard/server-factory.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/settings-contract.d.ts +1806 -0
- package/clinkx-workflows/dist/dashboard/settings-contract.js +630 -0
- package/clinkx-workflows/dist/dashboard/settings-contract.js.map +1 -0
- package/clinkx-workflows/dist/dashboard/settings-process-reader.d.ts +48 -0
- package/clinkx-workflows/dist/dashboard/settings-process-reader.js +195 -0
- package/clinkx-workflows/dist/dashboard/settings-process-reader.js.map +1 -0
- package/clinkx-workflows/dist/dashboard/settings-routes.d.ts +87 -0
- package/clinkx-workflows/dist/dashboard/settings-routes.js +690 -0
- package/clinkx-workflows/dist/dashboard/settings-routes.js.map +1 -0
- package/clinkx-workflows/dist/dashboard-ui/assets/index-DSOtuS0p.js +122 -0
- package/clinkx-workflows/dist/dashboard-ui/assets/style-C5guUjwN.css +1 -0
- package/clinkx-workflows/dist/dashboard-ui/index.html +2 -2
- package/clinkx-workflows/dist/durable-file-core.d.ts +76 -0
- package/clinkx-workflows/dist/durable-file-core.js +146 -0
- package/clinkx-workflows/dist/durable-file-core.js.map +1 -0
- package/clinkx-workflows/dist/durable-file.d.ts +8 -64
- package/clinkx-workflows/dist/durable-file.js +14 -137
- package/clinkx-workflows/dist/durable-file.js.map +1 -1
- package/clinkx-workflows/dist/index.js +68 -2
- package/clinkx-workflows/dist/index.js.map +1 -1
- package/clinkx-workflows/dist/settings/audit.d.ts +101 -0
- package/clinkx-workflows/dist/settings/audit.js +318 -0
- package/clinkx-workflows/dist/settings/audit.js.map +1 -0
- package/clinkx-workflows/dist/settings/bootstrap.d.ts +35 -0
- package/clinkx-workflows/dist/settings/bootstrap.js +52 -0
- package/clinkx-workflows/dist/settings/bootstrap.js.map +1 -0
- package/clinkx-workflows/dist/settings/codec.d.ts +51 -0
- package/clinkx-workflows/dist/settings/codec.js +410 -0
- package/clinkx-workflows/dist/settings/codec.js.map +1 -0
- package/clinkx-workflows/dist/settings/durable-write.d.ts +48 -0
- package/clinkx-workflows/dist/settings/durable-write.js +31 -0
- package/clinkx-workflows/dist/settings/durable-write.js.map +1 -0
- package/clinkx-workflows/dist/settings/index.d.ts +20 -0
- package/clinkx-workflows/dist/settings/index.js +23 -0
- package/clinkx-workflows/dist/settings/index.js.map +1 -0
- package/clinkx-workflows/dist/settings/loader.d.ts +80 -0
- package/clinkx-workflows/dist/settings/loader.js +577 -0
- package/clinkx-workflows/dist/settings/loader.js.map +1 -0
- package/clinkx-workflows/dist/settings/lock.d.ts +108 -0
- package/clinkx-workflows/dist/settings/lock.js +344 -0
- package/clinkx-workflows/dist/settings/lock.js.map +1 -0
- package/clinkx-workflows/dist/settings/paths.d.ts +65 -0
- package/clinkx-workflows/dist/settings/paths.js +173 -0
- package/clinkx-workflows/dist/settings/paths.js.map +1 -0
- package/clinkx-workflows/dist/settings/process-heartbeat.d.ts +47 -0
- package/clinkx-workflows/dist/settings/process-heartbeat.js +305 -0
- package/clinkx-workflows/dist/settings/process-heartbeat.js.map +1 -0
- package/clinkx-workflows/dist/settings/registry.d.ts +178 -0
- package/clinkx-workflows/dist/settings/registry.js +1285 -0
- package/clinkx-workflows/dist/settings/registry.js.map +1 -0
- package/clinkx-workflows/dist/settings/schema.d.ts +404 -0
- package/clinkx-workflows/dist/settings/schema.js +415 -0
- package/clinkx-workflows/dist/settings/schema.js.map +1 -0
- package/clinkx-workflows/dist/settings/store.d.ts +157 -0
- package/clinkx-workflows/dist/settings/store.js +842 -0
- package/clinkx-workflows/dist/settings/store.js.map +1 -0
- package/clinkx-workflows/dist/stdio-entry.d.ts +2 -0
- package/clinkx-workflows/dist/stdio-entry.js +52 -0
- package/clinkx-workflows/dist/stdio-entry.js.map +1 -0
- package/dist/dashboard-cli.js +50 -1
- package/dist/dashboard-cli.js.map +1 -1
- package/dist/dashboard-companion/protocol.js +17 -0
- package/dist/dashboard-companion/protocol.js.map +1 -1
- package/dist/dashboard-gateway/control-plane/contracts.d.ts +38 -38
- package/dist/dashboard-gateway/tunnel-http.js +20 -0
- package/dist/dashboard-gateway/tunnel-http.js.map +1 -1
- package/dist/elaris/config.d.ts +10 -0
- package/dist/elaris/config.js +27 -1
- package/dist/elaris/config.js.map +1 -1
- package/dist/elaris/tools.js +4 -1
- package/dist/elaris/tools.js.map +1 -1
- package/dist/index.d.ts +0 -31
- package/dist/index.js +41 -404
- package/dist/index.js.map +1 -1
- package/dist/lib.d.ts +17 -0
- package/dist/lib.js +17 -0
- package/dist/lib.js.map +1 -0
- package/dist/progress-report/lock.d.ts +17 -59
- package/dist/progress-report/lock.js +25 -329
- package/dist/progress-report/lock.js.map +1 -1
- package/dist/server.js +75 -4
- package/dist/server.js.map +1 -1
- package/dist/settings-cli/clients.d.ts +137 -0
- package/dist/settings-cli/clients.js +1124 -0
- package/dist/settings-cli/clients.js.map +1 -0
- package/dist/settings-cli/commands.d.ts +67 -0
- package/dist/settings-cli/commands.js +726 -0
- package/dist/settings-cli/commands.js.map +1 -0
- package/dist/settings-cli/format.d.ts +34 -0
- package/dist/settings-cli/format.js +40 -0
- package/dist/settings-cli/format.js.map +1 -0
- package/dist/settings-cli/main.d.ts +18 -0
- package/dist/settings-cli/main.js +256 -0
- package/dist/settings-cli/main.js.map +1 -0
- package/dist/stdio-main.d.ts +73 -0
- package/dist/stdio-main.js +455 -0
- package/dist/stdio-main.js.map +1 -0
- package/docs/configuration.md +340 -39
- package/docs/security.md +150 -6
- package/package.json +2 -2
- package/clinkx-workflows/dist/dashboard-ui/assets/index-DRId2DVA.js +0 -119
- 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;
|