@syncular/testkit 0.0.0

package/src/hono-node-server.ts

@@ -0,0 +1,86 @@
+import { createServer, type Server as NodeServer } from 'node:http';
+import type { Hono } from 'hono';
+
+export interface NodeHonoServerOptions {
+  cors?: boolean;
+  corsAllowMethods?: string;
+  corsAllowHeaders?: string;
+  corsMaxAgeSeconds?: number;
+}
+
+export function createNodeHonoServer(
+  app: Hono,
+  options?: NodeHonoServerOptions
+): NodeServer {
+  const corsEnabled = options?.cors ?? true;
+  const corsAllowMethods =
+    options?.corsAllowMethods ?? 'GET, POST, PUT, DELETE, OPTIONS';
+  const corsAllowHeaders =
+    options?.corsAllowHeaders ??
+    'content-type, x-actor-id, x-syncular-transport-path, x-user-id';
+  const corsMaxAgeSeconds = options?.corsMaxAgeSeconds ?? 86400;
+
+  return createServer(async (req, res) => {
+    const url = `http://localhost${req.url ?? '/'}`;
+
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+      if (!value) {
+        continue;
+      }
+
+      headers.set(key, Array.isArray(value) ? value.join(', ') : value);
+    }
+
+    if (corsEnabled && req.method === 'OPTIONS') {
+      res.writeHead(204, {
+        'access-control-allow-origin': '*',
+        'access-control-allow-methods': corsAllowMethods,
+        'access-control-allow-headers': corsAllowHeaders,
+        'access-control-max-age': String(corsMaxAgeSeconds),
+      });
+      res.end();
+      return;
+    }
+
+    const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
+    const body = hasBody
+      ? await new Promise<Uint8Array>((resolve) => {
+          const chunks: Uint8Array[] = [];
+          req.on('data', (chunk: Uint8Array) => chunks.push(chunk));
+          req.on('end', () => {
+            const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+            const merged = new Uint8Array(total);
+            let offset = 0;
+            for (const chunk of chunks) {
+              merged.set(chunk, offset);
+              offset += chunk.length;
+            }
+            resolve(merged);
+          });
+        })
+      : undefined;
+
+    const requestBody = body ? Uint8Array.from(body) : undefined;
+
+    const request = new Request(url, {
+      method: req.method,
+      headers,
+      body: requestBody,
+    });
+
+    const response = await app.fetch(request);
+    const responseHeaders: Record<string, string> = {};
+    response.headers.forEach((value, key) => {
+      responseHeaders[key] = value;
+    });
+
+    if (corsEnabled) {
+      responseHeaders['access-control-allow-origin'] = '*';
+    }
+
+    res.writeHead(response.status, responseHeaders);
+    const bytes = Buffer.from(await response.arrayBuffer());
+    res.end(bytes);
+  });
+}

package/src/http-fixtures.ts

@@ -0,0 +1,213 @@
+import {
+  ClientTableRegistry,
+  enqueueOutboxCommit,
+  ensureClientSyncSchema,
+  type SyncClientDb,
+  type SyncOnceOptions,
+  type SyncOnceResult,
+  type SyncPullOnceOptions,
+  type SyncPullResponse,
+  type SyncPushOnceOptions,
+  type SyncPushOnceResult,
+  syncOnce,
+  syncPullOnce,
+  syncPushOnce,
+} from '@syncular/client';
+import type { SyncTransport } from '@syncular/core';
+import { createBunSqliteDb } from '@syncular/dialect-bun-sqlite';
+import { createPgliteDb } from '@syncular/dialect-pglite';
+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 {
+  type CreateSyncRoutesOptions,
+  createSyncRoutes,
+} from '@syncular/server-hono';
+import { createHttpTransport } from '@syncular/transport-http';
+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>;
+  dialect: ServerSyncDialect;
+  app: Hono;
+  httpServer: ReturnType<typeof createNodeHonoServer>;
+  baseUrl: string;
+  destroy: () => Promise<void>;
+}
+
+export interface CreateHttpServerFixtureOptions<DB extends SyncCoreDb> {
+  serverDialect: HttpServerDialect;
+  createTables: (db: Kysely<DB>) => Promise<void>;
+  handlers: ServerTableHandler<DB>[];
+  authenticate: CreateSyncRoutesOptions<DB>['authenticate'];
+  sync?: CreateSyncRoutesOptions<DB>['sync'];
+  routePath?: string;
+  cors?: boolean;
+  corsAllowMethods?: string;
+  corsAllowHeaders?: string;
+  corsMaxAgeSeconds?: number;
+}
+
+export interface HttpClientFixture<DB extends SyncClientDb> {
+  db: Kysely<DB>;
+  transport: SyncTransport;
+  handlers: ClientTableRegistry<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: ClientTableRegistry<DB>) => void;
+  fetch?: typeof globalThis.fetch;
+  getHeaders?: () => Record<string, string>;
+}
+
+export async function createHttpServerFixture<DB extends SyncCoreDb>(
+  options: CreateHttpServerFixtureOptions<DB>
+): Promise<HttpServerFixture<DB>> {
+  const db =
+    options.serverDialect === 'pglite'
+      ? createPgliteDb<DB>()
+      : createBunSqliteDb<DB>({ path: ':memory:' });
+
+  const dialect =
+    options.serverDialect === 'pglite'
+      ? createPostgresServerDialect()
+      : createSqliteServerDialect();
+
+  await ensureSyncSchema(db, dialect);
+  if (dialect.ensureConsoleSchema) {
+    await dialect.ensureConsoleSchema(db);
+  }
+  await options.createTables(db);
+
+  const app = new Hono();
+  const routePath = options.routePath ?? '/sync';
+
+  const syncRoutes = createSyncRoutes<DB>({
+    db,
+    dialect,
+    handlers: options.handlers,
+    authenticate: options.authenticate,
+    sync: options.sync,
+  });
+
+  app.route(routePath, syncRoutes);
+
+  const httpServer = createNodeHonoServer(app, {
+    cors: options.cors,
+    corsAllowMethods: options.corsAllowMethods,
+    corsAllowHeaders: options.corsAllowHeaders,
+    corsMaxAgeSeconds: options.corsMaxAgeSeconds,
+  });
+
+  await new Promise<void>((resolve) => {
+    httpServer.listen(0, resolve);
+  });
+
+  const address = httpServer.address();
+  const port = typeof address === 'object' && address ? address.port : 0;
+
+  return {
+    db,
+    dialect,
+    app,
+    httpServer,
+    baseUrl: `http://localhost:${port}`,
+    destroy: async () => {
+      await new Promise<void>((resolve, reject) => {
+        httpServer.close((err) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve();
+        });
+      });
+      await db.destroy();
+    },
+  };
+}
+
+export async function createHttpClientFixture<DB extends SyncClientDb>(
+  options: CreateHttpClientFixtureOptions<DB>
+): Promise<HttpClientFixture<DB>> {
+  const db =
+    options.clientDialect === 'pglite'
+      ? createPgliteDb<DB>()
+      : createBunSqliteDb<DB>({ path: ':memory:' });
+
+  await ensureClientSyncSchema(db);
+  await options.createTables(db);
+
+  const handlers = new ClientTableRegistry<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

@@ -0,0 +1,6 @@
+export * from './assertions';
+export * from './faults';
+export * from './fixtures';
+export * from './hono-node-server';
+export * from './http-fixtures';
+export * from './project-scoped-tasks';

package/src/project-scoped-tasks.ts

@@ -0,0 +1,299 @@
+import { isRecord, type SyncOperation } from '@syncular/core';
+import type {
+  ApplyOperationResult,
+  EmittedChange,
+  ServerTableHandler,
+  SyncCoreDb,
+} from '@syncular/server';
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+
+export interface ProjectScopedTasksRow {
+  id: string;
+  title: string;
+  completed: number;
+  user_id: string;
+  project_id: string;
+  server_version: number;
+}
+
+export interface ProjectScopedTasksDb extends SyncCoreDb {
+  tasks: ProjectScopedTasksRow;
+}
+
+export const PROJECT_SCOPED_TASKS_DDL = `
+  CREATE TABLE IF NOT EXISTS tasks (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL DEFAULT '',
+    completed INTEGER NOT NULL DEFAULT 0,
+    user_id TEXT NOT NULL,
+    project_id TEXT NOT NULL,
+    server_version INTEGER NOT NULL DEFAULT 1
+  )
+`;
+
+export interface ProjectScopedTasksHandlerOptions {
+  projectScopeCount?: number;
+}
+
+function parseProjectScopedTaskPayload(payload: SyncOperation['payload']): {
+  title?: string;
+  completed?: number;
+  project_id?: string;
+} {
+  if (!isRecord(payload)) {
+    return {};
+  }
+
+  return {
+    title: typeof payload.title === 'string' ? payload.title : undefined,
+    completed:
+      typeof payload.completed === 'number' ? payload.completed : undefined,
+    project_id:
+      typeof payload.project_id === 'string' ? payload.project_id : undefined,
+  };
+}
+
+export async function ensureProjectScopedTasksTable<
+  DB extends SyncCoreDb & { tasks: ProjectScopedTasksRow },
+>(db: Kysely<DB>): Promise<void> {
+  await sql.raw(PROJECT_SCOPED_TASKS_DDL).execute(db);
+}
+
+export function createProjectScopedTasksHandler<
+  DB extends SyncCoreDb & { tasks: ProjectScopedTasksRow },
+>(options: ProjectScopedTasksHandlerOptions = {}): ServerTableHandler<DB> {
+  const projectScopeCount = Math.max(1, options.projectScopeCount ?? 100);
+
+  return {
+    table: 'tasks',
+    scopePatterns: ['user:{user_id}:project:{project_id}'],
+
+    async resolveScopes(ctx) {
+      return {
+        user_id: ctx.actorId,
+        project_id: Array.from(
+          { length: projectScopeCount },
+          (_, index) => `p${index}`
+        ),
+      };
+    },
+
+    extractScopes(row: Record<string, unknown>) {
+      return {
+        user_id: String(row.user_id ?? ''),
+        project_id: String(row.project_id ?? ''),
+      };
+    },
+
+    async snapshot(ctx) {
+      const userIdValue = ctx.scopeValues.user_id;
+      const projectIdValue = ctx.scopeValues.project_id;
+      const userId = Array.isArray(userIdValue) ? userIdValue[0] : userIdValue;
+      const projectId = Array.isArray(projectIdValue)
+        ? projectIdValue[0]
+        : projectIdValue;
+
+      if (!userId || userId !== ctx.actorId) {
+        return { rows: [], nextCursor: null };
+      }
+
+      if (!projectId) {
+        return { rows: [], nextCursor: null };
+      }
+
+      const pageSize = Math.max(1, Math.min(10_000, ctx.limit));
+      const cursor = ctx.cursor;
+
+      const cursorFilter =
+        cursor && cursor.length > 0
+          ? sql`and ${sql.ref('id')} > ${sql.val(cursor)}`
+          : sql``;
+
+      const result = await sql<ProjectScopedTasksRow>`
+        select id, title, completed, user_id, project_id, server_version
+        from tasks
+        where user_id = ${sql.val(userId)}
+          and project_id = ${sql.val(projectId)}
+        ${cursorFilter}
+        order by id asc
+        limit ${sql.val(pageSize + 1)}
+      `.execute(ctx.db);
+
+      const rows = result.rows;
+      const hasMore = rows.length > pageSize;
+      const pageRows = hasMore ? rows.slice(0, pageSize) : rows;
+      const nextCursor = hasMore
+        ? (pageRows[pageRows.length - 1]?.id ?? null)
+        : null;
+
+      return {
+        rows: pageRows,
+        nextCursor:
+          typeof nextCursor === 'string' && nextCursor.length > 0
+            ? nextCursor
+            : null,
+      };
+    },
+
+    async applyOperation(
+      ctx,
+      op: SyncOperation,
+      opIndex: number
+    ): Promise<ApplyOperationResult> {
+      if (op.table !== 'tasks') {
+        return {
+          result: {
+            opIndex,
+            status: 'error',
+            error: `UNKNOWN_TABLE:${op.table}`,
+            code: 'UNKNOWN_TABLE',
+            retriable: false,
+          },
+          emittedChanges: [],
+        };
+      }
+
+      if (op.op === 'delete') {
+        const existingResult = await sql<{ id: string; project_id: string }>`
+          select id, project_id from tasks
+          where id = ${sql.val(op.row_id)} and user_id = ${sql.val(ctx.actorId)}
+          limit 1
+        `.execute(ctx.trx);
+        const existing = existingResult.rows[0];
+
+        if (!existing) {
+          return { result: { opIndex, status: 'applied' }, emittedChanges: [] };
+        }
+
+        await sql`
+          delete from tasks
+          where id = ${sql.val(op.row_id)} and user_id = ${sql.val(ctx.actorId)}
+        `.execute(ctx.trx);
+
+        const emitted: EmittedChange = {
+          table: 'tasks',
+          row_id: op.row_id,
+          op: 'delete',
+          row_json: null,
+          row_version: null,
+          scopes: { user_id: ctx.actorId, project_id: existing.project_id },
+        };
+
+        return {
+          result: { opIndex, status: 'applied' },
+          emittedChanges: [emitted],
+        };
+      }
+
+      const payload = parseProjectScopedTaskPayload(op.payload);
+
+      const existingResult = await sql<{
+        id: string;
+        title: string;
+        completed: number;
+        project_id: string;
+        server_version: number;
+      }>`
+        select id, title, completed, project_id, server_version
+        from tasks
+        where id = ${sql.val(op.row_id)} and user_id = ${sql.val(ctx.actorId)}
+        limit 1
+      `.execute(ctx.trx);
+      const existing = existingResult.rows[0];
+
+      if (
+        existing &&
+        op.base_version != null &&
+        existing.server_version !== op.base_version
+      ) {
+        return {
+          result: {
+            opIndex,
+            status: 'conflict',
+            message: `Version conflict: server=${existing.server_version}, base=${op.base_version}`,
+            server_version: existing.server_version,
+            server_row: {
+              id: existing.id,
+              title: existing.title,
+              completed: existing.completed,
+              user_id: ctx.actorId,
+              project_id: existing.project_id,
+              server_version: existing.server_version,
+            },
+          },
+          emittedChanges: [],
+        };
+      }
+
+      const projectId = payload.project_id ?? existing?.project_id;
+      if (!projectId) {
+        return {
+          result: {
+            opIndex,
+            status: 'error',
+            error: 'MISSING_PROJECT_ID',
+            code: 'INVALID_REQUEST',
+            retriable: false,
+          },
+          emittedChanges: [],
+        };
+      }
+
+      if (existing) {
+        const nextVersion = existing.server_version + 1;
+        await sql`
+          update tasks set
+            title = ${sql.val(payload.title ?? existing.title)},
+            completed = ${sql.val(payload.completed ?? existing.completed)},
+            server_version = ${sql.val(nextVersion)}
+          where id = ${sql.val(op.row_id)} and user_id = ${sql.val(ctx.actorId)}
+        `.execute(ctx.trx);
+      } else {
+        await sql`
+          insert into tasks (id, title, completed, user_id, project_id, server_version)
+          values (
+            ${sql.val(op.row_id)},
+            ${sql.val(payload.title ?? '')},
+            ${sql.val(payload.completed ?? 0)},
+            ${sql.val(ctx.actorId)},
+            ${sql.val(projectId)},
+            ${sql.val(1)}
+          )
+        `.execute(ctx.trx);
+      }
+
+      const updatedResult = await sql<ProjectScopedTasksRow>`
+        select id, title, completed, user_id, project_id, server_version
+        from tasks
+        where id = ${sql.val(op.row_id)} and user_id = ${sql.val(ctx.actorId)}
+        limit 1
+      `.execute(ctx.trx);
+      const updated = updatedResult.rows[0];
+      if (!updated) {
+        throw new Error('TASKS_ROW_NOT_FOUND');
+      }
+
+      const emitted: EmittedChange = {
+        table: 'tasks',
+        row_id: op.row_id,
+        op: 'upsert',
+        row_json: {
+          id: updated.id,
+          title: updated.title,
+          completed: updated.completed,
+          user_id: updated.user_id,
+          project_id: updated.project_id,
+          server_version: updated.server_version,
+        },
+        row_version: updated.server_version,
+        scopes: { user_id: ctx.actorId, project_id: updated.project_id },
+      };
+
+      return {
+        result: { opIndex, status: 'applied' },
+        emittedChanges: [emitted],
+      };
+    },
+  };
+}