@fluidframework/container-runtime 2.4.0-297027 → 2.4.0-299374

package/src/summary/summarizerNode/summarizerNode.ts

@@ -37,9 +37,8 @@ import {
 	IRefreshSummaryResult,
 	IStartSummaryResult,
 	ISummarizerNodeRootContract,
-	SummaryNode,
 	ValidateSummaryResult,
-	parseSummaryForSubtrees,
+	PendingSummaryInfo,
 } from "./summarizerNodeUtils.js";
 
 export interface IRootSummarizerNode extends ISummarizerNode, ISummarizerNodeRootContract {}
@@ -63,13 +62,30 @@ export class SummarizerNode implements IRootSummarizerNode {
 	 * Returns 0 if there is not yet an acked summary.
 	 */
 	public get referenceSequenceNumber() {
-		return this._latestSummary?.referenceSequenceNumber ?? 0;
+		return this._lastSummaryReferenceSequenceNumber ?? 0;
+	}
+
+	/**
+	 * returns the handle of the last successful summary of this summarizerNode in string format
+	 * (this getter is primarily only used in the test code)
+	 */
+	public get summaryHandleId(): string {
+		return this._summaryHandleId.toString();
 	}
 
 	protected readonly children = new Map<string, SummarizerNode>();
-	protected readonly pendingSummaries = new Map<string, SummaryNode>();
+	/**
+	 * Key value pair of summaries submitted by this client which are not yet acked.
+	 * Key is the proposalHandle and value is the summary op's referece sequence number.
+	 */
+	protected readonly pendingSummaries = new Map<string, PendingSummaryInfo>();
 	protected wipReferenceSequenceNumber: number | undefined;
-	private wipLocalPaths: { localPath: EscapedPath; additionalPath?: EscapedPath } | undefined;
+	/**
+	 * True if the current node was summarized during the current summary process
+	 * This flag is used to identify scenarios where summarize was not called on a node.
+	 * For example, this node was created after its parent was already summarized due to out-of-order realization via application code.
+	 */
+	private wipSummarizeCalled: boolean = false;
 	private wipSkipRecursion = false;
 
 	protected readonly logger: ITelemetryLoggerExt;
@@ -82,9 +98,11 @@ export class SummarizerNode implements IRootSummarizerNode {
 		baseLogger: ITelemetryBaseLogger,
 		private readonly summarizeInternalFn: SummarizeInternalFn,
 		config: ISummarizerNodeConfig,
+		/** Encoded handle or path to the node */
+		private readonly _summaryHandleId: EscapedPath,
 		private _changeSequenceNumber: number,
-		/** Undefined means created without summary */
-		private _latestSummary?: SummaryNode,
+		/** Summary reference sequence number, i.e. last sequence number seen when last successful summary was created */
+		private _lastSummaryReferenceSequenceNumber?: number,
 		protected wipSummaryLogger?: ITelemetryBaseLogger,
 		/** A unique id of this node to be logged when sending telemetry. */
 		protected telemetryNodeId?: string,
@@ -124,10 +142,10 @@ export class SummarizerNode implements IRootSummarizerNode {
 			0x1a0 /* "Already tracking a summary" */,
 		);
 
-		let nodes = 1;
+		let nodes = 1; // number of summarizerNodes at the start of the summary
 		let invalidNodes = 0;
 		const sequenceNumberMismatchKeySet = new Set<string>();
-		const nodeLatestSummaryRefSeqNum = this._latestSummary?.referenceSequenceNumber;
+		const nodeLatestSummaryRefSeqNum = this._lastSummaryReferenceSequenceNumber;
 		if (
 			nodeLatestSummaryRefSeqNum !== undefined &&
 			latestSummaryRefSeqNum !== nodeLatestSummaryRefSeqNum
@@ -170,21 +188,19 @@ export class SummarizerNode implements IRootSummarizerNode {
 			return this.summarizeInternalFn(fullTree, trackState, telemetryContext);
 		}
 
+		// Set to wipSummarizeCalled true to represent that current node was included in the summary process.
+		this.wipSummarizeCalled = true;
+
 		// Try to reuse the tree if unchanged
 		if (this.canReuseHandle && !fullTree && !this.hasChanged()) {
-			const latestSummary = this._latestSummary;
-			if (latestSummary !== undefined) {
-				this.wipLocalPaths = {
-					localPath: latestSummary.localPath,
-					additionalPath: latestSummary.additionalPath,
-				};
+			if (this._lastSummaryReferenceSequenceNumber !== undefined) {
 				this.wipSkipRecursion = true;
 				const stats = mergeStats();
 				stats.handleNodeCount++;
 				return {
 					summary: {
 						type: SummaryType.Handle,
-						handle: latestSummary.fullPath.path,
+						handle: this.summaryHandleId,
 						handleType: SummaryType.Tree,
 					},
 					stats,
@@ -199,12 +215,12 @@ export class SummarizerNode implements IRootSummarizerNode {
 				0x5df /* Summarize should not be called when not tracking the summary */,
 			);
 			incrementalSummaryContext =
-				this._latestSummary !== undefined
+				this._lastSummaryReferenceSequenceNumber !== undefined
 					? {
 							summarySequenceNumber: this.wipReferenceSequenceNumber,
-							latestSummarySequenceNumber: this._latestSummary.referenceSequenceNumber,
-							// TODO: remove summaryPath
-							summaryPath: this._latestSummary.fullPath.path,
+							latestSummarySequenceNumber: this._lastSummaryReferenceSequenceNumber,
+							// TODO: remove summaryPath.
+							summaryPath: this.summaryHandleId,
 						}
 					: undefined;
 		}
@@ -215,12 +231,7 @@ export class SummarizerNode implements IRootSummarizerNode {
 			telemetryContext,
 			incrementalSummaryContext,
 		);
-		this.wipLocalPaths = { localPath: EscapedPath.create(result.id) };
-		if (result.pathPartsForChildren !== undefined) {
-			this.wipLocalPaths.additionalPath = EscapedPath.createAndConcat(
-				result.pathPartsForChildren,
-			);
-		}
+
 		return { summary: result.summary, stats: result.stats };
 	}
 
@@ -280,8 +291,8 @@ export class SummarizerNode implements IRootSummarizerNode {
 
 		// If the parent node skipped recursion, it did not call summarize on this node. So, summarize was not missed
 		// but was intentionally not called.
-		// Otherwise, summarize should have been called on this node and wipLocalPaths must be set.
-		if (parentSkipRecursion || this.wipLocalPaths !== undefined) {
+		// Otherwise, summarize should have been called on this node and wipSummarizeCalled must be set.
+		if (parentSkipRecursion || this.wipSummarizeCalled) {
 			return false;
 		}
 
@@ -307,11 +318,7 @@ export class SummarizerNode implements IRootSummarizerNode {
 	 * @param proposalHandle - The handle of the summary that was uploaded to the server.
 	 */
 	public completeSummary(proposalHandle: string) {
-		this.completeSummaryCore(
-			proposalHandle,
-			undefined /* parentPath */,
-			false /* parentSkipRecursion */,
-		);
+		this.completeSummaryCore(proposalHandle, false /* parentSkipRecursion */);
 	}
 
 	/**
@@ -322,31 +329,13 @@ export class SummarizerNode implements IRootSummarizerNode {
 	 * In that case, the children will not have work-in-progress state.
 	 * @param validate - true to validate that the in-progress summary is correct for all nodes.
 	 */
-	protected completeSummaryCore(
-		proposalHandle: string,
-		parentPath: EscapedPath | undefined,
-		parentSkipRecursion: boolean,
-	) {
+	protected completeSummaryCore(proposalHandle: string, parentSkipRecursion: boolean) {
 		assert(
 			this.wipReferenceSequenceNumber !== undefined,
 			0x1a4 /* "Not tracking a summary" */,
 		);
-		let localPathsToUse = this.wipLocalPaths;
-
 		if (parentSkipRecursion) {
-			const latestSummary = this._latestSummary;
-			if (latestSummary !== undefined) {
-				// This case the parent node created a failure summary or was reused.
-				// This node and all children should only try to reference their path
-				// by its last known good state in the actual summary tree.
-				// If parent fails or is reused, the child summarize is not called so
-				// it did not get a chance to change its paths.
-				// In this case, essentially only propagate the new summary ref seq num.
-				localPathsToUse = {
-					localPath: latestSummary.localPath,
-					additionalPath: latestSummary.additionalPath,
-				};
-			} else {
+			if (this._lastSummaryReferenceSequenceNumber === undefined) {
 				// This case the child is added after the latest non-failure summary.
 				// This node and all children should consider themselves as still not
 				// having a successful summary yet.
@@ -358,21 +347,8 @@ export class SummarizerNode implements IRootSummarizerNode {
 			}
 		}
 
-		// If localPathsToUse is undefined, it means summarize didn't run for this node and in that case the validate
-		// step should have failed.
-		assert(localPathsToUse !== undefined, 0x6fe /* summarize didn't run for node */);
-		const summary = new SummaryNode({
-			...localPathsToUse,
-			referenceSequenceNumber: this.wipReferenceSequenceNumber,
-			basePath: parentPath,
-		});
-		const fullPathForChildren = summary.fullPathForChildren;
 		for (const child of this.children.values()) {
-			child.completeSummaryCore(
-				proposalHandle,
-				fullPathForChildren,
-				this.wipSkipRecursion || parentSkipRecursion,
-			);
+			child.completeSummaryCore(proposalHandle, this.wipSkipRecursion || parentSkipRecursion);
 		}
 		// Note that this overwrites existing pending summary with
 		// the same proposalHandle. If proposalHandle is something like
@@ -380,13 +356,15 @@ export class SummarizerNode implements IRootSummarizerNode {
 		// can return the same proposalHandle for a different summary,
 		// this should still be okay, because we should be proposing the
 		// newer one later which would have to overwrite the previous one.
-		this.pendingSummaries.set(proposalHandle, summary);
+		this.pendingSummaries.set(proposalHandle, {
+			referenceSequenceNumber: this.wipReferenceSequenceNumber,
+		});
 		this.clearSummary();
 	}
 
 	public clearSummary() {
 		this.wipReferenceSequenceNumber = undefined;
-		this.wipLocalPaths = undefined;
+		this.wipSummarizeCalled = false;
 		this.wipSkipRecursion = false;
 		this.wipSummaryLogger = undefined;
 		for (const child of this.children.values()) {
@@ -398,7 +376,8 @@ export class SummarizerNode implements IRootSummarizerNode {
 	 * Refreshes the latest summary tracked by this node. If we have a pending summary for the given proposal handle,
 	 * it becomes the latest summary. If the current summary is already ahead, we skip the update.
 	 * If the current summary is behind, then we do not refresh.
-	 *
+	 * @param proposalHandle - Handle of the generated / uploaded summary.
+	 * @param summaryRefSeq - Reference sequence of the acked summary
 	 * @returns true if the summary is tracked by this node, false otherwise.
 	 */
 	public async refreshLatestSummary(
@@ -437,13 +416,17 @@ export class SummarizerNode implements IRootSummarizerNode {
 				if (summaryRefSeq > this.referenceSequenceNumber) {
 					isSummaryNewer = true;
 				}
-				const maybeSummaryNode = this.pendingSummaries.get(proposalHandle);
-				if (maybeSummaryNode !== undefined) {
+
+				// If the acked summary is found in the pendingSummaries, it means the summary was created and tracked by the current client
+				// so set the isSummaryTracked to true.
+				const pendingSummary = this.pendingSummaries.get(proposalHandle);
+				if (pendingSummary?.referenceSequenceNumber !== undefined) {
+					isSummaryTracked = true;
+					// update the pendingSummariesMap for the root and all child summarizerNodes
 					this.refreshLatestSummaryFromPending(
 						proposalHandle,
-						maybeSummaryNode.referenceSequenceNumber,
+						pendingSummary.referenceSequenceNumber,
 					);
-					isSummaryTracked = true;
 				}
 				event.end({ ...eventProps, isSummaryNewer, pendingSummaryFound: isSummaryTracked });
 				return { isSummaryTracked, isSummaryNewer };
@@ -461,17 +444,17 @@ export class SummarizerNode implements IRootSummarizerNode {
 		proposalHandle: string,
 		referenceSequenceNumber: number,
 	): void {
-		const summaryNode = this.pendingSummaries.get(proposalHandle);
-		if (summaryNode === undefined) {
+		const pendingSummary = this.pendingSummaries.get(proposalHandle);
+		if (pendingSummary === undefined) {
 			// This should only happen if parent skipped recursion AND no prior summary existed.
 			assert(
-				this._latestSummary === undefined,
+				this._lastSummaryReferenceSequenceNumber === undefined,
 				0x1a6 /* "Not found pending summary, but this node has previously completed a summary" */,
 			);
 			return;
 		} else {
 			assert(
-				referenceSequenceNumber === summaryNode.referenceSequenceNumber,
+				referenceSequenceNumber === pendingSummary.referenceSequenceNumber,
 				0x1a7 /* Pending summary reference sequence number should be consistent */,
 			);
 
@@ -479,30 +462,22 @@ export class SummarizerNode implements IRootSummarizerNode {
 			this.pendingSummaries.delete(proposalHandle);
 		}
 
-		this.refreshLatestSummaryCore(referenceSequenceNumber);
-
-		this._latestSummary = summaryNode;
+		// Delete all summaries whose reference sequence number is smaller than the one just acked.
+		for (const [key, summary] of this.pendingSummaries) {
+			if (summary.referenceSequenceNumber < referenceSequenceNumber) {
+				this.pendingSummaries.delete(key);
+			}
+		}
+		// Update the latest successful summary reference number
+		this._lastSummaryReferenceSequenceNumber = pendingSummary.referenceSequenceNumber;
 		// Propagate update to all child nodes
 		for (const child of this.children.values()) {
 			child.refreshLatestSummaryFromPending(proposalHandle, referenceSequenceNumber);
 		}
 	}
 
-	private refreshLatestSummaryCore(referenceSequenceNumber: number): void {
-		for (const [key, value] of this.pendingSummaries) {
-			if (value.referenceSequenceNumber < referenceSequenceNumber) {
-				this.pendingSummaries.delete(key);
-			}
-		}
-	}
-
 	public updateBaseSummaryState(snapshot: ISnapshotTree) {
-		// Check base summary to see if it has any additional path parts
-		// separating child SummarizerNodes. Checks for .channels subtrees.
-		const { childrenPathPart } = parseSummaryForSubtrees(snapshot);
-		if (childrenPathPart !== undefined && this._latestSummary !== undefined) {
-			this._latestSummary.additionalPath = EscapedPath.create(childrenPathPart);
-		}
+		// Function deprecated. Empty declaration is kept around to compat failures.
 	}
 
 	public recordChange(op: ISequencedDocumentMessage): void {
@@ -524,10 +499,6 @@ export class SummarizerNode implements IRootSummarizerNode {
 		return this._changeSequenceNumber > this.referenceSequenceNumber;
 	}
 
-	public get latestSummary(): Readonly<SummaryNode> | undefined {
-		return this._latestSummary;
-	}
-
 	protected readonly canReuseHandle: boolean;
 
 	public createChild(
@@ -550,8 +521,9 @@ export class SummarizerNode implements IRootSummarizerNode {
 			this.logger,
 			summarizeInternalFn,
 			config,
+			createDetails.summaryHandleId,
 			createDetails.changeSequenceNumber,
-			createDetails.latestSummary,
+			createDetails.lastSummaryReferenceSequenceNumber,
 			this.wipSummaryLogger,
 			createDetails.telemetryNodeId,
 		);
@@ -579,26 +551,26 @@ export class SummarizerNode implements IRootSummarizerNode {
 		id: string,
 		createParam: CreateChildSummarizerNodeParam,
 	): ICreateChildDetails {
-		let latestSummary: SummaryNode | undefined;
+		let childLastSummaryReferenceSequenceNumber: number | undefined;
 		let changeSequenceNumber: number;
 
-		const parentLatestSummary = this._latestSummary;
+		const parentLastSummaryReferenceSequenceNumber = this._lastSummaryReferenceSequenceNumber;
 		switch (createParam.type) {
 			case CreateSummarizerNodeSource.FromAttach: {
 				if (
-					parentLatestSummary !== undefined &&
-					createParam.sequenceNumber <= parentLatestSummary.referenceSequenceNumber
+					parentLastSummaryReferenceSequenceNumber !== undefined &&
+					createParam.sequenceNumber <= parentLastSummaryReferenceSequenceNumber
 				) {
 					// Prioritize latest summary if it was after this node was attached.
-					latestSummary = parentLatestSummary.createForChild(id);
+					childLastSummaryReferenceSequenceNumber = parentLastSummaryReferenceSequenceNumber;
 				}
 				changeSequenceNumber = createParam.sequenceNumber;
 				break;
 			}
 			case CreateSummarizerNodeSource.FromSummary:
 			case CreateSummarizerNodeSource.Local: {
-				latestSummary = parentLatestSummary?.createForChild(id);
-				changeSequenceNumber = parentLatestSummary?.referenceSequenceNumber ?? -1;
+				childLastSummaryReferenceSequenceNumber = parentLastSummaryReferenceSequenceNumber;
+				changeSequenceNumber = parentLastSummaryReferenceSequenceNumber ?? -1;
 				break;
 			}
 			default: {
@@ -608,11 +580,13 @@ export class SummarizerNode implements IRootSummarizerNode {
 		}
 
 		const childTelemetryNodeId = `${this.telemetryNodeId ?? ""}/${id}`;
+		const childSummaryHandleId = this._summaryHandleId.createChildPath(EscapedPath.create(id));
 
 		return {
-			latestSummary,
 			changeSequenceNumber,
 			telemetryNodeId: childTelemetryNodeId,
+			summaryHandleId: childSummaryHandleId,
+			lastSummaryReferenceSequenceNumber: childLastSummaryReferenceSequenceNumber,
 		};
 	}
 
@@ -632,21 +606,15 @@ export class SummarizerNode implements IRootSummarizerNode {
 			child.wipReferenceSequenceNumber = this.wipReferenceSequenceNumber;
 		}
 		// 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()) {
-				const newLatestSummaryNode = new SummaryNode({
-					referenceSequenceNumber: value.referenceSequenceNumber,
-					basePath: child._latestSummary.basePath,
-					localPath: child._latestSummary.localPath,
-				});
-
-				child.addPendingSummary(key, newLatestSummaryNode);
-			}
+		if (child._lastSummaryReferenceSequenceNumber !== undefined) {
+			this.pendingSummaries.forEach((pendingSummaryInfo, proposedHandle) => {
+				child.addPendingSummary(proposedHandle, pendingSummaryInfo);
+			});
 		}
 	}
 
-	protected addPendingSummary(key: string, summary: SummaryNode) {
-		this.pendingSummaries.set(key, summary);
+	protected addPendingSummary(key: string, pendingSummaryInfo: PendingSummaryInfo) {
+		this.pendingSummaries.set(key, pendingSummaryInfo);
 	}
 
 	/**
@@ -692,10 +660,9 @@ export const createRootSummarizerNode = (
 		logger,
 		summarizeInternalFn,
 		config,
+		EscapedPath.create("") /* summaryHandleId */,
 		changeSequenceNumber,
-		referenceSequenceNumber === undefined
-			? undefined
-			: SummaryNode.createForRoot(referenceSequenceNumber),
+		referenceSequenceNumber,
 		undefined /* wipSummaryLogger */,
 		"" /* telemetryNodeId */,
 	);

package/src/summary/summarizerNode/summarizerNodeUtils.ts

@@ -64,104 +64,46 @@ export interface ISummarizerNodeRootContract {
 	): Promise<IRefreshSummaryResult>;
 }
 
-/** Path for nodes in a tree with escaped special characters */
+/** Class to build paths for nodes in a tree with escaped special characters */
 export class EscapedPath {
 	private constructor(public readonly path: string) {}
+
+	/**
+	 * Creates and returns a new instance of this class.
+	 * @param path - Id or path part of a node
+	 */
 	public static create(path: string): EscapedPath {
 		return new EscapedPath(encodeURIComponent(path));
 	}
-	public static createAndConcat(pathParts: string[]): EscapedPath {
-		let ret = EscapedPath.create(pathParts[0] ?? "");
-		for (let i = 1; i < pathParts.length; i++) {
-			ret = ret.concat(EscapedPath.create(pathParts[i]));
-		}
-		return ret;
-	}
 	public toString(): string {
 		return this.path;
 	}
-	public concat(path: EscapedPath): EscapedPath {
-		return new EscapedPath(`${this.path}/${path.path}`);
-	}
-}
-
-/** Information about a summary relevant to a specific node in the tree */
-export class SummaryNode {
-	/** Creates an instance that is valid for the root with specific basePath and localPath */
-	public static createForRoot(referenceSequenceNumber: number): SummaryNode {
-		return new SummaryNode({
-			referenceSequenceNumber,
-			basePath: undefined,
-			localPath: EscapedPath.create(""), // root hard-coded to ""
-		});
-	}
-
-	/** Summary reference sequence number, i.e. last sequence number seen when it was created */
-	public get referenceSequenceNumber(): number {
-		return this.summary.referenceSequenceNumber;
-	}
-	/** Full path to parent node, or undefined if this is the root */
-	public get basePath(): EscapedPath | undefined {
-		return this.summary.basePath;
-	}
-	/** Relative path to this node from its parent node */
-	public get localPath(): EscapedPath {
-		return this.summary.localPath;
-	}
-	/** Relative path from this node to its node innermost base summary */
-	public get additionalPath(): EscapedPath | undefined {
-		return this.summary.additionalPath;
-	}
-	public set additionalPath(additionalPath: EscapedPath | undefined) {
-		this.summary.additionalPath = additionalPath;
-	}
-	constructor(
-		private readonly summary: {
-			readonly referenceSequenceNumber: number;
-			readonly basePath: EscapedPath | undefined;
-			readonly localPath: EscapedPath;
-			additionalPath?: EscapedPath;
-		},
-	) {}
-
-	/** Gets the full path to this node, to be used when sending a handle */
-	public get fullPath(): EscapedPath {
-		return this.basePath?.concat(this.localPath) ?? this.localPath;
-	}
-
-	/**
-	 * Gets the full path to this node's innermost base summary.
-	 * The children nodes can use this as their basePath to determine their path.
-	 */
-	public get fullPathForChildren(): EscapedPath {
-		return this.additionalPath !== undefined
-			? this.fullPath.concat(this.additionalPath)
-			: this.fullPath;
-	}
-
 	/**
-	 * Creates a new node within the same summary for a child of this node.
-	 * @param id - id of the child node
+	 * Creates and returns a new instance of this class for child of the current node.
 	 */
-	public createForChild(id: string): SummaryNode {
-		return new SummaryNode({
-			referenceSequenceNumber: this.referenceSequenceNumber,
-			basePath: this.fullPathForChildren,
-			localPath: EscapedPath.create(id),
-		});
+	public createChildPath(childNodePath: EscapedPath): EscapedPath {
+		return new EscapedPath(
+			`${this.path}/${encodeURIComponent(channelsTreeName)}/${childNodePath.path}`,
+		);
 	}
 }
+export interface PendingSummaryInfo {
+	/** The sequence number at which the summary was created. */
+	referenceSequenceNumber: number;
+}
 
 /**
  * Represents the details needed to create a child summarizer node.
  */
 export interface ICreateChildDetails {
-	/** Latest summary from server node data */
-	latestSummary: SummaryNode | undefined;
 	/** Sequence number of latest known change to the node */
 	changeSequenceNumber: number;
 	/** A unique id of this child to be logged when sending telemetry. */
 	telemetryNodeId: string;
+	/** Summary handle for child node */
+	summaryHandleId: EscapedPath;
+	/** the reference sequence number of the last successful summary. */
+	lastSummaryReferenceSequenceNumber: number | undefined;
 }
 
 export interface ISubtreeInfo<T extends ISnapshotTree | SummaryObject> {
@@ -170,25 +112,3 @@ export interface ISubtreeInfo<T extends ISnapshotTree | SummaryObject> {
 	/** Additional path part where children are isolated */
 	childrenPathPart: string | undefined;
 }
-
-/**
- * Checks if the summary contains .channels subtree where the children subtrees
- * would be located if exists.
- * @param baseSummary - summary to check
- */
-export function parseSummaryForSubtrees(
-	baseSummary: ISnapshotTree,
-): ISubtreeInfo<ISnapshotTree> {
-	// New versions of snapshots have child nodes isolated in .channels subtree
-	const channelsSubtree = baseSummary.trees[channelsTreeName];
-	if (channelsSubtree !== undefined) {
-		return {
-			childrenTree: channelsSubtree,
-			childrenPathPart: channelsTreeName,
-		};
-	}
-	return {
-		childrenTree: baseSummary,
-		childrenPathPart: undefined,
-	};
-}