@univerjs-pro/collaboration-client 1.0.4 → 1.2.0

package/lib/types/config/config.d.ts

@@ -28,7 +28,26 @@ export interface IUniverCollaborationClientConfig {
      * Override internal modules with custom implementations.
      */
     override?: DependencyOverride;
+    /**
+     * How long local edits are batched before they are sent as one changeset, in milliseconds. Edits made within
+     * this window after the first one go into the same changeset. This is a batching delay, not a network timeout;
+     * for the acknowledgement timeout see `changesetAckTimeout`.
+     * @default 2000
+     */
     sendChangesetTimeout?: number;
+    /**
+     * How long to wait for the server's acknowledgement of a changeset before sending it again, in milliseconds.
+     * Later resends wait twice as long each time, up to `maxChangesetAckTimeout`. The request that submits the
+     * changeset is given the same timeout.
+     * @default 20000
+     */
+    changesetAckTimeout?: number;
+    /**
+     * The longest wait between two resends of an unacknowledged changeset, in milliseconds. Set it equal to
+     * `changesetAckTimeout` for a constant interval.
+     * @default 120000
+     */
+    maxChangesetAckTimeout?: number;
     snapshotServerUrl?: string;
     collabSubmitChangesetUrl?: string;
     collabWebSocketUrl?: string;

package/lib/types/controllers/collaboration/changeset-submitter.d.ts

@@ -0,0 +1,132 @@
+import type { IChangeset } from '@univerjs-pro/collaboration';
+import type { ICollaborationSendOptions } from '../../services/socket/collaboration-socket.service';
+/** Why the awaiting changeset was sent again. */
+export type ChangesetResendReason = 'ack_timeout' | 'should_retry' | 'reconnect' | 'request_failed';
+/** Emitted every time an awaiting changeset is sent again. The first send is not an event. */
+export interface IChangesetResendEvent {
+    unitID: string;
+    reqId: number;
+    reason: ChangesetResendReason;
+    /** How many times the changeset has been resent, counting this one. */
+    attempt: number;
+    /** Milliseconds since the changeset was first sent. */
+    elapsedMs: number;
+    /** Mutations in the awaiting changeset plus pending mutations not yet sent. */
+    unsyncedMutationCount: number;
+    /** Milliseconds until the next resend if nothing is heard from the server. */
+    nextDelayMs: number;
+}
+export type ChangesetResendInfo = Omit<IChangesetResendEvent, 'unitID'>;
+/** The first wait for an acknowledgement before the awaiting changeset is resent. */
+export declare const DEFAULT_ACK_TIMEOUT = 20000;
+/** The longest wait for an acknowledgement between two resends. */
+export declare const MAX_ACK_TIMEOUT = 120000;
+/** The longest backoff between two resends requested by the server or caused by a failed request. */
+export declare const MAX_RETRY_TIMEOUT = 20000;
+/**
+ * Hands a changeset to the transport. `options.timeout` is how long the transport may wait for the server to
+ * answer: it equals the wait for the acknowledgement, so a request that is still unanswered when the changeset is
+ * sent again is given up at the same moment. The returned promise, when there is one, rejects when the request
+ * failed; its resolution is not used.
+ */
+export type SendChangeset = (changeset: IChangeset, options: ICollaborationSendOptions) => void | Promise<void>;
+/** What the bound state provides for a resend: the awaiting changeset as it currently is, and the unsynced count. */
+export interface IChangesetSubmitterSource {
+    changeset: IChangeset;
+    /** Mutations in the awaiting changeset plus pending mutations not yet sent. */
+    unsyncedMutationCount: number;
+}
+export interface IChangesetSubmitterOptions {
+    /** The first wait for an acknowledgement. Defaults to `DEFAULT_ACK_TIMEOUT`. */
+    ackTimeout?: number;
+    /** The longest wait between two resends. Defaults to `MAX_ACK_TIMEOUT`, and never less than `ackTimeout`. */
+    maxAckTimeout?: number;
+    onResend?: (info: ChangesetResendInfo) => void;
+    now?: () => number;
+}
+/**
+ * Submits one changeset and sends it again until the server acknowledges it.
+ *
+ * It is created when the changeset is first sent and handed from one state to the next while the
+ * changeset is kept, so the pending timer, the intervals and the attempt count survive state transitions.
+ * The states only tell it to `submit`, `requestRetry` and `dispose`; everything about delivery (timers, backoff,
+ * attempt counting) stays here. There is at most one timer at a time: every trigger replaces the previous one.
+ *
+ * - After every send, an acknowledgement timeout is armed (`ackTimeout`, then doubled up to `maxAckTimeout`).
+ *   The request itself is given the same timeout, so an unanswered request is cancelled when the changeset is
+ *   sent again.
+ * - A `changeset_should_retry` from the server replaces the timer with a short backoff (0, 1s, 2s, ... up to
+ *   `MAX_RETRY_TIMEOUT`). A request that fails for a transient reason (network error, 408, 429, 5xx) does the
+ *   same; other failures and the request timeout leave the timer alone. The two intervals are counted
+ *   independently.
+ * - A timer that fires while no state is bound (e.g. while missing changesets are fetched) is remembered and
+ *   runs as soon as the next awaiting state binds.
+ */
+export declare class ChangesetSubmitter {
+    private readonly _send;
+    private readonly _options;
+    private _attempt;
+    private readonly _firstSentAt;
+    private _ackTimeout;
+    private readonly _maxAckTimeout;
+    private _retryBackoff;
+    private _nextDelay;
+    private _timer;
+    private _pendingReason;
+    private _source;
+    /** Identifies the latest send; the outcome of an earlier send is ignored. */
+    private _sendToken;
+    private _disposed;
+    private readonly _now;
+    private _reqId;
+    constructor(reqId: number, _send: SendChangeset, _options?: IChangesetSubmitterOptions);
+    /** The request id of the changeset. It is assigned by the transport on the first send and read back then. */
+    get reqId(): number;
+    get attempt(): number;
+    get nextDelayMs(): number;
+    get elapsedMs(): number;
+    /**
+     * Bind the state that owns the awaiting changeset. `source` returns the changeset as it currently is (it may
+     * have been transformed since the last send) and the number of unsynced mutations. A resend that came due
+     * while nothing was bound runs now.
+     */
+    bind(source: () => IChangesetSubmitterSource): void;
+    /** Detach the current state while the changeset is handed to the next one. Timers keep running. */
+    unbind(): void;
+    /**
+     * Send the changeset and wait for its acknowledgement.
+     *
+     * Without `reason` this is the first send of the changeset, which is not reported as a resend. With `reason`
+     * it is a resend triggered outside this submitter (e.g. after a reconnect): it counts as an attempt and
+     * notifies the listener.
+     */
+    submit(changeset: IChangeset, unsyncedMutationCount: number, reason?: ChangesetResendReason): void;
+    /**
+     * Wait for the acknowledgement of a send that happened outside this submitter, e.g. a changeset restored
+     * from the cache that the entity resends itself.
+     */
+    armAckTimeout(): void;
+    /** The server asked for the changeset to be resent: replace the current timer with the short backoff. */
+    requestRetry(): void;
+    /** The changeset was acknowledged, rejected or dropped. */
+    dispose(): void;
+    private _deliver;
+    /**
+     * The request did not reach the server. A transient failure brings the next send forward to the short
+     * backoff; the acknowledgement timeout keeps its own count. A request that ran into its timeout is ignored:
+     * the changeset is being sent again at that very moment. So is the failure of a request that a later send
+     * superseded, e.g. when the server asked for a retry before the request was answered.
+     */
+    private _onRequestFailed;
+    private _schedule;
+    private _resend;
+    /** Count a resend and move the interval it belongs to; the request timeout follows the new interval. */
+    private _countResend;
+    private _notifyResend;
+    private _clearTimer;
+}
+/**
+ * How long to wait before sending again after a failed request, or `null` when the failure should not bring
+ * the next send forward.
+ */
+export declare function getRetryDelay(error: unknown, backoff: number): number | null;

package/lib/types/controllers/collaboration/collaboration-entity.d.ts

@@ -1,7 +1,9 @@
 import type { IDisposable, IMutationInfo, Nullable, UniverInstanceType } from '@univerjs/core';
 import type { Observable } from 'rxjs';
 import type { CollaborationSession } from '../../services/collaboration-session/collaboration-session';
-import type { CollaborationState, ICollaborationStateHandler, PrepareTransformSelectionsHandler, SyncEditingCollabCursorHandler, TransformIMEHandler, TransformRemoteChangesetByIMECache, TransformRemoteChangesetByStateCache, TransformSelectionsHandler, TransformStateHandler } from './collaboration-state';
+import type { IUnitCacheData } from '../../services/local-cache/local-cache.service';
+import type { IChangesetResendEvent } from './changeset-submitter';
+import type { CollaborationState, ICollaborationStateHandler, IConflictInfo, PrepareTransformSelectionsHandler, SyncEditingCollabCursorHandler, TransformIMEHandler, TransformRemoteChangesetByIMECache, TransformRemoteChangesetByStateCache, TransformSelectionsHandler, TransformStateHandler } from './collaboration-state';
 import { CompressMutationService, RevisionService } from '@univerjs-pro/collaboration';
 import { ICommandService, ILogService, Injector, IPermissionService, IUniverInstanceService, LocaleService, RxDisposable } from '@univerjs/core';
 import { DocStateChangeManagerService } from '@univerjs/docs';
@@ -11,6 +13,20 @@ import { ILocalCacheService } from '../../services/local-cache/local-cache.servi
 import { SheetTransformSelectionsService } from '../../services/range-selection/sheet-transform-selections.service';
 import { ISingleActiveUnitService } from '../../services/single-active-unit/single-active-unit.service';
 import { CollaborationStatus } from './collaboration-state';
+/**
+ * Emitted once when a unit enters the conflict state, after its offline cache has been cleared. Carries
+ * `IConflictInfo` and the local edits the server has not acknowledged.
+ */
+export interface ICollaborationConflictEvent extends IConflictInfo {
+    unitID: string;
+    /**
+     * The local edits the server has not acknowledged, in the format of the offline cache, or `null` when there are
+     * none. `awaitingChangeset` has been sent; whether the server applied it is unknown.
+     */
+    localChanges: IUnitCacheData | null;
+    /** Whether the offline cache of the unit was cleared. When `false`, a page reload replays the cached edits. */
+    cacheCleared: boolean;
+}
 /**
  * Each univer document instance would map to an `CollaborationEntity` to handle collaborated editing events.
  */
@@ -37,6 +53,12 @@ export declare abstract class CollaborationEntity extends RxDisposable {
     protected _changesetSessionId: string;
     protected _changesetReqId: number;
     readonly status$: Observable<CollaborationStatus>;
+    private readonly _changesetResend$;
+    /** Emits every time the awaiting changeset is sent again because it was not acknowledged. */
+    readonly changesetResend$: Observable<IChangesetResendEvent>;
+    private readonly _conflict$;
+    /** Emits once when the unit enters the conflict state, after its offline cache has been cleared. */
+    readonly conflict$: Observable<ICollaborationConflictEvent>;
     constructor(unitID: string, session: CollaborationSession, _type: UniverInstanceType, _injector: Injector, _compressMutationService: CompressMutationService, _localeService: LocaleService, _revisionService: RevisionService, _eventService: CollaborationUIEventService, _univerInstanceService: IUniverInstanceService, _logService: ILogService, _commandService: ICommandService, _permissionService: IPermissionService, _singleActiveUnitService?: ISingleActiveUnitService | undefined, _localCacheService?: ILocalCacheService | undefined);
     init(): Promise<void>;
     /**
@@ -45,6 +67,9 @@ export declare abstract class CollaborationEntity extends RxDisposable {
      */
     pauseCollaboration(): IDisposable;
     onLocalMutation(command: IMutationInfo): void;
+    /** Whether there are local mutations that the server has not acknowledged yet. */
+    hasWritePending(): boolean;
+    dispose(): void;
     private _updateState;
     protected _init(): Promise<CollaborationState>;
     /**
@@ -53,6 +78,8 @@ export declare abstract class CollaborationEntity extends RxDisposable {
     private _transitionLocked;
     private _unlockTransition;
     private _lockTransition;
+    /** Run one transition under the lock. The lock is released even when the state throws, so the next event can be handled. */
+    private _transit;
     protected _onLocalMutation(command: IMutationInfo): void;
     private _remoteChangesetQueue;
     private _onRemoteChangeset;

package/lib/types/controllers/collaboration/collaboration-state.d.ts

@@ -1,15 +1,18 @@
 import type { IAcknowledgedChangeset, IChangeset } from '@univerjs-pro/collaboration';
 import type { IMutationInfo, Nullable } from '@univerjs/core';
-import type { Observable } from 'rxjs';
+import type { IUnitCacheData } from '../../services/local-cache/local-cache.service';
 import type { ICollaborativeUndoRedoService } from '../../services/undoredo/collaborative-undoredo.service';
+import type { ChangesetResendInfo, ChangesetResendReason } from './changeset-submitter';
+import type { ICollaborationSendOptions } from '../../services/socket/collaboration-socket.service';
 import { ITransformService, RevisionService } from '@univerjs-pro/collaboration';
-import { ICommandService, IConfigService, ILogService, Injector, IPermissionService, IUniverInstanceService, LocaleService, UniverInstanceType, UserManagerService } from '@univerjs/core';
+import { ICommandService, IConfigService, ILogService, Injector, IPermissionService, IUniverInstanceService, UniverInstanceType, UserManagerService } from '@univerjs/core';
 import { CollaborationUIEventService } from '../../services/collaboration-ui-event/collaboration-ui-event';
 import { ILocalCacheService } from '../../services/local-cache/local-cache.service';
+import { ChangesetSubmitter } from './changeset-submitter';
 /** Provide both states when and after changing, so the parent could examine if state transition is correct. */
 export type StateChangeHandler = (before: CollaborationState, after: CollaborationState) => void;
 /** A network interface to send changeset and  */
-export type SendChangesetHandler = (changeset: IChangeset) => void;
+export type SendChangesetHandler = (changeset: IChangeset, options: ICollaborationSendOptions) => void | Promise<void>;
 export type MissingChangesetsHandler = (params: {
     from: number;
     to: number;
@@ -36,7 +39,57 @@ export interface ICollaborationStateHandler {
     onSyncEditingCollabCursor?: SyncEditingCollabCursorHandler;
     onTransformRemoteChangesetByIMECache?: TransformRemoteChangesetByIMECache;
     onTransformRemoteChangesetByStateCache?: TransformRemoteChangesetByStateCache;
+    /** The awaiting changeset was sent again. */
+    onChangesetResend?: (info: ChangesetResendInfo) => void;
+    /**
+     * The unit entered `ConflictState` and its recovery preparation is done: the unacknowledged local edits are backed
+     * up and the offline cache is cleared (`cacheCleared` tells whether that succeeded). Called once per conflict.
+     */
+    onConflict?: (info: IConflictInfo, localChanges: IUnitCacheData | null, cacheCleared: boolean) => void;
+    /** How long to wait for an acknowledgement before resending; see `IUniverCollaborationClientConfig`. */
+    resendTimeouts?: {
+        ackTimeout?: number;
+        maxAckTimeout?: number;
+    };
+}
+/** Why a unit entered `ConflictState`. */
+export type ConflictReason = 
+/** A remote changeset could not be transformed against the local edits. */
+'transform_failed'
+/** A remote changeset was transformed but one of its mutations failed to execute. */
+ | 'apply_failed'
+/** The server rejected the local changeset. */
+ | 'changeset_rejected'
+/** The server rejected the local changeset for lack of permission. */
+ | 'permission_rejected'
+/** Another collaborator reverted the unit to a historical revision. */
+ | 'remote_revert';
+/** The remote revert that caused a `remote_revert` conflict. */
+export interface IRemoteRevertInfo {
+    /** The revision that was restored. */
+    revision: number;
+    /** The member ID of the collaborator who restored it. */
+    memberId: string;
+    /** The user ID of the collaborator who restored it. */
+    userId: string;
+}
+/** Why a unit entered `ConflictState`. */
+export interface IConflictInfo {
+    reason: ConflictReason;
+    /** The error message, when the conflict was caused by an error. */
+    message?: string;
+    /** Present when `reason` is `remote_revert`. */
+    revert?: IRemoteRevertInfo;
+}
+/** A remote changeset was transformed successfully but executing its mutations failed. */
+export declare class RemoteChangesetApplyError extends Error {
+    readonly applyError: unknown;
+    constructor(applyError: unknown);
 }
+/** How a remote changeset relates to the local copy, see `CollaborationState._classifyRemoteChangeset`. */
+export type RemoteChangesetKind = 'echo' | 'remote_revert' | 'applied' | 'missing' | 'apply';
+/** How an acknowledgement relates to the local copy, see `CollaborationState._classifyAck`. */
+export type RemoteAckKind = 'ack_of_awaiting' | 'stale' | 'missing' | 'next';
 export declare enum CollaborationStatus {
     NOT_COLLAB = "not_collab",
     SYNCED = "synced",
@@ -68,7 +121,18 @@ export declare abstract class CollaborationState {
     constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], 
     /** State may change internally. Parent module should provide a callback to handle this event.  */
     _handler: ICollaborationStateHandler, _commandService: ICommandService, _undoRedoService: ICollaborativeUndoRedoService, _revisionService: RevisionService, _localCacheService?: ILocalCacheService | undefined);
-    abstract resend(): void;
+    /**
+     * Send the awaiting changeset again. Only states that keep an awaiting changeset implement it.
+     * @param reason Why the changeset is resent. Defaults to `reconnect`.
+     */
+    abstract resend(reason?: ChangesetResendReason): void;
+    /** Whether there are local mutations that the server has not acknowledged yet. */
+    hasLocalChanges(): boolean;
+    /** Release timers held by the state. Called when the entity is disposed while the state is current. */
+    dispose(): void;
+    /** Mutations in the awaiting changeset plus the pending mutations. */
+    protected _unsyncedMutationCount(): number;
+    protected _createChangesetSubmitter(changeset: IChangeset): ChangesetSubmitter;
     /**
      * Append a location mutation to collaboration queue.
      *
@@ -97,13 +161,48 @@ export declare abstract class CollaborationState {
     abstract toggleOffline(): CollaborationState;
     abstract toggleOnline(): CollaborationState;
     /**
-     * Check if there are some changesets missing. If true, the state should abort this changeset and request
-     * for missing changesets. Missing changesets will later be passed to `onRemoteChangeset` method.
+     * Classify a remote changeset against the local copy. Pure: nothing is requested from the server.
+     *
+     * - `echo`: the awaiting changeset came back as a broadcast, e.g. when the request was committed after the client
+     *   reconnected with another member id. It acknowledges the awaiting changeset even when the loaded snapshot
+     *   already contains its revision, so it is checked first.
+     * - `applied`: servers may deliver a changeset more than once or out of order, e.g. when several server nodes
+     *   relay changesets, or after the snapshot used to join already contains it. Applied revisions are ignored.
+     * - `missing`: there is a gap before this changeset. The missing changesets have to be fetched first.
+     * - `apply`: the changeset is the next revision and can be transformed and applied.
+     */
+    protected _classifyRemoteChangeset(changeset: IChangeset): RemoteChangesetKind;
+    /**
+     * Classify an acknowledgement against the local copy. Pure: nothing is requested from the server.
      *
-     * @param changeset The changeset sent from the remote collaboration server.
-     * @returns There is some changeset missing.
+     * - `ack_of_awaiting`: the revision is already applied but sid/reqId match the awaiting changeset, i.e. the
+     *   changeset was committed before the loaded snapshot, which already contains it.
+     * - `stale`: the revision is already applied and belongs to an earlier changeset.
+     * - `missing`: there is a gap before the acknowledged revision. The missing changesets have to be fetched first.
+     * - `next`: the acknowledged revision is the next one.
      */
-    protected _checkMissing(changeset: IChangeset | IAcknowledgedChangeset): boolean;
+    protected _classifyAck(ack: IAcknowledgedChangeset): RemoteAckKind;
+    /**
+     * Handle a remote changeset the way every online state does: an echo acknowledges the awaiting changeset, an
+     * applied revision is ignored, a gap is requested from the server before `onMissing` transits to
+     * `FetchingMissState`, and the next revision is handed to `onApply`.
+     */
+    protected _dispatchRemoteChangeset(changeset: IChangeset, handlers: {
+        onMissing: (changeset: IChangeset) => CollaborationState;
+        onApply: (changeset: IChangeset) => CollaborationState;
+        /** The unit was reverted on the server: enter `ConflictState` with `_remoteRevertInfo(changeset)`. */
+        onRemoteRevert: (changeset: IChangeset) => CollaborationState;
+    }): CollaborationState;
+    /** The conflict info of a remote changeset that reverts this unit. */
+    protected _remoteRevertInfo(changeset: IChangeset): IConflictInfo;
+    /** The conflict info of an error thrown while transforming or applying a remote changeset. */
+    protected _conflictInfoFromError(error: unknown): IConflictInfo;
+    /** The conflict info of a rejection from the server. */
+    protected _rejectionInfo(config?: {
+        isPermissionRej: boolean;
+    }): IConflictInfo;
+    /** Request the changesets after the current revision up to `revision`: left open, right closed. */
+    protected _requestMissingChangesets(revision: number): void;
     /** Transform undo redo mutations in the undo redo stack.  */
     protected _transformUndoredo(changeset: IChangeset): void;
     /** Transform selections by calling the selection manager service. */
@@ -115,6 +214,14 @@ export declare abstract class CollaborationState {
     protected _transformRemoteChangesetByStateCache(changeset: IChangeset): IChangeset;
     protected _syncEditingCollabCursor(changeset: IChangeset): void;
     protected _getCurrentRevision(): number;
+    /** The awaiting changeset came back as a broadcast instead of an acknowledgement. */
+    protected _isEchoedAwaitingChangeset(remoteChangeset: IChangeset): boolean;
+    /**
+     * The acknowledgement echoes the committed changeset, so it can be matched to the awaiting changeset by sid/reqId
+     * even when its revision is already contained in the loaded snapshot, e.g. the ack was lost and the awaiting
+     * changeset was resent after a reload.
+     */
+    protected _isAckOfAwaitingChangeset(ack: IAcknowledgedChangeset): boolean;
     protected _incrementRevisionNumber(): void;
     protected _executeRemoteChangeset(changeset: IChangeset): void;
 }
@@ -130,6 +237,7 @@ export declare class SyncedState extends CollaborationState {
     constructor(unitID: string, type: UniverInstanceType, handler: ICollaborationStateHandler, revisionService: RevisionService, _injector: Injector, undoRedoService: ICollaborativeUndoRedoService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, localCacheService?: ILocalCacheService | undefined);
     appendMutation(mutation: IMutationInfo): CollaborationState;
     onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    private _transformAndApply;
     private _onConflict;
     onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
     onRemoteRej(): CollaborationState;
@@ -157,6 +265,7 @@ export declare class PendingState extends CollaborationState {
     constructor(unitID: string, type: UniverInstanceType, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, _injector: Injector, _revisionService: RevisionService, _userManagerService: UserManagerService, _logService: ILogService, commandService: ICommandService, _configService: IConfigService, _transformService: ITransformService, _univerInstanceService: IUniverInstanceService, _undoRedoService: ICollaborativeUndoRedoService, _localCacheService?: ILocalCacheService);
     appendMutation(mutation: IMutationInfo): CollaborationState;
     onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    private _transformAndApply;
     onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
     onRemoteRej(): CollaborationState;
     onRemoteRetry(): CollaborationState;
@@ -165,6 +274,7 @@ export declare class PendingState extends CollaborationState {
     private _getSendChangesetTimeout;
     resend(): void;
     private _clearScheduledTask;
+    dispose(): void;
     private _onConflict;
 }
 /**
@@ -175,24 +285,25 @@ export declare class AwaitingState extends CollaborationState {
     private readonly _logService;
     private readonly _transformService;
     readonly status = CollaborationStatus.AWAITING;
-    private _resendTimeout;
-    private _maxTotalRetryTimeout;
-    private _resendTimer;
-    private _sender;
-    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: IChangeset, handler: ICollaborationStateHandler, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, undoRedoService: ICollaborativeUndoRedoService, localCacheService?: ILocalCacheService);
+    /** Resends the awaiting changeset until it is acknowledged. Handed to the next state that keeps the changeset. */
+    private readonly _submitter;
+    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: IChangeset, handler: ICollaborationStateHandler, submitter: ChangesetSubmitter | undefined, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, undoRedoService: ICollaborativeUndoRedoService, localCacheService?: ILocalCacheService);
     appendMutation(mutation: IMutationInfo): CollaborationState;
     onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    private _transformAndApply;
     onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
+    private _toSynced;
     onRemoteRej(config?: {
         isPermissionRej: boolean;
     }): CollaborationState;
     onRemoteRetry(changeset: IChangeset): CollaborationState;
     toggleOffline(): CollaborationState;
     toggleOnline(): CollaborationState;
-    resend(): void;
+    resend(reason?: ChangesetResendReason): void;
     private _onConflict;
-    private _resendWithTimeout;
-    private _clearScheduledTask;
+    dispose(): void;
+    /** Detach from the submitter before the awaiting changeset is handed to the next state. */
+    private _detachSubmitter;
 }
 /**
  * Some local mutations are sent to the server and waiting for acknowledgement, yet still some local mutations
@@ -204,42 +315,51 @@ export declare class AwaitingWithPendingState extends CollaborationState {
     private readonly _transformService;
     private readonly localCacheService?;
     readonly status = CollaborationStatus.AWAITING_WITH_PENDING;
-    private _resendTimeout;
-    private _maxTotalRetryTimeout;
-    private _resendTimer;
-    private _sender;
-    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: IChangeset, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, timer: Observable<{
-        timeout: number;
-        reqId: number;
-    }> | undefined, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, undoRedoService: ICollaborativeUndoRedoService, localCacheService?: ILocalCacheService | undefined);
+    /** Resends the awaiting changeset until it is acknowledged. Handed to the next state that keeps the changeset. */
+    private readonly _submitter;
+    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: IChangeset, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, submitter: ChangesetSubmitter | undefined, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, undoRedoService: ICollaborativeUndoRedoService, localCacheService?: ILocalCacheService | undefined);
     appendMutation(mutation: IMutationInfo): CollaborationState;
     onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    private _transformAndApply;
     onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
+    /** Transit to `PendingState` to schedule another sending task. */
+    private _toPending;
     onRemoteRej(config?: {
         isPermissionRej: boolean;
     }): CollaborationState;
     onRemoteRetry(changeset: IChangeset): CollaborationState;
     toggleOffline(): CollaborationState;
     toggleOnline(): CollaborationState;
-    resend(): void;
+    resend(reason?: ChangesetResendReason): void;
     private _onConflict;
-    private _resendWithTimeout;
-    private _clearScheduledTask;
+    dispose(): void;
+    /** Detach from the submitter before the awaiting changeset is handed to the next state. */
+    private _detachSubmitter;
 }
 /**
- * This state is special for handling collaboration conflicts.
- *
- * `ConflictState` is a dead end state. It cannot transit to any other state. User could only reload the page to
- * reload the document.
+ * A dead end state: the unit can no longer follow the server. Editing is disabled. `info` says why and `localChanges`
+ * holds the local edits the server has not acknowledged. Reported once through `CollaborationEntity.conflict$`.
  */
 export declare class ConflictState extends CollaborationState {
-    private _isPermissionRej;
+    readonly info: IConflictInfo;
     private readonly _permissionService;
-    private readonly _localeService;
+    private readonly _userManagerService;
+    private readonly _logService;
     private readonly _collaborationUIEventService;
     private readonly localCacheService?;
     readonly status = CollaborationStatus.CONFLICT;
-    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, _isPermissionRej: boolean | undefined, _permissionService: IPermissionService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, revisionService: RevisionService, _localeService: LocaleService, _collaborationUIEventService: CollaborationUIEventService, localCacheService?: ILocalCacheService | undefined);
+    /**
+     * The local edits the server has not acknowledged, in the format of the offline cache, or `null` when there are
+     * none. `awaitingChangeset` has been sent; whether the server applied it is unknown.
+     */
+    readonly localChanges: IUnitCacheData | null;
+    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, info: IConflictInfo, _permissionService: IPermissionService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, revisionService: RevisionService, _userManagerService: UserManagerService, _logService: ILogService, _collaborationUIEventService: CollaborationUIEventService, localCacheService?: ILocalCacheService | undefined);
+    /**
+     * Back up the unacknowledged local edits, then clear the offline cache so that the next load does not replay them
+     * (a cache with pending edits would also make the loader fetch the cached revision). Only then is the conflict
+     * reported, so that the handler may reload the page safely.
+     */
+    private _prepareConflictRecovery;
     appendMutation(): CollaborationState;
     onRemoteChangeset(): CollaborationState;
     onRemoteAck(): CollaborationState;
@@ -248,18 +368,17 @@ export declare class ConflictState extends CollaborationState {
     toggleOffline(): CollaborationState;
     toggleOnline(): CollaborationState;
     resend(): void;
-    private _prepareConflictRecovery;
     private _showConflictProcessingNotification;
-    private _showConflictNotification;
     private _disableEditing;
 }
 export declare class OfflineState extends CollaborationState {
     private readonly _injector;
+    private readonly _logService;
     readonly status = CollaborationStatus.OFFLINE;
-    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, localCacheService?: ILocalCacheService);
+    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, _logService: ILogService, localCacheService?: ILocalCacheService);
     appendMutation(mutation: IMutationInfo): CollaborationState;
-    onRemoteChangeset(_changeset: IChangeset): CollaborationState;
-    onRemoteAck(): CollaborationState;
+    onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
     onRemoteRej(): CollaborationState;
     onRemoteRetry(): CollaborationState;
     toggleOffline(): CollaborationState;
@@ -280,6 +399,11 @@ export declare class FetchingMissState extends CollaborationState {
      */
     private _acknowledgedAwaitingRevision;
     private _queuedRemoteChangesets;
+    /**
+     * The resends of the awaiting changeset. It is not bound while the gap is fetched: a resend that comes due
+     * meanwhile runs once the next awaiting state binds it.
+     */
+    private _submitter;
     private readonly _injector;
     private readonly _logService;
     private readonly _transformService;
@@ -291,13 +415,21 @@ export declare class FetchingMissState extends CollaborationState {
      * Keep the changeset in `_awaitingChangeset` for transform and sid/reqId de-duplication, and store only
      * the acknowledged server revision here.
      */
-    _acknowledgedAwaitingRevision: Nullable<number>, _queuedRemoteChangesets: IChangeset[], handler: ICollaborationStateHandler, _injector: Injector, revisionService: RevisionService, _logService: ILogService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, _transformService: ITransformService, localCacheService?: ILocalCacheService | undefined);
+    _acknowledgedAwaitingRevision: Nullable<number>, _queuedRemoteChangesets: IChangeset[], handler: ICollaborationStateHandler, 
+    /**
+     * The resends of the awaiting changeset. It is not bound while the gap is fetched: a resend that comes due
+     * meanwhile runs once the next awaiting state binds it.
+     */
+    _submitter: ChangesetSubmitter | undefined, _injector: Injector, revisionService: RevisionService, _logService: ILogService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, _transformService: ITransformService, localCacheService?: ILocalCacheService | undefined);
     onMissedChangesetFetched(changesets: IChangeset[]): CollaborationState;
     private _handleRemoteChangesets;
     private _transformAndApplyRemoteChangeset;
     private _acknowledgeAwaitingIfReady;
     private _acknowledgeAwaiting;
-    private _isEchoedAwaitingChangeset;
+    /** The awaiting changeset was committed before the loaded snapshot, so there is no new revision to count. */
+    private _dropAcknowledgedAwaiting;
+    private _disposeSubmitter;
+    dispose(): void;
     resend(): void;
     appendMutation(mutation: IMutationInfo<object>): CollaborationState;
     onRemoteChangeset(changeset: IChangeset): CollaborationState;
@@ -305,7 +437,7 @@ export declare class FetchingMissState extends CollaborationState {
     onRemoteRej(config?: {
         isPermissionRej: boolean;
     }): CollaborationState;
-    onRemoteRetry(): CollaborationState;
+    onRemoteRetry(changeset: IChangeset): CollaborationState;
     toggleOffline(): CollaborationState;
     toggleOnline(): CollaborationState;
     private _onConflict;

package/lib/types/controllers/collaboration/collaboration.controller.d.ts

@@ -14,8 +14,15 @@ export declare class CollaborationController extends RxDisposable {
     constructor(_injector: Injector, _collabSessionService: CollaborationSessionService, _configService: IConfigService, _univerInstanceService: IUniverInstanceService);
     dispose(): void;
     getCollabEntity(id: string): Nullable<CollaborationEntity>;
+    /** The entities of every unit that is collaborating now. */
+    getCollabEntities(): CollaborationEntity[];
     getCollabEntity$(id: string): Observable<CollaborationEntity>;
     readyForCollab(id: string): Promise<void>;
+    /**
+     * Whether a unit has local mutations that the server has not acknowledged yet.
+     * @param unitId The unit to check. When omitted, every collaborating unit is checked.
+     */
+    hasWritePending(unitId?: string): boolean;
     private _init;
     /**
      * Start collaboration on a document.

package/lib/types/controllers/collaboration/utils/changeset-utils.d.ts

@@ -1,6 +1,5 @@
-import type { IChangeset, RevisionService } from '@univerjs-pro/collaboration';
+import type { IChangeset, IRevertRevisionMutationParams, RevisionService } from '@univerjs-pro/collaboration';
 import type { IMutationInfo, IUniverInstanceService, UserManagerService } from '@univerjs/core';
-import type { Observable } from 'rxjs';
 export interface IAssembledChangeset {
     changeset: IChangeset;
     pendingMutations: IMutationInfo[];
@@ -23,4 +22,9 @@ export declare const assemblePdfChangeset: typeof assembleMutationChangeset;
 export declare function assembleBaseChangeset(pendingMutations: IMutationInfo[], unitID: string, univerInstanceService: IUniverInstanceService, revisionService: RevisionService, userManagerService: UserManagerService): IAssembledChangeset;
 export declare function assembleSlideChangeset(pendingMutations: IMutationInfo[], unitID: string, univerInstanceService: IUniverInstanceService, revisionService: RevisionService, userManagerService: UserManagerService): IAssembledChangeset;
 export declare function assembleDocChangeset(pendingMutations: IMutationInfo[], unitID: string, univerInstanceService: IUniverInstanceService, revisionService: RevisionService, userManagerService: UserManagerService): IAssembledChangeset;
-export declare function createTimerObservable$<T>(ms: number, options: T): Observable<T>;
+/**
+ * The revert of `unitID` carried by a remote changeset, if any. A revert is executed on the server: the next revision
+ * is the restored snapshot, so the local copy cannot transform it and has to be reloaded. Reverts of other units are
+ * ordinary changesets.
+ */
+export declare function findRemoteRevert(changeset: IChangeset, unitID: string): IRevertRevisionMutationParams | null;