@syncular/server-hono 0.0.1-100

package/dist/routes.js

@@ -0,0 +1,884 @@
+/**
+ * @syncular/server-hono - Sync routes for Hono
+ *
+ * Provides:
+ * - POST /      (combined push + pull in one round-trip)
+ * - 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 { Hono } from 'hono';
+import { describeRoute, resolver, validator as zValidator } from 'hono-openapi';
+import { sql, } from 'kysely';
+import { z } from 'zod';
+import { createRateLimiter, DEFAULT_SYNC_RATE_LIMITS, } from './rate-limit.js';
+import { createWebSocketConnection, WebSocketConnectionManager, } from './ws.js';
+/**
+ * WeakMaps for storing Hono-instance-specific data without augmenting the type.
+ */
+const wsConnectionManagerMap = new WeakMap();
+const realtimeUnsubscribeMap = new WeakMap();
+// ============================================================================
+// Route Schemas
+// ============================================================================
+const snapshotChunkParamsSchema = z.object({
+    chunkId: z.string().min(1),
+});
+export function createSyncRoutes(options) {
+    const routes = new Hono();
+    routes.onError((error, c) => {
+        captureSyncException(error, {
+            event: 'sync.route.unhandled',
+            method: c.req.method,
+            path: c.req.path,
+        });
+        return c.text('Internal Server Error', 500);
+    });
+    const handlerRegistry = new TableRegistry();
+    for (const handler of options.handlers) {
+        handlerRegistry.register(handler);
+    }
+    const config = options.sync ?? {};
+    const maxPullLimitCommits = config.maxPullLimitCommits ?? 100;
+    const maxSubscriptionsPerPull = config.maxSubscriptionsPerPull ?? 200;
+    const maxPullLimitSnapshotRows = config.maxPullLimitSnapshotRows ?? 5000;
+    const maxPullMaxSnapshotPages = config.maxPullMaxSnapshotPages ?? 10;
+    const maxOperationsPerPush = config.maxOperationsPerPush ?? 200;
+    // -------------------------------------------------------------------------
+    // Optional WebSocket manager (scope-key based wake-ups)
+    // -------------------------------------------------------------------------
+    const websocketConfig = config.websocket;
+    if (websocketConfig?.enabled && !websocketConfig.upgradeWebSocket) {
+        throw new Error('sync.websocket.enabled requires sync.websocket.upgradeWebSocket');
+    }
+    const wsConnectionManager = websocketConfig?.enabled
+        ? (options.wsConnectionManager ??
+            new WebSocketConnectionManager({
+                heartbeatIntervalMs: websocketConfig.heartbeatIntervalMs ?? 30_000,
+            }))
+        : null;
+    if (wsConnectionManager) {
+        wsConnectionManagerMap.set(routes, wsConnectionManager);
+    }
+    // -------------------------------------------------------------------------
+    // Multi-instance realtime broadcaster (optional)
+    // -------------------------------------------------------------------------
+    const realtimeBroadcaster = config.realtime?.broadcaster ?? null;
+    const instanceId = config.realtime?.instanceId ??
+        (typeof crypto !== 'undefined' && 'randomUUID' in crypto
+            ? crypto.randomUUID()
+            : `${Date.now()}-${Math.random().toString(16).slice(2)}`);
+    const loggedAsyncFailureKeys = new Set();
+    const logAsyncFailureOnce = (key, event) => {
+        if (loggedAsyncFailureKeys.has(key))
+            return;
+        loggedAsyncFailureKeys.add(key);
+        logSyncEvent(event);
+    };
+    if (wsConnectionManager && realtimeBroadcaster) {
+        const unsubscribe = realtimeBroadcaster.subscribe((event) => {
+            void handleRealtimeEvent(event).catch((error) => {
+                logAsyncFailureOnce('sync.realtime.broadcast_delivery_failed', {
+                    event: 'sync.realtime.broadcast_delivery_failed',
+                    error: error instanceof Error ? error.message : String(error),
+                    sourceEventType: event.type,
+                });
+            });
+        });
+        realtimeUnsubscribeMap.set(routes, unsubscribe);
+    }
+    const recordRequestEvent = async (event) => {
+        const tablesValue = options.dialect.arrayToDb(event.tables ?? []);
+        await sql `
+      INSERT INTO sync_request_events (
+        event_type, actor_id, client_id, status_code, outcome,
+        duration_ms, commit_seq, operation_count, row_count,
+        tables, error_message, transport_path
+      ) VALUES (
+        ${event.eventType}, ${event.actorId}, ${event.clientId},
+        ${event.statusCode}, ${event.outcome}, ${event.durationMs},
+        ${event.commitSeq ?? null}, ${event.operationCount ?? null},
+        ${event.rowCount ?? null}, ${tablesValue}, ${event.errorMessage ?? null},
+        ${event.transportPath}
+      )
+    `.execute(options.db);
+    };
+    const recordRequestEventInBackground = (event) => {
+        void recordRequestEvent(event).catch((error) => {
+            logAsyncFailureOnce('sync.request_event_record_failed', {
+                event: 'sync.request_event_record_failed',
+                userId: event.actorId,
+                clientId: event.clientId,
+                requestEventType: event.eventType,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+    };
+    const authCache = new WeakMap();
+    const getAuth = (c) => {
+        const cached = authCache.get(c);
+        if (cached)
+            return cached;
+        const pending = options.authenticate(c);
+        authCache.set(c, pending);
+        return pending;
+    };
+    // -------------------------------------------------------------------------
+    // Rate limiting (optional)
+    // -------------------------------------------------------------------------
+    const rateLimitConfig = config.rateLimit;
+    if (rateLimitConfig !== false) {
+        const pullRateLimit = rateLimitConfig?.pull ?? DEFAULT_SYNC_RATE_LIMITS.pull;
+        const pushRateLimit = rateLimitConfig?.push ?? DEFAULT_SYNC_RATE_LIMITS.push;
+        const createAuthBasedRateLimiter = (limitConfig) => {
+            if (limitConfig === false || !limitConfig)
+                return null;
+            return createRateLimiter({
+                ...limitConfig,
+                keyGenerator: async (c) => {
+                    const auth = await getAuth(c);
+                    return auth?.actorId ?? null;
+                },
+            });
+        };
+        const pullLimiter = createAuthBasedRateLimiter(pullRateLimit);
+        const pushLimiter = createAuthBasedRateLimiter(pushRateLimit);
+        const syncRateLimiter = async (c, next) => {
+            if (!pullLimiter && !pushLimiter)
+                return next();
+            let shouldApplyPull = pullLimiter !== null;
+            let shouldApplyPush = pushLimiter !== null;
+            if (pullLimiter && pushLimiter && c.req.method === 'POST') {
+                try {
+                    const parsed = await c.req.raw.clone().json();
+                    if (parsed !== null && typeof parsed === 'object') {
+                        shouldApplyPull = Reflect.get(parsed, 'pull') !== undefined;
+                        shouldApplyPush = Reflect.get(parsed, 'push') !== undefined;
+                    }
+                }
+                catch {
+                    // Keep default behavior and apply both limiters when payload parsing fails.
+                }
+            }
+            if (pullLimiter && shouldApplyPull && pushLimiter && shouldApplyPush) {
+                return pullLimiter(c, async () => {
+                    const pushResult = await pushLimiter(c, next);
+                    if (pushResult instanceof Response) {
+                        c.res = pushResult;
+                    }
+                });
+            }
+            if (pullLimiter && shouldApplyPull) {
+                return pullLimiter(c, next);
+            }
+            if (pushLimiter && shouldApplyPush) {
+                return pushLimiter(c, next);
+            }
+            return next();
+        };
+        routes.use('/', syncRateLimiter);
+    }
+    // -------------------------------------------------------------------------
+    // GET /health
+    // -------------------------------------------------------------------------
+    routes.get('/health', (c) => {
+        return c.json({
+            status: 'healthy',
+            timestamp: new Date().toISOString(),
+        });
+    });
+    // -------------------------------------------------------------------------
+    // POST /  (combined push + pull in one round-trip)
+    // -------------------------------------------------------------------------
+    routes.post('/', describeRoute({
+        tags: ['sync'],
+        summary: 'Combined push and pull',
+        description: 'Perform push and/or pull in a single request to reduce round-trips',
+        responses: {
+            200: {
+                description: 'Combined sync response',
+                content: {
+                    'application/json': {
+                        schema: resolver(SyncCombinedResponseSchema),
+                    },
+                },
+            },
+            400: {
+                description: 'Invalid request',
+                content: {
+                    'application/json': { schema: resolver(ErrorResponseSchema) },
+                },
+            },
+            401: {
+                description: 'Unauthenticated',
+                content: {
+                    'application/json': { schema: resolver(ErrorResponseSchema) },
+                },
+            },
+        },
+    }), zValidator('json', SyncCombinedRequestSchema), async (c) => {
+        const auth = await getAuth(c);
+        if (!auth)
+            return c.json({ error: 'UNAUTHENTICATED' }, 401);
+        const partitionId = auth.partitionId ?? 'default';
+        const body = c.req.valid('json');
+        const clientId = body.clientId;
+        let pushResponse;
+        let pullResponse;
+        // --- Push phase ---
+        if (body.push) {
+            const pushOps = body.push.operations ?? [];
+            if (pushOps.length > maxOperationsPerPush) {
+                return c.json({
+                    error: 'TOO_MANY_OPERATIONS',
+                    message: `Maximum ${maxOperationsPerPush} operations per push`,
+                }, 400);
+            }
+            const timer = createSyncTimer();
+            const pushed = await pushCommit({
+                db: options.db,
+                dialect: options.dialect,
+                shapes: handlerRegistry,
+                actorId: auth.actorId,
+                partitionId,
+                request: {
+                    clientId,
+                    clientCommitId: body.push.clientCommitId,
+                    operations: body.push.operations,
+                    schemaVersion: body.push.schemaVersion,
+                },
+            });
+            const pushDurationMs = timer();
+            logSyncEvent({
+                event: 'sync.push',
+                userId: auth.actorId,
+                durationMs: pushDurationMs,
+                operationCount: pushOps.length,
+                status: pushed.response.status,
+                commitSeq: pushed.response.commitSeq,
+            });
+            recordRequestEventInBackground({
+                eventType: 'push',
+                actorId: auth.actorId,
+                clientId,
+                transportPath: readTransportPath(c),
+                statusCode: 200,
+                outcome: pushed.response.status,
+                durationMs: pushDurationMs,
+                commitSeq: pushed.response.commitSeq,
+                operationCount: pushOps.length,
+                tables: pushed.affectedTables,
+            });
+            // WS notifications
+            if (wsConnectionManager &&
+                pushed.response.ok === true &&
+                pushed.response.status === 'applied' &&
+                typeof pushed.response.commitSeq === 'number') {
+                const scopeKeys = applyPartitionToScopeKeys(partitionId, pushed.scopeKeys);
+                if (scopeKeys.length > 0) {
+                    wsConnectionManager.notifyScopeKeys(scopeKeys, pushed.response.commitSeq, {
+                        excludeClientIds: [clientId],
+                        changes: pushed.emittedChanges,
+                    });
+                    if (realtimeBroadcaster) {
+                        realtimeBroadcaster
+                            .publish({
+                            type: 'commit',
+                            commitSeq: pushed.response.commitSeq,
+                            partitionId,
+                            scopeKeys,
+                            sourceInstanceId: instanceId,
+                        })
+                            .catch((error) => {
+                            logAsyncFailureOnce('sync.realtime.broadcast_publish_failed', {
+                                event: 'sync.realtime.broadcast_publish_failed',
+                                userId: auth.actorId,
+                                clientId,
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                        });
+                    }
+                }
+            }
+            pushResponse = pushed.response;
+        }
+        // --- Pull phase ---
+        if (body.pull) {
+            if (body.pull.subscriptions.length > maxSubscriptionsPerPull) {
+                return c.json({
+                    error: 'INVALID_REQUEST',
+                    message: `Too many subscriptions (max ${maxSubscriptionsPerPull})`,
+                }, 400);
+            }
+            const seenSubscriptionIds = new Set();
+            for (const sub of body.pull.subscriptions) {
+                const id = sub.id;
+                if (seenSubscriptionIds.has(id)) {
+                    return c.json({
+                        error: 'INVALID_REQUEST',
+                        message: `Duplicate subscription id: ${id}`,
+                    }, 400);
+                }
+                seenSubscriptionIds.add(id);
+            }
+            const request = {
+                clientId,
+                limitCommits: clampInt(body.pull.limitCommits ?? 50, 1, maxPullLimitCommits),
+                limitSnapshotRows: clampInt(body.pull.limitSnapshotRows ?? 1000, 1, maxPullLimitSnapshotRows),
+                maxSnapshotPages: clampInt(body.pull.maxSnapshotPages ?? 1, 1, maxPullMaxSnapshotPages),
+                dedupeRows: body.pull.dedupeRows === true,
+                subscriptions: body.pull.subscriptions.map((sub) => ({
+                    id: sub.id,
+                    shape: sub.shape,
+                    scopes: (sub.scopes ?? {}),
+                    params: sub.params,
+                    cursor: Math.max(-1, sub.cursor),
+                    bootstrapState: sub.bootstrapState ?? null,
+                })),
+            };
+            const timer = createSyncTimer();
+            let pullResult;
+            try {
+                pullResult = await pull({
+                    db: options.db,
+                    dialect: options.dialect,
+                    shapes: handlerRegistry,
+                    actorId: auth.actorId,
+                    partitionId,
+                    request,
+                    chunkStorage: options.chunkStorage,
+                });
+            }
+            catch (err) {
+                if (err instanceof InvalidSubscriptionScopeError) {
+                    return c.json({ error: 'INVALID_SUBSCRIPTION', message: err.message }, 400);
+                }
+                throw err;
+            }
+            // Fire-and-forget bookkeeping
+            void recordClientCursor(options.db, options.dialect, {
+                partitionId,
+                clientId,
+                actorId: auth.actorId,
+                cursor: pullResult.clientCursor,
+                effectiveScopes: pullResult.effectiveScopes,
+            }).catch((error) => {
+                logAsyncFailureOnce('sync.client_cursor_record_failed', {
+                    event: 'sync.client_cursor_record_failed',
+                    userId: auth.actorId,
+                    clientId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+            wsConnectionManager?.updateClientScopeKeys(clientId, applyPartitionToScopeKeys(partitionId, scopeValuesToScopeKeys(pullResult.effectiveScopes)));
+            const pullDurationMs = timer();
+            logSyncEvent({
+                event: 'sync.pull',
+                userId: auth.actorId,
+                durationMs: pullDurationMs,
+                subscriptionCount: pullResult.response.subscriptions.length,
+                clientCursor: pullResult.clientCursor,
+            });
+            recordRequestEventInBackground({
+                eventType: 'pull',
+                actorId: auth.actorId,
+                clientId,
+                transportPath: readTransportPath(c),
+                statusCode: 200,
+                outcome: 'applied',
+                durationMs: pullDurationMs,
+            });
+            pullResponse = pullResult.response;
+        }
+        return c.json({
+            ok: true,
+            ...(pushResponse ? { push: pushResponse } : {}),
+            ...(pullResponse ? { pull: pullResponse } : {}),
+        }, 200);
+    });
+    // -------------------------------------------------------------------------
+    // GET /snapshot-chunks/:chunkId
+    // -------------------------------------------------------------------------
+    routes.get('/snapshot-chunks/:chunkId', describeRoute({
+        tags: ['sync'],
+        summary: 'Download snapshot chunk',
+        description: 'Download an encoded bootstrap snapshot chunk',
+        responses: {
+            200: {
+                description: 'Snapshot chunk data (gzip-compressed framed JSON rows)',
+                content: {
+                    'application/octet-stream': {
+                        schema: resolver(z.string()),
+                    },
+                },
+            },
+            304: {
+                description: 'Not modified (cached)',
+            },
+            401: {
+                description: 'Unauthenticated',
+                content: {
+                    'application/json': { schema: resolver(ErrorResponseSchema) },
+                },
+            },
+            403: {
+                description: 'Forbidden',
+                content: {
+                    'application/json': { schema: resolver(ErrorResponseSchema) },
+                },
+            },
+            404: {
+                description: 'Not found',
+                content: {
+                    'application/json': { schema: resolver(ErrorResponseSchema) },
+                },
+            },
+        },
+    }), zValidator('param', snapshotChunkParamsSchema), async (c) => {
+        const auth = await getAuth(c);
+        if (!auth)
+            return c.json({ error: 'UNAUTHENTICATED' }, 401);
+        const partitionId = auth.partitionId ?? 'default';
+        const { chunkId } = c.req.valid('param');
+        const chunk = await readSnapshotChunk(options.db, chunkId, {
+            chunkStorage: options.chunkStorage,
+        });
+        if (!chunk)
+            return c.json({ error: 'NOT_FOUND' }, 404);
+        if (chunk.partitionId !== partitionId) {
+            return c.json({ error: 'FORBIDDEN' }, 403);
+        }
+        const nowIso = new Date().toISOString();
+        if (chunk.expiresAt <= nowIso) {
+            return c.json({ error: 'NOT_FOUND' }, 404);
+        }
+        // Note: Snapshot chunks are created during authorized pull requests
+        // and have opaque IDs that expire. Additional authorization is handled
+        // at the pull layer via shape-level resolveScopes.
+        const etag = `"sha256:${chunk.sha256}"`;
+        const ifNoneMatch = c.req.header('if-none-match');
+        if (ifNoneMatch && ifNoneMatch === etag) {
+            return new Response(null, {
+                status: 304,
+                headers: {
+                    ETag: etag,
+                    'Cache-Control': 'private, max-age=0',
+                    Vary: 'Authorization',
+                },
+            });
+        }
+        return new Response(chunk.body, {
+            status: 200,
+            headers: {
+                'Content-Type': 'application/octet-stream',
+                'Content-Encoding': 'gzip',
+                'Content-Length': String(chunk.byteLength),
+                ETag: etag,
+                'Cache-Control': 'private, max-age=0',
+                Vary: 'Authorization',
+                'X-Sync-Chunk-Id': chunk.chunkId,
+                'X-Sync-Chunk-Sha256': chunk.sha256,
+                'X-Sync-Chunk-Encoding': chunk.encoding,
+                'X-Sync-Chunk-Compression': chunk.compression,
+            },
+        });
+    });
+    // -------------------------------------------------------------------------
+    // GET /realtime (optional WebSocket wake-ups)
+    // -------------------------------------------------------------------------
+    if (wsConnectionManager && websocketConfig?.enabled) {
+        routes.get('/realtime', async (c) => {
+            const auth = await getAuth(c);
+            if (!auth)
+                return c.json({ error: 'UNAUTHENTICATED' }, 401);
+            const partitionId = auth.partitionId ?? 'default';
+            const clientId = c.req.query('clientId');
+            if (!clientId || typeof clientId !== 'string') {
+                return c.json({
+                    error: 'INVALID_REQUEST',
+                    message: 'clientId query param is required',
+                }, 400);
+            }
+            const realtimeTransportPath = readTransportPath(c, c.req.query('transportPath'));
+            // Load last-known effective scopes for this client (best-effort).
+            // Keeps /realtime lightweight and avoids sending large subscription payloads over the URL.
+            let initialScopeKeys = [];
+            try {
+                const cursorsQ = options.db.selectFrom('sync_client_cursors');
+                const row = await cursorsQ
+                    .selectAll()
+                    .where(sql `partition_id = ${partitionId}`)
+                    .where(sql `client_id = ${clientId}`)
+                    .executeTakeFirst();
+                if (row && row.actor_id !== auth.actorId) {
+                    return c.json({ error: 'FORBIDDEN' }, 403);
+                }
+                const raw = row?.effective_scopes;
+                let parsed = raw;
+                if (typeof raw === 'string') {
+                    try {
+                        parsed = JSON.parse(raw);
+                    }
+                    catch {
+                        parsed = null;
+                    }
+                }
+                initialScopeKeys = applyPartitionToScopeKeys(partitionId, scopeValuesToScopeKeys(parsed));
+            }
+            catch {
+                // ignore; realtime is best-effort
+            }
+            const maxConnectionsTotal = websocketConfig.maxConnectionsTotal ?? 5000;
+            const maxConnectionsPerClient = websocketConfig.maxConnectionsPerClient ?? 3;
+            if (maxConnectionsTotal > 0 &&
+                wsConnectionManager.getTotalConnections() >= maxConnectionsTotal) {
+                logSyncEvent({
+                    event: 'sync.realtime.rejected',
+                    userId: auth.actorId,
+                    reason: 'max_total',
+                });
+                return c.json({ error: 'WEBSOCKET_CONNECTION_LIMIT_TOTAL' }, 429);
+            }
+            if (maxConnectionsPerClient > 0 &&
+                wsConnectionManager.getConnectionCount(clientId) >=
+                    maxConnectionsPerClient) {
+                logSyncEvent({
+                    event: 'sync.realtime.rejected',
+                    userId: auth.actorId,
+                    reason: 'max_per_client',
+                });
+                return c.json({ error: 'WEBSOCKET_CONNECTION_LIMIT_CLIENT' }, 429);
+            }
+            logSyncEvent({ event: 'sync.realtime.connect', userId: auth.actorId });
+            let unregister = null;
+            let connRef = null;
+            const upgradeWebSocket = websocketConfig.upgradeWebSocket;
+            if (!upgradeWebSocket) {
+                return c.json({ error: 'WEBSOCKET_NOT_CONFIGURED' }, 500);
+            }
+            return upgradeWebSocket(c, {
+                onOpen(_evt, ws) {
+                    const conn = createWebSocketConnection(ws, {
+                        actorId: auth.actorId,
+                        clientId,
+                        transportPath: realtimeTransportPath,
+                    });
+                    connRef = conn;
+                    unregister = wsConnectionManager.register(conn, initialScopeKeys);
+                    conn.sendHeartbeat();
+                },
+                onClose(_evt, _ws) {
+                    unregister?.();
+                    unregister = null;
+                    connRef = null;
+                    logSyncEvent({
+                        event: 'sync.realtime.disconnect',
+                        userId: auth.actorId,
+                    });
+                },
+                onError(_evt, _ws) {
+                    unregister?.();
+                    unregister = null;
+                    connRef = null;
+                    logSyncEvent({
+                        event: 'sync.realtime.disconnect',
+                        userId: auth.actorId,
+                    });
+                },
+                onMessage(evt, _ws) {
+                    if (!connRef)
+                        return;
+                    try {
+                        const raw = typeof evt.data === 'string' ? evt.data : String(evt.data);
+                        const msg = JSON.parse(raw);
+                        if (!msg || typeof msg !== 'object')
+                            return;
+                        if (msg.type === 'push') {
+                            void handleWsPush(msg, connRef, auth.actorId, partitionId, clientId);
+                            return;
+                        }
+                        if (msg.type !== 'presence' || !msg.scopeKey)
+                            return;
+                        const scopeKey = normalizeScopeKeyForPartition(partitionId, String(msg.scopeKey));
+                        if (!scopeKey)
+                            return;
+                        switch (msg.action) {
+                            case 'join':
+                                if (!wsConnectionManager.joinPresence(clientId, scopeKey, msg.metadata)) {
+                                    logSyncEvent({
+                                        event: 'sync.realtime.presence.rejected',
+                                        userId: auth.actorId,
+                                        reason: 'scope_not_authorized',
+                                        scopeKey,
+                                    });
+                                    return;
+                                }
+                                // Send presence snapshot back to the joining client
+                                {
+                                    const entries = wsConnectionManager.getPresence(scopeKey);
+                                    connRef.sendPresence({
+                                        action: 'snapshot',
+                                        scopeKey,
+                                        entries,
+                                    });
+                                }
+                                break;
+                            case 'leave':
+                                wsConnectionManager.leavePresence(clientId, scopeKey);
+                                break;
+                            case 'update':
+                                if (!wsConnectionManager.updatePresenceMetadata(clientId, scopeKey, msg.metadata ?? {}) &&
+                                    !wsConnectionManager.isClientSubscribedToScopeKey(clientId, scopeKey)) {
+                                    logSyncEvent({
+                                        event: 'sync.realtime.presence.rejected',
+                                        userId: auth.actorId,
+                                        reason: 'scope_not_authorized',
+                                        scopeKey,
+                                    });
+                                }
+                                break;
+                        }
+                    }
+                    catch {
+                        // Ignore malformed messages
+                    }
+                },
+            });
+        });
+    }
+    return routes;
+    async function handleRealtimeEvent(event) {
+        if (!wsConnectionManager)
+            return;
+        if (event.type !== 'commit')
+            return;
+        if (event.sourceInstanceId && event.sourceInstanceId === instanceId)
+            return;
+        const commitSeq = event.commitSeq;
+        const partitionId = event.partitionId ?? 'default';
+        const scopeKeys = event.scopeKeys && event.scopeKeys.length > 0
+            ? event.scopeKeys
+            : await readCommitScopeKeys(options.db, commitSeq, partitionId);
+        if (scopeKeys.length === 0)
+            return;
+        wsConnectionManager.notifyScopeKeys(scopeKeys, commitSeq);
+    }
+    async function handleWsPush(msg, conn, actorId, partitionId, clientId) {
+        const requestId = typeof msg.requestId === 'string' ? msg.requestId : '';
+        if (!requestId)
+            return;
+        try {
+            // Validate the push payload
+            const parsed = SyncPushRequestSchema.omit({ clientId: true }).safeParse(msg);
+            if (!parsed.success) {
+                conn.sendPushResponse({
+                    requestId,
+                    ok: false,
+                    status: 'rejected',
+                    results: [
+                        { opIndex: 0, status: 'error', error: 'Invalid push payload' },
+                    ],
+                });
+                return;
+            }
+            const pushOps = parsed.data.operations ?? [];
+            if (pushOps.length > maxOperationsPerPush) {
+                conn.sendPushResponse({
+                    requestId,
+                    ok: false,
+                    status: 'rejected',
+                    results: [
+                        {
+                            opIndex: 0,
+                            status: 'error',
+                            error: `Maximum ${maxOperationsPerPush} operations per push`,
+                        },
+                    ],
+                });
+                return;
+            }
+            const timer = createSyncTimer();
+            const pushed = await pushCommit({
+                db: options.db,
+                dialect: options.dialect,
+                shapes: handlerRegistry,
+                actorId,
+                partitionId,
+                request: {
+                    clientId,
+                    clientCommitId: parsed.data.clientCommitId,
+                    operations: parsed.data.operations,
+                    schemaVersion: parsed.data.schemaVersion,
+                },
+            });
+            const pushDurationMs = timer();
+            logSyncEvent({
+                event: 'sync.push',
+                userId: actorId,
+                durationMs: pushDurationMs,
+                operationCount: pushOps.length,
+                status: pushed.response.status,
+                commitSeq: pushed.response.commitSeq,
+            });
+            recordRequestEventInBackground({
+                eventType: 'push',
+                actorId,
+                clientId,
+                transportPath: conn.transportPath,
+                statusCode: 200,
+                outcome: pushed.response.status,
+                durationMs: pushDurationMs,
+                commitSeq: pushed.response.commitSeq,
+                operationCount: pushOps.length,
+                tables: pushed.affectedTables,
+            });
+            // WS notifications to other clients
+            if (wsConnectionManager &&
+                pushed.response.ok === true &&
+                pushed.response.status === 'applied' &&
+                typeof pushed.response.commitSeq === 'number') {
+                const scopeKeys = applyPartitionToScopeKeys(partitionId, pushed.scopeKeys);
+                if (scopeKeys.length > 0) {
+                    wsConnectionManager.notifyScopeKeys(scopeKeys, pushed.response.commitSeq, {
+                        excludeClientIds: [clientId],
+                        changes: pushed.emittedChanges,
+                    });
+                    if (realtimeBroadcaster) {
+                        realtimeBroadcaster
+                            .publish({
+                            type: 'commit',
+                            commitSeq: pushed.response.commitSeq,
+                            partitionId,
+                            scopeKeys,
+                            sourceInstanceId: instanceId,
+                        })
+                            .catch((error) => {
+                            logAsyncFailureOnce('sync.realtime.broadcast_publish_failed', {
+                                event: 'sync.realtime.broadcast_publish_failed',
+                                userId: actorId,
+                                clientId,
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                        });
+                    }
+                }
+            }
+            conn.sendPushResponse({
+                requestId,
+                ok: pushed.response.ok,
+                status: pushed.response.status,
+                commitSeq: pushed.response.commitSeq,
+                results: pushed.response.results,
+            });
+        }
+        catch (err) {
+            captureSyncException(err, {
+                event: 'sync.realtime.push_failed',
+                requestId,
+                clientId,
+                actorId,
+                partitionId,
+            });
+            const message = err instanceof Error ? err.message : 'Internal server error';
+            conn.sendPushResponse({
+                requestId,
+                ok: false,
+                status: 'rejected',
+                results: [{ opIndex: 0, status: 'error', error: message }],
+            });
+        }
+    }
+}
+export function getSyncWebSocketConnectionManager(routes) {
+    return wsConnectionManagerMap.get(routes);
+}
+export function getSyncRealtimeUnsubscribe(routes) {
+    return realtimeUnsubscribeMap.get(routes);
+}
+function clampInt(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+function readTransportPath(c, queryValue) {
+    if (queryValue === 'relay' || queryValue === 'direct') {
+        return queryValue;
+    }
+    const headerValue = c.req.header('x-syncular-transport-path');
+    if (headerValue === 'relay' || headerValue === 'direct') {
+        return headerValue;
+    }
+    return 'direct';
+}
+function scopeValuesToScopeKeys(scopes) {
+    if (!scopes || typeof scopes !== 'object')
+        return [];
+    const scopeKeys = new Set();
+    for (const [key, value] of Object.entries(scopes)) {
+        if (!value)
+            continue;
+        const prefix = key.replace(/_id$/, '');
+        if (Array.isArray(value)) {
+            for (const v of value) {
+                if (typeof v !== 'string')
+                    continue;
+                if (!v)
+                    continue;
+                scopeKeys.add(`${prefix}:${v}`);
+            }
+            continue;
+        }
+        if (typeof value === 'string') {
+            if (!value)
+                continue;
+            scopeKeys.add(`${prefix}:${value}`);
+            continue;
+        }
+        // Best-effort: stringify scalars.
+        if (typeof value === 'number' || typeof value === 'bigint') {
+            scopeKeys.add(`${prefix}:${String(value)}`);
+        }
+    }
+    return Array.from(scopeKeys);
+}
+function partitionScopeKey(partitionId, scopeKey) {
+    return `${partitionId}::${scopeKey}`;
+}
+function applyPartitionToScopeKeys(partitionId, scopeKeys) {
+    const prefixed = new Set();
+    for (const scopeKey of scopeKeys) {
+        if (!scopeKey)
+            continue;
+        if (scopeKey.startsWith(`${partitionId}::`)) {
+            prefixed.add(scopeKey);
+            continue;
+        }
+        prefixed.add(partitionScopeKey(partitionId, scopeKey));
+    }
+    return Array.from(prefixed);
+}
+function normalizeScopeKeyForPartition(partitionId, scopeKey) {
+    if (scopeKey.startsWith(`${partitionId}::`))
+        return scopeKey;
+    if (scopeKey.includes('::'))
+        return '';
+    return partitionScopeKey(partitionId, scopeKey);
+}
+async function readCommitScopeKeys(db, commitSeq, partitionId) {
+    // Read scopes from the JSONB column and convert to scope strings
+    const rowsResult = await sql `
+    select scopes
+    from ${sql.table('sync_changes')}
+    where commit_seq = ${commitSeq}
+      and partition_id = ${partitionId}
+  `.execute(db);
+    const rows = rowsResult.rows;
+    const scopeKeys = new Set();
+    for (const row of rows) {
+        const scopes = typeof row.scopes === 'string' ? JSON.parse(row.scopes) : row.scopes;
+        for (const k of applyPartitionToScopeKeys(partitionId, scopeValuesToScopeKeys(scopes))) {
+            scopeKeys.add(k);
+        }
+    }
+    return Array.from(scopeKeys);
+}
+//# sourceMappingURL=routes.js.map