@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 488 lines 19.2 KB
Raw
1 import type { DurableObjectState, SqlStorageValue } from "@alchemy.run/cloudflare/Workers/index";
2 /**
3 * Repo / Registry DO SQLite schema (DESIGN.md §3.1) and typed query helpers.
4 *
5 * Exposes:
6 *
7 * - the exact DDL as idempotent init effects ({@link initRepoSchema},
8 * {@link initRegistrySchema}) — run in the DO's outer init under
9 * `blockConcurrencyWhile` semantics,
10 * - typed row interfaces mirroring each table,
11 * - a small {@link SqlClient} over the raw synchronous `cf.SqlStorage`
12 * surface: `all`/`first`/`run`, the chunked-`IN` helper (≤ 100 bound
13 * params per statement), and the {@link SqlClient.transactionSync}
14 * wrapper every ref mutation goes through (DESIGN.md §3.4).
15 *
16 * All helpers operate on the raw synchronous SQLite surface (`cursor
17 * .toArray()` is synchronous inside a DO) wrapped in `Effect.try`, so SQL
18 * failures surface as typed {@link StoreError}s instead of defects.
19 */
20 import type * as cf from "@cloudflare/workers-types";
21 import * as Effect from "effect/Effect";
22 import { StoreError } from "../Protocol/Store.ts";
23
24 // ─────────────────────────────────────────────────────────────────────────────
25 // DDL (exact, DESIGN.md §3.1)
26 // ─────────────────────────────────────────────────────────────────────────────
27
28 /**
29 * Current Repo DO schema version, stored in the `config` table under
30 * {@link SCHEMA_VERSION_KEY} for future migrations.
31 */
32 export const SCHEMA_VERSION = 2;
33
34 /**
35 * The `config` key holding {@link SCHEMA_VERSION}.
36 */
37 export const SCHEMA_VERSION_KEY = "schema_version";
38
39 /**
40 * The Repo DO DDL, one statement per element, applied in order. Every
41 * statement is idempotent (`CREATE TABLE IF NOT EXISTS`), so re-running init
42 * after a crash or on every cold start is safe.
43 */
44 export const REPO_DDL: ReadonlyArray<string> = [
45 // config: repoId, owner, name, default_branch, description, created_at,
46 // schema_version, status ('ready'|'importing'|'forking'|'deleting'),
47 // read_only ('0'|'1'), fork_of (parent repoId or absent)
48 `CREATE TABLE IF NOT EXISTS config (key TEXT PRIMARY KEY, value TEXT NOT NULL)`,
49 // all refs, full names. HEAD is virtual: symref to config.default_branch.
50 `CREATE TABLE IF NOT EXISTS refs (
51 name TEXT PRIMARY KEY,
52 oid TEXT NOT NULL
53 ) WITHOUT ROWID`,
54 // object index + loose bytes. zdata is zlib(content) WITHOUT the loose
55 // header, so pack emission is: varint(type,size) + zdata, verbatim.
56 `CREATE TABLE IF NOT EXISTS objects (
57 oid TEXT PRIMARY KEY,
58 type INTEGER NOT NULL,
59 size INTEGER NOT NULL,
60 zsize INTEGER NOT NULL,
61 location TEXT NOT NULL DEFAULT 'row',
62 zdata BLOB,
63 r2_key TEXT,
64 pack_id TEXT,
65 pack_offset INTEGER,
66 staged_push TEXT
67 ) WITHOUT ROWID`,
68 `CREATE INDEX IF NOT EXISTS idx_objects_staged ON objects(staged_push) WHERE staged_push IS NOT NULL`,
69 // commit graph for closure/negotiation walks (populated at ingest)
70 `CREATE TABLE IF NOT EXISTS commits (
71 oid TEXT PRIMARY KEY,
72 tree TEXT NOT NULL,
73 gen INTEGER NOT NULL,
74 commit_time INTEGER NOT NULL
75 ) WITHOUT ROWID`,
76 `CREATE TABLE IF NOT EXISTS commit_parents (
77 oid TEXT NOT NULL,
78 parent TEXT NOT NULL,
79 ord INTEGER NOT NULL,
80 PRIMARY KEY (oid, parent)
81 ) WITHOUT ROWID`,
82 // crash-safety bookkeeping for pushes (GC'd by alarm)
83 `CREATE TABLE IF NOT EXISTS pushes (
84 push_id TEXT PRIMARY KEY,
85 started_at INTEGER NOT NULL,
86 state TEXT NOT NULL
87 ) WITHOUT ROWID`,
88 // async job bookkeeping (import/fork/delete-purge progress; one row per kind)
89 `CREATE TABLE IF NOT EXISTS jobs (
90 kind TEXT PRIMARY KEY,
91 state TEXT NOT NULL,
92 detail TEXT,
93 updated_at INTEGER NOT NULL
94 ) WITHOUT ROWID`,
95 // pull requests: base/head are live branch refs — the rows store intent +
96 // lifecycle, never a diff snapshot. Rows are never deleted (close, don't
97 // delete — numbers stay dense and stable); `merge_commit` is set iff
98 // state='merged' (the head tip for a fast-forward, the two-parent merge
99 // commit otherwise).
100 `CREATE TABLE IF NOT EXISTS pulls (
101 number INTEGER PRIMARY KEY,
102 title TEXT NOT NULL,
103 body TEXT,
104 base_ref TEXT NOT NULL,
105 head_ref TEXT NOT NULL,
106 state TEXT NOT NULL DEFAULT 'open',
107 created_at INTEGER NOT NULL,
108 updated_at INTEGER NOT NULL,
109 merged_at INTEGER,
110 merge_commit TEXT
111 ) WITHOUT ROWID`,
112 `CREATE INDEX IF NOT EXISTS idx_pulls_state ON pulls(state, number)`,
113 ];
114
115 /**
116 * Additive column migrations for Repo tables created by an earlier schema
117 * version (mirrors {@link REGISTRY_MIGRATIONS}). `CREATE TABLE IF NOT
118 * EXISTS` leaves an existing table untouched, so any future `pulls` (or
119 * other) column addition goes here — never into the `CREATE TABLE`.
120 * Re-running is safe because "duplicate column name" is swallowed.
121 */
122 export const REPO_MIGRATIONS: ReadonlyArray<string> = [];
123
124 /**
125 * The Registry DO DDL (DESIGN.md §3.1, bottom): the `owner/name → repoId`
126 * authority, listing surface, and fork-lineage ledger.
127 */
128 export const REGISTRY_DDL: ReadonlyArray<string> = [
129 `CREATE TABLE IF NOT EXISTS repos (
130 owner TEXT NOT NULL,
131 name TEXT NOT NULL,
132 repo_id TEXT NOT NULL UNIQUE,
133 description TEXT,
134 fork_of TEXT,
135 fork_count INTEGER NOT NULL DEFAULT 0,
136 created_at INTEGER NOT NULL,
137 deleted_at INTEGER,
138 -- Denormalised display fields, pushed here by the Repo DO whenever they
139 -- change (DESIGN.md section 15, bottleneck 7). The DO remains the source
140 -- of truth; these exist so listing repos does not have to wake one
141 -- Durable Object per listed row just to render a page.
142 default_branch TEXT NOT NULL DEFAULT 'main',
143 read_only INTEGER NOT NULL DEFAULT 0,
144 is_public INTEGER NOT NULL DEFAULT 0,
145 status TEXT NOT NULL DEFAULT 'ready',
146 PRIMARY KEY (owner, name)
147 ) WITHOUT ROWID`,
148 ];
149
150 // ─────────────────────────────────────────────────────────────────────────────
151 // Typed row interfaces
152 // ─────────────────────────────────────────────────────────────────────────────
153
154 /** One `config` row. */
155 export interface ConfigRow extends Record<string, SqlStorageValue> {
156 readonly key: string;
157 readonly value: string;
158 }
159
160 /** One `refs` row: a full ref name and its 40-hex tip oid. */
161 export interface RefRow extends Record<string, SqlStorageValue> {
162 readonly name: string;
163 readonly oid: string;
164 }
165
166 /**
167 * One full `objects` row. `zdata` BLOBs come back from workerd SQLite as
168 * `ArrayBuffer`s; `location` is `'row' | 'r2' | 'pack'` (pack = v1.1);
169 * `staged_push` is `NULL` for live objects, else the staging push id.
170 */
171 export interface ObjectRow extends Record<string, SqlStorageValue> {
172 readonly oid: string;
173 readonly type: number;
174 readonly size: number;
175 readonly zsize: number;
176 readonly location: string;
177 readonly zdata: ArrayBuffer | null;
178 readonly r2_key: string | null;
179 readonly pack_id: string | null;
180 readonly pack_offset: number | null;
181 readonly staged_push: string | null;
182 }
183
184 /** The metadata projection of an `objects` row (no byte payload columns). */
185 export interface ObjectMetaRow extends Record<string, SqlStorageValue> {
186 readonly oid: string;
187 readonly type: number;
188 readonly size: number;
189 readonly zsize: number;
190 readonly location: string;
191 }
192
193 /** One `commits` row (commit-graph node). */
194 export interface CommitRow extends Record<string, SqlStorageValue> {
195 readonly oid: string;
196 readonly tree: string;
197 readonly gen: number;
198 readonly commit_time: number;
199 }
200
201 /** One `commit_parents` row (commit-graph edge, `ord` = parent position). */
202 export interface CommitParentRow extends Record<string, SqlStorageValue> {
203 readonly oid: string;
204 readonly parent: string;
205 readonly ord: number;
206 }
207
208 /** One `pushes` row (`state` is `'staging' | 'committed'`). */
209 export interface PushRow extends Record<string, SqlStorageValue> {
210 readonly push_id: string;
211 readonly started_at: number;
212 readonly state: string;
213 }
214
215 /** One `pulls` row (`state` is `'open' | 'closed' | 'merged'`). */
216 export interface PullRow extends Record<string, SqlStorageValue> {
217 readonly number: number;
218 readonly title: string;
219 readonly body: string | null;
220 readonly base_ref: string;
221 readonly head_ref: string;
222 readonly state: string;
223 readonly created_at: number;
224 readonly updated_at: number;
225 readonly merged_at: number | null;
226 readonly merge_commit: string | null;
227 }
228
229 /** One `jobs` row (`kind` is `'import' | 'fork' | 'purge' | 'gc'`). */
230 export interface JobRow extends Record<string, SqlStorageValue> {
231 readonly kind: string;
232 readonly state: string;
233 readonly detail: string | null;
234 readonly updated_at: number;
235 }
236
237 /** One Registry `repos` row. */
238 export interface RegistryRepoRow extends Record<string, SqlStorageValue> {
239 readonly owner: string;
240 readonly name: string;
241 readonly repo_id: string;
242 readonly description: string | null;
243 readonly fork_of: string | null;
244 readonly fork_count: number;
245 readonly created_at: number;
246 readonly deleted_at: number | null;
247 /** Denormalised from the Repo DO — see the DDL comment. */
248 readonly default_branch: string;
249 readonly read_only: number;
250 readonly is_public: number;
251 readonly status: string;
252 }
253
254 // ─────────────────────────────────────────────────────────────────────────────
255 // Chunked-IN helpers
256 // ─────────────────────────────────────────────────────────────────────────────
257
258 /**
259 * The maximum number of bound parameters per statement (DESIGN.md: chunked
260 * `IN` lists ≤ 100 params).
261 */
262 export const MAX_IN_PARAMS = 100;
263
264 /**
265 * Splits `items` into chunks of at most `size` elements (default
266 * {@link MAX_IN_PARAMS}).
267 */
268 export const chunk = <T>(
269 items: ReadonlyArray<T>,
270 size: number = MAX_IN_PARAMS,
271 ): Array<ReadonlyArray<T>> => {
272 const out: Array<ReadonlyArray<T>> = [];
273 for (let i = 0; i < items.length; i += size) {
274 out.push(items.slice(i, i + size));
275 }
276 return out;
277 };
278
279 /**
280 * Builds an `IN`-list placeholder string: `placeholders(3)` → `"?, ?, ?"`.
281 */
282 export const placeholders = (count: number): string =>
283 Array.from({ length: count }, () => "?").join(", ");
284
285 // ─────────────────────────────────────────────────────────────────────────────
286 // SqlClient
287 // ─────────────────────────────────────────────────────────────────────────────
288
289 /**
290 * Options for {@link SqlClient.inChunks}: fixed bindings placed before /
291 * after each chunk's `IN`-list params, and an optional chunk-size override.
292 */
293 export interface InChunksOptions {
294 /** Bindings placed before the chunk params in each statement. */
295 readonly prefix?: ReadonlyArray<SqlStorageValue> | undefined;
296 /** Bindings placed after the chunk params in each statement. */
297 readonly suffix?: ReadonlyArray<SqlStorageValue> | undefined;
298 /** Max chunk params per statement (capped so total ≤ {@link MAX_IN_PARAMS}). */
299 readonly chunkSize?: number | undefined;
300 }
301
302 /**
303 * A thin, typed, Effect-wrapped client over a Durable Object's synchronous
304 * SQLite surface. Construct with {@link makeSqlClient}. All methods fail with
305 * {@link StoreError} on SQL errors (never defects).
306 */
307 export interface SqlClient {
308 /** The raw synchronous Cloudflare SQL surface (for advanced callers). */
309 readonly raw: cf.SqlStorage;
310 /** Runs a query and returns every row. */
311 readonly all: <Row extends Record<string, SqlStorageValue>>(
312 query: string,
313 ...bindings: Array<SqlStorageValue>
314 ) => Effect.Effect<Array<Row>, StoreError>;
315 /** Runs a query and returns the first row, or `undefined` when empty. */
316 readonly first: <Row extends Record<string, SqlStorageValue>>(
317 query: string,
318 ...bindings: Array<SqlStorageValue>
319 ) => Effect.Effect<Row | undefined, StoreError>;
320 /** Runs a statement for its side effects, consuming any cursor fully. */
321 readonly run: (
322 query: string,
323 ...bindings: Array<SqlStorageValue>
324 ) => Effect.Effect<void, StoreError>;
325 /**
326 * Runs `makeQuery(placeholders)` once per ≤ 100-param chunk of `items` and
327 * concatenates the rows. Row order across chunks follows input order of the
328 * chunks, but callers must not rely on intra-query ordering.
329 */
330 readonly inChunks: <Row extends Record<string, SqlStorageValue>>(
331 makeQuery: (placeholders: string) => string,
332 items: ReadonlyArray<SqlStorageValue>,
333 options?: InChunksOptions,
334 ) => Effect.Effect<Array<Row>, StoreError>;
335 /**
336 * Runs `body` inside `DurableObjectStorage.transactionSync` — atomic
337 * against mid-event failure, with the DO's input/output gates guaranteeing
338 * no interleaving between statements (DESIGN.md §3.4). The body MUST be
339 * fully synchronous (no awaits, no Effects).
340 *
341 * `rollback(error)` aborts the transaction (every statement is rolled
342 * back) and surfaces `error` on the typed error channel — this is the CAS
343 * abort path for `atomic` pushes. Any other thrown value also rolls back
344 * and surfaces as a {@link StoreError}.
345 */
346 readonly transactionSync: <A, E = never>(
347 body: (sql: cf.SqlStorage, rollback: (error: E) => never) => A,
348 ) => Effect.Effect<A, StoreError | E>;
349 }
350
351 const errorMessage = (cause: unknown): string =>
352 cause instanceof Error ? cause.message : String(cause);
353
354 /** Internal control-flow signal for {@link SqlClient.transactionSync}. */
355 class RollbackSignal {
356 constructor(readonly error: unknown) {}
357 }
358
359 /**
360 * Creates a {@link SqlClient} over a Durable Object's state handle. Plain
361 * factory (not a Layer) so `RepoObject.ts` / `RegistryObject.ts` can wire it
362 * inside their inner (per-instance) effects.
363 */
364 export const makeSqlClient = (state: DurableObjectState["Service"]): SqlClient => {
365 const sql = state.storage.sql.raw;
366 const storage = state.raw.storage;
367
368 const allWith = <Row extends Record<string, SqlStorageValue>>(
369 query: string,
370 bindings: ReadonlyArray<SqlStorageValue>,
371 ): Effect.Effect<Array<Row>, StoreError> =>
372 Effect.try({
373 try: () => sql.exec<Row>(query, ...bindings).toArray(),
374 catch: (cause) =>
375 StoreError.make({
376 reason: `sql failed (${query.slice(0, 120)}): ${errorMessage(cause)}`,
377 }),
378 });
379
380 return {
381 raw: sql,
382 all: (query, ...bindings) => allWith(query, bindings),
383 first: <Row extends Record<string, SqlStorageValue>>(
384 query: string,
385 ...bindings: Array<SqlStorageValue>
386 ) =>
387 allWith<Row>(query, bindings).pipe(
388 Effect.map((rows) => (rows.length > 0 ? rows[0] : undefined)),
389 ),
390 run: (query, ...bindings) => allWith(query, bindings).pipe(Effect.asVoid),
391 inChunks: <Row extends Record<string, SqlStorageValue>>(
392 makeQuery: (ph: string) => string,
393 items: ReadonlyArray<SqlStorageValue>,
394 options?: InChunksOptions,
395 ): Effect.Effect<Array<Row>, StoreError> =>
396 Effect.gen(function* () {
397 const prefix = options?.prefix ?? [];
398 const suffix = options?.suffix ?? [];
399 const fixed = prefix.length + suffix.length;
400 const size = Math.max(
401 1,
402 Math.min(options?.chunkSize ?? MAX_IN_PARAMS, MAX_IN_PARAMS - fixed),
403 );
404 const rows: Array<Row> = [];
405 for (const part of chunk(items, size)) {
406 const batch = yield* allWith<Row>(makeQuery(placeholders(part.length)), [
407 ...prefix,
408 ...part,
409 ...suffix,
410 ]);
411 for (const row of batch) {
412 rows.push(row);
413 }
414 }
415 return rows;
416 }),
417 transactionSync: <A, E = never>(
418 body: (sql: cf.SqlStorage, rollback: (error: E) => never) => A,
419 ) =>
420 Effect.try({
421 try: () =>
422 storage.transactionSync(() =>
423 body(sql, (error: E): never => {
424 throw new RollbackSignal(error);
425 }),
426 ),
427 catch: (thrown): StoreError | E =>
428 thrown instanceof RollbackSignal
429 ? (thrown.error as E)
430 : StoreError.make({
431 reason: `transactionSync failed: ${errorMessage(thrown)}`,
432 }),
433 }),
434 };
435 };
436
437 // ─────────────────────────────────────────────────────────────────────────────
438 // Schema init
439 // ─────────────────────────────────────────────────────────────────────────────
440
441 /**
442 * Idempotently applies the Repo DO DDL ({@link REPO_DDL}) and seeds the
443 * `schema_version` config row. Run in the Repo DO's outer init effect under
444 * `blockConcurrencyWhile` semantics.
445 */
446 export const initRepoSchema = Effect.fn(function* (sql: SqlClient) {
447 for (const statement of REPO_DDL) {
448 yield* sql.run(statement);
449 }
450 for (const statement of REPO_MIGRATIONS) {
451 // Already-applied migrations fail with "duplicate column name" — that
452 // is the success case on every run after the first.
453 yield* sql.run(statement).pipe(Effect.ignore);
454 }
455 yield* sql.run(
456 `INSERT INTO config (key, value) VALUES (?, ?) ON CONFLICT (key) DO NOTHING`,
457 SCHEMA_VERSION_KEY,
458 String(SCHEMA_VERSION),
459 );
460 });
461
462 /**
463 * Idempotently applies the Registry DO DDL ({@link REGISTRY_DDL}). Run in
464 * the Registry DO's outer init effect.
465 */
466 /**
467 * Additive column migrations for Registry tables created by an earlier
468 * version. `CREATE TABLE IF NOT EXISTS` leaves an existing table untouched,
469 * so new columns must be added explicitly; re-running is safe because
470 * "duplicate column name" is swallowed.
471 */
472 const REGISTRY_MIGRATIONS: ReadonlyArray<string> = [
473 `ALTER TABLE repos ADD COLUMN default_branch TEXT NOT NULL DEFAULT 'main'`,
474 `ALTER TABLE repos ADD COLUMN read_only INTEGER NOT NULL DEFAULT 0`,
475 `ALTER TABLE repos ADD COLUMN is_public INTEGER NOT NULL DEFAULT 0`,
476 `ALTER TABLE repos ADD COLUMN status TEXT NOT NULL DEFAULT 'ready'`,
477 ];
478
479 export const initRegistrySchema = Effect.fn(function* (sql: SqlClient) {
480 for (const statement of REGISTRY_DDL) {
481 yield* sql.run(statement);
482 }
483 for (const statement of REGISTRY_MIGRATIONS) {
484 // Already-applied migrations fail with "duplicate column name" — that
485 // is the success case on every run after the first.
486 yield* sql.run(statement).pipe(Effect.ignore);
487 }
488 });