@exodus/stasis-core 1.0.0-beta.9 → 1.0.0-rc.1
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/bin/stasis-core.js +9 -98
- package/package.json +6 -2
- package/src/add.js +161 -157
- package/src/artifact-util.js +319 -221
- package/src/brotli.js +21 -6
- package/src/bundle-util.js +142 -100
- package/src/bundle.js +89 -128
- package/src/cli.js +123 -0
- package/src/config.js +74 -87
- package/src/extract.js +140 -67
- package/src/fs.js +57 -106
- package/src/hooks.js +126 -238
- package/src/host.js +9 -1
- package/src/loader.js +1 -1
- package/src/lockfile.js +58 -74
- package/src/policy.js +222 -0
- package/src/prune.js +60 -114
- package/src/shard.js +10 -25
- package/src/state-util.js +24 -9
- package/src/state.js +722 -865
- package/src/util.js +123 -172
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, parseResourcesOption } from './util.js'
|
|
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,16 +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` is flag/env-only (never from stasis.config.json).
|
|
19
|
+
// `lockFile` and `bundle` are flag/env-only; `extra`, `entries`, TREE_FLAGS and `lockfiles` are file-only.
|
|
23
20
|
const OPTIONS = {
|
|
24
|
-
scope: { env: 'EXODUS_STASIS_SCOPE', valid:
|
|
25
|
-
lock: { env: 'EXODUS_STASIS_LOCK', valid:
|
|
21
|
+
scope: { env: 'EXODUS_STASIS_SCOPE', valid: SCOPES },
|
|
22
|
+
lock: { env: 'EXODUS_STASIS_LOCK', valid: LOCK_MODES },
|
|
26
23
|
lockFile: { env: 'EXODUS_STASIS_LOCK_FILE', type: 'string' },
|
|
27
|
-
bundle: { env: 'EXODUS_STASIS_BUNDLE', valid:
|
|
24
|
+
bundle: { env: 'EXODUS_STASIS_BUNDLE', valid: BUNDLE_MODES },
|
|
28
25
|
bundleFile: { env: 'EXODUS_STASIS_BUNDLE_FILE', type: 'string' },
|
|
29
26
|
resourcesBundleFile: { env: 'EXODUS_STASIS_RESOURCES_BUNDLE_FILE', type: 'string' },
|
|
30
27
|
debug: { env: 'EXODUS_STASIS_DEBUG', parse: envBool, type: 'boolean' },
|
|
@@ -36,68 +33,47 @@ const OPTIONS = {
|
|
|
36
33
|
resources: { env: 'EXODUS_STASIS_RESOURCES', parse: (name, value) => parseResourcesOption('env', envList(value)), option: (value) => parseResourcesOption('options', value) },
|
|
37
34
|
}
|
|
38
35
|
const OPTION_KEYS = Object.keys(OPTIONS)
|
|
39
|
-
const
|
|
40
|
-
const
|
|
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.
|
|
39
|
+
const CONFIG_FILE_LOCK = 'frozen'
|
|
41
40
|
|
|
42
|
-
const assertKnownKeys = (keys, known, what) => {
|
|
41
|
+
export const assertKnownKeys = (keys, known, what) => {
|
|
43
42
|
const unknown = keys.filter((key) => !known.includes(key))
|
|
44
43
|
assert.equal(unknown.length, 0, `Unknown ${what} options: ${unknown.join(', ')}`)
|
|
45
44
|
}
|
|
46
45
|
|
|
47
|
-
//
|
|
48
|
-
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) {
|
|
49
48
|
const { valid, type } = OPTIONS[key]
|
|
50
49
|
if (valid) assert.ok(valid.has(value), `Invalid ${key}: ${value}`)
|
|
51
50
|
else if (type) assert.equal(typeof value, type, `${key} must be a ${type}`)
|
|
52
51
|
}
|
|
53
52
|
|
|
54
|
-
// Equal for the option's type: `resources` is a Set.
|
|
55
53
|
const assertSame = (key, actual, expected, message) => {
|
|
56
54
|
if (key === 'resources') assert.ok(extSetsEqual(actual, expected), message)
|
|
57
55
|
else assert.equal(actual, expected)
|
|
58
56
|
}
|
|
59
57
|
|
|
60
|
-
// Plugins validate the same options without constructing a Config (which has side effects).
|
|
61
|
-
export function validatePluginOptions(label, options) {
|
|
62
|
-
assertKnownKeys(Object.keys(options), PLUGIN_OPTION_KEYS, label)
|
|
63
|
-
for (const key of PLUGIN_OPTION_KEYS) {
|
|
64
|
-
if (options[key] === undefined) continue
|
|
65
|
-
if (key === 'resources') parseResourcesOption(label, options.resources)
|
|
66
|
-
else assertOption(key, options[key])
|
|
67
|
-
}
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
// The active Config is authoritative; options a plugin was given must agree with it.
|
|
71
|
-
export function assertOptionsMatchConfig(config, options) {
|
|
72
|
-
try {
|
|
73
|
-
// `resources` is deliberately NOT checked here: it's a Set, coordinated in resolvePluginState.
|
|
74
|
-
for (const key of PLUGIN_OPTION_KEYS) {
|
|
75
|
-
if (key !== 'resources' && options[key] !== undefined) assert.equal(config[key === 'bundle' ? 'bundleMode' : key], options[key])
|
|
76
|
-
}
|
|
77
|
-
} catch (cause) {
|
|
78
|
-
throw new Error(`Plugin options conflict with active stasis state: ${cause.message}`, { cause })
|
|
79
|
-
}
|
|
80
|
-
}
|
|
81
|
-
|
|
82
58
|
export class Config {
|
|
83
59
|
#env
|
|
84
60
|
#host
|
|
85
61
|
#explicit
|
|
62
|
+
#ownLock
|
|
86
63
|
#opts
|
|
87
64
|
#shardSignalFlush
|
|
88
65
|
|
|
89
|
-
//
|
|
66
|
+
// `ownLock`: a build's, which takes no lock mode or lock file of EXODUS_STASIS_LOCK(_FILE) or stasis.config.json.
|
|
90
67
|
constructor(options = {}) {
|
|
91
|
-
const { env = process.env, host = diskHost, ...rest } = options
|
|
68
|
+
const { env = process.env, host = diskHost, ownLock = false, ...rest } = options
|
|
92
69
|
assertKnownKeys(Object.keys(rest), OPTION_KEYS, 'Config')
|
|
93
|
-
// An empty-string path/mode option is unset,
|
|
94
|
-
// 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.
|
|
95
71
|
const explicit = Object.fromEntries(Object.entries(rest).map(([key, value]) =>
|
|
96
72
|
[key, value === '' && (OPTIONS[key].valid || OPTIONS[key].type === 'string') ? undefined : value]))
|
|
97
73
|
this.#host = host
|
|
98
74
|
this.#explicit = explicit
|
|
99
|
-
|
|
100
|
-
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
|
|
101
77
|
|
|
102
78
|
try {
|
|
103
79
|
for (const key of OPTION_KEYS) {
|
|
@@ -109,22 +85,24 @@ export class Config {
|
|
|
109
85
|
throw new Error('Config options can not override stasis env', { cause })
|
|
110
86
|
}
|
|
111
87
|
|
|
112
|
-
// Strings:
|
|
88
|
+
// Strings: '' falls through; booleans keep a false.
|
|
113
89
|
const str = (key, fallback) => this.#envValue(key) || explicit[key] || fallback
|
|
114
90
|
const val = (key, fallback) => this.#envValue(key) ?? explicit[key] ?? fallback
|
|
115
91
|
this.#opts = {
|
|
116
|
-
scope: str('scope',
|
|
92
|
+
scope: str('scope', 'full'),
|
|
117
93
|
lock: str('lock', DEFAULT_LOCK),
|
|
118
|
-
lockFile: str('lockFile'
|
|
119
|
-
bundle: str('bundle',
|
|
120
|
-
bundleFile: str('bundleFile'
|
|
121
|
-
resourcesBundleFile: str('resourcesBundleFile'
|
|
94
|
+
lockFile: str('lockFile'),
|
|
95
|
+
bundle: str('bundle', 'none'),
|
|
96
|
+
bundleFile: str('bundleFile'),
|
|
97
|
+
resourcesBundleFile: str('resourcesBundleFile'),
|
|
122
98
|
debug: val('debug', false),
|
|
123
99
|
childProcess: val('childProcess', false),
|
|
124
100
|
packageJSON: val('packageJSON', false),
|
|
125
|
-
fs: str('fs'
|
|
101
|
+
fs: str('fs'),
|
|
126
102
|
brotliQuality: this.#envValue('brotliQuality') ?? explicit.brotliQuality,
|
|
127
103
|
resources: parseResourcesOption('resources', this.#env.resources !== undefined ? envList(this.#env.resources) : explicit.resources),
|
|
104
|
+
extra: [],
|
|
105
|
+
policy: null,
|
|
128
106
|
}
|
|
129
107
|
const flush = env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH
|
|
130
108
|
this.#shardSignalFlush = Boolean(flush) && envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', flush)
|
|
@@ -132,7 +110,6 @@ export class Config {
|
|
|
132
110
|
this.#checkInvariants()
|
|
133
111
|
}
|
|
134
112
|
|
|
135
|
-
// An option's env value, parsed; undefined when unset.
|
|
136
113
|
#envValue(key) {
|
|
137
114
|
const raw = this.#env[key]
|
|
138
115
|
const { env, parse } = OPTIONS[key]
|
|
@@ -145,30 +122,20 @@ export class Config {
|
|
|
145
122
|
}
|
|
146
123
|
|
|
147
124
|
#checkInvariants() {
|
|
148
|
-
const { lock, lockFile, bundle,
|
|
149
|
-
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])
|
|
150
127
|
if (brotliQuality !== undefined && !isBrotliQuality(brotliQuality)) {
|
|
151
128
|
throw new RangeError(`brotliQuality must be an integer 0..11 (got ${JSON.stringify(brotliQuality)})`)
|
|
152
129
|
}
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
if (!['add', 'replace', 'load'].includes(bundle)) {
|
|
157
|
-
throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${bundle}')`)
|
|
158
|
-
}
|
|
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}')`)
|
|
159
133
|
}
|
|
160
|
-
if (
|
|
161
|
-
|
|
162
|
-
assertOption('lockFile', lockFile)
|
|
163
|
-
if (lock === 'none' || lock === 'ignore') {
|
|
164
|
-
throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
|
|
165
|
-
}
|
|
134
|
+
if (lockFile !== undefined && (lock === 'none' || lock === 'ignore')) {
|
|
135
|
+
throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
|
|
166
136
|
}
|
|
167
|
-
if (resourcesBundleFile !== undefined) {
|
|
168
|
-
|
|
169
|
-
if (bundle === 'none' || bundle === 'ignore') {
|
|
170
|
-
throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
|
|
171
|
-
}
|
|
137
|
+
if (resourcesBundleFile !== undefined && (bundle === 'none' || bundle === 'ignore')) {
|
|
138
|
+
throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
|
|
172
139
|
}
|
|
173
140
|
|
|
174
141
|
// Write targets must be distinct: canonicalize so './x.br' vs 'x.br' and symlinks to one inode compare equal.
|
|
@@ -189,31 +156,41 @@ export class Config {
|
|
|
189
156
|
}
|
|
190
157
|
|
|
191
158
|
// bundle=frozen deliberately constrains no lock mode: it verifies disk against the bundle, its own trust root.
|
|
192
|
-
if (lock === 'none' && bundle === 'none')
|
|
193
|
-
throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
|
|
194
|
-
}
|
|
159
|
+
if (lock === 'none' && bundle === 'none') throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
|
|
195
160
|
}
|
|
196
161
|
|
|
197
162
|
loadConfig(json) {
|
|
198
163
|
const config = JSON.parse(json)
|
|
199
164
|
const keys = Object.keys(config)
|
|
165
|
+
if (keys.includes('bundle')) {
|
|
166
|
+
throw new Error('stasis.config.json: bundle can not be set here; give the bundle mode explicitly (--bundle, EXODUS_STASIS_BUNDLE)')
|
|
167
|
+
}
|
|
168
|
+
if (keys.includes('lock') && config.lock !== CONFIG_FILE_LOCK) {
|
|
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)`)
|
|
170
|
+
}
|
|
200
171
|
assert.equal(keys.filter((key) => !CONFIG_FILE_KEYS.includes(key)).length, 0)
|
|
201
172
|
for (const key of keys) {
|
|
202
|
-
|
|
173
|
+
// `stasis bundle`'s, validated there; the policy's, below.
|
|
174
|
+
if (key === 'entries' || POLICY_KEYS.includes(key)) continue
|
|
175
|
+
// A run takes node_modules as installed, but a value github-bundle would refuse is refused here too.
|
|
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)
|
|
203
181
|
// '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
|
|
204
182
|
else if (key === 'bundleFile' || key === 'resourcesBundleFile') this.#opts[key] = config[key] || undefined
|
|
205
|
-
else this.#opts[key] = config[key]
|
|
183
|
+
else if (key !== 'lock' || !this.#ownLock) this.#opts[key] = config[key]
|
|
206
184
|
}
|
|
185
|
+
this.#opts.policy = parsePolicy(CONFIG_FILE, config)
|
|
207
186
|
this.#checkInvariants()
|
|
208
187
|
|
|
188
|
+
// Explicit constructor options are as authoritative as the env: an on-disk config can't override --scope=full.
|
|
209
189
|
try {
|
|
210
190
|
for (const key of CONFIG_FILE_KEYS) {
|
|
211
191
|
if (this.#env[key] !== undefined) {
|
|
212
192
|
assertSame(key, this.#opts[key], this.#envValue(key), 'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
|
|
213
193
|
}
|
|
214
|
-
}
|
|
215
|
-
// Explicit constructor options are equally authoritative: an on-disk config can't override --scope=full.
|
|
216
|
-
for (const key of CONFIG_FILE_KEYS) {
|
|
217
194
|
if (this.#explicit[key] !== undefined) {
|
|
218
195
|
assertSame(key, this.#opts[key], this.#explicitValue(key), 'resources in stasis.config.json must match the resources option')
|
|
219
196
|
}
|
|
@@ -237,16 +214,25 @@ export class Config {
|
|
|
237
214
|
return this.#opts.resourcesBundleFile
|
|
238
215
|
}
|
|
239
216
|
|
|
240
|
-
// Set of lowercase extensions/filenames treated as asset payloads.
|
|
241
217
|
get resources() {
|
|
242
218
|
return this.#opts.resources
|
|
243
219
|
}
|
|
244
220
|
|
|
221
|
+
// Attested beside what a writing run reaches (State#includeExtra). Not serialized.
|
|
222
|
+
get extra() {
|
|
223
|
+
return this.#opts.extra
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
// File-only, not serialized.
|
|
227
|
+
get policy() {
|
|
228
|
+
return this.#opts.policy
|
|
229
|
+
}
|
|
230
|
+
|
|
245
231
|
get debug() {
|
|
246
232
|
return this.#opts.debug
|
|
247
233
|
}
|
|
248
234
|
|
|
249
|
-
//
|
|
235
|
+
// A forked child writes a shard the root merges. Not attested.
|
|
250
236
|
get childProcess() {
|
|
251
237
|
return this.#opts.childProcess
|
|
252
238
|
}
|
|
@@ -256,18 +242,17 @@ export class Config {
|
|
|
256
242
|
return this.#opts.packageJSON
|
|
257
243
|
}
|
|
258
244
|
|
|
259
|
-
// Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers)
|
|
260
|
-
// 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.
|
|
261
246
|
get shardSignalFlush() {
|
|
262
247
|
return this.#shardSignalFlush
|
|
263
248
|
}
|
|
264
249
|
|
|
265
|
-
//
|
|
250
|
+
// Undefined leaves fs untouched. Not serialized.
|
|
266
251
|
get fs() {
|
|
267
252
|
return this.#opts.fs
|
|
268
253
|
}
|
|
269
254
|
|
|
270
|
-
//
|
|
255
|
+
// undefined -> DEFAULT_BROTLI_QUALITY. Not serialized: output decompresses identically.
|
|
271
256
|
get brotliQuality() {
|
|
272
257
|
return this.#opts.brotliQuality
|
|
273
258
|
}
|
|
@@ -337,10 +322,12 @@ export class Config {
|
|
|
337
322
|
return this.#opts.lock
|
|
338
323
|
}
|
|
339
324
|
|
|
325
|
+
// As a stasis.config.json holds it: `lock` only where it is the one a file can pin, `bundle` never.
|
|
340
326
|
get json() {
|
|
341
|
-
const { scope, lock,
|
|
342
|
-
const data = { scope
|
|
343
|
-
|
|
327
|
+
const { scope, lock, resources } = this.#opts
|
|
328
|
+
const data = { scope }
|
|
329
|
+
if (lock === CONFIG_FILE_LOCK) data.lock = lock
|
|
330
|
+
// Only when non-empty, so configs without an allowlist stay byte-identical.
|
|
344
331
|
if (resources.size > 0) data.resources = [...resources].toSorted()
|
|
345
332
|
return JSON.stringify(data, undefined, 2) + '\n'
|
|
346
333
|
}
|
package/src/extract.js
CHANGED
|
@@ -1,54 +1,92 @@
|
|
|
1
|
-
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
|
|
2
|
-
import { dirname,
|
|
3
|
-
import { brotliDecompressSync } from 'node:zlib'
|
|
1
|
+
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
|
|
2
|
+
import { dirname, join, relative, resolve, sep } from 'node:path'
|
|
4
3
|
|
|
4
|
+
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, moduleFileKey,
|
|
9
|
-
|
|
10
|
-
const FILE_LOCK = 'stasis.lock.json'
|
|
8
|
+
import { EXECUTE_BITS, canObserveExecuteBits, LOCK_FILE, LOCK_MODES, moduleFileKey, relativeEscapes } from './util.js'
|
|
11
9
|
|
|
12
10
|
// Buffer.from silently drops invalid chars, so a tampered `resource:base64` could hash-spoof; require a fixed point.
|
|
13
11
|
function assertCanonicalBase64(content, file) {
|
|
14
12
|
const buf = Buffer.from(content, 'base64')
|
|
15
|
-
if (buf.toString('base64') !== content) {
|
|
16
|
-
throw new Error(`extract: non-canonical base64 in resource:base64 content for ${file}`)
|
|
17
|
-
}
|
|
13
|
+
if (buf.toString('base64') !== content) throw new Error(`extract: non-canonical base64 in resource:base64 content for ${file}`)
|
|
18
14
|
return buf
|
|
19
15
|
}
|
|
20
16
|
|
|
21
|
-
export
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
17
|
+
export const lockfileFromBundle = (bundle) => Lockfile.fromBundle(bundle, (file, content) =>
|
|
18
|
+
sha512integrity(bundle.formats.get(file) === 'resource:base64' ? assertCanonicalBase64(content, file) : content))
|
|
19
|
+
|
|
20
|
+
function firstDifference(bundle, lock, path = '') {
|
|
21
|
+
if (bundle === lock) return null
|
|
22
|
+
const nested = (x) => typeof x === 'object' && x !== null
|
|
23
|
+
if (!nested(bundle) || !nested(lock) || Array.isArray(bundle) !== Array.isArray(lock)) {
|
|
24
|
+
return `${path} ${bundle === undefined ? 'is only in the lockfile' : lock === undefined ? 'is only in the bundle' : 'differs'}`
|
|
25
|
+
}
|
|
26
|
+
// Own keys only: JSON.parse makes a `__proto__` file name an own property, never the prototype.
|
|
27
|
+
const own = (x, key) => (Object.hasOwn(x, key) ? x[key] : undefined)
|
|
28
|
+
for (const key of new Set([...Object.keys(bundle), ...Object.keys(lock)])) {
|
|
29
|
+
const diff = firstDifference(own(bundle, key), own(lock, key), `${path}[${Array.isArray(bundle) ? key : JSON.stringify(key)}]`)
|
|
30
|
+
if (diff) return diff
|
|
31
|
+
}
|
|
32
|
+
return null
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function readLockfile(lockAbs) {
|
|
36
|
+
try {
|
|
37
|
+
return Lockfile.parse(readFileSync(lockAbs, 'utf-8'))
|
|
38
|
+
} catch (cause) {
|
|
39
|
+
throw new Error(`extract: not a valid stasis lockfile: ${lockAbs}`, { cause })
|
|
40
|
+
}
|
|
42
41
|
}
|
|
43
42
|
|
|
44
|
-
|
|
43
|
+
// Nothing recorded changes, execute bits too, but a payload-free stat:* record, which content of its kind upgrades.
|
|
44
|
+
function addToLockfile(lockAbs, derived) {
|
|
45
|
+
const lock = readLockfile(lockAbs)
|
|
46
|
+
try {
|
|
47
|
+
return lock.mergeAgreeing(derived)
|
|
48
|
+
} catch (cause) {
|
|
49
|
+
throw new Error(`extract: --lock=add: the bundle conflicts with ${lockAbs}: ${cause.message}`, { cause })
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// As bigints: a number can round a large Windows file id.
|
|
54
|
+
function fileId(path) {
|
|
55
|
+
const stats = statSync(path, { throwIfNoEntry: false, bigint: true })
|
|
56
|
+
return stats && `${stats.dev}:${stats.ino}`
|
|
57
|
+
}
|
|
58
|
+
|
|
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).
|
|
66
|
+
function alreadyInPlace(abs, file, content, bundleId) {
|
|
67
|
+
const stats = statSync(abs, { throwIfNoEntry: false, bigint: true })
|
|
68
|
+
if (stats === undefined) {
|
|
69
|
+
// A dangling symlink: the write would create its target, wherever that is.
|
|
70
|
+
if (lstatSync(abs, { throwIfNoEntry: false }) !== undefined) throw new Error(`extract: ${file} is a dangling symlink`)
|
|
71
|
+
return false
|
|
72
|
+
}
|
|
73
|
+
if (`${stats.dev}:${stats.ino}` === bundleId) throw new Error(`extract: ${file} is the bundle being extracted`)
|
|
74
|
+
if (!stats.isFile()) throw new Error(`extract: ${file} exists and is not a file`)
|
|
75
|
+
if (!readFileSync(abs).equals(Buffer.from(content))) throw new Error(`extract: ${file} exists with other content, which extract never overwrites`)
|
|
76
|
+
return true
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock: lockMode, logLabel = 'stasis-core' } = {}) {
|
|
45
80
|
if (!bundleFile) throw new Error('extract: a bundle file is required')
|
|
81
|
+
if (lockMode !== undefined && !LOCK_MODES.has(lockMode)) {
|
|
82
|
+
throw new Error(`extract: lock must be one of ${[...LOCK_MODES].join(', ')} (got ${JSON.stringify(lockMode)})`)
|
|
83
|
+
}
|
|
46
84
|
const bundleAbs = resolve(cwd, bundleFile)
|
|
47
85
|
if (!existsSync(bundleAbs)) throw new Error(`extract: bundle file not found: ${bundleAbs}`)
|
|
48
86
|
|
|
49
87
|
let bundle
|
|
50
88
|
try {
|
|
51
|
-
bundle =
|
|
89
|
+
bundle = parseBundleBytes(readFileSync(bundleAbs))
|
|
52
90
|
} catch (cause) {
|
|
53
91
|
// Bundle.parse throws message-less asserts; wrap so the user learns which file failed.
|
|
54
92
|
throw new Error(`extract: not a valid stasis bundle: ${bundleAbs}`, { cause })
|
|
@@ -59,53 +97,81 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLab
|
|
|
59
97
|
|
|
60
98
|
const outDir = resolve(cwd, output ?? '.')
|
|
61
99
|
const outPrefix = outDir === sep ? outDir : `${outDir}${sep}`
|
|
62
|
-
const lockAbs = join(outDir,
|
|
100
|
+
const lockAbs = join(outDir, LOCK_FILE)
|
|
101
|
+
// A file (or a dangling symlink) there holds neither a lockfile nor room for the bundle's paths.
|
|
102
|
+
const outStats = statSync(outDir, { throwIfNoEntry: false })
|
|
103
|
+
if (outStats === undefined ? lstatSync(outDir, { throwIfNoEntry: false }) !== undefined : !outStats.isDirectory()) {
|
|
104
|
+
throw new Error(`extract: output dir ${outDir} is not a directory`)
|
|
105
|
+
}
|
|
106
|
+
// lstat, not existsSync: a dangling symlink there is a lockfile too, so the default fails closed on it.
|
|
107
|
+
const lockPresent = lstatSync(lockAbs, { throwIfNoEntry: false }) !== undefined
|
|
108
|
+
const lock = lockMode ?? (lockPresent ? 'frozen' : 'none')
|
|
109
|
+
const frozen = lock === 'frozen'
|
|
110
|
+
if (frozen && !lockPresent) throw new Error(`extract: --lock=frozen needs ${lockAbs}`)
|
|
111
|
+
if (lock === 'none' && lockPresent) {
|
|
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)`)
|
|
113
|
+
}
|
|
114
|
+
if (lockPresent && !withLockfile && lock !== 'ignore') {
|
|
115
|
+
throw new Error(`extract: a legacy v0 bundle can not ${{ frozen: 'be checked against', add: 'be added to', replace: 'replace' }[lock]} ${lockAbs}`)
|
|
116
|
+
}
|
|
117
|
+
const merging = lock === 'add' && lockPresent
|
|
63
118
|
|
|
64
|
-
// Plan-first
|
|
65
|
-
//
|
|
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).
|
|
66
121
|
const writes = []
|
|
67
122
|
const targets = new Set()
|
|
68
|
-
let executables = 0
|
|
69
123
|
for (const [dir, { files }] of bundle.modules) {
|
|
70
124
|
for (const [rel, content] of Object.entries(files)) {
|
|
71
|
-
// A
|
|
125
|
+
// A listing at the dir's own path, not a file to write (its children recreate the dir).
|
|
72
126
|
const key = moduleFileKey(dir, rel)
|
|
73
127
|
if (bundle.formats.get(key) === 'directory') continue
|
|
74
|
-
// The
|
|
75
|
-
// 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.
|
|
76
129
|
const file = dir === '.' ? rel : `${dir}/${rel}`
|
|
77
130
|
if (typeof content !== 'string') throw new Error(`extract: bundle file content is not a string: ${file}`)
|
|
78
131
|
const abs = resolve(outDir, file)
|
|
79
132
|
const relToOut = relative(outDir, abs)
|
|
80
|
-
|
|
81
|
-
if (relToOut === '..' || relToOut.startsWith(`..${sep}`) || isAbsolute(relToOut) || !abs.startsWith(outPrefix)) {
|
|
82
|
-
throw new Error(`extract: bundle path escapes output dir: ${file}`)
|
|
83
|
-
}
|
|
133
|
+
if (relativeEscapes(relToOut) || !abs.startsWith(outPrefix)) throw new Error(`extract: bundle path escapes output dir: ${file}`)
|
|
84
134
|
// A non-canonical path changes under the resolve+relative round-trip; writing it desyncs tree from lockfile.
|
|
85
135
|
if (relToOut !== file) throw new Error(`extract: non-canonical bundle path: ${file}`)
|
|
136
|
+
// No bundle Bundle.parse takes carries a stasis.lock.json, so no write lands on the lockfile.
|
|
86
137
|
if (targets.has(abs)) throw new Error(`extract: duplicate bundle path: ${file}`)
|
|
87
|
-
if (withLockfile && abs === lockAbs) {
|
|
88
|
-
throw new Error(`extract: bundle contains ${FILE_LOCK}, which would collide with the derived lockfile`)
|
|
89
|
-
}
|
|
90
138
|
targets.add(abs)
|
|
91
|
-
// Executability rides the plan
|
|
139
|
+
// Executability rides the plan, so the chmod can only ever reach a file we actually wrote.
|
|
92
140
|
const exec = bundle.executable.has(key)
|
|
93
|
-
|
|
94
|
-
writes.push([abs, bundle.formats.get(key) === 'resource:base64' ? assertCanonicalBase64(content, file) : content, exec])
|
|
141
|
+
writes.push({ abs, content: bundle.formats.get(key) === 'resource:base64' ? assertCanonicalBase64(content, file) : content, exec, file })
|
|
95
142
|
}
|
|
96
143
|
}
|
|
97
|
-
// A
|
|
98
|
-
for (const
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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)}`)
|
|
148
|
+
}
|
|
149
|
+
const writesLock = lock === 'add' || lock === 'replace'
|
|
150
|
+
const derived = withLockfile && (frozen || writesLock) ? lockfileFromBundle(bundle) : null
|
|
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}`)
|
|
154
|
+
const lockText = derived === null || frozen ? null : (merging ? addToLockfile(lockAbs, derived) : derived).serialize()
|
|
155
|
+
|
|
156
|
+
// What is already on disk is checked whole before the first write too; nor may the lockfile's land on the bundle.
|
|
157
|
+
const bundleId = fileId(bundleAbs)
|
|
158
|
+
if (lockText !== null && fileId(lockAbs) === bundleId) throw new Error(`extract: ${LOCK_FILE} is the bundle being extracted`)
|
|
159
|
+
const checkedDirs = new Set()
|
|
160
|
+
const inPlace = new Set()
|
|
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()) {
|
|
164
|
+
if (checkedDirs.has(d)) continue
|
|
165
|
+
const stats = statSync(d, { throwIfNoEntry: false })
|
|
166
|
+
if (stats === undefined && lstatSync(d, { throwIfNoEntry: false }) === undefined) break
|
|
167
|
+
if (!stats?.isDirectory()) throw new Error(`extract: ${relative(outDir, d) || '.'} is in the way of ${file}: not a directory`)
|
|
168
|
+
checkedDirs.add(d)
|
|
103
169
|
}
|
|
170
|
+
if (alreadyInPlace(abs, file, content, bundleId)) inPlace.add(abs)
|
|
104
171
|
}
|
|
105
|
-
const lockText = withLockfile ? lockfileFromBundle(bundle).serialize() : null
|
|
106
172
|
|
|
107
|
-
// Only the execute bit is attested, so only it is touched -- rw bits stay as written (never widen a 0600
|
|
108
|
-
// 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.
|
|
109
175
|
const withModes = withLockfile && canObserveExecuteBits()
|
|
110
176
|
let chmodFailures = 0
|
|
111
177
|
const applyMode = (abs, exec) => {
|
|
@@ -131,21 +197,28 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLab
|
|
|
131
197
|
}
|
|
132
198
|
}
|
|
133
199
|
|
|
134
|
-
for (const
|
|
135
|
-
|
|
136
|
-
|
|
200
|
+
for (const { abs, content, exec } of writes) {
|
|
201
|
+
if (!inPlace.has(abs)) {
|
|
202
|
+
mkdirSync(dirname(abs), { recursive: true })
|
|
203
|
+
// Exclusive: a file that appeared since the check, or one a case-insensitive disk folds onto another, fails.
|
|
204
|
+
writeFileSync(abs, content, { flag: 'wx' })
|
|
205
|
+
}
|
|
137
206
|
if (withModes) applyMode(abs, exec)
|
|
138
207
|
}
|
|
139
208
|
mkdirSync(outDir, { recursive: true }) // for an empty bundle, where no write created it
|
|
140
|
-
if (
|
|
209
|
+
if (lockText !== null) writeFileSync(lockAbs, lockText)
|
|
141
210
|
|
|
142
|
-
const
|
|
143
|
-
|
|
211
|
+
const executables = writes.filter(({ exec }) => exec).length
|
|
212
|
+
const notes = [executables > 0 && `${executables} executable`, inPlace.size > 0 && `${inPlace.size} already in place`].filter(Boolean)
|
|
213
|
+
const execNote = notes.length > 0 ? ` (${notes.join(', ')})` : ''
|
|
214
|
+
const andLock = lockText !== null && !merging ? ` and ${LOCK_FILE}` : ''
|
|
215
|
+
const lockNote = frozen ? `, verified against ${LOCK_FILE}` : merging ? `, added to ${LOCK_FILE}` : ''
|
|
216
|
+
console.warn(`[${logLabel}] Extracted ${writes.length} file(s)${execNote}${andLock} to ${outDir}${lockNote}`)
|
|
144
217
|
if (chmodFailures > 0) {
|
|
145
218
|
console.warn(`[${logLabel}] Warning: could not set file modes on ${chmodFailures} file(s) (the filesystem may not support them); contents were written`)
|
|
146
219
|
}
|
|
147
|
-
if (!withLockfile) {
|
|
148
|
-
console.warn(`[${logLabel}] Warning: legacy v0 bundle records no package name/version, so ${
|
|
220
|
+
if (!withLockfile && writesLock) {
|
|
221
|
+
console.warn(`[${logLabel}] Warning: legacy v0 bundle records no package name/version, so ${LOCK_FILE} can not be restored and was not written`)
|
|
149
222
|
}
|
|
150
|
-
return { dir: outDir, files: writes.length, executable: executables }
|
|
223
|
+
return { dir: outDir, files: writes.length, executable: executables, inPlace: inPlace.size, lock }
|
|
151
224
|
}
|