@smoothbricks/nx-plugin 0.7.5 → 0.7.6

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.
Files changed (47) hide show
  1. package/README.md +20 -3
  2. package/dist/.build-inputs.json +11 -5
  3. package/dist/executors/bounded-exec/cpu-pool-thread.d.ts +3 -2
  4. package/dist/executors/bounded-exec/cpu-pool-thread.d.ts.map +1 -1
  5. package/dist/executors/bounded-exec/cpu-pool-thread.js +1 -1
  6. package/dist/executors/bounded-exec/cpu-pool.d.ts +24 -10
  7. package/dist/executors/bounded-exec/cpu-pool.d.ts.map +1 -1
  8. package/dist/executors/bounded-exec/cpu-pool.js +96 -52
  9. package/dist/executors/bounded-exec/executor.d.ts.map +1 -1
  10. package/dist/executors/bounded-exec/executor.js +98 -45
  11. package/dist/executors/bounded-exec/host-memory.d.ts +47 -0
  12. package/dist/executors/bounded-exec/host-memory.d.ts.map +1 -0
  13. package/dist/executors/bounded-exec/host-memory.darwin.d.ts +3 -0
  14. package/dist/executors/bounded-exec/host-memory.darwin.d.ts.map +1 -0
  15. package/dist/executors/bounded-exec/host-memory.darwin.js +40 -0
  16. package/dist/executors/bounded-exec/host-memory.js +29 -0
  17. package/dist/executors/bounded-exec/host-memory.linux.d.ts +14 -0
  18. package/dist/executors/bounded-exec/host-memory.linux.d.ts.map +1 -0
  19. package/dist/executors/bounded-exec/host-memory.linux.js +104 -0
  20. package/dist/executors/bounded-exec/leaf-peak.d.ts +55 -0
  21. package/dist/executors/bounded-exec/leaf-peak.d.ts.map +1 -0
  22. package/dist/executors/bounded-exec/leaf-peak.js +146 -0
  23. package/dist/executors/bounded-exec/peak-waiter.d.ts +2 -0
  24. package/dist/executors/bounded-exec/peak-waiter.d.ts.map +1 -0
  25. package/dist/executors/bounded-exec/peak-waiter.js +53 -0
  26. package/dist/executors/bounded-exec/pool-admission.d.ts +38 -0
  27. package/dist/executors/bounded-exec/pool-admission.d.ts.map +1 -0
  28. package/dist/executors/bounded-exec/pool-admission.js +31 -0
  29. package/dist/executors/bounded-exec/run-cpu-pool.d.ts +6 -4
  30. package/dist/executors/bounded-exec/run-cpu-pool.d.ts.map +1 -1
  31. package/dist/executors/bounded-exec/run-cpu-pool.js +20 -7
  32. package/dist/executors/bounded-exec/verdict.d.ts +18 -0
  33. package/dist/executors/bounded-exec/verdict.d.ts.map +1 -1
  34. package/dist/executors/bounded-exec/verdict.js +21 -1
  35. package/package.json +1 -1
  36. package/src/executors/bounded-exec/cpu-pool-thread.ts +4 -3
  37. package/src/executors/bounded-exec/cpu-pool.ts +111 -49
  38. package/src/executors/bounded-exec/executor.ts +103 -41
  39. package/src/executors/bounded-exec/host-memory.darwin.ts +44 -0
  40. package/src/executors/bounded-exec/host-memory.linux.ts +115 -0
  41. package/src/executors/bounded-exec/host-memory.ts +70 -0
  42. package/src/executors/bounded-exec/leaf-peak.ts +151 -0
  43. package/src/executors/bounded-exec/peak-waiter.ts +82 -0
  44. package/src/executors/bounded-exec/pool-admission.ts +64 -0
  45. package/src/executors/bounded-exec/run-cpu-pool.ts +20 -6
  46. package/src/executors/bounded-exec/verdict.ts +30 -1
  47. package/test-timings.json +134 -132
@@ -11,6 +11,7 @@ import { admissionWaitMs, earliestBound, NO_ADMISSION_WAIT, stepAdmissionWait, s
11
11
  import { CPU_POOL_ENV, createCpuPool, readInheritedCpuPool, takeParentCpuTokens, } from './cpu-pool.js';
12
12
  import { GATEWAY_SOCKET } from './gateway-lease.js';
13
13
  import { captureHangDiagnostics, HANG_CAPTURE_MS } from './hang-diagnostics.js';
14
+ import { PEAK_FD, peakWaiter, readWaiterReport, underWaiter } from './leaf-peak.js';
14
15
  import { askedCores, MBX_GRANT_FD, mbxIdleGated, mbxLeaf, mbxPool, withCountedReservation, withMbxLeaf, } from './mbx-pool.js';
15
16
  import { MBX_QUEUE_POLL_MS, snapshotMbxQueue } from './mbx-queue.js';
16
17
  import { RESERVATIONS_ENV, reserveCores } from './mbx-reservations.js';
@@ -22,7 +23,7 @@ import { createRunnerLifecycle, withFixtureLifecycle, withRunnerLifecycle } from
22
23
  import { CPU_TOKENS_ENV, runnerDemand, sizeRunner, sizeRunnerToGrant } from './runner-sizing.js';
23
24
  import { checkRuntimePin, describeRuntimePinRefusal } from './runtime-pin.js';
24
25
  import { createTestResultWriter } from './test-result-writer.js';
25
- import { BUN_TEST, clearTaskDirectory, describeAdmissionQueue, describeNoSpace, JUNIT_FILE, JUNIT_REPORT_ENV, judgeOperationalFailure, judgeRun, readJunitReport, taskDirectory, withJunitReport, writeRecord, } from './verdict.js';
26
+ import { BUN_TEST, clearTaskDirectory, describeAdmissionQueue, describeNoSpace, JUNIT_FILE, JUNIT_REPORT_ENV, judgeOperationalFailure, judgeRun, readJunitReport, readLastPeak, taskDirectory, withJunitReport, writeRecord, } from './verdict.js';
26
27
  const DEFAULT_KILL_AFTER_MS = 10_000;
27
28
  const REAP_AFTER_FORCE_KILL_MS = 2_000;
28
29
  const EXIT_CODE_BY_SIGNAL = {
@@ -148,6 +149,8 @@ export function recordContext(context) {
148
149
  export async function runBoundedExec(options, context, killer, tempVolume, inherited = null, captureDiagnostics = captureHangDiagnostics, owner = null, queueHost) {
149
150
  const cwd = resolveCwd(options.cwd, context.root);
150
151
  const directory = context.record?.directory ?? null;
152
+ // The task's last recorded peak is its charge in its parent's pool, read before the clear below removes it.
153
+ const lastPeak = directory !== null && inherited !== null ? await readLastPeak(directory) : null;
151
154
  // A previous run's verdict and report go first, so neither can be read as this run's.
152
155
  if (directory !== null) {
153
156
  await clearTaskDirectory(directory);
@@ -196,17 +199,26 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
196
199
  // Nobody is left to tell.
197
200
  }
198
201
  };
202
+ // A run refused before its command exists says why and records an operational failure, and no peak: nothing ran.
203
+ const refuseUnstarted = async (message) => {
204
+ appendStderr(message);
205
+ if (context.record !== undefined) {
206
+ const { task, directory: recordDirectory } = context.record;
207
+ await writeRecord(recordDirectory, {
208
+ task: task.id,
209
+ hash: task.hash,
210
+ verdict: judgeOperationalFailure(1, null),
211
+ peakBytes: null,
212
+ });
213
+ }
214
+ return { success: false, terminalOutput: outputChunks.join('') };
215
+ };
199
216
  // The fixture pair names one segment: a fixture with no build budget, or a budget with no fixture, is a
200
217
  // target that does not say what it runs, so it does not run. Units are counted at the end of that segment.
201
218
  if ((options.fixtureCommand === undefined) !== (options.fixtureTimeoutMs === undefined) ||
202
219
  (options.unitsCommand !== undefined && options.fixtureCommand === undefined) ||
203
220
  (fixture !== null && !(fixture.timeoutMs > 0))) {
204
- appendStderr('bounded-exec: fixtureCommand and a positive fixtureTimeoutMs must be named together, and unitsCommand only with them; refusing to run the command\n');
205
- if (context.record !== undefined) {
206
- const { task, directory: recordDirectory } = context.record;
207
- await writeRecord(recordDirectory, { task: task.id, hash: task.hash, verdict: judgeOperationalFailure(1, null) });
208
- }
209
- return { success: false, terminalOutput: outputChunks.join('') };
221
+ return refuseUnstarted('bounded-exec: fixtureCommand and a positive fixtureTimeoutMs must be named together, and unitsCommand only with them; refusing to run the command\n');
210
222
  }
211
223
  // A leg that runs bun runs the Bun its workspace declares, or it does not run. This comes before the RAM lease and the
212
224
  // CPU tokens: a refusal that waited in its pool's queue first would say nothing for minutes.
@@ -218,13 +230,13 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
218
230
  pathSource: options.env?.PATH === undefined ? 'the inherited environment' : "the target's env",
219
231
  });
220
232
  if (runtime !== null) {
221
- appendStderr(describeRuntimePinRefusal(runtime, context.record?.task.id));
222
- if (context.record !== undefined) {
223
- const { task, directory: recordDirectory } = context.record;
224
- await writeRecord(recordDirectory, { task: task.id, hash: task.hash, verdict: judgeOperationalFailure(1, null) });
225
- }
226
- return { success: false, terminalOutput: outputChunks.join('') };
233
+ return refuseUnstarted(describeRuntimePinRefusal(runtime, context.record?.task.id));
234
+ }
235
+ if (lastPeak !== null && !lastPeak.ok) {
236
+ return refuseUnstarted(`bounded-exec: ${lastPeak.error}; it is this task's memory charge, so the command does not run\n`);
227
237
  }
238
+ // A task with no recorded peak is charged nothing (null) until it has one.
239
+ const charge = lastPeak?.ok === true ? lastPeak.peakBytes : null;
228
240
  let lease = null;
229
241
  let ordinaryTemp = null;
230
242
  // Before spawn there is nothing to retire. Once started, only the owner's terminal retirement permits deletion.
@@ -364,7 +376,7 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
364
376
  let parentRefusal = null;
365
377
  let parentWait;
366
378
  if (inherited !== null) {
367
- const fromParent = await takeParentCpuTokens(inherited, demand.want);
379
+ const fromParent = await takeParentCpuTokens(inherited, demand.want, charge);
368
380
  if (fromParent.granted) {
369
381
  grant = fromParent;
370
382
  }
@@ -386,7 +398,10 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
386
398
  if (grant !== null) {
387
399
  sized = sizeRunner(demand, requested, grant.tokens);
388
400
  cpu = { tokens: grant.tokens, want: demand.want, waitedMs };
389
- appendStderr(`cowshed: cpu-pool wait done elapsed=${waitedMs}ms status=ok tokens=${grant.tokens}/${demand.want} runner=${demand.kind}\n`);
401
+ appendStderr(`cowshed: cpu-pool wait done elapsed=${waitedMs}ms status=ok tokens=${grant.tokens}/${demand.want} runner=${demand.kind} memory=${charge ?? 'none'}\n`);
402
+ if (grant.oversized !== null) {
403
+ appendStderr(`cowshed: cpu-pool granted while nothing else holds memory: this task's last peak of ${charge} bytes alone exceeds the run's ${grant.oversized.memory} bytes\n`);
404
+ }
390
405
  }
391
406
  else if (leaf?.kind === 'reserve') {
392
407
  sized = { command: sizeRunnerToGrant(leaf.demand, requested), env: {} };
@@ -444,7 +459,7 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
444
459
  };
445
460
  // Records the run's verdict when it has a task to record as. An `expiry` is set only when a bound ended the run.
446
461
  // Observation and ownership failures remain operational even after valid queue evidence; cancellation alone does not.
447
- const recordRun = async (exitCode, expiry, elapsedMs, operational, noSpace, lockWaits) => {
462
+ const recordRun = async (exitCode, expiry, elapsedMs, operational, noSpace, lockWaits, peakBytes) => {
448
463
  if (context.record === undefined) {
449
464
  return;
450
465
  }
@@ -485,6 +500,7 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
485
500
  verdict,
486
501
  ...(cpu ? { cpu } : {}),
487
502
  ...(parentWait ? { cpuWait: parentWait } : {}),
503
+ peakBytes,
488
504
  });
489
505
  };
490
506
  // A run refused before its command starts says why, gives back its grant and RAM, and records the failure.
@@ -493,7 +509,7 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
493
509
  await releaseCpu();
494
510
  // The command never started, so its lease holds nothing of its own to keep.
495
511
  await releaseLease(false);
496
- await recordRun(1, null, Date.now() - asked, false, null, []);
512
+ await recordRun(1, null, Date.now() - asked, false, null, [], null);
497
513
  return { success: false, terminalOutput: outputChunks.join('') };
498
514
  };
499
515
  if (parentRefusal !== null) {
@@ -508,7 +524,7 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
508
524
  // A granted run serves a sub-pool of its own grant, so its descendants draw from that and never from above it.
509
525
  // A pool that cannot be set up refuses the run: no granted command runs beside its grant.
510
526
  if (grant !== null) {
511
- const created = await createCpuPool(grant.tokens, grant.closed);
527
+ const created = await createCpuPool(grant.tokens, grant.closed, null);
512
528
  if (!created.ok) {
513
529
  return refuse(`cowshed: cpu pool unavailable: ${created.error}; refusing to run the command\n`);
514
530
  }
@@ -555,6 +571,17 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
555
571
  const grantSlots = leaf !== null ? ['ignore', 'pipe'] : [];
556
572
  const rootGrantSlot = leaf !== null ? ['pipe'] : [];
557
573
  const root = owner?.rootArgv(shellCommand);
574
+ // The command's own descriptors past stderr, from fd 3: the lifecycle channel, the subtree admission, mbx's grant.
575
+ const descriptors = root === undefined
576
+ ? hooked === null && leaf === null
577
+ ? []
578
+ : [hooked === null ? 'ignore' : 'pipe', ...grantSlots]
579
+ : [hooked === null ? 'ignore' : 'pipe', 'pipe', ...rootGrantSlot];
580
+ // A run that records its verdict records its command's peak too: the command runs under a waiter that reports it.
581
+ const waiter = context.record === undefined ? null : peakWaiter();
582
+ const measured = waiter?.kind === 'waiter'
583
+ ? underWaiter(waiter.runtime, root?.file ?? '/bin/sh', root?.args ?? ['-c', shellCommand], descriptors)
584
+ : null;
558
585
  let child;
559
586
  const results = directory === null ? null : await createTestResultWriter(directory, { cwd, root: context.root });
560
587
  if (results !== null && !results.ok)
@@ -562,32 +589,48 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
562
589
  resultWriter = results?.ok ? results.writer : null;
563
590
  try {
564
591
  // fd 3 is the runner lifecycle's duplex socket when the command is hooked; the subtree admission takes fd 4, which
565
- // cowshed closes fd 4 before exec; fd 5 is a Cargo leaf's mbx admission stream or a reserved leaf's ask and grant.
592
+ // cowshed closes fd 4 before exec; fd 5 is a Cargo leaf's mbx admission stream or a reserved leaf's ask and grant;
593
+ // the waiter, when there is one, passes them on and reports the command's peak on fd 6.
566
594
  child =
567
- root === undefined
568
- ? spawn(shellCommand, [], {
595
+ measured !== null
596
+ ? spawn(measured.file, measured.args, {
569
597
  cwd,
570
598
  env: mergeEnv(lease?.directory ?? ordinaryTemp, env),
571
- shell: true,
572
- stdio: hooked === null && leaf === null
573
- ? 'pipe'
574
- : ['pipe', 'pipe', 'pipe', hooked === null ? 'ignore' : 'pipe', ...grantSlots],
599
+ stdio: measured.stdio,
575
600
  detached: process.platform !== 'win32',
576
601
  windowsHide: true,
577
602
  })
578
- : spawn(root.file, root.args, {
579
- cwd,
580
- env: mergeEnv(lease?.directory ?? ordinaryTemp, env),
581
- stdio: ['pipe', 'pipe', 'pipe', hooked === null ? 'ignore' : 'pipe', 'pipe', ...rootGrantSlot],
582
- detached: process.platform !== 'win32',
583
- windowsHide: true,
584
- });
603
+ : root === undefined
604
+ ? spawn(shellCommand, [], {
605
+ cwd,
606
+ env: mergeEnv(lease?.directory ?? ordinaryTemp, env),
607
+ shell: true,
608
+ stdio: descriptors.length === 0 ? 'pipe' : ['pipe', 'pipe', 'pipe', ...descriptors],
609
+ detached: process.platform !== 'win32',
610
+ windowsHide: true,
611
+ })
612
+ : spawn(root.file, root.args, {
613
+ cwd,
614
+ env: mergeEnv(lease?.directory ?? ordinaryTemp, env),
615
+ stdio: ['pipe', 'pipe', 'pipe', ...descriptors],
616
+ detached: process.platform !== 'win32',
617
+ windowsHide: true,
618
+ });
585
619
  }
586
620
  catch (error) {
587
621
  // Nothing started, so nothing runs under the grant: it goes back here, with the RAM lease.
588
622
  return refuse(`cowshed: could not start the command: ${error instanceof Error ? error.message : String(error)}\n`);
589
623
  }
590
624
  subtreeRetired = false;
625
+ const reportChannel = child.stdio.at(PEAK_FD);
626
+ const waiterReport = measured === null ? null : readWaiterReport(reportChannel instanceof Readable ? reportChannel : null);
627
+ // The leaf's runner is its command: under a waiter, which leads the group, the child the waiter names; else the
628
+ // group's leader itself. A hang snapshot names and samples it (specs/cowshed/08_testing.md).
629
+ const runnerPid = waiterReport?.started ?? Promise.resolve(child.pid ?? null);
630
+ let runner = null;
631
+ void runnerPid.then((pid) => {
632
+ runner = pid;
633
+ });
591
634
  if (root !== undefined) {
592
635
  const channel = child.stdio[HANDLE_FD];
593
636
  const leased = lease;
@@ -643,20 +686,24 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
643
686
  captureTimer = setTimeout(() => {
644
687
  if (state.settled || state.expiry !== null || idleCapture !== capture)
645
688
  return;
646
- const pid = child.pid;
647
- if (pid === undefined) {
689
+ const group = child.pid;
690
+ if (group === undefined) {
648
691
  idleCapture.result = { kind: 'failed', detail: 'runner PID unavailable; no holder conclusion' };
649
692
  return;
650
693
  }
651
694
  idleCapture.result = { kind: 'pending', startedAtMs: Date.now() };
652
- void Promise.resolve()
653
- .then(() => captureDiagnostics({
654
- pid,
655
- pgid: process.platform === 'win32' ? null : pid,
656
- expiresAtMs: capture.expiresAtMs,
657
- deadlineMs: Math.max(0, Math.min(HANG_CAPTURE_MS, capture.expiresAtMs - Date.now())),
658
- signal: capture.controller.signal,
659
- }))
695
+ void runnerPid
696
+ .then((pid) => {
697
+ if (pid === null)
698
+ throw new Error('runner PID unavailable: its waiter named no command; no holder conclusion');
699
+ return captureDiagnostics({
700
+ pid,
701
+ pgid: process.platform === 'win32' ? null : group,
702
+ expiresAtMs: capture.expiresAtMs,
703
+ deadlineMs: Math.max(0, Math.min(HANG_CAPTURE_MS, capture.expiresAtMs - Date.now())),
704
+ signal: capture.controller.signal,
705
+ });
706
+ })
660
707
  .then((snapshot) => {
661
708
  if (idleCapture === capture)
662
709
  idleCapture.result = { kind: 'captured', snapshot };
@@ -900,7 +947,7 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
900
947
  .finally(releaseCpu)
901
948
  .finally(() => releaseLease(true))
902
949
  .finally(releaseReservation)
903
- .finally(async () => recordRun(signalToExitCode(signal), state.expiry, Date.now() - startedAt, state.poolCloseError !== null || lifecycleFailure !== null || state.retireError !== null, state.noSpace === null ? null : await state.noSpace, state.lockWaits))
950
+ .finally(async () => recordRun(signalToExitCode(signal), state.expiry, Date.now() - startedAt, state.poolCloseError !== null || lifecycleFailure !== null || state.retireError !== null, state.noSpace === null ? null : await state.noSpace, state.lockWaits, null))
904
951
  .finally(() => process.kill(process.pid, signal));
905
952
  };
906
953
  const onSigint = () => onTerminationSignal('SIGINT');
@@ -957,7 +1004,7 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
957
1004
  if (bound.kind === 'idle') {
958
1005
  const observed = idleCapture?.result;
959
1006
  state.lockWaits = observed?.kind === 'captured' ? observed.snapshot.lockWaits : [];
960
- appendStderr(`Hang diagnostics: runner pid=${child.pid ?? 'unavailable'} pgid=${process.platform === 'win32' ? 'unavailable' : (child.pid ?? 'unavailable')} expiryAtMs=${Date.now()} scheduledExpiryAtMs=${idleCapture?.expiresAtMs ?? 'unavailable'}\n`);
1007
+ appendStderr(`Hang diagnostics: runner pid=${runner ?? 'unavailable'} pgid=${process.platform === 'win32' ? 'unavailable' : (child.pid ?? 'unavailable')} expiryAtMs=${Date.now()} scheduledExpiryAtMs=${idleCapture?.expiresAtMs ?? 'unavailable'}\n`);
961
1008
  if (observed?.kind === 'captured') {
962
1009
  appendStderr(`Hang diagnostics: outcome=${observed.snapshot.outcome} capturedAtMs=${observed.snapshot.capturedAtMs} actualExpiryOffsetMs=${Date.now() - observed.snapshot.capturedAtMs}\n${observed.snapshot.text}`);
963
1010
  }
@@ -1177,10 +1224,16 @@ export async function runBoundedExec(options, context, killer, tempVolume, inher
1177
1224
  }
1178
1225
  await releaseLease(code !== 0 || state.expiry !== null || state.poolCloseError !== null || lifecycleFailure !== null);
1179
1226
  releaseReservation();
1227
+ // The command's peak, as its waiter reported it once both ended; a peak that was not measured is said, never zero.
1228
+ const reported = waiterReport === null ? (waiter?.kind === 'unmeasured' ? waiter : null) : await waiterReport.peak;
1229
+ if (reported?.kind === 'unmeasured') {
1230
+ appendStderr(`bounded-exec: this run's memory peak was not measured (${reported.reason}); its record names none\n`);
1231
+ }
1232
+ const peakBytes = reported?.kind === 'measured' ? reported.bytes : null;
1180
1233
  // Broken resource ownership, a lost native lifecycle, or leftovers that could not be retired fail even if a shell
1181
1234
  // branch later exited 0: its verdict is an ordinary operational failure, never a successful or silently unbounded run.
1182
1235
  const operationalFailure = state.poolCloseError !== null || lifecycleFailure !== null || state.retireError !== null;
1183
- await recordRun(code, state.expiry, Date.now() - startedAt, operationalFailure, seen, state.lockWaits);
1236
+ await recordRun(code, state.expiry, Date.now() - startedAt, operationalFailure, seen, state.lockWaits, peakBytes);
1184
1237
  return {
1185
1238
  success: !operationalFailure && resultFailure === null && state.expiry === null && code === 0,
1186
1239
  terminalOutput: outputChunks.join(''),
@@ -0,0 +1,47 @@
1
+ /**
2
+ * The memory facts a run's CPU pool charges by (specs/cowshed/05_gateway.md, "Without mbx, every Nx run budgets
3
+ * itself"; 13_telemetry.md, "Job resource peaks"), read by each platform's own mechanism: `host-memory.linux.ts`,
4
+ * `host-memory.darwin.ts`. Callers read them here and never ask which platform they run on.
5
+ */
6
+ export interface HostMemory {
7
+ /** The memory the run's pool charges its leaves' peaks against. */
8
+ readRunMemory(): Promise<RunMemoryReading>;
9
+ /**
10
+ * A leaf's peak in bytes, from the `maxRSS` that Bun's `Subprocess.resourceUsage()` on `bunVersion` reports for
11
+ * it: the exited leaf's `ru_maxrss`.
12
+ */
13
+ peakBytes(maxRss: number, bunVersion: string): number;
14
+ }
15
+ /** The run's memory in bytes, and where it was read: the file or sysctl that holds it. */
16
+ export interface RunMemory {
17
+ readonly bytes: number;
18
+ readonly source: string;
19
+ }
20
+ /** Why the run's memory could not be read: the file or sysctl, and what reading it gave. */
21
+ export interface RunMemoryError {
22
+ readonly operation: 'read-run-memory';
23
+ /**
24
+ * `unreadable`: reading it failed; `malformed`: it held no byte count; `unmounted`: the run's cgroup v2 hierarchy is
25
+ * mounted nowhere this process can see; `unsupported-platform`: the platform has no reader.
26
+ */
27
+ readonly code: 'unreadable' | 'malformed' | 'unmounted' | 'unsupported-platform';
28
+ readonly subject: string;
29
+ readonly cause: string;
30
+ }
31
+ export type RunMemoryReading = {
32
+ readonly ok: true;
33
+ readonly memory: RunMemory;
34
+ } | {
35
+ readonly ok: false;
36
+ readonly error: RunMemoryError;
37
+ };
38
+ /** A run whose memory cannot be read does not start: it is not shown to have room. */
39
+ export declare class RunMemoryUnreadable extends Error {
40
+ readonly error: RunMemoryError;
41
+ constructor(error: RunMemoryError);
42
+ }
43
+ /** This platform's mechanisms, or null where it has none: there a leaf's peak goes unmeasured. */
44
+ export declare const HOST_MEMORY: HostMemory | null;
45
+ /** The run's memory on this platform, or why it cannot be read. */
46
+ export declare function readRunMemory(): Promise<RunMemoryReading>;
47
+ //# sourceMappingURL=host-memory.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"host-memory.d.ts","sourceRoot":"","sources":["../../../src/executors/bounded-exec/host-memory.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,aAAa,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3C;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;CACvD;AAED,0FAA0F;AAC1F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,4FAA4F;AAC5F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,sBAAsB,CAAC;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC;AAE3D,sFAAsF;AACtF,qBAAa,mBAAoB,SAAQ,KAAK;IAChC,QAAQ,CAAC,KAAK,EAAE,cAAc;IAA1C,YAAqB,KAAK,EAAE,cAAc,EAKzC;CACF;AAID,kGAAkG;AAClG,eAAO,MAAM,WAAW,EAAE,UAAU,GAAG,IAA0C,CAAC;AAElF,mEAAmE;AACnE,wBAAgB,aAAa,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAazD"}
@@ -0,0 +1,3 @@
1
+ import type { HostMemory } from './host-memory.js';
2
+ export declare const darwinMemory: HostMemory;
3
+ //# sourceMappingURL=host-memory.darwin.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"host-memory.darwin.d.ts","sourceRoot":"","sources":["../../../src/executors/bounded-exec/host-memory.darwin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,kBAAkB,CAAC;AAyCrE,eAAO,MAAM,YAAY,EAAE,UAA6D,CAAC"}
@@ -0,0 +1,40 @@
1
+ import { execFile } from 'node:child_process';
2
+ import { promisify } from 'node:util';
3
+ /**
4
+ * macOS's memory mechanisms. A run's memory is the host's, `hw.memsize`: macOS confines no job to a memory limit of
5
+ * its own. Bun reports a leaf's `ru_maxrss` in bytes, as macOS does.
6
+ */
7
+ const run = promisify(execFile);
8
+ const HW_MEMSIZE = 'hw.memsize';
9
+ async function readRunMemory() {
10
+ let stdout;
11
+ try {
12
+ ({ stdout } = await run('sysctl', ['-n', HW_MEMSIZE]));
13
+ }
14
+ catch (error) {
15
+ return {
16
+ ok: false,
17
+ error: {
18
+ operation: 'read-run-memory',
19
+ code: 'unreadable',
20
+ subject: HW_MEMSIZE,
21
+ cause: error instanceof Error ? error.message : String(error),
22
+ },
23
+ };
24
+ }
25
+ const value = stdout.trim();
26
+ const bytes = Number(value);
27
+ if (!/^\d+$/.test(value) || !Number.isSafeInteger(bytes) || bytes === 0) {
28
+ return {
29
+ ok: false,
30
+ error: {
31
+ operation: 'read-run-memory',
32
+ code: 'malformed',
33
+ subject: HW_MEMSIZE,
34
+ cause: `sysctl printed ${JSON.stringify(value)}, not a byte count`,
35
+ },
36
+ };
37
+ }
38
+ return { ok: true, memory: { bytes, source: HW_MEMSIZE } };
39
+ }
40
+ export const darwinMemory = { readRunMemory, peakBytes: (maxRss) => maxRss };
@@ -0,0 +1,29 @@
1
+ import { darwinMemory } from './host-memory.darwin.js';
2
+ import { linuxMemory } from './host-memory.linux.js';
3
+ /** A run whose memory cannot be read does not start: it is not shown to have room. */
4
+ export class RunMemoryUnreadable extends Error {
5
+ error;
6
+ constructor(error) {
7
+ super(`bounded-exec: this run's memory cannot be read (${error.operation} ${error.code} ${error.subject}: ${error.cause}); a run whose memory cannot be read is not shown to have room, so it does not start`);
8
+ this.error = error;
9
+ this.name = 'RunMemoryUnreadable';
10
+ }
11
+ }
12
+ const PLATFORMS = { darwin: darwinMemory, linux: linuxMemory };
13
+ /** This platform's mechanisms, or null where it has none: there a leaf's peak goes unmeasured. */
14
+ export const HOST_MEMORY = PLATFORMS[process.platform] ?? null;
15
+ /** The run's memory on this platform, or why it cannot be read. */
16
+ export function readRunMemory() {
17
+ if (HOST_MEMORY === null) {
18
+ return Promise.resolve({
19
+ ok: false,
20
+ error: {
21
+ operation: 'read-run-memory',
22
+ code: 'unsupported-platform',
23
+ subject: process.platform,
24
+ cause: 'only Linux and macOS have a reader of the run memory',
25
+ },
26
+ });
27
+ }
28
+ return HOST_MEMORY.readRunMemory();
29
+ }
@@ -0,0 +1,14 @@
1
+ import type { HostMemory, RunMemoryReading } from './host-memory.js';
2
+ /** A file's text, or the errno code and message its read failed with. */
3
+ export type FileRead = {
4
+ readonly ok: true;
5
+ readonly text: string;
6
+ } | {
7
+ readonly ok: false;
8
+ readonly code: string;
9
+ readonly message: string;
10
+ };
11
+ /** The run's memory, reading every file through `read`. */
12
+ export declare function linuxRunMemory(read: (path: string) => Promise<FileRead>): Promise<RunMemoryReading>;
13
+ export declare const linuxMemory: HostMemory;
14
+ //# sourceMappingURL=host-memory.linux.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"host-memory.linux.d.ts","sourceRoot":"","sources":["../../../src/executors/bounded-exec/host-memory.linux.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAA6B,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAchG,yEAAyE;AACzE,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AA2B5E,2DAA2D;AAC3D,wBAAsB,cAAc,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA8CzG;AAqBD,eAAO,MAAM,WAAW,EAAE,UAAyE,CAAC"}
@@ -0,0 +1,104 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { posix } from 'node:path';
3
+ /**
4
+ * Linux's memory mechanisms. The run's memory is the least of the host's `MemTotal` and every finite `memory.max` of
5
+ * the cgroup v2 the run's process is in and of its ancestors, up to the root of the mounted hierarchy: the kernel holds
6
+ * a cgroup to its ancestors' limits too, so a job in cowshed's `background` class, whose own `memory.max` is `max`, has
7
+ * the class's three quarters of the host. A host with no cgroup v2 hierarchy, or a hierarchy that sets no limit, gives
8
+ * the run `MemTotal`.
9
+ */
10
+ const MEMINFO = '/proc/meminfo';
11
+ const CGROUP = '/proc/self/cgroup';
12
+ const MOUNTINFO = '/proc/self/mountinfo';
13
+ const failed = (code, subject, cause) => ({
14
+ ok: false,
15
+ error: { operation: 'read-run-memory', code, subject, cause },
16
+ });
17
+ const unreadable = (subject, read) => failed('unreadable', subject, `${read.code}: ${read.message}`);
18
+ /** A mount point or root as mountinfo writes it, its space, tab, newline and backslash escaped in octal. */
19
+ const decodeOctal = (field) => field.replace(/\\([0-7]{3})/g, (_, octal) => String.fromCharCode(Number.parseInt(octal, 8)));
20
+ /** The cgroup v2 mounts mountinfo lists: the cgroup each shows (`root`) and where (`point`). */
21
+ function cgroup2Mounts(mountinfo) {
22
+ const mounts = [];
23
+ for (const line of mountinfo.split('\n')) {
24
+ const fields = line.split(' ');
25
+ const separator = fields.indexOf('-');
26
+ const [root, point] = [fields[3], fields[4]];
27
+ if (separator !== -1 && fields[separator + 1] === 'cgroup2' && root !== undefined && point !== undefined) {
28
+ mounts.push({ root: decodeOctal(root), point: decodeOctal(point) });
29
+ }
30
+ }
31
+ return mounts;
32
+ }
33
+ /** The run's memory, reading every file through `read`. */
34
+ export async function linuxRunMemory(read) {
35
+ const meminfo = await read(MEMINFO);
36
+ if (!meminfo.ok)
37
+ return unreadable(MEMINFO, meminfo);
38
+ const total = /^MemTotal:\s+(\d+) kB$/m.exec(meminfo.text)?.[1];
39
+ if (total === undefined)
40
+ return failed('malformed', MEMINFO, 'it names no MemTotal in kB');
41
+ let least = { bytes: Number(total) * 1024, source: `${MEMINFO} MemTotal` };
42
+ const cgroups = await read(CGROUP);
43
+ if (!cgroups.ok)
44
+ return unreadable(CGROUP, cgroups);
45
+ const path = /^0::(\/.*)$/m.exec(cgroups.text)?.[1];
46
+ if (path === undefined) {
47
+ // No cgroup v2 hierarchy holds the run: the host's memory is its memory.
48
+ return { ok: true, memory: least };
49
+ }
50
+ const mounts = await read(MOUNTINFO);
51
+ if (!mounts.ok)
52
+ return unreadable(MOUNTINFO, mounts);
53
+ const mount = cgroup2Mounts(mounts.text).find(({ root }) => root === '/' || path === root || path.startsWith(`${root}/`));
54
+ if (mount === undefined) {
55
+ return failed('unmounted', path, `${MOUNTINFO} lists no cgroup2 mount that shows the run's cgroup`);
56
+ }
57
+ const top = posix.resolve(mount.point);
58
+ const own = posix.resolve(top, `.${mount.root === '/' ? path : path.slice(mount.root.length)}`);
59
+ if (own !== top && !own.startsWith(`${top}/`)) {
60
+ return failed('unmounted', path, `the run's cgroup lies outside the cgroup2 mount at ${top}`);
61
+ }
62
+ for (let directory = own;;) {
63
+ const file = posix.join(directory, 'memory.max');
64
+ const limit = await read(file);
65
+ if (limit.ok) {
66
+ const value = limit.text.trim();
67
+ if (value !== 'max') {
68
+ if (!/^\d+$/.test(value)) {
69
+ return failed('malformed', file, `it holds ${JSON.stringify(value)}, not max or bytes`);
70
+ }
71
+ // A limit above the host's memory (a near-2^63 one included) is no constraint, and is never made a number.
72
+ if (BigInt(value) < BigInt(least.bytes))
73
+ least = { bytes: Number(value), source: file };
74
+ }
75
+ }
76
+ else if (limit.code !== 'ENOENT') {
77
+ // ENOENT: the hierarchy's root, or a cgroup whose parent enables no memory controller, has no limit of its own.
78
+ return unreadable(file, limit);
79
+ }
80
+ if (directory === top)
81
+ break;
82
+ directory = posix.dirname(directory);
83
+ }
84
+ return { ok: true, memory: least };
85
+ }
86
+ async function readText(path) {
87
+ try {
88
+ return { ok: true, text: await readFile(path, 'utf8') };
89
+ }
90
+ catch (error) {
91
+ const code = error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : 'EIO';
92
+ return { ok: false, code, message: error instanceof Error ? error.message : String(error) };
93
+ }
94
+ }
95
+ /** Bun before 1.4.0 reports Linux's `ru_maxrss` as the kernel does, in KiB; from 1.4.0 it reports bytes. */
96
+ function peakBytes(maxRss, bunVersion) {
97
+ const version = /^(\d+)\.(\d+)\./.exec(bunVersion);
98
+ if (version === null) {
99
+ throw new Error(`Bun names its version ${JSON.stringify(bunVersion)}, which is no semver`);
100
+ }
101
+ const [major, minor] = [Number(version[1]), Number(version[2])];
102
+ return major < 1 || (major === 1 && minor < 4) ? maxRss * 1024 : maxRss;
103
+ }
104
+ export const linuxMemory = { readRunMemory: () => linuxRunMemory(readText), peakBytes };
@@ -0,0 +1,55 @@
1
+ import type { IOType } from 'node:child_process';
2
+ import type { Readable } from 'node:stream';
3
+ /**
4
+ * A leaf's memory peak (specs/cowshed/05_gateway.md, "Without mbx, every Nx run budgets itself"; 13_telemetry.md, "Job
5
+ * resource peaks"): the exited command's rusage `ru_maxrss`, which its waiter (`peak-waiter.ts`) reads. The leaf runs
6
+ * no cgroup of its own, even under a cowshed supervisor, whose subtree of the command is an observed fold inside the
7
+ * job's cgroup (07_api.md, `JobSubtreeHandle`), so the peak is the rusage on Linux and macOS alike. The executor writes
8
+ * it into the task's record, and the task's next run is charged it in its run's pool.
9
+ */
10
+ /** The descriptor the waiter reports on: past the lifecycle channel (3), the subtree admission (4) and mbx's grant (5). */
11
+ export declare const PEAK_FD = 6;
12
+ /** A leaf's peak in bytes, or why it went unmeasured. */
13
+ export type LeafPeak = {
14
+ readonly kind: 'measured';
15
+ readonly bytes: number;
16
+ } | {
17
+ readonly kind: 'unmeasured';
18
+ readonly reason: string;
19
+ };
20
+ /** The Bun a leaf's waiter runs on, or why its peak goes unmeasured. */
21
+ export type PeakWaiter = {
22
+ readonly kind: 'waiter';
23
+ readonly runtime: string;
24
+ } | {
25
+ readonly kind: 'unmeasured';
26
+ readonly reason: string;
27
+ };
28
+ /**
29
+ * The Bun that runs this executor, else the first `bun` on the executor's own PATH, never one a target's environment
30
+ * names: the waiter is the executor's, not the command's.
31
+ */
32
+ export declare function peakWaiter(): PeakWaiter;
33
+ /**
34
+ * The spawn of `file args` under the waiter on `runtime`. `descriptors` are the command's own past stderr, from fd 3:
35
+ * the waiter passes each one that is not ignored at its own number, and takes `PEAK_FD` for its report. The runtime's
36
+ * config is empty, so no preload a workspace's `bunfig.toml` names runs in the waiter.
37
+ */
38
+ export declare function underWaiter(runtime: string, file: string, args: readonly string[], descriptors: readonly IOType[]): {
39
+ file: string;
40
+ args: string[];
41
+ stdio: IOType[];
42
+ };
43
+ /** What a leaf's waiter reports on its descriptor. */
44
+ export interface WaiterReport {
45
+ /**
46
+ * The command's pid once the waiter started it: the leaf's runner, a member of the group the waiter leads. Null when
47
+ * the waiter ended without naming one.
48
+ */
49
+ readonly started: Promise<number | null>;
50
+ /** Once the waiter ends: the exited command's peak, or why it reported none. */
51
+ readonly peak: Promise<LeafPeak>;
52
+ }
53
+ /** What the waiter reports on `stream`: the command's pid as it starts it, and the command's peak once it ends. */
54
+ export declare function readWaiterReport(stream: Readable | null | undefined): WaiterReport;
55
+ //# sourceMappingURL=leaf-peak.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"leaf-peak.d.ts","sourceRoot":"","sources":["../../../src/executors/bounded-exec/leaf-peak.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAM5C;;;;;;GAMG;AAEH,2HAA2H;AAC3H,eAAO,MAAM,OAAO,IAAI,CAAC;AAiBzB,yDAAyD;AACzD,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D;;;GAGG;AACH,wBAAgB,UAAU,IAAI,UAAU,CASvC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAanD;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;CAClC;AAED,mHAAmH;AACnH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,CAuDlF"}