The best way to control Claude Code, Codex and more from any computer or phone

main
ts 124 lines 5.05 KB
Raw
1 /**
2 * R2 key scheme (DESIGN.md §3.2).
3 *
4 * All R2 keys are **immutable and content-addressed** — this sidesteps the
5 * 1-write/s/key limit, makes conditional-put re-runs (idempotent alarm jobs)
6 * safe, and makes cross-repo fork references safe: a fork's `objects.r2_key`
7 * may point into the parent repo's prefix, since the bytes at a key never
8 * change once written.
9 *
10 * ```
11 * {repoId}/objects/{oid} oversize loose objects, zlib(content)
12 * {repoId}/packs/pack-{sha1}.pack v1.1 compaction output
13 * {repoId}/incoming/{pushId}.pack v1.x streaming-push tee (reserved)
14 * {repoId}/lfs/{sha256} LFS objects (reserved)
15 * ```
16 *
17 * `list()` is never used on a hot path — the `objects` table is the sole
18 * inventory. The prefix helpers exist for the delete-purge and GC alarm jobs
19 * only.
20 */
21
22 /**
23 * R2 key for an oversize loose object: `{repoId}/objects/{oid}`.
24 *
25 * The stored bytes are `zlib(content)` without the loose header — byte-equal
26 * to what an `objects.location = 'row'` row would hold in `zdata`.
27 */
28 export const objectKey = (repoId: string, oid: string): string => `${repoId}/objects/${oid}`;
29
30 /**
31 * R2 key for a compacted pack (v1.1): `{repoId}/packs/pack-{sha1}.pack`.
32 * The `sha1` is the pack's trailer checksum, making the key content-addressed.
33 */
34 export const packKey = (repoId: string, sha: string): string => `${repoId}/packs/pack-${sha}.pack`;
35
36 /**
37 * R2 key of a clone bundle for a ref snapshot (DESIGN.md §12.2):
38 * `{repoId}/bundles/bundle-{refsHash}.pack`. Immutable and
39 * content-addressed by the refs it covers, so it is safe to cache at the
40 * edge and safe to write concurrently.
41 */
42 export const bundleKey = (repoId: string, refsHash: string): string =>
43 `${repoId}/bundles/bundle-${refsHash}.pack`;
44
45 /**
46 * The bundle's **pre-framed** twin (DESIGN §22.4): the same pack already
47 * cut into band-1 sideband frames of exactly 65515 data bytes. Real git
48 * always negotiates `side-band-64k`, and bytes that cross into JS to be
49 * framed measured a hard ~15 MiB/s ceiling regardless of how the framing
50 * was written; this twin lets the sideband case be a platform-to-platform
51 * pipe like the raw case. Written alongside the bundle, immutable, same
52 * lifecycle (purged with the prefix).
53 */
54 export const bundleSidebandKey = (repoId: string, refsHash: string): string =>
55 `${repoId}/bundles/bundle-${refsHash}.sideband`;
56
57 /**
58 * R2 key for a streamed incoming push pack (v1.x upgrade seam, DESIGN.md
59 * §3.6): `{repoId}/incoming/{pushId}.pack`. Reserved — unused in v1's
60 * buffered ingest.
61 */
62 export const incomingKey = (repoId: string, pushId: string): string =>
63 `${repoId}/incoming/${pushId}.pack`;
64
65 /**
66 * Pack-id prefix of a **promoted wire pack** (DESIGN §22.5): a push whose
67 * body spilled to blob storage already holds every non-delta blob in the
68 * compaction layout (`typeSize header + zdata`), so ingest points those
69 * rows straight into the incoming object instead of copying 40 MiB of
70 * blobs through SQLite and compacting them out again later. The pack id
71 * is `wire-<receiveId>`; the object stays at its `incomingKey`.
72 */
73 export const WIRE_PACK_PREFIX = "wire-";
74 export const wirePackId = (receiveId: string): string => `${WIRE_PACK_PREFIX}${receiveId}`;
75 export const isWirePackId = (packId: string): boolean => packId.startsWith(WIRE_PACK_PREFIX);
76
77 /** R2 key of any pack by id — compacted (`packKey`) or promoted wire pack. */
78 export const packKeyOf = (repoId: string, packId: string): string =>
79 isWirePackId(packId)
80 ? incomingKey(repoId, packId.slice(WIRE_PACK_PREFIX.length))
81 : packKey(repoId, packId);
82
83 /**
84 * R2 key reserved for a future LFS object (DESIGN.md §10):
85 * `{repoId}/lfs/{sha256}`.
86 */
87 export const lfsKey = (repoId: string, sha256: string): string => `${repoId}/lfs/${sha256}`;
88
89 /**
90 * The whole-repo R2 prefix (`{repoId}/`) — the unit the delete-purge alarm
91 * job lists and deletes (retained while the Registry reports
92 * `fork_count > 0`, since forks reference keys under it).
93 */
94 export const repoPrefix = (repoId: string): string => `${repoId}/`;
95
96 /**
97 * Prefix of all oversize loose objects for a repo: `{repoId}/objects/`.
98 */
99 export const objectsPrefix = (repoId: string): string => `${repoId}/objects/`;
100
101 /**
102 * Prefix of all compacted packs for a repo (v1.1): `{repoId}/packs/`.
103 */
104 export const packsPrefix = (repoId: string): string => `${repoId}/packs/`;
105
106 /**
107 * Prefix of all in-flight streamed push packs for a repo (reserved):
108 * `{repoId}/incoming/`.
109 */
110 export const incomingPrefix = (repoId: string): string => `${repoId}/incoming/`;
111
112 /**
113 * Prefix of all LFS objects for a repo (reserved): `{repoId}/lfs/`.
114 */
115 export const lfsPrefix = (repoId: string): string => `${repoId}/lfs/`;
116
117 /**
118 * R2 key of a repo's head snapshot (DESIGN.md §21): a small JSON object
119 * describing the current refs, visibility, and clone bundle, written by
120 * the Repo DO after every mutation commit. Lets the Worker serve
121 * anonymous public reads (advertisement + bundle clones) without waking
122 * the DO. Lives under the repo prefix so purge drains it.
123 */
124 export const headKey = (repoId: string): string => `${repoId}/head`;