@syncular/server-hono 0.0.4-25 → 0.0.6-100

package/dist/routes.d.ts

@@ -6,7 +6,7 @@
  * - GET  /snapshot-chunks/:chunkId (download encoded snapshot chunks)
  * - GET  /realtime (optional WebSocket "wake up" notifications)
  */
-import type { ServerSyncDialect, ServerTableHandler, SnapshotChunkStorage, SyncCoreDb, SyncRealtimeBroadcaster } from '@syncular/server';
+import type { ScopeCacheBackend, ServerSyncDialect, ServerTableHandler, SnapshotChunkStorage, SqlFamily, SyncCoreDb, SyncRealtimeBroadcaster, SyncServerAuth } from '@syncular/server';
 import { type CompactOptions, type PruneOptions } from '@syncular/server';
 import type { Context } from 'hono';
 import { Hono } from 'hono';
@@ -14,9 +14,7 @@ import type { UpgradeWebSocket } from 'hono/ws';
 import { type Kysely } from 'kysely';
 import { type SyncRateLimitConfig } from './rate-limit';
 import { WebSocketConnectionManager } from './ws';
-export interface SyncAuthResult {
-    actorId: string;
-    partitionId?: string;
+export interface SyncAuthResult extends SyncServerAuth {
 }
 /**
  * WebSocket configuration for realtime sync.
@@ -67,6 +65,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.
@@ -106,11 +120,11 @@ export interface SyncRoutesConfigWithRateLimit {
         instanceId?: string;
     };
 }
-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;
     /**
@@ -119,6 +133,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`.
@@ -130,8 +149,13 @@ 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>;
 }
-export declare function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(options: CreateSyncRoutesOptions<DB>): Hono;
+export declare function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb, Auth extends SyncAuthResult = SyncAuthResult, F extends SqlFamily = SqlFamily>(options: CreateSyncRoutesOptions<DB, Auth, F>): Hono;
 export declare function getSyncWebSocketConnectionManager(routes: Hono): WebSocketConnectionManager | undefined;
 export declare function getSyncRealtimeUnsubscribe(routes: Hono): (() => void) | undefined;
 //# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"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"}

package/dist/routes.js

@@ -6,8 +6,8 @@
  * - GET  /snapshot-chunks/:chunkId (download encoded snapshot chunks)
  * - GET  /realtime (optional WebSocket "wake up" notifications)
  */
-import { captureSyncException, createSyncTimer, ErrorResponseSchema, logSyncEvent, SyncCombinedRequestSchema, SyncCombinedResponseSchema, SyncPushRequestSchema, } from '@syncular/core';
-import { InvalidSubscriptionScopeError, pull, pushCommit, readSnapshotChunk, recordClientCursor, TableRegistry, } from '@syncular/server';
+import { captureSyncException, countSyncMetric, createSyncTimer, distributionSyncMetric, ErrorResponseSchema, logSyncEvent, SyncCombinedRequestSchema, SyncCombinedResponseSchema, SyncPushRequestSchema, } from '@syncular/core';
+import { createServerHandlerCollection, InvalidSubscriptionScopeError, pull, pushCommit, readSnapshotChunk, recordClientCursor, } from '@syncular/server';
 import { Hono } from 'hono';
 import { describeRoute, resolver, validator as zValidator } from 'hono-openapi';
 import { sql, } from 'kysely';
@@ -25,7 +25,7 @@ const realtimeUnsubscribeMap = new WeakMap();
 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;
 function createOpaqueId(prefix) {
     const randomPart = typeof crypto !== 'undefined' && 'randomUUID' in crypto
         ? crypto.randomUUID()
@@ -64,6 +64,15 @@ function parseSentryTraceHeader(sentryTrace) {
         return null;
     return { traceId, spanId };
 }
+function readPositiveInteger(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return fallback;
+    }
+    if (value <= 0) {
+        return fallback;
+    }
+    return Math.floor(value);
+}
 function readTraceContext(c) {
     const traceparent = parseW3cTraceparent(c.req.header('traceparent'));
     if (traceparent)
@@ -170,16 +179,16 @@ function countPullRows(response) {
         return totalRows + commitRows + snapshotRows;
     }, 0);
 }
-function encodePayloadSnapshot(value) {
+function encodePayloadSnapshot(value, maxBytes) {
     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 {
@@ -208,10 +217,7 @@ export function createSyncRoutes(options) {
         });
         return c.text('Internal Server Error', 500);
     });
-    const handlerRegistry = new TableRegistry();
-    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;
@@ -221,6 +227,21 @@ export function createSyncRoutes(options) {
     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)
     // -------------------------------------------------------------------------
@@ -275,8 +296,8 @@ export function createSyncRoutes(options) {
             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
@@ -325,7 +346,9 @@ export function createSyncRoutes(options) {
         if (!shouldRecordRequestEvents)
             return;
         const resolvedEvent = typeof event === 'function' ? event() : event;
-        void recordRequestEvent(resolvedEvent).catch((error) => {
+        void consoleSchemaReady
+            .then(() => recordRequestEvent(resolvedEvent))
+            .catch((error) => {
             logAsyncFailureOnce('sync.request_event_record_failed', {
                 event: 'sync.request_event_record_failed',
                 userId: resolvedEvent.actorId,
@@ -463,8 +486,7 @@ export function createSyncRoutes(options) {
                 db: options.db,
                 dialect: options.dialect,
                 handlers: handlerRegistry,
-                actorId: auth.actorId,
-                partitionId,
+                auth,
                 request: {
                     clientId,
                     clientCommitId: pushBody.clientCommitId,
@@ -499,15 +521,17 @@ export function createSyncRoutes(options) {
                 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,
@@ -610,10 +634,10 @@ export function createSyncRoutes(options) {
                     db: options.db,
                     dialect: options.dialect,
                     handlers: handlerRegistry,
-                    actorId: auth.actorId,
-                    partitionId,
+                    auth,
                     request,
                     chunkStorage: options.chunkStorage,
+                    scopeCache: options.scopeCache,
                 });
             }
             catch (err) {
@@ -663,7 +687,7 @@ export function createSyncRoutes(options) {
                 const scopesSummary = shouldRecordRequestEvents
                     ? summarizeScopeValues(pullResult.effectiveScopes)
                     : null;
-                const payloadSnapshot = shouldRecordRequestEvents
+                const payloadSnapshot = shouldCaptureRequestPayloadSnapshots
                     ? {
                         request: {
                             clientId,
@@ -887,6 +911,31 @@ export function createSyncRoutes(options) {
             logSyncEvent({ event: 'sync.realtime.connect', userId: auth.actorId });
             let unregister = null;
             let connRef = null;
+            const connectionCountBeforeUpgrade = wsConnectionManager.getConnectionCount(clientId);
+            let sessionStartedAtMs = null;
+            let sessionEnded = false;
+            const finishRealtimeSession = (reason) => {
+                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) {
                 return c.json({ error: 'WEBSOCKET_NOT_CONFIGURED' }, 500);
@@ -899,6 +948,20 @@ export function createSyncRoutes(options) {
                         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();
                     emitConsoleLiveEvent(consoleLiveEmitter, 'client_update', () => ({
@@ -914,6 +977,7 @@ export function createSyncRoutes(options) {
                     unregister?.();
                     unregister = null;
                     connRef = null;
+                    finishRealtimeSession('closed');
                     logSyncEvent({
                         event: 'sync.realtime.disconnect',
                         userId: auth.actorId,
@@ -929,6 +993,7 @@ export function createSyncRoutes(options) {
                     unregister?.();
                     unregister = null;
                     connRef = null;
+                    finishRealtimeSession('error');
                     logSyncEvent({
                         event: 'sync.realtime.disconnect',
                         userId: auth.actorId,
@@ -949,7 +1014,7 @@ export function createSyncRoutes(options) {
                         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;
                         }
                         if (msg.type !== 'presence' || !msg.scopeKey)
@@ -1018,7 +1083,9 @@ export function createSyncRoutes(options) {
             return;
         wsConnectionManager.notifyScopeKeys(scopeKeys, commitSeq);
     }
-    async function handleWsPush(msg, conn, actorId, partitionId, clientId) {
+    async function handleWsPush(msg, conn, auth, clientId) {
+        const actorId = auth.actorId;
+        const partitionId = auth.partitionId ?? 'default';
         const requestId = typeof msg.requestId === 'string' ? msg.requestId : '';
         if (!requestId)
             return;
@@ -1053,14 +1120,16 @@ export function createSyncRoutes(options) {
                     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,
@@ -1110,19 +1179,21 @@ export function createSyncRoutes(options) {
                     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,
@@ -1145,8 +1216,7 @@ export function createSyncRoutes(options) {
                 db: options.db,
                 dialect: options.dialect,
                 handlers: handlerRegistry,
-                actorId,
-                partitionId,
+                auth,
                 request: {
                     clientId,
                     clientCommitId: parsed.data.clientCommitId,
@@ -1181,15 +1251,17 @@ export function createSyncRoutes(options) {
                 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,
@@ -1207,6 +1279,15 @@ export function createSyncRoutes(options) {
                 operationCount: pushOps.length,
                 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 &&
                 pushed.response.ok === true &&
@@ -1283,15 +1364,17 @@ export function createSyncRoutes(options) {
                 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,