@fluidframework/container-loader 0.53.0-46105 → 0.54.1

package/src/container.ts

@@ -96,7 +96,8 @@ import {
 } from "@fluidframework/telemetry-utils";
 import { Audience } from "./audience";
 import { ContainerContext } from "./containerContext";
-import { IConnectionArgs, DeltaManager, ReconnectMode } from "./deltaManager";
+import { ReconnectMode, IConnectionManagerFactoryArgs } from "./contracts";
+import { DeltaManager, IConnectionArgs } from "./deltaManager";
 import { DeltaManagerProxy } from "./deltaManagerProxy";
 import { ILoaderOptions, Loader, RelativeLoader } from "./loader";
 import { pkgVersion } from "./packageVersion";
@@ -107,6 +108,7 @@ import { BlobOnlyStorage, ContainerStorageAdapter } from "./containerStorageAdap
 import { getSnapshotTreeFromSerializedContainer } from "./utils";
 import { QuorumProxy } from "./quorum";
 import { CollabWindowTracker } from "./collabWindowTracker";
+import { ConnectionManager } from "./connectionManager";
 
 const detachedContainerRefSeqNumber = 0;
 
@@ -169,7 +171,7 @@ export enum ConnectionState {
  *          false: storage does not provide indication of how far the client is. Container processed
  *          all the ops known to it, but it maybe still behind.
  */
-export async function waitContainerToCatchUp(container: Container) {
+export async function waitContainerToCatchUp(container: IContainer) {
     // Make sure we stop waiting if container is closed.
     if (container.closed) {
         throw new Error("Container is closed");
@@ -216,7 +218,9 @@ export async function waitContainerToCatchUp(container: Container) {
         };
         container.on(connectedEventName, callback);
 
-        container.resume();
+        // TODO: Remove null check after next release #8523
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        container.resume!();
     });
 }
 
@@ -374,7 +378,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
     }
 
     private readonly clientDetailsOverride: IClientDetails | undefined;
-    private readonly _deltaManager: DeltaManager;
+    private readonly _deltaManager: DeltaManager<ConnectionManager>;
     private service: IDocumentService | undefined;
     private readonly _audience: Audience;
 
@@ -415,6 +419,8 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         this.loader.services.options?.noopCountFrequency,
     );
 
+    private get connectionMode() { return this._deltaManager.connectionManager.connectionMode; }
+
     public get IFluidRouter(): IFluidRouter { return this; }
 
     public get resolvedUrl(): IResolvedUrl | undefined {
@@ -433,7 +439,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
      * Tracks host requiring read-only mode.
      */
     public forceReadonly(readonly: boolean) {
-        this._deltaManager.forceReadonly(readonly);
+        this._deltaManager.connectionManager.forceReadonly(readonly);
     }
 
     public get id(): string {
@@ -473,7 +479,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
      * Set once this.connected is true, otherwise undefined
      */
     public get scopes(): string[] | undefined {
-        return this._deltaManager.scopes;
+        return this._deltaManager.connectionManager.scopes;
     }
 
     public get clientDetails(): IClientDetails {
@@ -595,7 +601,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
                 protocolHandler: () => this._protocolHandler,
                 logConnectionStateChangeTelemetry: (value, oldState, reason) =>
                     this.logConnectionStateChangeTelemetry(value, oldState, reason),
-                shouldClientJoinWrite: () => this._deltaManager.shouldJoinWrite(),
+                shouldClientJoinWrite: () => this._deltaManager.connectionManager.shouldJoinWrite(),
                 maxClientLeaveWaitTime: this.loader.services.options.maxClientLeaveWaitTime,
                 logConnectionIssue: (eventName: string) => {
                     // We get here when socket does not receive any ops on "write" connection, including
@@ -915,7 +921,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
             throw new Error("Attempting to setAutoReconnect() a closed Container");
         }
         const mode = reconnect ? ReconnectMode.Enabled : ReconnectMode.Disabled;
-        const currentMode = this._deltaManager.reconnectMode;
+        const currentMode = this._deltaManager.connectionManager.reconnectMode;
 
         if (currentMode === mode) {
             return;
@@ -927,12 +933,12 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
 
         this.logger.sendTelemetryEvent({
             eventName: reconnect ? "AutoReconnectEnabled" : "AutoReconnectDisabled",
-            connectionMode: this._deltaManager.connectionMode,
+            connectionMode: this.connectionMode,
             connectionState: ConnectionState[this.connectionState],
             duration,
         });
 
-        this._deltaManager.setAutoReconnect(mode);
+        this._deltaManager.connectionManager.setAutoReconnect(mode);
 
         // If container state is not attached and resumed, then don't connect to delta stream. Also don't set the
         // manual reconnection flag to true as we haven't made the initial connection yet.
@@ -943,13 +949,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
             }
 
             // Ensure connection to web socket
-            this.connectToDeltaStream({ reason: "autoReconnect" }).catch((error) => {
-                // All errors are reported through events ("error" / "disconnected") and telemetry in DeltaManager
-                // So there shouldn't be a need to record error here.
-                // But we have number of cases where reconnects do not happen, and no errors are recorded, so
-                // adding this log point for easier diagnostics
-                this.logger.sendTelemetryEvent({ eventName: "setAutoReconnectError" }, error);
-            });
+            this.connectToDeltaStream({ reason: "autoReconnect" });
         }
     }
 
@@ -973,8 +973,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         }
 
         // Ensure connection to web socket
-        // All errors are reported through events ("error" / "disconnected") and telemetry in DeltaManager
-        this.connectToDeltaStream(args).catch(() => { });
+        this.connectToDeltaStream(args);
     }
 
     /**
@@ -1129,7 +1128,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         }
     }
 
-    private async connectToDeltaStream(args: IConnectionArgs) {
+    private connectToDeltaStream(args: IConnectionArgs) {
         this.recordConnectStartTime();
 
         // All agents need "write" access, including summarizer.
@@ -1137,7 +1136,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
             args.mode = "write";
         }
 
-        return this._deltaManager.connect(args);
+        this._deltaManager.connect(args);
     }
 
     /**
@@ -1157,8 +1156,6 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         }
         this.service = await this.serviceFactory.createDocumentService(this._resolvedUrl, this.subLogger);
 
-        let startConnectionP: Promise<IConnectionDetails> | undefined;
-
         // Ideally we always connect as "read" by default.
         // Currently that works with SPO & r11s, because we get "write" connection when connecting to non-existing file.
         // We should not rely on it by (one of them will address the issue, but we need to address both)
@@ -1173,8 +1170,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         // Start websocket connection as soon as possible. Note that there is no op handler attached yet, but the
         // DeltaManager is resilient to this and will wait to start processing ops until after it is attached.
         if (loadMode.deltaConnection === undefined) {
-            startConnectionP = this.connectToDeltaStream(connectionArgs);
-            startConnectionP.catch((error) => { });
+            this.connectToDeltaStream(connectionArgs);
         }
 
         await this.connectStorageService();
@@ -1538,16 +1534,21 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
      */
     private activeConnection() {
         return this.connectionState === ConnectionState.Connected &&
-            this._deltaManager.connectionMode === "write";
+            this.connectionMode === "write";
     }
 
     private createDeltaManager() {
-        const deltaManager: DeltaManager = new DeltaManager(
-            () => this.service,
-            this.client,
+        const serviceProvider = () => this.service;
+        const deltaManager = new DeltaManager<ConnectionManager>(
+            serviceProvider,
             ChildLogger.create(this.subLogger, "DeltaManager"),
-            this._canReconnect,
             () => this.activeConnection(),
+            (props: IConnectionManagerFactoryArgs) => new ConnectionManager(
+                serviceProvider,
+                this.client,
+                this._canReconnect,
+                ChildLogger.create(this.subLogger, "ConnectionManager"),
+                props),
         );
 
         // Disable inbound queues as Container is not ready to accept any ops until we are fully loaded!
@@ -1557,17 +1558,17 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         deltaManager.inboundSignal.pause();
 
         deltaManager.on("connect", (details: IConnectionDetails, opsBehind?: number) => {
-            this.connectionStateHandler.receivedConnectEvent(
-                this._deltaManager.connectionMode,
-                details,
-            );
-
             // Back-compat for new client and old server.
             this._audience.clear();
 
             for (const priorClient of details.initialClients ?? []) {
                 this._audience.addMember(priorClient.clientId, priorClient.client);
             }
+
+            this.connectionStateHandler.receivedConnectEvent(
+                this.connectionMode,
+                details,
+            );
         });
 
         deltaManager.on("disconnect", (reason: string) => {
@@ -1624,7 +1625,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         let checkpointSequenceNumber: number | undefined;
         let opsBehind: number | undefined;
         if (value === ConnectionState.Disconnected) {
-            autoReconnect = this._deltaManager.reconnectMode;
+            autoReconnect = this._deltaManager.connectionManager.reconnectMode;
         } else {
             if (value === ConnectionState.Connected) {
                 durationFromDisconnected = time - this.connectionTransitionTimes[ConnectionState.Disconnected];
@@ -1652,7 +1653,6 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
             durationFromDisconnected,
             reason,
             connectionInitiationReason,
-            socketDocumentId: this._deltaManager.socketDocumentId,
             pendingClientId: this.connectionStateHandler.pendingClientId,
             clientId: this.clientId,
             autoReconnect,
@@ -1660,7 +1660,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
             online: OnlineStatus[isOnline()],
             lastVisible: this.lastVisible !== undefined ? performance.now() - this.lastVisible : undefined,
             checkpointSequenceNumber,
-            ...this._deltaManager.connectionProps(),
+            ...this._deltaManager.connectionProps,
         });
 
         if (value === ConnectionState.Connected) {
@@ -1673,7 +1673,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         const logOpsOnReconnect: boolean =
             this.connectionState === ConnectionState.Connected &&
             !this.firstConnection &&
-            this._deltaManager.connectionMode === "write";
+            this.connectionMode === "write";
         if (logOpsOnReconnect) {
             this.messageCountAfterDisconnection = 0;
         }

package/src/contracts.ts

@@ -0,0 +1,156 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    ITelemetryProperties,
+} from "@fluidframework/common-definitions";
+import {
+    IDeltaQueue,
+    ReadOnlyInfo,
+    IConnectionDetails,
+} from "@fluidframework/container-definitions";
+import {
+    ConnectionMode,
+    IDocumentMessage,
+    ISequencedDocumentMessage,
+    IClientConfiguration,
+    IClientDetails,
+    ISignalMessage,
+} from "@fluidframework/protocol-definitions";
+
+export enum ReconnectMode {
+    Never = "Never",
+    Disabled = "Disabled",
+    Enabled = "Enabled",
+}
+
+/**
+ * Connection manager (implements this interface) is responsible for maintaining connection
+ * to relay service.
+ */
+export interface IConnectionManager {
+    readonly connected: boolean;
+
+    readonly clientId: string | undefined;
+
+    /** The queue of outbound delta messages */
+    readonly outbound: IDeltaQueue<IDocumentMessage[]>;
+
+    /** Details of client */
+    readonly clientDetails: IClientDetails;
+
+    /** Protocol version being used to communicate with the service */
+    readonly version: string;
+
+    /** Max message size allowed to the delta manager */
+    readonly maxMessageSize: number;
+
+    /** Service configuration provided by the service. */
+    readonly serviceConfiguration: IClientConfiguration | undefined;
+
+    readonly readOnlyInfo: ReadOnlyInfo;
+
+    // Various connectivity propetries for telemetry describing type of current connection
+    // Things like connection mode, service info, etc.
+    // Called when connection state changes (connect / disconnect)
+    readonly connectionProps: ITelemetryProperties;
+
+    // Verbose information about connection logged to telemetry in case of issues with
+    // maintaining healphy connection, including op gaps, not receiving join op in time, etc.
+    // Contains details information, like sequence numbers at connection time, initial ops info, etc.
+    readonly connectionVerboseProps: ITelemetryProperties;
+
+    /**
+     * Prepares message to be sent. Fills in clientSequenceNumber.
+     * Called only when active connection is present.
+     */
+    prepareMessageToSend(message: Omit<IDocumentMessage, "clientSequenceNumber">): IDocumentMessage | undefined;
+
+    /**
+     * Called before incomming message is processed. Incomming messages can be comming from connection,
+     * but also could come from storage.
+     * This call allows connection manager to adjust knowledge about acked ops sent on previous connection.
+     * Can be called at any time, including when there is no active connection.
+     */
+    beforeProcessingIncomingOp(message: ISequencedDocumentMessage): void;
+
+    /**
+     * Submits signal to relay service.
+     * Called only when active connection is present.
+     */
+    submitSignal(content: any): void;
+
+    /**
+     * Submits messages to relay service.
+     * Called only when active connection is present.
+     */
+    sendMessages(messages: IDocumentMessage[]): void;
+
+    /**
+     * Initiates connection to relay service (noop if already connected).
+     */
+    connect(connectionMode?: ConnectionMode): void;
+
+    /**
+     * Disposed connection manager
+     */
+    dispose(error: any): void;
+}
+
+/**
+ * This interface represents a set of callbacks provided by DeltaManager to IConnectionManager on its creation
+ * IConnectionManager instance will use them to communicate to DeltaManager abour various events.
+ */
+export interface IConnectionManagerFactoryArgs {
+    /**
+     * Called by connection manager for each incomming op. Some ops maybe delivered before
+     * connectHandler is called (initial ops on socket connection)
+     */
+    readonly incomingOpHandler: (messages: ISequencedDocumentMessage[], reason: string) => void,
+
+    /**
+     * Called by connection manager for each incoming signals.
+     * Maybe called before connectHandler is called (initial signals on socket connection)
+     */
+    readonly signalHandler: (message: ISignalMessage) => void,
+
+    /**
+     * Called when connection manager experiences delay in connecting to relay service.
+     * This can happen because client is offline, or service is busy and asks to not connect for some time.
+     * Can be called many times while not connected.
+     * Situation is considered resolved when connection is established and connectHandler is called.
+     */
+    readonly reconnectionDelayHandler: (delayMs: number, error: unknown) => void,
+
+    /**
+     * Called by connection manager whwnever critical error happens and container should be closed.
+     * Expects dispose() call in respose to this call.
+     */
+    readonly closeHandler: (error?: any) => void,
+
+    /**
+     * Called whenever connection to relay service is lost.
+     */
+    readonly disconnectHandler: (reason: string) => void,
+
+    /**
+     * Called whenever new connection to rely service is established
+     */
+    readonly connectHandler: (connection: IConnectionDetails) => void,
+
+    /**
+     * Called whenever ping/pong messages are roundtripped on connection.
+     */
+    readonly pongHandler: (latency: number) => void,
+
+    /**
+     * Called whenever connection type changes from writable to read-only or vice versa.
+     * Connection can be read-only if user has no edit permissions, or if container forced
+     * connection to be read-only.
+     * This should not be confused with "read" / "write"connection mode which is internal
+     * optimization.
+     */
+    readonly readonlyChangeHandler: (readonly?: boolean) => void,
+}