@fluidframework/container-runtime 2.115.0 → 2.116.0

package/src/containerRuntime.ts

@@ -131,7 +131,7 @@ import type {
 	ISummarizerNodeWithGC,
 	StageControlsInternal,
 	IContainerRuntimeBaseInternal,
-	MinimumVersionForCollab,
+	OldestSupportedClientVersion,
 	ContainerExtensionExpectations,
 } from "@fluidframework/runtime-definitions/internal";
 import {
@@ -804,25 +804,42 @@ export interface LoadContainerRuntimeParams {
 	requestHandler?: (request: IRequest, runtime: IContainerRuntime) => Promise<IResponse>;
 
 	/**
-	 * Minimum version of the FF runtime that is required to collaborate on new documents.
-	 * The input should be a string that represents the minimum version of the FF runtime that should be
-	 * supported for collaboration. The format of the string must be in valid semver format.
+	 * Oldest version of Fluid Framework client that must be able to open and process documents
+	 * written by this container runtime.
+	 * @remarks
+	 * Choosing an older version may limit the features and write formats the application can use to
+	 * those supported by that version. The value must be valid SemVer.
 	 *
 	 * The inputted version will be used to determine the default configuration for
 	 * {@link IContainerRuntimeOptionsInternal} to ensure compatibility with the specified version.
 	 *
 	 * @example
-	 * minVersionForCollab: "2.0.0"
+	 * oldestSupportedClient: "2.0.0"
 	 *
 	 * @privateRemarks
 	 * Used to determine the default configuration for {@link IContainerRuntimeOptionsInternal} that affect the document schema.
 	 * 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
+	 * understand the new op type. If a customer were to set oldestSupportedClient to 2.0.0, then `bar` would be set to
+	 * enable `foo` by default. If a customer were to set oldestSupportedClient to 1.0.0, then `bar` would be set to
 	 * disable `foo` by default.
 	 */
-	minVersionForCollab?: MinimumVersionForCollab;
+	oldestSupportedClient?: OldestSupportedClientVersion;
+
+	/**
+	 * Oldest version of Fluid Framework client that must be able to open and process documents
+	 * written by this container runtime.
+	 *
+	 * @remarks
+	 * See {@link LoadContainerRuntimeParams.oldestSupportedClient} for compatibility implications.
+	 *
+	 * Specifying both `oldestSupportedClient` and `minVersionForCollab` is an error.
+	 *
+	 * @deprecated 2.116.0. To be removed in 3.10.0. Use
+	 * {@link LoadContainerRuntimeParams.oldestSupportedClient} instead.
+	 * See {@link https://github.com/microsoft/FluidFramework/issues/27851} for context.
+	 */
+	minVersionForCollab?: OldestSupportedClientVersion;
 }
 /**
  * This is meant to be used by a {@link @fluidframework/container-definitions#IRuntimeFactory} to instantiate a container runtime.
@@ -833,7 +850,10 @@ export interface LoadContainerRuntimeParams {
 export async function loadContainerRuntime(
 	params: LoadContainerRuntimeParams,
 ): Promise<IContainerRuntime & IRuntime> {
-	return ContainerRuntime.loadRuntime(params);
+	return ContainerRuntime.loadRuntime({
+		...params,
+		registry: new FluidDataStoreRegistry(params.registryEntries),
+	});
 }
 
 /**
@@ -843,6 +863,10 @@ export async function loadContainerRuntime(
  * @param params - An object which specifies all required and optional params necessary to instantiate a runtime.
  * @returns An object containing the runtime.
  *
+ * @privateRemarks
+ * By using loadRuntime2 instead of loadRuntime, this prevents mixinAttributor's overriding of loadRuntime from affecting this new API:
+ * this might cause unexpected issues.
+ *
  * @legacy @alpha
  */
 export async function loadContainerRuntimeAlpha(params: LoadContainerRuntimeParams): Promise<{
@@ -909,6 +933,8 @@ export class ContainerRuntime
 	 * {@link LoadContainerRuntimeParams} except internal, while still having layer compat obligations.
 	 * @privateRemarks
 	 * Despite this being `@internal`, `@fluidframework/test-utils` uses it in `createTestContainerRuntimeFactory` and assumes multiple versions of the package expose the same API.
+	 * To enable this code to know what version of this API it should use, loadRuntimeAPIVersion has been added.
+	 * This is a workaround for the relevant code in test-utils not tracking the package version, so it can't special case it off of that.
 	 *
 	 * Also note that `mixinAttributor` from `@fluid-experimental/attributor` overrides this function:
 	 * that will have to be updated if changing the signature of this function as well.
@@ -917,21 +943,21 @@ export class ContainerRuntime
 	 * `loadRuntime` could be removed (replaced by `loadRuntime2` which could be renamed back to `loadRuntime`).
 	 */
 	public static async loadRuntime(
-		params: LoadContainerRuntimeParams & {
-			/**
-			 * Constructor to use to create the ContainerRuntime instance.
-			 * @remarks
-			 * Defaults to {@link ContainerRuntime}.
-			 */
+		params: Omit<LoadContainerRuntimeParams, "registryEntries" | "runtimeOptions"> & {
+			registry: IFluidDataStoreRegistry;
 			containerRuntimeCtor?: typeof ContainerRuntime;
+			runtimeOptions?: IContainerRuntimeOptionsInternal;
 		},
 	): Promise<ContainerRuntime> {
-		return ContainerRuntime.loadRuntime2({
-			...params,
-			registry: new FluidDataStoreRegistry(params.registryEntries),
-		}).then((r) => r.runtime);
+		return ContainerRuntime.loadRuntime2(params).then((r) => r.runtime);
 	}
 
+	/**
+	 * Hack to allow test-utils to detect which version of loadRuntime API to expect.
+	 * See note in loadRuntime's private remarks.
+	 */
+	public static readonly loadRuntimeAPIVersion: number | undefined = 2;
+
 	/**
 	 * Load the stores from a snapshot and returns an object containing the runtime.
 	 * @remarks
@@ -966,9 +992,27 @@ export class ContainerRuntime
 			runtimeOptions = {} satisfies IContainerRuntimeOptionsInternal,
 			containerScope = {},
 			containerRuntimeCtor = ContainerRuntime,
-			minVersionForCollab = defaultMinVersionForCollab,
+			oldestSupportedClient: oldestSupportedClientParam,
+			// eslint-disable-next-line import-x/no-deprecated -- accepted for compatibility. See #27851
+			minVersionForCollab: deprecatedMinVersionForCollab,
 		} = params;
 
+		if (
+			oldestSupportedClientParam !== undefined &&
+			deprecatedMinVersionForCollab !== undefined
+		) {
+			throw new UsageError(
+				"Specify only one of oldestSupportedClient or minVersionForCollab (deprecated), not both.",
+			);
+		}
+		// Internally this value is still threaded through as `minVersionForCollab`. Renaming the
+		// Runtime/DataStore/DDS propagation path crosses API layers and requires a staged migration
+		// where both names coexist for old and new consumers. See #27851.
+		const minVersionForCollab =
+			oldestSupportedClientParam ??
+			deprecatedMinVersionForCollab ??
+			defaultMinVersionForCollab;
+
 		// If taggedLogger exists, use it. Otherwise, wrap the vanilla logger:
 		// back-compat: Remove the TaggedLoggerAdapter fallback once all the host are using loader > 0.45
 		const backCompatContext: IContainerContext | OldContainerContextWithLogger = context;
@@ -1655,7 +1699,7 @@ export class ContainerRuntime
 		private readonly documentsSchemaController: DocumentsSchemaController,
 		featureGatesForTelemetry: Record<string, boolean | number | undefined>,
 		provideEntryPoint: (containerRuntime: IContainerRuntime) => Promise<FluidObject>,
-		public readonly minVersionForCollab: MinimumVersionForCollab,
+		public readonly minVersionForCollab: OldestSupportedClientVersion,
 		private readonly requestHandler?: (
 			request: IRequest,
 			runtime: IContainerRuntime,
@@ -2365,11 +2409,11 @@ export class ContainerRuntime
 	// #region `IFluidParentContext` APIs that should not be called on Root
 
 	public makeLocallyVisible(): void {
-		assert(false, 0x8eb /* should not be called */);
+		fail(0x8eb /* should not be called */);
 	}
 
 	public setChannelDirty(address: string): void {
-		assert(false, 0x909 /* should not be called */);
+		fail(0x909 /* should not be called */);
 	}
 
 	// #endregion
@@ -3655,7 +3699,7 @@ export class ContainerRuntime
 			case ContainerMessageType.ChunkedOp: {
 				// From observability POV, we should not expose the rest of the system (including "op" events on object) to these messages.
 				// Also resetReconnectCount() would be wrong - see comment that was there before this change was made.
-				assert(false, 0x93d /* should not even get here */);
+				fail(0x93d /* should not even get here */);
 			}
 			case ContainerMessageType.Rejoin: {
 				break;
@@ -4469,7 +4513,7 @@ export class ContainerRuntime
 				return this.channelCollection.getDataStorePackagePath(nodePath);
 			}
 			default: {
-				assert(false, 0x2de /* "Package path requested for unsupported node type." */);
+				fail(0x2de /* "Package path requested for unsupported node type." */);
 			}
 		}
 	}

package/src/dataStoreContext.ts

@@ -67,7 +67,7 @@ import type {
 	IFluidDataStoreFactory,
 	PackagePath,
 	IRuntimeStorageService,
-	MinimumVersionForCollab,
+	OldestSupportedClientVersion,
 	ContainerExtensionId,
 	ContainerExtensionExpectations,
 } from "@fluidframework/runtime-definitions/internal";
@@ -355,7 +355,7 @@ export abstract class FluidDataStoreContext
 	/**
 	 * {@inheritdoc IFluidDataStoreContext.minVersionForCollab}
 	 */
-	public readonly minVersionForCollab: MinimumVersionForCollab;
+	public readonly minVersionForCollab: OldestSupportedClientVersion;
 
 	private baseSnapshotSequenceNumber: number | undefined;
 

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-runtime";
-export const pkgVersion = "2.115.0";
+export const pkgVersion = "2.116.0";

package/src/summary/documentSchema.ts

@@ -107,9 +107,9 @@ export interface IDocumentSchemaInfo {
 	 * See {@link @fluidframework/container-runtime#LoadContainerRuntimeParams} for additional details on `minVersionForCollab`.
 	 *
 	 * @remarks
-	 * We use `SemanticVersion` instead of `MinimumVersionForCollab` since we may open future documents with a
-	 * minVersionForCollab version that `MinimumVersionForCollab` does not support.
-	 * Note that in such a case (where minVersionForCollab is not a valid `MinimumVersionForCollab`),
+	 * We use `SemanticVersion` instead of `OldestSupportedClientVersion` since we may open future documents with a
+	 * minVersionForCollab version that `OldestSupportedClientVersion` does not support.
+	 * Note that in such a case (where minVersionForCollab is not a valid `OldestSupportedClientVersion`),
 	 * loading the document might not work since this version of the runtime may not support it.
 	 */
 	minVersionForCollab: SemanticVersion;

package/src/versionMarks/versionMarkResolver.ts

@@ -33,7 +33,7 @@ export interface IHistoricalOpReader {
 /**
  * Result of resolving a pending batchId.
  *
- * @legacy @alpha
+ * @legacy @beta
  */
 export type ResolveResult =
 	| { readonly kind: "resolved"; readonly sequenceNumber: number }
@@ -46,7 +46,7 @@ export type ResolveResult =
  * work, so the mark already points at a durable sequence number. The app packs its own stored record from
  * this — the runtime does not define the stored locator shape.
  *
- * @legacy @alpha
+ * @legacy @beta
  */
 export type VersionMarkCapture =
 	| {
@@ -59,7 +59,7 @@ export type VersionMarkCapture =
 /**
  * Runtime-owned resolver for app-stored version mark locators.
  *
- * @legacy @alpha
+ * @legacy @beta
  */
 export interface IVersionMarkResolver {
 	/**