@fluidframework/container-runtime 2.42.0 → 2.43.0-343119

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/container-runtime",
-  "version": "2.42.0",
+  "version": "2.43.0-343119",
   "description": "Fluid container runtime",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -119,18 +119,18 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.42.0",
-    "@fluidframework/container-definitions": "~2.42.0",
-    "@fluidframework/container-runtime-definitions": "~2.42.0",
-    "@fluidframework/core-interfaces": "~2.42.0",
-    "@fluidframework/core-utils": "~2.42.0",
-    "@fluidframework/datastore": "~2.42.0",
-    "@fluidframework/driver-definitions": "~2.42.0",
-    "@fluidframework/driver-utils": "~2.42.0",
-    "@fluidframework/id-compressor": "~2.42.0",
-    "@fluidframework/runtime-definitions": "~2.42.0",
-    "@fluidframework/runtime-utils": "~2.42.0",
-    "@fluidframework/telemetry-utils": "~2.42.0",
+    "@fluid-internal/client-utils": "2.43.0-343119",
+    "@fluidframework/container-definitions": "2.43.0-343119",
+    "@fluidframework/container-runtime-definitions": "2.43.0-343119",
+    "@fluidframework/core-interfaces": "2.43.0-343119",
+    "@fluidframework/core-utils": "2.43.0-343119",
+    "@fluidframework/datastore": "2.43.0-343119",
+    "@fluidframework/driver-definitions": "2.43.0-343119",
+    "@fluidframework/driver-utils": "2.43.0-343119",
+    "@fluidframework/id-compressor": "2.43.0-343119",
+    "@fluidframework/runtime-definitions": "2.43.0-343119",
+    "@fluidframework/runtime-utils": "2.43.0-343119",
+    "@fluidframework/telemetry-utils": "2.43.0-343119",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "double-ended-queue": "^2.1.0-0",
     "lz4js": "^0.2.0",
@@ -140,16 +140,16 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "~2.42.0",
-    "@fluid-private/stochastic-test-utils": "~2.42.0",
-    "@fluid-private/test-pairwise-generator": "~2.42.0",
+    "@fluid-internal/mocha-test-setup": "2.43.0-343119",
+    "@fluid-private/stochastic-test-utils": "2.43.0-343119",
+    "@fluid-private/test-pairwise-generator": "2.43.0-343119",
     "@fluid-tools/benchmark": "^0.51.0",
     "@fluid-tools/build-cli": "^0.55.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.55.0",
-    "@fluidframework/container-runtime-previous": "npm:@fluidframework/container-runtime@2.41.0",
+    "@fluidframework/container-runtime-previous": "npm:@fluidframework/container-runtime@2.42.0",
     "@fluidframework/eslint-config-fluid": "^5.7.4",
-    "@fluidframework/test-runtime-utils": "~2.42.0",
+    "@fluidframework/test-runtime-utils": "2.43.0-343119",
     "@microsoft/api-extractor": "7.52.8",
     "@types/double-ended-queue": "^2.1.0",
     "@types/lz4js": "^0.2.0",

package/src/compatUtils.ts

@@ -66,6 +66,8 @@ export type MinimumVersionForCollab =
  * 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.
+ *
+ * @internal
  */
 export type SemanticVersion =
 	| `${bigint}.${bigint}.${bigint}`

package/src/containerRuntime.ts

@@ -160,6 +160,7 @@ import {
 	tagCodeArtifacts,
 	normalizeError,
 } from "@fluidframework/telemetry-utils/internal";
+import { gt } from "semver-ts";
 import { v4 as uuid } from "uuid";
 
 import { BindBatchTracker } from "./batchTracker.js";
@@ -183,6 +184,7 @@ import {
 	isValidMinVersionForCollab,
 	type RuntimeOptionsAffectingDocSchema,
 	type MinimumVersionForCollab,
+	type SemanticVersion,
 	validateRuntimeOptions,
 } from "./compatUtils.js";
 import type { ICompressionRuntimeOptions } from "./compressionDefinitions.js";
@@ -1114,8 +1116,19 @@ export class ContainerRuntime
 			(schema) => {
 				runtime.onSchemaChange(schema);
 			},
+			{ minVersionForCollab },
+			logger,
 		);
 
+		// If the minVersionForCollab for this client is greater than the existing one, we should use that one going forward.
+		const existingMinVersionForCollab =
+			documentSchemaController.sessionSchema.info.minVersionForCollab;
+		const updatedMinVersionForCollab =
+			existingMinVersionForCollab === undefined ||
+			gt(minVersionForCollab, existingMinVersionForCollab)
+				? minVersionForCollab
+				: existingMinVersionForCollab;
+
 		if (compressionLz4 && !enableGroupedBatching) {
 			throw new UsageError("If compression is enabled, op grouping must be enabled too");
 		}
@@ -1154,7 +1167,7 @@ export class ContainerRuntime
 			documentSchemaController,
 			featureGatesForTelemetry,
 			provideEntryPoint,
-			minVersionForCollab,
+			updatedMinVersionForCollab,
 			requestHandler,
 			undefined, // summaryConfiguration
 			recentBatchInfo,
@@ -1491,7 +1504,7 @@ export class ContainerRuntime
 		private readonly documentsSchemaController: DocumentsSchemaController,
 		featureGatesForTelemetry: Record<string, boolean | number | undefined>,
 		provideEntryPoint: (containerRuntime: IContainerRuntime) => Promise<FluidObject>,
-		private readonly minVersionForCollab: MinimumVersionForCollab,
+		private readonly minVersionForCollab: SemanticVersion,
 		private readonly requestHandler?: (
 			request: IRequest,
 			runtime: IContainerRuntime,
@@ -3474,22 +3487,29 @@ export class ContainerRuntime
 			throw new UsageError("cannot enter staging mode while detached");
 		}
 
-		// Make sure all BatchManagers are empty before entering staging mode,
+		// Make sure Outbox is empty before entering staging mode,
 		// since we mark whole batches as "staged" or not to indicate whether to submit them.
-		this.outbox.flush();
+		this.flush();
 
 		const exitStagingMode = (discardOrCommit: () => void) => (): void => {
-			// Final flush of any last staged changes
-			this.outbox.flush();
+			try {
+				// Final flush of any last staged changes
+				// NOTE: We can't use this.flush() here, because orderSequentially uses StagingMode and in the rollback case we'll hit assert 0x24c
+				this.outbox.flush();
 
-			this.stageControls = undefined;
+				this.stageControls = undefined;
 
-			// During Staging Mode, we avoid submitting any ID Allocation ops (apart from resubmitting pre-staging ops).
-			// Now that we've exited, we need to submit an ID Allocation op for any IDs that were generated while in Staging Mode.
-			this.submitIdAllocationOpIfNeeded({ staged: false });
-			discardOrCommit();
+				// During Staging Mode, we avoid submitting any ID Allocation ops (apart from resubmitting pre-staging ops).
+				// Now that we've exited, we need to submit an ID Allocation op for any IDs that were generated while in Staging Mode.
+				this.submitIdAllocationOpIfNeeded({ staged: false });
+				discardOrCommit();
 
-			this.channelCollection.notifyStagingMode(false);
+				this.channelCollection.notifyStagingMode(false);
+			} catch (error) {
+				const normalizedError = normalizeError(error);
+				this.closeFn(normalizedError);
+				throw normalizedError;
+			}
 		};
 
 		// eslint-disable-next-line import/no-deprecated
@@ -4572,6 +4592,7 @@ export class ContainerRuntime
 					newRuntimeSchema: JSON.stringify(schemaChangeMessage.runtime),
 					sessionRuntimeSchema: JSON.stringify(this.sessionSchema),
 					oldRuntimeSchema: JSON.stringify(this.metadata?.documentSchema?.runtime),
+					minVersionForCollab: schemaChangeMessage.info?.minVersionForCollab,
 				});
 				const msg: OutboundContainerRuntimeDocumentSchemaMessage = {
 					type: ContainerMessageType.DocumentSchemaChange,

package/src/index.ts

@@ -31,7 +31,7 @@ export {
 	ChannelCollectionFactory,
 	AllowTombstoneRequestHeaderKey,
 } from "./channelCollection.js";
-export type { MinimumVersionForCollab } from "./compatUtils.js";
+export type { MinimumVersionForCollab, SemanticVersion } from "./compatUtils.js";
 export {
 	GCNodeType,
 	IGCMetadata,
@@ -91,6 +91,7 @@ export {
 	IRetriableFailureError,
 	IdCompressorMode,
 	IDocumentSchema,
+	IDocumentSchemaInfo,
 	DocumentSchemaValueType,
 	IDocumentSchemaCurrent,
 	currentDocumentVersionSchema,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-runtime";
-export const pkgVersion = "2.42.0";
+export const pkgVersion = "2.43.0-343119";

package/src/summary/documentSchema.ts

@@ -4,8 +4,11 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+import type { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 import { DataProcessingError } from "@fluidframework/telemetry-utils/internal";
+import { gt, lt, parse } from "semver-ts";
 
+import type { SemanticVersion } from "../compatUtils.js";
 import { pkgVersion } from "../packageVersion.js";
 
 /**
@@ -80,10 +83,42 @@ export interface IDocumentSchema {
 	 * properties to be able to open the document.
 	 */
 	runtime: Record<string, DocumentSchemaValueType>;
+
+	/**
+	 * Info about this document that can be updated via Document Schema change op, but isn't required
+	 * to be understood by all clients (unlike the rest of IDocumentSchema properties). Because of this,
+	 * some older documents may not have this property, so it's an optional property.
+	 */
+	info?: IDocumentSchemaInfo;
+}
+
+/**
+ * Informational properties of the document that are not subject to strict schema enforcement.
+ *
+ * @internal
+ */
+export interface IDocumentSchemaInfo {
+	/**
+	 * The minimum version of the FF runtime that should be used to load this document.
+	 * Will likely be advanced over time as applications pick up later FF versions.
+	 *
+	 * We use this to issue telemetry warning events if a client tries to open a document
+	 * with a runtime version lower than this.
+	 *
+	 * See {@link @fluidframework/container-runtime#LoadContainerRuntimeParams} for additional details on `minVersionForCollab`.
+	 *
+	 * @remarks
+	 * We use `SemanticVersion` instead of `MinimumVersionForCollab` since we may open future documents that with a
+	 * minVersionForCollab version that `MinimumVersionForCollab` does not support.
+	 */
+	minVersionForCollab: SemanticVersion;
 }
 
 /**
  * Content of the type=ContainerMessageType.DocumentSchemaChange ops.
+ * The meaning of refSeq field is different in such messages (compared to other usages of IDocumentSchemaCurrent)
+ * ContainerMessageType.DocumentSchemaChange messages use CAS (Compare-and-swap) semantics, and convey
+ * regSeq of last known schema change (known to a client proposing schema change).
  * @see InboundContainerRuntimeDocumentSchemaMessage
  * @internal
  */
@@ -133,6 +168,8 @@ export interface IDocumentSchemaFeatures {
  * in a way that all old/new clients are required to understand.
  * Ex: Adding a new configuration property (under IDocumentSchema.runtime) does not require changing this version since there is logic
  * in old clients for handling new/unknown properties.
+ * Ex: Adding a new property to IDocumentSchema.info does not require changing this version, since info properties are not required to be
+ * understood by all clients.
  * Ex: Changing the 'document schema acceptance' mechanism from convert-and-swap to one requiring consensus does require changing this version
  * since all clients need to understand the new protocol.
  * @internal
@@ -141,11 +178,15 @@ export const currentDocumentVersionSchema = 1;
 
 /**
  * Current document schema.
+ * This interface represents the schema that we currently understand and know the
+ * structure of (which properties will be present).
+ *
  * @internal
  */
 export interface IDocumentSchemaCurrent extends Required<IDocumentSchema> {
 	// This is the version of the schema that we currently understand.
 	version: typeof currentDocumentVersionSchema;
+	// This narrows the runtime property to only include the properties in IDocumentSchemaFeatures (all as optional)
 	runtime: {
 		[P in keyof IDocumentSchemaFeatures]?: IDocumentSchemaFeatures[P] extends boolean
 			? true
@@ -153,6 +194,18 @@ export interface IDocumentSchemaCurrent extends Required<IDocumentSchema> {
 	};
 }
 
+/**
+ * Document schema that is incoming from another client but validated to be "current".
+ *
+ * This interface represents when we have validated that an incoming IDocumentSchema object
+ * is compatible with the current runtime (by calling `checkRuntimeCompatibility()`).
+ * However, the `info` property is optional because some older documents may not have this property, but
+ * `info` is not required to be understood by all clients to be compatible.
+ */
+interface IDocumentSchemaCurrentIncoming extends Omit<IDocumentSchemaCurrent, "info"> {
+	info?: IDocumentSchemaInfo;
+}
+
 interface IProperty<T = unknown> {
 	and: (persistedSchema: T, providedSchema: T) => T;
 	or: (persistedSchema: T, providedSchema: T) => T;
@@ -257,7 +310,7 @@ const documentSchemaSupportedConfigs = {
 function checkRuntimeCompatibility(
 	documentSchema: IDocumentSchema | undefined,
 	schemaName: string,
-): asserts documentSchema is IDocumentSchemaCurrent {
+): asserts documentSchema is IDocumentSchemaCurrentIncoming {
 	// Back-compat - we can't do anything about legacy documents.
 	// There is no way to validate them, so we are taking a guess that safe deployment processes used by a given app
 	// do not run into compat problems.
@@ -315,7 +368,7 @@ function checkRuntimeCompatibility(
 }
 
 function and(
-	persistedSchema: IDocumentSchemaCurrent,
+	persistedSchema: IDocumentSchemaCurrentIncoming,
 	providedSchema: IDocumentSchemaCurrent,
 ): IDocumentSchemaCurrent {
 	const runtime = {};
@@ -328,15 +381,22 @@ function and(
 			providedSchema.runtime[key],
 		);
 	}
+
+	// We keep the persisted minVersionForCollab if present, even if the provided minVersionForCollab
+	// is higher.
+	const minVersionForCollab =
+		persistedSchema.info?.minVersionForCollab ?? providedSchema.info.minVersionForCollab;
+
 	return {
 		version: currentDocumentVersionSchema,
 		refSeq: persistedSchema.refSeq,
+		info: { minVersionForCollab },
 		runtime,
 	};
 }
 
 function or(
-	persistedSchema: IDocumentSchemaCurrent,
+	persistedSchema: IDocumentSchemaCurrentIncoming,
 	providedSchema: IDocumentSchemaCurrent,
 ): IDocumentSchemaCurrent {
 	const runtime = {};
@@ -349,17 +409,40 @@ function or(
 			providedSchema.runtime[key],
 		);
 	}
+
+	// We take the greater of the persisted/provided minVersionForCollab
+	const minVersionForCollab =
+		persistedSchema.info === undefined
+			? providedSchema.info.minVersionForCollab
+			: gt(persistedSchema.info.minVersionForCollab, providedSchema.info.minVersionForCollab)
+				? persistedSchema.info.minVersionForCollab
+				: providedSchema.info.minVersionForCollab;
+
 	return {
 		version: currentDocumentVersionSchema,
 		refSeq: persistedSchema.refSeq,
+		info: { minVersionForCollab },
 		runtime,
 	};
 }
 
+/**
+ * Determines if two schemas are the "same".
+ * Schemas are considered **not** the same if a schema change op is required to make
+ * the properties of `persistedSchema` match to the properties of `providedSchema`.
+ */
 function same(
-	persistedSchema: IDocumentSchemaCurrent,
+	persistedSchema: IDocumentSchemaCurrentIncoming,
 	providedSchema: IDocumentSchemaCurrent,
 ): boolean {
+	if (
+		persistedSchema.info === undefined ||
+		lt(persistedSchema.info.minVersionForCollab, providedSchema.info.minVersionForCollab)
+	) {
+		// If the persisted schema's minVersionForCollab is undefined or less than the provided schema's
+		// minVersionForCollab, then we should send a schema change op to update the minVersionForCollab.
+		return false;
+	}
 	for (const key of new Set([
 		...Object.keys(persistedSchema.runtime),
 		...Object.keys(providedSchema.runtime),
@@ -483,6 +566,8 @@ export class DocumentsSchemaController {
 	 * @param documentMetadataSchema - current document's schema, if present.
 	 * @param features - features of the document schema that current session wants to see enabled.
 	 * @param onSchemaChange - callback that is called whenever schema is changed (not called on creation / load, only when processing document schema change ops)
+	 * @param info - Informational properties of the document that are not subject to strict schema enforcement
+	 * @param logger - telemetry logger from the runtime
 	 */
 	constructor(
 		existing: boolean,
@@ -490,6 +575,8 @@ export class DocumentsSchemaController {
 		documentMetadataSchema: IDocumentSchema | undefined,
 		features: IDocumentSchemaFeatures,
 		private readonly onSchemaChange: (schema: IDocumentSchemaCurrent) => void,
+		info: IDocumentSchemaInfo,
+		logger: ITelemetryLoggerExt,
 	) {
 		// For simplicity, let's only support new schema features for explicit schema control mode
 		assert(
@@ -497,10 +584,34 @@ export class DocumentsSchemaController {
 			0x949 /* not supported */,
 		);
 
+		// We check the document's metadata to see if there is a minVersionForCollab. If it's not an existing document or
+		// if the document is older, then it won't have one. If it does have a minVersionForCollab, we check if it's greater
+		// than this client's runtime version. If so, we log a telemetry event to warn the customer that the client is outdated.
+		// Note: We only send a warning because we will confirm via `checkRuntimeCompatibility` if this client **can** understand
+		// the existing document's schema. We still want to issue a warning regardless if this client can or cannot understand the
+		// schema since it may be a sign that the customer is not properly waiting for saturation before updating their
+		// `minVersionForCollab` value, which could cause disruptions to users in the future.
+		const existingMinVersionForCollab = documentMetadataSchema?.info?.minVersionForCollab;
+		if (
+			existingMinVersionForCollab !== undefined &&
+			gt(existingMinVersionForCollab, pkgVersion) &&
+			// We also want to avoid sending the telemetry warning for dev builds, since they currently are formatted as
+			// `0.0.0-#####-test`. This will cause the telemetry warning to constantly fire.
+			// TODO: This can be removed after ADO:41351
+			!isDevBuild(pkgVersion)
+		) {
+			const warnMsg = `WARNING: The version of Fluid Framework used by this client (${pkgVersion}) is not supported by this document! Please upgrade to version ${existingMinVersionForCollab} or later to ensure compatibility.`;
+			logger.sendTelemetryEvent({
+				eventName: "MinVersionForCollabWarning",
+				message: warnMsg,
+			});
+		}
+
 		// Desired schema by this session - almost all props are coming from arguments
 		this.desiredSchema = {
 			version: currentDocumentVersionSchema,
 			refSeq: documentMetadataSchema?.refSeq ?? 0,
+			info,
 			runtime: {
 				explicitSchemaControl: boolToProp(features.explicitSchemaControl),
 				compressionLz4: boolToProp(features.compressionLz4),
@@ -520,6 +631,7 @@ export class DocumentsSchemaController {
 					version: currentDocumentVersionSchema,
 					// see comment in summarizeDocumentSchema() on why it has to stay zero
 					refSeq: 0,
+					info,
 					// If it's existing document and it has no schema, then it was written by legacy client.
 					// If it's a new document, then we define it's legacy-related behaviors.
 					runtime: {
@@ -662,7 +774,7 @@ export class DocumentsSchemaController {
 			const schema = {
 				...content,
 				refSeq: sequenceNumber,
-			} satisfies IDocumentSchemaCurrent;
+			} satisfies IDocumentSchemaCurrentIncoming;
 			this.documentSchema = schema;
 			this.sessionSchema = and(schema, this.desiredSchema);
 			assert(this.sessionSchema.refSeq === sequenceNumber, 0x97d /* seq# */);
@@ -693,4 +805,12 @@ export class DocumentsSchemaController {
 	}
 }
 
+/**
+ * Determines if a given version is a dev-build (i.e. `0.0.0-#####-test`).
+ */
+function isDevBuild(version: string): boolean {
+	const parsed = parse(version);
+	return parsed !== null && parsed.prerelease.includes("test");
+}
+
 /* eslint-enable jsdoc/check-indentation */

package/src/summary/index.ts

@@ -103,6 +103,7 @@ export {
 	IdCompressorMode,
 	IDocumentSchemaCurrent,
 	IDocumentSchema,
+	IDocumentSchemaInfo,
 	currentDocumentVersionSchema,
 	DocumentSchemaValueType,
 	DocumentsSchemaController,