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?: SemanticVersion;
     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 SemanticVersion,
 } from "@fluidframework/container-runtime/internal";
 import type { IContainerRuntime } from "@fluidframework/container-runtime-definitions/internal";
 import type { FluidObject } from "@fluidframework/core-interfaces";
@@ -61,6 +62,10 @@ export interface BaseContainerRuntimeFactoryProps {
 	 * created with this factory
 	 */
 	provideEntryPoint: (runtime: IContainerRuntime) => Promise<FluidObject>;
+	/**
+	 * The minVersionForCollab passed to the ContainerRuntime when instantiating it
+	 */
+	minVersionForCollab?: SemanticVersion;
 }
 
 /**
@@ -88,6 +93,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?: SemanticVersion;
 
 	public constructor(props: BaseContainerRuntimeFactoryProps) {
 		super();
@@ -98,6 +104,7 @@ export class BaseContainerRuntimeFactory
 		this.provideEntryPoint = props.provideEntryPoint;
 		this.requestHandlers = props.requestHandlers ?? [];
 		this.registry = new FluidDataStoreRegistry(this.registryEntries);
+		this.minVersionForCollab = props.minVersionForCollab;
 	}
 
 	/**
@@ -146,6 +153,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.
+ *
+ * @remarks 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 SemanticVersion,
+} 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: Record<CompatibilityMode, SemanticVersion> = {
+	"1": "1.0.0", // TODO: Should this be the LTS version?
+	"2": "2.0.0",
+};
+
 /**
  * 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,6 +338,7 @@ export interface LoadContainerRuntimeParams {
     containerScope?: FluidObject;
     context: IContainerContext;
     existing: boolean;
+    minVersionForCollab?: SemanticVersion;
     provideEntryPoint: (containerRuntime: IContainerRuntime) => Promise<FluidObject>;
     registryEntries: NamedFluidDataStoreRegistryEntries;
     // @deprecated
@@ -357,6 +358,9 @@ export type OpActionEventName = MessageType.Summarize | MessageType.SummaryAck |
 // @alpha @deprecated @legacy
 export type ReadFluidDataStoreAttributes = IFluidDataStoreAttributes0 | IFluidDataStoreAttributes1 | IFluidDataStoreAttributes2;
 
+// @alpha @legacy
+export type SemanticVersion = `${bigint}.${bigint}.${bigint}` | `${bigint}.${bigint}.${bigint}-${string}`;
+
 // @alpha @legacy
 export interface SubmitSummaryFailureData {
     // (undocumented)

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

@@ -22,7 +22,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.
@@ -32,12 +32,17 @@ 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;
+
+/**
+ * We don't want to allow anyone to use a version less than 1.0.0 for minVersionForCollab.
+ */
+const lowestMinVersionForCollab = "1.0.0" as const;
 
 /**
  * String in a valid semver format specifying bottom of a minor version
@@ -49,6 +54,9 @@ 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 SemanticVersion =
 	| `${bigint}.${bigint}.${bigint}`
@@ -95,8 +103,8 @@ export type RuntimeOptionsAffectingDocSchema = Omit<
  * the format changes introduced by the property, then the default value for that SemanticVersion 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.
  */
@@ -124,14 +132,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,
@@ -144,7 +152,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: {
@@ -156,24 +164,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: SemanticVersion,
 ): 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> = {};
@@ -182,14 +190,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((a, b) => (semverGte(b, a) ? -1 : 1));
-		// 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 (semverGte(compatibilityVersion, version)) {
+			if (semverGte(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;
 			}
@@ -199,13 +207,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 SemanticVersion that is at least "1.0.0" and less than or equal to the current package version.
  */
-export function isValidCompatVersion(compatibilityVersion: SemanticVersion): boolean {
+export function isValidMinVersionForCollab(minVersionForCollab: SemanticVersion): boolean {
 	return (
-		compatibilityVersion !== undefined &&
-		semverValid(compatibilityVersion) !== null &&
-		semverLte(compatibilityVersion, pkgVersion)
+		minVersionForCollab !== undefined &&
+		semverValid(minVersionForCollab) !== null &&
+		// Note: We use semverGte/semverLte instead of a semver range because semver ranges don't include pre-releases.
+		semverGte(minVersionForCollab, lowestMinVersionForCollab) &&
+		semverLte(minVersionForCollab, pkgVersion)
 	);
 }

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

@@ -154,10 +154,11 @@ import {
 	wrapContext,
 } from "./channelCollection.js";
 import {
-	defaultCompatibilityVersion,
-	getCompatibilityVersionDefaults,
-	isValidCompatVersion,
+	defaultMinVersionForCollab,
+	getminVersionForCollabDefaults,
+	isValidMinVersionForCollab,
 	type RuntimeOptionsAffectingDocSchema,
+	type SemanticVersion,
 } from "./compatUtils.js";
 import type { ICompressionRuntimeOptions } from "./compressionDefinitions.js";
 import { CompressionAlgorithms, disabledCompressionConfig } from "./compressionDefinitions.js";
@@ -698,6 +699,24 @@ export interface LoadContainerRuntimeParams {
 	 * @deprecated Will be removed once Loader LTS version is "2.0.0-internal.7.0.0". Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
 	 * */
 	requestHandler?: (request: IRequest, runtime: IContainerRuntime) => Promise<IResponse>;
+
+	/**
+	 * Used to determine the default configuration for {@link IContainerRuntimeOptionsInternal}
+	 * properties, which affect the document schema. It can be considered to be the minimum version of
+	 * the FF runtime that we should support compatibility with.
+	 *
+	 * @example
+	 * For example, let's say that feature `foo` was added in 2.0 which introduces a new op type. Additionally, option `bar`
+	 * was added to `IContainerRuntimeOptionsInternal` in 2.0 to enable/disable `foo` since clients prior to 2.0 would not
+	 * understand the new op type. If a customer were to set minVersionForCollab to 2.0.0, then `bar` would be set to
+	 * enable `foo` by default. If a customer were to set minVersionForCollab to 1.0.0, then `bar` would be set to
+	 * disable `foo` by default.
+	 *
+	 * minVersionForCollab accepts a string that must be in valid semver format. It must include the minor and patch indicators as well (i.e. 1.0
+	 * is not acceptable, but 1.0.0 is). 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.
+	 */
+	minVersionForCollab?: SemanticVersion;
 }
 /**
  * This is meant to be used by a {@link @fluidframework/container-definitions#IRuntimeFactory} to instantiate a container runtime.
@@ -759,6 +778,7 @@ export class ContainerRuntime
 		 */
 		requestHandler?: (request: IRequest, runtime: IContainerRuntime) => Promise<IResponse>;
 		provideEntryPoint: (containerRuntime: IContainerRuntime) => Promise<FluidObject>;
+		minVersionForCollab?: SemanticVersion;
 	}): Promise<ContainerRuntime> {
 		const {
 			context,
@@ -790,19 +810,17 @@ export class ContainerRuntime
 		const mc = loggerToMonitoringContext(logger);
 
 		// Some options require a minimum version of the FF runtime to operate, so the default configs will be generated
-		// based on the compatibility mode.
-		// For example, if compatibility mode is set to "1.0.0", the default configs will ensure compatibility with FF runtime
-		// 1.0.0 or later. If the compatibility mode is set to "2.10.0", the default values will be generated to ensure compatibility
+		// based on the minVersionForCollab.
+		// For example, if minVersionForCollab is set to "1.0.0", the default configs will ensure compatibility with FF runtime
+		// 1.0.0 or later. If the minVersionForCollab is set to "2.10.0", the default values will be generated to ensure compatibility
 		// with FF runtime 2.10.0 or later.
-		// TODO: We will add in a way for users to pass in compatibilityVersion in a follow up PR.
-		const compatibilityVersion = defaultCompatibilityVersion;
-		if (!isValidCompatVersion(compatibilityVersion)) {
+		const minVersionForCollab = params.minVersionForCollab ?? defaultMinVersionForCollab;
+		if (!isValidMinVersionForCollab(minVersionForCollab)) {
 			throw new UsageError(
-				`Invalid compatibility version: ${compatibilityVersion}. It must be an existing FF version (i.e. 2.22.1).`,
+				`Invalid minVersionForCollab: ${minVersionForCollab}. It must be an existing FF version (i.e. 2.22.1).`,
 			);
 		}
-		const defaultVersionDependentConfigs =
-			getCompatibilityVersionDefaults(compatibilityVersion);
+		const defaultVersionDependentConfigs = getminVersionForCollabDefaults(minVersionForCollab);
 
 		// The following are the default values for the options that do not affect the DocumentSchema.
 		const defaultConfigsNonVersionDependent: Required<

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

@@ -31,6 +31,7 @@ export {
 	ChannelCollectionFactory,
 	AllowTombstoneRequestHeaderKey,
 } from "./channelCollection.js";
+export { SemanticVersion } from "./compatUtils.js";
 export {
 	GCNodeType,
 	IGCMetadata,