resyncAsync

fun resyncAsync(document: Document, discardLocalChanges: Boolean, initialPresence: P? = null): Deferred<Result<List<Document.Event.DroppedChange>>>

Recovers document in place after the server has refused to accept its local writes (D3; JS SDK client.ts resync, 61ca06c9/#1463): discards its un-pushed local changes, detaches without clearing presence, then re-attaches it under the SAME sync mode, disableGC, presence, and schema it had -- the same Document instance, never swapped for a new one. Restarts the sync loop if it had stopped.

discardLocalChanges is required true (ErrInvalidArgument otherwise, matching iOS): resyncing without discarding would simply re-send the same refused changes forever.

Failure contract -- not uniform; some paths throw out of the returned Deferred's await(), others resolve it with Result.failure:

  • discardLocalChanges == false, document not attached, or a resync/detach already in progress on it -- THROWS before anything is touched.

  • The detach RPC itself fails (refused, or an RPC/client error) -- resolves with Result.failure; the discarded queue is restored and minting re-opened, so document ends exactly as it was before this call, still under its ORIGINAL attach (never left Detached).

  • The re-attach after an otherwise-successful detach fails -- THROWS. By this point the queue is already discarded and Document.Event.LocalChangesDropped (reason Document.Event.Reason.WriteDenied) has already been published; document is left Detached, neither re-attached nor rolled back, and a caller must attach it again itself.

On success the returned Deferred resolves with the changes that were discarded, matching the list Document.Event.LocalChangesDropped carries, so a caller can show the user what was lost.

While a resync is in progress, document refuses updateAsync/undo/redo with YorkieException.Code.ErrRefused (Document.isMintable/canUndo/canRedo reflect this too), from the moment the queue is discarded until the resync either rolls back or re-anchors -- including a pass already suspended mid-call BEFORE this resync started and resumed only after it finished (a generation check, not just a flag, so straddling the whole call is refused too). Only one resync or detach may run on document at a time: an overlapping resyncAsync or detachDocument call is refused immediately with ErrInvalidArgument, before anything is discarded.

Cancellation is safe end-to-end. Cancelling the returned Deferred before the queue is discarded leaves document untouched -- still Attached, queue intact, no resync left marked in progress. Cancelling it at or after that point (including while the detach RPC is in flight) lets the discard/detach/re-attach run to completion uninterrupted rather than abandoning it partway: the cancelled caller's own await() still throws CancellationException, but document itself always finishes in one of the states this KDoc describes above, never stuck between them.