@fluidframework/container-runtime 2.31.1 → 2.33.0-333010

package/src/dataStoreContext.ts

@@ -9,8 +9,6 @@ import { IDeltaManager } from "@fluidframework/container-definitions/internal";
 import {
 	FluidObject,
 	IDisposable,
-	IRequest,
-	IResponse,
 	ITelemetryBaseProperties,
 	type IEvent,
 } from "@fluidframework/core-interfaces";
@@ -796,15 +794,6 @@ export abstract class FluidDataStoreContext
 		this.parentContext.addedGCOutboundRoute(fromPath, toPath, messageTimestampMs);
 	}
 
-	// eslint-disable-next-line jsdoc/require-description
-	/**
-	 * @deprecated 0.18.Should call request on the runtime directly
-	 */
-	public async request(request: IRequest): Promise<IResponse> {
-		const runtime = await this.realize();
-		return runtime.request(request);
-	}
-
 	public submitMessage(type: string, content: unknown, localOpMetadata: unknown): void {
 		this.verifyNotClosed("submitMessage");
 		assert(!!this.channel, 0x146 /* "Channel must exist when submitting message" */);

package/src/index.ts

@@ -27,7 +27,6 @@ export { IBlobManagerLoadInfo } from "./blobManager/index.js";
 export { FluidDataStoreRegistry } from "./dataStoreRegistry.js";
 export {
 	detectOutboundReferences,
-	RuntimeHeaders,
 	ChannelCollectionFactory,
 	AllowTombstoneRequestHeaderKey,
 } from "./channelCollection.js";

package/src/messageTypes.ts

@@ -147,12 +147,12 @@ export type InboundContainerRuntimeMessage =
 	| ContainerRuntimeAliasMessage
 	| ContainerRuntimeIdAllocationMessage
 	| ContainerRuntimeGCMessage
+	| ContainerRuntimeDocumentSchemaMessage
 	// Inbound messages may include unknown types from other clients, so we include that as a special case here
-	| UnknownContainerRuntimeMessage
-	| ContainerRuntimeDocumentSchemaMessage;
+	| UnknownContainerRuntimeMessage;
 
 /**
- * A {@link TypedContainerRuntimeMessage} that has been generated by the container runtime but is not yet being sent to the server.
+ * A {@link TypedContainerRuntimeMessage} that has been generated by the container runtime, eventually to be sent to the ordering service.
  * These are messages generated by the local runtime, before the outbox's op virtualization step.
  */
 export type LocalContainerRuntimeMessage =
@@ -163,23 +163,9 @@ export type LocalContainerRuntimeMessage =
 	| ContainerRuntimeAliasMessage
 	| ContainerRuntimeIdAllocationMessage
 	| ContainerRuntimeGCMessage
+	| ContainerRuntimeDocumentSchemaMessage
 	// In rare cases (e.g. related to stashed ops) we could have a local message of an unknown type
-	| UnknownContainerRuntimeMessage
-	| ContainerRuntimeDocumentSchemaMessage;
-
-/**
- * A {@link TypedContainerRuntimeMessage} that is being sent to the server from the container runtime.
- */
-export type OutboundContainerRuntimeMessage =
-	| ContainerRuntimeDataStoreOpMessage
-	| OutboundContainerRuntimeAttachMessage
-	| ContainerRuntimeChunkedOpMessage
-	| ContainerRuntimeBlobAttachMessage
-	| ContainerRuntimeRejoinMessage
-	| ContainerRuntimeAliasMessage
-	| ContainerRuntimeIdAllocationMessage
-	| ContainerRuntimeGCMessage
-	| ContainerRuntimeDocumentSchemaMessage;
+	| UnknownContainerRuntimeMessage;
 
 /**
  * An unpacked ISequencedDocumentMessage with the inner TypedContainerRuntimeMessage type/contents/etc

package/src/opLifecycle/batchManager.ts

@@ -14,11 +14,10 @@ import { ICompressionRuntimeOptions } from "../containerRuntime.js";
 import { asBatchMetadata, type IBatchMetadata } from "../metadata.js";
 import type { IPendingMessage } from "../pendingStateManager.js";
 
-import { BatchMessage, IBatch, IBatchCheckpoint } from "./definitions.js";
+import { LocalBatchMessage, IBatchCheckpoint, type LocalBatch } from "./definitions.js";
 import type { BatchStartInfo } from "./remoteMessageProcessor.js";
 
 export interface IBatchManagerOptions {
-	readonly hardLimit: number;
 	readonly compressionOptions?: ICompressionRuntimeOptions;
 
 	/**
@@ -73,26 +72,16 @@ export function getEffectiveBatchId(
 	return batchStart.batchId ?? generateBatchId(batchStart.clientId, batchStart.batchStartCsn);
 }
 
-/**
- * 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 pendingBatch: BatchMessage[] = [];
-	private batchContentSize = 0;
+	private pendingBatch: LocalBatchMessage[] = [];
 	private hasReentrantOps = false;
 
 	public get length(): number {
 		return this.pendingBatch.length;
 	}
-	public get contentSizeInBytes(): number {
-		return this.batchContentSize;
-	}
 
 	public get sequenceNumbers(): BatchSequenceNumbers {
 		return {
@@ -117,32 +106,17 @@ export class BatchManager {
 	constructor(public readonly options: IBatchManagerOptions) {}
 
 	public push(
-		message: BatchMessage,
+		message: LocalBatchMessage,
 		reentrant: boolean,
 		currentClientSequenceNumber?: number,
-	): boolean {
-		const contentSize = this.batchContentSize + (message.contents?.length ?? 0);
-		const opCount = this.pendingBatch.length;
+	): void {
 		this.hasReentrantOps = this.hasReentrantOps || reentrant;
 
-		// Attempt to estimate batch size, aka socket message size.
-		// Each op has pretty large envelope, estimating to be 200 bytes.
-		// 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 + opOverhead * opCount;
-
-		if (socketMessageSize >= this.options.hardLimit) {
-			return false;
-		}
-
 		if (this.pendingBatch.length === 0) {
 			this.clientSequenceNumber = currentClientSequenceNumber;
 		}
 
-		this.batchContentSize = contentSize;
 		this.pendingBatch.push(message);
-		return true;
 	}
 
 	public get empty(): boolean {
@@ -152,16 +126,14 @@ export class BatchManager {
 	/**
 	 * Gets the pending batch and clears state for the next batch.
 	 */
-	public popBatch(batchId?: BatchId): IBatch {
-		const batch: IBatch = {
+	public popBatch(batchId?: BatchId): LocalBatch {
+		const batch: LocalBatch = {
 			messages: this.pendingBatch,
-			contentSizeInBytes: this.batchContentSize,
 			referenceSequenceNumber: this.referenceSequenceNumber,
 			hasReentrantOps: this.hasReentrantOps,
 		};
 
 		this.pendingBatch = [];
-		this.batchContentSize = 0;
 		this.clientSequenceNumber = undefined;
 		this.hasReentrantOps = false;
 
@@ -175,19 +147,20 @@ export class BatchManager {
 		const startSequenceNumber = this.clientSequenceNumber;
 		const startPoint = this.pendingBatch.length;
 		return {
-			rollback: (process: (message: BatchMessage) => void) => {
+			rollback: (process: (message: LocalBatchMessage) => void) => {
 				this.clientSequenceNumber = startSequenceNumber;
 				const rollbackOpsLifo = this.pendingBatch.splice(startPoint).reverse();
 				for (const message of rollbackOpsLifo) {
-					this.batchContentSize -= message.contents?.length ?? 0;
 					process(message);
 				}
 				const count = this.pendingBatch.length - startPoint;
 				if (count !== 0) {
-					throw new LoggingError("Ops generated durning rollback", {
+					throw new LoggingError("Ops generated during rollback", {
 						count,
 						...tagData(TelemetryDataTag.UserData, {
-							ops: JSON.stringify(this.pendingBatch.slice(startPoint).map((b) => b.contents)),
+							ops: JSON.stringify(
+								this.pendingBatch.slice(startPoint).map((b) => b.serializedOp),
+							),
 						}),
 					});
 				}
@@ -196,7 +169,7 @@ export class BatchManager {
 	}
 }
 
-const addBatchMetadata = (batch: IBatch, batchId?: BatchId): IBatch => {
+const addBatchMetadata = (batch: LocalBatch, batchId?: BatchId): LocalBatch => {
 	const batchEnd = batch.messages.length - 1;
 
 	const firstMsg = batch.messages[0];
@@ -226,18 +199,6 @@ const addBatchMetadata = (batch: IBatch, batchId?: BatchId): 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.messages.length;
-};
-
 export const sequenceNumbersMatch = (
 	seqNums: BatchSequenceNumbers,
 	otherSeqNums: BatchSequenceNumbers,

package/src/opLifecycle/definitions.ts

@@ -3,28 +3,71 @@
  * Licensed under the MIT License.
  */
 
-import { IBatchMessage } from "@fluidframework/container-definitions/internal";
+import type { IBatchMessage } from "@fluidframework/container-definitions/internal";
 
 import { CompressionAlgorithms } from "../containerRuntime.js";
 
 /**
- * Batch message type used internally by the runtime
+ * Local Batch message, before it is virtualized and sent to the ordering service
  */
-export type BatchMessage = IBatchMessage & {
+export interface LocalBatchMessage {
+	serializedOp: string;
+	metadata?: Record<string, unknown>;
 	localOpMetadata?: unknown;
 	referenceSequenceNumber: number;
 	compression?: CompressionAlgorithms;
+
+	/**
+	 * @deprecated Use serializedOp
+	 */
+	contents?: never; // To ensure we don't leave this one when converting from OutboundBatchMessage
+}
+
+/**
+ * Virtualized Batch message, on its way out the door to the ordering service
+ */
+export type OutboundBatchMessage = IBatchMessage & {
+	localOpMetadata?: unknown;
+	referenceSequenceNumber: number;
+	compression?: CompressionAlgorithms;
+
+	/**
+	 * @deprecated Use contents
+	 */
+	serializedOp?: never; // To ensure we don't leave this one when converting from LocalBatchMessage
 };
 
 /**
- * Batch interface used internally by the runtime.
+ * A batch of messages we have accumulated locally, but haven't sent to the ordering service yet.
+ */
+export type LocalBatch = IBatch<LocalBatchMessage[]>;
+
+/**
+ * A batch of messages that has been virtualized as needed (grouped, compressed, chunked)
+ * and is ready to be sent to the ordering service.
+ * At the very least, the op contents have been serialized to string.
  */
-export interface IBatch<TMessages extends BatchMessage[] = BatchMessage[]> {
+export interface OutboundBatch<
+	TMessages extends OutboundBatchMessage[] = OutboundBatchMessage[],
+> extends IBatch<TMessages> {
 	/**
 	 * Sum of the in-memory content sizes of all messages in the batch.
 	 * If the batch is compressed, this number reflects the post-compression size.
 	 */
 	readonly contentSizeInBytes: number;
+}
+
+/**
+ * An {@link OutboundBatch} with exactly one message
+ * This type is helpful as Grouping yields this kind of batch, and Compression only operates on this type of batch.
+ */
+export type OutboundSingletonBatch = OutboundBatch<[OutboundBatchMessage]>;
+
+/**
+ * Base batch interface used internally by the runtime.
+ * See {@link LocalBatch} and {@link OutboundBatch} for the concrete types.
+ */
+interface IBatch<TMessages extends LocalBatchMessage[] | OutboundBatchMessage[]> {
 	/**
 	 * All the messages in the batch
 	 */
@@ -47,7 +90,7 @@ export interface IBatch<TMessages extends BatchMessage[] = BatchMessage[]> {
 }
 
 export interface IBatchCheckpoint {
-	rollback: (action: (message: BatchMessage) => void) => void;
+	rollback: (action: (message: LocalBatchMessage) => void) => void;
 }
 
 /**

package/src/opLifecycle/index.ts

@@ -7,19 +7,34 @@ export {
 	BatchId,
 	BatchManager,
 	BatchSequenceNumbers,
-	estimateSocketSize,
 	getEffectiveBatchId,
 	generateBatchId,
 	IBatchManagerOptions,
 } from "./batchManager.js";
-export { BatchMessage, IBatch, IBatchCheckpoint, IChunkedOp } from "./definitions.js";
+export {
+	LocalBatch,
+	LocalBatchMessage,
+	OutboundBatch,
+	OutboundBatchMessage,
+	OutboundSingletonBatch,
+	IBatchCheckpoint,
+	IChunkedOp,
+} from "./definitions.js";
 export { DuplicateBatchDetector } from "./duplicateBatchDetector.js";
-export { Outbox, getLongStack, serializeOpContents } from "./outbox.js";
+export {
+	serializeOp,
+	ensureContentsDeserialized,
+} from "./opSerialization.js";
+export {
+	estimateSocketSize,
+	localBatchToOutboundBatch,
+	Outbox,
+	getLongStack,
+} from "./outbox.js";
 export { OpCompressor } from "./opCompressor.js";
 export { OpDecompressor } from "./opDecompressor.js";
 export { OpSplitter, splitOp, isChunkedMessage } from "./opSplitter.js";
 export {
-	ensureContentsDeserialized,
 	InboundMessageResult,
 	BatchStartInfo,
 	RemoteMessageProcessor,

package/src/opLifecycle/opCompressor.ts

@@ -7,7 +7,7 @@ import { IsoBuffer } from "@fluid-internal/client-utils";
 import { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import {
-	UsageError,
+	DataProcessingError,
 	createChildLogger,
 	type ITelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
@@ -15,13 +15,14 @@ import { compress } from "lz4js";
 
 import { CompressionAlgorithms } from "../containerRuntime.js";
 
-import { estimateSocketSize } from "./batchManager.js";
-import { BatchMessage, IBatch } from "./definitions.js";
+import { type OutboundBatchMessage, type OutboundSingletonBatch } from "./definitions.js";
+import { estimateSocketSize } from "./outbox.js";
 
 /**
- * Compresses batches of ops. It generates a single compressed op that contains
- * the contents of each op in the batch. It then submits empty ops for each original
- * op to reserve sequence numbers.
+ * Compresses batches of ops.
+ *
+ * @remarks Only single-message batches are supported
+ * Use opGroupingManager to group a batch into a singleton batch suitable for compression.
  */
 export class OpCompressor {
 	private readonly logger: ITelemetryLoggerExt;
@@ -31,14 +32,12 @@ export class OpCompressor {
 	}
 
 	/**
-	 * Combines the contents of the batch into a single JSON string and compresses it, putting
-	 * the resulting string as the first message of the batch. The rest of the messages are
-	 * empty placeholders to reserve sequence numbers.
-	 * This should only take a single message batch and compress it.
-	 * @param batch - The batch to compress
-	 * @returns A batch of the same length as the input batch, containing a single compressed message followed by empty placeholders
+	 * Combines the contents of the singleton batch into a single JSON string and compresses it, putting
+	 * the resulting string as the message contents in place of the original uncompressed payload.
+	 * @param batch - The batch to compress. Must have only 1 message
+	 * @returns A singleton batch containing a single compressed message
 	 */
-	public compressBatch(batch: IBatch): IBatch<[BatchMessage]> {
+	public compressBatch(batch: OutboundSingletonBatch): OutboundSingletonBatch {
 		assert(
 			batch.contentSizeInBytes > 0 && batch.messages.length === 1,
 			0x5a4 /* Batch should not be empty and should contain a single message */,
@@ -50,7 +49,7 @@ export class OpCompressor {
 		const compressedContent = IsoBuffer.from(compressedContents).toString("base64");
 		const duration = Date.now() - compressionStart;
 
-		const messages: [BatchMessage] = [
+		const messages: [OutboundBatchMessage] = [
 			{
 				...batch.messages[0],
 				contents: JSON.stringify({ packedContents: compressedContent }),
@@ -59,7 +58,7 @@ export class OpCompressor {
 			},
 		];
 
-		const compressedBatch = {
+		const compressedBatch: OutboundSingletonBatch = {
 			contentSizeInBytes: compressedContent.length,
 			messages,
 			referenceSequenceNumber: batch.referenceSequenceNumber,
@@ -82,27 +81,29 @@ export class OpCompressor {
 	/**
 	 * Combine the batch's content strings into a single JSON string (a serialized array)
 	 */
-	private serializeBatchContents(batch: IBatch): string {
+	private serializeBatchContents(batch: OutboundSingletonBatch): string {
+		const [message, ...none] = batch.messages;
+		assert(none.length === 0, 0xb78 /* Batch should only contain a single message */);
 		try {
-			// Yields a valid JSON array, since each message.contents is already serialized to JSON
-			return `[${batch.messages.map(({ contents }) => contents).join(",")}]`;
-		} catch (newError: unknown) {
-			if ((newError as Partial<Error>).message === "Invalid string length") {
-				// This is how JSON.stringify signals that
+			// This is expressed as a JSON array, for legacy reasons
+			return `[${message.contents}]`;
+		} catch (error: unknown) {
+			if ((error as Partial<Error>).message === "Invalid string length") {
+				// This is how string interpolation signals that
 				// the content size exceeds its capacity
-				const error = new UsageError("Payload too large");
+				const dpe = DataProcessingError.create("Payload too large", "OpCompressor");
 				this.logger.sendErrorEvent(
 					{
 						eventName: "BatchTooLarge",
 						size: batch.contentSizeInBytes,
 						length: batch.messages.length,
 					},
-					error,
+					dpe,
 				);
-				throw error;
+				throw dpe;
 			}
 
-			throw newError;
+			throw error;
 		}
 	}
 }

package/src/opLifecycle/opGroupingManager.ts

@@ -11,7 +11,11 @@ import {
 	type ITelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 
-import { IBatch, type BatchMessage } from "./definitions.js";
+import {
+	type OutboundBatch,
+	type OutboundBatchMessage,
+	type OutboundSingletonBatch,
+} from "./definitions.js";
 
 /**
  * Grouping makes assumptions about the shape of message contents. This interface codifies those assumptions, but does not validate them.
@@ -58,44 +62,51 @@ export class OpGroupingManager {
 	 * This is needed as a placeholder if a batch becomes empty on resubmit, but we are tracking batch IDs.
 	 * @param resubmittingBatchId - batch ID of the resubmitting batch
 	 * @param referenceSequenceNumber - reference sequence number
-	 * @returns - IBatch containing a single empty Grouped Batch op
+	 * @returns - The outbound batch as well as the interior placeholder message
 	 */
 	public createEmptyGroupedBatch(
 		resubmittingBatchId: string,
 		referenceSequenceNumber: number,
-	): IBatch<[BatchMessage]> {
+	): { outboundBatch: OutboundSingletonBatch; placeholderMessage: OutboundBatchMessage } {
 		assert(
 			this.config.groupedBatchingEnabled,
 			0xa00 /* cannot create empty grouped batch when grouped batching is disabled */,
 		);
-		const serializedContent = JSON.stringify({
+		const serializedOp = JSON.stringify({
 			type: OpGroupingManager.groupedBatchOp,
 			contents: [],
 		});
 
-		return {
+		const placeholderMessage: OutboundBatchMessage = {
+			metadata: { batchId: resubmittingBatchId },
+			localOpMetadata: { emptyBatch: true },
+			referenceSequenceNumber,
+			contents: serializedOp,
+		};
+		const outboundBatch: OutboundSingletonBatch = {
 			contentSizeInBytes: 0,
-			messages: [
-				{
-					metadata: { batchId: resubmittingBatchId },
-					localOpMetadata: { emptyBatch: true },
-					referenceSequenceNumber,
-					contents: serializedContent,
-				},
-			],
+			messages: [placeholderMessage],
 			referenceSequenceNumber,
 		};
+		return { outboundBatch, placeholderMessage };
 	}
 
 	/**
 	 * Converts the given batch into a "grouped batch" - a batch with a single message of type "groupedBatch",
 	 * with contents being an array of the original batch's messages.
 	 *
+	 * If the batch already has only 1 message, it is returned as-is.
+	 *
 	 * @remarks - Remember that a BatchMessage has its content JSON serialized, so the incoming batch message contents
 	 * must be parsed first, and then the type and contents mentioned above are hidden in that JSON serialization.
 	 */
-	public groupBatch(batch: IBatch): IBatch<[BatchMessage]> {
-		assert(this.shouldGroup(batch), 0x946 /* cannot group the provided batch */);
+	public groupBatch(batch: OutboundBatch): OutboundSingletonBatch {
+		assert(this.groupedBatchingEnabled(), 0xb79 /* grouping disabled! */);
+		assert(batch.messages.length > 0, 0xb7a /* Unexpected attempt to group an empty batch */);
+
+		if (batch.messages.length === 1) {
+			return batch as OutboundSingletonBatch;
+		}
 
 		if (batch.messages.length >= 1000) {
 			this.logger.sendTelemetryEvent({
@@ -126,7 +137,7 @@ export class OpGroupingManager {
 			})),
 		});
 
-		const groupedBatch: IBatch<[BatchMessage]> = {
+		const groupedBatch: OutboundSingletonBatch = {
 			...batch,
 			messages: [
 				{
@@ -153,16 +164,6 @@ export class OpGroupingManager {
 		}));
 	}
 
-	public shouldGroup(batch: IBatch): boolean {
-		return (
-			// Grouped batching must be enabled
-			this.config.groupedBatchingEnabled &&
-			// The number of ops in the batch must be 2 or more
-			// or be empty (to allow for empty batches to be grouped)
-			batch.messages.length !== 1
-			// Support for reentrant batches will be on by default
-		);
-	}
 	public groupedBatchingEnabled(): boolean {
 		return this.config.groupedBatchingEnabled;
 	}

package/src/opLifecycle/opSerialization.ts

@@ -0,0 +1,46 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
+import {
+	encodeHandleForSerialization,
+	isFluidHandle,
+	toFluidHandleInternal,
+} from "@fluidframework/runtime-utils/internal";
+
+import type { LocalContainerRuntimeMessage } from "../messageTypes.js";
+
+/**
+ * Takes an incoming runtime message (outer type "op"), JSON.parses the message's contents in place,
+ * if needed (old Loader does this for us).
+ * Only to be used for runtime messages. The contents here would be the virtualized payload for a batch of ops.
+ * @remarks - Serialization during submit happens via {@link serializeOp}
+ * @param mutableMessage - op message received
+ */
+export function ensureContentsDeserialized(mutableMessage: ISequencedDocumentMessage): void {
+	// This should become unconditional once Loader LTS reaches 2.4 or later.
+	// There will be a long time of needing both cases, until LTS advances to that point.
+	if (typeof mutableMessage.contents === "string" && mutableMessage.contents !== "") {
+		mutableMessage.contents = JSON.parse(mutableMessage.contents);
+	}
+}
+
+/**
+ * Before submitting an op to the Outbox, its contents must be serialized using this function.
+ * @remarks - The deserialization on process happens via the function {@link ensureContentsDeserialized}.
+ */
+export function serializeOp(op: LocalContainerRuntimeMessage): string {
+	return JSON.stringify(
+		op,
+		// replacer:
+		(key, value: unknown) => {
+			// If 'value' is an IFluidHandle return its encoded form.
+			if (isFluidHandle(value)) {
+				return encodeHandleForSerialization(toFluidHandleInternal(value));
+			}
+			return value;
+		},
+	);
+}