Add connect(), disconnect(), deprecate setAutoReconnect(), resume(), and connected

api-report/container-loader.api.md

@@ -67,12 +67,16 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
     // (undocumented)
     get closed(): boolean;
     // (undocumented)
+    connect(): void;
+    // (undocumented)
     get connected(): boolean;
     // (undocumented)
     get connectionState(): ConnectionState;
     static createDetached(loader: Loader, codeDetails: IFluidCodeDetails): Promise<Container>;
     // (undocumented)
     get deltaManager(): IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
+    // (undocumented)
+    disconnect(): void;
     forceReadonly(readonly: boolean): void;
     // (undocumented)
     getAbsoluteUrl(relativeUrl: string): Promise<string | undefined>;

api-report/fluid-static.api.md

@@ -18,6 +18,16 @@ import { IFluidDataStoreFactory } from '@fluidframework/runtime-definitions';
 import { IFluidLoadable } from '@fluidframework/core-interfaces';
 import { TypedEventEmitter } from '@fluidframework/common-utils';
 
+// @public
+export namespace ConnectionState {
+    export type Connected = 2;
+    export type Connecting = 1;
+    export type Disconnected = 0;
+}
+
+// @public
+export type ConnectionState = ConnectionState.Disconnected | ConnectionState.Connecting | ConnectionState.Connected;
+
 // @public
 export interface ContainerSchema {
     dynamicObjectTypes?: LoadableObjectClass<any>[];
@@ -42,6 +52,7 @@ export class FluidContainer extends TypedEventEmitter<IFluidContainerEvents> imp
     attach(): Promise<string>;
     get attachState(): AttachState;
     get connected(): boolean;
+    get connectionState(): ConnectionState;
     create<T extends IFluidLoadable>(objectClass: LoadableObjectClass<T>): Promise<T>;
     dispose(): void;
     get disposed(): boolean;
@@ -59,7 +70,9 @@ export interface IConnection {
 export interface IFluidContainer extends IEventProvider<IFluidContainerEvents> {
     attach(): Promise<string>;
     readonly attachState: AttachState;
+    // @deprecated
     readonly connected: boolean;
+    readonly connectionState: ConnectionState;
     create<T extends IFluidLoadable>(objectClass: LoadableObjectClass<T>): Promise<T>;
     dispose(): void;
     readonly disposed: boolean;

common/lib/container-definitions/api-report/container-definitions.api.md

@@ -134,9 +134,12 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
     close(error?: ICriticalContainerError): void;
     closeAndGetPendingLocalState(): string;
     readonly closed: boolean;
+    connect?(): void;
+    // @deprecated
     readonly connected: boolean;
     readonly connectionState: ConnectionState;
     deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
+    disconnect?(): void;
     // @alpha
     forceReadonly?(readonly: boolean): any;
     getAbsoluteUrl(relativeUrl: string): Promise<string | undefined>;
@@ -148,10 +151,10 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
     readonly readOnlyInfo: ReadOnlyInfo;
     request(request: IRequest): Promise<IResponse>;
     resolvedUrl: IResolvedUrl | undefined;
-    // @alpha
+    // @deprecated
     resume?(): void;
     serialize(): string;
-    // @alpha
+    // @deprecated
     setAutoReconnect?(reconnect: boolean): void;
 }
 

common/lib/container-definitions/src/loader.ts

@@ -252,20 +252,37 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
 
     /**
      * Boolean indicating whether the container is currently connected or not
+     * @deprecated - 0.58, This API will be removed in 0.60
+     * Use `connectionState` instead
+     * See https://github.com/microsoft/FluidFramework/issues/9167 for context
      */
     readonly connected: boolean;
 
+    /**
+     * Try to connect the container to the delta stream
+     */
+    connect?(): void;
+
+    /**
+     * Disconnect the container from the delta stream
+     */
+    disconnect?(): void;
+
     /**
      * Dictates whether or not the current container will automatically attempt to reconnect to the delta stream
      * after receiving a disconnect event
      * @param reconnect - Boolean indicating if reconnect should automatically occur
-     * @alpha
+     * @deprecated - 0.58.1, This API will be removed in 0.59.0
+     * Use `connect()` and `disconnect()` instead
+     * See https://github.com/microsoft/FluidFramework/issues/9167 for context
      */
     setAutoReconnect?(reconnect: boolean): void;
 
     /**
      * Have the container attempt to resume processing ops
-     * @alpha
+     * @deprecated - 0.58.1, This API will be removed in 0.59.0
+     * Use `connect()` instead
+     * See https://github.com/microsoft/FluidFramework/issues/9167 for context
      */
     resume?(): void;
 

packages/framework/fluid-static/src/fluidContainer.ts

@@ -67,16 +67,49 @@ export interface IFluidContainerEvents extends IEvent {
     (event: "connected" | "dispose" | "disconnected" | "saved" | "dirty", listener: () => void): void;
 }
 
+/**
+ * Namespace for the different connection states a container can be in
+ */
+ export namespace ConnectionState {
+    /**
+     * The document is no longer connected to the delta server
+     */
+    export type Disconnected = 0;
+
+    /**
+     * The document has an inbound connection but is still pending for outbound deltas
+     */
+    export type Connecting = 1;
+
+    /**
+     * The document is fully connected
+     */
+     export type Connected = 2;
+}
+
+/**
+ * Type defining the different states of connectivity a container can be in
+ */
+export type ConnectionState = ConnectionState.Disconnected | ConnectionState.Connecting | ConnectionState.Connected;
+
 /**
  * The IFluidContainer provides an entrypoint into the client side of collaborative Fluid data.  It provides access
  * to the data as well as status on the collaboration session.
  */
 export interface IFluidContainer extends IEventProvider<IFluidContainerEvents> {
     /**
      * Whether the container is connected to the collaboration session.
+     * @deprecated - 0.58.1, This API will be removed in 0.59.0
+     * Use `connectionState` instead
+     * See https://github.com/microsoft/FluidFramework/issues/9167 for context
      */
     readonly connected: boolean;
 
+    /**
+     * Provides the current connected state of the container
+     */
+    readonly connectionState: ConnectionState;
+
      /**
      * A container is considered **dirty** if it has local changes that have not yet been acknowledged by the service.
      * You should always check the `isDirty` flag before closing the container or navigating away from the page.
@@ -184,6 +217,13 @@ export class FluidContainer extends TypedEventEmitter<IFluidContainerEvents> imp
         return this.container.connected;
     }
 
+    /**
+     * {@inheritDoc IFluidContainer.connectionState}
+     */
+     public get connectionState(): ConnectionState {
+        return this.container.connectionState;
+    }
+
     /**
      * {@inheritDoc IFluidContainer.initialObjects}
      */

packages/loader/container-loader/src/container.ts

@@ -935,6 +935,78 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         }
     }
 
+    public connect() {
+        if (!this.closed && !this.connected) {
+            // Note: no need to fetch ops as we do it preemptively as part of DeltaManager.attachOpHandler().
+            // If there is gap, we will learn about it once connected, but the gap should be small (if any),
+            // assuming that connect() is called quickly after initial container boot.
+            this.connectInternal({ reason: "DocumentOpenResume", fetchOpsFromStorage: false });
+        }
+    }
+
+    private connectInternal(args: IConnectionArgs) {
+        assert(!this.closed, "Attempting to connect() a closed DeltaManager");
+
+        // Resume processing ops
+        if (!this.resumedOpProcessingAfterLoad) {
+            this.resumedOpProcessingAfterLoad = true;
+            this._deltaManager.inbound.resume();
+            this._deltaManager.inboundSignal.resume();
+        }
+
+        // Ensure connection to web socket
+        this.connectToDeltaStream(args);
+
+        const mode = ReconnectMode.Enabled;
+        const currentMode = this._deltaManager.connectionManager.reconnectMode;
+
+        // Set Auto Reconnect Mode
+        if (currentMode !== mode) {
+            const now = performance.now();
+            const duration = now - this.setAutoReconnectTime;
+            this.setAutoReconnectTime = now;
+
+            this.mc.logger.sendTelemetryEvent({
+                eventName: "AutoReconnectEnabled",
+                connectionMode: this.connectionMode,
+                connectionState: ConnectionState[this.connectionState],
+                duration,
+            });
+
+            this._deltaManager.connectionManager.setAutoReconnect(mode);
+        }
+    }
+
+    public disconnect() {
+        if (!this.closed && this.connected) {
+            this.disconnectInternal();
+        }
+    }
+
+    private disconnectInternal() {
+        assert(!this.closed, "Attempting to disconnect() a closed DeltaManager");
+
+        const mode = ReconnectMode.Disabled;
+        const currentMode = this._deltaManager.connectionManager.reconnectMode;
+
+        // Set Auto Reconnect Mode
+        if (currentMode !== mode) {
+            const now = performance.now();
+            const duration = now - this.setAutoReconnectTime;
+            this.setAutoReconnectTime = now;
+
+            this.mc.logger.sendTelemetryEvent({
+                eventName: "AutoReconnectDisabled",
+                connectionMode: this.connectionMode,
+                connectionState: ConnectionState[this.connectionState],
+                duration,
+            });
+
+            // ConnectionManager will handle disconnecting the container
+            this._deltaManager.connectionManager.setAutoReconnect(mode);
+        }
+    }
+
     public resume() {
         if (!this.closed) {
             // Note: no need to fetch ops as we do it preemptively as part of DeltaManager.attachOpHandler().