@gusto/baerly-storage 0.1.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 +97 -0
- package/dist/API.md +850 -0
- package/dist/app-config-Cb5dO2s9.d.ts +480 -0
- package/dist/app-config.d.ts +2 -0
- package/dist/app-config.js +8 -0
- package/dist/app-config.js.map +1 -0
- package/dist/auth.d.ts +237 -0
- package/dist/auth.js +1335 -0
- package/dist/auth.js.map +1 -0
- package/dist/baerly.js +761 -0
- package/dist/baerly.js.map +1 -0
- package/dist/bucket-uri-BrDEYvzy.js +4922 -0
- package/dist/bucket-uri-BrDEYvzy.js.map +1 -0
- package/dist/chunk-EAsCxrDo.js +14 -0
- package/dist/client-BLf3Ae5s.d.ts +233 -0
- package/dist/client-react.d.ts +131 -0
- package/dist/client-react.js +559 -0
- package/dist/client-react.js.map +1 -0
- package/dist/client.d.ts +4 -0
- package/dist/client.js +160 -0
- package/dist/client.js.map +1 -0
- package/dist/cloudflare-CINJPKCW.js +911 -0
- package/dist/cloudflare-CINJPKCW.js.map +1 -0
- package/dist/cloudflare.d.ts +211 -0
- package/dist/cloudflare.js +445 -0
- package/dist/cloudflare.js.map +1 -0
- package/dist/config-Bsg8wgwo.js +198 -0
- package/dist/config-Bsg8wgwo.js.map +1 -0
- package/dist/context-Oj7ffwD-.js +187 -0
- package/dist/context-Oj7ffwD-.js.map +1 -0
- package/dist/cost-B1WiZxlf.js +203 -0
- package/dist/cost-B1WiZxlf.js.map +1 -0
- package/dist/current-json-BkatBzF7.js +252 -0
- package/dist/current-json-BkatBzF7.js.map +1 -0
- package/dist/db-D62JguBc.d.ts +336 -0
- package/dist/deploy-BB-wqbhf.js +83 -0
- package/dist/deploy-BB-wqbhf.js.map +1 -0
- package/dist/dev-banner-CWHIk8tH.d.ts +26 -0
- package/dist/dev-vite.d.ts +146 -0
- package/dist/dev-vite.js +223 -0
- package/dist/dev-vite.js.map +1 -0
- package/dist/dev.d.ts +3 -0
- package/dist/dev.js +2 -0
- package/dist/doctor-B8h9GCN9.js +331 -0
- package/dist/doctor-B8h9GCN9.js.map +1 -0
- package/dist/dump-BHo_sIMZ.js +116 -0
- package/dist/dump-BHo_sIMZ.js.map +1 -0
- package/dist/errors-DOdL95kK.js +58 -0
- package/dist/errors-DOdL95kK.js.map +1 -0
- package/dist/export-Dz2PZKSR.js +423 -0
- package/dist/export-Dz2PZKSR.js.map +1 -0
- package/dist/fsck-DEz9lyCy.js +293 -0
- package/dist/fsck-DEz9lyCy.js.map +1 -0
- package/dist/http-CjUO1Bec.js +1756 -0
- package/dist/http-CjUO1Bec.js.map +1 -0
- package/dist/http.d.ts +1619 -0
- package/dist/http.js +2 -0
- package/dist/index-BGC-ENnj.d.ts +1065 -0
- package/dist/index-BYv0hb8M.d.ts +1457 -0
- package/dist/index-BquQkhJi.d.ts +112 -0
- package/dist/index-COsQ-Mlz.d.ts +146 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.js +6 -0
- package/dist/indexes-BXn7a06a.js +297 -0
- package/dist/indexes-BXn7a06a.js.map +1 -0
- package/dist/indexes-DwOXkn1Y.d.ts +22 -0
- package/dist/inspect-x02aFWnh.js +149 -0
- package/dist/inspect-x02aFWnh.js.map +1 -0
- package/dist/log-walk-DIru96UT.js +260 -0
- package/dist/log-walk-DIru96UT.js.map +1 -0
- package/dist/maintenance-Bn6ul9aV.js +758 -0
- package/dist/maintenance-Bn6ul9aV.js.map +1 -0
- package/dist/maintenance.d.ts +323 -0
- package/dist/maintenance.js +2 -0
- package/dist/node.d.ts +422 -0
- package/dist/node.js +2 -0
- package/dist/normalize-XWY25_sG.js +133 -0
- package/dist/normalize-XWY25_sG.js.map +1 -0
- package/dist/observability-2IDYRuZK.js +2333 -0
- package/dist/observability-2IDYRuZK.js.map +1 -0
- package/dist/observability.d.ts +3 -0
- package/dist/observability.js +3 -0
- package/dist/plan-Cs17VqjU.js +224 -0
- package/dist/plan-Cs17VqjU.js.map +1 -0
- package/dist/query-DcSbFLJt.js +1880 -0
- package/dist/query-DcSbFLJt.js.map +1 -0
- package/dist/rebuild-index-C5gTXryd.js +119 -0
- package/dist/rebuild-index-C5gTXryd.js.map +1 -0
- package/dist/rebuild-index-DwXM0WfA.js +104 -0
- package/dist/rebuild-index-DwXM0WfA.js.map +1 -0
- package/dist/request-BEF_OvMh.js +72 -0
- package/dist/request-BEF_OvMh.js.map +1 -0
- package/dist/restore-CbKVMMpm.js +847 -0
- package/dist/restore-CbKVMMpm.js.map +1 -0
- package/dist/shared-secret-BJdSwpgw.js +71 -0
- package/dist/shared-secret-BJdSwpgw.js.map +1 -0
- package/dist/snapshot-D7C4_FSl.js +71 -0
- package/dist/snapshot-D7C4_FSl.js.map +1 -0
- package/dist/snapshot-z_N9hpTe.js +917 -0
- package/dist/snapshot-z_N9hpTe.js.map +1 -0
- package/dist/src-Chafbw8r.js +522 -0
- package/dist/src-Chafbw8r.js.map +1 -0
- package/dist/src-DyET_VPP.js +6199 -0
- package/dist/src-DyET_VPP.js.map +1 -0
- package/dist/src-n0Te1r98.js +352 -0
- package/dist/src-n0Te1r98.js.map +1 -0
- package/dist/subcommand-BWs6K7zb.js +110 -0
- package/dist/subcommand-BWs6K7zb.js.map +1 -0
- package/dist/usage-RVUQMLop.js +339 -0
- package/dist/usage-RVUQMLop.js.map +1 -0
- package/dist/validate-DhH1lO8I.js +377 -0
- package/dist/validate-DhH1lO8I.js.map +1 -0
- package/dist/wire-izfGZDvr.js +7 -0
- package/dist/wire-izfGZDvr.js.map +1 -0
- package/package.json +189 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"maintenance-Bn6ul9aV.js","names":["ctxMetrics","APPLICATION_JSON","internal"],"sources":["../packages/protocol/src/coordination/gc-pending.ts","../packages/server/src/compactor.ts","../packages/server/src/gc.ts","../packages/server/src/rebuild-index.ts","../packages/server/src/maintenance.ts"],"sourcesContent":["/**\n * `gc/pending.json` — the per-collection GC candidate ledger. CAS-\n * protected; one per `(tenant, collection)` key — for example\n * `<tenant>/<collection>/gc/pending.json`. `runGc()` in\n * `packages/server/src/gc.ts` is the single writer that adds and\n * removes entries. Stays small in steady state because every\n * candidate is deleted once `due_at` passes.\n *\n * \"Mark\" appends candidates with a future `due_at`; \"sweep\" deletes\n * candidates whose `due_at` is in the past. The two phases run in\n * the same compactor pass — see `runGc()` in\n * `packages/server/src/gc.ts`.\n *\n * Lives next to {@link CurrentJson} in `coordination/` — same shape\n * of \"CAS-protected small control object.\" Pure module; no Node\n * imports; Worker-bundleable.\n *\n * @see packages/server/src/gc.ts\n */\n\nimport { decodeJsonBytes, encodeJsonBytes } from \"../bytes.ts\";\nimport { GC_PENDING_CONTENT_TYPE, GC_PENDING_SCHEMA_VERSION } from \"../constants.ts\";\nimport { BaerlyError } from \"../errors.ts\";\nimport type { Storage, StoragePutOptions, StoragePutResult } from \"../storage/types.ts\";\n\n/**\n * On-bucket body of `gc/pending.json`. Bounded by\n * `GC_MAX_PENDING_CANDIDATES`. The shape is forward-compatible:\n * adding a new optional field is non-breaking. Renaming or removing\n * a field requires bumping {@link GC_PENDING_SCHEMA_VERSION} to `2`;\n * readers MUST reject unknown major versions with\n * `BaerlyError{code:\"InvalidResponse\"}`.\n */\nexport interface GcPending {\n /** Schema version. Today `1`. Readers MUST reject unknown majors. */\n schema_version: 1;\n /**\n * Candidate deletions. The compactor MUST keep this list bounded —\n * `runGc()` caps the per-run marks and sweeps.\n */\n candidates: ReadonlyArray<GcCandidate>;\n /**\n * Server-clock ISO-8601 timestamp of the last successful sweep\n * completion. Drives the `db.gc.entries_swept_per_second` metric.\n * Empty string `\"\"` before the first sweep.\n */\n last_swept_at: string;\n}\n\n/**\n * One pending deletion entry. The `runGc()` mark phase appends these\n * with a future `due_at`; the sweep phase deletes entries whose\n * `due_at` is in the past and prunes them from the list.\n */\nexport interface GcCandidate {\n /** Full bucket-relative key of the deletion candidate. */\n key: string;\n /** ISO-8601 server-clock time after which the key may be deleted. */\n due_at: string;\n /** Why the key is a candidate. */\n reason: \"stale-log\" | \"orphan-snapshot\" | \"orphan-content\";\n}\n\n/**\n * Return shape from {@link readGcPending}: the parsed JSON plus the\n * ETag needed for a follow-up CAS write.\n */\nexport interface GcPendingRead {\n readonly json: GcPending;\n readonly etag: string;\n}\n\n/**\n * Read + parse `gc/pending.json` at `key`. Returns `null` on\n * not-found.\n *\n * @throws BaerlyError{code:\"InvalidResponse\"} — body is not valid\n * JSON, or `schema_version` is unknown, or the shape fails\n * the runtime guard.\n */\nexport const readGcPending = async (\n storage: Storage,\n key: string,\n opts?: { signal?: AbortSignal },\n): Promise<GcPendingRead | null> => {\n const got = await storage.get(key, opts);\n if (got === null) {\n return null;\n }\n let parsed: unknown;\n try {\n parsed = decodeJsonBytes(got.body);\n } catch (error) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `gc/pending.json at ${key}: body is not valid JSON`,\n error,\n );\n }\n return { json: assertGcPending(parsed, key), etag: got.etag };\n};\n\n/**\n * Create `gc/pending.json` if-and-only-if it does not exist (S3\n * `If-None-Match: \"*\"`). Use this once per collection at first GC\n * run; subsequent updates go through {@link casUpdateGcPending}.\n *\n * @throws BaerlyError{code:\"Conflict\"} — the key already exists.\n * @throws BaerlyError{code:\"InvalidResponse\"} — `initial` fails the\n * runtime shape guard.\n */\nexport const createGcPending = async (\n storage: Storage,\n key: string,\n initial: GcPending,\n opts?: { signal?: AbortSignal },\n): Promise<GcPendingRead> => {\n assertGcPending(initial, key);\n const body = encodeJsonBytes(initial);\n const putOpts: StoragePutOptions = {\n ifNoneMatch: \"*\",\n contentType: GC_PENDING_CONTENT_TYPE,\n ...(opts?.signal !== undefined && { signal: opts.signal }),\n };\n let result: StoragePutResult;\n try {\n result = await storage.put(key, body, putOpts);\n } catch (error) {\n throw translateCasError(error, key);\n }\n return { json: initial, etag: result.etag };\n};\n\n/**\n * Read-modify-write `gc/pending.json` under CAS. The `mutator`\n * receives a deep clone of the current parsed JSON and returns the\n * new state. The new state is written with `If-Match: <currentEtag>`;\n * on conflict, throws `BaerlyError{code:\"Conflict\"}`.\n *\n * `mutator` MUST be deterministic — it may be called multiple times\n * if the caller wraps this in a retry loop, so it must not have side\n * effects.\n *\n * @throws BaerlyError{code:\"Conflict\"} — another writer landed a write\n * between this function's read and write.\n * @throws BaerlyError{code:\"InvalidResponse\"} — `key` does not exist\n * (use {@link createGcPending} instead) or body doesn't\n * parse / fails the shape guard.\n */\nexport const casUpdateGcPending = async (\n storage: Storage,\n key: string,\n mutator: (current: GcPending) => GcPending,\n opts?: { signal?: AbortSignal },\n): Promise<GcPendingRead> => {\n const existing = await readGcPending(storage, key, opts);\n if (existing === null) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `gc/pending.json at ${key} does not exist; use createGcPending first`,\n );\n }\n const next = mutator(structuredClone(existing.json));\n assertGcPending(next, key);\n const body = encodeJsonBytes(next);\n const putOpts: StoragePutOptions = {\n ifMatch: existing.etag,\n contentType: GC_PENDING_CONTENT_TYPE,\n ...(opts?.signal !== undefined && { signal: opts.signal }),\n };\n let result: StoragePutResult;\n try {\n result = await storage.put(key, body, putOpts);\n } catch (error) {\n throw translateCasError(error, key);\n }\n return { json: next, etag: result.etag };\n};\n\n// ---------------------------------------------------------------------\n// Internals\n// ---------------------------------------------------------------------\n\nconst VALID_REASONS = new Set<GcCandidate[\"reason\"]>([\n \"stale-log\",\n \"orphan-snapshot\",\n \"orphan-content\",\n]);\n\n/**\n * Runtime guard for `parsed` to be a {@link GcPending}. Throws\n * `BaerlyError{code:\"InvalidResponse\"}` rather than coercing.\n */\nconst assertGcPending = (parsed: unknown, key: string): GcPending => {\n if (parsed === null || typeof parsed !== \"object\") {\n throw new BaerlyError(\n \"InvalidResponse\",\n `gc/pending.json at ${key}: parsed body is not an object`,\n );\n }\n const r = parsed as Record<string, unknown>;\n if (r[\"schema_version\"] !== GC_PENDING_SCHEMA_VERSION) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `gc/pending.json at ${key}: unsupported schema_version ${String(r[\"schema_version\"])}; expected ${GC_PENDING_SCHEMA_VERSION}`,\n );\n }\n if (!Array.isArray(r[\"candidates\"])) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `gc/pending.json at ${key}: candidates must be an array`,\n );\n }\n for (let i = 0; i < r[\"candidates\"].length; i++) {\n const c = r[\"candidates\"][i];\n if (c === null || typeof c !== \"object\") {\n throw new BaerlyError(\n \"InvalidResponse\",\n `gc/pending.json at ${key}: candidates[${String(i)}] is not an object`,\n );\n }\n const cr = c as Record<string, unknown>;\n if (typeof cr[\"key\"] !== \"string\" || cr[\"key\"].length === 0) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `gc/pending.json at ${key}: candidates[${String(i)}].key must be a non-empty string`,\n );\n }\n if (typeof cr[\"due_at\"] !== \"string\") {\n throw new BaerlyError(\n \"InvalidResponse\",\n `gc/pending.json at ${key}: candidates[${String(i)}].due_at must be a string`,\n );\n }\n if (\n typeof cr[\"reason\"] !== \"string\" ||\n !VALID_REASONS.has(cr[\"reason\"] as GcCandidate[\"reason\"])\n ) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `gc/pending.json at ${key}: candidates[${String(i)}].reason must be one of stale-log|orphan-snapshot|orphan-content`,\n );\n }\n }\n if (typeof r[\"last_swept_at\"] !== \"string\") {\n throw new BaerlyError(\n \"InvalidResponse\",\n `gc/pending.json at ${key}: last_swept_at must be a string`,\n );\n }\n return parsed as GcPending;\n};\n\n/**\n * Wrap a storage-level error with `gc/pending.json at <key>`\n * location context. `Conflict` (the storage layer's CAS-lost signal)\n * is re-thrown with an annotated message; other `BaerlyError`s pass\n * through; non-`BaerlyError` falls through as `InvalidResponse`.\n */\nconst translateCasError = (e: unknown, key: string): BaerlyError => {\n if (e instanceof BaerlyError && e.code === \"Conflict\") {\n return new BaerlyError(\"Conflict\", `gc/pending.json CAS lost at ${key}: ${e.message}`, e);\n }\n if (e instanceof BaerlyError) {\n return e;\n }\n return new BaerlyError(\n \"InvalidResponse\",\n `gc/pending.json write at ${key} failed: ${String(e)}`,\n e,\n );\n};\n","/* eslint-disable no-underscore-dangle -- `_id` is the locked primary-key\n field on document shapes (see `@baerly/protocol/src/collection-api.ts`'s `Collection<T>` /\n `Query<T>` declarations); the snapshot body carries it through. */\n\n/**\n * Compactor: fold a prefix of the live log into a content-\n * hashed snapshot file and CAS-advance `current.json` to swap the\n * pointer.\n *\n * The hard correctness requirement is **atomic snapshot generation**:\n * a compactor that crashes mid-write must not leave a corrupted body\n * that readers consume as truth. The design: every snapshot's filename\n * embeds the SHA-256 of its body. A crashed mid-PUT leaves a body that\n * doesn't match its own filename hash, and readers reject it as\n * \"missing.\" The atomic moment is the CAS-swap of\n * `current.json.snapshot`, which is a single conditional PUT.\n *\n * Order of operations (matches `Writer.commit`'s manifest-first-\n * REVERSED ordering): PUT snapshot body → CAS-advance `current.json`.\n * A crash before the swap leaves an orphan snapshot file; the swap\n * succeeds iff our captured ETag still matches.\n *\n * Why level-prefixed chunked snapshots over the alternatives: a\n * single monolithic snapshot (every compaction rewrites one well-\n * known key) makes partial writes catastrophic and serializes every\n * writer on one key. WAL-checkpointing in the rqlite / Raft tradition\n * requires a consensus layer Baerly doesn't have. The Litestream-\n * style multi-level scheme — small fixed number of levels, chunked\n * files keyed by sequence range — keeps random GETs cheap on\n * S3-compatible storage and avoids LIST. Current ship is single-\n * level at L9 (one snapshot replaces the prior; no multi-level merge\n * yet); the key format is forward-compatible with future L0..L9\n * rolling merges without a wire change.\n *\n * @see ../../../docs/spec/sync-protocol.md\n */\n\nimport {\n type CurrentJson,\n type DocumentData,\n type MetricsRecorder,\n encodeJsonBytes,\n logSeqStartOf,\n BaerlyError,\n noopMetricsRecorder,\n readCurrentJson,\n snapshotHash,\n type Storage,\n type StoragePutOptions,\n} from \"@baerly/protocol\";\nimport { walkLogRange } from \"./log-walk.ts\";\nimport { getCurrentContext } from \"./observability/context.ts\";\nimport {\n encodeSnapshotBody,\n loadSnapshotAsMap,\n type SnapshotBody,\n snapshotKey,\n} from \"./snapshot.ts\";\n\nconst ctxMetrics = (): MetricsRecorder => getCurrentContext()?.recorder ?? noopMetricsRecorder;\n\n/**\n * Public configuration knobs for {@link compact}. All optional; the\n * engine works unbounded by default. Opt into a per-run cap via the\n * `CLOUDFLARE_FREE_TIER` profile (from `./maintenance.ts`) or by\n * reaching for {@link InternalCompactOptions} via the\n * `@baerly/server/_internal/testing` subpath.\n */\nexport interface CompactOptions {\n /**\n * Minimum log-tail length to compact. Skips work when there are\n * fewer than this many live entries past the last snapshot.\n * Default 100.\n */\n readonly minEntriesToCompact?: number;\n\n /** Optional AbortSignal forwarded to every storage call. */\n readonly signal?: AbortSignal;\n}\n\n/**\n * Internal-only widening of {@link CompactOptions}. Surfaced via the\n * `@baerly/server/_internal/testing` subpath (NOT in the published\n * `publishConfig.exports`); production callers should use\n * {@link CompactOptions}.\n *\n * @internal\n */\nexport interface InternalCompactOptions extends CompactOptions {\n /**\n * @internal Budget cap for the CF free-tier subrequest budget;\n * `CLOUDFLARE_FREE_TIER` sets it. Tests also set it to exercise\n * the cap path. The compactor's I/O profile is\n * `maxEntriesPerRun + 3` subrequests (N GETs + 1 PUT snapshot +\n * 1 GET current + 1 PUT current). The default is effectively\n * unbounded (`Number.MAX_SAFE_INTEGER`).\n */\n readonly maxEntriesPerRun?: number;\n}\n\nexport interface CompactResult {\n /** `true` iff a new snapshot landed and `current.json` was advanced. */\n readonly written: boolean;\n /** Reason `written === false`. */\n readonly skippedReason?: \"below-min-threshold\" | \"current-json-missing\" | \"cas-lost\";\n /** Prior snapshot key (`null` if no prior snapshot existed). */\n readonly previousSnapshotKey: string | null;\n /** New snapshot key (`undefined` if `written === false` and no PUT happened). */\n readonly newSnapshotKey?: string;\n /** `log_seq_start` before the run. */\n readonly logSeqStartBefore: number;\n /** `log_seq_start` after the run. */\n readonly logSeqStartAfter: number;\n /** Number of log entries folded into the new snapshot. */\n readonly entriesFolded: number;\n}\n\nconst DEFAULT_MAX_PER_RUN = Number.MAX_SAFE_INTEGER;\nconst DEFAULT_MIN_TO_COMPACT = 100;\nconst APPLICATION_JSON = \"application/json\";\n\n/**\n * Fold a prefix of the live log into a new snapshot and CAS-advance\n * `current.json`. Idempotent: a second run with no new writes is a\n * no-op (below-min-threshold).\n *\n * Single-attempt: on CAS conflict we return\n * `{written: false, skippedReason: \"cas-lost\", newSnapshotKey}` — the\n * caller (the cron handler invoking `runScheduledMaintenance` from\n * `./maintenance.ts`) decides whether to schedule another run. The\n * orphan snapshot file just written will be swept by `runGc()`.\n *\n * @throws BaerlyError code=\"InvalidResponse\" — `current.json` is\n * present but malformed, or a snapshot body fails its schema /\n * collection cross-check.\n * @throws BaerlyError code=\"Internal\" — protocol-invariant violation:\n * a log entry missing inside `[log_seq_start, foldEnd)`, or the\n * prior-snapshot pointer resolves to no body / a body whose hash\n * doesn't match its filename.\n *\n * @example\n * ```ts\n * import { compact } from \"@gusto/baerly-storage\";\n *\n * const res = await compact(\n * { storage, currentJsonKey: \"app/x/tenant/t/manifests/tickets/current.json\" },\n * { minEntriesToCompact: 100, maxEntriesPerRun: 40 },\n * );\n * if (res.written) console.log(\"snapshot landed at\", res.newSnapshotKey);\n * ```\n */\nexport const compact = async (\n args: {\n storage: Storage;\n /** Full bucket-relative key of the CAS pointer. */\n currentJsonKey: string;\n },\n options: CompactOptions = {},\n): Promise<CompactResult> => {\n const { storage, currentJsonKey } = args;\n // The internal cap fields ride on the same runtime object even\n // though the public `CompactOptions` doesn't surface them. The cast\n // is safe — the JS runtime carries every property regardless of TS\n // narrowing — and keeps the public type honest.\n const internal = options as InternalCompactOptions;\n const maxPerRun = internal.maxEntriesPerRun ?? DEFAULT_MAX_PER_RUN;\n const minToCompact = options.minEntriesToCompact ?? DEFAULT_MIN_TO_COMPACT;\n const collectionPrefix = currentJsonKey.slice(0, currentJsonKey.lastIndexOf(\"/\"));\n const collectionName = collectionPrefix.slice(collectionPrefix.lastIndexOf(\"/\") + 1);\n\n // ── Step 1. Read current.json fresh. ────────────────────────────\n const read = await readCurrentJson(\n storage,\n currentJsonKey,\n options.signal !== undefined ? { signal: options.signal } : undefined,\n );\n if (read === null) {\n return {\n written: false,\n skippedReason: \"current-json-missing\",\n previousSnapshotKey: null,\n logSeqStartBefore: 0,\n logSeqStartAfter: 0,\n entriesFolded: 0,\n };\n }\n const current = read.json;\n const baseEtag = read.etag;\n const logSeqStartBefore = logSeqStartOf(current);\n const nextSeq = current.next_seq;\n const available = nextSeq - logSeqStartBefore;\n if (available < minToCompact) {\n return {\n written: false,\n skippedReason: \"below-min-threshold\",\n previousSnapshotKey: current.snapshot,\n logSeqStartBefore,\n logSeqStartAfter: logSeqStartBefore,\n entriesFolded: 0,\n };\n }\n\n const foldEnd = Math.min(nextSeq, logSeqStartBefore + maxPerRun);\n\n // ── Step 2. Load the previous snapshot (if any) as the fold base.\n const base =\n current.snapshot === null\n ? new Map<string, DocumentData>()\n : await loadSnapshotAsMap(storage, current.snapshot, collectionName, options.signal);\n\n // ── Step 3. Parallel-fetch [logSeqStartBefore, foldEnd) entries. ──\n const entries = await walkLogRange(storage, collectionPrefix, logSeqStartBefore, foldEnd, {\n signal: options.signal,\n });\n\n // ── Step 4. Apply the fold onto `base`. ─────────────────────────\n // I / U overwrite with the post-image (today's per-doc-replace\n // model: writer emits `entry.new` as the full post-image, see\n // packages/protocol/src/log.ts:67-72). D tombstones. T / M are\n // forward-compat shapes (writer doesn't emit them today).\n for (const entry of entries) {\n if (entry.collection !== collectionName) {\n continue;\n }\n if (entry.doc_id === undefined) {\n continue;\n }\n switch (entry.op) {\n case \"I\":\n case \"U\": {\n if (entry.new !== undefined) {\n base.set(entry.doc_id, entry.new);\n }\n break;\n }\n case \"D\": {\n base.delete(entry.doc_id);\n break;\n }\n case \"T\":\n case \"M\": {\n // No-op for this ticket.\n break;\n }\n }\n }\n\n // ── Step 5. Build the canonical snapshot body. ──────────────────\n // Sort by `_id` so the byte output is deterministic — same fold ⇒\n // same body ⇒ same hash ⇒ same filename. Idempotent re-runs.\n const sortedDocs = Array.from(base.entries())\n .toSorted(([a], [b]) => {\n if (a < b) {\n return -1;\n }\n if (a > b) {\n return 1;\n }\n return 0;\n })\n .map(([id, body]) => ({ _id: id, body }));\n const snapshotBody: SnapshotBody = {\n schema_version: 1,\n min_seq: 0,\n max_seq: foldEnd,\n collection: collectionName,\n docs: sortedDocs,\n };\n const bodyBytes = encodeSnapshotBody(snapshotBody);\n const sha256 = await snapshotHash(bodyBytes);\n const newKey = snapshotKey(collectionPrefix, 0, foldEnd, sha256);\n\n // ── Step 6. PUT the snapshot. ───────────────────────────────────\n // No CAS guard — content-hash filenames make collisions impossible\n // for distinct bodies. If a concurrent compactor produced the same\n // body, this PUT is an idempotent overwrite of the same bytes.\n const putOpts: StoragePutOptions = {\n contentType: APPLICATION_JSON,\n ...(options.signal !== undefined && { signal: options.signal }),\n };\n await storage.put(newKey, bodyBytes, putOpts);\n\n // ── Step 7. CAS-advance current.json. ───────────────────────────\n const next: CurrentJson = {\n ...current,\n snapshot: newKey,\n log_seq_start: foldEnd,\n };\n const nextBody = encodeJsonBytes(next);\n const casOpts: StoragePutOptions = {\n ifMatch: baseEtag,\n contentType: APPLICATION_JSON,\n ...(options.signal !== undefined && { signal: options.signal }),\n };\n try {\n await storage.put(currentJsonKey, nextBody, casOpts);\n } catch (error) {\n if (isCasConflict(error)) {\n // Another writer landed between our read and write. The\n // snapshot file we just wrote is now an orphan (correct\n // content, unreferenced) — `runGc()` will sweep it. Surface\n // cas-lost; the cron handler can rerun us next tick.\n return {\n written: false,\n skippedReason: \"cas-lost\",\n previousSnapshotKey: current.snapshot,\n newSnapshotKey: newKey,\n logSeqStartBefore,\n logSeqStartAfter: logSeqStartBefore,\n entriesFolded: foldEnd - logSeqStartBefore,\n };\n }\n throw error;\n }\n\n // ── Step 8. Emit metrics on a successful run. ───────────────────\n // `lag_window_depth` is the post-compaction live tail length —\n // entries still pending fold after this run. `entries_folded` is\n // the per-run histogram sample. Metrics are in-memory only; they\n // add zero storage ops.\n const entriesFolded = foldEnd - logSeqStartBefore;\n const metrics = ctxMetrics();\n metrics.histogram(\"db.compact.entries_folded\", entriesFolded, { collection: collectionName });\n metrics.gauge(\"db.manifest.lag_window_depth\", current.next_seq - foldEnd, {\n collection: collectionName,\n });\n\n return {\n written: true,\n previousSnapshotKey: current.snapshot,\n newSnapshotKey: newKey,\n logSeqStartBefore,\n logSeqStartAfter: foldEnd,\n entriesFolded,\n };\n};\n\n// ---------------------------------------------------------------------\n// Internals\n// ---------------------------------------------------------------------\n\n/**\n * `true` when an `If-Match` CAS guard lost. Every in-tree\n * {@link Storage} impl surfaces a lost CAS as\n * `BaerlyError{code:\"Conflict\"}`.\n */\nconst isCasConflict = (err: unknown): boolean =>\n err instanceof BaerlyError && err.code === \"Conflict\";\n","/**\n * GC mark + sweep.\n *\n * `runGc` is a single-pass garbage collector that:\n * 1. Reads `current.json` (and bootstraps `gc/pending.json` on first\n * run).\n * 2. Marks new orphan candidates by LISTing the three artifact\n * prefixes — log, snapshot, content — and classifying each key.\n * 3. Sweeps any already-pending candidate whose `due_at` has passed.\n * 4. CAS-writes the updated `gc/pending.json`.\n *\n * Two-phase by design: every candidate sits in `gc/pending.json` for a\n * grace period (default 7 days, see {@link GC_GRACE_PERIOD_MILLIS})\n * before it is deleted. The grace bounds the worst plausible\n * writer-retry window — a paused-process writer that resumes hours\n * later still finds its idempotency anchor on the bucket.\n *\n * Idempotent: same input bucket state ⇒ same `pending.json` output.\n * Unbounded by default — the run marks and sweeps the entire eligible\n * set in one pass. Callers on the Cloudflare 50-subrequest free-tier\n * budget opt INTO caps via the `CLOUDFLARE_FREE_TIER` profile's\n * `gc.maxMarksPerRun` / `maxSweepsPerRun` knobs (`InternalRunGcOptions`,\n * not on the public `RunGcOptions`).\n *\n * Three categories of orphan:\n * - `stale-log`: `<collectionPrefix>/log/<seq>.json` with\n * `seq < log_seq_start`. After `compact()` folds these into a\n * snapshot, they're unreferenced.\n * - `orphan-snapshot`: a `<collectionPrefix>/snapshot/L<n>/...` key not\n * equal to `current.snapshot`. Each compactor run replaces the\n * pointer; the prior file becomes unreferenced.\n * - `orphan-content`: `<collectionPrefix>/content/<sha>.json` whose\n * 32-hex truncated-SHA-256 hash is not in the live content-hash\n * set (computed by hashing every live `entry.new` post-image —\n * the same hash the writer's step 4 produces). Surfaces writer\n * crashes between the content PUT and the log-entry PUT.\n *\n * CAS-lost on `gc/pending.json` is non-fatal: the DELETEs already\n * issued are durable, so we return a successful result and the next\n * pass will pick up any work this pass lost.\n */\n\nimport {\n type CurrentJson,\n type GcCandidate,\n type GcPending,\n type MetricsRecorder,\n type Storage,\n type StorageListEntry,\n GC_GRACE_PERIOD_MILLIS,\n GC_MAX_PENDING_CANDIDATES,\n GC_PENDING_SCHEMA_VERSION,\n BaerlyError,\n casUpdateGcPending,\n createGcPending,\n decodeJsonBytes,\n encodeJsonBytes,\n logSeqStartOf,\n noopMetricsRecorder,\n readCurrentJson,\n readGcPending,\n versionFromContent,\n} from \"@baerly/protocol\";\nimport { loadSnapshotAsMap } from \"./snapshot.ts\";\nimport { getCurrentContext } from \"./observability/context.ts\";\n\nconst ctxMetrics = (): MetricsRecorder => getCurrentContext()?.recorder ?? noopMetricsRecorder;\n\n/**\n * Public tunables for {@link runGc}. All optional; the engine works\n * unbounded by default. Opt into per-run caps via the\n * `CLOUDFLARE_FREE_TIER` profile (from `./maintenance.ts`) or by\n * reaching for {@link InternalRunGcOptions} via the\n * `@baerly/server/_internal/testing` subpath.\n */\nexport interface RunGcOptions {\n readonly signal?: AbortSignal;\n}\n\n/**\n * Internal-only widening of {@link RunGcOptions}. Surfaced via the\n * `@baerly/server/_internal/testing` subpath (NOT in the published\n * `publishConfig.exports`); production callers should use\n * {@link RunGcOptions}.\n *\n * @internal\n */\nexport interface InternalRunGcOptions extends RunGcOptions {\n /**\n * @internal Override grace-period for tests. Defaults to\n * {@link GC_GRACE_PERIOD_MILLIS} (7 days). Tests use `0` to bypass\n * the grace and exercise the sweep path in one pass.\n */\n readonly graceMillis?: number;\n\n /**\n * @internal Budget cap on candidates marked per category per run.\n * `CLOUDFLARE_FREE_TIER` sets it; bounds LIST + classification\n * cost per pass. The default is effectively unbounded\n * (`Number.MAX_SAFE_INTEGER`).\n */\n readonly maxMarksPerRun?: number;\n\n /**\n * @internal Budget cap on keys deleted per run.\n * `CLOUDFLARE_FREE_TIER` sets it — CF free-tier safe when paired\n * with `compact()` in the same scheduled handler. The default is\n * effectively unbounded (`Number.MAX_SAFE_INTEGER`).\n */\n readonly maxSweepsPerRun?: number;\n\n /**\n * @internal Clock injection for tests. Defaults to\n * `() => new Date()`. The function is invoked at mark time (to\n * compute `due_at` when `lastModified` is absent) and at sweep\n * time (to compare against candidate `due_at`).\n */\n readonly now?: () => Date;\n}\n\n/**\n * Return shape of {@link runGc}.\n */\nexport interface RunGcResult {\n /** Per-category counts of newly-marked candidates in this pass. */\n readonly marked: {\n readonly stale_log: number;\n readonly orphan_snapshot: number;\n readonly orphan_content: number;\n };\n /** Number of keys deleted in this pass. */\n readonly swept: number;\n /**\n * Depth of `gc/pending.json` after this pass. Drives the\n * `db.orphan.candidate_count` metric. Best-effort on `cas-lost` —\n * see module JSDoc.\n */\n readonly pendingDepth: number;\n}\n\nconst DEFAULT_MAX_MARKS = Number.MAX_SAFE_INTEGER;\nconst DEFAULT_MAX_SWEEPS = Number.MAX_SAFE_INTEGER;\n\n/**\n * Single GC pass — mark new orphans, sweep due-elapsed candidates,\n * persist via CAS-update on `gc/pending.json`.\n *\n * Returns immediately if `current.json` is missing — there's nothing\n * to do until a writer has bootstrapped the collection.\n *\n * @example\n * ```ts\n * import { runGc } from \"@gusto/baerly-storage\";\n *\n * const r = await runGc({ storage, currentJsonKey });\n * console.log(`marked ${r.marked.stale_log} stale logs, swept ${r.swept}`);\n * ```\n */\nexport const runGc = async (\n args: { storage: Storage; currentJsonKey: string },\n options: RunGcOptions = {},\n): Promise<RunGcResult> => {\n const { storage, currentJsonKey } = args;\n // The internal seam fields (caps + clock + grace) ride on the same\n // runtime object even though the public `RunGcOptions` doesn't\n // surface them. Safe cast — the JS runtime carries every property.\n const internal = options as InternalRunGcOptions;\n const grace = internal.graceMillis ?? GC_GRACE_PERIOD_MILLIS;\n const maxMarks = internal.maxMarksPerRun ?? DEFAULT_MAX_MARKS;\n const maxSweeps = internal.maxSweepsPerRun ?? DEFAULT_MAX_SWEEPS;\n const now = internal.now ?? ((): Date => new Date());\n const collectionPrefix = currentJsonKey.slice(0, currentJsonKey.lastIndexOf(\"/\"));\n const collectionName = collectionPrefix.slice(collectionPrefix.lastIndexOf(\"/\") + 1);\n const gcPendingKey = `${collectionPrefix}/gc/pending.json`;\n const signal = options.signal;\n const signalOpts = signal !== undefined ? { signal } : undefined;\n\n // ── Step 1. Read current.json (skip silently if absent). ────────\n const cur = await readCurrentJson(storage, currentJsonKey, signalOpts);\n if (cur === null) {\n return {\n marked: { stale_log: 0, orphan_snapshot: 0, orphan_content: 0 },\n swept: 0,\n pendingDepth: 0,\n };\n }\n const current = cur.json;\n const logSeqStart = logSeqStartOf(current);\n\n // ── Step 2. Read or create gc/pending.json. ─────────────────────\n // Race-tolerant create: a concurrent pass may have bootstrapped\n // between our read and our create. Re-read on Conflict.\n let pending = await readGcPending(storage, gcPendingKey, signalOpts);\n if (pending === null) {\n const initial: GcPending = {\n schema_version: GC_PENDING_SCHEMA_VERSION,\n candidates: [],\n last_swept_at: \"\",\n };\n try {\n pending = await createGcPending(storage, gcPendingKey, initial, signalOpts);\n } catch (error) {\n if (error instanceof BaerlyError && error.code === \"Conflict\") {\n pending = await readGcPending(storage, gcPendingKey, signalOpts);\n if (pending === null) {\n throw error;\n }\n } else {\n throw error;\n }\n }\n }\n\n // Set of keys already pending — don't re-mark.\n const known = new Set(pending.json.candidates.map((c) => c.key));\n\n // ── Step 3. Mark stale log entries [0, log_seq_start). ──────────\n const newCandidates: GcCandidate[] = [];\n let markedStaleLog = 0;\n if (logSeqStart > 0) {\n for await (const entry of listBounded(storage, `${collectionPrefix}/log/`, maxMarks, signal)) {\n if (markedStaleLog >= maxMarks) {\n break;\n }\n const seq = parseSeqFromLogKey(entry.key);\n if (seq === null || seq >= logSeqStart) {\n continue;\n }\n if (known.has(entry.key)) {\n continue;\n }\n newCandidates.push({\n key: entry.key,\n due_at: computeDueAt(entry, now, grace),\n reason: \"stale-log\",\n });\n markedStaleLog++;\n }\n }\n\n // ── Step 4. Mark orphan snapshots. ──────────────────────────────\n let markedOrphanSnapshot = 0;\n for await (const entry of listBounded(\n storage,\n `${collectionPrefix}/snapshot/`,\n maxMarks,\n signal,\n )) {\n if (markedOrphanSnapshot >= maxMarks) {\n break;\n }\n if (entry.key === current.snapshot) {\n continue;\n }\n if (known.has(entry.key)) {\n continue;\n }\n newCandidates.push({\n key: entry.key,\n due_at: computeDueAt(entry, now, grace),\n reason: \"orphan-snapshot\",\n });\n markedOrphanSnapshot++;\n }\n\n // ── Step 5. Mark orphan content. ────────────────────────────────\n // Build the live content-hash set by hashing every live post-image:\n // - log entries [log_seq_start, next_seq)\n // - snapshot rows (via `loadSnapshotAsMap` so the hash check\n // defends against a tampered snapshot)\n // Hash with the same `versionFromContent` (32-hex truncated SHA-256)\n // the writer used to mint the content key.\n const liveHashes = await collectLiveContentHashes(\n storage,\n collectionPrefix,\n collectionName,\n current,\n logSeqStart,\n signal,\n );\n let markedOrphanContent = 0;\n for await (const entry of listBounded(\n storage,\n `${collectionPrefix}/content/`,\n maxMarks,\n signal,\n )) {\n if (markedOrphanContent >= maxMarks) {\n break;\n }\n const hash = parseHashFromContentKey(entry.key);\n if (hash === null || liveHashes.has(hash)) {\n continue;\n }\n if (known.has(entry.key)) {\n continue;\n }\n newCandidates.push({\n key: entry.key,\n due_at: computeDueAt(entry, now, grace),\n reason: \"orphan-content\",\n });\n markedOrphanContent++;\n }\n\n // ── Step 6. Sweep candidates whose due_at is in the past. ───────\n // Eligible set = previously-pending entries PLUS this pass's freshly\n // marked entries. Including the new marks lets `runGc({graceMillis:0})`\n // mark-and-sweep in a single pass — useful for tests and for\n // grace-bypassing maintenance jobs. Order: pre-existing first\n // (they've been waiting longer), then new marks.\n const nowMs = now().getTime();\n const sweepCandidates: GcCandidate[] = [...pending.json.candidates, ...newCandidates];\n const toSweep: GcCandidate[] = [];\n const remaining: GcCandidate[] = [];\n for (const cand of sweepCandidates) {\n if (toSweep.length < maxSweeps && Date.parse(cand.due_at) <= nowMs) {\n toSweep.push(cand);\n } else {\n remaining.push(cand);\n }\n }\n // Idempotent DELETE on every in-tree Storage impl — a 404 is a\n // no-op. Parallel via Promise.all; one failure aborts the rest,\n // but the per-key DELETEs that landed are durable.\n await Promise.all(toSweep.map((c) => storage.delete(c.key, signalOpts)));\n\n // ── Step 7. CAS-write pending.json. ─────────────────────────────\n // Un-swept candidates (pre-existing un-due + new un-due) form the\n // post-pass ledger. Bounded by GC_MAX_PENDING_CANDIDATES.\n const merged: GcCandidate[] = remaining.slice(0, GC_MAX_PENDING_CANDIDATES);\n const lastSweptAt = toSweep.length > 0 ? now().toISOString() : pending.json.last_swept_at;\n const markedSummary = {\n stale_log: markedStaleLog,\n orphan_snapshot: markedOrphanSnapshot,\n orphan_content: markedOrphanContent,\n };\n let pendingDepth: number;\n try {\n const updated = await casUpdateGcPending(\n storage,\n gcPendingKey,\n () => ({\n schema_version: GC_PENDING_SCHEMA_VERSION,\n candidates: merged,\n last_swept_at: lastSweptAt,\n }),\n signalOpts,\n );\n pendingDepth = updated.json.candidates.length;\n } catch (error) {\n // CAS-lost on pending.json: another GC pass landed concurrently.\n // The DELETEs we issued are durable; the next pass picks up any\n // marks we couldn't persist. Surface success — re-throwing here\n // would mask the work we DID complete.\n if (error instanceof BaerlyError && error.code === \"Conflict\") {\n // Best-effort: we know `remaining.length` is at least the\n // post-sweep depth; concurrent passes may have moved it.\n pendingDepth = remaining.length;\n } else {\n throw error;\n }\n }\n\n // ── Step 8. Emit metrics. ───────────────────────────────────────\n // In-memory only — zero storage ops. Emit regardless of CAS-lost\n // (the operator wants visibility into best-effort runs too).\n const labels = { collection: collectionName };\n const metrics = ctxMetrics();\n metrics.gauge(\"db.orphan.candidate_count\", pendingDepth, labels);\n metrics.gauge(\"db.gc.entries_swept_per_second\", toSweep.length, labels);\n if (toSweep.length > 0) {\n const byReason = new Map<GcCandidate[\"reason\"], number>();\n for (const c of toSweep) {\n byReason.set(c.reason, (byReason.get(c.reason) ?? 0) + 1);\n }\n for (const [reason, count] of byReason) {\n metrics.counter(\"db.gc.swept_total\", count, { collection: collectionName, reason });\n }\n }\n\n return {\n marked: markedSummary,\n swept: toSweep.length,\n pendingDepth,\n };\n};\n\n// ---------------------------------------------------------------------\n// Internals\n// ---------------------------------------------------------------------\n\n/**\n * `Storage.list` with a hard ceiling — bounds the I/O cost of a\n * single pass when a runaway prefix has accumulated many keys.\n */\nconst listBounded = async function* (\n storage: Storage,\n prefix: string,\n cap: number,\n signal: AbortSignal | undefined,\n): AsyncGenerator<StorageListEntry> {\n let yielded = 0;\n const opts = signal !== undefined ? { signal } : undefined;\n for await (const entry of storage.list(prefix, opts)) {\n if (yielded >= cap) {\n return;\n }\n yield entry;\n yielded++;\n }\n};\n\n/**\n * Parse `<...>/log/<seq>.json` and return `seq`. Returns `null` on\n * any shape that doesn't look like a log entry key — defensively\n * tolerates an unrelated key under the log prefix.\n */\nconst parseSeqFromLogKey = (key: string): number | null => {\n const match = /\\/log\\/(\\d+)\\.json$/.exec(key);\n if (match === null) {\n return null;\n }\n const n = Number.parseInt(match[1]!, 10);\n return Number.isFinite(n) && n >= 0 ? n : null;\n};\n\n/**\n * Parse `<...>/content/<sha-32>.json` and return the 32-hex hash.\n * Returns `null` on any shape that doesn't match the writer's\n * `versionFromContent`-produced key format.\n */\nconst parseHashFromContentKey = (key: string): string | null => {\n const match = /\\/content\\/([0-9a-f]{32})\\.json$/.exec(key);\n return match === null ? null : match[1]!;\n};\n\n/**\n * Anchor `due_at` to `lastModified` when the storage adapter\n * surfaces it; fall back to the injected `now` so a Storage impl\n * without a server clock still GCs after `grace` from the mark\n * moment.\n */\nconst computeDueAt = (entry: StorageListEntry, now: () => Date, graceMs: number): string => {\n const base = entry.lastModified ?? now();\n return new Date(base.getTime() + graceMs).toISOString();\n};\n\n/**\n * Build the live content-hash set. The set covers every live\n * post-image: every `entry.new` in `[logSeqStart, next_seq)` plus\n * every row body in the current snapshot.\n *\n * A snapshot read that throws (corrupt body, hash mismatch) is\n * tolerated — the worst-case effect is missing some live hashes,\n * which could mark a live content blob as orphan. The grace period\n * absorbs the false-positive: a retry that re-PUTs the same hash\n * recreates the key before the sweep deletes it.\n */\nconst collectLiveContentHashes = async (\n storage: Storage,\n collectionPrefix: string,\n collectionName: string,\n current: CurrentJson,\n logSeqStart: number,\n signal: AbortSignal | undefined,\n): Promise<Set<string>> => {\n const hashes = new Set<string>();\n const getOpts = signal !== undefined ? { signal } : undefined;\n\n // Live log tail.\n const logReads: Array<Promise<void>> = [];\n for (let s = logSeqStart; s < current.next_seq; s++) {\n logReads.push(\n (async (): Promise<void> => {\n const got = await storage.get(`${collectionPrefix}/log/${s}.json`, getOpts);\n if (got === null) {\n return;\n }\n let entry: { new?: unknown };\n try {\n entry = decodeJsonBytes<{ new?: unknown }>(got.body);\n } catch {\n // A malformed log entry is the writer's concern, not GC's.\n // Skip and let other invariants catch it.\n return;\n }\n if (entry.new === undefined) {\n return;\n }\n const bodyBytes = encodeJsonBytes(entry.new);\n hashes.add(await versionFromContent(bodyBytes));\n })(),\n );\n }\n await Promise.all(logReads);\n\n // Snapshot rows.\n if (current.snapshot !== null) {\n try {\n const map = await loadSnapshotAsMap(storage, current.snapshot, collectionName, signal);\n const rowReads: Array<Promise<void>> = [];\n for (const body of map.values()) {\n rowReads.push(\n (async (): Promise<void> => {\n const bytes = encodeJsonBytes(body);\n hashes.add(await versionFromContent(bytes));\n })(),\n );\n }\n await Promise.all(rowReads);\n } catch {\n // Snapshot read failure is non-fatal — see the docstring.\n }\n }\n\n return hashes;\n};\n","/**\n * Idempotent reconciliation for one secondary index.\n *\n * {@link rebuildIndex} folds the live `(snapshot, log_tail)` of a\n * collection into the doc set the writer's index emission would\n * have produced, then PUTs every missing index key and DELETEs every\n * orphaned one. Same-key zero-byte PUTs are no-ops (the entries are\n * content-addressed by composition); same-key DELETEs are\n * contractually idempotent.\n *\n * Invariants:\n *\n * - **Re-running on a healthy index is a no-op.** `added = 0`,\n * `removed = 0`.\n * - **Re-running after a crashed mid-commit** reconciles toward\n * the live `current.json` view — orphans deleted, missing keys\n * PUT.\n * - **Re-running while writes are in flight** is safe up to a\n * race window: a write that lands during the rebuild may\n * produce a transient \"orphan\" the rebuild sweeps, which the\n * next live write then re-PUTs. The race converges on the next\n * commit.\n *\n * The function reads the same fold the writer / reader use\n * (snapshot via {@link loadSnapshotAsMap}; log tail by direct\n * `get(<logPrefix>/log/<seq>.json)`) so it MUST agree with the\n * writer on the live doc set by construction.\n *\n * @see ./indexes.ts — `IndexDefinition`, `allIndexKeysFor`,\n * `indexKeyPrefix`.\n * @see ./writer.ts — the fence-time emission path this\n * command reconciles.\n */\n\nimport {\n BaerlyError,\n type DocumentData,\n logSeqStartOf,\n readCurrentJson,\n type Storage,\n} from \"@baerly/protocol\";\nimport { loadSnapshotAsMap } from \"./snapshot.ts\";\nimport { allIndexKeysFor, type IndexDefinition, indexKeyPrefix } from \"./indexes.ts\";\nimport { foldLogEntriesOnto, walkLogRange } from \"./log-walk.ts\";\n\nconst EMPTY_BODY = new Uint8Array(0);\nconst APPLICATION_JSON = \"application/json\";\n\n/**\n * Reconciliation summary.\n *\n * In a normal (mutating) run, the counts describe what was actually\n * PUT / DELETEd. In `dryRun` mode ({@link RebuildIndexOptions.dryRun}),\n * `added` / `removed` report the counts that a real rebuild *would*\n * have produced — storage is unchanged. `kept` counts pre-existing\n * intersection keys (`expected ∩ actual`) at function entry. In a real\n * run, `kept` may also include keys promoted from `added` via the\n * Conflict-race fallback (a PUT with `ifNoneMatch:\"*\"` returned 412\n * because a peer wrote the same key first, so the key was already\n * in place by the time we observed it); dryRun mode never issues\n * those PUTs and therefore does not observe that race.\n */\nexport interface RebuildIndexResult {\n /**\n * Keys PUT because they were missing on storage. In `dryRun` mode,\n * the predicted PUT count — no writes were issued.\n */\n readonly added: number;\n /**\n * Keys DELETEd because the doc no longer exists / no longer projects\n * them. In `dryRun` mode, the predicted DELETE count — no deletes\n * were issued.\n */\n readonly removed: number;\n /** Keys already in place. The healthy-index re-run reports this as the full expected count. */\n readonly kept: number;\n}\n\n/**\n * Optional knobs accepted by {@link rebuildIndex}. Every field is\n * optional; the function behaves identically to the older\n * positional-arg shape when `opts` is omitted.\n *\n * @public — surfaced from `baerly-storage` so admin tooling and the\n * observability layer can opt in.\n */\nexport interface RebuildIndexOptions {\n /**\n * Cancellation signal. Forwarded to every storage `list` call so\n * long-running rebuilds over large collections can be cut short\n * by admin tooling. Storage `get` / `put` / `delete` calls inside\n * the reconciliation loop do not currently honour the signal\n * (the per-call durations are short enough that cooperative\n * cancellation between calls suffices); future tightening can\n * forward it through without breaking callers.\n */\n readonly signal?: AbortSignal;\n /**\n * When `true`, walk the expected-vs-actual diff and return the\n * counts that a real rebuild would have produced WITHOUT issuing\n * any PUT or DELETE. Used by `baerly admin fsck --indexes`\n * to report drift cheaply. Defaults to `false`.\n *\n * `kept` is reported as the pre-existing intersection\n * (`expected ∩ actual`); a real run can additionally fold\n * Conflict-race-demoted PUTs into `kept`, which dryRun does not\n * observe. See {@link RebuildIndexResult}.\n */\n readonly dryRun?: boolean;\n}\n\n/**\n * Idempotently reconcile one secondary index for one collection.\n *\n * @param storage Storage handle (any in-tree `Storage`).\n * @param currentJsonKey The collection's `current.json` key.\n * @param def The index to reconcile. Single-field today;\n * composite definitions are accepted by the\n * key encoder but the read path only consults\n * single-field keys.\n * @param opts Optional knobs — see {@link RebuildIndexOptions}.\n * Strictly additive: existing positional-arg\n * callers compile and behave unchanged when\n * omitted.\n *\n * @throws BaerlyError code=\"InvalidResponse\" — `current.json` missing.\n * @throws BaerlyError code=\"Internal\" — protocol-invariant\n * violation (snapshot hash mismatch, missing log entry inside\n * `[log_seq_start, next_seq)`).\n */\nexport const rebuildIndex = async (\n storage: Storage,\n currentJsonKey: string,\n def: IndexDefinition,\n opts: RebuildIndexOptions = {},\n): Promise<RebuildIndexResult> => {\n const read = await readCurrentJson(storage, currentJsonKey);\n if (read === null) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `rebuildIndex: current.json missing at ${JSON.stringify(currentJsonKey)}`,\n );\n }\n const lastSlash = currentJsonKey.lastIndexOf(\"/\");\n if (lastSlash < 0) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `rebuildIndex: currentJsonKey ${JSON.stringify(currentJsonKey)} must contain \"/\"`,\n );\n }\n const collectionPrefix = currentJsonKey.slice(0, lastSlash);\n const collection = collectionPrefix.slice(collectionPrefix.lastIndexOf(\"/\") + 1);\n const logSeqStart = logSeqStartOf(read.json);\n const nextSeq = read.json.next_seq;\n\n // 1. Build the live doc set by folding snapshot + log tail.\n // Same shape the reader uses in `runRead` and the CLI uses in\n // `doCopy`.\n const live =\n read.json.snapshot === null\n ? new Map<string, DocumentData>()\n : await loadSnapshotAsMap(storage, read.json.snapshot, collection);\n const entries = await walkLogRange(storage, collectionPrefix, logSeqStart, nextSeq);\n foldLogEntriesOnto(live, entries, { collection });\n\n // 2. Compute the expected index-key set.\n const expected = new Set<string>();\n for (const [docId, body] of live) {\n for (const k of allIndexKeysFor(collectionPrefix, [def], body, docId)) {\n expected.add(k);\n }\n }\n\n // 3. List actual keys under the index prefix. Forward the abort\n // signal so admin tooling can cut short a rebuild over a huge\n // collection; the storage `list` contract is the only step\n // here that's unbounded in cost.\n const actual = new Set<string>();\n const listOpts: { signal?: AbortSignal } = {};\n if (opts.signal !== undefined) {\n listOpts.signal = opts.signal;\n }\n for await (const entry of storage.list(indexKeyPrefix(collectionPrefix, def.name), listOpts)) {\n actual.add(entry.key);\n }\n\n // 4. Reconcile: PUT what's missing, DELETE what's orphaned.\n // `ifNoneMatch:\"*\"` makes a same-key re-issue no-op; on the\n // rare race where the entry already exists, swallow the 412 and\n // count it as `kept` rather than `added`.\n //\n // Under `opts.dryRun`, we walk the same diff but skip every\n // mutating storage call — `added` / `removed` then report the\n // counts a real rebuild WOULD have produced, leaving storage\n // untouched. This is what `baerly admin fsck --indexes`\n // consumes to surface drift without paying the rebuild cost.\n const dryRun = opts.dryRun === true;\n let added = 0;\n let removed = 0;\n let kept = 0;\n for (const k of expected) {\n if (actual.has(k)) {\n kept += 1;\n continue;\n }\n if (dryRun) {\n added += 1;\n continue;\n }\n try {\n await storage.put(k, EMPTY_BODY, {\n ifNoneMatch: \"*\",\n contentType: APPLICATION_JSON,\n });\n added += 1;\n } catch (error) {\n // 412 = a peer wrote the entry between our `list` and our\n // PUT. The entry exists; we couldn't have written different\n // bytes (zero-byte body); count it as kept and move on.\n if (error instanceof BaerlyError && error.code === \"Conflict\") {\n kept += 1;\n } else {\n throw error;\n }\n }\n }\n for (const k of actual) {\n if (expected.has(k)) {\n continue;\n }\n if (dryRun) {\n removed += 1;\n continue;\n }\n // Storage.delete is contractually idempotent — no defensive catch.\n await storage.delete(k);\n removed += 1;\n }\n return { added, removed, kept };\n};\n","/**\n * `runScheduledMaintenance` — single-pass compose of `compact()` and\n * `runGc()` over one collection. Designed to fit a single Cloudflare\n * Cron Trigger invocation's 50-subrequest free-tier budget when\n * called with the {@link CLOUDFLARE_FREE_TIER} profile (which the\n * caller pairs with even/odd-minute alternation between compact and\n * GC ticks); unbounded on Node.\n *\n * Single-attempt: returns the combined result. The caller (cron\n * handler) is responsible for scheduling the next invocation; this\n * function does not loop or retry. `compact()` and `runGc()` are\n * already CAS-protected single-attempts — a restart safely retries\n * next tick.\n *\n * Callers that want only one phase to fire this tick should invoke\n * the underlying primitive directly (`compact()` or `runGc()` from\n * this same module's re-exports). The even/odd-minute CF cron\n * pattern uses exactly that.\n */\n\nimport { type Storage } from \"@baerly/protocol\";\nimport {\n compact,\n type CompactOptions,\n type CompactResult,\n type InternalCompactOptions,\n} from \"./compactor.ts\";\nimport { runGc, type InternalRunGcOptions, type RunGcOptions, type RunGcResult } from \"./gc.ts\";\n\nexport { type CompactOptions, type CompactResult, compact } from \"./compactor.ts\";\nexport { type RunGcOptions, type RunGcResult, runGc } from \"./gc.ts\";\nexport {\n type RebuildIndexOptions,\n type RebuildIndexResult,\n rebuildIndex,\n} from \"./rebuild-index.ts\";\n\nexport interface MaintenanceArgs {\n readonly storage: Storage;\n /** Full bucket-relative key of the CAS pointer for the target collection. */\n readonly currentJsonKey: string;\n}\n\nexport interface MaintenanceOptions {\n /** Forwarded to `compact()`. */\n readonly compact?: CompactOptions;\n /** Forwarded to `runGc()`. */\n readonly gc?: RunGcOptions;\n /** Forwarded to both primitives. */\n readonly signal?: AbortSignal;\n}\n\n/**\n * Internal-only widening of {@link MaintenanceOptions}. Surfaced via\n * the `@baerly/server/_internal/testing` subpath (NOT in the\n * published `publishConfig.exports`); production callers should use\n * {@link MaintenanceOptions}.\n *\n * @internal\n */\nexport interface InternalMaintenanceOptions extends MaintenanceOptions {\n /** @internal Internal compact options (budget caps). */\n readonly compact?: InternalCompactOptions;\n /** @internal Internal GC options (budget caps + clock seam + grace). */\n readonly gc?: InternalRunGcOptions;\n}\n\nexport interface MaintenanceResult {\n readonly compact: CompactResult;\n readonly gc: RunGcResult;\n}\n\n/**\n * Single maintenance pass for one collection. Runs `compact()` then\n * `runGc()` (in that order; the compactor's advance of\n * `log_seq_start` produces the stale-log candidates the GC then\n * marks). Callers wanting a single phase per tick invoke\n * `compact()` or `runGc()` directly instead.\n *\n * Errors propagate — the caller's cron handler is responsible for\n * logging them. The Cloudflare runtime ships uncaught Worker errors\n * to the dashboard; Node operators wrap their `node-cron` callbacks\n * themselves.\n *\n * @example\n * ```ts\n * import { runScheduledMaintenance, CLOUDFLARE_FREE_TIER } from \"@gusto/baerly-storage/maintenance\";\n *\n * // Node (unbounded — defaults fold the entire live tail):\n * const res = await runScheduledMaintenance(\n * { storage, currentJsonKey: \"app/x/tenant/t/manifests/tickets/current.json\" },\n * );\n * console.log(\"compacted:\", res.compact.entriesFolded, \"swept:\", res.gc.swept);\n *\n * // Cloudflare free tier (50-subrequest cap, single phase per tick):\n * await runScheduledMaintenance({ storage, currentJsonKey }, CLOUDFLARE_FREE_TIER);\n * ```\n */\nexport const runScheduledMaintenance = async (\n args: MaintenanceArgs,\n options: MaintenanceOptions = {},\n): Promise<MaintenanceResult> => {\n const compactRes = await compact(args, {\n ...options.compact,\n ...(options.signal !== undefined && { signal: options.signal }),\n });\n const gcRes = await runGc(args, {\n ...options.gc,\n ...(options.signal !== undefined && { signal: options.signal }),\n });\n return { compact: compactRes, gc: gcRes };\n};\n\n/**\n * Tuning profile for the 50-subrequest Cloudflare free-tier budget.\n *\n * Budget arithmetic (worst case):\n * compact: 1 GET current + 1 GET snapshot (if any) + N GETs log\n * + 1 PUT snapshot + 1 PUT current = 3 + N (N = maxEntriesPerRun).\n * runGc: 1 GET current + 1 GET pending + 3 LISTs (one page each)\n * + M GETs log (live tail for content hashes) + S DELETEs + 1 PUT\n * pending = 6 + M + S.\n *\n * With N=20, M=20, S=10 the totals are: compact ≈ 23, gc ≈ 36 — over\n * the 50 cap combined. The Cloudflare scheduled handler therefore\n * alternates phases per tick (even minute → compact, odd minute →\n * GC) by calling `compact()` / `runGc()` directly instead of\n * `runScheduledMaintenance`; the `maintenance.budget.test.ts`\n * worst-case test proves each phase in isolation sits under 50 ops\n * with these bounds.\n */\nconst cfFreeTier: InternalMaintenanceOptions = {\n compact: { maxEntriesPerRun: 20, minEntriesToCompact: 50 },\n gc: { maxMarksPerRun: 20, maxSweepsPerRun: 10 },\n};\nexport const CLOUDFLARE_FREE_TIER: MaintenanceOptions = cfFreeTier;\n"],"mappings":"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"}
|
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
import { d as IndexDefinition } from "./app-config-Cb5dO2s9.js";
|
|
2
|
+
import { m as Storage } from "./index-BGC-ENnj.js";
|
|
3
|
+
//#region packages/server/src/compactor.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* Public configuration knobs for {@link compact}. All optional; the
|
|
6
|
+
* engine works unbounded by default. Opt into a per-run cap via the
|
|
7
|
+
* `CLOUDFLARE_FREE_TIER` profile (from `./maintenance.ts`) or by
|
|
8
|
+
* reaching for {@link InternalCompactOptions} via the
|
|
9
|
+
* `@baerly/server/_internal/testing` subpath.
|
|
10
|
+
*/
|
|
11
|
+
interface CompactOptions {
|
|
12
|
+
/**
|
|
13
|
+
* Minimum log-tail length to compact. Skips work when there are
|
|
14
|
+
* fewer than this many live entries past the last snapshot.
|
|
15
|
+
* Default 100.
|
|
16
|
+
*/
|
|
17
|
+
readonly minEntriesToCompact?: number;
|
|
18
|
+
/** Optional AbortSignal forwarded to every storage call. */
|
|
19
|
+
readonly signal?: AbortSignal;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Internal-only widening of {@link CompactOptions}. Surfaced via the
|
|
23
|
+
* `@baerly/server/_internal/testing` subpath (NOT in the published
|
|
24
|
+
* `publishConfig.exports`); production callers should use
|
|
25
|
+
* {@link CompactOptions}.
|
|
26
|
+
*
|
|
27
|
+
* @internal
|
|
28
|
+
*/
|
|
29
|
+
interface InternalCompactOptions extends CompactOptions {
|
|
30
|
+
/**
|
|
31
|
+
* @internal Budget cap for the CF free-tier subrequest budget;
|
|
32
|
+
* `CLOUDFLARE_FREE_TIER` sets it. Tests also set it to exercise
|
|
33
|
+
* the cap path. The compactor's I/O profile is
|
|
34
|
+
* `maxEntriesPerRun + 3` subrequests (N GETs + 1 PUT snapshot +
|
|
35
|
+
* 1 GET current + 1 PUT current). The default is effectively
|
|
36
|
+
* unbounded (`Number.MAX_SAFE_INTEGER`).
|
|
37
|
+
*/
|
|
38
|
+
readonly maxEntriesPerRun?: number;
|
|
39
|
+
}
|
|
40
|
+
interface CompactResult {
|
|
41
|
+
/** `true` iff a new snapshot landed and `current.json` was advanced. */
|
|
42
|
+
readonly written: boolean;
|
|
43
|
+
/** Reason `written === false`. */
|
|
44
|
+
readonly skippedReason?: "below-min-threshold" | "current-json-missing" | "cas-lost";
|
|
45
|
+
/** Prior snapshot key (`null` if no prior snapshot existed). */
|
|
46
|
+
readonly previousSnapshotKey: string | null;
|
|
47
|
+
/** New snapshot key (`undefined` if `written === false` and no PUT happened). */
|
|
48
|
+
readonly newSnapshotKey?: string;
|
|
49
|
+
/** `log_seq_start` before the run. */
|
|
50
|
+
readonly logSeqStartBefore: number;
|
|
51
|
+
/** `log_seq_start` after the run. */
|
|
52
|
+
readonly logSeqStartAfter: number;
|
|
53
|
+
/** Number of log entries folded into the new snapshot. */
|
|
54
|
+
readonly entriesFolded: number;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Fold a prefix of the live log into a new snapshot and CAS-advance
|
|
58
|
+
* `current.json`. Idempotent: a second run with no new writes is a
|
|
59
|
+
* no-op (below-min-threshold).
|
|
60
|
+
*
|
|
61
|
+
* Single-attempt: on CAS conflict we return
|
|
62
|
+
* `{written: false, skippedReason: "cas-lost", newSnapshotKey}` — the
|
|
63
|
+
* caller (the cron handler invoking `runScheduledMaintenance` from
|
|
64
|
+
* `./maintenance.ts`) decides whether to schedule another run. The
|
|
65
|
+
* orphan snapshot file just written will be swept by `runGc()`.
|
|
66
|
+
*
|
|
67
|
+
* @throws BaerlyError code="InvalidResponse" — `current.json` is
|
|
68
|
+
* present but malformed, or a snapshot body fails its schema /
|
|
69
|
+
* collection cross-check.
|
|
70
|
+
* @throws BaerlyError code="Internal" — protocol-invariant violation:
|
|
71
|
+
* a log entry missing inside `[log_seq_start, foldEnd)`, or the
|
|
72
|
+
* prior-snapshot pointer resolves to no body / a body whose hash
|
|
73
|
+
* doesn't match its filename.
|
|
74
|
+
*
|
|
75
|
+
* @example
|
|
76
|
+
* ```ts
|
|
77
|
+
* import { compact } from "@gusto/baerly-storage";
|
|
78
|
+
*
|
|
79
|
+
* const res = await compact(
|
|
80
|
+
* { storage, currentJsonKey: "app/x/tenant/t/manifests/tickets/current.json" },
|
|
81
|
+
* { minEntriesToCompact: 100, maxEntriesPerRun: 40 },
|
|
82
|
+
* );
|
|
83
|
+
* if (res.written) console.log("snapshot landed at", res.newSnapshotKey);
|
|
84
|
+
* ```
|
|
85
|
+
*/
|
|
86
|
+
declare const compact: (args: {
|
|
87
|
+
storage: Storage; /** Full bucket-relative key of the CAS pointer. */
|
|
88
|
+
currentJsonKey: string;
|
|
89
|
+
}, options?: CompactOptions) => Promise<CompactResult>;
|
|
90
|
+
//#endregion
|
|
91
|
+
//#region packages/server/src/gc.d.ts
|
|
92
|
+
/**
|
|
93
|
+
* Public tunables for {@link runGc}. All optional; the engine works
|
|
94
|
+
* unbounded by default. Opt into per-run caps via the
|
|
95
|
+
* `CLOUDFLARE_FREE_TIER` profile (from `./maintenance.ts`) or by
|
|
96
|
+
* reaching for {@link InternalRunGcOptions} via the
|
|
97
|
+
* `@baerly/server/_internal/testing` subpath.
|
|
98
|
+
*/
|
|
99
|
+
interface RunGcOptions {
|
|
100
|
+
readonly signal?: AbortSignal;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Internal-only widening of {@link RunGcOptions}. Surfaced via the
|
|
104
|
+
* `@baerly/server/_internal/testing` subpath (NOT in the published
|
|
105
|
+
* `publishConfig.exports`); production callers should use
|
|
106
|
+
* {@link RunGcOptions}.
|
|
107
|
+
*
|
|
108
|
+
* @internal
|
|
109
|
+
*/
|
|
110
|
+
interface InternalRunGcOptions extends RunGcOptions {
|
|
111
|
+
/**
|
|
112
|
+
* @internal Override grace-period for tests. Defaults to
|
|
113
|
+
* {@link GC_GRACE_PERIOD_MILLIS} (7 days). Tests use `0` to bypass
|
|
114
|
+
* the grace and exercise the sweep path in one pass.
|
|
115
|
+
*/
|
|
116
|
+
readonly graceMillis?: number;
|
|
117
|
+
/**
|
|
118
|
+
* @internal Budget cap on candidates marked per category per run.
|
|
119
|
+
* `CLOUDFLARE_FREE_TIER` sets it; bounds LIST + classification
|
|
120
|
+
* cost per pass. The default is effectively unbounded
|
|
121
|
+
* (`Number.MAX_SAFE_INTEGER`).
|
|
122
|
+
*/
|
|
123
|
+
readonly maxMarksPerRun?: number;
|
|
124
|
+
/**
|
|
125
|
+
* @internal Budget cap on keys deleted per run.
|
|
126
|
+
* `CLOUDFLARE_FREE_TIER` sets it — CF free-tier safe when paired
|
|
127
|
+
* with `compact()` in the same scheduled handler. The default is
|
|
128
|
+
* effectively unbounded (`Number.MAX_SAFE_INTEGER`).
|
|
129
|
+
*/
|
|
130
|
+
readonly maxSweepsPerRun?: number;
|
|
131
|
+
/**
|
|
132
|
+
* @internal Clock injection for tests. Defaults to
|
|
133
|
+
* `() => new Date()`. The function is invoked at mark time (to
|
|
134
|
+
* compute `due_at` when `lastModified` is absent) and at sweep
|
|
135
|
+
* time (to compare against candidate `due_at`).
|
|
136
|
+
*/
|
|
137
|
+
readonly now?: () => Date;
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Return shape of {@link runGc}.
|
|
141
|
+
*/
|
|
142
|
+
interface RunGcResult {
|
|
143
|
+
/** Per-category counts of newly-marked candidates in this pass. */
|
|
144
|
+
readonly marked: {
|
|
145
|
+
readonly stale_log: number;
|
|
146
|
+
readonly orphan_snapshot: number;
|
|
147
|
+
readonly orphan_content: number;
|
|
148
|
+
};
|
|
149
|
+
/** Number of keys deleted in this pass. */
|
|
150
|
+
readonly swept: number;
|
|
151
|
+
/**
|
|
152
|
+
* Depth of `gc/pending.json` after this pass. Drives the
|
|
153
|
+
* `db.orphan.candidate_count` metric. Best-effort on `cas-lost` —
|
|
154
|
+
* see module JSDoc.
|
|
155
|
+
*/
|
|
156
|
+
readonly pendingDepth: number;
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* Single GC pass — mark new orphans, sweep due-elapsed candidates,
|
|
160
|
+
* persist via CAS-update on `gc/pending.json`.
|
|
161
|
+
*
|
|
162
|
+
* Returns immediately if `current.json` is missing — there's nothing
|
|
163
|
+
* to do until a writer has bootstrapped the collection.
|
|
164
|
+
*
|
|
165
|
+
* @example
|
|
166
|
+
* ```ts
|
|
167
|
+
* import { runGc } from "@gusto/baerly-storage";
|
|
168
|
+
*
|
|
169
|
+
* const r = await runGc({ storage, currentJsonKey });
|
|
170
|
+
* console.log(`marked ${r.marked.stale_log} stale logs, swept ${r.swept}`);
|
|
171
|
+
* ```
|
|
172
|
+
*/
|
|
173
|
+
declare const runGc: (args: {
|
|
174
|
+
storage: Storage;
|
|
175
|
+
currentJsonKey: string;
|
|
176
|
+
}, options?: RunGcOptions) => Promise<RunGcResult>;
|
|
177
|
+
//#endregion
|
|
178
|
+
//#region packages/server/src/rebuild-index.d.ts
|
|
179
|
+
/**
|
|
180
|
+
* Reconciliation summary.
|
|
181
|
+
*
|
|
182
|
+
* In a normal (mutating) run, the counts describe what was actually
|
|
183
|
+
* PUT / DELETEd. In `dryRun` mode ({@link RebuildIndexOptions.dryRun}),
|
|
184
|
+
* `added` / `removed` report the counts that a real rebuild *would*
|
|
185
|
+
* have produced — storage is unchanged. `kept` counts pre-existing
|
|
186
|
+
* intersection keys (`expected ∩ actual`) at function entry. In a real
|
|
187
|
+
* run, `kept` may also include keys promoted from `added` via the
|
|
188
|
+
* Conflict-race fallback (a PUT with `ifNoneMatch:"*"` returned 412
|
|
189
|
+
* because a peer wrote the same key first, so the key was already
|
|
190
|
+
* in place by the time we observed it); dryRun mode never issues
|
|
191
|
+
* those PUTs and therefore does not observe that race.
|
|
192
|
+
*/
|
|
193
|
+
interface RebuildIndexResult {
|
|
194
|
+
/**
|
|
195
|
+
* Keys PUT because they were missing on storage. In `dryRun` mode,
|
|
196
|
+
* the predicted PUT count — no writes were issued.
|
|
197
|
+
*/
|
|
198
|
+
readonly added: number;
|
|
199
|
+
/**
|
|
200
|
+
* Keys DELETEd because the doc no longer exists / no longer projects
|
|
201
|
+
* them. In `dryRun` mode, the predicted DELETE count — no deletes
|
|
202
|
+
* were issued.
|
|
203
|
+
*/
|
|
204
|
+
readonly removed: number;
|
|
205
|
+
/** Keys already in place. The healthy-index re-run reports this as the full expected count. */
|
|
206
|
+
readonly kept: number;
|
|
207
|
+
}
|
|
208
|
+
/**
|
|
209
|
+
* Optional knobs accepted by {@link rebuildIndex}. Every field is
|
|
210
|
+
* optional; the function behaves identically to the older
|
|
211
|
+
* positional-arg shape when `opts` is omitted.
|
|
212
|
+
*
|
|
213
|
+
* @public — surfaced from `baerly-storage` so admin tooling and the
|
|
214
|
+
* observability layer can opt in.
|
|
215
|
+
*/
|
|
216
|
+
interface RebuildIndexOptions {
|
|
217
|
+
/**
|
|
218
|
+
* Cancellation signal. Forwarded to every storage `list` call so
|
|
219
|
+
* long-running rebuilds over large collections can be cut short
|
|
220
|
+
* by admin tooling. Storage `get` / `put` / `delete` calls inside
|
|
221
|
+
* the reconciliation loop do not currently honour the signal
|
|
222
|
+
* (the per-call durations are short enough that cooperative
|
|
223
|
+
* cancellation between calls suffices); future tightening can
|
|
224
|
+
* forward it through without breaking callers.
|
|
225
|
+
*/
|
|
226
|
+
readonly signal?: AbortSignal;
|
|
227
|
+
/**
|
|
228
|
+
* When `true`, walk the expected-vs-actual diff and return the
|
|
229
|
+
* counts that a real rebuild would have produced WITHOUT issuing
|
|
230
|
+
* any PUT or DELETE. Used by `baerly admin fsck --indexes`
|
|
231
|
+
* to report drift cheaply. Defaults to `false`.
|
|
232
|
+
*
|
|
233
|
+
* `kept` is reported as the pre-existing intersection
|
|
234
|
+
* (`expected ∩ actual`); a real run can additionally fold
|
|
235
|
+
* Conflict-race-demoted PUTs into `kept`, which dryRun does not
|
|
236
|
+
* observe. See {@link RebuildIndexResult}.
|
|
237
|
+
*/
|
|
238
|
+
readonly dryRun?: boolean;
|
|
239
|
+
}
|
|
240
|
+
/**
|
|
241
|
+
* Idempotently reconcile one secondary index for one collection.
|
|
242
|
+
*
|
|
243
|
+
* @param storage Storage handle (any in-tree `Storage`).
|
|
244
|
+
* @param currentJsonKey The collection's `current.json` key.
|
|
245
|
+
* @param def The index to reconcile. Single-field today;
|
|
246
|
+
* composite definitions are accepted by the
|
|
247
|
+
* key encoder but the read path only consults
|
|
248
|
+
* single-field keys.
|
|
249
|
+
* @param opts Optional knobs — see {@link RebuildIndexOptions}.
|
|
250
|
+
* Strictly additive: existing positional-arg
|
|
251
|
+
* callers compile and behave unchanged when
|
|
252
|
+
* omitted.
|
|
253
|
+
*
|
|
254
|
+
* @throws BaerlyError code="InvalidResponse" — `current.json` missing.
|
|
255
|
+
* @throws BaerlyError code="Internal" — protocol-invariant
|
|
256
|
+
* violation (snapshot hash mismatch, missing log entry inside
|
|
257
|
+
* `[log_seq_start, next_seq)`).
|
|
258
|
+
*/
|
|
259
|
+
declare const rebuildIndex: (storage: Storage, currentJsonKey: string, def: IndexDefinition, opts?: RebuildIndexOptions) => Promise<RebuildIndexResult>;
|
|
260
|
+
//#endregion
|
|
261
|
+
//#region packages/server/src/maintenance.d.ts
|
|
262
|
+
interface MaintenanceArgs {
|
|
263
|
+
readonly storage: Storage;
|
|
264
|
+
/** Full bucket-relative key of the CAS pointer for the target collection. */
|
|
265
|
+
readonly currentJsonKey: string;
|
|
266
|
+
}
|
|
267
|
+
interface MaintenanceOptions {
|
|
268
|
+
/** Forwarded to `compact()`. */
|
|
269
|
+
readonly compact?: CompactOptions;
|
|
270
|
+
/** Forwarded to `runGc()`. */
|
|
271
|
+
readonly gc?: RunGcOptions;
|
|
272
|
+
/** Forwarded to both primitives. */
|
|
273
|
+
readonly signal?: AbortSignal;
|
|
274
|
+
}
|
|
275
|
+
/**
|
|
276
|
+
* Internal-only widening of {@link MaintenanceOptions}. Surfaced via
|
|
277
|
+
* the `@baerly/server/_internal/testing` subpath (NOT in the
|
|
278
|
+
* published `publishConfig.exports`); production callers should use
|
|
279
|
+
* {@link MaintenanceOptions}.
|
|
280
|
+
*
|
|
281
|
+
* @internal
|
|
282
|
+
*/
|
|
283
|
+
interface InternalMaintenanceOptions extends MaintenanceOptions {
|
|
284
|
+
/** @internal Internal compact options (budget caps). */
|
|
285
|
+
readonly compact?: InternalCompactOptions;
|
|
286
|
+
/** @internal Internal GC options (budget caps + clock seam + grace). */
|
|
287
|
+
readonly gc?: InternalRunGcOptions;
|
|
288
|
+
}
|
|
289
|
+
interface MaintenanceResult {
|
|
290
|
+
readonly compact: CompactResult;
|
|
291
|
+
readonly gc: RunGcResult;
|
|
292
|
+
}
|
|
293
|
+
/**
|
|
294
|
+
* Single maintenance pass for one collection. Runs `compact()` then
|
|
295
|
+
* `runGc()` (in that order; the compactor's advance of
|
|
296
|
+
* `log_seq_start` produces the stale-log candidates the GC then
|
|
297
|
+
* marks). Callers wanting a single phase per tick invoke
|
|
298
|
+
* `compact()` or `runGc()` directly instead.
|
|
299
|
+
*
|
|
300
|
+
* Errors propagate — the caller's cron handler is responsible for
|
|
301
|
+
* logging them. The Cloudflare runtime ships uncaught Worker errors
|
|
302
|
+
* to the dashboard; Node operators wrap their `node-cron` callbacks
|
|
303
|
+
* themselves.
|
|
304
|
+
*
|
|
305
|
+
* @example
|
|
306
|
+
* ```ts
|
|
307
|
+
* import { runScheduledMaintenance, CLOUDFLARE_FREE_TIER } from "@gusto/baerly-storage/maintenance";
|
|
308
|
+
*
|
|
309
|
+
* // Node (unbounded — defaults fold the entire live tail):
|
|
310
|
+
* const res = await runScheduledMaintenance(
|
|
311
|
+
* { storage, currentJsonKey: "app/x/tenant/t/manifests/tickets/current.json" },
|
|
312
|
+
* );
|
|
313
|
+
* console.log("compacted:", res.compact.entriesFolded, "swept:", res.gc.swept);
|
|
314
|
+
*
|
|
315
|
+
* // Cloudflare free tier (50-subrequest cap, single phase per tick):
|
|
316
|
+
* await runScheduledMaintenance({ storage, currentJsonKey }, CLOUDFLARE_FREE_TIER);
|
|
317
|
+
* ```
|
|
318
|
+
*/
|
|
319
|
+
declare const runScheduledMaintenance: (args: MaintenanceArgs, options?: MaintenanceOptions) => Promise<MaintenanceResult>;
|
|
320
|
+
declare const CLOUDFLARE_FREE_TIER: MaintenanceOptions;
|
|
321
|
+
//#endregion
|
|
322
|
+
export { CLOUDFLARE_FREE_TIER, type CompactOptions, type CompactResult, InternalMaintenanceOptions, MaintenanceArgs, MaintenanceOptions, MaintenanceResult, type RebuildIndexOptions, type RebuildIndexResult, type RunGcOptions, type RunGcResult, compact, rebuildIndex, runGc, runScheduledMaintenance };
|
|
323
|
+
//# sourceMappingURL=maintenance.d.ts.map
|