@syncular/server-hono 0.0.1 → 0.0.2-126

package/src/ws.ts

@@ -17,12 +17,23 @@ export interface PresenceEntry {
   metadata?: Record<string, unknown>;
 }
 
+/**
+ * Push response data sent back to the client over WS
+ */
+export interface WsPushResponseData {
+  requestId: string;
+  ok: boolean;
+  status: string;
+  commitSeq?: number;
+  results: Array<{ opIndex: number; status: string; [k: string]: unknown }>;
+}
+
 /**
  * WebSocket event data for sync notifications
  */
 export interface SyncWebSocketEvent {
   /** Event type */
-  event: 'sync' | 'heartbeat' | 'error' | 'presence';
+  event: 'sync' | 'heartbeat' | 'error' | 'presence' | 'push-response';
   /** Data payload */
   data: {
     /** New cursor position (for sync events) */
@@ -38,6 +49,12 @@ export interface SyncWebSocketEvent {
       metadata?: Record<string, unknown>;
       entries?: PresenceEntry[];
     };
+    /** Push response data (for push-response events) */
+    requestId?: string;
+    ok?: boolean;
+    status?: string;
+    commitSeq?: number;
+    results?: Array<{ opIndex: number; status: string; [k: string]: unknown }>;
     /** Timestamp */
     timestamp: number;
   };
@@ -47,8 +64,8 @@ export interface SyncWebSocketEvent {
  * WebSocket connection controller for managing active connections
  */
 export interface WebSocketConnection {
-  /** Send a sync notification */
-  sendSync(cursor: number): void;
+  /** Send a sync notification, optionally with inline change data */
+  sendSync(cursor: number, changes?: unknown[]): void;
   /** Send a heartbeat */
   sendHeartbeat(): void;
   /** Send a presence event */
@@ -60,6 +77,8 @@ export interface WebSocketConnection {
     metadata?: Record<string, unknown>;
     entries?: PresenceEntry[];
   }): void;
+  /** Send a push response back to the client */
+  sendPushResponse(data: WsPushResponseData): void;
   /** Send an error and close */
   sendError(message: string): void;
   /** Close the connection */
@@ -97,15 +116,16 @@ export function createWebSocketConnection(
     actorId: args.actorId,
     clientId: args.clientId,
     transportPath: args.transportPath,
-    sendSync(cursor: number) {
+    sendSync(cursor: number, changes?: unknown[]) {
       if (!connection.isOpen) return;
-      const ok = safeSend(
-        ws,
-        JSON.stringify({
-          event: 'sync',
-          data: { cursor, timestamp: Date.now() },
-        })
-      );
+      const payload: Record<string, unknown> = {
+        cursor,
+        timestamp: Date.now(),
+      };
+      if (changes && changes.length > 0) {
+        payload.changes = changes;
+      }
+      const ok = safeSend(ws, JSON.stringify({ event: 'sync', data: payload }));
       if (!ok) closed = true;
     },
     sendHeartbeat() {
@@ -134,6 +154,17 @@ export function createWebSocketConnection(
       );
       if (!ok) closed = true;
     },
+    sendPushResponse(data: WsPushResponseData) {
+      if (!connection.isOpen) return;
+      const ok = safeSend(
+        ws,
+        JSON.stringify({
+          event: 'push-response',
+          data: { ...data, timestamp: Date.now() },
+        })
+      );
+      if (!ok) closed = true;
+    },
     sendError(message: string) {
       if (connection.isOpen) {
         safeSend(
@@ -575,10 +606,16 @@ export class WebSocketConnectionManager {
    * Notify clients that new data is available for the given scopes.
    * Dedupes connections that match multiple scopes.
    */
+  /**
+   * Maximum serialized size (bytes) for inline WS change delivery.
+   * Larger payloads fall back to cursor-only notification.
+   */
+  private static readonly WS_INLINE_MAX_BYTES = 64 * 1024;
+
   notifyScopeKeys(
     scopeKeys: string[],
     cursor: number,
-    opts?: { excludeClientIds?: string[] }
+    opts?: { excludeClientIds?: string[]; changes?: unknown[] }
   ): void {
     const exclude = new Set(opts?.excludeClientIds ?? []);
     const targets = new Set<WebSocketConnection>();
@@ -589,10 +626,36 @@ export class WebSocketConnectionManager {
       for (const conn of conns) targets.add(conn);
     }
 
+    // Size guard: only deliver inline changes if under threshold
+    let inlineChanges: unknown[] | undefined;
+    if (opts?.changes && opts.changes.length > 0) {
+      const serialized = JSON.stringify(opts.changes);
+      if (serialized.length <= WebSocketConnectionManager.WS_INLINE_MAX_BYTES) {
+        inlineChanges = opts.changes;
+      }
+    }
+
     for (const conn of targets) {
       if (!conn.isOpen) continue;
       if (exclude.has(conn.clientId)) continue;
-      conn.sendSync(cursor);
+      if (inlineChanges) {
+        conn.sendSync(cursor, inlineChanges);
+      } else {
+        conn.sendSync(cursor);
+      }
+    }
+  }
+
+  /**
+   * Notify all connected clients of a new cursor position.
+   * Used for external data changes that affect all clients regardless of scope.
+   */
+  notifyAllClients(cursor: number): void {
+    for (const conns of this.connectionsByClientId.values()) {
+      for (const conn of conns) {
+        if (!conn.isOpen) continue;
+        conn.sendSync(cursor);
+      }
     }
   }