@syncular/testkit 0.1.2 → 0.2.0

package/src/faults.ts

@@ -1,349 +1,88 @@
-import type {
-  SyncCombinedRequest,
-  SyncPullResponse,
-  SyncPushBatchResponse,
-  SyncTransport,
-  SyncTransportOptions,
-} from '@syncular/core';
-
-export type FaultTransportOperation = 'push' | 'pull' | 'fetch';
-
-export type FaultTransportAction = 'pass' | 'fail';
-
-export type FaultTransportPhase = 'before' | 'after';
-
-export interface FaultPlanStep {
-  operation: FaultTransportOperation | 'any';
-  action?: FaultTransportAction;
-  phase?: FaultTransportPhase;
-  repeat?: number;
-  failWith?: Error;
-  latencyMs?: number;
-}
-
-export interface FaultTransportOptions {
-  failAfter?: number;
-  failWith?: Error;
-  latencyMs?: number;
-  flaky?: number;
-  failOnPush?: boolean;
-  failOnPull?: boolean;
-  failOnFetch?: boolean;
-  plan?: FaultPlanStep[];
-  onFail?: (operation: 'push' | 'pull' | 'fetch', error: Error) => void;
-  onSuccess?: (operation: 'push' | 'pull' | 'fetch') => void;
-}
-
-export interface FaultTransportState {
-  pushCount: number;
-  pullCount: number;
-  fetchCount: number;
-  failureCount: number;
-}
-
-export interface FaultTransportResult {
-  transport: SyncTransport;
-  getState: () => FaultTransportState;
-  reset: () => void;
-  setOptions: (options: Partial<FaultTransportOptions>) => void;
-}
-
-interface ActiveFaultPlanStep {
-  operation: FaultPlanStep['operation'];
-  action: FaultTransportAction;
-  phase: FaultTransportPhase;
-  remaining: number;
-  failWith?: Error;
-  latencyMs?: number;
-}
-
-interface PlannedFaultDecision {
-  action: FaultTransportAction;
-  phase: FaultTransportPhase;
-  error: Error;
-  latencyMs: number;
-}
-
-export function withFaults(
-  baseTransport: SyncTransport,
-  options: FaultTransportOptions = {}
-): FaultTransportResult {
-  let currentOptions = { ...options };
-  let currentPlan = createActivePlan(currentOptions.plan);
-  const state: FaultTransportState = {
-    pushCount: 0,
-    pullCount: 0,
-    fetchCount: 0,
-    failureCount: 0,
-  };
-
-  const defaultError = new Error('Simulated transport error');
-
-  const maybeDelay = async (extraLatencyMs = 0): Promise<void> => {
-    const latencyMs = (currentOptions.latencyMs ?? 0) + extraLatencyMs;
-    if (latencyMs > 0) {
-      await new Promise((resolve) => setTimeout(resolve, latencyMs));
-    }
-  };
-
-  const shouldTargetOperation = (
-    operation: FaultTransportOperation
-  ): boolean => {
-    const hasTargets =
-      currentOptions.failOnPush === true ||
-      currentOptions.failOnPull === true ||
-      currentOptions.failOnFetch === true;
-
-    if (!hasTargets) {
-      return true;
-    }
-
-    if (operation === 'push') {
-      return currentOptions.failOnPush === true;
-    }
-    if (operation === 'pull') {
-      return currentOptions.failOnPull === true;
-    }
-    return currentOptions.failOnFetch === true;
-  };
-
-  const shouldFail = (
-    operation: FaultTransportOperation,
-    count: number
-  ): boolean => {
-    if (!shouldTargetOperation(operation)) {
-      return false;
-    }
-
-    if (
-      currentOptions.failAfter !== undefined &&
-      count >= currentOptions.failAfter
-    ) {
-      return true;
-    }
-
-    if (currentOptions.flaky !== undefined && currentOptions.flaky > 0) {
-      return Math.random() < currentOptions.flaky;
-    }
-
-    return false;
-  };
-
-  const getError = (): Error => currentOptions.failWith ?? defaultError;
-
-  const fail = (operation: FaultTransportOperation, error: Error): never => {
-    state.failureCount++;
-    currentOptions.onFail?.(operation, error);
-    throw error;
-  };
-
-  const recordSuccess = (operation: FaultTransportOperation): void => {
-    if (operation === 'push') {
-      state.pushCount++;
-      return;
-    }
-    if (operation === 'pull') {
-      state.pullCount++;
-      return;
-    }
-    state.fetchCount++;
-  };
-
-  const takePlannedDecision = (
-    operation: FaultTransportOperation
-  ): PlannedFaultDecision | null => {
-    const step = currentPlan.find(
-      (candidate) =>
-        candidate.remaining > 0 &&
-        (candidate.operation === 'any' || candidate.operation === operation)
-    );
-    if (!step) {
-      return null;
-    }
-
-    step.remaining -= 1;
-    return {
-      action: step.action,
-      phase: step.phase,
-      error: step.failWith ?? getError(),
-      latencyMs: step.latencyMs ?? 0,
-    };
-  };
-
-  const runWithFaults = async <Result>(
-    operation: FaultTransportOperation,
-    count: number,
-    run: () => Promise<Result>
-  ): Promise<Result> => {
-    const plannedDecision = takePlannedDecision(operation);
-    await maybeDelay(plannedDecision?.latencyMs ?? 0);
-
-    if (
-      plannedDecision?.action === 'fail' &&
-      plannedDecision.phase === 'before'
-    ) {
-      return fail(operation, plannedDecision.error);
-    }
-
-    if (!plannedDecision && shouldFail(operation, count)) {
-      return fail(operation, getError());
-    }
-
-    const result = await run();
-    recordSuccess(operation);
-
-    if (
-      plannedDecision?.action === 'fail' &&
-      plannedDecision.phase === 'after'
-    ) {
-      return fail(operation, plannedDecision.error);
-    }
-
-    currentOptions.onSuccess?.(operation);
-    return result;
-  };
-
-  const transport: SyncTransport = {
-    async sync(request, transportOptions) {
-      const operation: FaultTransportOperation = request.push ? 'push' : 'pull';
-      const count = operation === 'push' ? state.pushCount : state.pullCount;
-
-      return runWithFaults(operation, count, () =>
-        baseTransport.sync(request, transportOptions)
-      );
-    },
-
-    async fetchSnapshotChunk(
-      request: { chunkId: string },
-      transportOptions?: SyncTransportOptions
-    ): Promise<Uint8Array> {
-      return runWithFaults('fetch', state.fetchCount, () =>
-        baseTransport.fetchSnapshotChunk(request, transportOptions)
-      );
-    },
-  };
-
-  return {
-    transport,
-    getState: () => ({ ...state }),
-    reset: () => {
-      state.pushCount = 0;
-      state.pullCount = 0;
-      state.fetchCount = 0;
-      state.failureCount = 0;
-      currentPlan = createActivePlan(currentOptions.plan);
-    },
-    setOptions: (newOptions) => {
-      currentOptions = { ...currentOptions, ...newOptions };
-      if ('plan' in newOptions) {
-        currentPlan = createActivePlan(currentOptions.plan);
-      }
-    },
+/**
+ * Fault injection at the transport seam (test doctrine, REVISE B4).
+ *
+ * Canonical home: the PUBLIC app test kit. The private conformance harness
+ * re-exports from here so both arm the SAME fault vocabulary — one
+ * implementation, publishable dependency direction (testkit ships to npm;
+ * conformance stays private).
+ *
+ * The harness owns the loopback between a ClientInstance and a
+ * ServerInstance; scenarios arm faults on this controller and the next
+ * matching exchange misbehaves — deterministically, with no timers. The
+ * only randomness is the truncation offset, drawn from a seeded PRNG so
+ * every run of a scenario byte-truncates at the same place.
+ *
+ * Fault vocabulary (§2.3, §1.4, §5.1):
+ * - drop request     — the request never reaches the server;
+ * - drop response    — the server processed it, the ack is lost;
+ * - duplicate        — the request is delivered twice (replayed bytes);
+ * - truncate         — the response is cut short (decode-error surfacing);
+ * - segment faults   — the same, at the segment download hop.
+ */
+
+/** Deterministic PRNG (mulberry32) — seeded per scenario. */
+export function seededRandom(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
   };
 }
 
-function createActivePlan(
-  plan: FaultPlanStep[] | undefined
-): ActiveFaultPlanStep[] {
-  if (!plan || plan.length === 0) {
-    return [];
+export function seedFromName(name: string): number {
+  let hash = 2166136261;
+  for (let i = 0; i < name.length; i++) {
+    hash ^= name.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
   }
-
-  return plan.flatMap((step) => {
-    const remaining = step.repeat ?? 1;
-    if (remaining <= 0) {
-      return [];
-    }
-
-    return [
-      {
-        operation: step.operation,
-        action: step.action ?? 'fail',
-        phase: step.phase ?? 'before',
-        remaining,
-        failWith: step.failWith,
-        latencyMs: step.latencyMs,
-      },
-    ];
-  });
-}
-
-export function createMockTransport(options?: {
-  pullResponse?: SyncPullResponse;
-  pushResponse?: SyncPushBatchResponse;
-  chunkData?: Uint8Array;
-}): SyncTransport {
-  return {
-    async sync(request) {
-      const result: {
-        ok: true;
-        push?: SyncPushBatchResponse;
-        pull?: SyncPullResponse;
-      } = { ok: true };
-
-      if (request.push) {
-        result.push = options?.pushResponse ?? {
-          ok: true,
-          commits: request.push.commits.map((commit) => ({
-            ok: true,
-            clientCommitId: commit.clientCommitId,
-            status: 'applied',
-            results: commit.operations.map((_: unknown, i: number) => ({
-              opIndex: i,
-              status: 'applied',
-            })),
-          })),
-        };
-      }
-
-      if (request.pull) {
-        result.pull = options?.pullResponse ?? {
-          ok: true,
-          subscriptions: [],
-        };
-      }
-
-      return result;
-    },
-
-    async fetchSnapshotChunk(): Promise<Uint8Array> {
-      return options?.chunkData ?? new Uint8Array();
-    },
-  };
+  return hash >>> 0;
 }
 
-export interface RecordingTransportResult {
-  transport: SyncTransport;
-  syncRequests: SyncCombinedRequest[];
-  fetchRequests: { chunkId: string }[];
-  clear: () => void;
+/** The error a faulted transport rejects with (client-observable). */
+export class TransportFault extends Error {
+  override readonly name = 'TransportFault';
+  /** Client drivers surface transport losses under this code. */
+  readonly code = 'transport.lost';
 }
 
-export function withRecording(
-  baseTransport: SyncTransport
-): RecordingTransportResult {
-  const syncRequests: SyncCombinedRequest[] = [];
-  const fetchRequests: { chunkId: string }[] = [];
-
-  const transport: SyncTransport = {
-    async sync(request, options) {
-      syncRequests.push(structuredClone(request));
-      return baseTransport.sync(request, options);
-    },
+export class TransportFaults {
+  /** Fail the next N sync requests before they reach the server. */
+  dropNextRequests = 0;
+  /** Deliver the next N sync requests, then lose their responses. */
+  dropNextResponses = 0;
+  /** Deliver the next sync request twice; return the second response. */
+  duplicateNextRequest = false;
+  /** Truncate the next sync response at a seeded offset. */
+  truncateNextResponse = false;
+  /** Fail the next N segment downloads before they reach the server. */
+  dropNextSegmentRequests = 0;
+  /** Truncate the next segment download at a seeded offset. */
+  truncateNextSegmentDownload = false;
+  /** Fail the next N signed-URL fetches (the CDN hop, §5.4). */
+  dropNextUrlFetches = 0;
+  /** Corrupt the next signed-URL fetch's bytes (§5.1 tamper). */
+  corruptNextUrlFetch = false;
+
+  readonly #random: () => number;
+
+  constructor(random: () => number) {
+    this.#random = random;
+  }
 
-    async fetchSnapshotChunk(request, options) {
-      fetchRequests.push({ ...request });
-      return baseTransport.fetchSnapshotChunk(request, options);
-    },
-  };
+  /** Seeded cut point: at least 1 byte kept, at least 1 byte removed. */
+  truncate(bytes: Uint8Array): Uint8Array {
+    const cut = 1 + Math.floor(this.#random() * (bytes.length - 1));
+    return bytes.slice(0, cut);
+  }
 
-  return {
-    transport,
-    syncRequests,
-    fetchRequests,
-    clear: () => {
-      syncRequests.length = 0;
-      fetchRequests.length = 0;
-    },
-  };
+  /** Flip one seeded byte — same length, different content address. */
+  corrupt(bytes: Uint8Array): Uint8Array {
+    const out = bytes.slice();
+    const index = Math.floor(this.#random() * out.length);
+    out[index] = (out[index] ?? 0) ^ 0xff;
+    return out;
+  }
 }

package/src/index.ts

@@ -1,14 +1,44 @@
-export * from './audit';
-export * from './client-bridge';
-export * from './deterministic';
-export * from './disposable';
-export * from './faults';
-export * from './hono-node-server';
-export * from './http-fixtures';
-export * from './project-scoped-tasks';
-export * from './realtime-ws';
-export * from './runtime-process';
-export * from './sync-builders';
-export * from './sync-http';
-export * from './sync-parse';
-export * from './sync-response';
+/**
+ * @syncular/testkit — the app-developer test kit (TODO §2).
+ *
+ * A small, documented surface over the shipped Syncular core: an in-memory
+ * server, N real clients on bun:sqlite through an in-process loopback (no
+ * HTTP), a shared virtual clock, per-client offline/online, and the
+ * conformance harness's transport-fault vocabulary. Designed for APP tests
+ * (readable, minimal) — not conformance (no driver/pairing machinery).
+ *
+ * The React helper lives behind `@syncular/testkit/react` so the core
+ * pulls in no React. See README.md for paste-ready examples.
+ */
+
+export type {
+  TestClient,
+  TestClientOptions,
+} from './client';
+export {
+  createVirtualClock,
+  DEFAULT_EPOCH_MS,
+  type VirtualClock,
+} from './clock';
+export {
+  type CreateTestSyncOptions,
+  createTestSync,
+  type TestClientOverrides,
+  type TestSync,
+} from './create-test-sync';
+// The transport-fault controller, re-exported from the conformance harness
+// (never duplicated) — the SAME vocabulary the reference pairing arms.
+export {
+  seededRandom,
+  seedFromName,
+  TransportFault,
+  TransportFaults,
+} from './faults';
+export {
+  allowAllScopes,
+  createTestServer,
+  DEFAULT_ACTOR,
+  DEFAULT_PARTITION,
+  type TestServer,
+  type TestServerOptions,
+} from './server';

package/src/react.ts

@@ -0,0 +1,46 @@
+/**
+ * React helper for the test kit (`@syncular/testkit/react`).
+ *
+ * `@syncular/react`'s `SyncProvider` already accepts any `SyncClient`, so
+ * mounting hooks against a test client is just:
+ *
+ *     <SyncProvider client={testClient.api}>…</SyncProvider>
+ *
+ * This module is the tiny convenience over that pattern: `syncWrapper`
+ * returns the `wrapper` prop `@testing-library/react`'s `renderHook` /
+ * `render` want, so a test never hand-writes the provider element.
+ *
+ *     import { renderHook, waitFor } from '@testing-library/react';
+ *     import { useSyncQuery } from '@syncular/react';
+ *     import { createTestSync } from '@syncular/testkit';
+ *     import { syncWrapper } from '@syncular/testkit/react';
+ *
+ *     const sync = await createTestSync({ schema });
+ *     const client = await sync.client('a');
+ *     const { result } = renderHook(
+ *       () => useSyncQuery('SELECT * FROM notes'),
+ *       { wrapper: syncWrapper(client) },
+ *     );
+ *
+ * `react` is an OPTIONAL peer of the kit: import this subpath only from a
+ * test that already depends on React. The core (`@syncular/testkit`)
+ * pulls in no React.
+ *
+ * NOTE: this file uses `createElement` (no JSX) so the kit typechecks under
+ * the repo's `.ts`-only root tsconfig — same posture as `SyncProvider`.
+ */
+import { SyncProvider } from '@syncular/react';
+import { createElement, type ReactNode } from 'react';
+import type { TestClient } from './client';
+
+/**
+ * Build the `wrapper` component `renderHook` / `render` take, providing the
+ * given test client to the Syncular hook tree. Pass a `TestClient` — its
+ * `.api` (the real `SyncClient`) is supplied to `SyncProvider`.
+ */
+export function syncWrapper(
+  client: TestClient,
+): (props: { children: ReactNode }) => ReactNode {
+  return ({ children }) =>
+    createElement(SyncProvider, { client: client.api }, children);
+}

package/src/server.ts

@@ -0,0 +1,102 @@
+/**
+ * The in-memory test server: one `SqliteServerStorage` (`:memory:`), a
+ * `MemorySegmentStore`, and a `RealtimeHub`, all sharing the test's virtual
+ * clock. It is the SHIPPED `@syncular/server` core — the kit adds no
+ * server logic, it only wires the pieces an app would wire in production
+ * (minus the HTTP adapter). Clients reach it through the loopback seam in
+ * `client.ts`, calling `handleSyncRequest` / `handleSegmentDownload`
+ * directly.
+ */
+
+import { type ClientSchema, compileClientSchema } from '@syncular/client';
+import {
+  createRealtimeHub,
+  MemorySegmentStore,
+  type RealtimeHub,
+  type ResolveScopes,
+  type ServerSchema,
+  SqliteServerStorage,
+  type SyncRequestContext,
+} from '@syncular/server';
+import type { VirtualClock } from './clock';
+
+/** Default partition every actor lives in (apps override via options). */
+export const DEFAULT_PARTITION = 'test';
+/** Default actor a client is bound to when none is given. */
+export const DEFAULT_ACTOR = 'test-actor';
+
+/**
+ * `resolveScopes` that grants every value (`'*'`) for every scope variable
+ * the schema declares — the "no authorization, just make it converge"
+ * default an app test wants. Override with your own resolver to exercise
+ * scope-scoping / revocation.
+ */
+export function allowAllScopes(schema: ClientSchema): ResolveScopes {
+  const compiled = compileClientSchema(schema);
+  const variables = new Set<string>();
+  for (const table of compiled.tables.values()) {
+    for (const variable of table.scopeColumnByVariable.keys()) {
+      variables.add(variable);
+    }
+  }
+  const allowed: Record<string, string[]> = {};
+  for (const variable of variables) allowed[variable] = ['*'];
+  return () => allowed;
+}
+
+export interface TestServerOptions {
+  readonly schema: ClientSchema;
+  readonly clock: VirtualClock;
+  readonly partition: string;
+  /** Defaults to {@link allowAllScopes}. */
+  readonly resolveScopes?: ResolveScopes;
+}
+
+/**
+ * The server half of a test sync. `ctxFor(actorId)` builds the per-request
+ * context the loopback transport feeds `handleSyncRequest`; `hub` is the
+ * realtime fanout every client's socket attaches to.
+ */
+export interface TestServer {
+  readonly storage: SqliteServerStorage;
+  readonly segments: MemorySegmentStore;
+  readonly hub: RealtimeHub;
+  readonly partition: string;
+  ctxFor(actorId: string): SyncRequestContext;
+  close(): void;
+}
+
+export function createTestServer(options: TestServerOptions): TestServer {
+  const { schema, clock, partition } = options;
+  const serverSchema = schema as ServerSchema;
+  const storage = new SqliteServerStorage();
+  const segments = new MemorySegmentStore();
+  const resolveScopes = options.resolveScopes ?? allowAllScopes(schema);
+  const clockFn = () => clock.now();
+  const hub = createRealtimeHub({
+    schema: serverSchema,
+    storage,
+    resolveScopes,
+    clock: clockFn,
+    segments,
+  });
+  return {
+    storage,
+    segments,
+    hub,
+    partition,
+    ctxFor: (actorId) => ({
+      partition,
+      actorId,
+      schema: serverSchema,
+      storage,
+      segments,
+      resolveScopes,
+      clock: clockFn,
+      realtime: hub,
+    }),
+    close: () => {
+      storage.db.close();
+    },
+  };
+}

package/dist/audit.d.ts

@@ -1,22 +0,0 @@
-export interface RedactedAuditChange {
-    redaction?: {
-        payload?: unknown;
-        reason?: unknown;
-    };
-    rowJson?: unknown;
-    scopes?: unknown;
-    [key: string]: unknown;
-}
-export interface RedactedAuditDebugExport {
-    commits?: Array<{
-        changes?: RedactedAuditChange[];
-        [key: string]: unknown;
-    }>;
-    [key: string]: unknown;
-}
-export declare function assertAuditChangeRedacted(change: RedactedAuditChange, message?: string): void;
-export declare function assertAuditJsonExcludes(value: unknown, forbiddenNeedles: readonly string[], message?: string): void;
-export declare function assertAuditDebugExportRedacted(value: RedactedAuditDebugExport, forbiddenNeedles?: readonly string[], message?: string): void;
-export declare function readJsonResponse<T>(response: Response): Promise<T>;
-export declare function readTextResponse(response: Response): Promise<string>;
-//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE;QACV,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;IACF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;QAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC,CAAC;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,SAAyC,GAC/C,IAAI,CAeN;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,gBAAgB,EAAE,SAAS,MAAM,EAAE,EACnC,OAAO,SAAwC,GAC9C,IAAI,CAQN;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,wBAAwB,EAC/B,gBAAgB,GAAE,SAAS,MAAM,EAAO,EACxC,OAAO,SAA+C,GACrD,IAAI,CAON;AAED,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAExE;AAED,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E"}