@syncular/server 0.0.6-96 → 0.1.1

package/src/hono/openapi.ts

@@ -0,0 +1,139 @@
+/**
+ * @syncular/server/hono - OpenAPI Spec Export
+ *
+ * Provides utilities for generating and serving OpenAPI specifications.
+ */
+
+import { Scalar } from '@scalar/hono-api-reference';
+import { type Handler, Hono } from 'hono';
+import { generateSpecs, openAPIRouteHandler } from 'hono-openapi';
+
+const DEFAULT_SCALAR_CDN =
+  'https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest';
+
+export interface OpenAPIConfig {
+  title?: string;
+  version?: string;
+  description?: string;
+  servers?: Array<{ url: string; description?: string }>;
+}
+
+export interface ScalarReferenceConfig {
+  url?: string;
+  cdn?: string;
+}
+
+export interface OpenAPIDocsRoutesConfig extends OpenAPIConfig {
+  openAPIPath?: string;
+  scalarPath?: string;
+  scalar?: ScalarReferenceConfig;
+}
+
+function normalizeRoutePath(path: string): string {
+  return path.startsWith('/') ? path : `/${path}`;
+}
+
+/**
+ * Create an OpenAPI spec handler that can be used with Hono routes.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { createSyncRoutes, createConsoleRoutes, createOpenAPIHandler } from '@syncular/server/hono';
+ *
+ * const app = new Hono();
+ * const syncRoutes = createSyncRoutes({ ... });
+ * const consoleRoutes = createConsoleRoutes({ ... });
+ *
+ * app.route('/sync', syncRoutes);
+ * app.route('/console', consoleRoutes);
+ *
+ * // Add OpenAPI spec endpoint
+ * app.get('/openapi.json', createOpenAPIHandler(app, {
+ *   title: 'Syncular API',
+ *   version: '1.0.0',
+ * }));
+ * ```
+ */
+export function createOpenAPIHandler(app: Hono, config: OpenAPIConfig = {}) {
+  return openAPIRouteHandler(app, {
+    documentation: {
+      info: {
+        title: config.title ?? 'Syncular API',
+        version: config.version ?? '1.0.0',
+        description:
+          config.description ??
+          'Sync infrastructure API for real-time data synchronization',
+      },
+      servers: config.servers,
+    },
+  });
+}
+
+/**
+ * Create a Scalar API reference handler that points at an OpenAPI document.
+ */
+export function createScalarReferenceHandler(
+  config: ScalarReferenceConfig = {}
+): Handler {
+  return Scalar({
+    url: config.url ?? '/openapi.json',
+    cdn: config.cdn ?? DEFAULT_SCALAR_CDN,
+  });
+}
+
+/**
+ * Create a small Hono app that serves both `/openapi.json` and `/spec`.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { createOpenAPIDocsRoutes } from '@syncular/server/hono';
+ *
+ * const app = new Hono();
+ * app.route('/', createOpenAPIDocsRoutes(app, {
+ *   title: 'Syncular API',
+ * }));
+ * ```
+ */
+export function createOpenAPIDocsRoutes(
+  app: Hono,
+  config: OpenAPIDocsRoutesConfig = {}
+) {
+  const docsApp = new Hono();
+  const openAPIPath = normalizeRoutePath(config.openAPIPath ?? '/openapi.json');
+  const scalarPath = normalizeRoutePath(config.scalarPath ?? '/spec');
+
+  docsApp.get(openAPIPath, createOpenAPIHandler(app, config));
+  docsApp.get(
+    scalarPath,
+    createScalarReferenceHandler({
+      url: config.scalar?.url ?? openAPIPath,
+      cdn: config.scalar?.cdn,
+    })
+  );
+
+  return docsApp;
+}
+
+/**
+ * Generate OpenAPI document from a Hono app instance.
+ * This is useful for build-time spec generation.
+ */
+export async function generateOpenAPIDocument(
+  app: Hono,
+  config: OpenAPIConfig = {}
+): Promise<unknown> {
+  return generateSpecs(app, {
+    documentation: {
+      info: {
+        title: config.title ?? 'Syncular API',
+        version: config.version ?? '1.0.0',
+        description:
+          config.description ??
+          'Sync infrastructure API for real-time data synchronization',
+      },
+      servers: config.servers,
+    },
+  });
+}

package/src/hono/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,
+  ProxyHandlerCollection,
+  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 handlers for oplog generation */
+  handlers: ProxyHandlerCollection;
+  /** 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,
+      handlers: this.config.handlers,
+      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/hono/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';