@fluidframework/container-runtime 2.0.0-dev.3.1.0.125672 → 2.0.0-dev.4.2.0.153917

package/src/opLifecycle/README.md

@@ -0,0 +1,263 @@
+# Configs and feature gates for solving the 1MB limit.
+
+## Introduction
+
+There is a current limitation regarding the size of the payload a Fluid client can send and receive. [The limit is 1MB per payload](https://github.com/microsoft/FluidFramework/issues/9023) and it is currently enforced explicitly with the `BatchTooLarge` error which closes the container.
+
+There are two features which can be used to work around this size limit, batch compression and compressed batch chunking. This document describes how to enable/disable them, along with a brief description of how they work. The features are enabled by default.
+
+By default, the runtime is configured with a max batch size of `716800` bytes, which is lower than the 1MB limit. The reason for the lower value is to account for possible overhead from the op envelope and metadata.
+
+## Table of contents
+
+-   [Introduction](#introduction)
+    -   [Compression](#compression)
+    -   [Grouped batching](#grouped-batching)
+    -   [Chunking for compression](#chunking-for-compression)
+    -   [Disabling in case of emergency](#disabling-in-case-of-emergency)
+    -   [Example configs](#example-configs)
+    -   [How it works](#how-it-works)
+    -   [How grouped batching works](#how-grouped-batching-works)
+
+## Compression
+
+**Compression targets payloads which exceed the max batch size and it is enabled by default.**. The `IContainerRuntimeOptions.compressionOptions` property, of type `ICompressionRuntimeOptions` is the configuration governing how compression works.
+
+`ICompressionRuntimeOptions` has two properties:
+
+-   `minimumBatchSizeInBytes` – the minimum size of the batch for which compression should kick in. If the payload is too small, compression may not yield too many benefits. To target the original 1MB issue, a good value here would be to match the default maxBatchSizeInBytes (972800), however, experimentally, a good lower value could be at around 614400 bytes. Setting this value to `Number.POSITIVE_INFINITY` will disable compression.
+-   `compressionAlgorithm` – currently, only `lz4` is supported.
+
+## Grouped batching
+
+**Note: This feature is currently considered experimental and is not ready for production usage.**
+
+The `IContainerRuntimeOptions.enableGroupedBatching` option has been added to the container runtime layer and is **off by default**. This option will group all batch messages under a new "grouped" message to be sent to the service. Upon receiving this new "grouped" message, the batch messages will be extracted and given the sequence number of the parent "grouped" message.
+
+The purpose for enabling grouped batching on top of compression is that regular compression won't include the empty messages in the chunks. Thus, if we have batches with many messages (i.e. more than 4k), we will go over the batch size limit just on empty op envelopes alone.
+
+See [below](#how-grouped-batching-works) for an example.
+
+## Chunking for compression
+
+**Op chunking for compression targets payloads which exceed the max batch size after compression.** So, only payloads which are already compressed. By default, the feature is enabled.
+
+The `IContainerRuntimeOptions.chunkSizeInBytes` property is the only configuration for chunking and it represents the size of the chunked ops, when chunking is necessary. When chunking is performed, the large op is split into smaller ops (chunks). This config represents both the size of the chunks and the threshold for the feature to activate. The value enables a trade-off between large chunks / few ops and small chunks / many ops. A good value for this would be at around 204800. Setting this value to `Number.POSITIVE_INFINITY` will disable chunking.
+
+This config would govern chunking compressed batches only. We will not be enabling chunking across all types of ops/batches but **only when compression is enabled and when the batch is compressed**, and its payload size is more than `IContainerRuntimeOptions.chunkSizeInBytes`.
+
+## Disabling in case of emergency
+
+If the features are enabled using the configs, they can be disabled at runtime via feature gates as following:
+
+-   `Fluid.ContainerRuntime.CompressionDisabled` - if set to true, will disable compression (this has a side effect of also disabling chunking, as chunking is invoked only for compressed payloads).
+-   `Fluid.ContainerRuntime.DisableGroupedBatching` - if set to true, will disable grouped batching.
+-   `Fluid.ContainerRuntime.CompressionChunkingDisabled` - if set to true, will disable chunking for compression.
+
+## Example configs
+
+By default, the runtime is configured with the following values related to compression and chunking:
+
+```
+    const runtimeOptions: IContainerRuntimeOptions = {
+        compressionOptions: {
+            minimumBatchSizeInBytes: 614400,
+            compressionAlgorithm: CompressionAlgorithms.lz4,
+        },
+        chunkSizeInBytes: 204800,
+        maxBatchSizeInBytes: 716800,
+    }
+```
+
+To use compression but disable chunking:
+
+```
+    const runtimeOptions: IContainerRuntimeOptions = {
+        chunkSizeInBytes: Number.POSITIVE_INFINITY,
+    }
+```
+
+To disable compression (will also disable chunking, as chunking works only for compressed batches):
+
+```
+    const runtimeOptions: IContainerRuntimeOptions = {
+        compressionOptions: {
+            minimumBatchSizeInBytes: Number.POSITIVE_INFINITY,
+            compressionAlgorithm: CompressionAlgorithms.lz4,
+        },
+    }
+```
+
+To enable grouped batching:
+
+```
+    const runtimeOptions: IContainerRuntimeOptions = {
+        enableGroupedBatching: true,
+    }
+```
+
+## How it works
+
+Compression currently works as a runtime layer over the regular op sending/receiving pipeline.
+
+If we have a batch with a size larger than the configured minimum required for compression (in the example let’s say it’s 850 bytes), as following:
+
+```
++-----------+-----------+-----------+-----------+
+| Op 1      | Op 2      | Op 3      | Op 4      |
+| SeqNum: 1 | SeqNum: 2 | SeqNum: 3 | SeqNum: 4 |
+| Size: 100 | Size: 150 | Size: 200 | Size: 400 |
++-----------+-----------+-----------+-----------+
+```
+
+The total size of the batch is 850 bytes. The client which needs to send the batch would compress the batch to a smaller size (200 bytes) and will send a new batch like the following:
+
+```
++--------------------+-----------+-----------+-----------+
+| Op 1               | Op 2      | Op 3      | Op 4      |
+| SeqNum: 1          | SeqNum: 2 | SeqNum: 3 | SeqNum: 4 |
+| Size: 200          | Size: 0   | Size: 0   | Size: 0   |
+| Compression: 'lz4' |           |           |           |
++--------------------+-----------+-----------+-----------+
+```
+
+The first op in the batch is the only one with content (which is opaque due to it being compressed), the rest of the ops serve only to reserve the sequence numbers so that the state machine which rebuilds the original batch on the receiving client can reconstruct the original batch.
+
+When the batch is received by a client, it will detect the first op as being compressed, it will decompress it and store it in memory. For each empty op subsequently received, it will fetch the uncompressed content from memory and rebuild the original ops. The original ops are then processed by the runtime and applied accordingly.
+So, compression virtualizes the batch.
+
+After compression, the first op in the batch can exceed 1MB, therefore it would still be rejected. In this case, another layer of virtualization is added after compression (and before decompression, symmetrically on the receiving end).
+
+The first op in the compressed batch can be chunked into smaller ops which can be sent outside the original batch. However, to conveniently maintain the batch semantics, the last chunk (the chunk which triggers rebuilding the original op) is the first op in the new batch.
+
+To illustrate, let’s take the large batch below:
+
+```
++--------------------+-----------+-----------+-----------+
+| Op 1               | Op 2      | Op 3      | Op 4      |
+| SeqNum: 1          | SeqNum: 2 | SeqNum: 3 | SeqNum: 4 |
+| Size: 900          | Size: 0   | Size: 0   | Size: 0   |
+| Compression: 'lz4' |           |           |           |
++--------------------+-----------+-----------+-----------+
+```
+
+This will produce the following batches:
+
+```
++-----------+
+| Chunk 1/3 |
+| SeqNum: 1 |
+| Size: 300 |
++-----------+
+
+```
+
+```
++-----------+
+| Chunk 2/3 |
+| SeqNum: 2 |
+| Size: 300 |
++-----------+
+
+```
+
+```
++-----------+-----------+-----------+-----------+
+| Chunk 3/3 | Op 2      | Op 3      | Op 4      |
+| SeqNum: 3 | SeqNum: 4 | SeqNum: 5 | SeqNum: 6 |
+| Size: 300 | Size: 0   | Size: 0   | Size: 0   |
++-----------+-----------+-----------+-----------+
+```
+
+The first 2 chunks are sent in their own batches, while the last chunk is the first op in the last batch which contains the ops reserving the required sequence numbers.
+
+Notice that the sequence numbers don’t matter here, as all ops will be based off the same reference sequence number, so the sequence number will be recalculated for all, without additional work.
+
+Additionally, as compression preserves the original uncompressed batch layout in terms of the number of ops by using empty ops to reserve the sequence numbers, this ensures that the clients will always receive the exact count of ops to rebuild the uncompressed batch sequentially.
+
+On the receiving end, the client will accumulate chunks 1 and 2 and keep them in memory. When chunk 3 is received, the original large, decompressed op will be rebuilt, and the runtime will then process the batch as if it is a compressed batch.
+
+## How grouped batching works
+
+**Note: There are plans to replace empty ops with something more efficient when doing grouped batching AB#4092**
+
+Given the following baseline batch:
+
+```
++---------------+---------------+---------------+---------------+---------------+
+| Op 1          | Op 2          | Op 3          | Op 4          | Op 5          |
+| Contents: "a" | Contents: "b" | Contents: "c" | Contents: "d" | Contents: "e" |
++---------------+---------------+---------------+---------------+---------------+
+```
+
+Compressed batch:
+
+```
++--------------------+-----------------+-----------------+-----------------+-----------------+
+| Op 1               | Op 2            | Op 3            | Op 4            | Op 5            |
+| Contents: "abcde"  | Contents: empty | Contents: empty | Contents: empty | Contents: empty |
+| Compression: 'lz4' |                 |                 |                 |                 |
++--------------------+-----------------+-----------------+-----------------+-----------------+
+```
+
+Grouped batch:
+
+```
++---------------------------------------------------------------------------------------------------------------------------------+
+| Op 1                   Contents: +--------------------+-----------------+-----------------+-----------------+-----------------+ |
+| SeqNum: 1                        | Op 1               | Op 2            | Op 3            | Op 4            | Op 5            | |
+| Type: "groupedBatch"             | Contents: "abcde"  | Contents: empty | Contents: empty | Contents: empty | Contents: empty | |
+|                                  | Compression: 'lz4' |                 |                 |                 |                 | |
+|                                  +--------------------+-----------------+-----------------+-----------------+-----------------+ |
++---------------------------------------------------------------------------------------------------------------------------------+
+```
+
+Can produce the following chunks:
+
+```
++-------------------------------------------------+
+| Chunk 1/2    Contents: +----------------------+ |
+| SeqNum: 1              |  +-----------------+ | |
+|                        |  | Contents: "abc" | | |
+|                        |  +-----------------+ | |
+|                        +----------------------+ |
++-------------------------------------------------+
+```
+
+```
++--------------------------------------------------------------------------------------------------------------------------+
+| Chunk 2/2    Contents: +---------------------------------------------------------------------------------------------+ | |
+| SeqNum: 2              |  +----------------+-----------------+-----------------+-----------------+-----------------+ | | |
+|                        |  | Contents: "de" | Contents: empty | Contents: empty | Contents: empty | Contents: empty | | | |
+|                        |  +----------------+-----------------+-----------------+-----------------+-----------------+ | | |
+|                        +---------------------------------------------------------------------------------------------+ | |
++--------------------------------------------------------------------------------------------------------------------------+
+```
+
+-   Send to service
+-   Service acks ops sent
+-   Receive chunks from service
+-   Recompile to the grouped batch step
+
+Ungrouped batch:
+
+```
++--------------------+-----------------+-----------------+-----------------+-----------------+
+| Op 1               | Op 2            | Op 3            | Op 4            | Op 5            |
+| Contents: "abcde"  | Contents: empty | Contents: empty | Contents: empty | Contents: empty |
+| SeqNum: 2          | SeqNum: 2       | SeqNum: 2       | SeqNum: 2       | SeqNum: 2       |
+| ClientSeqNum: 1    | ClientSeqNum: 2 | ClientSeqNum: 3 | ClientSeqNum: 4 | ClientSeqNum: 5 |
+| Compression: 'lz4' |                 |                 |                 |                 |
++--------------------+-----------------+-----------------+-----------------+-----------------+
+```
+
+Uncompressed batch:
+
+```
++-----------------+-----------------+-----------------+-----------------+-----------------+
+| Op 1            | Op 2            | Op 3            | Op 4            | Op 5            |
+| Contents: "a"   | Contents: "b"   | Contents: "c"   | Contents: "d"   | Contents: "e"   |
+| SeqNum: 2       | SeqNum: 2       | SeqNum: 2       | SeqNum: 2       | SeqNum: 2       |
+| ClientSeqNum: 1 | ClientSeqNum: 2 | ClientSeqNum: 3 | ClientSeqNum: 4 | ClientSeqNum: 5 |
++-----------------+-----------------+-----------------+-----------------+-----------------+
+```

package/src/opLifecycle/batchManager.ts

@@ -3,34 +3,27 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryLogger } from "@fluidframework/common-definitions";
-import { UsageError } from "@fluidframework/driver-utils";
-import { ChildLogger } from "@fluidframework/telemetry-utils";
 import { ICompressionRuntimeOptions } from "../containerRuntime";
 import { BatchMessage, IBatch, IBatchCheckpoint } from "./definitions";
 
 export interface IBatchManagerOptions {
-	readonly enableOpReentryCheck?: boolean;
 	readonly hardLimit: number;
 	readonly softLimit?: number;
 	readonly compressionOptions?: ICompressionRuntimeOptions;
 }
 
+/**
+ * Estimated size of the stringification overhead for an op accumulated
+ * from runtime to loader to the service.
+ */
+const opOverhead = 200;
+
 /**
  * Helper class that manages partial batch & rollback.
  */
 export class BatchManager {
-	private readonly logger;
 	private pendingBatch: BatchMessage[] = [];
 	private batchContentSize = 0;
-	/**
-	 * Track the number of ops which were detected to have a mismatched
-	 * reference sequence number, in order to self-throttle the telemetry events.
-	 *
-	 * This should be removed as part of ADO:2322
-	 */
-	private readonly maxMismatchedOpsToReport = 5;
-	private mismatchedOpsReported = 0;
 
 	public get length() {
 		return this.pendingBatch.length;
@@ -39,13 +32,15 @@ export class BatchManager {
 		return this.batchContentSize;
 	}
 
-	constructor(public readonly options: IBatchManagerOptions, logger: ITelemetryLogger) {
-		this.logger = ChildLogger.create(logger, "BatchManager");
+	public get referenceSequenceNumber(): number | undefined {
+		return this.pendingBatch.length === 0
+			? undefined
+			: this.pendingBatch[this.pendingBatch.length - 1].referenceSequenceNumber;
 	}
 
-	public push(message: BatchMessage): boolean {
-		this.checkReferenceSequenceNumber(message);
+	constructor(public readonly options: IBatchManagerOptions) {}
 
+	public push(message: BatchMessage): boolean {
 		const contentSize = this.batchContentSize + (message.contents?.length ?? 0);
 		const opCount = this.pendingBatch.length;
 
@@ -54,7 +49,7 @@ export class BatchManager {
 		// Also content will be strigified, and that adds a lot of overhead due to a lot of escape characters.
 		// Not taking it into account, as compression work should help there - compressed payload will be
 		// initially stored as base64, and that requires only 2 extra escape characters.
-		const socketMessageSize = contentSize + 200 * opCount;
+		const socketMessageSize = contentSize + opOverhead * opCount;
 
 		// If we were provided soft limit, check for exceeding it.
 		// But only if we have any ops, as the intention here is to flush existing ops (on exceeding this limit)
@@ -86,6 +81,7 @@ export class BatchManager {
 		const batch: IBatch = {
 			content: this.pendingBatch,
 			contentSizeInBytes: this.batchContentSize,
+			referenceSequenceNumber: this.referenceSequenceNumber,
 		};
 
 		this.pendingBatch = [];
@@ -112,43 +108,6 @@ export class BatchManager {
 			},
 		};
 	}
-
-	private checkReferenceSequenceNumber(message: BatchMessage) {
-		if (
-			this.pendingBatch.length === 0 ||
-			message.referenceSequenceNumber === this.pendingBatch[0].referenceSequenceNumber
-		) {
-			// The reference sequence numbers are stable
-			return;
-		}
-
-		const telemetryProperties = {
-			referenceSequenceNumber: this.pendingBatch[0].referenceSequenceNumber,
-			messageReferenceSequenceNumber: message.referenceSequenceNumber,
-			type: message.deserializedContent.type,
-			length: this.pendingBatch.length,
-			enableOpReentryCheck: this.options.enableOpReentryCheck === true,
-		};
-		const error = new UsageError("Submission of an out of order message");
-		const eventName = "ReferenceSequenceNumberMismatch";
-
-		if (this.options.enableOpReentryCheck === true) {
-			this.logger.sendErrorEvent({ eventName, ...telemetryProperties }, error);
-			throw error;
-		}
-
-		if (++this.mismatchedOpsReported <= this.maxMismatchedOpsToReport) {
-			this.logger.sendErrorEvent(
-				{
-					eventName,
-					...telemetryProperties,
-					ops: this.mismatchedOpsReported,
-					maxOps: this.maxMismatchedOpsToReport,
-				},
-				error,
-			);
-		}
-	}
 }
 
 const addBatchMetadata = (batch: IBatch): IBatch => {
@@ -165,3 +124,15 @@ const addBatchMetadata = (batch: IBatch): IBatch => {
 
 	return batch;
 };
+
+/**
+ * Estimates the real size in bytes on the socket for a given batch. It assumes that
+ * the envelope size (and the size of an empty op) is 200 bytes, taking into account
+ * extra overhead from stringification.
+ *
+ * @param batch - the batch to inspect
+ * @returns An estimate of the payload size in bytes which will be produced when the batch is sent over the wire
+ */
+export const estimateSocketSize = (batch: IBatch): number => {
+	return batch.contentSizeInBytes + opOverhead * batch.content.length;
+};

package/src/opLifecycle/definitions.ts

@@ -30,6 +30,10 @@ export interface IBatch {
 	 * All the messages in the batch
 	 */
 	readonly content: BatchMessage[];
+	/**
+	 * The reference sequence number for the batch
+	 */
+	readonly referenceSequenceNumber: number | undefined;
 }
 
 export interface IBatchCheckpoint {

package/src/opLifecycle/index.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-export { BatchManager } from "./batchManager";
+export { BatchManager, estimateSocketSize } from "./batchManager";
 export {
 	BatchMessage,
 	IBatch,
@@ -16,3 +16,4 @@ export { OpCompressor } from "./opCompressor";
 export { OpDecompressor } from "./opDecompressor";
 export { OpSplitter, splitOp } from "./opSplitter";
 export { RemoteMessageProcessor, unpackRuntimeMessage } from "./remoteMessageProcessor";
+export { OpGroupingManager } from "./opGroupingManager";

package/src/opLifecycle/opCompressor.ts

@@ -4,11 +4,12 @@
  */
 
 import { ITelemetryLogger } from "@fluidframework/common-definitions";
-import { IsoBuffer } from "@fluidframework/common-utils";
+import { assert, IsoBuffer } from "@fluidframework/common-utils";
 import { UsageError } from "@fluidframework/container-utils";
 import { ChildLogger } from "@fluidframework/telemetry-utils";
 import { compress } from "lz4js";
 import { CompressionAlgorithms } from "../containerRuntime";
+import { estimateSocketSize } from "./batchManager";
 import { IBatch, BatchMessage } from "./definitions";
 
 /**
@@ -24,21 +25,17 @@ export class OpCompressor {
 	}
 
 	public compressBatch(batch: IBatch): IBatch {
+		assert(
+			batch.contentSizeInBytes > 0 && batch.content.length > 0,
+			0x5a4 /* Batch should not be empty */,
+		);
+
 		const compressionStart = Date.now();
 		const contentsAsBuffer = new TextEncoder().encode(this.serializeBatch(batch));
 		const compressedContents = compress(contentsAsBuffer);
 		const compressedContent = IsoBuffer.from(compressedContents).toString("base64");
 		const duration = Date.now() - compressionStart;
 
-		if (batch.contentSizeInBytes > 200000) {
-			this.logger.sendPerformanceEvent({
-				eventName: "CompressedBatch",
-				duration,
-				sizeBeforeCompression: batch.contentSizeInBytes,
-				sizeAfterCompression: compressedContent.length,
-			});
-		}
-
 		const messages: BatchMessage[] = [];
 		messages.push({
 			...batch.content[0],
@@ -47,14 +44,37 @@ export class OpCompressor {
 			compression: CompressionAlgorithms.lz4,
 		});
 
+		// Add empty placeholder messages to reserve the sequence numbers
 		for (const message of batch.content.slice(1)) {
-			messages.push({ ...message, contents: undefined });
+			messages.push({
+				deserializedContent: {
+					contents: undefined,
+					type: message.deserializedContent.type,
+				},
+				localOpMetadata: message.localOpMetadata,
+				metadata: message.metadata,
+				referenceSequenceNumber: message.referenceSequenceNumber,
+			});
 		}
 
-		return {
+		const compressedBatch: IBatch = {
 			contentSizeInBytes: compressedContent.length,
 			content: messages,
+			referenceSequenceNumber: batch.referenceSequenceNumber,
 		};
+
+		if (batch.contentSizeInBytes > 200000) {
+			this.logger.sendPerformanceEvent({
+				eventName: "CompressedBatch",
+				duration,
+				sizeBeforeCompression: batch.contentSizeInBytes,
+				sizeAfterCompression: compressedBatch.contentSizeInBytes,
+				opCount: compressedBatch.content.length,
+				socketSize: estimateSocketSize(compressedBatch),
+			});
+		}
+
+		return compressedBatch;
 	}
 
 	private serializeBatch(batch: IBatch): string {

package/src/opLifecycle/opDecompressor.ts

@@ -6,6 +6,8 @@
 import { decompress } from "lz4js";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
 import { assert, IsoBuffer, Uint8ArrayToString } from "@fluidframework/common-utils";
+import { ChildLogger } from "@fluidframework/telemetry-utils";
+import { ITelemetryLogger } from "@fluidframework/common-definitions";
 import { CompressionAlgorithms } from "../containerRuntime";
 import { IMessageProcessingResult } from "./definitions";
 
@@ -21,6 +23,11 @@ export class OpDecompressor {
 	private activeBatch = false;
 	private rootMessageContents: any | undefined;
 	private processedCount = 0;
+	private readonly logger;
+
+	constructor(logger: ITelemetryLogger) {
+		this.logger = ChildLogger.create(logger, "OpDecompressor");
+	}
 
 	public processMessage(message: ISequencedDocumentMessage): IMessageProcessingResult {
 		assert(
@@ -28,7 +35,7 @@ export class OpDecompressor {
 			0x511 /* Only lz4 compression is supported */,
 		);
 
-		if (message.metadata?.batch === true && message.compression === CompressionAlgorithms.lz4) {
+		if (message.metadata?.batch === true && this.isCompressed(message)) {
 			// Beginning of a compressed batch
 			assert(this.activeBatch === false, 0x4b8 /* shouldn't have multiple active batches */);
 			if (message.compression) {
@@ -84,10 +91,7 @@ export class OpDecompressor {
 			};
 		}
 
-		if (
-			message.metadata?.batch === undefined &&
-			message.compression === CompressionAlgorithms.lz4
-		) {
+		if (message.metadata?.batch === undefined && this.isCompressed(message)) {
 			// Single compressed message
 			assert(
 				this.activeBatch === false,
@@ -110,6 +114,47 @@ export class OpDecompressor {
 			state: "Skipped",
 		};
 	}
+
+	private isCompressed(message: ISequencedDocumentMessage) {
+		if (message.compression === CompressionAlgorithms.lz4) {
+			return true;
+		}
+
+		/**
+		 * Back-compat self healing mechanism for ADO:3538, as loaders from
+		 * version client_v2.0.0-internal.1.2.0 to client_v2.0.0-internal.2.2.0 do not
+		 * support adding the proper compression metadata to compressed messages submitted
+		 * by the runtime. Should be removed after the loader reaches sufficient saturation
+		 * for a version greater or equal than client_v2.0.0-internal.2.2.0.
+		 *
+		 * The condition holds true for compressed messages, regardless of metadata. We are ultimately
+		 * looking for a message with a single property `packedContents` inside `contents`, of type 'string'
+		 * with a base64 encoded value.
+		 */
+		try {
+			if (
+				message.contents !== null &&
+				typeof message.contents === "object" &&
+				Object.keys(message.contents).length === 1 &&
+				message.contents?.packedContents !== undefined &&
+				typeof message.contents?.packedContents === "string" &&
+				message.contents.packedContents.length > 0 &&
+				IsoBuffer.from(message.contents.packedContents, "base64").toString("base64") ===
+					message.contents.packedContents
+			) {
+				this.logger.sendTelemetryEvent({
+					eventName: "LegacyCompression",
+					type: message.type,
+					batch: message.metadata?.batch,
+				});
+				return true;
+			}
+		} catch (err) {
+			return false;
+		}
+
+		return false;
+	}
 }
 
 // We should not be mutating the input message nor its metadata

package/src/opLifecycle/opGroupingManager.ts

@@ -0,0 +1,78 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/common-utils";
+import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
+import { ContainerRuntimeMessage } from "..";
+import { IBatch } from "./definitions";
+
+interface IGroupedMessage {
+	contents?: unknown;
+	metadata?: Record<string, unknown>;
+	compression?: string;
+}
+
+export class OpGroupingManager {
+	static groupedBatchOp = "groupedBatch";
+
+	constructor(private readonly groupedBatchingEnabled: boolean) {}
+
+	public groupBatch(batch: IBatch): IBatch {
+		if (batch.content.length < 2 || !this.groupedBatchingEnabled) {
+			return batch;
+		}
+
+		for (const message of batch.content) {
+			if (message.metadata) {
+				const keys = Object.keys(message.metadata);
+				assert(keys.length < 2, 0x5dd /* cannot group ops with metadata */);
+				assert(
+					keys.length === 0 || keys[0] === "batch",
+					0x5de /* unexpected op metadata */,
+				);
+			}
+		}
+
+		// Need deserializedContent for back-compat
+		const deserializedContent = {
+			type: OpGroupingManager.groupedBatchOp,
+			contents: batch.content.map<IGroupedMessage>((message) => ({
+				contents: message.contents === undefined ? undefined : JSON.parse(message.contents),
+				metadata: message.metadata,
+				compression: message.compression,
+			})),
+		};
+
+		const groupedBatch: IBatch = {
+			...batch,
+			content: [
+				{
+					localOpMetadata: undefined,
+					metadata: undefined,
+					referenceSequenceNumber: batch.content[0].referenceSequenceNumber,
+					deserializedContent: deserializedContent as ContainerRuntimeMessage,
+					contents: JSON.stringify(deserializedContent),
+				},
+			],
+		};
+		return groupedBatch;
+	}
+
+	public ungroupOp(op: ISequencedDocumentMessage): ISequencedDocumentMessage[] {
+		if (op.contents?.type !== OpGroupingManager.groupedBatchOp) {
+			return [op];
+		}
+
+		const messages = op.contents.contents as IGroupedMessage[];
+		let fakeCsn = 1;
+		return messages.map((subMessage) => ({
+			...op,
+			clientSequenceNumber: fakeCsn++,
+			contents: subMessage.contents,
+			metadata: subMessage.metadata,
+			compression: subMessage.compression,
+		}));
+	}
+}