@syncular/server 0.0.1 → 0.0.2-127

package/src/proxy/handler.test.ts

@@ -0,0 +1,120 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import type { Kysely } from 'kysely';
+import { createBunSqliteDb } from '../../../dialect-bun-sqlite/src';
+import { createSqliteServerDialect } from '../../../server-dialect-sqlite/src';
+import { ensureSyncSchema } from '../migrate';
+import type { SyncCoreDb } from '../schema';
+import { executeProxyQuery } from './handler';
+import { ProxyTableRegistry } from './registry';
+
+interface TasksTable {
+  id: string;
+  user_id: string;
+  title: string;
+  server_version: number;
+}
+
+interface ProxyTestDb extends SyncCoreDb {
+  tasks: TasksTable;
+}
+
+describe('executeProxyQuery', () => {
+  let db: Kysely<ProxyTestDb>;
+  const dialect = createSqliteServerDialect();
+  const handlers = new ProxyTableRegistry().register({
+    table: 'tasks',
+    computeScopes: (row) => ({
+      user_id: String(row.user_id),
+    }),
+  });
+
+  beforeEach(async () => {
+    db = createBunSqliteDb<ProxyTestDb>({ path: ':memory:' });
+    await ensureSyncSchema(db, dialect);
+
+    await db.schema
+      .createTable('tasks')
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('user_id', 'text', (col) => col.notNull())
+      .addColumn('title', 'text', (col) => col.notNull())
+      .addColumn('server_version', 'integer', (col) => col.notNull())
+      .execute();
+
+    await db
+      .insertInto('tasks')
+      .values({
+        id: 't1',
+        user_id: 'u1',
+        title: 'old title',
+        server_version: 1,
+      })
+      .execute();
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+  });
+
+  it('tracks comment-prefixed mutations in the sync oplog', async () => {
+    const result = await executeProxyQuery({
+      db,
+      dialect,
+      handlers,
+      ctx: { actorId: 'actor-1', clientId: 'proxy-client-1' },
+      sqlQuery:
+        '/* admin */ UPDATE tasks SET title = $1, server_version = server_version + 1 WHERE id = $2',
+      parameters: ['new title', 't1'],
+    });
+
+    expect(result.rowCount).toBe(1);
+    expect(result.commitSeq).toBeGreaterThan(0);
+
+    const commitCount = await db
+      .selectFrom('sync_commits')
+      .select(({ fn }) => fn.countAll().as('count'))
+      .executeTakeFirstOrThrow();
+    expect(Number(commitCount.count)).toBe(1);
+
+    const changeCount = await db
+      .selectFrom('sync_changes')
+      .select(({ fn }) => fn.countAll().as('count'))
+      .executeTakeFirstOrThrow();
+    expect(Number(changeCount.count)).toBe(1);
+
+    const updated = await db
+      .selectFrom('tasks')
+      .select(['title', 'server_version'])
+      .where('id', '=', 't1')
+      .executeTakeFirstOrThrow();
+    expect(updated.title).toBe('new title');
+    expect(updated.server_version).toBe(2);
+  });
+
+  it('rejects non-wildcard RETURNING on synced-table mutations', async () => {
+    await expect(
+      executeProxyQuery({
+        db,
+        dialect,
+        handlers,
+        ctx: { actorId: 'actor-1', clientId: 'proxy-client-1' },
+        sqlQuery: 'UPDATE tasks SET title = $1 WHERE id = $2 RETURNING id',
+        parameters: ['blocked title', 't1'],
+      })
+    ).rejects.toThrow(
+      'Proxy mutation on synced table "tasks" must use RETURNING * (or omit RETURNING)'
+    );
+
+    const commitCount = await db
+      .selectFrom('sync_commits')
+      .select(({ fn }) => fn.countAll().as('count'))
+      .executeTakeFirstOrThrow();
+    expect(Number(commitCount.count)).toBe(0);
+
+    const row = await db
+      .selectFrom('tasks')
+      .select(['title'])
+      .where('id', '=', 't1')
+      .executeTakeFirstOrThrow();
+    expect(row.title).toBe('old title');
+  });
+});

package/src/proxy/handler.ts

@@ -12,6 +12,7 @@ import {
   appendReturning,
   detectMutation,
   hasReturningClause,
+  hasReturningWildcard,
 } from './mutation-detector';
 import { createOplogEntries } from './oplog';
 import type { ProxyTableRegistry } from './registry';
@@ -23,7 +24,7 @@ export interface ExecuteProxyQueryArgs<DB extends SyncCoreDb = SyncCoreDb> {
   /** Server sync dialect */
   dialect: ServerSyncDialect;
   /** Proxy table registry for oplog generation */
-  shapes: ProxyTableRegistry;
+  handlers: ProxyTableRegistry;
   /** Query context (actor/client IDs) */
   ctx: ProxyQueryContext;
   /** SQL query string */
@@ -99,7 +100,7 @@ function buildRawQuery(
 export async function executeProxyQuery<DB extends SyncCoreDb>(
   args: ExecuteProxyQueryArgs<DB>
 ): Promise<ExecuteProxyQueryResult> {
-  const { db, dialect, shapes, ctx, sqlQuery, parameters } = args;
+  const { db, dialect, handlers, ctx, sqlQuery, parameters } = args;
 
   const mutation = detectMutation(sqlQuery);
 
@@ -109,10 +110,10 @@ export async function executeProxyQuery<DB extends SyncCoreDb>(
     return { rows: result.rows };
   }
 
-  // Check if this table has a registered shape
-  const shape = shapes.get(mutation.tableName);
-  if (!shape) {
-    // No shape registered - execute without oplog
+  // Check if this table has a registered handler
+  const handler = handlers.get(mutation.tableName);
+  if (!handler) {
+    // No handler registered - execute without oplog
     // This allows proxy operations on non-synced tables
     const result = await buildRawQuery(sqlQuery, parameters).execute(db);
     return {
@@ -121,9 +122,15 @@ export async function executeProxyQuery<DB extends SyncCoreDb>(
     };
   }
 
-  // Mutation with registered shape - append RETURNING * and create oplog
-  const needsReturning = !hasReturningClause(sqlQuery);
-  const finalSql = needsReturning ? appendReturning(sqlQuery) : sqlQuery;
+  // Mutation with registered handler - append RETURNING * and create oplog
+  const hasReturning = hasReturningClause(sqlQuery);
+  if (hasReturning && !hasReturningWildcard(sqlQuery)) {
+    throw new Error(
+      `Proxy mutation on synced table "${mutation.tableName}" must use RETURNING * (or omit RETURNING)`
+    );
+  }
+
+  const finalSql = hasReturning ? sqlQuery : appendReturning(sqlQuery);
 
   const result = await buildRawQuery(finalSql, parameters).execute(db);
   const affectedRows = result.rows as Record<string, unknown>[];
@@ -138,7 +145,8 @@ export async function executeProxyQuery<DB extends SyncCoreDb>(
     dialect,
     actorId: ctx.actorId,
     clientId: ctx.clientId,
-    shape,
+    partitionId: ctx.partitionId,
+    handler,
     operation: mutation.operation,
     rows: affectedRows,
   });

package/src/proxy/index.ts

@@ -6,11 +6,12 @@
 
 // Query execution
 export {
+  type ExecuteProxyQueryArgs,
   type ExecuteProxyQueryResult,
   executeProxyQuery,
 } from './handler';
 // Mutation detection
-export { detectMutation } from './mutation-detector';
+export { type DetectedMutation, detectMutation } from './mutation-detector';
 // Oplog creation
 // Registry
 export { ProxyTableRegistry } from './registry';

package/src/proxy/mutation-detector.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  appendReturning,
+  detectMutation,
+  hasReturningWildcard,
+} from './mutation-detector';
+
+describe('detectMutation', () => {
+  it('detects comment-prefixed update statements', () => {
+    const detected = detectMutation(`
+      /* admin tooling */
+      UPDATE tasks
+      SET title = 'updated'
+      WHERE id = 't1'
+    `);
+
+    expect(detected).toEqual({
+      operation: 'upsert',
+      tableName: 'tasks',
+    });
+  });
+
+  it('detects cte-prefixed update statements', () => {
+    const detected = detectMutation(`
+      WITH touched AS (
+        SELECT id FROM tasks WHERE id = 't1'
+      )
+      UPDATE tasks
+      SET title = 'updated'
+      WHERE id IN (SELECT id FROM touched)
+    `);
+
+    expect(detected).toEqual({
+      operation: 'upsert',
+      tableName: 'tasks',
+    });
+  });
+
+  it('returns null for cte-prefixed read queries', () => {
+    const detected = detectMutation(`
+      WITH filtered AS (
+        SELECT id FROM tasks WHERE user_id = 'u1'
+      )
+      SELECT * FROM filtered
+    `);
+
+    expect(detected).toBeNull();
+  });
+});
+
+describe('returning helpers', () => {
+  it('recognizes wildcard RETURNING clauses', () => {
+    expect(
+      hasReturningWildcard('UPDATE tasks SET title = $1 RETURNING *')
+    ).toBe(true);
+    expect(
+      hasReturningWildcard(
+        'UPDATE tasks SET title = $1 RETURNING tasks.id, tasks.*'
+      )
+    ).toBe(true);
+    expect(
+      hasReturningWildcard('UPDATE tasks SET title = $1 RETURNING id')
+    ).toBe(false);
+  });
+
+  it('appends RETURNING * when missing', () => {
+    expect(appendReturning('UPDATE tasks SET title = $1')).toBe(
+      'UPDATE tasks SET title = $1 RETURNING *'
+    );
+  });
+});

package/src/proxy/mutation-detector.ts

@@ -13,6 +13,205 @@ export interface DetectedMutation {
   tableName: string;
 }
 
+function isWordStart(ch: string): boolean {
+  return /[A-Za-z_]/.test(ch);
+}
+
+function isWordPart(ch: string): boolean {
+  return /[A-Za-z0-9_$]/.test(ch);
+}
+
+function skipLeadingNoise(sql: string): string {
+  let index = 0;
+  while (index < sql.length) {
+    while (index < sql.length && /[\s;]/.test(sql[index]!)) {
+      index += 1;
+    }
+
+    if (sql.startsWith('--', index)) {
+      index += 2;
+      while (index < sql.length && sql[index] !== '\n') {
+        index += 1;
+      }
+      continue;
+    }
+
+    if (sql.startsWith('/*', index)) {
+      const end = sql.indexOf('*/', index + 2);
+      if (end === -1) return '';
+      index = end + 2;
+      continue;
+    }
+
+    break;
+  }
+
+  return sql.slice(index);
+}
+
+function extractMainStatement(sql: string): string {
+  const normalized = skipLeadingNoise(sql);
+  if (!normalized.toLowerCase().startsWith('with')) {
+    return normalized;
+  }
+
+  const lower = normalized.toLowerCase();
+  const rootKeywords = new Set(['insert', 'update', 'delete', 'select']);
+
+  let index = 0;
+  let depth = 0;
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+
+  while (index < normalized.length) {
+    const ch = normalized[index]!;
+    const next = normalized[index + 1];
+
+    if (inLineComment) {
+      if (ch === '\n') inLineComment = false;
+      index += 1;
+      continue;
+    }
+    if (inBlockComment) {
+      if (ch === '*' && next === '/') {
+        inBlockComment = false;
+        index += 2;
+        continue;
+      }
+      index += 1;
+      continue;
+    }
+    if (inSingleQuote) {
+      if (ch === "'" && next === "'") {
+        index += 2;
+        continue;
+      }
+      if (ch === "'") inSingleQuote = false;
+      index += 1;
+      continue;
+    }
+    if (inDoubleQuote) {
+      if (ch === '"' && next === '"') {
+        index += 2;
+        continue;
+      }
+      if (ch === '"') inDoubleQuote = false;
+      index += 1;
+      continue;
+    }
+
+    if (ch === '-' && next === '-') {
+      inLineComment = true;
+      index += 2;
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      inBlockComment = true;
+      index += 2;
+      continue;
+    }
+    if (ch === "'") {
+      inSingleQuote = true;
+      index += 1;
+      continue;
+    }
+    if (ch === '"') {
+      inDoubleQuote = true;
+      index += 1;
+      continue;
+    }
+    if (ch === '(') {
+      depth += 1;
+      index += 1;
+      continue;
+    }
+    if (ch === ')') {
+      if (depth > 0) depth -= 1;
+      index += 1;
+      continue;
+    }
+
+    if (depth === 0 && isWordStart(ch)) {
+      const tokenStart = index;
+      index += 1;
+      while (index < normalized.length && isWordPart(normalized[index]!)) {
+        index += 1;
+      }
+      const token = lower.slice(tokenStart, index);
+      if (
+        token !== 'with' &&
+        token !== 'recursive' &&
+        rootKeywords.has(token)
+      ) {
+        return normalized.slice(tokenStart);
+      }
+      continue;
+    }
+
+    index += 1;
+  }
+
+  return normalized;
+}
+
+function parseIdentifier(
+  input: string,
+  startIndex: number
+): { name: string; nextIndex: number } | null {
+  let index = startIndex;
+  while (index < input.length && /\s/.test(input[index]!)) {
+    index += 1;
+  }
+  if (index >= input.length) return null;
+
+  if (input[index] === '"') {
+    index += 1;
+    let value = '';
+    while (index < input.length) {
+      const ch = input[index]!;
+      if (ch === '"' && input[index + 1] === '"') {
+        value += '"';
+        index += 2;
+        continue;
+      }
+      if (ch === '"') {
+        index += 1;
+        return { name: value, nextIndex: index };
+      }
+      value += ch;
+      index += 1;
+    }
+    return null;
+  }
+
+  if (!isWordStart(input[index]!)) return null;
+  const first = index;
+  index += 1;
+  while (index < input.length && isWordPart(input[index]!)) {
+    index += 1;
+  }
+  return { name: input.slice(first, index), nextIndex: index };
+}
+
+function parseTargetTable(input: string): string | null {
+  const first = parseIdentifier(input, 0);
+  if (!first) return null;
+
+  let index = first.nextIndex;
+  while (index < input.length && /\s/.test(input[index]!)) {
+    index += 1;
+  }
+  if (input[index] !== '.') {
+    return first.name;
+  }
+
+  const second = parseIdentifier(input, index + 1);
+  if (!second) return null;
+  return second.name;
+}
+
 /**
  * Detect if a SQL query is a mutation and extract table info.
  *
@@ -20,39 +219,29 @@ export interface DetectedMutation {
  * @returns Mutation info if detected, null for read queries
  */
 export function detectMutation(sql: string): DetectedMutation | null {
-  const trimmed = sql.trim();
-
-  // INSERT INTO [schema.]table
-  const insertMatch = trimmed.match(
-    /^\s*INSERT\s+INTO\s+(?:["']?(\w+)["']?\.)?["']?(\w+)["']?/i
-  );
-  if (insertMatch) {
-    return {
-      operation: 'upsert',
-      tableName: insertMatch[2]!,
-    };
+  const statement = extractMainStatement(sql).trimStart();
+  const lower = statement.toLowerCase();
+
+  if (lower.startsWith('insert')) {
+    const tableName = parseTargetTable(
+      statement.replace(/^insert\s+into\s+/i, '')
+    );
+    if (!tableName) return null;
+    return { operation: 'upsert', tableName };
   }
 
-  // UPDATE [schema.]table
-  const updateMatch = trimmed.match(
-    /^\s*UPDATE\s+(?:["']?(\w+)["']?\.)?["']?(\w+)["']?/i
-  );
-  if (updateMatch) {
-    return {
-      operation: 'upsert',
-      tableName: updateMatch[2]!,
-    };
+  if (lower.startsWith('update')) {
+    const tableName = parseTargetTable(statement.replace(/^update\s+/i, ''));
+    if (!tableName) return null;
+    return { operation: 'upsert', tableName };
   }
 
-  // DELETE FROM [schema.]table
-  const deleteMatch = trimmed.match(
-    /^\s*DELETE\s+FROM\s+(?:["']?(\w+)["']?\.)?["']?(\w+)["']?/i
-  );
-  if (deleteMatch) {
-    return {
-      operation: 'delete',
-      tableName: deleteMatch[2]!,
-    };
+  if (lower.startsWith('delete')) {
+    const tableName = parseTargetTable(
+      statement.replace(/^delete\s+from\s+/i, '')
+    );
+    if (!tableName) return null;
+    return { operation: 'delete', tableName };
   }
 
   return null;
@@ -66,6 +255,15 @@ export function hasReturningClause(sql: string): boolean {
   return /\bRETURNING\b/i.test(sql);
 }
 
+/**
+ * Check if SQL has a wildcard RETURNING clause (RETURNING * or alias.*).
+ */
+export function hasReturningWildcard(sql: string): boolean {
+  const match = sql.match(/\bRETURNING\b([\s\S]*)$/i);
+  if (!match) return false;
+  return /(^|,)\s*(?:[A-Za-z_][A-Za-z0-9_$]*\.)?\*/i.test(match[1]);
+}
+
 /**
  * Append RETURNING * to a mutation query if not already present.
  *

package/src/proxy/oplog.ts

@@ -29,22 +29,25 @@ export async function createOplogEntries<DB extends SyncCoreDb>(args: {
   dialect: ServerSyncDialect;
   actorId: string;
   clientId: string;
-  shape: ProxyTableHandler;
+  partitionId?: string;
+  handler: ProxyTableHandler;
   operation: SyncOp;
   rows: Record<string, unknown>[];
 }): Promise<{ commitSeq: number; affectedTables: string[] }> {
-  const { trx, dialect, actorId, clientId, shape, operation, rows } = args;
+  const { trx, dialect, actorId, clientId, handler, operation, rows } = args;
+  const partitionId = args.partitionId ?? 'default';
 
   if (rows.length === 0) {
     return { commitSeq: 0, affectedTables: [] };
   }
 
-  const pk = shape.primaryKey ?? 'id';
-  const versionCol = shape.versionColumn ?? 'server_version';
+  const pk = handler.primaryKey ?? 'id';
+  const versionCol = handler.versionColumn ?? 'server_version';
 
   // Create commit record
   const commitResult = await sql<{ commit_seq: number }>`
     insert into ${sql.table('sync_commits')} (
+      partition_id,
       actor_id,
       client_id,
       client_commit_id,
@@ -52,6 +55,7 @@ export async function createOplogEntries<DB extends SyncCoreDb>(args: {
       result_json
     )
     values (
+      ${partitionId},
       ${actorId},
       ${clientId},
       ${`proxy:${generateId()}`},
@@ -69,14 +73,15 @@ export async function createOplogEntries<DB extends SyncCoreDb>(args: {
 
   // Compute scopes for all rows and collect changes
   const affectedTablesSet = new Set<string>();
-  affectedTablesSet.add(shape.table);
+  affectedTablesSet.add(handler.table);
 
   const changes = rows.map((row) => {
-    const scopes = shape.computeScopes(row);
+    const scopes = handler.computeScopes(row);
 
     return {
       commit_seq: commitSeq,
-      table: shape.table,
+      partition_id: partitionId,
+      table: handler.table,
       row_id: String(row[pk]),
       op: operation,
       row_json: operation === 'delete' ? null : row,
@@ -89,6 +94,7 @@ export async function createOplogEntries<DB extends SyncCoreDb>(args: {
   await sql`
 	    insert into ${sql.table('sync_changes')} (
 	      commit_seq,
+	      partition_id,
 	      "table",
 	      row_id,
 	      op,
@@ -100,6 +106,7 @@ export async function createOplogEntries<DB extends SyncCoreDb>(args: {
       changes.map(
         (c) => sql`(
           ${c.commit_seq},
+          ${c.partition_id},
           ${c.table},
           ${c.row_id},
           ${c.op},
@@ -124,12 +131,14 @@ export async function createOplogEntries<DB extends SyncCoreDb>(args: {
   // Insert table commits for subscription filtering
   if (affectedTables.length > 0) {
     await sql`
-	      insert into ${sql.table('sync_table_commits')} ("table", commit_seq)
+	      insert into ${sql.table('sync_table_commits')} (partition_id, "table", commit_seq)
 	      values ${sql.join(
-          sortedAffectedTables.map((table) => sql`(${table}, ${commitSeq})`),
+          sortedAffectedTables.map(
+            (table) => sql`(${partitionId}, ${table}, ${commitSeq})`
+          ),
           sql`, `
         )}
-	      on conflict ("table", commit_seq) do nothing
+	      on conflict (partition_id, "table", commit_seq) do nothing
 	    `.execute(trx);
   }
 

package/src/proxy/registry.ts

@@ -4,7 +4,6 @@
  * Registry for proxy table handlers.
  */
 
-import type { TableRegistry } from '../shapes/registry';
 import type { ProxyTableHandler } from './types';
 
 /**
@@ -55,35 +54,3 @@ export class ProxyTableRegistry {
     return Array.from(this.handlers.values());
   }
 }
-
-/**
- * Create a ProxyTableRegistry from existing ServerTableHandlers.
- *
- * This helper extracts extractScopes from ServerTableHandlers that define it,
- * avoiding duplication of scope extraction logic.
- *
- * @param tables - The existing table registry
- * @param tableNameMap - Map from table name to database table name
- */
-export function createProxyRegistryFromTables(
-  tables: TableRegistry,
-  tableNameMap: Record<string, string>
-): ProxyTableRegistry {
-  const registry = new ProxyTableRegistry();
-
-  for (const [tableName, dbTableName] of Object.entries(tableNameMap)) {
-    const handler = tables.get(tableName);
-    if (
-      handler &&
-      'extractScopes' in handler &&
-      typeof handler.extractScopes === 'function'
-    ) {
-      registry.register({
-        table: dbTableName,
-        computeScopes: handler.extractScopes,
-      });
-    }
-  }
-
-  return registry;
-}

package/src/proxy/types.ts

@@ -41,4 +41,6 @@ export interface ProxyQueryContext {
   actorId: string;
   /** Client ID for oplog tracking */
   clientId: string;
+  /** Logical partition key (default: 'default') */
+  partitionId?: string;
 }