@exodus/stasis-core 1.0.0-beta.0 → 1.0.0-beta.2

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/src/hooks.js CHANGED
@@ -33,6 +33,7 @@ const NODEJS_FORMATS = new Set(['module', 'commonjs', 'json', 'module-typescript
33
33
  // the allowlist stays the single trust gate and the message is just UX.
34
34
  const NON_NODE_SOURCE_LANGUAGES = new Set(['solidity', 'php', 'bash', 'rust'])
35
35
  const RESOURCE_FORMATS = new Set(['resource', 'resource:base64'])
36
+ const STAT_FORMATS = new Set(['stat:file', 'stat:directory'])
36
37
  // The executable CommonJS formats (plain CJS + TS-CJS). Named like the sets above so
37
38
  // "which formats are CJS" lives in one place; the require-repair below keys off it.
38
39
  const CJS_FORMATS = new Set(['commonjs', 'commonjs-typescript'])
@@ -56,6 +57,13 @@ function refuseNonNodeFormat(format, url) {
56
57
  `fs.readdirSync result is not executable JavaScript. Read it with fs.readdirSync instead (${url})`
57
58
  )
58
59
  }
60
+ if (STAT_FORMATS.has(format)) {
61
+ throw new Error(
62
+ `[stasis] cannot import '${url}': the bundle carries only a payload-free stat record ` +
63
+ `('${format}', an fs.lstatSync/statSync capture attesting existence and kind) -- ` +
64
+ `not the file's content. Capture a run that reads or imports it to bundle its bytes.`
65
+ )
66
+ }
59
67
  // Unknown format string: usually a tampered or forward-incompatible bundle.
60
68
  throw new Error(
61
69
  `[stasis] cannot execute '${url}': attested format '${format}' is not a Node loader ` +
@@ -461,7 +469,10 @@ function initState(root) {
461
469
  // not taint, so the files captured so far ARE still written. That is intentional and
462
470
  // safe: those recorded hashes are accurate (nothing drifted is baked in), and a later
463
471
  // lock=frozen run fails closed on anything missing. Unhandled signals (SIGINT/SIGTERM
464
- // with no handler) bypass exit hooks entirely; servers own that behavior, we don't touch it.
472
+ // with no handler) bypass exit hooks entirely; servers own that behavior, we don't touch
473
+ // it -- except for a capturing CHILD under the EXODUS_STASIS_SHARD_SIGNAL_FLUSH opt-in
474
+ // (StasisMetro sets it for its force-killed transform workers), which flushes its shard
475
+ // on SIGTERM and re-delivers the signal -- see the handler registered below.
465
476
  //
466
477
  // save() runs on EVERY beforeExit/exit firing rather than latching after the first.
467
478
  // These handlers were registered at initState -- before any user code ran -- so they fire
@@ -513,6 +524,64 @@ function initState(root) {
513
524
 
514
525
  process.on('beforeExit', save)
515
526
  process.on('exit', save)
527
+
528
+ // config.shardSignalFlush (EXODUS_STASIS_SHARD_SIGNAL_FLUSH, opt-in; StasisMetro's
529
+ // capture wiring sets it for its build's children -- see the plugin's constructor):
530
+ // flush the shard when a capturing child is ended BY SIGNAL. Metro's transform workers
531
+ // are routinely killed that way: jest-worker's end() sends its END message, gives the
532
+ // worker 500ms to drain its event loop, then forceExit()s it -- SIGTERM, and SIGKILL
533
+ // another 500ms later -- and a worker whose loop doesn't drain in time (a watcher or
534
+ // ref'd timer some transformer left behind) dies by SIGTERM, which bypasses
535
+ // beforeExit/exit entirely. Everything ONLY that worker observed (its fork-target
536
+ // entry, jest-worker's processChild.js; babel.config.js + the preset/plugin graph
537
+ // loaded per transform) then silently vanished from the capture, surfacing only later
538
+ // at bundle=load as "file not attested in bundle" when the forked child's loader can't
539
+ // be served its own entry. The handler runs the same save() the exit hooks run (for a
540
+ // child: forward the shard unless the capture aborted) and re-delivers the signal;
541
+ // semantics are preserved:
542
+ // - the `once` listener is already removed when the handler runs, so when no user
543
+ // listener remains the OS default disposition is restored and the re-kill terminates
544
+ // the process BY that signal (the parent still observes code=null, signal=SIGTERM);
545
+ // the finally makes that re-delivery unconditional even if a future save() edit
546
+ // grows a throw path (today it cannot throw on the child branch);
547
+ // - when user code owns process lifetime we only flush and do NOT re-kill. "User code"
548
+ // is detected two ways, because a `once` listener that ran EARLIER in this same emit
549
+ // has already removed itself and is invisible to a post-emit listenerCount: listeners
550
+ // present at REGISTRATION time (a --require preload's graceful-shutdown hook -- those
551
+ // always precede this initState-time registration) are remembered in
552
+ // `userOwnedSigterm`, and listeners added later are still attached when the handler
553
+ // runs. A user handler that exits normally re-flushes via the exit hooks
554
+ // (lastShardWritten dedups); if a SECOND signal kills it instead, capture accrued
555
+ // after this one-shot flush is lost -- an accepted residual, fail-closed at verify.
556
+ // The conservative direction is deliberate: when in doubt, don't re-kill -- the
557
+ // worst case is jest-worker's own SIGKILL landing 500ms later;
558
+ // - signal listeners don't ref the event loop, so a cleanly-draining worker still
559
+ // exits (and writes) exactly as before.
560
+ // NOT a global default: a signal listener changes a process's default-kill disposition,
561
+ // which in arbitrary user children is the user's domain -- the Metro plugin opts in its
562
+ // KNOWN tool workers, where flush-then-redeliver is the right trade. Gated additionally
563
+ // to a CHILD (the root's signal behavior stays untouched -- servers own it) with shard
564
+ // forwarding on; a channel that was never minted (root mint failure cleared DIR+KEY) just
565
+ // makes the flush a no-op via writeChildShard's own guard. SIGTERM only -- it's what
566
+ // jest-worker's forceExit sends (Metro doesn't override killSignal). Best-effort
567
+ // residuals, all fail-closed at a later frozen/load run: the flush must fit inside
568
+ // forceExit's 500ms SIGTERM->SIGKILL window; SIGKILL and any OTHER signal (group
569
+ // SIGINT/SIGHUP, a killSignal override) are not covered; and a capturing child that
570
+ // is itself the process EVALUATING metro.config.js (a nested orchestration) snapshots
571
+ // its Config before the plugin sets the flag, so only its DESCENDANTS are covered --
572
+ // see the plugin's KNOWN LIMITATIONS bullet.
573
+ if (isChildProcess && shardForwardingEnabled() && state.config.shardSignalFlush) {
574
+ const userOwnedSigterm = process.listenerCount('SIGTERM') > 0
575
+ process.once('SIGTERM', () => {
576
+ try {
577
+ save()
578
+ } finally {
579
+ if (!userOwnedSigterm && process.listenerCount('SIGTERM') === 0) {
580
+ process.kill(process.pid, 'SIGTERM')
581
+ }
582
+ }
583
+ })
584
+ }
516
585
  }
517
586
 
518
587
  function load(url, context, nextLoad) {
@@ -778,8 +847,9 @@ function patchCjsResolution() {
778
847
  // path.resolve()d form, matching native's normalized cache-key contract). Falling
779
848
  // through to native would stat a file the bundle carries but disk (pruned /
780
849
  // never-shipped node_modules) may not -- MODULE_NOT_FOUND on a servable path.
781
- // getFsStat === 'file' (not mere presence) keeps a --fs-captured directory
782
- // LISTING from hijacking native directory->main/index resolution. This widens
850
+ // hasFsFileContent (byte content, not getFsStat's kind) keeps a --fs-captured
851
+ // directory LISTING -- and a payload-free 'stat:*' record, whose bytes the
852
+ // bundle can NOT serve -- from hijacking native disk resolution. This widens
783
853
  // parentless reachability to any attested in-scope file when disk lacks the path;
784
854
  // that is bounded by attestation and the load hook's gates (getFile +
785
855
  // NODEJS_FORMATS), which remain the load-bearing checks.
@@ -788,7 +858,7 @@ function patchCjsResolution() {
788
858
  // re-resolves through here, and the no-parent shape survives on >=24.18 too (the
789
859
  // deferred-resolution branch and createCJSNoSourceModuleWrap still take it).
790
860
  const url = pathToFileURL(request).toString()
791
- if ((state.config.full || state.inNodeModules(url)) && state.getFsStat(url) === 'file') {
861
+ if ((state.config.full || state.inNodeModules(url)) && state.hasFsFileContent(url)) {
792
862
  return resolvePath(request)
793
863
  }
794
864
  }
package/src/lockfile.js CHANGED
@@ -119,7 +119,13 @@ export class Lockfile {
119
119
  // tampered or forward-incompatible lockfile fails closed at the schema
120
120
  // boundary, with a message that names the offending value.
121
121
  assert(KNOWN_FORMATS.has(format), `unknown format '${format}' for ${file}`)
122
- formats.set(file, format)
122
+ // The project root's `directory` listing is keyed '.' -- lockfiles written
123
+ // before that normalization keyed it '' (see moduleFileKey), which never
124
+ // matches the '.' the hash absorb (join('.', '')) and lookups use. Normalize
125
+ // on parse; both keys appearing is a duplicate under the alias -- fail closed.
126
+ const key = file === '' ? '.' : file
127
+ assert(!formats.has(key), `duplicate format key '${key}'`)
128
+ formats.set(key, format)
123
129
  }
124
130
  }
125
131