@fluidframework/container-runtime 1.4.0-115997 → 2.0.0-dev-rc.1.0.0.224419

package/src/gc/gcHelpers.ts

@@ -0,0 +1,284 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils";
+import { ISnapshotTree } from "@fluidframework/protocol-definitions";
+import {
+	gcBlobPrefix,
+	gcDeletedBlobKey,
+	gcTombstoneBlobKey,
+	IGarbageCollectionData,
+	IGarbageCollectionDetailsBase,
+} from "@fluidframework/runtime-definitions";
+import { GCFeatureMatrix, GCVersion, IGCMetadata } from "./gcDefinitions";
+import {
+	IGarbageCollectionNodeData,
+	IGarbageCollectionSnapshotData,
+	IGarbageCollectionState,
+} from "./gcSummaryDefinitions";
+
+export function getGCVersion(metadata?: IGCMetadata): GCVersion {
+	if (!metadata) {
+		// Force to 0/disallowed in prior versions
+		return 0;
+	}
+	return metadata.gcFeature ?? 0;
+}
+
+/**
+ * Indicates whether Sweep is allowed for this document based on the persisted GC Feature Matrix and current gcGeneration.
+ * This applies to the entire Sweep Phase the same - both Tombstone Enforcement (i.e. should loading a Tombstone fail?) and Deletion.
+ *
+ * In order to protect old documents that were created at a time when known bugs exist that violate GC's invariants
+ * such that enforcing GC Sweep would cause legitimate data loss, the container author may increment the generation value for Sweep
+ * such that containers created with a different value will not be subjected to GC Sweep.
+ *
+ * If no generation is provided, Sweep will be enabled for all documents.
+ *
+ * For backwards compatibility, the current generation value is also compared against the persisted gcTombstoneGeneration if present.
+ *
+ * @param featureMatrix - The GC Feature Matrix, containing the persisted generation value
+ * @param currentGeneration - The current app-provided gcGeneration value
+ * @returns true if GC Sweep should be allowed for this document
+ */
+export function shouldAllowGcSweep(
+	featureMatrix: GCFeatureMatrix,
+	currentGeneration: number | undefined,
+): boolean {
+	// If no Generation value is provided for this session, default to true
+	if (currentGeneration === undefined) {
+		return true;
+	}
+
+	// tombstoneGeneration is the predecessor and needs to be supported for back-compat reasons
+	const targetGeneration = featureMatrix.tombstoneGeneration ?? featureMatrix.gcGeneration;
+
+	return currentGeneration === targetGeneration;
+}
+
+/**
+ * Sorts the given GC state as per the id of the GC nodes. It also sorts the outbound routes array of each node.
+ */
+export function generateSortedGCState(gcState: IGarbageCollectionState): IGarbageCollectionState {
+	const sortableArray: [string, IGarbageCollectionNodeData][] = Object.entries(gcState.gcNodes);
+	sortableArray.sort(([a], [b]) => a.localeCompare(b));
+	const sortedGCState: IGarbageCollectionState = { gcNodes: {} };
+	for (const [nodeId, nodeData] of sortableArray) {
+		nodeData.outboundRoutes.sort();
+		sortedGCState.gcNodes[nodeId] = nodeData;
+	}
+	return sortedGCState;
+}
+
+/**
+ * Concatenates the given GC states and returns the concatenated GC state.
+ */
+export function concatGarbageCollectionStates(
+	gcState1: IGarbageCollectionState,
+	gcState2: IGarbageCollectionState,
+): IGarbageCollectionState {
+	const combinedGCNodes: { [id: string]: IGarbageCollectionNodeData } = {};
+	for (const [nodeId, nodeData] of Object.entries(gcState1.gcNodes)) {
+		combinedGCNodes[nodeId] = {
+			outboundRoutes: Array.from(nodeData.outboundRoutes),
+			unreferencedTimestampMs: nodeData.unreferencedTimestampMs,
+		};
+	}
+
+	for (const [nodeId, nodeData] of Object.entries(gcState2.gcNodes)) {
+		let combineNodeData = combinedGCNodes[nodeId];
+		if (combineNodeData === undefined) {
+			combineNodeData = {
+				outboundRoutes: Array.from(nodeData.outboundRoutes),
+				unreferencedTimestampMs: nodeData.unreferencedTimestampMs,
+			};
+		} else {
+			// Validate that same node doesn't have different unreferenced timestamp.
+			if (
+				nodeData.unreferencedTimestampMs !== undefined &&
+				combineNodeData.unreferencedTimestampMs !== undefined
+			) {
+				assert(
+					nodeData.unreferencedTimestampMs === combineNodeData.unreferencedTimestampMs,
+					0x5d7 /* Two entries for the same GC node with different unreferenced timestamp */,
+				);
+			}
+			combineNodeData = {
+				outboundRoutes: [
+					...new Set([...nodeData.outboundRoutes, ...combineNodeData.outboundRoutes]),
+				],
+				unreferencedTimestampMs:
+					nodeData.unreferencedTimestampMs ?? combineNodeData.unreferencedTimestampMs,
+			};
+		}
+		combinedGCNodes[nodeId] = combineNodeData;
+	}
+	return { gcNodes: combinedGCNodes };
+}
+
+/**
+ * Helper function that clones the GC data.
+ * @param gcData - The GC data to clone.
+ * @returns a clone of the given GC data.
+ */
+export function cloneGCData(gcData: IGarbageCollectionData): IGarbageCollectionData {
+	const clonedGCNodes: { [id: string]: string[] } = {};
+	for (const [id, outboundRoutes] of Object.entries(gcData.gcNodes)) {
+		clonedGCNodes[id] = Array.from(outboundRoutes);
+	}
+	return {
+		gcNodes: clonedGCNodes,
+	};
+}
+
+/**
+ * Concatenates the given GC data and returns the concatenated GC data.
+ */
+export function concatGarbageCollectionData(
+	gcData1: IGarbageCollectionData,
+	gcData2: IGarbageCollectionData,
+) {
+	const combinedGCData: IGarbageCollectionData = cloneGCData(gcData1);
+	for (const [id, routes] of Object.entries(gcData2.gcNodes)) {
+		if (combinedGCData.gcNodes[id] === undefined) {
+			combinedGCData.gcNodes[id] = Array.from(routes);
+		} else {
+			const combinedRoutes = [...routes, ...combinedGCData.gcNodes[id]];
+			combinedGCData.gcNodes[id] = [...new Set(combinedRoutes)];
+		}
+	}
+	return combinedGCData;
+}
+
+/**
+ * Gets the base garbage collection state from the given snapshot tree. It contains GC state, deleted nodes and
+ * tombstones. The GC state may be written into multiple blobs. Merge the GC state from all such blobs into one.
+ */
+export async function getGCDataFromSnapshot(
+	gcSnapshotTree: ISnapshotTree,
+	readAndParseBlob: <T>(id: string) => Promise<T>,
+): Promise<IGarbageCollectionSnapshotData> {
+	let rootGCState: IGarbageCollectionState = { gcNodes: {} };
+	let tombstones: string[] | undefined;
+	let deletedNodes: string[] | undefined;
+	for (const key of Object.keys(gcSnapshotTree.blobs)) {
+		// Update deleted nodes blob.
+		if (key === gcDeletedBlobKey) {
+			deletedNodes = await readAndParseBlob<string[]>(gcSnapshotTree.blobs[key]);
+			continue;
+		}
+
+		// Update tombstone blob.
+		if (key === gcTombstoneBlobKey) {
+			tombstones = await readAndParseBlob<string[]>(gcSnapshotTree.blobs[key]);
+			continue;
+		}
+
+		// Skip blobs that do not start with the GC prefix.
+		if (!key.startsWith(gcBlobPrefix)) {
+			continue;
+		}
+
+		const blobId = gcSnapshotTree.blobs[key];
+		if (blobId === undefined) {
+			continue;
+		}
+		const gcState = await readAndParseBlob<IGarbageCollectionState>(blobId);
+		assert(gcState !== undefined, 0x5d8 /* GC blob missing from snapshot */);
+		// Merge the GC state of this blob into the root GC state.
+		rootGCState = concatGarbageCollectionStates(rootGCState, gcState);
+	}
+	return { gcState: rootGCState, tombstones, deletedNodes };
+}
+
+/**
+ * Helper function that unpacks the GC details of the children from a given node's GC details.
+ * @param gcDetails - The GC details of a node.
+ * @returns A map of GC details of each children of the the given node.
+ */
+export function unpackChildNodesGCDetails(gcDetails: IGarbageCollectionDetailsBase) {
+	const childGCDetailsMap: Map<string, IGarbageCollectionDetailsBase> = new Map();
+
+	// If GC data is not available, bail out.
+	if (gcDetails.gcData === undefined) {
+		return childGCDetailsMap;
+	}
+
+	const gcNodes = gcDetails.gcData.gcNodes;
+	for (const [id, outboundRoutes] of Object.entries(gcNodes)) {
+		// Skip self-node since only children GC data is to be generated.
+		if (id === "/") {
+			continue;
+		}
+
+		assert(id.startsWith("/"), 0x5d9 /* node id should always be an absolute route */);
+		const childId = id.split("/")[1];
+		let childGCNodeId = id.slice(childId.length + 1);
+		// GC node id always begins with "/". Handle the special case where a child's id in the parent's GC nodes is
+		// of format `/root`. In this case, the childId is root and childGCNodeId is "". Make childGCNodeId = "/".
+		if (childGCNodeId === "") {
+			childGCNodeId = "/";
+		}
+
+		let childGCDetails = childGCDetailsMap.get(childId);
+		if (childGCDetails === undefined) {
+			childGCDetails = { gcData: { gcNodes: {} }, usedRoutes: [] };
+		}
+		// gcData should not undefined as its always at least initialized as  empty above.
+		assert(
+			childGCDetails.gcData !== undefined,
+			0x5da /* Child GC data should have been initialized */,
+		);
+		childGCDetails.gcData.gcNodes[childGCNodeId] = [...new Set(outboundRoutes)];
+		childGCDetailsMap.set(childId, childGCDetails);
+	}
+
+	if (gcDetails.usedRoutes === undefined) {
+		return childGCDetailsMap;
+	}
+
+	// Remove the node's self used route, if any, and generate the children used routes.
+	const usedRoutes = gcDetails.usedRoutes.filter((route) => route !== "" && route !== "/");
+	for (const route of usedRoutes) {
+		assert(route.startsWith("/"), 0x5db /* Used route should always be an absolute route */);
+		const childId = route.split("/")[1];
+		const childUsedRoute = route.slice(childId.length + 1);
+
+		const childGCDetails = childGCDetailsMap.get(childId);
+		assert(
+			childGCDetails?.usedRoutes !== undefined,
+			0x5dc /* This should have be initialized when generate GC nodes above */,
+		);
+
+		childGCDetails.usedRoutes.push(childUsedRoute);
+		childGCDetailsMap.set(childId, childGCDetails);
+	}
+	return childGCDetailsMap;
+}
+
+/**
+ * Trims the leading and trailing slashes from the given string.
+ * @param str - A string that may contain leading and / or trailing slashes.
+ * @returns A new string without leading and trailing slashes.
+ */
+export function trimLeadingAndTrailingSlashes(str: string) {
+	return str.replace(/^\/+|\/+$/g, "");
+}
+
+/**
+ * Utility to implement compat behaviors given an unknown message type
+ * The parameters are typed to support compile-time enforcement of handling all known types/behaviors
+ *
+ * @param _unknownGCMessageType - Typed as never to ensure all known types have been
+ * handled before calling this function (e.g. in a switch statement).
+ * @param compatBehavior - Typed redundantly with CompatModeBehavior to ensure handling is added when updating that type
+ */
+export function compatBehaviorAllowsGCMessageType(
+	_unknownGCMessageType: never,
+	compatBehavior: "Ignore" | "FailToProcess" | undefined,
+): boolean {
+	// undefined defaults to same behavior as "FailToProcess"
+	return compatBehavior === "Ignore";
+}

package/src/gc/gcReferenceGraphAlgorithm.ts

@@ -0,0 +1,52 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IGCResult } from "./gcDefinitions";
+
+/**
+ * Runs garbage collection on the given reference graph.
+ * @param referenceGraph - The reference graph to run GC on. It's a list of nodes where each node has an id and set of
+ * routes to other nodes in the graph.
+ * @param rootIds - The ids of root nodes that are considered referenced.
+ * @returns the ids of referenced nodes and the ids of deleted nodes in the referenced graph.
+ */
+export function runGarbageCollection(
+	referenceGraph: { [id: string]: string[] },
+	rootIds: string[],
+): IGCResult {
+	// This set keeps track of nodes that we have visited. It is used to detect cycles in the graph.
+	const visited: Set<string> = new Set();
+
+	// This tracks the ids of referenced nodes. The nodes corresponding to rootIds are always considered
+	// referenced so we start with those.
+	const referencedIds: string[] = [...rootIds];
+	for (const id of referencedIds) {
+		// If we have already seen this node, ignore and continue. Else, add it to visited list.
+		if (visited.has(id)) {
+			continue;
+		}
+		visited.add(id);
+
+		// Get the node for the referenced id and add its outbound routes to referencedIds since they are
+		// also referenced.
+		const routes = referenceGraph[id];
+		if (routes !== undefined) {
+			referencedIds.push(...routes);
+		}
+	}
+
+	const referencedNodeIds: string[] = [];
+	const deletedNodeIds: string[] = [];
+	for (const id of Object.keys(referenceGraph)) {
+		// The nodes from the reference graph whose ids are in the visited list are referenced.
+		// The rest of the nodes are deleted.
+		if (visited.has(id)) {
+			referencedNodeIds.push(id);
+		} else {
+			deletedNodeIds.push(id);
+		}
+	}
+	return { referencedNodeIds, deletedNodeIds };
+}

package/src/gc/gcSummaryDefinitions.ts

@@ -0,0 +1,54 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IGarbageCollectionData } from "@fluidframework/runtime-definitions";
+
+/**
+ * The garbage collection data of each node in the reference graph. Each node's GC data is written in the summary
+ * in this format.
+ */
+export interface IGarbageCollectionNodeData {
+	/**
+	 * The set of routes to other nodes in the graph.
+	 */
+	outboundRoutes: string[];
+	/**
+	 * If the node is unreferenced, the timestamp of when it was marked unreferenced.
+	 */
+	unreferencedTimestampMs?: number;
+}
+
+/**
+ * The garbage collection state of the reference graph. It contains a list of all the nodes in the graph and their
+ * GC data. The GC data is written in the summary in this format.
+ */
+export interface IGarbageCollectionState {
+	gcNodes: { [id: string]: IGarbageCollectionNodeData };
+}
+
+/**
+ * The GC data that is read from a snapshot. It contains the Garbage CollectionState state and tombstone state.
+ */
+export interface IGarbageCollectionSnapshotData {
+	/** The garbage collection state. It is a list of nodes in the container and their GC data. */
+	gcState: IGarbageCollectionState | undefined;
+	/** A list of nodes that have been tombstoned by GC. */
+	tombstones: string[] | undefined;
+	/** A list of nodes that have been deleted by GC. */
+	deletedNodes: string[] | undefined;
+}
+
+/**
+ * @deprecated IGarbageCollectionState is written in the root of the summary now.
+ * Legacy GC details from when the GC details were written at the data store's summary tree.
+ */
+export interface IGarbageCollectionSummaryDetailsLegacy {
+	/** A list of routes to Fluid objects that are used in this node. */
+	usedRoutes?: string[];
+	/** The GC data of this node. */
+	gcData?: IGarbageCollectionData;
+	/** If this node is unreferenced, the time when it was marked as such. */
+	unrefTimestamp?: number;
+}

package/src/gc/gcSummaryStateTracker.ts

@@ -0,0 +1,299 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { SummaryType } from "@fluidframework/protocol-definitions";
+import {
+	gcBlobPrefix,
+	gcDeletedBlobKey,
+	gcTombstoneBlobKey,
+	gcTreeKey,
+	ISummarizeResult,
+	ISummaryTreeWithStats,
+} from "@fluidframework/runtime-definitions";
+import { mergeStats, SummaryTreeBuilder } from "@fluidframework/runtime-utils";
+import { IRefreshSummaryResult } from "../summary";
+import { GCVersion, IGarbageCollectorConfigs, IGCStats } from "./gcDefinitions";
+import { generateSortedGCState } from "./gcHelpers";
+import { IGarbageCollectionSnapshotData, IGarbageCollectionState } from "./gcSummaryDefinitions";
+
+export const gcStateBlobKey = `${gcBlobPrefix}_root`;
+
+/**
+ * The GC data that is tracked for a summary.
+ */
+export interface IGCSummaryTrackingData {
+	serializedGCState: string | undefined;
+	serializedTombstones: string | undefined;
+	serializedDeletedNodes: string | undefined;
+}
+
+/**
+ * Encapsulates the garbage collection state that is tracked across summaries.
+ * It maintains the GC state as per the latest summary in by the server. It updates state when a summary tracked by this
+ * client is acked by the server or from a snapshot is downloaded from the server.
+ * On summarize, it decides whether to write new state or re-use previous summary's state.
+ */
+export class GCSummaryStateTracker {
+	// This is the version of GC data in the latest summary being tracked.
+	private latestSummaryGCVersion: GCVersion;
+
+	// Keeps track of the GC data from the latest summary successfully acked by the server.
+	private latestSummaryData: IGCSummaryTrackingData | undefined;
+	// Keeps track of the GC data from the last summary submitted to the server but not yet acked.
+	private pendingSummaryData: IGCSummaryTrackingData | undefined;
+
+	// Tracks whether there was GC was run in latest summary being tracked.
+	private wasGCRunInLatestSummary: boolean;
+
+	// Tracks the count of data stores whose state updated since the last summary, i.e., they went from referenced
+	// to unreferenced or vice-versa.
+	public updatedDSCountSinceLastSummary: number = 0;
+
+	constructor(
+		// Tells whether GC should run or not.
+		private readonly configs: Pick<
+			IGarbageCollectorConfigs,
+			"shouldRunGC" | "tombstoneMode" | "gcVersionInBaseSnapshot" | "gcVersionInEffect"
+		>,
+		// Tells whether GC was run in the base snapshot this container loaded from.
+		wasGCRunInBaseSnapshot: boolean,
+	) {
+		this.wasGCRunInLatestSummary = wasGCRunInBaseSnapshot;
+		// For existing document, the latest summary is the one that we loaded from. So, use its GC version as the
+		// latest tracked GC version. For new documents, we will be writing the first summary with the current version.
+		this.latestSummaryGCVersion =
+			this.configs.gcVersionInBaseSnapshot ?? this.configs.gcVersionInEffect;
+	}
+
+	/**
+	 * Tells whether the GC state needs to be reset. This can happen under 3 conditions:
+	 *
+	 * 1. The base snapshot contains GC state but GC is disabled. This will happen the first time GC is disabled after
+	 * it was enabled before. GC state needs to be removed from summary and all nodes should be marked referenced.
+	 *
+	 * 2. The base snapshot does not have GC state but GC is enabled. This will happen the very first time GC runs on
+	 * a document and the first time GC is enabled after is was disabled before.
+	 *
+	 * 3. GC is enabled and the latest summary state is refreshed from a snapshot that had GC disabled and vice-versa.
+	 *
+	 * Note that the state will be reset only once for the first summary generated after this returns true. After that,
+	 * this will return false.
+	 */
+	public get doesGCStateNeedReset(): boolean {
+		return this.wasGCRunInLatestSummary !== this.configs.shouldRunGC;
+	}
+
+	/**
+	 * Tells whether the GC state needs to be reset in the next summary. We need to do this if:
+	 *
+	 * 1. GC was enabled and is now disabled. The GC state needs to be removed and everything becomes referenced.
+	 *
+	 * 2. GC was disabled and is now enabled. The GC state needs to be regenerated and added to summary.
+	 *
+	 * 3. GC is enabled and the latest summary state is refreshed from a snapshot that had GC disabled and vice-versa.
+	 *
+	 * 4. The GC version in the latest summary is different from the current GC version. This can happen if:
+	 *
+	 * 4.1. The summary this client loaded with has data from a different GC version.
+	 *
+	 * 4.2. This client's latest summary was updated from a snapshot that has a different GC version.
+	 */
+	public get doesSummaryStateNeedReset(): boolean {
+		return (
+			this.doesGCStateNeedReset ||
+			(this.configs.shouldRunGC &&
+				this.latestSummaryGCVersion !== this.configs.gcVersionInEffect)
+		);
+	}
+
+	/**
+	 * Called during GC initialization. Initialize the latest summary data from the base snapshot data.
+	 */
+	public initializeBaseState(baseSnapshotData: IGarbageCollectionSnapshotData | undefined) {
+		if (baseSnapshotData === undefined) {
+			return;
+		}
+
+		// If tracking state across summaries, update latest summary data from the snapshot's GC data.
+		this.latestSummaryData = {
+			serializedGCState: baseSnapshotData.gcState
+				? JSON.stringify(generateSortedGCState(baseSnapshotData.gcState))
+				: undefined,
+			serializedTombstones: JSON.stringify(baseSnapshotData.tombstones),
+			serializedDeletedNodes: JSON.stringify(baseSnapshotData.deletedNodes),
+		};
+	}
+
+	/**
+	 * Summarizes three component of the GC data - GC state, tombstones and deleted nodes.
+	 * It does incremental summary, i.e., it writes summary tree / summary blob only for the component that changed.
+	 * For components that did not change, a summary handle is returned that points to the previous successful summary.
+	 * If none of the components changed, it returns a summary handle for the entire GC data.
+	 */
+	public summarize(
+		fullTree: boolean,
+		trackState: boolean,
+		gcState: IGarbageCollectionState,
+		deletedNodes: Set<string>,
+		tombstones: string[],
+	): ISummarizeResult | undefined {
+		if (!this.configs.shouldRunGC) {
+			return;
+		}
+
+		const serializedGCState = JSON.stringify(generateSortedGCState(gcState));
+		// Serialize and write deleted nodes, if any. This is done irrespective of whether sweep is enabled or not so
+		// to identify deleted nodes' usage.
+		const serializedDeletedNodes =
+			deletedNodes.size > 0 ? JSON.stringify(Array.from(deletedNodes).sort()) : undefined;
+		// If running in tombstone mode, serialize and write tombstones, if any.
+		const serializedTombstones = this.configs.tombstoneMode
+			? tombstones.length > 0
+				? JSON.stringify(tombstones.sort())
+				: undefined
+			: undefined;
+
+		/**
+		 * Incremental summary of GC data - If none of GC state, deleted nodes or tombstones changed since last summary,
+		 * write summary handle instead of summary tree for GC.
+		 * Otherwise, write the GC summary tree. In the tree, for each of these that changed, write a summary blob and
+		 * for each of these that did not change, write a summary handle.
+		 */
+		this.pendingSummaryData = {
+			serializedGCState,
+			serializedTombstones,
+			serializedDeletedNodes,
+		};
+
+		if (trackState && !fullTree && this.latestSummaryData !== undefined) {
+			// If nothing changed since last summary, send a summary handle for the entire GC data.
+			if (
+				this.latestSummaryData.serializedGCState === serializedGCState &&
+				this.latestSummaryData.serializedTombstones === serializedTombstones &&
+				this.latestSummaryData.serializedDeletedNodes === serializedDeletedNodes
+			) {
+				const stats = mergeStats();
+				stats.handleNodeCount++;
+				return {
+					summary: {
+						type: SummaryType.Handle,
+						handle: `/${gcTreeKey}`,
+						handleType: SummaryType.Tree,
+					},
+					stats,
+				};
+			}
+
+			// If some state changed, build a GC summary tree.
+			return this.buildGCSummaryTree(
+				serializedGCState,
+				serializedTombstones,
+				serializedDeletedNodes,
+				true /* trackState */,
+			);
+		}
+		// If not tracking GC state, build a GC summary tree without any summary handles.
+		return this.buildGCSummaryTree(
+			serializedGCState,
+			serializedTombstones,
+			serializedDeletedNodes,
+			false /* trackState */,
+		);
+	}
+
+	/**
+	 * Builds the GC summary tree which contains GC state, deleted nodes and tombstones.
+	 * If trackState is false, all of GC state, deleted nodes and tombstones are written as summary blobs.
+	 * If trackState is true, only states that changed are written. Rest are written as handles.
+	 * @param serializedGCState - The GC state serialized as string.
+	 * @param serializedTombstones - The tombstone state serialized as string.
+	 * @param serializedDeletedNodes - Deleted nodes serialized as string.
+	 * @param trackState - Whether we are tracking GC state across summaries.
+	 * @returns the GC summary tree.
+	 */
+	private buildGCSummaryTree(
+		serializedGCState: string,
+		serializedTombstones: string | undefined,
+		serializedDeletedNodes: string | undefined,
+		trackState: boolean,
+	): ISummaryTreeWithStats {
+		const builder = new SummaryTreeBuilder();
+
+		// If the GC state hasn't changed, write a summary handle, else write a summary blob for it.
+		if (this.latestSummaryData?.serializedGCState === serializedGCState && trackState) {
+			builder.addHandle(gcStateBlobKey, SummaryType.Blob, `/${gcTreeKey}/${gcStateBlobKey}`);
+		} else {
+			builder.addBlob(gcStateBlobKey, serializedGCState);
+		}
+
+		// If tombstones exist, write a summary handle if it hasn't changed. If it has changed, write a
+		// summary blob.
+		if (serializedTombstones !== undefined) {
+			if (
+				this.latestSummaryData?.serializedTombstones === serializedTombstones &&
+				trackState
+			) {
+				builder.addHandle(
+					gcTombstoneBlobKey,
+					SummaryType.Blob,
+					`/${gcTreeKey}/${gcTombstoneBlobKey}`,
+				);
+			} else {
+				builder.addBlob(gcTombstoneBlobKey, serializedTombstones);
+			}
+		}
+
+		// If there are no deleted nodes, return the summary tree.
+		if (serializedDeletedNodes === undefined) {
+			return builder.getSummaryTree();
+		}
+
+		// If the deleted nodes hasn't changed, write a summary handle, else write a summary blob for it.
+		if (
+			this.latestSummaryData?.serializedDeletedNodes === serializedDeletedNodes &&
+			trackState
+		) {
+			builder.addHandle(
+				gcDeletedBlobKey,
+				SummaryType.Blob,
+				`/${gcTreeKey}/${gcDeletedBlobKey}`,
+			);
+		} else {
+			builder.addBlob(gcDeletedBlobKey, serializedDeletedNodes);
+		}
+		return builder.getSummaryTree();
+	}
+
+	/**
+	 * Called to refresh the latest summary state. This happens when either a pending summary is acked.
+	 */
+	public async refreshLatestSummary(result: IRefreshSummaryResult): Promise<void> {
+		if (!result.isSummaryTracked) {
+			return;
+		}
+
+		// If the summary is tracked, this client is the one that generated it. So, update wasGCRunInLatestSummary.
+		// Note that this has to be updated if GC did not run too. Otherwise, `gcStateNeedsReset` will always return
+		// true in scenarios where GC is currently disabled but enabled in the snapshot we loaded from.
+		this.wasGCRunInLatestSummary = this.configs.shouldRunGC;
+
+		if (!this.configs.shouldRunGC) {
+			return;
+		}
+
+		this.latestSummaryGCVersion = this.configs.gcVersionInEffect;
+		this.latestSummaryData = this.pendingSummaryData;
+		this.pendingSummaryData = undefined;
+		this.updatedDSCountSinceLastSummary = 0;
+		return;
+	}
+
+	/**
+	 * Called to update the state from a GC run's stats. Used to update the count of data stores whose state updated.
+	 */
+	public updateStateFromGCRunStats(stats: IGCStats) {
+		this.updatedDSCountSinceLastSummary += stats.updatedDataStoreCount;
+	}
+}