@boxxy/dispatch 0.1.0 → 0.1.3

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

@@ -0,0 +1,314 @@
+import { brandSchemas } from '@boxxy/model';
+import { buildMockItemRules } from '@boxxy/model/test-utils/build-mock-item-rules';
+import { buildMockV1AttemptRow } from '@boxxy/model/test-utils/build-mock-v1-attempt-row';
+import { buildMockV1ItemRow } from '@boxxy/model/test-utils/build-mock-v1-item-row';
+import { buildMockV1LeverRow } from '@boxxy/model/test-utils/build-mock-v1-lever-row';
+import { buildMockClaimChange } from './build-mock-claim-change.ts';
+import { buildMockFileItemChange } from './build-mock-file-item-change.ts';
+import { buildMockLeverChange } from './build-mock-lever-change.ts';
+import { buildMockNoteChange } from './build-mock-note-change.ts';
+import { buildMockPauseChange } from './build-mock-pause-change.ts';
+import type { ClaimStoreCase } from './types.ts';
+
+export const claimStoreClaimCases: readonly ClaimStoreCase[] = [
+  [
+    '#applyChange returns lease-held for a second live lease on one item phase',
+    async (store) => {
+      const item = buildMockV1ItemRow();
+      const first = buildMockV1AttemptRow({ item: item.id, state: 'starting', leaseGen: 1 });
+
+      const second = buildMockV1AttemptRow({
+        item: item.id,
+        state: 'starting',
+        leaseGen: 2,
+        number: 2,
+      });
+
+      await store.exclusive(async (transaction) => {
+        await transaction.applyChange(buildMockFileItemChange(item));
+        await transaction.applyChange(buildMockClaimChange(first));
+      });
+
+      const result = await store.exclusive((transaction) =>
+        transaction.applyChange(buildMockClaimChange(second)),
+      );
+
+      return { received: result, expected: { kind: 'lease-held' } };
+    },
+  ],
+  [
+    '#applyChange writes no row and takes no seat for a change that returns lease-held',
+    async (store) => {
+      const workers = brandSchemas.limitName.parse('workers');
+      const item = buildMockV1ItemRow();
+      const first = buildMockV1AttemptRow({ item: item.id, state: 'starting', leaseGen: 1 });
+
+      const second = buildMockV1AttemptRow({
+        item: item.id,
+        state: 'starting',
+        leaseGen: 2,
+        number: 2,
+      });
+
+      await store.exclusive(async (transaction) => {
+        await transaction.syncLimits(
+          [{ name: workers, max: 2, counts: {} }],
+          brandSchemas.instant.parse(500),
+        );
+
+        await transaction.applyChange(buildMockFileItemChange(item));
+        await transaction.applyChange(buildMockClaimChange(first, [workers]));
+        await transaction.applyChange(buildMockClaimChange(second, [workers]));
+      });
+
+      const state: unknown = await store.read(async (transaction) => {
+        const snapshot = await transaction.readSnapshot(
+          brandSchemas.instant.parse(5000),
+          buildMockItemRules(),
+        );
+
+        const seats = await transaction.listLimitSeats();
+
+        return {
+          attempt: await transaction.readAttempt(second.id),
+          seats: seats.map((seat) => seat.attempt),
+          lastGen: await transaction.readLastLeaseGen(item.id, first.phase),
+          version: snapshot.storeVersion,
+        };
+      });
+
+      return {
+        received: state,
+        expected: { attempt: null, seats: [first.id], lastGen: 1, version: 2 },
+      };
+    },
+  ],
+  [
+    '#applyChange returns limit-full and changes no row when a limit has no free seat',
+    async (store) => {
+      const workers = brandSchemas.limitName.parse('workers');
+      const held = buildMockV1ItemRow();
+      const waiting = buildMockV1ItemRow();
+      const first = buildMockV1AttemptRow({ item: held.id, state: 'starting' });
+      const second = buildMockV1AttemptRow({ item: waiting.id, state: 'starting' });
+
+      await store.exclusive(async (transaction) => {
+        await transaction.syncLimits(
+          [{ name: workers, max: 1, counts: {} }],
+          brandSchemas.instant.parse(500),
+        );
+
+        await transaction.applyChange(buildMockFileItemChange(held));
+        await transaction.applyChange(buildMockFileItemChange(waiting));
+        await transaction.applyChange(buildMockClaimChange(first, [workers]));
+      });
+
+      const result = await store.exclusive((transaction) =>
+        transaction.applyChange(buildMockClaimChange(second, [workers])),
+      );
+
+      const state: unknown = await store.read(async (transaction) => {
+        const snapshot = await transaction.readSnapshot(
+          brandSchemas.instant.parse(5000),
+          buildMockItemRules(),
+        );
+
+        return {
+          attempt: await transaction.readAttempt(second.id),
+          lastGen: await transaction.readLastLeaseGen(waiting.id, second.phase),
+          version: snapshot.storeVersion,
+        };
+      });
+
+      return {
+        received: { result, state },
+        expected: {
+          result: { kind: 'limit-full', limit: 'workers' },
+          state: { attempt: null, lastGen: 0, version: 3 },
+        },
+      };
+    },
+  ],
+  [
+    '#applyChange takes the seats of a claim all or none',
+    async (store) => {
+      const workers = brandSchemas.limitName.parse('workers');
+      const ownerDesign = brandSchemas.limitName.parse('owner-design');
+
+      const first = buildMockV1AttemptRow({
+        state: 'starting',
+        phase: brandSchemas.phaseName.parse('design'),
+      });
+
+      const second = buildMockV1AttemptRow({
+        state: 'starting',
+        phase: brandSchemas.phaseName.parse('design'),
+      });
+
+      await store.exclusive(async (transaction) => {
+        await transaction.syncLimits(
+          [
+            { name: workers, max: 7, counts: {} },
+            { name: ownerDesign, max: 1, counts: { designMode: ['attended'] } },
+          ],
+          brandSchemas.instant.parse(500),
+        );
+
+        await transaction.applyChange(
+          buildMockFileItemChange(buildMockV1ItemRow({ id: first.item })),
+        );
+
+        await transaction.applyChange(
+          buildMockFileItemChange(buildMockV1ItemRow({ id: second.item })),
+        );
+
+        await transaction.applyChange(buildMockClaimChange(first, [ownerDesign, workers]));
+      });
+
+      const result = await store.exclusive((transaction) =>
+        transaction.applyChange(buildMockClaimChange(second, [workers, ownerDesign])),
+      );
+
+      const limits = await store.read((transaction) => transaction.listLimits());
+
+      return {
+        received: { result, held: limits.map((limit) => [limit.name, limit.held]) },
+        expected: {
+          result: { kind: 'limit-full', limit: 'owner-design' },
+          held: [
+            ['owner-design', 1],
+            ['workers', 1],
+          ],
+        },
+      };
+    },
+  ],
+  [
+    '#applyChange returns unknown-limit for a take that names a limit the store does not hold',
+    async (store) => {
+      const attempt = buildMockV1AttemptRow({ state: 'starting' });
+
+      await store.exclusive(async (transaction) => {
+        await transaction.applyChange(
+          buildMockFileItemChange(buildMockV1ItemRow({ id: attempt.item })),
+        );
+      });
+
+      const result = await store.exclusive((transaction) =>
+        transaction.applyChange(
+          buildMockClaimChange(attempt, [brandSchemas.limitName.parse('reviews')]),
+        ),
+      );
+
+      return { received: result, expected: { kind: 'unknown-limit', limit: 'reviews' } };
+    },
+  ],
+  [
+    '#applyChange gives each lever insert its seq, in the row and the fact',
+    async (store) => {
+      const item = buildMockV1ItemRow();
+      const defer = buildMockV1LeverRow({ seq: 0, item: item.id, kind: 'plan.defer' });
+      const expedite = buildMockV1LeverRow({ seq: 0, item: item.id, kind: 'plan.expedite' });
+
+      await store.exclusive(async (transaction) => {
+        await transaction.applyChange(buildMockFileItemChange(item));
+        await transaction.applyChange(buildMockLeverChange(defer));
+        await transaction.applyChange(buildMockLeverChange(expedite));
+      });
+
+      const state: unknown = await store.read(async (transaction) => {
+        const items = await transaction.listItems(
+          {},
+          brandSchemas.instant.parse(5000),
+          buildMockItemRules(),
+        );
+
+        const facts = await transaction.readUnsentFacts(10);
+
+        return { levers: items[0]?.levers, payloads: facts.slice(1).map((fact) => fact.payload) };
+      });
+
+      return {
+        received: state,
+        expected: {
+          levers: [
+            { ...defer, seq: 1 },
+            { ...expedite, seq: 2 },
+          ],
+          payloads: [
+            { ...defer, seq: 1 },
+            { ...expedite, seq: 2 },
+          ],
+        },
+      };
+    },
+  ],
+  [
+    '#applyChange throws and writes nothing for a fact whose payload its type refuses',
+    async (store) => {
+      const item = buildMockV1ItemRow();
+
+      await store.exclusive((transaction) =>
+        transaction.applyChange(buildMockFileItemChange(item)),
+      );
+
+      const outcome = await Promise.allSettled([
+        store.exclusive((transaction) =>
+          transaction.applyChange(
+            buildMockNoteChange({
+              item: item.id,
+              seq: 1,
+              text: '',
+              by: 'boxxy:owner:local',
+              at: brandSchemas.instant.parse(4500),
+            }),
+          ),
+        ),
+      ]);
+
+      const state: unknown = await store.read(async (transaction) => {
+        const facts = await transaction.readUnsentFacts(10);
+
+        return { notes: await transaction.listItemNotes(item.id), facts: facts.length };
+      });
+
+      return {
+        received: { status: outcome[0]?.status, state },
+        expected: { status: 'rejected', state: { notes: [], facts: 1 } },
+      };
+    },
+  ],
+  [
+    '#applyChange applies a change with no fact and moves no store version',
+    async (store) => {
+      const runner = brandSchemas.runnerId.parse('runner-1');
+      const item = buildMockV1ItemRow();
+
+      await store.exclusive(async (transaction) => {
+        await transaction.applyChange(buildMockFileItemChange(item));
+        await transaction.writeHeartbeat(runner, brandSchemas.instant.parse(1000));
+      });
+
+      const result = await store.exclusive((transaction) =>
+        transaction.applyChange(buildMockPauseChange(runner)),
+      );
+
+      const state: unknown = await store.read(async (transaction) => {
+        const snapshot = await transaction.readSnapshot(
+          brandSchemas.instant.parse(5000),
+          buildMockItemRules(),
+        );
+
+        return { runner: await transaction.readRunner(runner), version: snapshot.storeVersion };
+      });
+
+      return {
+        received: { result, state },
+        expected: {
+          result: { kind: 'applied' },
+          state: { runner: { id: 'runner-1', heartbeatAt: 1000, paused: true }, version: 1 },
+        },
+      };
+    },
+  ],
+];

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

@@ -0,0 +1,95 @@
+import { setImmediate } from 'node:timers/promises';
+import type { ClaimStoreCase } from './types.ts';
+
+export const claimStoreCloseCases: readonly ClaimStoreCase[] = [
+  [
+    '#read rejects after the store closes',
+    async (store) => {
+      await store.close();
+
+      const settled = await store
+        .read((transaction) => transaction.listLimits())
+        .then(
+          () => 'resolved',
+          () => 'rejected',
+        );
+
+      return { received: settled, expected: 'rejected' };
+    },
+  ],
+  [
+    '#exclusive rejects after the store closes',
+    async (store) => {
+      await store.close();
+
+      const settled = await store
+        .exclusive((transaction) => transaction.listLimits())
+        .then(
+          () => 'resolved',
+          () => 'rejected',
+        );
+
+      return { received: settled, expected: 'rejected' };
+    },
+  ],
+  [
+    '#close waits for a read that is running',
+    async (store) => {
+      const events: string[] = [];
+      const gate = Promise.withResolvers<void>();
+
+      const reading = store.read(async () => {
+        await gate.promise;
+
+        events.push('read end');
+      });
+
+      const close = async () => {
+        await store.close();
+
+        events.push('close end');
+      };
+
+      const closing = close();
+
+      // one turn of the event loop lets a store that doesn't wait finish the close
+      await setImmediate();
+
+      gate.resolve();
+
+      await Promise.all([reading, closing]);
+
+      return { received: events, expected: ['read end', 'close end'] };
+    },
+  ],
+  [
+    '#close waits for an exclusive call that is running',
+    async (store) => {
+      const events: string[] = [];
+      const gate = Promise.withResolvers<void>();
+
+      const writing = store.exclusive(async () => {
+        await gate.promise;
+
+        events.push('exclusive end');
+      });
+
+      const close = async () => {
+        await store.close();
+
+        events.push('close end');
+      };
+
+      const closing = close();
+
+      // one turn of the event loop lets a store that doesn't wait finish the close
+      await setImmediate();
+
+      gate.resolve();
+
+      await Promise.all([writing, closing]);
+
+      return { received: events, expected: ['exclusive end', 'close end'] };
+    },
+  ],
+];

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

@@ -0,0 +1,28 @@
+import { claimStoreAttemptReaderCases } from './claim-store-attempt-reader-cases.ts';
+import { claimStoreClaimCases } from './claim-store-claim-cases.ts';
+import { claimStoreCloseCases } from './claim-store-close-cases.ts';
+import { claimStoreCopyCases } from './claim-store-copy-cases.ts';
+import { claimStoreExclusiveCases } from './claim-store-exclusive-cases.ts';
+import { claimStoreGuardCases } from './claim-store-guard-cases.ts';
+import { claimStoreItemReaderCases } from './claim-store-item-reader-cases.ts';
+import { claimStoreOutboxCases } from './claim-store-outbox-cases.ts';
+import { claimStoreRaceCases } from './claim-store-race-cases.ts';
+import { claimStoreRollbackCases } from './claim-store-rollback-cases.ts';
+import { claimStoreSeatCases } from './claim-store-seat-cases.ts';
+import { claimStoreSessionCases } from './claim-store-session-cases.ts';
+import type { ClaimStoreCase } from './types.ts';
+
+export const claimStoreContract: readonly ClaimStoreCase[] = [
+  ...claimStoreExclusiveCases,
+  ...claimStoreClaimCases,
+  ...claimStoreGuardCases,
+  ...claimStoreRollbackCases,
+  ...claimStoreCopyCases,
+  ...claimStoreCloseCases,
+  ...claimStoreSeatCases,
+  ...claimStoreItemReaderCases,
+  ...claimStoreAttemptReaderCases,
+  ...claimStoreSessionCases,
+  ...claimStoreOutboxCases,
+  ...claimStoreRaceCases,
+];

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

@@ -0,0 +1,100 @@
+import { brandSchemas } from '@boxxy/model';
+import type { Criterion } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+import { buildMockItemRules } from '@boxxy/model/test-utils/build-mock-item-rules';
+import { buildMockV1AttemptRow } from '@boxxy/model/test-utils/build-mock-v1-attempt-row';
+import { buildMockV1ItemRow } from '@boxxy/model/test-utils/build-mock-v1-item-row';
+import { buildMockClaimChange } from './build-mock-claim-change.ts';
+import { buildMockFileItemChange } from './build-mock-file-item-change.ts';
+import { buildMockStartChange } from './build-mock-start-change.ts';
+import type { ClaimStoreCase } from './types.ts';
+
+export const claimStoreCopyCases: readonly ClaimStoreCase[] = [
+  [
+    '#readAttempt returns a row that a later change in the same call leaves as it was',
+    async (store) => {
+      const item = buildMockV1ItemRow();
+      const attempt = buildMockV1AttemptRow({ item: item.id, state: 'starting' });
+
+      await store.exclusive(async (transaction) => {
+        await transaction.applyChange(buildMockFileItemChange(item));
+        await transaction.applyChange(buildMockClaimChange(attempt));
+      });
+
+      const before = await store.exclusive(async (transaction) => {
+        const read = await transaction.readAttempt(attempt.id);
+
+        await transaction.applyChange(buildMockStartChange(attempt));
+
+        return read;
+      });
+
+      return { received: before?.state, expected: 'starting' };
+    },
+  ],
+  [
+    '#read returns rows whose edits by the caller leave the store as it was',
+    async (store) => {
+      const item = buildMockV1ItemRow();
+      const attempt = buildMockV1AttemptRow({ item: item.id, state: 'starting' });
+
+      await store.exclusive(async (transaction) => {
+        await transaction.applyChange(buildMockFileItemChange(item));
+        await transaction.applyChange(buildMockClaimChange(attempt));
+      });
+
+      const read = await store.read((transaction) => transaction.readAttempt(attempt.id));
+
+      Object.assign(read ?? {}, { state: 'failed' });
+
+      const reread = await store.read((transaction) => transaction.readAttempt(attempt.id));
+
+      return { received: reread?.state, expected: 'starting' };
+    },
+  ],
+  [
+    '#applyChange stores a copy of a list that an update sets',
+    async (store) => {
+      const item = buildMockV1ItemRow();
+
+      const acceptance: Criterion[] = [
+        { id: brandSchemas.criterionId.parse('a1'), text: 'The gate latches', evidence: [] },
+      ];
+
+      await store.exclusive(async (transaction) => {
+        await transaction.applyChange(buildMockFileItemChange(item));
+
+        await transaction.applyChange({
+          at: brandSchemas.instant.parse(3000),
+          writes: [
+            { op: 'update', table: 'items', key: { id: item.id }, expect: {}, set: { acceptance } },
+          ],
+          facts: [
+            {
+              id: buildMockFactId(),
+              type: 'boxxy.item.edited',
+              entity: `boxxy:item:${item.id}`,
+              actor: 'boxxy:owner:local',
+              payload: { acceptance: [...acceptance], byAttempt: null },
+            },
+          ],
+        });
+      });
+
+      acceptance.push({
+        id: brandSchemas.criterionId.parse('a2'),
+        text: 'The hinge is oiled',
+        evidence: [],
+      });
+
+      const reread = await store.read((transaction) =>
+        transaction.readItem(item.id, brandSchemas.instant.parse(5000), buildMockItemRules()),
+      );
+
+      return {
+        received: reread?.acceptance,
+        expected: [{ id: 'a1', text: 'The gate latches', evidence: [] }],
+      };
+    },
+  ],
+];