@fluidframework/container-runtime 2.0.0-dev.4.1.0.148229 → 2.0.0-dev.4.3.0.157531

package/src/id-compressor/utils.ts

@@ -0,0 +1,114 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Remove `readonly` from all fields.
+ */
+export type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+
+/** A union type of the first `N` positive integers */
+export type TakeWholeNumbers<N extends number, A extends never[] = []> = N extends A["length"]
+	? never
+	: A["length"] | TakeWholeNumbers<N, [never, ...A]>;
+
+/** Returns a tuple type with exactly `Length` elements of type `T` */
+export type ArrayOfLength<T, Length extends number, A extends T[] = []> = Length extends A["length"]
+	? A
+	: ArrayOfLength<T, Length, [T, ...A]>;
+
+/**
+ * Fails true iff `array` has at least `length` elements
+ */
+export function hasAtLeastLength<T, Len extends TakeWholeNumbers<16>>(
+	array: readonly T[],
+	length: Len,
+): array is [...ArrayOfLength<T, Len>, ...T[]] {
+	return array.length >= length;
+}
+
+/**
+ * A numeric comparator used for sorting in ascending order.
+ *
+ * Handles +/-0 like Map: -0 is equal to +0.
+ */
+export function compareFiniteNumbers<T extends number>(a: T, b: T): number {
+	return a - b;
+}
+
+/**
+ * A numeric comparator used for sorting in descending order.
+ *
+ * Handles +/-0 like Map: -0 is equal to +0.
+ */
+export function compareFiniteNumbersReversed<T extends number>(a: T, b: T): number {
+	return b - a;
+}
+
+/**
+ * Compare two maps and return true if their contents are equivalent.
+ * @param mapA - The first array to compare
+ * @param mapB - The second array to compare
+ * @param elementComparator - The function used to check if two `T`s are equivalent.
+ * Defaults to `Object.is()` equality (a shallow compare)
+ */
+export function compareMaps<K, V>(
+	mapA: ReadonlyMap<K, V>,
+	mapB: ReadonlyMap<K, V>,
+	elementComparator: (a: V, b: V) => boolean = Object.is,
+): boolean {
+	if (mapA.size !== mapB.size) {
+		return false;
+	}
+
+	for (const [keyA, valueA] of mapA) {
+		const valueB = mapB.get(keyA);
+		if (valueB === undefined || !elementComparator(valueA, valueB)) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+/**
+ * Retrieve a value from a map with the given key, or create a new entry if the key is not in the map.
+ * @param map - The map to query/update
+ * @param key - The key to lookup in the map
+ * @param defaultValue - a function which returns a default value. This is called and used to set an initial value for the given key in the map if none exists
+ * @returns either the existing value for the given key, or the newly-created value (the result of `defaultValue`)
+ */
+export function getOrCreate<K, V>(map: Map<K, V>, key: K, defaultValue: (key: K) => V): V {
+	let value = map.get(key);
+	if (value === undefined) {
+		value = defaultValue(key);
+		map.set(key, value);
+	}
+	return value;
+}
+
+/**
+ * Compares strings lexically to form a strict partial ordering.
+ */
+export function compareStrings<T extends string>(a: T, b: T): number {
+	return a > b ? 1 : a === b ? 0 : -1;
+}
+
+export function fail(message: string): never {
+	throw new Error(message);
+}
+
+/**
+ * Sets a property in such a way that it is only set on `destination` if the provided value is not undefined.
+ * This avoids having explicit undefined values under properties that would cause `Object.hasOwnProperty` to return true.
+ */
+export function setPropertyIfDefined<TDst, P extends keyof TDst>(
+	value: TDst[P] | undefined,
+	destination: TDst,
+	property: P,
+): void {
+	if (value !== undefined) {
+		destination[property] = value;
+	}
+}

package/src/id-compressor/uuidUtilities.ts

@@ -0,0 +1,123 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/common-utils";
+import { StableId, UuidString } from "@fluidframework/runtime-definitions";
+import { v4, NIL } from "uuid";
+
+const hexadecimalCharCodes = Array.from("09afAF").map((c) => c.charCodeAt(0)) as [
+	zero: number,
+	nine: number,
+	a: number,
+	f: number,
+	A: number,
+	F: number,
+];
+
+function isHexadecimalCharacter(charCode: number): boolean {
+	return (
+		(charCode >= hexadecimalCharCodes[0] && charCode <= hexadecimalCharCodes[1]) ||
+		(charCode >= hexadecimalCharCodes[2] && charCode <= hexadecimalCharCodes[3]) ||
+		(charCode >= hexadecimalCharCodes[4] && charCode <= hexadecimalCharCodes[5])
+	);
+}
+
+/** The null (lowest/all-zeros) UUID */
+export const nilUuid = assertIsUuidString(NIL);
+
+/**
+ * Asserts that the given string is a UUID
+ */
+export function assertIsUuidString(uuidString: string): UuidString {
+	assert(isUuidString(uuidString), 0x4a2 /* Expected an UuidString */);
+	return uuidString;
+}
+
+/**
+ * Returns true iff the given string is a valid UUID-like string of hexadecimal characters
+ * 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+ */
+export function isUuidString(str: string): str is UuidString {
+	for (let i = 0; i < str.length; i++) {
+		switch (i) {
+			case 8:
+			case 13:
+			case 18:
+			case 23:
+				if (str.charAt(i) !== "-") {
+					return false;
+				}
+				break;
+
+			default:
+				if (!isHexadecimalCharacter(str.charCodeAt(i))) {
+					return false;
+				}
+				break;
+		}
+	}
+
+	return true;
+}
+
+/**
+ * Generate a random stable ID
+ */
+export function generateStableId(): StableId {
+	return assertIsStableId(v4());
+}
+
+/**
+ * Asserts that the given string is a stable ID.
+ */
+export function assertIsStableId(stableId: string): StableId {
+	assert(isStableId(stableId), 0x4a3 /* Expected a StableId */);
+	return stableId;
+}
+
+/**
+ * Returns true iff the given string is a valid Version 4, variant 2 UUID
+ * 'xxxxxxxx-xxxx-4xxx-vxxx-xxxxxxxxxxxx'
+ */
+export function isStableId(str: string): str is StableId {
+	if (str.length !== 36) {
+		return false;
+	}
+
+	for (let i = 0; i < str.length; i++) {
+		switch (i) {
+			case 8:
+			case 13:
+			case 18:
+			case 23:
+				if (str.charAt(i) !== "-") {
+					return false;
+				}
+				break;
+
+			case 14:
+				if (str.charAt(i) !== "4") {
+					return false;
+				}
+				break;
+
+			case 19: {
+				const char = str.charAt(i);
+				if (char !== "8" && char !== "9" && char !== "a" && char !== "b") {
+					return false;
+				}
+				break;
+			}
+
+			default:
+				if (!isHexadecimalCharacter(str.charCodeAt(i))) {
+					return false;
+				}
+				break;
+		}
+	}
+
+	return true;
+}

package/src/index.ts

@@ -69,3 +69,4 @@ export {
 	ICancellableSummarizerController,
 } from "./summary";
 export { IChunkedOp, unpackRuntimeMessage } from "./opLifecycle";
+export { generateStableId, isStableId, assertIsStableId } from "./id-compressor";

package/src/opLifecycle/README.md

@@ -12,10 +12,13 @@ By default, the runtime is configured with a max batch size of `716800` bytes, w
 
 -   [Introduction](#introduction)
     -   [Compression](#compression)
+    -   [Grouped batching](#grouped-batching)
+        -   [Risks](#risks)
     -   [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
 
@@ -26,6 +29,28 @@ By default, the runtime is configured with a max batch size of `716800` bytes, w
 -   `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.
+
+### Risks
+
+This option is experimental and should not be enabled yet in production. This option should **ONLY** be enabled after observing that 99.9% of your application sessions contains these changes (runtime version "2.0.0-internal.4.1.0" or later). Containers created with this option may not open in future versions of the framework.
+
+This option will change a couple of expectations around message structure and runtime layer expectations. Only enable this option after testing
+and verifying that the following expectation changes won't have any effects:
+
+-   batch messages observed at the runtime layer will not match messages seen at the loader layer (i.e. grouped form at loader layer, ungrouped form at runtime layer)
+-   messages within the same batch will have the same sequence number
+-   client sequence numbers on batch messages can only be used to order messages with the same sequenceNumber
+-   requires all ops to be processed by runtime layer (version "2.0.0-internal.1.2.0" or later https://github.com/microsoft/FluidFramework/pull/11832)
+
 ## 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.
@@ -39,6 +64,7 @@ This config would govern chunking compressed batches only. We will not be enabli
 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
@@ -75,6 +101,14 @@ To disable compression (will also disable chunking, as chunking works only for c
     }
 ```
 
+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.
@@ -155,3 +189,88 @@ Notice that the sequence numbers don’t matter here, as all ops will be based o
 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

@@ -12,6 +12,11 @@ export interface IBatchManagerOptions {
 	readonly compressionOptions?: ICompressionRuntimeOptions;
 }
 
+export interface BatchSequenceNumbers {
+	referenceSequenceNumber?: number;
+	clientSequenceNumber?: number;
+}
+
 /**
  * Estimated size of the stringification overhead for an op accumulated
  * from runtime to loader to the service.
@@ -32,15 +37,24 @@ export class BatchManager {
 		return this.batchContentSize;
 	}
 
-	public get referenceSequenceNumber(): number | undefined {
+	public get sequenceNumbers(): BatchSequenceNumbers {
+		return {
+			referenceSequenceNumber: this.referenceSequenceNumber,
+			clientSequenceNumber: this.clientSequenceNumber,
+		};
+	}
+
+	private get referenceSequenceNumber(): number | undefined {
 		return this.pendingBatch.length === 0
 			? undefined
 			: this.pendingBatch[this.pendingBatch.length - 1].referenceSequenceNumber;
 	}
 
+	private clientSequenceNumber: number | undefined;
+
 	constructor(public readonly options: IBatchManagerOptions) {}
 
-	public push(message: BatchMessage): boolean {
+	public push(message: BatchMessage, currentClientSequenceNumber?: number): boolean {
 		const contentSize = this.batchContentSize + (message.contents?.length ?? 0);
 		const opCount = this.pendingBatch.length;
 
@@ -68,6 +82,10 @@ export class BatchManager {
 			return false;
 		}
 
+		if (this.pendingBatch.length === 0) {
+			this.clientSequenceNumber = currentClientSequenceNumber;
+		}
+
 		this.batchContentSize = contentSize;
 		this.pendingBatch.push(message);
 		return true;
@@ -86,6 +104,7 @@ export class BatchManager {
 
 		this.pendingBatch = [];
 		this.batchContentSize = 0;
+		this.clientSequenceNumber = undefined;
 
 		return addBatchMetadata(batch);
 	}
@@ -136,3 +155,17 @@ const addBatchMetadata = (batch: IBatch): IBatch => {
 export const estimateSocketSize = (batch: IBatch): number => {
 	return batch.contentSizeInBytes + opOverhead * batch.content.length;
 };
+
+export const sequenceNumbersMatch = (
+	seqNums: BatchSequenceNumbers,
+	otherSeqNums: BatchSequenceNumbers,
+): boolean => {
+	return (
+		(seqNums.referenceSequenceNumber === undefined ||
+			otherSeqNums.referenceSequenceNumber === undefined ||
+			seqNums.referenceSequenceNumber === otherSeqNums.referenceSequenceNumber) &&
+		(seqNums.clientSequenceNumber === undefined ||
+			otherSeqNums.clientSequenceNumber === undefined ||
+			seqNums.clientSequenceNumber === otherSeqNums.clientSequenceNumber)
+	);
+};

package/src/opLifecycle/index.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-export { BatchManager, estimateSocketSize } from "./batchManager";
+export { BatchManager, estimateSocketSize, BatchSequenceNumbers } 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/opDecompressor.ts

@@ -133,6 +133,7 @@ export class OpDecompressor {
 		 */
 		try {
 			if (
+				message.contents !== null &&
 				typeof message.contents === "object" &&
 				Object.keys(message.contents).length === 1 &&
 				message.contents?.packedContents !== undefined &&

package/src/opLifecycle/opGroupingManager.ts

@@ -0,0 +1,82 @@
+/*!
+ * 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 { ContainerMessageType, 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) {
+			// Blob attaches cannot be grouped (grouped batching would hide metadata)
+			if (message.deserializedContent.type === ContainerMessageType.BlobAttach) {
+				return batch;
+			}
+			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,
+		}));
+	}
+}

package/src/opLifecycle/opSplitter.ts

@@ -135,7 +135,7 @@ export class OpSplitter {
 	 * @param batch - the compressed batch which needs to be processed
 	 * @returns A new adjusted batch which can be sent over the wire
 	 */
-	public splitCompressedBatch(batch: IBatch): IBatch {
+	public splitFirstBatchMessage(batch: IBatch): IBatch {
 		assert(this.isBatchChunkingEnabled, 0x513 /* Chunking needs to be enabled */);
 		assert(
 			batch.contentSizeInBytes > 0 && batch.content.length > 0,
@@ -152,10 +152,6 @@ export class OpSplitter {
 		);
 
 		const firstMessage = batch.content[0]; // we expect this to be the large compressed op, which needs to be split
-		assert(
-			firstMessage.metadata?.compressed === true || firstMessage.compression !== undefined,
-			0x517 /* Batch needs to be compressed */,
-		);
 		assert(
 			(firstMessage.contents?.length ?? 0) >= this.chunkSizeInBytes,
 			0x518 /* First message in the batch needs to be chunkable */,