Runtime: Begin to deprecate Compat Details on ContainerRuntime messages (#21355)

This last year we added support to include "compat details" on an op,
with the one feature there being the ability to say "it's ok if you
don't recognize this op type, just ignore it". We added this to try to
speed up early development of features that introduce new op types - GC
in particular.

But upon further reflection, this is a very dubious prospect. It glosses
over a ton of complex cases that end up making little sense. Not worth
any perceived utility.

So we are deprecating it and will soon remove it.

Author: markfields

packages/runtime/container-runtime/package.json

@@ -287,6 +287,10 @@
 			},
 			"InterfaceDeclaration_IGCNodeUpdatedProps": {
 				"forwardCompat": false
+			},
+			"RemovedInterfaceDeclaration_ContainerRuntimeMessage": {
+				"backCompat": false,
+				"forwardCompat": false
 			}
 		}
 	}

packages/runtime/container-runtime/src/gc/garbageCollection.ts

@@ -746,7 +746,7 @@ export class GarbageCollector implements IGarbageCollector {
 			const containerGCMessage: ContainerRuntimeGCMessage = {
 				type: ContainerMessageType.GC,
 				contents,
-				compatDetails: { behavior: "Ignore" },
+				compatDetails: { behavior: "Ignore" }, // DEPRECATED: For temporary back compat only
 			};
 			this.submitMessage(containerGCMessage);
 			return;
@@ -1095,7 +1095,7 @@ export class GarbageCollector implements IGarbageCollector {
 				type: GarbageCollectionMessageType.TombstoneLoaded,
 				nodePath,
 			},
-			compatDetails: { behavior: "Ignore" },
+			compatDetails: { behavior: "Ignore" }, // DEPRECATED: For temporary back compat only
 		};
 		this.submitMessage(containerGCMessage);
 	}

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

@@ -25,7 +25,6 @@ export {
 } from "./containerRuntime.js";
 export {
 	ContainerMessageType,
-	ContainerRuntimeMessage,
 	IContainerRuntimeMessageCompatDetails,
 	CompatModeBehavior,
 	RecentlyAddedContainerRuntimeMessageDetails,

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

@@ -60,6 +60,7 @@ export enum ContainerMessageType {
 /**
  * How should an older client handle an unrecognized remote op type?
  *
+ * @deprecated The utility of a mechanism to handle unknown messages is outweighed by the nuance required to get it right.
  * @internal
  */
 export type CompatModeBehavior =
@@ -71,6 +72,7 @@ export type CompatModeBehavior =
 /**
  * All the info an older client would need to know how to handle an unrecognized remote op type
  *
+ * @deprecated The utility of a mechanism to handle unknown messages is outweighed by the nuance required to get it right.
  * @internal
  */
 export interface IContainerRuntimeMessageCompatDetails {
@@ -85,8 +87,7 @@ export interface IContainerRuntimeMessageCompatDetails {
  * IMPORTANT: when creating one to be serialized, set the properties in the order they appear here.
  * This way stringified values can be compared.
  */
-interface TypedContainerRuntimeMessage<TType extends ContainerMessageType, TContents>
-	extends Partial<RecentlyAddedContainerRuntimeMessageDetails> {
+interface TypedContainerRuntimeMessage<TType extends ContainerMessageType, TContents> {
 	/** Type of the op, within the ContainerRuntime's domain */
 	type: TType;
 	/** Domain-specific contents, interpreted according to the type */
@@ -95,6 +96,7 @@ interface TypedContainerRuntimeMessage<TType extends ContainerMessageType, TCont
 
 /**
  * Additional details expected for any recently added message.
+ * @deprecated The utility of a mechanism to handle unknown messages is outweighed by the nuance required to get it right.
  * @internal
  */
 export interface RecentlyAddedContainerRuntimeMessageDetails {
@@ -137,7 +139,9 @@ export type ContainerRuntimeIdAllocationMessage = TypedContainerRuntimeMessage<
 export type ContainerRuntimeGCMessage = TypedContainerRuntimeMessage<
 	ContainerMessageType.GC,
 	GarbageCollectionMessage
->;
+> &
+	// While deprecating: GC messages may still contain compat details for now
+	Partial<RecentlyAddedContainerRuntimeMessageDetails>;
 export type ContainerRuntimeDocumentSchemaMessage = TypedContainerRuntimeMessage<
 	ContainerMessageType.DocumentSchemaChange,
 	IDocumentSchemaChangeMessage
@@ -232,23 +236,3 @@ export type InboundSequencedContainerRuntimeMessageOrSystemMessage =
  */
 export type InboundSequencedRecentlyAddedContainerRuntimeMessage = ISequencedDocumentMessage &
 	Partial<RecentlyAddedContainerRuntimeMessageDetails>;
-
-/**
- * The unpacked runtime message / details to be handled or dispatched by the ContainerRuntime
- *
- * IMPORTANT: when creating one to be serialized, set the properties in the order they appear here.
- * This way stringified values can be compared.
- *
- * @deprecated this is an internal type which should not be used outside of the package.
- * Internally, it is superseded by `TypedContainerRuntimeMessage`.
- *
- * @internal
- */
-export interface ContainerRuntimeMessage {
-	/** Type of the op, within the ContainerRuntime's domain */
-	type: ContainerMessageType;
-	/** Domain-specific contents, interpreted according to the type */
-	contents: any;
-	/** Info describing how to handle this op in case the type is unrecognized (default: fail to process) */
-	compatDetails?: IContainerRuntimeMessageCompatDetails;
-}

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

@@ -64,6 +64,7 @@ import {
 } from "../containerRuntime.js";
 import {
 	ContainerMessageType,
+	type ContainerRuntimeGCMessage,
 	type OutboundContainerRuntimeMessage,
 	type RecentlyAddedContainerRuntimeMessageDetails,
 	type UnknownContainerRuntimeMessage,
@@ -75,6 +76,12 @@ import {
 } from "../pendingStateManager.js";
 import { ISummaryCancellationToken, neverCancelledSummaryToken } from "../summary/index.js";
 
+// Type test:
+const outboundMessage: OutboundContainerRuntimeMessage =
+	{} as unknown as OutboundContainerRuntimeMessage;
+// @ts-expect-error Outbound type should not include compat behavior
+(() => {})(outboundMessage.compatDetails);
+
 function submitDataStoreOp(
 	runtime: Pick<ContainerRuntime, "submitMessage">,
 	id: string,
@@ -973,7 +980,7 @@ describe("Runtime", () => {
 			);
 		});
 
-		describe("Future op type compatibility", () => {
+		describe("[DEPRECATED] Future op type compatibility", () => {
 			let containerRuntime: ContainerRuntime;
 			beforeEach(async () => {
 				containerRuntime = await ContainerRuntime.loadRuntime({
@@ -988,7 +995,7 @@ describe("Runtime", () => {
 				});
 			});
 
-			it("can submit op compat behavior", async () => {
+			it("can submit op compat behavior (temporarily still available for GC op)", async () => {
 				// Create a container runtime type where the submit method is public. This makes it easier to test
 				// submission and processing of ops. The other option is to send data store or alias ops whose
 				// processing requires creation of data store context and runtime as well.
@@ -1002,22 +1009,16 @@ describe("Runtime", () => {
 				const containerRuntimeWithSubmit =
 					containerRuntime as unknown as ContainerRuntimeWithSubmit;
 
-				const runtimeCompatMessage: Omit<
-					OutboundContainerRuntimeMessage,
-					"type" | "contents"
-				> & {
-					type: string;
-					contents: any;
-				} = {
-					type: "NEW",
-					contents: "Hello",
+				const gcMessageWithDeprecatedCompatDetails: ContainerRuntimeGCMessage = {
+					type: ContainerMessageType.GC,
+					contents: { type: "Sweep", deletedNodeIds: [] },
 					compatDetails: { behavior: "Ignore" },
 				};
 
 				assert.doesNotThrow(
 					() =>
 						containerRuntimeWithSubmit.submit(
-							runtimeCompatMessage as OutboundContainerRuntimeMessage,
+							gcMessageWithDeprecatedCompatDetails,
 							undefined,
 							undefined,
 						),

packages/runtime/container-runtime/src/test/types/validateContainerRuntimePrevious.generated.ts

@@ -248,28 +248,16 @@ use_old_ClassDeclaration_ContainerRuntime(
  * If this test starts failing, it indicates a change that is not forward compatible.
  * To acknowledge the breaking change, add the following to package.json under
  * typeValidation.broken:
- * "InterfaceDeclaration_ContainerRuntimeMessage": {"forwardCompat": false}
+ * "RemovedInterfaceDeclaration_ContainerRuntimeMessage": {"forwardCompat": false}
  */
-declare function get_old_InterfaceDeclaration_ContainerRuntimeMessage():
-    TypeOnly<old.ContainerRuntimeMessage>;
-declare function use_current_InterfaceDeclaration_ContainerRuntimeMessage(
-    use: TypeOnly<current.ContainerRuntimeMessage>): void;
-use_current_InterfaceDeclaration_ContainerRuntimeMessage(
-    get_old_InterfaceDeclaration_ContainerRuntimeMessage());
 
 /*
  * Validate backward compatibility by using the current type in place of the old type.
  * If this test starts failing, it indicates a change that is not backward compatible.
  * To acknowledge the breaking change, add the following to package.json under
  * typeValidation.broken:
- * "InterfaceDeclaration_ContainerRuntimeMessage": {"backCompat": false}
+ * "RemovedInterfaceDeclaration_ContainerRuntimeMessage": {"backCompat": false}
  */
-declare function get_current_InterfaceDeclaration_ContainerRuntimeMessage():
-    TypeOnly<current.ContainerRuntimeMessage>;
-declare function use_old_InterfaceDeclaration_ContainerRuntimeMessage(
-    use: TypeOnly<old.ContainerRuntimeMessage>): void;
-use_old_InterfaceDeclaration_ContainerRuntimeMessage(
-    get_current_InterfaceDeclaration_ContainerRuntimeMessage());
 
 /*
  * Validate forward compatibility by using the old type in place of the current type.

packages/test/test-end-to-end-tests/src/test/batching.spec.ts

@@ -148,7 +148,7 @@ describeCompat("Flushing ops", "NoCompat", (getTestObjectProvider, apis) => {
 		await provider.ensureSynchronized();
 	}
 
-	it("can send and a batch containing a future/unknown op type", async () => {
+	it("[DEPRECATED] can send and a batch containing a future/unknown op type", async () => {
 		await setupContainers({
 			flushMode: FlushMode.TurnBased,
 			compressionOptions: {

packages/test/test-end-to-end-tests/src/test/stashedOps.spec.ts

@@ -376,6 +376,7 @@ describeCompat("stashed ops", "NoCompat", (getTestObjectProvider, apis) => {
 				const string = await d.getSharedObject<SharedString>(stringId);
 				const collection = string.getIntervalCollection(collectionId);
 				collection.add({ start: testStart, end: testEnd });
+				// [DEPRECATED]
 				// Submit a message with an unrecognized type
 				// Super rare corner case where you stash an op and then roll back to a previous runtime version that doesn't recognize it
 				(

packages/test/test-service-load/src/loadTestDataStore.ts

@@ -652,6 +652,7 @@ class LoadTestDataStore extends DataObject implements ILoadTest {
 				largeOpsSent++;
 			}
 
+			// [DEPRECATED] This flow is deprecated and is expected to be removed from FF soon.
 			if (futureOpPeriod !== undefined && opsSent % futureOpPeriod === 0) {
 				(
 					this.context.containerRuntime as unknown as {