@syncular/server 0.0.6-96 → 0.1.0

package/dist/hono/ws.js

@@ -0,0 +1,711 @@
+/**
+ * @syncular/server/hono - WebSocket helpers for realtime sync wake-ups
+ *
+ * WebSockets deliver binary sync-pack deltas or explicit pull-required wake-ups.
+ * Also supports presence tracking for collaborative features.
+ */
+import { RealtimeConnectionRegistry } from '@syncular/core';
+export function createWebSocketConnectionOwnerKey(args) {
+    return JSON.stringify([args.partitionId, args.actorId, args.clientId]);
+}
+export const DEFAULT_WS_SYNC_PACK_MAX_BYTES = 64 * 1024;
+function safeSend(ws, message) {
+    try {
+        ws.send(message);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function createRealtimeSessionId() {
+    const randomUuid = globalThis.crypto?.randomUUID?.();
+    if (randomUuid)
+        return randomUuid;
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+export function createWebSocketConnection(ws, args) {
+    let closed = false;
+    const connection = {
+        get isOpen() {
+            if (closed)
+                return false;
+            return ws.readyState === 1;
+        },
+        actorId: args.actorId,
+        clientId: args.clientId,
+        ownerKey: args.ownerKey,
+        transportPath: args.transportPath,
+        syncPackEncoding: args.syncPackEncoding ?? null,
+        sendHello(data) {
+            if (!connection.isOpen)
+                return;
+            const ok = safeSend(ws, JSON.stringify({
+                event: 'hello',
+                data: { ...data, timestamp: Date.now() },
+            }));
+            if (!ok)
+                closed = true;
+        },
+        sendSync(cursor, metadata) {
+            if (!connection.isOpen)
+                return;
+            const payload = {
+                cursor,
+                timestamp: Date.now(),
+            };
+            if (metadata?.reason) {
+                payload.reason = metadata.reason;
+            }
+            if (metadata?.requiresPull) {
+                payload.requiresPull = true;
+            }
+            if (metadata?.droppedCount !== undefined) {
+                payload.droppedCount = metadata.droppedCount;
+            }
+            if (metadata?.payloadBytes !== undefined) {
+                payload.payloadBytes = metadata.payloadBytes;
+            }
+            const ok = safeSend(ws, JSON.stringify({ event: 'sync', data: payload }));
+            if (!ok)
+                closed = true;
+        },
+        sendSyncPack(bytes) {
+            if (!connection.isOpen)
+                return;
+            const body = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+            const ok = safeSend(ws, body);
+            if (!ok)
+                closed = true;
+        },
+        sendHeartbeat() {
+            if (!connection.isOpen)
+                return;
+            const ok = safeSend(ws, JSON.stringify({ event: 'heartbeat', data: { timestamp: Date.now() } }));
+            if (!ok)
+                closed = true;
+        },
+        sendPresence(data) {
+            if (!connection.isOpen)
+                return;
+            const ok = safeSend(ws, JSON.stringify({
+                event: 'presence',
+                data: { presence: data, timestamp: Date.now() },
+            }));
+            if (!ok)
+                closed = true;
+        },
+        sendPushResponse(data) {
+            if (!connection.isOpen)
+                return;
+            const ok = safeSend(ws, JSON.stringify({
+                event: 'push-response',
+                data: { ...data, timestamp: Date.now() },
+            }));
+            if (!ok)
+                closed = true;
+        },
+        sendError(message) {
+            if (connection.isOpen) {
+                safeSend(ws, JSON.stringify({
+                    event: 'error',
+                    data: { error: message, timestamp: Date.now() },
+                }));
+            }
+            connection.close(1011, 'server error');
+        },
+        close(code, reason) {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                ws.close(code, reason);
+            }
+            catch {
+                // ignore
+            }
+        },
+    };
+    return connection;
+}
+/**
+ * Connection manager for tracking active WebSocket connections.
+ * Scope-key based notifications and presence tracking.
+ */
+export class WebSocketConnectionManager {
+    registry;
+    replayWindowSize;
+    maxSyncPackBytes;
+    replayRecords = [];
+    subscriptionsByOwnerKey = new Map();
+    replayDroppedThroughCursor = -1;
+    flowStateByConnection = new WeakMap();
+    maxInFlightSyncsPerConnection;
+    /**
+     * In-memory presence tracking by scope key.
+     * Map<scopeKey, Map<ownerKey, PresenceEntry>>
+     */
+    presenceByScopeKey = new Map();
+    /**
+     * Callback for presence changes - allows integration with SyncRealtimeBroadcaster
+     */
+    onPresenceChange;
+    constructor(options) {
+        this.onPresenceChange = options?.onPresenceChange;
+        this.maxInFlightSyncsPerConnection =
+            options?.maxInFlightSyncsPerConnection ?? 64;
+        this.maxSyncPackBytes = normalizeMaxSyncPackBytes(options?.maxSyncPackBytes);
+        this.replayWindowSize = normalizeReplayWindowSize(options?.replayWindowSize);
+        this.registry = new RealtimeConnectionRegistry({
+            heartbeatIntervalMs: options?.heartbeatIntervalMs,
+            onOwnerDisconnected: (ownerKey) => {
+                this.cleanupOwnerPresence(ownerKey);
+            },
+        });
+    }
+    recordAck(connection, cursor) {
+        if (!Number.isSafeInteger(cursor) || cursor < 0)
+            return;
+        const state = this.getFlowState(connection);
+        if (cursor <= state.lastAckedCursor)
+            return;
+        state.lastAckedCursor = cursor;
+        state.inFlightCursors = state.inFlightCursors.filter((inFlightCursor) => inFlightCursor > cursor);
+        if (cursor >= state.lastSentCursor) {
+            state.inFlightCursors = [];
+            state.resyncRequired = false;
+            state.droppedCount = 0;
+        }
+    }
+    /**
+     * Register a connection for a client.
+     * Returns a cleanup function to unregister.
+     */
+    register(connection, initialScopeKeys = []) {
+        return this.registry.register(connection, initialScopeKeys);
+    }
+    /**
+     * Update the effective scopes for an already-connected client.
+     * If the client has no active connections, this is a no-op.
+     */
+    updateConnectionScopeKeys(ownerKey, scopeKeys) {
+        this.registry.updateOwnerScopeKeys(ownerKey, scopeKeys);
+    }
+    /**
+     * Update the active pull subscriptions for an owner. Realtime binary deltas
+     * use these records to emit the same per-subscription integrity contract as
+     * HTTP pull responses.
+     */
+    updateConnectionSubscriptions(ownerKey, subscriptions) {
+        if (subscriptions.length === 0) {
+            this.subscriptionsByOwnerKey.delete(ownerKey);
+            this.registry.updateOwnerScopeKeys(ownerKey, []);
+            return;
+        }
+        this.subscriptionsByOwnerKey.set(ownerKey, subscriptions.map((subscription) => ({
+            ...subscription,
+            scopeKeys: [...subscription.scopeKeys],
+        })));
+        this.registry.updateOwnerScopeKeys(ownerKey, uniqueScopeKeys(subscriptions.flatMap((subscription) => subscription.scopeKeys)));
+    }
+    updateConnectionSubscriptionRoots(ownerKey, updates) {
+        if (updates.length === 0)
+            return;
+        const subscriptions = this.subscriptionsByOwnerKey.get(ownerKey);
+        if (!subscriptions || subscriptions.length === 0)
+            return;
+        const updatesBySubscription = new Map(updates.map((update) => [update.subscriptionId, update]));
+        let changed = false;
+        const next = subscriptions.map((subscription) => {
+            const update = updatesBySubscription.get(subscription.id);
+            if (!update)
+                return subscription;
+            changed = true;
+            return {
+                ...subscription,
+                cursor: Math.max(subscription.cursor, update.cursor),
+                verifiedRoot: update.verifiedRoot,
+            };
+        });
+        if (changed) {
+            this.subscriptionsByOwnerKey.set(ownerKey, next);
+        }
+    }
+    getConnectionSubscriptions(ownerKey) {
+        return this.subscriptionsByOwnerKey.get(ownerKey) ?? [];
+    }
+    getConnectionsForScopeKeys(scopeKeys, options) {
+        const connections = [];
+        this.registry.forEachConnectionInScopeKeys(scopeKeys, (connection) => connections.push(connection), options);
+        return connections;
+    }
+    /**
+     * Check whether a client is currently authorized/subscribed for a scope key.
+     */
+    isConnectionSubscribedToScopeKey(ownerKey, scopeKey) {
+        return this.registry.isOwnerSubscribedToScopeKey(ownerKey, scopeKey);
+    }
+    getConnectionScopeKeys(ownerKey) {
+        return this.registry.getScopeKeysForOwner(ownerKey);
+    }
+    /**
+     * Replay recent websocket delta notifications for a reconnecting client.
+     * Returns false when the requested cursor range is no longer fully in memory,
+     * so the caller can send an explicit pull-required recovery frame.
+     */
+    replayScopeKeys(connection, scopeKeys, fromCursor, latestCursor) {
+        if (!Number.isSafeInteger(fromCursor) ||
+            !Number.isSafeInteger(latestCursor)) {
+            return false;
+        }
+        if (latestCursor <= fromCursor) {
+            return true;
+        }
+        if (scopeKeys.length === 0 || this.replayRecords.length === 0) {
+            return false;
+        }
+        if (fromCursor < this.replayDroppedThroughCursor) {
+            return false;
+        }
+        const scopeKeySet = new Set(scopeKeys);
+        const records = this.replayRecords.filter((record) => record.cursor > fromCursor &&
+            record.cursor <= latestCursor &&
+            record.scopeKeys.some((scopeKey) => scopeKeySet.has(scopeKey)));
+        if (records.length === 0) {
+            return false;
+        }
+        const lastRecordCursor = records.reduce((cursor, record) => Math.max(cursor, record.cursor), fromCursor);
+        if (lastRecordCursor < latestCursor) {
+            return false;
+        }
+        for (const record of records) {
+            this.deliverSyncRecordToConnection(connection, record);
+        }
+        return true;
+    }
+    // =========================================================================
+    // Presence Tracking
+    // =========================================================================
+    /**
+     * Join presence for a scope key.
+     * Called when a client wants to be visible to others in a scope.
+     */
+    joinPresence(ownerKey, scopeKey, metadata) {
+        const conns = this.registry.getConnectionsForOwner(ownerKey);
+        if (!conns || conns.size === 0)
+            return false;
+        if (!this.isConnectionSubscribedToScopeKey(ownerKey, scopeKey))
+            return false;
+        const conn = conns.values().next().value;
+        if (!conn)
+            return false;
+        const { actorId, clientId } = conn;
+        let scopePresence = this.presenceByScopeKey.get(scopeKey);
+        if (!scopePresence) {
+            scopePresence = new Map();
+            this.presenceByScopeKey.set(scopeKey, scopePresence);
+        }
+        const entry = {
+            clientId,
+            actorId,
+            joinedAt: Date.now(),
+            metadata,
+        };
+        scopePresence.set(ownerKey, entry);
+        this.broadcastPresenceEvent(scopeKey, {
+            action: 'join',
+            scopeKey,
+            ownerKey,
+            clientId,
+            actorId,
+            metadata,
+        });
+        this.onPresenceChange?.({
+            action: 'join',
+            scopeKey,
+            ownerKey,
+            clientId,
+            actorId,
+            metadata,
+        });
+        return true;
+    }
+    /**
+     * Leave presence for a scope key.
+     * Called when a client no longer wants to be visible in a scope.
+     */
+    leavePresence(ownerKey, scopeKey) {
+        const scopePresence = this.presenceByScopeKey.get(scopeKey);
+        if (!scopePresence)
+            return false;
+        const entry = scopePresence.get(ownerKey);
+        if (!entry)
+            return false;
+        scopePresence.delete(ownerKey);
+        if (scopePresence.size === 0) {
+            this.presenceByScopeKey.delete(scopeKey);
+        }
+        this.broadcastPresenceEvent(scopeKey, {
+            action: 'leave',
+            scopeKey,
+            ownerKey,
+            clientId: entry.clientId,
+            actorId: entry.actorId,
+        });
+        this.onPresenceChange?.({
+            action: 'leave',
+            scopeKey,
+            ownerKey,
+            clientId: entry.clientId,
+            actorId: entry.actorId,
+        });
+        return true;
+    }
+    /**
+     * Update presence metadata for a client in a scope.
+     * Used to update what entity a user is viewing/editing.
+     */
+    updatePresenceMetadata(ownerKey, scopeKey, metadata) {
+        if (!this.isConnectionSubscribedToScopeKey(ownerKey, scopeKey))
+            return false;
+        const scopePresence = this.presenceByScopeKey.get(scopeKey);
+        if (!scopePresence)
+            return false;
+        const entry = scopePresence.get(ownerKey);
+        if (!entry)
+            return false;
+        entry.metadata = metadata;
+        this.broadcastPresenceEvent(scopeKey, {
+            action: 'update',
+            scopeKey,
+            ownerKey,
+            clientId: entry.clientId,
+            actorId: entry.actorId,
+            metadata,
+        });
+        this.onPresenceChange?.({
+            action: 'update',
+            scopeKey,
+            ownerKey,
+            clientId: entry.clientId,
+            actorId: entry.actorId,
+            metadata,
+        });
+        return true;
+    }
+    /**
+     * Get presence entries for a scope key.
+     */
+    getPresence(scopeKey) {
+        const scopePresence = this.presenceByScopeKey.get(scopeKey);
+        if (!scopePresence)
+            return [];
+        return Array.from(scopePresence.values());
+    }
+    /**
+     * Get presence for multiple scopes.
+     */
+    getPresenceMultiple(scopeKeys) {
+        const result = {};
+        for (const scopeKey of scopeKeys) {
+            result[scopeKey] = this.getPresence(scopeKey);
+        }
+        return result;
+    }
+    /**
+     * Send current presence snapshot to a specific connection.
+     * Called when a client first subscribes to presence for a scope.
+     */
+    sendPresenceSnapshot(connection, scopeKey) {
+        const entries = this.getPresence(scopeKey);
+        connection.sendPresence({
+            action: 'snapshot',
+            scopeKey,
+            entries,
+        });
+    }
+    /**
+     * Handle a presence event from another server instance (via broadcaster).
+     * Updates local state and notifies local clients.
+     */
+    handleRemotePresenceEvent(event) {
+        const { action, scopeKey, clientId, actorId, metadata, ownerKey = createWebSocketConnectionOwnerKey({
+            partitionId: scopeKey.split(':', 1)[0] ?? 'default',
+            actorId,
+            clientId,
+        }), } = event;
+        let scopePresence = this.presenceByScopeKey.get(scopeKey);
+        switch (action) {
+            case 'join': {
+                if (!scopePresence) {
+                    scopePresence = new Map();
+                    this.presenceByScopeKey.set(scopeKey, scopePresence);
+                }
+                scopePresence.set(ownerKey, {
+                    clientId,
+                    actorId,
+                    joinedAt: Date.now(),
+                    metadata,
+                });
+                break;
+            }
+            case 'leave': {
+                if (scopePresence) {
+                    scopePresence.delete(ownerKey);
+                    if (scopePresence.size === 0) {
+                        this.presenceByScopeKey.delete(scopeKey);
+                    }
+                }
+                break;
+            }
+            case 'update': {
+                if (scopePresence) {
+                    const entry = scopePresence.get(ownerKey);
+                    if (entry) {
+                        entry.metadata = metadata;
+                    }
+                }
+                break;
+            }
+        }
+        // Notify local clients
+        this.broadcastPresenceEvent(scopeKey, event);
+    }
+    /**
+     * Broadcast a presence event to all clients subscribed to a scope key.
+     */
+    broadcastPresenceEvent(scopeKey, event) {
+        this.registry.forEachConnectionInScopeKeys([scopeKey], (conn) => {
+            conn.sendPresence(event);
+        }, {
+            excludeClientIds: event.clientId ? [event.clientId] : undefined,
+        });
+    }
+    /**
+     * Clean up presence when an owner fully disconnects (all connections closed).
+     */
+    cleanupOwnerPresence(ownerKey) {
+        for (const [scopeKey, scopePresence] of this.presenceByScopeKey) {
+            const entry = scopePresence.get(ownerKey);
+            if (!entry)
+                continue;
+            scopePresence.delete(ownerKey);
+            if (scopePresence.size === 0) {
+                this.presenceByScopeKey.delete(scopeKey);
+            }
+            this.broadcastPresenceEvent(scopeKey, {
+                action: 'leave',
+                scopeKey,
+                ownerKey,
+                clientId: entry.clientId,
+                actorId: entry.actorId,
+            });
+            this.onPresenceChange?.({
+                action: 'leave',
+                scopeKey,
+                ownerKey,
+                clientId: entry.clientId,
+                actorId: entry.actorId,
+            });
+        }
+    }
+    // =========================================================================
+    // Sync Notifications
+    // =========================================================================
+    /**
+     * Notify clients that new data is available for the given scopes.
+     * Dedupes connections that match multiple scopes.
+     */
+    notifyScopeKeys(scopeKeys, cursor, opts) {
+        const websocketSyncPack = opts?.syncPack && opts.syncPack.byteLength <= this.maxSyncPackBytes
+            ? opts.syncPack
+            : undefined;
+        const replayRecord = {
+            scopeKeys: [...scopeKeys],
+            cursor,
+            syncPack: websocketSyncPack,
+            payloadBytes: opts?.syncPack?.byteLength,
+            syncPackForConnection: opts?.syncPackForConnection,
+            hasSharedPayload: opts?.syncPack !== undefined ||
+                opts?.syncPackForConnection !== undefined,
+        };
+        this.rememberReplayRecord(replayRecord);
+        this.registry.forEachConnectionInScopeKeys(scopeKeys, (conn) => {
+            this.deliverSyncRecordToConnection(conn, replayRecord);
+        }, { excludeClientIds: opts?.excludeClientIds });
+    }
+    /**
+     * Notify all connected clients of a new cursor position.
+     * Used for external data changes that affect all clients regardless of scope.
+     */
+    notifyAllClients(cursor) {
+        this.registry.forEachConnection((conn) => {
+            if (this.shouldSendResyncRequired(conn, cursor)) {
+                this.sendResyncRequired(conn, cursor);
+                return;
+            }
+            this.markSyncSent(conn, cursor);
+            conn.sendSync(cursor, {
+                reason: 'server-wakeup',
+                requiresPull: true,
+            });
+        });
+    }
+    /**
+     * Get the number of active connections for a client.
+     */
+    getConnectionCount(clientId) {
+        return this.registry.getConnectionCount(clientId);
+    }
+    /**
+     * Get the number of active connections for one owner identity.
+     */
+    getScopedConnectionCount(ownerKey) {
+        return this.registry.getScopedConnectionCount(ownerKey);
+    }
+    /**
+     * Get the current transport path for a client if connected.
+     */
+    getClientTransportPath(clientId) {
+        const conns = this.registry.getConnectionsForClient(clientId);
+        if (!conns || conns.size === 0) {
+            return null;
+        }
+        for (const conn of conns) {
+            if (conn.transportPath === 'relay') {
+                return 'relay';
+            }
+        }
+        return 'direct';
+    }
+    /**
+     * Get total number of active connections.
+     */
+    getTotalConnections() {
+        return this.registry.getTotalConnections();
+    }
+    /**
+     * Close all connections for a client.
+     */
+    closeClientConnections(clientId) {
+        this.registry.closeClientConnections(clientId, 1000, 'client closed');
+    }
+    /**
+     * Close all connections.
+     */
+    closeAll() {
+        this.registry.closeAll(1000, 'server shutdown');
+        this.presenceByScopeKey.clear();
+    }
+    getFlowState(connection) {
+        let state = this.flowStateByConnection.get(connection);
+        if (!state) {
+            state = {
+                lastAckedCursor: -1,
+                lastSentCursor: -1,
+                inFlightCursors: [],
+                resyncRequired: false,
+                droppedCount: 0,
+            };
+            this.flowStateByConnection.set(connection, state);
+        }
+        return state;
+    }
+    shouldSendResyncRequired(connection, cursor) {
+        if (this.maxInFlightSyncsPerConnection <= 0 ||
+            !Number.isSafeInteger(cursor) ||
+            cursor < 0) {
+            return false;
+        }
+        const state = this.getFlowState(connection);
+        if (cursor <= state.lastAckedCursor)
+            return false;
+        return (state.resyncRequired ||
+            state.inFlightCursors.length >= this.maxInFlightSyncsPerConnection);
+    }
+    markSyncSent(connection, cursor) {
+        if (this.maxInFlightSyncsPerConnection <= 0 ||
+            !Number.isSafeInteger(cursor) ||
+            cursor < 0) {
+            return;
+        }
+        const state = this.getFlowState(connection);
+        if (cursor <= state.lastAckedCursor)
+            return;
+        state.lastSentCursor = Math.max(state.lastSentCursor, cursor);
+        if (!state.inFlightCursors.includes(cursor)) {
+            state.inFlightCursors.push(cursor);
+        }
+    }
+    sendResyncRequired(connection, cursor) {
+        const state = this.getFlowState(connection);
+        state.resyncRequired = true;
+        state.lastSentCursor = Math.max(state.lastSentCursor, cursor);
+        state.droppedCount += 1;
+        connection.sendSync(cursor, {
+            reason: 'resync-required',
+            requiresPull: true,
+            droppedCount: state.droppedCount,
+        });
+    }
+    rememberReplayRecord(record) {
+        if (this.replayWindowSize <= 0 ||
+            record.scopeKeys.length === 0 ||
+            !Number.isSafeInteger(record.cursor) ||
+            record.cursor < 0) {
+            return;
+        }
+        this.replayRecords.push(record);
+        while (this.replayRecords.length > this.replayWindowSize) {
+            const dropped = this.replayRecords.shift();
+            if (dropped) {
+                this.replayDroppedThroughCursor = Math.max(this.replayDroppedThroughCursor, dropped.cursor);
+            }
+        }
+    }
+    deliverSyncRecordToConnection(connection, record) {
+        if (this.shouldSendResyncRequired(connection, record.cursor)) {
+            this.sendResyncRequired(connection, record.cursor);
+            return;
+        }
+        const connectionSyncPack = record.syncPackForConnection?.(connection) ?? record.syncPack;
+        if (connectionSyncPack &&
+            connectionSyncPack.byteLength <= this.maxSyncPackBytes &&
+            connection.syncPackEncoding === 'binary-sync-pack-v1') {
+            this.markSyncSent(connection, record.cursor);
+            connection.sendSyncPack(connectionSyncPack);
+            return;
+        }
+        this.markSyncSent(connection, record.cursor);
+        connection.sendSync(record.cursor, {
+            reason: connectionSyncPack || record.payloadBytes !== undefined
+                ? 'payload-too-large'
+                : 'server-wakeup',
+            requiresPull: true,
+            payloadBytes: connectionSyncPack?.byteLength ?? record.payloadBytes,
+        });
+    }
+}
+function normalizeMaxSyncPackBytes(value) {
+    if (value === undefined)
+        return DEFAULT_WS_SYNC_PACK_MAX_BYTES;
+    if (!Number.isFinite(value))
+        return DEFAULT_WS_SYNC_PACK_MAX_BYTES;
+    return Math.max(0, Math.floor(value));
+}
+function normalizeReplayWindowSize(value) {
+    if (value === undefined)
+        return 64;
+    if (!Number.isFinite(value))
+        return 64;
+    return Math.max(0, Math.floor(value));
+}
+function uniqueScopeKeys(scopeKeys) {
+    const unique = new Set();
+    for (const scopeKey of scopeKeys) {
+        if (scopeKey)
+            unique.add(scopeKey);
+    }
+    return Array.from(unique);
+}
+//# sourceMappingURL=ws.js.map