@fluidframework/container-runtime 2.1.0 → 2.2.0

package/src/summary/summarizerNode/summarizerNode.ts

@@ -165,6 +165,11 @@ export class SummarizerNode implements IRootSummarizerNode {
 		trackState: boolean = true,
 		telemetryContext?: ITelemetryContext,
 	): Promise<ISummarizeResult> {
+		// If trackState is false, call summarize internal directly and don't track any state.
+		if (!trackState) {
+			return this.summarizeInternalFn(fullTree, trackState, telemetryContext);
+		}
+
 		// Try to reuse the tree if unchanged
 		if (this.canReuseHandle && !fullTree && !this.hasChanged()) {
 			const latestSummary = this._latestSummary;
@@ -206,7 +211,7 @@ export class SummarizerNode implements IRootSummarizerNode {
 
 		const result = await this.summarizeInternalFn(
 			fullTree,
-			true,
+			trackState,
 			telemetryContext,
 			incrementalSummaryContext,
 		);

package/src/summary/summarizerNode/summarizerNodeWithGc.ts

@@ -6,13 +6,9 @@
 import { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert, LazyPromise } from "@fluidframework/core-utils/internal";
 import {
-	IExperimentalIncrementalSummaryContext,
-	ITelemetryContext,
 	IGarbageCollectionData,
 	CreateChildSummarizerNodeParam,
 	IGarbageCollectionDetailsBase,
-	ISummarizeInternalResult,
-	ISummarizeResult,
 	ISummarizerNodeConfigWithGC,
 	ISummarizerNodeWithGC,
 	SummarizeInternalFn,
@@ -72,6 +68,9 @@ export class SummarizerNodeWithGC extends SummarizerNode implements IRootSummari
 	// Tracks the work-in-progress used routes during summary.
 	private wipSerializedUsedRoutes: string | undefined;
 
+	// Tracks the work-in-progress used routes of child nodes during summary.
+	private wipChildNodesUsedRoutes: Map<string, string[]> | undefined;
+
 	// This is the last known used routes of this node as seen by the server as part of a summary.
 	private referenceUsedRoutes: string[] | undefined;
 
@@ -102,12 +101,7 @@ export class SummarizerNodeWithGC extends SummarizerNode implements IRootSummari
 	 */
 	public constructor(
 		logger: ITelemetryBaseLogger,
-		private readonly summarizeFn: (
-			fullTree: boolean,
-			trackState: boolean,
-			telemetryContext?: ITelemetryContext,
-			incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
-		) => Promise<ISummarizeInternalResult>,
+		summarizeInternalFn: SummarizeInternalFn,
 		config: ISummarizerNodeConfigWithGC,
 		changeSequenceNumber: number,
 		/** Undefined means created without summary */
@@ -120,18 +114,7 @@ export class SummarizerNodeWithGC extends SummarizerNode implements IRootSummari
 	) {
 		super(
 			logger,
-			async (
-				fullTree: boolean,
-				_trackState: boolean,
-				telemetryContext?: ITelemetryContext,
-				incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
-			) =>
-				summarizeFn(
-					fullTree,
-					true /* trackState */,
-					telemetryContext,
-					incrementalSummaryContext,
-				),
+			summarizeInternalFn,
 			config,
 			changeSequenceNumber,
 			latestSummary,
@@ -182,27 +165,6 @@ export class SummarizerNodeWithGC extends SummarizerNode implements IRootSummari
 		}
 	}
 
-	public async summarize(
-		fullTree: boolean,
-		trackState: boolean = true,
-		telemetryContext?: ITelemetryContext,
-	): Promise<ISummarizeResult> {
-		// If GC is not disabled and a summary is in progress, GC should have run and updated the used routes for this
-		// summary by calling updateUsedRoutes which sets wipSerializedUsedRoutes.
-		if (!this.gcDisabled && this.isSummaryInProgress()) {
-			assert(
-				this.wipSerializedUsedRoutes !== undefined,
-				0x1b1 /* "wip used routes should be set if tracking a summary" */,
-			);
-		}
-
-		// If trackState is true, get summary from base summarizer node which tracks summary state.
-		// If trackState is false, get summary from summarizeInternal.
-		return trackState
-			? super.summarize(fullTree, true /* trackState */, telemetryContext)
-			: this.summarizeFn(fullTree, trackState, telemetryContext);
-	}
-
 	/**
 	 * Returns the GC data of this node. If nothing has changed since last summary, it tries to reuse the data from
 	 * the previous summary. Else, it gets new GC data from the underlying Fluid object.
@@ -338,6 +300,7 @@ export class SummarizerNodeWithGC extends SummarizerNode implements IRootSummari
 	 */
 	public clearSummary() {
 		this.wipSerializedUsedRoutes = undefined;
+		this.wipChildNodesUsedRoutes = undefined;
 		super.clearSummary();
 	}
 
@@ -444,6 +407,20 @@ export class SummarizerNodeWithGC extends SummarizerNode implements IRootSummari
 	protected maybeUpdateChildState(child: SummarizerNodeWithGC, id: string) {
 		super.maybeUpdateChildState(child, id);
 
+		// If GC has run on this node and summarization isn't complete, this.wipSerializedUsedRoutes will be defined.
+		// In that case, update the used routes of the child node. This can happen in scenarios where a data store
+		// doesn't have any ops but its reference state changed. So, it gets realized during summarize after GC ran
+		// so GC would not have run on this node which is fine.
+		if (this.wipSerializedUsedRoutes !== undefined) {
+			// If the child route used routes are not defined, initialize it now and it can be used for all child nodes
+			// created until this summarization process is completed. This is an optimization to unpack the used routes
+			// only when needed.
+			if (this.wipChildNodesUsedRoutes === undefined) {
+				this.wipChildNodesUsedRoutes = unpackChildNodesUsedRoutes(this.usedRoutes);
+			}
+			child.updateUsedRoutes(this.wipChildNodesUsedRoutes.get(id) ?? [""]);
+		}
+
 		// In case we have pending summaries on the parent, let's initialize it on the child.
 		if (child.latestSummary !== undefined) {
 			for (const [key, value] of this.pendingSummaries.entries()) {

package/src/summary/summaryFormats.md

@@ -8,17 +8,17 @@
 -   [Summary / Snapshot Tree Visualization](#summary--snapshot-tree-visualization)
     -   [Protocol Tree](#protocol-tree)
     -   [App Tree](#app-tree)
-    -   [Summary Tree distinction](#summary-tree-distinction)
+    -   [Summary tree distinction - Incremental summaries](#summary-tree-distinction---incremental-summaries)
 
 ## Introduction
 
 This document describes the format of summaries and snapshots. For learning the differences between summaries and snapshots, see the FAQ section [here](https://fluidframework.com/docs/faq/#whats-the-difference-between-a-summary-and-a-snapshot).
 
-The goal of this document is to describe the fundamental structure of a summary / snapshot tree as produced by the runtime, to explain the various node types within the tree along with their respective data, and to show the distinctions between a summary tree and a snapshot tree.
+The following sections describe the fundamental structure of a summary / snapshot tree as produced by the runtime, explains the various node types within the tree along with their respective data, and shows the distinctions between a summary tree and a snapshot tree.
 
-## Summary Format
+### Summary Format
 
-Summary is uploaded to storage and is the container's state at a point in time. A summary is represented by an `ISummaryTree` which is defined in [this file](../../../../../common/lib/protocol-definitions/src/summary.ts) and has the following basic structure (some optional properties are removed for simplicity):
+Summary is uploaded to storage and is the container's state at a point in time. A summary is represented by an `ISummaryTree` which is defined in [summary.ts in the protocol-definitions package][summary-protocol] and has the following basic structure (some optional properties are removed for simplicity):
 
 ```typescript
 export interface ISummaryTree {
@@ -62,21 +62,21 @@ Each tree node in a summary tree is represented by the `ISummaryTree` interface
 
     -   `ISummaryHandle` - A summary handle is used for incremental summaries. If a node hasn't changed since the last successful summary, instead of sending it's entire contents, it can send a "handle" which is a path to its summary tree object in the last summary. For example, if a data store or DDS did not change since the last summary, the runtime will use a handle for the entire data store instead of re-sending the entire subtree. The same concept applies for a summary blob or a summary attachment and the "handleType" should be set according to the type of the node. An example of "handle" that a DDS sends would be something like: "/_dataStoreId_/_ddsId_".
 
-            ```typescript
-            export interface ISummaryHandle {
-            	type: SummaryType.Handle;
-            	handleType: SummaryTypeNoHandle;
-            	handle: string;
-            }
-            export type SummaryTypeNoHandle =
-            	| SummaryType.Tree
-            	| SummaryType.Blob
-            	| SummaryType.Attachment;
-            ```
+        ```typescript
+        export interface ISummaryHandle {
+            type: SummaryType.Handle;
+            handleType: SummaryTypeNoHandle;
+            handle: string;
+        }
+        export type SummaryTypeNoHandle =
+            | SummaryType.Tree
+            | SummaryType.Blob
+            | SummaryType.Attachment;
+        ```
 
-## Snapshot Format
+### Snapshot Format
 
-Snapshot is downloaded from the storage (typically on document load) and is the container's state at a point in time. A snapshot is represented by an `ISnapshotTree` which is defined in [this file](../../../../../common/lib/protocol-definitions/src/storage.ts) and has the following basic structure (some optional properties are removed for simplicity):
+Snapshot is downloaded from the storage (typically on document load) and is the container's state at a point in time. A snapshot is represented by an `ISnapshotTree` which is defined in [storage.ts in the protocol-definitions package][storage-protocol] and has the following basic structure (some optional properties are removed for simplicity):
 
 ```typescript
 export interface ISnapshotTree {
@@ -99,7 +99,7 @@ Each node in a snapshot tree is represented by the above interface and contains
 
     `<tree name>`: `<snapshot tree>` where `tree name` is the name given to the subtree by the node and `snapshot tree` is its content in `ISnapshotTree` format.
 
-## Summary / Snapshot Tree Visualization
+### Summary / Snapshot Tree Visualization
 
 This section shows what a typical summary or snapshot tree in a container looks like. Some key things to note:
 
@@ -129,7 +129,7 @@ flowchart TD
 
 `App tree` - This is the tree named `.app` and contains the container's state and data. The subtree under .app is what is generated by the container runtime.
 
-### Protocol tree
+#### Protocol tree
 
 The contents of the protocol tree are:
 
@@ -139,7 +139,7 @@ The contents of the protocol tree are:
 -   `quorum values blob` - The quorum values at the time summary was taken.
 -   Other blobs and trees may be added at this level as needed.
 
-### App tree
+#### App tree
 
 This is what the ".app" tree looks like which is generated by the container runtime during summary upload. The same is passed to container runtime during snapshot download:
 
@@ -172,8 +172,8 @@ flowchart TD
     A --> T[.blobs]:::tree
         T --> U["attachment blob 1"]:::attachment
         T --> V["attachment blob N"]:::attachment
-
 ```
+
 -   `Container`: The root represents the container or container runtime node. Its contents are described below:
 
     -   `.metadata blob` - The container level metadata such as creation time, create version, etc.
@@ -195,7 +195,7 @@ flowchart TD
     -   `.header blob` - Added by some DDSs and may contains its data. Note that all DDSs may not add this.
     -   A DDS may add other blobs and / or trees to represent its data. Basically, a DDS can write its data in any form
 
-### Summary tree distinction - Incremental summaries
+#### Summary tree distinction - Incremental summaries
 
 In the visualization above, a summary tree differs from a snapshot tree in the following way:
 A summary tree supports incremental summaries via summary handles. Any node in the tree that has not changed since the previous successful summary can send a summary handle (`ISummaryHandle`) instead of sending its entire contents in a full summary. The following diagram shows this with an example where certain parts of the summary tree use a summary handle. It is a zoomed in version of the same app tree as above where nodes where summary handles are marked in red:
@@ -219,3 +219,6 @@ flowchart TD
         C --> L["data store N"]:::tree
     A --> M["handle: '/gc'"]:::handle
 ```
+
+[summary-protocol]: /common/lib/protocol-definitions/src/summary.ts
+[storage-protocol]: /common/lib/protocol-definitions/src/storage.ts