feat(client): processing during CatchingUp ConnectionState

[jason-ha]

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

[Copilot]

Pull Request Overview

This PR introduces a new setConnectionStatus method on IRuntime that provides more granular connection state information, including support for CatchingUp and EstablishingConnection states. The new method deprecates the existing setConnectionState method while maintaining backwards compatibility. Key changes include:

• Added setConnectionStatus method to IRuntime with connection status interfaces for all connection states
• Implemented signal-based audience for faster connection state updates during CatchingUp
• Renamed "connectionTypeChanged" event to "operabilityChanged" in Container Extensions for clarity

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/runtime/container-runtime/src/containerRuntime.ts	Implements new setConnectionStatus method, handles CatchingUp state, renames event to "operabilityChanged"
packages/runtime/container-runtime/src/test/containerRuntime.extensions.spec.ts	Updates tests for renamed event and adds signalAudience simulation support
packages/runtime/container-runtime-definitions/src/containerExtension.ts	Documents JoinedStatus states and renames "connectionTypeChanged" to "operabilityChanged"
packages/runtime/container-runtime-definitions/src/index.ts	Exports new JoinedStatus type variants
packages/common/container-definitions/src/runtime.ts	Defines ConnectionStatus interfaces and adds setConnectionStatus to IRuntime
packages/common/container-definitions/src/index.ts	Exports new ConnectionStatus types
packages/loader/container-loader/src/container.ts	Implements setConnectionStatus calling logic with backwards compatibility for older runtimes
packages/loader/container-loader/src/containerContext.ts	Adds signalAudience property
packages/loader/container-loader/src/protocol.ts	Implements wrapProtocolHandlerBuilder for signal-based audience
packages/loader/container-loader/src/test/loader.spec.ts	Adds test for IRuntime without setConnectionStatus
packages/loader/container-loader/src/test/testProxies.ts	Adds support for testing runtime without setConnectionStatus
packages/common/container-definitions/api-report/container-definitions.legacy.beta.api.md	Updates API surface with new ConnectionStatus types

[WillieHabi]

LGTM. Left one comment about canSendOpsChanged when transitioning to CatchingUp status

[WillieHabi]

Can this just be false? AFAIK the ability to send ops doesn't change when transitioning to CatchingUp

[jason-ha]

Probably. But I don't see a reason to mess with the state machine. If it was true in some case we aren't thinking about then this would be accurate. Perhaps some funny transition from write-client going back to CatchingUp when becoming a read-only client.

[WillieHabi]

nit: Do we need this attribute? I don't see it used when passed into setConnectionStatus in this PR

[jason-ha]

It is more informational than anything else. If someone were trying to track client id information through the transitions this would be good to know.

[github-actions]

🔗 Found some broken links! 💔

Run a link check locally to find them. See
https://github.com/microsoft/FluidFramework/wiki/Checking-for-broken-links-in-the-documentation for more information.

linkcheck output

> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

 ELIFECYCLE  Command failed with exit code 1.

[anthony-murphy]

it seems odd that we never re-signal if and when canSendOps changes? specifically if readonly becomes false? Overall, i find these kinds of composed values difficult to reason about in the current design where each value is separate, as it seem like a consumer still needs to understand the internals of canSendOps, so they know to track readonly, and only then can they figure out if they can actually send ops or not.

I don't know what the right solution to the above problem is, but i think it need some solution. A couple ideas

• do not compose into canSendOps but just call this readonly which to me makes it clear i also need to track the read-only signal
• send this combined signal on both connection and readonly status change

my preference is to not compose into canSendOps, and just expose readonly. we could add a free function to container utils that takes ConnectionStatusTemplate can computes canSendOPs.

[jason-ha]

We do signal changes of canSendOps. See emitServiceConnectionEvents implementation and calls. In test code look at case "should handle connection type changes".
Additionally, you can look at #25751 which uses this new support fully.

[anthony-murphy]

are you saying when readonly state changes we trigger a connection state change with the updated canSendOps? I don't see code that does that, but it could just be missing it.

[anthony-murphy]

the call i see to emitServiceConnectionEvents only occurs on setConnectionStatus which i don't believe is called readonly changes

[jason-ha]

From my read of the code ContainerRuntime maintains canSendOps exclusively through setConnectionStateCore. At the end of that method is call to emitServiceConnectionEvents which will notify for a change in canSendOps whether from readonly or other reasons.
(started Teams chat for efficient discussion)

[WillieHabi]

In container.ts:

deltaManager.on("readonly", (readonly) => {
			if (this.loaded) {
				this.setConnectionStatus(readonly);
			}
			this.emit("readonly", readonly);
});

[jason-ha]

Per discussion we will follow up with a break-out of readonly explicitly in the new connection status object. That will help is stay distinct from canSendOp (that will still always be false if readonly is true). We can also extend it overtime to add more things of interest.