@fluidframework/container-runtime 2.0.0-internal.3.1.0 → 2.0.0-internal.3.2.1

package/src/gc/gcDefinitions.ts

@@ -0,0 +1,244 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ICriticalContainerError } from "@fluidframework/container-definitions";
+import { IRequestHeader } from "@fluidframework/core-interfaces";
+import { ISnapshotTree } from "@fluidframework/protocol-definitions";
+import {
+	IGarbageCollectionData,
+	IGarbageCollectionDetailsBase,
+	ISummarizeResult,
+	ITelemetryContext,
+} from "@fluidframework/runtime-definitions";
+import { ReadAndParseBlob, RefreshSummaryResult } from "@fluidframework/runtime-utils";
+import { ITelemetryLogger } from "@fluidframework/common-definitions";
+import { IGCRuntimeOptions } from "../containerRuntime";
+import { IContainerRuntimeMetadata, ICreateContainerMetadata } from "../summary";
+
+export type GCVersion = number;
+
+/** The stable version of garbage collection in production. */
+export const stableGCVersion: GCVersion = 1;
+/** The current version of garbage collection. */
+export const currentGCVersion: GCVersion = 2;
+
+/** This undocumented GC Option (on ContainerRuntime Options) allows an app to disable enforcing GC on old documents by incrementing this value */
+export const gcTombstoneGenerationOptionName = "gcTombstoneGeneration";
+
+// Feature gate key to turn GC on / off.
+export const runGCKey = "Fluid.GarbageCollection.RunGC";
+// Feature gate key to turn GC sweep on / off.
+export const runSweepKey = "Fluid.GarbageCollection.RunSweep";
+// Feature gate key to turn GC test mode on / off.
+export const gcTestModeKey = "Fluid.GarbageCollection.GCTestMode";
+// Feature gate key to expire a session after a set period of time.
+export const runSessionExpiryKey = "Fluid.GarbageCollection.RunSessionExpiry";
+// Feature gate key to write the gc blob as a handle if the data is the same.
+export const trackGCStateKey = "Fluid.GarbageCollection.TrackGCState";
+// Feature gate key to turn GC sweep log off.
+export const disableSweepLogKey = "Fluid.GarbageCollection.DisableSweepLog";
+// Feature gate key to disable the tombstone feature, i.e., tombstone information is not read / written into summary.
+export const disableTombstoneKey = "Fluid.GarbageCollection.DisableTombstone";
+// Feature gate to enable throwing an error when tombstone object is loaded (requested).
+export const throwOnTombstoneLoadKey = "Fluid.GarbageCollection.ThrowOnTombstoneLoad";
+// Feature gate to enable throwing an error when tombstone object is used (e.g. outgoing or incoming ops).
+export const throwOnTombstoneUsageKey = "Fluid.GarbageCollection.ThrowOnTombstoneUsage";
+// Feature gate to enable GC version upgrade.
+export const gcVersionUpgradeToV2Key = "Fluid.GarbageCollection.GCVersionUpgradeToV2";
+// Feature gate to enable GC sweep for datastores.
+// TODO: Remove Test from the flag when we are confident to turn on sweep
+export const sweepDatastoresKey = "Fluid.GarbageCollection.Test.SweepDataStores";
+// Feature gate to enable GC sweep for attachment blobs.
+export const sweepAttachmentBlobsKey = "Fluid.GarbageCollection.Test.SweepAttachmentBlobs";
+
+// One day in milliseconds.
+export const oneDayMs = 1 * 24 * 60 * 60 * 1000;
+
+export const defaultInactiveTimeoutMs = 7 * oneDayMs; // 7 days
+export const defaultSessionExpiryDurationMs = 30 * oneDayMs; // 30 days
+
+/** @see IGCMetadata.gcFeatureMatrix */
+export interface GCFeatureMatrix {
+	/**
+	 * The Tombstone Generation value in effect when this file was created.
+	 * Gives a way for an app to disqualify old files from GC Tombstone enforcement
+	 * Provided via Container Runtime Options
+	 */
+	tombstoneGeneration?: number;
+}
+
+export interface IGCMetadata {
+	/**
+	 * The version of the GC code that was run to generate the GC data that is written in the summary.
+	 * If the persisted value doesn't match the current value in the code, saved GC data will be discarded and regenerated from scratch.
+	 * Also, used to determine whether GC is enabled for this container or not:
+	 * - A value of 0 or undefined means GC is disabled.
+	 * - A value greater than 0 means GC is enabled.
+	 */
+	readonly gcFeature?: GCVersion;
+
+	/**
+	 * A collection of different numerical "Generations" for different features,
+	 * used to determine feature availability over time.
+	 * This info may come from multiple sources (FF code, config service, app via Container Runtime Options),
+	 * and pertains to aspects of the document that may be fixed for its lifetime.
+	 *
+	 * For each dimension, if the persisted value doesn't match the currently provided value,
+	 * then this file does not support the corresponding feature as currently implemented.
+	 *
+	 * Guidance is that if no value is provided at runtime, it should result in the current default behavior.
+	 */
+	readonly gcFeatureMatrix?: GCFeatureMatrix;
+	/**
+	 * Tells whether the GC sweep phase is enabled for this container.
+	 * - True means sweep phase is enabled.
+	 * - False means sweep phase is disabled. If GC is disabled as per gcFeature, sweep is also disabled.
+	 */
+	readonly sweepEnabled?: boolean;
+	/** If this is present, the session for this container will expire after this time and the container will close */
+	readonly sessionExpiryTimeoutMs?: number;
+	/** How long to wait after an object is unreferenced before deleting it via GC Sweep */
+	readonly sweepTimeoutMs?: number;
+}
+
+/** The statistics of the system state after a garbage collection run. */
+export interface IGCStats {
+	/** The number of nodes in the container. */
+	nodeCount: number;
+	/** The number of data stores in the container. */
+	dataStoreCount: number;
+	/** The number of attachment blobs in the container. */
+	attachmentBlobCount: number;
+	/** The number of unreferenced nodes in the container. */
+	unrefNodeCount: number;
+	/** The number of unreferenced data stores in the container. */
+	unrefDataStoreCount: number;
+	/** The number of unreferenced attachment blobs in the container. */
+	unrefAttachmentBlobCount: number;
+	/** The number of nodes whose reference state updated since last GC run. */
+	updatedNodeCount: number;
+	/** The number of data stores whose reference state updated since last GC run. */
+	updatedDataStoreCount: number;
+	/** The number of attachment blobs whose reference state updated since last GC run. */
+	updatedAttachmentBlobCount: number;
+}
+
+/** The types of GC nodes in the GC reference graph. */
+export const GCNodeType = {
+	// Nodes that are for data stores.
+	DataStore: "DataStore",
+	// Nodes that are within a data store. For example, DDS nodes.
+	SubDataStore: "SubDataStore",
+	// Nodes that are for attachment blobs, i.e., blobs uploaded via BlobManager.
+	Blob: "Blob",
+	// Nodes that are neither of the above. For example, root node.
+	Other: "Other",
+};
+export type GCNodeType = typeof GCNodeType[keyof typeof GCNodeType];
+
+/** Defines the APIs for the runtime object to be passed to the garbage collector. */
+export interface IGarbageCollectionRuntime {
+	/** Before GC runs, called to notify the runtime to update any pending GC state. */
+	updateStateBeforeGC(): Promise<void>;
+	/** Returns the garbage collection data of the runtime. */
+	getGCData(fullGC?: boolean): Promise<IGarbageCollectionData>;
+	/** After GC has run, called to notify the runtime of routes that are used in it. */
+	updateUsedRoutes(usedRoutes: string[]): void;
+	/** After GC has run, called to notify the runtime of routes that are unused in it. */
+	updateUnusedRoutes(unusedRoutes: string[]): void;
+	/**
+	 * After GC has run and identified nodes that are sweep ready, called to delete the sweep ready nodes. The runtime
+	 * should return the routes of nodes that were deleted.
+	 * @param sweepReadyRoutes - The routes of nodes that are sweep ready and should be deleted.
+	 */
+	deleteSweepReadyNodes(sweepReadyRoutes: string[]): string[];
+	/** Called to notify the runtime of routes that are tombstones. */
+	updateTombstonedRoutes(tombstoneRoutes: string[]): void;
+	/** Returns a referenced timestamp to be used to track unreferenced nodes. */
+	getCurrentReferenceTimestampMs(): number | undefined;
+	/** Returns the type of the GC node. */
+	getNodeType(nodePath: string): GCNodeType;
+	/** Called when the runtime should close because of an error. */
+	closeFn: (error?: ICriticalContainerError) => void;
+	/** If false, loading or using a Tombstoned object should merely log, not fail */
+	gcTombstoneEnforcementAllowed: boolean;
+}
+
+/** Defines the contract for the garbage collector. */
+export interface IGarbageCollector {
+	/** Tells whether GC should run or not. */
+	readonly shouldRunGC: boolean;
+	/** Tells whether the GC state in summary needs to be reset in the next summary. */
+	readonly summaryStateNeedsReset: boolean;
+	/** Initialize the state from the base snapshot after its creation. */
+	initializeBaseState(): Promise<void>;
+	/** Run garbage collection and update the reference / used state of the system. */
+	collectGarbage(
+		options: {
+			logger?: ITelemetryLogger;
+			runSweep?: boolean;
+			fullGC?: boolean;
+		},
+		telemetryContext?: ITelemetryContext,
+	): Promise<IGCStats | undefined>;
+	/** Summarizes the GC data and returns it as a summary tree. */
+	summarize(
+		fullTree: boolean,
+		trackState: boolean,
+		telemetryContext?: ITelemetryContext,
+	): ISummarizeResult | undefined;
+	/** Returns the garbage collector specific metadata to be written into the summary. */
+	getMetadata(): IGCMetadata;
+	/** Returns the GC details generated from the base snapshot. */
+	getBaseGCDetails(): Promise<IGarbageCollectionDetailsBase>;
+	/** Called when the latest summary of the system has been refreshed. */
+	refreshLatestSummary(
+		proposalHandle: string | undefined,
+		result: RefreshSummaryResult,
+		readAndParseBlob: ReadAndParseBlob,
+	): Promise<void>;
+	/** Called when a node is updated. Used to detect and log when an inactive node is changed or loaded. */
+	nodeUpdated(
+		nodePath: string,
+		reason: "Loaded" | "Changed",
+		timestampMs?: number,
+		packagePath?: readonly string[],
+		requestHeaders?: IRequestHeader,
+	): void;
+	/** Called when a reference is added to a node. Used to identify nodes that were referenced between summaries. */
+	addedOutboundReference(fromNodePath: string, toNodePath: string): void;
+	/** Returns true if this node has been deleted by GC during sweep phase. */
+	isNodeDeleted(nodePath: string): boolean;
+	setConnectionState(connected: boolean, clientId?: string): void;
+	dispose(): void;
+}
+
+/** Parameters necessary for creating a GarbageCollector. */
+export interface IGarbageCollectorCreateParams {
+	readonly runtime: IGarbageCollectionRuntime;
+	readonly gcOptions: IGCRuntimeOptions;
+	readonly baseLogger: ITelemetryLogger;
+	readonly existing: boolean;
+	readonly metadata: IContainerRuntimeMetadata | undefined;
+	readonly createContainerMetadata: ICreateContainerMetadata;
+	readonly baseSnapshot: ISnapshotTree | undefined;
+	readonly isSummarizerClient: boolean;
+	readonly getNodePackagePath: (nodePath: string) => Promise<readonly string[] | undefined>;
+	readonly getLastSummaryTimestampMs: () => number | undefined;
+	readonly readAndParseBlob: ReadAndParseBlob;
+	readonly activeConnection: () => boolean;
+	readonly getContainerDiagnosticId: () => string;
+}
+
+/** The state of node that is unreferenced. */
+export const UnreferencedState = {
+	/** The node is active, i.e., it can become referenced again. */
+	Active: "Active",
+	/** The node is inactive, i.e., it should not become referenced. */
+	Inactive: "Inactive",
+	/** The node is ready to be deleted by the sweep phase. */
+	SweepReady: "SweepReady",
+} as const;
+export type UnreferencedState = typeof UnreferencedState[keyof typeof UnreferencedState];

package/src/{garbageCollectionHelpers.ts → gc/gcHelpers.ts}

@@ -4,14 +4,28 @@
  */
 
 import { ITelemetryGenericEvent } from "@fluidframework/common-definitions";
+import {
+	IGarbageCollectionNodeData,
+	IGarbageCollectionState,
+} from "@fluidframework/runtime-definitions";
 import { packagePathToTelemetryProperty } from "@fluidframework/runtime-utils";
 import { MonitoringContext } from "@fluidframework/telemetry-utils";
 import {
 	disableTombstoneKey,
+	GCVersion,
+	IGCMetadata,
 	runSweepKey,
 	throwOnTombstoneLoadKey,
 	throwOnTombstoneUsageKey,
-} from "./garbageCollectionConstants";
+} from "./gcDefinitions";
+
+export function getGCVersion(metadata?: IGCMetadata): GCVersion {
+	if (!metadata) {
+		// Force to 0/disallowed in prior versions
+		return 0;
+	}
+	return metadata.gcFeature ?? 0;
+}
 
 /**
  * Consolidates info / logic for logging when we encounter unexpected usage of GC'd objects. For example, when a
@@ -59,3 +73,14 @@ export function shouldAllowGcTombstoneEnforcement(
 	}
 	return persistedGeneration === currentGeneration;
 }
+
+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;
+}

package/src/gc/gcSummaryStateTracker.ts

@@ -0,0 +1,339 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { getGCDataFromSnapshot } from "@fluidframework/garbage-collector";
+import { SummaryType } from "@fluidframework/protocol-definitions";
+import {
+	gcBlobPrefix,
+	gcDeletedBlobKey,
+	gcTombstoneBlobKey,
+	gcTreeKey,
+	IGarbageCollectionSnapshotData,
+	IGarbageCollectionState,
+	ISummarizeResult,
+	ISummaryTreeWithStats,
+} from "@fluidframework/runtime-definitions";
+import {
+	mergeStats,
+	ReadAndParseBlob,
+	RefreshSummaryResult,
+	SummaryTreeBuilder,
+} from "@fluidframework/runtime-utils";
+import { MonitoringContext } from "@fluidframework/telemetry-utils";
+import { IContainerRuntimeMetadata, metadataBlobName } from "../summary";
+import {
+	currentGCVersion,
+	GCVersion,
+	gcVersionUpgradeToV2Key,
+	stableGCVersion,
+} from "./gcDefinitions";
+import { generateSortedGCState, getGCVersion } from "./gcHelpers";
+
+/**
+ * The GC data that is tracked for a summary.
+ */
+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 {
+	// The current version of GC running.
+	public readonly currentGCVersion: GCVersion;
+	// 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;
+
+	constructor(
+		// Tells whether GC should run or not.
+		private readonly shouldRunGC: boolean,
+		// Tells whether GC state should be tracked across summaries or not.
+		private readonly trackGCState: boolean,
+		// Tells whether tombstone mode is enabled or not.
+		private readonly tombstoneMode: boolean,
+		private readonly mc: MonitoringContext,
+		// Tells whether GC was run in the base snapshot this container loaded from.
+		wasGCRunInBaseSnapshot: boolean,
+		// The GC version in the base snapshot this container loaded from.
+		gcVersionInBaseSnapshot: GCVersion | undefined,
+	) {
+		this.wasGCRunInLatestSummary = wasGCRunInBaseSnapshot;
+		// If version upgrade is not enabled, fall back to the stable GC version.
+		this.currentGCVersion =
+			this.mc.config.getBoolean(gcVersionUpgradeToV2Key) === true
+				? currentGCVersion
+				: stableGCVersion;
+		// 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 = gcVersionInBaseSnapshot ?? this.currentGCVersion;
+	}
+
+	/**
+	 * 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 doesGCStateNeedReset(): boolean {
+		return this.wasGCRunInLatestSummary !== this.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 doesSummaryStateNeedReset(): boolean {
+		return (
+			this.doesGCStateNeedReset() ||
+			(this.shouldRunGC && this.latestSummaryGCVersion !== this.currentGCVersion)
+		);
+	}
+
+	/**
+	 * 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.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.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.
+		 */
+		if (this.trackGCState) {
+			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
+				) {
+					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 gcStateBlobKey = `${gcBlobPrefix}_root`;
+		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 or a snapshot
+	 * is downloaded and should be used to update the state.
+	 */
+	public async refreshLatestSummary(
+		proposalHandle: string | undefined,
+		result: RefreshSummaryResult,
+		readAndParseBlob: ReadAndParseBlob,
+	): Promise<IGarbageCollectionSnapshotData | undefined> {
+		// If the latest summary was updated and the summary was tracked, this client is the one that generated this
+		// summary. 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 disabled but enabled in the snapshot we loaded from.
+		if (result.latestSummaryUpdated && result.wasSummaryTracked) {
+			this.wasGCRunInLatestSummary = this.shouldRunGC;
+		}
+
+		if (!result.latestSummaryUpdated || !this.shouldRunGC) {
+			return undefined;
+		}
+
+		// If the summary was tracked by this client, it was the one that generated the summary in the first place.
+		// Update latest state from pending.
+		if (result.wasSummaryTracked) {
+			this.latestSummaryGCVersion = this.currentGCVersion;
+			if (this.trackGCState) {
+				this.latestSummaryData = this.pendingSummaryData;
+				this.pendingSummaryData = undefined;
+			}
+			return undefined;
+		}
+
+		// If the summary was not tracked by this client, the state should be updated from the downloaded snapshot.
+		const snapshotTree = result.snapshotTree;
+		const metadataBlobId = snapshotTree.blobs[metadataBlobName];
+		if (metadataBlobId) {
+			const metadata = await readAndParseBlob<IContainerRuntimeMetadata>(metadataBlobId);
+			this.latestSummaryGCVersion = getGCVersion(metadata);
+		}
+
+		const gcSnapshotTree = snapshotTree.trees[gcTreeKey];
+		// If GC ran in the container that generated this snapshot, it will have a GC tree.
+		this.wasGCRunInLatestSummary = gcSnapshotTree !== undefined;
+		let latestGCData: IGarbageCollectionSnapshotData | undefined;
+		if (gcSnapshotTree !== undefined) {
+			latestGCData = await getGCDataFromSnapshot(gcSnapshotTree, readAndParseBlob);
+		}
+		this.pendingSummaryData = undefined;
+		return latestGCData;
+	}
+
+	/**
+	 * Update state from the given snapshot data. This is done during load and during refreshing state from a snapshot.
+	 * @param gcSnapshotData - The GC snapshot data to update state from.
+	 */
+	public updateStateFromSnapshotData(gcSnapshotData: IGarbageCollectionSnapshotData | undefined) {
+		// If there is no snapshot data, it means this snapshot was generated with GC disabled. Unset all GC state.
+		if (gcSnapshotData === undefined) {
+			this.latestSummaryData = undefined;
+			return;
+		}
+
+		// If tracking state across summaries, update latest summary data from the snapshot's GC data.
+		if (this.trackGCState) {
+			this.latestSummaryData = {
+				serializedGCState: JSON.stringify(generateSortedGCState(gcSnapshotData.gcState)),
+				serializedTombstones: JSON.stringify(gcSnapshotData.tombstones),
+				serializedDeletedNodes: JSON.stringify(gcSnapshotData.deletedNodes),
+			};
+		}
+	}
+}

package/src/{gcSweepReadyUsageDetection.ts → gc/gcSweepReadyUsageDetection.ts}

@@ -11,7 +11,7 @@ import {
 	LoggingError,
 	MonitoringContext,
 } from "@fluidframework/telemetry-utils";
-import { oneDayMs } from "./garbageCollectionConstants";
+import { oneDayMs } from "./gcDefinitions";
 
 /**
  * Feature Gate Key -