@exodus/stasis-core 1.0.0-beta.15 → 1.0.0-beta.17
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/package.json +3 -1
- package/src/add.js +109 -194
- package/src/artifact-util.js +234 -291
- package/src/brotli.js +3 -9
- package/src/bundle-util.js +66 -162
- package/src/bundle.js +57 -130
- package/src/cli.js +15 -45
- package/src/config.js +58 -102
- package/src/extract.js +40 -74
- package/src/fs.js +54 -89
- package/src/hooks.js +118 -235
- package/src/host.js +1 -4
- package/src/loader.js +1 -1
- package/src/lockfile.js +48 -80
- package/src/policy.js +222 -0
- package/src/prune.js +60 -114
- package/src/shard.js +10 -25
- package/src/state-util.js +11 -40
- package/src/state.js +498 -830
- package/src/util.js +97 -149
package/src/fs.js
CHANGED
|
@@ -1,8 +1,5 @@
|
|
|
1
|
-
// `stasis run --fs
|
|
2
|
-
//
|
|
3
|
-
// program's explicit reads into the bundle (bundle=add|replace) or serve them from it (bundle=load).
|
|
4
|
-
// SECURITY INVARIANT: only paths whose REAL path (symlinks resolved) stays inside the project root are
|
|
5
|
-
// captured/served; anything else falls through to the real fs and is never attested.
|
|
1
|
+
// `stasis run --fs`: capture a program's fs reads into the bundle, or serve them from it (bundle=load).
|
|
2
|
+
// SECURITY INVARIANT: a path whose REAL path leaves the project root falls through to the real fs, never attested.
|
|
6
3
|
|
|
7
4
|
import { createRequire, syncBuiltinESMExports } from 'node:module'
|
|
8
5
|
import { resolve } from 'node:path'
|
|
@@ -14,10 +11,8 @@ import { isDotEnvFile, isPathWithin, isStasisArtifactName } from './util.js'
|
|
|
14
11
|
const require = createRequire(import.meta.url)
|
|
15
12
|
const fs = require('node:fs')
|
|
16
13
|
|
|
17
|
-
//
|
|
18
|
-
//
|
|
19
|
-
// node:fs/promises (same object). The legacy callback fs.exists is deliberately NOT reassigned
|
|
20
|
-
// (wrapping would clobber its util.promisify.custom); it still answers via the patched fs.access.
|
|
14
|
+
// The hooks call these real fns, so there's no recursion and capture sees real bytes. Callback fs.exists is
|
|
15
|
+
// NOT patched (wrapping would clobber its util.promisify.custom); it answers via the patched fs.access.
|
|
21
16
|
const {
|
|
22
17
|
readdirSync: realReaddirSync, lstatSync: realLstatSync, statSync: realStatSync, realpathSync: realRealpathSync,
|
|
23
18
|
existsSync: realExistsSync, accessSync: realAccessSync,
|
|
@@ -27,12 +22,10 @@ const { readFile: realReadFileP, readdir: realReaddirP, lstat: realLstatP, stat:
|
|
|
27
22
|
const realRealpathSyncNative = realRealpathSync.native
|
|
28
23
|
const realRealpathNative = realRealpath.native
|
|
29
24
|
|
|
30
|
-
// The bundle serves read-only, so
|
|
31
|
-
// so a W_OK/X_OK or out-of-range mode defers to the real fs.
|
|
25
|
+
// The bundle serves read-only: an allowlist, so a W_OK/X_OK or out-of-range mode defers to the real fs.
|
|
32
26
|
const READ_ACCESS = fs.constants.F_OK | fs.constants.R_OK
|
|
33
27
|
const isReadOnlyAccessMode = (mode) => ((mode | 0) & ~READ_ACCESS) === 0
|
|
34
28
|
|
|
35
|
-
// Resolve a path argument to an absolute path, or null for what we don't capture (fd, non-file URL).
|
|
36
29
|
function toAbsPath(path) {
|
|
37
30
|
if (typeof path === 'string') return resolve(path)
|
|
38
31
|
if (Buffer.isBuffer(path)) return resolve(path.toString())
|
|
@@ -40,50 +33,40 @@ function toAbsPath(path) {
|
|
|
40
33
|
return null
|
|
41
34
|
}
|
|
42
35
|
|
|
43
|
-
|
|
44
|
-
// whether an earlier run left them behind; the program still receives the true on-disk `names`.
|
|
45
|
-
function dirCaptureNames(root, abs, names) {
|
|
46
|
-
if (!isPathWithin(abs, root)) return names
|
|
47
|
-
return names.filter((name) => !isStasisArtifactName(name))
|
|
48
|
-
}
|
|
36
|
+
const encodingOf = (options) => (typeof options === 'string' ? options : options?.encoding)
|
|
49
37
|
|
|
50
|
-
//
|
|
38
|
+
// Buffer.toString throws fs's ERR_UNKNOWN_ENCODING.
|
|
51
39
|
function decode(buf, options) {
|
|
52
|
-
const encoding =
|
|
40
|
+
const encoding = encodingOf(options)
|
|
53
41
|
return encoding == null ? buf : buf.toString(encoding)
|
|
54
42
|
}
|
|
55
43
|
|
|
56
|
-
//
|
|
57
|
-
|
|
58
|
-
const encoding = typeof options === 'string' ? options : options?.encoding
|
|
59
|
-
return encoding === 'buffer' ? Buffer.from(abs) : abs
|
|
60
|
-
}
|
|
44
|
+
// The synthetic realpath of a bundle-served path gone from disk.
|
|
45
|
+
const encodeRealpath = (abs, options) => (encodingOf(options) === 'buffer' ? Buffer.from(abs) : abs)
|
|
61
46
|
|
|
62
|
-
//
|
|
63
|
-
//
|
|
64
|
-
// resources) and `.env`/`.env.*` (an automated capture can never bake a secret in; no opt-in). The
|
|
65
|
-
// ONE way either serves at load is bundle membership (an explicit `stasis add .env`).
|
|
47
|
+
// Absent under --fs: `*.map` (a captured build replays byte-identically; `map` in resources opts out) and
|
|
48
|
+
// `.env*` (a capture never bakes in a secret). Either serves at load only as an explicit bundle member.
|
|
66
49
|
function isSkippedFsPath(state, abs) {
|
|
67
50
|
const skipped = (abs.toLowerCase().endsWith('.map') && !state.config.resources?.has('map')) || isDotEnvFile(abs)
|
|
68
51
|
return skipped && !(state.config.loadBundle && state.getFsStatFamily(pathToFileURL(abs).toString()) !== undefined)
|
|
69
52
|
}
|
|
70
53
|
|
|
71
|
-
//
|
|
54
|
+
// Indistinguishable from a real absent file's. String() spells a Buffer path as UTF-8 and a URL as its href.
|
|
72
55
|
function enoent(syscall, path) {
|
|
73
|
-
const p =
|
|
56
|
+
const p = String(path)
|
|
74
57
|
return Object.assign(new Error(`ENOENT: no such file or directory, ${syscall} '${p}'`), { code: 'ENOENT', errno: -2, syscall, path: p })
|
|
75
58
|
}
|
|
76
59
|
|
|
77
|
-
//
|
|
78
|
-
|
|
79
|
-
const
|
|
60
|
+
// An absent path's stat answers as the real fn does for '' (never exists), re-spelled: which options it honours
|
|
61
|
+
// varies by Node version (async stat takes throwIfNoEntry from 24.15, async lstat doesn't).
|
|
62
|
+
const asAbsent = (syscall, path) => (err) => (err?.code === 'ENOENT' ? enoent(syscall, path) : err)
|
|
80
63
|
|
|
81
|
-
//
|
|
82
|
-
// reading uid/gid etc. keep working.
|
|
64
|
+
// For a bundle-served path gone from disk; never throws, so wrappers reading uid/gid etc. keep working.
|
|
83
65
|
function syntheticStat(isDir) {
|
|
84
66
|
const epoch = new Date(0)
|
|
85
67
|
return {
|
|
86
|
-
|
|
68
|
+
// S_IFDIR / S_IFREG: code reading stats.mode, not is*(), still tells file from dir.
|
|
69
|
+
dev: 0, ino: 0, mode: isDir ? 0o040000 : 0o100000, nlink: 1, uid: 0, gid: 0,
|
|
87
70
|
rdev: 0, size: 0, blksize: 4096, blocks: 0,
|
|
88
71
|
atimeMs: 0, mtimeMs: 0, ctimeMs: 0, birthtimeMs: 0,
|
|
89
72
|
atime: epoch, mtime: epoch, ctime: epoch, birthtime: epoch,
|
|
@@ -92,9 +75,7 @@ function syntheticStat(isDir) {
|
|
|
92
75
|
}
|
|
93
76
|
}
|
|
94
77
|
|
|
95
|
-
//
|
|
96
|
-
// members from the REAL stat while on disk, else syntheticStat. `then` is short-circuited so a
|
|
97
|
-
// bundle-served Stats is never an accidental (rejecting) thenable under `await`.
|
|
78
|
+
// The rest from the real stat while on disk; `then` short-circuited: never an accidental thenable under `await`.
|
|
98
79
|
function bundleStats(realStatFn, statPath, isDir) {
|
|
99
80
|
let data
|
|
100
81
|
const overrides = { isFile: () => !isDir, isDirectory: () => isDir }
|
|
@@ -117,39 +98,34 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
|
|
|
117
98
|
if (installed) return
|
|
118
99
|
installed = true
|
|
119
100
|
|
|
120
|
-
// Node's glob takes fs's readers when
|
|
121
|
-
// of stasis.config.json's `extra` at write (expandExtra) is never captured as the program's reads.
|
|
101
|
+
// Node's glob takes fs's readers when first loaded: load it on the real ones, so the `extra` sweep isn't captured.
|
|
122
102
|
fs.globSync([])
|
|
123
103
|
|
|
124
|
-
//
|
|
125
|
-
// with mode 'absent' (a skipped path: ENOENT), 'serve' (bundle=load; an uncaptured path still falls
|
|
126
|
-
// through to disk) or 'capture' (bundle=add|replace, outside a loader read).
|
|
104
|
+
// null passes through to the real fs; 'serve' still falls through to disk for an uncaptured path.
|
|
127
105
|
const classify = (path) => {
|
|
128
106
|
const state = getState()
|
|
129
107
|
if (!state) return null
|
|
130
108
|
const abs = toAbsPath(path)
|
|
131
109
|
if (abs === null || !isPathWithin(state.root, abs)) return null
|
|
132
|
-
if (isSkippedFsPath(state, abs)) return { mode: 'absent'
|
|
110
|
+
if (isSkippedFsPath(state, abs)) return { mode: 'absent' }
|
|
133
111
|
const url = pathToFileURL(abs).toString()
|
|
134
112
|
if (state.config.loadBundle) return { mode: 'serve', state, url, abs }
|
|
135
113
|
if (state.config.writeBundle && !isLoadingModule()) return { mode: 'capture', state, url, abs }
|
|
136
114
|
return null
|
|
137
115
|
}
|
|
138
|
-
// A path the bundle knows (content, listing, stat record or implied dir), for the serve-only probes.
|
|
139
116
|
const served = (t) => t?.mode === 'serve' && t.state.getFsStatFamily(t.url) !== undefined
|
|
140
117
|
|
|
141
|
-
//
|
|
118
|
+
// A rejected capture taints the run rather than failing the read.
|
|
142
119
|
const record = (fn) => { try { fn() } catch (err) { markAborted(err) } }
|
|
143
|
-
//
|
|
144
|
-
// a read a bundler-plugin sidecar already attests.
|
|
120
|
+
// An in-tree symlink out of root is read but NOT recorded, nor is a read a bundler-plugin sidecar attests.
|
|
145
121
|
const captureFile = ({ state, abs, url }, buf) => {
|
|
146
122
|
if (realContained(state.root, abs) && !state.attestedBySidecar(url)) record(() => state.addFsFile(url, buf))
|
|
147
123
|
}
|
|
148
124
|
const captureDir = ({ state, abs, url }, names) => {
|
|
149
|
-
if (realContained(state.root, abs))
|
|
125
|
+
if (!realContained(state.root, abs)) return
|
|
126
|
+
// At the root, the RECORDED listing leaves out stasis's own artifacts, so an earlier run's don't matter.
|
|
127
|
+
record(() => state.addFsDir(url, isPathWithin(abs, state.root) ? names.filter((name) => !isStasisArtifactName(name)) : names))
|
|
150
128
|
}
|
|
151
|
-
// A stat records the path's KIND as a payload-free record so a stat-ONLY path's type getters answer
|
|
152
|
-
// at load. Only file and dir are modelled.
|
|
153
129
|
const captureStat = ({ state, abs, url }, stats) => {
|
|
154
130
|
const isDir = stats.isDirectory()
|
|
155
131
|
if (!isDir && !stats.isFile()) return
|
|
@@ -173,7 +149,6 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
|
|
|
173
149
|
fs.readdirSync = function readdirSync(path, options) {
|
|
174
150
|
const t = classify(path)
|
|
175
151
|
if (t?.mode === 'absent') throw enoent('scandir', path)
|
|
176
|
-
// Served/captured in the single-argument form only; any options pass straight through.
|
|
177
152
|
if (options == null && t?.mode === 'serve') {
|
|
178
153
|
const names = t.state.getFsDirFamily(t.url)
|
|
179
154
|
if (names !== undefined) return names // sorted at capture time
|
|
@@ -185,16 +160,17 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
|
|
|
185
160
|
return realReaddirSync(path, options)
|
|
186
161
|
}
|
|
187
162
|
|
|
188
|
-
//
|
|
189
|
-
// symlinks, so it must use the real statSync: an in-root symlink records the TARGET's kind there.
|
|
163
|
+
// statSync follows symlinks: an in-root symlink records the TARGET's kind.
|
|
190
164
|
const servedStatSync = (syscall, realFn) => ({
|
|
191
165
|
[`${syscall}Sync`](path, options) {
|
|
192
|
-
const t =
|
|
193
|
-
if (t?.mode === 'absent')
|
|
194
|
-
|
|
166
|
+
const t = classify(path)
|
|
167
|
+
if (t?.mode === 'absent') {
|
|
168
|
+
try { return realFn('', options) } catch (err) { throw asAbsent(syscall, path)(err) }
|
|
169
|
+
}
|
|
170
|
+
if (options == null && t?.mode === 'serve') {
|
|
195
171
|
const kind = t.state.getFsStatFamily(t.url)
|
|
196
172
|
if (kind !== undefined) return bundleStats(realFn, path, kind === 'directory')
|
|
197
|
-
} else if (t?.mode === 'capture') {
|
|
173
|
+
} else if (options == null && t?.mode === 'capture') {
|
|
198
174
|
const stats = realFn(path)
|
|
199
175
|
captureStat(t, stats)
|
|
200
176
|
return stats
|
|
@@ -205,8 +181,7 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
|
|
|
205
181
|
fs.lstatSync = servedStatSync('lstat', realLstatSync)
|
|
206
182
|
fs.statSync = servedStatSync('stat', realStatSync)
|
|
207
183
|
|
|
208
|
-
//
|
|
209
|
-
// a tool may probe before reading bytes (@babel/core does); capture mode and unrecorded paths defer.
|
|
184
|
+
// The probes are served (a tool may probe before reading bytes, as @babel/core does) but never captured.
|
|
210
185
|
fs.existsSync = function existsSync(path) {
|
|
211
186
|
const t = classify(path)
|
|
212
187
|
if (t?.mode === 'absent') return false
|
|
@@ -220,27 +195,21 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
|
|
|
220
195
|
return realAccessSync(path, mode)
|
|
221
196
|
}
|
|
222
197
|
|
|
223
|
-
//
|
|
224
|
-
// once gone (ancestor symlinks not re-resolved then).
|
|
198
|
+
// The real realpath while on disk, else the lexical abs (ancestor symlinks not re-resolved then).
|
|
225
199
|
const servedRealpathSync = (realFn) => function realpathSync(path, options) {
|
|
226
200
|
const t = classify(path)
|
|
227
201
|
if (t?.mode === 'absent') throw enoent('realpath', path)
|
|
228
|
-
if (served(t))
|
|
229
|
-
|
|
230
|
-
}
|
|
231
|
-
return realFn(path, options)
|
|
202
|
+
if (!served(t)) return realFn(path, options)
|
|
203
|
+
try { return realFn(path, options) } catch { return encodeRealpath(t.abs, options) }
|
|
232
204
|
}
|
|
233
205
|
fs.realpathSync = servedRealpathSync(realRealpathSync)
|
|
234
206
|
fs.realpathSync.native = servedRealpathSync(realRealpathSyncNative)
|
|
235
207
|
|
|
236
|
-
//
|
|
237
|
-
// always-async contract.
|
|
208
|
+
// A served callback is deferred, keeping fs's always-async contract.
|
|
238
209
|
if (patchAsync) {
|
|
239
|
-
// Split a trailing callback from its optional options argument.
|
|
240
210
|
const cbArgs = (options, callback) => (typeof options === 'function' ? [undefined, options] : [options, callback])
|
|
241
211
|
const later = (cb, ...args) => queueMicrotask(() => cb(...args))
|
|
242
|
-
//
|
|
243
|
-
// would escape as an uncaught exception and crash the process.
|
|
212
|
+
// A decode error goes to the callback, as fs.readFile's does: a throw here would be uncaught.
|
|
244
213
|
const decodeToCb = (cb, buf, options) => {
|
|
245
214
|
let out
|
|
246
215
|
try { out = decode(buf, options) } catch (err) { cb(err); return }
|
|
@@ -282,8 +251,7 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
|
|
|
282
251
|
const [opts, cb] = cbArgs(options, callback)
|
|
283
252
|
const t = typeof cb === 'function' ? classify(path) : null
|
|
284
253
|
if (t?.mode === 'absent') return later(cb, enoent('scandir', path))
|
|
285
|
-
//
|
|
286
|
-
// (graceful-fs normalises to that), else its reads never hit the bundle.
|
|
254
|
+
// A null options counts as none: graceful-fs normalises to that, else its reads never hit the bundle.
|
|
287
255
|
if (opts == null && t?.mode === 'serve') {
|
|
288
256
|
const names = t.state.getFsDirFamily(t.url)
|
|
289
257
|
if (names !== undefined) return later(cb, null, names)
|
|
@@ -311,16 +279,16 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
|
|
|
311
279
|
return realReaddirP(path, options)
|
|
312
280
|
}
|
|
313
281
|
|
|
314
|
-
//
|
|
282
|
+
// bundleStats's field fallback stays sync.
|
|
315
283
|
const servedStat = (syscall, realFn, realSyncFn) => ({
|
|
316
284
|
[syscall](path, options, callback) {
|
|
317
285
|
const [opts, cb] = cbArgs(options, callback)
|
|
318
|
-
const t =
|
|
319
|
-
if (t?.mode === 'absent') return
|
|
320
|
-
if (t?.mode === 'serve') {
|
|
286
|
+
const t = typeof cb === 'function' ? classify(path) : null
|
|
287
|
+
if (t?.mode === 'absent') return realFn('', opts, (err, stats) => cb(asAbsent(syscall, path)(err), stats))
|
|
288
|
+
if (opts == null && t?.mode === 'serve') {
|
|
321
289
|
const kind = t.state.getFsStatFamily(t.url)
|
|
322
290
|
if (kind !== undefined) return later(cb, null, bundleStats(realSyncFn, path, kind === 'directory'))
|
|
323
|
-
} else if (t?.mode === 'capture') {
|
|
291
|
+
} else if (opts == null && t?.mode === 'capture') {
|
|
324
292
|
return realFn(path, (err, stats) => {
|
|
325
293
|
if (err) return cb(err)
|
|
326
294
|
captureStat(t, stats)
|
|
@@ -335,12 +303,12 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
|
|
|
335
303
|
|
|
336
304
|
const servedStatP = (syscall, realFn, realSyncFn) => ({
|
|
337
305
|
async [syscall](path, options) {
|
|
338
|
-
const t =
|
|
339
|
-
if (t?.mode === 'absent') throw
|
|
340
|
-
if (t?.mode === 'serve') {
|
|
306
|
+
const t = classify(path)
|
|
307
|
+
if (t?.mode === 'absent') return realFn('', options).catch((err) => { throw asAbsent(syscall, path)(err) })
|
|
308
|
+
if (options == null && t?.mode === 'serve') {
|
|
341
309
|
const kind = t.state.getFsStatFamily(t.url)
|
|
342
310
|
if (kind !== undefined) return bundleStats(realSyncFn, path, kind === 'directory')
|
|
343
|
-
} else if (t?.mode === 'capture') {
|
|
311
|
+
} else if (options == null && t?.mode === 'capture') {
|
|
344
312
|
const stats = await realFn(path)
|
|
345
313
|
captureStat(t, stats)
|
|
346
314
|
return stats
|
|
@@ -379,14 +347,11 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
|
|
|
379
347
|
fs.promises.realpath = async function realpath(path, options) {
|
|
380
348
|
const t = classify(path)
|
|
381
349
|
if (t?.mode === 'absent') throw enoent('realpath', path)
|
|
382
|
-
if (served(t))
|
|
383
|
-
|
|
384
|
-
}
|
|
385
|
-
return realRealpathP(path, options)
|
|
350
|
+
if (!served(t)) return realRealpathP(path, options)
|
|
351
|
+
try { return await realRealpathP(path, options) } catch { return encodeRealpath(t.abs, options) }
|
|
386
352
|
}
|
|
387
353
|
}
|
|
388
354
|
|
|
389
|
-
// Refresh the node:fs (+ node:fs/promises) ESM wrappers so user-code live imports see the patched fns.
|
|
390
355
|
// INVARIANT: a stasis module needing the real fs must snapshot it (`const { ... } = fs`), never live-import.
|
|
391
356
|
syncBuiltinESMExports()
|
|
392
357
|
}
|