@syncular/server-hono 0.0.1-60

package/src/proxy/connection-manager.ts

@@ -0,0 +1,340 @@
+/**
+ * @syncular/server-hono - Proxy Connection Manager
+ *
+ * Manages WebSocket connections for the proxy.
+ */
+
+import type {
+  ProxyHandshake,
+  ProxyMessage,
+  ProxyResponse,
+} from '@syncular/core';
+import type {
+  ExecuteProxyQueryResult,
+  ProxyTableRegistry,
+  ServerSyncDialect,
+  SyncCoreDb,
+} from '@syncular/server';
+import { executeProxyQuery } from '@syncular/server';
+import type { WSContext } from 'hono/ws';
+import type { Kysely, Transaction } from 'kysely';
+
+export interface ProxyConnectionManagerConfig<
+  DB extends SyncCoreDb = SyncCoreDb,
+> {
+  /** Database connection */
+  db: Kysely<DB>;
+  /** Server sync dialect */
+  dialect: ServerSyncDialect;
+  /** Proxy table registry for oplog generation */
+  shapes: ProxyTableRegistry;
+  /** Maximum concurrent connections (default: 100) */
+  maxConnections?: number;
+  /** Idle connection timeout in ms (default: 30000) */
+  idleTimeoutMs?: number;
+}
+
+interface ProxyConnectionState<DB extends SyncCoreDb> {
+  ws: WSContext;
+  actorId: string;
+  clientId: string;
+  transaction: Transaction<DB> | null;
+  lastActivity: number;
+  idleTimer: ReturnType<typeof setTimeout> | null;
+  /** Transaction promise resolve callback */
+  __resolveTransaction?: () => void;
+  /** Transaction promise reject callback */
+  __rejectTransaction?: (error: Error) => void;
+}
+
+/**
+ * Manages proxy WebSocket connections and their state.
+ */
+export class ProxyConnectionManager<DB extends SyncCoreDb = SyncCoreDb> {
+  private connections = new Map<WSContext, ProxyConnectionState<DB>>();
+  private config: ProxyConnectionManagerConfig<DB>;
+  private idleTimeoutMs: number;
+  private maxConnections: number;
+
+  constructor(config: ProxyConnectionManagerConfig<DB>) {
+    this.config = config;
+    this.idleTimeoutMs = config.idleTimeoutMs ?? 30000;
+    this.maxConnections = config.maxConnections ?? 100;
+  }
+
+  /**
+   * Check if a new connection can be accepted.
+   */
+  canAccept(): boolean {
+    return this.connections.size < this.maxConnections;
+  }
+
+  /**
+   * Get the current connection count.
+   */
+  getConnectionCount(): number {
+    return this.connections.size;
+  }
+
+  /**
+   * Handle the handshake message and register the connection.
+   */
+  register(ws: WSContext, handshake: ProxyHandshake): ProxyConnectionState<DB> {
+    const state: ProxyConnectionState<DB> = {
+      ws,
+      actorId: handshake.actorId,
+      clientId: handshake.clientId,
+      transaction: null,
+      lastActivity: Date.now(),
+      idleTimer: null,
+    };
+
+    this.connections.set(ws, state);
+    this.resetIdleTimer(state);
+
+    return state;
+  }
+
+  /**
+   * Get the connection state for a WebSocket.
+   */
+  get(ws: WSContext): ProxyConnectionState<DB> | undefined {
+    return this.connections.get(ws);
+  }
+
+  /**
+   * Unregister and cleanup a connection.
+   */
+  async unregister(ws: WSContext): Promise<void> {
+    const state = this.connections.get(ws);
+    if (!state) return;
+
+    // Clear idle timer
+    if (state.idleTimer) {
+      clearTimeout(state.idleTimer);
+    }
+
+    // Rollback any pending transaction by rejecting the promise
+    if (state.transaction) {
+      const rejectTransaction = state.__rejectTransaction;
+      if (rejectTransaction) {
+        rejectTransaction(new Error('Connection closed'));
+      }
+      state.transaction = null;
+      state.__resolveTransaction = undefined;
+      state.__rejectTransaction = undefined;
+    }
+
+    this.connections.delete(ws);
+  }
+
+  /**
+   * Handle a proxy message and return the response.
+   */
+  async handleMessage(
+    ws: WSContext,
+    message: ProxyMessage
+  ): Promise<ProxyResponse> {
+    const state = this.connections.get(ws);
+    if (!state) {
+      return {
+        id: message.id,
+        type: 'error',
+        error: 'Connection not registered',
+      };
+    }
+
+    // Update activity and reset idle timer
+    state.lastActivity = Date.now();
+    this.resetIdleTimer(state);
+
+    try {
+      switch (message.type) {
+        case 'begin':
+          return await this.handleBegin(state, message);
+
+        case 'commit':
+          return await this.handleCommit(state, message);
+
+        case 'rollback':
+          return await this.handleRollback(state, message);
+
+        case 'query':
+          return await this.handleQuery(state, message);
+
+        default:
+          return {
+            id: message.id,
+            type: 'error',
+            error: `Unknown message type: ${message.type}`,
+          };
+      }
+    } catch (err) {
+      return {
+        id: message.id,
+        type: 'error',
+        error: err instanceof Error ? err.message : 'Unknown error',
+      };
+    }
+  }
+
+  private async handleBegin(
+    state: ProxyConnectionState<DB>,
+    message: ProxyMessage
+  ): Promise<ProxyResponse> {
+    if (state.transaction) {
+      return {
+        id: message.id,
+        type: 'error',
+        error: 'Transaction already in progress',
+      };
+    }
+
+    // Start a transaction and keep it open
+    // We use a workaround since Kysely doesn't expose raw transaction control
+    return new Promise((resolve) => {
+      this.config.db
+        .transaction()
+        .execute(async (trx) => {
+          state.transaction = trx;
+
+          // Wait for commit or rollback
+          return new Promise<void>((resolveTransaction, rejectTransaction) => {
+            state.__resolveTransaction = resolveTransaction;
+            state.__rejectTransaction = rejectTransaction;
+            resolve({
+              id: message.id,
+              type: 'result',
+            });
+          });
+        })
+        .catch(() => {
+          // Transaction was rolled back externally
+        });
+    });
+  }
+
+  private async handleCommit(
+    state: ProxyConnectionState<DB>,
+    message: ProxyMessage
+  ): Promise<ProxyResponse> {
+    if (!state.transaction) {
+      return {
+        id: message.id,
+        type: 'error',
+        error: 'No transaction in progress',
+      };
+    }
+
+    // Resolve the transaction promise to commit
+    const resolveTransaction = state.__resolveTransaction;
+    if (resolveTransaction) {
+      resolveTransaction();
+    }
+    state.transaction = null;
+    state.__resolveTransaction = undefined;
+    state.__rejectTransaction = undefined;
+
+    return {
+      id: message.id,
+      type: 'result',
+    };
+  }
+
+  private async handleRollback(
+    state: ProxyConnectionState<DB>,
+    message: ProxyMessage
+  ): Promise<ProxyResponse> {
+    if (!state.transaction) {
+      return {
+        id: message.id,
+        type: 'error',
+        error: 'No transaction in progress',
+      };
+    }
+
+    // Reject the transaction promise to trigger rollback
+    const rejectTransaction = state.__rejectTransaction;
+    if (rejectTransaction) {
+      rejectTransaction(new Error('Transaction rolled back'));
+    }
+    state.transaction = null;
+    state.__resolveTransaction = undefined;
+    state.__rejectTransaction = undefined;
+
+    return {
+      id: message.id,
+      type: 'result',
+    };
+  }
+
+  private async handleQuery(
+    state: ProxyConnectionState<DB>,
+    message: ProxyMessage
+  ): Promise<ProxyResponse> {
+    if (!message.sql) {
+      return {
+        id: message.id,
+        type: 'error',
+        error: 'Missing SQL query',
+      };
+    }
+
+    const db = state.transaction ?? this.config.db;
+
+    const result: ExecuteProxyQueryResult = await executeProxyQuery({
+      db,
+      dialect: this.config.dialect,
+      shapes: this.config.shapes,
+      ctx: {
+        actorId: state.actorId,
+        clientId: state.clientId,
+      },
+      sqlQuery: message.sql,
+      parameters: message.parameters ?? [],
+    });
+
+    return {
+      id: message.id,
+      type: 'result',
+      rows: result.rows,
+      rowCount: result.rowCount,
+    };
+  }
+
+  private resetIdleTimer(state: ProxyConnectionState<DB>): void {
+    if (state.idleTimer) {
+      clearTimeout(state.idleTimer);
+    }
+
+    if (this.idleTimeoutMs <= 0) return;
+
+    state.idleTimer = setTimeout(() => {
+      // Close idle connection
+      try {
+        state.ws.close(4000, 'Idle timeout');
+      } catch {
+        // Ignore close errors
+      }
+      this.unregister(state.ws);
+    }, this.idleTimeoutMs);
+  }
+
+  /**
+   * Close all connections.
+   */
+  async closeAll(): Promise<void> {
+    const promises: Promise<void>[] = [];
+
+    for (const [ws] of this.connections) {
+      try {
+        ws.close(1000, 'Server shutdown');
+      } catch {
+        // Ignore close errors
+      }
+      promises.push(this.unregister(ws));
+    }
+
+    await Promise.all(promises);
+  }
+}

package/src/proxy/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @syncular/server-hono - Proxy Exports
+ *
+ * WebSocket endpoint for admin database proxy.
+ */
+
+export * from './connection-manager';
+export * from './routes';

package/src/proxy/routes.ts

@@ -0,0 +1,223 @@
+/**
+ * @syncular/server-hono - Proxy Routes
+ *
+ * WebSocket endpoint for database proxy.
+ */
+
+import type {
+  ProxyHandshake,
+  ProxyHandshakeAck,
+  ProxyMessage,
+  ProxyResponse,
+} from '@syncular/core';
+import { logSyncEvent } from '@syncular/core';
+import type {
+  ProxyTableRegistry,
+  ServerSyncDialect,
+  SyncCoreDb,
+} from '@syncular/server';
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+import type { UpgradeWebSocket, WSContext } from 'hono/ws';
+import type { Kysely } from 'kysely';
+import { ProxyConnectionManager } from './connection-manager';
+
+/**
+ * WeakMap for storing proxy connection manager per Hono instance.
+ */
+interface ProxyConnectionManagerHandle {
+  canAccept(): boolean;
+  getConnectionCount(): number;
+  register(ws: WSContext, handshake: ProxyHandshake): unknown;
+  handleMessage(ws: WSContext, message: ProxyMessage): Promise<ProxyResponse>;
+  unregister(ws: WSContext): Promise<void>;
+}
+
+const proxyConnectionManagerMap = new WeakMap<
+  Hono,
+  ProxyConnectionManagerHandle
+>();
+
+interface ProxyAuthResult {
+  /** Actor ID for oplog tracking */
+  actorId: string;
+}
+
+interface CreateProxyRoutesConfig<DB extends SyncCoreDb = SyncCoreDb> {
+  /** Database connection */
+  db: Kysely<DB>;
+  /** Server sync dialect */
+  dialect: ServerSyncDialect;
+  /** Proxy table registry for oplog generation */
+  shapes: ProxyTableRegistry;
+  /** Authenticate the request and return actor info */
+  authenticate: (c: Context) => Promise<ProxyAuthResult | null>;
+  /** WebSocket upgrade function from Hono */
+  upgradeWebSocket: UpgradeWebSocket;
+  /** Maximum concurrent connections (default: 100) */
+  maxConnections?: number;
+  /** Idle connection timeout in ms (default: 30000) */
+  idleTimeoutMs?: number;
+}
+
+/**
+ * Create Hono routes for the proxy WebSocket endpoint.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { createBunWebSocket } from 'hono/bun';
+ * import { createProxyRoutes } from '@syncular/server-hono/proxy';
+ *
+ * const { upgradeWebSocket, websocket } = createBunWebSocket();
+ *
+ * const app = new Hono();
+ *
+ * app.route('/proxy', createProxyRoutes({
+ *   db,
+ *   shapes: proxyTableRegistry,
+ *   authenticate: async (c) => {
+ *     // Verify admin auth
+ *     return { actorId: 'admin:123' };
+ *   },
+ *   upgradeWebSocket,
+ * }));
+ *
+ * export default { fetch: app.fetch, websocket };
+ * ```
+ */
+export function createProxyRoutes<DB extends SyncCoreDb>(
+  config: CreateProxyRoutesConfig<DB>
+): Hono {
+  const app = new Hono();
+
+  const manager = new ProxyConnectionManager({
+    db: config.db,
+    dialect: config.dialect,
+    shapes: config.shapes,
+    maxConnections: config.maxConnections,
+    idleTimeoutMs: config.idleTimeoutMs,
+  });
+
+  // Store manager for external access if needed
+  proxyConnectionManagerMap.set(app, manager);
+
+  // WebSocket upgrade endpoint - using regular route since WebSocket doesn't fit OpenAPI well
+  app.get('/', async (c) => {
+    // Authenticate before upgrade
+    const auth = await config.authenticate(c);
+    if (!auth) {
+      return c.json({ error: 'UNAUTHENTICATED' }, 401);
+    }
+
+    // Check connection limit
+    if (!manager.canAccept()) {
+      logSyncEvent({
+        event: 'proxy.rejected',
+        userId: auth.actorId,
+        reason: 'max_connections',
+      });
+      return c.json({ error: 'PROXY_CONNECTION_LIMIT' }, 429);
+    }
+
+    logSyncEvent({
+      event: 'proxy.connect',
+      userId: auth.actorId,
+    });
+
+    return config.upgradeWebSocket(c, {
+      onOpen(_evt, _ws) {
+        // Connection opened, wait for handshake message
+      },
+
+      async onMessage(evt, ws) {
+        try {
+          const data =
+            typeof evt.data === 'string'
+              ? evt.data
+              : new TextDecoder().decode(evt.data as ArrayBuffer);
+
+          const message = JSON.parse(data);
+
+          // Handle handshake
+          if (message.type === 'handshake') {
+            const handshake = message as ProxyHandshake;
+
+            // Validate that the handshake actor matches authenticated actor
+            if (handshake.actorId !== auth.actorId) {
+              const ack: ProxyHandshakeAck = {
+                type: 'handshake_ack',
+                ok: false,
+                error: 'Actor ID mismatch',
+              };
+              ws.send(JSON.stringify(ack));
+              ws.close(4001, 'Unauthorized');
+              return;
+            }
+
+            manager.register(ws, handshake);
+
+            const ack: ProxyHandshakeAck = {
+              type: 'handshake_ack',
+              ok: true,
+            };
+            ws.send(JSON.stringify(ack));
+            return;
+          }
+
+          // Handle proxy messages
+          const proxyMessage = message as ProxyMessage;
+          const response = await manager.handleMessage(ws, proxyMessage);
+          ws.send(JSON.stringify(response));
+        } catch (err) {
+          // Send error response if we can parse the message ID
+          try {
+            const parsed = JSON.parse(
+              typeof evt.data === 'string'
+                ? evt.data
+                : new TextDecoder().decode(evt.data as ArrayBuffer)
+            );
+            if (parsed.id) {
+              ws.send(
+                JSON.stringify({
+                  id: parsed.id,
+                  type: 'error',
+                  error: err instanceof Error ? err.message : 'Unknown error',
+                })
+              );
+            }
+          } catch {
+            // Ignore parse errors
+          }
+        }
+      },
+
+      async onClose(_evt, ws) {
+        await manager.unregister(ws);
+        logSyncEvent({
+          event: 'proxy.disconnect',
+          userId: auth.actorId,
+        });
+      },
+
+      async onError(_evt, ws) {
+        await manager.unregister(ws);
+        logSyncEvent({
+          event: 'proxy.error',
+          userId: auth.actorId,
+        });
+      },
+    });
+  });
+
+  return app;
+}
+
+/**
+ * Get the ProxyConnectionManager from a proxy routes instance.
+ */
+export function getProxyConnectionManager(
+  routes: Hono
+): ProxyConnectionManagerHandle | undefined {
+  return proxyConnectionManagerMap.get(routes);
+}