container-runtime: Add API for default configuration

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

@@ -19,6 +19,7 @@ export class BaseContainerRuntimeFactory extends RuntimeFactoryHelper implements
 export interface BaseContainerRuntimeFactoryProps {
     // @deprecated (undocumented)
     dependencyContainer?: IFluidDependencySynthesizer;
+    minVersionForCollab?: MinimumVersionForCollab | undefined;
     provideEntryPoint: (runtime: IContainerRuntime) => Promise<FluidObject>;
     registryEntries: NamedFluidDataStoreRegistryEntries;
     // @deprecated

packages/framework/aqueduct/src/container-runtime-factories/baseContainerRuntimeFactory.ts

@@ -11,6 +11,7 @@ import {
 	FluidDataStoreRegistry,
 	loadContainerRuntime,
 	type IContainerRuntimeOptions,
+	type MinimumVersionForCollab,
 } from "@fluidframework/container-runtime/internal";
 import type { IContainerRuntime } from "@fluidframework/container-runtime-definitions/internal";
 import type { FluidObject } from "@fluidframework/core-interfaces";
@@ -61,6 +62,11 @@ export interface BaseContainerRuntimeFactoryProps {
 	 * created with this factory
 	 */
 	provideEntryPoint: (runtime: IContainerRuntime) => Promise<FluidObject>;
+	/**
+	 * The minVersionForCollab passed to the ContainerRuntime when instantiating it.
+	 * See {@link @fluidframework/container-runtime#LoadContainerRuntimeParams} for more details on this property.
+	 */
+	minVersionForCollab?: MinimumVersionForCollab | undefined;
 }
 
 /**
@@ -88,6 +94,7 @@ export class BaseContainerRuntimeFactory
 	// eslint-disable-next-line import/no-deprecated
 	private readonly requestHandlers: RuntimeRequestHandler[];
 	private readonly provideEntryPoint: (runtime: IContainerRuntime) => Promise<FluidObject>;
+	private readonly minVersionForCollab: MinimumVersionForCollab | undefined;
 
 	public constructor(props: BaseContainerRuntimeFactoryProps) {
 		super();
@@ -98,6 +105,7 @@ export class BaseContainerRuntimeFactory
 		this.provideEntryPoint = props.provideEntryPoint;
 		this.requestHandlers = props.requestHandlers ?? [];
 		this.registry = new FluidDataStoreRegistry(this.registryEntries);
+		this.minVersionForCollab = props.minVersionForCollab;
 	}
 
 	/**
@@ -146,6 +154,7 @@ export class BaseContainerRuntimeFactory
 			// eslint-disable-next-line import/no-deprecated
 			requestHandler: buildRuntimeRequestHandler(...this.requestHandlers),
 			provideEntryPoint: this.provideEntryPoint,
+			minVersionForCollab: this.minVersionForCollab,
 		});
 	}
 

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

@@ -3,48 +3,27 @@
  * Licensed under the MIT License.
  */
 
-import {
-	CompressionAlgorithms,
-	type IContainerRuntimeOptionsInternal,
-} from "@fluidframework/container-runtime/internal";
-import { FlushMode } from "@fluidframework/runtime-definitions/internal";
+import type { IContainerRuntimeOptionsInternal } from "@fluidframework/container-runtime/internal";
 
 import type { CompatibilityMode } from "./types.js";
 
 /**
- * Specifies the configured runtime options for each {@link CompatibilityMode}..
+ * The CompatibilityMode selected determines the set of runtime options to use. In "1" mode we support
+ * full interop with true 1.x clients, while in "2" mode we only support interop with 2.x clients.
+ *
+ * @privateRemarks In general, we can use the `compatibilityMode` property of `LoadContainerRuntimeParams` to apply
+ * the proper configurations. However, there are some options that we need to explicity set that differ
+ * from the default values (i.e. `enableRuntimeIdCompressor` below).
  */
 export const compatibilityModeRuntimeOptions: Record<
 	CompatibilityMode,
 	IContainerRuntimeOptionsInternal
 > = {
-	"1": {
-		// 1.x clients are compatible with TurnBased flushing, but here we elect to remain on Immediate flush mode
-		// as a work-around for inability to send batches larger than 1Mb. Immediate flushing keeps batches smaller as
-		// fewer messages will be included per flush.
-		flushMode: FlushMode.Immediate,
-		// Op compression is on by default but introduces a new type of op which is not compatible with 1.x clients.
-		compressionOptions: {
-			minimumBatchSizeInBytes: Number.POSITIVE_INFINITY, // disabled
-			compressionAlgorithm: CompressionAlgorithms.lz4,
-		},
-		// Grouped batching is on by default but introduces a new type of op which is not compatible with 1.x clients.
-		enableGroupedBatching: false,
-		// TODO: Include explicit disables for things that are currently off-by-default?
-
-		// Explicitly disable running Sweep in compat mode "1". Sweep is supported only in 2.x. So, when 1.x and 2.x
-		// clients are running in parallel, running sweep will fail 1.x clients.
-		gcOptions: { enableGCSweep: undefined },
-	},
+	"1": {},
 	"2": {
-		// Explicit schema control explicitly makes the container incompatible with 1.x clients, to force their
-		// ejection from collaboration and prevent container corruption.  It is off by default and must be explicitly enabled.
-		explicitSchemaControl: true,
 		// The runtime ID compressor is a prerequisite to use SharedTree but is off by default and must be explicitly enabled.
-		// It introduces a new type of op which is not compatible with 1.x clients.
+		// In general, we don't want to enable this by default since it increases the bundle size. However, since SharedTree
+		// is bundled with the fluid-framework package, we need to enable it here to support SharedTree.
 		enableRuntimeIdCompressor: "on",
-		// 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.
-		gcOptions: { enableGCSweep: undefined },
 	},
 };

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

@@ -10,7 +10,10 @@ import {
 	DataObjectFactory,
 } from "@fluidframework/aqueduct/internal";
 import type { IRuntimeFactory } from "@fluidframework/container-definitions/internal";
-import { FluidDataStoreRegistry } from "@fluidframework/container-runtime/internal";
+import {
+	FluidDataStoreRegistry,
+	type MinimumVersionForCollab,
+} from "@fluidframework/container-runtime/internal";
 import type { IContainerRuntime } from "@fluidframework/container-runtime-definitions/internal";
 import type { FluidObject, IFluidLoadable } from "@fluidframework/core-interfaces";
 import type { IChannelFactory } from "@fluidframework/datastore-definitions/internal";
@@ -36,6 +39,14 @@ import {
 	parseDataObjectsFromSharedObjects,
 } from "./utils.js";
 
+/**
+ * Maps CompatibilityMode to a semver valid string that can be passed to the container runtime.
+ */
+const compatibilityModeToMinVersionForCollab = {
+	"1": "1.0.0",
+	"2": "2.0.0",
+} as const satisfies Record<CompatibilityMode, MinimumVersionForCollab>;
+
 /**
  * Input props for {@link RootDataObject.initializingFirstTime}.
  */
@@ -242,6 +253,7 @@ class DOProviderContainerRuntimeFactory extends BaseContainerRuntimeFactory {
 			registryEntries: [rootDataObjectFactory.registryEntry],
 			runtimeOptions: compatibilityModeRuntimeOptions[compatibilityMode],
 			provideEntryPoint,
+			minVersionForCollab: compatibilityModeToMinVersionForCollab[compatibilityMode],
 		});
 		this.rootDataObjectFactory = rootDataObjectFactory;
 		this.initialObjects = schema.initialObjects;

packages/runtime/container-runtime/api-report/container-runtime.legacy.alpha.api.md

@@ -338,13 +338,17 @@ export interface LoadContainerRuntimeParams {
     containerScope?: FluidObject;
     context: IContainerContext;
     existing: boolean;
+    minVersionForCollab?: MinimumVersionForCollab;
     provideEntryPoint: (containerRuntime: IContainerRuntime) => Promise<FluidObject>;
     registryEntries: NamedFluidDataStoreRegistryEntries;
     // @deprecated
     requestHandler?: (request: IRequest, runtime: IContainerRuntime) => Promise<IResponse>;
     runtimeOptions?: IContainerRuntimeOptions;
 }
 
+// @alpha @legacy
+export type MinimumVersionForCollab = `${1 | 2}.${bigint}.${bigint}` | `${1 | 2}.${bigint}.${bigint}-${string}`;
+
 // @alpha @deprecated @legacy (undocumented)
 export type OmitAttributesVersions<T> = Omit<T, "snapshotFormatVersion" | "summaryFormatVersion">;
 

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

@@ -16,7 +16,7 @@ import { pkgVersion } from "./packageVersion.js";
 /**
  * Our policy is to support N/N-1 compatibility by default, where N is the most
  * recent public major release of the runtime.
- * Therefore, if the customer does not provide a compatibility mode, we will
+ * Therefore, if the customer does not provide a minVersionForCollab, we will
  * default to use N-1.
  *
  * However, this is not consistent with today's behavior. Some options (i.e.
@@ -26,12 +26,21 @@ import { pkgVersion } from "./packageVersion.js";
  * Importantly though, N/N-2 compatibility is still guaranteed with the proper
  * configurations set.
  *
- * Further to distinguish unspecified `compatibilityVersion` from a specified
+ * Further to distinguish unspecified `minVersionForCollab` from a specified
  * version and allow `enableExplicitSchemaControl` to default to `true` for
  * any 2.0.0+ version, we will use a special value of `2.0.0-defaults`, which
  * is semantically less than 2.0.0.
  */
-export const defaultCompatibilityVersion = "2.0.0-defaults" as const;
+export const defaultMinVersionForCollab =
+	"2.0.0-defaults" as const satisfies MinimumVersionForCollab;
+
+/**
+ * We don't want allow a version before the major public release of the LTS version.
+ * Today we use "1.0.0", because our policy supports N/N-1 & N/N-2, which includes
+ * all minor versions of N. Though LTS starts at 1.4.0, we should stay consistent
+ * with our policy and allow all 1.x versions to be compatible with 2.x.
+ */
+const lowestMinVersionForCollab = "1.0.0" as const satisfies MinimumVersionForCollab;
 
 /**
  * String in a valid semver format specifying bottom of a minor version
@@ -43,6 +52,18 @@ export type MinimumMinorSemanticVersion = `${bigint}.${bigint}.0` | `${bigint}.0
 
 /**
  * String in a valid semver format of a specific version at least specifying minor.
+ *
+ * @legacy
+ * @alpha
+ */
+export type MinimumVersionForCollab =
+	| `${1 | 2}.${bigint}.${bigint}`
+	| `${1 | 2}.${bigint}.${bigint}-${string}`;
+
+/**
+ * String in a valid semver format of a specific version at least specifying minor.
+ * Unlike {@link MinimumVersionForCollab}, this type allows any bigint for the major version.
+ * Used as a more generic type that allows major versions other than 1 or 2.
  */
 export type SemanticVersion =
 	| `${bigint}.${bigint}.${bigint}`
@@ -84,13 +105,13 @@ export type RuntimeOptionsAffectingDocSchema = Omit<
 /**
  * Mapping of RuntimeOptionsAffectingDocSchema to their compatibility related configs.
  *
- * Each key in this map corresponds to a property in RuntimeOptionsAffectingDocSchema. The value is an object that maps SemanticVersions
- * to the appropriate default value for that property to supporting that SemanticVersion. If clients running SemanticVersion X are able to understand
- * the format changes introduced by the property, then the default value for that SemanticVersion will enable the feature associated with the property.
+ * Each key in this map corresponds to a property in RuntimeOptionsAffectingDocSchema. The value is an object that maps MinimumVersionForCollab
+ * to the appropriate default value for that property to supporting that MinimumVersionForCollab. If clients running MinimumVersionForCollab X are able to understand
+ * the format changes introduced by the property, then the default value for that MinimumVersionForCollab will enable the feature associated with the property.
  * Otherwise, the feature will be disabled.
  *
- * For example if the compatibilityVersion is a 1.x version (i.e. "1.5.0"), then the default value for `enableGroupedBatching` will be false since 1.x
- * clients do not understand the document format when batching is enabled. If the compatibilityVersion is a 2.x client (i.e. "2.0.0" or later), then the
+ * For example if the minVersionForCollab is a 1.x version (i.e. "1.5.0"), then the default value for `enableGroupedBatching` will be false since 1.x
+ * clients do not understand the document format when batching is enabled. If the minVersionForCollab is a 2.x client (i.e. "2.0.0" or later), then the
  * default value for `enableGroupedBatching` will be true because clients running 2.0 or later will be able to understand the format changes associated
  * with the batching feature.
  */
@@ -118,14 +139,14 @@ const runtimeOptionsAffectingDocSchemaConfigMap = {
 	explicitSchemaControl: {
 		"1.0.0": false,
 		// This option's intention is to prevent 1.x clients from joining sessions
-		// when enabled. This is set to true when the compatibility version is set
+		// when enabled. This is set to true when the minVersionForCollab is set
 		// to >=2.0.0 (explicitly). This is different than other 2.0 defaults
 		// because it was not enabled by default prior to the implementation of
-		// `compatibilityVersion`.
-		// `defaultCompatibilityVersion` is set to "2.0.0-defaults" which "2.0.0"
+		// `minVersionForCollab`.
+		// `defaultMinVersionForCollab` is set to "2.0.0-defaults" which "2.0.0"
 		// does not satisfy to avoiding enabling this option by default as of
-		// `compatibilityVersion` introduction, which could be unexpected.
-		// Only enable as a default when `compatibilityVersion` is specified at
+		// `minVersionForCollab` introduction, which could be unexpected.
+		// Only enable as a default when `minVersionForCollab` is specified at
 		// 2.0.0+.
 		"2.0.0": true,
 	} as const,
@@ -138,7 +159,7 @@ const runtimeOptionsAffectingDocSchemaConfigMap = {
 	} as const,
 	gcOptions: {
 		"1.0.0": {},
-		// Although sweep is supported in 2.x, it is disabled by default until compatibilityVersion>=3.0.0 to be extra safe.
+		// Although sweep is supported in 2.x, it is disabled by default until minVersionForCollab>=3.0.0 to be extra safe.
 		"3.0.0": { enableGCSweep: true },
 	} as const,
 	createBlobPayloadPending: {
@@ -150,24 +171,24 @@ const runtimeOptionsAffectingDocSchemaConfigMap = {
 } as const satisfies ConfigMap<RuntimeOptionsAffectingDocSchema>;
 
 /**
- * Returns the default RuntimeOptionsAffectingDocSchema configuration for a given compatibility version.
+ * Returns the default RuntimeOptionsAffectingDocSchema configuration for a given minVersionForCollab.
  */
-export function getCompatibilityVersionDefaults(
-	compatibilityVersion: SemanticVersion,
+export function getMinVersionForCollabDefaults(
+	minVersionForCollab: MinimumVersionForCollab,
 ): RuntimeOptionsAffectingDocSchema {
 	return getConfigsForCompatMode(
-		compatibilityVersion,
+		minVersionForCollab,
 		runtimeOptionsAffectingDocSchemaConfigMap,
 		// This is a bad cast away from Partial that getConfigsForCompatMode provides.
 		// ConfigMap should be restructured to provide RuntimeOptionsAffectingDocSchema guarantee.
 	) as RuntimeOptionsAffectingDocSchema;
 }
 
 /**
- * Returns a default configuration given compatibility version and configuration version map.
+ * Returns a default configuration given minVersionForCollab and configuration version map.
  */
 export function getConfigsForCompatMode<T extends Record<SemanticVersion, unknown>>(
-	compatibilityVersion: SemanticVersion,
+	minVersionForCollab: SemanticVersion,
 	configMap: ConfigMap<T>,
 ): Partial<T> {
 	const defaultConfigs: Partial<T> = {};
@@ -176,14 +197,14 @@ export function getConfigsForCompatMode<T extends Record<SemanticVersion, unknow
 		const config = configMap[key as keyof T];
 		// Sort the versions in ascending order so we can short circuit the loop.
 		const versions = Object.keys(config).sort(compare);
-		// For each config, we iterate over the keys and check if compatibilityVersion is greater than or equal to the version.
+		// For each config, we iterate over the keys and check if minVersionForCollab is greater than or equal to the version.
 		// If so, we set it as the default value for the option. At the end of the loop we should have the most recent default
-		// value that is compatible with the version specified as the compatibilityVersion.
+		// value that is compatible with the version specified as the minVersionForCollab.
 		for (const version of versions) {
-			if (gte(compatibilityVersion, version)) {
+			if (gte(minVersionForCollab, version)) {
 				defaultConfigs[key] = config[version as MinimumMinorSemanticVersion];
 			} else {
-				// If the compatibility mode is less than the version, we break out of the loop since we don't need to check
+				// If the minVersionForCollab is less than the version, we break out of the loop since we don't need to check
 				// any later versions.
 				break;
 			}
@@ -193,13 +214,15 @@ export function getConfigsForCompatMode<T extends Record<SemanticVersion, unknow
 }
 
 /**
- * Checks if the compatibility version is valid.
- * A valid compatibility version is a string that is a valid semver version and is less than or equal to the current package version.
+ * Checks if the minVersionForCollab is valid.
+ * A valid minVersionForCollab is a MinimumVersionForCollab that is at least `lowestMinVersionForCollab` and less than or equal to the current package version.
  */
-export function isValidCompatVersion(compatibilityVersion: SemanticVersion): boolean {
+export function isValidMinVersionForCollab(
+	minVersionForCollab: MinimumVersionForCollab,
+): boolean {
 	return (
-		compatibilityVersion !== undefined &&
-		valid(compatibilityVersion) !== null &&
-		lte(compatibilityVersion, pkgVersion)
+		valid(minVersionForCollab) !== null &&
+		gte(minVersionForCollab, lowestMinVersionForCollab) &&
+		lte(minVersionForCollab, pkgVersion)
 	);
 }