@exodus/stasis-core 1.0.0-beta.14 → 1.0.0-beta.16
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 +108 -190
- package/src/artifact-util.js +234 -291
- package/src/brotli.js +3 -9
- package/src/bundle-util.js +66 -162
- package/src/bundle.js +55 -129
- package/src/cli.js +15 -45
- package/src/config.js +58 -104
- 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 +34 -78
- package/src/policy.js +222 -0
- package/src/prune.js +60 -114
- package/src/shard.js +10 -25
- package/src/state-util.js +13 -24
- package/src/state.js +500 -834
- package/src/util.js +97 -144
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` and `lazyDependencies` the trees laid out from the lockfile's (`stasis
|
|
26
|
-
// 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,71 +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
|
-
const
|
|
44
|
-
|
|
45
|
-
//
|
|
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.
|
|
46
39
|
const CONFIG_FILE_LOCK = 'frozen'
|
|
47
|
-
const PLUGIN_OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'childProcess', 'packageJSON', 'resources']
|
|
48
40
|
|
|
49
|
-
const assertKnownKeys = (keys, known, what) => {
|
|
41
|
+
export const assertKnownKeys = (keys, known, what) => {
|
|
50
42
|
const unknown = keys.filter((key) => !known.includes(key))
|
|
51
43
|
assert.equal(unknown.length, 0, `Unknown ${what} options: ${unknown.join(', ')}`)
|
|
52
44
|
}
|
|
53
45
|
|
|
54
|
-
//
|
|
55
|
-
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) {
|
|
56
48
|
const { valid, type } = OPTIONS[key]
|
|
57
49
|
if (valid) assert.ok(valid.has(value), `Invalid ${key}: ${value}`)
|
|
58
50
|
else if (type) assert.equal(typeof value, type, `${key} must be a ${type}`)
|
|
59
51
|
}
|
|
60
52
|
|
|
61
|
-
// Equal for the option's type: `resources` is a Set.
|
|
62
53
|
const assertSame = (key, actual, expected, message) => {
|
|
63
54
|
if (key === 'resources') assert.ok(extSetsEqual(actual, expected), message)
|
|
64
55
|
else assert.equal(actual, expected)
|
|
65
56
|
}
|
|
66
57
|
|
|
67
|
-
// Plugins validate the same options without constructing a Config (which has side effects).
|
|
68
|
-
export function validatePluginOptions(label, options) {
|
|
69
|
-
assertKnownKeys(Object.keys(options), PLUGIN_OPTION_KEYS, label)
|
|
70
|
-
for (const key of PLUGIN_OPTION_KEYS) {
|
|
71
|
-
if (options[key] === undefined) continue
|
|
72
|
-
if (key === 'resources') parseResourcesOption(label, options.resources)
|
|
73
|
-
else assertOption(key, options[key])
|
|
74
|
-
}
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
// The active Config is authoritative; options a plugin was given must agree with it.
|
|
78
|
-
export function assertOptionsMatchConfig(config, options) {
|
|
79
|
-
try {
|
|
80
|
-
// `resources` is deliberately NOT checked here: it's a Set, coordinated in resolvePluginState.
|
|
81
|
-
for (const key of PLUGIN_OPTION_KEYS) {
|
|
82
|
-
if (key !== 'resources' && options[key] !== undefined) assert.equal(config[key === 'bundle' ? 'bundleMode' : key], options[key])
|
|
83
|
-
}
|
|
84
|
-
} catch (cause) {
|
|
85
|
-
throw new Error(`Plugin options conflict with active stasis state: ${cause.message}`, { cause })
|
|
86
|
-
}
|
|
87
|
-
}
|
|
88
|
-
|
|
89
58
|
export class Config {
|
|
90
59
|
#env
|
|
91
60
|
#host
|
|
92
61
|
#explicit
|
|
62
|
+
#ownLock
|
|
93
63
|
#opts
|
|
94
64
|
#shardSignalFlush
|
|
95
65
|
|
|
96
|
-
//
|
|
66
|
+
// `ownLock`: a build's, which takes no lock mode or lock file of EXODUS_STASIS_LOCK(_FILE) or stasis.config.json.
|
|
97
67
|
constructor(options = {}) {
|
|
98
|
-
const { env = process.env, host = diskHost, ...rest } = options
|
|
68
|
+
const { env = process.env, host = diskHost, ownLock = false, ...rest } = options
|
|
99
69
|
assertKnownKeys(Object.keys(rest), OPTION_KEYS, 'Config')
|
|
100
|
-
// An empty-string path/mode option is unset,
|
|
101
|
-
// 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.
|
|
102
71
|
const explicit = Object.fromEntries(Object.entries(rest).map(([key, value]) =>
|
|
103
72
|
[key, value === '' && (OPTIONS[key].valid || OPTIONS[key].type === 'string') ? undefined : value]))
|
|
104
73
|
this.#host = host
|
|
105
74
|
this.#explicit = explicit
|
|
106
|
-
|
|
107
|
-
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
|
|
108
77
|
|
|
109
78
|
try {
|
|
110
79
|
for (const key of OPTION_KEYS) {
|
|
@@ -116,23 +85,24 @@ export class Config {
|
|
|
116
85
|
throw new Error('Config options can not override stasis env', { cause })
|
|
117
86
|
}
|
|
118
87
|
|
|
119
|
-
// Strings:
|
|
88
|
+
// Strings: '' falls through; booleans keep a false.
|
|
120
89
|
const str = (key, fallback) => this.#envValue(key) || explicit[key] || fallback
|
|
121
90
|
const val = (key, fallback) => this.#envValue(key) ?? explicit[key] ?? fallback
|
|
122
91
|
this.#opts = {
|
|
123
|
-
scope: str('scope',
|
|
92
|
+
scope: str('scope', 'full'),
|
|
124
93
|
lock: str('lock', DEFAULT_LOCK),
|
|
125
|
-
lockFile: str('lockFile'
|
|
126
|
-
bundle: str('bundle',
|
|
127
|
-
bundleFile: str('bundleFile'
|
|
128
|
-
resourcesBundleFile: str('resourcesBundleFile'
|
|
94
|
+
lockFile: str('lockFile'),
|
|
95
|
+
bundle: str('bundle', 'none'),
|
|
96
|
+
bundleFile: str('bundleFile'),
|
|
97
|
+
resourcesBundleFile: str('resourcesBundleFile'),
|
|
129
98
|
debug: val('debug', false),
|
|
130
99
|
childProcess: val('childProcess', false),
|
|
131
100
|
packageJSON: val('packageJSON', false),
|
|
132
|
-
fs: str('fs'
|
|
101
|
+
fs: str('fs'),
|
|
133
102
|
brotliQuality: this.#envValue('brotliQuality') ?? explicit.brotliQuality,
|
|
134
103
|
resources: parseResourcesOption('resources', this.#env.resources !== undefined ? envList(this.#env.resources) : explicit.resources),
|
|
135
104
|
extra: [],
|
|
105
|
+
policy: null,
|
|
136
106
|
}
|
|
137
107
|
const flush = env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH
|
|
138
108
|
this.#shardSignalFlush = Boolean(flush) && envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', flush)
|
|
@@ -140,7 +110,6 @@ export class Config {
|
|
|
140
110
|
this.#checkInvariants()
|
|
141
111
|
}
|
|
142
112
|
|
|
143
|
-
// An option's env value, parsed; undefined when unset.
|
|
144
113
|
#envValue(key) {
|
|
145
114
|
const raw = this.#env[key]
|
|
146
115
|
const { env, parse } = OPTIONS[key]
|
|
@@ -153,30 +122,20 @@ export class Config {
|
|
|
153
122
|
}
|
|
154
123
|
|
|
155
124
|
#checkInvariants() {
|
|
156
|
-
const { lock, lockFile, bundle,
|
|
157
|
-
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])
|
|
158
127
|
if (brotliQuality !== undefined && !isBrotliQuality(brotliQuality)) {
|
|
159
128
|
throw new RangeError(`brotliQuality must be an integer 0..11 (got ${JSON.stringify(brotliQuality)})`)
|
|
160
129
|
}
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
if (!['add', 'replace', 'load'].includes(bundle)) {
|
|
165
|
-
throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${bundle}')`)
|
|
166
|
-
}
|
|
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}')`)
|
|
167
133
|
}
|
|
168
|
-
if (
|
|
169
|
-
|
|
170
|
-
assertOption('lockFile', lockFile)
|
|
171
|
-
if (lock === 'none' || lock === 'ignore') {
|
|
172
|
-
throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
|
|
173
|
-
}
|
|
134
|
+
if (lockFile !== undefined && (lock === 'none' || lock === 'ignore')) {
|
|
135
|
+
throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
|
|
174
136
|
}
|
|
175
|
-
if (resourcesBundleFile !== undefined) {
|
|
176
|
-
|
|
177
|
-
if (bundle === 'none' || bundle === 'ignore') {
|
|
178
|
-
throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
|
|
179
|
-
}
|
|
137
|
+
if (resourcesBundleFile !== undefined && (bundle === 'none' || bundle === 'ignore')) {
|
|
138
|
+
throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
|
|
180
139
|
}
|
|
181
140
|
|
|
182
141
|
// Write targets must be distinct: canonicalize so './x.br' vs 'x.br' and symlinks to one inode compare equal.
|
|
@@ -197,9 +156,7 @@ export class Config {
|
|
|
197
156
|
}
|
|
198
157
|
|
|
199
158
|
// bundle=frozen deliberately constrains no lock mode: it verifies disk against the bundle, its own trust root.
|
|
200
|
-
if (lock === 'none' && bundle === 'none')
|
|
201
|
-
throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
|
|
202
|
-
}
|
|
159
|
+
if (lock === 'none' && bundle === 'none') throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
|
|
203
160
|
}
|
|
204
161
|
|
|
205
162
|
loadConfig(json) {
|
|
@@ -209,37 +166,31 @@ export class Config {
|
|
|
209
166
|
throw new Error('stasis.config.json: bundle can not be set here; give the bundle mode explicitly (--bundle, EXODUS_STASIS_BUNDLE)')
|
|
210
167
|
}
|
|
211
168
|
if (keys.includes('lock') && config.lock !== CONFIG_FILE_LOCK) {
|
|
212
|
-
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)`)
|
|
213
170
|
}
|
|
214
171
|
assert.equal(keys.filter((key) => !CONFIG_FILE_KEYS.includes(key)).length, 0)
|
|
215
172
|
for (const key of keys) {
|
|
216
|
-
// `stasis bundle`'s, validated there.
|
|
217
|
-
if (key === 'entries') continue
|
|
173
|
+
// `stasis bundle`'s, validated there; the policy's, below.
|
|
174
|
+
if (key === 'entries' || POLICY_KEYS.includes(key)) continue
|
|
218
175
|
// A run takes node_modules as installed, but a value github-bundle would refuse is refused here too.
|
|
219
|
-
if (key
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
if (key === '
|
|
224
|
-
parseLazyDependencies('stasis.config.json', config.lazyDependencies)
|
|
225
|
-
continue
|
|
226
|
-
}
|
|
227
|
-
if (key === 'resources') this.#opts.resources = parseResourcesOption('stasis.config.json', config.resources)
|
|
228
|
-
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)
|
|
229
181
|
// '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
|
|
230
182
|
else if (key === 'bundleFile' || key === 'resourcesBundleFile') this.#opts[key] = config[key] || undefined
|
|
231
|
-
else this.#opts[key] = config[key]
|
|
183
|
+
else if (key !== 'lock' || !this.#ownLock) this.#opts[key] = config[key]
|
|
232
184
|
}
|
|
185
|
+
this.#opts.policy = parsePolicy(CONFIG_FILE, config)
|
|
233
186
|
this.#checkInvariants()
|
|
234
187
|
|
|
188
|
+
// Explicit constructor options are as authoritative as the env: an on-disk config can't override --scope=full.
|
|
235
189
|
try {
|
|
236
190
|
for (const key of CONFIG_FILE_KEYS) {
|
|
237
191
|
if (this.#env[key] !== undefined) {
|
|
238
192
|
assertSame(key, this.#opts[key], this.#envValue(key), 'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
|
|
239
193
|
}
|
|
240
|
-
}
|
|
241
|
-
// Explicit constructor options are equally authoritative: an on-disk config can't override --scope=full.
|
|
242
|
-
for (const key of CONFIG_FILE_KEYS) {
|
|
243
194
|
if (this.#explicit[key] !== undefined) {
|
|
244
195
|
assertSame(key, this.#opts[key], this.#explicitValue(key), 'resources in stasis.config.json must match the resources option')
|
|
245
196
|
}
|
|
@@ -263,21 +214,25 @@ export class Config {
|
|
|
263
214
|
return this.#opts.resourcesBundleFile
|
|
264
215
|
}
|
|
265
216
|
|
|
266
|
-
// Set of lowercase extensions/filenames treated as asset payloads.
|
|
267
217
|
get resources() {
|
|
268
218
|
return this.#opts.resources
|
|
269
219
|
}
|
|
270
220
|
|
|
271
|
-
//
|
|
221
|
+
// Attested beside what a writing run reaches (State#includeExtra). Not serialized.
|
|
272
222
|
get extra() {
|
|
273
223
|
return this.#opts.extra
|
|
274
224
|
}
|
|
275
225
|
|
|
226
|
+
// File-only, not serialized.
|
|
227
|
+
get policy() {
|
|
228
|
+
return this.#opts.policy
|
|
229
|
+
}
|
|
230
|
+
|
|
276
231
|
get debug() {
|
|
277
232
|
return this.#opts.debug
|
|
278
233
|
}
|
|
279
234
|
|
|
280
|
-
//
|
|
235
|
+
// A forked child writes a shard the root merges. Not attested.
|
|
281
236
|
get childProcess() {
|
|
282
237
|
return this.#opts.childProcess
|
|
283
238
|
}
|
|
@@ -287,18 +242,17 @@ export class Config {
|
|
|
287
242
|
return this.#opts.packageJSON
|
|
288
243
|
}
|
|
289
244
|
|
|
290
|
-
// Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers)
|
|
291
|
-
// 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.
|
|
292
246
|
get shardSignalFlush() {
|
|
293
247
|
return this.#shardSignalFlush
|
|
294
248
|
}
|
|
295
249
|
|
|
296
|
-
//
|
|
250
|
+
// Undefined leaves fs untouched. Not serialized.
|
|
297
251
|
get fs() {
|
|
298
252
|
return this.#opts.fs
|
|
299
253
|
}
|
|
300
254
|
|
|
301
|
-
//
|
|
255
|
+
// undefined -> DEFAULT_BROTLI_QUALITY. Not serialized: output decompresses identically.
|
|
302
256
|
get brotliQuality() {
|
|
303
257
|
return this.#opts.brotliQuality
|
|
304
258
|
}
|
|
@@ -373,7 +327,7 @@ export class Config {
|
|
|
373
327
|
const { scope, lock, resources } = this.#opts
|
|
374
328
|
const data = { scope }
|
|
375
329
|
if (lock === CONFIG_FILE_LOCK) data.lock = lock
|
|
376
|
-
// Only
|
|
330
|
+
// Only when non-empty, so configs without an allowlist stay byte-identical.
|
|
377
331
|
if (resources.size > 0) data.resources = [...resources].toSorted()
|
|
378
332
|
return JSON.stringify(data, undefined, 2) + '\n'
|
|
379
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
|
}
|