@xiangyixie/dsh-superagent 0.9.2 → 0.10.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 +109 -0
- package/LICENSE +21 -21
- package/README.md +181 -28
- package/bin/report.js +79 -79
- package/bin/watch.js +57 -57
- package/cordis.patch.yml +9 -9
- package/lib/control.js +495 -494
- package/lib/errors.js +205 -199
- package/lib/index.js +1104 -822
- package/lib/lock.js +107 -0
- package/lib/memory.js +503 -0
- package/lib/notify.js +257 -0
- package/lib/orchestrator.js +670 -16
- package/lib/report.js +733 -733
- package/lib/store.js +402 -385
- package/lib/usage.js +152 -152
- package/lib/watch.js +458 -458
- package/package.json +5 -2
package/lib/store.js
CHANGED
|
@@ -1,385 +1,402 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Durable run storage for dsh-superagent.
|
|
3
|
-
*
|
|
4
|
-
* One JSON file per run under `<root>/runs/<runId>.json`. Writes are atomic
|
|
5
|
-
* (temp file + rename) so a host crash mid-write cannot leave a half-written
|
|
6
|
-
* run that blocks recovery.
|
|
7
|
-
*
|
|
8
|
-
* Sibling files carry signals that are safe to write from another process:
|
|
9
|
-
* `<runId>.cancel` asks the owning process to stop the run, `<runId>.lock`
|
|
10
|
-
* claims the right to schedule it so two processes cannot run the same one, and
|
|
11
|
-
* `<runId>.json.corrupt-<ts>` keeps an unparsable state file instead of
|
|
12
|
-
* deleting the evidence.
|
|
13
|
-
*
|
|
14
|
-
* @module dsh-superagent/store
|
|
15
|
-
*/
|
|
16
|
-
import fsp from 'node:fs/promises'
|
|
17
|
-
import os from 'node:os'
|
|
18
|
-
import path from 'node:path'
|
|
19
|
-
|
|
20
|
-
/** Statuses for a run that still owns live work. */
|
|
21
|
-
export const ACTIVE_STATUSES = new Set(['queued', 'planning', 'running', 'aggregating'])
|
|
22
|
-
|
|
23
|
-
/** Statuses after which a run will not change on its own. */
|
|
24
|
-
export const TERMINAL_STATUSES = new Set(['completed', 'partial', 'failed', 'cancelled', 'interrupted'])
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
*
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
const
|
|
56
|
-
const
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
async
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
if (!
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
}
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
*
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
* @
|
|
248
|
-
*/
|
|
249
|
-
async
|
|
250
|
-
try {
|
|
251
|
-
await fsp.
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
return
|
|
287
|
-
}
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
try {
|
|
297
|
-
await fsp.
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
*
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
* @
|
|
321
|
-
*/
|
|
322
|
-
async
|
|
323
|
-
try {
|
|
324
|
-
await fsp.
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
*
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
}
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
}
|
|
385
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Durable run storage for dsh-superagent.
|
|
3
|
+
*
|
|
4
|
+
* One JSON file per run under `<root>/runs/<runId>.json`. Writes are atomic
|
|
5
|
+
* (temp file + rename) so a host crash mid-write cannot leave a half-written
|
|
6
|
+
* run that blocks recovery.
|
|
7
|
+
*
|
|
8
|
+
* Sibling files carry signals that are safe to write from another process:
|
|
9
|
+
* `<runId>.cancel` asks the owning process to stop the run, `<runId>.lock`
|
|
10
|
+
* claims the right to schedule it so two processes cannot run the same one, and
|
|
11
|
+
* `<runId>.json.corrupt-<ts>` keeps an unparsable state file instead of
|
|
12
|
+
* deleting the evidence.
|
|
13
|
+
*
|
|
14
|
+
* @module dsh-superagent/store
|
|
15
|
+
*/
|
|
16
|
+
import fsp from 'node:fs/promises'
|
|
17
|
+
import os from 'node:os'
|
|
18
|
+
import path from 'node:path'
|
|
19
|
+
|
|
20
|
+
/** Statuses for a run that still owns live work. */
|
|
21
|
+
export const ACTIVE_STATUSES = new Set(['queued', 'planning', 'running', 'aggregating'])
|
|
22
|
+
|
|
23
|
+
/** Statuses after which a run will not change on its own. */
|
|
24
|
+
export const TERMINAL_STATUSES = new Set(['completed', 'partial', 'failed', 'cancelled', 'interrupted'])
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Prefix of a goal guard: the lock a start holds while it decides whether a run
|
|
28
|
+
* for that goal already exists. It is keyed by the goal rather than by a run id,
|
|
29
|
+
* so it has no run file of its own and the mount-time cleanup must leave it
|
|
30
|
+
* alone instead of treating it as a lock left behind by a finished run.
|
|
31
|
+
*/
|
|
32
|
+
export const GOAL_GUARD_PREFIX = 'goal-'
|
|
33
|
+
|
|
34
|
+
const RUN_ID_PATTERN = /^[0-9A-Za-z][0-9A-Za-z-]{3,63}$/
|
|
35
|
+
const STALE_TMP_MS = 10 * 60 * 1000
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Resolve the state root. An explicit `stateDir` wins, then `$DSH_HOME`, then
|
|
39
|
+
* the harness default `~/.dsh`.
|
|
40
|
+
* @param {string | undefined} configured - plugin config `stateDir`.
|
|
41
|
+
* @returns {string} absolute state root.
|
|
42
|
+
*/
|
|
43
|
+
export function resolveStateRoot(configured) {
|
|
44
|
+
if (typeof configured === 'string' && configured.trim()) return path.resolve(configured.trim())
|
|
45
|
+
const home = process.env.DSH_HOME?.trim() || path.join(os.homedir(), '.dsh')
|
|
46
|
+
return path.join(home, 'state', 'superagent')
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Build a store bound to one state root.
|
|
51
|
+
* @param {string} root - absolute state root.
|
|
52
|
+
* @param {{ warn?: (message: string) => void }} [options] - diagnostics sink.
|
|
53
|
+
*/
|
|
54
|
+
export function createStore(root, options = {}) {
|
|
55
|
+
const runsDir = path.join(root, 'runs')
|
|
56
|
+
const warn = options.warn ?? (() => {})
|
|
57
|
+
// Two saves of the same run can land in the same millisecond, so the temp
|
|
58
|
+
// name needs a counter as well as a clock.
|
|
59
|
+
let writeSeq = 0
|
|
60
|
+
/** runId -> quarantine path, so status can explain a run it cannot parse. */
|
|
61
|
+
const corrupt = new Map()
|
|
62
|
+
|
|
63
|
+
const runFile = runId => path.join(runsDir, `${runId}.json`)
|
|
64
|
+
const cancelFile = runId => path.join(runsDir, `${runId}.cancel`)
|
|
65
|
+
const lockFile = runId => path.join(runsDir, `${runId}.lock`)
|
|
66
|
+
const reportFile = runId => path.join(root, 'reports', `${runId}.md`)
|
|
67
|
+
const ownerFile = path.join(root, '.owner')
|
|
68
|
+
|
|
69
|
+
return {
|
|
70
|
+
root,
|
|
71
|
+
runsDir,
|
|
72
|
+
ownerFile,
|
|
73
|
+
corrupt,
|
|
74
|
+
|
|
75
|
+
async init() {
|
|
76
|
+
await fsp.mkdir(runsDir, { recursive: true })
|
|
77
|
+
await this.cleanup()
|
|
78
|
+
},
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Remove temp files left by a killed process and sibling markers whose run
|
|
82
|
+
* already reached a terminal state, so none of them can affect later runs.
|
|
83
|
+
*/
|
|
84
|
+
async cleanup() {
|
|
85
|
+
let names
|
|
86
|
+
try {
|
|
87
|
+
names = await fsp.readdir(runsDir)
|
|
88
|
+
} catch {
|
|
89
|
+
return
|
|
90
|
+
}
|
|
91
|
+
for (const name of names) {
|
|
92
|
+
const file = path.join(runsDir, name)
|
|
93
|
+
if (name.startsWith('.') && name.endsWith('.tmp')) {
|
|
94
|
+
try {
|
|
95
|
+
const stat = await fsp.stat(file)
|
|
96
|
+
if (Date.now() - stat.mtimeMs > STALE_TMP_MS) await fsp.unlink(file)
|
|
97
|
+
} catch {
|
|
98
|
+
// Already gone; nothing to clean.
|
|
99
|
+
}
|
|
100
|
+
continue
|
|
101
|
+
}
|
|
102
|
+
const marker = ['.cancel', '.lock'].find(suffix => name.endsWith(suffix))
|
|
103
|
+
if (!marker) continue
|
|
104
|
+
// A goal guard is not a run lock and has no run file to read; its
|
|
105
|
+
// holder releases it, or a later start breaks a dead holder's guard.
|
|
106
|
+
if (name.startsWith(GOAL_GUARD_PREFIX) && marker === '.lock') continue
|
|
107
|
+
let run = null
|
|
108
|
+
let readable = true
|
|
109
|
+
try {
|
|
110
|
+
run = await this.read(name.slice(0, -marker.length))
|
|
111
|
+
} catch {
|
|
112
|
+
// An unreadable run file is not a reason to drop its control files.
|
|
113
|
+
readable = false
|
|
114
|
+
}
|
|
115
|
+
if (!readable) continue
|
|
116
|
+
if (!run || TERMINAL_STATUSES.has(run.status)) {
|
|
117
|
+
try {
|
|
118
|
+
await fsp.unlink(file)
|
|
119
|
+
} catch {
|
|
120
|
+
// Nothing to clean.
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
},
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Read every readable run, newest first. A corrupt file is quarantined and
|
|
128
|
+
* skipped rather than failing the whole listing; a file that cannot be read
|
|
129
|
+
* at all is reported and skipped for the same reason.
|
|
130
|
+
*/
|
|
131
|
+
async list() {
|
|
132
|
+
let names
|
|
133
|
+
try {
|
|
134
|
+
names = await fsp.readdir(runsDir)
|
|
135
|
+
} catch (error) {
|
|
136
|
+
// A missing runs directory means initialization did not happen; saying
|
|
137
|
+
// "no runs recorded" would hide that. Only an empty directory is empty.
|
|
138
|
+
const code = error?.code ? `${error.code}: ` : ''
|
|
139
|
+
throw new Error(
|
|
140
|
+
`cannot read the run state directory ${runsDir} (${code}${error?.message ?? error}); `
|
|
141
|
+
+ 'the plugin could not initialize it, so no run can be listed or resumed',
|
|
142
|
+
)
|
|
143
|
+
}
|
|
144
|
+
const runs = []
|
|
145
|
+
for (const name of names) {
|
|
146
|
+
if (!name.endsWith('.json') || name.startsWith('.')) continue
|
|
147
|
+
try {
|
|
148
|
+
const run = await this.read(name.slice(0, -'.json'.length))
|
|
149
|
+
if (run) runs.push(run)
|
|
150
|
+
} catch (error) {
|
|
151
|
+
warn(`skipping run file ${name}: ${error?.message ?? error}`)
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
runs.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
|
|
155
|
+
return runs
|
|
156
|
+
},
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* @param {string} runId - run identity.
|
|
160
|
+
* @returns {Promise<object | null>} parsed run, or null when missing/invalid.
|
|
161
|
+
* @throws when the file exists but cannot be read (EPERM, EMFILE, ENOSPC...).
|
|
162
|
+
* Reporting that as "unknown run" would hide a real filesystem problem.
|
|
163
|
+
*/
|
|
164
|
+
async read(runId) {
|
|
165
|
+
if (!RUN_ID_PATTERN.test(String(runId))) return null
|
|
166
|
+
// Windows can fail a read with EBUSY/EACCES for a moment while another
|
|
167
|
+
// process replaces the file. Those are transient for a reader, so retry
|
|
168
|
+
// before turning a poll into a hard error; real permission errors still
|
|
169
|
+
// surface after the retries.
|
|
170
|
+
for (let attempt = 1; ; attempt++) {
|
|
171
|
+
try {
|
|
172
|
+
const text = await fsp.readFile(runFile(runId), 'utf8')
|
|
173
|
+
const run = JSON.parse(text)
|
|
174
|
+
if (!run || typeof run !== 'object') {
|
|
175
|
+
await this.quarantine(runId)
|
|
176
|
+
return null
|
|
177
|
+
}
|
|
178
|
+
return run
|
|
179
|
+
} catch (error) {
|
|
180
|
+
if (error?.code === 'ENOENT') return null
|
|
181
|
+
if (error instanceof SyntaxError) {
|
|
182
|
+
const moved = await this.quarantine(runId)
|
|
183
|
+
warn(`state file for run ${runId} was not valid JSON; kept at ${moved ?? 'the runs directory'}`)
|
|
184
|
+
return null
|
|
185
|
+
}
|
|
186
|
+
const transient = ['EPERM', 'EACCES', 'EBUSY', 'EMFILE'].includes(error?.code)
|
|
187
|
+
if (transient && attempt < 3) {
|
|
188
|
+
await new Promise(resolve => setTimeout(resolve, 15 * attempt))
|
|
189
|
+
continue
|
|
190
|
+
}
|
|
191
|
+
const code = error?.code ? `${error.code}: ` : ''
|
|
192
|
+
throw new Error(`cannot read state for run ${runId} (${code}${error?.message ?? error})`)
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
},
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Move an unparsable state file aside so it neither blocks recovery nor
|
|
199
|
+
* gets overwritten by the next save of the same id.
|
|
200
|
+
* @param {string} runId - run identity.
|
|
201
|
+
* @returns {Promise<string | null>} new path, or null when nothing moved.
|
|
202
|
+
*/
|
|
203
|
+
async quarantine(runId) {
|
|
204
|
+
const target = `${runFile(runId)}.corrupt-${Date.now()}`
|
|
205
|
+
try {
|
|
206
|
+
await fsp.rename(runFile(runId), target)
|
|
207
|
+
corrupt.set(runId, target)
|
|
208
|
+
return target
|
|
209
|
+
} catch {
|
|
210
|
+
return null
|
|
211
|
+
}
|
|
212
|
+
},
|
|
213
|
+
|
|
214
|
+
/**
|
|
215
|
+
* Atomically persist one run.
|
|
216
|
+
* @param {object} run - run record with an `id`.
|
|
217
|
+
*/
|
|
218
|
+
async write(run) {
|
|
219
|
+
const file = runFile(run.id)
|
|
220
|
+
const tmp = path.join(runsDir, `.${run.id}.${process.pid}.${++writeSeq}.tmp`)
|
|
221
|
+
await fsp.writeFile(tmp, `${JSON.stringify(run, null, 2)}\n`, 'utf8')
|
|
222
|
+
for (let attempt = 1; ; attempt++) {
|
|
223
|
+
try {
|
|
224
|
+
await fsp.rename(tmp, file)
|
|
225
|
+
return
|
|
226
|
+
} catch (error) {
|
|
227
|
+
// A reader holding the destination open can fail the replace on Windows.
|
|
228
|
+
if (attempt >= 5 || !['EPERM', 'EACCES', 'EBUSY'].includes(error?.code)) throw error
|
|
229
|
+
await new Promise(resolve => setTimeout(resolve, 20 * attempt))
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
},
|
|
233
|
+
|
|
234
|
+
/**
|
|
235
|
+
* Ask whichever process owns a run to stop it. This is a file, not IPC, so
|
|
236
|
+
* it works across processes and survives a restart.
|
|
237
|
+
* @param {string} runId - run identity.
|
|
238
|
+
*/
|
|
239
|
+
async requestCancel(runId) {
|
|
240
|
+
if (!RUN_ID_PATTERN.test(String(runId))) return false
|
|
241
|
+
await fsp.writeFile(cancelFile(runId), `${JSON.stringify({ requestedAt: new Date().toISOString(), pid: process.pid })}\n`, 'utf8')
|
|
242
|
+
return true
|
|
243
|
+
},
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* @param {string} runId - run identity.
|
|
247
|
+
* @returns {Promise<boolean>} true when a cancel was requested by any process.
|
|
248
|
+
*/
|
|
249
|
+
async hasCancelRequest(runId) {
|
|
250
|
+
try {
|
|
251
|
+
await fsp.access(cancelFile(runId))
|
|
252
|
+
return true
|
|
253
|
+
} catch {
|
|
254
|
+
return false
|
|
255
|
+
}
|
|
256
|
+
},
|
|
257
|
+
|
|
258
|
+
/**
|
|
259
|
+
* @param {string} runId - run identity.
|
|
260
|
+
*/
|
|
261
|
+
async clearCancel(runId) {
|
|
262
|
+
try {
|
|
263
|
+
await fsp.unlink(cancelFile(runId))
|
|
264
|
+
} catch {
|
|
265
|
+
// Nothing to clear.
|
|
266
|
+
}
|
|
267
|
+
},
|
|
268
|
+
|
|
269
|
+
cancelFile,
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* Claim the right to schedule one run. The lock is created with `wx`, so
|
|
273
|
+
* exactly one process wins even when two profiles point at the same state
|
|
274
|
+
* directory; the loser gets the holder instead of a second copy of the run.
|
|
275
|
+
* @param {string} runId - run identity.
|
|
276
|
+
* @param {{ pid: number, hostname: string, at: string }} holder - claimant.
|
|
277
|
+
* @returns {Promise<{ acquired: boolean, holder: object | null }>}
|
|
278
|
+
*/
|
|
279
|
+
async acquireLock(runId, holder) {
|
|
280
|
+
if (!RUN_ID_PATTERN.test(String(runId))) return { acquired: false, holder: null }
|
|
281
|
+
try {
|
|
282
|
+
await fsp.writeFile(lockFile(runId), `${JSON.stringify(holder)}\n`, { encoding: 'utf8', flag: 'wx' })
|
|
283
|
+
return { acquired: true, holder }
|
|
284
|
+
} catch (error) {
|
|
285
|
+
if (error?.code !== 'EEXIST') throw error
|
|
286
|
+
return { acquired: false, holder: await this.readLock(runId) }
|
|
287
|
+
}
|
|
288
|
+
},
|
|
289
|
+
|
|
290
|
+
/**
|
|
291
|
+
* @param {string} runId - run identity.
|
|
292
|
+
* @returns {Promise<object | null>} recorded holder, or null.
|
|
293
|
+
*/
|
|
294
|
+
async readLock(runId) {
|
|
295
|
+
if (!RUN_ID_PATTERN.test(String(runId))) return null
|
|
296
|
+
try {
|
|
297
|
+
const parsed = JSON.parse(await fsp.readFile(lockFile(runId), 'utf8'))
|
|
298
|
+
return parsed && typeof parsed === 'object' ? parsed : null
|
|
299
|
+
} catch {
|
|
300
|
+
return null
|
|
301
|
+
}
|
|
302
|
+
},
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* @param {string} runId - run identity.
|
|
306
|
+
*/
|
|
307
|
+
async releaseLock(runId) {
|
|
308
|
+
try {
|
|
309
|
+
await fsp.unlink(lockFile(runId))
|
|
310
|
+
} catch {
|
|
311
|
+
// Nothing to release.
|
|
312
|
+
}
|
|
313
|
+
},
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* Machine identity of the state directory, written once by the first
|
|
317
|
+
* process that mounts it. Its presence tells later processes whether a pid
|
|
318
|
+
* in a run file belongs to this machine (local) or possibly to another one
|
|
319
|
+
* sharing the directory, where the pid is meaningless.
|
|
320
|
+
* @returns {Promise<{ hostname?: string, createdAt?: string } | null>}
|
|
321
|
+
*/
|
|
322
|
+
async readOwner() {
|
|
323
|
+
try {
|
|
324
|
+
const parsed = JSON.parse(await fsp.readFile(ownerFile, 'utf8'))
|
|
325
|
+
return parsed && typeof parsed === 'object' ? parsed : null
|
|
326
|
+
} catch {
|
|
327
|
+
return null
|
|
328
|
+
}
|
|
329
|
+
},
|
|
330
|
+
|
|
331
|
+
/**
|
|
332
|
+
* @param {{ hostname: string, createdAt?: string }} owner - identity to record.
|
|
333
|
+
*/
|
|
334
|
+
async writeOwner(owner) {
|
|
335
|
+
try {
|
|
336
|
+
await fsp.writeFile(ownerFile, `${JSON.stringify(owner, null, 2)}\n`, 'utf8')
|
|
337
|
+
} catch (error) {
|
|
338
|
+
warn(`cannot record the state directory owner in ${ownerFile}: ${error?.message ?? error}`)
|
|
339
|
+
}
|
|
340
|
+
},
|
|
341
|
+
|
|
342
|
+
/**
|
|
343
|
+
* Delete terminal runs older than `olderThanDays`, so an install that runs
|
|
344
|
+
* for months does not accumulate state forever. Opt-in: called with a
|
|
345
|
+
* positive number only when the user configured `keepRuns`.
|
|
346
|
+
* @param {{ olderThanDays: number }} options - retention window.
|
|
347
|
+
* @returns {Promise<{ removed: string[] }>} removed run ids.
|
|
348
|
+
*/
|
|
349
|
+
async prune({ olderThanDays }) {
|
|
350
|
+
const days = Number(olderThanDays)
|
|
351
|
+
const removed = []
|
|
352
|
+
if (!Number.isFinite(days) || days <= 0) return { removed }
|
|
353
|
+
const cutoff = Date.now() - days * 86400000
|
|
354
|
+
for (const run of await this.list()) {
|
|
355
|
+
if (!TERMINAL_STATUSES.has(run.status)) continue
|
|
356
|
+
const finished = Date.parse(run.finishedAt ?? run.updatedAt ?? run.createdAt)
|
|
357
|
+
if (!Number.isFinite(finished) || finished > cutoff) continue
|
|
358
|
+
try {
|
|
359
|
+
await fsp.unlink(runFile(run.id))
|
|
360
|
+
await this.clearCancel(run.id)
|
|
361
|
+
await this.releaseLock(run.id)
|
|
362
|
+
// The report artifact belongs to the run; leaving it behind would make
|
|
363
|
+
// `keepRuns` bound the state directory for the runs but not the reports.
|
|
364
|
+
await fsp.unlink(reportFile(run.id)).catch(error => {
|
|
365
|
+
if (error?.code !== 'ENOENT') throw error
|
|
366
|
+
})
|
|
367
|
+
removed.push(run.id)
|
|
368
|
+
} catch (error) {
|
|
369
|
+
warn(`cannot prune run ${run.id}: ${error?.message ?? error}`)
|
|
370
|
+
}
|
|
371
|
+
}
|
|
372
|
+
return { removed }
|
|
373
|
+
},
|
|
374
|
+
|
|
375
|
+
/**
|
|
376
|
+
* Size of the state directory, for `superagent_list`.
|
|
377
|
+
* @returns {Promise<{ bytes: number, files: number, corrupt: number }>} totals.
|
|
378
|
+
*/
|
|
379
|
+
async stats() {
|
|
380
|
+
const totals = { bytes: 0, files: 0, corrupt: 0 }
|
|
381
|
+
let names
|
|
382
|
+
try {
|
|
383
|
+
names = await fsp.readdir(runsDir)
|
|
384
|
+
} catch {
|
|
385
|
+
return totals
|
|
386
|
+
}
|
|
387
|
+
for (const name of names) {
|
|
388
|
+
try {
|
|
389
|
+
const stat = await fsp.stat(path.join(runsDir, name))
|
|
390
|
+
if (!stat.isFile()) continue
|
|
391
|
+
totals.files++
|
|
392
|
+
totals.bytes += stat.size
|
|
393
|
+
if (name.includes('.corrupt-')) totals.corrupt++
|
|
394
|
+
} catch {
|
|
395
|
+
// A file removed mid-scan does not change the answer.
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
return totals
|
|
399
|
+
},
|
|
400
|
+
}
|
|
401
|
+
}
|
|
402
|
+
|