feat(container-runtime): Add default configuration #24248

scottn12 · 2025-04-03T19:35:28Z

Description

This PR adds "default configurations" to the encapsulated model. To do so, it adds compatibilityMode property to IContainerRuntimeOptions, which takes a string and represents a valid FF version. FF will automatically apply the proper version-dependent configurations based on the inputted compatibilityMode. For example, if compatibilityMode is set to "1.0.0", we will automatically disable features that are not compatible with clients running FF runtime v1.0.0 (i.e. grouped batching).

Declarative Model

The main intended audience of this PR are encapsulated model customers, since it adds new capabilities that did not previously exist in the encapsulated model. That said, these changes can also be leveraged by the declarative model as well. This PR modifies the declarative model's implementation of default configurations to leveraging the newly added compatibilityMode directly. The benefit is that we no longer need to manually maintain compatibilityModeRuntimeOptions, since the options will be automatically generated based on the inputted compatibilityMode. Aditionally, we can/do still add additional configurations to the declarative model (i.e. idCompressor being on by default) when necessary.
For declarative model users, there will be no noticeable changes to the public API surface or the behavior when inputting a compatibilityMode. The input for compatibilityMode remains restricted to "1" | "2".

Next Steps

This PR does not include "version control" changes prototyped in [Prototype]: Cross-client compat policy enforcement changes #24122. We will want to consider adding those capabilities (or similar capabilities) in a future PR.
We will add supporting documentation on how to use default configurations when adding/adjusting a new version-dependent feature.

Copilot

Copilot reviewed 13 out of 15 changed files in this pull request and generated 1 comment.

Files not reviewed (2)

packages/runtime/container-runtime/package.json: Language not supported
pnpm-lock.yaml: Language not supported

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

packages/runtime/container-runtime/src/compatUtils.ts

markfields · 2025-04-04T19:36:56Z

packages/runtime/container-runtime/src/containerRuntime.ts

+	 * For example, use "2.0.0" to set the default configuration for clients running at least the 2.0.0 version
+	 * of the FF runtime.
+	 */
+	readonly compatibilityMode?: string;


Why not name it more transparently - minVersionRequiredToCollaborate or something.

I was leaning towards compatibilityMode to stay consistent with the existing implementation in the declarative model. I'm open to other's opinions on this though

@markfields, I've thought about this a little bit more and I think I still prefer compatibilityMode for a couple reasons:

Something like minVersionRequiredToCollaborate is a bit misleading IMO. What compatibilityMode does is set the default configurations for a container runtime based on the inputted version. But if a client with compatibilityMode set to "2.0.0" tries to join a session created by a 1.x client, then the 2.x depdenet configs will be disabled by Document Schema and it will still be able to collaborate.

We have not yet implemented a "version control" mechanism that explicity requires version X to collab. For example, let's say compatibilityMode is set to "2.40.0" and a client running v2.30.0 tries to join. If there is no difference between the default configurations generated for 2.40/2.30, then they will be able to collaborate without any issue.

But if a client with compatibilityMode set to "2.0.0" tries to join a session created by a 1.x client, then the 2.x depdenet configs will be disabled by Document Schema and it will still be able to collaborate.

Oh, I thought it would be the other way around - The client running 1.x would be kicked out because it doesn't understand the features enabled by the 2.x client.

I would suggest using the word "version" somewhere in the name. "mode" doesn't convey anything meaningful anymore. It made sense when it was a simple number and it explicitly included a set of features. Now, all we are asking is for customers to specify a "version" that they want to be able to collaborate with. What happens behind the scene is something they do not need to care about.

The other thing to note that this is specifically targetting cross-client compat. So, we should ensure that it is not confused with other compatibility types.

i'm not even sure this should exist on this object, or if using compatibility mode should just produce a IContainerRuntimeOptions. I find it hard to understand the result of setting combability mode, as it really only sets defaults which could be overridden. I think just having some method like, computeCompatibleOptions(mode): IContainerRuntimeOptions, which a consumer could them choose to modify would be much clearer than all the current config mutations.

After thinking about it a bit more, I agree that compatibilityMode should probably not exist in IContainerRuntimeOptions. I'm not sure if a method like computeCompatibleOptions is the way to go, since I think it adds unnecessary steps for the average customer. Personally, I would prefer to keep the approach I took in this PR, but move compatibilityMode to LoadContainerRuntimeParams (as an optional param). One reason I like this approach is that it makes the path to making compatibilityMode a required param easier (if we choose to do so).

I experimented with moving compatibilityMode to LoadContainerRuntimeParams in this PR - #24362. If we think this is a good direction I can port the changes to this PR.

I still have quite a few questions about how consumers use this, especially around custom settings for things like mid version rollout. i'd prefer we just have a free function today, and evolve to something else over time, rather than try to do it all at once.

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

packages/runtime/container-runtime/src/compatUtils.ts

anthony-murphy · 2025-04-14T18:49:34Z

packages/runtime/container-runtime/src/compatUtils.ts

+ *
+ * TODO: This should be updated to "2.0.0" when 3.0 is released.
+ */
+export const defaultCompatibilityMode = "pre-3.0-default";


can we use something semver compatible here, could we just use today's latest version?

The reason I used a non-semver compatible version here was because I didn't want it to overlap with any actual versions. The goal is to maintain today's default configurations if compatibilityMode is not defined, but today's default configuratios are inconsistent in terms of what features are enabled/disabled and don't align with any version. For example, there is no such version where batching is enabled, and explicit schema control is disabled. So, the easiest solution IMO is to just use a "placeholder" version until 3.0 is released, then we can use actual semver versions as the default.

now that we use a list of versions below can't we just set the exact version of today to the exact values of today, and use that version as the default version?

I think the same problem still exists. The main issue is that explicitSchemaControl is disabled by default in today's code. We could potentially hardcode explicitSchemaControl to be false when no compatMode is provided, but we would still need to remove that logic when 3.0 is released. Since we will need to update defaultCompatibilityMode when 3.0 is released anyway, I figure it makes sense to have the temporary workarounds be associated with it.

Why can't this just be 2.33.0 and then add entries below to versionDependentOptionConfigMap for 2.33.0 which map for the default values right now. this also gets ride of defaultConfigsForPreFF3

Because if a customer would want to actually use 2.33.0 as their compatMode, then they would get the equivalent of defaultConfigsForPreFF3 which has explicit schema control disabled. If a customer were to use 2.32.0 or 2.34.0, then explicit schema control would be enabled

packages/runtime/container-runtime/src/compatUtils.ts

anthony-murphy · 2025-04-14T19:00:33Z

packages/runtime/container-runtime/src/compatUtils.ts

+		// Explicitly disable running Sweep in compat mode "2". Although sweep is supported in 2.x, it is disabled by default.
+		// This setting explicitly disables it to be extra safe.
+		minVersionForModernConfig: "3.0.0",
+		legacyConfig: {},
+		modernConfig: { enableGCSweep: true },


this is very confusing. compact mode isn't a concept at this layer, it is built above this. 3.0.0 isn't a release version, so why is it necessary for the minVersionForModernConfig to be "3.0.0"?

i think my above comment fixes this: https://github.com/microsoft/FluidFramework/pull/24248/files#r2042841307

@markfields @agarwal-navin helped inform what version to use for minVersionForModernConfig. In this case it's not "minimum version that can understand this feature", but more "minimum compatibilityMode that we want this feature to be enabled by default for". In this case they felt that we should hold off until it's enabled by default, but we could also choose to change it in the future. Sidenote - I could think about alternative names for minVersionForModernConfig to make it more clear.

packages/runtime/container-runtime/src/compatUtils.ts

packages/runtime/container-runtime/src/test/compatUtils.spec.ts

packages/runtime/container-runtime/src/compatUtils.ts

github-actions · 2025-04-15T23:32:30Z

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> [email protected] 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"


> [email protected] serve
> docusaurus serve --no-open

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

> [email protected] check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  163664 links
    1315 destination URLs
    1547 URLs ignored
       0 warnings
       0 errors

scottn12 · 2025-04-15T23:35:34Z

Closing in favor of #24248, may reopen in the future

…time options (#24379) ## Description This PR adds "default configurations" for container runtime options to the encapsulated model. FF will automatically populate `IContainerRuntimeOptionsInternal` based on the `compatibilityMode` with default values. For example, if `compatibilityMode` is set to `"1.0.0"`, we will automatically disable features that are not compatible with clients running FF runtime v1.0.0 (i.e. grouped batching). Users can still manually define any properties in `IContainerRuntimeOptionsInternal`, which will take precedence over the default configurations. This PR does not yet allow users to input their own `compatibilityMode`, this will be added in a follow up PR. For an example of how it may be implemented, see #24248, which is mostly a superset of the changes in this PR. --------- Co-authored-by: Copilot <[email protected]>

add default config to container runtime

d10075d

scottn12 added 2 commits April 3, 2025 16:06

change options matrix compat mode

352a86b

Merge branch 'main' into addDefaultConfig

5cc29a3

scottn12 marked this pull request as ready for review April 3, 2025 20:43

Copilot AI review requested due to automatic review settings April 3, 2025 20:43

scottn12 requested a review from a team as a code owner April 3, 2025 20:43

scottn12 requested review from anthony-murphy, Abe27342, markfields, agarwal-navin and kashms April 3, 2025 20:43

Copilot AI reviewed Apr 3, 2025

View reviewed changes

packages/framework/fluid-static/src/rootDataObject.ts Outdated Show resolved Hide resolved

fix gcSweep modernConfig

2341618

markfields reviewed Apr 4, 2025

View reviewed changes

packages/runtime/container-runtime/src/compatUtils.ts Show resolved Hide resolved

markfields reviewed Apr 4, 2025

View reviewed changes

packages/runtime/container-runtime/src/compatUtils.ts Outdated Show resolved Hide resolved

markfields reviewed Apr 4, 2025

View reviewed changes

ChumpChief reviewed Apr 7, 2025

View reviewed changes

packages/framework/fluid-static/src/rootDataObject.ts Outdated Show resolved Hide resolved

packages/runtime/container-runtime/src/compatUtils.ts Outdated Show resolved Hide resolved

scottn12 added 3 commits April 8, 2025 09:27

update minVersionRequired

c2eade5

add compatibilityModeVersionMap

d845ec1

remove TODO

2502289

pragya91 reviewed Apr 8, 2025

View reviewed changes

packages/runtime/container-runtime/src/compatUtils.ts Outdated Show resolved Hide resolved

scottn12 added 3 commits April 9, 2025 09:09

update idCompressor default

23c6b92

add compatConfig file back and exception for idCompressor

1d962bd

Merge branch 'main' into addDefaultConfig

091fc2e

scottn12 requested a review from TommyBrosman April 11, 2025 21:28

scottn12 added 2 commits April 14, 2025 09:30

PR feedback

c99af85

Merge branch 'main' into addDefaultConfig

8ea9988

anthony-murphy reviewed Apr 14, 2025

View reviewed changes

packages/runtime/container-runtime/src/compatUtils.ts Outdated Show resolved Hide resolved

anthony-murphy reviewed Apr 14, 2025

View reviewed changes

packages/runtime/container-runtime/src/compatUtils.ts Show resolved Hide resolved

scottn12 added 2 commits April 14, 2025 20:00

use back-compat instead of legacy for config name

a7b264c

Merge branch 'main' into addDefaultConfig

6a8043c

scottn12 mentioned this pull request Apr 15, 2025

DRAFT: feat(container-runtime): Add default configuration - using LoadContainerRuntimeParams #24362

Closed

change how default values are set

69310ec

anthony-murphy reviewed Apr 15, 2025

View reviewed changes

packages/runtime/container-runtime/src/compatUtils.ts Outdated Show resolved Hide resolved

anthony-murphy reviewed Apr 15, 2025

View reviewed changes

packages/runtime/container-runtime/src/compatUtils.ts Show resolved Hide resolved

scottn12 added 2 commits April 15, 2025 12:55

add SemanticVersion type

b6654b4

add UT for getConfigsForCompatMode

a07575f

anthony-murphy reviewed Apr 15, 2025

View reviewed changes

packages/runtime/container-runtime/src/test/compatUtils.spec.ts Outdated Show resolved Hide resolved

anthony-murphy reviewed Apr 15, 2025

View reviewed changes

packages/runtime/container-runtime/src/test/compatUtils.spec.ts Outdated Show resolved Hide resolved

anthony-murphy reviewed Apr 15, 2025

View reviewed changes

packages/runtime/container-runtime/src/compatUtils.ts Outdated Show resolved Hide resolved

anthony-murphy reviewed Apr 15, 2025

View reviewed changes

packages/runtime/container-runtime/src/compatUtils.ts Outdated Show resolved Hide resolved

scottn12 added 5 commits April 15, 2025 15:35

make unit tests generic

410502c

randomize order for test features, fix sort

1e840a4

remove .only

be8cc08

move compatMode to a param

d3434d9

remove pre-3.0 logic

3193ddd

github-actions bot removed the area: tests Tests to add, test infrastructure improvements, etc label Apr 15, 2025

scottn12 closed this Apr 15, 2025

scottn12 mentioned this pull request Apr 15, 2025

feat(container-runtime): Add default configurations for container runtime options #24379

Merged

feat(container-runtime): Add default configuration #24248

feat(container-runtime): Add default configuration #24248

Uh oh!

Conversation

scottn12 commented Apr 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Declarative Model

Next Steps

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

agarwal-navin Apr 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Apr 15, 2025

linkcheck output

Uh oh!

scottn12 commented Apr 15, 2025

Uh oh!

Uh oh!

scottn12 commented Apr 3, 2025 •

edited

Loading

agarwal-navin Apr 14, 2025 •

edited

Loading