@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/config.js
CHANGED
|
@@ -1,12 +1,11 @@
|
|
|
1
1
|
import assert from 'node:assert/strict'
|
|
2
2
|
|
|
3
3
|
import { diskHost } from './host.js'
|
|
4
|
+
import { POLICY_KEYS, parsePolicy } from './policy.js'
|
|
4
5
|
import { canonicalizePath } from './state-util.js'
|
|
5
|
-
import { extSetsEqual, isBrotliQuality, parseBrotliQuality, parseExtraOption,
|
|
6
|
+
import { BUNDLE_MODES, CONFIG_FILE, extSetsEqual, isBrotliQuality, LOCK_MODES, parseBrotliQuality, parseExtraOption, parseLockfilesOption, parseResourcesOption, SCOPES } from './util.js'
|
|
6
7
|
|
|
7
8
|
export const DEFAULT_LOCK = 'add'
|
|
8
|
-
export const DEFAULT_BUNDLE = 'none'
|
|
9
|
-
export const DEFAULT_SCOPE = 'full'
|
|
10
9
|
|
|
11
10
|
// Strict, not truthy: a truthiness parse would read 'no'/'off' as *enabling* the toggle.
|
|
12
11
|
const envBool = (name, value) => {
|
|
@@ -15,20 +14,14 @@ const envBool = (name, value) => {
|
|
|
15
14
|
throw new RangeError(`${name} must be ''/'0'/'false' or '1'/'true' (got '${value}')`)
|
|
16
15
|
}
|
|
17
16
|
|
|
18
|
-
// EXODUS_STASIS_RESOURCES is a comma-separated extension list; empty/unset means "no allowlist".
|
|
19
17
|
const envList = (value) => value.split(',').map((s) => s.trim()).filter(Boolean)
|
|
20
18
|
|
|
21
|
-
//
|
|
22
|
-
// option, how a `new Config()` option does. `lockFile` and `bundle` are flag/env-only (never from
|
|
23
|
-
// stasis.config.json), and the file's `lock` can only be CONFIG_FILE_LOCK; `extra` is the reverse,
|
|
24
|
-
// stasis.config.json only (no env var or option), `entries` is `stasis bundle`'s and
|
|
25
|
-
// `installDevDependencies`, `lazyDependencies` and `generatePrisma` the trees laid out from the
|
|
26
|
-
// lockfile's (`stasis github-bundle`), which a run takes nothing from.
|
|
19
|
+
// `lockFile` and `bundle` are flag/env-only; `extra`, `entries`, TREE_FLAGS and `lockfiles` are file-only.
|
|
27
20
|
const OPTIONS = {
|
|
28
|
-
scope: { env: 'EXODUS_STASIS_SCOPE', valid:
|
|
29
|
-
lock: { env: 'EXODUS_STASIS_LOCK', valid:
|
|
21
|
+
scope: { env: 'EXODUS_STASIS_SCOPE', valid: SCOPES },
|
|
22
|
+
lock: { env: 'EXODUS_STASIS_LOCK', valid: LOCK_MODES },
|
|
30
23
|
lockFile: { env: 'EXODUS_STASIS_LOCK_FILE', type: 'string' },
|
|
31
|
-
bundle: { env: 'EXODUS_STASIS_BUNDLE', valid:
|
|
24
|
+
bundle: { env: 'EXODUS_STASIS_BUNDLE', valid: BUNDLE_MODES },
|
|
32
25
|
bundleFile: { env: 'EXODUS_STASIS_BUNDLE_FILE', type: 'string' },
|
|
33
26
|
resourcesBundleFile: { env: 'EXODUS_STASIS_RESOURCES_BUNDLE_FILE', type: 'string' },
|
|
34
27
|
debug: { env: 'EXODUS_STASIS_DEBUG', parse: envBool, type: 'boolean' },
|
|
@@ -40,73 +33,47 @@ const OPTIONS = {
|
|
|
40
33
|
resources: { env: 'EXODUS_STASIS_RESOURCES', parse: (name, value) => parseResourcesOption('env', envList(value)), option: (value) => parseResourcesOption('options', value) },
|
|
41
34
|
}
|
|
42
35
|
const OPTION_KEYS = Object.keys(OPTIONS)
|
|
43
|
-
|
|
44
|
-
const
|
|
45
|
-
|
|
46
|
-
// The one mode a stasis.config.json can pin: a run that writes, loads or ignores is given its modes
|
|
47
|
-
// explicitly (flags, env, options), never by a file.
|
|
36
|
+
const TREE_FLAGS = ['installDevDependencies', 'lazyDependencies', 'generatePrisma']
|
|
37
|
+
const CONFIG_FILE_KEYS = [...OPTION_KEYS.filter((key) => key !== 'lockFile' && key !== 'bundle'), 'extra', 'entries', ...TREE_FLAGS, 'lockfiles', ...POLICY_KEYS]
|
|
38
|
+
// The one mode a stasis.config.json can pin: a run that writes, loads or ignores is given its modes explicitly.
|
|
48
39
|
const CONFIG_FILE_LOCK = 'frozen'
|
|
49
|
-
const PLUGIN_OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'childProcess', 'packageJSON', 'resources']
|
|
50
40
|
|
|
51
|
-
const assertKnownKeys = (keys, known, what) => {
|
|
41
|
+
export const assertKnownKeys = (keys, known, what) => {
|
|
52
42
|
const unknown = keys.filter((key) => !known.includes(key))
|
|
53
43
|
assert.equal(unknown.length, 0, `Unknown ${what} options: ${unknown.join(', ')}`)
|
|
54
44
|
}
|
|
55
45
|
|
|
56
|
-
//
|
|
57
|
-
function assertOption(key, value) {
|
|
46
|
+
// Plugins validate their options with it too, without constructing a Config (which has side effects).
|
|
47
|
+
export function assertOption(key, value) {
|
|
58
48
|
const { valid, type } = OPTIONS[key]
|
|
59
49
|
if (valid) assert.ok(valid.has(value), `Invalid ${key}: ${value}`)
|
|
60
50
|
else if (type) assert.equal(typeof value, type, `${key} must be a ${type}`)
|
|
61
51
|
}
|
|
62
52
|
|
|
63
|
-
// Equal for the option's type: `resources` is a Set.
|
|
64
53
|
const assertSame = (key, actual, expected, message) => {
|
|
65
54
|
if (key === 'resources') assert.ok(extSetsEqual(actual, expected), message)
|
|
66
55
|
else assert.equal(actual, expected)
|
|
67
56
|
}
|
|
68
57
|
|
|
69
|
-
// Plugins validate the same options without constructing a Config (which has side effects).
|
|
70
|
-
export function validatePluginOptions(label, options) {
|
|
71
|
-
assertKnownKeys(Object.keys(options), PLUGIN_OPTION_KEYS, label)
|
|
72
|
-
for (const key of PLUGIN_OPTION_KEYS) {
|
|
73
|
-
if (options[key] === undefined) continue
|
|
74
|
-
if (key === 'resources') parseResourcesOption(label, options.resources)
|
|
75
|
-
else assertOption(key, options[key])
|
|
76
|
-
}
|
|
77
|
-
}
|
|
78
|
-
|
|
79
|
-
// The active Config is authoritative; options a plugin was given must agree with it.
|
|
80
|
-
export function assertOptionsMatchConfig(config, options) {
|
|
81
|
-
try {
|
|
82
|
-
// `resources` is deliberately NOT checked here: it's a Set, coordinated in resolvePluginState.
|
|
83
|
-
for (const key of PLUGIN_OPTION_KEYS) {
|
|
84
|
-
if (key !== 'resources' && options[key] !== undefined) assert.equal(config[key === 'bundle' ? 'bundleMode' : key], options[key])
|
|
85
|
-
}
|
|
86
|
-
} catch (cause) {
|
|
87
|
-
throw new Error(`Plugin options conflict with active stasis state: ${cause.message}`, { cause })
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
|
|
91
58
|
export class Config {
|
|
92
59
|
#env
|
|
93
60
|
#host
|
|
94
61
|
#explicit
|
|
62
|
+
#ownLock
|
|
95
63
|
#opts
|
|
96
64
|
#shardSignalFlush
|
|
97
65
|
|
|
98
|
-
//
|
|
66
|
+
// `ownLock`: a build's, which takes no lock mode or lock file of EXODUS_STASIS_LOCK(_FILE) or stasis.config.json.
|
|
99
67
|
constructor(options = {}) {
|
|
100
|
-
const { env = process.env, host = diskHost, ...rest } = options
|
|
68
|
+
const { env = process.env, host = diskHost, ownLock = false, ...rest } = options
|
|
101
69
|
assertKnownKeys(Object.keys(rest), OPTION_KEYS, 'Config')
|
|
102
|
-
// An empty-string path/mode option is unset,
|
|
103
|
-
// agree, or loadConfig would refuse a stasis.config.json for not matching a phantom override.
|
|
70
|
+
// An empty-string path/mode option is unset; #explicit must agree, or loadConfig would refuse a phantom override.
|
|
104
71
|
const explicit = Object.fromEntries(Object.entries(rest).map(([key, value]) =>
|
|
105
72
|
[key, value === '' && (OPTIONS[key].valid || OPTIONS[key].type === 'string') ? undefined : value]))
|
|
106
73
|
this.#host = host
|
|
107
74
|
this.#explicit = explicit
|
|
108
|
-
|
|
109
|
-
this.#
|
|
75
|
+
this.#env = Object.fromEntries(OPTION_KEYS.map((key) => [key, (ownLock && (key === 'lock' || key === 'lockFile')) ? undefined : env[OPTIONS[key].env] || undefined]))
|
|
76
|
+
this.#ownLock = ownLock
|
|
110
77
|
|
|
111
78
|
try {
|
|
112
79
|
for (const key of OPTION_KEYS) {
|
|
@@ -118,23 +85,24 @@ export class Config {
|
|
|
118
85
|
throw new Error('Config options can not override stasis env', { cause })
|
|
119
86
|
}
|
|
120
87
|
|
|
121
|
-
// Strings:
|
|
88
|
+
// Strings: '' falls through; booleans keep a false.
|
|
122
89
|
const str = (key, fallback) => this.#envValue(key) || explicit[key] || fallback
|
|
123
90
|
const val = (key, fallback) => this.#envValue(key) ?? explicit[key] ?? fallback
|
|
124
91
|
this.#opts = {
|
|
125
|
-
scope: str('scope',
|
|
92
|
+
scope: str('scope', 'full'),
|
|
126
93
|
lock: str('lock', DEFAULT_LOCK),
|
|
127
|
-
lockFile: str('lockFile'
|
|
128
|
-
bundle: str('bundle',
|
|
129
|
-
bundleFile: str('bundleFile'
|
|
130
|
-
resourcesBundleFile: str('resourcesBundleFile'
|
|
94
|
+
lockFile: str('lockFile'),
|
|
95
|
+
bundle: str('bundle', 'none'),
|
|
96
|
+
bundleFile: str('bundleFile'),
|
|
97
|
+
resourcesBundleFile: str('resourcesBundleFile'),
|
|
131
98
|
debug: val('debug', false),
|
|
132
99
|
childProcess: val('childProcess', false),
|
|
133
100
|
packageJSON: val('packageJSON', false),
|
|
134
|
-
fs: str('fs'
|
|
101
|
+
fs: str('fs'),
|
|
135
102
|
brotliQuality: this.#envValue('brotliQuality') ?? explicit.brotliQuality,
|
|
136
103
|
resources: parseResourcesOption('resources', this.#env.resources !== undefined ? envList(this.#env.resources) : explicit.resources),
|
|
137
104
|
extra: [],
|
|
105
|
+
policy: null,
|
|
138
106
|
}
|
|
139
107
|
const flush = env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH
|
|
140
108
|
this.#shardSignalFlush = Boolean(flush) && envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', flush)
|
|
@@ -142,7 +110,6 @@ export class Config {
|
|
|
142
110
|
this.#checkInvariants()
|
|
143
111
|
}
|
|
144
112
|
|
|
145
|
-
// An option's env value, parsed; undefined when unset.
|
|
146
113
|
#envValue(key) {
|
|
147
114
|
const raw = this.#env[key]
|
|
148
115
|
const { env, parse } = OPTIONS[key]
|
|
@@ -155,30 +122,20 @@ export class Config {
|
|
|
155
122
|
}
|
|
156
123
|
|
|
157
124
|
#checkInvariants() {
|
|
158
|
-
const { lock, lockFile, bundle,
|
|
159
|
-
for (const key of
|
|
125
|
+
const { lock, lockFile, bundle, resourcesBundleFile, fs, brotliQuality } = this.#opts
|
|
126
|
+
for (const key of OPTION_KEYS) if (this.#opts[key] !== undefined) assertOption(key, this.#opts[key])
|
|
160
127
|
if (brotliQuality !== undefined && !isBrotliQuality(brotliQuality)) {
|
|
161
128
|
throw new RangeError(`brotliQuality must be an integer 0..11 (got ${JSON.stringify(brotliQuality)})`)
|
|
162
129
|
}
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
if (!['add', 'replace', 'load'].includes(bundle)) {
|
|
167
|
-
throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${bundle}')`)
|
|
168
|
-
}
|
|
130
|
+
// --fs captures into the bundle (add/replace) or serves from it (load); other modes have nothing to do.
|
|
131
|
+
if (fs !== undefined && !['add', 'replace', 'load'].includes(bundle)) {
|
|
132
|
+
throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${bundle}')`)
|
|
169
133
|
}
|
|
170
|
-
if (
|
|
171
|
-
|
|
172
|
-
assertOption('lockFile', lockFile)
|
|
173
|
-
if (lock === 'none' || lock === 'ignore') {
|
|
174
|
-
throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
|
|
175
|
-
}
|
|
134
|
+
if (lockFile !== undefined && (lock === 'none' || lock === 'ignore')) {
|
|
135
|
+
throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
|
|
176
136
|
}
|
|
177
|
-
if (resourcesBundleFile !== undefined) {
|
|
178
|
-
|
|
179
|
-
if (bundle === 'none' || bundle === 'ignore') {
|
|
180
|
-
throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
|
|
181
|
-
}
|
|
137
|
+
if (resourcesBundleFile !== undefined && (bundle === 'none' || bundle === 'ignore')) {
|
|
138
|
+
throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
|
|
182
139
|
}
|
|
183
140
|
|
|
184
141
|
// Write targets must be distinct: canonicalize so './x.br' vs 'x.br' and symlinks to one inode compare equal.
|
|
@@ -199,9 +156,7 @@ export class Config {
|
|
|
199
156
|
}
|
|
200
157
|
|
|
201
158
|
// bundle=frozen deliberately constrains no lock mode: it verifies disk against the bundle, its own trust root.
|
|
202
|
-
if (lock === 'none' && bundle === 'none')
|
|
203
|
-
throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
|
|
204
|
-
}
|
|
159
|
+
if (lock === 'none' && bundle === 'none') throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
|
|
205
160
|
}
|
|
206
161
|
|
|
207
162
|
loadConfig(json) {
|
|
@@ -211,33 +166,31 @@ export class Config {
|
|
|
211
166
|
throw new Error('stasis.config.json: bundle can not be set here; give the bundle mode explicitly (--bundle, EXODUS_STASIS_BUNDLE)')
|
|
212
167
|
}
|
|
213
168
|
if (keys.includes('lock') && config.lock !== CONFIG_FILE_LOCK) {
|
|
214
|
-
throw new Error(
|
|
169
|
+
throw new Error(`${CONFIG_FILE}: lock can only be '${CONFIG_FILE_LOCK}' (got ${JSON.stringify(config.lock)}); give any other lock mode explicitly (--lock, EXODUS_STASIS_LOCK)`)
|
|
215
170
|
}
|
|
216
171
|
assert.equal(keys.filter((key) => !CONFIG_FILE_KEYS.includes(key)).length, 0)
|
|
217
172
|
for (const key of keys) {
|
|
218
|
-
// `stasis bundle`'s, validated there.
|
|
219
|
-
if (key === 'entries') continue
|
|
173
|
+
// `stasis bundle`'s, validated there; the policy's, below.
|
|
174
|
+
if (key === 'entries' || POLICY_KEYS.includes(key)) continue
|
|
220
175
|
// A run takes node_modules as installed, but a value github-bundle would refuse is refused here too.
|
|
221
|
-
if (
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
if (key === '
|
|
226
|
-
else if (key === 'extra') this.#opts.extra = parseExtraOption('stasis.config.json', config.extra)
|
|
176
|
+
if (TREE_FLAGS.includes(key)) {
|
|
177
|
+
if (typeof config[key] !== 'boolean') throw new TypeError(`stasis.config.json: ${key} must be true or false, got ${JSON.stringify(config[key])}`)
|
|
178
|
+
} else if (key === 'lockfiles') parseLockfilesOption(CONFIG_FILE, config.lockfiles)
|
|
179
|
+
else if (key === 'resources') this.#opts.resources = parseResourcesOption(CONFIG_FILE, config.resources)
|
|
180
|
+
else if (key === 'extra') this.#opts.extra = parseExtraOption(CONFIG_FILE, config.extra)
|
|
227
181
|
// '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
|
|
228
182
|
else if (key === 'bundleFile' || key === 'resourcesBundleFile') this.#opts[key] = config[key] || undefined
|
|
229
|
-
else this.#opts[key] = config[key]
|
|
183
|
+
else if (key !== 'lock' || !this.#ownLock) this.#opts[key] = config[key]
|
|
230
184
|
}
|
|
185
|
+
this.#opts.policy = parsePolicy(CONFIG_FILE, config)
|
|
231
186
|
this.#checkInvariants()
|
|
232
187
|
|
|
188
|
+
// Explicit constructor options are as authoritative as the env: an on-disk config can't override --scope=full.
|
|
233
189
|
try {
|
|
234
190
|
for (const key of CONFIG_FILE_KEYS) {
|
|
235
191
|
if (this.#env[key] !== undefined) {
|
|
236
192
|
assertSame(key, this.#opts[key], this.#envValue(key), 'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
|
|
237
193
|
}
|
|
238
|
-
}
|
|
239
|
-
// Explicit constructor options are equally authoritative: an on-disk config can't override --scope=full.
|
|
240
|
-
for (const key of CONFIG_FILE_KEYS) {
|
|
241
194
|
if (this.#explicit[key] !== undefined) {
|
|
242
195
|
assertSame(key, this.#opts[key], this.#explicitValue(key), 'resources in stasis.config.json must match the resources option')
|
|
243
196
|
}
|
|
@@ -261,21 +214,25 @@ export class Config {
|
|
|
261
214
|
return this.#opts.resourcesBundleFile
|
|
262
215
|
}
|
|
263
216
|
|
|
264
|
-
// Set of lowercase extensions/filenames treated as asset payloads.
|
|
265
217
|
get resources() {
|
|
266
218
|
return this.#opts.resources
|
|
267
219
|
}
|
|
268
220
|
|
|
269
|
-
//
|
|
221
|
+
// Attested beside what a writing run reaches (State#includeExtra). Not serialized.
|
|
270
222
|
get extra() {
|
|
271
223
|
return this.#opts.extra
|
|
272
224
|
}
|
|
273
225
|
|
|
226
|
+
// File-only, not serialized.
|
|
227
|
+
get policy() {
|
|
228
|
+
return this.#opts.policy
|
|
229
|
+
}
|
|
230
|
+
|
|
274
231
|
get debug() {
|
|
275
232
|
return this.#opts.debug
|
|
276
233
|
}
|
|
277
234
|
|
|
278
|
-
//
|
|
235
|
+
// A forked child writes a shard the root merges. Not attested.
|
|
279
236
|
get childProcess() {
|
|
280
237
|
return this.#opts.childProcess
|
|
281
238
|
}
|
|
@@ -285,18 +242,17 @@ export class Config {
|
|
|
285
242
|
return this.#opts.packageJSON
|
|
286
243
|
}
|
|
287
244
|
|
|
288
|
-
// Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers)
|
|
289
|
-
// then re-delivers the signal. Not a user option, not attested.
|
|
245
|
+
// Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers). Not attested.
|
|
290
246
|
get shardSignalFlush() {
|
|
291
247
|
return this.#shardSignalFlush
|
|
292
248
|
}
|
|
293
249
|
|
|
294
|
-
//
|
|
250
|
+
// Undefined leaves fs untouched. Not serialized.
|
|
295
251
|
get fs() {
|
|
296
252
|
return this.#opts.fs
|
|
297
253
|
}
|
|
298
254
|
|
|
299
|
-
//
|
|
255
|
+
// undefined -> DEFAULT_BROTLI_QUALITY. Not serialized: output decompresses identically.
|
|
300
256
|
get brotliQuality() {
|
|
301
257
|
return this.#opts.brotliQuality
|
|
302
258
|
}
|
|
@@ -371,7 +327,7 @@ export class Config {
|
|
|
371
327
|
const { scope, lock, resources } = this.#opts
|
|
372
328
|
const data = { scope }
|
|
373
329
|
if (lock === CONFIG_FILE_LOCK) data.lock = lock
|
|
374
|
-
// Only
|
|
330
|
+
// Only when non-empty, so configs without an allowlist stay byte-identical.
|
|
375
331
|
if (resources.size > 0) data.resources = [...resources].toSorted()
|
|
376
332
|
return JSON.stringify(data, undefined, 2) + '\n'
|
|
377
333
|
}
|
package/src/extract.js
CHANGED
|
@@ -5,25 +5,18 @@ import { parseBundleBytes } from './brotli.js'
|
|
|
5
5
|
import { Bundle } from './bundle.js'
|
|
6
6
|
import { Lockfile } from './lockfile.js'
|
|
7
7
|
import { sha512integrity } from './state-util.js'
|
|
8
|
-
import { EXECUTE_BITS, canObserveExecuteBits,
|
|
9
|
-
|
|
10
|
-
const FILE_LOCK = 'stasis.lock.json'
|
|
11
|
-
const LOCK_MODES = new Set(['frozen', 'add', 'replace', 'ignore', 'none'])
|
|
8
|
+
import { EXECUTE_BITS, canObserveExecuteBits, LOCK_FILE, LOCK_MODES, moduleFileKey, relativeEscapes } from './util.js'
|
|
12
9
|
|
|
13
10
|
// Buffer.from silently drops invalid chars, so a tampered `resource:base64` could hash-spoof; require a fixed point.
|
|
14
11
|
function assertCanonicalBase64(content, file) {
|
|
15
12
|
const buf = Buffer.from(content, 'base64')
|
|
16
|
-
if (buf.toString('base64') !== content) {
|
|
17
|
-
throw new Error(`extract: non-canonical base64 in resource:base64 content for ${file}`)
|
|
18
|
-
}
|
|
13
|
+
if (buf.toString('base64') !== content) throw new Error(`extract: non-canonical base64 in resource:base64 content for ${file}`)
|
|
19
14
|
return buf
|
|
20
15
|
}
|
|
21
16
|
|
|
22
|
-
// Hashes the raw on-disk bytes, so decodes 'resource:base64' back first.
|
|
23
17
|
export const lockfileFromBundle = (bundle) => Lockfile.fromBundle(bundle, (file, content) =>
|
|
24
18
|
sha512integrity(bundle.formats.get(file) === 'resource:base64' ? assertCanonicalBase64(content, file) : content))
|
|
25
19
|
|
|
26
|
-
// Where two parsed JSON values first differ, as a path into them, or null when they are equal.
|
|
27
20
|
function firstDifference(bundle, lock, path = '') {
|
|
28
21
|
if (bundle === lock) return null
|
|
29
22
|
const nested = (x) => typeof x === 'object' && x !== null
|
|
@@ -47,42 +40,29 @@ function readLockfile(lockAbs) {
|
|
|
47
40
|
}
|
|
48
41
|
}
|
|
49
42
|
|
|
50
|
-
//
|
|
51
|
-
// entries, packages, hashes, imports, formats and execute bits. Compared re-serialized, so formatting is free.
|
|
52
|
-
function assertLockfileMatches(lockAbs, derived) {
|
|
53
|
-
const diff = firstDifference(JSON.parse(derived.serialize()), JSON.parse(readLockfile(lockAbs).serialize()))
|
|
54
|
-
if (diff !== null) throw new Error(`extract: --lock=frozen: the bundle does not match ${lockAbs}: ${diff}`)
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
// lock=add: the derived lockfile is merged into the one in the output dir, which must agree with it on all
|
|
58
|
-
// both record -- Lockfile.merge refuses any other conflict -- so what is new is recorded and nothing recorded changes,
|
|
59
|
-
// save a payload-free stat:* record, which content of the same kind upgrades as a run's lock=add does.
|
|
43
|
+
// Nothing recorded changes, execute bits too, but a payload-free stat:* record, which content of its kind upgrades.
|
|
60
44
|
function addToLockfile(lockAbs, derived) {
|
|
61
45
|
const lock = readLockfile(lockAbs)
|
|
62
|
-
let merged
|
|
63
46
|
try {
|
|
64
|
-
|
|
47
|
+
return lock.mergeAgreeing(derived)
|
|
65
48
|
} catch (cause) {
|
|
66
49
|
throw new Error(`extract: --lock=add: the bundle conflicts with ${lockAbs}: ${cause.message}`, { cause })
|
|
67
50
|
}
|
|
68
|
-
// merge lets the incoming side's execute bits win, which here would change a recorded one.
|
|
69
|
-
const recorded = moduleFileKeys(lock.modules, { scope: lock.config.scope })
|
|
70
|
-
for (const file of moduleFileKeys(derived.modules, { scope: derived.config.scope })) {
|
|
71
|
-
if (recorded.has(file) && lock.executable.has(file) !== derived.executable.has(file)) {
|
|
72
|
-
throw new Error(`extract: --lock=add: the bundle conflicts with ${lockAbs}: ${file}'s execute bit differs`)
|
|
73
|
-
}
|
|
74
|
-
}
|
|
75
|
-
return merged
|
|
76
51
|
}
|
|
77
52
|
|
|
78
|
-
//
|
|
53
|
+
// As bigints: a number can round a large Windows file id.
|
|
79
54
|
function fileId(path) {
|
|
80
55
|
const stats = statSync(path, { throwIfNoEntry: false, bigint: true })
|
|
81
56
|
return stats && `${stats.dev}:${stats.ino}`
|
|
82
57
|
}
|
|
83
58
|
|
|
84
|
-
|
|
85
|
-
|
|
59
|
+
function dirsBelow(outDir, abs) {
|
|
60
|
+
const dirs = []
|
|
61
|
+
for (let d = dirname(abs); d.length > outDir.length; d = dirname(d)) dirs.push(d)
|
|
62
|
+
return dirs
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
// Extract never overwrites a file with other bytes, nor the bundle it reads, under any name (symlink, hard link).
|
|
86
66
|
function alreadyInPlace(abs, file, content, bundleId) {
|
|
87
67
|
const stats = statSync(abs, { throwIfNoEntry: false, bigint: true })
|
|
88
68
|
if (stats === undefined) {
|
|
@@ -117,7 +97,7 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock:
|
|
|
117
97
|
|
|
118
98
|
const outDir = resolve(cwd, output ?? '.')
|
|
119
99
|
const outPrefix = outDir === sep ? outDir : `${outDir}${sep}`
|
|
120
|
-
const lockAbs = join(outDir,
|
|
100
|
+
const lockAbs = join(outDir, LOCK_FILE)
|
|
121
101
|
// A file (or a dangling symlink) there holds neither a lockfile nor room for the bundle's paths.
|
|
122
102
|
const outStats = statSync(outDir, { throwIfNoEntry: false })
|
|
123
103
|
if (outStats === undefined ? lstatSync(outDir, { throwIfNoEntry: false }) !== undefined : !outStats.isDirectory()) {
|
|
@@ -125,76 +105,62 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock:
|
|
|
125
105
|
}
|
|
126
106
|
// lstat, not existsSync: a dangling symlink there is a lockfile too, so the default fails closed on it.
|
|
127
107
|
const lockPresent = lstatSync(lockAbs, { throwIfNoEntry: false }) !== undefined
|
|
128
|
-
// Unset: assert the lockfile already in the output dir, else write none.
|
|
129
108
|
const lock = lockMode ?? (lockPresent ? 'frozen' : 'none')
|
|
130
109
|
const frozen = lock === 'frozen'
|
|
131
110
|
if (frozen && !lockPresent) throw new Error(`extract: --lock=frozen needs ${lockAbs}`)
|
|
132
111
|
if (lock === 'none' && lockPresent) {
|
|
133
112
|
throw new Error(`extract: unexpected ${lockAbs} with --lock=none (frozen checks the bundle against it, add merges the bundle into it, replace replaces it, ignore leaves it alone)`)
|
|
134
113
|
}
|
|
135
|
-
// ignore neither reads nor writes the lockfile; a v0 bundle derives none, so it has nothing to check against one, add or replace one with.
|
|
136
114
|
if (lockPresent && !withLockfile && lock !== 'ignore') {
|
|
137
115
|
throw new Error(`extract: a legacy v0 bundle can not ${{ frozen: 'be checked against', add: 'be added to', replace: 'replace' }[lock]} ${lockAbs}`)
|
|
138
116
|
}
|
|
139
117
|
const merging = lock === 'add' && lockPresent
|
|
140
118
|
|
|
141
|
-
// Plan-first
|
|
142
|
-
//
|
|
119
|
+
// Plan-first; walk modules, not the last-wins `sources` getter. Containment is lexical -- symlinks are
|
|
120
|
+
// followed, so untrusted bundles need a fresh dir (doc/extract.md).
|
|
143
121
|
const writes = []
|
|
144
122
|
const targets = new Set()
|
|
145
|
-
let executables = 0
|
|
146
123
|
for (const [dir, { files }] of bundle.modules) {
|
|
147
124
|
for (const [rel, content] of Object.entries(files)) {
|
|
148
|
-
// A
|
|
125
|
+
// A listing at the dir's own path, not a file to write (its children recreate the dir).
|
|
149
126
|
const key = moduleFileKey(dir, rel)
|
|
150
127
|
if (bundle.formats.get(key) === 'directory') continue
|
|
151
|
-
// The
|
|
152
|
-
// check instead of writing at the bucket root.
|
|
128
|
+
// The plain join, so a non-`directory` rel === '' fails the canonical-path check, not writes at the bucket root.
|
|
153
129
|
const file = dir === '.' ? rel : `${dir}/${rel}`
|
|
154
130
|
if (typeof content !== 'string') throw new Error(`extract: bundle file content is not a string: ${file}`)
|
|
155
131
|
const abs = resolve(outDir, file)
|
|
156
132
|
const relToOut = relative(outDir, abs)
|
|
157
|
-
|
|
158
|
-
if (relativeEscapes(relToOut) || !abs.startsWith(outPrefix)) {
|
|
159
|
-
throw new Error(`extract: bundle path escapes output dir: ${file}`)
|
|
160
|
-
}
|
|
133
|
+
if (relativeEscapes(relToOut) || !abs.startsWith(outPrefix)) throw new Error(`extract: bundle path escapes output dir: ${file}`)
|
|
161
134
|
// A non-canonical path changes under the resolve+relative round-trip; writing it desyncs tree from lockfile.
|
|
162
135
|
if (relToOut !== file) throw new Error(`extract: non-canonical bundle path: ${file}`)
|
|
163
136
|
// No bundle Bundle.parse takes carries a stasis.lock.json, so no write lands on the lockfile.
|
|
164
137
|
if (targets.has(abs)) throw new Error(`extract: duplicate bundle path: ${file}`)
|
|
165
138
|
targets.add(abs)
|
|
166
|
-
// Executability rides the plan
|
|
139
|
+
// Executability rides the plan, so the chmod can only ever reach a file we actually wrote.
|
|
167
140
|
const exec = bundle.executable.has(key)
|
|
168
|
-
|
|
169
|
-
writes.push([abs, bundle.formats.get(key) === 'resource:base64' ? assertCanonicalBase64(content, file) : content, exec, file])
|
|
141
|
+
writes.push({ abs, content: bundle.formats.get(key) === 'resource:base64' ? assertCanonicalBase64(content, file) : content, exec, file })
|
|
170
142
|
}
|
|
171
143
|
}
|
|
172
|
-
// A
|
|
173
|
-
for (const
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
throw new Error(`extract: bundle path used as both file and directory: ${relative(outDir, d)}`)
|
|
177
|
-
}
|
|
178
|
-
}
|
|
144
|
+
// A file planned as another's parent directory would make the writes throw halfway through.
|
|
145
|
+
for (const { abs } of writes) {
|
|
146
|
+
const clash = dirsBelow(outDir, abs).find((d) => targets.has(d))
|
|
147
|
+
if (clash !== undefined) throw new Error(`extract: bundle path used as both file and directory: ${relative(outDir, clash)}`)
|
|
179
148
|
}
|
|
180
|
-
// Only add and replace write a lockfile, and frozen checks one; each before the first write.
|
|
181
149
|
const writesLock = lock === 'add' || lock === 'replace'
|
|
182
150
|
const derived = withLockfile && (frozen || writesLock) ? lockfileFromBundle(bundle) : null
|
|
183
|
-
|
|
151
|
+
// Every field of the lockfile must match, compared re-serialized, so formatting is free.
|
|
152
|
+
const diff = frozen ? firstDifference(JSON.parse(derived.serialize()), JSON.parse(readLockfile(lockAbs).serialize())) : null
|
|
153
|
+
if (diff !== null) throw new Error(`extract: --lock=frozen: the bundle does not match ${lockAbs}: ${diff}`)
|
|
184
154
|
const lockText = derived === null || frozen ? null : (merging ? addToLockfile(lockAbs, derived) : derived).serialize()
|
|
185
155
|
|
|
186
|
-
// What is already on disk
|
|
187
|
-
// missing), and each target missing or already holding its bytes. The lockfile, which --lock governs, is no
|
|
188
|
-
// exception to the bundle being off limits.
|
|
156
|
+
// What is already on disk is checked whole before the first write too; nor may the lockfile's land on the bundle.
|
|
189
157
|
const bundleId = fileId(bundleAbs)
|
|
190
|
-
if (lockText !== null && fileId(lockAbs) === bundleId) throw new Error(`extract: ${
|
|
158
|
+
if (lockText !== null && fileId(lockAbs) === bundleId) throw new Error(`extract: ${LOCK_FILE} is the bundle being extracted`)
|
|
191
159
|
const checkedDirs = new Set()
|
|
192
160
|
const inPlace = new Set()
|
|
193
|
-
for (const
|
|
194
|
-
// Top-down, so a stat never runs into a file higher up (ENOTDIR)
|
|
195
|
-
const
|
|
196
|
-
for (let d = dirname(abs); d.length > outDir.length; d = dirname(d)) dirs.push(d)
|
|
197
|
-
for (const d of dirs.toReversed()) {
|
|
161
|
+
for (const { abs, content, file } of writes) {
|
|
162
|
+
// Top-down, so a stat never runs into a file higher up (ENOTDIR).
|
|
163
|
+
for (const d of dirsBelow(outDir, abs).toReversed()) {
|
|
198
164
|
if (checkedDirs.has(d)) continue
|
|
199
165
|
const stats = statSync(d, { throwIfNoEntry: false })
|
|
200
166
|
if (stats === undefined && lstatSync(d, { throwIfNoEntry: false }) === undefined) break
|
|
@@ -204,8 +170,8 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock:
|
|
|
204
170
|
if (alreadyInPlace(abs, file, content, bundleId)) inPlace.add(abs)
|
|
205
171
|
}
|
|
206
172
|
|
|
207
|
-
// Only the execute bit is attested, so only it is touched -- rw bits stay as written (never widen a 0600
|
|
208
|
-
// and setuid/setgid/sticky are cleared.
|
|
173
|
+
// Only the execute bit is attested, so only it is touched -- rw bits stay as written (never widen a 0600
|
|
174
|
+
// target) and setuid/setgid/sticky are cleared. v0 attests no modes.
|
|
209
175
|
const withModes = withLockfile && canObserveExecuteBits()
|
|
210
176
|
let chmodFailures = 0
|
|
211
177
|
const applyMode = (abs, exec) => {
|
|
@@ -231,11 +197,10 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock:
|
|
|
231
197
|
}
|
|
232
198
|
}
|
|
233
199
|
|
|
234
|
-
for (const
|
|
200
|
+
for (const { abs, content, exec } of writes) {
|
|
235
201
|
if (!inPlace.has(abs)) {
|
|
236
202
|
mkdirSync(dirname(abs), { recursive: true })
|
|
237
|
-
// Exclusive: a file that appeared since the check, or
|
|
238
|
-
// earlier one, fails the write rather than being overwritten.
|
|
203
|
+
// Exclusive: a file that appeared since the check, or one a case-insensitive disk folds onto another, fails.
|
|
239
204
|
writeFileSync(abs, content, { flag: 'wx' })
|
|
240
205
|
}
|
|
241
206
|
if (withModes) applyMode(abs, exec)
|
|
@@ -243,16 +208,17 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock:
|
|
|
243
208
|
mkdirSync(outDir, { recursive: true }) // for an empty bundle, where no write created it
|
|
244
209
|
if (lockText !== null) writeFileSync(lockAbs, lockText)
|
|
245
210
|
|
|
211
|
+
const executables = writes.filter(({ exec }) => exec).length
|
|
246
212
|
const notes = [executables > 0 && `${executables} executable`, inPlace.size > 0 && `${inPlace.size} already in place`].filter(Boolean)
|
|
247
213
|
const execNote = notes.length > 0 ? ` (${notes.join(', ')})` : ''
|
|
248
|
-
const andLock = lockText !== null && !merging ? ` and ${
|
|
249
|
-
const lockNote = frozen ? `, verified against ${
|
|
214
|
+
const andLock = lockText !== null && !merging ? ` and ${LOCK_FILE}` : ''
|
|
215
|
+
const lockNote = frozen ? `, verified against ${LOCK_FILE}` : merging ? `, added to ${LOCK_FILE}` : ''
|
|
250
216
|
console.warn(`[${logLabel}] Extracted ${writes.length} file(s)${execNote}${andLock} to ${outDir}${lockNote}`)
|
|
251
217
|
if (chmodFailures > 0) {
|
|
252
218
|
console.warn(`[${logLabel}] Warning: could not set file modes on ${chmodFailures} file(s) (the filesystem may not support them); contents were written`)
|
|
253
219
|
}
|
|
254
220
|
if (!withLockfile && writesLock) {
|
|
255
|
-
console.warn(`[${logLabel}] Warning: legacy v0 bundle records no package name/version, so ${
|
|
221
|
+
console.warn(`[${logLabel}] Warning: legacy v0 bundle records no package name/version, so ${LOCK_FILE} can not be restored and was not written`)
|
|
256
222
|
}
|
|
257
223
|
return { dir: outDir, files: writes.length, executable: executables, inPlace: inPlace.size, lock }
|
|
258
224
|
}
|