@awebai/oats 0.51.0 → 0.53.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/README.md +3 -1
- package/bin/oats.mjs +407 -123
- package/docs/capabilities.md +75 -6
- package/docs/configuration.md +200 -91
- package/docs/desktop-cli-api.md +1563 -113
- package/docs/desktop-instance-start.md +69 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +145 -58
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +238 -17
- package/docs/integrations.md +13 -9
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -2
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/macos-test-runs.md +246 -0
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +225 -11
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/release-notes/v0.53.0.md +1274 -0
- package/docs/schedules.md +97 -4
- package/docs/souls-and-instances.md +332 -40
- package/docs/tui.md +584 -0
- package/docs/upgrading.md +298 -0
- package/docs/workspaces.md +3 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +278 -49
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +1282 -289
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +45 -17
- package/lib/instance-lifecycle.mjs +306 -57
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +236 -9
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +13 -4
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +190 -25
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +125 -22
- package/lib/schedule.mjs +73 -24
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/system-tools.mjs +39 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +54 -30
- package/lib/worktree-hooks.mjs +98 -20
- package/lib/worktree.mjs +83 -24
- package/package-catalog.json +4 -4
- package/package.json +8 -2
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +561 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +72 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +95 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +180 -0
- package/packages/client/deployment-read-cli.mjs +57 -0
- package/packages/client/display-text.mjs +50 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +90 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +76 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +86 -0
- package/packages/client/instance-tree.mjs +462 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +200 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +413 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +48 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +293 -0
- package/packages/client/readiness-contract.mjs +174 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +151 -0
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +153 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +195 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +142 -0
- package/packages/client/spawn-preview-cli.mjs +38 -0
- package/packages/client/spawn-preview-contract.mjs +318 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +183 -0
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +64 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +44 -0
- package/packages/tui/lib/client.mjs +35 -0
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +176 -0
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +367 -0
- package/packages/tui/lib/term/screen.mjs +134 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +109 -0
- package/packages/tui/lib/term/tty.mjs +178 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +256 -0
- package/packages/tui/lib/views/help.mjs +140 -0
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +30 -23
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- package/lib/launch-prompt-policy.mjs +0 -87
package/lib/claim.mjs
CHANGED
|
@@ -1,45 +1,117 @@
|
|
|
1
1
|
/** The claim: one file that says which process is doing a thing that must happen once at a time.
|
|
2
2
|
* One protocol, used by `oats worktree add|remove` (the purpose's claim, lib/worktree.mjs
|
|
3
|
-
* `withClaim`) and by `oats retire` (the home's claim, lib/core.mjs
|
|
3
|
+
* `withClaim`) and by `oats retire` and `oats instance stop` (the home's claim, lib/core.mjs
|
|
4
|
+
* `claimHomeFor`).
|
|
4
5
|
*
|
|
5
6
|
* Unlike lib/dir-lock.mjs, a claim left by a process that died is taken over, so a killed command
|
|
6
7
|
* can always be run again: the owner is named by pid AND start time (processLiveness), never by a
|
|
7
8
|
* pid alone, and a holder whose start cannot be read is never taken for gone.
|
|
8
9
|
*
|
|
9
|
-
* - Taking it: the owner's facts `{ pid, processStart, nonce, at }
|
|
10
|
-
* and hard-linked to `path`, which fails if
|
|
11
|
-
* owner, and the nonce makes each holding
|
|
10
|
+
* - Taking it: the owner's facts `{ pid, processStart, nonce, at }`, with what the caller adds to
|
|
11
|
+
* them (`facts`), are written to a private file and hard-linked to `path`, which fails if
|
|
12
|
+
* `path` exists. So a claim is never seen without its owner, and the nonce makes each holding
|
|
13
|
+
* distinct, even for the same process.
|
|
12
14
|
* - Its owner is alive: waited for up to `waitMs`, then refused (`busy`).
|
|
13
|
-
* - Its owner is gone (processLiveness "gone"; "unknown" is refused, never
|
|
14
|
-
* is removed under a second claim, `<path>.reclaim-<owner nonce>`, taken
|
|
15
|
+
* - Its owner is gone (processLiveness "gone", which a zombie is too; "unknown" is refused, never
|
|
16
|
+
* taken over): the claim is removed under a second claim, `<path>.reclaim-<owner nonce>`, taken
|
|
17
|
+
* by this same protocol.
|
|
15
18
|
* Its holder re-reads `path` and removes it only if it still names that owner. Nothing else
|
|
16
19
|
* removes another's claim: its owner never releases it, and a new acquirer cannot write over an
|
|
17
20
|
* existing file. Two takeovers of one dead owner are therefore serialized, and neither removes
|
|
18
21
|
* a claim made after it read. A takeover cut short leaves its own claim behind, which the next
|
|
19
22
|
* takeover takes over in turn, up to CLAIM_MAX_DEPTH nested levels.
|
|
23
|
+
* - Its owner is gone and the file cannot be taken over: refused with `cannotTakeOver`, which
|
|
24
|
+
* says that the holder is gone and what to do with the file. Never with `busy`: nobody is
|
|
25
|
+
* running (awebai/oats#874). That is a file whose `nonce` is not the 32 hex digits a claim
|
|
26
|
+
* carries, so no takeover can be serialized on it; the claim of a takeover nested
|
|
27
|
+
* CLAIM_MAX_DEPTH deep; and, which comes first on the file systems there are, one whose
|
|
28
|
+
* takeover claim the system refuses to name: each nested level adds 41 bytes to the name, so a
|
|
29
|
+
* chain of four or five dead takeovers reaches the limit of a file name (ENAMETOOLONG). The
|
|
30
|
+
* refusal names the file whose takeover could not be named, the one to remove.
|
|
20
31
|
* - A step the holder recorded in its claim (recordInClaim) is ended by a takeover first
|
|
21
32
|
* (`endHolderStep`), which refuses, keeping the claim, if the step cannot be ended.
|
|
33
|
+
* - Once a takeover has ended a holder's step, no later answer of that acquisition says that
|
|
34
|
+
* nothing was done: whatever it is then refused with, or fails on, is answered
|
|
35
|
+
* E_LIFECYCLE_FAILED, naming first what was ended. Every refusal is handed what was ended so
|
|
36
|
+
* far (`ended`, the clauses in order; empty before any effect) and writes its own sentence
|
|
37
|
+
* for it (lib/errors.mjs nothingAfter, afterEndedSteps; lifecycleBusy takes `ended`): no
|
|
38
|
+
* message is rewritten here. A refusal that was made without them is still answered after
|
|
39
|
+
* them (claimUnavailable). A refusal before any effect stays what its caller made it.
|
|
22
40
|
* - Released by unlinking `path`, only while it still names this holding.
|
|
23
|
-
* -
|
|
41
|
+
* - A claim that could not be WRITTEN is marked as that, for the one caller that then reads it
|
|
42
|
+
* in place of taking it (`oats instance stop --apply`: lib/core.mjs claimHomeFor). The mark is
|
|
43
|
+
* made at the place, one of the claim's writes (claimWrite: its directory, its private file,
|
|
44
|
+
* its link, and the same of a takeover's own claim), for the system's code as it was thrown
|
|
45
|
+
* there, one of CLAIM_UNWRITABLE_CODES; it travels on the refusal (unwritableCode). No reader
|
|
46
|
+
* of an answer's code, words or details can tell this failure from another, and none tries:
|
|
47
|
+
* a defect, and a claim that could not be removed, are E_LIFECYCLE_FAILED too. Whether
|
|
48
|
+
* anybody holds a claim that was not taken is read by claimUnheld, which says "nobody" only
|
|
49
|
+
* of a path that is absent or of a claim whose holder is verifiably gone.
|
|
50
|
+
* - A claim is read back as whatever JSON is in its file, and the file is where others than its
|
|
51
|
+
* writer can write. Who holds it, and whether that process lives, is decided on the record as
|
|
52
|
+
* it is; what an ANSWER shows of it is only what shownHolder allows, never the file's text.
|
|
53
|
+
* - An unreadable claim file is never removed: the command is refused, naming the file. So is a
|
|
54
|
+
* path that exists and keeps reading as absent (a dangling symbolic link where the claim
|
|
55
|
+
* belongs), once the retries below are spent.
|
|
56
|
+
* - Every pass that does not take the claim falls through one check of its time and one pause
|
|
57
|
+
* (takeClaim): none starts the next pass at once, so no state of the path makes it spin, and
|
|
58
|
+
* each ends in a refusal within `waitMs` plus CLAIM_FREED_RETRIES pauses (awebai/oats#874).
|
|
59
|
+
* A claim that every one of those passes found held again by a process that is gone, after it
|
|
60
|
+
* took the one before over, is refused with `heldAgain`: an ordinary claim, which the next
|
|
61
|
+
* run takes over.
|
|
62
|
+
* - A claim that cannot be taken for a reason of the system's (its directory cannot be made, its
|
|
63
|
+
* private file cannot be written, the link fails otherwise than because the claim exists) is
|
|
64
|
+
* refused as E_LIFECYCLE_FAILED (claimUnavailable), never with the system's code
|
|
65
|
+
* (awebai/oats#874): the claim was not taken, so nothing was done.
|
|
24
66
|
*
|
|
25
|
-
* Everything is synchronous. What is the caller's own goes in `opts
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
67
|
+
* Everything is synchronous. What is the caller's own goes in `opts`. Each refusal is an error
|
|
68
|
+
* whose message states its effects, once: in the caller's words for "nothing was done" before
|
|
69
|
+
* any effect, and as "nothing else was done" when `ended`, its last argument, names what this
|
|
70
|
+
* acquisition's takeovers ended before it:
|
|
71
|
+
* busy(holder, unknown, at, ended) the refusal for a holder that lives (`unknown` unset)
|
|
72
|
+
* or whose liveness cannot be read (`unknown` is the
|
|
73
|
+
* reason); `at` is the claim file that names it
|
|
74
|
+
* ownStartUnreadable(reason, at, ended) the refusal when this process's own start cannot be
|
|
75
|
+
* read, so it could not hold `at` verifiably
|
|
76
|
+
* unreadableClaim(at, ended) the refusal for a claim file that does not parse, or
|
|
77
|
+
* for a path that exists and cannot be read as one
|
|
78
|
+
* cannotTakeOver(holder, at, why, ended) the refusal for a holder that is gone and whose claim
|
|
79
|
+
* file `at` this kernel cannot take over; `why` is a
|
|
80
|
+
* clause saying what stops it
|
|
81
|
+
* heldAgain(holder, at, times, ended) the refusal for a claim that this command found
|
|
82
|
+
* without a live holder `times` times and that was
|
|
83
|
+
* taken again each time, the last time by `holder`,
|
|
84
|
+
* which is gone: nothing is wrong with `at`
|
|
85
|
+
* endHolderStep(holder, at, ended) optional: end the step a dead holder recorded
|
|
86
|
+
* → { refusal?, warning?, ended? }; `refusal` is the
|
|
87
|
+
* caller's answer for a step that could not be ended
|
|
88
|
+
* (`at` is kept); `ended` is a clause naming what it
|
|
89
|
+
* ended, when it ended something
|
|
34
90
|
* waitMs how long a live holder is waited for (default CLAIM_WAIT_MS)
|
|
35
|
-
* warnings optional array a takeover's warnings are pushed to
|
|
36
|
-
|
|
91
|
+
* warnings optional array a takeover's warnings are pushed to
|
|
92
|
+
* facts optional object, what the caller's claim says besides its
|
|
93
|
+
* owner (a home's lifecycle claim: `action`, the holder's verb).
|
|
94
|
+
* It is in the record that is linked, so the claim is never
|
|
95
|
+
* seen without it; the owner's four fields win over it */
|
|
96
|
+
import { linkSync, lstatSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
|
|
37
97
|
import { randomBytes } from "node:crypto";
|
|
38
|
-
import { processLiveness, processStart } from "./worktree-hooks.mjs";
|
|
98
|
+
import { isStartToken, processLiveness, processStart } from "./worktree-hooks.mjs";
|
|
99
|
+
import { NOTHING_ELSE, afterEndedSteps, asKernelError, nothingAfter } from "./errors.mjs";
|
|
39
100
|
|
|
40
101
|
export const CLAIM_WAIT_MS = 3000;
|
|
41
102
|
const CLAIM_MAX_DEPTH = 8;
|
|
103
|
+
/** How long a pass that did not take the claim pauses before the next one. */
|
|
104
|
+
const CLAIM_PAUSE_MS = 50;
|
|
105
|
+
/** How many passes that found nobody holding the claim (it read as absent, or its holder was gone
|
|
106
|
+
* and it was taken over) are followed by another once `waitMs` is over; passes before that are
|
|
107
|
+
* not counted. With `waitMs: 0` that is every retry there is: enough for the true race, a claim
|
|
108
|
+
* released or freed between two steps of this process, and an end for a path that never becomes
|
|
109
|
+
* a claim. */
|
|
110
|
+
const CLAIM_FREED_RETRIES = 5;
|
|
42
111
|
const NONCE_RE = /^[0-9a-f]{32}$/;
|
|
112
|
+
const ISO_INSTANT = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$/;
|
|
113
|
+
/** Whether `at` is an instant exactly as `toISOString()` gives it, and one that exists. */
|
|
114
|
+
const isInstant = (at) => typeof at === "string" && ISO_INSTANT.test(at) && !Number.isNaN(Date.parse(at)) && new Date(at).toISOString() === at;
|
|
43
115
|
const pauseSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
|
|
44
116
|
|
|
45
117
|
/** The claim at `path` → its record, `{ unreadable: true }` when it does not parse, null when there is none. */
|
|
@@ -48,53 +120,209 @@ export function readClaim(path) {
|
|
|
48
120
|
catch (e) { return e.code === "ENOENT" ? null : { unreadable: true }; }
|
|
49
121
|
}
|
|
50
122
|
|
|
51
|
-
/**
|
|
52
|
-
*
|
|
123
|
+
/** What of the claim record `record` may be shown in an answer → `{ pid, since, start }`, each
|
|
124
|
+
* null unless it has the shape takeClaim writes it in:
|
|
125
|
+
* pid the record's `pid`, a positive safe integer;
|
|
126
|
+
* since the record's `at`, exactly what `toISOString()` gives (`2026-01-01T00:00:00.000Z`);
|
|
127
|
+
* start the record's `processStart`, a token of the kernel's (worktree-hooks isStartToken).
|
|
128
|
+
* A claim is a file in a directory that other instances of the deployment can write, and it is
|
|
129
|
+
* read back as whatever JSON is there: text of it is never part of an answer. Every refusal of a
|
|
130
|
+
* claim names its holder through this, in its message and in its `details`; a caller's own
|
|
131
|
+
* fact (`facts`) has its own closed reading (lib/core.mjs claimAction). Only for what is shown:
|
|
132
|
+
* who holds the claim, and whether it lives, is decided on the record as it is. */
|
|
133
|
+
export function shownHolder(record) {
|
|
134
|
+
const { pid, at, processStart: start } = record && typeof record === "object" ? record : {};
|
|
135
|
+
return {
|
|
136
|
+
pid: Number.isSafeInteger(pid) && pid > 0 ? pid : null,
|
|
137
|
+
since: isInstant(at) ? at : null,
|
|
138
|
+
start: isStartToken(start) ? start : null,
|
|
139
|
+
};
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** The system's codes for which a claim that cannot be written is read in place of being taken, by
|
|
143
|
+
* the one verb that may (a stop apply). Each is here for one reason: what stops this process
|
|
144
|
+
* from writing a claim in that directory stops a retire or another stop of the same user as
|
|
145
|
+
* well, so a claim that reads as held by nobody is held by nobody.
|
|
146
|
+
* ENOSPC the file system is full
|
|
147
|
+
* EDQUOT this user's quota is spent
|
|
148
|
+
* EROFS the file system is read-only
|
|
149
|
+
* EACCES, EPERM the claims directory is not writable by this user (EPERM also where the file
|
|
150
|
+
* system has no hard links). Every instance of a deployment can change that
|
|
151
|
+
* directory, and one that takes write permission from it must not take Stop from the
|
|
152
|
+
* operator.
|
|
153
|
+
* It is not true of space that is freed a moment later, nor of a process of another user. Any
|
|
154
|
+
* other code (EIO, EMFILE, ENAMETOOLONG, EEXIST from a file where the directory belongs) says
|
|
155
|
+
* nothing about who else could write there, and is never in this list. */
|
|
156
|
+
export const CLAIM_UNWRITABLE_CODES = Object.freeze(["ENOSPC", "EDQUOT", "EROFS", "EACCES", "EPERM"]);
|
|
157
|
+
const UNWRITABLE = Symbol("oats.claimUnwritable");
|
|
158
|
+
/** Make one of a claim's writes: `write()`, and what it returns. An error of the system's it
|
|
159
|
+
* throws with a code of CLAIM_UNWRITABLE_CODES is marked with that code and thrown as it is:
|
|
160
|
+
* the place and the code as thrown are what make a claim "one that could not be written"
|
|
161
|
+
* (unwritableCode). For the writes of taking a claim and for no other call: its directory
|
|
162
|
+
* (the caller's mkdir), its private file, its link. */
|
|
163
|
+
export function claimWrite(write) {
|
|
164
|
+
try { return write(); }
|
|
165
|
+
catch (e) {
|
|
166
|
+
if (e instanceof Error && typeof e.syscall === "string" && CLAIM_UNWRITABLE_CODES.includes(e.code)) Object.defineProperty(e, UNWRITABLE, { value: e.code });
|
|
167
|
+
throw e;
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
/** The code for which the claim behind `refusal` could not be written (CLAIM_UNWRITABLE_CODES),
|
|
171
|
+
* when that is why it was not taken and nothing was ended before; else undefined. `refusal` is
|
|
172
|
+
* what acquireClaim or claimUnavailable answered. */
|
|
173
|
+
export const unwritableCode = (refusal) => (refusal instanceof Error ? refusal[UNWRITABLE] : undefined);
|
|
174
|
+
|
|
175
|
+
/** The refusal for a claim `path` that could not be taken because of `e`, an error that is not the
|
|
176
|
+
* kernel's. The caller's command did nothing: it acts only once it holds its claim. Also for a
|
|
177
|
+
* caller that fails to make the claim's directory. `ended` is what this acquisition's takeovers
|
|
178
|
+
* ended before `e`: with it the answer names that first and says "nothing else was done". An
|
|
179
|
+
* error that is the kernel's is returned as it is before any effect, and after what was ended
|
|
180
|
+
* otherwise: the refusals of a claim are made for `ended` already, and one that was not still
|
|
181
|
+
* never says, by its code, that nothing happened. The one error on the way to a claim that itself
|
|
182
|
+
* comes after something was done says so (takeOver: the claim of a gone holder that cannot be
|
|
183
|
+
* removed once that holder's step was ended). */
|
|
184
|
+
export function claimUnavailable(path, e, ended) {
|
|
185
|
+
const refusal = asKernelError(e, "E_LIFECYCLE_FAILED", `the claim ${path} could not be taken (${e?.message ?? e}); ${nothingAfter(ended)}`);
|
|
186
|
+
// The mark of a write that failed (claimWrite) goes with the refusal. Once something was ended
|
|
187
|
+
// the answer is another error, made below, and carries none: nobody reads a claim in the place
|
|
188
|
+
// of an answer that says what was done.
|
|
189
|
+
const code = unwritableCode(e);
|
|
190
|
+
if (code && refusal !== e) Object.defineProperty(refusal, UNWRITABLE, { value: code });
|
|
191
|
+
return afterEndedSteps(ended, refusal);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/** Whether anybody holds the claim `path`, read and not taken: for the caller whose claim could
|
|
195
|
+
* not be written (unwritableCode). Returns when NOBODY holds it, which is said only of a path
|
|
196
|
+
* that is absent and of a claim whose holder is verifiably gone and that could be taken over
|
|
197
|
+
* (it is left as it is). Throws otherwise, what taking it would have answered for what is
|
|
198
|
+
* there, from the caller's refusals (`opts`, as acquireClaim takes them):
|
|
199
|
+
* a holder that lives, or whose liveness cannot be read busy
|
|
200
|
+
* bytes that are no claim; a directory; a path that is
|
|
201
|
+
* there and reads as absent (a dangling symbolic link) unreadableClaim
|
|
202
|
+
* a gone holder whose claim no kernel can take over cannotTakeOver
|
|
203
|
+
* and `otherwise`, the refusal of the write that failed, when the read itself fails for a
|
|
204
|
+
* reason of the system's: the path was not reached, so neither a holder nor nobody was
|
|
205
|
+
* established. The read is positive or it is nothing. */
|
|
206
|
+
export function claimUnheld(path, opts, otherwise) {
|
|
207
|
+
for (let pass = 0; ; pass++) {
|
|
208
|
+
let text;
|
|
209
|
+
try { text = readFileSync(path, "utf8"); }
|
|
210
|
+
catch (e) {
|
|
211
|
+
// Something is there that is no file to read: no claim, as the taking finds it.
|
|
212
|
+
if (e?.code === "EISDIR") throw opts.unreadableClaim(path, []);
|
|
213
|
+
if (e?.code !== "ENOENT") throw otherwise;
|
|
214
|
+
// Absent, unless the path itself is there: a link to nowhere reads as absent for ever.
|
|
215
|
+
let entry;
|
|
216
|
+
try { entry = lstatSync(path); } catch (e2) { if (e2?.code === "ENOENT") return; throw otherwise; }
|
|
217
|
+
// A claim made between the two reads is read again, once, and is a claim.
|
|
218
|
+
if (entry.isSymbolicLink() || pass) throw opts.unreadableClaim(path, []);
|
|
219
|
+
continue;
|
|
220
|
+
}
|
|
221
|
+
let holder;
|
|
222
|
+
try { holder = JSON.parse(text); } catch { holder = null; }
|
|
223
|
+
// readClaim's own reading of bytes that are no claim, `unreadable` in a record included.
|
|
224
|
+
if (!holder || typeof holder !== "object" || holder.unreadable) throw opts.unreadableClaim(path, []);
|
|
225
|
+
const live = processLiveness(holder);
|
|
226
|
+
if (live.state !== "gone") throw opts.busy(holder, live.state === "unknown" ? live.reason : null, path, []);
|
|
227
|
+
const stuck = cannotBeTakenOver(holder, 0);
|
|
228
|
+
if (stuck) throw opts.cannotTakeOver(holder, path, stuck, []);
|
|
229
|
+
return;
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** Take the claim `path` → this holding (`{ pid, processStart, nonce, at }`, with `opts.facts`), to
|
|
234
|
+
* pass to releaseClaim. Throws the caller's refusal when it cannot be taken, and claimUnavailable for
|
|
235
|
+
* any error that is not the kernel's. The directory exists. */
|
|
53
236
|
export function acquireClaim(path, opts, depth = 0) {
|
|
237
|
+
const endedSteps = [];
|
|
238
|
+
try { return takeClaim(path, opts, depth, endedSteps); }
|
|
239
|
+
catch (e) { throw claimUnavailable(path, e, endedSteps); }
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** `endedSteps` collects what the takeovers of one acquisition ended, nested ones included; every
|
|
243
|
+
* refusal is handed it as it is when the refusal is made. */
|
|
244
|
+
function takeClaim(path, opts, depth, endedSteps) {
|
|
54
245
|
const { busy, waitMs = CLAIM_WAIT_MS } = opts;
|
|
55
246
|
const own = processStart(process.pid);
|
|
56
|
-
if (own.state !== "alive") throw opts.ownStartUnreadable(own.reason ?? `pid ${process.pid} reads as ${own.state}`, path);
|
|
57
|
-
const me = { pid: process.pid, processStart: own.token, nonce: randomBytes(16).toString("hex"), at: new Date().toISOString() };
|
|
247
|
+
if (own.state !== "alive") throw opts.ownStartUnreadable(own.reason ?? `pid ${process.pid} reads as ${own.state}`, path, endedSteps);
|
|
248
|
+
const me = { ...opts.facts, pid: process.pid, processStart: own.token, nonce: randomBytes(16).toString("hex"), at: new Date().toISOString() };
|
|
58
249
|
const tmp = `${path}.tmp-${process.pid}-${me.nonce}`;
|
|
59
|
-
writeFileSync(tmp, JSON.stringify(me) + "\n", { mode: 0o600 });
|
|
60
250
|
try {
|
|
251
|
+
// Inside the block that removes it: a write that fails after the file was created (a full
|
|
252
|
+
// file system does exactly that) leaves nothing behind.
|
|
253
|
+
claimWrite(() => writeFileSync(tmp, JSON.stringify(me) + "\n", { mode: 0o600 }));
|
|
61
254
|
const deadline = Date.now() + waitMs;
|
|
62
|
-
for (
|
|
63
|
-
try { linkSync(tmp, path); return me; }
|
|
64
|
-
catch (e) { if (e
|
|
255
|
+
for (let freed = 0; ;) {
|
|
256
|
+
try { claimWrite(() => linkSync(tmp, path)); return me; }
|
|
257
|
+
catch (e) { if (e?.code !== "EEXIST") throw e; }
|
|
65
258
|
const holder = readClaim(path);
|
|
66
|
-
if (holder
|
|
67
|
-
|
|
68
|
-
const live = processLiveness(holder);
|
|
259
|
+
if (holder?.unreadable) throw opts.unreadableClaim(path, endedSteps);
|
|
260
|
+
const live = holder ? processLiveness(holder) : null;
|
|
69
261
|
// Unreadable is never taken for gone: the claim is kept, and the refusal names the way out.
|
|
70
|
-
if (live
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
262
|
+
if (live?.state === "unknown") throw busy(holder, live.reason, path, endedSteps);
|
|
263
|
+
const gone = live?.state === "gone";
|
|
264
|
+
const stuck = gone ? cannotBeTakenOver(holder, depth) : null;
|
|
265
|
+
if (stuck) throw opts.cannotTakeOver(holder, path, stuck, endedSteps);
|
|
266
|
+
// Nobody holds it: the link said it exists and it reads as absent (released in between; or a
|
|
267
|
+
// path that never reads, a dangling symbolic link), or its holder is gone and it is taken
|
|
268
|
+
// over below. The next pass is owed even with no time to wait, but not for ever.
|
|
269
|
+
const free = !holder || gone;
|
|
270
|
+
// What this pass answers once its time is up, about the file as it has just been read. A
|
|
271
|
+
// gone holder here is the last of several: each pass took the one before over, and the
|
|
272
|
+
// claim was taken again before this process could. The file is a claim like any other.
|
|
273
|
+
const refusal = !holder ? () => opts.unreadableClaim(path, endedSteps)
|
|
274
|
+
: gone ? () => opts.heldAgain(holder, path, freed, endedSteps)
|
|
275
|
+
: () => busy(holder, null, path, endedSteps);
|
|
276
|
+
// One check of its time and one pause for every pass that did not take the claim: nothing
|
|
277
|
+
// above starts the next pass (lib/remote.mjs withCacheWriteLock, the same rule).
|
|
278
|
+
if (Date.now() >= deadline) {
|
|
279
|
+
if (!(free && freed < CLAIM_FREED_RETRIES)) throw refusal();
|
|
280
|
+
freed++;
|
|
75
281
|
}
|
|
76
|
-
if (
|
|
77
|
-
pauseSync(
|
|
282
|
+
if (gone) takeOver(path, holder, opts, depth, endedSteps);
|
|
283
|
+
pauseSync(CLAIM_PAUSE_MS);
|
|
78
284
|
}
|
|
79
285
|
} finally {
|
|
80
286
|
try { unlinkSync(tmp); } catch { /* gone */ }
|
|
81
287
|
}
|
|
82
288
|
}
|
|
83
289
|
|
|
84
|
-
/**
|
|
85
|
-
|
|
290
|
+
/** Why the claim of the gone `holder`, met at `depth`, cannot be taken over → a clause, or null
|
|
291
|
+
* when it can. A takeover is serialized on the holder's nonce, so a file without one that this
|
|
292
|
+
* kernel writes is not removed by anybody (removeGoneClaim skips it too). */
|
|
293
|
+
function cannotBeTakenOver(holder, depth) {
|
|
294
|
+
if (typeof holder.nonce !== "string" || !NONCE_RE.test(holder.nonce)) return "its nonce is not the 32 hexadecimal digits a claim carries";
|
|
295
|
+
if (depth >= CLAIM_MAX_DEPTH) return `it is the claim of a takeover nested ${CLAIM_MAX_DEPTH} deep`;
|
|
296
|
+
return null;
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
/** Remove `path`, held by the dead `holder`, under the claim that serializes takeovers of it. What
|
|
300
|
+
* it ended of the holder's goes to `endedSteps`, once the claim is removed. */
|
|
301
|
+
function takeOver(path, holder, opts, depth, endedSteps) {
|
|
86
302
|
const reclaim = `${path}.reclaim-${holder.nonce}`;
|
|
87
|
-
|
|
303
|
+
let me;
|
|
304
|
+
try { me = takeClaim(reclaim, opts, depth + 1, endedSteps); }
|
|
305
|
+
catch (e) {
|
|
306
|
+
// The system will not name the claim of this takeover: `path` is as deep as takeovers nest
|
|
307
|
+
// here. Its own answer is read, never a limit assumed, so this holds on any file system; and
|
|
308
|
+
// it comes before the holder's step is ended or anything is removed. A refusal from a level
|
|
309
|
+
// below is a kernel error and passes as it is, so the answer names the deepest claim reached.
|
|
310
|
+
if (e?.code === "ENAMETOOLONG") throw opts.cannotTakeOver(holder, path, "the claim of one more takeover would have a name longer than this file system allows", endedSteps);
|
|
311
|
+
throw claimUnavailable(reclaim, e, endedSteps);
|
|
312
|
+
}
|
|
88
313
|
try {
|
|
89
314
|
const now = readClaim(path);
|
|
90
315
|
if (now?.nonce === holder.nonce) {
|
|
91
|
-
const ended = opts.endHolderStep?.(now, path) ?? {};
|
|
92
|
-
if (ended.
|
|
93
|
-
const e = opts.busy(now);
|
|
94
|
-
throw Object.assign(e, { message: `${ended.owed}; ${path} is kept and nothing was done — ${ended.remedy}`, details: { ...e.details, ...ended.details } });
|
|
95
|
-
}
|
|
316
|
+
const ended = opts.endHolderStep?.(now, path, endedSteps) ?? {};
|
|
317
|
+
if (ended.refusal) throw ended.refusal;
|
|
96
318
|
if (ended.warning) opts.warnings?.push(ended.warning);
|
|
97
|
-
unlinkSync(path);
|
|
319
|
+
try { unlinkSync(path); }
|
|
320
|
+
catch (e) {
|
|
321
|
+
// The holder's step is ended by now: "nothing was done" (claimUnavailable) would not be true.
|
|
322
|
+
if (!ended.ended) throw e;
|
|
323
|
+
throw asKernelError(e, "E_LIFECYCLE_FAILED", `the claim ${path} could not be taken (${e?.message ?? e}): ${ended.ended}, and the claim it left is kept; ${NOTHING_ELSE}`);
|
|
324
|
+
}
|
|
325
|
+
if (ended.ended) endedSteps.push(ended.ended);
|
|
98
326
|
}
|
|
99
327
|
} finally {
|
|
100
328
|
releaseClaim(reclaim, me);
|
|
@@ -116,11 +344,12 @@ export function recordInClaim(path, me, step) {
|
|
|
116
344
|
|
|
117
345
|
/** Remove the claim `path` when its holder is verifiably gone, through the takeover above, and
|
|
118
346
|
* take nothing: for a claim nobody will come back for. → whether it was removed. A claim whose
|
|
119
|
-
* holder is alive, unknown or unreadable
|
|
347
|
+
* holder is alive, unknown or unreadable, or that cannot be taken over (cannotBeTakenOver), is
|
|
348
|
+
* left as it is. Throws what a takeover throws. */
|
|
120
349
|
export function removeGoneClaim(path, opts) {
|
|
121
350
|
const holder = readClaim(path);
|
|
122
|
-
if (!holder || holder.unreadable ||
|
|
351
|
+
if (!holder || holder.unreadable || cannotBeTakenOver(holder, 0)) return false;
|
|
123
352
|
if (processLiveness(holder).state !== "gone") return false;
|
|
124
|
-
takeOver(path, holder, opts, 0);
|
|
353
|
+
takeOver(path, holder, opts, 0, []);
|
|
125
354
|
return readClaim(path)?.nonce !== holder.nonce;
|
|
126
355
|
}
|
package/lib/config-data.mjs
CHANGED
|
@@ -34,6 +34,9 @@ function boundedYaml(source, limits) {
|
|
|
34
34
|
}
|
|
35
35
|
return result;
|
|
36
36
|
}
|
|
37
|
+
/** The syntax `format: "auto"` reads a document as: one that opens with `{` or `[` is strict JSON, anything
|
|
38
|
+
* else YAML. A writer that rewrites a document keeps it in the syntax this names (lib/local-edit.mjs). */
|
|
39
|
+
export const isJsonSource = (source) => /^[\s]*[\[{]/.test(source);
|
|
37
40
|
export function parseConfigData(input, { format = "auto", origin = null, limits: requested = {} } = {}) {
|
|
38
41
|
const limits = dataLimits({ maxBytes: 1024 * 1024, ...requested });
|
|
39
42
|
const data = typeof input === "string" ? input : byteView(input);
|
|
@@ -42,7 +45,7 @@ export function parseConfigData(input, { format = "auto", origin = null, limits:
|
|
|
42
45
|
const source = decodeUtf8(input);
|
|
43
46
|
canonicalJson(origin, { maxBytes: 64 * 1024, maxDepth: 16, maxEntries: 1024 });
|
|
44
47
|
if (!["auto", "json", "yaml"].includes(format)) throw oatsError("invalid-declaration", "unsupported configuration syntax");
|
|
45
|
-
const json = format === "json" || (format === "auto" &&
|
|
48
|
+
const json = format === "json" || (format === "auto" && isJsonSource(source));
|
|
46
49
|
const origins = Object.create(null);
|
|
47
50
|
let entries = 0;
|
|
48
51
|
const mark = (pointer, depth, node) => {
|