feat(client): processing during CatchingUp ConnectionState (#25750)

`IRuntime` now has an optional (preferred) `setConnectionStatus` method
that replaces the previous `setConnectionState` method (still required
for compatibility). The new method is called for all `ConnectionState`
changes, including `CatchingUp` and `EstablishingConnection`. Calls may
also be made when readonly state changes, even if there is no overall
change in connection status.

`ContainerRuntime` announces fewer "disconnected" events when a client
is not fully connected and the readonly state changes.

And add case to test missing setConnectionStatus while making its
presence the default.

Add internal Signal only based Audience that can be used while
CatchingUp.

For Container Extensions:
- rename "connectionTypeChanged" event to "operabilityChanged" to allow
for later move to operate during CatchingUp
- Document JoinedStatus states

Author: jason-ha

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

@@ -26,6 +26,52 @@ export namespace ConnectionState {
 // @public
 export type ConnectionState = ConnectionState.Disconnected | ConnectionState.EstablishingConnection | ConnectionState.CatchingUp | ConnectionState.Connected;
 
+// @beta @sealed @legacy
+export type ConnectionStatus = ConnectionStatusEstablishingConnection | ConnectionStatusCatchingUp | ConnectionStatusConnected | ConnectionStatusDisconnected;
+
+// @beta @sealed @legacy
+export interface ConnectionStatusCatchingUp extends ConnectionStatusTemplate {
+    // (undocumented)
+    canSendOps: false;
+    // (undocumented)
+    connectionState: ConnectionState.CatchingUp;
+    pendingClientConnectionId: string;
+}
+
+// @beta @sealed @legacy
+export interface ConnectionStatusConnected extends ConnectionStatusTemplate {
+    // (undocumented)
+    canSendOps: boolean;
+    clientConnectionId: string;
+    // (undocumented)
+    connectionState: ConnectionState.Connected;
+}
+
+// @beta @sealed @legacy
+export interface ConnectionStatusDisconnected extends ConnectionStatusTemplate {
+    // (undocumented)
+    canSendOps: false;
+    // (undocumented)
+    connectionState: ConnectionState.Disconnected;
+    priorConnectedClientConnectionId: string | undefined;
+    priorPendingClientConnectionId: string | undefined;
+}
+
+// @beta @sealed @legacy
+export interface ConnectionStatusEstablishingConnection extends ConnectionStatusTemplate {
+    // (undocumented)
+    canSendOps: false;
+    // (undocumented)
+    connectionState: ConnectionState.EstablishingConnection;
+}
+
+// @beta @sealed @legacy
+export interface ConnectionStatusTemplate {
+    canSendOps: boolean;
+    // (undocumented)
+    connectionState: ConnectionState;
+}
+
 // @beta @legacy
 export const ContainerErrorTypes: {
     readonly clientSessionExpiredError: "clientSessionExpiredError";
@@ -157,6 +203,8 @@ export interface IContainerContext {
     // (undocumented)
     readonly quorum: IQuorumClients;
     readonly scope: FluidObject;
+    // @system
+    readonly signalAudience?: IAudience;
     readonly snapshotWithContents?: ISnapshot;
     // (undocumented)
     readonly storage: IContainerStorageService;
@@ -421,6 +469,7 @@ export interface IRuntime extends IDisposable {
     processSignal(message: any, local: boolean): any;
     setAttachState(attachState: AttachState.Attaching | AttachState.Attached): void;
     setConnectionState(canSendOps: boolean, clientId?: string): any;
+    setConnectionStatus?(status: ConnectionStatus): void;
 }
 
 // @beta @legacy (undocumented)

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

@@ -59,6 +59,12 @@ export {
 	isFluidCodeDetails,
 } from "./fluidPackage.js";
 export type {
+	ConnectionStatus,
+	ConnectionStatusCatchingUp,
+	ConnectionStatusConnected,
+	ConnectionStatusDisconnected,
+	ConnectionStatusEstablishingConnection,
+	ConnectionStatusTemplate,
 	IBatchMessage,
 	IContainerContext,
 	IProvideRuntimeFactory,

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

@@ -57,6 +57,92 @@ export enum AttachState {
 	Attached = "Attached",
 }
 
+/**
+ * Defines the connection status of the container.
+ *
+ * @legacy @beta
+ * @sealed
+ */
+export interface ConnectionStatusTemplate {
+	connectionState: ConnectionState;
+	/**
+	 * True if the runtime is currently allowed to send ops.
+	 */
+	canSendOps: boolean;
+}
+
+/**
+ * Status for an establishing connection.
+ *
+ * @legacy @beta
+ * @sealed
+ */
+export interface ConnectionStatusEstablishingConnection extends ConnectionStatusTemplate {
+	connectionState: ConnectionState.EstablishingConnection;
+	canSendOps: false;
+}
+
+/**
+ * Status for an in-progress connection that is catching up to latest op state.
+ *
+ * @legacy @beta
+ * @sealed
+ */
+export interface ConnectionStatusCatchingUp extends ConnectionStatusTemplate {
+	connectionState: ConnectionState.CatchingUp;
+	/**
+	 * The ID of the client connection that is connecting.
+	 */
+	pendingClientConnectionId: string;
+	canSendOps: false;
+}
+
+/**
+ * Status for a full connection.
+ *
+ * @legacy @beta
+ * @sealed
+ */
+export interface ConnectionStatusConnected extends ConnectionStatusTemplate {
+	connectionState: ConnectionState.Connected;
+	/**
+	 * The ID of the client connection that is connected.
+	 */
+	clientConnectionId: string;
+	canSendOps: boolean;
+}
+
+/**
+ * Status for a disconnected connection.
+ *
+ * @legacy @beta
+ * @sealed
+ */
+export interface ConnectionStatusDisconnected extends ConnectionStatusTemplate {
+	connectionState: ConnectionState.Disconnected;
+	canSendOps: false;
+	/**
+	 * The ID of the client connection that was most recently connecting (catching up).
+	 */
+	priorPendingClientConnectionId: string | undefined;
+	/**
+	 * The ID of the client connection that was most recently connected.
+	 */
+	priorConnectedClientConnectionId: string | undefined;
+}
+
+/**
+ * Connection status of the container.
+ *
+ * @legacy @beta
+ * @sealed
+ */
+export type ConnectionStatus =
+	| ConnectionStatusEstablishingConnection
+	| ConnectionStatusCatchingUp
+	| ConnectionStatusConnected
+	| ConnectionStatusDisconnected;
+
 /**
  * The IRuntime represents an instantiation of a code package within a Container.
  * Primarily held by the ContainerContext to be able to interact with the running instance of the Container.
@@ -68,9 +154,24 @@ export interface IRuntime extends IDisposable {
 	 * Notifies the runtime of a change in the connection state
 	 * @param canSendOps - true if the runtime is allowed to send ops
 	 * @param clientId - the ID of the client that is connecting or disconnecting
+	 *
+	 * @remarks
+	 * This is deprecated when used with `@fluidframework/container-loader` v2.63
+	 * and later. Implement {@link IRuntime.setConnectionStatus}. Then this method
+	 * will not be called, when using newer container-loader.
+	 *
+	 * Note: when {@link IRuntime.setConnectionStatus} is implemented, there will
+	 * not be a call exactly when Container loads as happens currently without it.
 	 */
 	setConnectionState(canSendOps: boolean, clientId?: string);
 
+	/**
+	 * Notifies the runtime of a change in the connection state.
+	 *
+	 * @remarks This supersedes {@link IRuntime.setConnectionState}.
+	 */
+	setConnectionStatus?(status: ConnectionStatus): void;
+
 	/**
 	 * Processes the given op (message)
 	 * @param message - delta message received from the server
@@ -273,6 +374,16 @@ export interface IContainerContext {
 	readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
 	readonly quorum: IQuorumClients;
 	readonly audience: IAudience;
+	/**
+	 * Signal-based audience provides a view of the audience that only relies
+	 * on system signals which will be updated more quickly than
+	 * {@link IContainerContext#audience} that relies on ops for write clients.
+	 * Being signal-based the write members are inherently less reliable than
+	 * {@link IContainerContext#audience}.
+	 *
+	 * @system
+	 */
+	readonly signalAudience?: IAudience;
 	readonly loader: ILoader;
 	// The logger implementation, which would support tagged events, should be provided by the loader.
 	readonly taggedLogger: ITelemetryBaseLogger;