@joe-broadhead/opencode-mem 0.9.14 → 0.11.3
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 +1856 -0
- package/README.md +15 -7
- package/SECURITY.md +3 -1
- package/docs/agent-instructions.md +1 -1
- package/docs/agent-protocol.md +7 -7
- package/docs/permissions.md +16 -0
- package/package.json +8921 -1070
- package/shared/page-paths.js +44 -0
- package/skills/mem.pages/SKILL.md +3 -1
- package/skills/mem.usage/SKILL.md +15 -15
- package/src/action-grant-keys.js +159 -0
- package/src/action-grant.js +439 -0
- package/src/actions.js +1690 -0
- package/src/backend/records.js +25 -2
- package/src/backend/v3.js +76 -22
- package/src/call-shapes.js +17 -16
- package/src/collector-lock.js +533 -62
- package/src/collector-service.js +153 -26
- package/src/collector.js +623 -30
- package/src/config.js +88 -7
- package/src/connect.js +106 -8
- package/src/credentials.js +123 -25
- package/src/events.js +174 -3
- package/src/forget-turn.js +141 -0
- package/src/host-refusal.js +78 -0
- package/src/index.js +209 -22
- package/src/jobs/host.js +557 -0
- package/src/ops/codes.js +110 -0
- package/src/ops/copy-lineage.js +42 -0
- package/src/ops/index.js +28 -0
- package/src/ops/space-ops.js +1936 -0
- package/src/outlinks.js +103 -0
- package/src/p2-reservation.js +151 -0
- package/src/permissions.js +30 -0
- package/src/plugins/descriptor.js +62 -0
- package/src/plugins/discovery.js +318 -0
- package/src/plugins/grants.js +178 -0
- package/src/plugins/locate.js +319 -0
- package/src/plugins/manifest.js +1162 -0
- package/src/plugins/source-contract/index.js +34 -0
- package/src/plugins/source-contract/policy.js +102 -0
- package/src/plugins/source-contract/vendor/PROVENANCE.json +17 -0
- package/src/plugins/source-contract/vendor/RELEASE-SHA256SUMS +3 -0
- package/src/plugins/source-contract/vendor/RELEASE.json +17 -0
- package/src/plugins/source-contract/vendor/SHA256SUMS +41 -0
- package/src/plugins/source-contract/vendor/THIRD-PARTY-NOTICES.md +35 -0
- package/src/plugins/source-contract/vendor/broker-client.js +93 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-3M5PAKSS.js +84 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-4ERCA4TK.js +185 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-6HDIB2SA.js +183 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-ELPJD3ND.js +10 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-HLVAKAYG.js +10 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-I2RXJJJM.js +81 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-KWEWSZ4V.js +505 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-KYWBTAF4.js +182 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-Q3RQA5J2.js +249 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-RRUAIQ4I.js +156 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-RYNKNCPP.js +165 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-W5SHR7DQ.js +9477 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-ZUKF7P6U.js +653 -0
- package/src/plugins/source-contract/vendor/cursor.js +26 -0
- package/src/plugins/source-contract/vendor/descriptor.js +34 -0
- package/src/plugins/source-contract/vendor/events.js +257 -0
- package/src/plugins/source-contract/vendor/index.js +10 -0
- package/src/plugins/source-contract/vendor/params.js +22 -0
- package/src/plugins/source-contract/vendor/permission.js +28 -0
- package/src/plugins/source-contract/vendor/pick.js +22 -0
- package/src/plugins/source-contract/vendor/read.js +29 -0
- package/src/plugins/source-contract/vendor/registry.js +23 -0
- package/src/plugins/source-contract/vendor/schema.js +17 -0
- package/src/plugins/source-contract/vendor/schemas/output.agenda.json +96 -0
- package/src/plugins/source-contract/vendor/schemas/output.countdown.json +28 -0
- package/src/plugins/source-contract/vendor/schemas/output.image.json +28 -0
- package/src/plugins/source-contract/vendor/schemas/output.inbox.json +84 -0
- package/src/plugins/source-contract/vendor/schemas/output.links.json +46 -0
- package/src/plugins/source-contract/vendor/schemas/output.list.json +57 -0
- package/src/plugins/source-contract/vendor/schemas/output.metric.json +61 -0
- package/src/plugins/source-contract/vendor/schemas/output.note.json +14 -0
- package/src/plugins/source-contract/vendor/schemas/output.progress.json +50 -0
- package/src/plugins/source-contract/vendor/schemas/output.record.json +38 -0
- package/src/plugins/source-contract/vendor/schemas/output.table.json +61 -0
- package/src/plugins/source-contract/vendor/schemas/output.thread.json +62 -0
- package/src/plugins/source-contract/vendor/schemas/sources.json +819 -0
- package/src/plugins/source-contract/vendor/schemas.js +19 -0
- package/src/plugins/source-contract/vendor/tools-rpc.js +42 -0
- package/src/plugins/verify.js +56 -0
- package/src/protocol.js +11 -6
- package/src/recall.js +92 -5
- package/src/records.js +61 -2
- package/src/requests.js +216 -0
- package/src/runtime.js +89 -7
- package/src/setup-time.js +68 -0
- package/src/skills.js +230 -8
- package/src/source-ids.js +25 -0
- package/src/sources/declaration.js +365 -0
- package/src/sources/reads.js +772 -0
- package/src/sources/rpc.js +151 -0
- package/src/sources.js +389 -92
- package/src/spaces.js +283 -11
- package/src/spool.js +61 -4
- package/src/stated.js +10 -5
- package/src/storable.js +139 -0
- package/src/tools/commitments.js +74 -23
- package/src/tools/held-write.js +46 -19
- package/src/tools/index.js +28 -0
- package/src/tools/ingest.js +38 -2
- package/src/tools/memory.js +56 -25
- package/src/tools/page.js +212 -95
- package/src/tools/recall.js +218 -4
- package/src/tools/share.js +42 -3
- package/src/tools/shared.js +84 -6
- package/src/tools/space-lifecycle.js +278 -0
- package/src/tools/spaces.js +381 -30
- package/src/tools/status.js +9 -2
- package/src/tools/wiki.js +231 -116
- package/src/util.js +110 -6
- package/src/vendor/source-contract/README.md +24 -0
- package/src/vendor/source-contract/THIRD-PARTY-NOTICES.md +35 -0
- package/src/vendor/source-contract/VENDOR.json +81 -0
- package/src/vendor/source-contract/chunks/chunk-3M5PAKSS.js +84 -0
- package/src/vendor/source-contract/chunks/chunk-6HDIB2SA.js +183 -0
- package/src/vendor/source-contract/chunks/chunk-HLVAKAYG.js +10 -0
- package/src/vendor/source-contract/chunks/chunk-I2RXJJJM.js +81 -0
- package/src/vendor/source-contract/chunks/chunk-KWEWSZ4V.js +505 -0
- package/src/vendor/source-contract/chunks/chunk-W5SHR7DQ.js +9477 -0
- package/src/vendor/source-contract/chunks/chunk-ZUKF7P6U.js +653 -0
- package/src/vendor/source-contract/cursor.js +26 -0
- package/src/vendor/source-contract/events.js +257 -0
- package/src/vendor/source-contract/registry.js +23 -0
- package/src/vendor/source-contract/tools-rpc.js +42 -0
- package/src/views/access-reads.js +256 -0
- package/src/views/communities.js +77 -0
- package/src/views/contracts.js +1082 -23
- package/src/views/inbox-bytes.js +103 -0
- package/src/views/profile.js +31 -0
- package/src/views/receipt.js +26 -1
- package/src/views/records-reads.js +520 -41
- package/src/views/rpc.js +153 -25
- package/src/views/shape.js +8 -5
- package/src/views/write-state.js +89 -0
- package/src/wiki-ingest.js +215 -0
- package/src/wiki-state.js +228 -0
- package/views/pages.html +2 -2
package/src/collector-lock.js
CHANGED
|
@@ -1,61 +1,228 @@
|
|
|
1
1
|
import fs from "node:fs"
|
|
2
2
|
import os from "node:os"
|
|
3
3
|
import path from "node:path"
|
|
4
|
+
import { execFileSync } from "node:child_process"
|
|
4
5
|
import { randomUUID } from "node:crypto"
|
|
5
6
|
|
|
6
7
|
/** A lease whose heartbeat is older than this belongs to a process that stopped. */
|
|
7
8
|
export const LEASE_STALE_MS = 10 * 60_000
|
|
8
9
|
|
|
10
|
+
/**
|
|
11
|
+
* A same-host pid that is alive but not provably the lease's holder is kept for
|
|
12
|
+
* this long and no longer: half an hour of silence is 30 missed heartbeats of
|
|
13
|
+
* the collector's 60 seconds (HEARTBEAT_MS), far past any healthy holder — one
|
|
14
|
+
* that was merely asleep, or stopped, beats within a minute of waking. It can
|
|
15
|
+
* be this short because a holder that wakes after losing its lease stops
|
|
16
|
+
* before its next read or write (stillHolder, src/collector-service.js), so the
|
|
17
|
+
* cost of recovering early is a moment's overlap, not two collectors writing.
|
|
18
|
+
*/
|
|
19
|
+
export const LEASE_CEILING_MS = 30 * 60_000
|
|
20
|
+
|
|
21
|
+
/** A recorded process start and the lease's own `since` are compared with this much slack (ps reports whole seconds). */
|
|
22
|
+
const START_SLACK_MS = 2_000
|
|
23
|
+
|
|
24
|
+
/** The machine that wrote the lease records its hostname, so a pid can be checked only where it means something. */
|
|
25
|
+
const HOST = os.hostname()
|
|
26
|
+
|
|
27
|
+
/** A pid's start on Linux, in wall-clock milliseconds, from /proc (the tick rate is calibrated against this process's own). */
|
|
28
|
+
function linuxStarted(pid) {
|
|
29
|
+
try {
|
|
30
|
+
const ticksOf = (text) => Number(String(text).slice(String(text).lastIndexOf(") ") + 2).split(" ")[19])
|
|
31
|
+
const ticks = ticksOf(fs.readFileSync(`/proc/${pid}/stat`, "utf8"))
|
|
32
|
+
const btime = Number(/^btime (\d+)$/m.exec(fs.readFileSync("/proc/stat", "utf8"))?.[1])
|
|
33
|
+
const ownTicks = ticksOf(fs.readFileSync("/proc/self/stat", "utf8"))
|
|
34
|
+
if (!Number.isFinite(ticks) || !Number.isFinite(btime) || !Number.isFinite(ownTicks) || ownTicks <= 0) return null
|
|
35
|
+
const ownSeconds = (Date.now() - process.uptime() * 1000) / 1000 - btime
|
|
36
|
+
if (!(ownSeconds > 0)) return null
|
|
37
|
+
const hz = ownTicks / ownSeconds
|
|
38
|
+
return btime * 1000 + (ticks / hz) * 1000
|
|
39
|
+
} catch {
|
|
40
|
+
return null
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** A pid's start from `ps -o lstart=` (macOS, and Linux without /proc), in wall-clock milliseconds. */
|
|
45
|
+
function psStarted(pid) {
|
|
46
|
+
try {
|
|
47
|
+
const text = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
|
|
48
|
+
encoding: "utf8",
|
|
49
|
+
timeout: 2_000,
|
|
50
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
51
|
+
env: { ...process.env, LC_ALL: "C" },
|
|
52
|
+
}).trim()
|
|
53
|
+
const at = Date.parse(text)
|
|
54
|
+
return Number.isFinite(at) ? at : null
|
|
55
|
+
} catch {
|
|
56
|
+
return null
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** When a pid's process started, as wall-clock milliseconds, or null when this machine cannot say. */
|
|
61
|
+
function processStarted(pid) {
|
|
62
|
+
return (process.platform === "linux" ? linuxStarted(pid) : null) ?? psStarted(pid)
|
|
63
|
+
}
|
|
64
|
+
|
|
9
65
|
/**
|
|
10
66
|
* One collector per machine (docs/design/memory-v1-contracts.md §4.4): a lease
|
|
11
67
|
* on `collector.lock` beside the spool, held by one OpenCode process and kept
|
|
12
68
|
* alive by a heartbeat (the file's modification time). Every other process
|
|
13
|
-
* sees a fresh lease and skips
|
|
14
|
-
*
|
|
69
|
+
* sees a fresh lease and skips. A lease is taken over only when it has been
|
|
70
|
+
* abandoned:
|
|
71
|
+
*
|
|
72
|
+
* 1. its holder's process is gone;
|
|
73
|
+
* 2. its pid is alive but is not the holder — a later process took that pid
|
|
74
|
+
* (it started after the lease was written), or the pid is the taking
|
|
75
|
+
* process's own, which cannot be the holder of a lease it does not hold;
|
|
76
|
+
* 3. a same-host pid that is alive but not provably the holder has not beaten
|
|
77
|
+
* for half an hour (LEASE_CEILING_MS, 30 missed 60-second beats), so such a
|
|
78
|
+
* lease is never kept forever. A live, healthy holder never misses that
|
|
79
|
+
* long.
|
|
80
|
+
*
|
|
81
|
+
* A record from another machine, or one with no usable pid, is judged by its
|
|
82
|
+
* heartbeat alone, as before: a pid means nothing elsewhere, and a holder that
|
|
83
|
+
* wakes after losing its lease stops rather than writes.
|
|
15
84
|
*
|
|
16
85
|
* Built on the same file primitives as the spool's cross-process claims
|
|
17
|
-
* (src/spool.js): no-clobber
|
|
18
|
-
* helpers are one-shot claims with no heartbeat, so the lease
|
|
86
|
+
* (src/spool.js): no-clobber hard links and checks made through one open file.
|
|
87
|
+
* The spool's own helpers are one-shot claims with no heartbeat, so the lease
|
|
88
|
+
* is its own:
|
|
19
89
|
*
|
|
20
90
|
* - **create** writes the record to a private temp file and hard-links it to
|
|
21
91
|
* `collector.lock`; `link` fails when the name exists, so exactly one of
|
|
22
|
-
* several racing processes creates it
|
|
92
|
+
* several racing processes creates it — and nobody ever reads a half-written
|
|
23
93
|
* lock;
|
|
24
|
-
* - **take over**
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
94
|
+
* - **take over** is a claim plus a removal, and both are no-clobber hard
|
|
95
|
+
* links, which is the whole of the exclusivity:
|
|
96
|
+
* the taker hard-links a **takeover claim** whose name is the inode of the
|
|
97
|
+
* stale lease it judged (`collector.lock.take-<dev>-<ino>`). Two takers of
|
|
98
|
+
* one lease can therefore never both hold it, and only the claim's holder
|
|
99
|
+
* removes the name — so the window between a taker's stat of the name and
|
|
100
|
+
* its unlink of it, which gave two takers two leases on `a13b245f`, can be
|
|
101
|
+
* entered by one process only. The claim is re-checked immediately before the
|
|
102
|
+
* unlink, the lease is re-read and must still be the very one judged (same
|
|
103
|
+
* id, inode and heartbeat: a holder that beat, or a taker that won first,
|
|
104
|
+
* stands), and the name is removed only while it still points at that inode;
|
|
105
|
+
* - **fence** every protected action: the token is the inode this holder
|
|
106
|
+
* created, and `heartbeat()` (run before every read and every write:
|
|
107
|
+
* `stillHolder`, src/collector-service.js) proves the name still holds that
|
|
108
|
+
* inode with this holder's record. A taker whose lease was removed anyway —
|
|
109
|
+
* a stopped taker resumed, a claim stolen from a dead one — cannot act, so a
|
|
110
|
+
* moment of double ownership never becomes two collectors collecting;
|
|
111
|
+
* - **beat and release** open the lock file first and work through that open
|
|
112
|
+
* file (fstat, the record, futimes), then check the name still points at it:
|
|
113
|
+
* a takeover between the read and the write can never be mistaken for
|
|
114
|
+
* holding the lease, and a beat is never applied to another holder's lock.
|
|
115
|
+
* A holder that lost its lease this way learns it from `heartbeat()` (and
|
|
116
|
+
* from `acquire()` before its next run), so it stops rather than writes.
|
|
30
117
|
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
118
|
+
* A claim, or a temp file, left by a taker is recovered by its owner being
|
|
119
|
+
* **provably dead**, never by age: `acquire()` sweeps the lock's directory and
|
|
120
|
+
* removes a file of its own whose recorded pid no longer runs, or whose pid now
|
|
121
|
+
* belongs to a process that started after the file was written. A file from
|
|
122
|
+
* another machine, or a damaged one, cannot be judged that way at all and ages
|
|
123
|
+
* out at the lease ceiling (LEASE_CEILING_MS, thirty minutes of silence, as a
|
|
124
|
+
* lease does). So a live process's claim is never removed, however old: a taker
|
|
125
|
+
* stopped mid-takeover keeps its claim until it resumes or dies — killing it
|
|
126
|
+
* frees the claim at the next `acquire()`, and no other process can tell a
|
|
127
|
+
* stopped taker from a slow one without opening exactly this window.
|
|
33
128
|
*
|
|
34
|
-
*
|
|
129
|
+
* **The residual, stated plainly.** POSIX has no compare-and-unlink, so a
|
|
130
|
+
* recovery that removes a dead claim and then links its own is still a read and
|
|
131
|
+
* an unlink. A sweeper preempted between them can remove the claim a second
|
|
132
|
+
* taker linked in between (`dropGone` narrows this to a single syscall gap by
|
|
133
|
+
* requiring the very inode it judged). That needs a crashed claim, a sweeper
|
|
134
|
+
* and a second preemption, and it leaves two `owned: true`. The fence is what
|
|
135
|
+
* makes it harmless: the displaced owner's `held()`/`heartbeat()` fail, so it
|
|
136
|
+
* takes no further guarded action, and every local write it already had in
|
|
137
|
+
* flight is fenced again at its commit (`writeStatus`). Only a call already
|
|
138
|
+
* sent to the records service can land, which no token of this machine can
|
|
139
|
+
* stop; the run then stops before the next one.
|
|
140
|
+
*
|
|
141
|
+
* A filesystem without hard links (FAT, exFAT, SMB without Unix extensions)
|
|
142
|
+
* makes `link` fail and `acquire()` throw: the collector refuses to collect
|
|
143
|
+
* rather than risk two collectors.
|
|
144
|
+
*
|
|
145
|
+
* `onStale` (tests only) runs between judging a lease stale and claiming it,
|
|
146
|
+
* the window in which another process may beat or take it. `onStep` (tests
|
|
147
|
+
* only) reports each step of a takeover and of a beat, so a crash at every one
|
|
148
|
+
* can be replayed. `startedAt` (tests only) answers when a pid's process
|
|
149
|
+
* started.
|
|
150
|
+
*
|
|
151
|
+
* @param {{ file: string, staleMs?: number, ceilingMs?: number, now?: () => number, id?: string, pid?: number, log?: any, onStale?: (lease: object) => void, onStep?: (step: string) => void, startedAt?: (pid: number) => number | null }} input
|
|
35
152
|
*/
|
|
36
|
-
export function createLease({
|
|
153
|
+
export function createLease({
|
|
154
|
+
file,
|
|
155
|
+
staleMs = LEASE_STALE_MS,
|
|
156
|
+
ceilingMs = LEASE_CEILING_MS,
|
|
157
|
+
now = Date.now,
|
|
158
|
+
id = randomUUID(),
|
|
159
|
+
pid = process.pid,
|
|
160
|
+
log,
|
|
161
|
+
onStale,
|
|
162
|
+
onStep,
|
|
163
|
+
startedAt = processStarted,
|
|
164
|
+
}) {
|
|
37
165
|
const dir = path.dirname(file)
|
|
166
|
+
const base = path.basename(file)
|
|
167
|
+
/** The inode this holder's lease occupies: the token every protected action is checked against. */
|
|
168
|
+
let mine = null
|
|
38
169
|
|
|
170
|
+
/**
|
|
171
|
+
* A stat whose device and inode are bigints: NTFS file ids above 2^53 lose
|
|
172
|
+
* their low bits as JS numbers, so two different leases could compare equal.
|
|
173
|
+
*/
|
|
174
|
+
function statOf(target) {
|
|
175
|
+
return fs.statSync(target, { bigint: true })
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/**
|
|
179
|
+
* A file's modification time in milliseconds, keeping the sub-millisecond
|
|
180
|
+
* part a bigint stat reports only in whole nanoseconds: the heartbeat is
|
|
181
|
+
* compared and aged to the millisecond, and rounding it would make a beat
|
|
182
|
+
* look older than it is.
|
|
183
|
+
*/
|
|
184
|
+
function heartbeatOf(stat) {
|
|
185
|
+
if (stat.mtimeNs === undefined) return Number(stat.mtimeMs)
|
|
186
|
+
return Number(stat.mtimeNs / 1_000_000n) + Number(stat.mtimeNs % 1_000_000n) / 1e6
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/** Read the lease through one open file, so the record and the heartbeat it is judged by come from the same inode. */
|
|
39
190
|
function readAt(target) {
|
|
40
|
-
let
|
|
191
|
+
let fd
|
|
41
192
|
try {
|
|
42
|
-
|
|
193
|
+
fd = fs.openSync(target, "r")
|
|
43
194
|
} catch (error) {
|
|
44
195
|
if (error?.code === "ENOENT") return null
|
|
45
196
|
throw error
|
|
46
197
|
}
|
|
47
|
-
let record = {}
|
|
48
198
|
try {
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
199
|
+
const stat = fs.fstatSync(fd, { bigint: true })
|
|
200
|
+
let record = {}
|
|
201
|
+
try {
|
|
202
|
+
record = JSON.parse(fs.readFileSync(fd, "utf8"))
|
|
203
|
+
} catch {
|
|
204
|
+
record = {}
|
|
205
|
+
}
|
|
206
|
+
return {
|
|
207
|
+
id: typeof record.id === "string" ? record.id : "",
|
|
208
|
+
pid: Number(record.pid) || 0,
|
|
209
|
+
host: typeof record.host === "string" ? record.host : "",
|
|
210
|
+
since: typeof record.since === "string" ? record.since : "",
|
|
211
|
+
heartbeat: heartbeatOf(stat),
|
|
212
|
+
ino: stat.ino,
|
|
213
|
+
dev: stat.dev,
|
|
214
|
+
}
|
|
215
|
+
} finally {
|
|
216
|
+
fs.closeSync(fd)
|
|
52
217
|
}
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/** Read a lock file this process has open: its record, or {} when it is damaged. */
|
|
221
|
+
function readOpen(fd) {
|
|
222
|
+
try {
|
|
223
|
+
return JSON.parse(fs.readFileSync(fd, "utf8"))
|
|
224
|
+
} catch {
|
|
225
|
+
return {}
|
|
59
226
|
}
|
|
60
227
|
}
|
|
61
228
|
|
|
@@ -66,9 +233,55 @@ export function createLease({ file, staleMs = LEASE_STALE_MS, now = Date.now, id
|
|
|
66
233
|
|
|
67
234
|
const isStale = (lease) => now() - lease.heartbeat >= staleMs
|
|
68
235
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
236
|
+
/** The record's pid, when it is a process id this machine may look up: 0 for none, damaged, or negative. */
|
|
237
|
+
function holderPid(lease) {
|
|
238
|
+
const value = lease?.pid
|
|
239
|
+
return Number.isSafeInteger(value) && value > 0 ? value : 0
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** Is `target` still the file this process has open? */
|
|
243
|
+
function stillAtPath(target, stat) {
|
|
244
|
+
try {
|
|
245
|
+
const current = statOf(target)
|
|
246
|
+
return current.ino === stat.ino && current.dev === stat.dev
|
|
247
|
+
} catch {
|
|
248
|
+
return false
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/** Does pid's process still run? */
|
|
253
|
+
function running(holder) {
|
|
254
|
+
try {
|
|
255
|
+
process.kill(holder, 0)
|
|
256
|
+
return true
|
|
257
|
+
} catch (error) {
|
|
258
|
+
return error?.code === "EPERM"
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* Has this lease been abandoned? A pid is checked only against this machine's
|
|
264
|
+
* processes: another host's record (a hostname that changed, a container made
|
|
265
|
+
* again over a kept state directory), or one with no usable pid, is judged by
|
|
266
|
+
* its heartbeat alone, as it always was.
|
|
267
|
+
*/
|
|
268
|
+
function abandoned(lease) {
|
|
269
|
+
const recorded = holderPid(lease)
|
|
270
|
+
if (!recorded || lease.host !== HOST) return true
|
|
271
|
+
if (!running(recorded)) return true
|
|
272
|
+
// This process's own pid on a lease it does not hold: the record's holder
|
|
273
|
+
// is gone and this process inherited its pid.
|
|
274
|
+
if (recorded === pid && lease.id !== id) return true
|
|
275
|
+
// A process that started after the lease was written cannot be its holder.
|
|
276
|
+
const began = startedAt(recorded)
|
|
277
|
+
if (Number.isFinite(began)) {
|
|
278
|
+
const since = Date.parse(lease.since)
|
|
279
|
+
const held = Number.isFinite(since) ? since : lease.heartbeat
|
|
280
|
+
if (began > held + START_SLACK_MS) return true
|
|
281
|
+
}
|
|
282
|
+
// A pid that still runs is otherwise kept: only a silence past the ceiling
|
|
283
|
+
// recovers it.
|
|
284
|
+
return now() - lease.heartbeat >= ceilingMs
|
|
72
285
|
}
|
|
73
286
|
|
|
74
287
|
function unlinkQuiet(target) {
|
|
@@ -79,16 +292,91 @@ export function createLease({ file, staleMs = LEASE_STALE_MS, now = Date.now, id
|
|
|
79
292
|
}
|
|
80
293
|
}
|
|
81
294
|
|
|
295
|
+
/** Report a step to the test seam (tests only: a crash at each step, and the takeover's gap). */
|
|
296
|
+
function step(name) {
|
|
297
|
+
onStep?.(name)
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
/**
|
|
301
|
+
* Is `fd` this holder's lease, as the name proves it? Its record must be this
|
|
302
|
+
* holder's and the name must still point at the very inode this holder
|
|
303
|
+
* created: the token, re-verified before every action the lease guards.
|
|
304
|
+
* Returns that stat, or null.
|
|
305
|
+
*/
|
|
306
|
+
function holds(fd) {
|
|
307
|
+
const stat = fs.fstatSync(fd, { bigint: true })
|
|
308
|
+
if (readOpen(fd).id !== id) return null
|
|
309
|
+
if (mine && (stat.ino !== mine.ino || stat.dev !== mine.dev)) return null
|
|
310
|
+
return stillAtPath(file, stat) ? stat : null
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/**
|
|
314
|
+
* Beat on the locked file itself: open it, prove through that open file that
|
|
315
|
+
* it is this holder's lease, set its times through that open file, then check
|
|
316
|
+
* the name still points at what was opened. A takeover between any two of
|
|
317
|
+
* those steps leaves this process without the lease.
|
|
318
|
+
*/
|
|
319
|
+
function beat() {
|
|
320
|
+
let fd
|
|
321
|
+
try {
|
|
322
|
+
fd = fs.openSync(file, "r+")
|
|
323
|
+
} catch (error) {
|
|
324
|
+
if (error?.code === "ENOENT") return false
|
|
325
|
+
throw error
|
|
326
|
+
}
|
|
327
|
+
try {
|
|
328
|
+
const stat = holds(fd)
|
|
329
|
+
if (!stat) return false
|
|
330
|
+
step("beat")
|
|
331
|
+
const seconds = now() / 1000
|
|
332
|
+
fs.futimesSync(fd, seconds, seconds)
|
|
333
|
+
if (!stillAtPath(file, stat)) return false
|
|
334
|
+
mine = { dev: stat.dev, ino: stat.ino }
|
|
335
|
+
return true
|
|
336
|
+
} catch {
|
|
337
|
+
return false
|
|
338
|
+
} finally {
|
|
339
|
+
fs.closeSync(fd)
|
|
340
|
+
}
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/**
|
|
344
|
+
* Is this process still the holder, without beating? The same proof as
|
|
345
|
+
* `beat()`: an action taken only after this passes was taken by the holder.
|
|
346
|
+
*/
|
|
347
|
+
function held() {
|
|
348
|
+
let fd
|
|
349
|
+
try {
|
|
350
|
+
fd = fs.openSync(file, "r")
|
|
351
|
+
} catch {
|
|
352
|
+
return false
|
|
353
|
+
}
|
|
354
|
+
try {
|
|
355
|
+
return Boolean(holds(fd))
|
|
356
|
+
} catch {
|
|
357
|
+
return false
|
|
358
|
+
} finally {
|
|
359
|
+
fs.closeSync(fd)
|
|
360
|
+
}
|
|
361
|
+
}
|
|
362
|
+
|
|
82
363
|
/** Create the lock without clobbering one that exists; true when this holder made it. */
|
|
83
364
|
function create() {
|
|
84
365
|
const temp = `${file}.${id}.tmp`
|
|
85
|
-
|
|
366
|
+
const at = now()
|
|
367
|
+
fs.writeFileSync(temp, JSON.stringify({ id, pid, host: HOST, since: new Date(at).toISOString() }), { mode: 0o600 })
|
|
86
368
|
try {
|
|
87
|
-
|
|
369
|
+
fs.utimesSync(temp, at / 1000, at / 1000)
|
|
370
|
+
const stat = statOf(temp)
|
|
371
|
+
step("create-temp")
|
|
88
372
|
fs.linkSync(temp, file)
|
|
373
|
+
mine = { dev: stat.dev, ino: stat.ino }
|
|
374
|
+
step("create")
|
|
89
375
|
return true
|
|
90
376
|
} catch (error) {
|
|
91
377
|
if (error?.code === "EEXIST") return false
|
|
378
|
+
// No hard links here (FAT, exFAT, SMB without Unix extensions): refuse to
|
|
379
|
+
// hold the lease at all rather than guess.
|
|
92
380
|
throw error
|
|
93
381
|
} finally {
|
|
94
382
|
unlinkQuiet(temp)
|
|
@@ -96,41 +384,205 @@ export function createLease({ file, staleMs = LEASE_STALE_MS, now = Date.now, id
|
|
|
96
384
|
}
|
|
97
385
|
|
|
98
386
|
/**
|
|
99
|
-
*
|
|
100
|
-
*
|
|
387
|
+
* The takeover claim on one lease, named for the inode it would remove: the
|
|
388
|
+
* single arbiter of which taker may remove that inode, so no two takers of one
|
|
389
|
+
* stale lease can both get past it. The name carries no lease of its own; its
|
|
390
|
+
* record says whose attempt it is.
|
|
391
|
+
*/
|
|
392
|
+
function claimName(lease) {
|
|
393
|
+
return `${file}.take-${lease.dev}-${lease.ino}`
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
/** Create the claim without clobbering another taker's; true when this taker made it. */
|
|
397
|
+
function claim(target) {
|
|
398
|
+
const temp = `${target}.${id}.tmp`
|
|
399
|
+
const at = now()
|
|
400
|
+
fs.writeFileSync(temp, JSON.stringify({ id, pid, host: HOST, since: new Date(at).toISOString() }), { mode: 0o600 })
|
|
401
|
+
try {
|
|
402
|
+
fs.utimesSync(temp, at / 1000, at / 1000)
|
|
403
|
+
fs.linkSync(temp, target)
|
|
404
|
+
return true
|
|
405
|
+
} catch (error) {
|
|
406
|
+
if (error?.code === "EEXIST") return false
|
|
407
|
+
throw error
|
|
408
|
+
} finally {
|
|
409
|
+
unlinkQuiet(temp)
|
|
410
|
+
}
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
/** Is the claim at `target` this taker's own? */
|
|
414
|
+
function claimed(target) {
|
|
415
|
+
try {
|
|
416
|
+
return readAt(target)?.id === id
|
|
417
|
+
} catch {
|
|
418
|
+
return false
|
|
419
|
+
}
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
function dropClaim(target) {
|
|
423
|
+
if (claimed(target)) unlinkQuiet(target)
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
/**
|
|
427
|
+
* Has the owner of a file beside the lock gone? One of these is a claim, a
|
|
428
|
+
* temp file, or an aside an older build left: its record names the process
|
|
429
|
+
* that made it. It is judged exactly as a lease's holder is, and only that
|
|
430
|
+
* way: the pid no longer runs, or the pid now belongs to a process that
|
|
431
|
+
* started after the file was written. **Never by age** for a pid this machine
|
|
432
|
+
* can judge — a live taker that was stopped mid-takeover is indistinguishable
|
|
433
|
+
* from a slow one, and removing its claim is how a second taker gets past it
|
|
434
|
+
* (the residual above). A record this machine cannot judge at all — another
|
|
435
|
+
* host's, a damaged one, or a pid whose start time cannot be read (Windows
|
|
436
|
+
* has no `ps` and no `/proc`) — ages out at the lease ceiling, so no file can
|
|
437
|
+
* outlive every judgement.
|
|
438
|
+
*/
|
|
439
|
+
function gone(record) {
|
|
440
|
+
if (!record) return true
|
|
441
|
+
const recorded = holderPid(record)
|
|
442
|
+
if (recorded && record.host === HOST) {
|
|
443
|
+
if (!running(recorded)) return true
|
|
444
|
+
const began = startedAt(recorded)
|
|
445
|
+
const since = Date.parse(record.since)
|
|
446
|
+
// An unreadable start time makes the pid unjudgeable: age it out rather
|
|
447
|
+
// than let a reused pid block the lock for as long as it lives.
|
|
448
|
+
if (!Number.isFinite(began) || !Number.isFinite(since)) return now() - record.heartbeat >= ceilingMs
|
|
449
|
+
return began > since + START_SLACK_MS
|
|
450
|
+
}
|
|
451
|
+
return now() - record.heartbeat >= ceilingMs
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
/**
|
|
455
|
+
* Remove a file beside the lock only while it is still the very file judged
|
|
456
|
+
* gone: another taker may have removed that one and linked its own in the
|
|
457
|
+
* meantime, and that live claim is not this process's to remove. This narrows
|
|
458
|
+
* the residual to one syscall gap (the stat below and the unlink).
|
|
459
|
+
*/
|
|
460
|
+
function dropGone(target, judged) {
|
|
461
|
+
if (!judged) return false
|
|
462
|
+
try {
|
|
463
|
+
const current = readAt(target)
|
|
464
|
+
if (!current || current.ino !== judged.ino || current.dev !== judged.dev) return false
|
|
465
|
+
if (!gone(current)) return false
|
|
466
|
+
step("gone")
|
|
467
|
+
fs.unlinkSync(target)
|
|
468
|
+
return true
|
|
469
|
+
} catch {
|
|
470
|
+
return false
|
|
471
|
+
}
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
/**
|
|
475
|
+
* Win the right to remove this one stale lease, or stand down. `link` is
|
|
476
|
+
* no-clobber, so of any number of takers that judged the same lease exactly
|
|
477
|
+
* one holds the claim; a claim whose taker died is recovered, a live taker's
|
|
478
|
+
* is never touched.
|
|
479
|
+
*/
|
|
480
|
+
function takeClaim(lease) {
|
|
481
|
+
const target = claimName(lease)
|
|
482
|
+
for (let attempt = 0; attempt < 2; attempt++) {
|
|
483
|
+
if (claim(target)) return target
|
|
484
|
+
const judged = readAt(target)
|
|
485
|
+
// Gone under this taker already: race for the claim once more.
|
|
486
|
+
if (!judged) continue
|
|
487
|
+
// Another taker's claim, and its taker is alive: stand down.
|
|
488
|
+
if (!gone(judged)) return null
|
|
489
|
+
// Its taker is provably dead: remove that very file and race for the
|
|
490
|
+
// claim again. A competing sweeper may take the removal first, or may
|
|
491
|
+
// have linked its own claim, and then this backs off.
|
|
492
|
+
if (!dropGone(target, judged)) return null
|
|
493
|
+
}
|
|
494
|
+
return null
|
|
495
|
+
}
|
|
496
|
+
|
|
497
|
+
/**
|
|
498
|
+
* Remove what an interrupted attempt of any process left beside the lock —
|
|
499
|
+
* a takeover claim, a temp file, an aside a build before this one made. A
|
|
500
|
+
* file whose owner is alive is left alone, whatever its age: only a provably
|
|
501
|
+
* dead owner frees one. This is what keeps crash recovery from leaving a
|
|
502
|
+
* stray file: the next start removes it.
|
|
503
|
+
*/
|
|
504
|
+
function sweep() {
|
|
505
|
+
let names
|
|
506
|
+
try {
|
|
507
|
+
names = fs.readdirSync(dir)
|
|
508
|
+
} catch {
|
|
509
|
+
return
|
|
510
|
+
}
|
|
511
|
+
for (const name of names) {
|
|
512
|
+
if (name === base || !name.startsWith(`${base}.`)) continue
|
|
513
|
+
const target = path.join(dir, name)
|
|
514
|
+
let record = null
|
|
515
|
+
try {
|
|
516
|
+
record = readAt(target)
|
|
517
|
+
} catch {
|
|
518
|
+
record = null
|
|
519
|
+
}
|
|
520
|
+
if (!record || !gone(record)) continue
|
|
521
|
+
dropGone(target, record)
|
|
522
|
+
}
|
|
523
|
+
}
|
|
524
|
+
|
|
525
|
+
/**
|
|
526
|
+
* Hold the lease: keep it (beating) when this holder has it, create it when
|
|
527
|
+
* nobody does, take it over when its holder has abandoned it.
|
|
101
528
|
*
|
|
102
529
|
* @returns {{ owned: true, took?: "free" | "stale" } | { owned: false, holder: ReturnType<typeof holder> }}
|
|
103
530
|
*/
|
|
104
531
|
function acquire() {
|
|
105
532
|
fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
|
|
106
|
-
|
|
533
|
+
sweep()
|
|
534
|
+
let current = holder()
|
|
107
535
|
if (current && current.id === id) {
|
|
108
|
-
|
|
109
|
-
|
|
536
|
+
if (beat()) return { owned: true }
|
|
537
|
+
// Lost between the read and the beat (another process took the lease):
|
|
538
|
+
// judge the lock as it stands now, not the record that was read.
|
|
539
|
+
current = holder()
|
|
110
540
|
}
|
|
111
541
|
if (current && !isStale(current)) return { owned: false, holder: current }
|
|
542
|
+
if (current && !abandoned(current)) {
|
|
543
|
+
log?.info?.("collector lease left alone: its holder process is running", { pid: current.pid })
|
|
544
|
+
return { owned: false, holder: current }
|
|
545
|
+
}
|
|
112
546
|
if (current) {
|
|
113
547
|
onStale?.(current)
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
548
|
+
// One taker at a time per stale lease, keyed on the inode to be removed:
|
|
549
|
+
// two takers of one lease can never both get past this, so the gap
|
|
550
|
+
// between a taker's stat and its unlink is entered by one process only.
|
|
551
|
+
const target = takeClaim(current)
|
|
552
|
+
if (!target) {
|
|
553
|
+
log?.debug?.("collector lease takeover is another process's", { pid: current.pid })
|
|
554
|
+
return { owned: false, holder: holder() ?? current }
|
|
119
555
|
}
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
556
|
+
step("claim")
|
|
557
|
+
let removed = false
|
|
558
|
+
let replaced = false
|
|
559
|
+
try {
|
|
560
|
+
// Still the very lease this taker judged, and still this taker's to
|
|
561
|
+
// remove? A holder that beat, a taker that won first, or a claim that
|
|
562
|
+
// was taken from a taker thought dead all stand.
|
|
563
|
+
const again = readAt(file)
|
|
564
|
+
if (again) {
|
|
565
|
+
if (again.id !== current.id || again.ino !== current.ino || again.heartbeat !== current.heartbeat || !claimed(target)) {
|
|
566
|
+
replaced = true
|
|
567
|
+
} else {
|
|
568
|
+
const at = statOf(file)
|
|
569
|
+
if (at.ino === current.ino && at.dev === current.dev) {
|
|
570
|
+
step("stat")
|
|
571
|
+
fs.unlinkSync(file)
|
|
572
|
+
step("unlink")
|
|
573
|
+
removed = true
|
|
574
|
+
} else {
|
|
575
|
+
replaced = true
|
|
576
|
+
}
|
|
577
|
+
}
|
|
128
578
|
}
|
|
129
|
-
|
|
130
|
-
|
|
579
|
+
} catch {
|
|
580
|
+
/* the name went away under this taker: create() decides who wins */
|
|
581
|
+
} finally {
|
|
582
|
+
dropClaim(target)
|
|
131
583
|
}
|
|
132
|
-
|
|
133
|
-
if (
|
|
584
|
+
if (replaced) return { owned: false, holder: holder() ?? current }
|
|
585
|
+
if (removed) log?.info?.("collector lease taken over from a stopped process", { pid: current.pid })
|
|
134
586
|
}
|
|
135
587
|
if (create()) return { owned: true, took: current ? "stale" : "free" }
|
|
136
588
|
return { owned: false, holder: holder() }
|
|
@@ -139,24 +591,43 @@ export function createLease({ file, staleMs = LEASE_STALE_MS, now = Date.now, id
|
|
|
139
591
|
/** Refresh the heartbeat; false when the lease is no longer this holder's. */
|
|
140
592
|
function heartbeat() {
|
|
141
593
|
try {
|
|
142
|
-
|
|
143
|
-
if (!current || current.id !== id) return false
|
|
144
|
-
touch(file)
|
|
145
|
-
return true
|
|
594
|
+
return beat()
|
|
146
595
|
} catch {
|
|
147
596
|
return false
|
|
148
597
|
}
|
|
149
598
|
}
|
|
150
599
|
|
|
151
|
-
/**
|
|
600
|
+
/**
|
|
601
|
+
* Give the lease up, only while it is still this holder's: the record is read
|
|
602
|
+
* through this process's own open file, the name must still point at the very
|
|
603
|
+
* inode this holder created, and it is never moved or removed to find out
|
|
604
|
+
* whose it is.
|
|
605
|
+
*/
|
|
152
606
|
function release() {
|
|
607
|
+
let fd
|
|
153
608
|
try {
|
|
154
|
-
|
|
155
|
-
|
|
609
|
+
fd = fs.openSync(file, "r+")
|
|
610
|
+
} catch {
|
|
611
|
+
return
|
|
612
|
+
}
|
|
613
|
+
try {
|
|
614
|
+
const stat = fs.fstatSync(fd, { bigint: true })
|
|
615
|
+
if (readOpen(fd).id !== id) return
|
|
616
|
+
if (mine && (stat.ino !== mine.ino || stat.dev !== mine.dev)) return
|
|
617
|
+
// A taker takes only an abandoned lease, and this process is running:
|
|
618
|
+
// its lease changes hands only if this check and the unlink straddle a
|
|
619
|
+
// clock jump past the ceiling — the inode check makes that the one
|
|
620
|
+
// window, and it is the smallest one these calls allow.
|
|
621
|
+
if (!stillAtPath(file, stat)) return
|
|
622
|
+
step("release")
|
|
623
|
+
fs.unlinkSync(file)
|
|
624
|
+
mine = null
|
|
156
625
|
} catch {
|
|
157
626
|
/* nothing to release */
|
|
627
|
+
} finally {
|
|
628
|
+
fs.closeSync(fd)
|
|
158
629
|
}
|
|
159
630
|
}
|
|
160
631
|
|
|
161
|
-
return { id, file, acquire, heartbeat, release, holder, isStale }
|
|
632
|
+
return { id, file, acquire, heartbeat, release, holder, isStale, held }
|
|
162
633
|
}
|