@fluidframework/container-runtime 2.0.0-internal.6.4.0 → 2.0.0-internal.7.1.0

package/src/dataStoreContext.ts

@@ -740,11 +740,6 @@ export abstract class FluidDataStoreContext
 		this.makeLocallyVisibleFn();
 	}
 
-	/** @deprecated - To be replaced by calling makeLocallyVisible directly  */
-	public bindToContext() {
-		this.makeLocallyVisibleFn();
-	}
-
 	protected bindRuntime(channel: IFluidDataStoreChannel) {
 		if (this.channel) {
 			throw new Error("Runtime already bound");
@@ -1206,7 +1201,7 @@ export class LocalDetachedFluidDataStoreContext
 		// of data store factories tends to construct the data object (at least kick off an async method that returns
 		// it); that code moved to the entryPoint initialization function, so we want to ensure it still executes
 		// before the data store is attached.
-		await dataStoreChannel.entryPoint?.get();
+		await dataStoreChannel.entryPoint.get();
 
 		if (await this.isRoot()) {
 			dataStoreChannel.makeVisibleAndAttachGraph();

package/src/error.ts

@@ -12,7 +12,10 @@ import { IFluidErrorBase, LoggingError } from "@fluidframework/telemetry-utils";
 export class ClientSessionExpiredError extends LoggingError implements IFluidErrorBase {
 	readonly errorType = ContainerErrorTypes.clientSessionExpiredError;
 
-	constructor(message: string, readonly expiryMs: number) {
+	constructor(
+		message: string,
+		readonly expiryMs: number,
+	) {
 		super(message, { timeoutMs: expiryMs });
 	}
 }

package/src/gc/gcDefinitions.ts

@@ -165,7 +165,7 @@ export const GCNodeType = {
 	// Nodes that are neither of the above. For example, root node.
 	Other: "Other",
 };
-export type GCNodeType = typeof GCNodeType[keyof typeof GCNodeType];
+export type GCNodeType = (typeof GCNodeType)[keyof typeof GCNodeType];
 
 /**
  * Defines the APIs for the runtime object to be passed to the garbage collector.
@@ -267,24 +267,12 @@ export interface IGCRuntimeOptions {
 	 * GC has mark phase and sweep phase. In mark phase, unreferenced objects are identified
 	 * and marked as such in the summary. This option enables the mark phase.
 	 * In sweep phase, unreferenced objects are eventually deleted from the container if they meet certain conditions.
-	 * Sweep phase can be enabled via the "sweepAllowed" option.
+	 * Sweep phase can be enabled using the "gcSweepGeneration" option.
 	 *
 	 * Note: This setting is persisted in the container's summary and cannot be changed.
 	 */
 	gcAllowed?: boolean;
 
-	/**
-	 * @deprecated -  @see gcSweepGenerationOptionName and @see GCFeatureMatrix.sweepGeneration
-	 *
-	 * Flag that if true, enables GC's sweep phase for a new container.
-	 *
-	 * This will allow GC to eventually delete unreferenced objects from the container.
-	 * This flag should only be set to true if "gcAllowed" is true.
-	 *
-	 * Note: This setting is persisted in the container's summary and cannot be changed.
-	 */
-	sweepAllowed?: boolean;
-
 	/**
 	 * Flag that if true, will disable garbage collection for the session.
 	 * Can be used to disable running GC on containers where it is allowed via the gcAllowed option.
@@ -372,7 +360,7 @@ export const UnreferencedState = {
 	/** The node is ready to be deleted by the sweep phase. */
 	SweepReady: "SweepReady",
 } as const;
-export type UnreferencedState = typeof UnreferencedState[keyof typeof UnreferencedState];
+export type UnreferencedState = (typeof UnreferencedState)[keyof typeof UnreferencedState];
 
 /**
  * Represents the result of a GC run.

package/src/gc/gcEarlyAdoption.md

@@ -78,7 +78,7 @@ For this to work, you must disable the `Fluid.GarbageCollection.ThrowOnTombstone
 
 When a Tombstoned object (via `handle.get()`) fails to load, the 404 response error object has an `underlyingResponseHeaders` with the
 `isTombstoned` flag set to true: i.e. `error.underlyingResponseHeaders?.isTombstoned === true`. In this case,
-you may turn around and use `IContainerRuntime.resolveHandle` with `allowTombstone: true` in `IRequest.headers` to request
+you may turn around and use `IContainerRuntimeWithResolveHandle_Deprecated.resolveHandle` with `allowTombstone: true` in `IRequest.headers` to request
 the object again - this time it will succeed.
 
 To be very clear once again - This path uses deprecated APIs (`resolveHandle`) and comes with no guarantees of support.

package/src/index.ts

@@ -23,6 +23,7 @@ export {
 	DefaultSummaryConfiguration,
 	ICompressionRuntimeOptions,
 	CompressionAlgorithms,
+	TEST_requestSummarizer,
 } from "./containerRuntime";
 export {
 	ContainerMessageType,

package/src/opLifecycle/README.md

@@ -1,5 +1,19 @@
 # Configs and feature gates for solving the 1MB limit.
 
+## Table of contents
+
+-   [Introduction](#introduction)
+    -   [How batching works](#how-batching-works)
+-   [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)
+-   [Note about performance and latency](#note-about-performance-and-latency)
+-   [How it works](#how-it-works)
+-   [How grouped batching works](#how-grouped-batching-works)
+
 ## 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.
@@ -8,17 +22,35 @@ There are two features which can be used to work around this size limit, batch c
 
 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
+### How batching works
 
--   [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)
+Batching in the context of Fluid ops is a way in which the framework accumulates and applies ops. A batch is a group of ops accumulated within a single JS turn, which will be broadcasted in the same order to all the other connected clients and applied synchronously. Additional logic and validation ensure that batches are never interleaved, nested or interrupted and they are processed in isolation without interleaving of ops from other clients.
+
+The way batches are formed is governed by the `FlushMode` setting of the `ContainerRuntimeOptions` and it is immutable for the entire lifetime of the runtime and subsequently the container.
+
+```
+export enum FlushMode {
+    /**
+     * In Immediate flush mode the runtime will immediately send all operations to the driver layer.
+     */
+    Immediate,
+
+    /**
+     * When in TurnBased flush mode the runtime will buffer operations in the current turn and send them as a single
+     * batch at the end of the turn. The flush call on the runtime can be used to force send the current batch.
+     */
+    TurnBased,
+}
+```
+
+What this means is that `FlushMode.Immediate` will send each op in its own payload to the server, while `FlushMode.TurnBased` will accumulate all ops in a single JS turn and send them together in the same payload. Technically, `FlushMode.Immediate` can be simulated with `FlushMode.TurnBased` by interrupting the JS turn after producing only one op (for example by pausing the execution to wait on a promise). Therefore, for all intents and purposes, `FlushMode.Immediate` enables all batches to have only one op.
+
+**By default, Fluid uses `FlushMode.TurnBased`** as:
+
+-   it is more efficient from an I/O perspective (batching ops overall decrease the number of payloads sent to the server)
+-   reduces concurrency related bugs, as it ensures that all ops generated within the same JS turn are also applied by all other clients within a single JS turn. Clients using the same pattern can safely assume ops will be applied exactly as they are observed locally. The alternative would be for ops to be both produced and applied with interruptions (which may involve processing input or rendering), invalidating the state based off which the changes were produced.
+
+As `FlushMode.TurnBased` accumulates ops, it is the most vulnerable to run into the 1MB socket limit.
 
 ## Compression
 
@@ -29,6 +61,8 @@ 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.
 
+Compression is relevant for both `FlushMode.TurnBased` and `FlushMode.Immediate` as it only targets the contents of the ops and not the number of ops in a batch. Compression is opaque to the server and implementations of the Fluid protocol do not need to alter their behavior to support this client feature.
+
 ## Grouped batching
 
 **Note: This feature is currently considered experimental and is not ready for production usage.**
@@ -71,6 +105,8 @@ If all prerequisites in the previous section are met, enabling the feature can b
 
 In case of emergency grouped batching can be disabled at runtime, using feature gates. If `"Fluid.ContainerRuntime.DisableGroupedBatching"` is set to `true`, it will disable grouped batching if enabled from `IContainerRuntimeOptions` in the code.
 
+Grouped batching is only relevant for `FlushMode.TurnBased` as it only targets the number of ops in a batch. Grouped batching is opaque to the server and implementations of the Fluid protocol do not need to alter their behavior to support this client feature.
+
 ## 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.
@@ -79,6 +115,8 @@ The `IContainerRuntimeOptions.chunkSizeInBytes` property is the only configurati
 
 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`.
 
+Chunking is relevant for both `FlushMode.TurnBased` and `FlushMode.Immediate` as it only targets the contents of the ops and not the number of ops in a batch. Chunking is opaque to the server and implementations of the Fluid protocol do not need to alter their behavior to support this client feature.
+
 ## Disabling in case of emergency
 
 If the features are enabled using the configs, they can be disabled at runtime via feature gates as following:
@@ -102,32 +140,19 @@ By default, the runtime is configured with the following values related to compr
     }
 ```
 
-To use compression but disable chunking:
+To enable grouped batching, use the following property:
 
 ```
     const runtimeOptions: IContainerRuntimeOptions = {
-        chunkSizeInBytes: Number.POSITIVE_INFINITY,
+        enableGroupedBatching: true,
     }
 ```
 
-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,
-        },
-    }
-```
+## Note about performance and latency
 
-To enable grouped batching:
+In terms of performance and impact on latency, the results greatly depend on payload size, payload structure, network speed and CPU speed. Therefore, customers must perform the required measurements and adjust the settings according to their scenarios.
 
-```
-    const runtimeOptions: IContainerRuntimeOptions = {
-        enableGroupedBatching: true,
-    }
-```
+In general, compression offers a trade-off between higher compute costs, lower bandwidth consumption and lower storage requirements, while chunking slightly increases latency due to the overhead of splitting an op, sending the chunks and reconstructing them on each client. Grouped batching heavily decreases the number of ops observed by the server and slightly decreases the bandwidth requirements as it merges all the ops in a batch into a single op and also eliminates the op envelope overhead.
 
 ## How it works
 

package/src/opLifecycle/outbox.ts

@@ -65,10 +65,13 @@ export interface IOutboxParameters {
 export function getLongStack<T>(action: () => T, length: number = 50): T {
 	const errorObj = Error as any;
 	if (
+		/* eslint-disable @typescript-eslint/prefer-nullish-coalescing */
+		// ?? is not logically equivalent when the first clause returns false.
 		(
 			Object.getOwnPropertyDescriptor(errorObj, "stackTraceLimit") ||
 			Object.getOwnPropertyDescriptor(Object.getPrototypeOf(errorObj), "stackTraceLimit")
 		)?.writable !== true
+		/* eslint-enable @typescript-eslint/prefer-nullish-coalescing */
 	) {
 		return action();
 	}

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-runtime";
-export const pkgVersion = "2.0.0-internal.6.4.0";
+export const pkgVersion = "2.0.0-internal.7.1.0";

package/src/pendingStateManager.ts

@@ -15,24 +15,11 @@ import { ContainerMessageType, InboundSequencedContainerRuntimeMessage } from ".
 import { pkgVersion } from "./packageVersion";
 import { IBatchMetadata } from "./metadata";
 
-/**
- * ! TODO: Remove this interface in "2.0.0-internal.7.0.0" once we only read IPendingMessageNew (AB#4763)
- */
-export interface IPendingMessageOld {
-	type: "message";
-	messageType: ContainerMessageType;
-	clientSequenceNumber: number;
-	referenceSequenceNumber: number;
-	content: any;
-	localOpMetadata: unknown;
-	opMetadata: Record<string, unknown> | undefined;
-}
-
 /**
  * This represents a message that has been submitted and is added to the pending queue when `submit` is called on the
  * ContainerRuntime. This message has either not been ack'd by the server or has not been submitted to the server yet.
  */
-export interface IPendingMessageNew {
+export interface IPendingMessage {
 	type: "message";
 	clientSequenceNumber: number;
 	referenceSequenceNumber: number;
@@ -41,16 +28,11 @@ export interface IPendingMessageNew {
 	opMetadata: Record<string, unknown> | undefined;
 }
 
-/**
- * ! TODO: Remove this type in "2.0.0-internal.7.0.0" (AB#4763)
- */
-export type IPendingState = IPendingMessageOld | IPendingMessageNew;
-
 export interface IPendingLocalState {
 	/**
 	 * list of pending states, including ops and batch information
 	 */
-	pendingStates: IPendingState[];
+	pendingStates: IPendingMessage[];
 }
 
 export interface IPendingBatchMessage {
@@ -99,13 +81,13 @@ function buildPendingMessageContent(
  * It verifies that all the ops are acked, are received in the right order and batch information is correct.
  */
 export class PendingStateManager implements IDisposable {
-	private readonly pendingMessages = new Deque<IPendingMessageNew>();
-	private readonly initialMessages = new Deque<IPendingMessageNew>();
+	private readonly pendingMessages = new Deque<IPendingMessage>();
+	private readonly initialMessages = new Deque<IPendingMessage>();
 
 	/**
 	 * Sequenced local ops that are saved when stashing since pending ops may depend on them
 	 */
-	private savedOps: IPendingMessageNew[] = [];
+	private savedOps: IPendingMessage[] = [];
 
 	private readonly disposeOnce = new Lazy<void>(() => {
 		this.initialMessages.clear();
@@ -169,29 +151,8 @@ export class PendingStateManager implements IDisposable {
 		initialLocalState: IPendingLocalState | undefined,
 		private readonly logger: ITelemetryLoggerExt | undefined,
 	) {
-		/**
-		 * Convert old local state format to the new format (IPendingMessageOld to IPendingMessageNew)
-		 * ! TODO: Remove this conversion in "2.0.0-internal.7.0.0" (AB#4763)
-		 */
 		if (initialLocalState?.pendingStates) {
-			for (const initialState of initialLocalState.pendingStates) {
-				let messageContent = initialState.content;
-				if (
-					(initialState as IPendingMessageOld).messageType !== undefined &&
-					typeof initialState.content !== "string"
-				) {
-					// Convert IPendingMessageOld to IPendingMessageNew
-					messageContent = JSON.stringify({
-						type: (initialState as IPendingMessageOld).messageType,
-						contents: initialState.content,
-					});
-				}
-				// Note: this object may contain "messageType" prop, but it should not be easily accesible due to interface being used
-				this.initialMessages.push({
-					...initialState,
-					content: messageContent,
-				});
-			}
+			this.initialMessages.push(...initialLocalState.pendingStates);
 		}
 	}
 
@@ -213,7 +174,7 @@ export class PendingStateManager implements IDisposable {
 		localOpMetadata: unknown,
 		opMetadata: Record<string, unknown> | undefined,
 	) {
-		const pendingMessage: IPendingMessageNew = {
+		const pendingMessage: IPendingMessage = {
 			type: "message",
 			clientSequenceNumber: -1, // dummy value (not to be used anywhere)
 			referenceSequenceNumber,
@@ -357,6 +318,7 @@ export class PendingStateManager implements IDisposable {
 							{
 								runtimeVersion: pkgVersion,
 								batchClientId:
+									// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
 									this.pendingBatchBeginMessage.clientId === null
 										? "null"
 										: this.pendingBatchBeginMessage.clientId,

package/src/scheduleManager.ts

@@ -271,6 +271,7 @@ class ScheduleManagerCore {
 					{
 						runtimeVersion: pkgVersion,
 						batchClientId:
+							// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
 							this.currentBatchClientId === null ? "null" : this.currentBatchClientId,
 						pauseSequenceNumber: this.pauseSequenceNumber,
 						localBatch: this.currentBatchClientId === this.getClientId(),
@@ -306,6 +307,7 @@ class ScheduleManagerCore {
 			throw new DataCorruptionError("OpBatchIncomplete", {
 				runtimeVersion: pkgVersion,
 				batchClientId:
+					// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
 					this.currentBatchClientId === null ? "null" : this.currentBatchClientId,
 				pauseSequenceNumber: this.pauseSequenceNumber,
 				localBatch: this.currentBatchClientId === this.getClientId(),

package/src/summary/summarizer.ts

@@ -15,8 +15,8 @@ import {
 } from "@fluidframework/telemetry-utils";
 import { ILoader, LoaderHeader } from "@fluidframework/container-definitions";
 import { DriverHeader } from "@fluidframework/driver-definitions";
-import { requestFluidObject } from "@fluidframework/runtime-utils";
 import { FluidObject, IFluidHandleContext, IRequest } from "@fluidframework/core-interfaces";
+import { responseToException } from "@fluidframework/runtime-utils";
 import { ISummaryConfiguration } from "../containerRuntime";
 import { ICancellableSummarizerController } from "./runWhileConnectedCoordinator";
 import { summarizerClientType } from "./summarizerClientElection";
@@ -49,7 +49,10 @@ export class SummarizingWarning
 	readonly errorType = summarizingError;
 	readonly canRetry = true;
 
-	constructor(errorMessage: string, readonly logged: boolean = false) {
+	constructor(
+		errorMessage: string,
+		readonly logged: boolean = false,
+	) {
 		super(errorMessage);
 	}
 
@@ -107,6 +110,7 @@ export class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements
 	 * interface will expect an absolute URL and will not handle "/".
 	 * @param loader - the loader that resolves the request
 	 * @param url - the URL used to resolve the container
+	 * @deprecated Creating a summarizer is not a publicly supported API. Please remove all usage of this static method.
 	 */
 	public static async create(loader: ILoader, url: string): Promise<ISummarizer> {
 		const request: IRequest = {
@@ -123,11 +127,20 @@ export class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements
 		};
 
 		const resolvedContainer = await loader.resolve(request);
-		const fluidObject: FluidObject<ISummarizer> | undefined = resolvedContainer.getEntryPoint
-			? await resolvedContainer.getEntryPoint?.()
-			: await requestFluidObject<FluidObject<ISummarizer>>(resolvedContainer, {
-					url: "_summarizer",
-			  });
+		let fluidObject: FluidObject<ISummarizer> | undefined;
+
+		// Older containers may not have the "getEntryPoint" API
+		// ! This check will need to stay until LTS of loader moves past 2.0.0-internal.7.0.0
+		if (resolvedContainer.getEntryPoint !== undefined) {
+			fluidObject = await resolvedContainer.getEntryPoint();
+		} else {
+			const response = await resolvedContainer.request({ url: "_summarizer" });
+			if (response.status !== 200 || response.mimeType !== "fluid/object") {
+				throw responseToException(response, request);
+			}
+			fluidObject = response.value;
+		}
+
 		if (fluidObject?.ISummarizer === undefined) {
 			throw new UsageError("Fluid object does not implement ISummarizer");
 		}

package/src/summary/summaryCollection.ts

@@ -405,6 +405,7 @@ export class SummaryCollection extends TypedEventEmitter<ISummaryCollectionOpEve
 	private handleSummaryAck(op: ISummaryAckMessage) {
 		const seq = op.contents.summaryProposal.summarySequenceNumber;
 		const summary = this.pendingSummaries.get(seq);
+		// eslint-disable-next-line @typescript-eslint/prefer-optional-chain -- optional chain is not logically equivalent
 		if (!summary || summary.summaryOp === undefined) {
 			// Summary ack without an op should be rare. We could fetch the
 			// reference sequence number from the snapshot, but instead we

package/src/summary/summaryGenerator.ts

@@ -47,12 +47,12 @@ export async function raceTimer<T>(
 	cancellationToken?: ISummaryCancellationToken,
 ): Promise<raceTimerResult<T>> {
 	const promises: Promise<raceTimerResult<T>>[] = [
-		promise.then((value) => ({ result: "done", value } as const)),
-		timer.then(({ timerResult: result }) => ({ result } as const)),
+		promise.then((value) => ({ result: "done", value }) as const),
+		timer.then(({ timerResult: result }) => ({ result }) as const),
 	];
 	if (cancellationToken !== undefined) {
 		promises.push(
-			cancellationToken.waitCancelled.then(() => ({ result: "cancelled" } as const)),
+			cancellationToken.waitCancelled.then(() => ({ result: "cancelled" }) as const),
 		);
 	}
 	return Promise.race(promises);

package/src/summary/summaryManager.ts

@@ -114,7 +114,7 @@ export class SummaryManager extends TypedEventEmitter<ISummarizerEvents> impleme
 		parentLogger: ITelemetryBaseLogger,
 		/** Creates summarizer by asking interactive container to spawn summarizing container and
 		 * get back its Summarizer instance. */
-		private readonly requestSummarizerFn: () => Promise<ISummarizer>,
+		private readonly createSummarizerFn: () => Promise<ISummarizer>,
 		private readonly startThrottler: IThrottler,
 		{
 			initialDelayMs = defaultInitialDelayMs,
@@ -264,7 +264,7 @@ export class SummaryManager extends TypedEventEmitter<ISummarizerEvents> impleme
 				);
 				this.state = SummaryManagerState.Running;
 
-				const summarizer = await this.requestSummarizerFn();
+				const summarizer = await this.createSummarizerFn();
 				this.summarizer = summarizer;
 				this.summarizer.on("summarize", this.handleSummarizeEvent);