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

package/src/routes.ts

@@ -9,7 +9,9 @@
 
 import {
   captureSyncException,
+  countSyncMetric,
   createSyncTimer,
+  distributionSyncMetric,
   ErrorResponseSchema,
   logSyncEvent,
   SyncCombinedRequestSchema,
@@ -17,15 +19,19 @@ import {
   SyncPushRequestSchema,
 } from '@syncular/core';
 import type {
+  ScopeCacheBackend,
   ServerSyncDialect,
   ServerTableHandler,
   SnapshotChunkStorage,
+  SqlFamily,
   SyncCoreDb,
   SyncRealtimeBroadcaster,
   SyncRealtimeEvent,
+  SyncServerAuth,
 } from '@syncular/server';
 import {
   type CompactOptions,
+  createServerHandlerCollection,
   InvalidSubscriptionScopeError,
   type PruneOptions,
   type PullResult,
@@ -33,7 +39,6 @@ import {
   pushCommit,
   readSnapshotChunk,
   recordClientCursor,
-  TableRegistry,
 } from '@syncular/server';
 import type { Context, MiddlewareHandler } from 'hono';
 import { Hono } from 'hono';
@@ -64,10 +69,7 @@ import {
 const wsConnectionManagerMap = new WeakMap<Hono, WebSocketConnectionManager>();
 const realtimeUnsubscribeMap = new WeakMap<Hono, () => void>();
 
-export interface SyncAuthResult {
-  actorId: string;
-  partitionId?: string;
-}
+export interface SyncAuthResult extends SyncServerAuth {}
 
 /**
  * WebSocket configuration for realtime sync.
@@ -119,6 +121,22 @@ export interface SyncRoutesConfigWithRateLimit {
    * Default: 200
    */
   maxOperationsPerPush?: number;
+  /**
+   * Request/response payload snapshots recorded for console inspection.
+   */
+  requestPayloadSnapshots?: {
+    /**
+     * Enable payload snapshot storage in `sync_request_payloads`.
+     * Default: true when console event recording is enabled.
+     */
+    enabled?: boolean;
+    /**
+     * Max serialized payload size in bytes per request/response snapshot.
+     * Larger payloads are truncated with metadata.
+     * Default: 128 KiB.
+     */
+    maxBytes?: number;
+  };
   /**
    * Rate limiting configuration.
    * Set to false to disable all rate limiting.
@@ -162,11 +180,15 @@ export interface SyncRoutesConfigWithRateLimit {
   };
 }
 
-export interface CreateSyncRoutesOptions<DB extends SyncCoreDb = SyncCoreDb> {
+export interface CreateSyncRoutesOptions<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncAuthResult = SyncAuthResult,
+  F extends SqlFamily = SqlFamily,
+> {
   db: Kysely<DB>;
-  dialect: ServerSyncDialect;
-  handlers: ServerTableHandler<DB>[];
-  authenticate: (c: Context) => Promise<SyncAuthResult | null>;
+  dialect: ServerSyncDialect<F>;
+  handlers: ServerTableHandler<DB, Auth>[];
+  authenticate: (c: Context) => Promise<Auth | null>;
   sync?: SyncRoutesConfigWithRateLimit;
   wsConnectionManager?: WebSocketConnectionManager;
   /**
@@ -175,6 +197,11 @@ export interface CreateSyncRoutesOptions<DB extends SyncCoreDb = SyncCoreDb> {
    * (S3, R2, etc.) instead of inline in the database.
    */
   chunkStorage?: SnapshotChunkStorage;
+  /**
+   * Optional scope cache backend for resolveScopes() results.
+   * Request-local memoization is always applied for every pull.
+   */
+  scopeCache?: ScopeCacheBackend;
   /**
    * Optional live emitter for console websocket activity feed.
    * When provided, sync lifecycle events are published to `/console/events/live`.
@@ -186,6 +213,11 @@ export interface CreateSyncRoutesOptions<DB extends SyncCoreDb = SyncCoreDb> {
       data: Record<string, unknown>;
     }): void;
   };
+  /**
+   * Optional console schema readiness promise.
+   * When provided, request-event recording waits for this promise before writing.
+   */
+  consoleSchemaReady?: Promise<void>;
 }
 
 // ============================================================================
@@ -196,7 +228,7 @@ const snapshotChunkParamsSchema = z.object({
   chunkId: z.string().min(1),
 });
 
-const MAX_REQUEST_PAYLOAD_SNAPSHOT_BYTES = 128 * 1024;
+const DEFAULT_REQUEST_PAYLOAD_SNAPSHOT_MAX_BYTES = 128 * 1024;
 
 type TraceContext = {
   traceId: string | null;
@@ -243,6 +275,19 @@ function parseSentryTraceHeader(
   return { traceId, spanId };
 }
 
+function readPositiveInteger(
+  value: number | undefined,
+  fallback: number
+): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return fallback;
+  }
+  if (value <= 0) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+
 function readTraceContext(c: Context): TraceContext {
   const traceparent = parseW3cTraceparent(c.req.header('traceparent'));
   if (traceparent) return traceparent;
@@ -390,16 +435,16 @@ function countPullRows(response: PullResult['response']): number {
   }, 0);
 }
 
-function encodePayloadSnapshot(value: unknown): string {
+function encodePayloadSnapshot(value: unknown, maxBytes: number): string {
   try {
     const serialized = JSON.stringify(value);
-    if (serialized.length <= MAX_REQUEST_PAYLOAD_SNAPSHOT_BYTES) {
+    if (serialized.length <= maxBytes) {
       return serialized;
     }
     return JSON.stringify({
       truncated: true,
       originalSizeBytes: serialized.length,
-      preview: serialized.slice(0, MAX_REQUEST_PAYLOAD_SNAPSHOT_BYTES),
+      preview: serialized.slice(0, maxBytes),
     });
   } catch {
     return JSON.stringify({
@@ -430,9 +475,11 @@ function emitConsoleLiveEvent(
   });
 }
 
-export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
-  options: CreateSyncRoutesOptions<DB>
-): Hono {
+export function createSyncRoutes<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncAuthResult = SyncAuthResult,
+  F extends SqlFamily = SqlFamily,
+>(options: CreateSyncRoutesOptions<DB, Auth, F>): Hono {
   const routes = new Hono();
   routes.onError((error, c) => {
     captureSyncException(error, {
@@ -442,10 +489,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
     });
     return c.text('Internal Server Error', 500);
   });
-  const handlerRegistry = new TableRegistry<DB>();
-  for (const handler of options.handlers) {
-    handlerRegistry.register(handler);
-  }
+  const handlerRegistry = createServerHandlerCollection(options.handlers);
   const config = options.sync ?? {};
   const maxPullLimitCommits = config.maxPullLimitCommits ?? 100;
   const maxSubscriptionsPerPull = config.maxSubscriptionsPerPull ?? 200;
@@ -455,6 +499,25 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
   const consoleLiveEmitter = options.consoleLiveEmitter;
   const shouldEmitConsoleLiveEvents = consoleLiveEmitter !== undefined;
   const shouldRecordRequestEvents = shouldEmitConsoleLiveEvents;
+  const shouldCaptureRequestPayloadSnapshots =
+    shouldRecordRequestEvents &&
+    config.requestPayloadSnapshots?.enabled !== false;
+  const requestPayloadSnapshotMaxBytes = readPositiveInteger(
+    config.requestPayloadSnapshots?.maxBytes,
+    DEFAULT_REQUEST_PAYLOAD_SNAPSHOT_MAX_BYTES
+  );
+  const consoleSchemaReadyBase = shouldRecordRequestEvents
+    ? (options.consoleSchemaReady ??
+      options.dialect.ensureConsoleSchema?.(options.db) ??
+      Promise.resolve())
+    : Promise.resolve();
+  const consoleSchemaReady = consoleSchemaReadyBase.catch((error) => {
+    logSyncEvent({
+      event: 'sync.console_schema_ready_failed',
+      error: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  });
 
   // -------------------------------------------------------------------------
   // Optional WebSocket manager (scope-key based wake-ups)
@@ -565,8 +628,14 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             payload_ref, partition_id, request_payload, response_payload, created_at
           ) VALUES (
             ${nextPayloadRef}, ${event.partitionId},
-            ${encodePayloadSnapshot(event.payloadSnapshot.request)},
-            ${encodePayloadSnapshot(event.payloadSnapshot.response)},
+            ${encodePayloadSnapshot(
+              event.payloadSnapshot.request,
+              requestPayloadSnapshotMaxBytes
+            )},
+            ${encodePayloadSnapshot(
+              event.payloadSnapshot.response,
+              requestPayloadSnapshotMaxBytes
+            )},
             ${nowIso}
           )
           ON CONFLICT (payload_ref) DO UPDATE SET
@@ -620,19 +689,21 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
 
     const resolvedEvent = typeof event === 'function' ? event() : event;
 
-    void recordRequestEvent(resolvedEvent).catch((error) => {
-      logAsyncFailureOnce('sync.request_event_record_failed', {
-        event: 'sync.request_event_record_failed',
-        userId: resolvedEvent.actorId,
-        clientId: resolvedEvent.clientId,
-        requestEventType: resolvedEvent.eventType,
-        error: error instanceof Error ? error.message : String(error),
+    void consoleSchemaReady
+      .then(() => recordRequestEvent(resolvedEvent))
+      .catch((error) => {
+        logAsyncFailureOnce('sync.request_event_record_failed', {
+          event: 'sync.request_event_record_failed',
+          userId: resolvedEvent.actorId,
+          clientId: resolvedEvent.clientId,
+          requestEventType: resolvedEvent.eventType,
+          error: error instanceof Error ? error.message : String(error),
+        });
       });
-    });
   };
 
-  const authCache = new WeakMap<Context, Promise<SyncAuthResult | null>>();
-  const getAuth = (c: Context): Promise<SyncAuthResult | null> => {
+  const authCache = new WeakMap<Context, Promise<Auth | null>>();
+  const getAuth = (c: Context): Promise<Auth | null> => {
     const cached = authCache.get(c);
     if (cached) return cached;
     const pending = options.authenticate(c);
@@ -787,8 +858,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           db: options.db,
           dialect: options.dialect,
           handlers: handlerRegistry,
-          actorId: auth.actorId,
-          partitionId,
+          auth,
           request: {
             clientId,
             clientCommitId: pushBody.clientCommitId,
@@ -826,15 +896,17 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           commitSeq: pushed.response.commitSeq,
           operationCount: pushOps.length,
           tables: pushed.affectedTables,
-          payloadSnapshot: {
-            request: {
-              clientId,
-              clientCommitId: pushBody.clientCommitId,
-              schemaVersion: pushBody.schemaVersion,
-              operations: pushBody.operations,
-            },
-            response: pushed.response,
-          },
+          payloadSnapshot: shouldCaptureRequestPayloadSnapshots
+            ? {
+                request: {
+                  clientId,
+                  clientCommitId: pushBody.clientCommitId,
+                  schemaVersion: pushBody.schemaVersion,
+                  operations: pushBody.operations,
+                },
+                response: pushed.response,
+              }
+            : null,
         }));
         emitConsoleLiveEvent(consoleLiveEmitter, 'push', () => ({
           partitionId,
@@ -979,10 +1051,10 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             db: options.db,
             dialect: options.dialect,
             handlers: handlerRegistry,
-            actorId: auth.actorId,
-            partitionId,
+            auth,
             request,
             chunkStorage: options.chunkStorage,
+            scopeCache: options.scopeCache,
           });
         } catch (err) {
           if (err instanceof InvalidSubscriptionScopeError) {
@@ -1045,7 +1117,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           const scopesSummary = shouldRecordRequestEvents
             ? summarizeScopeValues(pullResult.effectiveScopes)
             : null;
-          const payloadSnapshot = shouldRecordRequestEvents
+          const payloadSnapshot = shouldCaptureRequestPayloadSnapshots
             ? {
                 request: {
                   clientId,
@@ -1318,6 +1390,32 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
 
       let unregister: (() => void) | null = null;
       let connRef: ReturnType<typeof createWebSocketConnection> | null = null;
+      const connectionCountBeforeUpgrade =
+        wsConnectionManager.getConnectionCount(clientId);
+      let sessionStartedAtMs: number | null = null;
+      let sessionEnded = false;
+
+      const finishRealtimeSession = (reason: 'closed' | 'error') => {
+        if (sessionEnded) return;
+        sessionEnded = true;
+        if (sessionStartedAtMs === null) {
+          return;
+        }
+        const durationMs = Math.max(0, Date.now() - sessionStartedAtMs);
+        countSyncMetric('sync.sessions.ended', 1, {
+          attributes: {
+            transportPath: realtimeTransportPath,
+            reason,
+          },
+        });
+        distributionSyncMetric('sync.sessions.duration_ms', durationMs, {
+          unit: 'millisecond',
+          attributes: {
+            transportPath: realtimeTransportPath,
+            reason,
+          },
+        });
+      };
 
       const upgradeWebSocket = websocketConfig.upgradeWebSocket;
       if (!upgradeWebSocket) {
@@ -1332,6 +1430,20 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             transportPath: realtimeTransportPath,
           });
           connRef = conn;
+          sessionStartedAtMs = Date.now();
+          countSyncMetric('sync.sessions.started', 1, {
+            attributes: {
+              transportPath: realtimeTransportPath,
+            },
+          });
+          if (connectionCountBeforeUpgrade > 0) {
+            countSyncMetric('sync.transport.reconnects', 1, {
+              attributes: {
+                transportPath: realtimeTransportPath,
+                source: 'server',
+              },
+            });
+          }
 
           unregister = wsConnectionManager.register(conn, initialScopeKeys);
           conn.sendHeartbeat();
@@ -1348,6 +1460,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           unregister?.();
           unregister = null;
           connRef = null;
+          finishRealtimeSession('closed');
           logSyncEvent({
             event: 'sync.realtime.disconnect',
             userId: auth.actorId,
@@ -1363,6 +1476,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           unregister?.();
           unregister = null;
           connRef = null;
+          finishRealtimeSession('error');
           logSyncEvent({
             event: 'sync.realtime.disconnect',
             userId: auth.actorId,
@@ -1383,13 +1497,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             if (!msg || typeof msg !== 'object') return;
 
             if (msg.type === 'push') {
-              void handleWsPush(
-                msg,
-                connRef,
-                auth.actorId,
-                partitionId,
-                clientId
-              );
+              void handleWsPush(msg, connRef, auth, clientId);
               return;
             }
 
@@ -1481,10 +1589,11 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
   async function handleWsPush(
     msg: Record<string, unknown>,
     conn: WebSocketConnection,
-    actorId: string,
-    partitionId: string,
+    auth: Auth,
     clientId: string
   ): Promise<void> {
+    const actorId = auth.actorId;
+    const partitionId = auth.partitionId ?? 'default';
     const requestId = typeof msg.requestId === 'string' ? msg.requestId : '';
     if (!requestId) return;
     const traceContext = readTraceContextFromMessage(msg);
@@ -1521,14 +1630,16 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           durationMs: invalidDurationMs,
           errorCode: 'INVALID_PUSH_PAYLOAD',
           errorMessage: 'Invalid push payload',
-          payloadSnapshot: {
-            request: msg,
-            response: {
-              ok: false,
-              status: 'rejected',
-              reason: 'invalid_push_payload',
-            },
-          },
+          payloadSnapshot: shouldCaptureRequestPayloadSnapshots
+            ? {
+                request: msg,
+                response: {
+                  ok: false,
+                  status: 'rejected',
+                  reason: 'invalid_push_payload',
+                },
+              }
+            : null,
         }));
         emitConsoleLiveEvent(consoleLiveEmitter, 'push', () => ({
           partitionId,
@@ -1579,19 +1690,21 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           errorCode: 'MAX_OPERATIONS_EXCEEDED',
           errorMessage: `Maximum ${maxOperationsPerPush} operations per push`,
           operationCount: pushOps.length,
-          payloadSnapshot: {
-            request: {
-              clientId,
-              clientCommitId: parsed.data.clientCommitId,
-              schemaVersion: parsed.data.schemaVersion,
-              operations: parsed.data.operations,
-            },
-            response: {
-              ok: false,
-              status: 'rejected',
-              reason: 'max_operations_exceeded',
-            },
-          },
+          payloadSnapshot: shouldCaptureRequestPayloadSnapshots
+            ? {
+                request: {
+                  clientId,
+                  clientCommitId: parsed.data.clientCommitId,
+                  schemaVersion: parsed.data.schemaVersion,
+                  operations: parsed.data.operations,
+                },
+                response: {
+                  ok: false,
+                  status: 'rejected',
+                  reason: 'max_operations_exceeded',
+                },
+              }
+            : null,
         }));
         emitConsoleLiveEvent(consoleLiveEmitter, 'push', () => ({
           partitionId,
@@ -1615,8 +1728,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
         db: options.db,
         dialect: options.dialect,
         handlers: handlerRegistry,
-        actorId,
-        partitionId,
+        auth,
         request: {
           clientId,
           clientCommitId: parsed.data.clientCommitId,
@@ -1654,15 +1766,17 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
         commitSeq: pushed.response.commitSeq,
         operationCount: pushOps.length,
         tables: pushed.affectedTables,
-        payloadSnapshot: {
-          request: {
-            clientId,
-            clientCommitId: parsed.data.clientCommitId,
-            schemaVersion: parsed.data.schemaVersion,
-            operations: parsed.data.operations,
-          },
-          response: pushed.response,
-        },
+        payloadSnapshot: shouldCaptureRequestPayloadSnapshots
+          ? {
+              request: {
+                clientId,
+                clientCommitId: parsed.data.clientCommitId,
+                schemaVersion: parsed.data.schemaVersion,
+                operations: parsed.data.operations,
+              },
+              response: pushed.response,
+            }
+          : null,
       }));
       emitConsoleLiveEvent(consoleLiveEmitter, 'push', () => ({
         partitionId,
@@ -1681,6 +1795,19 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
         tables: pushed.affectedTables,
       }));
 
+      const detectedConflicts = pushed.response.results.reduce(
+        (count, result) => count + (result.status === 'conflict' ? 1 : 0),
+        0
+      );
+      if (detectedConflicts > 0) {
+        countSyncMetric('sync.conflicts.detected', detectedConflicts, {
+          attributes: {
+            syncPath: 'ws-push',
+            transportPath: conn.transportPath,
+          },
+        });
+      }
+
       // WS notifications to other clients
       if (
         wsConnectionManager &&
@@ -1771,15 +1898,17 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
         durationMs: failedDurationMs,
         errorCode: 'INTERNAL_SERVER_ERROR',
         errorMessage: message,
-        payloadSnapshot: {
-          request: msg,
-          response: {
-            ok: false,
-            status: 'rejected',
-            reason: 'internal_server_error',
-            message,
-          },
-        },
+        payloadSnapshot: shouldCaptureRequestPayloadSnapshots
+          ? {
+              request: msg,
+              response: {
+                ok: false,
+                status: 'rejected',
+                reason: 'internal_server_error',
+                message,
+              },
+            }
+          : null,
       }));
       emitConsoleLiveEvent(consoleLiveEmitter, 'push', () => ({
         partitionId,