@syncular/client 0.0.1-60

package/src/proxy/connection.ts

@@ -0,0 +1,191 @@
+/**
+ * @syncular/client - Proxy Connection
+ *
+ * DatabaseConnection implementation that proxies queries over WebSocket.
+ */
+
+import type {
+  ProxyHandshake,
+  ProxyHandshakeAck,
+  ProxyMessage,
+  ProxyResponse,
+} from '@syncular/core';
+import type { CompiledQuery, DatabaseConnection, QueryResult } from 'kysely';
+
+/**
+ * WebSocket wrapper that handles reconnection and message correlation.
+ */
+export class ProxyConnection implements DatabaseConnection {
+  private ws: WebSocket;
+  private messageId = 0;
+  private pendingRequests = new Map<
+    string,
+    {
+      resolve: (response: ProxyResponse) => void;
+      reject: (error: Error) => void;
+    }
+  >();
+  private handshakeComplete = false;
+  private handshakePromise: Promise<void>;
+  private handshakeResolve: (() => void) | null = null;
+  private handshakeReject: ((error: Error) => void) | null = null;
+  private closed = false;
+
+  constructor(
+    ws: WebSocket,
+    private actorId: string,
+    private clientId: string
+  ) {
+    this.ws = ws;
+
+    this.handshakePromise = new Promise((resolve, reject) => {
+      this.handshakeResolve = resolve;
+      this.handshakeReject = reject;
+    });
+
+    this.ws.onmessage = (event) => {
+      this.handleMessage(event.data as string);
+    };
+
+    this.ws.onerror = (_event) => {
+      const error = new Error('WebSocket error');
+      this.rejectAllPending(error);
+      if (!this.handshakeComplete) {
+        this.handshakeReject?.(error);
+      }
+    };
+
+    this.ws.onclose = () => {
+      this.closed = true;
+      const error = new Error('WebSocket closed');
+      this.rejectAllPending(error);
+      if (!this.handshakeComplete) {
+        this.handshakeReject?.(error);
+      }
+    };
+
+    // Send handshake
+    const handshake: ProxyHandshake = {
+      type: 'handshake',
+      actorId: this.actorId,
+      clientId: this.clientId,
+    };
+    this.ws.send(JSON.stringify(handshake));
+  }
+
+  private handleMessage(data: string): void {
+    try {
+      const message = JSON.parse(data);
+
+      // Handle handshake acknowledgement
+      if (message.type === 'handshake_ack') {
+        const ack = message as ProxyHandshakeAck;
+        if (ack.ok) {
+          this.handshakeComplete = true;
+          this.handshakeResolve?.();
+        } else {
+          this.handshakeReject?.(new Error(ack.error ?? 'Handshake failed'));
+        }
+        return;
+      }
+
+      // Handle query responses
+      const response = message as ProxyResponse;
+      const pending = this.pendingRequests.get(response.id);
+      if (pending) {
+        this.pendingRequests.delete(response.id);
+        pending.resolve(response);
+      }
+    } catch {
+      // Ignore malformed messages
+    }
+  }
+
+  private rejectAllPending(error: Error): void {
+    for (const pending of this.pendingRequests.values()) {
+      pending.reject(error);
+    }
+    this.pendingRequests.clear();
+  }
+
+  private async send(message: ProxyMessage): Promise<ProxyResponse> {
+    // Wait for handshake to complete
+    await this.handshakePromise;
+
+    if (this.closed) {
+      throw new Error('Connection is closed');
+    }
+
+    return new Promise((resolve, reject) => {
+      this.pendingRequests.set(message.id, { resolve, reject });
+      this.ws.send(JSON.stringify(message));
+    });
+  }
+
+  private nextMessageId(): string {
+    return `${++this.messageId}`;
+  }
+
+  async executeQuery<R>(query: CompiledQuery): Promise<QueryResult<R>> {
+    const response = await this.send({
+      id: this.nextMessageId(),
+      type: 'query',
+      sql: query.sql,
+      parameters: query.parameters,
+    });
+
+    if (response.type === 'error') {
+      throw new Error(response.error ?? 'Query failed');
+    }
+
+    return {
+      rows: (response.rows ?? []) as R[],
+      numAffectedRows:
+        response.rowCount != null ? BigInt(response.rowCount) : undefined,
+    };
+  }
+
+  async beginTransaction(): Promise<void> {
+    const response = await this.send({
+      id: this.nextMessageId(),
+      type: 'begin',
+    });
+
+    if (response.type === 'error') {
+      throw new Error(response.error ?? 'Failed to begin transaction');
+    }
+  }
+
+  async commitTransaction(): Promise<void> {
+    const response = await this.send({
+      id: this.nextMessageId(),
+      type: 'commit',
+    });
+
+    if (response.type === 'error') {
+      throw new Error(response.error ?? 'Failed to commit transaction');
+    }
+  }
+
+  async rollbackTransaction(): Promise<void> {
+    const response = await this.send({
+      id: this.nextMessageId(),
+      type: 'rollback',
+    });
+
+    if (response.type === 'error') {
+      throw new Error(response.error ?? 'Failed to rollback transaction');
+    }
+  }
+
+  streamQuery<R>(): AsyncIterableIterator<QueryResult<R>> {
+    throw new Error('Streaming queries are not supported over proxy');
+  }
+
+  close(): void {
+    if (!this.closed) {
+      this.closed = true;
+      this.ws.close();
+    }
+  }
+}

package/src/proxy/dialect.ts

@@ -0,0 +1,76 @@
+/**
+ * @syncular/client - Proxy Dialect
+ *
+ * Kysely Dialect that proxies queries over WebSocket to a sync server.
+ */
+
+import type {
+  DatabaseIntrospector,
+  Dialect,
+  DialectAdapter,
+  Driver,
+  Kysely,
+  QueryCompiler,
+} from 'kysely';
+import {
+  PostgresAdapter,
+  PostgresIntrospector,
+  PostgresQueryCompiler,
+} from 'kysely';
+import { ProxyDriver, type ProxyDriverConfigWithFactory } from './driver';
+
+interface ProxyDialectConfig extends ProxyDriverConfigWithFactory {}
+
+/**
+ * Creates a Kysely dialect that proxies queries over WebSocket.
+ *
+ * This dialect uses PostgreSQL query compilation and adapters since
+ * the proxy server typically runs against a PostgreSQL database.
+ *
+ * @example
+ * ```typescript
+ * import { Kysely } from 'kysely';
+ * import { createProxyDialect } from '@syncular/client/proxy';
+ *
+ * const db = new Kysely<MySchema>({
+ *   dialect: createProxyDialect({
+ *     endpoint: 'wss://api.example.com/proxy',
+ *     actorId: 'admin:worker',
+ *     clientId: 'cf-worker-123',
+ *     headers: { authorization: 'Bearer ...' },
+ *   }),
+ * });
+ *
+ * // Full Kysely API works
+ * const tasks = await db.selectFrom('tasks').selectAll().execute();
+ *
+ * // Transactions work
+ * await db.transaction().execute(async (trx) => {
+ *   const user = await trx.selectFrom('users')
+ *     .where('id', '=', 'u1')
+ *     .executeTakeFirst();
+ *   await trx.insertInto('tasks')
+ *     .values({ id: 'x', user_id: user.id, title: 'New' })
+ *     .execute();
+ * });
+ * ```
+ */
+export function createProxyDialect(config: ProxyDialectConfig): Dialect {
+  return {
+    createDriver(): Driver {
+      return new ProxyDriver(config);
+    },
+
+    createQueryCompiler(): QueryCompiler {
+      return new PostgresQueryCompiler();
+    },
+
+    createAdapter(): DialectAdapter {
+      return new PostgresAdapter();
+    },
+
+    createIntrospector(db: Kysely<any>): DatabaseIntrospector {
+      return new PostgresIntrospector(db);
+    },
+  };
+}

package/src/proxy/driver.ts

@@ -0,0 +1,126 @@
+/**
+ * @syncular/client - Proxy Driver
+ *
+ * Kysely Driver that creates WebSocket connections for query execution.
+ */
+
+import type { DatabaseConnection, Driver } from 'kysely';
+import { ProxyConnection } from './connection';
+
+interface ProxyDriverConfig {
+  /** WebSocket endpoint URL (wss://...) */
+  endpoint: string;
+  /** Actor ID for oplog tracking */
+  actorId: string;
+  /** Client ID for oplog tracking */
+  clientId: string;
+  /** Optional headers for authentication */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Custom WebSocket factory type for environments that need it.
+ */
+export type WebSocketFactory = (
+  url: string,
+  protocols?: string | string[]
+) => WebSocket;
+
+/**
+ * Extended config with optional WebSocket factory.
+ */
+export interface ProxyDriverConfigWithFactory extends ProxyDriverConfig {
+  /** Optional WebSocket factory for custom environments */
+  createWebSocket?: WebSocketFactory;
+}
+
+export class ProxyDriver implements Driver {
+  private connection: ProxyConnection | null = null;
+
+  constructor(private config: ProxyDriverConfigWithFactory) {}
+
+  async init(): Promise<void> {
+    // No initialization needed
+  }
+
+  async acquireConnection(): Promise<DatabaseConnection> {
+    // Reuse existing connection if available
+    if (this.connection) {
+      return this.connection as DatabaseConnection;
+    }
+
+    const ws = await this.createWebSocket();
+    this.connection = new ProxyConnection(
+      ws,
+      this.config.actorId,
+      this.config.clientId
+    );
+    return this.connection as DatabaseConnection;
+  }
+
+  private async createWebSocket(): Promise<WebSocket> {
+    return new Promise((resolve, reject) => {
+      // Build URL with auth info if needed
+      const url = new URL(this.config.endpoint);
+
+      // Note: WebSocket doesn't support custom headers directly,
+      // so auth is typically done via query params or after connection
+      // The server should handle auth during the handshake
+      if (this.config.headers?.authorization) {
+        url.searchParams.set(
+          'authorization',
+          this.config.headers.authorization
+        );
+      }
+
+      let ws: WebSocket;
+      if (this.config.createWebSocket) {
+        ws = this.config.createWebSocket(url.toString());
+      } else {
+        ws = new WebSocket(url.toString());
+      }
+
+      ws.onopen = () => {
+        resolve(ws);
+      };
+
+      ws.onerror = (_event) => {
+        reject(new Error('Failed to connect to proxy endpoint'));
+      };
+
+      // Set a connection timeout
+      const timeout = setTimeout(() => {
+        ws.close();
+        reject(new Error('Connection timeout'));
+      }, 30000);
+
+      ws.onopen = () => {
+        clearTimeout(timeout);
+        resolve(ws);
+      };
+    });
+  }
+
+  async beginTransaction(connection: DatabaseConnection): Promise<void> {
+    await (connection as ProxyConnection).beginTransaction();
+  }
+
+  async commitTransaction(connection: DatabaseConnection): Promise<void> {
+    await (connection as ProxyConnection).commitTransaction();
+  }
+
+  async rollbackTransaction(connection: DatabaseConnection): Promise<void> {
+    await (connection as ProxyConnection).rollbackTransaction();
+  }
+
+  async releaseConnection(): Promise<void> {
+    // Keep the connection alive for reuse
+  }
+
+  async destroy(): Promise<void> {
+    if (this.connection) {
+      this.connection.close();
+      this.connection = null;
+    }
+  }
+}

package/src/proxy/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @syncular/client - Proxy Dialect Exports
+ *
+ * Kysely dialect for proxying queries over WebSocket to a sync server.
+ */
+
+export * from './connection';
+export * from './dialect';
+export * from './driver';
+export * from './mutations';

package/src/proxy/mutations.ts

@@ -0,0 +1,18 @@
+/**
+ * @syncular/client - Proxy mutations
+ *
+ * Exposes the same Proxy-based mutation interface as the offline client,
+ * but pushes commits to the server immediately (no local outbox/db writes).
+ */
+
+import {
+  createPushMutations,
+  type MutationsApi,
+  type PushCommitConfig,
+} from '../mutations';
+
+export function createProxyMutations<DB extends Record<string, any>>(
+  config: PushCommitConfig
+): MutationsApi<DB, undefined> {
+  return createPushMutations(config);
+}