@boxxy/dispatch 0.1.1 → 0.1.3

package/src/test-utils/forge-contract.ts

@@ -0,0 +1,171 @@
+import type { Forge, PullRequestRef } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import type { SeededPullRequest } from './create-fake-forge.ts';
+
+// What a forge adapter's test gives each case: the forge, and a way to put a pull request on the
+// service behind it.
+export interface ForgeHarness {
+  readonly forge: Forge;
+  seed: (pullRequest: SeededPullRequest) => void;
+}
+
+export interface ForgeContractOutcome {
+  readonly received: unknown;
+  readonly expected: unknown;
+}
+
+export type ForgeContractCase = readonly [
+  title: string,
+  check: (harness: ForgeHarness) => Promise<ForgeContractOutcome>,
+];
+
+const repo = brandSchemas.repoName.parse('acme/lamps');
+const otherRepo = brandSchemas.repoName.parse('acme/shades');
+
+// The behaviour of the forge port that dispatch relies on. Every adapter and the fake pass it.
+export const forgeContract: readonly ForgeContractCase[] = [
+  [
+    '#readPullRequest reads an open pull request with its GitHub id, url and commits',
+    async (harness) => {
+      harness.seed(buildOpen(7, 2));
+
+      const reading = await harness.forge.readPullRequest(buildRef(7));
+
+      return {
+        received: reading,
+        expected: {
+          url: 'https://github.com/acme/lamps/pull/7',
+          githubId: 5_000_007,
+          state: 'open',
+          mergedAt: null,
+          mergeCommit: null,
+          commits: [
+            {
+              sha: buildSha(1),
+              message: 'Fix lamp 1\n\nBoxxy-Attempt: 0190a6f4-0000-7000-8000-000000000001',
+            },
+            {
+              sha: buildSha(2),
+              message: 'Fix lamp 2\n\nBoxxy-Attempt: 0190a6f4-0000-7000-8000-000000000001',
+            },
+          ],
+        },
+      };
+    },
+  ],
+  [
+    '#readPullRequest reads a merged pull request with its merge time and merge commit',
+    async (harness) => {
+      const mergedAt = brandSchemas.instant.parse(1_800_000_000_000);
+      const open = buildOpen(8);
+
+      harness.seed({
+        ...open,
+        reading: { ...open.reading, state: 'merged', mergedAt, mergeCommit: buildSha(99) },
+      });
+
+      const reading = await harness.forge.readPullRequest(buildRef(8));
+
+      return {
+        received:
+          reading === 'not-found'
+            ? reading
+            : [reading.state, reading.mergedAt, reading.mergeCommit],
+        expected: ['merged', mergedAt, buildSha(99)],
+      };
+    },
+  ],
+  [
+    '#readPullRequest reads a pull request closed with no merge as closed',
+    async (harness) => {
+      const open = buildOpen(9);
+
+      harness.seed({ ...open, reading: { ...open.reading, state: 'closed' } });
+
+      const reading = await harness.forge.readPullRequest(buildRef(9));
+
+      return {
+        received:
+          reading === 'not-found'
+            ? reading
+            : [reading.state, reading.mergedAt, reading.mergeCommit],
+        expected: ['closed', null, null],
+      };
+    },
+  ],
+  [
+    '#readPullRequest reads every commit of a pull request over one page',
+    async (harness) => {
+      harness.seed(buildOpen(10, 130));
+
+      const reading = await harness.forge.readPullRequest(buildRef(10));
+
+      return {
+        received: reading === 'not-found' ? reading : reading.commits.map((commit) => commit.sha),
+        expected: Array.from({ length: 130 }, (_unused, index) => buildSha(index + 1)),
+      };
+    },
+  ],
+  [
+    '#readPullRequest answers not-found for a pull request that does not exist',
+    async (harness) => ({
+      received: await harness.forge.readPullRequest(buildRef(404)),
+      expected: 'not-found',
+    }),
+  ],
+  [
+    '#listOpenPullRequests lists the open pull requests of the repo, lowest number first',
+    async (harness) => {
+      const merged = buildOpen(2);
+
+      harness.seed(buildOpen(3));
+      harness.seed(buildOpen(1));
+      harness.seed({ ...merged, reading: { ...merged.reading, state: 'closed' } });
+      harness.seed(buildOpen(1, 0, otherRepo));
+
+      return {
+        received: await harness.forge.listOpenPullRequests(repo),
+        expected: [buildRef(1), buildRef(3)],
+      };
+    },
+  ],
+  [
+    '#listOpenPullRequests lists every open pull request over one page',
+    async (harness) => {
+      for (let number = 1; number <= 105; number += 1) {
+        harness.seed(buildOpen(number));
+      }
+
+      const listed = await harness.forge.listOpenPullRequests(repo);
+
+      return {
+        received: listed.map((ref) => ref.number),
+        expected: Array.from({ length: 105 }, (_unused, index) => index + 1),
+      };
+    },
+  ],
+];
+
+function buildOpen(number: number, commitCount = 0, inRepo = repo): SeededPullRequest {
+  return {
+    ref: buildRef(number, inRepo),
+    githubId: 5_000_000 + number,
+    reading: {
+      state: 'open',
+      mergedAt: null,
+      mergeCommit: null,
+      commits: Array.from({ length: commitCount }, (_unused, index) => ({
+        sha: buildSha(index + 1),
+        message: `Fix lamp ${index + 1}\n\nBoxxy-Attempt: 0190a6f4-0000-7000-8000-000000000001`,
+      })),
+    },
+  };
+}
+
+function buildRef(number: number, inRepo = repo): PullRequestRef {
+  return { repo: inRepo, number };
+}
+
+function buildSha(index: number): ReturnType<typeof brandSchemas.commitSha.parse> {
+  return brandSchemas.commitSha.parse(index.toString(16).padStart(40, '0'));
+}

package/src/test-utils/is-same-held-seat.ts

@@ -0,0 +1,11 @@
+import type { LimitSeatRow } from '@boxxy/model';
+
+// the key of the store's unique index over the held seats
+export function isSameHeldSeat(seat: LimitSeatRow, held: LimitSeatRow): boolean {
+  return (
+    seat.limit === held.limit &&
+    seat.attempt === held.attempt &&
+    seat.holdGen === held.holdGen &&
+    held.releasedAt === null
+  );
+}

package/src/test-utils/types.ts

@@ -1,4 +1,8 @@
-import type { ClaimStore } from '@boxxy/model';
+import type { ClaimStore, Limit, LimitSeatRow, OutboxFact, TableName, Tables } from '@boxxy/model';
+
+export interface ClosableClaimStore extends ClaimStore {
+  close: () => Promise<void>;
+}
 
 export interface ClaimStoreOutcome {
   readonly received: unknown;
@@ -7,5 +11,13 @@ export interface ClaimStoreOutcome {
 
 export type ClaimStoreCase = readonly [
   title: string,
-  check: (store: ClaimStore) => Promise<ClaimStoreOutcome>,
+  check: (store: ClosableClaimStore) => Promise<ClaimStoreOutcome>,
 ];
+
+// The memory store's tables: one array per table that a row write names, and the ones only the
+// store writes.
+export type MemoryTables = { [T in TableName]: Tables[T][] } & {
+  outbox: OutboxFact[];
+  limits: Limit[];
+  limit_seats: LimitSeatRow[];
+};

package/src/test-utils/worker-contract.ts

@@ -0,0 +1,192 @@
+import type { AtcSessionId, AttemptId, AttemptRow, SpawnRequest, WorkerKind } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import { buildMockV1AttemptRow } from '@boxxy/model/test-utils/build-mock-v1-attempt-row';
+import invariant from 'tiny-invariant';
+
+// What a worker adapter's test gives each case: the worker, and a spawn request on a target the
+// test owns, for a new attempt ID each call.
+export interface WorkerHarness {
+  readonly worker: WorkerKind;
+  buildSpawnRequest: (attempt: AttemptId) => SpawnRequest;
+}
+
+export interface WorkerContractOutcome {
+  readonly received: unknown;
+  readonly expected: unknown;
+}
+
+export type WorkerContractCase = readonly [
+  title: string,
+  check: (harness: WorkerHarness) => Promise<WorkerContractOutcome>,
+];
+
+// The behaviour of the worker port that dispatch relies on. Every adapter and the fake pass it.
+export const workerContract: readonly WorkerContractCase[] = [
+  [
+    '#start starts a session that reads as running on the same atc session',
+    async (harness) => {
+      const attempt = await startAttempt(harness);
+      const reading = await harness.worker.reconcile(attempt);
+
+      return {
+        received: [reading.kind, 'atcSession' in reading ? reading.atcSession : null],
+        expected: ['running', attempt.atcSession],
+      };
+    },
+  ],
+  [
+    '#start gives the same session for a second request with the same idempotency key',
+    async (harness) => {
+      const id = buildMockV1AttemptRow().id;
+      const request = harness.buildSpawnRequest(id);
+
+      const first = await harness.worker.start(request);
+      const second = await harness.worker.start(request);
+
+      return {
+        received: findStartedSession(second),
+        expected: findStartedSession(first),
+      };
+    },
+  ],
+  [
+    '#reconcile reads absent for an attempt whose spawn never ran',
+    async (harness) => {
+      const id = buildMockV1AttemptRow().id;
+
+      const reading = await harness.worker.reconcile(
+        buildMockV1AttemptRow({
+          id,
+          atcSession: null,
+          spawnRequest: { ...harness.buildSpawnRequest(id) },
+        }),
+      );
+
+      return { received: reading, expected: { kind: 'absent' } };
+    },
+  ],
+  [
+    '#suspend answers active for a session with activity after the idle time',
+    async (harness) => {
+      const attempt = await startAttempt(harness);
+      const outcome = await harness.worker.suspend(attempt, brandSchemas.instant.parse(0));
+
+      return { received: outcome, expected: { kind: 'active' } };
+    },
+  ],
+  [
+    '#suspend with no idle check stops a running session, which then reads stopped',
+    async (harness) => {
+      const attempt = await startAttempt(harness);
+      const outcome = await harness.worker.suspend(attempt, null);
+      const reading = await harness.worker.reconcile(attempt);
+
+      return {
+        received: [outcome.kind, isStopped(reading.kind)],
+        expected: ['suspended', true],
+      };
+    },
+  ],
+  [
+    '#stop stops a running session, and a second stop is safe',
+    async (harness) => {
+      const attempt = await startAttempt(harness);
+      const first = await harness.worker.stop(attempt);
+      const second = await harness.worker.stop(attempt);
+      const reading = await harness.worker.reconcile(attempt);
+
+      return {
+        received: [first.kind, second.kind, isStopped(reading.kind)],
+        expected: ['stopped', 'stopped', true],
+      };
+    },
+  ],
+  [
+    '#resume runs a stopped session again on the same atc session',
+    async (harness) => {
+      const attempt = await startAttempt(harness);
+
+      await harness.worker.stop(attempt);
+
+      const outcome = await harness.worker.resume(attempt);
+
+      return { received: findStartedSession(outcome), expected: attempt.atcSession };
+    },
+  ],
+  [
+    '#forget removes a stopped session, and a second forget answers absent',
+    async (harness) => {
+      const attempt = await startAttempt(harness);
+
+      const session = getSession(attempt);
+
+      await harness.worker.stop(attempt);
+
+      const first = await harness.worker.forget(session);
+      const second = await harness.worker.forget(session);
+      const reading = await harness.worker.reconcile(attempt);
+
+      return {
+        received: [first.kind, second.kind, reading.kind],
+        expected: ['forgotten', 'absent', 'absent'],
+      };
+    },
+  ],
+  [
+    '#resumeKept runs a stopped session again for a new attempt',
+    async (harness) => {
+      const first = await startAttempt(harness);
+
+      const session = getSession(first);
+
+      await harness.worker.stop(first);
+
+      const second = buildMockV1AttemptRow().id;
+
+      const outcome = await harness.worker.resumeKept(
+        {
+          atcSession: session,
+          target: harness.buildSpawnRequest(first.id).target,
+          attempt: first.id,
+          keptAt: brandSchemas.instant.parse(0),
+          caller: first.caller,
+        },
+        harness.buildSpawnRequest(second),
+      );
+
+      return { received: findStartedSession(outcome), expected: session };
+    },
+  ],
+];
+
+// An attempt row as the store holds it after the worker started its session.
+async function startAttempt(harness: WorkerHarness): Promise<AttemptRow> {
+  const id = buildMockV1AttemptRow().id;
+  const request = harness.buildSpawnRequest(id);
+
+  const outcome = await harness.worker.start(request);
+
+  return buildMockV1AttemptRow({
+    id,
+    spawnRequest: { ...request },
+    atcSession: findStartedSession(outcome),
+    caller: outcome.kind === 'started' ? outcome.caller : null,
+  });
+}
+
+function findStartedSession(
+  outcome: Awaited<ReturnType<WorkerKind['start']>>,
+): AtcSessionId | null {
+  return outcome.kind === 'started' ? outcome.atcSession : null;
+}
+
+// a stop sleeps the host of an imp target, and ends the process of a local one
+function isStopped(kind: string): boolean {
+  return kind === 'suspended' || kind === 'ended';
+}
+
+function getSession(attempt: AttemptRow): AtcSessionId {
+  invariant(attempt.atcSession !== null, 'the worker started a session');
+
+  return attempt.atcSession;
+}

package/src/timeouts.ts

@@ -0,0 +1,17 @@
+import type { DispatchTimeouts } from './types.ts';
+
+export const timeouts: DispatchTimeouts = {
+  spawnLostMinutes: 10,
+  resumeLostMinutes: 10,
+  closingGiveUpMinutes: 10,
+  stopGraceSeconds: 60,
+
+  // two ticks of the runner's 5-second loop: the reconcile table reads the time, not a tick count
+  seatlessSeconds: 10,
+  capacityBackoffSeconds: 60,
+  stallMinutes: 30,
+  keptSessionHours: 24,
+  failedSessionHours: 24,
+  usageLimitBackoffHours: 24,
+  strayHours: 24,
+};

package/src/types.ts

@@ -0,0 +1,32 @@
+// Every time limit of dispatch that the rules file does not hold.
+export interface DispatchTimeouts {
+  // `starting` or `reconciling` with no session
+  readonly spawnLostMinutes: number;
+
+  // `waking` with no running session
+  readonly resumeLostMinutes: number;
+
+  // `closing` with a session that does not stop
+  readonly closingGiveUpMinutes: number;
+
+  // a `closing` session inside a turn is not stopped before this
+  readonly stopGraceSeconds: number;
+
+  // a session that runs on a `sleeping` attempt wakes over the cap this long after its request
+  readonly seatlessSeconds: number;
+
+  // a pool gives no pick this long after the worker refused a session for capacity
+  readonly capacityBackoffSeconds: number;
+
+  // agent mode: a session with no activity this long is stopped
+  readonly stallMinutes: number;
+  readonly keptSessionHours: number;
+  readonly failedSessionHours: number;
+
+  // the most a pool waits after `usage-limit`, and the wait when the reading's reset time is not
+  // in the future
+  readonly usageLimitBackoffHours: number;
+
+  // how long the runner keeps stopping a stray session
+  readonly strayHours: number;
+}

package/dist/test-utils/claim-store-pool-cases.d.ts

@@ -1,2 +0,0 @@
-import type { ClaimStoreCase } from './types.ts';
-export declare const claimStorePoolCases: readonly ClaimStoreCase[];

package/src/test-utils/claim-store-pool-cases.ts

@@ -1,178 +0,0 @@
-import { brandSchemas } from '@boxxy/model';
-import { buildMockAttemptRow } from '@boxxy/model/test-utils/build-mock-attempt-row';
-import { buildMockItemRow } from '@boxxy/model/test-utils/build-mock-item-row';
-import { buildMockClaimChange } from './build-mock-claim-change.ts';
-import { buildMockFileItemChange } from './build-mock-file-item-change.ts';
-import { buildMockSettleChange } from './build-mock-settle-change.ts';
-import type { ClaimStoreCase } from './types.ts';
-
-export const claimStorePoolCases: readonly ClaimStoreCase[] = [
-  [
-    '#syncPoolSlots adds a row for each slot of each pool',
-    async (store) => {
-      await store.exclusive((transaction) =>
-        transaction.syncPoolSlots([
-          { name: brandSchemas.poolName.parse('build'), slots: 2 },
-          { name: brandSchemas.poolName.parse('review'), slots: 1 },
-        ]),
-      );
-
-      const slots: unknown = await store.read((transaction) => transaction.listPoolSlots());
-
-      return {
-        received: slots,
-        expected: [
-          { pool: 'build', slot: 1, holder: null, gen: 0, retired: false },
-          { pool: 'build', slot: 2, holder: null, gen: 0, retired: false },
-          { pool: 'review', slot: 1, holder: null, gen: 0, retired: false },
-        ],
-      };
-    },
-  ],
-  [
-    '#syncPoolSlots retires the rows above a smaller count and deletes none',
-    async (store) => {
-      const pool = brandSchemas.poolName.parse('build');
-
-      await store.exclusive(async (transaction) => {
-        await transaction.syncPoolSlots([{ name: pool, slots: 3 }]);
-        await transaction.syncPoolSlots([{ name: pool, slots: 1 }]);
-      });
-
-      const slots = await store.read((transaction) => transaction.listPoolSlots());
-
-      const retired: unknown = slots.map((slot) => [slot.slot, slot.retired]);
-
-      return {
-        received: retired,
-        expected: [
-          [1, false],
-          [2, true],
-          [3, true],
-        ],
-      };
-    },
-  ],
-  [
-    '#syncPoolSlots retires every row of a pool the rules no longer name',
-    async (store) => {
-      const build = brandSchemas.poolName.parse('build');
-      const review = brandSchemas.poolName.parse('review');
-
-      await store.exclusive(async (transaction) => {
-        await transaction.syncPoolSlots([
-          { name: build, slots: 1 },
-          { name: review, slots: 2 },
-        ]);
-
-        await transaction.syncPoolSlots([{ name: build, slots: 1 }]);
-      });
-
-      const slots = await store.read((transaction) => transaction.listPoolSlots());
-
-      const retired: unknown = slots.map((slot) => [slot.pool, slot.slot, slot.retired]);
-
-      return {
-        received: retired,
-        expected: [
-          ['build', 1, false],
-          ['review', 1, true],
-          ['review', 2, true],
-        ],
-      };
-    },
-  ],
-  [
-    '#syncPoolSlots leaves the holder on a slot it retires',
-    async (store) => {
-      const first = buildMockItemRow();
-      const second = buildMockItemRow();
-      const lower = buildMockAttemptRow({ item: first.id, state: 'starting' });
-      const upper = buildMockAttemptRow({ item: second.id, state: 'starting' });
-
-      await store.exclusive(async (transaction) => {
-        await transaction.syncPoolSlots([{ name: lower.pool, slots: 2 }]);
-        await transaction.applyChange(buildMockFileItemChange(first));
-        await transaction.applyChange(buildMockFileItemChange(second));
-        await transaction.applyChange(buildMockClaimChange(lower));
-        await transaction.applyChange(buildMockClaimChange(upper));
-        await transaction.syncPoolSlots([{ name: lower.pool, slots: 1 }]);
-      });
-
-      const slots = await store.read((transaction) => transaction.listPoolSlots());
-
-      return {
-        received: slots[1],
-        expected: {
-          pool: upper.pool,
-          slot: 2,
-          holder: upper.id,
-          gen: 1,
-          retired: true,
-        },
-      };
-    },
-  ],
-  [
-    '#applyChange never takes a retired slot',
-    async (store) => {
-      const first = buildMockItemRow();
-      const second = buildMockItemRow();
-      const held = buildMockAttemptRow({ item: first.id, state: 'starting' });
-      const refused = buildMockAttemptRow({ item: second.id, state: 'starting' });
-
-      await store.exclusive(async (transaction) => {
-        await transaction.syncPoolSlots([{ name: held.pool, slots: 2 }]);
-        await transaction.syncPoolSlots([{ name: held.pool, slots: 1 }]);
-        await transaction.applyChange(buildMockFileItemChange(first));
-        await transaction.applyChange(buildMockFileItemChange(second));
-        await transaction.applyChange(buildMockClaimChange(held));
-      });
-
-      const result = await store.exclusive((transaction) =>
-        transaction.applyChange(buildMockClaimChange(refused)),
-      );
-
-      return { received: result, expected: { kind: 'no-free-slot' } };
-    },
-  ],
-  [
-    '#syncPoolSlots reuses a retired row with its gen when the pool grows again',
-    async (store) => {
-      const first = buildMockItemRow();
-      const second = buildMockItemRow();
-      const third = buildMockItemRow();
-      const lower = buildMockAttemptRow({ item: first.id, state: 'starting' });
-      const upper = buildMockAttemptRow({ item: second.id, state: 'starting' });
-      const later = buildMockAttemptRow({ item: third.id, state: 'starting' });
-
-      await store.exclusive(async (transaction) => {
-        await transaction.syncPoolSlots([{ name: lower.pool, slots: 2 }]);
-        await transaction.applyChange(buildMockFileItemChange(first));
-        await transaction.applyChange(buildMockFileItemChange(second));
-        await transaction.applyChange(buildMockFileItemChange(third));
-        await transaction.applyChange(buildMockClaimChange(lower));
-        await transaction.applyChange(buildMockClaimChange(upper));
-
-        await transaction.applyChange(
-          buildMockSettleChange({ attempt: { ...upper, slot: 2, slotGen: 1 }, state: 'failed' }),
-        );
-
-        await transaction.syncPoolSlots([{ name: lower.pool, slots: 1 }]);
-        await transaction.syncPoolSlots([{ name: lower.pool, slots: 2 }]);
-      });
-
-      const result = await store.exclusive((transaction) =>
-        transaction.applyChange(buildMockClaimChange(later)),
-      );
-
-      return {
-        received: result,
-        expected: {
-          kind: 'applied',
-          slot: { pool: later.pool, slot: 2, gen: 2 },
-        },
-      };
-    },
-  ],
-];