@syncular/server-hono 0.0.6-96 → 0.2.0

package/src/console/ui.ts

@@ -1,100 +0,0 @@
-import {
-  type ConsoleStaticResponder,
-  type ConsoleUiPrefill,
-  type CreateConsoleStaticResponderOptions,
-  createConsoleStaticResponder,
-  type ServeConsoleStaticRequestOptions,
-} from '@syncular/console/server';
-import type { Context, Hono } from 'hono';
-
-type MaybePromise<T> = T | Promise<T>;
-
-export interface MountConsoleUiOptions {
-  /**
-   * Browser mount path for the console UI. Defaults to `/console`.
-   */
-  mountPath?: string;
-  /**
-   * API base path used to prefill the console server URL.
-   * Defaults to `/api`.
-   */
-  apiBasePath?: string;
-  /**
-   * Resolve prefill values per request.
-   * Return `null`/`undefined` to keep defaults.
-   */
-  resolvePrefill?: (
-    c: Context
-  ) => MaybePromise<ConsoleUiPrefill | null | undefined>;
-  /**
-   * Convenience callback for prefilled token.
-   */
-  resolveToken?: (c: Context) => MaybePromise<string | undefined>;
-  /**
-   * Override distributable directory.
-   */
-  staticDir?: string;
-  /**
-   * Cache-Control header for index responses.
-   */
-  indexCacheControl?: string;
-  /**
-   * Cache-Control header for static asset responses.
-   */
-  assetCacheControl?: string;
-}
-
-type StaticResponderConfig = Pick<
-  CreateConsoleStaticResponderOptions,
-  'mountPath' | 'staticDir' | 'indexCacheControl' | 'assetCacheControl'
->;
-
-function normalizePath(pathname: string | undefined, fallback: string): string {
-  const value = pathname?.trim() ?? '';
-  if (!value) return fallback;
-  if (value === '/') return '/';
-  const withLeadingSlash = value.startsWith('/') ? value : `/${value}`;
-  return withLeadingSlash.replace(/\/+$/g, '') || '/';
-}
-
-export function mountConsoleUi(
-  app: Hono,
-  options: MountConsoleUiOptions = {}
-): void {
-  const mountPath = normalizePath(options.mountPath, '/console');
-  const apiBasePath = normalizePath(options.apiBasePath, '/api');
-
-  const staticResponderConfig: StaticResponderConfig = {
-    mountPath,
-    staticDir: options.staticDir,
-    indexCacheControl: options.indexCacheControl,
-    assetCacheControl: options.assetCacheControl,
-  };
-  const serveConsoleStatic: ConsoleStaticResponder =
-    createConsoleStaticResponder(staticResponderConfig);
-
-  const handler = async (c: Context) => {
-    const prefillFromResolver = await options.resolvePrefill?.(c);
-    const token = await options.resolveToken?.(c);
-    const origin = new URL(c.req.url).origin;
-
-    const prefill: ConsoleUiPrefill = {
-      basePath: mountPath,
-      serverUrl: `${origin}${apiBasePath}`,
-      ...prefillFromResolver,
-    };
-
-    if (token !== undefined) {
-      prefill.token = token;
-    }
-
-    const requestOptions: ServeConsoleStaticRequestOptions = { prefill };
-    const response = await serveConsoleStatic(c.req.raw, requestOptions);
-    if (!response) return c.notFound();
-    return response;
-  };
-
-  const wildcardPath = mountPath === '/' ? '/*' : `${mountPath}/*`;
-  app.get(mountPath, handler);
-  app.get(wildcardPath, handler);
-}

package/src/create-server.ts

@@ -1,207 +0,0 @@
-/**
- * Simplified server factory for Hono
- *
- * Breaking changes from legacy createSyncRoutes:
- * - sync contract instead of top-level handlers/authenticate
- * - Combined sync + console routes in one call
- */
-
-import type {
-  ScopeCacheBackend,
-  ServerSyncConfig,
-  ServerSyncDialect,
-  SnapshotChunkStorage,
-  SqlFamily,
-  SyncCoreDb,
-} from '@syncular/server';
-import type { UpgradeWebSocket } from 'hono/ws';
-import type { Kysely } from 'kysely';
-import {
-  createConsoleEventEmitter,
-  createConsoleRoutes,
-  createTokenAuthenticator,
-} from './console/routes';
-import type {
-  ConsoleEventEmitter,
-  ConsoleSharedOptions,
-} from './console/types';
-import {
-  createSyncRoutes,
-  getSyncWebSocketConnectionManager,
-  type SyncAuthResult,
-  type SyncRoutesConfigWithRateLimit,
-} from './routes';
-
-export interface SyncServerOptions<
-  DB extends SyncCoreDb = SyncCoreDb,
-  Auth extends SyncAuthResult = SyncAuthResult,
-  F extends SqlFamily = SqlFamily,
-> {
-  /** Kysely database instance */
-  db: Kysely<DB>;
-
-  /** Server sync dialect */
-  dialect: ServerSyncDialect<F>;
-
-  /** Sync contract with auth + table handlers */
-  sync: ServerSyncConfig<DB, Auth>;
-
-  /** Snapshot chunk storage (external body storage, e.g. R2/S3) */
-  chunkStorage?: SnapshotChunkStorage;
-
-  /** Scope cache backend for resolveScopes() results */
-  scopeCache?: ScopeCacheBackend;
-
-  /** Sync route configuration */
-  routes?: SyncRoutesConfigWithRateLimit;
-
-  /** WebSocket upgrader for realtime */
-  upgradeWebSocket?: UpgradeWebSocket;
-
-  /**
-   * Console configuration for dashboard/monitoring.
-   * Omit or set to false to disable console routes.
-   */
-  console?:
-    | false
-    | ({
-        /** Console bearer token for authentication (required unless SYNC_CONSOLE_TOKEN is set) */
-        token?: string;
-      } & ConsoleSharedOptions);
-}
-
-export interface SyncServerResult {
-  /** Sync routes for Hono */
-  syncRoutes: ReturnType<typeof createSyncRoutes>;
-  /** Console routes for Hono (if enabled) */
-  consoleRoutes?: ReturnType<typeof createConsoleRoutes>;
-  /** Console event emitter (if console enabled) */
-  consoleEventEmitter?: ConsoleEventEmitter;
-}
-
-/**
- * Create a simplified sync server with sync and optional console routes.
- *
- * @example
- * ```typescript
- * // With sync contract
- * const { syncRoutes } = createSyncServer({
- *   db,
- *   dialect,
- *   sync,
- * });
- *
- * // With custom handlers
- * const { syncRoutes, consoleRoutes } = createSyncServer({
- *   db,
- *   dialect,
- *   sync,
- *   console: { token: process.env.CONSOLE_TOKEN },
- * });
- * ```
- */
-export function createSyncServer<
-  DB extends SyncCoreDb = SyncCoreDb,
-  Auth extends SyncAuthResult = SyncAuthResult,
-  F extends SqlFamily = SqlFamily,
->(options: SyncServerOptions<DB, Auth, F>): SyncServerResult {
-  const {
-    db,
-    dialect,
-    sync,
-    chunkStorage,
-    scopeCache,
-    routes,
-    upgradeWebSocket,
-    console: consoleConfig,
-  } = options;
-
-  if (sync.handlers.length === 0) {
-    throw new Error('At least one handler must be provided');
-  }
-
-  const resolvedConsoleConfig =
-    consoleConfig === false || consoleConfig === undefined
-      ? undefined
-      : consoleConfig;
-  const isConsoleEnabled = Boolean(resolvedConsoleConfig);
-  const consoleToken = isConsoleEnabled
-    ? (resolvedConsoleConfig?.token ?? process.env.SYNC_CONSOLE_TOKEN)
-    : undefined;
-
-  if (isConsoleEnabled && !consoleToken) {
-    throw new Error(
-      'Console is enabled but no token is configured. Set `console.token` or SYNC_CONSOLE_TOKEN.'
-    );
-  }
-
-  const consoleEventEmitter = isConsoleEnabled
-    ? createConsoleEventEmitter()
-    : undefined;
-  const consoleSchemaReady =
-    isConsoleEnabled && dialect.ensureConsoleSchema
-      ? dialect.ensureConsoleSchema(db)
-      : undefined;
-
-  // Create sync routes
-  const syncRoutes = createSyncRoutes({
-    db,
-    dialect,
-    handlers: sync.handlers,
-    authenticate: async (context): Promise<Auth | null> =>
-      sync.authenticate(context.req.raw),
-    chunkStorage,
-    scopeCache,
-    consoleLiveEmitter: consoleEventEmitter,
-    consoleSchemaReady,
-    sync: {
-      ...routes,
-      websocket: upgradeWebSocket
-        ? {
-            enabled: true,
-            upgradeWebSocket,
-            ...(routes?.websocket?.heartbeatIntervalMs !== undefined && {
-              heartbeatIntervalMs: routes.websocket.heartbeatIntervalMs,
-            }),
-            ...(routes?.websocket?.maxConnectionsTotal !== undefined && {
-              maxConnectionsTotal: routes.websocket.maxConnectionsTotal,
-            }),
-            ...(routes?.websocket?.maxConnectionsPerClient !== undefined && {
-              maxConnectionsPerClient: routes.websocket.maxConnectionsPerClient,
-            }),
-          }
-        : { enabled: false },
-    },
-  });
-
-  // Console is opt-in; disable unless explicitly configured.
-  if (!resolvedConsoleConfig) {
-    return { syncRoutes };
-  }
-
-  const consoleRoutes = createConsoleRoutes({
-    db,
-    dialect,
-    handlers: sync.handlers,
-    authenticate: createTokenAuthenticator(consoleToken),
-    corsOrigins: resolvedConsoleConfig.corsOrigins,
-    eventEmitter: consoleEventEmitter,
-    consoleSchemaReady,
-    wsConnectionManager: getSyncWebSocketConnectionManager(syncRoutes),
-    metrics: resolvedConsoleConfig.metrics,
-    maintenance: resolvedConsoleConfig.maintenance,
-    blobBucket: resolvedConsoleConfig.blobBucket,
-    ...(upgradeWebSocket && {
-      websocket: {
-        enabled: true,
-        upgradeWebSocket,
-      },
-    }),
-  });
-
-  return {
-    syncRoutes,
-    consoleRoutes,
-    consoleEventEmitter,
-  };
-}

package/src/openapi.ts

@@ -1,74 +0,0 @@
-/**
- * @syncular/server-hono - OpenAPI Spec Export
- *
- * Provides utilities for generating and serving OpenAPI specifications.
- */
-
-import type { Hono } from 'hono';
-import { generateSpecs, openAPIRouteHandler } from 'hono-openapi';
-
-interface OpenAPIConfig {
-  title?: string;
-  version?: string;
-  description?: string;
-  servers?: Array<{ url: string; description?: string }>;
-}
-
-/**
- * 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,
-    },
-  });
-}
-
-/**
- * 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/proxy/connection-manager.ts

@@ -1,340 +0,0 @@
-/**
- * @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);
-  }
-}