@syncular/testkit 0.0.6-96 → 0.1.0

package/src/faults.ts

@@ -1,11 +1,26 @@
 import type {
   SyncCombinedRequest,
   SyncPullResponse,
-  SyncPushResponse,
+  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;
@@ -14,6 +29,7 @@ export interface FaultTransportOptions {
   failOnPush?: boolean;
   failOnPull?: boolean;
   failOnFetch?: boolean;
+  plan?: FaultPlanStep[];
   onFail?: (operation: 'push' | 'pull' | 'fetch', error: Error) => void;
   onSuccess?: (operation: 'push' | 'pull' | 'fetch') => void;
 }
@@ -32,11 +48,28 @@ export interface FaultTransportResult {
   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,
@@ -46,29 +79,41 @@ export function withFaults(
 
   const defaultError = new Error('Simulated transport error');
 
-  const maybeDelay = async (): Promise<void> => {
-    if (currentOptions.latencyMs && currentOptions.latencyMs > 0) {
-      await new Promise((resolve) =>
-        setTimeout(resolve, currentOptions.latencyMs)
-      );
+  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: 'push' | 'pull' | 'fetch',
+    operation: FaultTransportOperation,
     count: number
   ): boolean => {
-    if (operation === 'push' && currentOptions.failOnPull) {
-      return false;
-    }
-    if (operation === 'pull' && currentOptions.failOnPush) {
+    if (!shouldTargetOperation(operation)) {
       return false;
     }
-    if (operation === 'fetch' && !currentOptions.failOnFetch) {
-      if (currentOptions.failOnPush || currentOptions.failOnPull) {
-        return false;
-      }
-    }
 
     if (
       currentOptions.failAfter !== undefined &&
@@ -86,51 +131,95 @@ export function withFaults(
 
   const getError = (): Error => currentOptions.failWith ?? defaultError;
 
-  const transport: SyncTransport = {
-    async sync(request, transportOptions) {
-      await maybeDelay();
+  const fail = (operation: FaultTransportOperation, error: Error): never => {
+    state.failureCount++;
+    currentOptions.onFail?.(operation, error);
+    throw error;
+  };
 
-      const operation = request.push ? 'push' : 'pull';
-      const count = operation === 'push' ? state.pushCount : state.pullCount;
+  const recordSuccess = (operation: FaultTransportOperation): void => {
+    if (operation === 'push') {
+      state.pushCount++;
+      return;
+    }
+    if (operation === 'pull') {
+      state.pullCount++;
+      return;
+    }
+    state.fetchCount++;
+  };
 
-      if (shouldFail(operation, count)) {
-        const error = getError();
-        state.failureCount++;
-        currentOptions.onFail?.(operation, error);
-        throw error;
-      }
+  const takePlannedDecision = (
+    operation: FaultTransportOperation
+  ): PlannedFaultDecision | null => {
+    const step = currentPlan.find(
+      (candidate) =>
+        candidate.remaining > 0 &&
+        (candidate.operation === 'any' || candidate.operation === operation)
+    );
+    if (!step) {
+      return null;
+    }
 
-      if (operation === 'push') {
-        state.pushCount++;
-      } else {
-        state.pullCount++;
-      }
+    step.remaining -= 1;
+    return {
+      action: step.action,
+      phase: step.phase,
+      error: step.failWith ?? getError(),
+      latencyMs: step.latencyMs ?? 0,
+    };
+  };
 
-      const result = await baseTransport.sync(request, transportOptions);
-      currentOptions.onSuccess?.(operation);
-      return result;
+  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> {
-      await maybeDelay();
-
-      if (shouldFail('fetch', state.fetchCount)) {
-        const error = getError();
-        state.failureCount++;
-        currentOptions.onFail?.('fetch', error);
-        throw error;
-      }
-
-      state.fetchCount++;
-      const result = await baseTransport.fetchSnapshotChunk(
-        request,
-        transportOptions
+      return runWithFaults('fetch', state.fetchCount, () =>
+        baseTransport.fetchSnapshotChunk(request, transportOptions)
       );
-      currentOptions.onSuccess?.('fetch');
-      return result;
     },
   };
 
@@ -142,33 +231,67 @@ export function withFaults(
       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);
+      }
     },
   };
 }
 
+function createActivePlan(
+  plan: FaultPlanStep[] | undefined
+): ActiveFaultPlanStep[] {
+  if (!plan || plan.length === 0) {
+    return [];
+  }
+
+  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?: SyncPushResponse;
+  pushResponse?: SyncPushBatchResponse;
   chunkData?: Uint8Array;
 }): SyncTransport {
   return {
     async sync(request) {
       const result: {
         ok: true;
-        push?: SyncPushResponse;
+        push?: SyncPushBatchResponse;
         pull?: SyncPullResponse;
       } = { ok: true };
 
       if (request.push) {
         result.push = options?.pushResponse ?? {
           ok: true,
-          status: 'applied',
-          results: request.push.operations.map((_, i) => ({
-            opIndex: i,
+          commits: request.push.commits.map((commit) => ({
+            ok: true,
+            clientCommitId: commit.clientCommitId,
             status: 'applied',
+            results: commit.operations.map((_: unknown, i: number) => ({
+              opIndex: i,
+              status: 'applied',
+            })),
           })),
         };
       }

package/src/hono-node-server.ts

@@ -30,7 +30,7 @@ export function createNodeHonoServer(
     options?.corsAllowMethods ?? 'GET, POST, PUT, DELETE, OPTIONS';
   const corsAllowHeaders =
     options?.corsAllowHeaders ??
-    'content-type, x-actor-id, x-syncular-transport-path, x-user-id';
+    'authorization, content-type, x-actor-id, x-partition-id, x-syncular-schema-version, x-syncular-snapshot-scopes, x-syncular-transport-path, x-upload-token, x-user-id';
   const corsMaxAgeSeconds = options?.corsMaxAgeSeconds ?? 86400;
 
   return createServer(async (req, res) => {

package/src/http-fixtures.ts

@@ -1,40 +1,23 @@
-import {
-  type ClientHandlerCollection,
-  enqueueOutboxCommit,
-  ensureClientSyncSchema,
-  type SyncClientDb,
-  type SyncOnceOptions,
-  type SyncOnceResult,
-  type SyncPullOnceOptions,
-  type SyncPullResponse,
-  type SyncPushOnceOptions,
-  type SyncPushOnceResult,
-  syncOnce,
-  syncPullOnce,
-  syncPushOnce,
-} from '@syncular/client';
-import { createDatabase, type SyncTransport } from '@syncular/core';
-import { createBunSqliteDialect } from '@syncular/dialect-bun-sqlite';
-import { createPgliteDialect } from '@syncular/dialect-pglite';
+import { createDatabase } from '@syncular/core';
 import {
   ensureSyncSchema,
   type ServerSyncDialect,
   type ServerTableHandler,
   type SyncCoreDb,
 } from '@syncular/server';
-import { createPostgresServerDialect } from '@syncular/server-dialect-postgres';
-import { createSqliteServerDialect } from '@syncular/server-dialect-sqlite';
+import { createBunSqliteDialect } from '@syncular/server/bun-sqlite';
 import {
   type CreateSyncRoutesOptions,
   createSyncRoutes,
-} from '@syncular/server-hono';
-import { createHttpTransport } from '@syncular/transport-http';
+} from '@syncular/server/hono';
+import { createPgliteDialect } from '@syncular/server/pglite';
+import { createPostgresServerDialect } from '@syncular/server/postgres';
+import { createSqliteServerDialect } from '@syncular/server/sqlite';
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';
 import { createNodeHonoServer } from './hono-node-server';
 
 export type HttpServerDialect = 'sqlite' | 'pglite';
-export type HttpClientDialect = 'bun-sqlite' | 'pglite';
 
 export interface HttpServerFixture<DB extends SyncCoreDb> {
   db: Kysely<DB>;
@@ -61,38 +44,6 @@ export interface CreateHttpServerFixtureOptions<DB extends SyncCoreDb> {
   corsMaxAgeSeconds?: number;
 }
 
-export interface HttpClientFixture<DB extends SyncClientDb> {
-  db: Kysely<DB>;
-  transport: SyncTransport;
-  handlers: ClientHandlerCollection<DB>;
-  actorId: string;
-  clientId: string;
-  enqueue: (
-    args: Parameters<typeof enqueueOutboxCommit<DB>>[1]
-  ) => Promise<{ id: string; clientCommitId: string }>;
-  push: (
-    options?: Omit<SyncPushOnceOptions, 'clientId' | 'actorId'>
-  ) => Promise<SyncPushOnceResult>;
-  pull: (
-    options: Omit<SyncPullOnceOptions, 'clientId' | 'actorId'>
-  ) => Promise<SyncPullResponse>;
-  syncOnce: (
-    options: Omit<SyncOnceOptions, 'clientId' | 'actorId'>
-  ) => Promise<SyncOnceResult>;
-  destroy: () => Promise<void>;
-}
-
-export interface CreateHttpClientFixtureOptions<DB extends SyncClientDb> {
-  clientDialect: HttpClientDialect;
-  baseUrl: string;
-  actorId: string;
-  clientId: string;
-  createTables: (db: Kysely<DB>) => Promise<void>;
-  registerHandlers: (handlers: ClientHandlerCollection<DB>) => void;
-  fetch?: typeof globalThis.fetch;
-  getHeaders?: () => Record<string, string>;
-}
-
 const PGLITE_INIT_ATTEMPTS = 3;
 
 function isTransientPgliteInitError(error: Error): boolean {
@@ -234,75 +185,3 @@ export async function createHttpServerFixture<DB extends SyncCoreDb>(
     },
   };
 }
-
-export async function createHttpClientFixture<DB extends SyncClientDb>(
-  options: CreateHttpClientFixtureOptions<DB>
-): Promise<HttpClientFixture<DB>> {
-  const db = await withPgliteInitRetry(
-    options.clientDialect === 'pglite',
-    async () => {
-      const candidateDb =
-        options.clientDialect === 'pglite'
-          ? createDatabase<DB>({
-              dialect: createPgliteDialect(),
-              family: 'postgres',
-            })
-          : createDatabase<DB>({
-              dialect: createBunSqliteDialect({ path: ':memory:' }),
-              family: 'sqlite',
-            });
-
-      try {
-        await ensureClientSyncSchema(candidateDb);
-        await options.createTables(candidateDb);
-        return candidateDb;
-      } catch (error) {
-        await candidateDb.destroy();
-        throw error;
-      }
-    }
-  );
-
-  const handlers: ClientHandlerCollection<DB> = [];
-  options.registerHandlers(handlers);
-
-  const transport = createHttpTransport({
-    baseUrl: options.baseUrl,
-    getHeaders:
-      options.getHeaders ??
-      (() => ({
-        'x-actor-id': options.actorId,
-      })),
-    ...(options.fetch ? { fetch: options.fetch } : {}),
-  });
-
-  return {
-    db,
-    transport,
-    handlers,
-    actorId: options.actorId,
-    clientId: options.clientId,
-    enqueue: (args) => enqueueOutboxCommit(db, args),
-    push: (pushOptions) =>
-      syncPushOnce(db, transport, {
-        clientId: options.clientId,
-        actorId: options.actorId,
-        plugins: pushOptions?.plugins,
-      }),
-    pull: (pullOptions) =>
-      syncPullOnce(db, transport, handlers, {
-        ...pullOptions,
-        clientId: options.clientId,
-        actorId: options.actorId,
-      }),
-    syncOnce: (syncOptions) =>
-      syncOnce(db, transport, handlers, {
-        ...syncOptions,
-        clientId: options.clientId,
-        actorId: options.actorId,
-      }),
-    destroy: async () => {
-      await db.destroy();
-    },
-  };
-}

package/src/index.ts

@@ -1,15 +1,13 @@
-export * from './assertions';
+export * from './audit';
+export * from './client-bridge';
 export * from './deterministic';
 export * from './disposable';
 export * from './faults';
-export * from './fixtures';
 export * from './hono-node-server';
 export * from './http-fixtures';
 export * from './project-scoped-tasks';
 export * from './realtime-ws';
-export * from './resources';
 export * from './runtime-process';
-export * from './scenario-flow';
 export * from './sync-builders';
 export * from './sync-http';
 export * from './sync-parse';

package/src/project-scoped-tasks.ts

@@ -150,8 +150,8 @@ export function createProjectScopedTasksHandler<
           result: {
             opIndex,
             status: 'error',
-            error: `UNKNOWN_TABLE:${op.table}`,
-            code: 'UNKNOWN_TABLE',
+            error: `Unknown table: ${op.table}`,
+            code: 'sync.unknown_table',
             retriable: false,
           },
           emittedChanges: [],
@@ -216,6 +216,7 @@ export function createProjectScopedTasksHandler<
             opIndex,
             status: 'conflict',
             message: `Version conflict: server=${existing.server_version}, base=${op.base_version}`,
+            code: 'sync.version_conflict',
             server_version: existing.server_version,
             server_row: {
               id: existing.id,
@@ -236,8 +237,8 @@ export function createProjectScopedTasksHandler<
           result: {
             opIndex,
             status: 'error',
-            error: 'MISSING_PROJECT_ID',
-            code: 'INVALID_REQUEST',
+            error: 'Missing project id',
+            code: 'sync.invalid_request',
             retriable: false,
           },
           emittedChanges: [],
@@ -321,6 +322,7 @@ export function createProjectScopedTasksSubscription(
     },
     cursor: options.cursor ?? 0,
     bootstrapState: null,
+    crdtStateVectors: [],
   };
 }
 

package/src/sync-builders.ts

@@ -2,7 +2,7 @@ import type {
   SyncCombinedRequest,
   SyncOperation,
   SyncPullRequest,
-  SyncPushRequest,
+  SyncPushBatchRequest,
   SyncSubscriptionRequest,
 } from '@syncular/core';
 
@@ -50,6 +50,7 @@ export interface CreateSyncSubscriptionOptions {
   params?: SyncSubscriptionRequest['params'];
   cursor?: number;
   bootstrapState?: SyncSubscriptionRequest['bootstrapState'];
+  crdtStateVectors?: SyncSubscriptionRequest['crdtStateVectors'];
 }
 
 export function createSyncSubscription(
@@ -62,6 +63,7 @@ export function createSyncSubscription(
     ...(options.params ? { params: options.params } : {}),
     cursor: options.cursor ?? 0,
     bootstrapState: options.bootstrapState ?? null,
+    crdtStateVectors: options.crdtStateVectors ?? [],
   };
 }
 
@@ -74,17 +76,22 @@ export interface CreateSyncPushRequestOptions {
 
 export function createSyncPushRequest(
   options: CreateSyncPushRequestOptions
-): SyncPushRequest {
+): SyncPushBatchRequest {
   return {
     clientId: options.clientId,
-    clientCommitId: options.clientCommitId,
-    operations: options.operations,
-    schemaVersion: options.schemaVersion ?? 1,
+    commits: [
+      {
+        clientCommitId: options.clientCommitId,
+        operations: options.operations,
+        schemaVersion: options.schemaVersion ?? 1,
+      },
+    ],
   };
 }
 
 export interface CreateSyncPullRequestOptions {
   clientId: string;
+  schemaVersion?: number;
   subscriptions: SyncSubscriptionRequest[];
   limitCommits?: number;
   limitSnapshotRows?: number;
@@ -97,6 +104,7 @@ export function createSyncPullRequest(
 ): SyncPullRequest {
   return {
     clientId: options.clientId,
+    schemaVersion: options.schemaVersion ?? 1,
     subscriptions: options.subscriptions,
     limitCommits: options.limitCommits ?? 50,
     ...(options.limitSnapshotRows !== undefined
@@ -113,7 +121,7 @@ export function createSyncPullRequest(
 
 export interface CreateSyncCombinedRequestOptions {
   clientId: string;
-  push?: Omit<SyncPushRequest, 'clientId'>;
+  push?: Omit<SyncPushBatchRequest, 'clientId'>;
   pull?: Omit<SyncPullRequest, 'clientId'>;
 }
 

package/src/sync-response.ts

@@ -4,8 +4,6 @@ import {
   type SyncPullResponse,
 } from '@syncular/core';
 
-export type SyncChangeRecord = SyncChange;
-
 export type SyncSubscriptionRecord = Pick<
   SyncPullResponse['subscriptions'][number],
   'id' | 'commits'
@@ -14,7 +12,7 @@ export type SyncSubscriptionRecord = Pick<
 export function subscriptionChanges(
   subscriptions: SyncSubscriptionRecord[] | undefined,
   subscriptionId: string
-): SyncChangeRecord[] {
+): SyncChange[] {
   const subscription = subscriptions?.find(
     (item) => item.id === subscriptionId
   );
@@ -29,13 +27,13 @@ export function findSubscriptionChange(
   subscriptions: SyncSubscriptionRecord[] | undefined,
   subscriptionId: string,
   rowId: string
-): SyncChangeRecord | undefined {
+): SyncChange | undefined {
   const changes = subscriptionChanges(subscriptions, subscriptionId);
   return changes.find((change) => change.row_id === rowId);
 }
 
 export function subscriptionChangeRow(
-  change: SyncChangeRecord | undefined
+  change: SyncChange | undefined
 ): Record<string, unknown> | undefined {
   if (!change) {
     return undefined;