@pickleball/expo-sdk 0.1.1

package/src/match/persistence/store.ts

@@ -0,0 +1,497 @@
+import type {
+  MatchCreateInput,
+  MatchEvent,
+  MatchInputSource,
+  MatchSnapshot,
+} from "../contracts";
+import { applyMatchEvent, createMatch as createMatchState } from "../engine";
+import { replayMatchEvents } from "../replay";
+import { valuesEqual } from "../state";
+import {
+  assertRuntimeMatchEvent,
+  assertRuntimeMatchSnapshot,
+} from "../validation";
+import type {
+  MatchPersistenceDriver,
+  MatchSummary,
+  PersistedMatch,
+  StoredMatchEventRow,
+  StoredMatchRow,
+} from "./types";
+import type { RemoteBinding } from "../remote/types";
+import {
+  MATCH_PERSISTENCE_SCHEMA_VERSION,
+  MatchPersistenceError,
+} from "./types";
+
+interface MatchEventStoreOptions {
+  readonly now?: () => number;
+}
+
+function asPersistenceError(error: unknown): MatchPersistenceError {
+  if (error instanceof MatchPersistenceError) return error;
+  return new MatchPersistenceError(
+    "storage_failure",
+    "The local match database operation failed",
+    { cause: error },
+  );
+}
+
+function parseJson(json: string, label: string): unknown {
+  try {
+    return JSON.parse(json) as unknown;
+  } catch (error) {
+    throw new MatchPersistenceError("corrupt_data", `${label} contains malformed JSON`, {
+      cause: error,
+    });
+  }
+}
+
+function snapshotRow(snapshot: MatchSnapshot, updatedAt: number): StoredMatchRow {
+  return {
+    matchId: snapshot.id,
+    schemaVersion: MATCH_PERSISTENCE_SCHEMA_VERSION,
+    snapshotJson: JSON.stringify(snapshot),
+    snapshotSequence: snapshot.sequence,
+    status: snapshot.status,
+    updatedAt,
+  };
+}
+
+function eventRow(matchId: string, event: MatchEvent, createdAt: number): StoredMatchEventRow {
+  return {
+    matchId,
+    sequence: event.sequence,
+    eventId: event.id,
+    schemaVersion: event.schemaVersion,
+    eventJson: JSON.stringify(event),
+    createdAt,
+  };
+}
+
+function decodePersistedMatch(
+  matchId: string,
+  row: StoredMatchRow,
+  eventRows: readonly StoredMatchEventRow[],
+): PersistedMatch {
+  if (
+    row.schemaVersion !== MATCH_PERSISTENCE_SCHEMA_VERSION ||
+    eventRows.some((event) => event.schemaVersion !== MATCH_PERSISTENCE_SCHEMA_VERSION)
+  ) {
+    throw new MatchPersistenceError(
+      "unsupported_schema",
+      "The stored match uses an unsupported schema version",
+    );
+  }
+  if (eventRows.length === 0) {
+    throw new MatchPersistenceError("corrupt_data", "The match creation event is missing");
+  }
+  eventRows.forEach((storedEvent, index) => {
+    if (
+      storedEvent.matchId !== matchId ||
+      storedEvent.sequence !== index ||
+      storedEvent.eventId !== `${matchId}:${index}`
+    ) {
+      throw new MatchPersistenceError(
+        "sequence_mismatch",
+        "The stored match event sequence is not contiguous",
+      );
+    }
+  });
+  const events = eventRows.map((storedEvent) => {
+    const value = parseJson(storedEvent.eventJson, "Stored match event");
+    try {
+      assertRuntimeMatchEvent(value);
+    } catch (error) {
+      throw new MatchPersistenceError("corrupt_data", "A stored match event is invalid", {
+        cause: error,
+      });
+    }
+    if (
+      value.id !== storedEvent.eventId ||
+      value.sequence !== storedEvent.sequence ||
+      value.schemaVersion !== storedEvent.schemaVersion
+    ) {
+      throw new MatchPersistenceError(
+        "sequence_mismatch",
+        "A stored event does not match its database ordering metadata",
+      );
+    }
+    return value;
+  });
+  let replayed: MatchSnapshot;
+  try {
+    replayed = replayMatchEvents(events);
+  } catch (error) {
+    throw new MatchPersistenceError("corrupt_data", "The stored event log cannot be replayed", {
+      cause: error,
+    });
+  }
+  const cachedValue = parseJson(row.snapshotJson, "Stored match snapshot");
+  try {
+    assertRuntimeMatchSnapshot(cachedValue);
+  } catch (error) {
+    throw new MatchPersistenceError("corrupt_data", "The stored match snapshot is invalid", {
+      cause: error,
+    });
+  }
+  if (
+    row.matchId !== replayed.id ||
+    row.snapshotSequence !== replayed.sequence ||
+    row.status !== replayed.status ||
+    !valuesEqual(cachedValue, replayed)
+  ) {
+    throw new MatchPersistenceError(
+      "snapshot_mismatch",
+      "The snapshot cache does not match the immutable event log",
+    );
+  }
+  return { snapshot: replayed, events };
+}
+
+async function readPersistedMatch(
+  driver: MatchPersistenceDriver,
+  matchId: string,
+): Promise<PersistedMatch | null> {
+  const { match, events } = await driver.readMatch(matchId);
+  return match ? decodePersistedMatch(matchId, match, events) : null;
+}
+
+function resolveCreateRetry(
+  existing: PersistedMatch,
+  requested: PersistedMatch,
+): PersistedMatch {
+  if (valuesEqual(existing.events[0], requested.events[0])) {
+    return existing;
+  }
+  throw new MatchPersistenceError(
+    "already_exists",
+    "A different match already uses this match id",
+  );
+}
+
+function resolveAppendRetry(
+  persisted: PersistedMatch,
+  currentSnapshot: MatchSnapshot,
+  event: MatchEvent,
+): PersistedMatch | null {
+  if (
+    event.sequence !== currentSnapshot.sequence + 1 ||
+    event.id !== `${currentSnapshot.id}:${event.sequence}`
+  ) {
+    return null;
+  }
+  const existingEvent = persisted.events[event.sequence];
+  if (!existingEvent) return null;
+
+  let snapshotBeforeEvent: MatchSnapshot;
+  try {
+    snapshotBeforeEvent = replayMatchEvents(persisted.events.slice(0, event.sequence));
+  } catch (error) {
+    throw new MatchPersistenceError(
+      "corrupt_data",
+      "The persisted event prefix cannot be replayed",
+      { cause: error },
+    );
+  }
+  if (!valuesEqual(snapshotBeforeEvent, currentSnapshot)) {
+    throw new MatchPersistenceError(
+      "snapshot_mismatch",
+      "The caller snapshot does not match the event's persisted prefix",
+    );
+  }
+  if (!valuesEqual(existingEvent, event)) {
+    throw new MatchPersistenceError(
+      "conflict",
+      "A different event already exists at this match sequence",
+    );
+  }
+  return persisted;
+}
+
+function assertMatchListMetadata(row: StoredMatchRow) {
+  if (row.schemaVersion !== MATCH_PERSISTENCE_SCHEMA_VERSION) {
+    throw new MatchPersistenceError(
+      "unsupported_schema",
+      "A stored match summary uses an unsupported schema version",
+    );
+  }
+  if (
+    typeof row.matchId !== "string" ||
+    row.matchId.trim().length === 0 ||
+    typeof row.snapshotJson !== "string" ||
+    !Number.isSafeInteger(row.snapshotSequence) ||
+    row.snapshotSequence < 0 ||
+    (row.status !== "inProgress" &&
+      row.status !== "completed" &&
+      row.status !== "ended") ||
+    !Number.isSafeInteger(row.updatedAt) ||
+    row.updatedAt < 0
+  ) {
+    throw new MatchPersistenceError(
+      "corrupt_data",
+      "A stored match summary contains invalid metadata",
+    );
+  }
+}
+
+export class MatchEventStore {
+  private initialized: Promise<void> | null = null;
+  private readonly now: () => number;
+
+  constructor(
+    private readonly driver: MatchPersistenceDriver,
+    options: MatchEventStoreOptions = {},
+  ) {
+    this.now = options.now ?? Date.now;
+  }
+
+  initialize(): Promise<void> {
+    if (!this.initialized) {
+      this.initialized = this.driver.migrate().catch((error) => {
+        this.initialized = null;
+        throw asPersistenceError(error);
+      });
+    }
+    return this.initialized;
+  }
+
+  async getRemoteBinding(): Promise<RemoteBinding | null> {
+    await this.initialize();
+    if (!this.driver.getRemoteBinding) return null;
+    try {
+      return await this.driver.getRemoteBinding();
+    } catch (error) {
+      throw asPersistenceError(error);
+    }
+  }
+
+  async setRemoteBinding(binding: RemoteBinding | null): Promise<void> {
+    if (binding && binding.deviceId.trim().length === 0) {
+      throw new MatchPersistenceError("corrupt_data", "Remote binding identifier cannot be empty");
+    }
+    await this.initialize();
+    if (!this.driver.setRemoteBinding) {
+      throw new MatchPersistenceError("storage_failure", "Remote binding storage is unavailable");
+    }
+    try {
+      await this.driver.setRemoteBinding(binding);
+    } catch (error) {
+      throw asPersistenceError(error);
+    }
+  }
+
+  async createMatch(
+    input: MatchCreateInput,
+    source: MatchInputSource = "system",
+  ): Promise<PersistedMatch> {
+    await this.initialize();
+    const created = createMatchState(input, source);
+    const timestamp = this.now();
+    try {
+      return await this.driver.transaction(async (transaction) => {
+        const [existingRow, existingEvents] = await Promise.all([
+          transaction.getMatch(created.snapshot.id),
+          transaction.getEvents(created.snapshot.id),
+        ]);
+        if (existingRow) {
+          return resolveCreateRetry(
+            decodePersistedMatch(created.snapshot.id, existingRow, existingEvents),
+            created,
+          );
+        }
+        if (existingEvents.length > 0) {
+          throw new MatchPersistenceError(
+            "corrupt_data",
+            "Match events exist without their aggregate",
+          );
+        }
+        await transaction.insertMatch(snapshotRow(created.snapshot, timestamp));
+        await transaction.insertEvent(eventRow(created.snapshot.id, created.events[0], timestamp));
+        await transaction.setActiveMatch(created.snapshot.id);
+        return created;
+      });
+    } catch (error) {
+      if (error instanceof MatchPersistenceError) throw error;
+      try {
+        const existing = await readPersistedMatch(this.driver, created.snapshot.id);
+        if (existing) return resolveCreateRetry(existing, created);
+      } catch (reconciliationError) {
+        if (reconciliationError instanceof MatchPersistenceError) {
+          throw reconciliationError;
+        }
+      }
+      throw asPersistenceError(error);
+    }
+  }
+
+  async appendEvent(
+    currentSnapshot: MatchSnapshot,
+    event: MatchEvent,
+  ): Promise<PersistedMatch> {
+    await this.initialize();
+    const timestamp = this.now();
+    try {
+      return await this.driver.transaction(async (transaction) => {
+        const [row, eventRows] = await Promise.all([
+          transaction.getMatch(currentSnapshot.id),
+          transaction.getEvents(currentSnapshot.id),
+        ]);
+        if (!row) {
+          throw new MatchPersistenceError("not_found", "The match to update is missing");
+        }
+        const persisted = decodePersistedMatch(currentSnapshot.id, row, eventRows);
+        const retried = resolveAppendRetry(persisted, currentSnapshot, event);
+        if (retried) return retried;
+        if (!valuesEqual(persisted.snapshot, currentSnapshot)) {
+          throw new MatchPersistenceError(
+            "snapshot_mismatch",
+            "The caller snapshot does not match the immutable event log",
+          );
+        }
+        let nextSnapshot: MatchSnapshot;
+        try {
+          nextSnapshot = applyMatchEvent(currentSnapshot, event);
+        } catch (error) {
+          throw new MatchPersistenceError(
+            "sequence_mismatch",
+            "The match event cannot follow the current snapshot",
+            { cause: error },
+          );
+        }
+        await transaction.insertEvent(eventRow(currentSnapshot.id, event, timestamp));
+        const updated = await transaction.updateSnapshot(
+          currentSnapshot.id,
+          currentSnapshot.sequence,
+          snapshotRow(nextSnapshot, timestamp),
+        );
+        if (!updated) {
+          throw new MatchPersistenceError(
+            "sequence_mismatch",
+            "The persisted match sequence changed before this event committed",
+          );
+        }
+        if (
+          currentSnapshot.status !== "inProgress" &&
+          nextSnapshot.status === "inProgress"
+        ) {
+          await transaction.setActiveMatch(currentSnapshot.id);
+        } else if (
+          currentSnapshot.status === "inProgress" &&
+          nextSnapshot.status !== "inProgress"
+        ) {
+          await transaction.clearActiveMatch(currentSnapshot.id);
+        }
+        return {
+          snapshot: nextSnapshot,
+          events: [...persisted.events, event],
+        };
+      });
+    } catch (error) {
+      if (error instanceof MatchPersistenceError) throw error;
+      try {
+        const persisted = await readPersistedMatch(this.driver, currentSnapshot.id);
+        if (persisted) {
+          const retried = resolveAppendRetry(persisted, currentSnapshot, event);
+          if (retried) return retried;
+        }
+      } catch (reconciliationError) {
+        if (reconciliationError instanceof MatchPersistenceError) {
+          throw reconciliationError;
+        }
+      }
+      throw asPersistenceError(error);
+    }
+  }
+
+  async resumeActiveMatch(): Promise<PersistedMatch | null> {
+    await this.initialize();
+    let activeMatchId: string | null;
+    let row: StoredMatchRow | null;
+    let eventRows: readonly StoredMatchEventRow[];
+    try {
+      ({ activeMatchId, match: row, events: eventRows } =
+        await this.driver.readActiveMatch());
+    } catch (error) {
+      throw asPersistenceError(error);
+    }
+    if (!activeMatchId) return null;
+    if (!row) {
+      throw new MatchPersistenceError(
+        "corrupt_data",
+        "The active match pointer has no aggregate",
+      );
+    }
+    const persisted = decodePersistedMatch(activeMatchId, row, eventRows);
+    if (persisted.snapshot.status !== "inProgress") {
+      throw new MatchPersistenceError(
+        "corrupt_data",
+        "The active match pointer targets a non-active match",
+      );
+    }
+    return persisted;
+  }
+
+  async resumeMatch(matchId: string): Promise<PersistedMatch | null> {
+    await this.initialize();
+    let row: StoredMatchRow | null;
+    let eventRows: readonly StoredMatchEventRow[];
+    try {
+      ({ match: row, events: eventRows } = await this.driver.readMatch(matchId));
+    } catch (error) {
+      throw asPersistenceError(error);
+    }
+    if (!row) return null;
+    return decodePersistedMatch(matchId, row, eventRows);
+  }
+
+  async listMatches(): Promise<readonly MatchSummary[]> {
+    await this.initialize();
+    try {
+      const { matches, activeMatchId } = await this.driver.readMatchList();
+      matches.forEach(assertMatchListMetadata);
+      const ids = new Set(matches.map((row) => row.matchId));
+      if (ids.size !== matches.length) {
+        throw new MatchPersistenceError(
+          "corrupt_data",
+          "The stored match list contains duplicate match ids",
+        );
+      }
+      if (activeMatchId !== null && !ids.has(activeMatchId)) {
+        throw new MatchPersistenceError(
+          "corrupt_data",
+          "The active match pointer is missing from the stored match list",
+        );
+      }
+      if (
+        activeMatchId !== null &&
+        matches.find((row) => row.matchId === activeMatchId)?.status !== "inProgress"
+      ) {
+        throw new MatchPersistenceError(
+          "corrupt_data",
+          "The active match pointer targets a non-active match summary",
+        );
+      }
+      return matches.map((row) => ({
+        id: row.matchId,
+        sequence: row.snapshotSequence,
+        status: row.status,
+        updatedAt: row.updatedAt,
+        isActive: row.matchId === activeMatchId,
+      }));
+    } catch (error) {
+      throw asPersistenceError(error);
+    }
+  }
+
+  async archiveMatch(matchId: string): Promise<void> {
+    await this.initialize();
+    try {
+      await this.driver.transaction(async (transaction) => {
+        await transaction.clearActiveMatch(matchId);
+      });
+    } catch (error) {
+      throw asPersistenceError(error);
+    }
+  }
+}

package/src/match/persistence/types.ts

@@ -0,0 +1,98 @@
+import type { MatchEvent, MatchSnapshot } from "../contracts";
+import type { RemoteBinding } from "../remote/types";
+
+export const MATCH_PERSISTENCE_SCHEMA_VERSION = 1 as const;
+
+export interface StoredMatchRow {
+  readonly matchId: string;
+  readonly schemaVersion: number;
+  readonly snapshotJson: string;
+  readonly snapshotSequence: number;
+  readonly status: MatchSnapshot["status"];
+  readonly updatedAt: number;
+}
+
+export interface StoredMatchEventRow {
+  readonly matchId: string;
+  readonly sequence: number;
+  readonly eventId: string;
+  readonly schemaVersion: number;
+  readonly eventJson: string;
+  readonly createdAt: number;
+}
+
+export interface MatchPersistenceTransaction {
+  getMatch(matchId: string): Promise<StoredMatchRow | null>;
+  getEvents(matchId: string): Promise<readonly StoredMatchEventRow[]>;
+  insertMatch(row: StoredMatchRow): Promise<void>;
+  insertEvent(row: StoredMatchEventRow): Promise<void>;
+  updateSnapshot(
+    matchId: string,
+    expectedSequence: number,
+    row: Pick<
+      StoredMatchRow,
+      "schemaVersion" | "snapshotJson" | "snapshotSequence" | "status" | "updatedAt"
+    >,
+  ): Promise<boolean>;
+  setActiveMatch(matchId: string | null): Promise<void>;
+  clearActiveMatch(matchId: string): Promise<void>;
+}
+
+export interface MatchPersistenceDriver {
+  migrate(): Promise<void>;
+  transaction<T>(work: (transaction: MatchPersistenceTransaction) => Promise<T>): Promise<T>;
+  readMatch(matchId: string): Promise<{
+    readonly match: StoredMatchRow | null;
+    readonly events: readonly StoredMatchEventRow[];
+  }>;
+  getActiveMatchId(): Promise<string | null>;
+  readActiveMatch(): Promise<{
+    readonly activeMatchId: string | null;
+    readonly match: StoredMatchRow | null;
+    readonly events: readonly StoredMatchEventRow[];
+  }>;
+  readMatchList(): Promise<{
+    readonly matches: readonly StoredMatchRow[];
+    readonly activeMatchId: string | null;
+  }>;
+  getRemoteBinding?(): Promise<RemoteBinding | null>;
+  setRemoteBinding?(binding: RemoteBinding | null): Promise<void>;
+}
+
+export interface PersistedMatch {
+  readonly snapshot: MatchSnapshot;
+  readonly events: readonly MatchEvent[];
+}
+
+export interface MatchSummary {
+  readonly id: string;
+  readonly sequence: number;
+  readonly status: MatchSnapshot["status"];
+  readonly updatedAt: number;
+  readonly isActive: boolean;
+}
+
+export type MatchPersistenceErrorCode =
+  | "not_found"
+  | "already_exists"
+  | "conflict"
+  | "corrupt_data"
+  | "unsupported_schema"
+  | "sequence_mismatch"
+  | "snapshot_mismatch"
+  | "storage_failure";
+
+export class MatchPersistenceError extends Error {
+  readonly name = "MatchPersistenceError";
+  readonly recoverable = true;
+  readonly retryable: boolean;
+
+  constructor(
+    readonly code: MatchPersistenceErrorCode,
+    message: string,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options);
+    this.retryable = code === "storage_failure";
+  }
+}