@gusto/baerly-storage 0.6.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 -512
- package/dist/CHANGELOG.md +1137 -378
- 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-ypCm3zjt.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-wrVYf4bb.js → cloudflare-CKHYXccw.js} +61 -82
- 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-Di_Q01qx.js → deploy-Obj4nE-Z.js} +10 -14
- 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 +9 -14
- package/dist/dev-vite.js +11 -10
- 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-Bx6xSNJj.d.ts → gcs-admin-Dso1HWQj.d.ts} +18 -14
- package/dist/gcs.d.ts +19 -7
- package/dist/gcs.js +1 -2
- package/dist/{goog4-signer-Z7KnJ1su.js → goog4-signer-CeLIABoE.js} +102 -92
- package/dist/goog4-signer-CeLIABoE.js.map +1 -0
- package/dist/{http-7zT29K3P.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-DP3ClvcA.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 +119 -92
- package/dist/node.js +3 -3
- package/dist/{observability-Ch-VQJyE.js → observability-C-ISCCLE.js} +1247 -326
- 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-C4qgiXSg.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--LykAdl1.js → runtime-spec-B5mg3pHF.js} +189 -28
- package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
- package/dist/{s3-http-DD5gDc7t.d.ts → s3-http-DBC_wiCL.d.ts} +14 -8
- package/dist/s3.d.ts +20 -7
- package/dist/s3.js +4 -5
- package/dist/s3.js.map +1 -1
- package/dist/{sha256-CqcKTjw9.js → sha256-4FfGQNPw.js} +9 -9
- 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/{aws4fetch.esm-CXE5ZbAa.js → sigv4-sign-5IUflUD_.js} +143 -96
- 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-BMFfDUI2.js → src-Actga-bO.js} +949 -363
- 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-BV68pqwJ.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-BMZR8o6U.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 +90 -69
- package/dist/aws4fetch.esm-CXE5ZbAa.js.map +0 -1
- package/dist/bytes-BXdamO3L.js +0 -11
- package/dist/bytes-BXdamO3L.js.map +0 -1
- package/dist/cloudflare-wrVYf4bb.js.map +0 -1
- package/dist/config-B6nTy8e2.js +0 -3095
- package/dist/config-B6nTy8e2.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-_SE_SVgZ.js +0 -203
- package/dist/cost-_SE_SVgZ.js.map +0 -1
- package/dist/current-json-C6nhPOm1.js.map +0 -1
- package/dist/db-DjjthkTi.d.ts +0 -254
- package/dist/deploy-Di_Q01qx.js.map +0 -1
- package/dist/doctor-RWVRpvat.js +0 -102
- package/dist/doctor-RWVRpvat.js.map +0 -1
- package/dist/dump-m2vEYDNY.js +0 -94
- package/dist/dump-m2vEYDNY.js.map +0 -1
- package/dist/errors-Dfa3p78c.js +0 -78
- package/dist/errors-Dfa3p78c.js.map +0 -1
- package/dist/export-DenKwEQu.js +0 -401
- package/dist/export-DenKwEQu.js.map +0 -1
- package/dist/fsck-2Vq-7-e2.js +0 -279
- package/dist/fsck-2Vq-7-e2.js.map +0 -1
- package/dist/goog4-signer-Z7KnJ1su.js.map +0 -1
- package/dist/http-7zT29K3P.js.map +0 -1
- package/dist/http-transport-BTgVCY5r.js +0 -1250
- package/dist/http-transport-BTgVCY5r.js.map +0 -1
- package/dist/index-BHz92Acj.d.ts +0 -162
- package/dist/index-CEZKQsKt.d.ts +0 -1113
- package/dist/index-uE-w2dgj.d.ts +0 -115
- package/dist/indexes-Dn9hbGQG.d.ts +0 -22
- package/dist/inspect-BpYbH1DM.js +0 -133
- package/dist/inspect-BpYbH1DM.js.map +0 -1
- package/dist/log-tail-QWU4wlu-.js +0 -514
- package/dist/log-tail-QWU4wlu-.js.map +0 -1
- package/dist/maintenance-BGHGt2Yg.d.ts +0 -537
- package/dist/maintenance-DULFcpd1.js +0 -2144
- package/dist/maintenance-DULFcpd1.js.map +0 -1
- package/dist/maintenance-fEi-UZ2o.js +0 -1412
- package/dist/maintenance-fEi-UZ2o.js.map +0 -1
- package/dist/normalize-rjnZLwS4.js +0 -133
- package/dist/normalize-rjnZLwS4.js.map +0 -1
- package/dist/observability-Ch-VQJyE.js.map +0 -1
- package/dist/plan-C4qgiXSg.js.map +0 -1
- package/dist/query-C43r-6ib.js +0 -1773
- package/dist/query-C43r-6ib.js.map +0 -1
- package/dist/rebuild-index-BH1dc1p6.js +0 -81
- package/dist/rebuild-index-BH1dc1p6.js.map +0 -1
- package/dist/request-u0M51mhJ.js +0 -72
- package/dist/request-u0M51mhJ.js.map +0 -1
- package/dist/restore-D0VYWzfP.js +0 -778
- package/dist/restore-D0VYWzfP.js.map +0 -1
- package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
- package/dist/runtime-spec--LykAdl1.js.map +0 -1
- package/dist/sha256-CqcKTjw9.js.map +0 -1
- package/dist/shared-secret-DgEicd3x.js.map +0 -1
- package/dist/src-BMFfDUI2.js.map +0 -1
- package/dist/src-DYZ4H1aF.js +0 -392
- package/dist/src-DYZ4H1aF.js.map +0 -1
- package/dist/src-DvbTEya2.js +0 -536
- package/dist/src-DvbTEya2.js.map +0 -1
- package/dist/subcommand-BV68pqwJ.js.map +0 -1
- package/dist/time-DUqvFMHq.js.map +0 -1
- package/dist/usage-BMZR8o6U.js.map +0 -1
- package/dist/validate-DtljsCh1.js.map +0 -1
- package/dist/wire-izfGZDvr.js.map +0 -1
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
import { a as isJsonMode, s as BaerlyError, t as color } from "./baerly.js";
|
|
2
|
+
import { l as uuid, n as parseBucketUri, t as loadAppConfig } from "./config-DEzInG6M.js";
|
|
3
|
+
import { a as mergeReports, i as doctorCloudflare, n as defaultRunner, o as rollupStatus, r as doctorGcsConfig, s as doctorCas } from "./cloudflare-CKHYXccw.js";
|
|
4
|
+
import { c as defineBaerlySubcommand, i as JSON_ARG } from "./subcommand-BLoF66dG.js";
|
|
5
|
+
// src/doctor/list-encoding.ts
|
|
6
|
+
/**
|
|
7
|
+
* `baerly doctor --bucket <uri>` — live LIST key-encoding probe.
|
|
8
|
+
*
|
|
9
|
+
* App, tenant, and collection names may hold `%`, spaces, `+`, and
|
|
10
|
+
* XML-special characters, and they are interpolated raw into object keys.
|
|
11
|
+
* The S3 and GCS adapters list with `encoding-type=url` and decode each
|
|
12
|
+
* returned key once; GC then deletes the keys LIST hands back. A backend
|
|
13
|
+
* or gateway that ignores `encoding-type=url`, encodes twice, or encodes
|
|
14
|
+
* `+` / spaces differently hands back keys that are not the ones written,
|
|
15
|
+
* so this probe writes keys with those characters, lists them, and
|
|
16
|
+
* compares the listed key byte-for-byte against what was put.
|
|
17
|
+
*
|
|
18
|
+
* Bounded: two puts, two single-prefix lists (at most
|
|
19
|
+
* {@link LIST_ENTRY_LIMIT} entries each), and two deletes, all under a
|
|
20
|
+
* fresh `__baerly_list_probe__/<uuid>/` prefix. Cleanup runs in `finally`
|
|
21
|
+
* and a failed delete is reported, not swallowed.
|
|
22
|
+
*/
|
|
23
|
+
/**
|
|
24
|
+
* The two sentinel key leaves. `escapes` carries already-valid percent
|
|
25
|
+
* escapes (`%2F`, `%25`), whitespace, `+`, the five XML-special
|
|
26
|
+
* characters, and a non-ASCII letter; it decodes cleanly, so a key that
|
|
27
|
+
* was decoded one time too many is recognisable. `bare-percent` carries
|
|
28
|
+
* a `%` that starts no valid escape, which a raw (unencoded) LIST
|
|
29
|
+
* response cannot decode at all.
|
|
30
|
+
*/
|
|
31
|
+
const LIST_PROBE_SENTINELS = [{
|
|
32
|
+
name: "escapes",
|
|
33
|
+
leaf: `e/a%2Fb %25 c+d & < > " ' é`
|
|
34
|
+
}, {
|
|
35
|
+
name: "bare-percent",
|
|
36
|
+
leaf: "p/100% bare"
|
|
37
|
+
}];
|
|
38
|
+
const utf8 = new TextEncoder();
|
|
39
|
+
const LIST_FIX = "Point baerly at a store whose ListObjects honours `encoding-type=url` and returns each key exactly as written (AWS S3, Cloudflare R2, MinIO, and native GCS do). A gateway or proxy that rewrites list responses can break this; names holding `%`, spaces, `+`, or `&<>\"'` would otherwise be mis-listed and mishandled by maintenance.";
|
|
40
|
+
/** The adapters' decode step: `+` → space, then one percent-decode. */
|
|
41
|
+
const decodeOnce = (s) => {
|
|
42
|
+
try {
|
|
43
|
+
return decodeURIComponent(s.replace(/\+/g, " "));
|
|
44
|
+
} catch {
|
|
45
|
+
return;
|
|
46
|
+
}
|
|
47
|
+
};
|
|
48
|
+
const xmlEscape = (s) => s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """).replace(/'/g, "'");
|
|
49
|
+
const firstByteDiff = (a, b) => {
|
|
50
|
+
const n = Math.min(a.length, b.length);
|
|
51
|
+
for (let i = 0; i < n; i += 1) if (a[i] !== b[i]) return i;
|
|
52
|
+
return n;
|
|
53
|
+
};
|
|
54
|
+
const sameBytes = (a, b) => {
|
|
55
|
+
const x = utf8.encode(a);
|
|
56
|
+
const y = utf8.encode(b);
|
|
57
|
+
return x.length === y.length && firstByteDiff(x, y) === x.length;
|
|
58
|
+
};
|
|
59
|
+
/**
|
|
60
|
+
* Known ways a listed key goes wrong, checked in order. Each derives the
|
|
61
|
+
* expected-wrong listing from the put key and names the likely cause.
|
|
62
|
+
*/
|
|
63
|
+
const DIAGNOSES = [
|
|
64
|
+
{
|
|
65
|
+
kind: "not decoded",
|
|
66
|
+
matches: (listed, put) => decodeOnce(listed) === put,
|
|
67
|
+
cause: "it still carries one layer of URL encoding: the backend encodes list keys twice, or the client does not decode `encoding-type=url` responses"
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
kind: "double decoded",
|
|
71
|
+
matches: (listed, put) => {
|
|
72
|
+
const once = decodeOnce(put);
|
|
73
|
+
return once !== void 0 && once !== put && listed === once;
|
|
74
|
+
},
|
|
75
|
+
cause: "it was decoded one time too many: the backend ignores `encoding-type=url` and returns raw keys, or the client decodes twice"
|
|
76
|
+
},
|
|
77
|
+
{
|
|
78
|
+
kind: "`+` not decoded to space",
|
|
79
|
+
matches: (listed, put) => put.includes(" ") && listed === put.replaceAll(" ", "+"),
|
|
80
|
+
cause: "spaces came back as `+`: the encoded form uses `+` for space and the client percent-decodes without mapping `+` back"
|
|
81
|
+
},
|
|
82
|
+
{
|
|
83
|
+
kind: "literal `+` decoded to space",
|
|
84
|
+
matches: (listed, put) => put.includes("+") && listed === put.replaceAll("+", " "),
|
|
85
|
+
cause: "a literal `+` came back as a space: the backend does not percent-encode `+` in list keys"
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
kind: "XML entities not unescaped",
|
|
89
|
+
matches: (listed, put) => listed === xmlEscape(put),
|
|
90
|
+
cause: "XML entities such as `&` were left in the key: the list response was not XML-unescaped"
|
|
91
|
+
}
|
|
92
|
+
];
|
|
93
|
+
const describeMismatch = (listed, put, show) => {
|
|
94
|
+
const diagnosis = DIAGNOSES.find((d) => d.matches(listed, put));
|
|
95
|
+
const got = `expected ${show(put)}, got ${show(listed)}`;
|
|
96
|
+
if (diagnosis !== void 0) return `${diagnosis.kind} — ${got}; ${diagnosis.cause}.`;
|
|
97
|
+
return `wrong decoding — ${got}; first differing UTF-8 byte at offset ${firstByteDiff(utf8.encode(put), utf8.encode(listed))}.`;
|
|
98
|
+
};
|
|
99
|
+
const errorText = (error) => error instanceof Error ? error.message : String(error);
|
|
100
|
+
/**
|
|
101
|
+
* Write each sentinel, list it back under its own prefix, compare the
|
|
102
|
+
* listed key byte-for-byte, and delete it. Status is `error` iff a
|
|
103
|
+
* sentinel was not listed exactly as written; a failed cleanup delete is
|
|
104
|
+
* a `warning` naming the leaked key.
|
|
105
|
+
*/
|
|
106
|
+
const doctorListEncoding = async (storage, keyPrefix) => {
|
|
107
|
+
const root = `${keyPrefix}__baerly_list_probe__/${uuid()}/`;
|
|
108
|
+
const show = (k) => JSON.stringify(k.startsWith(root) ? k.slice(root.length) : k);
|
|
109
|
+
const findings = [];
|
|
110
|
+
const written = [];
|
|
111
|
+
try {
|
|
112
|
+
for (const sentinel of LIST_PROBE_SENTINELS) {
|
|
113
|
+
const check = `list-encoding-${sentinel.name}`;
|
|
114
|
+
const key = `${root}${sentinel.leaf}`;
|
|
115
|
+
const fail = (message) => {
|
|
116
|
+
findings.push({
|
|
117
|
+
severity: "error",
|
|
118
|
+
check,
|
|
119
|
+
message,
|
|
120
|
+
fix: LIST_FIX
|
|
121
|
+
});
|
|
122
|
+
};
|
|
123
|
+
try {
|
|
124
|
+
written.push(key);
|
|
125
|
+
await storage.put(key, utf8.encode(sentinel.name));
|
|
126
|
+
} catch (error) {
|
|
127
|
+
fail(`PUT of the ${show(key)} sentinel failed: ${errorText(error)}`);
|
|
128
|
+
continue;
|
|
129
|
+
}
|
|
130
|
+
const listed = [];
|
|
131
|
+
try {
|
|
132
|
+
const prefix = `${root}${sentinel.leaf.slice(0, sentinel.leaf.indexOf("/") + 1)}`;
|
|
133
|
+
for await (const entry of storage.list(prefix, { maxKeys: 8 })) {
|
|
134
|
+
listed.push(entry.key);
|
|
135
|
+
if (listed.length >= 8) break;
|
|
136
|
+
}
|
|
137
|
+
} catch (error) {
|
|
138
|
+
const hint = error instanceof BaerlyError && error.code === "InvalidResponse" ? " The listed key is not valid URL encoding: the backend likely ignores `encoding-type=url` and returns raw keys." : "";
|
|
139
|
+
fail(`LIST after writing ${show(key)} failed: ${errorText(error)}.${hint}`);
|
|
140
|
+
continue;
|
|
141
|
+
}
|
|
142
|
+
if (listed.some((k) => sameBytes(k, key))) findings.push({
|
|
143
|
+
severity: "ok",
|
|
144
|
+
check,
|
|
145
|
+
message: `LIST returned the ${show(key)} sentinel byte-for-byte as written.`
|
|
146
|
+
});
|
|
147
|
+
else if (listed.length === 0) fail(`LIST did not return the ${show(key)} sentinel just written (no keys under its prefix).`);
|
|
148
|
+
else fail(`LIST mis-encoded the sentinel key: ${describeMismatch(listed[0], key, show)}`);
|
|
149
|
+
}
|
|
150
|
+
} finally {
|
|
151
|
+
for (const key of written) try {
|
|
152
|
+
await storage.delete(key);
|
|
153
|
+
} catch (error) {
|
|
154
|
+
findings.push({
|
|
155
|
+
severity: "warning",
|
|
156
|
+
check: "list-encoding-cleanup",
|
|
157
|
+
message: `Could not delete probe sentinel ${JSON.stringify(key)}: ${errorText(error)}`,
|
|
158
|
+
fix: "Delete that object by hand; it is not read by baerly."
|
|
159
|
+
});
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
return {
|
|
163
|
+
findings,
|
|
164
|
+
status: rollupStatus(findings)
|
|
165
|
+
};
|
|
166
|
+
};
|
|
167
|
+
// src/doctor.ts
|
|
168
|
+
const DOCTOR_ARGS = {
|
|
169
|
+
target: {
|
|
170
|
+
type: "string",
|
|
171
|
+
description: "Override `baerly.config.ts:target`. Only \"cloudflare\" supported (Node variants self-validate at scaffold time).",
|
|
172
|
+
valueHint: "cloudflare"
|
|
173
|
+
},
|
|
174
|
+
bucket: {
|
|
175
|
+
type: "string",
|
|
176
|
+
description: "Live-probe a bucket's CAS support (verifies If-Match / If-None-Match are honoured) and LIST key encoding (listed keys must match written keys byte-for-byte); writes + deletes throwaway sentinels. s3://, gcs://, file:///, or memory:// URI. For gcs://, also runs GCS-specific bucket-config checks (Object Versioning probe + soft-delete advisory). Independent of --target.",
|
|
177
|
+
valueHint: "s3://bucket/prefix | gcs://bucket"
|
|
178
|
+
},
|
|
179
|
+
fix: {
|
|
180
|
+
type: "boolean",
|
|
181
|
+
description: "Remediate auto-fixable findings (R2 bucket creation; secret prompts stay manual)."
|
|
182
|
+
},
|
|
183
|
+
json: JSON_ARG
|
|
184
|
+
};
|
|
185
|
+
const SEVERITY_GLYPH = {
|
|
186
|
+
ok: "✓",
|
|
187
|
+
info: "•",
|
|
188
|
+
warning: "⚠",
|
|
189
|
+
error: "✗"
|
|
190
|
+
};
|
|
191
|
+
const colorize = (severity, glyph) => {
|
|
192
|
+
if (severity === "error") return color.red(glyph);
|
|
193
|
+
if (severity === "warning") return color.yellow(glyph);
|
|
194
|
+
if (severity === "info") return color.dim(glyph);
|
|
195
|
+
return glyph;
|
|
196
|
+
};
|
|
197
|
+
const renderReport = (label, report) => {
|
|
198
|
+
if (isJsonMode()) {
|
|
199
|
+
process.stdout.write(`${JSON.stringify({ result: {
|
|
200
|
+
command: "doctor",
|
|
201
|
+
[label.kind]: label.value,
|
|
202
|
+
...report
|
|
203
|
+
} })}\n`);
|
|
204
|
+
return;
|
|
205
|
+
}
|
|
206
|
+
process.stdout.write(`baerly doctor --${label.kind}=${label.value}\n\n`);
|
|
207
|
+
let okCount = 0;
|
|
208
|
+
let warningCount = 0;
|
|
209
|
+
let errorCount = 0;
|
|
210
|
+
for (const f of report.findings) {
|
|
211
|
+
const glyph = SEVERITY_GLYPH[f.severity] ?? "•";
|
|
212
|
+
process.stdout.write(` ${colorize(f.severity, glyph)} ${f.message}\n`);
|
|
213
|
+
if (f.fix !== void 0) process.stdout.write(` fix: ${f.fix}\n`);
|
|
214
|
+
if (f.severity === "ok") okCount += 1;
|
|
215
|
+
else if (f.severity === "warning") warningCount += 1;
|
|
216
|
+
else if (f.severity === "error") errorCount += 1;
|
|
217
|
+
}
|
|
218
|
+
process.stdout.write(`\nStatus: ${errorCount} error${errorCount === 1 ? "" : "s"}, ${warningCount} warning${warningCount === 1 ? "" : "s"}, ${okCount} ok.\n`);
|
|
219
|
+
};
|
|
220
|
+
const bundle = defineBaerlySubcommand({
|
|
221
|
+
name: "doctor",
|
|
222
|
+
meta: { description: "Walk the deploy invariants and report findings. Dispatches by baerly.config.ts:target." },
|
|
223
|
+
args: DOCTOR_ARGS,
|
|
224
|
+
handler: async (args) => {
|
|
225
|
+
if (args.bucket !== void 0) {
|
|
226
|
+
const { storage, keyPrefix, gcs } = await parseBucketUri(args.bucket);
|
|
227
|
+
if (gcs !== void 0) {
|
|
228
|
+
const report = await doctorCas(storage, keyPrefix, { staleEtag: "1" });
|
|
229
|
+
const listReport = await doctorListEncoding(storage, keyPrefix);
|
|
230
|
+
const gcsReport = await doctorGcsConfig(gcs);
|
|
231
|
+
const merged = mergeReports([
|
|
232
|
+
report,
|
|
233
|
+
listReport,
|
|
234
|
+
gcsReport
|
|
235
|
+
]);
|
|
236
|
+
renderReport({
|
|
237
|
+
kind: "bucket",
|
|
238
|
+
value: args.bucket
|
|
239
|
+
}, merged);
|
|
240
|
+
return merged.status === "error" ? 2 : 0;
|
|
241
|
+
}
|
|
242
|
+
const report = mergeReports([await doctorCas(storage, keyPrefix), await doctorListEncoding(storage, keyPrefix)]);
|
|
243
|
+
renderReport({
|
|
244
|
+
kind: "bucket",
|
|
245
|
+
value: args.bucket
|
|
246
|
+
}, report);
|
|
247
|
+
return report.status === "error" ? 2 : 0;
|
|
248
|
+
}
|
|
249
|
+
const config = await loadAppConfig();
|
|
250
|
+
const target = args.target ?? config.target;
|
|
251
|
+
if (target === "cloudflare") {
|
|
252
|
+
const report = await doctorCloudflare(config, {
|
|
253
|
+
runner: defaultRunner(),
|
|
254
|
+
...args.fix === true && { fix: true }
|
|
255
|
+
});
|
|
256
|
+
renderReport({
|
|
257
|
+
kind: "target",
|
|
258
|
+
value: target
|
|
259
|
+
}, report);
|
|
260
|
+
return report.status === "error" ? 2 : 0;
|
|
261
|
+
}
|
|
262
|
+
throw new BaerlyError("InvalidConfig", `baerly doctor: target ${JSON.stringify(target)} has no doctor backend. (Node variants self-validate at scaffold time; the example IS the contract.)`);
|
|
263
|
+
}
|
|
264
|
+
});
|
|
265
|
+
/** citty `defineCommand` block for `baerly doctor`. */
|
|
266
|
+
const doctor = bundle.cmd;
|
|
267
|
+
bundle.run;
|
|
268
|
+
export { doctor };
|
|
269
|
+
|
|
270
|
+
//# sourceMappingURL=doctor-BA0i-YAN.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"doctor-BA0i-YAN.js","names":[],"sources":["../packages/cli/src/doctor/list-encoding.ts","../packages/cli/src/doctor.ts"],"sourcesContent":["/**\n * `baerly doctor --bucket <uri>` — live LIST key-encoding probe.\n *\n * App, tenant, and collection names may hold `%`, spaces, `+`, and\n * XML-special characters, and they are interpolated raw into object keys.\n * The S3 and GCS adapters list with `encoding-type=url` and decode each\n * returned key once; GC then deletes the keys LIST hands back. A backend\n * or gateway that ignores `encoding-type=url`, encodes twice, or encodes\n * `+` / spaces differently hands back keys that are not the ones written,\n * so this probe writes keys with those characters, lists them, and\n * compares the listed key byte-for-byte against what was put.\n *\n * Bounded: two puts, two single-prefix lists (at most\n * {@link LIST_ENTRY_LIMIT} entries each), and two deletes, all under a\n * fresh `__baerly_list_probe__/<uuid>/` prefix. Cleanup runs in `finally`\n * and a failed delete is reported, not swallowed.\n */\n\nimport { BaerlyError, type Storage, uuid } from \"@baerly/protocol\";\nimport { type DoctorFinding, type DoctorReport, rollupStatus } from \"./cloudflare.ts\";\n\n/**\n * The two sentinel key leaves. `escapes` carries already-valid percent\n * escapes (`%2F`, `%25`), whitespace, `+`, the five XML-special\n * characters, and a non-ASCII letter; it decodes cleanly, so a key that\n * was decoded one time too many is recognisable. `bare-percent` carries\n * a `%` that starts no valid escape, which a raw (unencoded) LIST\n * response cannot decode at all.\n */\nexport const LIST_PROBE_SENTINELS = [\n { name: \"escapes\", leaf: `e/a%2Fb %25 c+d & < > \" ' é` },\n { name: \"bare-percent\", leaf: \"p/100% bare\" },\n] as const;\n\n/** Per-list entry cap. Only one object lives under each listed prefix. */\nexport const LIST_ENTRY_LIMIT = 8;\n\nconst utf8 = new TextEncoder();\n\nconst LIST_FIX =\n \"Point baerly at a store whose ListObjects honours `encoding-type=url` and returns each key \" +\n \"exactly as written (AWS S3, Cloudflare R2, MinIO, and native GCS do). A gateway or proxy \" +\n \"that rewrites list responses can break this; names holding `%`, spaces, `+`, or `&<>\\\"'` \" +\n \"would otherwise be mis-listed and mishandled by maintenance.\";\n\n/** The adapters' decode step: `+` → space, then one percent-decode. */\nconst decodeOnce = (s: string): string | undefined => {\n try {\n return decodeURIComponent(s.replace(/\\+/g, \" \"));\n } catch {\n return undefined;\n }\n};\n\nconst xmlEscape = (s: string): string =>\n s\n .replace(/&/g, \"&\")\n .replace(/</g, \"<\")\n .replace(/>/g, \">\")\n .replace(/\"/g, \""\")\n .replace(/'/g, \"'\");\n\nconst firstByteDiff = (a: Uint8Array, b: Uint8Array): number => {\n const n = Math.min(a.length, b.length);\n for (let i = 0; i < n; i += 1) {\n if (a[i] !== b[i]) {\n return i;\n }\n }\n return n;\n};\n\nconst sameBytes = (a: string, b: string): boolean => {\n const x = utf8.encode(a);\n const y = utf8.encode(b);\n return x.length === y.length && firstByteDiff(x, y) === x.length;\n};\n\n/**\n * Known ways a listed key goes wrong, checked in order. Each derives the\n * expected-wrong listing from the put key and names the likely cause.\n */\nconst DIAGNOSES: ReadonlyArray<{\n readonly kind: string;\n readonly matches: (listed: string, put: string) => boolean;\n readonly cause: string;\n}> = [\n {\n kind: \"not decoded\",\n matches: (listed, put) => decodeOnce(listed) === put,\n cause:\n \"it still carries one layer of URL encoding: the backend encodes list keys twice, or the client does not decode `encoding-type=url` responses\",\n },\n {\n kind: \"double decoded\",\n matches: (listed, put) => {\n const once = decodeOnce(put);\n return once !== undefined && once !== put && listed === once;\n },\n cause:\n \"it was decoded one time too many: the backend ignores `encoding-type=url` and returns raw keys, or the client decodes twice\",\n },\n {\n kind: \"`+` not decoded to space\",\n matches: (listed, put) => put.includes(\" \") && listed === put.replaceAll(\" \", \"+\"),\n cause:\n \"spaces came back as `+`: the encoded form uses `+` for space and the client percent-decodes without mapping `+` back\",\n },\n {\n kind: \"literal `+` decoded to space\",\n matches: (listed, put) => put.includes(\"+\") && listed === put.replaceAll(\"+\", \" \"),\n cause:\n \"a literal `+` came back as a space: the backend does not percent-encode `+` in list keys\",\n },\n {\n kind: \"XML entities not unescaped\",\n matches: (listed, put) => listed === xmlEscape(put),\n cause:\n \"XML entities such as `&` were left in the key: the list response was not XML-unescaped\",\n },\n];\n\nconst describeMismatch = (listed: string, put: string, show: (k: string) => string): string => {\n const diagnosis = DIAGNOSES.find((d) => d.matches(listed, put));\n const got = `expected ${show(put)}, got ${show(listed)}`;\n if (diagnosis !== undefined) {\n return `${diagnosis.kind} — ${got}; ${diagnosis.cause}.`;\n }\n const offset = firstByteDiff(utf8.encode(put), utf8.encode(listed));\n return `wrong decoding — ${got}; first differing UTF-8 byte at offset ${offset}.`;\n};\n\nconst errorText = (error: unknown): string =>\n error instanceof Error ? error.message : String(error);\n\n/**\n * Write each sentinel, list it back under its own prefix, compare the\n * listed key byte-for-byte, and delete it. Status is `error` iff a\n * sentinel was not listed exactly as written; a failed cleanup delete is\n * a `warning` naming the leaked key.\n */\nexport const doctorListEncoding = async (\n storage: Storage,\n keyPrefix: string,\n): Promise<DoctorReport> => {\n const root = `${keyPrefix}__baerly_list_probe__/${uuid()}/`;\n const show = (k: string): string => JSON.stringify(k.startsWith(root) ? k.slice(root.length) : k);\n const findings: DoctorFinding[] = [];\n const written: string[] = [];\n try {\n for (const sentinel of LIST_PROBE_SENTINELS) {\n const check = `list-encoding-${sentinel.name}`;\n const key = `${root}${sentinel.leaf}`;\n const fail = (message: string): void => {\n findings.push({ severity: \"error\", check, message, fix: LIST_FIX });\n };\n try {\n written.push(key);\n await storage.put(key, utf8.encode(sentinel.name));\n } catch (error) {\n fail(`PUT of the ${show(key)} sentinel failed: ${errorText(error)}`);\n continue;\n }\n const listed: string[] = [];\n try {\n const prefix = `${root}${sentinel.leaf.slice(0, sentinel.leaf.indexOf(\"/\") + 1)}`;\n for await (const entry of storage.list(prefix, { maxKeys: LIST_ENTRY_LIMIT })) {\n listed.push(entry.key);\n if (listed.length >= LIST_ENTRY_LIMIT) {\n break;\n }\n }\n } catch (error) {\n const hint =\n error instanceof BaerlyError && error.code === \"InvalidResponse\"\n ? \" The listed key is not valid URL encoding: the backend likely ignores `encoding-type=url` and returns raw keys.\"\n : \"\";\n fail(`LIST after writing ${show(key)} failed: ${errorText(error)}.${hint}`);\n continue;\n }\n if (listed.some((k) => sameBytes(k, key))) {\n findings.push({\n severity: \"ok\",\n check,\n message: `LIST returned the ${show(key)} sentinel byte-for-byte as written.`,\n });\n } else if (listed.length === 0) {\n fail(\n `LIST did not return the ${show(key)} sentinel just written (no keys under its prefix).`,\n );\n } else {\n fail(`LIST mis-encoded the sentinel key: ${describeMismatch(listed[0]!, key, show)}`);\n }\n }\n } finally {\n for (const key of written) {\n try {\n await storage.delete(key);\n } catch (error) {\n findings.push({\n severity: \"warning\",\n check: \"list-encoding-cleanup\",\n message: `Could not delete probe sentinel ${JSON.stringify(key)}: ${errorText(error)}`,\n fix: \"Delete that object by hand; it is not read by baerly.\",\n });\n }\n }\n }\n return { findings, status: rollupStatus(findings) };\n};\n","/**\n * `baerly doctor` — citty dispatcher for deploy-invariant checks.\n *\n * Two modes:\n * - `--bucket <uri>` — connect to a live bucket and probe its CAS\n * support (the protocol's load-bearing backend prerequisite). This\n * mode WRITES + deletes throwaway sentinels; see\n * {@link doctorCas}. Then runs {@link doctorListEncoding}, which\n * writes, lists, and deletes two sentinels whose keys hold `%`,\n * spaces, `+`, and XML-special characters, and checks LIST returns\n * them byte-for-byte. Independent of `baerly.config.ts` / `--target`.\n * For `gcs://` URIs, also runs the GCS-specific bucket-config checks\n * in {@link doctorGcsConfig} (an active Object Versioning probe plus\n * a static soft-delete advisory) and merges their findings into the\n * same report.\n * - otherwise — reads `baerly.config.ts:target` and routes to\n * {@link doctorCloudflare} (read-only deploy-invariant checks). The\n * Node target self-validates at scaffold time — the example IS the\n * contract — so it has no doctor backend.\n *\n * Consistency checks and writes/min health are separate verbs:\n * - `baerly admin fsck` — snapshot hash and log-range consistency.\n * - `baerly admin usage` — writes/min M-size graduation.\n *\n * Renders the returned {@link DoctorReport} into either a\n * stdout checklist (text mode) or a JSON envelope (`--json`\n * mode).\n *\n * Exit-code contract (mirrors `baerly deploy`):\n * - 0 success — report status is `ok` or `warning`.\n * - 1 user error (InvalidConfig, unknown target, missing config).\n * - 2 storage / external error.\n * - 3 protocol invariant.\n *\n * A `warning` status returns exit 0 (the user can deploy; we just\n * flagged a maintenance / coherence issue). An `error` status\n * returns exit 2 unless the underlying cause was an InvalidConfig\n * (which already returned 1 via a thrown BaerlyError).\n */\n\nimport { type ArgsDef } from \"citty\";\nimport { BaerlyError } from \"@baerly/protocol\";\nimport { parseBucketUri } from \"./bucket-uri.ts\";\nimport { loadAppConfig } from \"./config.ts\";\nimport { doctorCas } from \"./doctor/cas.ts\";\nimport { doctorCloudflare, mergeReports, type DoctorReport } from \"./doctor/cloudflare.ts\";\nimport { doctorGcsConfig, GCS_STALE_GENERATION_PROBE_VALUE } from \"./doctor/gcs.ts\";\nimport { doctorListEncoding } from \"./doctor/list-encoding.ts\";\nimport { defaultRunner } from \"./runner.ts\";\nimport { color, isJsonMode } from \"./output.ts\";\nimport { defineBaerlySubcommand, JSON_ARG } from \"./subcommand.ts\";\n\nconst DOCTOR_ARGS = {\n target: {\n type: \"string\",\n description:\n 'Override `baerly.config.ts:target`. Only \"cloudflare\" supported (Node variants self-validate at scaffold time).',\n valueHint: \"cloudflare\",\n },\n bucket: {\n type: \"string\",\n description:\n \"Live-probe a bucket's CAS support (verifies If-Match / If-None-Match are honoured) and LIST key encoding (listed keys must match written keys byte-for-byte); writes + deletes throwaway sentinels. s3://, gcs://, file:///, or memory:// URI. For gcs://, also runs GCS-specific bucket-config checks (Object Versioning probe + soft-delete advisory). Independent of --target.\",\n valueHint: \"s3://bucket/prefix | gcs://bucket\",\n },\n fix: {\n type: \"boolean\",\n description:\n \"Remediate auto-fixable findings (R2 bucket creation; secret prompts stay manual).\",\n },\n json: JSON_ARG,\n} as const satisfies ArgsDef;\n\nconst SEVERITY_GLYPH: Record<string, string> = {\n ok: \"✓\",\n info: \"•\",\n warning: \"⚠\",\n error: \"✗\",\n};\n\nconst colorize = (severity: string, glyph: string): string => {\n if (severity === \"error\") {\n return color.red(glyph);\n }\n if (severity === \"warning\") {\n return color.yellow(glyph);\n }\n if (severity === \"info\") {\n return color.dim(glyph);\n }\n return glyph;\n};\n\nconst renderReport = (\n label: { kind: \"target\" | \"bucket\"; value: string },\n report: DoctorReport,\n): void => {\n if (isJsonMode()) {\n process.stdout.write(\n `${JSON.stringify({ result: { command: \"doctor\", [label.kind]: label.value, ...report } })}\\n`,\n );\n return;\n }\n process.stdout.write(`baerly doctor --${label.kind}=${label.value}\\n\\n`);\n let okCount = 0;\n let warningCount = 0;\n let errorCount = 0;\n for (const f of report.findings) {\n const glyph = SEVERITY_GLYPH[f.severity] ?? \"•\";\n process.stdout.write(` ${colorize(f.severity, glyph)} ${f.message}\\n`);\n if (f.fix !== undefined) {\n process.stdout.write(` fix: ${f.fix}\\n`);\n }\n if (f.severity === \"ok\") {\n okCount += 1;\n } else if (f.severity === \"warning\") {\n warningCount += 1;\n } else if (f.severity === \"error\") {\n errorCount += 1;\n }\n }\n process.stdout.write(\n `\\nStatus: ${errorCount} error${errorCount === 1 ? \"\" : \"s\"}, ${warningCount} warning${warningCount === 1 ? \"\" : \"s\"}, ${okCount} ok.\\n`,\n );\n};\n\nconst bundle = defineBaerlySubcommand({\n name: \"doctor\",\n meta: {\n description:\n \"Walk the deploy invariants and report findings. Dispatches by baerly.config.ts:target.\",\n },\n args: DOCTOR_ARGS,\n handler: async (args) => {\n // --bucket is a standalone live-probe mode: it connects to a real\n // bucket and checks CAS, independent of baerly.config.ts / --target.\n if (args.bucket !== undefined) {\n const { storage, keyPrefix, gcs } = await parseBucketUri(args.bucket);\n if (gcs !== undefined) {\n // Native GCS's generation-based preconditions reject the CAS\n // probe's default S3/R2-shaped stale-etag sentinel as malformed\n // (400) rather than as a conflict (412) — override with a\n // well-formed-but-stale generation. See doctor/gcs.ts.\n const report = await doctorCas(storage, keyPrefix, {\n staleEtag: GCS_STALE_GENERATION_PROBE_VALUE,\n });\n const listReport = await doctorListEncoding(storage, keyPrefix);\n const gcsReport = await doctorGcsConfig(gcs);\n const merged = mergeReports([report, listReport, gcsReport]);\n renderReport({ kind: \"bucket\", value: args.bucket }, merged);\n return merged.status === \"error\" ? 2 : 0;\n }\n const report = mergeReports([\n await doctorCas(storage, keyPrefix),\n await doctorListEncoding(storage, keyPrefix),\n ]);\n renderReport({ kind: \"bucket\", value: args.bucket }, report);\n return report.status === \"error\" ? 2 : 0;\n }\n const config = await loadAppConfig();\n const target = args.target ?? config.target;\n if (target === \"cloudflare\") {\n const report = await doctorCloudflare(config, {\n runner: defaultRunner(),\n ...(args.fix === true && { fix: true }),\n });\n renderReport({ kind: \"target\", value: target }, report);\n return report.status === \"error\" ? 2 : 0;\n }\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly doctor: target ${JSON.stringify(target)} has no doctor backend. ` +\n `(Node variants self-validate at scaffold time; the example IS the contract.)`,\n );\n },\n});\n\n/** citty `defineCommand` block for `baerly doctor`. */\nexport const doctor = bundle.cmd;\n\n/**\n * Programmatic entry used by tests. Bypasses citty's `run` wrapper\n * (which would call `process.exit` and kill vitest) and returns the\n * integer exit code directly.\n */\nexport const runDoctor = bundle.run;\n"],"mappings":"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"}
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import { a as isJsonMode, r as emitSuccess, s as BaerlyError } from "./baerly.js";
|
|
2
|
+
import { n as loadMaterialisedView } from "./plan-BvQbaNMe.js";
|
|
3
|
+
import { n as parseBucketUri } from "./config-DEzInG6M.js";
|
|
4
|
+
import { a as illFormedNames, i as LEGACY_NAME_MIGRATION, n as LEGACY_ILL_FORMED_ID_MIGRATION, o as legacyIdReport, r as LEGACY_ILL_FORMED_NAME_MIGRATION, s as nonNfcNames, t as LEGACY_ID_MIGRATION } from "./legacy-names-DgZBtgOh.js";
|
|
5
|
+
import { a as TENANT_ARG, c as defineBaerlySubcommand, i as JSON_ARG, n as BUCKET_ARG, o as assertCollectionArg, r as COLLECTION_ARG, t as APP_ARG } from "./subcommand-BLoF66dG.js";
|
|
6
|
+
import "node:stream";
|
|
7
|
+
// src/admin/dump.ts
|
|
8
|
+
const DUMP_ARGS = {
|
|
9
|
+
bucket: BUCKET_ARG,
|
|
10
|
+
app: APP_ARG,
|
|
11
|
+
tenant: TENANT_ARG,
|
|
12
|
+
collection: COLLECTION_ARG,
|
|
13
|
+
"recover-legacy-names": {
|
|
14
|
+
type: "boolean",
|
|
15
|
+
description: "Recover one exact collection spelling from a mixed legacy log; requires a matching snapshot and cannot recover previously discarded data."
|
|
16
|
+
},
|
|
17
|
+
json: JSON_ARG
|
|
18
|
+
};
|
|
19
|
+
/**
|
|
20
|
+
* Recursive byte-stable JSON stringifier. Object keys at every nesting
|
|
21
|
+
* level are sorted ASCII-lex; array element order is preserved as-is.
|
|
22
|
+
* Numbers must be finite (protocol forbids NaN / Infinity in bodies).
|
|
23
|
+
*/
|
|
24
|
+
const canonicalStringify = (value) => {
|
|
25
|
+
if (typeof value === "number") {
|
|
26
|
+
if (!Number.isFinite(value)) throw new BaerlyError("InvalidResponse", `baerly admin dump: non-finite number in row body (${String(value)}); protocol violation`);
|
|
27
|
+
return JSON.stringify(value);
|
|
28
|
+
}
|
|
29
|
+
if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
|
|
30
|
+
if (value === null) return "null";
|
|
31
|
+
if (Array.isArray(value)) return `[${value.map((v) => canonicalStringify(v)).join(",")}]`;
|
|
32
|
+
if (typeof value === "object") {
|
|
33
|
+
const keys = Object.keys(value).toSorted();
|
|
34
|
+
const parts = [];
|
|
35
|
+
for (const k of keys) {
|
|
36
|
+
const v = value[k];
|
|
37
|
+
if (v === void 0) continue;
|
|
38
|
+
parts.push(`${JSON.stringify(k)}:${canonicalStringify(v)}`);
|
|
39
|
+
}
|
|
40
|
+
return `{${parts.join(",")}}`;
|
|
41
|
+
}
|
|
42
|
+
throw new BaerlyError("InvalidResponse", `baerly admin dump: unsupported value type ${typeof value}`);
|
|
43
|
+
};
|
|
44
|
+
/**
|
|
45
|
+
* Drain rows to the supplied writable, applying back-pressure on every
|
|
46
|
+
* line. We don't `end()` the stream — the caller owns its lifecycle
|
|
47
|
+
* (`process.stdout` shouldn't be closed; a test-supplied
|
|
48
|
+
* `createWriteStream` flushes on its own `end()`).
|
|
49
|
+
*/
|
|
50
|
+
const writeToSink = async (sink, rows) => {
|
|
51
|
+
const ids = [...rows.keys()].toSorted();
|
|
52
|
+
let count = 0;
|
|
53
|
+
for (const id of ids) {
|
|
54
|
+
const body = rows.get(id);
|
|
55
|
+
if (body === void 0) continue;
|
|
56
|
+
const row = {
|
|
57
|
+
...body,
|
|
58
|
+
_id: id
|
|
59
|
+
};
|
|
60
|
+
const line = `${canonicalStringify(row)}\n`;
|
|
61
|
+
if (!sink.write(line)) await new Promise((resolve) => sink.once("drain", resolve));
|
|
62
|
+
count++;
|
|
63
|
+
}
|
|
64
|
+
return count;
|
|
65
|
+
};
|
|
66
|
+
/** Text-mode migration warnings on stderr; stdout carries the NDJSON. */
|
|
67
|
+
const warnLegacy = (legacy) => {
|
|
68
|
+
const lines = [];
|
|
69
|
+
if (legacy.non_nfc_names.length > 0) lines.push(`non-NFC ${legacy.non_nfc_names.join(", ")} name: ${LEGACY_NAME_MIGRATION}`);
|
|
70
|
+
if (legacy.ill_formed_names.length > 0) lines.push(`${legacy.ill_formed_names.join(", ")} name with an unpaired UTF-16 surrogate: ${LEGACY_ILL_FORMED_NAME_MIGRATION}`);
|
|
71
|
+
if (legacy.non_nfc_ids.length > 0) lines.push(`${legacy.non_nfc_ids.length} non-NFC _id(s) ${JSON.stringify(legacy.non_nfc_ids)}: ${LEGACY_ID_MIGRATION}`);
|
|
72
|
+
if (legacy.ill_formed_ids.length > 0) lines.push(`${legacy.ill_formed_ids.length} _id(s) with an unpaired UTF-16 surrogate ${JSON.stringify(legacy.ill_formed_ids)}: ${LEGACY_ILL_FORMED_ID_MIGRATION}`);
|
|
73
|
+
for (const group of legacy.twin_ids) lines.push(`canonically-equivalent twin _ids ${JSON.stringify(group)} have one NFC spelling, which the SDK accepts for only one row: ${LEGACY_ID_MIGRATION}`);
|
|
74
|
+
for (const line of lines) process.stderr.write(`baerly admin dump: warning: ${line}\n`);
|
|
75
|
+
};
|
|
76
|
+
const bundle = defineBaerlySubcommand({
|
|
77
|
+
name: "admin.dump",
|
|
78
|
+
meta: { description: "Canonical NDJSON of the materialised view of one collection." },
|
|
79
|
+
args: DUMP_ARGS,
|
|
80
|
+
handler: async (args, ctx) => {
|
|
81
|
+
const bucket = await parseBucketUri(args.bucket);
|
|
82
|
+
const { app, tenant } = await ctx.resolveAppTenant({
|
|
83
|
+
app: args.app,
|
|
84
|
+
tenant: args.tenant
|
|
85
|
+
});
|
|
86
|
+
assertCollectionArg(args.collection, "baerly admin dump");
|
|
87
|
+
const currentJsonKey = `${bucket.keyPrefix}app/${app}/tenant/${tenant}/manifests/${args.collection}/current.json`;
|
|
88
|
+
const view = await loadMaterialisedView({
|
|
89
|
+
storage: bucket.storage,
|
|
90
|
+
currentJsonKey,
|
|
91
|
+
collection: args.collection,
|
|
92
|
+
recoverLegacyNames: args["recover-legacy-names"] === true
|
|
93
|
+
});
|
|
94
|
+
if (view === null) throw new BaerlyError("InvalidConfig", `baerly admin dump: current.json not found at ${currentJsonKey}`);
|
|
95
|
+
const sink = ctx.streams?.stdout ?? process.stdout;
|
|
96
|
+
const count = await writeToSink(sink, view);
|
|
97
|
+
const legacy = {
|
|
98
|
+
non_nfc_names: nonNfcNames({
|
|
99
|
+
app,
|
|
100
|
+
tenant,
|
|
101
|
+
collection: args.collection
|
|
102
|
+
}),
|
|
103
|
+
ill_formed_names: illFormedNames({
|
|
104
|
+
app,
|
|
105
|
+
tenant,
|
|
106
|
+
collection: args.collection
|
|
107
|
+
}),
|
|
108
|
+
...legacyIdReport(view.keys())
|
|
109
|
+
};
|
|
110
|
+
if (!isJsonMode()) {
|
|
111
|
+
warnLegacy(legacy);
|
|
112
|
+
if (args["recover-legacy-names"] === true) process.stderr.write("baerly admin dump: warning: recovery selects only the exact stored collection spelling; historical completeness is not guaranteed. Rows discarded by earlier compaction cannot be recovered. Keep a copy of the source bucket.\n");
|
|
113
|
+
}
|
|
114
|
+
emitSuccess({
|
|
115
|
+
command: "admin.dump",
|
|
116
|
+
status: "ok",
|
|
117
|
+
collection: args.collection,
|
|
118
|
+
dumped: count,
|
|
119
|
+
legacy,
|
|
120
|
+
...args["recover-legacy-names"] === true && { recovery: {
|
|
121
|
+
collection_match: "exact",
|
|
122
|
+
historical_completeness: "not_guaranteed"
|
|
123
|
+
} }
|
|
124
|
+
});
|
|
125
|
+
return 0;
|
|
126
|
+
}
|
|
127
|
+
});
|
|
128
|
+
/** citty `defineCommand` block for `baerly admin dump`. */
|
|
129
|
+
const dumpCmd = bundle.cmd;
|
|
130
|
+
bundle.run;
|
|
131
|
+
export { dumpCmd };
|
|
132
|
+
|
|
133
|
+
//# sourceMappingURL=dump-D1vX8ozg.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"dump-D1vX8ozg.js","names":[],"sources":["../packages/cli/src/admin/dump.ts"],"sourcesContent":["/**\n * `baerly admin dump` — canonical NDJSON of the materialised view.\n *\n * Writes one row per line to stdout, in a strict byte-stable shape so\n * two semantically-equal collections produce byte-equal output. Tests\n * and other programmatic callers can divert the NDJSON output to a\n * file or buffer by passing `{ streams: { stdout } }` to {@link runDump}.\n *\n * Canonical NDJSON dump format:\n *\n * 1. Each row is `{\"_id\":\"<id>\",…}` (no spaces).\n * 2. Row order = ASCII-lex sort on `_id`.\n * 3. Within each row, object keys are sorted ASCII-lex\n * RECURSIVELY — every nested object's keys are sorted too.\n * 4. Numbers as their canonical `JSON.stringify` output.\n * Finite-only (the protocol forbids NaN / Infinity).\n * 5. Strings as `JSON.stringify` output (escape sequences\n * identical to `\\uXXXX` for control codes).\n * 6. One trailing newline at EOF (`\\n`, not `\\r\\n`).\n * 7. No BOM.\n *\n * The round-trip ticket (73) gates byte-equality on this format. A\n * change to any of (1)–(7) is a BREAKING change requiring a\n * round-trip schema-version bump.\n *\n * Empty collection → empty file (no trailing newline) — disambiguates\n * \"zero rows\" from \"one row with empty body\".\n *\n * Args:\n * --bucket Required. Bucket URI.\n * --app Required (or via baerly.config.ts).\n * --tenant Required (or via baerly.config.ts).\n * --collection Required. Collection name.\n * --recover-legacy-names Select only this exact stored collection\n * spelling in a mixed legacy log. Snapshot validation\n * remains strict; historical completeness is not guaranteed.\n * --json JSON envelope (on stdout). Its `legacy` field is the\n * migration preflight: `non_nfc_names` and\n * `ill_formed_names` (roles), `non_nfc_ids`,\n * `ill_formed_ids`, and `twin_ids` (groups of\n * canonically-equivalent `_id`s). Ill-formed means an\n * unpaired UTF-16 surrogate. Text mode prints the same as\n * warnings on stderr. Every row is exported either way. Programmatic callers can\n * divert the NDJSON body to a separate writable via the\n * `streams.stdout` option on {@link runDump}.\n *\n * Exit codes:\n * 0 — dump completed.\n * 1 — InvalidConfig (bad bucket URI, missing args).\n * 2 — Storage / Network / Internal protocol violation.\n * 3 — Protocol invariant / conflict (WriteConflict / AlreadyExists /\n * Internal / InvalidResponse / AmbiguousCommit).\n */\n\nimport { type Writable } from \"node:stream\";\nimport { type ArgsDef } from \"citty\";\nimport { BaerlyError, type DocumentValue, type DocumentData } from \"@baerly/protocol\";\nimport { loadMaterialisedView } from \"../export/index.ts\";\nimport { parseBucketUri } from \"../bucket-uri.ts\";\nimport {\n LEGACY_ID_MIGRATION,\n LEGACY_ILL_FORMED_ID_MIGRATION,\n LEGACY_ILL_FORMED_NAME_MIGRATION,\n LEGACY_NAME_MIGRATION,\n illFormedNames,\n type LegacyIdReport,\n legacyIdReport,\n type NameRole,\n nonNfcNames,\n} from \"../legacy-names.ts\";\nimport { emitSuccess, isJsonMode } from \"../output.ts\";\nimport {\n APP_ARG,\n assertCollectionArg,\n BUCKET_ARG,\n COLLECTION_ARG,\n defineBaerlySubcommand,\n JSON_ARG,\n TENANT_ARG,\n} from \"../subcommand.ts\";\n\nconst DUMP_ARGS = {\n bucket: BUCKET_ARG,\n app: APP_ARG,\n tenant: TENANT_ARG,\n collection: COLLECTION_ARG,\n \"recover-legacy-names\": {\n type: \"boolean\",\n description:\n \"Recover one exact collection spelling from a mixed legacy log; requires a matching snapshot and cannot recover previously discarded data.\",\n },\n json: JSON_ARG,\n} as const satisfies ArgsDef;\n\n/**\n * Recursive byte-stable JSON stringifier. Object keys at every nesting\n * level are sorted ASCII-lex; array element order is preserved as-is.\n * Numbers must be finite (protocol forbids NaN / Infinity in bodies).\n */\nexport const canonicalStringify = (value: DocumentValue): string => {\n if (typeof value === \"number\") {\n if (!Number.isFinite(value)) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `baerly admin dump: non-finite number in row body (${String(value)}); protocol violation`,\n );\n }\n return JSON.stringify(value);\n }\n if (typeof value === \"string\" || typeof value === \"boolean\") {\n return JSON.stringify(value);\n }\n if (value === null) {\n // DocumentValue excludes null at the type level, but `unknown` may\n // sneak in via the snapshot fold — be defensive.\n return \"null\";\n }\n if (Array.isArray(value)) {\n const parts = value.map((v) => canonicalStringify(v));\n return `[${parts.join(\",\")}]`;\n }\n if (typeof value === \"object\") {\n const keys = Object.keys(value).toSorted();\n const parts: string[] = [];\n for (const k of keys) {\n const v = (value as Record<string, DocumentValue>)[k];\n if (v === undefined) {\n continue;\n }\n parts.push(`${JSON.stringify(k)}:${canonicalStringify(v)}`);\n }\n return `{${parts.join(\",\")}}`;\n }\n throw new BaerlyError(\n \"InvalidResponse\",\n `baerly admin dump: unsupported value type ${typeof value}`,\n );\n};\n\n/**\n * Drain rows to the supplied writable, applying back-pressure on every\n * line. We don't `end()` the stream — the caller owns its lifecycle\n * (`process.stdout` shouldn't be closed; a test-supplied\n * `createWriteStream` flushes on its own `end()`).\n */\nconst writeToSink = async (\n sink: Writable,\n rows: ReadonlyMap<string, DocumentData>,\n): Promise<number> => {\n const ids = [...rows.keys()].toSorted();\n let count = 0;\n for (const id of ids) {\n const body = rows.get(id);\n if (body === undefined) {\n continue;\n }\n // Merge `_id` into the body so the row literal carries it. The\n // map key is authoritative; if a stale `_id` field disagrees, we\n // overwrite it.\n const row: DocumentData = { ...body, _id: id };\n const line = `${canonicalStringify(row)}\\n`;\n if (!sink.write(line)) {\n await new Promise<void>((resolve) => sink.once(\"drain\", resolve));\n }\n count++;\n }\n return count;\n};\n\n/** Text-mode migration warnings on stderr; stdout carries the NDJSON. */\nconst warnLegacy = (\n legacy: LegacyIdReport & {\n non_nfc_names: readonly NameRole[];\n ill_formed_names: readonly NameRole[];\n },\n): void => {\n const lines: string[] = [];\n if (legacy.non_nfc_names.length > 0) {\n lines.push(`non-NFC ${legacy.non_nfc_names.join(\", \")} name: ${LEGACY_NAME_MIGRATION}`);\n }\n if (legacy.ill_formed_names.length > 0) {\n lines.push(\n `${legacy.ill_formed_names.join(\", \")} name with an unpaired UTF-16 surrogate: ${LEGACY_ILL_FORMED_NAME_MIGRATION}`,\n );\n }\n if (legacy.non_nfc_ids.length > 0) {\n lines.push(\n `${legacy.non_nfc_ids.length} non-NFC _id(s) ${JSON.stringify(legacy.non_nfc_ids)}: ${LEGACY_ID_MIGRATION}`,\n );\n }\n if (legacy.ill_formed_ids.length > 0) {\n lines.push(\n `${legacy.ill_formed_ids.length} _id(s) with an unpaired UTF-16 surrogate ${JSON.stringify(legacy.ill_formed_ids)}: ${LEGACY_ILL_FORMED_ID_MIGRATION}`,\n );\n }\n for (const group of legacy.twin_ids) {\n lines.push(\n `canonically-equivalent twin _ids ${JSON.stringify(group)} have one NFC spelling, which the SDK accepts for only one row: ${LEGACY_ID_MIGRATION}`,\n );\n }\n for (const line of lines) {\n process.stderr.write(`baerly admin dump: warning: ${line}\\n`);\n }\n};\n\nconst bundle = defineBaerlySubcommand({\n name: \"admin.dump\",\n meta: {\n description: \"Canonical NDJSON of the materialised view of one collection.\",\n },\n args: DUMP_ARGS,\n handler: async (args, ctx) => {\n const bucket = await parseBucketUri(args.bucket);\n const { app, tenant } = await ctx.resolveAppTenant({ app: args.app, tenant: args.tenant });\n assertCollectionArg(args.collection, \"baerly admin dump\");\n const currentJsonKey = `${bucket.keyPrefix}app/${app}/tenant/${tenant}/manifests/${args.collection}/current.json`;\n const view = await loadMaterialisedView({\n storage: bucket.storage,\n currentJsonKey,\n collection: args.collection,\n recoverLegacyNames: args[\"recover-legacy-names\"] === true,\n });\n if (view === null) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly admin dump: current.json not found at ${currentJsonKey}`,\n );\n }\n const sink: Writable = ctx.streams?.stdout ?? process.stdout;\n const count = await writeToSink(sink, view);\n // Migration preflight. Every row is still exported; this reports\n // what `admin restore` (which requires NFC, well-formed names and\n // `_id`s) needs changed first.\n const legacy = {\n non_nfc_names: nonNfcNames({ app, tenant, collection: args.collection }),\n ill_formed_names: illFormedNames({ app, tenant, collection: args.collection }),\n ...legacyIdReport(view.keys()),\n };\n if (!isJsonMode()) {\n warnLegacy(legacy);\n if (args[\"recover-legacy-names\"] === true) {\n process.stderr.write(\n \"baerly admin dump: warning: recovery selects only the exact stored collection spelling; historical completeness is not guaranteed. Rows discarded by earlier compaction cannot be recovered. Keep a copy of the source bucket.\\n\",\n );\n }\n }\n emitSuccess({\n command: \"admin.dump\",\n status: \"ok\",\n collection: args.collection,\n dumped: count,\n legacy,\n ...(args[\"recover-legacy-names\"] === true && {\n recovery: { collection_match: \"exact\", historical_completeness: \"not_guaranteed\" },\n }),\n });\n return 0;\n },\n});\n\n/** citty `defineCommand` block for `baerly admin dump`. */\nexport const dumpCmd = bundle.cmd;\n\n/**\n * Programmatic entry used by tests. Bypasses citty's `run` wrapper\n * (which would call `process.exit` and kill vitest) and returns the\n * integer exit code directly.\n */\nexport const runDump = bundle.run;\n"],"mappings":"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"}
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
// packages/protocol/src/errors.ts
|
|
2
|
+
/**
|
|
3
|
+
* Runtime enumeration of every {@link BaerlyErrorCode}. The spec
|
|
4
|
+
* generator and the drift gate iterate this to assert the IR lists
|
|
5
|
+
* each code; the type guard in `spec/ir-schema.test.ts` fails tsc if
|
|
6
|
+
* this tuple and the union diverge. Keep order stable for deterministic
|
|
7
|
+
* artifact diffs. This is the canonical code list — do not re-list
|
|
8
|
+
* codes elsewhere (see RETRIABLE_CODES, the sibling retriable subset).
|
|
9
|
+
*/
|
|
10
|
+
const ERROR_CODES = [
|
|
11
|
+
"InvalidConfig",
|
|
12
|
+
"NetworkError",
|
|
13
|
+
"AccessDenied",
|
|
14
|
+
"InvalidResponse",
|
|
15
|
+
"Internal",
|
|
16
|
+
"SchemaError",
|
|
17
|
+
"WriteConflict",
|
|
18
|
+
"AlreadyExists",
|
|
19
|
+
"AmbiguousCommit",
|
|
20
|
+
"CapacityExceeded",
|
|
21
|
+
"MaintenancePending",
|
|
22
|
+
"Unauthorized",
|
|
23
|
+
"NotFound",
|
|
24
|
+
"PayloadTooLarge",
|
|
25
|
+
"UnsupportedMediaType",
|
|
26
|
+
"UnsatisfiablePredicate",
|
|
27
|
+
"CursorExpired",
|
|
28
|
+
"UseQueryAwaitedRecorder",
|
|
29
|
+
"UnexpectedWriteInQuery",
|
|
30
|
+
"MutationFailed"
|
|
31
|
+
];
|
|
32
|
+
/**
|
|
33
|
+
* Codes whose failure can clear on retry. `BaerlyError.retriable` is
|
|
34
|
+
* exactly membership in this set; there are no per-instance overrides.
|
|
35
|
+
*/
|
|
36
|
+
const RETRIABLE_CODES = /* @__PURE__ */ new Set([
|
|
37
|
+
"NetworkError",
|
|
38
|
+
"WriteConflict",
|
|
39
|
+
"MaintenancePending"
|
|
40
|
+
]);
|
|
41
|
+
/**
|
|
42
|
+
* True iff `value` is a code this build knows. Wire decoders use it to
|
|
43
|
+
* catch a code minted by a newer server before it reaches `code`, where
|
|
44
|
+
* an unknown string would defeat both exhaustive switches and
|
|
45
|
+
* {@link isRetriableCode}.
|
|
46
|
+
*/
|
|
47
|
+
const isBaerlyErrorCode = (value) => typeof value === "string" && ERROR_CODES.includes(value);
|
|
48
|
+
/**
|
|
49
|
+
* True iff `err` is a `WriteConflict`: a lost conditional write or CAS
|
|
50
|
+
* race. The one predicate every kernel catch site uses, so the code's
|
|
51
|
+
* meaning is tested in one place. Matches on `name` and `code` rather
|
|
52
|
+
* than `instanceof`, so an error from a second loaded copy of this module
|
|
53
|
+
* or another realm still classifies.
|
|
54
|
+
*/
|
|
55
|
+
const isWriteConflict = (err) => typeof err === "object" && err !== null && err.name === "BaerlyError" && err.code === "WriteConflict";
|
|
56
|
+
/** True iff this error code is retriable (membership in {@link RETRIABLE_CODES}). */
|
|
57
|
+
const isRetriableCode = (code) => RETRIABLE_CODES.has(code);
|
|
58
|
+
/**
|
|
59
|
+
* The single error class thrown by baerly-storage. Discriminate by `code`, not
|
|
60
|
+
* `instanceof`: the code string survives `JSON.stringify` round-trips
|
|
61
|
+
* across Worker / iframe / postMessage realm boundaries, where each
|
|
62
|
+
* realm has its own `BaerlyError` constructor identity. IDB-restored
|
|
63
|
+
* writes can replay across realms, so `instanceof` would spuriously
|
|
64
|
+
* fail on a structurally-identical error from another realm.
|
|
65
|
+
*
|
|
66
|
+
* @example
|
|
67
|
+
* ```ts
|
|
68
|
+
* try {
|
|
69
|
+
* await db.collection("tickets").insert({ _id: "t-1", title: "hi" });
|
|
70
|
+
* } catch (err) {
|
|
71
|
+
* if (!(err instanceof BaerlyError)) throw err;
|
|
72
|
+
* if (err.code === "AlreadyExists") {
|
|
73
|
+
* // t-1 is taken; retrying cannot succeed.
|
|
74
|
+
* } else if (err.code === "AmbiguousCommit") {
|
|
75
|
+
* // May have landed: re-read err._id before deciding.
|
|
76
|
+
* } else if (err.retriable) {
|
|
77
|
+
* // WriteConflict or NetworkError: retry with bounded backoff.
|
|
78
|
+
* } else {
|
|
79
|
+
* throw err;
|
|
80
|
+
* }
|
|
81
|
+
* }
|
|
82
|
+
* ```
|
|
83
|
+
*/
|
|
84
|
+
var BaerlyError = class extends Error {
|
|
85
|
+
code;
|
|
86
|
+
cause;
|
|
87
|
+
/**
|
|
88
|
+
* Structured field-path issues, set only when `code === "SchemaError"`.
|
|
89
|
+
* Each entry's `path` is a dotted-key list (e.g. `["assignee", "team"]`
|
|
90
|
+
* or `["items", 3, "qty"]`) that targets the offending field on the
|
|
91
|
+
* input document. `message` is the validator-emitted human string.
|
|
92
|
+
*
|
|
93
|
+
* The HTTP layer's `mapError` renders these into the 400 body via
|
|
94
|
+
* the existing `HttpErrorEnvelope`; older callers that don't know
|
|
95
|
+
* about `issues` see a plain message-only error and stay correct.
|
|
96
|
+
*/
|
|
97
|
+
issues;
|
|
98
|
+
/**
|
|
99
|
+
* The `_id` of the row whose commit outcome is unknown, set only when
|
|
100
|
+
* `code === "AmbiguousCommit"`. For an auto-ID insert it is the minted
|
|
101
|
+
* id, so the caller can re-read the row and retry with the same `_id`
|
|
102
|
+
* rather than mint a second document. A missing row does not prove the
|
|
103
|
+
* write failed. The HTTP layer carries it in `HttpErrorEnvelope`.
|
|
104
|
+
*/
|
|
105
|
+
_id;
|
|
106
|
+
/**
|
|
107
|
+
* Raw HTTP status, set only by the client-side wire decoder when
|
|
108
|
+
* inflating an `HttpErrorEnvelope` into this class. Server-side
|
|
109
|
+
* throws never set it (the HTTP layer's `mapError` derives the
|
|
110
|
+
* outbound status from `code`). Useful for diagnostics — e.g. to
|
|
111
|
+
* distinguish 404-as-"no such row" from 404-as-"route not found".
|
|
112
|
+
* Discriminate by `code` for behavior; reach for `status` only when
|
|
113
|
+
* you genuinely need the wire value.
|
|
114
|
+
*/
|
|
115
|
+
status;
|
|
116
|
+
/** Canonical corrective action; crosses the wire via `HttpErrorEnvelope.error.resolution`. */
|
|
117
|
+
resolution;
|
|
118
|
+
/** Suggested delay in seconds before retrying; set only for `MaintenancePending`. Crosses the wire via `HttpErrorEnvelope.error.retryAfter` and the `Retry-After` header. */
|
|
119
|
+
retryAfter;
|
|
120
|
+
/**
|
|
121
|
+
* `true` iff re-running the operation from its read step can succeed:
|
|
122
|
+
* `NetworkError` (retry with backoff) and `WriteConflict` (re-read, then
|
|
123
|
+
* write again). A `Collection` / `Query` verb re-reads on every call, so
|
|
124
|
+
* calling it again is the retry; a blind resend of the same conditional
|
|
125
|
+
* `Storage` put loses again. A pure function of `code`
|
|
126
|
+
* ({@link isRetriableCode}): every instance of a code gives the same
|
|
127
|
+
* answer. `AmbiguousCommit` is `false` because the write may have landed;
|
|
128
|
+
* reconcile by `_id` first.
|
|
129
|
+
*/
|
|
130
|
+
get retriable() {
|
|
131
|
+
return isRetriableCode(this.code);
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* `code` and `message` are positional; everything else goes in `options`,
|
|
135
|
+
* as with `new Error(message, { cause })`. Passing an `Error` (or any
|
|
136
|
+
* non-options value) as the third argument does not compile; the
|
|
137
|
+
* options object is where `cause` goes.
|
|
138
|
+
*
|
|
139
|
+
* @example
|
|
140
|
+
* ```ts
|
|
141
|
+
* throw new BaerlyError("NetworkError", "PUT failed", { cause: err });
|
|
142
|
+
* throw new BaerlyError("AmbiguousCommit", "commit outcome unknown", { _id: "t-1" });
|
|
143
|
+
* ```
|
|
144
|
+
*/
|
|
145
|
+
constructor(code, message, options) {
|
|
146
|
+
super(message);
|
|
147
|
+
this.name = "BaerlyError";
|
|
148
|
+
this.code = code;
|
|
149
|
+
this.cause = options?.cause;
|
|
150
|
+
const { issues, status, resolution, _id, retryAfter } = options ?? {};
|
|
151
|
+
if (issues !== void 0) this.issues = issues;
|
|
152
|
+
if (status !== void 0) this.status = status;
|
|
153
|
+
if (resolution !== void 0) this.resolution = resolution;
|
|
154
|
+
if (_id !== void 0) this._id = _id;
|
|
155
|
+
if (retryAfter !== void 0) this.retryAfter = retryAfter;
|
|
156
|
+
}
|
|
157
|
+
};
|
|
158
|
+
export { isWriteConflict as i, isBaerlyErrorCode as n, isRetriableCode as r, BaerlyError as t };
|
|
159
|
+
|
|
160
|
+
//# sourceMappingURL=errors-7Rk1HGCE.js.map
|