@fluidframework/container-runtime 2.42.0 → 2.43.0

package/src/pendingStateManager.ts

@@ -48,9 +48,9 @@ export interface IPendingMessage {
 	content: string;
 	/**
 	 * The original runtime op that was submitted to the ContainerRuntime
-	 * Unless this pending message came from stashed content, in which case this was roundtripped through string
+	 * Unless this pending message came from stashed content, in which case this is undefined at first and then deserialized from the contents string
 	 */
-	runtimeOp?: LocalContainerRuntimeMessage | EmptyGroupedBatch | undefined; // Undefined for initial messages before parsing
+	runtimeOp: LocalContainerRuntimeMessage | EmptyGroupedBatch | undefined; // Undefined for initial messages before parsing
 	/**
 	 * Local Op Metadata that was passed to the ContainerRuntime when the op was submitted.
 	 * This contains state needed when processing the ack, or to resubmit or rollback the op.
@@ -234,10 +234,11 @@ function toSerializableForm(
 
 interface ReplayPendingStateOptions {
 	/**
-	 * If true, only replay staged batches. This is used when we are exiting staging mode and want to rebase and submit the staged batches.
+	 * If true, only replay staged batches, clearing the "staged" flag.
+	 * This is used when we are exiting staging mode and want to rebase and submit the staged batches without resubmitting pre-staged messages.
 	 * Default: false
 	 */
-	onlyStagedBatches: boolean;
+	committingStagedBatches: boolean;
 	/**
 	 * @param squash - If true, edits should be squashed when resubmitting.
 	 * Default: false
@@ -246,7 +247,7 @@ interface ReplayPendingStateOptions {
 }
 
 const defaultReplayPendingStatesOptions: ReplayPendingStateOptions = {
-	onlyStagedBatches: false,
+	committingStagedBatches: false,
 	squash: false,
 };
 
@@ -300,8 +301,8 @@ export class PendingStateManager implements IDisposable {
 		for (let i = 0; i < this.pendingMessages.length; i++) {
 			const element = this.pendingMessages.get(i);
 			if (
-				element?.runtimeOp !== undefined &&
-				isNotEmptyGroupedBatch(element) &&
+				element !== undefined &&
+				hasTypicalRuntimeOp(element) && // Empty batches don't count towards user changes
 				isContainerMessageDirtyable(element.runtimeOp)
 			) {
 				return true;
@@ -742,16 +743,18 @@ export class PendingStateManager implements IDisposable {
 	 * states in its queue. This includes triggering resubmission of unacked ops.
 	 * ! Note: successfully resubmitting an op that has been successfully sequenced is not possible due to checks in the ConnectionStateHandler (Loader layer)
 	 */
-	public replayPendingStates(optionsParam?: ReplayPendingStateOptions): void {
-		const options = { ...defaultReplayPendingStatesOptions, ...optionsParam };
-		const { onlyStagedBatches, squash } = options;
+	public replayPendingStates(options?: ReplayPendingStateOptions): void {
+		const { committingStagedBatches, squash } = {
+			...defaultReplayPendingStatesOptions,
+			...options,
+		};
 		assert(
-			this.stateHandler.connected() || onlyStagedBatches === true,
+			this.stateHandler.connected() || committingStagedBatches === true,
 			0x172 /* "The connection state is not consistent with the runtime" */,
 		);
 
 		// Staged batches have not yet been submitted so check doesn't apply
-		if (!onlyStagedBatches) {
+		if (!committingStagedBatches) {
 			// This assert suggests we are about to send same ops twice, which will result in data loss.
 			assert(
 				this.clientIdFromLastReplay !== this.stateHandler.clientId(),
@@ -778,8 +781,8 @@ export class PendingStateManager implements IDisposable {
 			let pendingMessage = this.pendingMessages.shift()!;
 			remainingPendingMessagesCount--;
 
-			// Re-queue pre-staging messages if we are only processing staged batches
-			if (onlyStagedBatches) {
+			// Re-queue pre-staging messages - we are only to replay staged batches
+			if (committingStagedBatches) {
 				if (!pendingMessage.batchInfo.staged) {
 					assert(!seenStagedBatch, 0xb86 /* Staged batch was followed by non-staged batch */);
 					this.pendingMessages.push(pendingMessage);
@@ -807,8 +810,8 @@ export class PendingStateManager implements IDisposable {
 			}
 
 			assert(
-				pendingMessage.runtimeOp !== undefined && isNotEmptyGroupedBatch(pendingMessage),
-				0xb87 /* viableOp is only undefined for empty batches */,
+				hasTypicalRuntimeOp(pendingMessage),
+				0xb87 /* runtimeOp is only undefined for empty batches */,
 			);
 
 			/**
@@ -843,8 +846,8 @@ export class PendingStateManager implements IDisposable {
 			// check is >= because batch end may be last pending message
 			while (remainingPendingMessagesCount >= 0) {
 				assert(
-					pendingMessage.runtimeOp !== undefined && isNotEmptyGroupedBatch(pendingMessage),
-					0xb88 /* viableOp is only undefined for empty batches */,
+					hasTypicalRuntimeOp(pendingMessage),
+					0xb88 /* runtimeOp is only undefined for empty batches */,
 				);
 				batch.push({
 					runtimeOp: pendingMessage.runtimeOp,
@@ -890,15 +893,17 @@ export class PendingStateManager implements IDisposable {
 	 */
 	public popStagedBatches(
 		callback: (
-			stagedMessage: IPendingMessage & { runtimeOp?: LocalContainerRuntimeMessage }, // exclude empty grouped batches
+			// callback will only be given staged messages with a valid runtime op (i.e. not empty batch and not an initial message with only serialized content)
+			stagedMessage: IPendingMessage & { runtimeOp: LocalContainerRuntimeMessage },
 		) => void,
 	): void {
 		while (!this.pendingMessages.isEmpty()) {
 			const stagedMessage = this.pendingMessages.peekBack();
 			if (stagedMessage?.batchInfo.staged === true) {
-				if (isNotEmptyGroupedBatch(stagedMessage)) {
+				this.pendingMessages.pop();
+
+				if (hasTypicalRuntimeOp(stagedMessage)) {
 					callback(stagedMessage);
-					this.pendingMessages.pop();
 				}
 			} else {
 				break; // no more staged messages
@@ -924,7 +929,10 @@ function patchbatchInfo(
 	}
 }
 
-function isNotEmptyGroupedBatch(
+/**
+ * This filters out messages that are not "typical" runtime ops, i.e. empty batches or initial messages (which only have serialized content).
+ */
+function hasTypicalRuntimeOp(
 	message: IPendingMessage,
 ): message is IPendingMessage & { runtimeOp: LocalContainerRuntimeMessage } {
 	return message.runtimeOp !== undefined && message.runtimeOp.type !== "groupedBatch";

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,