feat: surface update errors

Author: zxch3n

llms.md

@@ -278,7 +278,7 @@ The resolved room implements:
   to stay within limits.
 - On receiving `DocUpdate`/fragments, the client reassembles updates and passes
   them to `crdtAdaptor.applyUpdate`.
-- `Ack` messages are logged; non‑zero statuses indicate the update batch was rejected.
+- `Ack` messages with non‑zero status trigger `crdtAdaptor.onUpdateError(updates, status)` using the original sent batch; missing batches are still logged.
 
 ### 3.8 Ping/Pong Integration
 

packages/loro-adaptors/README.md

@@ -107,12 +107,12 @@ import { YjsAwarenessServerAdaptor } from "loro-adaptors/yjs";
 ## API
 
 - `loro-adaptors/loro`
-  - `new LoroAdaptor(doc?: LoroDoc, config?: { onImportError? })`
+  - `new LoroAdaptor(doc?: LoroDoc, config?: { onImportError?, onUpdateError? })`
   - `new LoroEphemeralAdaptor(store?: EphemeralStore)`
   - `new LoroPersistentStoreAdaptor(store?: EphemeralStore)`
-  - `new EloAdaptor(docOrConfig: LoroDoc | { getPrivateKey, ivFactory?, onDecryptError? })`
+  - `new EloAdaptor(docOrConfig: LoroDoc | { getPrivateKey, ivFactory?, onDecryptError?, onUpdateError? })`
 - `loro-adaptors/flock`
-  - `new FlockAdaptor(flock: Flock, config?: { onImportError? })`
+  - `new FlockAdaptor(flock: Flock, config?: { onImportError?, onUpdateError? })`
 - `loro-adaptors/yjs`
   - `new YjsAwarenessServerAdaptor()`
 

packages/loro-adaptors/src/elo-adaptor.ts

@@ -24,6 +24,11 @@ export interface EloAdaptorConfig {
     err: Error,
     meta: { kind: "delta" | "snapshot"; keyId: string }
   ) => void;
+  onUpdateError?: (
+    updates: Uint8Array[],
+    errorCode: number,
+    reason?: string
+  ) => void;
 }
 
 export class EloAdaptor implements CrdtDocAdaptor {
@@ -157,6 +162,14 @@ export class EloAdaptor implements CrdtDocAdaptor {
     return undefined;
   }
 
+  onUpdateError(
+    updates: Uint8Array[],
+    errorCode: number,
+    reason?: string
+  ): void {
+    this.config.onUpdateError?.(updates, errorCode, reason);
+  }
+
   async handleJoinOk(res: JoinResponseOk): Promise<void> {
     if (this.destroyed) return;
     try {

packages/loro-adaptors/src/flock-adaptor.ts

@@ -95,6 +95,11 @@ function deserializeBundle(bytes: Uint8Array): FlockExportBundle {
 
 export interface FlockAdaptorConfig {
   onImportError?: (error: Error, data: Uint8Array[]) => void;
+  onUpdateError?: (
+    updates: Uint8Array[],
+    errorCode: number,
+    reason?: string
+  ) => void;
 }
 
 /**
@@ -169,6 +174,14 @@ export class FlockAdaptor implements CrdtDocAdaptor {
     return undefined;
   }
 
+  onUpdateError(
+    updates: Uint8Array[],
+    errorCode: number,
+    reason?: string
+  ): void {
+    this.config.onUpdateError?.(updates, errorCode, reason);
+  }
+
   async handleJoinOk(res: JoinResponseOk): Promise<void> {
     if (this.destroyed) return;
     try {

packages/loro-adaptors/src/loro-adaptor.ts

@@ -7,6 +7,11 @@ import type { CrdtAdaptorContext, CrdtDocAdaptor } from "./types";
 
 export interface LoroAdaptorConfig {
   onImportError?: (error: Error, data: Uint8Array[]) => void;
+  onUpdateError?: (
+    updates: Uint8Array[],
+    errorCode: number,
+    reason?: string
+  ) => void;
 }
 
 export class LoroAdaptor implements CrdtDocAdaptor {
@@ -74,6 +79,14 @@ export class LoroAdaptor implements CrdtDocAdaptor {
     return undefined;
   }
 
+  onUpdateError(
+    updates: Uint8Array[],
+    errorCode: number,
+    reason?: string
+  ): void {
+    this.config.onUpdateError?.(updates, errorCode, reason);
+  }
+
   async handleJoinOk(res: JoinResponseOk): Promise<void> {
     if (this.destroyed) return;
 

packages/loro-adaptors/src/types.ts

@@ -39,6 +39,17 @@ export interface CrdtDocAdaptor {
   getAlternativeVersion?: (
     currentVersion: Uint8Array
   ) => Uint8Array | undefined;
+  /**
+   * Called when the server rejects a previously sent update batch.
+   * @param updates The original updates that were sent
+   * @param errorCode The numeric update status code from the Ack
+   * @param reason Optional human-readable reason if available
+   */
+  onUpdateError?: (
+    updates: Uint8Array[],
+    errorCode: number,
+    reason?: string
+  ) => void;
   // Legacy hook retained for compatibility
   handleUpdateError?: (error: unknown) => void;
   destroy: () => void;

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

@@ -167,6 +167,8 @@ export class LoroWebsocketClient {
   private activeRooms: Map<string, ActiveRoom> = new Map();
   // Buffer for %ELO only: backfills can arrive immediately after JoinResponseOk
   private preJoinUpdates: Map<string, Array<{ updates: Uint8Array[]; refId?: HexString }>> = new Map();
+  // Track outbound update batches so we can surface errors with payload context
+  private sentUpdateBatches: Map<HexString, { roomKey: string; updates: Uint8Array[] }> = 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
@@ -856,6 +858,7 @@ export class LoroWebsocketClient {
 
   cleanupRoom(roomId: string, crdtType: CrdtType) {
     const id = crdtType + roomId;
+    this.purgeSentBatchesForRoom(id);
     this.activeRooms.delete(id);
     this.pendingRooms.delete(id);
     this.roomAdaptors.delete(id);
@@ -1079,6 +1082,12 @@ export class LoroWebsocketClient {
     );
 
     const batchId = randomBatchId();
+    const roomKey = `${crdt}${roomId}`;
+    // Store the original payload so we can surface detailed errors on Ack
+    this.sentUpdateBatches.set(batchId, {
+      roomKey,
+      updates: [update.slice()],
+    });
 
     if (update.length <= FRAG_LIMIT) {
       // Send as a single DocUpdate with one update entry
@@ -1135,6 +1144,22 @@ export class LoroWebsocketClient {
     );
   }
 
+  consumeSentBatch(refId: HexString): { roomKey: string; updates: Uint8Array[] } | undefined {
+    const entry = this.sentUpdateBatches.get(refId);
+    if (entry) {
+      this.sentUpdateBatches.delete(refId);
+    }
+    return entry;
+  }
+
+  private purgeSentBatchesForRoom(roomKey: string): void {
+    for (const [refId, entry] of Array.from(this.sentUpdateBatches.entries())) {
+      if (entry.roomKey === roomKey) {
+        this.sentUpdateBatches.delete(refId);
+      }
+    }
+  }
+
   /**
    * Destroy the client, removing listeners and stopping timers.
    * After destroy, the instance should not be used.
@@ -1162,6 +1187,7 @@ export class LoroWebsocketClient {
       this.ops.onWsClose?.();
     }
     this.queuedJoins = [];
+    this.sentUpdateBatches.clear();
     this.detachSocketListeners(ws);
     try {
       this.removeNetworkListeners?.();
@@ -1482,8 +1508,14 @@ class LoroWebsocketClientRoomImpl
   }
 
   handleAck(ack: Ack) {
+    const sent = this.client.consumeSentBatch(ack.refId);
     if (ack.status !== UpdateStatusCode.Ok) {
-      console.warn(`Ack status ${ack.status} for ${this.crdtType}:${this.roomId} (ref ${ack.refId})`);
+      const updates = sent?.updates ?? [];
+      const reason = updateStatusToReason(ack.status);
+      this.crdtAdaptor.onUpdateError?.(updates, ack.status, reason);
+      if (!sent) {
+        console.warn(`Ack status ${ack.status} for ${this.crdtType}:${this.roomId} (ref ${ack.refId}) with no matching batch`);
+      }
     }
   }
 
@@ -1524,6 +1556,27 @@ class LoroWebsocketClientRoomImpl
 
 // --- Keepalive helpers (ping/pong) ---
 
+function updateStatusToReason(status: UpdateStatusCode): string | undefined {
+  switch (status) {
+    case UpdateStatusCode.Unknown:
+      return "unknown";
+    case UpdateStatusCode.PermissionDenied:
+      return "permission_denied";
+    case UpdateStatusCode.InvalidUpdate:
+      return "invalid_update";
+    case UpdateStatusCode.PayloadTooLarge:
+      return "payload_too_large";
+    case UpdateStatusCode.RateLimited:
+      return "rate_limited";
+    case UpdateStatusCode.FragmentTimeout:
+      return "fragment_timeout";
+    case UpdateStatusCode.AppError:
+      return "app_error";
+    default:
+      return undefined;
+  }
+}
+
 // --- Internal ping helpers ---
 function isPositive(v: unknown): v is number {
   return typeof v === "number" && isFinite(v) && v > 0;