owenloop 0.2.1 → 0.3.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/CHANGELOG.md +54 -0
- package/README.md +76 -7
- package/bin/owenloop.mjs +2 -2
- package/dist/add.d.ts +412 -0
- package/dist/add.js +999 -0
- package/dist/cli.d.ts +47 -0
- package/dist/cli.js +1809 -19
- package/dist/defs.d.ts +33 -0
- package/dist/defs.js +112 -19
- package/dist/engine.d.ts +338 -50
- package/dist/engine.js +854 -170
- package/dist/factory.d.ts +19 -0
- package/dist/factory.js +41 -5
- package/dist/hub.d.ts +290 -0
- package/dist/hub.js +408 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.js +2 -1
- package/dist/model.d.ts +36 -0
- package/dist/store.d.ts +14 -2
- package/dist/store.js +269 -21
- package/dist/types.d.ts +92 -0
- package/dist/untar.d.ts +47 -0
- package/dist/untar.js +164 -0
- package/dist/util.d.ts +76 -0
- package/dist/util.js +96 -0
- package/docs/authoring.md +48 -1
- package/docs/cli.md +446 -3
- package/docs/design.md +72 -9
- package/docs/embedding.md +53 -7
- package/package.json +1 -1
package/dist/add.js
ADDED
|
@@ -0,0 +1,999 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure helpers for the `owenloop add <owner>/<repo>[@ref]` CLI verb (workflow
|
|
3
|
+
* distribution Stage 1 — see the design doc this implements,
|
|
4
|
+
* `docs/workflow-distribution.md` §3 in the companion hub repo).
|
|
5
|
+
*
|
|
6
|
+
* These are the network-free, filesystem-adjacent pieces: spec parsing, URL
|
|
7
|
+
* building, lockfile read/write, and file installation. The network fetch and
|
|
8
|
+
* arg glue live in `src/cli.ts` (`dispatchAdd`) so this module stays trivially
|
|
9
|
+
* unit-testable and `cli.ts` doesn't widen its export surface just to reuse
|
|
10
|
+
* `Args`/`CliError`/etc.
|
|
11
|
+
*/
|
|
12
|
+
import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
|
|
13
|
+
import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
|
|
14
|
+
import { createHash, randomBytes } from 'node:crypto';
|
|
15
|
+
import { hostname } from 'node:os';
|
|
16
|
+
import { setTimeout as sleep } from 'node:timers/promises';
|
|
17
|
+
/** Max length for an in-archive relative path we are willing to join and write. */
|
|
18
|
+
const MAX_ARCHIVE_PATH_LENGTH = 1024;
|
|
19
|
+
/**
|
|
20
|
+
* Returns `undefined` if `relPath` is safe to `join()` under a destination
|
|
21
|
+
* directory, else a human-readable reason it must be rejected. This is
|
|
22
|
+
* reject-don't-normalize: a synthetic archive entry like
|
|
23
|
+
* `workflows/../../victim` is refused outright, never canonicalized into a
|
|
24
|
+
* "safe" path. Part of SEC-1 — an unnormalized entry name must never escape
|
|
25
|
+
* the staging or install directory.
|
|
26
|
+
*/
|
|
27
|
+
export function archivePathViolation(relPath) {
|
|
28
|
+
if (relPath === '')
|
|
29
|
+
return 'empty path';
|
|
30
|
+
if (relPath.includes('\0'))
|
|
31
|
+
return 'contains a NUL byte';
|
|
32
|
+
if (isAbsolute(relPath) || /^[\\/]/.test(relPath) || /^[A-Za-z]:/.test(relPath)) {
|
|
33
|
+
return 'is an absolute path';
|
|
34
|
+
}
|
|
35
|
+
// Split on both separators so '..\\' tricks and doubled separators can't
|
|
36
|
+
// smuggle a traversal segment past the check.
|
|
37
|
+
const segments = relPath.split(/[\\/]+/);
|
|
38
|
+
if (segments.some((s) => s === '.' || s === '..')) {
|
|
39
|
+
return "contains a '.' or '..' segment";
|
|
40
|
+
}
|
|
41
|
+
if (relPath.length > MAX_ARCHIVE_PATH_LENGTH) {
|
|
42
|
+
return `exceeds ${MAX_ARCHIVE_PATH_LENGTH}-char path length limit`;
|
|
43
|
+
}
|
|
44
|
+
return undefined;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Returns `undefined` if `relPath` is a safe SINGLE-SEGMENT lockfile install
|
|
48
|
+
* path, else a human-readable reason it must be rejected. Stricter than
|
|
49
|
+
* {@link archivePathViolation}: a lockfile entry's `path` is one on-disk path
|
|
50
|
+
* segment by construction — both the current `<owner>-<repo>-<hash>` scheme and
|
|
51
|
+
* the only legacy scheme this tool ever wrote (`<owner>-<repo>`, see
|
|
52
|
+
* {@link installFolder}) — so ANY separator is refused outright. That single
|
|
53
|
+
* rule makes `..` traversal, `.owenloop/../../x`, and nested escape shapes
|
|
54
|
+
* unrepresentable before any `join`/`rename` ever touches the path. Like
|
|
55
|
+
* `archivePathViolation` this is reject-don't-normalize: a bad path is refused,
|
|
56
|
+
* never canonicalized into a "safe" one.
|
|
57
|
+
*/
|
|
58
|
+
export function lockfilePathViolation(relPath) {
|
|
59
|
+
// Reuse the shared checks (empty, NUL, absolute, '.'/'..' segments, length).
|
|
60
|
+
const base = archivePathViolation(relPath);
|
|
61
|
+
if (base)
|
|
62
|
+
return base;
|
|
63
|
+
// A lockfile install path additionally must be a single segment: no
|
|
64
|
+
// separators at all, so a multi-segment on-disk path like 'legacy/olddir'
|
|
65
|
+
// (which passes archivePathViolation) is still refused here.
|
|
66
|
+
if (/[\\/]/.test(relPath))
|
|
67
|
+
return 'contains a path separator';
|
|
68
|
+
return undefined;
|
|
69
|
+
}
|
|
70
|
+
/** Parse `owner/repo` or `owner/repo@ref` into its parts; `ref` defaults to `'HEAD'`. */
|
|
71
|
+
export function parseRepoSpec(spec) {
|
|
72
|
+
const atIdx = spec.lastIndexOf('@');
|
|
73
|
+
const ownerRepo = atIdx >= 0 ? spec.slice(0, atIdx) : spec;
|
|
74
|
+
const ref = atIdx >= 0 ? spec.slice(atIdx + 1) : 'HEAD';
|
|
75
|
+
const slashIdx = ownerRepo.indexOf('/');
|
|
76
|
+
if (slashIdx < 0) {
|
|
77
|
+
throw new Error(`malformed repo spec '${spec}' — expected owner/repo[@ref]`);
|
|
78
|
+
}
|
|
79
|
+
const owner = ownerRepo.slice(0, slashIdx);
|
|
80
|
+
const repo = ownerRepo.slice(slashIdx + 1);
|
|
81
|
+
if (!owner || !repo) {
|
|
82
|
+
throw new Error(`malformed repo spec '${spec}' — expected owner/repo[@ref]`);
|
|
83
|
+
}
|
|
84
|
+
if (repo.includes('/')) {
|
|
85
|
+
throw new Error(`malformed repo spec '${spec}' — expected owner/repo[@ref]`);
|
|
86
|
+
}
|
|
87
|
+
if (!ref) {
|
|
88
|
+
throw new Error(`malformed repo spec '${spec}' — empty ref after '@'`);
|
|
89
|
+
}
|
|
90
|
+
// Owner and repo become a single on-disk path segment (see `installFolder`),
|
|
91
|
+
// so restrict them to the GitHub-legal charset (a superset — letters, digits,
|
|
92
|
+
// '.', '_', '-'). This guarantees no '/', '\\', or NUL can reach the folder
|
|
93
|
+
// name on any platform — defense-in-depth alongside `archivePathViolation`.
|
|
94
|
+
if (!REPO_NAME_RE.test(owner) || !REPO_NAME_RE.test(repo)) {
|
|
95
|
+
throw new Error(`malformed repo spec '${spec}' — owner and repo may only contain letters, digits, '.', '_', '-'`);
|
|
96
|
+
}
|
|
97
|
+
return { owner, repo, ref };
|
|
98
|
+
}
|
|
99
|
+
/** GitHub-legal (superset) charset for an owner/repo name — see `parseRepoSpec`. */
|
|
100
|
+
const REPO_NAME_RE = /^[A-Za-z0-9._-]+$/;
|
|
101
|
+
/**
|
|
102
|
+
* The single-path-segment install folder for a package, derived from its
|
|
103
|
+
* `owner/repo` identity: `<owner>-<repo>-<sha256(owner/repo)[:8]>`. The 8-hex
|
|
104
|
+
* suffix makes the (owner,repo)→folder mapping injective in practice — the old
|
|
105
|
+
* `<owner>-<repo>` scheme collided (`a-b/c` and `a/b-c` both mapped to
|
|
106
|
+
* `a-b-c`, and the second install clobbered the first). Keying on the source
|
|
107
|
+
* (matching the lockfile key) keeps the folder STABLE across versions, so a
|
|
108
|
+
* user's documented `--defs workflows/<folder>` pointer survives upgrades.
|
|
109
|
+
*/
|
|
110
|
+
export function installFolder(owner, repo) {
|
|
111
|
+
const hash = createHash('sha256').update(`${owner}/${repo}`).digest('hex').slice(0, 8);
|
|
112
|
+
return `${owner}-${repo}-${hash}`;
|
|
113
|
+
}
|
|
114
|
+
export function githubShaUrl(owner, repo, ref) {
|
|
115
|
+
return `https://api.github.com/repos/${owner}/${repo}/commits/${ref}`;
|
|
116
|
+
}
|
|
117
|
+
export function githubTarballUrl(owner, repo, sha) {
|
|
118
|
+
return `https://api.github.com/repos/${owner}/${repo}/tarball/${sha}`;
|
|
119
|
+
}
|
|
120
|
+
/** A 40-char hex commit sha (case-insensitive), as GitHub returns. */
|
|
121
|
+
const SHA_HEX_RE = /^[0-9a-f]{40}$/i;
|
|
122
|
+
function isPlainObject(value) {
|
|
123
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Structurally validate a parsed `installed.json`, fail-closed. A
|
|
127
|
+
* parseable-but-schema-invalid lockfile is a hard error naming the offending
|
|
128
|
+
* entry+field — never silently reset to `{}` (which would erase ownership
|
|
129
|
+
* records and re-enable the clobbering {@link installFolder} was hardened
|
|
130
|
+
* against) and never normalized. This is the trust boundary for the lockfile:
|
|
131
|
+
* downstream code (`dispatchAdd`, `parkOldNameDir`) may only act on entries
|
|
132
|
+
* that have passed through here. Critically, EVERY entry is validated, not just
|
|
133
|
+
* the one being installed — `dispatchAdd` re-serializes the whole lockfile on
|
|
134
|
+
* success, so acting while carrying a poisoned sibling entry would re-persist
|
|
135
|
+
* it. Unknown extra keys (on the lockfile or an entry) are tolerated for
|
|
136
|
+
* forward compatibility; required shape is enforced, additions are not
|
|
137
|
+
* forbidden. Returns the value narrowed to {@link Lockfile}. `path` appears
|
|
138
|
+
* only in error messages.
|
|
139
|
+
*/
|
|
140
|
+
export function validateLockfile(parsed, path) {
|
|
141
|
+
const fail = (detail) => {
|
|
142
|
+
throw new Error(`invalid lockfile at ${path}: ${detail} — fix or remove it manually`);
|
|
143
|
+
};
|
|
144
|
+
if (!isPlainObject(parsed))
|
|
145
|
+
return fail('top-level value is not an object');
|
|
146
|
+
if (parsed.version !== 1) {
|
|
147
|
+
return fail(`unsupported lockfile version ${JSON.stringify(parsed.version)} (expected 1)`);
|
|
148
|
+
}
|
|
149
|
+
if (!isPlainObject(parsed.installed))
|
|
150
|
+
return fail("'installed' is not an object");
|
|
151
|
+
for (const [key, entry] of Object.entries(parsed.installed)) {
|
|
152
|
+
const at = (field) => `installed[${JSON.stringify(key)}].${field}`;
|
|
153
|
+
if (!isPlainObject(entry))
|
|
154
|
+
return fail(`installed[${JSON.stringify(key)}] is not an object`);
|
|
155
|
+
if (typeof entry.source !== 'string' || entry.source === '') {
|
|
156
|
+
return fail(`${at('source')} is not a non-empty string`);
|
|
157
|
+
}
|
|
158
|
+
if (entry.source !== key) {
|
|
159
|
+
return fail(`${at('source')} '${entry.source}' does not match its key '${key}'`);
|
|
160
|
+
}
|
|
161
|
+
if (typeof entry.ref !== 'string' || entry.ref === '') {
|
|
162
|
+
return fail(`${at('ref')} is not a non-empty string`);
|
|
163
|
+
}
|
|
164
|
+
if (typeof entry.sha !== 'string' || !SHA_HEX_RE.test(entry.sha)) {
|
|
165
|
+
return fail(`${at('sha')} is not a 40-char hex commit sha`);
|
|
166
|
+
}
|
|
167
|
+
if (typeof entry.installedAt !== 'number' || !Number.isFinite(entry.installedAt)) {
|
|
168
|
+
return fail(`${at('installedAt')} is not a finite number`);
|
|
169
|
+
}
|
|
170
|
+
if (typeof entry.path !== 'string')
|
|
171
|
+
return fail(`${at('path')} is not a string`);
|
|
172
|
+
const pathViolation = lockfilePathViolation(entry.path);
|
|
173
|
+
if (pathViolation)
|
|
174
|
+
return fail(`${at('path')} ${pathViolation}`);
|
|
175
|
+
if (!Array.isArray(entry.files))
|
|
176
|
+
return fail(`${at('files')} is not an array`);
|
|
177
|
+
entry.files.forEach((file, i) => {
|
|
178
|
+
if (typeof file !== 'string')
|
|
179
|
+
return fail(`${at(`files[${i}]`)} is not a string`);
|
|
180
|
+
const fileViolation = archivePathViolation(file);
|
|
181
|
+
if (fileViolation)
|
|
182
|
+
return fail(`${at(`files[${i}]`)} ${fileViolation}`);
|
|
183
|
+
});
|
|
184
|
+
}
|
|
185
|
+
return parsed;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Read `.owenloop/installed.json`; a missing file is an empty lockfile, not an
|
|
189
|
+
* error. A file that exists but does not parse is a hard error naming the path
|
|
190
|
+
* — never silently reset to `{}`, which would erase ownership records and
|
|
191
|
+
* re-enable the clobbering `installFolder` was hardened against. A file that
|
|
192
|
+
* parses but is structurally invalid (bad version, malformed entry, a `path`
|
|
193
|
+
* that is not a safe single segment, a bad `sha`/`files`) is likewise a
|
|
194
|
+
* fail-closed hard error — see {@link validateLockfile}. The lockfile is never
|
|
195
|
+
* trusted for filesystem paths.
|
|
196
|
+
*/
|
|
197
|
+
export function readLockfile(path) {
|
|
198
|
+
if (!existsSync(path))
|
|
199
|
+
return { version: 1, installed: {} };
|
|
200
|
+
const raw = readFileSync(path, 'utf8');
|
|
201
|
+
let parsed;
|
|
202
|
+
try {
|
|
203
|
+
parsed = JSON.parse(raw);
|
|
204
|
+
}
|
|
205
|
+
catch (e) {
|
|
206
|
+
throw new Error(`corrupt lockfile at ${path}: ${e.message} — fix or remove it manually`);
|
|
207
|
+
}
|
|
208
|
+
return validateLockfile(parsed, path);
|
|
209
|
+
}
|
|
210
|
+
/**
|
|
211
|
+
* Serialize `value` as pretty JSON into a sibling temp file, then `renameSync`
|
|
212
|
+
* over `path` — the same atomic tmp+rename discipline {@link writeLockfile} has
|
|
213
|
+
* always used, extracted so the crash-recovery journal writer
|
|
214
|
+
* ({@link writeAddJournal}) shares one implementation of it (and its
|
|
215
|
+
* double-fault cleanup semantics) rather than duplicating the seam. A crash or
|
|
216
|
+
* a concurrent reader never sees a half-written file (rename is atomic within a
|
|
217
|
+
* directory).
|
|
218
|
+
*
|
|
219
|
+
* If the final `renameSync` throws (EACCES, EISDIR on `path`, a full disk), the
|
|
220
|
+
* temp sibling is removed on a best-effort basis before the error propagates so
|
|
221
|
+
* a failed write cannot leak a `<path>.tmp.<pid>` file. The original rename
|
|
222
|
+
* error is surfaced unchanged — never swallowed, and never masked by a failure
|
|
223
|
+
* of that cleanup removal (if the removal itself throws, that error is swallowed
|
|
224
|
+
* and the tmp sibling may remain in that double fault).
|
|
225
|
+
*/
|
|
226
|
+
function writeJsonAtomic(path, value, opts = {}) {
|
|
227
|
+
const rm = opts.rm ?? ((p, o) => rmSync(p, o));
|
|
228
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
229
|
+
const tmp = `${path}.tmp.${process.pid}`;
|
|
230
|
+
writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
|
|
231
|
+
try {
|
|
232
|
+
renameSync(tmp, path);
|
|
233
|
+
}
|
|
234
|
+
catch (e) {
|
|
235
|
+
// Best-effort cleanup: the temp sibling should not leak on a failed write,
|
|
236
|
+
// but if the removal ITSELF throws (e.g. unlink EACCES) we must not let that
|
|
237
|
+
// replace the original rename error — swallow the cleanup error and rethrow
|
|
238
|
+
// `e`. A tmp sibling may survive in that double fault.
|
|
239
|
+
try {
|
|
240
|
+
rm(tmp, { force: true });
|
|
241
|
+
}
|
|
242
|
+
catch {
|
|
243
|
+
// ignore — surfacing the original rename error matters more than cleanup.
|
|
244
|
+
}
|
|
245
|
+
throw e;
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
export function writeLockfile(path, lf, opts = {}) {
|
|
249
|
+
writeJsonAtomic(path, lf, opts);
|
|
250
|
+
}
|
|
251
|
+
// ---- staging + atomic commit -----------------------------------------------
|
|
252
|
+
/** The staging root under a defs dir where installs are assembled + validated. */
|
|
253
|
+
export const STAGING_DIRNAME = '.owenloop-staging';
|
|
254
|
+
/**
|
|
255
|
+
* Write `files` (relative path → bytes) into `targetDir` (a staging dir), NOT
|
|
256
|
+
* the final install destination. Unlike a direct install, this never clears a
|
|
257
|
+
* live folder: the caller stages here, validates, then `commitInstall`s with an
|
|
258
|
+
* atomic rename, so a failure mid-write can only ever corrupt throwaway staging
|
|
259
|
+
* content. Returns the sorted list of relative paths written.
|
|
260
|
+
*/
|
|
261
|
+
export function stageFiles(targetDir, files) {
|
|
262
|
+
const written = [];
|
|
263
|
+
for (const [relPath, bytes] of files) {
|
|
264
|
+
// Defense-in-depth: this function is exported and writes whole directory
|
|
265
|
+
// trees, so it must not trust its caller to have validated keys.
|
|
266
|
+
const violation = archivePathViolation(relPath);
|
|
267
|
+
if (violation) {
|
|
268
|
+
throw new Error(`refusing to write unsafe archive path '${relPath}': ${violation}`);
|
|
269
|
+
}
|
|
270
|
+
const full = join(targetDir, relPath);
|
|
271
|
+
mkdirSync(dirname(full), { recursive: true });
|
|
272
|
+
writeFileSync(full, bytes);
|
|
273
|
+
written.push(relPath);
|
|
274
|
+
}
|
|
275
|
+
return written.sort();
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* Thrown by `commitInstall` when the atomic swap fails AND the rollback of it
|
|
279
|
+
* fails too — a near-impossible same-filesystem double-fault. Carries the path
|
|
280
|
+
* where the previous version was left so the caller can preserve it (its
|
|
281
|
+
* `preservedAt` sits under the staging root, which the caller would otherwise
|
|
282
|
+
* clean up as debris). A distinguishable type so the caller can tell this
|
|
283
|
+
* "must-preserve" double-fault apart from an ordinary swap failure.
|
|
284
|
+
*/
|
|
285
|
+
export class RollbackFailedError extends Error {
|
|
286
|
+
preservedAt;
|
|
287
|
+
constructor(message, preservedAt) {
|
|
288
|
+
super(message);
|
|
289
|
+
this.name = 'RollbackFailedError';
|
|
290
|
+
this.preservedAt = preservedAt;
|
|
291
|
+
}
|
|
292
|
+
}
|
|
293
|
+
/**
|
|
294
|
+
* Atomically swap a validated `stagingDir` into place at `defsDir/folder`,
|
|
295
|
+
* rolling back to the previous install if the swap itself fails. Both dirs live
|
|
296
|
+
* on the same filesystem by construction (staging is under `defsDir`), so the
|
|
297
|
+
* renames are atomic and `EXDEV` is impossible.
|
|
298
|
+
*
|
|
299
|
+
* Two-phase commit: unlike a one-shot swap, this does NOT delete the displaced
|
|
300
|
+
* previous install on success — it returns an {@link InstallCommitHandle} whose
|
|
301
|
+
* `backupDir` still holds it. The caller must then either
|
|
302
|
+
* {@link finalizeInstallCommit} (discard the backup, making the swap permanent)
|
|
303
|
+
* once its follow-on work — the lockfile write — has durably succeeded, or
|
|
304
|
+
* {@link rollbackInstallCommit} to restore the previous directory state if that
|
|
305
|
+
* work fails. This is what lets "commit the directory + write the lockfile" be
|
|
306
|
+
* one recoverable operation.
|
|
307
|
+
*
|
|
308
|
+
* Sequence: back up any existing install (rename dest → `<stagingDir>-old`) — if
|
|
309
|
+
* that fails nothing has changed; rename staging → dest; on failure rename the
|
|
310
|
+
* backup back (throwing {@link RollbackFailedError} if even that fails, so the
|
|
311
|
+
* caller can preserve the named copy).
|
|
312
|
+
*/
|
|
313
|
+
export function commitInstall(defsDir, folder, stagingDir) {
|
|
314
|
+
mkdirSync(defsDir, { recursive: true });
|
|
315
|
+
const dest = join(defsDir, folder);
|
|
316
|
+
const backupDir = `${stagingDir}-old`;
|
|
317
|
+
const undoDir = `${stagingDir}-undo`;
|
|
318
|
+
let backedUp = false;
|
|
319
|
+
if (existsSync(dest)) {
|
|
320
|
+
// Ownership is verified by the caller before we get here. If this rename
|
|
321
|
+
// throws, nothing has changed — dest is still the previous install.
|
|
322
|
+
renameSync(dest, backupDir);
|
|
323
|
+
backedUp = true;
|
|
324
|
+
}
|
|
325
|
+
try {
|
|
326
|
+
renameSync(stagingDir, dest);
|
|
327
|
+
}
|
|
328
|
+
catch (e) {
|
|
329
|
+
if (backedUp) {
|
|
330
|
+
try {
|
|
331
|
+
renameSync(backupDir, dest);
|
|
332
|
+
}
|
|
333
|
+
catch (rollbackErr) {
|
|
334
|
+
// Near-impossible (same dir, same fs), but if even the rollback fails,
|
|
335
|
+
// name the backup so the previous version is recoverable by hand — and
|
|
336
|
+
// signal (via the type) that the caller must preserve it.
|
|
337
|
+
throw new RollbackFailedError(`install of '${folder}' failed and rollback failed too; ` +
|
|
338
|
+
`previous version preserved at ${backupDir}: ${rollbackErr.message}`, backupDir);
|
|
339
|
+
}
|
|
340
|
+
}
|
|
341
|
+
throw e;
|
|
342
|
+
}
|
|
343
|
+
return { dest, backupDir: backedUp ? backupDir : undefined, undoDir };
|
|
344
|
+
}
|
|
345
|
+
/**
|
|
346
|
+
* Migrate a source off its old `<owner>-<repo>` install directory by PARKING it
|
|
347
|
+
* (rename → `<stagingDir>-undo-oldname`) instead of deleting it, so a later
|
|
348
|
+
* rollback can put it back where the (still-unchanged) lockfile expects it.
|
|
349
|
+
* Records the move on `handle.oldName`. If the old dir does not exist on disk
|
|
350
|
+
* (the lockfile names a path that is already gone), records nothing — matching
|
|
351
|
+
* the previous `rmSync(..., { force: true })` tolerance of absence.
|
|
352
|
+
*
|
|
353
|
+
* Defense-in-depth (Layer 3): even though `readLockfile`/`validateLockfile` and
|
|
354
|
+
* the use-site in `dispatchAdd` already constrain `oldRelPath` to a safe single
|
|
355
|
+
* segment, the authoritative containment check is re-asserted HERE, at the
|
|
356
|
+
* mutation site, before any rename — a poisoned `existing.path` must never move
|
|
357
|
+
* a directory outside `defsDir` (which `finalizeInstallCommit` would then
|
|
358
|
+
* recursively delete). Following this project's TOCTOU discipline, the check
|
|
359
|
+
* that matters is the one at the filesystem operation, not only up front:
|
|
360
|
+
* `oldRelPath` must be a single segment AND resolve under `defsDir`, and the
|
|
361
|
+
* target must be a real directory — a symlink at the legacy path is refused (a
|
|
362
|
+
* symlinked segment must never be parked/finalized, since finalize deletes it).
|
|
363
|
+
* Deliberate behavior change vs. the old `existsSync` probe: a DANGLING symlink
|
|
364
|
+
* at the old path was previously silently ignored (existsSync follows links);
|
|
365
|
+
* it is now refused, which is fail-closed and correct.
|
|
366
|
+
*/
|
|
367
|
+
export function parkOldNameDir(handle, defsDir, oldRelPath) {
|
|
368
|
+
const violation = lockfilePathViolation(oldRelPath);
|
|
369
|
+
if (violation) {
|
|
370
|
+
throw new Error(`refusing old-name migration path '${oldRelPath}': ${violation}`);
|
|
371
|
+
}
|
|
372
|
+
const originalPath = join(defsDir, oldRelPath);
|
|
373
|
+
// Resolved-path containment: '..'-free by the single-segment rule above, but
|
|
374
|
+
// recompute at the rename site so no path outside defsDir can ever be moved.
|
|
375
|
+
if (!resolve(originalPath).startsWith(resolve(defsDir) + sep)) {
|
|
376
|
+
throw new Error(`refusing old-name migration path '${oldRelPath}': escapes the defs directory`);
|
|
377
|
+
}
|
|
378
|
+
let st;
|
|
379
|
+
try {
|
|
380
|
+
st = lstatSync(originalPath); // lstat, not stat: never follow a symlink here.
|
|
381
|
+
}
|
|
382
|
+
catch (e) {
|
|
383
|
+
if (e.code === 'ENOENT')
|
|
384
|
+
return; // already gone — nothing to park
|
|
385
|
+
throw e;
|
|
386
|
+
}
|
|
387
|
+
if (st.isSymbolicLink()) {
|
|
388
|
+
throw new Error(`refusing old-name migration: '${originalPath}' is a symlink`);
|
|
389
|
+
}
|
|
390
|
+
if (!st.isDirectory()) {
|
|
391
|
+
throw new Error(`refusing old-name migration: '${originalPath}' is not a directory`);
|
|
392
|
+
}
|
|
393
|
+
const parkedAt = `${handle.undoDir}-oldname`;
|
|
394
|
+
renameSync(originalPath, parkedAt);
|
|
395
|
+
handle.oldName = { originalPath, parkedAt };
|
|
396
|
+
}
|
|
397
|
+
/**
|
|
398
|
+
* Make the commit permanent: discard the retained previous install and any
|
|
399
|
+
* parked old-name dir. Call ONLY after the follow-on lockfile write has durably
|
|
400
|
+
* succeeded — this is the point of no return.
|
|
401
|
+
*/
|
|
402
|
+
export function finalizeInstallCommit(handle) {
|
|
403
|
+
if (handle.backupDir)
|
|
404
|
+
rmSync(handle.backupDir, { recursive: true, force: true });
|
|
405
|
+
if (handle.oldName)
|
|
406
|
+
rmSync(handle.oldName.parkedAt, { recursive: true, force: true });
|
|
407
|
+
}
|
|
408
|
+
/**
|
|
409
|
+
* Undo a `commitInstall` (plus any `parkOldNameDir`), restoring the pre-commit
|
|
410
|
+
* directory state. Order matters:
|
|
411
|
+
* 1. park the new content out of `dest` (rename dest → undoDir) — for a fresh
|
|
412
|
+
* install, this alone restores "nothing installed";
|
|
413
|
+
* 2. if a previous install was displaced, rename its backup back over `dest`;
|
|
414
|
+
* 3. if an old-name dir was parked, rename it back to where the lockfile says.
|
|
415
|
+
* The parked new content under `undoDir` is left for the caller's staging-root
|
|
416
|
+
* cleanup to dispose of. Any throw propagates to the caller.
|
|
417
|
+
*
|
|
418
|
+
* Safe to call from a FAILED `parkOldNameDir`: that helper records
|
|
419
|
+
* `handle.oldName` only after its single rename succeeds, so a park failure
|
|
420
|
+
* leaves `oldName` unset and step 3 self-skips — there is no "park partially
|
|
421
|
+
* happened" state to reconcile (the park is one atomic rename).
|
|
422
|
+
*/
|
|
423
|
+
export function rollbackInstallCommit(handle) {
|
|
424
|
+
renameSync(handle.dest, handle.undoDir);
|
|
425
|
+
if (handle.backupDir)
|
|
426
|
+
renameSync(handle.backupDir, handle.dest);
|
|
427
|
+
if (handle.oldName)
|
|
428
|
+
renameSync(handle.oldName.parkedAt, handle.oldName.originalPath);
|
|
429
|
+
}
|
|
430
|
+
// ---- per-project install lock ----------------------------------------------
|
|
431
|
+
/** Default wait/stale/poll timings for the install lock (overridable in tests). */
|
|
432
|
+
const LOCK_WAIT_MS = 10_000;
|
|
433
|
+
const LOCK_STALE_MS = 10 * 60_000;
|
|
434
|
+
const LOCK_POLL_MS = 100;
|
|
435
|
+
/** `true` if a process with `pid` exists (signal 0 probes without delivering). */
|
|
436
|
+
function defaultIsPidAlive(pid) {
|
|
437
|
+
try {
|
|
438
|
+
process.kill(pid, 0);
|
|
439
|
+
return true;
|
|
440
|
+
}
|
|
441
|
+
catch (e) {
|
|
442
|
+
// EPERM: the process exists but we may not signal it — treat as alive.
|
|
443
|
+
// ESRCH (and anything else): no such process — dead.
|
|
444
|
+
return e.code === 'EPERM';
|
|
445
|
+
}
|
|
446
|
+
}
|
|
447
|
+
/** Read the lock file's raw bytes, or `null` if it is gone/unreadable. */
|
|
448
|
+
function readLockRaw(lockPath) {
|
|
449
|
+
try {
|
|
450
|
+
return readFileSync(lockPath, 'utf8');
|
|
451
|
+
}
|
|
452
|
+
catch {
|
|
453
|
+
return null;
|
|
454
|
+
}
|
|
455
|
+
}
|
|
456
|
+
/** Parse raw lock bytes into a holder, or `null` if absent/unparseable. */
|
|
457
|
+
function parseLockHolder(raw) {
|
|
458
|
+
if (raw === null)
|
|
459
|
+
return null;
|
|
460
|
+
try {
|
|
461
|
+
return JSON.parse(raw);
|
|
462
|
+
}
|
|
463
|
+
catch {
|
|
464
|
+
return null;
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
/** Read + parse the lock file in one step (fresh read). Used off the hot loop. */
|
|
468
|
+
function readLockHolder(lockPath) {
|
|
469
|
+
return parseLockHolder(readLockRaw(lockPath));
|
|
470
|
+
}
|
|
471
|
+
/**
|
|
472
|
+
* Decide whether the lock described by `holder` (parsed from a raw read) may be
|
|
473
|
+
* reclaimed, given the current host. Liveness-aware, not age-based:
|
|
474
|
+
*
|
|
475
|
+
* 1. `statSync` fails — the lock vanished mid-judgment → treat as reclaimable
|
|
476
|
+
* (the acquire loop re-verifies and simply retries the exclusive create).
|
|
477
|
+
* 2. Holder records a `host` that differs from ours → NOT stale, ever. A
|
|
478
|
+
* foreign PID space means `process.kill(pid, 0)` proves nothing; a shared
|
|
479
|
+
* filesystem could be locked by another machine. Held; caller refuses.
|
|
480
|
+
* 3. Holder has a numeric `pid` and either matches our host or omits `host`
|
|
481
|
+
* (a legacy same-machine payload) → stale iff that pid is dead. Age never
|
|
482
|
+
* reclaims a live-pid lock — this is the core safety policy.
|
|
483
|
+
* 4. Unparseable, or parses without a numeric pid → fail closed: held until
|
|
484
|
+
* `now() - mtimeMs > staleMs` (age is the only abandonment signal left).
|
|
485
|
+
*/
|
|
486
|
+
function lockIsStale(lockPath, holder, staleMs, isPidAlive, now, currentHost) {
|
|
487
|
+
let mtimeMs;
|
|
488
|
+
try {
|
|
489
|
+
mtimeMs = statSync(lockPath).mtimeMs;
|
|
490
|
+
}
|
|
491
|
+
catch {
|
|
492
|
+
// Vanished between the EEXIST and here — someone else reclaimed it; retry.
|
|
493
|
+
return true;
|
|
494
|
+
}
|
|
495
|
+
// Case 2: recorded on a different host — its pid tells us nothing. Held.
|
|
496
|
+
if (holder && typeof holder.host === 'string' && holder.host !== currentHost) {
|
|
497
|
+
return false;
|
|
498
|
+
}
|
|
499
|
+
// Case 3: same host (or legacy no-host payload) with a numeric pid — liveness decides.
|
|
500
|
+
if (holder && typeof holder.pid === 'number') {
|
|
501
|
+
return !isPidAlive(holder.pid);
|
|
502
|
+
}
|
|
503
|
+
// Case 4: no attributable live owner — age is the only abandonment signal.
|
|
504
|
+
return now() - mtimeMs > staleMs;
|
|
505
|
+
}
|
|
506
|
+
/**
|
|
507
|
+
* Acquire the per-project install lock at `lockPath` (an exclusive-create of the
|
|
508
|
+
* file, `openSync(..,'wx')` — the O_EXCL create is the real serialization point).
|
|
509
|
+
* The payload carries an ownership token, the owner pid, a start timestamp, and
|
|
510
|
+
* the host. If another process holds it: reclaim it only when liveness-aware
|
|
511
|
+
* staleness says its owner is gone (see `lockIsStale`), otherwise poll until it
|
|
512
|
+
* frees, and if it does not free within `waitMs` fail cleanly with a clear
|
|
513
|
+
* in-progress message. Always pair with `releaseInstallLock` in a `finally`.
|
|
514
|
+
*/
|
|
515
|
+
export async function acquireInstallLock(lockPath, opts = {}) {
|
|
516
|
+
const waitMs = opts.waitMs ?? LOCK_WAIT_MS;
|
|
517
|
+
const staleMs = opts.staleMs ?? LOCK_STALE_MS;
|
|
518
|
+
const pollMs = opts.pollMs ?? LOCK_POLL_MS;
|
|
519
|
+
const isPidAlive = opts.isPidAlive ?? defaultIsPidAlive;
|
|
520
|
+
const now = opts.now ?? Date.now;
|
|
521
|
+
const host = (opts.hostname ?? hostname)();
|
|
522
|
+
mkdirSync(dirname(lockPath), { recursive: true });
|
|
523
|
+
const deadline = now() + waitMs;
|
|
524
|
+
for (;;) {
|
|
525
|
+
try {
|
|
526
|
+
const fd = openSync(lockPath, 'wx');
|
|
527
|
+
const token = randomBytes(16).toString('hex');
|
|
528
|
+
try {
|
|
529
|
+
writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: now(), token, host }));
|
|
530
|
+
}
|
|
531
|
+
finally {
|
|
532
|
+
closeSync(fd);
|
|
533
|
+
}
|
|
534
|
+
return { lockPath, acquired: true, token };
|
|
535
|
+
}
|
|
536
|
+
catch (e) {
|
|
537
|
+
if (e.code !== 'EEXIST')
|
|
538
|
+
throw e;
|
|
539
|
+
}
|
|
540
|
+
// Judge staleness from a single captured raw read...
|
|
541
|
+
const raw = readLockRaw(lockPath);
|
|
542
|
+
const holder = parseLockHolder(raw);
|
|
543
|
+
if (lockIsStale(lockPath, holder, staleMs, isPidAlive, now, host)) {
|
|
544
|
+
// ...then re-verify the bytes are unchanged immediately before deleting.
|
|
545
|
+
// Between judging stale and rmSync a third process could reclaim and
|
|
546
|
+
// re-create the lock; deleting then would destroy a *fresh* owner's lock.
|
|
547
|
+
// Residual window is a few syscalls (read-compare-delete) rather than the
|
|
548
|
+
// poll interval — and the `wx` create below is the true arbiter: if two
|
|
549
|
+
// reclaimers race, one wins the create and the other loops on EEXIST. A
|
|
550
|
+
// rename-based reclaim was rejected: POSIX rename clobbers its target, so
|
|
551
|
+
// any "rename back on mismatch" arm can itself destroy a newer lock.
|
|
552
|
+
const raw2 = readLockRaw(lockPath);
|
|
553
|
+
if (raw2 !== null && raw2 === raw) {
|
|
554
|
+
rmSync(lockPath, { force: true });
|
|
555
|
+
continue; // reclaimed — retry the exclusive create
|
|
556
|
+
}
|
|
557
|
+
// Bytes changed under us, or the lock is stat-able but unreadable (a
|
|
558
|
+
// root-owned 0600 lock: statSync needs only dir perms, readFileSync
|
|
559
|
+
// EACCES → raw/raw2 null). Do NOT delete — fall through to the deadline
|
|
560
|
+
// check and poll sleep below. Never `continue` here: with an unreadable,
|
|
561
|
+
// backdated lock this branch would otherwise spin sleeplessly, starving
|
|
562
|
+
// the event loop and never enforcing `waitMs`.
|
|
563
|
+
}
|
|
564
|
+
if (now() >= deadline) {
|
|
565
|
+
throw new Error(inProgressMessage(lockPath, holder, waitMs));
|
|
566
|
+
}
|
|
567
|
+
await sleep(pollMs);
|
|
568
|
+
}
|
|
569
|
+
}
|
|
570
|
+
/** Build the clear "another add is in progress" timeout error, with graceful fallbacks. */
|
|
571
|
+
function inProgressMessage(lockPath, holder, waitMs) {
|
|
572
|
+
const who = typeof holder?.pid === 'number' ? `pid ${holder.pid}` : 'another process';
|
|
573
|
+
// Lock content is untrusted input: a finite `startedAt` outside the ECMAScript
|
|
574
|
+
// Date range (|t| > 8.64e15 ms) makes `new Date(t).toISOString()` throw
|
|
575
|
+
// RangeError. Only render held-since when the value is a valid time value;
|
|
576
|
+
// otherwise omit it (same graceful fallback as an absent startedAt).
|
|
577
|
+
const heldSince = typeof holder?.startedAt === 'number' &&
|
|
578
|
+
Number.isFinite(holder.startedAt) &&
|
|
579
|
+
Math.abs(holder.startedAt) <= 8.64e15
|
|
580
|
+
? `, held since ${new Date(holder.startedAt).toISOString()}`
|
|
581
|
+
: '';
|
|
582
|
+
const s = Math.round(waitMs / 1000);
|
|
583
|
+
return `another owenloop add is in progress (${who}${heldSince}) — holds ${lockPath}; timed out waiting after ${s}s`;
|
|
584
|
+
}
|
|
585
|
+
/**
|
|
586
|
+
* Release a lock acquired by `acquireInstallLock`. Token-checked and
|
|
587
|
+
* best-effort: a no-op if not acquired, if the lock is already gone/unparseable,
|
|
588
|
+
* or if its token no longer matches this handle (someone else legitimately
|
|
589
|
+
* re-acquired it — deleting would steal *their* lock). Never throws; it runs in
|
|
590
|
+
* `dispatchAdd`'s `finally` and must not mask the real error.
|
|
591
|
+
*/
|
|
592
|
+
export function releaseInstallLock(handle) {
|
|
593
|
+
if (!handle.acquired)
|
|
594
|
+
return;
|
|
595
|
+
try {
|
|
596
|
+
const holder = readLockHolder(handle.lockPath);
|
|
597
|
+
if (!holder || holder.token !== handle.token)
|
|
598
|
+
return;
|
|
599
|
+
rmSync(handle.lockPath, { force: true });
|
|
600
|
+
}
|
|
601
|
+
catch {
|
|
602
|
+
// Already reclaimed/replaced, or an unexpected fs error — swallow.
|
|
603
|
+
}
|
|
604
|
+
}
|
|
605
|
+
// ---- crash-recovery journal ------------------------------------------------
|
|
606
|
+
//
|
|
607
|
+
// A process that dies (crash, SIGKILL — see docs/cli.md on power-loss limits)
|
|
608
|
+
// partway through the destructive part of an install — the `commitInstall` swap,
|
|
609
|
+
// the old-name park, or the ledger write — must leave `.owenloop` recoverable to a consistent
|
|
610
|
+
// (defs-on-disk ⇔ ledger) state by the NEXT `add`, never a half-applied tree.
|
|
611
|
+
// Today's failure arms in `dispatchAdd` only cover IN-PROCESS failures (a throw
|
|
612
|
+
// we catch and roll back); a hard kill skips them entirely. This journal closes
|
|
613
|
+
// that gap: `dispatchAdd` writes a one-record intent file before the first
|
|
614
|
+
// destructive step and advances/removes it as the install progresses, and the
|
|
615
|
+
// next `add` runs `recoverInterruptedInstall` under the same A3 install lock,
|
|
616
|
+
// BEFORE the stale-staging cleanup, to roll a leftover install forward or back.
|
|
617
|
+
//
|
|
618
|
+
// The journal is attacker-influenceable input, exactly like the lockfile (a
|
|
619
|
+
// hostile checkout can ship a crafted `.owenloop/add.journal`). It is validated
|
|
620
|
+
// fail-closed with the A1 discipline (`lockfilePathViolation` on every path
|
|
621
|
+
// field, single-segment ⇒ traversal unrepresentable), every mutation path is
|
|
622
|
+
// re-derived from the CURRENT run's resolved `defsDir` plus those validated
|
|
623
|
+
// segments — never from a recorded absolute path — and A2's symlink rule is
|
|
624
|
+
// re-asserted at each mutation site. Any bad shape, unknown phase, defsDir
|
|
625
|
+
// mismatch, or contradictory disk state REFUSES with no filesystem mutation and
|
|
626
|
+
// leaves the journal in place as evidence.
|
|
627
|
+
/** Journal filename under `.owenloop/` (sibling of `installed.json`/`add.lock`). */
|
|
628
|
+
export const ADD_JOURNAL_FILENAME = 'add.journal';
|
|
629
|
+
/**
|
|
630
|
+
* Structurally validate a parsed `add.journal`, fail-closed — the trust
|
|
631
|
+
* boundary for the journal, mirroring {@link validateLockfile}. A
|
|
632
|
+
* parseable-but-invalid journal is a hard error naming the file and the manual
|
|
633
|
+
* remedy; recovery NEVER acts on a field that has not passed through here. Every
|
|
634
|
+
* path field must be a safe single segment so a crafted journal cannot represent
|
|
635
|
+
* traversal before any `join`/`rename`. Unknown extra keys are tolerated
|
|
636
|
+
* (forward compatibility, same as the lockfile). `ref`/`startedAt` are
|
|
637
|
+
* diagnostics: validated for type when present, but not required. `path`
|
|
638
|
+
* appears only in error messages.
|
|
639
|
+
*/
|
|
640
|
+
export function validateAddJournal(parsed, path) {
|
|
641
|
+
const fail = (detail) => {
|
|
642
|
+
throw new Error(`invalid crash-recovery journal at ${path}: ${detail} — ` +
|
|
643
|
+
`inspect and remove it manually, then re-run add`);
|
|
644
|
+
};
|
|
645
|
+
if (!isPlainObject(parsed))
|
|
646
|
+
return fail('top-level value is not an object');
|
|
647
|
+
if (parsed.version !== 1) {
|
|
648
|
+
return fail(`unsupported journal version ${JSON.stringify(parsed.version)} (expected 1)`);
|
|
649
|
+
}
|
|
650
|
+
if (parsed.phase !== 'applying' && parsed.phase !== 'finalizing') {
|
|
651
|
+
return fail(`unknown phase ${JSON.stringify(parsed.phase)} (expected 'applying' or 'finalizing')`);
|
|
652
|
+
}
|
|
653
|
+
if (typeof parsed.source !== 'string' || parsed.source === '') {
|
|
654
|
+
return fail("'source' is not a non-empty string");
|
|
655
|
+
}
|
|
656
|
+
if (typeof parsed.sha !== 'string' || !SHA_HEX_RE.test(parsed.sha)) {
|
|
657
|
+
return fail("'sha' is not a 40-char hex commit sha");
|
|
658
|
+
}
|
|
659
|
+
const segment = (field, value) => {
|
|
660
|
+
if (typeof value !== 'string')
|
|
661
|
+
fail(`'${field}' is not a string`);
|
|
662
|
+
const violation = lockfilePathViolation(value);
|
|
663
|
+
if (violation)
|
|
664
|
+
fail(`'${field}' ${violation}`);
|
|
665
|
+
};
|
|
666
|
+
segment('folder', parsed.folder);
|
|
667
|
+
segment('stagingId', parsed.stagingId);
|
|
668
|
+
if (parsed.oldNamePath !== undefined)
|
|
669
|
+
segment('oldNamePath', parsed.oldNamePath);
|
|
670
|
+
if (typeof parsed.hadDest !== 'boolean')
|
|
671
|
+
return fail("'hadDest' is not a boolean");
|
|
672
|
+
if (typeof parsed.defsDir !== 'string' || parsed.defsDir === '') {
|
|
673
|
+
return fail("'defsDir' is not a non-empty string");
|
|
674
|
+
}
|
|
675
|
+
if (parsed.ref !== undefined && typeof parsed.ref !== 'string')
|
|
676
|
+
return fail("'ref' is not a string");
|
|
677
|
+
if (parsed.startedAt !== undefined && typeof parsed.startedAt !== 'number') {
|
|
678
|
+
return fail("'startedAt' is not a number");
|
|
679
|
+
}
|
|
680
|
+
return parsed;
|
|
681
|
+
}
|
|
682
|
+
/**
|
|
683
|
+
* Read `.owenloop/add.journal`. Absent ⇒ `null` (the happy path — no
|
|
684
|
+
* interrupted install to recover). Present-but-unparseable ⇒ a hard error;
|
|
685
|
+
* present-but-schema-invalid ⇒ a hard error via {@link validateAddJournal}.
|
|
686
|
+
* Never silently ignores a malformed journal (that would let a crafted file
|
|
687
|
+
* quietly disable recovery) and never trusts it for filesystem paths.
|
|
688
|
+
*/
|
|
689
|
+
export function readAddJournal(path) {
|
|
690
|
+
if (!existsSync(path))
|
|
691
|
+
return null;
|
|
692
|
+
const raw = readFileSync(path, 'utf8');
|
|
693
|
+
let parsed;
|
|
694
|
+
try {
|
|
695
|
+
parsed = JSON.parse(raw);
|
|
696
|
+
}
|
|
697
|
+
catch (e) {
|
|
698
|
+
throw new Error(`corrupt crash-recovery journal at ${path}: ${e.message} — ` +
|
|
699
|
+
`inspect and remove it manually, then re-run add`);
|
|
700
|
+
}
|
|
701
|
+
return validateAddJournal(parsed, path);
|
|
702
|
+
}
|
|
703
|
+
/** Write the journal atomically (tmp+rename), same discipline as the lockfile. */
|
|
704
|
+
export function writeAddJournal(path, journal, opts = {}) {
|
|
705
|
+
writeJsonAtomic(path, journal, opts);
|
|
706
|
+
}
|
|
707
|
+
/** Remove the journal (force: absence is not an error — clean-completion / idempotent). */
|
|
708
|
+
export function removeAddJournal(path) {
|
|
709
|
+
rmSync(path, { force: true });
|
|
710
|
+
}
|
|
711
|
+
/** Build a fail-closed recovery-refusal error naming the journal + manual remedy. */
|
|
712
|
+
function recoveryRefusal(journalPath, detail) {
|
|
713
|
+
return new Error(`refusing crash-recovery: ${detail} — inspect ${journalPath} and the defs dir, ` +
|
|
714
|
+
`resolve the state by hand, then re-run add`);
|
|
715
|
+
}
|
|
716
|
+
/**
|
|
717
|
+
* `lstat`-probe a recovery path: `'dir'` if it is a real directory, `'absent'`
|
|
718
|
+
* if it does not exist. Fail-closed on anything else — a symlink (A2 rule: a
|
|
719
|
+
* symlinked segment must never be renamed/rm'd, since finalize/rollback would
|
|
720
|
+
* act through it) or a non-directory file is refused. `lstat`, never `stat`, so
|
|
721
|
+
* a symlink is seen as a symlink, not followed to its target.
|
|
722
|
+
*
|
|
723
|
+
* The PARENT is checked too, not just the leaf: `lstat` on the leaf sees a
|
|
724
|
+
* symlinked leaf, but a symlinked *parent* directory would be silently followed
|
|
725
|
+
* by the `rename`/`rm` that acts on the leaf, redirecting the whole mutation
|
|
726
|
+
* outside `defsDir` (a hostile checkout planting `.owenloop-staging` as a
|
|
727
|
+
* symlink is exactly this). Refuse a symlinked immediate parent before trusting
|
|
728
|
+
* the leaf probe. (Absent parent ⇒ the leaf is absent too; nothing to refuse.)
|
|
729
|
+
*/
|
|
730
|
+
function probeRecoveryDir(p, journalPath, label) {
|
|
731
|
+
const parent = dirname(p);
|
|
732
|
+
const parentSt = lstatSync(parent, { throwIfNoEntry: false });
|
|
733
|
+
if (parentSt?.isSymbolicLink()) {
|
|
734
|
+
throw recoveryRefusal(journalPath, `${label} parent '${parent}' is a symlink`);
|
|
735
|
+
}
|
|
736
|
+
let st;
|
|
737
|
+
try {
|
|
738
|
+
st = lstatSync(p);
|
|
739
|
+
}
|
|
740
|
+
catch (e) {
|
|
741
|
+
if (e.code === 'ENOENT')
|
|
742
|
+
return 'absent';
|
|
743
|
+
throw e;
|
|
744
|
+
}
|
|
745
|
+
if (st.isSymbolicLink())
|
|
746
|
+
throw recoveryRefusal(journalPath, `${label} at '${p}' is a symlink`);
|
|
747
|
+
if (!st.isDirectory())
|
|
748
|
+
throw recoveryRefusal(journalPath, `${label} at '${p}' is not a directory`);
|
|
749
|
+
return 'dir';
|
|
750
|
+
}
|
|
751
|
+
/** Re-assert resolved-path containment at a mutation target (belt-and-braces). */
|
|
752
|
+
function assertUnderDefs(p, defsDir, journalPath) {
|
|
753
|
+
if (!resolve(p).startsWith(resolve(defsDir) + sep)) {
|
|
754
|
+
throw recoveryRefusal(journalPath, `path '${p}' escapes the defs directory`);
|
|
755
|
+
}
|
|
756
|
+
}
|
|
757
|
+
/**
|
|
758
|
+
* Bring an interrupted install back to a consistent (defs ⇔ ledger) state, then
|
|
759
|
+
* remove the journal. Called by `dispatchAdd` under the A3 install lock,
|
|
760
|
+
* BEFORE the stale-staging cleanup (the backups a rollback needs live under the
|
|
761
|
+
* staging root). No journal ⇒ returns immediately (happy path unchanged).
|
|
762
|
+
*
|
|
763
|
+
* Roll-forward vs roll-back rule: the durable ledger write is the commit point.
|
|
764
|
+
* At or past it, roll FORWARD (finish the discard); before it, roll BACK
|
|
765
|
+
* (restore the previous state). Concretely:
|
|
766
|
+
*
|
|
767
|
+
* 1. `finalizing` ⇒ roll forward: the ledger is durably new; only finalize's
|
|
768
|
+
* discards may be missing. Clear the retained backup + parked old-name and
|
|
769
|
+
* the staging root. Trivially idempotent.
|
|
770
|
+
* 2. `applying` + the ledger already records this source at `journal.sha`/
|
|
771
|
+
* `journal.folder` ⇒ the commit MAY have landed, but the ledger match alone
|
|
772
|
+
* does not prove it — branch on disk: dest present ⇒ the swap completed ⇒
|
|
773
|
+
* roll forward; dest ABSENT ⇒ a same-sha re-add crashed inside commitInstall's
|
|
774
|
+
* dest→backup / staging→dest window and backupDir holds the only copy ⇒ roll
|
|
775
|
+
* back (restore it) rather than discarding it (which would be silent data
|
|
776
|
+
* loss against a ledger that still records the install).
|
|
777
|
+
* 3. `applying`, no ledger match (or ledger match with dest absent) ⇒ roll back
|
|
778
|
+
* through the guarded, idempotent decision table below (mirroring
|
|
779
|
+
* `rollbackInstallCommit`'s order) — EXCEPT the case-(c) fresh-install
|
|
780
|
+
* discard, which acts on the journal alone (staging + backup both absent) and
|
|
781
|
+
* so requires LEDGER corroboration of an interrupted old-name migration
|
|
782
|
+
* (`installed.path === journal.oldNamePath`) before it will delete an
|
|
783
|
+
* existing dest; uncorroborated ⇒ refuse fail-closed, mutate nothing, leave
|
|
784
|
+
* the journal and dest in place (the journal is repo-committable, so a forged
|
|
785
|
+
* one must never drive a deletion).
|
|
786
|
+
*
|
|
787
|
+
* Crash-safety of recovery itself: the journal is removed LAST, after all
|
|
788
|
+
* restore/discard renames, and every step is a single atomic rename guarded by
|
|
789
|
+
* existence probes — so a crash mid-recovery leaves the journal intact and a
|
|
790
|
+
* strict subset of the work done; the next attempt re-derives state from disk
|
|
791
|
+
* and continues (the dest-absent arm of case (b), the touch-nothing arm of
|
|
792
|
+
* case (c), and the case-(c) uncorroborated refusal ARE the mid-rollback resume
|
|
793
|
+
* / fail-closed states). Running it twice is a no-op the second time.
|
|
794
|
+
*
|
|
795
|
+
* Any refusal (invalid journal, defsDir mismatch, symlink where a directory is
|
|
796
|
+
* expected, contradictory disk state) throws WITHOUT mutating anything and
|
|
797
|
+
* leaves the journal in place; `dispatchAdd` sets `preserveStagingRoot` so its
|
|
798
|
+
* `finally` cannot then destroy the backups a later attempt needs.
|
|
799
|
+
*/
|
|
800
|
+
export function recoverInterruptedInstall(args) {
|
|
801
|
+
const { defsDir, journalPath, lockfilePath } = args;
|
|
802
|
+
const journal = readAddJournal(journalPath);
|
|
803
|
+
if (journal === null)
|
|
804
|
+
return 'no-journal'; // no interrupted install — happy path, unchanged.
|
|
805
|
+
// An interrupted install in a DIFFERENT defs tree: recovering "here" would act
|
|
806
|
+
// on paths this invocation was never pointed at, and trusting the recorded
|
|
807
|
+
// absolute path would let a crafted journal point mutations anywhere. Fail
|
|
808
|
+
// closed — the operator must re-run with the same --defs/OWENLOOP_DEFS.
|
|
809
|
+
if (resolve(journal.defsDir) !== resolve(defsDir)) {
|
|
810
|
+
throw recoveryRefusal(journalPath, `journal records defs dir '${journal.defsDir}', but this add resolved '${resolve(defsDir)}' ` +
|
|
811
|
+
`(re-run add with the same --defs/OWENLOOP_DEFS)`);
|
|
812
|
+
}
|
|
813
|
+
// Every mutation path is derived HERE from the current defsDir + the validated
|
|
814
|
+
// single segments — never from the recorded absolute defsDir. These are
|
|
815
|
+
// exactly the derivations commitInstall/parkOldNameDir use.
|
|
816
|
+
const stagingRoot = join(defsDir, STAGING_DIRNAME);
|
|
817
|
+
const stagingDir = join(stagingRoot, journal.stagingId);
|
|
818
|
+
const backupDir = `${stagingDir}-old`;
|
|
819
|
+
const undoDir = `${stagingDir}-undo`;
|
|
820
|
+
const parkedOldName = `${undoDir}-oldname`;
|
|
821
|
+
const dest = join(defsDir, journal.folder);
|
|
822
|
+
const oldNameOriginal = journal.oldNamePath !== undefined ? join(defsDir, journal.oldNamePath) : undefined;
|
|
823
|
+
// Symlink-guard the staging ROOT itself before deriving any mutation from it.
|
|
824
|
+
// `dispatchAdd`'s `mkdirRefusingSymlink` guards `.owenloop` and the default
|
|
825
|
+
// defsDir, but NOT `<defsDir>/.owenloop-staging` — and stagingDir/backupDir/
|
|
826
|
+
// undoDir/parkedOldName all hang off it, so a hostile checkout that ships
|
|
827
|
+
// `.owenloop-staging` as a symlink would make every rename/rm below act
|
|
828
|
+
// through it, moving/deleting dirs OUTSIDE defsDir. `lstat` (never `stat`) so
|
|
829
|
+
// the link is seen as a link; a non-dir squatting there is refused too; absent
|
|
830
|
+
// is fine (a fresh recovery mkdirs it). This runs BEFORE any fs mutation, and
|
|
831
|
+
// recovery now precedes dispatchAdd's `rmSync(stagingRoot)`, so nothing else
|
|
832
|
+
// clears it first.
|
|
833
|
+
const stagingRootSt = lstatSync(stagingRoot, { throwIfNoEntry: false });
|
|
834
|
+
if (stagingRootSt?.isSymbolicLink()) {
|
|
835
|
+
throw recoveryRefusal(journalPath, `staging root '${stagingRoot}' is a symlink`);
|
|
836
|
+
}
|
|
837
|
+
if (stagingRootSt && !stagingRootSt.isDirectory()) {
|
|
838
|
+
throw recoveryRefusal(journalPath, `staging root '${stagingRoot}' is not a directory`);
|
|
839
|
+
}
|
|
840
|
+
// Belt-and-braces containment: re-assert that EVERY rename/rm source and target
|
|
841
|
+
// resolves under defsDir — not just dest/oldNameOriginal, but every staging-
|
|
842
|
+
// root-derived path too (a crafted journal + a symlinked staging root must not
|
|
843
|
+
// drive a mutation outside the tree). Single-segment folder/oldNamePath/
|
|
844
|
+
// stagingId already make lexical traversal unrepresentable; this is the extra
|
|
845
|
+
// guard the review asked for on the staging-derived paths.
|
|
846
|
+
for (const p of [stagingRoot, stagingDir, backupDir, undoDir, parkedOldName, dest]) {
|
|
847
|
+
assertUnderDefs(p, defsDir, journalPath);
|
|
848
|
+
}
|
|
849
|
+
if (oldNameOriginal !== undefined)
|
|
850
|
+
assertUnderDefs(oldNameOriginal, defsDir, journalPath);
|
|
851
|
+
// Roll forward: the ledger is durably new; discard the retained backup + parked
|
|
852
|
+
// old-name dir and clear the staging root, then drop the journal. Symlink-
|
|
853
|
+
// guarded before each rm; both dirs live under the staging root, so the final
|
|
854
|
+
// clear is the real cleanup — the explicit rms honor "refuse a symlink" first.
|
|
855
|
+
const rollForward = () => {
|
|
856
|
+
if (probeRecoveryDir(backupDir, journalPath, 'backup dir') === 'dir') {
|
|
857
|
+
rmSync(backupDir, { recursive: true, force: true });
|
|
858
|
+
}
|
|
859
|
+
if (probeRecoveryDir(parkedOldName, journalPath, 'parked old-name dir') === 'dir') {
|
|
860
|
+
rmSync(parkedOldName, { recursive: true, force: true });
|
|
861
|
+
}
|
|
862
|
+
rmSync(stagingRoot, { recursive: true, force: true });
|
|
863
|
+
removeAddJournal(journalPath);
|
|
864
|
+
};
|
|
865
|
+
if (journal.phase === 'finalizing') {
|
|
866
|
+
rollForward();
|
|
867
|
+
return 'rolled-forward';
|
|
868
|
+
}
|
|
869
|
+
// phase === 'applying': the ledger write may or may not have landed. Read it
|
|
870
|
+
// (fail-closed validation applies — a corrupt ledger aborts the add exactly as
|
|
871
|
+
// it does today) and check whether it already records this exact install.
|
|
872
|
+
const lf = readLockfile(lockfilePath);
|
|
873
|
+
const installed = lf.installed[journal.source];
|
|
874
|
+
if (installed && installed.sha === journal.sha && installed.path === journal.folder) {
|
|
875
|
+
// The ledger records this exact source@sha — but a ledger match ALONE does
|
|
876
|
+
// NOT prove the commit swap landed. Branch on ACTUAL disk state:
|
|
877
|
+
// - dest PRESENT ⇒ the swap completed (a crash in the writeLockfile→phase-
|
|
878
|
+
// rewrite window, or a same-sha re-add already past the swap): dest holds
|
|
879
|
+
// that sha's content, so (defs ⇔ ledger) is consistent ⇒ roll forward
|
|
880
|
+
// (discard the now-stale backup).
|
|
881
|
+
// - dest ABSENT ⇒ we are inside commitInstall's 4a→4b window of a SAME-sha
|
|
882
|
+
// re-add (dest was renamed to backupDir, and the staging→dest swap never
|
|
883
|
+
// ran). backupDir now holds the ONLY copy of the content. Rolling forward
|
|
884
|
+
// would `rmSync` it — silent data loss, leaving the ledger claiming an
|
|
885
|
+
// install that is gone from disk. Fall THROUGH to the roll-back table,
|
|
886
|
+
// which restores backupDir → dest; the ledger already records this sha, so
|
|
887
|
+
// the restored state is consistent. The two cases are distinguishable by
|
|
888
|
+
// disk, so branch on it rather than trusting the ledger match alone.
|
|
889
|
+
if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
|
|
890
|
+
rollForward();
|
|
891
|
+
return 'rolled-forward';
|
|
892
|
+
}
|
|
893
|
+
}
|
|
894
|
+
// ROLL BACK — restore the pre-commit directory state. Guarded idempotent
|
|
895
|
+
// renames mirroring rollbackInstallCommit's order; a symlinked source is
|
|
896
|
+
// refused fail-closed at each probe.
|
|
897
|
+
mkdirSync(stagingRoot, { recursive: true }); // ensure undo/backup renames have a home
|
|
898
|
+
const stagingState = probeRecoveryDir(stagingDir, journalPath, 'staging dir');
|
|
899
|
+
const backupState = probeRecoveryDir(backupDir, journalPath, 'backup dir');
|
|
900
|
+
if (stagingState === 'dir') {
|
|
901
|
+
// (a) Swap 4b (staging → dest) never happened.
|
|
902
|
+
if (backupState === 'dir') {
|
|
903
|
+
// Crash between 4a (dest → backup) and 4b: dest is necessarily absent.
|
|
904
|
+
// Restore the backup. Fail closed if dest unexpectedly exists too.
|
|
905
|
+
if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
|
|
906
|
+
throw recoveryRefusal(journalPath, `both the backup dir and destination '${dest}' exist`);
|
|
907
|
+
}
|
|
908
|
+
renameSync(backupDir, dest);
|
|
909
|
+
}
|
|
910
|
+
// else backup absent: dest still holds the original (upgrade, pre-backup) or
|
|
911
|
+
// is absent (fresh install, pre-swap) — already consistent, nothing to move.
|
|
912
|
+
}
|
|
913
|
+
else if (backupState === 'dir') {
|
|
914
|
+
// (b) Staging gone, backup present — an upgrade crashed AFTER the swap.
|
|
915
|
+
if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
|
|
916
|
+
// Park the new content aside, then restore the backup over dest.
|
|
917
|
+
if (probeRecoveryDir(undoDir, journalPath, 'undo dir') === 'dir') {
|
|
918
|
+
throw recoveryRefusal(journalPath, `undo dir '${undoDir}' already exists`);
|
|
919
|
+
}
|
|
920
|
+
renameSync(dest, undoDir);
|
|
921
|
+
renameSync(backupDir, dest);
|
|
922
|
+
}
|
|
923
|
+
else {
|
|
924
|
+
// dest absent: a prior rollback/recovery died between its two renames (the
|
|
925
|
+
// new content is already parked under undoDir) — just restore the backup.
|
|
926
|
+
renameSync(backupDir, dest);
|
|
927
|
+
}
|
|
928
|
+
}
|
|
929
|
+
else {
|
|
930
|
+
// (c) Staging gone, backup gone.
|
|
931
|
+
if (!journal.hadDest) {
|
|
932
|
+
// Fresh install: the swap may have put new content at dest. Discarding it
|
|
933
|
+
// (rename → undoDir, then rm with the staging root at step (e)) is the ONLY
|
|
934
|
+
// destructive arm that acts on the word of the journal alone — staging and
|
|
935
|
+
// backup are both absent by definition of case (c), so the journal is the
|
|
936
|
+
// only thing asserting this dir is a crash orphan. But the journal lives in
|
|
937
|
+
// repository-controlled content (`.owenloop/add.journal` is committable), so
|
|
938
|
+
// a hostile checkout can forge a schema-VALID `applying`/`hadDest:false`
|
|
939
|
+
// journal naming an existing UNRELATED workflow dir and drive its deletion.
|
|
940
|
+
// Fail closed: only delete when the LEDGER corroborates that this dest is a
|
|
941
|
+
// fresh hashed dir left by an interrupted OLD-NAME MIGRATION — i.e. the
|
|
942
|
+
// ledger still records `journal.source` at the migration's old-name path
|
|
943
|
+
// (`installed.path === journal.oldNamePath`). That is exactly the state of
|
|
944
|
+
// the corroborated old-name-migration crash; the parked old-name dir is NOT
|
|
945
|
+
// required as evidence (a crash in the swap→park window legitimately has no
|
|
946
|
+
// parked dir yet). Anything else — no ledger entry, or an entry at some
|
|
947
|
+
// other path (including `journal.folder` itself, which contradicts
|
|
948
|
+
// `hadDest:false`) — is uncorroborated: refuse, mutate nothing, leave the
|
|
949
|
+
// journal AND dest in place as evidence.
|
|
950
|
+
//
|
|
951
|
+
// Deliberate, documented regression: the genuine fresh-install crash between
|
|
952
|
+
// the swap and the ledger write (dest present, no ledger, no staging, no
|
|
953
|
+
// backup) is on-disk INDISTINGUISHABLE from the forgery — every
|
|
954
|
+
// distinguishing artifact is itself repo-committable and therefore forgeable
|
|
955
|
+
// — so it now fails closed here instead of auto-discarding. The error names
|
|
956
|
+
// the manual remedy. Raising the bar from "journal alone" to "journal +
|
|
957
|
+
// corroborating ledger" is the scope; moving/authenticating recovery state
|
|
958
|
+
// OUTSIDE repository-controlled content is the tracked follow-up (an attacker
|
|
959
|
+
// who forges BOTH the journal and a matching ledger old-name entry — or a
|
|
960
|
+
// backup dir, reaching case (b) — can still drive destructive recovery).
|
|
961
|
+
if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
|
|
962
|
+
const migrationCorroborated = journal.oldNamePath !== undefined &&
|
|
963
|
+
installed !== undefined &&
|
|
964
|
+
installed.path === journal.oldNamePath;
|
|
965
|
+
if (!migrationCorroborated) {
|
|
966
|
+
throw recoveryRefusal(journalPath, `journal claims an interrupted fresh install of '${journal.folder}', but nothing ` +
|
|
967
|
+
`corroborates it (no ledger entry for this source at the journal's old-name path, ` +
|
|
968
|
+
`no staging dir, no backup) while '${dest}' exists — refusing to discard that ` +
|
|
969
|
+
`directory. If you did not run an interrupted add in this checkout, remove the ` +
|
|
970
|
+
`journal; if a fresh install really was interrupted, remove '${dest}' as well`);
|
|
971
|
+
}
|
|
972
|
+
if (probeRecoveryDir(undoDir, journalPath, 'undo dir') === 'dir') {
|
|
973
|
+
throw recoveryRefusal(journalPath, `undo dir '${undoDir}' already exists`);
|
|
974
|
+
}
|
|
975
|
+
renameSync(dest, undoDir);
|
|
976
|
+
}
|
|
977
|
+
}
|
|
978
|
+
// hadDest === true: the backup was already restored (a completed in-process
|
|
979
|
+
// rollback whose journal-remove failed, or a prior recovery attempt) — dirs
|
|
980
|
+
// are consistent; touch nothing.
|
|
981
|
+
}
|
|
982
|
+
// (d) Restore a parked old-name dir to where the (unchanged) ledger expects it.
|
|
983
|
+
if (oldNameOriginal !== undefined) {
|
|
984
|
+
if (probeRecoveryDir(parkedOldName, journalPath, 'parked old-name dir') === 'dir') {
|
|
985
|
+
if (probeRecoveryDir(oldNameOriginal, journalPath, 'old-name original') === 'dir') {
|
|
986
|
+
// Both present is contradictory — unreachable under the single-writer
|
|
987
|
+
// lock, so don't guess which to keep.
|
|
988
|
+
throw recoveryRefusal(journalPath, `both the parked old-name dir and its original '${oldNameOriginal}' exist`);
|
|
989
|
+
}
|
|
990
|
+
renameSync(parkedOldName, oldNameOriginal);
|
|
991
|
+
}
|
|
992
|
+
// parked absent ⇒ already restored (idempotent re-run) — skip.
|
|
993
|
+
}
|
|
994
|
+
// (e) The undo/backup leftovers are debris now; clear the staging root and
|
|
995
|
+
// remove the journal LAST so a crash before this leaves everything replayable.
|
|
996
|
+
rmSync(stagingRoot, { recursive: true, force: true });
|
|
997
|
+
removeAddJournal(journalPath);
|
|
998
|
+
return 'rolled-back';
|
|
999
|
+
}
|