@syncular/server-hono 0.0.4-26 → 0.0.6-101

package/src/console/schemas.ts

@@ -403,3 +403,32 @@ export const LiveEventSchema = z.object({
 });
 
 export type LiveEvent = z.infer<typeof LiveEventSchema>;
+
+// ---------------------------------------------------------------------------
+// Blob storage
+// ---------------------------------------------------------------------------
+
+export const ConsoleBlobSchema = z.object({
+  key: z.string(),
+  size: z.number().int(),
+  uploaded: z.string(),
+  httpMetadata: z.object({ contentType: z.string().optional() }).optional(),
+});
+
+export type ConsoleBlob = z.infer<typeof ConsoleBlobSchema>;
+
+export const ConsoleBlobListQuerySchema = z.object({
+  prefix: z.string().optional(),
+  cursor: z.string().optional(),
+  limit: z.coerce.number().int().min(1).max(1000).default(100),
+});
+
+export const ConsoleBlobListResponseSchema = z.object({
+  items: z.array(ConsoleBlobSchema),
+  truncated: z.boolean(),
+  cursor: z.string().nullable(),
+});
+
+export const ConsoleBlobDeleteResponseSchema = z.object({
+  deleted: z.boolean(),
+});

package/src/console/types.ts

@@ -0,0 +1,185 @@
+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;
+}
+
+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;
+  };
+  /**
+   * Optional console schema readiness promise.
+   * When provided, routes wait for this promise before querying console tables.
+   */
+  consoleSchemaReady?: Promise<void>;
+}

package/src/create-server.ts

@@ -2,25 +2,29 @@
  * Simplified server factory for Hono
  *
  * Breaking changes from legacy createSyncRoutes:
- * - handlers: array instead of TableRegistry
+ * - sync contract instead of top-level handlers/authenticate
  * - Combined sync + console routes in one call
  */
 
 import type {
+  ScopeCacheBackend,
+  ServerSyncConfig,
   ServerSyncDialect,
-  ServerTableHandler,
   SnapshotChunkStorage,
+  SqlFamily,
   SyncCoreDb,
 } from '@syncular/server';
-import type { Context } from 'hono';
 import type { UpgradeWebSocket } from 'hono/ws';
 import type { Kysely } from 'kysely';
 import {
-  type ConsoleEventEmitter,
   createConsoleEventEmitter,
   createConsoleRoutes,
   createTokenAuthenticator,
-} from './console';
+} from './console/routes';
+import type {
+  ConsoleEventEmitter,
+  ConsoleSharedOptions,
+} from './console/types';
 import {
   createSyncRoutes,
   getSyncWebSocketConnectionManager,
@@ -28,26 +32,28 @@ import {
   type SyncRoutesConfigWithRateLimit,
 } from './routes';
 
-export interface SyncServerOptions<DB extends SyncCoreDb = SyncCoreDb> {
+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;
-
-  /**
-   * Table handlers for sync operations.
-   */
-  handlers: ServerTableHandler<DB>[];
+  dialect: ServerSyncDialect<F>;
 
-  /** Authentication function - returns actorId or null for unauthenticated */
-  authenticate: (c: Context) => Promise<SyncAuthResult | null>;
+  /** 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 */
-  sync?: SyncRoutesConfigWithRateLimit;
+  routes?: SyncRoutesConfigWithRateLimit;
 
   /** WebSocket upgrader for realtime */
   upgradeWebSocket?: UpgradeWebSocket;
@@ -58,17 +64,10 @@ export interface SyncServerOptions<DB extends SyncCoreDb = SyncCoreDb> {
    */
   console?:
     | false
-    | {
+    | ({
         /** Console bearer token for authentication (required unless SYNC_CONSOLE_TOKEN is set) */
         token?: string;
-        /** CORS origins (defaults to '*') */
-        corsOrigins?: '*' | string[];
-        /** Metrics aggregation strategy for console stats endpoints */
-        metrics?: {
-          aggregationMode?: 'auto' | 'raw' | 'aggregated';
-          rawFallbackMaxEvents?: number;
-        };
-      };
+      } & ConsoleSharedOptions);
 }
 
 export interface SyncServerResult {
@@ -85,45 +84,39 @@ export interface SyncServerResult {
  *
  * @example
  * ```typescript
- * // With handlers
+ * // With sync contract
  * const { syncRoutes } = createSyncServer({
  *   db,
  *   dialect,
- *   handlers: [tasksHandler, notesHandler],
- *   authenticate: async (c) => {
- *     const userId = c.req.header('x-user-id');
- *     return userId ? { actorId: userId } : null;
- *   },
+ *   sync,
  * });
  *
  * // With custom handlers
  * const { syncRoutes, consoleRoutes } = createSyncServer({
  *   db,
  *   dialect,
- *   handlers: [tasksHandler, notesHandler],
- *   authenticate: async (c) => {
- *     const userId = c.req.header('x-user-id');
- *     return userId ? { actorId: userId } : null;
- *   },
+ *   sync,
  *   console: { token: process.env.CONSOLE_TOKEN },
  * });
  * ```
  */
-export function createSyncServer<DB extends SyncCoreDb = SyncCoreDb>(
-  options: SyncServerOptions<DB>
-): SyncServerResult {
+export function createSyncServer<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncAuthResult = SyncAuthResult,
+  F extends SqlFamily = SqlFamily,
+>(options: SyncServerOptions<DB, Auth, F>): SyncServerResult {
   const {
     db,
     dialect,
-    handlers,
-    authenticate,
-    chunkStorage,
     sync,
+    chunkStorage,
+    scopeCache,
+    routes,
     upgradeWebSocket,
     console: consoleConfig,
   } = options;
 
-  if (handlers.length === 0) {
+  if (sync.handlers.length === 0) {
     throw new Error('At least one handler must be provided');
   }
 
@@ -145,29 +138,36 @@ export function createSyncServer<DB extends SyncCoreDb = SyncCoreDb>(
   const consoleEventEmitter = isConsoleEnabled
     ? createConsoleEventEmitter()
     : undefined;
+  const consoleSchemaReady =
+    isConsoleEnabled && dialect.ensureConsoleSchema
+      ? dialect.ensureConsoleSchema(db)
+      : undefined;
 
   // Create sync routes
   const syncRoutes = createSyncRoutes({
     db,
     dialect,
-    handlers,
-    authenticate,
+    handlers: sync.handlers,
+    authenticate: async (context): Promise<Auth | null> =>
+      sync.authenticate(context.req.raw),
     chunkStorage,
+    scopeCache,
     consoleLiveEmitter: consoleEventEmitter,
+    consoleSchemaReady,
     sync: {
-      ...sync,
+      ...routes,
       websocket: upgradeWebSocket
         ? {
             enabled: true,
             upgradeWebSocket,
-            ...(sync?.websocket?.heartbeatIntervalMs !== undefined && {
-              heartbeatIntervalMs: sync.websocket.heartbeatIntervalMs,
+            ...(routes?.websocket?.heartbeatIntervalMs !== undefined && {
+              heartbeatIntervalMs: routes.websocket.heartbeatIntervalMs,
             }),
-            ...(sync?.websocket?.maxConnectionsTotal !== undefined && {
-              maxConnectionsTotal: sync.websocket.maxConnectionsTotal,
+            ...(routes?.websocket?.maxConnectionsTotal !== undefined && {
+              maxConnectionsTotal: routes.websocket.maxConnectionsTotal,
             }),
-            ...(sync?.websocket?.maxConnectionsPerClient !== undefined && {
-              maxConnectionsPerClient: sync.websocket.maxConnectionsPerClient,
+            ...(routes?.websocket?.maxConnectionsPerClient !== undefined && {
+              maxConnectionsPerClient: routes.websocket.maxConnectionsPerClient,
             }),
           }
         : { enabled: false },
@@ -182,12 +182,15 @@ export function createSyncServer<DB extends SyncCoreDb = SyncCoreDb>(
   const consoleRoutes = createConsoleRoutes({
     db,
     dialect,
-    handlers,
+    handlers: sync.handlers,
     authenticate: createTokenAuthenticator(consoleToken),
-    corsOrigins: resolvedConsoleConfig.corsOrigins ?? '*',
+    corsOrigins: resolvedConsoleConfig.corsOrigins,
     eventEmitter: consoleEventEmitter,
+    consoleSchemaReady,
     wsConnectionManager: getSyncWebSocketConnectionManager(syncRoutes),
     metrics: resolvedConsoleConfig.metrics,
+    maintenance: resolvedConsoleConfig.maintenance,
+    blobBucket: resolvedConsoleConfig.blobBucket,
     ...(upgradeWebSocket && {
       websocket: {
         enabled: true,

package/src/proxy/connection-manager.ts

@@ -11,7 +11,7 @@ import type {
 } from '@syncular/core';
 import type {
   ExecuteProxyQueryResult,
-  ProxyTableRegistry,
+  ProxyHandlerCollection,
   ServerSyncDialect,
   SyncCoreDb,
 } from '@syncular/server';
@@ -26,8 +26,8 @@ export interface ProxyConnectionManagerConfig<
   db: Kysely<DB>;
   /** Server sync dialect */
   dialect: ServerSyncDialect;
-  /** Proxy table registry for oplog generation */
-  handlers: ProxyTableRegistry;
+  /** Proxy table handlers for oplog generation */
+  handlers: ProxyHandlerCollection;
   /** Maximum concurrent connections (default: 100) */
   maxConnections?: number;
   /** Idle connection timeout in ms (default: 30000) */

package/src/proxy/routes.ts

@@ -12,7 +12,7 @@ import type {
 } from '@syncular/core';
 import { logSyncEvent } from '@syncular/core';
 import type {
-  ProxyTableRegistry,
+  ProxyHandlerCollection,
   ServerSyncDialect,
   SyncCoreDb,
 } from '@syncular/server';
@@ -48,8 +48,8 @@ interface CreateProxyRoutesConfig<DB extends SyncCoreDb = SyncCoreDb> {
   db: Kysely<DB>;
   /** Server sync dialect */
   dialect: ServerSyncDialect;
-  /** Proxy table registry for oplog generation */
-  handlers: ProxyTableRegistry;
+  /** Proxy table handlers for oplog generation */
+  handlers: ProxyHandlerCollection;
   /** Authenticate the request and return actor info */
   authenticate: (c: Context) => Promise<ProxyAuthResult | null>;
   /** WebSocket upgrade function from Hono */
@@ -75,7 +75,7 @@ interface CreateProxyRoutesConfig<DB extends SyncCoreDb = SyncCoreDb> {
  *
  * app.route('/proxy', createProxyRoutes({
  *   db,
- *   handlers: proxyTableRegistry,
+ *   handlers: proxyHandlers,
  *   authenticate: async (c) => {
  *     // Verify admin auth
  *     return { actorId: 'admin:123' };