@syncular/server 0.0.6-95 → 0.1.0

package/src/hono/console/types.ts

@@ -0,0 +1,223 @@
+import type {
+  ServerSyncDialect,
+  ServerTableHandler,
+  SqlFamily,
+  SyncCoreDb,
+  SyncServerAuth,
+} from '@syncular/server';
+import type { Context } from 'hono';
+import type { UpgradeWebSocket } from 'hono/ws';
+import type { Kysely } from 'kysely';
+import type { WebSocketConnectionManager } from '../ws';
+import type { LiveEvent } from './schemas';
+
+export interface ConsoleAuthResult {
+  /** Identifier for the console user (for audit logging). */
+  consoleUserId?: string;
+}
+
+/**
+ * Listener for console live events (SSE streaming).
+ */
+export type ConsoleEventListener = (event: LiveEvent) => void;
+
+/**
+ * Console event emitter for broadcasting live events.
+ */
+export interface ConsoleEventEmitter {
+  /** Add a listener for live events */
+  addListener(listener: ConsoleEventListener): void;
+  /** Remove a listener */
+  removeListener(listener: ConsoleEventListener): void;
+  /** Emit an event to all listeners */
+  emit(event: LiveEvent): void;
+  /**
+   * Replay recent events, optionally constrained by timestamp, partition, and max count.
+   */
+  replay(options?: {
+    since?: string;
+    limit?: number;
+    partitionId?: string;
+  }): LiveEvent[];
+}
+
+export interface ConsoleMetricsOptions {
+  /**
+   * Metrics query strategy for timeseries/latency endpoints.
+   * - raw: in-memory processing from raw event rows
+   * - aggregated: DB-level aggregation where supported (raw fallback for unsupported paths)
+   * - auto: use raw for small windows, aggregated for larger windows
+   */
+  aggregationMode?: 'auto' | 'raw' | 'aggregated';
+  /** Max events for using raw mode when aggregationMode is 'auto'. */
+  rawFallbackMaxEvents?: number;
+}
+
+export interface ConsoleMaintenanceOptions {
+  /**
+   * Minimum interval between automatic event-prune runs.
+   * Set to 0 to disable automatic pruning.
+   * Default: 5 minutes.
+   */
+  autoPruneIntervalMs?: number;
+  /**
+   * Max age for request events before pruning.
+   * Set to 0 to disable age-based pruning.
+   * Default: 7 days.
+   */
+  requestEventsMaxAgeMs?: number;
+  /**
+   * Max number of request events to retain.
+   * Set to 0 to disable count-based pruning.
+   * Default: 10000.
+   */
+  requestEventsMaxRows?: number;
+  /**
+   * Max age for operation audit events before pruning.
+   * Set to 0 to disable age-based pruning.
+   * Default: 30 days.
+   */
+  operationEventsMaxAgeMs?: number;
+  /**
+   * Max number of operation audit events to retain.
+   * Set to 0 to disable count-based pruning.
+   * Default: 5000.
+   */
+  operationEventsMaxRows?: number;
+  /**
+   * Max rows to scan per source (commits/events) for `/timeline` requests.
+   * Prevents unbounded memory growth on large histories.
+   * Set to 0 to disable the guard.
+   * Default: 10000.
+   */
+  timelineScanMaxRows?: number;
+  /**
+   * Max retained redacted client diagnostic snapshots.
+   * Set to 0 to disable count-based pruning.
+   * Default: 500.
+   */
+  clientDiagnosticsMaxRows?: number;
+}
+
+export interface ConsoleBlobObject {
+  key: string;
+  size: number;
+  uploaded: Date;
+  httpMetadata?: { contentType?: string };
+}
+
+export interface ConsoleBlobGetResult {
+  body: ReadableStream;
+  size: number;
+  httpMetadata?: { contentType?: string };
+}
+
+export interface ConsoleBlobHeadResult {
+  size: number;
+  httpMetadata?: { contentType?: string };
+}
+
+export interface ConsoleBlobBucket {
+  list(options: { prefix?: string; cursor?: string; limit?: number }): Promise<{
+    objects: ConsoleBlobObject[];
+    truncated: boolean;
+    cursor?: string;
+  }>;
+  get(key: string): Promise<ConsoleBlobGetResult | null>;
+  delete(key: string | string[]): Promise<void>;
+  head(key: string): Promise<ConsoleBlobHeadResult | null>;
+}
+
+export interface ConsoleSharedOptions {
+  /**
+   * CORS origins to allow. Defaults to ['http://localhost:5173', 'https://console.sync.dev'].
+   * Set to '*' to allow all origins (not recommended for production).
+   */
+  corsOrigins?: string[] | '*';
+  metrics?: ConsoleMetricsOptions;
+  maintenance?: ConsoleMaintenanceOptions;
+  blobBucket?: ConsoleBlobBucket;
+}
+
+export interface CreateConsoleRoutesOptions<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+  F extends SqlFamily = SqlFamily,
+> extends ConsoleSharedOptions {
+  db: Kysely<DB>;
+  dialect: ServerSyncDialect<F>;
+  handlers: ServerTableHandler<DB, Auth>[];
+  /**
+   * Authentication function for console requests.
+   * Return null to reject the request.
+   */
+  authenticate: (c: Context) => Promise<ConsoleAuthResult | null>;
+  /**
+   * Compaction options (required for /compact endpoint).
+   */
+  compact?: {
+    fullHistoryHours?: number;
+  };
+  /**
+   * Pruning options.
+   */
+  prune?: {
+    activeWindowMs?: number;
+    fallbackMaxAgeMs?: number;
+    keepNewestCommits?: number;
+  };
+  /**
+   * Event emitter for live console events.
+   * If provided along with websocket config, enables the /events/live WebSocket endpoint.
+   */
+  eventEmitter?: ConsoleEventEmitter;
+  /**
+   * Shared sync WebSocket connection manager.
+   * When provided, `/clients` includes realtime connection state per client.
+   */
+  wsConnectionManager?: WebSocketConnectionManager;
+  /**
+   * WebSocket configuration for live events streaming.
+   */
+  websocket?: {
+    enabled?: boolean;
+    /**
+     * Runtime-provided WebSocket upgrader (e.g. from `hono/bun`'s `createBunWebSocket()`).
+     */
+    upgradeWebSocket?: UpgradeWebSocket;
+    /**
+     * Heartbeat interval in milliseconds. Default: 30000
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Maximum inbound websocket message size in bytes.
+     * Messages above this limit are rejected and the connection is closed.
+     * Default: 1048576 (1 MiB)
+     */
+    maxMessageBytes?: number;
+    /**
+     * Maximum inbound websocket messages allowed per connection within one window.
+     * Set to 0 to disable rate limiting.
+     * Default: 120
+     */
+    maxMessagesPerWindow?: number;
+    /**
+     * Window size in milliseconds for inbound websocket message rate limiting.
+     * Ignored when maxMessagesPerWindow is 0.
+     * Default: 10000 (10s)
+     */
+    messageRateWindowMs?: number;
+    /**
+     * Optional list of allowed websocket origins.
+     * - undefined: allow same-origin browser upgrades and origin-less non-browser clients
+     * - '*': allow all origins
+     * - string[]: exact origin match (scheme + host + port)
+     */
+    allowedOrigins?: string[] | '*';
+  };
+  /**
+   * Optional console schema readiness promise.
+   * When provided, routes wait for this promise before querying console tables.
+   */
+  consoleSchemaReady?: Promise<void>;
+}

package/src/hono/console/ui.ts

@@ -0,0 +1,100 @@
+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>;
+
+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/hono/create-server.ts

@@ -0,0 +1,230 @@
+/**
+ * Simplified server factory for Hono
+ *
+ * Current server contract:
+ * - sync contract instead of top-level handlers/authenticate
+ * - Combined sync + console routes in one call
+ */
+
+import type {
+  ScopeCacheBackend,
+  ServerSyncConfig,
+  ServerSyncDialect,
+  SnapshotArtifactStorage,
+  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 { isBenignConsoleSchemaError } from './console/schema-errors';
+import type {
+  ConsoleEventEmitter,
+  ConsoleSharedOptions,
+} from './console/types';
+import {
+  createSyncRoutes,
+  getSyncWebSocketConnectionManager,
+  normalizeSyncCorsConfig,
+  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;
+
+  /** Scoped snapshot artifact body storage (external body storage, e.g. R2/S3) */
+  snapshotArtifactStorage?: SnapshotArtifactStorage;
+
+  /** 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;
+}
+
+export function resolveDefaultWebSocketAllowedOrigins(
+  routes: SyncRoutesConfigWithRateLimit | undefined
+): string[] | '*' | undefined {
+  return (
+    routes?.websocket?.allowedOrigins ??
+    normalizeSyncCorsConfig(routes?.cors)?.staticAllowedOrigins
+  );
+}
+
+/**
+ * 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,
+    snapshotArtifactStorage,
+    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).catch((error) => {
+          if (isBenignConsoleSchemaError(error)) {
+            return;
+          }
+          throw error;
+        })
+      : undefined;
+  const defaultWebSocketAllowedOrigins =
+    resolveDefaultWebSocketAllowedOrigins(routes);
+
+  // Create sync routes
+  const syncRoutes = createSyncRoutes({
+    db,
+    dialect,
+    handlers: sync.handlers,
+    plugins: sync.plugins,
+    authenticate: async (context): Promise<Auth | null> =>
+      sync.authenticate(context.req.raw),
+    chunkStorage,
+    snapshotArtifactStorage,
+    scopeCache,
+    consoleLiveEmitter: consoleEventEmitter,
+    consoleSchemaReady,
+    sync: {
+      ...routes,
+      websocket: upgradeWebSocket
+        ? {
+            ...routes?.websocket,
+            allowedOrigins: defaultWebSocketAllowedOrigins,
+            enabled: true,
+            upgradeWebSocket,
+          }
+        : { 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,
+        heartbeatIntervalMs: routes?.websocket?.heartbeatIntervalMs,
+        maxMessageBytes: routes?.websocket?.maxMessageBytes,
+        maxMessagesPerWindow: routes?.websocket?.maxMessagesPerWindow,
+        messageRateWindowMs: routes?.websocket?.messageRateWindowMs,
+        allowedOrigins: defaultWebSocketAllowedOrigins,
+      },
+    }),
+  });
+
+  return {
+    syncRoutes,
+    consoleRoutes,
+    consoleEventEmitter,
+  };
+}

package/src/hono/errors.ts

@@ -0,0 +1,50 @@
+import {
+  createSyncularErrorResponse,
+  type SyncularErrorCode,
+} from '@syncular/core';
+import type { Context } from 'hono';
+
+type JsonErrorStatus = 400 | 401 | 403 | 404 | 409 | 413 | 429 | 500;
+
+export function syncError(
+  c: Context,
+  status: JsonErrorStatus,
+  code: SyncularErrorCode,
+  message?: string
+): Response {
+  return c.json(createSyncularErrorResponse(code, { message }), status);
+}
+
+export function syncErrorResponse(
+  status: JsonErrorStatus,
+  code: SyncularErrorCode,
+  message?: string
+): Response {
+  return Response.json(createSyncularErrorResponse(code, { message }), {
+    status,
+  });
+}
+
+export function syncLimitExceeded(
+  c: Context,
+  args: {
+    limit: string;
+    observed: number;
+    max: number;
+    message?: string;
+  }
+): Response {
+  return c.json(
+    createSyncularErrorResponse('runtime.limit_exceeded', {
+      message:
+        args.message ??
+        `${args.limit} exceeded: ${args.observed} bytes > ${args.max} bytes`,
+      details: {
+        limit: args.limit,
+        observed: args.observed,
+        max: args.max,
+      },
+    }),
+    413
+  );
+}

package/src/hono/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Hono adapter for Syncular server infrastructure.
+ *
+ * The root @syncular/server export stays framework-agnostic; Hono-specific
+ * imports live behind this opt-in subpath.
+ */
+
+// API Key Auth
+export * from './api-key-auth';
+
+// Blob routes
+export { type CreateBlobRoutesOptions, createBlobRoutes } from './blobs';
+
+// Console API and live gateway. Console UI mounting lives in ./console/ui and
+// intentionally is not re-exported here because it requires @syncular/console.
+export * from './console/gateway';
+export * from './console/routes';
+export * from './console/schemas';
+export * from './console/types';
+
+// Simplified server factory
+export {
+  createSyncServer,
+  type SyncServerOptions,
+  type SyncServerResult,
+} from './create-server';
+
+// OpenAPI utilities
+export * from './openapi';
+
+// Proxy
+export * from './proxy';
+
+// Rate limiting
+export * from './rate-limit';
+
+// Realtime binary sync-pack helpers
+export * from './realtime-sync-packs';
+
+// Route types and factory
+export {
+  type CreateSyncRoutesOptions,
+  createSyncRoutes,
+  getSyncRealtimeUnsubscribe,
+  getSyncWebSocketConnectionManager,
+  type NormalizedSyncCorsConfig,
+  normalizeSyncCorsConfig,
+  type SyncCorsOptions,
+  type SyncCorsOrigin,
+  type SyncCorsOriginResolver,
+} from './routes';
+
+// WebSocket helpers for realtime sync
+export * from './ws';