@gusto/baerly-storage 0.5.0 → 0.7.0
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/README.md +47 -124
- package/dist/API.md +161 -511
- package/dist/CHANGELOG.md +1148 -307
- package/dist/RECIPES.md +398 -80
- package/dist/THIRD-PARTY-LICENSES.txt +5 -26
- package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
- package/dist/app-config.d.ts +31 -1
- package/dist/app-config.js +1 -2
- package/dist/app-config.js.map +1 -1
- package/dist/auth.d.ts +33 -28
- package/dist/auth.js +549 -985
- package/dist/auth.js.map +1 -1
- package/dist/baerly.js +130 -138
- package/dist/baerly.js.map +1 -1
- package/dist/baerly.spec.json +97 -22
- package/dist/capacity-warning-header-BlVopyiI.js +16 -0
- package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
- package/dist/{client-Fe8CwB73.d.ts → client-CHQTXpef.d.ts} +121 -36
- package/dist/client-react.d.ts +67 -20
- package/dist/client-react.js +240 -54
- package/dist/client-react.js.map +1 -1
- package/dist/client.d.ts +5 -4
- package/dist/client.js +51 -16
- package/dist/client.js.map +1 -1
- package/dist/{cloudflare-DzKBrUlg.js → cloudflare-CKHYXccw.js} +504 -124
- package/dist/cloudflare-CKHYXccw.js.map +1 -0
- package/dist/cloudflare.d.ts +106 -71
- package/dist/cloudflare.js +334 -271
- package/dist/cloudflare.js.map +1 -1
- package/dist/code-resolution-CL_7L0wS.js +22 -0
- package/dist/code-resolution-CL_7L0wS.js.map +1 -0
- package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
- package/dist/config-DEzInG6M.js +4035 -0
- package/dist/config-DEzInG6M.js.map +1 -0
- package/dist/constants-D3GSH3tc.js +469 -0
- package/dist/constants-D3GSH3tc.js.map +1 -0
- package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
- package/dist/context-rlpSnHFA.js.map +1 -0
- package/dist/cost-B52llVDx.js +330 -0
- package/dist/cost-B52llVDx.js.map +1 -0
- package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
- package/dist/current-json-CC6lE4Aj.js.map +1 -0
- package/dist/db-plFUNTSF.d.ts +130 -0
- package/dist/db-read-seams-BSs0m1z1.js +3261 -0
- package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
- package/dist/{deploy-DonTr-CV.js → deploy-Obj4nE-Z.js} +12 -16
- package/dist/deploy-Obj4nE-Z.js.map +1 -0
- package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
- package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
- package/dist/dev-landing-CD-si4dW.js +50 -0
- package/dist/dev-landing-CD-si4dW.js.map +1 -0
- package/dist/dev-vite.d.ts +38 -39
- package/dist/dev-vite.js +67 -36
- package/dist/dev-vite.js.map +1 -1
- package/dist/dev.d.ts +3 -2
- package/dist/dev.js +2 -1
- package/dist/doctor-BA0i-YAN.js +270 -0
- package/dist/doctor-BA0i-YAN.js.map +1 -0
- package/dist/dump-D1vX8ozg.js +133 -0
- package/dist/dump-D1vX8ozg.js.map +1 -0
- package/dist/errors-7Rk1HGCE.js +160 -0
- package/dist/errors-7Rk1HGCE.js.map +1 -0
- package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
- package/dist/export-BVL2EvYE.js.map +1 -0
- package/dist/fsck-BWkPgov4.js +145 -0
- package/dist/fsck-BWkPgov4.js.map +1 -0
- package/dist/gcs-admin-Dso1HWQj.d.ts +127 -0
- package/dist/gcs.d.ts +30 -0
- package/dist/gcs.js +1 -0
- package/dist/goog4-signer-CeLIABoE.js +331 -0
- package/dist/goog4-signer-CeLIABoE.js.map +1 -0
- package/dist/{http-DGd5tbNs.js → http-Z5rZyYMX.js} +898 -271
- package/dist/http-Z5rZyYMX.js.map +1 -0
- package/dist/http-transport-DNUM8kU-.js +1299 -0
- package/dist/http-transport-DNUM8kU-.js.map +1 -0
- package/dist/http.d.ts +366 -294
- package/dist/http.js +2 -2
- package/dist/index-JJrIu1pO.d.ts +135 -0
- package/dist/index-LEgHN0qJ.d.ts +50 -0
- package/dist/{index-CuA9Mi3K.d.ts → index-RiEYj8t0.d.ts} +291 -78
- package/dist/index.d.ts +27 -6
- package/dist/index.js +3 -5
- package/dist/inspect-BTsVYZKd.js +196 -0
- package/dist/inspect-BTsVYZKd.js.map +1 -0
- package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
- package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
- package/dist/ledger-Dj_bGgo0.js +192 -0
- package/dist/ledger-Dj_bGgo0.js.map +1 -0
- package/dist/legacy-names-DgZBtgOh.js +47 -0
- package/dist/legacy-names-DgZBtgOh.js.map +1 -0
- package/dist/log-C9W15Dfo.d.ts +94 -0
- package/dist/log-tail-DWJbneBF.js +142 -0
- package/dist/log-tail-DWJbneBF.js.map +1 -0
- package/dist/log-walk-C-vA-WGJ.js +111 -0
- package/dist/log-walk-C-vA-WGJ.js.map +1 -0
- package/dist/maintenance-Dd-Yakqj.js +1709 -0
- package/dist/maintenance-Dd-Yakqj.js.map +1 -0
- package/dist/maintenance-DevB6z4e.js +2237 -0
- package/dist/maintenance-DevB6z4e.js.map +1 -0
- package/dist/maintenance.d.ts +100 -3
- package/dist/maintenance.js +1 -3
- package/dist/node.d.ts +130 -142
- package/dist/node.js +4 -3
- package/dist/{observability-BmflLCdF.js → observability-C-ISCCLE.js} +1275 -332
- package/dist/observability-C-ISCCLE.js.map +1 -0
- package/dist/observability.d.ts +27 -3
- package/dist/observability.js +3 -3
- package/dist/path-segment-DBXG26PW.js +363 -0
- package/dist/path-segment-DBXG26PW.js.map +1 -0
- package/dist/{plan-a7PJHBCy.js → plan-BvQbaNMe.js} +19 -11
- package/dist/plan-BvQbaNMe.js.map +1 -0
- package/dist/request-CRWiTrza.js +272 -0
- package/dist/request-CRWiTrza.js.map +1 -0
- package/dist/restore-U6Im8V1V.js +1467 -0
- package/dist/restore-U6Im8V1V.js.map +1 -0
- package/dist/retry-OBtLB2GC.js +126 -0
- package/dist/retry-OBtLB2GC.js.map +1 -0
- package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
- package/dist/{runtime-spec-Dsw2-n8S.js → runtime-spec-B5mg3pHF.js} +189 -28
- package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
- package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DBC_wiCL.d.ts} +18 -10
- package/dist/s3.d.ts +20 -7
- package/dist/s3.js +4 -5
- package/dist/s3.js.map +1 -1
- package/dist/sha256-4FfGQNPw.js +22 -0
- package/dist/sha256-4FfGQNPw.js.map +1 -0
- package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
- package/dist/shared-secret-Vkur-8r0.js.map +1 -0
- package/dist/sigv4-sign-5IUflUD_.js +507 -0
- package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
- package/dist/snapshot-CknzkDM0.js +148 -0
- package/dist/snapshot-CknzkDM0.js.map +1 -0
- package/dist/{src-BL_JoPTn.js → src-Actga-bO.js} +1004 -378
- package/dist/src-Actga-bO.js.map +1 -0
- package/dist/src-D0MQfvOp.js +812 -0
- package/dist/src-D0MQfvOp.js.map +1 -0
- package/dist/src-Dr9uo3dc.js +501 -0
- package/dist/src-Dr9uo3dc.js.map +1 -0
- package/dist/{subcommand-DoDA-K7d.js → subcommand-BLoF66dG.js} +89 -16
- package/dist/subcommand-BLoF66dG.js.map +1 -0
- package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
- package/dist/time-DRxTP9iv.js.map +1 -0
- package/dist/types-suVbsEWS.d.ts +116 -0
- package/dist/{usage-DBV1eQHC.js → usage-CPzVhrQr.js} +40 -45
- package/dist/usage-CPzVhrQr.js.map +1 -0
- package/dist/uuid-BuT_c404.js +333 -0
- package/dist/uuid-BuT_c404.js.map +1 -0
- package/dist/verifier-Bmlmndzo.d.ts +95 -0
- package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
- package/dist/wire-DndvKU-K.js.map +1 -0
- package/package.json +96 -69
- package/dist/aws4fetch.esm-p7eEzLCs.js +0 -1702
- package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
- package/dist/bytes-BXdamO3L.js +0 -11
- package/dist/bytes-BXdamO3L.js.map +0 -1
- package/dist/cloudflare-DzKBrUlg.js.map +0 -1
- package/dist/config-1tv0-Yzm.js +0 -2693
- package/dist/config-1tv0-Yzm.js.map +0 -1
- package/dist/constants-CfeMWQWk.js +0 -222
- package/dist/constants-CfeMWQWk.js.map +0 -1
- package/dist/context-DRZ3tZ5l.js.map +0 -1
- package/dist/cost-DSMIVqzL.js +0 -203
- package/dist/cost-DSMIVqzL.js.map +0 -1
- package/dist/current-json-C6nhPOm1.js.map +0 -1
- package/dist/db-DsPkOVEH.d.ts +0 -254
- package/dist/deploy-DonTr-CV.js.map +0 -1
- package/dist/doctor-DSIyCDg_.js +0 -346
- package/dist/doctor-DSIyCDg_.js.map +0 -1
- package/dist/dump-Bh5k26VQ.js +0 -94
- package/dist/dump-Bh5k26VQ.js.map +0 -1
- package/dist/errors-Dfa3p78c.js +0 -78
- package/dist/errors-Dfa3p78c.js.map +0 -1
- package/dist/export-DtF5tDIM.js +0 -401
- package/dist/export-DtF5tDIM.js.map +0 -1
- package/dist/fsck-D_djMO5D.js +0 -279
- package/dist/fsck-D_djMO5D.js.map +0 -1
- package/dist/http-DGd5tbNs.js.map +0 -1
- package/dist/index-0rZcMBwy.d.ts +0 -115
- package/dist/index-BNRh23K9.d.ts +0 -162
- package/dist/index-BYk9oCNf.d.ts +0 -1112
- package/dist/indexes-Dn9hbGQG.d.ts +0 -22
- package/dist/inspect-6WZ-pC7-.js +0 -133
- package/dist/inspect-6WZ-pC7-.js.map +0 -1
- package/dist/log-tail-D98U1JBo.js +0 -522
- package/dist/log-tail-D98U1JBo.js.map +0 -1
- package/dist/maintenance-B4Dki6Ig.js +0 -2157
- package/dist/maintenance-B4Dki6Ig.js.map +0 -1
- package/dist/maintenance-B_e0T99L.d.ts +0 -537
- package/dist/maintenance-C7coQp4c.js +0 -1418
- package/dist/maintenance-C7coQp4c.js.map +0 -1
- package/dist/normalize-rjnZLwS4.js +0 -133
- package/dist/normalize-rjnZLwS4.js.map +0 -1
- package/dist/observability-BmflLCdF.js.map +0 -1
- package/dist/plan-a7PJHBCy.js.map +0 -1
- package/dist/query-rAtXNQQB.js +0 -1773
- package/dist/query-rAtXNQQB.js.map +0 -1
- package/dist/rebuild-index-BVzQSZlm.js +0 -81
- package/dist/rebuild-index-BVzQSZlm.js.map +0 -1
- package/dist/request-u0M51mhJ.js +0 -72
- package/dist/request-u0M51mhJ.js.map +0 -1
- package/dist/restore-R-4rbciV.js +0 -778
- package/dist/restore-R-4rbciV.js.map +0 -1
- package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
- package/dist/runtime-spec-Dsw2-n8S.js.map +0 -1
- package/dist/shared-secret-DgEicd3x.js.map +0 -1
- package/dist/src-BL_JoPTn.js.map +0 -1
- package/dist/src-CYHFDrKz.js +0 -536
- package/dist/src-CYHFDrKz.js.map +0 -1
- package/dist/src-DYZ4H1aF.js +0 -392
- package/dist/src-DYZ4H1aF.js.map +0 -1
- package/dist/subcommand-DoDA-K7d.js.map +0 -1
- package/dist/time-DUqvFMHq.js.map +0 -1
- package/dist/usage-DBV1eQHC.js.map +0 -1
- package/dist/validate-DtljsCh1.js.map +0 -1
- package/dist/wire-izfGZDvr.js.map +0 -1
|
@@ -0,0 +1,812 @@
|
|
|
1
|
+
import { i as isWriteConflict, t as BaerlyError } from "./errors-7Rk1HGCE.js";
|
|
2
|
+
import { f as mintGeneration, l as createCurrentJson, t as assertNameSegment } from "./path-segment-DBXG26PW.js";
|
|
3
|
+
import { t as assertValidStorageKey } from "./key-C4FPZ9Io.js";
|
|
4
|
+
import { dirname, join, resolve, sep } from "node:path";
|
|
5
|
+
import { createHash } from "node:crypto";
|
|
6
|
+
import { link, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
|
|
7
|
+
import { styleText } from "node:util";
|
|
8
|
+
// packages/dev/src/key-lock.ts
|
|
9
|
+
/**
|
|
10
|
+
* Live locks, keyed by caller-supplied string.
|
|
11
|
+
*
|
|
12
|
+
* Module-level rather than per-owner on purpose. `LocalFsStorage` is
|
|
13
|
+
* constructed freely — `localFsStorage()` mints a fresh instance on every
|
|
14
|
+
* call over the same default root, and the randomized cascade builds N
|
|
15
|
+
* instances over one directory specifically to make them contend — so a
|
|
16
|
+
* lock map hanging off the instance would serialize nothing in exactly the
|
|
17
|
+
* cases that need it. Callers key on the resolved root plus the storage
|
|
18
|
+
* key, which is the real identity of the thing being mutated.
|
|
19
|
+
*/
|
|
20
|
+
const locks = /* @__PURE__ */ new Map();
|
|
21
|
+
/**
|
|
22
|
+
* Run `fn` with exclusive access to `lockKey`, in FIFO order among
|
|
23
|
+
* contenders. Concurrent calls on *different* keys are unaffected.
|
|
24
|
+
*
|
|
25
|
+
* A rejecting `fn` releases the lock like any other completion and the
|
|
26
|
+
* rejection propagates to its own caller only — one failed critical
|
|
27
|
+
* section must not wedge the key or poison the next holder.
|
|
28
|
+
*
|
|
29
|
+
* Scope: one loaded copy of this module, since `locks` is module-level.
|
|
30
|
+
* That is one process in every normal setup. It says nothing about other
|
|
31
|
+
* processes, which need a lock file, a lease, or server-side CAS.
|
|
32
|
+
*
|
|
33
|
+
* `fn` must not itself call `withKeyLock` on the same key — the inner
|
|
34
|
+
* call would wait on the outer call's release and self-deadlock. Nothing
|
|
35
|
+
* in this package does; only one lock is ever held at a time, so there is
|
|
36
|
+
* no lock-ordering cycle either.
|
|
37
|
+
*/
|
|
38
|
+
const withKeyLock = async (lockKey, fn) => {
|
|
39
|
+
const lock = locks.getOrInsertComputed(lockKey, () => ({
|
|
40
|
+
tail: Promise.resolve(),
|
|
41
|
+
waiters: 0
|
|
42
|
+
}));
|
|
43
|
+
lock.waiters += 1;
|
|
44
|
+
const predecessor = lock.tail;
|
|
45
|
+
let release;
|
|
46
|
+
lock.tail = new Promise((resolve) => {
|
|
47
|
+
release = resolve;
|
|
48
|
+
});
|
|
49
|
+
await predecessor;
|
|
50
|
+
try {
|
|
51
|
+
return await fn();
|
|
52
|
+
} finally {
|
|
53
|
+
release();
|
|
54
|
+
lock.waiters -= 1;
|
|
55
|
+
if (lock.waiters === 0 && locks.get(lockKey) === lock) locks.delete(lockKey);
|
|
56
|
+
}
|
|
57
|
+
};
|
|
58
|
+
/** Longest component that still fits {@link CONTINUATION} under `NAME_MAX`. */
|
|
59
|
+
const MAX_PART_BYTES = 254;
|
|
60
|
+
const utf8Encoder$1 = new TextEncoder();
|
|
61
|
+
const utf8Decoder = new TextDecoder("utf-8", {
|
|
62
|
+
fatal: true,
|
|
63
|
+
ignoreBOM: true
|
|
64
|
+
});
|
|
65
|
+
/** Bytes that stay literal: `-` `.` `0-9` `_` `a-z`. `.` is special-cased. */
|
|
66
|
+
const isLiteralByte = (b) => b >= 97 && b <= 122 || b >= 48 && b <= 57 || b === 45 || b === 95 || b === 46;
|
|
67
|
+
const DOT = 46;
|
|
68
|
+
const escapeByte = (b) => `%${b.toString(16).padStart(2, "0")}`;
|
|
69
|
+
/** Tokens of one encoded segment: a literal char or a `%xx` triplet. */
|
|
70
|
+
const tokenize = (segment) => {
|
|
71
|
+
const tokens = [];
|
|
72
|
+
for (const b of utf8Encoder$1.encode(segment)) tokens.push(isLiteralByte(b) ? String.fromCharCode(b) : escapeByte(b));
|
|
73
|
+
return tokens;
|
|
74
|
+
};
|
|
75
|
+
/**
|
|
76
|
+
* Pack tokens into on-disk components. A component never starts with a
|
|
77
|
+
* literal `.`: such a token is written as `%2e` instead.
|
|
78
|
+
*/
|
|
79
|
+
const pack = (tokens, limit) => {
|
|
80
|
+
const parts = [];
|
|
81
|
+
let current = "";
|
|
82
|
+
for (let token of tokens) {
|
|
83
|
+
if (current.length + token.length > limit) {
|
|
84
|
+
parts.push(current);
|
|
85
|
+
current = "";
|
|
86
|
+
}
|
|
87
|
+
if (current === "" && token === ".") token = escapeByte(DOT);
|
|
88
|
+
current += token;
|
|
89
|
+
}
|
|
90
|
+
parts.push(current);
|
|
91
|
+
return parts;
|
|
92
|
+
};
|
|
93
|
+
/** Encode one non-empty `/`-segment into its on-disk component(s). */
|
|
94
|
+
const encodeSegment = (segment) => {
|
|
95
|
+
const tokens = tokenize(segment);
|
|
96
|
+
const single = pack(tokens, Number.POSITIVE_INFINITY);
|
|
97
|
+
if (single[0].length <= 255) return single;
|
|
98
|
+
const parts = pack(tokens, MAX_PART_BYTES);
|
|
99
|
+
return parts.map((p, i) => i < parts.length - 1 ? p + "~" : p);
|
|
100
|
+
};
|
|
101
|
+
/**
|
|
102
|
+
* Encode a key into on-disk path components. The caller has already
|
|
103
|
+
* validated the key's `/`-structure (no empty, `.`, or `..` segment).
|
|
104
|
+
* Rejects a key that is not well-formed UTF-16: `TextEncoder` maps every
|
|
105
|
+
* lone surrogate to U+FFFD, which would make the encoding non-injective.
|
|
106
|
+
*/
|
|
107
|
+
const encodeKey = (key) => {
|
|
108
|
+
if (!key.isWellFormed()) throw new BaerlyError("InvalidConfig", `LocalFsStorage: key is not well-formed UTF-16 (lone surrogate): ${JSON.stringify(key)}`);
|
|
109
|
+
return key.split("/").flatMap(encodeSegment);
|
|
110
|
+
};
|
|
111
|
+
const HEX = /^[0-9a-f]{2}$/;
|
|
112
|
+
/** Decode one component's bytes (continuation marker already stripped). */
|
|
113
|
+
const decodeBytes = (component, out) => {
|
|
114
|
+
for (let i = 0; i < component.length; i++) {
|
|
115
|
+
const c = component.charCodeAt(i);
|
|
116
|
+
if (c === 37) {
|
|
117
|
+
const hex = component.slice(i + 1, i + 3);
|
|
118
|
+
if (!HEX.test(hex)) return false;
|
|
119
|
+
out.push(Number.parseInt(hex, 16));
|
|
120
|
+
i += 2;
|
|
121
|
+
} else if (isLiteralByte(c)) out.push(c);
|
|
122
|
+
else return false;
|
|
123
|
+
}
|
|
124
|
+
return true;
|
|
125
|
+
};
|
|
126
|
+
/**
|
|
127
|
+
* Decode on-disk path components (relative to the root) back to a key.
|
|
128
|
+
* Returns `null` for anything that is not the canonical encoding of some
|
|
129
|
+
* key — a foreign file, a non-canonical escape, a dangling continuation —
|
|
130
|
+
* so the caller can decide how loudly to fail.
|
|
131
|
+
*/
|
|
132
|
+
const decodeComponents = (components) => {
|
|
133
|
+
const segments = [];
|
|
134
|
+
let bytes = [];
|
|
135
|
+
for (const component of components) {
|
|
136
|
+
const continued = component.endsWith("~");
|
|
137
|
+
const body = continued ? component.slice(0, -1) : component;
|
|
138
|
+
if (body === "" || !decodeBytes(body, bytes)) return null;
|
|
139
|
+
if (!continued) {
|
|
140
|
+
let segment;
|
|
141
|
+
try {
|
|
142
|
+
segment = utf8Decoder.decode(new Uint8Array(bytes));
|
|
143
|
+
} catch {
|
|
144
|
+
return null;
|
|
145
|
+
}
|
|
146
|
+
if (segment === "." || segment === "..") return null;
|
|
147
|
+
segments.push(segment);
|
|
148
|
+
bytes = [];
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
if (bytes.length > 0 || segments.length === 0) return null;
|
|
152
|
+
const key = segments.join("/");
|
|
153
|
+
let canonical;
|
|
154
|
+
try {
|
|
155
|
+
canonical = encodeKey(key);
|
|
156
|
+
} catch {
|
|
157
|
+
return null;
|
|
158
|
+
}
|
|
159
|
+
if (canonical.length !== components.length || canonical.some((c, i) => c !== components[i])) return null;
|
|
160
|
+
return key;
|
|
161
|
+
};
|
|
162
|
+
// packages/dev/src/local-fs.ts
|
|
163
|
+
/**
|
|
164
|
+
* Prefix for the in-directory staging temps (see `put`). Dot-prefixed, so
|
|
165
|
+
* it can never collide with an encoded key (see `local-fs-key-codec.ts`)
|
|
166
|
+
* and `walk` skips it with every other adapter-private name.
|
|
167
|
+
*/
|
|
168
|
+
const TEMP_PREFIX = ".baerly-tmp-";
|
|
169
|
+
/**
|
|
170
|
+
* Root marker recording the on-disk key encoding. Dot-prefixed, so it is
|
|
171
|
+
* never a key. A directory without it is scanned once for names written
|
|
172
|
+
* by the pre-encoding layout (see `#ensureFormat`).
|
|
173
|
+
*/
|
|
174
|
+
const FORMAT_MARKER = ".baerly-localfs.json";
|
|
175
|
+
/** Version of the key encoding in `local-fs-key-codec.ts`. */
|
|
176
|
+
const KEY_ENCODING = 1;
|
|
177
|
+
/** Legacy paths named in the refusal message before it truncates. */
|
|
178
|
+
const LEGACY_PATHS_SHOWN = 10;
|
|
179
|
+
/**
|
|
180
|
+
* Staging path for a two-phase (write → publish) `put`. Always a sibling
|
|
181
|
+
* of the destination: `rename(2)`/`link(2)` refuse to cross filesystems
|
|
182
|
+
* (`EXDEV`), and the bucket root is routinely on a different volume from
|
|
183
|
+
* `os.tmpdir()`. The leading `.` of `TEMP_PREFIX` is what makes staging
|
|
184
|
+
* in-bucket safe — `walk` skips dot-prefixed names at every depth, and no
|
|
185
|
+
* encoded key starts with one, so a crash before the publish leaves a file
|
|
186
|
+
* invisible to `list` rather than a bogus key.
|
|
187
|
+
*
|
|
188
|
+
* The trade-off that invisibility buys: a temp stranded by a hard crash
|
|
189
|
+
* now sits inside the bucket, and because every enumerator goes through
|
|
190
|
+
* `list`, nothing — not `runGc`, not `admin fsck` — will ever reclaim it.
|
|
191
|
+
* Staging in `os.tmpdir()` at least let the OS reap it. Repeated crashes
|
|
192
|
+
* therefore grow the data directory, and clearing that is a manual
|
|
193
|
+
* `find . -name '.baerly-tmp-*' -delete`. Non-crash failures are cleaned
|
|
194
|
+
* up by `put`'s `finally`.
|
|
195
|
+
*/
|
|
196
|
+
const tempPathFor = (finalPath) => join(dirname(finalPath), `${TEMP_PREFIX}${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
|
|
197
|
+
const utf8Encoder = new TextEncoder();
|
|
198
|
+
/**
|
|
199
|
+
* Compare two keys by their UTF-8 byte sequences — the order S3 and R2
|
|
200
|
+
* use for `list`. JS's default string sort compares UTF-16 code units,
|
|
201
|
+
* which diverges from UTF-8 byte order for supplementary-plane
|
|
202
|
+
* characters; using this keeps `list` ordering faithful to the real
|
|
203
|
+
* adapters. (All kernel keys are ASCII base-32, where both orders
|
|
204
|
+
* coincide.)
|
|
205
|
+
*/
|
|
206
|
+
const compareKeysUtf8 = (a, b) => {
|
|
207
|
+
const ba = utf8Encoder.encode(a);
|
|
208
|
+
const bb = utf8Encoder.encode(b);
|
|
209
|
+
const n = Math.min(ba.length, bb.length);
|
|
210
|
+
for (let i = 0; i < n; i++) if (ba[i] !== bb[i]) return ba[i] - bb[i];
|
|
211
|
+
return ba.length - bb.length;
|
|
212
|
+
};
|
|
213
|
+
/**
|
|
214
|
+
* `Storage` backed by a directory tree. Keys may contain `/` and map
|
|
215
|
+
* to nested directories on disk so `ls`/`cat` work as expected.
|
|
216
|
+
*
|
|
217
|
+
* Keys are byte-exact, as on S3 and R2: keys that differ only by case or
|
|
218
|
+
* Unicode normalization are distinct objects even on a filesystem that
|
|
219
|
+
* folds both (default macOS APFS). Each segment is escaped into a
|
|
220
|
+
* fold-invariant alphabet on disk — `A` is stored as `%41`, NFC `é` as
|
|
221
|
+
* `%c3%a9` — while kernel-written segments (lowercase ids, base-32 index
|
|
222
|
+
* values, `current.json`) are stored verbatim. See
|
|
223
|
+
* `local-fs-key-codec.ts`.
|
|
224
|
+
*
|
|
225
|
+
* The root carries a `.baerly-localfs.json` marker naming that encoding.
|
|
226
|
+
* A directory written by an older release, before keys were escaped, is
|
|
227
|
+
* adopted as-is when every name in it already reads the same under the
|
|
228
|
+
* encoding; otherwise every operation refuses with `InvalidConfig`.
|
|
229
|
+
* Such a directory is dev data: move it aside or delete it. Collections
|
|
230
|
+
* worth keeping can be dumped with the older release (`baerly admin
|
|
231
|
+
* dump`, rows only) and restored into a fresh directory (`baerly admin
|
|
232
|
+
* restore`). Data a folding filesystem has already merged is not
|
|
233
|
+
* recoverable.
|
|
234
|
+
*
|
|
235
|
+
* ETags are content-addressed: `"<sha-256-hex>"` (the surrounding
|
|
236
|
+
* double-quotes match S3's wire format for non-multipart objects).
|
|
237
|
+
* Identical bodies share an ETag across runs — the property that
|
|
238
|
+
* makes this adapter useful for fixture-based tests.
|
|
239
|
+
*
|
|
240
|
+
* Writes are atomic via `writeFile(temp) + rename(final)`; readers
|
|
241
|
+
* never see a partially-written file. The temp is always a sibling of
|
|
242
|
+
* its destination — `rename(2)`/`link(2)` fail with `EXDEV` across
|
|
243
|
+
* filesystems, and the bucket root is routinely on a different volume
|
|
244
|
+
* from `os.tmpdir()` (see `tempPathFor`).
|
|
245
|
+
*
|
|
246
|
+
* `ifNoneMatch:"*"` uses `link(2)` (atomic exclusive create; `EEXIST` ⇒
|
|
247
|
+
* key exists) so concurrent creates have exactly one winner. temp+`link`
|
|
248
|
+
* over `open(…,"wx")` keeps a partially-written new key invisible to a
|
|
249
|
+
* concurrent reader.
|
|
250
|
+
*
|
|
251
|
+
* `ifMatch` is a read-compare-write, so it is made atomic by serializing
|
|
252
|
+
* every mutation of a key against every other — see `#lockKey`.
|
|
253
|
+
*
|
|
254
|
+
* Scope of that guarantee, precisely: **one loaded copy of this module**.
|
|
255
|
+
* Within it, concurrent CAS on one key admits exactly one winner and the
|
|
256
|
+
* losers get `WriteConflict`, across any number of `LocalFsStorage` instances
|
|
257
|
+
* whose roots resolve — through symlinks — to the same directory. That is
|
|
258
|
+
* one process in every normal setup, but the lock lives in a module-level
|
|
259
|
+
* map, so a process that somehow loads both this source and the bundled
|
|
260
|
+
* copy has two of them.
|
|
261
|
+
*
|
|
262
|
+
* Across processes it guarantees nothing: two `baerly` CLI runs, or two
|
|
263
|
+
* servers, sharing a directory can both win, because nothing in POSIX
|
|
264
|
+
* makes read-compare-write atomic without a lock file or a lease. That is
|
|
265
|
+
* why this adapter is for single-process dev and self-hosting;
|
|
266
|
+
* horizontally-scaled deploys need S3 / R2, whose server-side conditional
|
|
267
|
+
* write is what the no-lease maintenance fold actually relies on.
|
|
268
|
+
*
|
|
269
|
+
* Node-only — imports `node:fs`, `node:path`, `node:crypto`. Lives in
|
|
270
|
+
* `@baerly/dev` because the protocol kernel is pure-modules / no I/O
|
|
271
|
+
* and must remain Worker-bundleable.
|
|
272
|
+
*
|
|
273
|
+
* ⚠️ **Hard termination and temp files.**
|
|
274
|
+
*
|
|
275
|
+
* Writes stage a sibling `.baerly-tmp-*` file before atomic rename/link.
|
|
276
|
+
* Normal failures clean up the temp in `finally`, but hard termination
|
|
277
|
+
* (`SIGKILL`, OOM, power loss) can strand a temp inside the root directory.
|
|
278
|
+
*
|
|
279
|
+
* These files are hidden from `list`, `gc`, `fsck`, and usage reporting
|
|
280
|
+
* by design—the temp filter applies at every depth.
|
|
281
|
+
*
|
|
282
|
+
* **Manual cleanup procedure:**
|
|
283
|
+
* 1. Stop all writers using the root
|
|
284
|
+
* 2. Run: `find <root> -name '.baerly-tmp-*' -delete`
|
|
285
|
+
*
|
|
286
|
+
* Do not clean while writes are in progress—races with in-flight PUTs
|
|
287
|
+
* can delete a file that a concurrent operation is about to rename.
|
|
288
|
+
*/
|
|
289
|
+
var LocalFsStorage = class {
|
|
290
|
+
#root;
|
|
291
|
+
/** Memoized `realpath` of {@link #root} — see {@link #canonicalRoot}. */
|
|
292
|
+
#realRoot;
|
|
293
|
+
/** Set once the root's key encoding is known to be current. */
|
|
294
|
+
#formatChecked = false;
|
|
295
|
+
constructor(opts) {
|
|
296
|
+
this.#root = resolve(opts.root);
|
|
297
|
+
}
|
|
298
|
+
async get(key, opts) {
|
|
299
|
+
opts?.signal?.throwIfAborted();
|
|
300
|
+
const path = this.#pathFor(key);
|
|
301
|
+
await this.#ensureFormat(false);
|
|
302
|
+
let body;
|
|
303
|
+
try {
|
|
304
|
+
body = await readFile(path);
|
|
305
|
+
} catch (error) {
|
|
306
|
+
if (isErrnoException(error) && error.code === "ENOENT") return null;
|
|
307
|
+
throw new BaerlyError("InvalidResponse", `LocalFsStorage.get(${key}): ${error.message}`, { cause: error });
|
|
308
|
+
}
|
|
309
|
+
const etag = etagOf(body);
|
|
310
|
+
return {
|
|
311
|
+
body: toUint8Array(body),
|
|
312
|
+
etag
|
|
313
|
+
};
|
|
314
|
+
}
|
|
315
|
+
async put(key, body, opts) {
|
|
316
|
+
opts?.signal?.throwIfAborted();
|
|
317
|
+
const path = this.#pathFor(key);
|
|
318
|
+
await this.#ensureFormat(true);
|
|
319
|
+
await mkdir(dirname(path), { recursive: true });
|
|
320
|
+
return withKeyLock(await this.#lockKey(path), () => this.#putSerialized(key, path, body, opts));
|
|
321
|
+
}
|
|
322
|
+
async #putSerialized(key, path, body, opts) {
|
|
323
|
+
opts?.signal?.throwIfAborted();
|
|
324
|
+
const newEtag = etagOf(body);
|
|
325
|
+
if (opts?.ifNoneMatch === "*") {
|
|
326
|
+
const tmp = tempPathFor(path);
|
|
327
|
+
try {
|
|
328
|
+
await writeFile(tmp, body);
|
|
329
|
+
await link(tmp, path);
|
|
330
|
+
} catch (error) {
|
|
331
|
+
if (isErrnoException(error) && error.code === "EEXIST") throw new BaerlyError("WriteConflict", `PUT ${key}: precondition failed (ifNoneMatch="*" but key exists)`);
|
|
332
|
+
throw new BaerlyError("InvalidResponse", `LocalFsStorage.put(${key}): ${error.message}`, { cause: error });
|
|
333
|
+
} finally {
|
|
334
|
+
await rm(tmp, { force: true }).catch(() => {});
|
|
335
|
+
}
|
|
336
|
+
return {
|
|
337
|
+
etag: newEtag,
|
|
338
|
+
serverDate: /* @__PURE__ */ new Date()
|
|
339
|
+
};
|
|
340
|
+
}
|
|
341
|
+
if (opts?.ifMatch !== void 0) {
|
|
342
|
+
const existing = await readExisting(path);
|
|
343
|
+
if (existing === null) throw new BaerlyError("WriteConflict", `PUT ${key}: precondition failed (ifMatch=${opts.ifMatch} but key does not exist)`);
|
|
344
|
+
const currentEtag = etagOf(existing);
|
|
345
|
+
if (currentEtag !== opts.ifMatch) throw new BaerlyError("WriteConflict", `PUT ${key}: precondition failed (ifMatch=${opts.ifMatch} but current ETag is ${currentEtag})`);
|
|
346
|
+
}
|
|
347
|
+
const tmp = tempPathFor(path);
|
|
348
|
+
try {
|
|
349
|
+
await writeFile(tmp, body);
|
|
350
|
+
await rename(tmp, path);
|
|
351
|
+
} catch (error) {
|
|
352
|
+
throw new BaerlyError("InvalidResponse", `LocalFsStorage.put(${key}): ${error.message}`, { cause: error });
|
|
353
|
+
} finally {
|
|
354
|
+
await rm(tmp, { force: true }).catch(() => {});
|
|
355
|
+
}
|
|
356
|
+
return {
|
|
357
|
+
etag: newEtag,
|
|
358
|
+
serverDate: /* @__PURE__ */ new Date()
|
|
359
|
+
};
|
|
360
|
+
}
|
|
361
|
+
async delete(key, opts) {
|
|
362
|
+
opts?.signal?.throwIfAborted();
|
|
363
|
+
const path = this.#pathFor(key);
|
|
364
|
+
await this.#ensureFormat(false);
|
|
365
|
+
return withKeyLock(await this.#lockKey(path), async () => {
|
|
366
|
+
opts?.signal?.throwIfAborted();
|
|
367
|
+
try {
|
|
368
|
+
await rm(path);
|
|
369
|
+
} catch (error) {
|
|
370
|
+
if (isErrnoException(error) && error.code === "ENOENT") return;
|
|
371
|
+
throw new BaerlyError("InvalidResponse", `LocalFsStorage.delete(${key}): ${error.message}`, { cause: error });
|
|
372
|
+
}
|
|
373
|
+
});
|
|
374
|
+
}
|
|
375
|
+
/**
|
|
376
|
+
* Identity of the thing being mutated, for {@link withKeyLock}.
|
|
377
|
+
*
|
|
378
|
+
* Keyed on the *canonical filesystem path*, not on the key and not on
|
|
379
|
+
* `this`. Not on `this` because separate instances over one directory
|
|
380
|
+
* are the common case (`localFsStorage()` mints a fresh one per call),
|
|
381
|
+
* so an instance-scoped lock would serialize nothing where it matters.
|
|
382
|
+
* Not on the root spelling the caller passed, because several spellings
|
|
383
|
+
* of a root can name one directory, and handing an alias its own lock
|
|
384
|
+
* lets the race straight back in:
|
|
385
|
+
*
|
|
386
|
+
* - Symlinks. `resolve()` collapses `.`/`..` but not links, so
|
|
387
|
+
* `/tmp/data` and `/private/tmp/data` — the same directory on every
|
|
388
|
+
* Mac — look like two (measured at 2 winners before it was closed).
|
|
389
|
+
* Hence `realpath`, memoized per instance and only cached once it
|
|
390
|
+
* succeeds, so a root that does not exist yet cannot poison the entry.
|
|
391
|
+
* - Case and Unicode in the root path. A caller can spell a root on a
|
|
392
|
+
* folding filesystem as `/Users/me/Data` or `/users/me/data`, or in
|
|
393
|
+
* NFC or NFD, and reach one directory.
|
|
394
|
+
*
|
|
395
|
+
* The key-derived tail of `path` cannot alias: it is the fold-invariant
|
|
396
|
+
* encoding from `local-fs-key-codec.ts`, so distinct keys are distinct
|
|
397
|
+
* files on every filesystem and the case/NFC fold below changes nothing
|
|
398
|
+
* there. The fold is kept for the root-spelling case only. It
|
|
399
|
+
* over-approximates on a case-sensitive filesystem, where two roots
|
|
400
|
+
* differing only in case are really different directories and share a
|
|
401
|
+
* lock; that costs a little concurrency, never correctness. And it is
|
|
402
|
+
* not exact Unicode case folding (JS has no `toCaseFold()`), so a root
|
|
403
|
+
* spelled with `Σ` and one with `σ` get separate locks — acceptable for
|
|
404
|
+
* a root path, which the operator chooses once.
|
|
405
|
+
*/
|
|
406
|
+
async #lockKey(path) {
|
|
407
|
+
return (await this.#canonicalRoot() + path.slice(this.#root.length)).normalize("NFC").toLowerCase();
|
|
408
|
+
}
|
|
409
|
+
/**
|
|
410
|
+
* {@link #root} with symlinks resolved. Cached only on success: `delete`
|
|
411
|
+
* against a bucket that was never created would otherwise memoize the
|
|
412
|
+
* un-canonicalized spelling and defeat the aliasing guard for every
|
|
413
|
+
* later `put`.
|
|
414
|
+
*
|
|
415
|
+
* Only `ENOENT` falls back. Every other `realpath` failure — `EACCES`,
|
|
416
|
+
* `ELOOP`, `ENAMETOOLONG` — throws, because the fallback is a *different
|
|
417
|
+
* lock key*, and absorbing those would let an instance that cannot
|
|
418
|
+
* canonicalize run unserialized against one that can. That is the
|
|
419
|
+
* exactly-one-winner guarantee this lock exists to provide, failing
|
|
420
|
+
* silently, which is indistinguishable from the defect it fixed. A root
|
|
421
|
+
* that is unreadable is a broken deployment either way; the only choice
|
|
422
|
+
* is whether it says so.
|
|
423
|
+
*
|
|
424
|
+
* Not caching failure bounds that to one call but does not erase it.
|
|
425
|
+
* `put` mkdirs before locking so it always canonicalizes; `delete` does
|
|
426
|
+
* not, so against a not-yet-created symlinked root it locks the
|
|
427
|
+
* unresolved spelling while a concurrent `put` locks the resolved one —
|
|
428
|
+
* two locks, no serialization. That needs only ONE spelling in play, not
|
|
429
|
+
* two: the split is resolved-vs-unresolved form of the same path.
|
|
430
|
+
*
|
|
431
|
+
* Known and kept, not overlooked. The hazard `delete` locks
|
|
432
|
+
* against is slipping inside an `ifMatch` compare→publish, which needs
|
|
433
|
+
* the key to exist, hence the root to exist, hence `realpath` to have
|
|
434
|
+
* succeeded — so both conditions hold only if the root appears between
|
|
435
|
+
* this call and the `rm`, and the next call self-heals. Fixes cost more
|
|
436
|
+
* than that: mkdir-to-get-a-lock-key makes deleting from an absent
|
|
437
|
+
* bucket create it, and walking to the deepest existing ancestor adds
|
|
438
|
+
* real complexity for an unreachable window.
|
|
439
|
+
*/
|
|
440
|
+
async #canonicalRoot() {
|
|
441
|
+
if (this.#realRoot !== void 0) return this.#realRoot;
|
|
442
|
+
try {
|
|
443
|
+
this.#realRoot = await realpath(this.#root);
|
|
444
|
+
return this.#realRoot;
|
|
445
|
+
} catch (error) {
|
|
446
|
+
if (isErrnoException(error) && error.code === "ENOENT") return this.#root;
|
|
447
|
+
throw new BaerlyError("InvalidResponse", `LocalFsStorage: cannot canonicalize root (${this.#root}): ${error.message}`, { cause: error });
|
|
448
|
+
}
|
|
449
|
+
}
|
|
450
|
+
async *list(prefix, opts) {
|
|
451
|
+
opts?.signal?.throwIfAborted();
|
|
452
|
+
const startAfter = opts?.startAfter ?? "";
|
|
453
|
+
const maxKeys = opts?.maxKeys ?? 1e400;
|
|
454
|
+
await this.#ensureFormat(false);
|
|
455
|
+
const keys = [];
|
|
456
|
+
for (const components of await walk(this.#root) ?? []) {
|
|
457
|
+
const key = decodeComponents(components);
|
|
458
|
+
if (key !== null) {
|
|
459
|
+
keys.push(key);
|
|
460
|
+
continue;
|
|
461
|
+
}
|
|
462
|
+
const alias = await this.#aliasedKey(components);
|
|
463
|
+
if (alias !== null) throw new BaerlyError("InvalidConfig", `LocalFsStorage.list: ${join(this.#root, ...components)} was not written by this adapter but the filesystem resolves key ${JSON.stringify(alias)} to it; move the file out of the data directory`);
|
|
464
|
+
}
|
|
465
|
+
keys.sort(compareKeysUtf8);
|
|
466
|
+
let yielded = 0;
|
|
467
|
+
for (const key of keys) {
|
|
468
|
+
if (!key.startsWith(prefix)) continue;
|
|
469
|
+
if (compareKeysUtf8(key, startAfter) <= 0) continue;
|
|
470
|
+
if (yielded >= maxKeys) return;
|
|
471
|
+
opts?.signal?.throwIfAborted();
|
|
472
|
+
let buf;
|
|
473
|
+
try {
|
|
474
|
+
buf = await readFile(this.#pathFor(key));
|
|
475
|
+
} catch (error) {
|
|
476
|
+
if (isErrnoException(error) && error.code === "ENOENT") continue;
|
|
477
|
+
throw new BaerlyError("InvalidResponse", `LocalFsStorage.list(${key}): ${error.message}`, { cause: error });
|
|
478
|
+
}
|
|
479
|
+
yield {
|
|
480
|
+
key,
|
|
481
|
+
etag: etagOf(buf)
|
|
482
|
+
};
|
|
483
|
+
yielded += 1;
|
|
484
|
+
}
|
|
485
|
+
}
|
|
486
|
+
/**
|
|
487
|
+
* The key whose on-disk path the filesystem resolves to the stray file at
|
|
488
|
+
* `components`, or `null` if none does. Only a case- or
|
|
489
|
+
* normalization-folding filesystem produces one: the candidate is
|
|
490
|
+
* {@link foldToEncodedAlphabet} of the name, which is a key only if it
|
|
491
|
+
* decodes, and an alias only if both paths name the same inode.
|
|
492
|
+
*/
|
|
493
|
+
async #aliasedKey(components) {
|
|
494
|
+
const folded = components.map(foldToEncodedAlphabet);
|
|
495
|
+
const key = decodeComponents(folded);
|
|
496
|
+
if (key === null) return null;
|
|
497
|
+
try {
|
|
498
|
+
const [a, b] = await Promise.all([stat(join(this.#root, ...components)), stat(join(this.#root, ...folded))]);
|
|
499
|
+
return a.dev === b.dev && a.ino === b.ino ? key : null;
|
|
500
|
+
} catch (error) {
|
|
501
|
+
if (isErrnoException(error) && (error.code === "ENOENT" || error.code === "ENOTDIR" || error.code === "ENAMETOOLONG")) return null;
|
|
502
|
+
throw new BaerlyError("InvalidResponse", `LocalFsStorage.list: ${error.message}`, { cause: error });
|
|
503
|
+
}
|
|
504
|
+
}
|
|
505
|
+
/**
|
|
506
|
+
* Make sure the root uses the current key encoding before any operation
|
|
507
|
+
* touches it. With the marker present this is one small read per
|
|
508
|
+
* instance. Without it the root is scanned once:
|
|
509
|
+
*
|
|
510
|
+
* - absent root: nothing to read, so reads return without stamping, and
|
|
511
|
+
* the first `put` (`create`) makes the root and stamps it;
|
|
512
|
+
* - every on-disk name already reads the same under the encoding (true
|
|
513
|
+
* of kernel-written trees with lowercase ids that hold no snapshot;
|
|
514
|
+
* the snapshot segment `L9` is escaped): stamp, nothing moves;
|
|
515
|
+
* - otherwise refuse with `InvalidConfig`. There is no in-place
|
|
516
|
+
* migration — renaming cannot undo merges a folding filesystem has
|
|
517
|
+
* already made — so the remedy is dump with the older release and
|
|
518
|
+
* restore into a fresh directory.
|
|
519
|
+
*
|
|
520
|
+
* Only success is cached, so a refusal repeats on every call.
|
|
521
|
+
*/
|
|
522
|
+
async #ensureFormat(create) {
|
|
523
|
+
if (this.#formatChecked) return;
|
|
524
|
+
await this.#canonicalRoot();
|
|
525
|
+
const marker = join(this.#root, FORMAT_MARKER);
|
|
526
|
+
if (await readFormatMarker(marker)) {
|
|
527
|
+
this.#formatChecked = true;
|
|
528
|
+
return;
|
|
529
|
+
}
|
|
530
|
+
if (create) await mkdir(this.#root, { recursive: true });
|
|
531
|
+
const legacy = await findLegacyPaths(this.#root);
|
|
532
|
+
if (legacy === null) return;
|
|
533
|
+
if (legacy.length > 0 && !await readFormatMarker(marker)) {
|
|
534
|
+
const shown = legacy.slice(0, LEGACY_PATHS_SHOWN).map((p) => ` ${p}`);
|
|
535
|
+
if (legacy.length > LEGACY_PATHS_SHOWN) shown.push(` … and ${legacy.length - LEGACY_PATHS_SHOWN} more`);
|
|
536
|
+
throw new BaerlyError("InvalidConfig", `LocalFsStorage: ${this.#root} holds dev data from an older release, which this release cannot read. Move the directory aside or delete it; the next write starts a fresh one. The usual causes are a folded collection (\`snapshot/L9/\`) and an uppercase letter in a collection name or id (a camelCase name such as \`boardInvitees\`). To keep a collection's rows, dump it with the older release (\`baerly admin dump\`) and restore into the fresh directory (\`baerly admin restore\`); a dump holds collection rows only, not other files the app stored here. Paths not valid under the current key encoding (no ${FORMAT_MARKER} marker):\n${shown.join("\n")}\nIf a listed path is a stray file that is not data, move it out of the directory instead. Keys that differed only by case or Unicode normalization may already have been merged by the filesystem.`);
|
|
537
|
+
}
|
|
538
|
+
await stampFormatMarker(marker);
|
|
539
|
+
this.#formatChecked = true;
|
|
540
|
+
}
|
|
541
|
+
/**
|
|
542
|
+
* Map an S3-style key to a filesystem path under `#root`, rejecting
|
|
543
|
+
* anything that could escape the root (path traversal, absolute
|
|
544
|
+
* paths, empty segments, backslashes) or that the encoding cannot
|
|
545
|
+
* represent injectively (lone surrogates). All rejections throw
|
|
546
|
+
* `BaerlyError("InvalidConfig", …)`.
|
|
547
|
+
*/
|
|
548
|
+
#pathFor(key) {
|
|
549
|
+
assertValidStorageKey(key);
|
|
550
|
+
if (key.startsWith("/")) throw new BaerlyError("InvalidConfig", `LocalFsStorage: leading "/" in key: ${key}`);
|
|
551
|
+
if (key.includes("\\")) throw new BaerlyError("InvalidConfig", `LocalFsStorage: backslash in key: ${key}`);
|
|
552
|
+
if (key.split("/").some((s) => s === "" || s === "." || s === "..")) throw new BaerlyError("InvalidConfig", `LocalFsStorage: illegal segment in key: ${key}`);
|
|
553
|
+
const path = join(this.#root, ...encodeKey(key));
|
|
554
|
+
if (path !== this.#root && !path.startsWith(this.#root + sep)) throw new BaerlyError("InvalidConfig", `LocalFsStorage: resolved path escapes root: ${key}`);
|
|
555
|
+
return path;
|
|
556
|
+
}
|
|
557
|
+
};
|
|
558
|
+
const etagOf = (body) => {
|
|
559
|
+
return `"${createHash("sha256").update(body).digest("hex")}"`;
|
|
560
|
+
};
|
|
561
|
+
const toUint8Array = (buf) => new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
|
|
562
|
+
const isErrnoException = (e) => typeof e === "object" && e !== null && "code" in e;
|
|
563
|
+
const readExisting = async (path) => {
|
|
564
|
+
try {
|
|
565
|
+
return await readFile(path);
|
|
566
|
+
} catch (error) {
|
|
567
|
+
if (isErrnoException(error) && error.code === "ENOENT") return null;
|
|
568
|
+
throw error;
|
|
569
|
+
}
|
|
570
|
+
};
|
|
571
|
+
/**
|
|
572
|
+
* `true` when the root's format marker exists and names the current
|
|
573
|
+
* encoding, `false` when it is absent. A marker naming another encoding
|
|
574
|
+
* means a newer release wrote this directory, so it is refused.
|
|
575
|
+
*/
|
|
576
|
+
const readFormatMarker = async (marker) => {
|
|
577
|
+
const body = await readExisting(marker).catch((error) => {
|
|
578
|
+
throw new BaerlyError("InvalidResponse", `LocalFsStorage: cannot read ${marker}: ${error.message}`, { cause: error });
|
|
579
|
+
});
|
|
580
|
+
if (body === null) return false;
|
|
581
|
+
let encoding;
|
|
582
|
+
try {
|
|
583
|
+
encoding = JSON.parse(new TextDecoder().decode(body)).key_encoding;
|
|
584
|
+
} catch (error) {
|
|
585
|
+
throw new BaerlyError("InvalidResponse", `LocalFsStorage: ${marker} is not valid JSON`, { cause: error });
|
|
586
|
+
}
|
|
587
|
+
if (encoding !== KEY_ENCODING) throw new BaerlyError("InvalidConfig", `LocalFsStorage: ${marker} names key_encoding ${JSON.stringify(encoding)}; this release reads only key_encoding ${KEY_ENCODING}`);
|
|
588
|
+
return true;
|
|
589
|
+
};
|
|
590
|
+
/**
|
|
591
|
+
* Write the format marker with the same temp + `link(2)` exclusive create
|
|
592
|
+
* as `ifNoneMatch:"*"`. Losing that race to a concurrent opener is fine as
|
|
593
|
+
* long as what it wrote is the current encoding.
|
|
594
|
+
*/
|
|
595
|
+
const stampFormatMarker = async (marker) => {
|
|
596
|
+
const tmp = tempPathFor(marker);
|
|
597
|
+
try {
|
|
598
|
+
await writeFile(tmp, `${JSON.stringify({ key_encoding: KEY_ENCODING })}\n`);
|
|
599
|
+
await link(tmp, marker);
|
|
600
|
+
} catch (error) {
|
|
601
|
+
if (isErrnoException(error) && error.code === "EEXIST" && await readFormatMarker(marker)) return;
|
|
602
|
+
throw new BaerlyError("InvalidResponse", `LocalFsStorage: cannot write ${marker}: ${error.message}`, { cause: error });
|
|
603
|
+
} finally {
|
|
604
|
+
await rm(tmp, { force: true }).catch(() => {});
|
|
605
|
+
}
|
|
606
|
+
};
|
|
607
|
+
/**
|
|
608
|
+
* Non-ASCII characters that APFS's full case folding maps to ASCII but
|
|
609
|
+
* `toLowerCase` leaves alone (Unicode CaseFolding.txt status `F`, plus the
|
|
610
|
+
* `C` mapping of long `ſ`). Each was checked on an APFS volume: a file
|
|
611
|
+
* named with the left side is reached by the right side.
|
|
612
|
+
*/
|
|
613
|
+
const APFS_ASCII_FOLDS = {
|
|
614
|
+
ß: "ss",
|
|
615
|
+
ẞ: "ss",
|
|
616
|
+
ſ: "s",
|
|
617
|
+
ff: "ff",
|
|
618
|
+
fi: "fi",
|
|
619
|
+
fl: "fl",
|
|
620
|
+
ffi: "ffi",
|
|
621
|
+
ffl: "ffl",
|
|
622
|
+
ſt: "st",
|
|
623
|
+
st: "st"
|
|
624
|
+
};
|
|
625
|
+
const APFS_ASCII_FOLDABLE = /[ßẞſff-st]/g;
|
|
626
|
+
/**
|
|
627
|
+
* Fold an on-disk name the way a folding filesystem matches it, as far as
|
|
628
|
+
* the result can land in the encoded alphabet (`a-z0-9-_.%`). A name
|
|
629
|
+
* containing anything else after the fold cannot decode, so only folds to
|
|
630
|
+
* ASCII matter: lowercase (which also maps Kelvin `K` to `k`) plus
|
|
631
|
+
* {@link APFS_ASCII_FOLDS}. Normalization adds none: the only canonical
|
|
632
|
+
* decompositions to ASCII are Kelvin `K`, U+037E (`;`) and U+1FEF (`` ` ``),
|
|
633
|
+
* and the last two are escaped by the encoding.
|
|
634
|
+
*/
|
|
635
|
+
const foldToEncodedAlphabet = (name) => name.replace(APFS_ASCII_FOLDABLE, (c) => APFS_ASCII_FOLDS[c]).toLowerCase();
|
|
636
|
+
/**
|
|
637
|
+
* Paths under `root` that the pre-encoding layout wrote and the current
|
|
638
|
+
* encoding would read differently (uppercase, non-ASCII, `%`, `~`, a
|
|
639
|
+
* leading `.` …). Empty when the tree can be adopted as-is; `null` when
|
|
640
|
+
* the root does not exist.
|
|
641
|
+
*
|
|
642
|
+
* Walks dot-prefixed names too: the old layout stored a key segment such
|
|
643
|
+
* as an `_id` or collection named `.foo` verbatim, and the encoding treats
|
|
644
|
+
* that name as adapter-private, so skipping it here would adopt the tree
|
|
645
|
+
* and silently drop or orphan that data.
|
|
646
|
+
*/
|
|
647
|
+
const findLegacyPaths = async (root) => {
|
|
648
|
+
const files = await walk(root, isLegacyScanNoise);
|
|
649
|
+
if (files === null) return null;
|
|
650
|
+
return files.filter((components) => decodeComponents(components) !== components.join("/")).map((components) => components.join("/")).toSorted();
|
|
651
|
+
};
|
|
652
|
+
/**
|
|
653
|
+
* Entries the legacy scan may skip: staging temps (both layouts wrote them,
|
|
654
|
+
* and the old one rejected keys with that prefix), and the files Finder
|
|
655
|
+
* and git leave behind. Junk names are skipped as FILES only — a directory
|
|
656
|
+
* called `.DS_Store` would be a legacy collection or tenant, i.e. data.
|
|
657
|
+
* Nothing else is assumed not to be data.
|
|
658
|
+
*
|
|
659
|
+
* The format marker is deliberately not here. The scan runs only when the
|
|
660
|
+
* marker was absent; if a concurrent opener stamps it mid-scan, the scan
|
|
661
|
+
* flags it like any other name and `#ensureFormat`'s re-read of the marker
|
|
662
|
+
* is what accepts the directory. A nested file with the marker's name is
|
|
663
|
+
* legacy data (a key segment that old layout stored verbatim).
|
|
664
|
+
*/
|
|
665
|
+
const isLegacyScanNoise = (name, isDirectory) => name.startsWith(TEMP_PREFIX) || !isDirectory && (name === ".DS_Store" || name === ".gitkeep");
|
|
666
|
+
/**
|
|
667
|
+
* In the current layout every dot-prefixed name is not a key: no encoded
|
|
668
|
+
* key component starts with `.`, so those are adapter-private (staging
|
|
669
|
+
* temps, the format marker) or foreign (`.DS_Store`). Skipping temps is
|
|
670
|
+
* what keeps a concurrent `list` from surfacing a half-published key.
|
|
671
|
+
*/
|
|
672
|
+
const isDotName = (name, _isDirectory) => name.startsWith(".");
|
|
673
|
+
/**
|
|
674
|
+
* Recursive directory walk. Returns each file's path components relative
|
|
675
|
+
* to `root`, or `null` when `root` does not exist. Entries for which
|
|
676
|
+
* `skip` holds are ignored at every depth, directories included.
|
|
677
|
+
*/
|
|
678
|
+
const walk = async (root, skip = isDotName) => {
|
|
679
|
+
const out = [];
|
|
680
|
+
const stack = [{
|
|
681
|
+
dir: root,
|
|
682
|
+
components: []
|
|
683
|
+
}];
|
|
684
|
+
while (stack.length > 0) {
|
|
685
|
+
const { dir, components } = stack.pop();
|
|
686
|
+
let entries;
|
|
687
|
+
try {
|
|
688
|
+
entries = await readdir(dir, { withFileTypes: true });
|
|
689
|
+
} catch (error) {
|
|
690
|
+
if (isErrnoException(error) && error.code === "ENOENT") {
|
|
691
|
+
if (dir === root) return null;
|
|
692
|
+
continue;
|
|
693
|
+
}
|
|
694
|
+
throw error;
|
|
695
|
+
}
|
|
696
|
+
for (const entry of entries) {
|
|
697
|
+
if (skip(entry.name, entry.isDirectory())) continue;
|
|
698
|
+
const next = [...components, entry.name];
|
|
699
|
+
if (entry.isDirectory()) stack.push({
|
|
700
|
+
dir: join(dir, entry.name),
|
|
701
|
+
components: next
|
|
702
|
+
});
|
|
703
|
+
else if (entry.isFile()) out.push(next);
|
|
704
|
+
}
|
|
705
|
+
}
|
|
706
|
+
return out;
|
|
707
|
+
};
|
|
708
|
+
// packages/dev/src/dev-banner.ts
|
|
709
|
+
function printDevBanner(opts) {
|
|
710
|
+
const isPlain = opts.plain !== void 0 ? opts.plain : process.env["CI"] !== void 0 || !process.stderr.isTTY;
|
|
711
|
+
const write = opts.write ?? ((chunk) => process.stderr.write(chunk));
|
|
712
|
+
const paint = (format, text) => isPlain ? text : styleText(format, text, { validateStream: false });
|
|
713
|
+
const pc = {
|
|
714
|
+
boldCyan: (text) => paint(["bold", "cyan"], text),
|
|
715
|
+
green: (text) => paint("green", text),
|
|
716
|
+
dim: (text) => paint("dim", text)
|
|
717
|
+
};
|
|
718
|
+
const hints = opts.hints ?? [];
|
|
719
|
+
const lines = [];
|
|
720
|
+
if (isPlain) {
|
|
721
|
+
lines.push(`baerly · ${opts.name}`);
|
|
722
|
+
if (opts.primaryUrl) lines.push(`${opts.primaryUrl.label}: ${opts.primaryUrl.url}`);
|
|
723
|
+
if (opts.apiUrl) {
|
|
724
|
+
const note = opts.apiUrl.note ? ` (${opts.apiUrl.note})` : "";
|
|
725
|
+
lines.push(`${opts.apiUrl.label}: ${opts.apiUrl.url}${note}`);
|
|
726
|
+
}
|
|
727
|
+
for (const hint of hints) lines.push(`${hint.key}: ${hint.value}`);
|
|
728
|
+
write(lines.join("\n") + "\n");
|
|
729
|
+
} else {
|
|
730
|
+
lines.push(pc.boldCyan(`▎ baerly · ${opts.name}`));
|
|
731
|
+
lines.push("");
|
|
732
|
+
if (opts.primaryUrl) {
|
|
733
|
+
const marker = ` ${pc.green("← open this")}`;
|
|
734
|
+
lines.push(` ${pc.dim(opts.primaryUrl.label)} → ${opts.primaryUrl.url}${marker}`);
|
|
735
|
+
}
|
|
736
|
+
if (opts.apiUrl) {
|
|
737
|
+
const note = opts.apiUrl.note ? ` ${pc.dim(`(${opts.apiUrl.note})`)}` : "";
|
|
738
|
+
lines.push(` ${pc.dim(opts.apiUrl.label)} → ${opts.apiUrl.url}${note}`);
|
|
739
|
+
}
|
|
740
|
+
if ((opts.primaryUrl || opts.apiUrl) && hints.length > 0) lines.push("");
|
|
741
|
+
if (hints.length > 0) {
|
|
742
|
+
const maxKeyLen = Math.max(...hints.map((h) => h.key.length));
|
|
743
|
+
for (const hint of hints) lines.push(` ${pc.dim(hint.key.padEnd(maxKeyLen))} ${hint.value}`);
|
|
744
|
+
}
|
|
745
|
+
lines.push("");
|
|
746
|
+
write(lines.join("\n"));
|
|
747
|
+
}
|
|
748
|
+
}
|
|
749
|
+
// packages/dev/src/ensure-table.ts
|
|
750
|
+
/**
|
|
751
|
+
* Optional pre-warm: idempotently create the `current.json` manifest
|
|
752
|
+
* for a single `(app, tenant, collection)` triple. The kernel auto-creates
|
|
753
|
+
* this manifest on the first commit anyway (see `Db.create` and
|
|
754
|
+
* `Writer.commit`), so calling `ensureTable` is **not required** for
|
|
755
|
+
* correctness — it's a one-Class-A-PUT optimization for callers that
|
|
756
|
+
* want the manifest in place before the first request lands (seed
|
|
757
|
+
* scripts, deploy-time provisioning, CI fixtures that snapshot the
|
|
758
|
+
* bucket between phases, etc.).
|
|
759
|
+
*
|
|
760
|
+
* Wraps {@link createCurrentJson} with the canonical key shape
|
|
761
|
+
* (`app/<app>/tenant/<tenant>/manifests/<collection>/current.json`) and
|
|
762
|
+
* swallows `BaerlyError{code:"WriteConflict"}` so re-runs are safe. The
|
|
763
|
+
* three names follow the same rule as `Db.create` / `db.collection`
|
|
764
|
+
* (including Unicode Normalization Form C), refused with
|
|
765
|
+
* `BaerlyError{code:"InvalidConfig"}` before any write. An
|
|
766
|
+
* existing manifest is preserved verbatim — this function never
|
|
767
|
+
* overwrites a populated manifest. The seed shape matches the kernel's
|
|
768
|
+
* auto-create, with one deliberate exception: `generation` is a fresh
|
|
769
|
+
* nonce, so a pre-warm and an auto-provision are equivalent rather than
|
|
770
|
+
* byte-identical. Only one of them can win the `If-None-Match` create,
|
|
771
|
+
* and a generation is only ever compared against a cursor minted from
|
|
772
|
+
* it, so the difference is unobservable.
|
|
773
|
+
*
|
|
774
|
+
* @example
|
|
775
|
+
* ```ts
|
|
776
|
+
* import { LocalFsStorage, ensureTable } from "@gusto/baerly-storage/dev";
|
|
777
|
+
*
|
|
778
|
+
* const storage = new LocalFsStorage({ root: "./.baerly-data" });
|
|
779
|
+
* // Pre-warm so the first request doesn't pay the bootstrap PUT.
|
|
780
|
+
* await ensureTable(storage, { app: "helpdesk", tenant: "demo", collection: "tickets" });
|
|
781
|
+
* // …then `baerlyNode({ config, storage, verifier })`.
|
|
782
|
+
* ```
|
|
783
|
+
*/
|
|
784
|
+
const ensureTable = async (storage, args) => {
|
|
785
|
+
if (typeof args.collection !== "string") throw new BaerlyError("InvalidConfig", "table" in args ? "ensureTable: the `table` key is now `collection`; pass { app, tenant, collection }" : "ensureTable: collection must be a string");
|
|
786
|
+
assertNameSegment(args.app, "app", "ensureTable");
|
|
787
|
+
assertNameSegment(args.tenant, "tenant", "ensureTable");
|
|
788
|
+
assertNameSegment(args.collection, "collection", "ensureTable");
|
|
789
|
+
const key = `app/${args.app}/tenant/${args.tenant}/manifests/${args.collection}/current.json`;
|
|
790
|
+
try {
|
|
791
|
+
await createCurrentJson(storage, key, {
|
|
792
|
+
schema_version: 3,
|
|
793
|
+
snapshot: null,
|
|
794
|
+
tail_hint: 0,
|
|
795
|
+
log_seq_start: 0,
|
|
796
|
+
writer_fence: {
|
|
797
|
+
epoch: 0,
|
|
798
|
+
owner: "",
|
|
799
|
+
claimed_at: ""
|
|
800
|
+
},
|
|
801
|
+
snapshot_bytes: 0,
|
|
802
|
+
snapshot_rows: 0,
|
|
803
|
+
generation: mintGeneration()
|
|
804
|
+
});
|
|
805
|
+
} catch (error) {
|
|
806
|
+
if (isWriteConflict(error)) return;
|
|
807
|
+
throw error;
|
|
808
|
+
}
|
|
809
|
+
};
|
|
810
|
+
export { printDevBanner as n, LocalFsStorage as r, ensureTable as t };
|
|
811
|
+
|
|
812
|
+
//# sourceMappingURL=src-D0MQfvOp.js.map
|