@fluidframework/container-runtime 2.0.0-internal.7.0.0 → 2.0.0-internal.7.2.0

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/definitions.ts

@@ -52,6 +52,9 @@ export interface IBatchCheckpoint {
 	rollback: (action: (message: BatchMessage) => void) => void;
 }
 
+/**
+ * @public
+ */
 export interface IChunkedOp {
 	chunkId: number;
 	totalChunks: number;

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.7.0.0";
+export const pkgVersion = "2.0.0-internal.7.2.0";

package/src/pendingStateManager.ts

@@ -318,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/orderedClientElection.ts

@@ -225,7 +225,10 @@ export interface IOrderedClientElectionEvents extends IEvent {
 	);
 }
 
-/** Serialized state of IOrderedClientElection. */
+/**
+ * Serialized state of IOrderedClientElection.
+ * @public
+ */
 export interface ISerializedElection {
 	/** Sequence number at the time of the latest election. */
 	readonly electionSequenceNumber: number;

package/src/summary/runWhileConnectedCoordinator.ts

@@ -10,7 +10,10 @@ import {
 	ISummaryCancellationToken,
 } from "./summarizerTypes";
 
-/* Similar to AbortController, but using promise instead of events */
+/**
+ * Similar to AbortController, but using promise instead of events
+ * @public
+ */
 export interface ICancellableSummarizerController extends ISummaryCancellationToken {
 	stop(reason: SummarizerStopReason): void;
 }
@@ -18,6 +21,7 @@ export interface ICancellableSummarizerController extends ISummaryCancellationTo
 /**
  * Can be useful in testing as well as in places where caller does not use cancellation.
  * This object implements ISummaryCancellationToken interface but cancellation is never leveraged.
+ * @public
  */
 export const neverCancelledSummaryToken: ISummaryCancellationToken = {
 	cancelled: false,

package/src/summary/summarizer.ts

@@ -15,9 +15,8 @@ import {
 } from "@fluidframework/telemetry-utils";
 import { ILoader, LoaderHeader } from "@fluidframework/container-definitions";
 import { DriverHeader } from "@fluidframework/driver-definitions";
-// eslint-disable-next-line import/no-deprecated
-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";
@@ -50,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);
 	}
 
@@ -67,6 +69,7 @@ export const createSummarizingWarning = (errorMessage: string, logged: boolean)
  * Summarizer is responsible for coordinating when to generate and send summaries.
  * It is the main entry point for summary work.
  * It is created only by summarizing container (i.e. one with clientType === "summarizer")
+ * @public
  */
 export class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements ISummarizer {
 	public get ISummarizer() {
@@ -108,6 +111,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 = {
@@ -124,12 +128,20 @@ export class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements
 		};
 
 		const resolvedContainer = await loader.resolve(request);
-		const fluidObject: FluidObject<ISummarizer> | undefined = resolvedContainer.getEntryPoint
-			? await resolvedContainer.getEntryPoint?.()
-			: // eslint-disable-next-line import/no-deprecated
-			  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/summarizerTypes.ts

@@ -19,6 +19,7 @@ import { SummarizeReason } from "./summaryGenerator";
 /**
  * Similar to AbortSignal, but using promise instead of events
  * @param T - cancellation reason type
+ * @public
  */
 export interface ICancellationToken<T> {
 	/** Tells if this cancellable token is cancelled */
@@ -30,11 +31,15 @@ export interface ICancellationToken<T> {
 	readonly waitCancelled: Promise<T>;
 }
 
-/* Similar to AbortSignal, but using promise instead of events */
+/**
+ * Similar to AbortSignal, but using promise instead of events
+ * @public
+ */
 export type ISummaryCancellationToken = ICancellationToken<SummarizerStopReason>;
 
 /**
  * Data required to update internal tracking state after receiving a Summary Ack.
+ * @public
  */
 export interface IRefreshSummaryAckOptions {
 	/** Handle from the ack's summary op. */
@@ -47,6 +52,9 @@ export interface IRefreshSummaryAckOptions {
 	readonly summaryLogger: ITelemetryLoggerExt;
 }
 
+/**
+ * @public
+ */
 export interface ISummarizerInternalsProvider {
 	/** Encapsulates the work to walk the internals of the running container to generate a summary */
 	submitSummary(options: ISubmitSummaryOptions): Promise<SubmitSummaryResult>;
@@ -57,6 +65,7 @@ export interface ISummarizerInternalsProvider {
 
 /**
  * @deprecated Options that control the behavior of a running summarizer.
+ * @public
  * */
 export interface ISummarizerOptions {
 	/**
@@ -68,11 +77,17 @@ export interface ISummarizerOptions {
 	disableHeuristics: boolean;
 }
 
+/**
+ * @public
+ */
 export interface ISummarizingWarning extends ContainerWarning {
 	readonly errorType: "summarizingError";
 	readonly logged: boolean;
 }
 
+/**
+ * @public
+ */
 export interface IConnectableRuntime {
 	readonly disposed: boolean;
 	readonly connected: boolean;
@@ -80,6 +95,9 @@ export interface IConnectableRuntime {
 	once(event: "connected" | "disconnected" | "dispose", listener: () => void): this;
 }
 
+/**
+ * @public
+ */
 export interface ISummarizerRuntime extends IConnectableRuntime {
 	readonly logger: ITelemetryLoggerExt;
 	/** clientId of parent (non-summarizing) container that owns summarizer container */
@@ -97,19 +115,25 @@ export interface ISummarizerRuntime extends IConnectableRuntime {
 	): this;
 }
 
-/** Options affecting summarize behavior. */
+/**
+ * Options affecting summarize behavior.
+ * @public
+ */
 export interface ISummarizeOptions {
 	/** True to generate the full tree with no handle reuse optimizations; defaults to false */
 	readonly fullTree?: boolean;
 	/**
 	 * True to ask the server what the latest summary is first; defaults to false
 	 *
-	 * @deprecated - Summarize will not refresh latest snapshot state anymore. Instead it updates the cache and closes
+	 * @deprecated Summarize will not refresh latest snapshot state anymore. Instead it updates the cache and closes.
 	 * It's expected a new summarizer client will be created, likely by the same parent.
 	 */
 	readonly refreshLatestAck?: boolean;
 }
 
+/**
+ * @public
+ */
 export interface ISubmitSummaryOptions extends ISummarizeOptions {
 	/** Logger to use for correlated summary events */
 	readonly summaryLogger: ITelemetryLoggerExt;
@@ -119,12 +143,18 @@ export interface ISubmitSummaryOptions extends ISummarizeOptions {
 	readonly finalAttempt?: boolean;
 }
 
+/**
+ * @public
+ */
 export interface IOnDemandSummarizeOptions extends ISummarizeOptions {
 	/** Reason for generating summary. */
 	readonly reason: string;
 }
 
-/** Options to use when enqueueing a summarize attempt. */
+/**
+ * Options to use when enqueueing a summarize attempt.
+ * @public
+ */
 export interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions {
 	/** If specified, The summarize attempt will not occur until after this sequence number. */
 	readonly afterSequenceNumber?: number;
@@ -141,6 +171,7 @@ export interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions {
 /**
  * In addition to the normal summary tree + stats, this contains additional stats
  * only relevant at the root of the tree.
+ * @public
  */
 export interface IGeneratedSummaryStats extends ISummaryStats {
 	/** The total number of data stores in the container. */
@@ -157,7 +188,10 @@ export interface IGeneratedSummaryStats extends ISummaryStats {
 	readonly summaryNumber: number;
 }
 
-/** Base results for all submitSummary attempts. */
+/**
+ * Base results for all submitSummary attempts.
+ * @public
+ */
 export interface IBaseSummarizeResult {
 	readonly stage: "base";
 	/** Error object related to failed summarize attempt. */
@@ -167,7 +201,10 @@ export interface IBaseSummarizeResult {
 	readonly minimumSequenceNumber: number;
 }
 
-/** Results of submitSummary after generating the summary tree. */
+/**
+ * Results of submitSummary after generating the summary tree.
+ * @public
+ */
 export interface IGenerateSummaryTreeResult extends Omit<IBaseSummarizeResult, "stage"> {
 	readonly stage: "generate";
 	/** Generated summary tree. */
@@ -180,7 +217,10 @@ export interface IGenerateSummaryTreeResult extends Omit<IBaseSummarizeResult, "
 	readonly forcedFullTree: boolean;
 }
 
-/** Results of submitSummary after uploading the tree to storage. */
+/**
+ * Results of submitSummary after uploading the tree to storage.
+ * @public
+ */
 export interface IUploadSummaryResult extends Omit<IGenerateSummaryTreeResult, "stage"> {
 	readonly stage: "upload";
 	/** The handle returned by storage pointing to the uploaded summary tree. */
@@ -189,7 +229,10 @@ export interface IUploadSummaryResult extends Omit<IGenerateSummaryTreeResult, "
 	readonly uploadDuration: number;
 }
 
-/** Results of submitSummary after submitting the summarize op. */
+/**
+ * Results of submitSummary after submitting the summarize op.
+ * @public
+ */
 export interface ISubmitSummaryOpResult extends Omit<IUploadSummaryResult, "stage" | "error"> {
 	readonly stage: "submit";
 	/** The client sequence number of the summarize op submitted for the summary. */
@@ -213,6 +256,7 @@ export interface ISubmitSummaryOpResult extends Omit<IUploadSummaryResult, "stag
  * 3. "upload" - the summary was uploaded to storage, and the result contains the server-provided handle
  *
  * 4. "submit" - the summarize op was submitted, and the result contains the op client sequence number.
+ * @public
  */
 export type SubmitSummaryResult =
 	| IBaseSummarizeResult
@@ -220,34 +264,55 @@ export type SubmitSummaryResult =
 	| IUploadSummaryResult
 	| ISubmitSummaryOpResult;
 
-/** The stages of Summarize, used to describe how far progress succeeded in case of a failure at a later stage. */
+/**
+ * The stages of Summarize, used to describe how far progress succeeded in case of a failure at a later stage.
+ * @public
+ */
 export type SummaryStage = SubmitSummaryResult["stage"] | "unknown";
 
-/** Type for summarization failures that are retriable. */
+/**
+ * Type for summarization failures that are retriable.
+ * @public
+ */
 export interface IRetriableFailureResult {
 	readonly retryAfterSeconds?: number;
 }
 
-/** The data in summarizer result when submit summary stage fails. */
+/**
+ * The data in summarizer result when submit summary stage fails.
+ * @public
+ */
 export interface SubmitSummaryFailureData extends IRetriableFailureResult {
 	stage: SummaryStage;
 }
 
+/**
+ * @public
+ */
 export interface IBroadcastSummaryResult {
 	readonly summarizeOp: ISummaryOpMessage;
 	readonly broadcastDuration: number;
 }
 
+/**
+ * @public
+ */
 export interface IAckSummaryResult {
 	readonly summaryAckOp: ISummaryAckMessage;
 	readonly ackNackDuration: number;
 }
 
+/**
+ * @public
+ */
 export interface INackSummaryResult extends IRetriableFailureResult {
 	readonly summaryNackOp: ISummaryNackMessage;
 	readonly ackNackDuration: number;
 }
 
+/**
+ * @public
+ */
 export type SummarizeResultPart<TSuccess, TFailure = undefined> =
 	| {
 			success: true;
@@ -260,6 +325,9 @@ export type SummarizeResultPart<TSuccess, TFailure = undefined> =
 			error: any;
 	  };
 
+/**
+ * @public
+ */
 export interface ISummarizeResults {
 	/** Resolves when we generate, upload, and submit the summary. */
 	readonly summarySubmitted: Promise<
@@ -273,6 +341,9 @@ export interface ISummarizeResults {
 	>;
 }
 
+/**
+ * @public
+ */
 export type EnqueueSummarizeResult =
 	| (ISummarizeResults & {
 			/**
@@ -300,6 +371,9 @@ export type EnqueueSummarizeResult =
 			readonly overridden?: undefined;
 	  };
 
+/**
+ * @public
+ */
 export type SummarizerStopReason =
 	/** Summarizer client failed to summarize in all 3 consecutive attempts. */
 	| "failToSummarize"
@@ -326,16 +400,26 @@ export type SummarizerStopReason =
 	 */
 	| "latestSummaryStateStale";
 
+/**
+ * @public
+ */
 export interface ISummarizeEventProps {
 	result: "success" | "failure" | "canceled";
 	currentAttempt: number;
 	maxAttempts: number;
 	error?: any;
 }
+
+/**
+ * @public
+ */
 export interface ISummarizerEvents extends IEvent {
 	(event: "summarize", listener: (props: ISummarizeEventProps) => void);
 }
 
+/**
+ * @public
+ */
 export interface ISummarizer extends IEventProvider<ISummarizerEvents> {
 	/**
 	 * Allows {@link ISummarizer} to be used with our {@link @fluidframework/core-interfaces#FluidObject} pattern.

package/src/summary/summaryCollection.ts

@@ -19,6 +19,7 @@ import {
 
 /**
  * Interface for summary op messages with typed contents.
+ * @public
  */
 export interface ISummaryOpMessage extends ISequencedDocumentMessage {
 	type: MessageType.Summarize;
@@ -27,6 +28,7 @@ export interface ISummaryOpMessage extends ISequencedDocumentMessage {
 
 /**
  * Interface for summary ack messages with typed contents.
+ * @public
  */
 export interface ISummaryAckMessage extends ISequencedDocumentMessage {
 	type: MessageType.SummaryAck;
@@ -35,6 +37,7 @@ export interface ISummaryAckMessage extends ISequencedDocumentMessage {
 
 /**
  * Interface for summary nack messages with typed contents.
+ * @public
  */
 export interface ISummaryNackMessage extends ISequencedDocumentMessage {
 	type: MessageType.SummaryNack;
@@ -44,6 +47,7 @@ export interface ISummaryNackMessage extends ISequencedDocumentMessage {
 /**
  * A single summary which can be tracked as it goes through its life cycle.
  * The life cycle is: Local to Broadcast to Acked/Nacked.
+ * @public
  */
 export interface ISummary {
 	readonly clientId: string;
@@ -54,6 +58,7 @@ export interface ISummary {
 
 /**
  * A single summary which has already been acked by the server.
+ * @public
  */
 export interface IAckedSummary {
 	readonly summaryOp: ISummaryOpMessage;
@@ -140,6 +145,7 @@ class Summary implements ISummary {
 
 /**
  * Watches summaries created by a specific client.
+ * @public
  */
 export interface IClientSummaryWatcher extends IDisposable {
 	watchSummary(clientSequenceNumber: number): ISummary;
@@ -207,13 +213,23 @@ class ClientSummaryWatcher implements IClientSummaryWatcher {
 		this._disposed = true;
 	}
 }
-
+/**
+ * @public
+ */
 export type OpActionEventName =
 	| MessageType.Summarize
 	| MessageType.SummaryAck
 	| MessageType.SummaryNack
 	| "default";
+
+/**
+ * @public
+ */
 export type OpActionEventListener = (op: ISequencedDocumentMessage) => void;
+
+/**
+ * @public
+ */
 export interface ISummaryCollectionOpEvents extends IEvent {
 	(event: OpActionEventName, listener: OpActionEventListener);
 }
@@ -222,6 +238,7 @@ export interface ISummaryCollectionOpEvents extends IEvent {
  * Data structure that looks at the op stream to track summaries as they
  * are broadcast, acked and nacked.
  * It provides functionality for watching specific summaries.
+ * @public
  */
 export class SummaryCollection extends TypedEventEmitter<ISummaryCollectionOpEvents> {
 	// key: clientId
@@ -405,6 +422,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