@aisac/cli 0.4.0-beta.21 → 0.4.0-beta.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -1
- package/dist/assets/codex-context-compaction.mjs +603 -9
- package/dist/assets/jev-paid-pilot-terminal.mjs +6 -1
- package/dist/claude-observation.mjs +1 -1
- package/dist/cli.mjs +61 -4
- package/dist/engineering-pack.mjs +21 -4
- package/dist/extensions-catalog.mjs +18 -1
- package/dist/guardrails/guards.mjs +1144 -36
- package/dist/launch.mjs +132 -20
- package/dist/manager/bus.mjs +1921 -0
- package/dist/manager/delegation.mjs +354 -0
- package/dist/manager/hooks.mjs +918 -0
- package/dist/manager/launch-role.mjs +476 -0
- package/dist/manager/mcp-stdio.mjs +463 -0
- package/dist/manager/messages.mjs +791 -0
- package/dist/manager/reserve.mjs +2166 -0
- package/dist/manager/room.mjs +106 -0
- package/dist/manager/server.mjs +1792 -0
- package/dist/manager/status.mjs +118 -0
- package/dist/manager/watch.mjs +87 -0
- package/dist/manager/worker.mjs +2793 -0
- package/dist/manager/workers-cli.mjs +1403 -0
- package/dist/package.json +1 -1
- package/dist/release-manifest.json +7 -7
- package/package.json +1 -1
|
@@ -0,0 +1,1921 @@
|
|
|
1
|
+
// The local file bus of the manager feature (spec aisac-engineering-manager,
|
|
2
|
+
// D3, D4, FR2, FR11; ADR-0058): rooms, the session registry, private files
|
|
3
|
+
// written by rename, the content-free audit and the sweeps. Nothing here
|
|
4
|
+
// listens on anything, and nothing here reads or writes message text: that is
|
|
5
|
+
// `messages.mjs`. Node built-ins only, because the worker role loads this
|
|
6
|
+
// module inside the Codex adapter process.
|
|
7
|
+
//
|
|
8
|
+
// Every file another process may have written is read with `readBoundedFile`:
|
|
9
|
+
// opened without following a symlink and without blocking, checked on the
|
|
10
|
+
// open handle (a regular file of this user, within its size limit) and read
|
|
11
|
+
// at most to that limit. Every sweep checks first that the room's directories
|
|
12
|
+
// are real directories of this user, so that it never deletes through a
|
|
13
|
+
// symlink, and runs its destructive steps under the room lock.
|
|
14
|
+
|
|
15
|
+
import { createHash, randomBytes } from 'node:crypto';
|
|
16
|
+
import { constants, readFileSync } from 'node:fs';
|
|
17
|
+
import {
|
|
18
|
+
chmod,
|
|
19
|
+
link,
|
|
20
|
+
lstat,
|
|
21
|
+
mkdir,
|
|
22
|
+
open,
|
|
23
|
+
readdir,
|
|
24
|
+
rename,
|
|
25
|
+
rm,
|
|
26
|
+
unlink,
|
|
27
|
+
writeFile,
|
|
28
|
+
} from 'node:fs/promises';
|
|
29
|
+
import { dirname, join, resolve } from 'node:path';
|
|
30
|
+
|
|
31
|
+
export const BUS_SCHEMA_VERSION = 1;
|
|
32
|
+
export const BUS_DIRECTORY = 'bus';
|
|
33
|
+
export const MANAGER_NAME = 'manager';
|
|
34
|
+
/** The manager's inbox and pending records belong to the room, not to a session (FR2). */
|
|
35
|
+
export const MANAGER_RECIPIENT = 'manager';
|
|
36
|
+
export const NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/u;
|
|
37
|
+
export const SESSION_ID_PATTERN = /^[0-9a-f]{32}$/u;
|
|
38
|
+
export const ROOM_ID_PATTERN = /^[0-9a-f]{32}$/u;
|
|
39
|
+
export const CODE_PATTERN = /^[a-z0-9_]{1,64}$/u;
|
|
40
|
+
/** An audit reason: a code of the client, or an error kind of the app-server (`contextWindowExceeded`). */
|
|
41
|
+
export const AUDIT_REASON_PATTERN = /^[A-Za-z0-9_]{1,64}$/u;
|
|
42
|
+
/** A message id: its creation time in milliseconds (13 digits) and 16 random hexadecimal characters (FR3). */
|
|
43
|
+
export const MESSAGE_ID_PATTERN = /^\d{13}-[0-9a-f]{16}$/u;
|
|
44
|
+
/** A value the app-server reports (sandbox, approval policy), as the worker's adapter keeps it. */
|
|
45
|
+
export const REPORTED_VALUE_PATTERN = /^[A-Za-z0-9_.:-]{1,64}$/u;
|
|
46
|
+
/** A host version: `0.166.0`, `2.1.323`, `1.0.0-beta.1+build`. */
|
|
47
|
+
export const VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z.+_-]{0,63}$/u;
|
|
48
|
+
/** What identifies one process over its life: the boot id and the start time in clock ticks (Linux). */
|
|
49
|
+
export const START_TOKEN_PATTERN = /^(?:[0-9a-f-]{36}:)?\d{1,20}$/u;
|
|
50
|
+
|
|
51
|
+
/** Set by the launcher for the Codex chain: the worker role, as JSON. */
|
|
52
|
+
export const WORKER_ROLE_ENV = 'AISAC_WORKER_ROLE';
|
|
53
|
+
/** Set by the launcher for the Codex chain: absolute path of `manager/worker.mjs`. */
|
|
54
|
+
export const WORKER_MODULE_ENV = 'AISAC_WORKER_MODULE';
|
|
55
|
+
/** Set by the launcher for the manager's Claude Code process and its MCP entry: the manager role, as JSON. */
|
|
56
|
+
export const MANAGER_ROLE_ENV = 'AISAC_MANAGER_ROLE';
|
|
57
|
+
|
|
58
|
+
const MINUTE_MS = 60_000;
|
|
59
|
+
const HOUR_MS = 60 * MINUTE_MS;
|
|
60
|
+
const DAY_MS = 24 * HOUR_MS;
|
|
61
|
+
const KIBIBYTE = 1024;
|
|
62
|
+
const MEBIBYTE = 1024 * KIBIBYTE;
|
|
63
|
+
|
|
64
|
+
/** Every limit of the spec in one place (FR2, FR3, FR6, FR9, FR13). */
|
|
65
|
+
export const LIMITS = Object.freeze({
|
|
66
|
+
workersPerRoom: 16,
|
|
67
|
+
queuedPerWorker: 8,
|
|
68
|
+
pendingPerRoom: 32,
|
|
69
|
+
sendsPerWindow: 30,
|
|
70
|
+
sendWindowMs: 10 * MINUTE_MS,
|
|
71
|
+
requestTextMax: 16_000,
|
|
72
|
+
replyTextMax: 64_000,
|
|
73
|
+
fileBytesMax: 256 * KIBIBYTE,
|
|
74
|
+
ttlDefaultMs: 30 * MINUTE_MS,
|
|
75
|
+
ttlMinMs: MINUTE_MS,
|
|
76
|
+
ttlMaxMs: DAY_MS,
|
|
77
|
+
retentionMs: DAY_MS,
|
|
78
|
+
/** A pending record outlives its request's expiry by this much, so a late reply still finds it. */
|
|
79
|
+
pendingGraceMs: HOUR_MS,
|
|
80
|
+
idempotencyWindowMs: 10 * MINUTE_MS,
|
|
81
|
+
idempotencyKeyMax: 64,
|
|
82
|
+
auditRotateBytes: MEBIBYTE,
|
|
83
|
+
readPageChars: 8_000,
|
|
84
|
+
waitIdsMax: 16,
|
|
85
|
+
waitTimeoutMaxSeconds: 120,
|
|
86
|
+
waitTimeoutDefaultSeconds: 30,
|
|
87
|
+
wakeTimeoutDefaultSeconds: 30 * 60,
|
|
88
|
+
wakeTimeoutMaxSeconds: 6 * 60 * 60,
|
|
89
|
+
holdMs: 10 * MINUTE_MS,
|
|
90
|
+
delegatedPerHour: 30,
|
|
91
|
+
delegationMinMs: 10 * MINUTE_MS,
|
|
92
|
+
delegationMaxMs: DAY_MS,
|
|
93
|
+
delegationDefaultMs: 8 * HOUR_MS,
|
|
94
|
+
decisionReasonMax: 500,
|
|
95
|
+
commandTextMax: 4_000,
|
|
96
|
+
decisionsRotateBytes: 4 * MEBIBYTE,
|
|
97
|
+
decisionsRetentionMs: 30 * DAY_MS,
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
const PRIVATE_DIRECTORY_MODE = 0o700;
|
|
101
|
+
const PRIVATE_FILE_MODE = 0o600;
|
|
102
|
+
const NOT_PRIVATE_MASK = 0o077;
|
|
103
|
+
const SESSION_FILE_BYTES_MAX = 16 * KIBIBYTE;
|
|
104
|
+
const ROOM_FILE_BYTES_MAX = 4 * KIBIBYTE;
|
|
105
|
+
export const PENDING_FILE_BYTES_MAX = 2 * KIBIBYTE;
|
|
106
|
+
const LOCK_FILE_BYTES_MAX = 256;
|
|
107
|
+
const PATH_LENGTH_MAX = 4096;
|
|
108
|
+
const LABEL_MAX = 128;
|
|
109
|
+
const HELD_APPROVALS_MAX = 32;
|
|
110
|
+
const LOCK_STALE_MS = 10_000;
|
|
111
|
+
const LOCK_WAIT_MS = 3_000;
|
|
112
|
+
const LOCK_RETRY_MS = 25;
|
|
113
|
+
/** A hard stop for the lock loop, so that a clock that never moves cannot spin it forever. */
|
|
114
|
+
const LOCK_ATTEMPTS_MAX = 4 * Math.ceil(LOCK_WAIT_MS / LOCK_RETRY_MS);
|
|
115
|
+
const LOCK_NONCE_BYTES = 16;
|
|
116
|
+
const RANDOM_NAME_BYTES = 8;
|
|
117
|
+
const REGISTER_ATTEMPTS_MAX = 3;
|
|
118
|
+
const TEMPORARY_FILE_MAX_AGE_MS = HOUR_MS;
|
|
119
|
+
const JSON_SUFFIX = '.json';
|
|
120
|
+
const JSON_FILE = /\.json$/u;
|
|
121
|
+
const MESSAGE_TIME = /^(\d{13})-/u;
|
|
122
|
+
const REMOVED_ROOM_PATTERN = /^\.removed-[0-9a-f]{32}$/u;
|
|
123
|
+
const LOCK_LINE = /^(\d{1,10}) (\d{1,16}) ([0-9a-f]{32}) (-|(?:[0-9a-f-]{36}:)?\d{1,20})\n$/u;
|
|
124
|
+
const NO_TOKEN = '-';
|
|
125
|
+
const BREAKER_SUFFIX = '.break';
|
|
126
|
+
const PROC_STAT_START_TIME_INDEX = 19;
|
|
127
|
+
const BOOT_ID_FILE = '/proc/sys/kernel/random/boot_id';
|
|
128
|
+
const BOOT_ID_PATTERN = /^[0-9a-f-]{36}$/u;
|
|
129
|
+
const DIGITS = /^\d{1,20}$/u;
|
|
130
|
+
const REPLACEMENT_CHARACTER = '�';
|
|
131
|
+
const C0_LAST = 0x1f;
|
|
132
|
+
const DELETE = 0x7f;
|
|
133
|
+
const C1_LAST = 0x9f;
|
|
134
|
+
const HIGH_SURROGATE_FIRST = 0xd800;
|
|
135
|
+
const HIGH_SURROGATE_LAST = 0xdbff;
|
|
136
|
+
/** Invisible format characters, bidirectional overrides and lone surrogates. */
|
|
137
|
+
const INVISIBLE_RANGES = Object.freeze([
|
|
138
|
+
[0x00ad, 0x00ad],
|
|
139
|
+
[0x061c, 0x061c],
|
|
140
|
+
[0x180e, 0x180e],
|
|
141
|
+
[0x200b, 0x200f],
|
|
142
|
+
[0x2028, 0x202e],
|
|
143
|
+
[0x2060, 0x206f],
|
|
144
|
+
[0xd800, 0xdfff],
|
|
145
|
+
[0xfeff, 0xfeff],
|
|
146
|
+
[0xfff9, 0xfffb],
|
|
147
|
+
]);
|
|
148
|
+
const READ_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
|
|
149
|
+
const APPEND_FLAGS =
|
|
150
|
+
constants.O_WRONLY |
|
|
151
|
+
constants.O_APPEND |
|
|
152
|
+
constants.O_CREAT |
|
|
153
|
+
(constants.O_NOFOLLOW ?? 0) |
|
|
154
|
+
(constants.O_NONBLOCK ?? 0);
|
|
155
|
+
/** What `open` reports for an entry that is not a regular file it may open: a symlink (`O_NOFOLLOW`), a socket. */
|
|
156
|
+
const NOT_A_FILE_ERRORS = ['ELOOP', 'EMLINK', 'ENXIO', 'EOPNOTSUPP', 'EISDIR'];
|
|
157
|
+
const MISSING_ERRORS = ['ENOENT', 'ENOTDIR'];
|
|
158
|
+
|
|
159
|
+
/** @typedef {'pt-BR' | 'en'} BusLocale */
|
|
160
|
+
/** @typedef {'manager' | 'worker'} Role */
|
|
161
|
+
/** @typedef {'claude' | 'codex'} Host */
|
|
162
|
+
/** @typedef {'starting' | 'idle' | 'busy' | 'waiting_approval'} SessionState */
|
|
163
|
+
/** @typedef {'command' | 'fileChange' | 'permissions'} ApprovalKind */
|
|
164
|
+
/**
|
|
165
|
+
* @typedef {object} SessionApproval
|
|
166
|
+
* @property {ApprovalKind} kind
|
|
167
|
+
* @property {'user' | 'manager'} decider who answers it: the terminal's user, or the manager under a delegation (FR13)
|
|
168
|
+
* @property {number} since
|
|
169
|
+
*/
|
|
170
|
+
/**
|
|
171
|
+
* One live role session (FR2). The launcher writes it at registration; from
|
|
172
|
+
* then on only the session's own role process replaces it.
|
|
173
|
+
* @typedef {object} SessionRecord
|
|
174
|
+
* @property {1} schemaVersion
|
|
175
|
+
* @property {string} sessionId 128 random bits, hexadecimal
|
|
176
|
+
* @property {string} name
|
|
177
|
+
* @property {Role} role
|
|
178
|
+
* @property {Host} host
|
|
179
|
+
* @property {string | null} hostVersion
|
|
180
|
+
* @property {number} launcherPid
|
|
181
|
+
* @property {number | null} childPid the role process (the adapter, or the manager's MCP server), written by itself
|
|
182
|
+
* @property {number} startedAt
|
|
183
|
+
* @property {string} cwd
|
|
184
|
+
* @property {BusLocale} locale
|
|
185
|
+
* @property {SessionState} state
|
|
186
|
+
* @property {number} stateSince
|
|
187
|
+
* @property {'user' | 'manager' | null} turnOrigin
|
|
188
|
+
* @property {number} queued
|
|
189
|
+
* @property {string} sandbox as the app-server reports it, `unknown` otherwise
|
|
190
|
+
* @property {string} approvalPolicy as the app-server reports it, `unknown` otherwise
|
|
191
|
+
* @property {SessionApproval | null} approval the approval the session waits for, without any request text
|
|
192
|
+
* @property {string[]} heldApprovals ids of the approval requests the worker's adapter holds for the manager right now (FR13)
|
|
193
|
+
* @property {string | null} [launcherStartTime] what identifies the launcher process (`processStartToken`), filled at registration; absent or null: pid only
|
|
194
|
+
* @property {string | null} [childStartTime] what identifies the role process, filled by `writeSession` when the role process writes its own pid
|
|
195
|
+
*/
|
|
196
|
+
/**
|
|
197
|
+
* @typedef {object} RoomDescriptor
|
|
198
|
+
* @property {string} id
|
|
199
|
+
* @property {'repository' | 'named'} kind
|
|
200
|
+
* @property {string} label
|
|
201
|
+
*/
|
|
202
|
+
/**
|
|
203
|
+
* @typedef {object} RoomPaths
|
|
204
|
+
* @property {string} bus
|
|
205
|
+
* @property {string} rooms
|
|
206
|
+
* @property {string} room
|
|
207
|
+
* @property {string} roomFile
|
|
208
|
+
* @property {string} sessions
|
|
209
|
+
* @property {string} inbox
|
|
210
|
+
* @property {string} claimed
|
|
211
|
+
* @property {string} manager
|
|
212
|
+
* @property {string} pending
|
|
213
|
+
* @property {string} tmp
|
|
214
|
+
* @property {string} delegation
|
|
215
|
+
* @property {string} decisions
|
|
216
|
+
* @property {string} audit
|
|
217
|
+
* @property {string} lock
|
|
218
|
+
*/
|
|
219
|
+
/**
|
|
220
|
+
* @typedef {object} BusClock
|
|
221
|
+
* @property {() => number} [now]
|
|
222
|
+
* @property {(pid: number) => boolean} [alive]
|
|
223
|
+
* @property {(milliseconds: number) => Promise<void>} [delay]
|
|
224
|
+
* @property {(pid: number) => string | null} [startToken] what identifies a live process; null when it cannot be told
|
|
225
|
+
*/
|
|
226
|
+
|
|
227
|
+
/** A coded failure of the bus. The code is the whole public message. */
|
|
228
|
+
export class BusError extends Error {
|
|
229
|
+
/** @param {string} code @param {string} [detail] */
|
|
230
|
+
constructor(code, detail) {
|
|
231
|
+
super(code);
|
|
232
|
+
this.name = 'BusError';
|
|
233
|
+
this.code = code;
|
|
234
|
+
this.detail = detail ?? null;
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** @param {unknown} value @returns {value is Record<string, unknown>} */
|
|
239
|
+
export function isPlainRecord(value) {
|
|
240
|
+
return (
|
|
241
|
+
typeof value === 'object' &&
|
|
242
|
+
value !== null &&
|
|
243
|
+
!Array.isArray(value) &&
|
|
244
|
+
Object.getPrototypeOf(value) === Object.prototype
|
|
245
|
+
);
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/** @param {unknown} error @returns {string | null} */
|
|
249
|
+
function errorCode(error) {
|
|
250
|
+
if (typeof error !== 'object' || error === null) return null;
|
|
251
|
+
const code = /** @type {{ code?: unknown }} */ (error).code;
|
|
252
|
+
return typeof code === 'string' ? code : null;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/** @param {unknown} value */
|
|
256
|
+
function isPid(value) {
|
|
257
|
+
return Number.isSafeInteger(value) && /** @type {number} */ (value) > 0;
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/**
|
|
261
|
+
* Whether a process of this user with that pid exists. A process of another
|
|
262
|
+
* user (`EPERM`) is never a session of this user: every bus session runs as
|
|
263
|
+
* the user who owns the state root.
|
|
264
|
+
* @param {number} pid
|
|
265
|
+
*/
|
|
266
|
+
export function processAlive(pid) {
|
|
267
|
+
if (!isPid(pid)) return false;
|
|
268
|
+
try {
|
|
269
|
+
process.kill(pid, 0);
|
|
270
|
+
return true;
|
|
271
|
+
} catch {
|
|
272
|
+
return false;
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/** @type {string | null | undefined} */
|
|
277
|
+
let cachedBootId;
|
|
278
|
+
|
|
279
|
+
function bootId() {
|
|
280
|
+
if (cachedBootId !== undefined) return cachedBootId;
|
|
281
|
+
try {
|
|
282
|
+
const text = readFileSync(BOOT_ID_FILE, 'utf8').trim();
|
|
283
|
+
cachedBootId = BOOT_ID_PATTERN.test(text) ? text : null;
|
|
284
|
+
} catch {
|
|
285
|
+
cachedBootId = null;
|
|
286
|
+
}
|
|
287
|
+
return cachedBootId;
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/**
|
|
291
|
+
* What identifies one process over its whole life, so that a pid reused by a
|
|
292
|
+
* later process is not taken for it: on Linux the boot id and the start time
|
|
293
|
+
* (field 22 of `/proc/<pid>/stat`, clock ticks since boot). Where there is no
|
|
294
|
+
* `/proc` (macOS), or the process is gone, null: liveness is then the pid
|
|
295
|
+
* alone, with `EPERM` as "not ours" (`processAlive`).
|
|
296
|
+
* @param {number} pid
|
|
297
|
+
* @returns {string | null}
|
|
298
|
+
*/
|
|
299
|
+
export function processStartToken(pid) {
|
|
300
|
+
if (!isPid(pid)) return null;
|
|
301
|
+
let text;
|
|
302
|
+
try {
|
|
303
|
+
text = readFileSync(`/proc/${pid}/stat`, 'latin1');
|
|
304
|
+
} catch {
|
|
305
|
+
return null;
|
|
306
|
+
}
|
|
307
|
+
// The command name (field 2) is in parentheses and may hold spaces or `)`.
|
|
308
|
+
const close = text.lastIndexOf(')');
|
|
309
|
+
if (close === -1) return null;
|
|
310
|
+
const start = text.slice(close + 2).split(' ')[PROC_STAT_START_TIME_INDEX];
|
|
311
|
+
if (start === undefined || !DIGITS.test(start)) return null;
|
|
312
|
+
const boot = bootId();
|
|
313
|
+
return boot === null ? start : `${boot}:${start}`;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/** @param {number} milliseconds @returns {Promise<void>} */
|
|
317
|
+
function realDelay(milliseconds) {
|
|
318
|
+
return new Promise((resolvePromise) => {
|
|
319
|
+
setTimeout(resolvePromise, milliseconds);
|
|
320
|
+
});
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
/** @param {BusClock} [clock] */
|
|
324
|
+
function clockOf(clock = {}) {
|
|
325
|
+
return {
|
|
326
|
+
now: clock.now ?? (() => Date.now()),
|
|
327
|
+
alive: clock.alive ?? processAlive,
|
|
328
|
+
delay: clock.delay ?? realDelay,
|
|
329
|
+
startToken: clock.startToken ?? processStartToken,
|
|
330
|
+
};
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
/**
|
|
334
|
+
* Whether a pid is still the process a record names: alive, and, when the
|
|
335
|
+
* record has its start time, started at that time.
|
|
336
|
+
* @param {number} pid
|
|
337
|
+
* @param {string | null | undefined} token
|
|
338
|
+
* @param {(pid: number) => boolean} alive
|
|
339
|
+
* @param {(pid: number) => string | null} startToken
|
|
340
|
+
*/
|
|
341
|
+
function pidIsProcess(pid, token, alive, startToken) {
|
|
342
|
+
if (!alive(pid)) return false;
|
|
343
|
+
if (typeof token !== 'string') return true;
|
|
344
|
+
const current = startToken(pid);
|
|
345
|
+
// Unreadable for an instant (it may be exiting): the next listing decides.
|
|
346
|
+
return current === null || current === token;
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
// ------------------------------------------------------------------ text
|
|
350
|
+
|
|
351
|
+
/** @param {number} codePoint */
|
|
352
|
+
export function isUnsafeCodePoint(codePoint) {
|
|
353
|
+
if (codePoint <= C0_LAST || (codePoint >= DELETE && codePoint <= C1_LAST)) return true;
|
|
354
|
+
return INVISIBLE_RANGES.some(([first, last]) => codePoint >= first && codePoint <= last);
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
/**
|
|
358
|
+
* Text with every control character, invisible format character and lone
|
|
359
|
+
* surrogate replaced by U+FFFD, one for one, so that it can repaint no
|
|
360
|
+
* terminal and its length is unchanged.
|
|
361
|
+
* @param {string} text
|
|
362
|
+
*/
|
|
363
|
+
export function sanitizeText(text) {
|
|
364
|
+
let result = '';
|
|
365
|
+
for (const character of text)
|
|
366
|
+
result += isUnsafeCodePoint(character.codePointAt(0) ?? 0)
|
|
367
|
+
? REPLACEMENT_CHARACTER.repeat(character.length)
|
|
368
|
+
: character;
|
|
369
|
+
return result;
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
/** @param {unknown} value @param {number} max @returns {value is string} */
|
|
373
|
+
function isSafeText(value, max) {
|
|
374
|
+
if (typeof value !== 'string' || value.length === 0 || value.length > max) return false;
|
|
375
|
+
for (const character of value) if (isUnsafeCodePoint(character.codePointAt(0) ?? 0)) return false;
|
|
376
|
+
return true;
|
|
377
|
+
}
|
|
378
|
+
|
|
379
|
+
/** @param {string} text @param {number} max */
|
|
380
|
+
function cutCodeUnits(text, max) {
|
|
381
|
+
if (text.length <= max) return text;
|
|
382
|
+
const last = text.charCodeAt(max - 1);
|
|
383
|
+
return text.slice(0, last >= HIGH_SURROGATE_FIRST && last <= HIGH_SURROGATE_LAST ? max - 1 : max);
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
/**
|
|
387
|
+
* A room's label as it is stored and shown: no control characters, at most
|
|
388
|
+
* 128 code units.
|
|
389
|
+
* @param {string} label
|
|
390
|
+
*/
|
|
391
|
+
export function roomLabel(label) {
|
|
392
|
+
return cutCodeUnits(sanitizeText(label), LABEL_MAX);
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
// ------------------------------------------------------------------ ids and paths
|
|
396
|
+
|
|
397
|
+
/** @returns {string} 128 random bits, hexadecimal */
|
|
398
|
+
export function newSessionId() {
|
|
399
|
+
return randomBytes(16).toString('hex');
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
/** @returns {string} */
|
|
403
|
+
function randomName() {
|
|
404
|
+
return randomBytes(RANDOM_NAME_BYTES).toString('hex');
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
/**
|
|
408
|
+
* The room id of an identity (`repository:<real path>` or `named:<name>`).
|
|
409
|
+
* @param {string} identity
|
|
410
|
+
*/
|
|
411
|
+
export function roomIdFor(identity) {
|
|
412
|
+
return createHash('sha256').update(identity, 'utf8').digest('hex').slice(0, 32);
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
/** @param {string} stateRoot */
|
|
416
|
+
export function busRoot(stateRoot) {
|
|
417
|
+
return join(resolve(stateRoot), BUS_DIRECTORY);
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
/**
|
|
421
|
+
* @param {string} stateRoot
|
|
422
|
+
* @param {string} roomId
|
|
423
|
+
* @returns {RoomPaths}
|
|
424
|
+
*/
|
|
425
|
+
export function roomPaths(stateRoot, roomId) {
|
|
426
|
+
if (!ROOM_ID_PATTERN.test(roomId)) throw new BusError('bus_unavailable', 'room_id_invalid');
|
|
427
|
+
const bus = busRoot(stateRoot);
|
|
428
|
+
const rooms = join(bus, 'rooms');
|
|
429
|
+
const room = join(rooms, roomId);
|
|
430
|
+
const manager = join(room, 'manager');
|
|
431
|
+
return {
|
|
432
|
+
bus,
|
|
433
|
+
rooms,
|
|
434
|
+
room,
|
|
435
|
+
roomFile: join(room, 'room.json'),
|
|
436
|
+
sessions: join(room, 'sessions'),
|
|
437
|
+
inbox: join(room, 'inbox'),
|
|
438
|
+
claimed: join(room, 'claimed'),
|
|
439
|
+
manager,
|
|
440
|
+
pending: join(manager, 'pending'),
|
|
441
|
+
tmp: join(room, 'tmp'),
|
|
442
|
+
delegation: join(room, 'delegation'),
|
|
443
|
+
decisions: join(room, 'decisions.jsonl'),
|
|
444
|
+
audit: join(room, 'audit.jsonl'),
|
|
445
|
+
lock: join(room, 'lock'),
|
|
446
|
+
};
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
/**
|
|
450
|
+
* A recipient's directory inside `inbox/` or `claimed/`. The key is a worker's
|
|
451
|
+
* session id or the literal `manager`.
|
|
452
|
+
* @param {RoomPaths} paths
|
|
453
|
+
* @param {'inbox' | 'claimed'} box
|
|
454
|
+
* @param {string} recipient
|
|
455
|
+
*/
|
|
456
|
+
export function mailboxDirectory(paths, box, recipient) {
|
|
457
|
+
if (recipient !== MANAGER_RECIPIENT && !SESSION_ID_PATTERN.test(recipient))
|
|
458
|
+
throw new BusError('bus_unavailable', 'recipient_invalid');
|
|
459
|
+
return join(box === 'inbox' ? paths.inbox : paths.claimed, recipient);
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
/** Every directory of a room, the room itself first. @param {RoomPaths} paths */
|
|
463
|
+
function roomDirectories(paths) {
|
|
464
|
+
return [
|
|
465
|
+
paths.room,
|
|
466
|
+
paths.sessions,
|
|
467
|
+
paths.inbox,
|
|
468
|
+
paths.claimed,
|
|
469
|
+
paths.manager,
|
|
470
|
+
paths.pending,
|
|
471
|
+
paths.tmp,
|
|
472
|
+
paths.delegation,
|
|
473
|
+
mailboxDirectory(paths, 'inbox', MANAGER_RECIPIENT),
|
|
474
|
+
mailboxDirectory(paths, 'claimed', MANAGER_RECIPIENT),
|
|
475
|
+
];
|
|
476
|
+
}
|
|
477
|
+
|
|
478
|
+
// ------------------------------------------------------------------ the file system
|
|
479
|
+
|
|
480
|
+
/** @param {import('node:fs').Stats} entry */
|
|
481
|
+
function ownedByUser(entry) {
|
|
482
|
+
return typeof process.getuid !== 'function' || entry.uid === process.getuid();
|
|
483
|
+
}
|
|
484
|
+
|
|
485
|
+
/**
|
|
486
|
+
* What one path is, without following it: a real directory of this user, not
|
|
487
|
+
* there at all, or anything else (a symlink, a file, another user's).
|
|
488
|
+
* @param {string} path
|
|
489
|
+
* @returns {Promise<'directory' | 'missing' | 'unsafe'>}
|
|
490
|
+
*/
|
|
491
|
+
async function directoryState(path) {
|
|
492
|
+
try {
|
|
493
|
+
const entry = await lstat(path);
|
|
494
|
+
return entry.isDirectory() && ownedByUser(entry) ? 'directory' : 'unsafe';
|
|
495
|
+
} catch (error) {
|
|
496
|
+
return MISSING_ERRORS.includes(errorCode(error) ?? '') ? 'missing' : 'unsafe';
|
|
497
|
+
}
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
/**
|
|
501
|
+
* Whether a path is a real directory of this user, not a symlink to one.
|
|
502
|
+
* @param {string} path
|
|
503
|
+
*/
|
|
504
|
+
export async function isPrivateDirectory(path) {
|
|
505
|
+
return (await directoryState(path)) === 'directory';
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
/**
|
|
509
|
+
* Whether a sweep may touch the room: the bus, `rooms/`, the room and each of
|
|
510
|
+
* its directories are real directories of this user. A directory that is
|
|
511
|
+
* missing is fine (there is nothing to sweep in it); a symlink is not.
|
|
512
|
+
* @param {RoomPaths} paths
|
|
513
|
+
*/
|
|
514
|
+
export async function roomIsSafe(paths) {
|
|
515
|
+
if ((await directoryState(paths.bus)) !== 'directory') return false;
|
|
516
|
+
if ((await directoryState(paths.rooms)) !== 'directory') return false;
|
|
517
|
+
if ((await directoryState(paths.room)) !== 'directory') return false;
|
|
518
|
+
for (const directory of roomDirectories(paths).slice(1))
|
|
519
|
+
if ((await directoryState(directory)) === 'unsafe') return false;
|
|
520
|
+
return true;
|
|
521
|
+
}
|
|
522
|
+
|
|
523
|
+
/** @param {number | null} modifiedAt @param {number} limit */
|
|
524
|
+
function isOlderThan(modifiedAt, limit) {
|
|
525
|
+
return modifiedAt !== null && modifiedAt < limit;
|
|
526
|
+
}
|
|
527
|
+
|
|
528
|
+
/**
|
|
529
|
+
* Create, or confirm, one private directory: a real directory of this user
|
|
530
|
+
* with no group or other permission bits.
|
|
531
|
+
* @param {string} path
|
|
532
|
+
*/
|
|
533
|
+
export async function ensurePrivateDirectory(path) {
|
|
534
|
+
await mkdir(path, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
|
|
535
|
+
const entry = await lstat(path);
|
|
536
|
+
if (!entry.isDirectory()) throw new BusError('bus_unavailable', 'not_a_directory');
|
|
537
|
+
if (!ownedByUser(entry)) throw new BusError('bus_unavailable', 'owner_mismatch');
|
|
538
|
+
if ((entry.mode & NOT_PRIVATE_MASK) !== 0) await chmod(path, PRIVATE_DIRECTORY_MODE);
|
|
539
|
+
return path;
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
/**
|
|
543
|
+
* Write one private file by rename: the bytes go to a file in `tmp/` first, so
|
|
544
|
+
* a reader of the target directory never sees a partial file (FR3). Nothing
|
|
545
|
+
* is written through a `tmp/` or a target directory that is a symlink or not
|
|
546
|
+
* this user's (`bus_unavailable`, `not_a_directory`); a missing one fails as
|
|
547
|
+
* the file system reports it.
|
|
548
|
+
* @param {RoomPaths} paths
|
|
549
|
+
* @param {string} target
|
|
550
|
+
* @param {string | Uint8Array} bytes
|
|
551
|
+
*/
|
|
552
|
+
export async function writePrivateFile(paths, target, bytes) {
|
|
553
|
+
for (const directory of [paths.tmp, dirname(target)])
|
|
554
|
+
if ((await directoryState(directory)) === 'unsafe')
|
|
555
|
+
throw new BusError('bus_unavailable', 'not_a_directory');
|
|
556
|
+
const temporary = join(paths.tmp, `${process.pid}-${randomName()}.tmp`);
|
|
557
|
+
try {
|
|
558
|
+
await writeFile(temporary, bytes, { mode: PRIVATE_FILE_MODE, flag: 'wx' });
|
|
559
|
+
await chmod(temporary, PRIVATE_FILE_MODE);
|
|
560
|
+
await rename(temporary, target);
|
|
561
|
+
} catch (error) {
|
|
562
|
+
await unlink(temporary).catch(() => undefined);
|
|
563
|
+
throw error;
|
|
564
|
+
}
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
/**
|
|
568
|
+
* @typedef {'missing' | 'not_a_file' | 'owner_mismatch' | 'too_large' | 'io_error'} ReadFailure
|
|
569
|
+
* `io_error` is a read that failed for another reason (a permission, the
|
|
570
|
+
* system's file table): the file may be valid, so no caller deletes it.
|
|
571
|
+
*/
|
|
572
|
+
/**
|
|
573
|
+
* @typedef {{ ok: true, data: Buffer, size: number, modifiedAt: number, ino: number }
|
|
574
|
+
* | { ok: false, reason: ReadFailure, size: number, modifiedAt: number | null, ino: number | null }} BoundedRead
|
|
575
|
+
*/
|
|
576
|
+
|
|
577
|
+
/** @param {unknown} error @returns {ReadFailure} */
|
|
578
|
+
function openFailure(error) {
|
|
579
|
+
const code = errorCode(error) ?? '';
|
|
580
|
+
if (MISSING_ERRORS.includes(code)) return 'missing';
|
|
581
|
+
if (NOT_A_FILE_ERRORS.includes(code)) return 'not_a_file';
|
|
582
|
+
return 'io_error';
|
|
583
|
+
}
|
|
584
|
+
|
|
585
|
+
/**
|
|
586
|
+
* The facts of an entry that could not be opened, read without following it,
|
|
587
|
+
* so that a caller can still age it.
|
|
588
|
+
* @param {string} path
|
|
589
|
+
* @param {ReadFailure} reason
|
|
590
|
+
* @returns {Promise<BoundedRead>}
|
|
591
|
+
*/
|
|
592
|
+
async function failedRead(path, reason) {
|
|
593
|
+
if (reason === 'missing') return { ok: false, reason, size: 0, modifiedAt: null, ino: null };
|
|
594
|
+
return lstat(path).then(
|
|
595
|
+
(entry) => ({ ok: false, reason, size: entry.size, modifiedAt: entry.mtimeMs, ino: entry.ino }),
|
|
596
|
+
() => ({ ok: false, reason, size: 0, modifiedAt: null, ino: null }),
|
|
597
|
+
);
|
|
598
|
+
}
|
|
599
|
+
|
|
600
|
+
/**
|
|
601
|
+
* @param {import('node:fs/promises').FileHandle} handle
|
|
602
|
+
* @param {number} length
|
|
603
|
+
* @param {number} position
|
|
604
|
+
*/
|
|
605
|
+
async function readFromHandle(handle, length, position) {
|
|
606
|
+
const buffer = Buffer.alloc(length);
|
|
607
|
+
let filled = 0;
|
|
608
|
+
while (filled < length) {
|
|
609
|
+
const { bytesRead } = await handle.read(buffer, filled, length - filled, position + filled);
|
|
610
|
+
if (bytesRead === 0) break;
|
|
611
|
+
filled += bytesRead;
|
|
612
|
+
}
|
|
613
|
+
return buffer.subarray(0, filled);
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
/**
|
|
617
|
+
* Read one file another process may have written. It is opened without
|
|
618
|
+
* following a symlink and without blocking (a FIFO never stalls the reader),
|
|
619
|
+
* checked on the open handle (a regular file of this user, within the limit)
|
|
620
|
+
* and read at most to the limit. With `tail`, a larger file is not refused:
|
|
621
|
+
* its last `bytesMax` bytes are read. Never throws.
|
|
622
|
+
* @param {string} path
|
|
623
|
+
* @param {number} bytesMax
|
|
624
|
+
* @param {{ tail?: boolean }} [options]
|
|
625
|
+
* @returns {Promise<BoundedRead>}
|
|
626
|
+
*/
|
|
627
|
+
export async function readBoundedFile(path, bytesMax, options = {}) {
|
|
628
|
+
let handle;
|
|
629
|
+
try {
|
|
630
|
+
handle = await open(path, READ_FLAGS);
|
|
631
|
+
} catch (error) {
|
|
632
|
+
return failedRead(path, openFailure(error));
|
|
633
|
+
}
|
|
634
|
+
try {
|
|
635
|
+
const entry = await handle.stat();
|
|
636
|
+
const facts = { size: entry.size, modifiedAt: entry.mtimeMs, ino: entry.ino };
|
|
637
|
+
if (!entry.isFile()) return { ok: false, reason: 'not_a_file', ...facts };
|
|
638
|
+
if (!ownedByUser(entry)) return { ok: false, reason: 'owner_mismatch', ...facts };
|
|
639
|
+
const tail = options.tail === true;
|
|
640
|
+
if (entry.size > bytesMax && !tail) return { ok: false, reason: 'too_large', ...facts };
|
|
641
|
+
const position = tail ? Math.max(0, entry.size - bytesMax) : 0;
|
|
642
|
+
// One byte more than allowed tells a file that grew after the check.
|
|
643
|
+
const data = await readFromHandle(handle, tail ? bytesMax : bytesMax + 1, position);
|
|
644
|
+
if (data.length > bytesMax) return { ok: false, reason: 'too_large', ...facts };
|
|
645
|
+
return { ok: true, data, ...facts };
|
|
646
|
+
} catch {
|
|
647
|
+
return { ok: false, reason: 'io_error', size: 0, modifiedAt: null, ino: null };
|
|
648
|
+
} finally {
|
|
649
|
+
await handle.close().catch(() => undefined);
|
|
650
|
+
}
|
|
651
|
+
}
|
|
652
|
+
|
|
653
|
+
/**
|
|
654
|
+
* @typedef {{ ok: true, value: unknown, bytes: number, modifiedAt: number, ino: number }
|
|
655
|
+
* | { ok: false, reason: ReadFailure | 'invalid_json', bytes: number, modifiedAt: number | null, ino: number | null }} JsonFileResult
|
|
656
|
+
*/
|
|
657
|
+
|
|
658
|
+
/**
|
|
659
|
+
* Read one JSON file another process may have written (`readBoundedFile`).
|
|
660
|
+
* Never throws; the reason is a code.
|
|
661
|
+
* @param {string} path
|
|
662
|
+
* @param {number} bytesMax
|
|
663
|
+
* @returns {Promise<JsonFileResult>}
|
|
664
|
+
*/
|
|
665
|
+
export async function readJsonFile(path, bytesMax) {
|
|
666
|
+
const read = await readBoundedFile(path, bytesMax);
|
|
667
|
+
if (!read.ok)
|
|
668
|
+
return {
|
|
669
|
+
ok: false,
|
|
670
|
+
reason: read.reason,
|
|
671
|
+
bytes: read.size,
|
|
672
|
+
modifiedAt: read.modifiedAt,
|
|
673
|
+
ino: read.ino,
|
|
674
|
+
};
|
|
675
|
+
try {
|
|
676
|
+
return {
|
|
677
|
+
ok: true,
|
|
678
|
+
value: JSON.parse(read.data.toString('utf8')),
|
|
679
|
+
bytes: read.size,
|
|
680
|
+
modifiedAt: read.modifiedAt,
|
|
681
|
+
ino: read.ino,
|
|
682
|
+
};
|
|
683
|
+
} catch {
|
|
684
|
+
return {
|
|
685
|
+
ok: false,
|
|
686
|
+
reason: 'invalid_json',
|
|
687
|
+
bytes: read.size,
|
|
688
|
+
modifiedAt: read.modifiedAt,
|
|
689
|
+
ino: read.ino,
|
|
690
|
+
};
|
|
691
|
+
}
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
/**
|
|
695
|
+
* Remove an entry, but only while it is still the file that was read (same
|
|
696
|
+
* inode), so that a file renamed into its place meanwhile survives, and only
|
|
697
|
+
* when its directory is a real directory of this user (never through a link).
|
|
698
|
+
* @param {string} path
|
|
699
|
+
* @param {number | null} ino
|
|
700
|
+
*/
|
|
701
|
+
export async function removeIfUnchanged(path, ino) {
|
|
702
|
+
if (ino === null) return;
|
|
703
|
+
if ((await directoryState(dirname(path))) !== 'directory') return;
|
|
704
|
+
const entry = await lstat(path).catch(() => null);
|
|
705
|
+
if (entry !== null && entry.ino === ino) await rm(path, { force: true }).catch(() => undefined);
|
|
706
|
+
}
|
|
707
|
+
|
|
708
|
+
// ------------------------------------------------------------------ rooms
|
|
709
|
+
|
|
710
|
+
/**
|
|
711
|
+
* The rooms this process prepared with `ensureRoom`, so that a registration
|
|
712
|
+
* whose room a sweep removed meanwhile can build it again.
|
|
713
|
+
* @type {WeakMap<RoomPaths, { stateRoot: string, room: RoomDescriptor }>}
|
|
714
|
+
*/
|
|
715
|
+
const preparedRooms = new WeakMap();
|
|
716
|
+
|
|
717
|
+
/** @param {RoomPaths} paths @param {RoomDescriptor} room @param {number} now */
|
|
718
|
+
async function writeRoomFile(paths, room, now) {
|
|
719
|
+
const descriptor = {
|
|
720
|
+
schemaVersion: BUS_SCHEMA_VERSION,
|
|
721
|
+
id: room.id,
|
|
722
|
+
kind: room.kind,
|
|
723
|
+
label: roomLabel(room.label),
|
|
724
|
+
createdAt: now,
|
|
725
|
+
};
|
|
726
|
+
await writePrivateFile(paths, paths.roomFile, `${JSON.stringify(descriptor)}\n`);
|
|
727
|
+
}
|
|
728
|
+
|
|
729
|
+
/** @param {RoomPaths} paths @param {RoomDescriptor} room @param {number} now */
|
|
730
|
+
async function prepareRoom(paths, room, now) {
|
|
731
|
+
for (const directory of [paths.bus, paths.rooms, ...roomDirectories(paths)])
|
|
732
|
+
await ensurePrivateDirectory(directory);
|
|
733
|
+
const existing = await readJsonFile(paths.roomFile, ROOM_FILE_BYTES_MAX);
|
|
734
|
+
// Also the rename probe: a file system without it cannot carry the bus.
|
|
735
|
+
if (!existing.ok) await writeRoomFile(paths, room, now);
|
|
736
|
+
}
|
|
737
|
+
|
|
738
|
+
/**
|
|
739
|
+
* A failure that means the room went away meanwhile: another launch's sweep
|
|
740
|
+
* removed it as empty.
|
|
741
|
+
* @param {unknown} error
|
|
742
|
+
*/
|
|
743
|
+
function isRoomGone(error) {
|
|
744
|
+
const code = error instanceof BusError ? error.detail : errorCode(error);
|
|
745
|
+
return code !== null && MISSING_ERRORS.includes(code);
|
|
746
|
+
}
|
|
747
|
+
|
|
748
|
+
/**
|
|
749
|
+
* Create the room's private directories and its descriptor, and prove that a
|
|
750
|
+
* rename works there. A room that another launch's sweep removes meanwhile is
|
|
751
|
+
* built again, up to three times. Any failure is `bus_unavailable` (FR1: the
|
|
752
|
+
* role never blocks a launch; the caller starts the host without it).
|
|
753
|
+
* @param {string} stateRoot
|
|
754
|
+
* @param {RoomDescriptor} room
|
|
755
|
+
* @param {BusClock} [clock]
|
|
756
|
+
* @returns {Promise<RoomPaths>}
|
|
757
|
+
*/
|
|
758
|
+
export async function ensureRoom(stateRoot, room, clock) {
|
|
759
|
+
const { now } = clockOf(clock);
|
|
760
|
+
const paths = roomPaths(stateRoot, room.id);
|
|
761
|
+
for (let attempt = 1; ; attempt += 1) {
|
|
762
|
+
try {
|
|
763
|
+
await prepareRoom(paths, room, now());
|
|
764
|
+
break;
|
|
765
|
+
} catch (error) {
|
|
766
|
+
if (isRoomGone(error) && attempt < REGISTER_ATTEMPTS_MAX) continue;
|
|
767
|
+
if (error instanceof BusError) throw error;
|
|
768
|
+
throw new BusError('bus_unavailable', errorCode(error) ?? 'io_error');
|
|
769
|
+
}
|
|
770
|
+
}
|
|
771
|
+
preparedRooms.set(paths, {
|
|
772
|
+
stateRoot,
|
|
773
|
+
room: { id: room.id, kind: room.kind, label: room.label },
|
|
774
|
+
});
|
|
775
|
+
return paths;
|
|
776
|
+
}
|
|
777
|
+
|
|
778
|
+
/**
|
|
779
|
+
* @param {RoomPaths} paths
|
|
780
|
+
* @returns {Promise<RoomDescriptor | null>}
|
|
781
|
+
*/
|
|
782
|
+
export async function readRoom(paths) {
|
|
783
|
+
const file = await readJsonFile(paths.roomFile, ROOM_FILE_BYTES_MAX);
|
|
784
|
+
if (!file.ok || !isPlainRecord(file.value)) return null;
|
|
785
|
+
const { id, kind, label } = file.value;
|
|
786
|
+
if (typeof id !== 'string' || !ROOM_ID_PATTERN.test(id)) return null;
|
|
787
|
+
if (kind !== 'repository' && kind !== 'named') return null;
|
|
788
|
+
if (typeof label !== 'string' || label.length > LABEL_MAX) return null;
|
|
789
|
+
return { id, kind, label: roomLabel(label) };
|
|
790
|
+
}
|
|
791
|
+
|
|
792
|
+
// ------------------------------------------------------------------ locks
|
|
793
|
+
|
|
794
|
+
/**
|
|
795
|
+
* @typedef {object} LockOwner
|
|
796
|
+
* @property {number} pid
|
|
797
|
+
* @property {number} at
|
|
798
|
+
* @property {string} nonce
|
|
799
|
+
* @property {string | null} token
|
|
800
|
+
*/
|
|
801
|
+
/**
|
|
802
|
+
* A lock as one waiter saw it. `text` is its whole content, so that a lock
|
|
803
|
+
* created later on a reused inode number is not taken for it.
|
|
804
|
+
* @typedef {{ ino: number | null, modifiedAt: number | null, text: string | null, owner: LockOwner | null }} HeldLock
|
|
805
|
+
*/
|
|
806
|
+
|
|
807
|
+
/** @param {number} pid @param {number} at @param {string} nonce @param {string | null} token */
|
|
808
|
+
function lockLine(pid, at, nonce, token) {
|
|
809
|
+
return `${pid} ${at} ${nonce} ${token ?? NO_TOKEN}\n`;
|
|
810
|
+
}
|
|
811
|
+
|
|
812
|
+
/** @param {string} text @returns {LockOwner | null} */
|
|
813
|
+
function parseLockLine(text) {
|
|
814
|
+
const match = LOCK_LINE.exec(text);
|
|
815
|
+
if (!match) return null;
|
|
816
|
+
const [, pid, at, nonce, token] = /** @type {[string, string, string, string, string]} */ (
|
|
817
|
+
/** @type {unknown} */ (match)
|
|
818
|
+
);
|
|
819
|
+
return { pid: Number(pid), at: Number(at), nonce, token: token === NO_TOKEN ? null : token };
|
|
820
|
+
}
|
|
821
|
+
|
|
822
|
+
/**
|
|
823
|
+
* Create the lock already holding its owner line: the line is written to a
|
|
824
|
+
* temporary file that is then hard-linked to the lock's name, which fails when
|
|
825
|
+
* the name exists. No reader ever sees a lock without its owner.
|
|
826
|
+
* @param {string} lockPath
|
|
827
|
+
* @param {string} temporaryDirectory
|
|
828
|
+
* @param {string} line
|
|
829
|
+
* @returns {Promise<boolean>} false when the lock is held
|
|
830
|
+
*/
|
|
831
|
+
async function createLock(lockPath, temporaryDirectory, line) {
|
|
832
|
+
const temporary = join(temporaryDirectory, `${process.pid}-${randomName()}.lock`);
|
|
833
|
+
await writeFile(temporary, line, { mode: PRIVATE_FILE_MODE, flag: 'wx' });
|
|
834
|
+
try {
|
|
835
|
+
await link(temporary, lockPath);
|
|
836
|
+
return true;
|
|
837
|
+
} catch (error) {
|
|
838
|
+
if (errorCode(error) === 'EEXIST') return false;
|
|
839
|
+
throw error;
|
|
840
|
+
} finally {
|
|
841
|
+
await unlink(temporary).catch(() => undefined);
|
|
842
|
+
}
|
|
843
|
+
}
|
|
844
|
+
|
|
845
|
+
/** @param {string} lockPath @returns {Promise<HeldLock | null>} null when there is no lock */
|
|
846
|
+
async function inspectLock(lockPath) {
|
|
847
|
+
const read = await readBoundedFile(lockPath, LOCK_FILE_BYTES_MAX);
|
|
848
|
+
if (!read.ok && read.reason === 'missing') return null;
|
|
849
|
+
const text = read.ok ? read.data.toString('utf8') : null;
|
|
850
|
+
return {
|
|
851
|
+
ino: read.ino,
|
|
852
|
+
modifiedAt: read.modifiedAt,
|
|
853
|
+
text,
|
|
854
|
+
owner: text === null ? null : parseLockLine(text),
|
|
855
|
+
};
|
|
856
|
+
}
|
|
857
|
+
|
|
858
|
+
/** Whether two looks at a lock saw the same file. @param {HeldLock} left @param {HeldLock} right */
|
|
859
|
+
function sameLock(left, right) {
|
|
860
|
+
return (
|
|
861
|
+
left.ino !== null &&
|
|
862
|
+
left.ino === right.ino &&
|
|
863
|
+
left.modifiedAt === right.modifiedAt &&
|
|
864
|
+
left.text === right.text
|
|
865
|
+
);
|
|
866
|
+
}
|
|
867
|
+
|
|
868
|
+
/**
|
|
869
|
+
* A lock is stale when its owner is gone. A lock without a readable owner
|
|
870
|
+
* line is held until it is older than ten seconds; a live owner's lock is
|
|
871
|
+
* never broken, however old.
|
|
872
|
+
* @param {HeldLock} held
|
|
873
|
+
* @param {number} now
|
|
874
|
+
* @param {ReturnType<typeof clockOf>} clock
|
|
875
|
+
*/
|
|
876
|
+
function lockIsStale(held, now, clock) {
|
|
877
|
+
if (held.owner === null) return isOlderThan(held.modifiedAt, now - LOCK_STALE_MS);
|
|
878
|
+
return !pidIsProcess(held.owner.pid, held.owner.token, clock.alive, clock.startToken);
|
|
879
|
+
}
|
|
880
|
+
|
|
881
|
+
/**
|
|
882
|
+
* Remove a breaker lock whose owner died inside its few instructions, when it
|
|
883
|
+
* is still the file that was judged.
|
|
884
|
+
* @param {string} breaker
|
|
885
|
+
* @param {ReturnType<typeof clockOf>} timing
|
|
886
|
+
*/
|
|
887
|
+
async function clearDeadBreaker(breaker, timing) {
|
|
888
|
+
const held = await inspectLock(breaker);
|
|
889
|
+
if (held === null || !lockIsStale(held, timing.now(), timing)) return;
|
|
890
|
+
const current = await inspectLock(breaker);
|
|
891
|
+
if (current !== null && sameLock(current, held)) await unlink(breaker).catch(() => undefined);
|
|
892
|
+
}
|
|
893
|
+
|
|
894
|
+
/**
|
|
895
|
+
* Break a stale lock. Waiters break one at a time, under a breaker lock
|
|
896
|
+
* (`<lock>.break`), and only while the lock is still the file that was judged:
|
|
897
|
+
* the same inode and the same content (another waiter may have broken it and
|
|
898
|
+
* taken the room meanwhile, on a reused inode number). While the stale lock
|
|
899
|
+
* exists nobody else can create one, so nothing replaces it between that
|
|
900
|
+
* check and the removal.
|
|
901
|
+
* @param {string} lockPath
|
|
902
|
+
* @param {string} temporaryDirectory
|
|
903
|
+
* @param {HeldLock} held
|
|
904
|
+
* @param {ReturnType<typeof clockOf>} timing
|
|
905
|
+
* @returns {Promise<boolean>} whether the lock is gone, so the waiter may try at once
|
|
906
|
+
*/
|
|
907
|
+
async function breakLock(lockPath, temporaryDirectory, held, timing) {
|
|
908
|
+
const breaker = `${lockPath}${BREAKER_SUFFIX}`;
|
|
909
|
+
const nonce = randomBytes(LOCK_NONCE_BYTES).toString('hex');
|
|
910
|
+
const line = lockLine(process.pid, timing.now(), nonce, timing.startToken(process.pid));
|
|
911
|
+
try {
|
|
912
|
+
if (!(await createLock(breaker, temporaryDirectory, line))) {
|
|
913
|
+
await clearDeadBreaker(breaker, timing);
|
|
914
|
+
return false;
|
|
915
|
+
}
|
|
916
|
+
} catch {
|
|
917
|
+
return false;
|
|
918
|
+
}
|
|
919
|
+
try {
|
|
920
|
+
const current = await inspectLock(lockPath);
|
|
921
|
+
if (current === null) return true;
|
|
922
|
+
if (!sameLock(current, held)) return false;
|
|
923
|
+
await unlink(lockPath);
|
|
924
|
+
return true;
|
|
925
|
+
} catch {
|
|
926
|
+
return false;
|
|
927
|
+
} finally {
|
|
928
|
+
await releaseLock(breaker, nonce);
|
|
929
|
+
}
|
|
930
|
+
}
|
|
931
|
+
|
|
932
|
+
/** @param {string} lockPath @param {string} nonce */
|
|
933
|
+
async function releaseLock(lockPath, nonce) {
|
|
934
|
+
const read = await readBoundedFile(lockPath, LOCK_FILE_BYTES_MAX);
|
|
935
|
+
if (!read.ok) return;
|
|
936
|
+
const owner = parseLockLine(read.data.toString('utf8'));
|
|
937
|
+
if (owner?.nonce === nonce && owner.pid === process.pid)
|
|
938
|
+
await removeIfUnchanged(lockPath, read.ino);
|
|
939
|
+
}
|
|
940
|
+
|
|
941
|
+
/**
|
|
942
|
+
* Run one task while holding a lock file (see `withRoomLock`).
|
|
943
|
+
* @template T
|
|
944
|
+
* @param {string} lockPath
|
|
945
|
+
* @param {string} temporaryDirectory
|
|
946
|
+
* @param {() => Promise<T>} task
|
|
947
|
+
* @param {BusClock} [clock]
|
|
948
|
+
* @returns {Promise<T>}
|
|
949
|
+
*/
|
|
950
|
+
async function withFileLock(lockPath, temporaryDirectory, task, clock) {
|
|
951
|
+
const timing = clockOf(clock);
|
|
952
|
+
const nonce = randomBytes(LOCK_NONCE_BYTES).toString('hex');
|
|
953
|
+
const token = timing.startToken(process.pid);
|
|
954
|
+
const deadline = timing.now() + LOCK_WAIT_MS;
|
|
955
|
+
for (let attempt = 1; ; attempt += 1) {
|
|
956
|
+
let acquired;
|
|
957
|
+
try {
|
|
958
|
+
acquired = await createLock(
|
|
959
|
+
lockPath,
|
|
960
|
+
temporaryDirectory,
|
|
961
|
+
lockLine(process.pid, timing.now(), nonce, token),
|
|
962
|
+
);
|
|
963
|
+
} catch (error) {
|
|
964
|
+
throw new BusError('bus_unavailable', errorCode(error) ?? 'lock_failed');
|
|
965
|
+
}
|
|
966
|
+
if (acquired) break;
|
|
967
|
+
const held = await inspectLock(lockPath);
|
|
968
|
+
const free =
|
|
969
|
+
held === null ||
|
|
970
|
+
(lockIsStale(held, timing.now(), timing) &&
|
|
971
|
+
(await breakLock(lockPath, temporaryDirectory, held, timing)));
|
|
972
|
+
if (timing.now() >= deadline || attempt >= LOCK_ATTEMPTS_MAX)
|
|
973
|
+
throw new BusError('bus_unavailable', 'lock_timeout');
|
|
974
|
+
if (!free) await timing.delay(LOCK_RETRY_MS);
|
|
975
|
+
}
|
|
976
|
+
try {
|
|
977
|
+
return await task();
|
|
978
|
+
} finally {
|
|
979
|
+
await releaseLock(lockPath, nonce);
|
|
980
|
+
}
|
|
981
|
+
}
|
|
982
|
+
|
|
983
|
+
/**
|
|
984
|
+
* Run one task while holding the room's lock: a file created with its owner
|
|
985
|
+
* line already in it (pid, time, a nonce and the process start time), broken
|
|
986
|
+
* only when its owner is gone (`breakLock`), released only by its owner. The
|
|
987
|
+
* wait is three seconds at most; then `bus_unavailable` with `lock_timeout`.
|
|
988
|
+
* Not re-entrant: a task that takes the room lock again (`registerSession`,
|
|
989
|
+
* `sweepRoom`) waits for itself and fails with `lock_timeout`. Writing the
|
|
990
|
+
* audit or the decision record inside it is fine: their rotation has a lock
|
|
991
|
+
* file of its own.
|
|
992
|
+
* @template T
|
|
993
|
+
* @param {RoomPaths} paths
|
|
994
|
+
* @param {() => Promise<T>} task
|
|
995
|
+
* @param {BusClock} [clock]
|
|
996
|
+
* @returns {Promise<T>}
|
|
997
|
+
*/
|
|
998
|
+
export function withRoomLock(paths, task, clock) {
|
|
999
|
+
return withFileLock(paths.lock, paths.tmp, task, clock);
|
|
1000
|
+
}
|
|
1001
|
+
|
|
1002
|
+
// ------------------------------------------------------------------ session records
|
|
1003
|
+
|
|
1004
|
+
/** @param {unknown} value */
|
|
1005
|
+
function isTime(value) {
|
|
1006
|
+
return Number.isSafeInteger(value) && /** @type {number} */ (value) >= 0;
|
|
1007
|
+
}
|
|
1008
|
+
|
|
1009
|
+
/** @param {unknown} value */
|
|
1010
|
+
function isOptionalToken(value) {
|
|
1011
|
+
return (
|
|
1012
|
+
value === undefined ||
|
|
1013
|
+
value === null ||
|
|
1014
|
+
(typeof value === 'string' && START_TOKEN_PATTERN.test(value))
|
|
1015
|
+
);
|
|
1016
|
+
}
|
|
1017
|
+
|
|
1018
|
+
const SESSION_KEYS = [
|
|
1019
|
+
'schemaVersion',
|
|
1020
|
+
'sessionId',
|
|
1021
|
+
'name',
|
|
1022
|
+
'role',
|
|
1023
|
+
'host',
|
|
1024
|
+
'hostVersion',
|
|
1025
|
+
'launcherPid',
|
|
1026
|
+
'childPid',
|
|
1027
|
+
'startedAt',
|
|
1028
|
+
'cwd',
|
|
1029
|
+
'locale',
|
|
1030
|
+
'state',
|
|
1031
|
+
'stateSince',
|
|
1032
|
+
'turnOrigin',
|
|
1033
|
+
'queued',
|
|
1034
|
+
'sandbox',
|
|
1035
|
+
'approvalPolicy',
|
|
1036
|
+
'approval',
|
|
1037
|
+
'heldApprovals',
|
|
1038
|
+
];
|
|
1039
|
+
/** Added after the first records were written: a record without them is still valid. */
|
|
1040
|
+
const OPTIONAL_SESSION_KEYS = ['launcherStartTime', 'childStartTime'];
|
|
1041
|
+
const SESSION_STATES = ['starting', 'idle', 'busy', 'waiting_approval'];
|
|
1042
|
+
const APPROVAL_KINDS = ['command', 'fileChange', 'permissions'];
|
|
1043
|
+
const UNKNOWN_VALUE = 'unknown';
|
|
1044
|
+
|
|
1045
|
+
/** @param {unknown} value @returns {value is SessionApproval} */
|
|
1046
|
+
function isSessionApproval(value) {
|
|
1047
|
+
if (!isPlainRecord(value)) return false;
|
|
1048
|
+
if (Object.keys(value).some((key) => !['kind', 'decider', 'since'].includes(key))) return false;
|
|
1049
|
+
return (
|
|
1050
|
+
APPROVAL_KINDS.includes(/** @type {string} */ (value.kind)) &&
|
|
1051
|
+
(value.decider === 'user' || value.decider === 'manager') &&
|
|
1052
|
+
isTime(value.since)
|
|
1053
|
+
);
|
|
1054
|
+
}
|
|
1055
|
+
|
|
1056
|
+
/** @param {Record<string, unknown>} value */
|
|
1057
|
+
function hasSessionKeys(value) {
|
|
1058
|
+
const keys = Object.keys(value);
|
|
1059
|
+
return (
|
|
1060
|
+
keys.every((key) => SESSION_KEYS.includes(key) || OPTIONAL_SESSION_KEYS.includes(key)) &&
|
|
1061
|
+
SESSION_KEYS.every((key) => Object.hasOwn(value, key))
|
|
1062
|
+
);
|
|
1063
|
+
}
|
|
1064
|
+
|
|
1065
|
+
/** @param {Record<string, unknown>} value */
|
|
1066
|
+
function hasValidReportedValues(value) {
|
|
1067
|
+
return (
|
|
1068
|
+
(value.hostVersion === null ||
|
|
1069
|
+
(typeof value.hostVersion === 'string' && VERSION_PATTERN.test(value.hostVersion))) &&
|
|
1070
|
+
typeof value.sandbox === 'string' &&
|
|
1071
|
+
REPORTED_VALUE_PATTERN.test(value.sandbox) &&
|
|
1072
|
+
typeof value.approvalPolicy === 'string' &&
|
|
1073
|
+
REPORTED_VALUE_PATTERN.test(value.approvalPolicy)
|
|
1074
|
+
);
|
|
1075
|
+
}
|
|
1076
|
+
|
|
1077
|
+
/**
|
|
1078
|
+
* Strict: no unknown keys, every field of the expected type and size; the
|
|
1079
|
+
* reported values short identifiers, the working directory free of control
|
|
1080
|
+
* characters.
|
|
1081
|
+
* @param {unknown} value
|
|
1082
|
+
* @returns {value is SessionRecord}
|
|
1083
|
+
*/
|
|
1084
|
+
export function isSessionRecord(value) {
|
|
1085
|
+
if (!isPlainRecord(value) || !hasSessionKeys(value)) return false;
|
|
1086
|
+
const role = value.role;
|
|
1087
|
+
const name = value.name;
|
|
1088
|
+
if (role !== 'manager' && role !== 'worker') return false;
|
|
1089
|
+
if (typeof name !== 'string' || !NAME_PATTERN.test(name)) return false;
|
|
1090
|
+
if ((role === 'manager') !== (name === MANAGER_NAME)) return false;
|
|
1091
|
+
return (
|
|
1092
|
+
value.schemaVersion === BUS_SCHEMA_VERSION &&
|
|
1093
|
+
typeof value.sessionId === 'string' &&
|
|
1094
|
+
SESSION_ID_PATTERN.test(value.sessionId) &&
|
|
1095
|
+
(value.host === 'claude' || value.host === 'codex') &&
|
|
1096
|
+
hasValidReportedValues(value) &&
|
|
1097
|
+
isPid(value.launcherPid) &&
|
|
1098
|
+
(value.childPid === null || isPid(value.childPid)) &&
|
|
1099
|
+
isOptionalToken(value.launcherStartTime) &&
|
|
1100
|
+
isOptionalToken(value.childStartTime) &&
|
|
1101
|
+
isTime(value.startedAt) &&
|
|
1102
|
+
isSafeText(value.cwd, PATH_LENGTH_MAX) &&
|
|
1103
|
+
(value.locale === 'pt-BR' || value.locale === 'en') &&
|
|
1104
|
+
SESSION_STATES.includes(/** @type {string} */ (value.state)) &&
|
|
1105
|
+
isTime(value.stateSince) &&
|
|
1106
|
+
(value.turnOrigin === null || value.turnOrigin === 'user' || value.turnOrigin === 'manager') &&
|
|
1107
|
+
Number.isSafeInteger(value.queued) &&
|
|
1108
|
+
/** @type {number} */ (value.queued) >= 0 &&
|
|
1109
|
+
(value.approval === null || isSessionApproval(value.approval)) &&
|
|
1110
|
+
Array.isArray(value.heldApprovals) &&
|
|
1111
|
+
value.heldApprovals.length <= HELD_APPROVALS_MAX &&
|
|
1112
|
+
value.heldApprovals.every((id) => typeof id === 'string' && MESSAGE_ID_PATTERN.test(id))
|
|
1113
|
+
);
|
|
1114
|
+
}
|
|
1115
|
+
|
|
1116
|
+
/**
|
|
1117
|
+
* The record as it may be written: a working directory with its control
|
|
1118
|
+
* characters replaced, a host version that is not a version dropped, a
|
|
1119
|
+
* reported value that is not an identifier `unknown`. A strange directory
|
|
1120
|
+
* name or host output never stops a registration. Other fields are left for
|
|
1121
|
+
* `isSessionRecord` to judge.
|
|
1122
|
+
* @param {unknown} record
|
|
1123
|
+
* @returns {unknown}
|
|
1124
|
+
*/
|
|
1125
|
+
function normalizeSessionRecord(record) {
|
|
1126
|
+
if (!isPlainRecord(record)) return record;
|
|
1127
|
+
/** @param {unknown} value */
|
|
1128
|
+
const reported = (value) =>
|
|
1129
|
+
typeof value === 'string' && !REPORTED_VALUE_PATTERN.test(value) ? UNKNOWN_VALUE : value;
|
|
1130
|
+
return {
|
|
1131
|
+
...record,
|
|
1132
|
+
hostVersion:
|
|
1133
|
+
typeof record.hostVersion === 'string' && !VERSION_PATTERN.test(record.hostVersion)
|
|
1134
|
+
? null
|
|
1135
|
+
: record.hostVersion,
|
|
1136
|
+
cwd:
|
|
1137
|
+
typeof record.cwd === 'string'
|
|
1138
|
+
? cutCodeUnits(sanitizeText(record.cwd), PATH_LENGTH_MAX)
|
|
1139
|
+
: record.cwd,
|
|
1140
|
+
sandbox: reported(record.sandbox),
|
|
1141
|
+
approvalPolicy: reported(record.approvalPolicy),
|
|
1142
|
+
};
|
|
1143
|
+
}
|
|
1144
|
+
|
|
1145
|
+
/**
|
|
1146
|
+
* A session's recipient key: its own id for a worker, `manager` for the manager.
|
|
1147
|
+
* @param {Pick<SessionRecord, 'role' | 'sessionId'>} record
|
|
1148
|
+
*/
|
|
1149
|
+
export function recipientOf(record) {
|
|
1150
|
+
return record.role === 'manager' ? MANAGER_RECIPIENT : record.sessionId;
|
|
1151
|
+
}
|
|
1152
|
+
|
|
1153
|
+
/** @param {RoomPaths} paths @param {string} sessionId */
|
|
1154
|
+
function sessionFile(paths, sessionId) {
|
|
1155
|
+
if (!SESSION_ID_PATTERN.test(sessionId))
|
|
1156
|
+
throw new BusError('bus_unavailable', 'session_id_invalid');
|
|
1157
|
+
return join(paths.sessions, `${sessionId}${JSON_SUFFIX}`);
|
|
1158
|
+
}
|
|
1159
|
+
|
|
1160
|
+
/**
|
|
1161
|
+
* Replace a session's record. Only the session's own processes call this. A
|
|
1162
|
+
* record whose child is this process gets this process's start time, so that
|
|
1163
|
+
* the role process that spreads the launcher's record and writes its own pid
|
|
1164
|
+
* is identified by it.
|
|
1165
|
+
* @param {RoomPaths} paths
|
|
1166
|
+
* @param {SessionRecord} record
|
|
1167
|
+
*/
|
|
1168
|
+
export async function writeSession(paths, record) {
|
|
1169
|
+
const normalized = normalizeSessionRecord(record);
|
|
1170
|
+
const complete =
|
|
1171
|
+
isPlainRecord(normalized) && normalized.childPid === process.pid
|
|
1172
|
+
? { ...normalized, childStartTime: processStartToken(process.pid) }
|
|
1173
|
+
: normalized;
|
|
1174
|
+
if (!isSessionRecord(complete)) throw new BusError('bus_unavailable', 'session_record_invalid');
|
|
1175
|
+
await writePrivateFile(
|
|
1176
|
+
paths,
|
|
1177
|
+
sessionFile(paths, complete.sessionId),
|
|
1178
|
+
`${JSON.stringify(complete)}\n`,
|
|
1179
|
+
);
|
|
1180
|
+
}
|
|
1181
|
+
|
|
1182
|
+
/**
|
|
1183
|
+
* @param {RoomPaths} paths
|
|
1184
|
+
* @param {string} sessionId
|
|
1185
|
+
* @returns {Promise<SessionRecord | null>}
|
|
1186
|
+
*/
|
|
1187
|
+
export async function readSession(paths, sessionId) {
|
|
1188
|
+
const file = await readJsonFile(sessionFile(paths, sessionId), SESSION_FILE_BYTES_MAX);
|
|
1189
|
+
return file.ok && isSessionRecord(file.value) && file.value.sessionId === sessionId
|
|
1190
|
+
? file.value
|
|
1191
|
+
: null;
|
|
1192
|
+
}
|
|
1193
|
+
|
|
1194
|
+
/**
|
|
1195
|
+
* A session is live while its launcher or its role process is (FR2): a
|
|
1196
|
+
* process with that pid exists, belongs to this user, and, when the record
|
|
1197
|
+
* has its start time, is the process that started then (not a reused pid).
|
|
1198
|
+
* @param {SessionRecord} record
|
|
1199
|
+
* @param {(pid: number) => boolean} alive
|
|
1200
|
+
* @param {(pid: number) => string | null} [startToken]
|
|
1201
|
+
*/
|
|
1202
|
+
export function sessionLive(record, alive, startToken = processStartToken) {
|
|
1203
|
+
return (
|
|
1204
|
+
pidIsProcess(record.launcherPid, record.launcherStartTime, alive, startToken) ||
|
|
1205
|
+
(record.childPid !== null &&
|
|
1206
|
+
pidIsProcess(record.childPid, record.childStartTime, alive, startToken))
|
|
1207
|
+
);
|
|
1208
|
+
}
|
|
1209
|
+
|
|
1210
|
+
/**
|
|
1211
|
+
* Remove what a session leaves behind: its record, and for a worker its inbox,
|
|
1212
|
+
* its claimed directory and its delegation. The manager's inbox stays: it
|
|
1213
|
+
* belongs to the room. Nothing is removed through a directory that is not a
|
|
1214
|
+
* real directory of this user.
|
|
1215
|
+
* @param {RoomPaths} paths
|
|
1216
|
+
* @param {string} sessionId
|
|
1217
|
+
* @param {Role} role
|
|
1218
|
+
*/
|
|
1219
|
+
export async function removeSession(paths, sessionId, role) {
|
|
1220
|
+
const file = sessionFile(paths, sessionId);
|
|
1221
|
+
/** @type {[string, string][]} */
|
|
1222
|
+
const targets = [[paths.sessions, file]];
|
|
1223
|
+
if (role === 'worker')
|
|
1224
|
+
targets.push(
|
|
1225
|
+
[paths.inbox, mailboxDirectory(paths, 'inbox', sessionId)],
|
|
1226
|
+
[paths.claimed, mailboxDirectory(paths, 'claimed', sessionId)],
|
|
1227
|
+
[paths.delegation, join(paths.delegation, `${sessionId}${JSON_SUFFIX}`)],
|
|
1228
|
+
);
|
|
1229
|
+
for (const [parent, target] of targets)
|
|
1230
|
+
if ((await directoryState(parent)) === 'directory')
|
|
1231
|
+
await rm(target, { recursive: true, force: true }).catch(() => undefined);
|
|
1232
|
+
}
|
|
1233
|
+
|
|
1234
|
+
/**
|
|
1235
|
+
* @typedef {object} SessionScan
|
|
1236
|
+
* @property {SessionRecord[]} live the live sessions
|
|
1237
|
+
* @property {Set<string>} present every session id that still has a record file, live or not
|
|
1238
|
+
*/
|
|
1239
|
+
|
|
1240
|
+
/**
|
|
1241
|
+
* Read every record of the room. A valid record whose processes are gone is
|
|
1242
|
+
* removed with what it left. A record this client cannot validate (a newer
|
|
1243
|
+
* schema, a damaged file) is not live, and is removed only a day after its
|
|
1244
|
+
* last change; a record that could not be read at all is left alone.
|
|
1245
|
+
* @param {RoomPaths} paths
|
|
1246
|
+
* @param {BusClock & { sweep?: boolean }} [options]
|
|
1247
|
+
* @returns {Promise<SessionScan>}
|
|
1248
|
+
*/
|
|
1249
|
+
async function scanSessions(paths, options = {}) {
|
|
1250
|
+
const timing = clockOf(options);
|
|
1251
|
+
/** @type {SessionScan} */
|
|
1252
|
+
const scan = { live: [], present: new Set() };
|
|
1253
|
+
let names;
|
|
1254
|
+
try {
|
|
1255
|
+
names = await readdir(paths.sessions);
|
|
1256
|
+
} catch {
|
|
1257
|
+
return scan;
|
|
1258
|
+
}
|
|
1259
|
+
const sweep = options.sweep !== false && (await directoryState(paths.sessions)) === 'directory';
|
|
1260
|
+
const staleBefore = timing.now() - LIMITS.retentionMs;
|
|
1261
|
+
for (const name of names.sort()) {
|
|
1262
|
+
if (!JSON_FILE.test(name)) continue;
|
|
1263
|
+
const sessionId = name.slice(0, -JSON_SUFFIX.length);
|
|
1264
|
+
if (!SESSION_ID_PATTERN.test(sessionId)) continue;
|
|
1265
|
+
const file = await readJsonFile(join(paths.sessions, name), SESSION_FILE_BYTES_MAX);
|
|
1266
|
+
if (!file.ok && file.reason === 'missing') continue;
|
|
1267
|
+
scan.present.add(sessionId);
|
|
1268
|
+
if (!file.ok && file.reason === 'io_error') continue;
|
|
1269
|
+
const record =
|
|
1270
|
+
file.ok && isSessionRecord(file.value) && file.value.sessionId === sessionId
|
|
1271
|
+
? file.value
|
|
1272
|
+
: null;
|
|
1273
|
+
if (record !== null && sessionLive(record, timing.alive, timing.startToken)) {
|
|
1274
|
+
scan.live.push(record);
|
|
1275
|
+
continue;
|
|
1276
|
+
}
|
|
1277
|
+
if (!sweep || (record === null && !isOlderThan(file.modifiedAt, staleBefore))) continue;
|
|
1278
|
+
await removeSession(paths, sessionId, record?.role ?? 'worker');
|
|
1279
|
+
scan.present.delete(sessionId);
|
|
1280
|
+
}
|
|
1281
|
+
return scan;
|
|
1282
|
+
}
|
|
1283
|
+
|
|
1284
|
+
/**
|
|
1285
|
+
* The room's live sessions. A record whose processes are gone is removed with
|
|
1286
|
+
* what it left (FR2), unless `sweep` is false; see `scanSessions` for records
|
|
1287
|
+
* this client cannot read.
|
|
1288
|
+
* @param {RoomPaths} paths
|
|
1289
|
+
* @param {BusClock & { sweep?: boolean }} [options]
|
|
1290
|
+
* @returns {Promise<SessionRecord[]>}
|
|
1291
|
+
*/
|
|
1292
|
+
export async function listSessions(paths, options = {}) {
|
|
1293
|
+
return (await scanSessions(paths, options)).live;
|
|
1294
|
+
}
|
|
1295
|
+
|
|
1296
|
+
/**
|
|
1297
|
+
* Inside the room lock: the room is still there and safe; directories a
|
|
1298
|
+
* damaged room lost are made again, and its descriptor too when this process
|
|
1299
|
+
* prepared the room.
|
|
1300
|
+
* @param {RoomPaths} paths
|
|
1301
|
+
* @param {{ stateRoot: string, room: RoomDescriptor } | null} prepared
|
|
1302
|
+
* @param {number} now
|
|
1303
|
+
*/
|
|
1304
|
+
async function confirmRoom(paths, prepared, now) {
|
|
1305
|
+
if (!(await roomIsSafe(paths))) throw new BusError('bus_unavailable', 'room_unsafe');
|
|
1306
|
+
for (const directory of roomDirectories(paths)) await ensurePrivateDirectory(directory);
|
|
1307
|
+
if (prepared !== null && (await readRoom(paths)) === null)
|
|
1308
|
+
await writeRoomFile(paths, prepared.room, now);
|
|
1309
|
+
}
|
|
1310
|
+
|
|
1311
|
+
/**
|
|
1312
|
+
* @param {unknown} error
|
|
1313
|
+
* @param {{ stateRoot: string, room: RoomDescriptor } | null} prepared
|
|
1314
|
+
*/
|
|
1315
|
+
function roomWasRemoved(error, prepared) {
|
|
1316
|
+
return (
|
|
1317
|
+
prepared !== null &&
|
|
1318
|
+
error instanceof BusError &&
|
|
1319
|
+
error.code === 'bus_unavailable' &&
|
|
1320
|
+
isRoomGone(error)
|
|
1321
|
+
);
|
|
1322
|
+
}
|
|
1323
|
+
|
|
1324
|
+
/**
|
|
1325
|
+
* Register one session under the room's lock (FR1): one live manager per room,
|
|
1326
|
+
* a worker name unique among the live sessions, at most sixteen workers. The
|
|
1327
|
+
* record gets the launcher's start time. A room a sweep removed between
|
|
1328
|
+
* `ensureRoom` and this call is built again, up to three times.
|
|
1329
|
+
* @param {RoomPaths} paths
|
|
1330
|
+
* @param {SessionRecord} record
|
|
1331
|
+
* @param {BusClock} [clock]
|
|
1332
|
+
*/
|
|
1333
|
+
export async function registerSession(paths, record, clock) {
|
|
1334
|
+
const timing = clockOf(clock);
|
|
1335
|
+
const normalized = normalizeSessionRecord(record);
|
|
1336
|
+
if (!isSessionRecord(normalized)) throw new BusError('bus_unavailable', 'session_record_invalid');
|
|
1337
|
+
/** @type {SessionRecord} */
|
|
1338
|
+
const complete = {
|
|
1339
|
+
...normalized,
|
|
1340
|
+
launcherStartTime: normalized.launcherStartTime ?? timing.startToken(normalized.launcherPid),
|
|
1341
|
+
childStartTime:
|
|
1342
|
+
normalized.childPid === null
|
|
1343
|
+
? null
|
|
1344
|
+
: (normalized.childStartTime ?? timing.startToken(normalized.childPid)),
|
|
1345
|
+
};
|
|
1346
|
+
const prepared = preparedRooms.get(paths) ?? null;
|
|
1347
|
+
for (let attempt = 1; ; attempt += 1) {
|
|
1348
|
+
try {
|
|
1349
|
+
await withRoomLock(paths, () => registerLocked(paths, complete, prepared, clock), clock);
|
|
1350
|
+
return;
|
|
1351
|
+
} catch (error) {
|
|
1352
|
+
if (!roomWasRemoved(error, prepared) || attempt >= REGISTER_ATTEMPTS_MAX) throw error;
|
|
1353
|
+
const again = /** @type {{ stateRoot: string, room: RoomDescriptor }} */ (prepared);
|
|
1354
|
+
await ensureRoom(again.stateRoot, again.room, clock);
|
|
1355
|
+
}
|
|
1356
|
+
}
|
|
1357
|
+
}
|
|
1358
|
+
|
|
1359
|
+
/**
|
|
1360
|
+
* @param {RoomPaths} paths
|
|
1361
|
+
* @param {SessionRecord} record
|
|
1362
|
+
* @param {{ stateRoot: string, room: RoomDescriptor } | null} prepared
|
|
1363
|
+
* @param {BusClock} [clock]
|
|
1364
|
+
*/
|
|
1365
|
+
async function registerLocked(paths, record, prepared, clock) {
|
|
1366
|
+
await confirmRoom(paths, prepared, clockOf(clock).now());
|
|
1367
|
+
const live = await listSessions(paths, clock);
|
|
1368
|
+
if (record.role === 'manager' && live.some((entry) => entry.role === 'manager'))
|
|
1369
|
+
throw new BusError('manager_already_active');
|
|
1370
|
+
if (record.role === 'worker') {
|
|
1371
|
+
if (live.some((entry) => entry.name === record.name)) throw new BusError('worker_name_taken');
|
|
1372
|
+
if (live.filter((entry) => entry.role === 'worker').length >= LIMITS.workersPerRoom)
|
|
1373
|
+
throw new BusError('room_full');
|
|
1374
|
+
}
|
|
1375
|
+
const recipient = recipientOf(record);
|
|
1376
|
+
await ensurePrivateDirectory(mailboxDirectory(paths, 'inbox', recipient));
|
|
1377
|
+
await ensurePrivateDirectory(mailboxDirectory(paths, 'claimed', recipient));
|
|
1378
|
+
await writeSession(paths, record);
|
|
1379
|
+
}
|
|
1380
|
+
|
|
1381
|
+
/**
|
|
1382
|
+
* The live manager of the room, or null.
|
|
1383
|
+
* @param {RoomPaths} paths
|
|
1384
|
+
* @param {BusClock} [clock]
|
|
1385
|
+
*/
|
|
1386
|
+
export async function liveManager(paths, clock) {
|
|
1387
|
+
const live = await listSessions(paths, { ...clock, sweep: false });
|
|
1388
|
+
return live.find((entry) => entry.role === 'manager') ?? null;
|
|
1389
|
+
}
|
|
1390
|
+
|
|
1391
|
+
// ------------------------------------------------------------------ audit
|
|
1392
|
+
|
|
1393
|
+
export const AUDIT_EVENTS = Object.freeze([
|
|
1394
|
+
'registered',
|
|
1395
|
+
'closed',
|
|
1396
|
+
'sent',
|
|
1397
|
+
'queued',
|
|
1398
|
+
'started',
|
|
1399
|
+
'replied',
|
|
1400
|
+
'expired',
|
|
1401
|
+
'refused',
|
|
1402
|
+
'cancelled',
|
|
1403
|
+
'rejected',
|
|
1404
|
+
'approval_wait',
|
|
1405
|
+
'delegated',
|
|
1406
|
+
'delegation_ended',
|
|
1407
|
+
'approval_held',
|
|
1408
|
+
'approval_outcome',
|
|
1409
|
+
]);
|
|
1410
|
+
|
|
1411
|
+
/**
|
|
1412
|
+
* One audit line (FR11). Every field is an id, a number or a short code, so
|
|
1413
|
+
* message text, command text and paths cannot be written here by mistake.
|
|
1414
|
+
* @typedef {object} AuditEvent
|
|
1415
|
+
* @property {(typeof AUDIT_EVENTS)[number]} event
|
|
1416
|
+
* @property {string} [sessionId]
|
|
1417
|
+
* @property {string} [peerSessionId]
|
|
1418
|
+
* @property {string} [messageId] the correlation id of the whole exchange
|
|
1419
|
+
* @property {number} [bytes]
|
|
1420
|
+
* @property {number} [count]
|
|
1421
|
+
* @property {string} [kind]
|
|
1422
|
+
* @property {string} [outcome]
|
|
1423
|
+
* @property {string} [reason]
|
|
1424
|
+
*/
|
|
1425
|
+
|
|
1426
|
+
const AUDIT_ID_FIELDS = /** @type {const} */ (['sessionId', 'peerSessionId', 'messageId']);
|
|
1427
|
+
const AUDIT_NUMBER_FIELDS = /** @type {const} */ (['bytes', 'count']);
|
|
1428
|
+
const AUDIT_CODE_FIELDS = /** @type {const} */ (['kind', 'outcome']);
|
|
1429
|
+
const AUDIT_ID_PATTERN = /^(?:manager|[0-9a-f]{32}|\d{13}-[0-9a-f]{16})$/u;
|
|
1430
|
+
|
|
1431
|
+
/**
|
|
1432
|
+
* The line that will be written for an event: unknown fields and values that
|
|
1433
|
+
* are not an id, a count or a code are dropped.
|
|
1434
|
+
* @param {AuditEvent} event
|
|
1435
|
+
* @param {number} at
|
|
1436
|
+
* @returns {Record<string, string | number> | null}
|
|
1437
|
+
*/
|
|
1438
|
+
export function auditLine(event, at) {
|
|
1439
|
+
if (!AUDIT_EVENTS.includes(event.event)) return null;
|
|
1440
|
+
/** @type {Record<string, string | number>} */
|
|
1441
|
+
const line = { at, event: event.event };
|
|
1442
|
+
for (const field of AUDIT_ID_FIELDS) {
|
|
1443
|
+
const value = event[field];
|
|
1444
|
+
if (typeof value === 'string' && AUDIT_ID_PATTERN.test(value)) line[field] = value;
|
|
1445
|
+
}
|
|
1446
|
+
for (const field of AUDIT_NUMBER_FIELDS) {
|
|
1447
|
+
const value = event[field];
|
|
1448
|
+
if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) line[field] = value;
|
|
1449
|
+
}
|
|
1450
|
+
for (const field of AUDIT_CODE_FIELDS) {
|
|
1451
|
+
const value = event[field];
|
|
1452
|
+
if (typeof value === 'string' && CODE_PATTERN.test(value)) line[field] = value;
|
|
1453
|
+
}
|
|
1454
|
+
if (typeof event.reason === 'string' && AUDIT_REASON_PATTERN.test(event.reason))
|
|
1455
|
+
line.reason = event.reason;
|
|
1456
|
+
return line;
|
|
1457
|
+
}
|
|
1458
|
+
|
|
1459
|
+
/**
|
|
1460
|
+
* Append one line to a private file opened without following a symlink and
|
|
1461
|
+
* without blocking: a regular file of this user, or nothing is written.
|
|
1462
|
+
* @param {string} path
|
|
1463
|
+
* @param {string} text
|
|
1464
|
+
*/
|
|
1465
|
+
async function appendPrivateLine(path, text) {
|
|
1466
|
+
const handle = await open(path, APPEND_FLAGS, PRIVATE_FILE_MODE);
|
|
1467
|
+
try {
|
|
1468
|
+
const entry = await handle.stat();
|
|
1469
|
+
if (!entry.isFile() || !ownedByUser(entry)) throw new BusError('bus_unavailable', 'not_a_file');
|
|
1470
|
+
await handle.writeFile(text);
|
|
1471
|
+
} finally {
|
|
1472
|
+
await handle.close().catch(() => undefined);
|
|
1473
|
+
}
|
|
1474
|
+
}
|
|
1475
|
+
|
|
1476
|
+
/**
|
|
1477
|
+
* Move a full JSON-lines file to `<file>.1`. With the room's paths this runs
|
|
1478
|
+
* under a lock of that file and checks the size again inside it, so two
|
|
1479
|
+
* writers that crossed the limit together rotate once and the previous file
|
|
1480
|
+
* survives. A busy lock skips the rotation; the line is still written.
|
|
1481
|
+
* @param {string} path
|
|
1482
|
+
* @param {number} rotateBytes
|
|
1483
|
+
* @param {{ paths?: RoomPaths, clock?: BusClock | undefined }} options
|
|
1484
|
+
*/
|
|
1485
|
+
async function rotateJsonLines(path, rotateBytes, options) {
|
|
1486
|
+
const rotate = async () => {
|
|
1487
|
+
const entry = await lstat(path).catch(() => null);
|
|
1488
|
+
if (entry !== null && entry.isFile() && entry.size >= rotateBytes)
|
|
1489
|
+
await rename(path, `${path}.1`);
|
|
1490
|
+
};
|
|
1491
|
+
if (options.paths === undefined) {
|
|
1492
|
+
await rotate().catch(() => undefined);
|
|
1493
|
+
return;
|
|
1494
|
+
}
|
|
1495
|
+
await withFileLock(`${path}.lock`, options.paths.tmp, rotate, options.clock).catch(
|
|
1496
|
+
() => undefined,
|
|
1497
|
+
);
|
|
1498
|
+
}
|
|
1499
|
+
|
|
1500
|
+
/**
|
|
1501
|
+
* Append one line to a private JSON-lines file, rotating it first when it is
|
|
1502
|
+
* over the limit (one previous file is kept). Pass the room's paths so that
|
|
1503
|
+
* concurrent writers rotate once (`rotateJsonLines`).
|
|
1504
|
+
* @param {string} path
|
|
1505
|
+
* @param {unknown} line
|
|
1506
|
+
* @param {number} rotateBytes
|
|
1507
|
+
* @param {{ paths?: RoomPaths, clock?: BusClock | undefined }} [options]
|
|
1508
|
+
*/
|
|
1509
|
+
export async function appendJsonLine(path, line, rotateBytes, options = {}) {
|
|
1510
|
+
const size = await lstat(path).then(
|
|
1511
|
+
(entry) => entry.size,
|
|
1512
|
+
() => 0,
|
|
1513
|
+
);
|
|
1514
|
+
if (size >= rotateBytes) await rotateJsonLines(path, rotateBytes, options);
|
|
1515
|
+
await appendPrivateLine(path, `${JSON.stringify(line)}\n`);
|
|
1516
|
+
}
|
|
1517
|
+
|
|
1518
|
+
/**
|
|
1519
|
+
* Write one audit line. Never throws: the audit must not stop a delivery.
|
|
1520
|
+
* @param {RoomPaths} paths
|
|
1521
|
+
* @param {AuditEvent} event
|
|
1522
|
+
* @param {BusClock} [clock]
|
|
1523
|
+
*/
|
|
1524
|
+
export async function audit(paths, event, clock) {
|
|
1525
|
+
try {
|
|
1526
|
+
const line = auditLine(event, clockOf(clock).now());
|
|
1527
|
+
if (line === null) return;
|
|
1528
|
+
await appendJsonLine(paths.audit, line, LIMITS.auditRotateBytes, { paths, clock });
|
|
1529
|
+
} catch {
|
|
1530
|
+
// The audit never stops what it records.
|
|
1531
|
+
}
|
|
1532
|
+
}
|
|
1533
|
+
|
|
1534
|
+
// ------------------------------------------------------------------ pending records
|
|
1535
|
+
|
|
1536
|
+
/**
|
|
1537
|
+
* One request without a final reply (FR2). The full typedef is
|
|
1538
|
+
* `PendingRecord` in `messages.mjs`; the sweep needs only its times.
|
|
1539
|
+
* @param {unknown} value
|
|
1540
|
+
* @returns {value is { schemaVersion: 1, messageId: string, workerSessionId: string, workerName: string, createdAt: number, expiresAt: number }}
|
|
1541
|
+
*/
|
|
1542
|
+
export function isPendingRecord(value) {
|
|
1543
|
+
if (!isPlainRecord(value)) return false;
|
|
1544
|
+
const keys = Object.keys(value);
|
|
1545
|
+
const expected = [
|
|
1546
|
+
'schemaVersion',
|
|
1547
|
+
'messageId',
|
|
1548
|
+
'workerSessionId',
|
|
1549
|
+
'workerName',
|
|
1550
|
+
'createdAt',
|
|
1551
|
+
'expiresAt',
|
|
1552
|
+
];
|
|
1553
|
+
if (keys.length !== expected.length || !keys.every((key) => expected.includes(key))) return false;
|
|
1554
|
+
return (
|
|
1555
|
+
value.schemaVersion === BUS_SCHEMA_VERSION &&
|
|
1556
|
+
typeof value.messageId === 'string' &&
|
|
1557
|
+
MESSAGE_ID_PATTERN.test(value.messageId) &&
|
|
1558
|
+
typeof value.workerSessionId === 'string' &&
|
|
1559
|
+
SESSION_ID_PATTERN.test(value.workerSessionId) &&
|
|
1560
|
+
typeof value.workerName === 'string' &&
|
|
1561
|
+
NAME_PATTERN.test(value.workerName) &&
|
|
1562
|
+
isTime(value.createdAt) &&
|
|
1563
|
+
isTime(value.expiresAt)
|
|
1564
|
+
);
|
|
1565
|
+
}
|
|
1566
|
+
|
|
1567
|
+
/**
|
|
1568
|
+
* How long a pending record is kept (FR3): 24 hours after its request was
|
|
1569
|
+
* created, or one hour after the request expired, whichever is later, so that
|
|
1570
|
+
* a turn that started late and ends after 24 hours still finds it.
|
|
1571
|
+
* @param {{ createdAt: number, expiresAt: number }} record
|
|
1572
|
+
*/
|
|
1573
|
+
export function pendingKeptUntil(record) {
|
|
1574
|
+
return Math.max(record.createdAt + LIMITS.retentionMs, record.expiresAt + LIMITS.pendingGraceMs);
|
|
1575
|
+
}
|
|
1576
|
+
|
|
1577
|
+
// ------------------------------------------------------------------ sweeps
|
|
1578
|
+
|
|
1579
|
+
/**
|
|
1580
|
+
* The time a bus entry was created: from its name when it is a message id,
|
|
1581
|
+
* from its modification time otherwise (never following a symlink).
|
|
1582
|
+
* @param {string} directory
|
|
1583
|
+
* @param {string} name
|
|
1584
|
+
* @param {boolean} byName
|
|
1585
|
+
* @returns {Promise<number | null>}
|
|
1586
|
+
*/
|
|
1587
|
+
async function entryCreatedAt(directory, name, byName) {
|
|
1588
|
+
const match = byName ? MESSAGE_TIME.exec(name) : null;
|
|
1589
|
+
if (match) return Number(match[1]);
|
|
1590
|
+
return lstat(join(directory, name)).then(
|
|
1591
|
+
(entry) => entry.mtimeMs,
|
|
1592
|
+
() => null,
|
|
1593
|
+
);
|
|
1594
|
+
}
|
|
1595
|
+
|
|
1596
|
+
/**
|
|
1597
|
+
* Remove the entries of one directory that are older than a limit, when it is
|
|
1598
|
+
* a real directory of this user (a recipient's mailbox may be a symlink).
|
|
1599
|
+
* @param {string} directory
|
|
1600
|
+
* @param {number} olderThan
|
|
1601
|
+
* @param {{ byName: boolean }} options
|
|
1602
|
+
* @returns {Promise<number>} entries still there
|
|
1603
|
+
*/
|
|
1604
|
+
async function sweepOlderThan(directory, olderThan, { byName }) {
|
|
1605
|
+
if ((await directoryState(directory)) !== 'directory') return 0;
|
|
1606
|
+
let names;
|
|
1607
|
+
try {
|
|
1608
|
+
names = await readdir(directory);
|
|
1609
|
+
} catch {
|
|
1610
|
+
return 0;
|
|
1611
|
+
}
|
|
1612
|
+
let kept = 0;
|
|
1613
|
+
for (const name of names) {
|
|
1614
|
+
if (isOlderThan(await entryCreatedAt(directory, name, byName), olderThan))
|
|
1615
|
+
await rm(join(directory, name), { recursive: true, force: true }).catch(() => undefined);
|
|
1616
|
+
else kept += 1;
|
|
1617
|
+
}
|
|
1618
|
+
return kept;
|
|
1619
|
+
}
|
|
1620
|
+
|
|
1621
|
+
/**
|
|
1622
|
+
* The directories of worker recipients that no session record names any
|
|
1623
|
+
* more. An entry that is not a session id is removed only a day after its
|
|
1624
|
+
* last change.
|
|
1625
|
+
* @param {string} box
|
|
1626
|
+
* @param {Set<string>} present
|
|
1627
|
+
* @param {number} staleBefore
|
|
1628
|
+
*/
|
|
1629
|
+
async function sweepOrphanMailboxes(box, present, staleBefore) {
|
|
1630
|
+
let names;
|
|
1631
|
+
try {
|
|
1632
|
+
names = await readdir(box);
|
|
1633
|
+
} catch {
|
|
1634
|
+
return;
|
|
1635
|
+
}
|
|
1636
|
+
for (const name of names) {
|
|
1637
|
+
if (name === MANAGER_RECIPIENT || present.has(name)) continue;
|
|
1638
|
+
if (
|
|
1639
|
+
!SESSION_ID_PATTERN.test(name) &&
|
|
1640
|
+
!isOlderThan(await entryCreatedAt(box, name, false), staleBefore)
|
|
1641
|
+
)
|
|
1642
|
+
continue;
|
|
1643
|
+
await rm(join(box, name), { recursive: true, force: true }).catch(() => undefined);
|
|
1644
|
+
}
|
|
1645
|
+
}
|
|
1646
|
+
|
|
1647
|
+
/**
|
|
1648
|
+
* Grants of workers that no session record names any more. An entry that is
|
|
1649
|
+
* not a grant's name is removed only a day after its last change.
|
|
1650
|
+
* @param {RoomPaths} paths
|
|
1651
|
+
* @param {Set<string>} present
|
|
1652
|
+
* @param {number} staleBefore
|
|
1653
|
+
*/
|
|
1654
|
+
async function sweepGrants(paths, present, staleBefore) {
|
|
1655
|
+
const names = await readdir(paths.delegation).catch(() => []);
|
|
1656
|
+
for (const name of names) {
|
|
1657
|
+
const sessionId = name.endsWith(JSON_SUFFIX) ? name.slice(0, -JSON_SUFFIX.length) : null;
|
|
1658
|
+
const isGrantName = sessionId !== null && SESSION_ID_PATTERN.test(sessionId);
|
|
1659
|
+
if (isGrantName && present.has(/** @type {string} */ (sessionId))) continue;
|
|
1660
|
+
if (
|
|
1661
|
+
!isGrantName &&
|
|
1662
|
+
!isOlderThan(await entryCreatedAt(paths.delegation, name, false), staleBefore)
|
|
1663
|
+
)
|
|
1664
|
+
continue;
|
|
1665
|
+
await rm(join(paths.delegation, name), { recursive: true, force: true }).catch(() => undefined);
|
|
1666
|
+
}
|
|
1667
|
+
}
|
|
1668
|
+
|
|
1669
|
+
/**
|
|
1670
|
+
* Pending records past `pendingKeptUntil` are removed; a file that is not a
|
|
1671
|
+
* pending record a day after its last change.
|
|
1672
|
+
* @param {RoomPaths} paths
|
|
1673
|
+
* @param {number} now
|
|
1674
|
+
* @returns {Promise<number>} pending records still kept
|
|
1675
|
+
*/
|
|
1676
|
+
async function sweepPending(paths, now) {
|
|
1677
|
+
const names = await readdir(paths.pending).catch(() => []);
|
|
1678
|
+
let kept = 0;
|
|
1679
|
+
for (const name of names) {
|
|
1680
|
+
const path = join(paths.pending, name);
|
|
1681
|
+
const file = await readJsonFile(path, PENDING_FILE_BYTES_MAX);
|
|
1682
|
+
if (!file.ok && file.reason === 'missing') continue;
|
|
1683
|
+
if (!file.ok && file.reason === 'io_error') {
|
|
1684
|
+
kept += 1;
|
|
1685
|
+
continue;
|
|
1686
|
+
}
|
|
1687
|
+
const record = file.ok && isPendingRecord(file.value) ? file.value : null;
|
|
1688
|
+
if (record !== null && `${record.messageId}${JSON_SUFFIX}` === name) {
|
|
1689
|
+
if (now < pendingKeptUntil(record)) kept += 1;
|
|
1690
|
+
else await removeIfUnchanged(path, file.ino);
|
|
1691
|
+
continue;
|
|
1692
|
+
}
|
|
1693
|
+
if (isOlderThan(file.modifiedAt, now - LIMITS.retentionMs))
|
|
1694
|
+
await rm(path, { recursive: true, force: true }).catch(() => undefined);
|
|
1695
|
+
}
|
|
1696
|
+
return kept;
|
|
1697
|
+
}
|
|
1698
|
+
|
|
1699
|
+
/**
|
|
1700
|
+
* The decision record and its previous file, each deleted thirty days after
|
|
1701
|
+
* its last line (FR13).
|
|
1702
|
+
* @param {RoomPaths} paths
|
|
1703
|
+
* @param {number} now
|
|
1704
|
+
* @returns {Promise<boolean>} whether any of them is still kept
|
|
1705
|
+
*/
|
|
1706
|
+
async function purgeDecisions(paths, now) {
|
|
1707
|
+
let kept = false;
|
|
1708
|
+
for (const file of [paths.decisions, `${paths.decisions}.1`]) {
|
|
1709
|
+
const entry = await lstat(file).catch(() => null);
|
|
1710
|
+
if (entry === null) continue;
|
|
1711
|
+
if (now - entry.mtimeMs <= LIMITS.decisionsRetentionMs) kept = true;
|
|
1712
|
+
else await rm(file, { force: true }).catch(() => undefined);
|
|
1713
|
+
}
|
|
1714
|
+
return kept;
|
|
1715
|
+
}
|
|
1716
|
+
|
|
1717
|
+
/**
|
|
1718
|
+
* @typedef {object} RoomLeft
|
|
1719
|
+
* @property {number} sessions live sessions
|
|
1720
|
+
* @property {number} records session records still there, live or not
|
|
1721
|
+
* @property {number} pending pending records still kept
|
|
1722
|
+
* @property {boolean} decisions a decision record younger than thirty days
|
|
1723
|
+
*/
|
|
1724
|
+
|
|
1725
|
+
/**
|
|
1726
|
+
* The destructive part of a sweep, called under the room lock once the room
|
|
1727
|
+
* is known to be safe (FR2, FR3, D12, FR13).
|
|
1728
|
+
* @param {RoomPaths} paths
|
|
1729
|
+
* @param {BusClock} [clock]
|
|
1730
|
+
* @returns {Promise<RoomLeft>}
|
|
1731
|
+
*/
|
|
1732
|
+
async function sweepRoomContents(paths, clock) {
|
|
1733
|
+
const { now } = clockOf(clock);
|
|
1734
|
+
const { live, present } = await scanSessions(paths, clock);
|
|
1735
|
+
const at = now();
|
|
1736
|
+
const staleBefore = at - LIMITS.retentionMs;
|
|
1737
|
+
await sweepOrphanMailboxes(paths.inbox, present, staleBefore);
|
|
1738
|
+
await sweepOrphanMailboxes(paths.claimed, present, staleBefore);
|
|
1739
|
+
// Message bodies live 24 hours, whoever their recipient is (D12).
|
|
1740
|
+
for (const recipient of [MANAGER_RECIPIENT, ...present])
|
|
1741
|
+
for (const box of /** @type {const} */ (['inbox', 'claimed']))
|
|
1742
|
+
await sweepOlderThan(mailboxDirectory(paths, box, recipient), staleBefore, {
|
|
1743
|
+
byName: true,
|
|
1744
|
+
});
|
|
1745
|
+
const pending = await sweepPending(paths, at);
|
|
1746
|
+
await sweepOlderThan(paths.tmp, at - TEMPORARY_FILE_MAX_AGE_MS, { byName: false });
|
|
1747
|
+
await sweepGrants(paths, present, staleBefore);
|
|
1748
|
+
const decisions = await purgeDecisions(paths, at);
|
|
1749
|
+
return { sessions: live.length, records: present.size, pending, decisions };
|
|
1750
|
+
}
|
|
1751
|
+
|
|
1752
|
+
/**
|
|
1753
|
+
* Sweep one room (FR2, FR3): sessions whose processes are gone with what they
|
|
1754
|
+
* left, message bodies, pending records and temporary files past their time,
|
|
1755
|
+
* grants of workers that are gone, a decision record past thirty days. A room
|
|
1756
|
+
* whose directories are not real directories of this user is left alone; the
|
|
1757
|
+
* rest runs under the room lock. Never throws.
|
|
1758
|
+
* @param {RoomPaths} paths
|
|
1759
|
+
* @param {BusClock} [clock]
|
|
1760
|
+
* @returns {Promise<{ sessions: number, pending: number }>} what is still live
|
|
1761
|
+
*/
|
|
1762
|
+
export async function sweepRoom(paths, clock) {
|
|
1763
|
+
const nothing = { sessions: 0, pending: 0 };
|
|
1764
|
+
try {
|
|
1765
|
+
if (!(await roomIsSafe(paths))) return nothing;
|
|
1766
|
+
const left = await withRoomLock(
|
|
1767
|
+
paths,
|
|
1768
|
+
async () => ((await roomIsSafe(paths)) ? sweepRoomContents(paths, clock) : null),
|
|
1769
|
+
clock,
|
|
1770
|
+
);
|
|
1771
|
+
return left === null ? nothing : { sessions: left.sessions, pending: left.pending };
|
|
1772
|
+
} catch {
|
|
1773
|
+
return nothing;
|
|
1774
|
+
}
|
|
1775
|
+
}
|
|
1776
|
+
|
|
1777
|
+
/**
|
|
1778
|
+
* Sweep one room and, when nothing is left in it, remove it: renamed aside
|
|
1779
|
+
* under its lock, so that a launch waiting for the lock finds the room gone
|
|
1780
|
+
* and builds it again, then deleted.
|
|
1781
|
+
* @param {RoomPaths} paths
|
|
1782
|
+
* @param {BusClock} [clock]
|
|
1783
|
+
* @returns {Promise<boolean>} whether the room was removed
|
|
1784
|
+
*/
|
|
1785
|
+
async function sweepOrRemoveRoom(paths, clock) {
|
|
1786
|
+
if (!(await roomIsSafe(paths))) return false;
|
|
1787
|
+
let aside = null;
|
|
1788
|
+
try {
|
|
1789
|
+
aside = await withRoomLock(
|
|
1790
|
+
paths,
|
|
1791
|
+
async () => {
|
|
1792
|
+
if (!(await roomIsSafe(paths))) return null;
|
|
1793
|
+
const left = await sweepRoomContents(paths, clock);
|
|
1794
|
+
if (left.sessions > 0 || left.records > 0 || left.pending > 0 || left.decisions)
|
|
1795
|
+
return null;
|
|
1796
|
+
const target = join(paths.rooms, `.removed-${newSessionId()}`);
|
|
1797
|
+
await rename(paths.room, target);
|
|
1798
|
+
return target;
|
|
1799
|
+
},
|
|
1800
|
+
clock,
|
|
1801
|
+
);
|
|
1802
|
+
} catch {
|
|
1803
|
+
return false;
|
|
1804
|
+
}
|
|
1805
|
+
if (aside === null) return false;
|
|
1806
|
+
await rm(aside, { recursive: true, force: true }).catch(() => undefined);
|
|
1807
|
+
return true;
|
|
1808
|
+
}
|
|
1809
|
+
|
|
1810
|
+
/**
|
|
1811
|
+
* Sweep every room of the bus, and remove a room that has no session record,
|
|
1812
|
+
* no pending record still kept and no decision record left to review. Called
|
|
1813
|
+
* by each launch and each listing, like `sweepStaleLaunches`. Never throws.
|
|
1814
|
+
* @param {string} stateRoot
|
|
1815
|
+
* @param {BusClock} [clock]
|
|
1816
|
+
* @returns {Promise<number>} rooms removed
|
|
1817
|
+
*/
|
|
1818
|
+
export async function sweepBus(stateRoot, clock) {
|
|
1819
|
+
try {
|
|
1820
|
+
const bus = busRoot(stateRoot);
|
|
1821
|
+
const rooms = join(bus, 'rooms');
|
|
1822
|
+
if ((await directoryState(bus)) !== 'directory') return 0;
|
|
1823
|
+
if ((await directoryState(rooms)) !== 'directory') return 0;
|
|
1824
|
+
const entries = await readdir(rooms, { withFileTypes: true }).catch(() => []);
|
|
1825
|
+
let removed = 0;
|
|
1826
|
+
for (const entry of entries) {
|
|
1827
|
+
if (!entry.isDirectory()) continue;
|
|
1828
|
+
if (REMOVED_ROOM_PATTERN.test(entry.name)) {
|
|
1829
|
+
// Left by a sweep that stopped between its rename and its delete.
|
|
1830
|
+
await rm(join(rooms, entry.name), { recursive: true, force: true }).catch(() => undefined);
|
|
1831
|
+
continue;
|
|
1832
|
+
}
|
|
1833
|
+
if (!ROOM_ID_PATTERN.test(entry.name)) continue;
|
|
1834
|
+
if (await sweepOrRemoveRoom(roomPaths(stateRoot, entry.name), clock)) removed += 1;
|
|
1835
|
+
}
|
|
1836
|
+
return removed;
|
|
1837
|
+
} catch {
|
|
1838
|
+
return 0;
|
|
1839
|
+
}
|
|
1840
|
+
}
|
|
1841
|
+
|
|
1842
|
+
/**
|
|
1843
|
+
* Every room of the bus with its descriptor, for `aisac doctor` and listings.
|
|
1844
|
+
* @param {string} stateRoot
|
|
1845
|
+
* @returns {Promise<{ descriptor: RoomDescriptor, paths: RoomPaths }[]>}
|
|
1846
|
+
*/
|
|
1847
|
+
export async function listRooms(stateRoot) {
|
|
1848
|
+
const rooms = join(busRoot(stateRoot), 'rooms');
|
|
1849
|
+
const entries = await readdir(rooms, { withFileTypes: true }).catch(() => []);
|
|
1850
|
+
/** @type {{ descriptor: RoomDescriptor, paths: RoomPaths }[]} */
|
|
1851
|
+
const found = [];
|
|
1852
|
+
for (const entry of entries.sort((left, right) => (left.name < right.name ? -1 : 1))) {
|
|
1853
|
+
if (!entry.isDirectory() || !ROOM_ID_PATTERN.test(entry.name)) continue;
|
|
1854
|
+
const paths = roomPaths(stateRoot, entry.name);
|
|
1855
|
+
const descriptor = await readRoom(paths);
|
|
1856
|
+
if (descriptor !== null && descriptor.id === entry.name) found.push({ descriptor, paths });
|
|
1857
|
+
}
|
|
1858
|
+
return found;
|
|
1859
|
+
}
|
|
1860
|
+
|
|
1861
|
+
// ------------------------------------------------------------------ the role environment
|
|
1862
|
+
|
|
1863
|
+
/**
|
|
1864
|
+
* @typedef {object} RoleEnvironment
|
|
1865
|
+
* @property {1} schemaVersion
|
|
1866
|
+
* @property {Role} role
|
|
1867
|
+
* @property {string} stateRoot
|
|
1868
|
+
* @property {string} roomId
|
|
1869
|
+
* @property {string} sessionId
|
|
1870
|
+
* @property {string} name
|
|
1871
|
+
* @property {BusLocale} locale
|
|
1872
|
+
*/
|
|
1873
|
+
|
|
1874
|
+
/**
|
|
1875
|
+
* The value the launcher puts in `AISAC_WORKER_ROLE` or `AISAC_MANAGER_ROLE`.
|
|
1876
|
+
* Identity reaches a role process only this way (spec §8).
|
|
1877
|
+
* @param {Omit<RoleEnvironment, 'schemaVersion'>} role
|
|
1878
|
+
*/
|
|
1879
|
+
export function roleEnvironmentValue(role) {
|
|
1880
|
+
return JSON.stringify({ schemaVersion: BUS_SCHEMA_VERSION, ...role });
|
|
1881
|
+
}
|
|
1882
|
+
|
|
1883
|
+
const ROLE_KEYS = ['schemaVersion', 'role', 'stateRoot', 'roomId', 'sessionId', 'name', 'locale'];
|
|
1884
|
+
const ROLE_VALUE_BYTES_MAX = 8 * KIBIBYTE;
|
|
1885
|
+
|
|
1886
|
+
/**
|
|
1887
|
+
* Parse the role a launcher handed to this process. Anything that is not
|
|
1888
|
+
* exactly the expected shape is no role at all.
|
|
1889
|
+
* @param {string | undefined} value
|
|
1890
|
+
* @param {Role} role
|
|
1891
|
+
* @returns {RoleEnvironment | null}
|
|
1892
|
+
*/
|
|
1893
|
+
export function parseRoleEnvironment(value, role) {
|
|
1894
|
+
if (typeof value !== 'string' || value.length === 0 || value.length > ROLE_VALUE_BYTES_MAX)
|
|
1895
|
+
return null;
|
|
1896
|
+
/** @type {unknown} */
|
|
1897
|
+
let parsed;
|
|
1898
|
+
try {
|
|
1899
|
+
parsed = JSON.parse(value);
|
|
1900
|
+
} catch {
|
|
1901
|
+
return null;
|
|
1902
|
+
}
|
|
1903
|
+
if (!isPlainRecord(parsed)) return null;
|
|
1904
|
+
const keys = Object.keys(parsed);
|
|
1905
|
+
if (keys.length !== ROLE_KEYS.length || keys.some((key) => !ROLE_KEYS.includes(key))) return null;
|
|
1906
|
+
const { stateRoot, roomId, sessionId, name, locale } = parsed;
|
|
1907
|
+
if (parsed.schemaVersion !== BUS_SCHEMA_VERSION || parsed.role !== role) return null;
|
|
1908
|
+
if (
|
|
1909
|
+
typeof stateRoot !== 'string' ||
|
|
1910
|
+
!stateRoot.startsWith('/') ||
|
|
1911
|
+
resolve(stateRoot) !== stateRoot
|
|
1912
|
+
)
|
|
1913
|
+
return null;
|
|
1914
|
+
if (stateRoot.length > PATH_LENGTH_MAX) return null;
|
|
1915
|
+
if (typeof roomId !== 'string' || !ROOM_ID_PATTERN.test(roomId)) return null;
|
|
1916
|
+
if (typeof sessionId !== 'string' || !SESSION_ID_PATTERN.test(sessionId)) return null;
|
|
1917
|
+
if (typeof name !== 'string' || !NAME_PATTERN.test(name)) return null;
|
|
1918
|
+
if ((role === 'manager') !== (name === MANAGER_NAME)) return null;
|
|
1919
|
+
if (locale !== 'pt-BR' && locale !== 'en') return null;
|
|
1920
|
+
return { schemaVersion: BUS_SCHEMA_VERSION, role, stateRoot, roomId, sessionId, name, locale };
|
|
1921
|
+
}
|