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

main
ts 496 lines 19.7 KB
Raw
1 /**
2 * The singleton Registry Durable Object (DESIGN.md §2.1, §3.1).
3 *
4 * The Registry is the control-plane authority for the `owner/name → repoId`
5 * mapping: uniqueness CAS at creation, the listing surface, and the
6 * fork-lineage ledger (`fork_of`, `fork_count`). It is addressed as a
7 * singleton via `getByName(REGISTRY_DO_NAME)`; the sharding seam
8 * (`getByName("registry:" + owner)`) changes no RPC interface.
9 *
10 * Repo ids are ULIDs minted here at creation — **not** `owner/name` — so
11 * renames never move data and a deleted-then-recreated name gets a fresh
12 * Repo DO (no zombie state).
13 *
14 * ### Resolving a repo
15 * **Example:** Worker-side lookup
16 * ```typescript
17 * const registry = yield* Registry;
18 * const entry = yield* registry.getByName(REGISTRY_DO_NAME).resolve("acme", "web");
19 * if (entry === undefined) return yield* new RepoNotFound({ owner: "acme", repo: "web" });
20 * ```
21 */
22 import * as Cloudflare from "@alchemy.run/cloudflare";
23 import type { RuntimeContext } from "alchemy/RuntimeContext";
24 import * as Context from "effect/Context";
25 import * as Effect from "effect/Effect";
26 import * as Layer from "effect/Layer";
27 import { RepoAlreadyExists, ValidationError } from "./Api.ts";
28 import { StoreError } from "./Protocol/Store.ts";
29 import { initRegistrySchema, makeSqlClient, type RegistryRepoRow } from "./Store/Sql.ts";
30
31 // ─────────────────────────────────────────────────────────────────────────────
32 // ULID
33 // ─────────────────────────────────────────────────────────────────────────────
34
35 /** Crockford base32 alphabet used by ULIDs. */
36 const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
37
38 /**
39 * Mints a ULID (48-bit millisecond timestamp + 80 random bits, Crockford
40 * base32, 26 chars). Used for repo ids, token ids, and push ids —
41 * lexicographically sortable by creation time and safe as an R2 key prefix.
42 */
43 export const ulid = (): Effect.Effect<string> =>
44 Effect.sync(() => {
45 let time = Date.now();
46 const chars = Array.from({ length: 26 }, () => "0");
47 // 10 chars of time, most-significant first
48 for (let i = 9; i >= 0; i--) {
49 chars[i] = CROCKFORD[time % 32]!;
50 time = Math.floor(time / 32);
51 }
52 const rand = crypto.getRandomValues(new Uint8Array(16));
53 // 16 chars of randomness, 5 bits each from a fresh random byte
54 for (let i = 0; i < 16; i++) {
55 chars[10 + i] = CROCKFORD[rand[i]! % 32]!;
56 }
57 return chars.join("");
58 });
59
60 // ─────────────────────────────────────────────────────────────────────────────
61 // Contract
62 // ─────────────────────────────────────────────────────────────────────────────
63
64 /**
65 * The singleton Registry instance name: `registry.getByName(REGISTRY_DO_NAME)`.
66 */
67 export const REGISTRY_DO_NAME = "registry" as const;
68
69 /**
70 * The reserved owner name — `/api/v1/**` must never collide with a repo URL,
71 * so the Registry rejects `api` at creation (DESIGN.md §2.2).
72 */
73 export const RESERVED_OWNERS: ReadonlySet<string> = new Set(["api"]);
74
75 /** One registry row, as returned over RPC (plain serializable data). */
76 export interface RegistryEntry {
77 readonly owner: string;
78 readonly name: string;
79 readonly repoId: string;
80 readonly description: string | null;
81 /** Parent repoId when this repo is a fork, else `null`. */
82 readonly forkOf: string | null;
83 /** Live forks referencing this repo's R2 prefix. */
84 readonly forkCount: number;
85 /** Epoch milliseconds. */
86 readonly createdAt: number;
87 /** Anyone can read/clone without a token (GitHub public-repo model). */
88 readonly public: boolean;
89 /** Soft-delete marker set while the purge alarm runs, else `null`. */
90 readonly deletedAt: number | null;
91 /**
92 * Denormalised display fields, pushed by the Repo DO on change so
93 * `repos.list` renders a page without waking one DO per row
94 * (DESIGN.md §15 bottleneck 7). The DO stays the source of truth.
95 */
96 readonly defaultBranch: string;
97 readonly readOnly: boolean;
98 readonly status: string;
99 }
100
101 /** Summary fields the Repo DO pushes to the Registry when they change. */
102 export interface RepoSummary {
103 readonly defaultBranch: string;
104 readonly readOnly: boolean;
105 /** Anyone can read/clone without a token (GitHub public-repo model). */
106 readonly public: boolean;
107 readonly status: string;
108 }
109
110 /** Input of {@link RegistryShape.createRepo}. */
111 export interface CreateRepoInput {
112 readonly owner: string;
113 readonly name: string;
114 readonly description?: string | undefined;
115 /** Anyone can read/clone without a token when `true`. */
116 readonly public?: boolean | undefined;
117 /** Parent repoId when creating a fork target row. */
118 readonly forkOf?: string | undefined;
119 }
120
121 /** Input of {@link RegistryShape.list}. */
122 export interface ListReposInput {
123 readonly owner?: string | undefined;
124 readonly cursor?: string | undefined;
125 readonly limit?: number | undefined;
126 /** Restrict to public repos — the anonymous/non-admin listing. */
127 readonly publicOnly?: boolean | undefined;
128 }
129
130 /** Result page of {@link RegistryShape.list}. */
131 export interface ListReposResult {
132 readonly items: ReadonlyArray<RegistryEntry>;
133 readonly nextCursor: string | null;
134 readonly hasMore: boolean;
135 }
136
137 /**
138 * The Registry DO's typed RPC surface. Note the platform gotcha: no method
139 * may be named `delete` (reserved by Cloudflare's RPC stub proxy) — row
140 * removal is `removeRow`.
141 */
142 export interface RegistryShape {
143 /**
144 * Uniqueness-CAS insert of a new repo row; mints the repoId ULID.
145 * Rejects reserved owners with {@link ValidationError} and existing
146 * `owner/name` rows (including rows still purging) with
147 * {@link RepoAlreadyExists}. When `forkOf` is given, the parent's
148 * `fork_count` is bumped in the same transaction.
149 */
150 readonly createRepo: (
151 input: CreateRepoInput,
152 ) => Effect.Effect<
153 RegistryEntry,
154 RepoAlreadyExists | ValidationError | StoreError,
155 RuntimeContext
156 >;
157 /** Looks up a live (non-deleted) row, or `undefined`. */
158 readonly resolve: (
159 owner: string,
160 name: string,
161 ) => Effect.Effect<RegistryEntry | undefined, StoreError, RuntimeContext>;
162 /** Cursor-paginated listing of live rows, optionally filtered by owner. */
163 readonly list: (
164 input: ListReposInput,
165 ) => Effect.Effect<ListReposResult, StoreError, RuntimeContext>;
166 /**
167 * Records a new fork of `parentRepoId` (`fork_count + 1`). Equivalent to
168 * `bumpForkCount(parentRepoId, 1)`; kept as its own verb for call-site
169 * clarity.
170 */
171 readonly recordFork: (parentRepoId: string) => Effect.Effect<number, StoreError, RuntimeContext>;
172 /**
173 * Adjusts a repo's `fork_count` by `delta` (may be 0 to read) and returns
174 * the new value. The delete-purge job polls this: the parent's R2 prefix
175 * is retained while the count is positive (DESIGN.md §2.3 Delete).
176 */
177 readonly bumpForkCount: (
178 repoId: string,
179 delta: number,
180 ) => Effect.Effect<number, StoreError, RuntimeContext>;
181 /**
182 * Soft-deletes a row (sets `deleted_at`); the name stays reserved until
183 * {@link RegistryShape.removeRow} after the purge completes.
184 */
185 readonly markDeleted: (repoId: string) => Effect.Effect<void, StoreError, RuntimeContext>;
186 /**
187 * Hard-removes a row after purge — the last step of repo deletion, which
188 * frees the `owner/name` for reuse. Also decrements the fork parent's
189 * `fork_count` when the removed repo was a fork.
190 */
191 readonly removeRow: (repoId: string) => Effect.Effect<void, StoreError, RuntimeContext>;
192 /**
193 * Refreshes the denormalised display fields for a repo. Called by the
194 * Repo DO whenever they change (create, metadata update, status
195 * transition), so listing never has to consult the DO.
196 */
197 readonly updateSummary: (
198 repoId: string,
199 summary: RepoSummary,
200 ) => Effect.Effect<void, StoreError, RuntimeContext>;
201 }
202
203 // ─────────────────────────────────────────────────────────────────────────────
204 // Implementation
205 // ─────────────────────────────────────────────────────────────────────────────
206
207 export const toEntry = (row: RegistryRepoRow): RegistryEntry => ({
208 owner: row.owner,
209 name: row.name,
210 repoId: row.repo_id,
211 description: row.description,
212 forkOf: row.fork_of,
213 forkCount: row.fork_count,
214 createdAt: row.created_at,
215 deletedAt: row.deleted_at,
216 defaultBranch: row.default_branch,
217 readOnly: row.read_only === 1,
218 public: row.is_public === 1,
219 status: row.status,
220 });
221
222 /** Encodes/decodes the opaque list cursor: base64url of `owner\0name`. */
223 export const encodeCursor = (owner: string, name: string): string =>
224 Buffer.from(`${owner}\0${name}`, "utf8").toString("base64url");
225 export const decodeCursor = (
226 cursor: string,
227 ): readonly [owner: string, name: string] | undefined => {
228 try {
229 const text = Buffer.from(cursor, "base64url").toString("utf8");
230 const sep = text.indexOf("\0");
231 if (sep === -1) return undefined;
232 return [text.slice(0, sep), text.slice(sep + 1)];
233 } catch {
234 return undefined;
235 }
236 };
237
238 /** Default / maximum page size of {@link RegistryShape.list}. */
239 export const DEFAULT_LIST_LIMIT = 50;
240
241 /**
242 * The singleton Registry Durable Object class (modular form — the runtime
243 * implementation lives in {@link RegistryLive}, provided by `GitWorker`).
244 */
245 export class Registry extends Cloudflare.DurableObject<Registry, RegistryShape>()("GitRegistry", {
246 // RPC-boundary error revival (see `DurableObjectProps.errors`).
247 errors: [RepoAlreadyExists, ValidationError, StoreError],
248 }) {}
249
250 /**
251 * `Git.RegistryStore` — the repo *index* as a swappable block: the
252 * `owner/name -> repoId` mapping, uniqueness, and listing.
253 *
254 * The rest of the service depends on this contract, never on a
255 * particular backend, so the index can be chosen at assembly:
256 *
257 * - {@link RegistryDurableObject} — one Durable Object. Zero extra
258 * infrastructure, and the strongest consistency (a single-threaded
259 * `transactionSync` makes create a true CAS). It is also one object
260 * for the whole service, so reads funnel through a single thread in a
261 * single region.
262 * - `Git.RegistryD1` — a D1 database. Reads scale out (D1 replicates
263 * them) and `WHERE owner = ?` listing is what a relational store is
264 * for; uniqueness comes from the `PRIMARY KEY (owner, name)` instead
265 * of from single-threading.
266 *
267 * Both satisfy {@link RegistryShape} exactly, so swapping is one line in
268 * the layer graph.
269 *
270 * @binding
271 */
272 export class RegistryStore extends Context.Service<RegistryStore, RegistryShape>()(
273 "alchemy/Git/RegistryStore",
274 ) {}
275
276 /**
277 * The Registry DO implementation Layer. Provide on the hosting Worker's
278 * init effect (`Effect.provide(RegistryLive)`).
279 */
280 export const RegistryLive = Registry.make(
281 Effect.gen(function* () {
282 const state = yield* Cloudflare.DurableObjectState;
283
284 return Effect.gen(function* () {
285 const sql = makeSqlClient(state);
286 // Constructor effects cannot fail — schema init failure is a defect.
287 yield* initRegistrySchema(sql).pipe(Effect.orDie);
288
289 const shape: RegistryShape = {
290 createRepo: Effect.fn(function* (input: CreateRepoInput) {
291 const owner = input.owner.toLowerCase();
292 const name = input.name.toLowerCase();
293 if (RESERVED_OWNERS.has(owner)) {
294 return yield* ValidationError.make({
295 message: `owner name '${owner}' is reserved`,
296 });
297 }
298 const repoId = yield* ulid();
299 const createdAt = Date.now();
300 // The DO's single-threaded event loop + transactionSync make the
301 // exists-check + insert a real CAS.
302 return yield* sql.transactionSync<RegistryEntry, RepoAlreadyExists>((raw, rollback) => {
303 const existing = raw
304 .exec<RegistryRepoRow>(
305 `SELECT * FROM repos WHERE owner = ? AND name = ?`,
306 owner,
307 name,
308 )
309 .toArray();
310 if (existing.length > 0) {
311 // Includes soft-deleted rows: the name frees only after purge.
312 rollback(RepoAlreadyExists.make({ owner, repo: name }));
313 }
314 raw.exec(
315 `INSERT INTO repos (owner, name, repo_id, description, is_public, fork_of, fork_count, created_at, deleted_at)
316 VALUES (?, ?, ?, ?, ?, ?, 0, ?, NULL)`,
317 owner,
318 name,
319 repoId,
320 input.description ?? null,
321 input.public === true ? 1 : 0,
322 input.forkOf ?? null,
323 createdAt,
324 );
325 if (input.forkOf !== undefined) {
326 raw.exec(
327 `UPDATE repos SET fork_count = fork_count + 1 WHERE repo_id = ?`,
328 input.forkOf,
329 );
330 }
331 return {
332 owner,
333 name,
334 repoId,
335 defaultBranch: "main",
336 readOnly: false,
337 public: input.public === true,
338 status: "ready",
339 description: input.description ?? null,
340 forkOf: input.forkOf ?? null,
341 forkCount: 0,
342 createdAt,
343 deletedAt: null,
344 } satisfies RegistryEntry;
345 });
346 }),
347
348 resolve: Effect.fn(function* (owner: string, name: string) {
349 // Soft-deleted rows ARE returned (with `deletedAt` set): the name
350 // stays reserved until the purge alarm calls `removeRow`, and the
351 // Worker needs to see the in-flight deletion to report
352 // `status: "deleting"` on GET (instead of a premature 404 that
353 // would race re-creates against the purge).
354 const row = yield* sql.first<RegistryRepoRow>(
355 `SELECT * FROM repos WHERE owner = ? AND name = ?`,
356 owner.toLowerCase(),
357 name.toLowerCase(),
358 );
359 return row === undefined ? undefined : toEntry(row);
360 }),
361
362 list: Effect.fn(function* (input: ListReposInput) {
363 const limit = Math.max(1, Math.min(input.limit ?? DEFAULT_LIST_LIMIT, 100));
364 const after = input.cursor === undefined ? undefined : decodeCursor(input.cursor);
365 const conditions: Array<string> = ["deleted_at IS NULL"];
366 const bindings: Array<string | number> = [];
367 if (input.publicOnly === true) {
368 conditions.push("is_public = 1");
369 }
370 if (input.owner !== undefined) {
371 conditions.push("owner = ?");
372 bindings.push(input.owner.toLowerCase());
373 }
374 if (after !== undefined) {
375 conditions.push("(owner > ? OR (owner = ? AND name > ?))");
376 bindings.push(after[0], after[0], after[1]);
377 }
378 const rows = yield* sql.all<RegistryRepoRow>(
379 `SELECT * FROM repos WHERE ${conditions.join(" AND ")}
380 ORDER BY owner, name LIMIT ?`,
381 ...bindings,
382 limit + 1,
383 );
384 const hasMore = rows.length > limit;
385 const page = hasMore ? rows.slice(0, limit) : rows;
386 const last = page[page.length - 1];
387 return {
388 items: page.map(toEntry),
389 nextCursor: hasMore && last !== undefined ? encodeCursor(last.owner, last.name) : null,
390 hasMore,
391 } satisfies ListReposResult;
392 }),
393
394 recordFork: (parentRepoId) => shape.bumpForkCount(parentRepoId, 1),
395
396 bumpForkCount: Effect.fn(function* (repoId: string, delta: number) {
397 if (delta !== 0) {
398 yield* sql.run(
399 `UPDATE repos SET fork_count = MAX(0, fork_count + ?) WHERE repo_id = ?`,
400 delta,
401 repoId,
402 );
403 const row = yield* sql.first<{ fork_count: number }>(
404 `SELECT fork_count FROM repos WHERE repo_id = ?`,
405 repoId,
406 );
407 return row?.fork_count ?? 0;
408 }
409 // The read path (delta 0) DERIVES the count from live fork rows
410 // rather than the stored column: the purge fork-pin must keep
411 // working after the parent's own registry row is removed (the
412 // name frees immediately on delete; only the R2 prefix stays
413 // pinned while forks reference it), and fork rows keep their
414 // `fork_of` pointer until their own purge completes.
415 const row = yield* sql.first<{ n: number }>(
416 `SELECT COUNT(*) AS n FROM repos WHERE fork_of = ?`,
417 repoId,
418 );
419 return row?.n ?? 0;
420 }),
421
422 markDeleted: Effect.fn(function* (repoId: string) {
423 yield* sql.run(
424 `UPDATE repos SET deleted_at = ? WHERE repo_id = ? AND deleted_at IS NULL`,
425 Date.now(),
426 repoId,
427 );
428 }),
429
430 updateSummary: Effect.fn(function* (repoId: string, summary: RepoSummary) {
431 yield* sql.run(
432 `UPDATE repos SET default_branch = ?, read_only = ?, is_public = ?, status = ?
433 WHERE repo_id = ?`,
434 summary.defaultBranch,
435 summary.readOnly ? 1 : 0,
436 summary.public ? 1 : 0,
437 summary.status,
438 repoId,
439 );
440 }),
441
442 removeRow: Effect.fn(function* (repoId: string) {
443 const row = yield* sql.first<RegistryRepoRow>(
444 `SELECT * FROM repos WHERE repo_id = ?`,
445 repoId,
446 );
447 if (row === undefined) {
448 return; // idempotent — purge re-runs are expected
449 }
450 yield* sql.run(`DELETE FROM repos WHERE repo_id = ?`, repoId);
451 if (row.fork_of !== null) {
452 yield* sql.run(
453 `UPDATE repos SET fork_count = MAX(0, fork_count - 1) WHERE repo_id = ?`,
454 row.fork_of,
455 );
456 }
457 }),
458 };
459
460 return shape;
461 });
462 }),
463 );
464
465 /**
466 * {@link RegistryStore} backed by the singleton Registry Durable Object —
467 * the default. Registers the DO implementation and resolves the store to
468 * its stub, so callers never name the instance.
469 *
470 * @layer
471 * @provides Git.RegistryStore
472 */
473 export const RegistryDurableObject: Layer.Layer<RegistryStore> = Layer.effect(
474 RegistryStore,
475 Effect.gen(function* () {
476 const namespace = yield* Registry;
477 // `getByName` must stay LAZY: the layer is built during deploy
478 // planning as well as at runtime, and the namespace only resolves to
479 // something callable inside a request. Each method therefore takes
480 // the stub at call time, exactly as the hand-rolled `registryStub()`
481 // did before this contract existed.
482 const stub = () => namespace.getByName(REGISTRY_DO_NAME);
483 return {
484 createRepo: (input) => stub().createRepo(input),
485 resolve: (owner, name) => stub().resolve(owner, name),
486 list: (input) => stub().list(input),
487 recordFork: (parentRepoId) => stub().recordFork(parentRepoId),
488 bumpForkCount: (repoId, delta) => stub().bumpForkCount(repoId, delta),
489 markDeleted: (repoId) => stub().markDeleted(repoId),
490 removeRow: (repoId) => stub().removeRow(repoId),
491 updateSummary: (repoId, summary) => stub().updateSummary(repoId, summary),
492 } satisfies RegistryShape;
493 }),
494 ).pipe(Layer.provide(RegistryLive)) as never;
495
496 export default RegistryLive;