@orkestrel/scaffold 0.0.121 → 0.0.123
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/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +57 -9
- package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +22 -2
- package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +539 -0
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1163 -0
- package/dist/agents/skills/orkestrel-publish/scripts/pins.js +5 -5
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +67 -5
- package/dist/bin/main.js +8 -6
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +29 -18
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +7 -6
- package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +3 -2
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +65 -9
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +28 -2
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +4 -2
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +3 -2
- package/dist/host/agents/skills/orkestrel-harden/SKILL.md +24 -11
- package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +18 -12
- package/dist/host/agents/skills/orkestrel-harden/references/document.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +2 -1
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +4 -4
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +642 -0
- package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +665 -0
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +16 -15
- package/dist/host/agents/skills/orkestrel-parallel/references/{claude.md → claude-code.md} +13 -13
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1433 -0
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +12 -9
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +39 -8
- package/dist/host/agents/skills/orkestrel-publish/references/window.md +5 -1
- package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +5 -5
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +86 -7
- package/dist/host/claude/AGENTS.md +2 -2
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/builder.md +1 -1
- package/dist/host/claude/agents/distiller.md +2 -1
- package/dist/host/claude/agents/grok.md +2 -2
- package/dist/host/claude/agents/opus.md +8 -7
- package/dist/host/claude/agents/orkestrel.md +7 -7
- package/dist/host/claude/agents/planner.md +3 -3
- package/dist/host/claude/agents/reviewer.md +3 -3
- package/dist/host/claude/agents/scout.md +2 -1
- package/dist/host/claude/agents/verifier.md +2 -2
- package/dist/host/claude/rules/campaign.md +15 -13
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/names.md +13 -7
- package/dist/host/claude/rules/patterns.md +14 -0
- package/dist/host/claude/rules/quality.md +4 -1
- package/dist/host/claude/rules/tests.md +5 -1
- package/dist/host/claude/rules/workspace.md +9 -0
- package/dist/host/claude/rules/writing.md +1 -1
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +6 -6
- package/dist/host/codex/agents/astra.toml +1 -1
- package/dist/host/codex/agents/builder.toml +1 -1
- package/dist/host/codex/agents/distiller.toml +4 -2
- package/dist/host/codex/agents/grok.toml +5 -2
- package/dist/host/codex/agents/opus.toml +6 -4
- package/dist/host/codex/agents/planner.toml +6 -5
- package/dist/host/codex/agents/reviewer.toml +9 -8
- package/dist/host/codex/agents/scout.toml +5 -1
- package/dist/host/codex/agents/verifier.toml +8 -3
- package/dist/host/dotfiles/gitignore +1 -2
- package/dist/host/guides/agent.md +1119 -457
- package/dist/host/guides/ndjson.md +81 -21
- package/dist/host/guides/ollama.md +22 -18
- package/dist/host/guides/probe.md +29 -27
- package/dist/host/guides/scaffold.md +42 -15
- package/dist/host/guides/study.md +538 -450
- package/dist/host/manifest.json +81 -63
- package/dist/host/tests/config.test.ts +7 -0
- package/dist/src/core/index.cjs +14 -8
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1 -4
- package/dist/src/core/index.d.ts +1 -4
- package/dist/src/core/index.js +14 -8
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +87 -8
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +50 -6
- package/dist/src/server/index.d.ts +50 -6
- package/dist/src/server/index.js +87 -10
- package/dist/src/server/index.js.map +1 -1
- package/package.json +2 -2
|
@@ -0,0 +1,1433 @@
|
|
|
1
|
+
// Run one process-running command at a time on this host, in arrival order, across every checkout
|
|
2
|
+
// and shell of one user account. Run from the checkout root:
|
|
3
|
+
// node .agents/skills/orkestrel-parallel/scripts/lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] -- COMMAND [ARGS...]
|
|
4
|
+
// node .agents/skills/orkestrel-parallel/scripts/lane.ts --status [--root DIR] [--json]
|
|
5
|
+
// A run takes a ticket, waits for every earlier ticket, runs the command through the dispatch skill's
|
|
6
|
+
// `launch` script, reads the process tree, and releases. The launcher owns the cap, the journal, and
|
|
7
|
+
// the errors file; its stdout lines pass through verbatim, and the cap must be above 0. The two forms
|
|
8
|
+
// are two operation modes, so `--status` with a run's flag or a bare `--` is refused, and `--json`
|
|
9
|
+
// belongs to `--status` alone. A run therefore cannot ask the launcher for its own `--status` files.
|
|
10
|
+
// `--status` prints each ticket in arrival order with its label and
|
|
11
|
+
// `live`, `dead`, or `unread`, and names the holder: the earliest live ticket with a run record. It
|
|
12
|
+
// writes nothing, removes nothing, and creates no root; an absent root reads as an empty queue. The
|
|
13
|
+
// root is `.orkestrel/lane` under the account's home directory, read from the account record and
|
|
14
|
+
// never from an environment variable; `--root DIR` is for a proof. Bench execs stay outside the lane,
|
|
15
|
+
// because the host bound counts process-running commands.
|
|
16
|
+
// Exit: the launcher's code (the command's code, 124 when capped, 127 when the command could not
|
|
17
|
+
// start); 1 when a signal ended the launcher; 64 on usage; 75 when the lane refused before the
|
|
18
|
+
// command ran; 70 when the command ran and its tree still reads as present, or its ticket could not
|
|
19
|
+
// be removed. `--status` exits 0 on a read and 75 when the root cannot be listed. A command that itself
|
|
20
|
+
// exits 64, 70, or 75 reads like the lane's own code.
|
|
21
|
+
// Protocol: a process listens on an endpoint named by a random token, writes the complete ticket to
|
|
22
|
+
// `<token>.stage`, and hard-links that file to `<sequence>.ticket`, which publishes it in one step.
|
|
23
|
+
// A waiter parks on the `close` of the nearest earlier ticket's endpoint with no timer, and a refused
|
|
24
|
+
// connect means that owner is gone. A waiter on a stage file writes one byte, and a published owner
|
|
25
|
+
// closes that connection, because a connection its synchronous allocation left unaccepted would
|
|
26
|
+
// otherwise stay parked on a process that waits behind it.
|
|
27
|
+
// Limits:
|
|
28
|
+
// - Process-identifier reuse, Windows. A row is matched by id and creation date, bounded by a clock
|
|
29
|
+
// comparison, so a reuse of an exited seed's id inside the clock allowance can misattribute a row.
|
|
30
|
+
// Only the holder kills, and only inside its own bounds.
|
|
31
|
+
// - Process-identifier reuse, other hosts. A group id cannot be reused while the group has a member.
|
|
32
|
+
// An empty group's id can be reused by a later group leader, so a reclaimer might refuse on a stale
|
|
33
|
+
// run record. It never kills on one.
|
|
34
|
+
// - A descendant that detached itself. A process that left the group, a run started through the WMI
|
|
35
|
+
// detach of `.agents/platforms/windows.md`, and a Windows descendant whose parent exited before the
|
|
36
|
+
// reading and is no recorded seed are all outside every reading. A background child of a `bash`
|
|
37
|
+
// command can be that case, so pass a command directly rather than through `bash -c`. "No surviving
|
|
38
|
+
// process tree" means the group, or the parent-link closure, and no more.
|
|
39
|
+
// - An owner ended alone mid-run. No event reports a foreign tree's end. Arrivals exit 75 until that
|
|
40
|
+
// tree is gone, and the next arrival then reclaims.
|
|
41
|
+
// - An owner ended between the run record and the launcher id. The tree cannot be identified. Arrivals
|
|
42
|
+
// exit 75 until a person deletes the named files. An owner ended between the launcher id and the
|
|
43
|
+
// command id leaves the command as no seed, so its tree reads through the launcher alone.
|
|
44
|
+
// - An unreaped member. On a host whose init does not reap, a killed member can keep reading as
|
|
45
|
+
// present. The lane exits 70 and stays held.
|
|
46
|
+
// - Listing completeness. No probe proves that a listing returns every stable entry. The design takes
|
|
47
|
+
// it from the documented directory-read contract.
|
|
48
|
+
// - Queue scope. The queue is one per user account per host. A wiped root, a second account, or a
|
|
49
|
+
// `--root` outside a proof gives a second queue that does not see the first.
|
|
50
|
+
// - A denied root. A sandbox that refuses the root or the endpoint exits 75; no sandboxed bench exec
|
|
51
|
+
// has run this script.
|
|
52
|
+
// - Linux. Every non-Windows branch is unread on this host and needs a Linux run: the socket file, the
|
|
53
|
+
// process group, and the signal handling.
|
|
54
|
+
// Migration stop: a second queue does not see the first, so while a host's sessions run another
|
|
55
|
+
// serializer, no caller moves. After a scaffold release carries this script and no command runs on the
|
|
56
|
+
// host, move every caller in one step and delete the serializer this replaces.
|
|
57
|
+
import type { ChildProcess } from 'node:child_process'
|
|
58
|
+
import type { Server, Socket } from 'node:net'
|
|
59
|
+
import { spawn, spawnSync } from 'node:child_process'
|
|
60
|
+
import { randomUUID } from 'node:crypto'
|
|
61
|
+
import {
|
|
62
|
+
existsSync,
|
|
63
|
+
linkSync,
|
|
64
|
+
mkdirSync,
|
|
65
|
+
readdirSync,
|
|
66
|
+
readFileSync,
|
|
67
|
+
realpathSync,
|
|
68
|
+
rmSync,
|
|
69
|
+
writeFileSync,
|
|
70
|
+
} from 'node:fs'
|
|
71
|
+
import { connect, createServer } from 'node:net'
|
|
72
|
+
import { hostname, userInfo } from 'node:os'
|
|
73
|
+
import { dirname, extname, join } from 'node:path'
|
|
74
|
+
import { createInterface } from 'node:readline'
|
|
75
|
+
import { fileURLToPath } from 'node:url'
|
|
76
|
+
|
|
77
|
+
/** Holds the protocol version a ticket carries, so a process refuses a ticket it cannot read. */
|
|
78
|
+
export const PROTOCOL = 1
|
|
79
|
+
|
|
80
|
+
/** Lists the flags that take a value. */
|
|
81
|
+
export const VALUE_FLAGS: readonly string[] = [
|
|
82
|
+
'--label',
|
|
83
|
+
'--journal',
|
|
84
|
+
'--errors',
|
|
85
|
+
'--cap',
|
|
86
|
+
'--root',
|
|
87
|
+
]
|
|
88
|
+
|
|
89
|
+
/** Lists the flags only a run reads, which `--status` refuses. */
|
|
90
|
+
export const RUN_FLAGS: readonly string[] = ['--label', '--journal', '--errors', '--cap']
|
|
91
|
+
|
|
92
|
+
/** Lists every flag the script reads, value flags and switches alike. */
|
|
93
|
+
export const FLAGS: readonly string[] = [...VALUE_FLAGS, '--status', '--json']
|
|
94
|
+
|
|
95
|
+
/** Holds the usage line printed on a usage refusal. */
|
|
96
|
+
export const USAGE =
|
|
97
|
+
'usage: lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] -- COMMAND [ARGS...] | lane.ts --status [--root DIR] [--json]; the journal and the errors file differ, and the cap is a number of seconds above 0 up to 2147483'
|
|
98
|
+
|
|
99
|
+
/** Holds the longest cap in whole seconds, equal to the limit of the sibling launcher. */
|
|
100
|
+
export const MAX_CAP_SECONDS = 2_147_483
|
|
101
|
+
|
|
102
|
+
/** Holds the digit count of a ticket name, which keeps a directory listing readable in order. */
|
|
103
|
+
export const SEQUENCE_WIDTH = 12
|
|
104
|
+
|
|
105
|
+
/** Holds the name ending of a stage file. */
|
|
106
|
+
export const STAGE_SUFFIX = '.stage'
|
|
107
|
+
|
|
108
|
+
/** Holds the name ending of a ticket. */
|
|
109
|
+
export const TICKET_SUFFIX = '.ticket'
|
|
110
|
+
|
|
111
|
+
/** Holds the name ending of a run record. */
|
|
112
|
+
export const RUN_SUFFIX = '.run'
|
|
113
|
+
|
|
114
|
+
/** Holds the name ending of a token's socket file on a host without named pipes. */
|
|
115
|
+
export const SOCKET_SUFFIX = '.sock'
|
|
116
|
+
|
|
117
|
+
/** Matches a token, which every endpoint name and stage file name is built from. */
|
|
118
|
+
export const TOKEN_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u
|
|
119
|
+
|
|
120
|
+
/** Matches a ticket name and captures its sequence. */
|
|
121
|
+
export const TICKET_PATTERN = /^(\d+)\.ticket$/u
|
|
122
|
+
|
|
123
|
+
/** Matches one snapshot row: process id, parent id, and creation time in milliseconds. */
|
|
124
|
+
export const ROW_PATTERN = /^(\d+) (\d+) (\d+)$/u
|
|
125
|
+
|
|
126
|
+
/** Lists the signals that interrupt a lane on a host that delivers them. */
|
|
127
|
+
export const STOP_SIGNALS: readonly NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP']
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Holds the clock allowance in milliseconds between `Date.now` and a process's creation date.
|
|
131
|
+
*
|
|
132
|
+
* @remarks
|
|
133
|
+
* The allowance is one default clock tick of 15.625 ms, rounded up, in case the kernel stamps from
|
|
134
|
+
* the tick.
|
|
135
|
+
*/
|
|
136
|
+
export const CLOCK_ALLOWANCE_MS = 16
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Holds the kill attempts the handover reading makes before it stays held.
|
|
140
|
+
*
|
|
141
|
+
* @remarks
|
|
142
|
+
* Each attempt on Windows is a synchronous `taskkill` per member and a process snapshot. A member
|
|
143
|
+
* that outlives this many forced kills is a defect a person reads rather than a wait the queue absorbs.
|
|
144
|
+
*/
|
|
145
|
+
export const KILL_BUDGET = 5
|
|
146
|
+
|
|
147
|
+
/** Holds the pause in milliseconds after a group signal, because no event reports a group's end. */
|
|
148
|
+
export const KILL_PAUSE_MS = 200
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Holds the removal retries, each `rmSync` delay growing by {@link REMOVAL_DELAY_MS}.
|
|
152
|
+
*
|
|
153
|
+
* @remarks
|
|
154
|
+
* The retries outlast a scanner holding a file.
|
|
155
|
+
*/
|
|
156
|
+
export const REMOVAL_RETRIES = 10
|
|
157
|
+
|
|
158
|
+
/** Holds the base delay in milliseconds between removal retries. */
|
|
159
|
+
export const REMOVAL_DELAY_MS = 100
|
|
160
|
+
|
|
161
|
+
/** Holds the PowerShell text that prints one row per process with a creation date. */
|
|
162
|
+
export const SNAPSHOT_COMMAND =
|
|
163
|
+
"Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate | Where-Object { $_.CreationDate } | ForEach-Object { '{0} {1} {2}' -f $_.ProcessId, $_.ParentProcessId, ([DateTimeOffset]$_.CreationDate).ToUnixTimeMilliseconds() }"
|
|
164
|
+
|
|
165
|
+
/** Describes the complete record a stage file holds and a ticket publishes. */
|
|
166
|
+
export interface Ticket {
|
|
167
|
+
readonly protocol: number
|
|
168
|
+
readonly token: string
|
|
169
|
+
readonly label: string
|
|
170
|
+
readonly pid: number
|
|
171
|
+
readonly host: string
|
|
172
|
+
readonly platform: string
|
|
173
|
+
readonly cwd: string
|
|
174
|
+
readonly arrived: string
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** Describes one ticket in the queue: its sequence and its record, undefined when unreadable. */
|
|
178
|
+
export interface Entry {
|
|
179
|
+
readonly sequence: number
|
|
180
|
+
readonly ticket: Ticket | undefined
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/** Describes the record of a started command: when it started and the ids that seed its tree. */
|
|
184
|
+
export interface Run {
|
|
185
|
+
readonly started: number
|
|
186
|
+
readonly launcher: number | undefined
|
|
187
|
+
readonly command: number | undefined
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** Describes one process in a Windows snapshot. */
|
|
191
|
+
export interface Row {
|
|
192
|
+
readonly pid: number
|
|
193
|
+
readonly parent: number
|
|
194
|
+
readonly created: number
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/** Describes what a process does next on the queue. */
|
|
198
|
+
export type Turn =
|
|
199
|
+
| { readonly state: 'holder' }
|
|
200
|
+
| { readonly state: 'staged'; readonly name: string }
|
|
201
|
+
| { readonly state: 'behind'; readonly entry: Entry }
|
|
202
|
+
| { readonly state: 'refused'; readonly reason: string }
|
|
203
|
+
|
|
204
|
+
/** Describes what a sweep confirmed: whether the tree reads as gone, and the members it left. */
|
|
205
|
+
export interface Sweep {
|
|
206
|
+
readonly gone: boolean
|
|
207
|
+
readonly members: readonly number[]
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/** Describes one ticket as `--status` reports it. */
|
|
211
|
+
export interface StatusRow {
|
|
212
|
+
readonly sequence: number
|
|
213
|
+
readonly label: string | undefined
|
|
214
|
+
readonly pid: number | undefined
|
|
215
|
+
readonly state: 'live' | 'dead' | 'unread'
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/** Describes what `--status` reads: every ticket in arrival order and the holder among them. */
|
|
219
|
+
export interface Status {
|
|
220
|
+
readonly tickets: readonly StatusRow[]
|
|
221
|
+
readonly holder: StatusRow | undefined
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/** Describes one validated run. */
|
|
225
|
+
export interface LaneOptions {
|
|
226
|
+
readonly root: string
|
|
227
|
+
readonly label: string
|
|
228
|
+
readonly journal: string
|
|
229
|
+
readonly errors: string
|
|
230
|
+
readonly cap: number
|
|
231
|
+
readonly command: readonly string[]
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/**
|
|
235
|
+
* Holds a process's endpoint, whose existence is the process's liveness.
|
|
236
|
+
*
|
|
237
|
+
* @remarks
|
|
238
|
+
* The host closes the endpoint however the process ends. The server sends nothing. A stage waiter
|
|
239
|
+
* writes one byte, and a published owner closes that connection on reading it; the connection of a
|
|
240
|
+
* ticket waiter stays open until the process ends.
|
|
241
|
+
*/
|
|
242
|
+
export class Token {
|
|
243
|
+
readonly #sockets = new Set<Socket>()
|
|
244
|
+
readonly #server: Server
|
|
245
|
+
#published = false
|
|
246
|
+
|
|
247
|
+
constructor() {
|
|
248
|
+
this.#server = createServer((socket) => this.#admit(socket))
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* Starts listening.
|
|
253
|
+
*
|
|
254
|
+
* @param endpoint - The endpoint to listen on.
|
|
255
|
+
* @returns A promise that resolves when the endpoint accepts connections, and rejects with the
|
|
256
|
+
* listen failure.
|
|
257
|
+
*/
|
|
258
|
+
listen(endpoint: string): Promise<void> {
|
|
259
|
+
return new Promise((resolve, reject) => {
|
|
260
|
+
this.#server.once('error', reject)
|
|
261
|
+
this.#server.listen(endpoint, () => {
|
|
262
|
+
this.#server.removeListener('error', reject)
|
|
263
|
+
resolve()
|
|
264
|
+
})
|
|
265
|
+
})
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/** Marks the stage as ended and closes every accepted connection, which wakes each waiter. */
|
|
269
|
+
publish(): void {
|
|
270
|
+
this.#published = true
|
|
271
|
+
for (const socket of this.#sockets) socket.destroy()
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/**
|
|
275
|
+
* Closes the endpoint and every connection.
|
|
276
|
+
*
|
|
277
|
+
* @returns A promise that resolves when the server has closed.
|
|
278
|
+
*/
|
|
279
|
+
destroy(): Promise<void> {
|
|
280
|
+
for (const socket of this.#sockets) socket.destroy()
|
|
281
|
+
return new Promise((resolve) => {
|
|
282
|
+
this.#server.close(() => resolve())
|
|
283
|
+
})
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
// A byte after the publish comes from a stage waiter whose connection the allocation left unaccepted.
|
|
287
|
+
#admit(socket: Socket): void {
|
|
288
|
+
this.#sockets.add(socket)
|
|
289
|
+
socket.on('error', () => undefined)
|
|
290
|
+
socket.on('close', () => this.#sockets.delete(socket))
|
|
291
|
+
socket.on('data', () => {
|
|
292
|
+
if (this.#published) socket.destroy()
|
|
293
|
+
})
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/**
|
|
298
|
+
* Reads the value that follows a flag.
|
|
299
|
+
*
|
|
300
|
+
* @remarks
|
|
301
|
+
* The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
|
|
302
|
+
* and the `--flag=value` form is not read.
|
|
303
|
+
*
|
|
304
|
+
* @param argv - The arguments before the bare `--`.
|
|
305
|
+
* @param name - The flag, such as `--label`.
|
|
306
|
+
* @returns The value after the flag, or undefined when the flag is absent, last, or followed by
|
|
307
|
+
* another flag.
|
|
308
|
+
*/
|
|
309
|
+
export function readOption(argv: readonly string[], name: string): string | undefined {
|
|
310
|
+
const index = argv.indexOf(name)
|
|
311
|
+
const value = index === -1 ? undefined : argv[index + 1]
|
|
312
|
+
return value === undefined || value.startsWith('--') ? undefined : value
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* Names the value flags a caller gave with no value.
|
|
317
|
+
*
|
|
318
|
+
* @param argv - The arguments before the bare `--`.
|
|
319
|
+
* @param names - The flags that take a value.
|
|
320
|
+
* @returns Each named flag that appears last or is followed by another flag, in argument order.
|
|
321
|
+
*/
|
|
322
|
+
export function readMissingFlags(
|
|
323
|
+
argv: readonly string[],
|
|
324
|
+
names: readonly string[],
|
|
325
|
+
): readonly string[] {
|
|
326
|
+
return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* Names the flags a caller gave that the script does not read.
|
|
331
|
+
*
|
|
332
|
+
* @remarks
|
|
333
|
+
* A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
|
|
334
|
+
* scan, so the command after it keeps every argument.
|
|
335
|
+
*
|
|
336
|
+
* @param argv - The arguments after the script path.
|
|
337
|
+
* @param flags - Every flag the script reads, value flags and switches alike.
|
|
338
|
+
* @returns Each argument that opens with `--` and is not a read flag, in argument order.
|
|
339
|
+
*/
|
|
340
|
+
export function readUnknownFlags(
|
|
341
|
+
argv: readonly string[],
|
|
342
|
+
flags: readonly string[],
|
|
343
|
+
): readonly string[] {
|
|
344
|
+
const end = argv.indexOf('--')
|
|
345
|
+
return (end === -1 ? argv : argv.slice(0, end)).filter(
|
|
346
|
+
(argument) => argument.startsWith('--') && !flags.includes(argument),
|
|
347
|
+
)
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
/**
|
|
351
|
+
* Reads the arguments that are neither a flag nor the value of a value flag.
|
|
352
|
+
*
|
|
353
|
+
* @param argv - The arguments before the bare `--`.
|
|
354
|
+
* @param valueFlags - The flags that take a value.
|
|
355
|
+
* @returns The positional arguments in order.
|
|
356
|
+
*/
|
|
357
|
+
export function readPositionals(
|
|
358
|
+
argv: readonly string[],
|
|
359
|
+
valueFlags: readonly string[],
|
|
360
|
+
): readonly string[] {
|
|
361
|
+
return argv.filter(
|
|
362
|
+
(argument, index) => !argument.startsWith('--') && !valueFlags.includes(argv[index - 1] ?? ''),
|
|
363
|
+
)
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
/**
|
|
367
|
+
* Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
|
|
368
|
+
*
|
|
369
|
+
* @param text - The text to quote.
|
|
370
|
+
* @returns The JSON string literal of the text, ending in an ellipsis inside the quotes when cut.
|
|
371
|
+
*/
|
|
372
|
+
export function quote(text: string): string {
|
|
373
|
+
return JSON.stringify(text.length > 80 ? `${text.slice(0, 80)}…` : text)
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/**
|
|
377
|
+
* Reads the system error code a thrown value carries.
|
|
378
|
+
*
|
|
379
|
+
* @param error - The thrown value.
|
|
380
|
+
* @returns The code, or the value's text when it carries none.
|
|
381
|
+
*/
|
|
382
|
+
export function readCode(error: unknown): string {
|
|
383
|
+
return error instanceof Error && 'code' in error && typeof error.code === 'string'
|
|
384
|
+
? error.code
|
|
385
|
+
: String(error)
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
/**
|
|
389
|
+
* Resolves the queue root.
|
|
390
|
+
*
|
|
391
|
+
* @remarks
|
|
392
|
+
* `os.userInfo` reads the account record rather than `HOME`, `USERPROFILE`, or `TEMP`, so every
|
|
393
|
+
* checkout and shell of one account resolves one directory.
|
|
394
|
+
*
|
|
395
|
+
* @param argument - The `--root` value, for a proof.
|
|
396
|
+
* @returns The directory that holds the queue.
|
|
397
|
+
*/
|
|
398
|
+
export function resolveRoot(argument?: string): string {
|
|
399
|
+
return argument ?? join(userInfo().homedir, '.orkestrel', 'lane')
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
/**
|
|
403
|
+
* Resolves the sibling launcher from the running file, so a built twin spawns its `.js` sibling.
|
|
404
|
+
*
|
|
405
|
+
* @returns The path of the dispatch skill's `launch` script.
|
|
406
|
+
*/
|
|
407
|
+
export function resolveLauncher(): string {
|
|
408
|
+
const self = fileURLToPath(import.meta.url)
|
|
409
|
+
return join(dirname(self), '..', '..', 'orkestrel-dispatch', 'scripts', `launch${extname(self)}`)
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
/**
|
|
413
|
+
* Renders the endpoint a token names.
|
|
414
|
+
*
|
|
415
|
+
* @remarks
|
|
416
|
+
* The form is platform-defined: Windows has named pipes, and any other host takes a socket file
|
|
417
|
+
* under the root. The Windows host closes a pipe with its process, and a socket file outlives its
|
|
418
|
+
* process, so a reclaimer removes it.
|
|
419
|
+
*
|
|
420
|
+
* @param root - The queue root.
|
|
421
|
+
* @param token - The token.
|
|
422
|
+
* @returns The path `net.listen` and `net.connect` take.
|
|
423
|
+
*/
|
|
424
|
+
export function renderEndpoint(root: string, token: string): string {
|
|
425
|
+
return process.platform === 'win32'
|
|
426
|
+
? `\\\\.\\pipe\\orkestrel-lane-${token}`
|
|
427
|
+
: join(root, `${token}${SOCKET_SUFFIX}`)
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
/**
|
|
431
|
+
* Renders the name of a ticket.
|
|
432
|
+
*
|
|
433
|
+
* @param sequence - The ticket's sequence.
|
|
434
|
+
* @returns The file name, at a fixed width.
|
|
435
|
+
*/
|
|
436
|
+
export function renderTicketName(sequence: number): string {
|
|
437
|
+
return `${String(sequence).padStart(SEQUENCE_WIDTH, '0')}${TICKET_SUFFIX}`
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* Renders the name of a run record.
|
|
442
|
+
*
|
|
443
|
+
* @param sequence - The ticket's sequence.
|
|
444
|
+
* @returns The file name, at a fixed width.
|
|
445
|
+
*/
|
|
446
|
+
export function renderRunName(sequence: number): string {
|
|
447
|
+
return `${String(sequence).padStart(SEQUENCE_WIDTH, '0')}${RUN_SUFFIX}`
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
/**
|
|
451
|
+
* Lists a directory's names.
|
|
452
|
+
*
|
|
453
|
+
* @param root - The queue root.
|
|
454
|
+
* @returns The names; empty when the directory is absent.
|
|
455
|
+
*/
|
|
456
|
+
export function readNames(root: string): readonly string[] {
|
|
457
|
+
try {
|
|
458
|
+
return readdirSync(root)
|
|
459
|
+
} catch (error) {
|
|
460
|
+
if (readCode(error) === 'ENOENT') return []
|
|
461
|
+
throw error
|
|
462
|
+
}
|
|
463
|
+
}
|
|
464
|
+
|
|
465
|
+
/**
|
|
466
|
+
* Reads the sequences a listing holds.
|
|
467
|
+
*
|
|
468
|
+
* @param names - The directory's names.
|
|
469
|
+
* @returns Each ticket's sequence, in no promised order.
|
|
470
|
+
*/
|
|
471
|
+
export function readSequences(names: readonly string[]): readonly number[] {
|
|
472
|
+
return names.flatMap((name) => {
|
|
473
|
+
const match = TICKET_PATTERN.exec(name)
|
|
474
|
+
return match?.[1] === undefined ? [] : [Number(match[1])]
|
|
475
|
+
})
|
|
476
|
+
}
|
|
477
|
+
|
|
478
|
+
/**
|
|
479
|
+
* Checks whether a value is a ticket record.
|
|
480
|
+
*
|
|
481
|
+
* @param value - The parsed JSON value.
|
|
482
|
+
* @returns True when every field has its type and the token has the token's form; false otherwise.
|
|
483
|
+
*/
|
|
484
|
+
export function isTicket(value: unknown): value is Ticket {
|
|
485
|
+
return (
|
|
486
|
+
typeof value === 'object' &&
|
|
487
|
+
value !== null &&
|
|
488
|
+
'protocol' in value &&
|
|
489
|
+
typeof value.protocol === 'number' &&
|
|
490
|
+
'token' in value &&
|
|
491
|
+
typeof value.token === 'string' &&
|
|
492
|
+
TOKEN_PATTERN.test(value.token) &&
|
|
493
|
+
'label' in value &&
|
|
494
|
+
typeof value.label === 'string' &&
|
|
495
|
+
'pid' in value &&
|
|
496
|
+
typeof value.pid === 'number' &&
|
|
497
|
+
'host' in value &&
|
|
498
|
+
typeof value.host === 'string' &&
|
|
499
|
+
'platform' in value &&
|
|
500
|
+
typeof value.platform === 'string' &&
|
|
501
|
+
'cwd' in value &&
|
|
502
|
+
typeof value.cwd === 'string' &&
|
|
503
|
+
'arrived' in value &&
|
|
504
|
+
typeof value.arrived === 'string'
|
|
505
|
+
)
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
/**
|
|
509
|
+
* Checks whether a value is a run record.
|
|
510
|
+
*
|
|
511
|
+
* @param value - The parsed JSON value.
|
|
512
|
+
* @returns True when `started` is a number and each present id is a number; false otherwise.
|
|
513
|
+
*/
|
|
514
|
+
export function isRun(value: unknown): value is Run {
|
|
515
|
+
return (
|
|
516
|
+
typeof value === 'object' &&
|
|
517
|
+
value !== null &&
|
|
518
|
+
'started' in value &&
|
|
519
|
+
typeof value.started === 'number' &&
|
|
520
|
+
(!('launcher' in value) || typeof value.launcher === 'number') &&
|
|
521
|
+
(!('command' in value) || typeof value.command === 'number')
|
|
522
|
+
)
|
|
523
|
+
}
|
|
524
|
+
|
|
525
|
+
/**
|
|
526
|
+
* Parses text as JSON.
|
|
527
|
+
*
|
|
528
|
+
* @param text - The text.
|
|
529
|
+
* @returns The parsed value, or undefined when the text is not JSON.
|
|
530
|
+
*/
|
|
531
|
+
export function parseText(text: string): unknown {
|
|
532
|
+
try {
|
|
533
|
+
const parsed: unknown = JSON.parse(text)
|
|
534
|
+
return parsed
|
|
535
|
+
} catch {
|
|
536
|
+
return undefined
|
|
537
|
+
}
|
|
538
|
+
}
|
|
539
|
+
|
|
540
|
+
/**
|
|
541
|
+
* Reads one queue entry.
|
|
542
|
+
*
|
|
543
|
+
* @param root - The queue root.
|
|
544
|
+
* @param sequence - The ticket's sequence.
|
|
545
|
+
* @returns The entry, its ticket undefined when the file is unreadable or malformed; empty when the
|
|
546
|
+
* ticket is gone.
|
|
547
|
+
*/
|
|
548
|
+
export function readEntry(root: string, sequence: number): readonly Entry[] {
|
|
549
|
+
try {
|
|
550
|
+
const parsed = parseText(readFileSync(join(root, renderTicketName(sequence)), 'utf8'))
|
|
551
|
+
return [{ sequence, ticket: isTicket(parsed) ? parsed : undefined }]
|
|
552
|
+
} catch (error) {
|
|
553
|
+
return readCode(error) === 'ENOENT' ? [] : [{ sequence, ticket: undefined }]
|
|
554
|
+
}
|
|
555
|
+
}
|
|
556
|
+
|
|
557
|
+
/**
|
|
558
|
+
* Orders entries by arrival.
|
|
559
|
+
*
|
|
560
|
+
* @param entries - The entries in any order.
|
|
561
|
+
* @returns The entries by ascending sequence, which the exclusive link allocated.
|
|
562
|
+
*/
|
|
563
|
+
export function orderEntries(entries: readonly Entry[]): readonly Entry[] {
|
|
564
|
+
return entries.toSorted((left, right) => left.sequence - right.sequence)
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
/**
|
|
568
|
+
* Reads the queue in arrival order.
|
|
569
|
+
*
|
|
570
|
+
* @param root - The queue root.
|
|
571
|
+
* @returns Every ticket that exists when it is read.
|
|
572
|
+
*/
|
|
573
|
+
export function readQueue(root: string): readonly Entry[] {
|
|
574
|
+
return orderEntries(
|
|
575
|
+
readSequences(readNames(root)).flatMap((sequence) => readEntry(root, sequence)),
|
|
576
|
+
)
|
|
577
|
+
}
|
|
578
|
+
|
|
579
|
+
/**
|
|
580
|
+
* Reads a run record.
|
|
581
|
+
*
|
|
582
|
+
* @param root - The queue root.
|
|
583
|
+
* @param sequence - The ticket's sequence.
|
|
584
|
+
* @returns The record; `absent` when no record exists; `unread` when it cannot be read as a record.
|
|
585
|
+
*/
|
|
586
|
+
export function readRun(root: string, sequence: number): Run | 'absent' | 'unread' {
|
|
587
|
+
try {
|
|
588
|
+
const parsed = parseText(readFileSync(join(root, renderRunName(sequence)), 'utf8'))
|
|
589
|
+
return isRun(parsed)
|
|
590
|
+
? {
|
|
591
|
+
started: parsed.started,
|
|
592
|
+
launcher: parsed.launcher,
|
|
593
|
+
command: parsed.command,
|
|
594
|
+
}
|
|
595
|
+
: 'unread'
|
|
596
|
+
} catch (error) {
|
|
597
|
+
return readCode(error) === 'ENOENT' ? 'absent' : 'unread'
|
|
598
|
+
}
|
|
599
|
+
}
|
|
600
|
+
|
|
601
|
+
/**
|
|
602
|
+
* Writes a run record.
|
|
603
|
+
*
|
|
604
|
+
* @param root - The queue root.
|
|
605
|
+
* @param sequence - The ticket's sequence.
|
|
606
|
+
* @param run - The record.
|
|
607
|
+
*/
|
|
608
|
+
export function writeRun(root: string, sequence: number, run: Run): void {
|
|
609
|
+
writeFileSync(join(root, renderRunName(sequence)), JSON.stringify(run))
|
|
610
|
+
}
|
|
611
|
+
|
|
612
|
+
/**
|
|
613
|
+
* Removes a file inside the removal budget.
|
|
614
|
+
*
|
|
615
|
+
* @param path - The file; a file that is already gone is not an error.
|
|
616
|
+
*/
|
|
617
|
+
export function removeFile(path: string): void {
|
|
618
|
+
rmSync(path, { force: true, maxRetries: REMOVAL_RETRIES, retryDelay: REMOVAL_DELAY_MS })
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
/**
|
|
622
|
+
* Builds the ticket of this process.
|
|
623
|
+
*
|
|
624
|
+
* @param token - The process's token.
|
|
625
|
+
* @param label - The run's label.
|
|
626
|
+
* @returns The complete ticket.
|
|
627
|
+
*/
|
|
628
|
+
export function buildTicket(token: string, label: string): Ticket {
|
|
629
|
+
return {
|
|
630
|
+
protocol: PROTOCOL,
|
|
631
|
+
token,
|
|
632
|
+
label,
|
|
633
|
+
pid: process.pid,
|
|
634
|
+
host: hostname(),
|
|
635
|
+
platform: process.platform,
|
|
636
|
+
cwd: process.cwd(),
|
|
637
|
+
arrived: new Date().toISOString(),
|
|
638
|
+
}
|
|
639
|
+
}
|
|
640
|
+
|
|
641
|
+
/**
|
|
642
|
+
* Writes the complete ticket to the stage file, which also marks this process as choosing.
|
|
643
|
+
*
|
|
644
|
+
* @param root - The queue root.
|
|
645
|
+
* @param ticket - The ticket.
|
|
646
|
+
*/
|
|
647
|
+
export function writeStage(root: string, ticket: Ticket): void {
|
|
648
|
+
writeFileSync(join(root, `${ticket.token}${STAGE_SUFFIX}`), JSON.stringify(ticket))
|
|
649
|
+
}
|
|
650
|
+
|
|
651
|
+
/**
|
|
652
|
+
* Links a file to a name, reporting a name another process took.
|
|
653
|
+
*
|
|
654
|
+
* @param from - The existing file.
|
|
655
|
+
* @param to - The name to take.
|
|
656
|
+
* @returns True when this call took the name; false when the name exists. Thrown when the host
|
|
657
|
+
* refuses the link for any other reason.
|
|
658
|
+
*/
|
|
659
|
+
export function tryLink(from: string, to: string): boolean {
|
|
660
|
+
try {
|
|
661
|
+
linkSync(from, to)
|
|
662
|
+
return true
|
|
663
|
+
} catch (error) {
|
|
664
|
+
if (readCode(error) === 'EEXIST') return false
|
|
665
|
+
throw error
|
|
666
|
+
}
|
|
667
|
+
}
|
|
668
|
+
|
|
669
|
+
/**
|
|
670
|
+
* Publishes a stage file as the next ticket in one step.
|
|
671
|
+
*
|
|
672
|
+
* @remarks
|
|
673
|
+
* The sequence comes from a listing and the exclusive link, never from a clock, so tickets in one
|
|
674
|
+
* millisecond cannot tie. A lost link lists again.
|
|
675
|
+
*
|
|
676
|
+
* @param root - The queue root.
|
|
677
|
+
* @param token - The token that names the stage file.
|
|
678
|
+
* @returns The sequence this process took.
|
|
679
|
+
*/
|
|
680
|
+
export function linkStage(root: string, token: string): number {
|
|
681
|
+
const sequence = Math.max(0, ...readSequences(readNames(root))) + 1
|
|
682
|
+
return tryLink(join(root, `${token}${STAGE_SUFFIX}`), join(root, renderTicketName(sequence)))
|
|
683
|
+
? sequence
|
|
684
|
+
: linkStage(root, token)
|
|
685
|
+
}
|
|
686
|
+
|
|
687
|
+
/**
|
|
688
|
+
* Decides what a process with a ticket does next.
|
|
689
|
+
*
|
|
690
|
+
* @remarks
|
|
691
|
+
* The two listings are separate, because one listing can miss both a ticket linked and a stage file
|
|
692
|
+
* removed while it runs. A stage file absent from the first listing belongs to a process whose own
|
|
693
|
+
* listing sees this ticket, or to a ticket the second listing sees.
|
|
694
|
+
*
|
|
695
|
+
* @param root - The queue root.
|
|
696
|
+
* @param sequence - This process's sequence.
|
|
697
|
+
* @param token - This process's token.
|
|
698
|
+
* @returns The holder state, the stage file to wait on, the nearest earlier ticket, or a refusal.
|
|
699
|
+
*/
|
|
700
|
+
export function decideTurn(root: string, sequence: number, token: string): Turn {
|
|
701
|
+
const stage = readNames(root).find(
|
|
702
|
+
(name) => name.endsWith(STAGE_SUFFIX) && name !== `${token}${STAGE_SUFFIX}`,
|
|
703
|
+
)
|
|
704
|
+
if (stage !== undefined) return { state: 'staged', name: stage }
|
|
705
|
+
const entries = readQueue(root)
|
|
706
|
+
const position = entries.findIndex((entry) => entry.sequence === sequence)
|
|
707
|
+
if (position === -1) {
|
|
708
|
+
return { state: 'refused', reason: `ticket ${renderTicketName(sequence)} is gone` }
|
|
709
|
+
}
|
|
710
|
+
const lower = entries[position - 1]
|
|
711
|
+
return lower === undefined ? { state: 'holder' } : { state: 'behind', entry: lower }
|
|
712
|
+
}
|
|
713
|
+
|
|
714
|
+
/**
|
|
715
|
+
* Connects to an endpoint and parks until the connection closes.
|
|
716
|
+
*
|
|
717
|
+
* @param endpoint - The endpoint.
|
|
718
|
+
* @param stage - If `true`, writes the one byte a published owner closes the connection on; if
|
|
719
|
+
* `false`, writes nothing.
|
|
720
|
+
* @param parked - Called when the connection is open and the wait starts.
|
|
721
|
+
* @returns The connect failure's code, or undefined after a connection opened and closed.
|
|
722
|
+
*/
|
|
723
|
+
export function parkOn(
|
|
724
|
+
endpoint: string,
|
|
725
|
+
stage: boolean,
|
|
726
|
+
parked: () => void,
|
|
727
|
+
): Promise<string | undefined> {
|
|
728
|
+
return new Promise((resolve) => {
|
|
729
|
+
const socket = connect(endpoint)
|
|
730
|
+
socket.once('error', (error) => resolve(readCode(error)))
|
|
731
|
+
socket.once('connect', () => {
|
|
732
|
+
socket.removeAllListeners('error')
|
|
733
|
+
socket.on('error', () => undefined)
|
|
734
|
+
socket.once('close', () => resolve(undefined))
|
|
735
|
+
socket.resume()
|
|
736
|
+
if (stage) socket.write('s')
|
|
737
|
+
parked()
|
|
738
|
+
})
|
|
739
|
+
})
|
|
740
|
+
}
|
|
741
|
+
|
|
742
|
+
/**
|
|
743
|
+
* Connects to an endpoint and leaves at once.
|
|
744
|
+
*
|
|
745
|
+
* @param endpoint - The endpoint.
|
|
746
|
+
* @returns The connect failure's code, or undefined when the connection opened.
|
|
747
|
+
*/
|
|
748
|
+
export function probeEndpoint(endpoint: string): Promise<string | undefined> {
|
|
749
|
+
return new Promise((resolve) => {
|
|
750
|
+
const socket = connect(endpoint)
|
|
751
|
+
socket.once('error', (error) => resolve(readCode(error)))
|
|
752
|
+
socket.once('connect', () => {
|
|
753
|
+
socket.destroy()
|
|
754
|
+
resolve(undefined)
|
|
755
|
+
})
|
|
756
|
+
})
|
|
757
|
+
}
|
|
758
|
+
|
|
759
|
+
/**
|
|
760
|
+
* Checks whether a connect failure means the endpoint's owner is gone.
|
|
761
|
+
*
|
|
762
|
+
* @remarks
|
|
763
|
+
* A token is unique and its endpoint listens before any file names it, so only a refused connect on
|
|
764
|
+
* that name reads as gone. A busy endpoint or any other failure proves nothing.
|
|
765
|
+
*
|
|
766
|
+
* @param code - The connect failure's code.
|
|
767
|
+
* @returns True for `ENOENT` and `ECONNREFUSED`; false otherwise.
|
|
768
|
+
*/
|
|
769
|
+
export function isGone(code: string): boolean {
|
|
770
|
+
return code === 'ENOENT' || code === 'ECONNREFUSED'
|
|
771
|
+
}
|
|
772
|
+
|
|
773
|
+
/**
|
|
774
|
+
* Names what makes a ticket unreadable to this process.
|
|
775
|
+
*
|
|
776
|
+
* @param ticket - The ticket.
|
|
777
|
+
* @returns A description of the differing protocol, host, or platform; undefined when it matches.
|
|
778
|
+
*/
|
|
779
|
+
export function describeForeign(ticket: Ticket): string | undefined {
|
|
780
|
+
if (ticket.protocol !== PROTOCOL) return `protocol ${String(ticket.protocol)}`
|
|
781
|
+
if (ticket.host !== hostname()) return `host ${quote(ticket.host)}`
|
|
782
|
+
return ticket.platform === process.platform ? undefined : `platform ${quote(ticket.platform)}`
|
|
783
|
+
}
|
|
784
|
+
|
|
785
|
+
/**
|
|
786
|
+
* Parses the snapshot's text.
|
|
787
|
+
*
|
|
788
|
+
* @param text - The snapshot's standard output.
|
|
789
|
+
* @returns One row per line that has the row's form.
|
|
790
|
+
*/
|
|
791
|
+
export function parseRows(text: string): readonly Row[] {
|
|
792
|
+
return text.split(/\r\n|\n/u).flatMap((line) => {
|
|
793
|
+
const match = ROW_PATTERN.exec(line.trim())
|
|
794
|
+
return match === null
|
|
795
|
+
? []
|
|
796
|
+
: [{ pid: Number(match[1]), parent: Number(match[2]), created: Number(match[3]) }]
|
|
797
|
+
})
|
|
798
|
+
}
|
|
799
|
+
|
|
800
|
+
/**
|
|
801
|
+
* Reads one snapshot of the host's processes.
|
|
802
|
+
*
|
|
803
|
+
* @returns The rows, or undefined when the snapshot cannot be read.
|
|
804
|
+
*/
|
|
805
|
+
export function readSnapshot(): readonly Row[] | undefined {
|
|
806
|
+
const result = spawnSync(
|
|
807
|
+
'powershell.exe',
|
|
808
|
+
['-NoProfile', '-NonInteractive', '-Command', SNAPSHOT_COMMAND],
|
|
809
|
+
{ encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024 },
|
|
810
|
+
)
|
|
811
|
+
const rows = result.status === 0 ? parseRows(result.stdout) : []
|
|
812
|
+
return rows.length === 0 ? undefined : rows
|
|
813
|
+
}
|
|
814
|
+
|
|
815
|
+
/**
|
|
816
|
+
* Selects the rows of one run's process tree from a snapshot.
|
|
817
|
+
*
|
|
818
|
+
* @remarks
|
|
819
|
+
* A seed row inside the bounds is a member. A seed row outside them reused an exited seed's id and
|
|
820
|
+
* is excluded with its children. An exited seed's child keeps the seed's id as its parent, so it
|
|
821
|
+
* counts inside the bounds, and earlier than any row that reused the id. Below that, a row counts
|
|
822
|
+
* when its creation date is no earlier than its parent's. A process whose parent exited and is no
|
|
823
|
+
* seed is outside the reading.
|
|
824
|
+
*
|
|
825
|
+
* @param rows - The snapshot.
|
|
826
|
+
* @param seeds - The launcher id and the command id.
|
|
827
|
+
* @param floor - The earliest creation date a seed's tree can carry.
|
|
828
|
+
* @param ceiling - The latest creation date a row of an exited seed can carry.
|
|
829
|
+
* @returns The members.
|
|
830
|
+
*/
|
|
831
|
+
export function selectMembers(
|
|
832
|
+
rows: readonly Row[],
|
|
833
|
+
seeds: readonly number[],
|
|
834
|
+
floor: number,
|
|
835
|
+
ceiling: number,
|
|
836
|
+
): readonly Row[] {
|
|
837
|
+
const roots = seeds.flatMap((seed) => {
|
|
838
|
+
const own = rows.find((row) => row.pid === seed)
|
|
839
|
+
return own !== undefined && own.created >= floor && own.created <= ceiling
|
|
840
|
+
? [own]
|
|
841
|
+
: rows.filter(
|
|
842
|
+
(row) =>
|
|
843
|
+
row.parent === seed &&
|
|
844
|
+
row.created >= floor &&
|
|
845
|
+
row.created <= ceiling &&
|
|
846
|
+
(own === undefined || row.created < own.created),
|
|
847
|
+
)
|
|
848
|
+
})
|
|
849
|
+
const members = new Map(roots.map((row) => [row.pid, row]))
|
|
850
|
+
for (const member of members.values()) {
|
|
851
|
+
for (const row of rows) {
|
|
852
|
+
if (row.parent === member.pid && row.created >= member.created && !members.has(row.pid)) {
|
|
853
|
+
members.set(row.pid, row)
|
|
854
|
+
}
|
|
855
|
+
}
|
|
856
|
+
}
|
|
857
|
+
return [...members.values()]
|
|
858
|
+
}
|
|
859
|
+
|
|
860
|
+
/**
|
|
861
|
+
* Reads whether a process group still has a member.
|
|
862
|
+
*
|
|
863
|
+
* @param group - The group id.
|
|
864
|
+
* @returns The group id while the host reports the group; empty when it reports none.
|
|
865
|
+
*/
|
|
866
|
+
export function readGroup(group: number): readonly number[] {
|
|
867
|
+
try {
|
|
868
|
+
process.kill(-group, 0)
|
|
869
|
+
return [group]
|
|
870
|
+
} catch (error) {
|
|
871
|
+
return readCode(error) === 'ESRCH' ? [] : [group]
|
|
872
|
+
}
|
|
873
|
+
}
|
|
874
|
+
|
|
875
|
+
/**
|
|
876
|
+
* Reads the members of one run's process tree.
|
|
877
|
+
*
|
|
878
|
+
* @remarks
|
|
879
|
+
* The reading is platform-defined: Windows has no process group a descendant inherits, so it reads
|
|
880
|
+
* parent links, and any other host reads the launcher's group.
|
|
881
|
+
*
|
|
882
|
+
* @param run - The run record.
|
|
883
|
+
* @param ceiling - The latest creation date a row of an exited seed can carry.
|
|
884
|
+
* @returns The ids to kill, or undefined when the tree cannot be read.
|
|
885
|
+
*/
|
|
886
|
+
export function readTree(run: Run, ceiling: number): readonly number[] | undefined {
|
|
887
|
+
if (run.launcher === undefined) return undefined
|
|
888
|
+
if (process.platform !== 'win32') return readGroup(run.launcher)
|
|
889
|
+
const rows = readSnapshot()
|
|
890
|
+
return rows === undefined
|
|
891
|
+
? undefined
|
|
892
|
+
: selectMembers(
|
|
893
|
+
rows,
|
|
894
|
+
run.command === undefined ? [run.launcher] : [run.launcher, run.command],
|
|
895
|
+
run.started - CLOCK_ALLOWANCE_MS,
|
|
896
|
+
ceiling,
|
|
897
|
+
).map((row) => row.pid)
|
|
898
|
+
}
|
|
899
|
+
|
|
900
|
+
/**
|
|
901
|
+
* Kills each listed member.
|
|
902
|
+
*
|
|
903
|
+
* @remarks
|
|
904
|
+
* The kill is platform-defined: Windows ends a process by id with `taskkill`, whose `/T` ends
|
|
905
|
+
* nothing under a root that exited, so each member takes its own kill. Any other host signals the
|
|
906
|
+
* group, and a pause follows, because no event reports the end of a foreign group.
|
|
907
|
+
*
|
|
908
|
+
* @param members - The ids a reading returned.
|
|
909
|
+
*/
|
|
910
|
+
export function killMembers(members: readonly number[]): void {
|
|
911
|
+
for (const member of members) {
|
|
912
|
+
if (process.platform === 'win32') {
|
|
913
|
+
spawnSync('taskkill', ['/pid', String(member), '/T', '/F'], {
|
|
914
|
+
stdio: 'ignore',
|
|
915
|
+
windowsHide: true,
|
|
916
|
+
})
|
|
917
|
+
} else {
|
|
918
|
+
try {
|
|
919
|
+
process.kill(-member, 'SIGKILL')
|
|
920
|
+
} catch {}
|
|
921
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, KILL_PAUSE_MS)
|
|
922
|
+
}
|
|
923
|
+
}
|
|
924
|
+
}
|
|
925
|
+
|
|
926
|
+
/**
|
|
927
|
+
* Reads a tree, kills what it lists, and reads again, inside a bounded budget.
|
|
928
|
+
*
|
|
929
|
+
* @param read - Takes one reading; undefined means the tree cannot be read.
|
|
930
|
+
* @param kill - Kills what a reading listed.
|
|
931
|
+
* @param budget - The kills left.
|
|
932
|
+
* @returns Gone only after a reading lists no member; otherwise the members the last reading listed.
|
|
933
|
+
*/
|
|
934
|
+
export function sweepTree(
|
|
935
|
+
read: () => readonly number[] | undefined,
|
|
936
|
+
kill: (members: readonly number[]) => void,
|
|
937
|
+
budget: number,
|
|
938
|
+
): Sweep {
|
|
939
|
+
const members = read()
|
|
940
|
+
if (members === undefined) return { gone: false, members: [] }
|
|
941
|
+
if (members.length === 0) return { gone: true, members }
|
|
942
|
+
if (budget <= 0) return { gone: false, members }
|
|
943
|
+
kill(members)
|
|
944
|
+
return sweepTree(read, kill, budget - 1)
|
|
945
|
+
}
|
|
946
|
+
|
|
947
|
+
/**
|
|
948
|
+
* Reclaims the ticket of an owner whose endpoint refused a connect.
|
|
949
|
+
*
|
|
950
|
+
* @remarks
|
|
951
|
+
* A reclaimer never kills, because the parallel skill forbids ending another session's process.
|
|
952
|
+
*
|
|
953
|
+
* @param root - The queue root.
|
|
954
|
+
* @param sequence - The dead ticket's sequence.
|
|
955
|
+
* @param ticket - The dead ticket.
|
|
956
|
+
* @returns The refusal when the owner's tree reads as present or cannot be identified; undefined
|
|
957
|
+
* after the ticket and its files are removed.
|
|
958
|
+
*/
|
|
959
|
+
export function reclaimTicket(root: string, sequence: number, ticket: Ticket): string | undefined {
|
|
960
|
+
const run = readRun(root, sequence)
|
|
961
|
+
const files = `${renderTicketName(sequence)} and ${renderRunName(sequence)} under ${root}`
|
|
962
|
+
if (run === 'unread' || (run !== 'absent' && run.launcher === undefined)) {
|
|
963
|
+
return `the owner of ${quote(ticket.label)} (pid ${String(ticket.pid)}) ended before its tree could be identified; end its tree, then delete ${files}`
|
|
964
|
+
}
|
|
965
|
+
if (run !== 'absent') {
|
|
966
|
+
const members = readTree(run, Date.now())
|
|
967
|
+
if (members === undefined || members.length > 0) {
|
|
968
|
+
return `the owner of ${quote(ticket.label)} (pid ${String(ticket.pid)}) is gone and its tree reads as ${members === undefined ? 'unread' : `present: ${members.join(', ')}`}; launcher ${String(run.launcher)}, command ${String(run.command)}, files ${files}`
|
|
969
|
+
}
|
|
970
|
+
removeFile(join(root, renderRunName(sequence)))
|
|
971
|
+
}
|
|
972
|
+
removeFile(join(root, renderTicketName(sequence)))
|
|
973
|
+
removeFile(join(root, `${ticket.token}${SOCKET_SUFFIX}`))
|
|
974
|
+
return undefined
|
|
975
|
+
}
|
|
976
|
+
|
|
977
|
+
/**
|
|
978
|
+
* Waits on one stage file and removes it when its owner is gone.
|
|
979
|
+
*
|
|
980
|
+
* @param root - The queue root.
|
|
981
|
+
* @param name - The stage file's name.
|
|
982
|
+
* @returns The refusal, or undefined when the stage ended.
|
|
983
|
+
*/
|
|
984
|
+
export async function waitOnStage(root: string, name: string): Promise<string | undefined> {
|
|
985
|
+
const token = name.slice(0, -STAGE_SUFFIX.length)
|
|
986
|
+
if (!TOKEN_PATTERN.test(token)) return `stage file ${quote(name)} under ${root} names no token`
|
|
987
|
+
const code = await parkOn(renderEndpoint(root, token), true, () =>
|
|
988
|
+
console.error('lane: waiting behind an arrival'),
|
|
989
|
+
)
|
|
990
|
+
if (code === undefined) return undefined
|
|
991
|
+
if (!isGone(code)) return `the endpoint of ${quote(name)} reported ${code}`
|
|
992
|
+
removeFile(join(root, name))
|
|
993
|
+
removeFile(join(root, `${token}${SOCKET_SUFFIX}`))
|
|
994
|
+
return undefined
|
|
995
|
+
}
|
|
996
|
+
|
|
997
|
+
/**
|
|
998
|
+
* Waits on the nearest earlier ticket and reclaims it when its owner is gone.
|
|
999
|
+
*
|
|
1000
|
+
* @param root - The queue root.
|
|
1001
|
+
* @param entry - The earlier ticket.
|
|
1002
|
+
* @param announced - The token this process last printed a waiting line for.
|
|
1003
|
+
* @returns The refusal, or undefined when the wait ended.
|
|
1004
|
+
*/
|
|
1005
|
+
export async function waitOnTicket(
|
|
1006
|
+
root: string,
|
|
1007
|
+
entry: Entry,
|
|
1008
|
+
announced: string | undefined,
|
|
1009
|
+
): Promise<string | undefined> {
|
|
1010
|
+
const name = renderTicketName(entry.sequence)
|
|
1011
|
+
const ticket = entry.ticket
|
|
1012
|
+
if (ticket === undefined) return `ticket ${name} under ${root} cannot be read`
|
|
1013
|
+
const foreign = describeForeign(ticket)
|
|
1014
|
+
if (foreign !== undefined) return `ticket ${name} under ${root} carries ${foreign}`
|
|
1015
|
+
const code = await parkOn(renderEndpoint(root, ticket.token), false, () => {
|
|
1016
|
+
if (announced !== ticket.token) console.error(`lane: waiting behind ${quote(ticket.label)}`)
|
|
1017
|
+
})
|
|
1018
|
+
if (code === undefined) return undefined
|
|
1019
|
+
return isGone(code)
|
|
1020
|
+
? reclaimTicket(root, entry.sequence, ticket)
|
|
1021
|
+
: `the endpoint of ticket ${name} reported ${code}`
|
|
1022
|
+
}
|
|
1023
|
+
|
|
1024
|
+
/**
|
|
1025
|
+
* Waits for this process's turn, parked on events with no timer.
|
|
1026
|
+
*
|
|
1027
|
+
* @param root - The queue root.
|
|
1028
|
+
* @param sequence - This process's sequence.
|
|
1029
|
+
* @param token - This process's token.
|
|
1030
|
+
* @param announced - The token this process last printed a waiting line for.
|
|
1031
|
+
* @returns The refusal, or undefined when this process holds the lane.
|
|
1032
|
+
*/
|
|
1033
|
+
export async function waitForTurn(
|
|
1034
|
+
root: string,
|
|
1035
|
+
sequence: number,
|
|
1036
|
+
token: string,
|
|
1037
|
+
announced?: string,
|
|
1038
|
+
): Promise<string | undefined> {
|
|
1039
|
+
const turn = decideTurn(root, sequence, token)
|
|
1040
|
+
if (turn.state === 'holder') return undefined
|
|
1041
|
+
if (turn.state === 'refused') return turn.reason
|
|
1042
|
+
const refusal =
|
|
1043
|
+
turn.state === 'staged'
|
|
1044
|
+
? await waitOnStage(root, turn.name)
|
|
1045
|
+
: await waitOnTicket(root, turn.entry, announced)
|
|
1046
|
+
if (refusal !== undefined) return refusal
|
|
1047
|
+
return waitForTurn(
|
|
1048
|
+
root,
|
|
1049
|
+
sequence,
|
|
1050
|
+
token,
|
|
1051
|
+
turn.state === 'behind' ? turn.entry.ticket?.token : announced,
|
|
1052
|
+
)
|
|
1053
|
+
}
|
|
1054
|
+
|
|
1055
|
+
/**
|
|
1056
|
+
* Reads the command id from a launcher line.
|
|
1057
|
+
*
|
|
1058
|
+
* @param line - One line of the launcher's stdout.
|
|
1059
|
+
* @returns The pid of the spawn line; undefined for any other line.
|
|
1060
|
+
*/
|
|
1061
|
+
export function readCommandId(line: string): number | undefined {
|
|
1062
|
+
const parsed = parseText(line)
|
|
1063
|
+
return typeof parsed === 'object' &&
|
|
1064
|
+
parsed !== null &&
|
|
1065
|
+
'pid' in parsed &&
|
|
1066
|
+
typeof parsed.pid === 'number' &&
|
|
1067
|
+
!('exit' in parsed)
|
|
1068
|
+
? parsed.pid
|
|
1069
|
+
: undefined
|
|
1070
|
+
}
|
|
1071
|
+
|
|
1072
|
+
/**
|
|
1073
|
+
* Registers a handler on every stop signal, on a host that delivers them.
|
|
1074
|
+
*
|
|
1075
|
+
* @remarks
|
|
1076
|
+
* Windows runs no signal handler for a forced kill, so an ended lane process there is the reclaim
|
|
1077
|
+
* case.
|
|
1078
|
+
*
|
|
1079
|
+
* @param handler - The handler.
|
|
1080
|
+
* @returns The call that removes the handler.
|
|
1081
|
+
*/
|
|
1082
|
+
export function watchSignals(handler: () => void): () => void {
|
|
1083
|
+
if (process.platform === 'win32') return () => undefined
|
|
1084
|
+
for (const signal of STOP_SIGNALS) process.on(signal, handler)
|
|
1085
|
+
return () => {
|
|
1086
|
+
for (const signal of STOP_SIGNALS) process.removeListener(signal, handler)
|
|
1087
|
+
}
|
|
1088
|
+
}
|
|
1089
|
+
|
|
1090
|
+
/**
|
|
1091
|
+
* Starts the sibling launcher.
|
|
1092
|
+
*
|
|
1093
|
+
* @remarks
|
|
1094
|
+
* A host other than Windows starts it as a group leader, so the launcher's id is the group a
|
|
1095
|
+
* handover reads.
|
|
1096
|
+
*
|
|
1097
|
+
* @param launcher - The launcher's path.
|
|
1098
|
+
* @param options - The run.
|
|
1099
|
+
* @returns The started launcher.
|
|
1100
|
+
*/
|
|
1101
|
+
export function startLauncher(launcher: string, options: LaneOptions): ChildProcess {
|
|
1102
|
+
return spawn(
|
|
1103
|
+
process.execPath,
|
|
1104
|
+
[
|
|
1105
|
+
launcher,
|
|
1106
|
+
'--journal',
|
|
1107
|
+
options.journal,
|
|
1108
|
+
'--errors',
|
|
1109
|
+
options.errors,
|
|
1110
|
+
'--cap',
|
|
1111
|
+
String(options.cap),
|
|
1112
|
+
'--',
|
|
1113
|
+
...options.command,
|
|
1114
|
+
],
|
|
1115
|
+
{
|
|
1116
|
+
stdio: ['ignore', 'pipe', 'inherit'],
|
|
1117
|
+
windowsHide: true,
|
|
1118
|
+
detached: process.platform !== 'win32',
|
|
1119
|
+
},
|
|
1120
|
+
)
|
|
1121
|
+
}
|
|
1122
|
+
|
|
1123
|
+
/**
|
|
1124
|
+
* Waits for a started launcher to close.
|
|
1125
|
+
*
|
|
1126
|
+
* @param child - The started launcher.
|
|
1127
|
+
* @returns Its exit code, or undefined when a signal ended it or it could not start.
|
|
1128
|
+
*/
|
|
1129
|
+
export function waitForClose(child: ChildProcess): Promise<number | undefined> {
|
|
1130
|
+
return new Promise((resolve) => {
|
|
1131
|
+
child.once('error', () => resolve(undefined))
|
|
1132
|
+
child.once('close', (code) => resolve(code ?? undefined))
|
|
1133
|
+
})
|
|
1134
|
+
}
|
|
1135
|
+
|
|
1136
|
+
/**
|
|
1137
|
+
* Writes a run record, leaving an unwritten id to the handover reading.
|
|
1138
|
+
*
|
|
1139
|
+
* @param root - The queue root.
|
|
1140
|
+
* @param sequence - The ticket's sequence.
|
|
1141
|
+
* @param run - The record.
|
|
1142
|
+
* @returns True when the record was written; false otherwise.
|
|
1143
|
+
*/
|
|
1144
|
+
export function tryWriteRun(root: string, sequence: number, run: Run): boolean {
|
|
1145
|
+
try {
|
|
1146
|
+
writeRun(root, sequence, run)
|
|
1147
|
+
return true
|
|
1148
|
+
} catch {
|
|
1149
|
+
return false
|
|
1150
|
+
}
|
|
1151
|
+
}
|
|
1152
|
+
|
|
1153
|
+
/**
|
|
1154
|
+
* Removes a holder's run record and ticket.
|
|
1155
|
+
*
|
|
1156
|
+
* @param root - The queue root.
|
|
1157
|
+
* @param sequence - The ticket's sequence.
|
|
1158
|
+
* @returns The host's refusal when the removal budget ended; undefined after both are gone.
|
|
1159
|
+
*/
|
|
1160
|
+
export function releaseTicket(root: string, sequence: number): string | undefined {
|
|
1161
|
+
try {
|
|
1162
|
+
removeFile(join(root, renderRunName(sequence)))
|
|
1163
|
+
removeFile(join(root, renderTicketName(sequence)))
|
|
1164
|
+
return undefined
|
|
1165
|
+
} catch (error) {
|
|
1166
|
+
return readCode(error)
|
|
1167
|
+
}
|
|
1168
|
+
}
|
|
1169
|
+
|
|
1170
|
+
/**
|
|
1171
|
+
* Runs the command as the holder, reads the tree at handover, and releases.
|
|
1172
|
+
*
|
|
1173
|
+
* @param options - The run.
|
|
1174
|
+
* @param launcher - The launcher's path.
|
|
1175
|
+
* @param sequence - This process's sequence.
|
|
1176
|
+
* @returns The launcher's code; 1 when a signal ended it; 70 when the tree still reads as present or
|
|
1177
|
+
* the ticket could not be removed; 75 when the launcher could not start.
|
|
1178
|
+
*/
|
|
1179
|
+
export async function runHolder(
|
|
1180
|
+
options: LaneOptions,
|
|
1181
|
+
launcher: string,
|
|
1182
|
+
sequence: number,
|
|
1183
|
+
): Promise<number> {
|
|
1184
|
+
const { root } = options
|
|
1185
|
+
const started = Date.now()
|
|
1186
|
+
writeRun(root, sequence, { started, launcher: undefined, command: undefined })
|
|
1187
|
+
const child = startLauncher(launcher, options)
|
|
1188
|
+
const id = child.pid
|
|
1189
|
+
if (id === undefined) {
|
|
1190
|
+
releaseTicket(root, sequence)
|
|
1191
|
+
console.error(`lane: ${quote(launcher)} could not start`)
|
|
1192
|
+
return 75
|
|
1193
|
+
}
|
|
1194
|
+
tryWriteRun(root, sequence, { started, launcher: id, command: undefined })
|
|
1195
|
+
const unwatch = watchSignals(() => killMembers([id]))
|
|
1196
|
+
const closed = waitForClose(child)
|
|
1197
|
+
if (child.stdout !== null) {
|
|
1198
|
+
const lines = createInterface({ input: child.stdout, crlfDelay: Infinity })
|
|
1199
|
+
lines.on('error', () => undefined)
|
|
1200
|
+
lines.on('line', (line) => {
|
|
1201
|
+
console.log(line)
|
|
1202
|
+
const command = readCommandId(line)
|
|
1203
|
+
if (command !== undefined) tryWriteRun(root, sequence, { started, launcher: id, command })
|
|
1204
|
+
})
|
|
1205
|
+
}
|
|
1206
|
+
const code = await closed
|
|
1207
|
+
unwatch()
|
|
1208
|
+
const ended = Date.now()
|
|
1209
|
+
const run = readRun(root, sequence)
|
|
1210
|
+
const sweep =
|
|
1211
|
+
run === 'absent' || run === 'unread'
|
|
1212
|
+
? { gone: false, members: [] }
|
|
1213
|
+
: sweepTree(() => readTree(run, ended), killMembers, KILL_BUDGET)
|
|
1214
|
+
if (!sweep.gone) {
|
|
1215
|
+
console.error(
|
|
1216
|
+
`lane: the tree of ${quote(options.label)} still reads as ${sweep.members.length === 0 ? 'unread' : `present: ${sweep.members.join(', ')}`}; the lane stays held by ${renderTicketName(sequence)} and ${renderRunName(sequence)} under ${root}`,
|
|
1217
|
+
)
|
|
1218
|
+
return 70
|
|
1219
|
+
}
|
|
1220
|
+
const refusal = releaseTicket(root, sequence)
|
|
1221
|
+
if (refusal !== undefined) {
|
|
1222
|
+
console.error(`lane: removing ${renderTicketName(sequence)} reported ${refusal}`)
|
|
1223
|
+
return 70
|
|
1224
|
+
}
|
|
1225
|
+
return code ?? 1
|
|
1226
|
+
}
|
|
1227
|
+
|
|
1228
|
+
/**
|
|
1229
|
+
* Takes a ticket, waits for this process's turn, and runs the command.
|
|
1230
|
+
*
|
|
1231
|
+
* @param options - The run.
|
|
1232
|
+
* @param launcher - The launcher's path.
|
|
1233
|
+
* @param tokenId - This process's token.
|
|
1234
|
+
* @param token - This process's listening endpoint.
|
|
1235
|
+
* @returns The exit code.
|
|
1236
|
+
*/
|
|
1237
|
+
export async function enterLane(
|
|
1238
|
+
options: LaneOptions,
|
|
1239
|
+
launcher: string,
|
|
1240
|
+
tokenId: string,
|
|
1241
|
+
token: Token,
|
|
1242
|
+
): Promise<number> {
|
|
1243
|
+
const { root } = options
|
|
1244
|
+
try {
|
|
1245
|
+
mkdirSync(root, { recursive: true })
|
|
1246
|
+
await token.listen(renderEndpoint(root, tokenId))
|
|
1247
|
+
writeStage(root, buildTicket(tokenId, options.label))
|
|
1248
|
+
const sequence = linkStage(root, tokenId)
|
|
1249
|
+
removeFile(join(root, `${tokenId}${STAGE_SUFFIX}`))
|
|
1250
|
+
token.publish()
|
|
1251
|
+
const unwatch = watchSignals(() => {
|
|
1252
|
+
removeFile(join(root, renderTicketName(sequence)))
|
|
1253
|
+
removeFile(renderEndpoint(root, tokenId))
|
|
1254
|
+
process.exit(75)
|
|
1255
|
+
})
|
|
1256
|
+
const refusal = await waitForTurn(root, sequence, tokenId)
|
|
1257
|
+
unwatch()
|
|
1258
|
+
if (refusal === undefined) return await runHolder(options, launcher, sequence)
|
|
1259
|
+
removeFile(join(root, renderTicketName(sequence)))
|
|
1260
|
+
console.error(`lane: ${refusal}`)
|
|
1261
|
+
return 75
|
|
1262
|
+
} catch (error) {
|
|
1263
|
+
console.error(`lane: the queue under ${root} refused the run: ${String(error)}`)
|
|
1264
|
+
return 75
|
|
1265
|
+
}
|
|
1266
|
+
}
|
|
1267
|
+
|
|
1268
|
+
/**
|
|
1269
|
+
* Runs one validated command on the lane.
|
|
1270
|
+
*
|
|
1271
|
+
* @param options - The run.
|
|
1272
|
+
* @returns The exit code.
|
|
1273
|
+
*/
|
|
1274
|
+
export async function runLane(options: LaneOptions): Promise<number> {
|
|
1275
|
+
const launcher = resolveLauncher()
|
|
1276
|
+
if (!existsSync(launcher)) {
|
|
1277
|
+
console.error(`lane: the launcher ${quote(launcher)} does not exist`)
|
|
1278
|
+
return 75
|
|
1279
|
+
}
|
|
1280
|
+
const token = new Token()
|
|
1281
|
+
const code = await enterLane(options, launcher, randomUUID(), token)
|
|
1282
|
+
await token.destroy()
|
|
1283
|
+
return code
|
|
1284
|
+
}
|
|
1285
|
+
|
|
1286
|
+
/**
|
|
1287
|
+
* Reads one ticket's state for `--status`, connecting to its endpoint and writing nothing.
|
|
1288
|
+
*
|
|
1289
|
+
* @param root - The queue root.
|
|
1290
|
+
* @param entry - The ticket.
|
|
1291
|
+
* @returns The ticket's row.
|
|
1292
|
+
*/
|
|
1293
|
+
export async function readStatusRow(root: string, entry: Entry): Promise<StatusRow> {
|
|
1294
|
+
const ticket = entry.ticket
|
|
1295
|
+
const fields = { sequence: entry.sequence, label: ticket?.label, pid: ticket?.pid }
|
|
1296
|
+
if (ticket === undefined || describeForeign(ticket) !== undefined) {
|
|
1297
|
+
return { ...fields, state: 'unread' }
|
|
1298
|
+
}
|
|
1299
|
+
const code = await probeEndpoint(renderEndpoint(root, ticket.token))
|
|
1300
|
+
if (code === undefined) return { ...fields, state: 'live' }
|
|
1301
|
+
return { ...fields, state: isGone(code) ? 'dead' : 'unread' }
|
|
1302
|
+
}
|
|
1303
|
+
|
|
1304
|
+
/**
|
|
1305
|
+
* Reads the queue for `--status`.
|
|
1306
|
+
*
|
|
1307
|
+
* @param root - The queue root.
|
|
1308
|
+
* @returns Every ticket in arrival order, and the earliest live ticket with a run record.
|
|
1309
|
+
*/
|
|
1310
|
+
export async function readStatus(root: string): Promise<Status> {
|
|
1311
|
+
const tickets = await Promise.all(readQueue(root).map((entry) => readStatusRow(root, entry)))
|
|
1312
|
+
return {
|
|
1313
|
+
tickets,
|
|
1314
|
+
holder: tickets.find(
|
|
1315
|
+
(row) => row.state === 'live' && existsSync(join(root, renderRunName(row.sequence))),
|
|
1316
|
+
),
|
|
1317
|
+
}
|
|
1318
|
+
}
|
|
1319
|
+
|
|
1320
|
+
/**
|
|
1321
|
+
* Renders the queue as text.
|
|
1322
|
+
*
|
|
1323
|
+
* @param status - What `--status` read.
|
|
1324
|
+
* @returns One line for the holder and one per ticket, in arrival order.
|
|
1325
|
+
*/
|
|
1326
|
+
export function renderStatus(status: Status): string {
|
|
1327
|
+
return [
|
|
1328
|
+
`holder: ${status.holder === undefined ? 'none' : quote(status.holder.label ?? 'unread')}`,
|
|
1329
|
+
...status.tickets.map(
|
|
1330
|
+
(row) =>
|
|
1331
|
+
`${renderTicketName(row.sequence)} ${row.state} ${quote(row.label ?? 'unread')} pid ${String(row.pid)}`,
|
|
1332
|
+
),
|
|
1333
|
+
].join('\n')
|
|
1334
|
+
}
|
|
1335
|
+
|
|
1336
|
+
/**
|
|
1337
|
+
* Prints the queue, writing nothing under the root.
|
|
1338
|
+
*
|
|
1339
|
+
* @param root - The queue root.
|
|
1340
|
+
* @param json - If `true`, prints JSON; if `false`, prints text.
|
|
1341
|
+
* @returns 0 on a read; 75 when the root cannot be listed.
|
|
1342
|
+
*/
|
|
1343
|
+
export async function runStatus(root: string, json: boolean): Promise<number> {
|
|
1344
|
+
try {
|
|
1345
|
+
const status = await readStatus(root)
|
|
1346
|
+
console.log(json ? JSON.stringify(status) : renderStatus(status))
|
|
1347
|
+
return 0
|
|
1348
|
+
} catch (error) {
|
|
1349
|
+
console.error(`lane: the queue under ${root} cannot be read: ${readCode(error)}`)
|
|
1350
|
+
return 75
|
|
1351
|
+
}
|
|
1352
|
+
}
|
|
1353
|
+
|
|
1354
|
+
/**
|
|
1355
|
+
* Validates a run's arguments.
|
|
1356
|
+
*
|
|
1357
|
+
* @param own - The arguments before the bare `--`.
|
|
1358
|
+
* @param command - The arguments after the bare `--`.
|
|
1359
|
+
* @returns The run, or undefined when a flag or the command is missing or out of range.
|
|
1360
|
+
*/
|
|
1361
|
+
export function readLaneOptions(
|
|
1362
|
+
own: readonly string[],
|
|
1363
|
+
command: readonly string[],
|
|
1364
|
+
): LaneOptions | undefined {
|
|
1365
|
+
const label = readOption(own, '--label')
|
|
1366
|
+
const journal = readOption(own, '--journal')
|
|
1367
|
+
const errors = readOption(own, '--errors')
|
|
1368
|
+
const cap = Number(readOption(own, '--cap') ?? Number.NaN)
|
|
1369
|
+
if (
|
|
1370
|
+
label === undefined ||
|
|
1371
|
+
label === '' ||
|
|
1372
|
+
journal === undefined ||
|
|
1373
|
+
errors === undefined ||
|
|
1374
|
+
journal === errors ||
|
|
1375
|
+
!Number.isFinite(cap) ||
|
|
1376
|
+
cap <= 0 ||
|
|
1377
|
+
cap > MAX_CAP_SECONDS ||
|
|
1378
|
+
command[0] === undefined ||
|
|
1379
|
+
command[0] === ''
|
|
1380
|
+
) {
|
|
1381
|
+
return undefined
|
|
1382
|
+
}
|
|
1383
|
+
return { root: resolveRoot(readOption(own, '--root')), label, journal, errors, cap, command }
|
|
1384
|
+
}
|
|
1385
|
+
|
|
1386
|
+
/**
|
|
1387
|
+
* Runs the script on its arguments.
|
|
1388
|
+
*
|
|
1389
|
+
* @remarks
|
|
1390
|
+
* Every usage fault returns before a ticket exists, so none surfaces after a wait.
|
|
1391
|
+
*
|
|
1392
|
+
* @param argv - The arguments after the script path.
|
|
1393
|
+
* @returns The exit code the opening comment names.
|
|
1394
|
+
*/
|
|
1395
|
+
export async function main(argv: readonly string[]): Promise<number> {
|
|
1396
|
+
const end = argv.indexOf('--')
|
|
1397
|
+
const own = end === -1 ? argv : argv.slice(0, end)
|
|
1398
|
+
const command = end === -1 ? [] : argv.slice(end + 1)
|
|
1399
|
+
const unknown = readUnknownFlags(argv, FLAGS)
|
|
1400
|
+
if (unknown.length > 0) {
|
|
1401
|
+
console.error(`lane: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
|
|
1402
|
+
return 64
|
|
1403
|
+
}
|
|
1404
|
+
const missing = readMissingFlags(own, VALUE_FLAGS)
|
|
1405
|
+
if (missing.length > 0) {
|
|
1406
|
+
console.error(`lane: ${missing.join(', ')} given with no value; ${USAGE}`)
|
|
1407
|
+
return 64
|
|
1408
|
+
}
|
|
1409
|
+
if (readPositionals(own, VALUE_FLAGS).length > 0) {
|
|
1410
|
+
console.error(USAGE)
|
|
1411
|
+
return 64
|
|
1412
|
+
}
|
|
1413
|
+
const status = own.includes('--status')
|
|
1414
|
+
if (status) {
|
|
1415
|
+
if (end !== -1 || RUN_FLAGS.some((flag) => own.includes(flag))) {
|
|
1416
|
+
console.error(`lane: --status and a run are two modes; ${USAGE}`)
|
|
1417
|
+
return 64
|
|
1418
|
+
}
|
|
1419
|
+
return runStatus(resolveRoot(readOption(own, '--root')), own.includes('--json'))
|
|
1420
|
+
}
|
|
1421
|
+
const options = own.includes('--json') ? undefined : readLaneOptions(own, command)
|
|
1422
|
+
if (options === undefined) {
|
|
1423
|
+
console.error(USAGE)
|
|
1424
|
+
return 64
|
|
1425
|
+
}
|
|
1426
|
+
return runLane(options)
|
|
1427
|
+
}
|
|
1428
|
+
|
|
1429
|
+
if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
|
|
1430
|
+
main(process.argv.slice(2)).then((code) => {
|
|
1431
|
+
process.exitCode = code
|
|
1432
|
+
})
|
|
1433
|
+
}
|