@syncular/server 0.1.3 → 0.2.0

package/src/hono/console/types.ts

@@ -1,223 +0,0 @@
-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

@@ -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>;
-
-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

@@ -1,230 +0,0 @@
-/**
- * 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

@@ -1,50 +0,0 @@
-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

@@ -1,54 +0,0 @@
-/**
- * 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';