feat(container-extensions): true connection status for read and write clients (#24981)

## Description 

Fixes
[AB#17920](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/17920)

Currently, `isConnected` for container extensions tells us when the
local client is able to send ops. This is does not represent the true
connection state for read clients, since they can be connected to
service while still unable to send ops. This definiton of 'connected' is
too restrictive for a signal-based container extension like Presence,
since read clients should be considered 'connected' when they are able
to send signals.

To fix this, we pass container connection state to runtime to
circumevent the lie in `Container.setContextConnectedState`, and for
container extensions we replace`isConnected` with `getJoinedStatus`
which can either be "joinedForReading", "joinedForWriting", or
"disconnected". This way container extensions such as Presence are able
to know when there is an active connection to service even in readonly
mode.

---------

Co-authored-by: Copilot <[email protected]>

Author: WillieHabi

packages/common/container-definitions/api-report/container-definitions.beta.api.md

@@ -13,10 +13,14 @@ export enum AttachState {
 
 // @public
 export namespace ConnectionState {
-    export type CatchingUp = 1;
-    export type Connected = 2;
-    export type Disconnected = 0;
-    export type EstablishingConnection = 3;
+    const Disconnected = 0;
+    export type CatchingUp = typeof CatchingUp;
+    const EstablishingConnection = 3;
+    export type Connected = typeof Connected;
+    const CatchingUp = 1;
+    export type Disconnected = typeof Disconnected;
+    const Connected = 2;
+    export type EstablishingConnection = typeof EstablishingConnection;
 }
 
 // @public

packages/common/container-definitions/api-report/container-definitions.legacy.alpha.api.md

@@ -13,10 +13,14 @@ export enum AttachState {
 
 // @public
 export namespace ConnectionState {
-    export type CatchingUp = 1;
-    export type Connected = 2;
-    export type Disconnected = 0;
-    export type EstablishingConnection = 3;
+    const Disconnected = 0;
+    export type CatchingUp = typeof CatchingUp;
+    const EstablishingConnection = 3;
+    export type Connected = typeof Connected;
+    const CatchingUp = 1;
+    export type Disconnected = typeof Disconnected;
+    const Connected = 2;
+    export type EstablishingConnection = typeof EstablishingConnection;
 }
 
 // @public
@@ -140,6 +144,7 @@ export interface IContainerContext {
     // (undocumented)
     readonly disposeFn?: (error?: ICriticalContainerError) => void;
     getAbsoluteUrl?(relativeUrl: string): Promise<string | undefined>;
+    readonly getConnectionState?: () => ConnectionState;
     // (undocumented)
     getLoadedFromVersion(): IVersion | undefined;
     // @deprecated

packages/common/container-definitions/api-report/container-definitions.legacy.public.api.md

@@ -13,10 +13,14 @@ export enum AttachState {
 
 // @public
 export namespace ConnectionState {
-    export type CatchingUp = 1;
-    export type Connected = 2;
-    export type Disconnected = 0;
-    export type EstablishingConnection = 3;
+    const Disconnected = 0;
+    export type CatchingUp = typeof CatchingUp;
+    const EstablishingConnection = 3;
+    export type Connected = typeof Connected;
+    const CatchingUp = 1;
+    export type Disconnected = typeof Disconnected;
+    const Connected = 2;
+    export type EstablishingConnection = typeof EstablishingConnection;
 }
 
 // @public

packages/common/container-definitions/api-report/container-definitions.public.api.md

@@ -13,10 +13,14 @@ export enum AttachState {
 
 // @public
 export namespace ConnectionState {
-    export type CatchingUp = 1;
-    export type Connected = 2;
-    export type Disconnected = 0;
-    export type EstablishingConnection = 3;
+    const Disconnected = 0;
+    export type CatchingUp = typeof CatchingUp;
+    const EstablishingConnection = 3;
+    export type Connected = typeof Connected;
+    const CatchingUp = 1;
+    export type Disconnected = typeof Disconnected;
+    const Connected = 2;
+    export type EstablishingConnection = typeof EstablishingConnection;
 }
 
 // @public

packages/common/container-definitions/src/index.ts

@@ -29,7 +29,6 @@ export { isIDeltaManagerFull } from "./deltas.js";
 export type { ContainerWarning, ICriticalContainerError } from "./error.js";
 export { ContainerErrorTypes } from "./error.js";
 export type {
-	ConnectionState,
 	ICodeDetailsLoader,
 	IContainer,
 	IContainerEvents,
@@ -45,7 +44,7 @@ export type {
 	IResolvedFluidCodeDetails,
 	ISnapshotTreeWithBlobContents,
 } from "./loader.js";
-export { LoaderHeader } from "./loader.js";
+export { ConnectionState, LoaderHeader } from "./loader.js";
 export type { IFluidModule } from "./fluidModule.js";
 export type {
 	IFluidPackage,

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

@@ -283,26 +283,42 @@ export namespace ConnectionState {
 	 * or may remain disconnected until explicitly told to connect.
 	 * @public
 	 */
-	export type Disconnected = 0;
+	export const Disconnected = 0;
+	/**
+	 * {@inheritdoc @fluidframework/container-definitions#(ConnectionState:namespace).(Disconnected:variable)}
+	 */
+	export type Disconnected = typeof Disconnected;
 
 	/**
 	 * The container is disconnected but actively trying to establish a new connection.
 	 * PLEASE NOTE that this numerical value falls out of the order you may expect for this state.
 	 * @public
 	 */
-	export type EstablishingConnection = 3;
+	export const EstablishingConnection = 3;
+	/**
+	 * {@inheritdoc @fluidframework/container-definitions#(ConnectionState:namespace).(EstablishingConnection:variable)}
+	 */
+	export type EstablishingConnection = typeof EstablishingConnection;
 
 	/**
 	 * The container has an inbound connection only, and is catching up to the latest known state from the service.
 	 * @public
 	 */
-	export type CatchingUp = 1;
+	export const CatchingUp = 1;
+	/**
+	 * {@inheritdoc @fluidframework/container-definitions#(ConnectionState:namespace).(CatchingUp:variable)}
+	 */
+	export type CatchingUp = typeof CatchingUp;
 
 	/**
 	 * The container is fully connected and syncing.
 	 * @public
 	 */
-	export type Connected = 2;
+	export const Connected = 2;
+	/**
+	 * {@inheritdoc @fluidframework/container-definitions#(ConnectionState:namespace).(Connected:variable)}
+	 */
+	export type Connected = typeof Connected;
 }
 
 /**
@@ -462,7 +478,7 @@ export interface IContainer extends IEventProvider<IContainerEvents> {
 	 *
 	 * @remarks
 	 *
-	 * {@link IContainer.connectionState} will be set to {@link (ConnectionState:namespace).Connected}, and the
+	 * {@link IContainer.connectionState} will be set to {@link (ConnectionState:namespace).(Connected:variable)}, and the
 	 * "connected" event will be fired if/when connection succeeds.
 	 */
 	connect(): void;
@@ -472,7 +488,7 @@ export interface IContainer extends IEventProvider<IContainerEvents> {
 	 *
 	 * @remarks
 	 *
-	 * {@link IContainer.connectionState} will be set to {@link (ConnectionState:namespace).Disconnected}, and the
+	 * {@link IContainer.connectionState} will be set to {@link (ConnectionState:namespace).(Disconnected:variable)}, and the
 	 * "disconnected" event will be fired when disconnection completes.
 	 */
 	disconnect(): void;
@@ -485,7 +501,7 @@ export interface IContainer extends IEventProvider<IContainerEvents> {
 	/**
 	 * The server provided ID of the client.
 	 *
-	 * Set once {@link IContainer.connectionState} is {@link (ConnectionState:namespace).Connected},
+	 * Set once {@link IContainer.connectionState} is {@link (ConnectionState:namespace).(Connected:variable)},
 	 * otherwise will be `undefined`.
 	 */
 	readonly clientId?: string | undefined;

packages/common/container-definitions/src/runtime.ts

@@ -32,7 +32,7 @@ import type {
 import type { IAudience } from "./audience.js";
 import type { IDeltaManager } from "./deltas.js";
 import type { ICriticalContainerError } from "./error.js";
-import type { ILoader } from "./loader.js";
+import type { ConnectionState, ILoader } from "./loader.js";
 
 /**
  * The attachment state of some Fluid data (e.g. a container or data store), denoting whether it is uploaded to the
@@ -272,6 +272,15 @@ export interface IContainerContext {
 	readonly storage: IContainerStorageService;
 	readonly connected: boolean;
 	readonly baseSnapshot: ISnapshotTree | undefined;
+
+	/**
+	 * Gets the current connection state of the container.
+	 *
+	 * @remarks
+	 * This provides more detailed connection state information beyond the simple boolean `connected` property.
+	 * Available starting from version 2.52.0. Property is not present in older versions.
+	 */
+	readonly getConnectionState?: () => ConnectionState;
 	/**
 	 * @deprecated Please use submitBatchFn & submitSummaryFn
 	 */

packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md

@@ -140,10 +140,14 @@ export enum ConnectionState {
 
 // @public
 export namespace ConnectionStateType {
-    export type CatchingUp = 1;
-    export type Connected = 2;
-    export type Disconnected = 0;
-    export type EstablishingConnection = 3;
+    const Disconnected = 0;
+    export type CatchingUp = typeof CatchingUp;
+    const EstablishingConnection = 3;
+    export type Connected = typeof Connected;
+    const CatchingUp = 1;
+    export type Disconnected = typeof Disconnected;
+    const Connected = 2;
+    export type EstablishingConnection = typeof EstablishingConnection;
 }
 
 // @public

packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md

@@ -60,10 +60,14 @@ export enum ConnectionState {
 
 // @public
 export namespace ConnectionStateType {
-    export type CatchingUp = 1;
-    export type Connected = 2;
-    export type Disconnected = 0;
-    export type EstablishingConnection = 3;
+    const Disconnected = 0;
+    export type CatchingUp = typeof CatchingUp;
+    const EstablishingConnection = 3;
+    export type Connected = typeof Connected;
+    const CatchingUp = 1;
+    export type Disconnected = typeof Disconnected;
+    const Connected = 2;
+    export type EstablishingConnection = typeof EstablishingConnection;
 }
 
 // @public

packages/framework/fluid-framework/api-report/fluid-framework.legacy.alpha.api.md

@@ -49,10 +49,14 @@ export enum ConnectionState {
 
 // @public
 export namespace ConnectionStateType {
-    export type CatchingUp = 1;
-    export type Connected = 2;
-    export type Disconnected = 0;
-    export type EstablishingConnection = 3;
+    const Disconnected = 0;
+    export type CatchingUp = typeof CatchingUp;
+    const EstablishingConnection = 3;
+    export type Connected = typeof Connected;
+    const CatchingUp = 1;
+    export type Disconnected = typeof Disconnected;
+    const Connected = 2;
+    export type EstablishingConnection = typeof EstablishingConnection;
 }
 
 // @public