@univerjs-pro/collaboration-client 0.5.0-alpha.0 → 0.5.0-beta.1

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

@@ -0,0 +1,303 @@
+import { IMutationInfo, Nullable, ICommandService, IConfigService, ILogService, Injector, IPermissionService, IUniverInstanceService, LocaleService } from '@univerjs/core';
+import { IAcknowledgedChangeset, IChangeset, ITransformService, RevisionService } from '@univerjs-pro/collaboration';
+import { Observable } from 'rxjs';
+import { ICollabEditingCursor } from '../../services/sync-editing-collab-cursor/doc-sync-editing-collab-cursor.service';
+import { ICollaborativeUndoRedoService } from '../../services/undoredo/collaborative-undoredo.service';
+import { UniverType } from '@univerjs/protocol';
+import { INotificationService } from '@univerjs/ui';
+import { LocalCacheService } from '../../services/local-cache/local-cache.service';
+import { MemberService } from '../../services/member/member.service';
+/** 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 MissingChangesetsHandler = (params: {
+    from: number;
+    to: number;
+}) => void;
+export type TransformSelectionsHandler = (changeset: IChangeset) => void;
+export type TransformIMEHandler = (changeset: IChangeset) => void;
+export type TransformStateHandler = (changeset: IChangeset) => void;
+export type SyncEditingCollabCursorHandler = (params: ICollabEditingCursor) => void;
+export type TransformRemoteChangesetByIMECache = (changeset: IChangeset) => IChangeset;
+export type TransformRemoteChangesetByStateCache = (changeset: IChangeset) => IChangeset;
+export interface ICollaborationStateHandler {
+    onStateChange: StateChangeHandler;
+    onSendChangeset: SendChangesetHandler;
+    onMissingChangesets: MissingChangesetsHandler;
+    onTransformSelections?: TransformSelectionsHandler;
+    onTransformIME?: TransformIMEHandler;
+    onTransformState?: TransformStateHandler;
+    onSyncEditingCollabCursor?: SyncEditingCollabCursorHandler;
+    onTransformRemoteChangesetByIMECache?: TransformRemoteChangesetByIMECache;
+    onTransformRemoteChangesetByStateCache?: TransformRemoteChangesetByStateCache;
+}
+export declare enum CollaborationStatus {
+    NOT_COLLAB = "not_collab",
+    SYNCED = "synced",
+    PENDING = "pending",
+    AWAITING = "awaiting",
+    AWAITING_WITH_PENDING = "awaiting_with_pending",
+    FETCH_MISS = "fetch_missing",
+    CONFLICT = "conflict",
+    OFFLINE = "offline"
+}
+/**
+ * Use state machine to manage syncing states.
+ * An explanation to how these states are transformed to each other.
+ */
+export declare abstract class CollaborationState {
+    readonly unitID: string;
+    readonly type: UniverType;
+    /** State may change internally. Parent module should provide a callback to handle this event.  */
+    protected readonly _handler: ICollaborationStateHandler;
+    protected readonly _commandService: ICommandService;
+    protected readonly _undoRedoService: ICollaborativeUndoRedoService;
+    protected readonly _revisionService: RevisionService;
+    protected readonly _localCacheService: LocalCacheService;
+    abstract readonly status: CollaborationStatus;
+    /** Mutations that has been sent to the server but not yet acknowledged by the server.  */
+    protected _awaitingChangeset: Nullable<IChangeset>;
+    /** Mutations that has not been sent to the server. */
+    protected _pendingMutations: IMutationInfo[];
+    constructor(unitID: string, type: UniverType, 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: LocalCacheService);
+    abstract resend(): void;
+    /**
+     * Append a location mutation to collaboration queue.
+     *
+     * @param mutation a mutation that happened locally and should be broadcasted to other peers
+     */
+    abstract appendMutation(mutation: IMutationInfo): CollaborationState;
+    /**
+     * Received a changeset from the server.
+     * @param changeset
+     */
+    abstract onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    /**
+     * Received an acknowledgement from the server.
+     */
+    abstract onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
+    /**
+     * Received a rejection from the server, meaning that conflict could be resolved by the algorithm.
+     */
+    abstract onRemoteRej(config?: {
+        isPermissionRej: boolean;
+    }): CollaborationState;
+    /**
+     * Received a retry message from the server, meaning that some unexpected error occurred in server.
+     */
+    abstract onRemoteRetry(changeset: IChangeset): 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.
+     *
+     * @param changeset The changeset sent from the remote collaboration server.
+     * @returns There is some changeset missing.
+     */
+    protected _checkMissing(changeset: IChangeset | IAcknowledgedChangeset): boolean;
+    /** Transform undo redo mutations in the undo redo stack.  */
+    protected _transformUndoredo(changeset: IChangeset): void;
+    /** Transform selections by calling the selection manager service. */
+    protected _transformSelections(changeset: IChangeset): void;
+    protected _transformIMECache(changeset: IChangeset): void | undefined;
+    protected _transformStateCache(changeset: IChangeset): void | undefined;
+    protected _transformRemoteChangesetByIMECache(changeset: IChangeset): IChangeset;
+    protected _transformRemoteChangesetByStateCache(changeset: IChangeset): IChangeset;
+    protected _syncEditingCollabCursor(changeset: IChangeset): void;
+    /** @internal */
+    _updateLocalCache(): void;
+    protected _getCurrentRevision(): number;
+    protected _incrementRevisionNumber(): void;
+    protected _executeRemoteChangeset(changeset: IChangeset): void;
+}
+/**
+ * All local changesets are sent to and acknowledged by the server.
+ */
+export declare class SyncedState extends CollaborationState {
+    private readonly _injector;
+    private readonly _logService;
+    private readonly _transformService;
+    readonly status = CollaborationStatus.SYNCED;
+    constructor(unitID: string, type: UniverType, handler: ICollaborationStateHandler, revisionService: RevisionService, localCacheService: LocalCacheService, _injector: Injector, undoRedoService: ICollaborativeUndoRedoService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService);
+    appendMutation(mutation: IMutationInfo): CollaborationState;
+    onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    private _onConflict;
+    onRemoteAck(): never;
+    onRemoteRej(): CollaborationState;
+    onRemoteRetry(): CollaborationState;
+    toggleOffline(): CollaborationState;
+    toggleOnline(): CollaborationState;
+    resend(): void;
+    fetchMiss(): CollaborationState;
+}
+/**
+ * Some local changes are waiting to be sent to the server. But no changesets are waiting for acknowledgement.
+ *
+ * You should call schedule task after you create a `PendingState`.
+ */
+export declare class PendingState extends CollaborationState {
+    private readonly _injector;
+    private readonly _memberService;
+    private readonly _logService;
+    private readonly _configService;
+    private readonly _transformService;
+    private readonly _univerInstanceService;
+    readonly status = CollaborationStatus.PENDING;
+    private _scheduleTimestamp;
+    private _sendingTimer;
+    constructor(unitID: string, type: UniverType, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, _injector: Injector, _revisionService: RevisionService, _localCacheService: LocalCacheService, _memberService: MemberService, _logService: ILogService, commandService: ICommandService, _configService: IConfigService, _transformService: ITransformService, _univerInstanceService: IUniverInstanceService, _undoRedoService: ICollaborativeUndoRedoService);
+    appendMutation(mutation: IMutationInfo): CollaborationState;
+    onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    onRemoteAck(): CollaborationState;
+    onRemoteRej(): CollaborationState;
+    onRemoteRetry(): CollaborationState;
+    toggleOffline(): CollaborationState;
+    toggleOnline(): CollaborationState;
+    /**
+     * Schedule a task to send changeset to the server.
+     *
+     * @internal
+     */
+    _schedule(t?: number): void;
+    private _getSendChangesetTimeout;
+    resend(): void;
+    private _clearScheduledTask;
+    private _onConflict;
+}
+/**
+ * All local mutations are sent to the server and waiting for acknowledgement.
+ */
+export declare class AwaitingState extends CollaborationState {
+    private readonly _injector;
+    private readonly _logService;
+    private readonly _transformService;
+    readonly status = CollaborationStatus.AWAITING;
+    private _resendTimeout;
+    private _resendTimer;
+    private _sender;
+    constructor(unitID: string, type: UniverType, awaitingChangeset: IChangeset, handler: ICollaborationStateHandler, _injector: Injector, revisionService: RevisionService, localCacheService: LocalCacheService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, undoRedoService: ICollaborativeUndoRedoService);
+    appendMutation(mutation: IMutationInfo): CollaborationState;
+    onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
+    onRemoteRej(config?: {
+        isPermissionRej: boolean;
+    }): CollaborationState;
+    onRemoteRetry(changeset: IChangeset): CollaborationState;
+    toggleOffline(): CollaborationState;
+    toggleOnline(): CollaborationState;
+    resend(): void;
+    private _onConflict;
+    private _resendWithTimeout;
+    private _clearScheduledTask;
+}
+/**
+ * Some local mutations are sent to the server and waiting for acknowledgement, yet still some local mutations
+ * are waiting to be sent to the server.
+ */
+export declare class AwaitingWithPendingState extends CollaborationState {
+    private readonly _injector;
+    private readonly _logService;
+    private readonly _transformService;
+    readonly status = CollaborationStatus.AWAITING_WITH_PENDING;
+    private _resendTimeout;
+    private _resendTimer;
+    private _sender;
+    constructor(unitID: string, type: UniverType, awaitingChangeset: IChangeset, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, timer: Observable<{
+        timeout: number;
+        reqId: number;
+    }> | undefined, _injector: Injector, revisionService: RevisionService, localCacheService: LocalCacheService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, undoRedoService: ICollaborativeUndoRedoService);
+    appendMutation(mutation: IMutationInfo): CollaborationState;
+    onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
+    onRemoteRej(config?: {
+        isPermissionRej: boolean;
+    }): CollaborationState;
+    onRemoteRetry(changeset: IChangeset): CollaborationState;
+    toggleOffline(): CollaborationState;
+    toggleOnline(): CollaborationState;
+    resend(): void;
+    private _onConflict;
+    private _resendWithTimeout;
+    private _clearScheduledTask;
+}
+/**
+ * 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.
+ */
+export declare class ConflictState extends CollaborationState {
+    private _isPermissionRej;
+    private readonly _permissionService;
+    private readonly _localeService;
+    private readonly _notificationService;
+    readonly status = CollaborationStatus.CONFLICT;
+    constructor(unitID: string, type: UniverType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, _isPermissionRej: boolean | undefined, _permissionService: IPermissionService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, localCacheService: LocalCacheService, revisionService: RevisionService, _localeService: LocaleService, _notificationService: INotificationService);
+    appendMutation(): CollaborationState;
+    onRemoteChangeset(): CollaborationState;
+    onRemoteAck(): CollaborationState;
+    onRemoteRej(): CollaborationState;
+    onRemoteRetry(): CollaborationState;
+    toggleOffline(): CollaborationState;
+    toggleOnline(): CollaborationState;
+    resend(): void;
+    private _clearLocalCache;
+    private _showConflictNotification;
+    private _disableEditing;
+}
+export declare class OfflineState extends CollaborationState {
+    private readonly _injector;
+    readonly status = CollaborationStatus.OFFLINE;
+    constructor(unitID: string, type: UniverType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, _injector: Injector, revisionService: RevisionService, localCacheService: LocalCacheService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService);
+    appendMutation(mutation: IMutationInfo): CollaborationState;
+    onRemoteChangeset(_changeset: IChangeset): CollaborationState;
+    onRemoteAck(): CollaborationState;
+    onRemoteRej(): CollaborationState;
+    onRemoteRetry(): CollaborationState;
+    toggleOffline(): CollaborationState;
+    toggleOnline(): CollaborationState;
+    resend(): void;
+}
+/**
+ * When the client is trying to fetch missed changesets:
+ *
+ * 1. local changesets would not be send to the server until the missed changesets are fetched
+ * 2. remote changesets would not be applied util the missed changesets are fetched and applied
+ */
+export declare class FetchingMissState extends CollaborationState {
+    /**
+     * The awaiting changeset may have been acknowledged when missing is detected.
+     * We need to transform missing changeset against this acknowledged changeset,
+     * so other state should pass this acknowledged changeset to this parameter.
+     */
+    private _acknowledgedAwaitingChangeset;
+    private readonly _queuedRemoteChangesets;
+    private readonly _injector;
+    private readonly _logService;
+    private readonly _transformService;
+    readonly status = CollaborationStatus.FETCH_MISS;
+    constructor(unitID: string, type: UniverType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], 
+    /**
+     * The awaiting changeset may have been acknowledged when missing is detected.
+     * We need to transform missing changeset against this acknowledged changeset,
+     * so other state should pass this acknowledged changeset to this parameter.
+     */
+    _acknowledgedAwaitingChangeset: Nullable<IChangeset>, _queuedRemoteChangesets: IChangeset[], handler: ICollaborationStateHandler, _injector: Injector, revisionService: RevisionService, localCacheService: LocalCacheService, _logService: ILogService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, _transformService: ITransformService);
+    onMissedChangesetFetched(changesets: IChangeset[]): CollaborationState;
+    resend(): void;
+    appendMutation(mutation: IMutationInfo<object>): CollaborationState;
+    onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    onRemoteAck(_changeset: IAcknowledgedChangeset): CollaborationState;
+    onRemoteRej(config?: {
+        isPermissionRej: boolean;
+    }): CollaborationState;
+    onRemoteRetry(): CollaborationState;
+    toggleOffline(): CollaborationState;
+    toggleOnline(): CollaborationState;
+    private _onConflict;
+}
+export declare function createOnlineState(injector: Injector, unitID: string, type: UniverType, awaitingChangeset: Nullable<IChangeset>, mutations: IMutationInfo[], handler: ICollaborationStateHandler): SyncedState | PendingState | AwaitingState | AwaitingWithPendingState;

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

@@ -0,0 +1,24 @@
+import { Nullable, Injector, IUniverInstanceService, RxDisposable } from '@univerjs/core';
+import { Observable } from 'rxjs';
+import { CollaborationEntity } from './collaboration-entity';
+import { CollaborationSessionService } from '../../services/collaboration-session/collaboration-session.service';
+export declare class CollaborationController extends RxDisposable {
+    private readonly _injector;
+    private readonly _collabSessionService;
+    private readonly _univerInstanceService;
+    private readonly _entities;
+    private readonly _entityInit$;
+    constructor(_injector: Injector, _collabSessionService: CollaborationSessionService, _univerInstanceService: IUniverInstanceService);
+    dispose(): void;
+    getCollabEntity(id: string): Nullable<CollaborationEntity>;
+    getCollabEntity$(id: string): Observable<CollaborationEntity>;
+    private _init;
+    /**
+     * Start collaboration on a document.
+     *
+     * @param unitID ID of the document to start collaboration.
+     * @returns A disposable to stop collaboration.
+     */
+    private _startCollaboration;
+    private _getCtorByUniverType;
+}

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

@@ -0,0 +1,18 @@
+import { IMutationInfo, IUniverInstanceService } from '@univerjs/core';
+import { IChangeset, RevisionService } from '@univerjs-pro/collaboration';
+import { Observable } from 'rxjs';
+import { MemberService } from '../../../services/member/member.service';
+export interface IAssembledChangeset {
+    changeset: IChangeset;
+    pendingMutations: IMutationInfo[];
+}
+/**
+ * Mutations those should be assembled into a single changeset.
+ */
+export declare const SINGLE_CHANGESET_MUTATIONS: Set<string>;
+/**
+ * Assemble a changeset from a list of mutations.
+ */
+export declare function assembleSheetChangeset(pendingMutations: IMutationInfo[], unitID: string, univerInstanceService: IUniverInstanceService, revisionService: RevisionService, memberService: MemberService): IAssembledChangeset;
+export declare function assembleDocChangeset(pendingMutations: IMutationInfo[], unitID: string, univerInstanceService: IUniverInstanceService, revisionService: RevisionService, memberService: MemberService): IAssembledChangeset;
+export declare function createTimerObservable$<T>(ms: number, options: T): Observable<T>;

package/lib/types/controllers/collaboration/utils/empty.d.ts

@@ -0,0 +1,2 @@
+import { IMutationInfo } from '@univerjs/core';
+export declare const EmptyMutationInfo: IMutationInfo;

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

@@ -0,0 +1,33 @@
+import { Ctor, DependencyOverride } from '@univerjs/core';
+import { ICollaborationSocketService } from '../services/socket/collaboration-socket.service';
+export declare const PLUGIN_CONFIG_KEY = "collaboration-client.config";
+export declare const configSymbol: unique symbol;
+export interface IUniverCollaborationClientConfig {
+    socketService?: Ctor<ICollaborationSocketService>;
+    enableOfflineEditing?: boolean;
+    enableSingleActiveInstanceLock?: boolean;
+    enableAuthServer?: boolean;
+    /**
+     * Override internal modules with custom implementations.
+     */
+    override?: DependencyOverride;
+    sendChangesetTimeout?: number;
+    snapshotServerUrl?: string;
+    collabSubmitChangesetUrl?: string;
+    collabWebSocketUrl?: string;
+    /**
+     * The URL of the endpoint for getting the websocket session ticket.
+     */
+    wsSessionTicketUrl?: string;
+    loginUrlKey?: string;
+    retryConnectingInterval?: number;
+    authzUrl?: string;
+    /**
+     * The URL of the endpoint for downloading files.
+     * @default 'location.origin'
+     */
+    downloadEndpointUrl?: string;
+    uploadFileServerUrl?: string;
+    signUrlServerUrl?: string;
+}
+export declare const defaultPluginConfig: IUniverCollaborationClientConfig;

package/lib/types/controllers/data-loader/__tests__/data-loader.controller.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/controllers/data-loader/data-loader.controller.d.ts

@@ -0,0 +1,22 @@
+import { ICommandService, ILogService, RxDisposable } from '@univerjs/core';
+import { IRemoteInstanceService } from '@univerjs/rpc';
+import { SnapshotService } from '@univerjs-pro/collaboration';
+import { LocalCacheService } from '../../services/local-cache/local-cache.service';
+import { IURLService } from '../../services/url/url.service';
+/**
+ * This controller loads data when URL changes.
+ */
+export declare class DataLoaderController extends RxDisposable {
+    private _urlService;
+    private readonly _logService;
+    private readonly _commandService;
+    private readonly _localCacheService;
+    private readonly _snapshotService;
+    constructor(_urlService: IURLService, _logService: ILogService, _commandService: ICommandService, _localCacheService: LocalCacheService, _snapshotService: SnapshotService, remoteInstanceService?: IRemoteInstanceService);
+    private _init;
+    private _setupSubUnitSync;
+    private _updateURLWithCurrentState;
+    private _updateSubUnitFromURLParams;
+    private _loadSheet;
+    private _loadDoc;
+}

package/lib/types/controllers/file-name/file-name.controller.d.ts

@@ -0,0 +1,12 @@
+import { Disposable, IConfigService, IUniverInstanceService } from '@univerjs/core';
+export declare const DEFAULT_FILE_NAME_KEY = "DEFAULT_FILE_NAME";
+/**
+ * This controller would change the current tab's title to the
+ * currently focused unit's name.
+ */
+export declare class FileNameController extends Disposable {
+    private readonly _univerInstanceService;
+    private readonly _configService;
+    constructor(_univerInstanceService: IUniverInstanceService, _configService: IConfigService);
+    private _init;
+}

package/lib/types/controllers/telemetry.d.ts

@@ -0,0 +1,11 @@
+import { IMutationInfo, UniverInstanceType } from '@univerjs/core';
+export declare const TELEMETRY_COLLABORATION_NEW_CHANGESET = "collaboration_new_changeset";
+export interface INewChangesetTelemetryInfo {
+    startTime: number;
+    stopTime: number;
+    duration: number;
+    size: number;
+    type: UniverInstanceType;
+    unitId: string;
+}
+export declare function summaryChangesetSize(mutations: IMutationInfo[]): number;