@syncular/server 0.0.1-100

package/src/proxy/handler.ts

@@ -0,0 +1,159 @@
+/**
+ * @syncular/server - Proxy Query Handler
+ *
+ * Executes proxied queries with automatic oplog generation for mutations.
+ */
+
+import type { Kysely, RawBuilder } from 'kysely';
+import { sql } from 'kysely';
+import type { ServerSyncDialect } from '../dialect/types';
+import type { SyncCoreDb } from '../schema';
+import {
+  appendReturning,
+  detectMutation,
+  hasReturningClause,
+  hasReturningWildcard,
+} from './mutation-detector';
+import { createOplogEntries } from './oplog';
+import type { ProxyTableRegistry } from './registry';
+import type { ProxyQueryContext } from './types';
+
+export interface ExecuteProxyQueryArgs<DB extends SyncCoreDb = SyncCoreDb> {
+  /** Database connection or transaction */
+  db: Kysely<DB>;
+  /** Server sync dialect */
+  dialect: ServerSyncDialect;
+  /** Proxy table registry for oplog generation */
+  shapes: ProxyTableRegistry;
+  /** Query context (actor/client IDs) */
+  ctx: ProxyQueryContext;
+  /** SQL query string */
+  sqlQuery: string;
+  /** Query parameters */
+  parameters: readonly unknown[];
+}
+
+export interface ExecuteProxyQueryResult {
+  /** Query result rows (for SELECT or RETURNING) */
+  rows?: unknown[];
+  /** Number of affected rows (for mutations) */
+  rowCount?: number;
+  /** Commit sequence if oplog was created */
+  commitSeq?: number;
+  /** Affected tables if oplog was created */
+  affectedTables?: string[];
+}
+
+/**
+ * Build a raw SQL query with parameters using Kysely's sql helper.
+ *
+ * This converts parameterized SQL (using $1, $2, etc.) to Kysely's format.
+ */
+function buildRawQuery(
+  sqlQuery: string,
+  parameters: readonly unknown[]
+): RawBuilder<unknown> {
+  // If no parameters, just use sql.raw
+  if (parameters.length === 0) {
+    return sql.raw(sqlQuery);
+  }
+
+  // Parse the SQL and split by parameter placeholders ($1, $2, etc.)
+  // Then use sql.join to build the query with proper parameter binding
+  const parts: RawBuilder<unknown>[] = [];
+  let lastIndex = 0;
+  const paramRegex = /\$(\d+)/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = paramRegex.exec(sqlQuery)) !== null) {
+    // Add the SQL before this parameter
+    if (match.index > lastIndex) {
+      parts.push(sql.raw(sqlQuery.slice(lastIndex, match.index)));
+    }
+    // Add the parameter value (1-indexed in SQL, 0-indexed in array)
+    const paramIndex = Number.parseInt(match[1]!, 10) - 1;
+    if (paramIndex >= 0 && paramIndex < parameters.length) {
+      // Use sql.value to create a proper parameter binding
+      parts.push(sql.val(parameters[paramIndex]));
+    } else {
+      // Keep the original placeholder if out of bounds (shouldn't happen)
+      parts.push(sql.raw(match[0]));
+    }
+    lastIndex = match.index + match[0].length;
+  }
+
+  // Add remaining SQL after last parameter
+  if (lastIndex < sqlQuery.length) {
+    parts.push(sql.raw(sqlQuery.slice(lastIndex)));
+  }
+
+  // Join all parts together
+  return sql.join(parts, sql.raw(''));
+}
+
+/**
+ * Execute a proxied query with automatic oplog generation for mutations.
+ *
+ * - Read queries: Execute directly and return rows
+ * - Mutations: Append RETURNING *, execute, create oplog entries
+ */
+export async function executeProxyQuery<DB extends SyncCoreDb>(
+  args: ExecuteProxyQueryArgs<DB>
+): Promise<ExecuteProxyQueryResult> {
+  const { db, dialect, shapes, ctx, sqlQuery, parameters } = args;
+
+  const mutation = detectMutation(sqlQuery);
+
+  if (!mutation) {
+    // Read query - execute directly
+    const result = await buildRawQuery(sqlQuery, parameters).execute(db);
+    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
+    // This allows proxy operations on non-synced tables
+    const result = await buildRawQuery(sqlQuery, parameters).execute(db);
+    return {
+      rows: result.rows,
+      rowCount: Number(result.numAffectedRows ?? 0),
+    };
+  }
+
+  // Mutation with registered shape - 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>[];
+
+  if (affectedRows.length === 0) {
+    return { rowCount: 0 };
+  }
+
+  // Create oplog entries
+  const { commitSeq, affectedTables } = await createOplogEntries({
+    trx: db,
+    dialect,
+    actorId: ctx.actorId,
+    clientId: ctx.clientId,
+    partitionId: ctx.partitionId,
+    shape,
+    operation: mutation.operation,
+    rows: affectedRows,
+  });
+
+  return {
+    rowCount: affectedRows.length,
+    commitSeq,
+    affectedTables,
+  };
+}

package/src/proxy/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @syncular/server - Proxy Exports
+ *
+ * Server-side proxy functionality for database access.
+ */
+
+// Query execution
+export {
+  type ExecuteProxyQueryArgs,
+  type ExecuteProxyQueryResult,
+  executeProxyQuery,
+} from './handler';
+// Mutation detection
+export { type DetectedMutation, detectMutation } from './mutation-detector';
+// Oplog creation
+// Registry
+export { ProxyTableRegistry } from './registry';
+// Types

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

@@ -0,0 +1,281 @@
+/**
+ * @syncular/server - Mutation Detector
+ *
+ * Detects whether a SQL query is a mutation (INSERT/UPDATE/DELETE).
+ */
+
+import type { SyncOp } from '@syncular/core';
+
+export interface DetectedMutation {
+  /** Operation type */
+  operation: SyncOp;
+  /** Table name being modified */
+  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.
+ *
+ * @param sql - The SQL query string
+ * @returns Mutation info if detected, null for read queries
+ */
+export function detectMutation(sql: string): DetectedMutation | null {
+  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 };
+  }
+
+  if (lower.startsWith('update')) {
+    const tableName = parseTargetTable(statement.replace(/^update\s+/i, ''));
+    if (!tableName) return null;
+    return { operation: 'upsert', tableName };
+  }
+
+  if (lower.startsWith('delete')) {
+    const tableName = parseTargetTable(
+      statement.replace(/^delete\s+from\s+/i, '')
+    );
+    if (!tableName) return null;
+    return { operation: 'delete', tableName };
+  }
+
+  return null;
+}
+
+/**
+ * Check if SQL already has a RETURNING clause.
+ */
+export function hasReturningClause(sql: string): boolean {
+  // Simple check - look for RETURNING keyword not in a string
+  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.
+ *
+ * @param sql - The SQL query string
+ * @returns Modified SQL with RETURNING *
+ */
+export function appendReturning(sql: string): string {
+  if (hasReturningClause(sql)) {
+    return sql;
+  }
+
+  // Remove trailing semicolon if present
+  const trimmed = sql.trim().replace(/;\s*$/, '');
+  return `${trimmed} RETURNING *`;
+}

package/src/proxy/oplog.ts

@@ -0,0 +1,146 @@
+/**
+ * @syncular/server - Oplog Creation
+ *
+ * Creates sync oplog entries for proxy mutations.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { SyncOp } from '@syncular/core';
+import { type Kysely, sql } from 'kysely';
+import type { ServerSyncDialect } from '../dialect/types';
+import type { SyncCoreDb } from '../schema';
+import type { ProxyTableHandler } from './types';
+
+/**
+ * Generate a random ID for commit tracking.
+ */
+function generateId(): string {
+  return randomUUID();
+}
+
+/**
+ * Create oplog entries for affected rows.
+ *
+ * This is called after a mutation to record the changes in the sync oplog,
+ * making them visible to sync clients.
+ */
+export async function createOplogEntries<DB extends SyncCoreDb>(args: {
+  trx: Kysely<DB>;
+  dialect: ServerSyncDialect;
+  actorId: string;
+  clientId: string;
+  partitionId?: string;
+  shape: ProxyTableHandler;
+  operation: SyncOp;
+  rows: Record<string, unknown>[];
+}): Promise<{ commitSeq: number; affectedTables: string[] }> {
+  const { trx, dialect, actorId, clientId, shape, 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';
+
+  // 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,
+      meta,
+      result_json
+    )
+    values (
+      ${partitionId},
+      ${actorId},
+      ${clientId},
+      ${`proxy:${generateId()}`},
+      ${null},
+      ${null}
+    )
+    returning commit_seq
+  `.execute(trx);
+
+  const commitRow = commitResult.rows[0];
+  if (!commitRow) {
+    throw new Error('Failed to insert sync_commits row');
+  }
+  const commitSeq = Number(commitRow.commit_seq);
+
+  // Compute scopes for all rows and collect changes
+  const affectedTablesSet = new Set<string>();
+  affectedTablesSet.add(shape.table);
+
+  const changes = rows.map((row) => {
+    const scopes = shape.computeScopes(row);
+
+    return {
+      commit_seq: commitSeq,
+      partition_id: partitionId,
+      table: shape.table,
+      row_id: String(row[pk]),
+      op: operation,
+      row_json: operation === 'delete' ? null : row,
+      row_version: row[versionCol] != null ? Number(row[versionCol]) : null,
+      scopes: dialect.scopesToDb(scopes),
+    };
+  });
+
+  // Insert changes
+  await sql`
+	    insert into ${sql.table('sync_changes')} (
+	      commit_seq,
+	      partition_id,
+	      "table",
+	      row_id,
+	      op,
+	      row_json,
+	      row_version,
+	      scopes
+    )
+    values ${sql.join(
+      changes.map(
+        (c) => sql`(
+          ${c.commit_seq},
+          ${c.partition_id},
+          ${c.table},
+          ${c.row_id},
+          ${c.op},
+          ${c.row_json},
+          ${c.row_version},
+          ${c.scopes}
+        )`
+      ),
+      sql`, `
+    )}
+  `.execute(trx);
+
+  // Update commit with affected tables
+  const affectedTables = Array.from(affectedTablesSet);
+  const sortedAffectedTables = affectedTables.sort();
+  await sql`
+    update ${sql.table('sync_commits')}
+    set change_count = ${rows.length}, affected_tables = ${sortedAffectedTables}
+    where commit_seq = ${commitSeq}
+  `.execute(trx);
+
+  // Insert table commits for subscription filtering
+  if (affectedTables.length > 0) {
+    await sql`
+	      insert into ${sql.table('sync_table_commits')} (partition_id, "table", commit_seq)
+	      values ${sql.join(
+          sortedAffectedTables.map(
+            (table) => sql`(${partitionId}, ${table}, ${commitSeq})`
+          ),
+          sql`, `
+        )}
+	      on conflict (partition_id, "table", commit_seq) do nothing
+	    `.execute(trx);
+  }
+
+  return { commitSeq, affectedTables };
+}