@boxxy/store-sqlite 0.1.0 → 0.1.3

package/src/test-utils/create-claim-bench.ts

@@ -0,0 +1,66 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { claimNext } from '@boxxy/dispatch';
+import { createTestDispatch } from '@boxxy/dispatch/test-utils/create-test-dispatch';
+import type { ItemId } from '@boxxy/model';
+import { createSQLiteClaimStore } from '../create-sqlite-claim-store.ts';
+
+export interface ClaimBenchOptions {
+  readonly itemCount: number;
+}
+
+export interface ClaimBench extends AsyncDisposable {
+  // one `claimNext` call, which holds the store's lock for the whole decision; throws when it
+  // picks no item
+  readonly claim: () => Promise<ItemId>;
+}
+
+// A SQLite store in a temp folder, seeded with open items at their pipeline's first phase, and
+// every limit raised to the item count, so each claim finds a free seat with no close or settle
+// between claims.
+export async function createClaimBench(options: ClaimBenchOptions): Promise<ClaimBench> {
+  const stack = new AsyncDisposableStack();
+
+  const folder = await mkdtemp(join(tmpdir(), 'boxxy-claim-bench-'));
+
+  stack.defer(() => rm(folder, { recursive: true, force: true }));
+
+  const store = await createSQLiteClaimStore(join(folder, 'store.db'));
+
+  stack.defer(() => store.close());
+
+  const dispatch = await createTestDispatch({ store });
+
+  const rules = dispatch.rules();
+  const limits = rules.limits.map((limit) => ({ ...limit, max: options.itemCount }));
+
+  dispatch.setRules({ ...rules, limits });
+
+  await store.exclusive((tx) => tx.syncLimits(limits, dispatch.clock.now()));
+
+  for (let index = 0; index < options.itemCount; index += 1) {
+    await dispatch.seedItem({});
+  }
+
+  return {
+    claim: async () => {
+      const claim = await claimNext({
+        store,
+        runner: dispatch.runner,
+        rules: dispatch.rules(),
+        now: dispatch.clock.now(),
+        newId: dispatch.newId,
+        backoff: dispatch.backoff,
+        spawn: dispatch.spawn,
+      });
+
+      if (claim === null) {
+        throw new Error('the claim picked no item');
+      }
+
+      return claim.attempt.item;
+    },
+    [Symbol.asyncDispose]: () => stack.disposeAsync(),
+  };
+}

package/src/test-utils/create-test-claim-store.ts

@@ -0,0 +1,23 @@
+import { onTestFinished } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createSQLiteClaimStore } from '../create-sqlite-claim-store.ts';
+import type { SQLiteClaimStore } from '../create-sqlite-claim-store.ts';
+
+export async function createTestClaimStore(): Promise<SQLiteClaimStore> {
+  const cleanup = new AsyncDisposableStack();
+
+  onTestFinished(() => cleanup.disposeAsync());
+
+  // the process id keeps the folders of test runs that share a temp folder apart by name
+  const folder = await mkdtemp(join(tmpdir(), `boxxy-store-${process.pid}-`));
+
+  cleanup.defer(() => rm(folder, { recursive: true, force: true }));
+
+  const store = await createSQLiteClaimStore(join(folder, 'store.db'));
+
+  cleanup.defer(() => store.close());
+
+  return store;
+}

package/src/types.ts

@@ -0,0 +1,173 @@
+import type { Generated } from 'kysely';
+
+export interface StoreDatabase {
+  items: {
+    id: string;
+    kind: string;
+    repo: string;
+    title: string;
+    outcome: string;
+    acceptance: string;
+    fields: string;
+    labels: string;
+    found_in_attempt: string | null;
+    filed_by: string;
+    filed_at: number;
+    closed_at: number | null;
+    close_reason: string | null;
+    kept_session: string | null;
+  };
+  relations: {
+    source: string;
+    target: string;
+    type: string;
+    added_by: string;
+    added_at: number;
+    removed_at: number | null;
+  };
+  levers: {
+    seq: number;
+    kind: string;
+    item: string;
+    until: number | null;
+    expires_at: number | null;
+    reason: string | null;
+    phase: string | null;
+    actor: string;
+    at: number;
+  };
+  attempts: {
+    id: string;
+    item: string;
+    phase: string;
+    number: number;
+    runner: string;
+    recipe_hash: string;
+    rules_version: string;
+    pool: string;
+    lease_gen: number;
+    spawn_request: string;
+    spawn_request_hash: string;
+    state: string;
+    failure: string | null;
+    atc_session: string | null;
+    caller: string | null;
+    claimed_at: number;
+    started_at: number | null;
+    ended_at: number | null;
+    fields: string;
+    mode: string;
+    round: number;
+    input: string | null;
+    hold_gen: number;
+    close_out: string | null;
+    close_out_hash: string | null;
+    close_out_fact: string | null;
+    closing: string | null;
+    closing_at: number | null;
+    suspend_requested_at: number | null;
+    slept_at: number | null;
+    wake_requested_at: number | null;
+    woken_at: number | null;
+    outcome: string | null;
+    returned_outcome: string | null;
+    strayed_at: number | null;
+    session_stopped_at: number | null;
+    session_forgotten_at: number | null;
+  };
+  attempt_sessions: {
+    attempt: string;
+    agent_session: string;
+    atc_session: string;
+    product: string;
+    source: string;
+    seen_at: number;
+  };
+  leases: {
+    item: string;
+    phase: string;
+    attempt: string;
+    gen: number;
+    taken_at: number;
+    released_at: number | null;
+  };
+  limits: {
+    name: string;
+    max: number;
+    counts: string;
+  };
+  limit_seats: {
+    limit: string;
+    attempt: string;
+    hold_gen: number;
+    over_cap: number;
+    taken_at: number;
+    released_at: number | null;
+  };
+  decisions: {
+    id: string;
+    attempt: string;
+    item: string;
+    kind: string;
+    pool: string;
+    rules_version: string;
+    snapshot_hash: string;
+    store_version: number;
+    pepys_offsets: string;
+    faults: string;
+    limits: string;
+    at: number;
+  };
+  evidence: {
+    fact_id: string;
+    attempt: string;
+    kind: string;
+    ref: string;
+    observed: string | null;
+    source: string;
+    at: number;
+  };
+  pull_requests: {
+    repo: string;
+    number: number;
+    attempt: string;
+    github_id: number;
+    url: string;
+    state: string;
+    merged_at: number | null;
+    merge_commit: string | null;
+    checked_at: number;
+  };
+  runners: {
+    id: string;
+    heartbeat_at: number;
+    paused: number;
+  };
+  notes: {
+    item: string;
+    seq: number;
+    text: string;
+    by: string;
+    at: number;
+  };
+  notices: {
+    id: Generated<number>;
+    item: string;
+    reason: string;
+    at: number;
+    tries: number;
+    sent_at: number | null;
+  };
+  outbox: {
+    seq: Generated<number>;
+    fact_id: string;
+    type: string;
+    entity: string;
+    actor: string;
+    at: number;
+    payload: string;
+    sent_at: number | null;
+    parked_at: number | null;
+    parked_reason: string | null;
+  };
+}

package/src/with-busy-retry.ts

@@ -0,0 +1,32 @@
+import { SQLiteError } from 'bun:sqlite';
+
+const retryDelayMs = 10;
+
+// bun:sqlite waits on a busy lock synchronously, which stalls every other store in the process for
+// the whole wait, so the statement fails at once and this waits between tries without blocking.
+export async function withBusyRetry(waitLimitMs: number, work: () => unknown): Promise<void> {
+  const startMs = performance.now();
+
+  for (;;) {
+    try {
+      await work();
+
+      return;
+    } catch (error) {
+      if (!isBusy(error)) {
+        throw error;
+      }
+
+      await Bun.sleep(retryDelayMs);
+
+      // checked after the sleep, so no try starts once the limit has passed
+      if (performance.now() - startMs >= waitLimitMs) {
+        throw error;
+      }
+    }
+  }
+}
+
+function isBusy(error: unknown): boolean {
+  return error instanceof SQLiteError && error.code?.startsWith('SQLITE_BUSY') === true;
+}

package/src/with-transaction.ts

@@ -0,0 +1,29 @@
+import { sql } from 'kysely';
+import type { Kysely } from 'kysely';
+import type { StoreDatabase } from './types.ts';
+
+export async function withTransaction<T>(
+  db: Kysely<StoreDatabase>,
+  begin: (db: Kysely<StoreDatabase>) => Promise<unknown>,
+  work: () => Promise<T>,
+): Promise<T> {
+  await begin(db);
+
+  try {
+    const result = await work();
+
+    await sql`COMMIT`.execute(db);
+
+    return result;
+  } catch (error) {
+    // SQLite ends the transaction by itself after some errors, such as a full disk, and ROLLBACK
+    // then fails; its error joins the first one, never replaces it
+    await sql`ROLLBACK`.execute(db).catch((rollbackError: unknown) => {
+      throw new AggregateError([error, rollbackError], 'the work failed, and so did its rollback', {
+        cause: error,
+      });
+    });
+
+    throw error;
+  }
+}

package/src/writes/apply-sqlite-change.ts

@@ -0,0 +1,223 @@
+import { buildAppliedChange, parseNewFact, pickSeatTake, toJSONValue } from '@boxxy/model';
+import type { ApplyResult, Instant, RowWrite, SeatTake, StoreChange } from '@boxxy/model';
+import { sql } from 'kysely';
+import type { Kysely, RawBuilder } from 'kysely';
+import invariant from 'tiny-invariant';
+import { match } from 'ts-pattern';
+import { toStoreColumns } from '../codecs/to-store-columns.ts';
+import type { StoreValue } from '../codecs/to-store-columns.ts';
+import { buildSQLiteReader } from '../reads/build-sqlite-reader.ts';
+import type { StoreDatabase } from '../types.ts';
+
+// A savepoint, not the transaction, so a refusal keeps the caller's earlier changes in the same
+// exclusive call. The caller runs one change at a time, so one savepoint name is enough.
+export async function applySQLiteChange(
+  db: Kysely<StoreDatabase>,
+  change: StoreChange,
+): Promise<ApplyResult> {
+  const facts = change.facts.map((fact) => parseNewFact(fact));
+
+  await sql`SAVEPOINT apply_change`.execute(db);
+
+  try {
+    const result = await writeSQLiteChange(db, { ...change, facts });
+
+    if (result.kind !== 'applied') {
+      await sql`ROLLBACK TO apply_change`.execute(db);
+    }
+
+    await sql`RELEASE apply_change`.execute(db);
+
+    return result;
+  } catch (error) {
+    await removeSavepoint(db, error);
+
+    throw error;
+  }
+}
+
+async function writeSQLiteChange(
+  db: Kysely<StoreDatabase>,
+  change: StoreChange,
+): Promise<ApplyResult> {
+  if (!(await probeLiveUnder(db, change.under))) {
+    return { kind: 'stale-generation' };
+  }
+
+  const lastLever = await db
+    .selectFrom('levers')
+    .select((builder) => builder.fn.max('seq').as('seq'))
+    .executeTakeFirst();
+
+  const lastNotice = await db
+    .selectFrom('notices')
+    .select((builder) => builder.fn.max('id').as('id'))
+    .executeTakeFirst();
+
+  const applied = buildAppliedChange(change, {
+    lastLeverSeq: lastLever?.seq ?? 0,
+    lastNoticeId: lastNotice?.id ?? 0,
+  });
+
+  for (const write of applied.writes) {
+    const refusal = await writeSQLiteRow(db, write, change.at);
+
+    if (refusal !== null) {
+      return refusal;
+    }
+  }
+
+  for (const fact of applied.facts) {
+    await db
+      .insertInto('outbox')
+      .values({
+        fact_id: fact.id,
+        type: fact.type,
+        entity: fact.entity,
+        actor: fact.actor,
+        at: change.at,
+        payload: JSON.stringify(toJSONValue(fact.payload)),
+        sent_at: null,
+        parked_at: null,
+        parked_reason: null,
+      })
+      .execute();
+  }
+
+  return { kind: 'applied' };
+}
+
+async function probeLiveUnder(
+  db: Kysely<StoreDatabase>,
+  under: StoreChange['under'],
+): Promise<boolean> {
+  if (under === undefined || under === null) {
+    return true;
+  }
+
+  const lease = await db
+    .selectFrom('leases')
+    .innerJoin('attempts', 'attempts.id', 'leases.attempt')
+    .select('attempts.hold_gen')
+    .where('leases.item', '=', under.item)
+    .where('leases.phase', '=', under.phase)
+    .where('leases.gen', '=', under.gen)
+    .where('leases.released_at', 'is', null)
+    .executeTakeFirst();
+
+  return lease !== undefined && (under.holdGen === undefined || lease.hold_gen === under.holdGen);
+}
+
+function writeSQLiteRow(
+  db: Kysely<StoreDatabase>,
+  write: RowWrite,
+  at: Instant,
+): Promise<ApplyResult | null> {
+  return match(write)
+    .with({ op: 'take-seats' }, (seats) => writeSeatTake(db, seats.take, at))
+    .with({ op: 'release-seats' }, async (seats) => {
+      await db
+        .updateTable('limit_seats')
+        .set({ released_at: at })
+        .where('attempt', '=', seats.release.attempt)
+        .where('hold_gen', '=', seats.release.holdGen)
+        .where('released_at', 'is', null)
+        .execute();
+
+      return null;
+    })
+    .with({ op: 'insert', table: 'leases' }, async (insert) => {
+      const columns = toStoreColumns(insert.table, insert.row);
+
+      // ON CONFLICT names the partial unique index, so SQLite skips a second live lease, not throws
+      const result = await sql`${buildInsert(insert.table, columns)}
+        ON CONFLICT (item, phase) WHERE released_at IS NULL DO NOTHING`.execute(db);
+
+      return result.numAffectedRows === 0n ? ({ kind: 'lease-held' } as const) : null;
+    })
+    .with({ op: 'insert' }, async (insert) => {
+      await buildInsert(insert.table, toStoreColumns(insert.table, insert.row)).execute(db);
+
+      return null;
+    })
+    .with({ op: 'update' }, async (update) => {
+      const set = toStoreColumns(update.table, update.set);
+
+      const guards = [
+        ...toStoreColumns(update.table, update.key),
+        ...toStoreColumns(update.table, update.expect),
+      ];
+
+      invariant(set.length > 0, 'an update sets at least one field');
+
+      const result = await sql`UPDATE ${sql.table(update.table)}
+        SET ${sql.join(set.map(([column, value]) => sql`${sql.ref(column)} = ${value}`))}
+        WHERE ${buildGuards(guards)}`.execute(db);
+
+      return result.numAffectedRows === 0n
+        ? ({ kind: 'guard-mismatch', table: update.table, key: toJSONValue(update.key) } as const)
+        : null;
+    })
+    .exhaustive();
+}
+
+// The write lock is held for the whole transaction, so the counts read here stay true until the
+// seats are inserted.
+async function writeSeatTake(
+  db: Kysely<StoreDatabase>,
+  take: SeatTake,
+  at: Instant,
+): Promise<ApplyResult | null> {
+  const limits = await buildSQLiteReader(db).listLimits();
+
+  const answer = pickSeatTake(take, limits, at);
+
+  if (answer.kind !== 'take') {
+    return { kind: answer.kind, limit: answer.limit };
+  }
+
+  for (const seat of answer.seats) {
+    await db
+      .insertInto('limit_seats')
+      .values({
+        limit: seat.limit,
+        attempt: seat.attempt,
+        hold_gen: seat.holdGen,
+        over_cap: seat.overCap ? 1 : 0,
+        taken_at: seat.takenAt,
+        released_at: seat.releasedAt,
+      })
+      .execute();
+  }
+
+  return null;
+}
+
+function buildInsert(table: string, columns: [string, StoreValue][]): RawBuilder<unknown> {
+  return sql`INSERT INTO ${sql.table(table)}
+    (${sql.join(columns.map(([column]) => sql.ref(column)))})
+    VALUES (${sql.join(columns.map(([, value]) => value))})`;
+}
+
+// IS compares NULL as a value, so an expect of null matches a NULL column
+function buildGuards(guards: [string, StoreValue][]): RawBuilder<unknown> {
+  invariant(guards.length > 0, 'an update names its key');
+
+  return sql.join(
+    guards.map(([column, value]) => sql`${sql.ref(column)} IS ${value}`),
+    sql` AND `,
+  );
+}
+
+// SQLite rolls the whole transaction back by itself after some errors, such as a full disk, and the
+// savepoint is gone; the rollback's own error then joins the first one, never replaces it.
+async function removeSavepoint(db: Kysely<StoreDatabase>, cause: unknown): Promise<void> {
+  try {
+    await sql`ROLLBACK TO apply_change`.execute(db);
+    await sql`RELEASE apply_change`.execute(db);
+  } catch (rollbackError) {
+    throw new AggregateError([cause, rollbackError], 'the change failed, and so did its rollback', {
+      cause: rollbackError,
+    });
+  }
+}