docs: clarify ack direction and report client failures

Author: zxch3n

packages/loro-websocket/src/client/index.ts

@@ -41,7 +41,7 @@ interface PendingRoom {
 }
 
 interface InternalRoomHandler {
-  handleDocUpdate(updates: Uint8Array[]): void;
+  handleDocUpdate(updates: Uint8Array[], refId?: HexString): void;
   handleAck(ack: Ack): void;
   handleRoomError(error: RoomError): void;
 }
@@ -166,7 +166,7 @@ export class LoroWebsocketClient {
   private pendingRooms: Map<string, PendingRoom> = new Map();
   private activeRooms: Map<string, ActiveRoom> = new Map();
   // Buffer for %ELO only: backfills can arrive immediately after JoinResponseOk
-  private preJoinUpdates: Map<string, Uint8Array[]> = new Map();
+  private preJoinUpdates: Map<string, Array<{ updates: Uint8Array[]; refId?: HexString }>> = new Map();
   private fragmentBatches: Map<string, FragmentBatch> = new Map();
   private roomAdaptors: Map<string, CrdtDocAdaptor> = new Map();
   // Track roomId for each active id so we can rejoin on reconnect
@@ -641,12 +641,12 @@ export class LoroWebsocketClient {
       case MessageType.DocUpdate: {
         const active = this.activeRooms.get(roomId);
         if (active) {
-          active.handler.handleDocUpdate(msg.updates);
+          active.handler.handleDocUpdate(msg.updates, msg.batchId);
         } else {
           const pending = this.pendingRooms.get(roomId);
           if (pending) {
             const buf = this.preJoinUpdates.get(roomId) ?? [];
-            buf.push(...msg.updates);
+            buf.push({ updates: msg.updates, refId: msg.batchId });
             this.preJoinUpdates.set(roomId, buf);
           }
         }
@@ -763,12 +763,12 @@ export class LoroWebsocketClient {
       const active = this.activeRooms.get(id);
       if (active) {
         // Treat reassembled data as a single update
-        active.handler.handleDocUpdate([reassembledData]);
+        active.handler.handleDocUpdate([reassembledData], batch.header.batchId);
       } else {
         const pending = this.pendingRooms.get(id);
         if (pending) {
           const buf = this.preJoinUpdates.get(id) ?? [];
-          buf.push(reassembledData);
+          buf.push({ updates: [reassembledData], refId: batch.header.batchId });
           this.preJoinUpdates.set(id, buf);
         }
       }
@@ -791,7 +791,9 @@ export class LoroWebsocketClient {
     const buf = this.preJoinUpdates.get(id);
     if (buf && buf.length) {
       try {
-        handler.handleDocUpdate(buf);
+        for (const entry of buf) {
+          handler.handleDocUpdate(entry.updates, entry.refId);
+        }
       } finally {
         this.preJoinUpdates.delete(id);
       }
@@ -1457,8 +1459,29 @@ class LoroWebsocketClientRoomImpl
     return this.crdtAdaptor.waitForReachingServerVersion();
   }
 
-  handleDocUpdate(updates: Uint8Array[]) {
-    this.crdtAdaptor.applyUpdate(updates);
+  handleDocUpdate(updates: Uint8Array[], refId?: HexString) {
+    try {
+      this.crdtAdaptor.applyUpdate(updates);
+    } catch (error) {
+      // Surface to adaptor for custom handling
+      this.crdtAdaptor.handleUpdateError?.(error);
+      // Inform server that the update failed if we can reference the batch ID
+      if (refId && this.client.socket?.readyState === WebSocket.OPEN) {
+        try {
+          this.client.socket.send(
+            encode({
+              type: MessageType.Ack,
+              crdt: this.crdtType,
+              roomId: this.roomId,
+              refId,
+              status: UpdateStatusCode.InvalidUpdate,
+            } as Ack)
+          );
+        } catch (err) {
+          console.error("Failed to send failure Ack", err);
+        }
+      }
+    }
   }
 
   handleAck(ack: Ack) {

packages/loro-websocket/src/server/simple-server.ts

@@ -265,6 +265,13 @@ export class SimpleServer {
         this.handleLeave(client, message);
         break;
       case MessageType.Ack:
+        // Clients may report failures when they cannot apply a server update.
+        if (message.status !== UpdateStatusCode.Ok) {
+          console.warn(
+            `Client reported update failure for ${message.crdt}:${message.roomId} ref ${message.refId} status ${message.status}`
+          );
+        }
+        break;
       case MessageType.RoomError:
         // Server does not expect these from clients; ignore.
         break;

protocol.md

@@ -92,6 +92,8 @@ When Recv receives updates in the same room from other peers, it broadcasts them
 
 When Req makes local edits on the document, it sends `DocUpdate` (with its Update Batch ID) or `DocUpdateFragment` messages to Recv. Recv MUST reply with an `Ack` referencing that Update Batch ID (or the fragment batch ID when fragments are used). A status of `0x00` confirms acceptance; non-zero statuses follow Update Status Codes. For example, if Req lacks write permission, Recv sends `Ack(status=0x03 permission_denied)` for that batch.
 
+**WebSocket (client–server) directionality:** when Recv (the server) pushes updates to Req (the client), Req SHOULD NOT send `Ack(status=0x00)` back. The server already assumes delivery over the WebSocket. The client MAY send a non‑zero `Ack` (referencing the server’s batch ID) to report that it failed to apply the update (for example `invalid_update` or `fragment_timeout`).
+
 If Recv forces the peer out of the room (permission change, quota enforcement, malicious behavior, etc.), it sends `RoomError`. After receiving `RoomError`, the peer MUST treat the room as closed and will not receive further messages until it rejoins.
 
 Req sends `Leave` if it is no longer interested in updates for the target document.
@@ -111,6 +113,8 @@ If Recv times out waiting for remaining fragments of a batch, it MUST:
 
 Upon receiving `Ack(status=0x07 fragment_timeout)`, Req SHOULD resend the whole batch (header + all fragments) with the same or a new batch ID.
 
+If Req (client) times out while reassembling fragments sent by Recv (server), it MAY send `Ack(status=0x07 fragment_timeout)` with that batch ID to signal the failure. Servers MAY choose to resend the batch or fall back to a snapshot/delta strategy.
+
 ## Errors and status
 
 Two message types carry error semantics; update-level results travel in `Ack` status bytes.
@@ -181,7 +185,7 @@ Implementation note: On platforms that support automatic responses (e.g., Cloudf
 
 ## Why these changes (v1)
 
-- Reliable delivery semantics: explicit `Ack` for each update batch (or fragment batch) lets applications know whether a change was accepted instead of inferring success from silence.
+- Reliable delivery semantics: explicit `Ack` for each client‑originated update batch (or fragment batch) lets applications know whether a change was accepted instead of inferring success from silence; clients only emit `Ack` when a server‑originated update fails.
 - Clear eviction signal: `RoomError` distinguishes "your update failed" from "you are no longer in the room", enabling clients to stop syncing and prompt rejoin or escalation.
 - Better error mapping: moving `ok` to `0x00` and `unknown` to `0x01` aligns status bytes with common success/failure conventions and leaves room for app-specific errors.
 - Debuggability: 64-bit batch IDs make ACK correlation collision-resistant even on long-lived, multiplexed connections while adding negligible overhead versus the 256 KiB frame limit.