@fluidframework/container-runtime 2.0.0-dev.5.3.2.178189 → 2.0.0-dev.6.4.0.191457

package/src/summary/summarizer.ts

@@ -3,17 +3,17 @@
  * Licensed under the MIT License.
  */
 
-import { EventEmitter } from "events";
-import { Deferred } from "@fluidframework/common-utils";
+import { Deferred } from "@fluidframework/core-utils";
+import { TypedEventEmitter } from "@fluid-internal/client-utils";
 import {
 	ITelemetryLoggerExt,
-	ChildLogger,
+	createChildLogger,
 	IFluidErrorBase,
 	LoggingError,
+	UsageError,
 	wrapErrorAndLog,
 } from "@fluidframework/telemetry-utils";
 import { ILoader, LoaderHeader } from "@fluidframework/container-definitions";
-import { UsageError } from "@fluidframework/container-utils";
 import { DriverHeader } from "@fluidframework/driver-definitions";
 import { requestFluidObject } from "@fluidframework/runtime-utils";
 import { FluidObject, IFluidHandleContext, IRequest } from "@fluidframework/core-interfaces";
@@ -30,6 +30,12 @@ import {
 	ISummarizerRuntime,
 	ISummarizingWarning,
 	SummarizerStopReason,
+	IOnDemandSummarizeOptions,
+	ISummarizeResults,
+	IEnqueueSummarizeOptions,
+	EnqueueSummarizeResult,
+	ISummarizerEvents,
+	ISummarizeEventProps,
 } from "./summarizerTypes";
 import { SummarizeHeuristicData } from "./summarizerHeuristics";
 import { SummarizeResultBuilder } from "./summaryGenerator";
@@ -61,7 +67,7 @@ export const createSummarizingWarning = (errorMessage: string, logged: boolean)
  * It is the main entry point for summary work.
  * It is created only by summarizing container (i.e. one with clientType === "summarizer")
  */
-export class Summarizer extends EventEmitter implements ISummarizer {
+export class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements ISummarizer {
 	public get ISummarizer() {
 		return this;
 	}
@@ -90,7 +96,7 @@ export class Summarizer extends EventEmitter implements ISummarizer {
 		) => Promise<ICancellableSummarizerController>,
 	) {
 		super();
-		this.logger = ChildLogger.create(this.runtime.logger, "Summarizer");
+		this.logger = createChildLogger({ logger: this.runtime.logger, namespace: "Summarizer" });
 	}
 
 	/**
@@ -210,7 +216,7 @@ export class Summarizer extends EventEmitter implements ISummarizer {
 	 * Should we try to run a last summary for the given stop reason?
 	 * Currently only allows "parentNotConnected"
 	 * @param stopReason - SummarizerStopReason
-	 * @returns - true if the stop reason can run a last summary
+	 * @returns `true` if the stop reason can run a last summary, otherwise `false`.
 	 */
 	public static stopReasonCanRunLastSummary(stopReason: SummarizerStopReason): boolean {
 		return stopReason === "parentNotConnected";
@@ -225,7 +231,7 @@ export class Summarizer extends EventEmitter implements ISummarizer {
 	 * @param onBehalfOf - ID of the client that requested that the summarizer start
 	 * @param runCoordinator - cancellation token
 	 * @param newConfig - Summary configuration to override the existing config when invoking the RunningSummarizer.
-	 * @returns - Promise that is fulfilled when the RunningSummarizer is ready
+	 * @returns A promise that is fulfilled when the RunningSummarizer is ready.
 	 */
 	private async start(
 		onBehalfOf: string,
@@ -277,11 +283,15 @@ export class Summarizer extends EventEmitter implements ISummarizer {
 			this.runtime,
 		);
 		this.runningSummarizer = runningSummarizer;
+		this.runningSummarizer.on("summarize", this.handleSummarizeEvent);
 		this.starting = false;
-
 		return runningSummarizer;
 	}
 
+	private readonly handleSummarizeEvent = (eventProps: ISummarizeEventProps) => {
+		this.emit("summarize", eventProps);
+	};
+
 	/**
 	 * Disposes of resources after running.  This cleanup will
 	 * clear any outstanding timers and reset some of the state
@@ -294,12 +304,13 @@ export class Summarizer extends EventEmitter implements ISummarizer {
 
 		this._disposed = true;
 		if (this.runningSummarizer) {
+			this.runningSummarizer.off("summarize", this.handleSummarizeEvent);
 			this.runningSummarizer.dispose();
 			this.runningSummarizer = undefined;
 		}
 	}
 
-	public readonly summarizeOnDemand: ISummarizer["summarizeOnDemand"] = (...args) => {
+	public summarizeOnDemand(options: IOnDemandSummarizeOptions): ISummarizeResults {
 		try {
 			if (this._disposed || this.runningSummarizer?.disposed) {
 				throw new UsageError("Summarizer is already disposed.");
@@ -318,7 +329,7 @@ export class Summarizer extends EventEmitter implements ISummarizer {
 			const builder = new SummarizeResultBuilder();
 			if (this.runningSummarizer) {
 				// Summarizer is already running. Go ahead and start.
-				return this.runningSummarizer.summarizeOnDemand(builder, ...args);
+				return this.runningSummarizer.summarizeOnDemand(options, builder);
 			}
 
 			// Summarizer isn't running, so we need to start it, which is an async operation.
@@ -335,7 +346,7 @@ export class Summarizer extends EventEmitter implements ISummarizer {
 					startP
 						.then(async (runningSummarizer) => {
 							// Successfully started the summarizer. Run it.
-							runningSummarizer.summarizeOnDemand(builder, ...args);
+							runningSummarizer.summarizeOnDemand(options, builder);
 							// Wait for a command to stop or loss of connectivity before tearing down the summarizer and client.
 							const stopReason = await Promise.race([
 								this.stopDeferred.promise,
@@ -357,9 +368,9 @@ export class Summarizer extends EventEmitter implements ISummarizer {
 		} catch (error) {
 			throw SummarizingWarning.wrap(error, false /* logged */, this.logger);
 		}
-	};
+	}
 
-	public readonly enqueueSummarize: ISummarizer["enqueueSummarize"] = (...args) => {
+	public enqueueSummarize(options: IEnqueueSummarizeOptions): EnqueueSummarizeResult {
 		if (
 			this._disposed ||
 			this.runningSummarizer === undefined ||
@@ -367,8 +378,8 @@ export class Summarizer extends EventEmitter implements ISummarizer {
 		) {
 			throw new UsageError("Summarizer is not running or already disposed.");
 		}
-		return this.runningSummarizer.enqueueSummarize(...args);
-	};
+		return this.runningSummarizer.enqueueSummarize(options);
+	}
 
 	public recordSummaryAttempt?(summaryRefSeqNum?: number) {
 		this._heuristicData?.recordAttempt(summaryRefSeqNum);

package/src/summary/summarizerClientElection.ts

@@ -3,9 +3,9 @@
  * Licensed under the MIT License.
  */
 
-import { IEvent, IEventProvider } from "@fluidframework/common-definitions";
+import { IEvent, IEventProvider } from "@fluidframework/core-interfaces";
 import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
-import { TypedEventEmitter } from "@fluidframework/common-utils";
+import { TypedEventEmitter } from "@fluid-internal/client-utils";
 import { IClientDetails, MessageType } from "@fluidframework/protocol-definitions";
 import {
 	IOrderedClientElection,

package/src/summary/summarizerHeuristics.ts

@@ -4,7 +4,7 @@
  */
 
 import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
-import { Timer } from "@fluidframework/common-utils";
+import { Timer } from "@fluidframework/core-utils";
 import { ISummaryConfigurationHeuristics } from "../containerRuntime";
 import {
 	ISummarizeHeuristicData,

package/src/summary/summarizerNode/index.ts

@@ -4,9 +4,8 @@
  */
 
 export {
-	IFetchSnapshotResult,
+	IRefreshSummaryResult,
 	ISummarizerNodeRootContract,
-	RefreshSummaryResult,
 	ValidateSummaryResult,
 } from "./summarizerNodeUtils";
 export { IRootSummarizerNode, createRootSummarizerNode } from "./summarizerNode";

package/src/summary/summarizerNode/summarizerNode.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryErrorEvent } from "@fluidframework/core-interfaces";
+import { ITelemetryBaseLogger, ITelemetryErrorEvent } from "@fluidframework/core-interfaces";
 import {
 	ISummarizerNode,
 	ISummarizerNodeConfig,
@@ -23,27 +23,22 @@ import {
 } from "@fluidframework/protocol-definitions";
 import {
 	ITelemetryLoggerExt,
-	ChildLogger,
+	createChildLogger,
 	LoggingError,
 	PerformanceEvent,
 	TelemetryDataTag,
+	tagCodeArtifacts,
 } from "@fluidframework/telemetry-utils";
-import { assert, unreachableCase } from "@fluidframework/common-utils";
-import {
-	convertToSummaryTree,
-	calculateStats,
-	mergeStats,
-	ReadAndParseBlob,
-} from "@fluidframework/runtime-utils";
+import { assert, unreachableCase } from "@fluidframework/core-utils";
+import { convertToSummaryTree, calculateStats, mergeStats } from "@fluidframework/runtime-utils";
 import {
 	EscapedPath,
 	ICreateChildDetails,
-	IFetchSnapshotResult,
 	IInitialSummary,
+	IRefreshSummaryResult,
 	ISummarizerNodeRootContract,
 	parseSummaryForSubtrees,
 	parseSummaryTreeForSubtrees,
-	RefreshSummaryResult,
 	SummaryNode,
 	ValidateSummaryResult,
 } from "./summarizerNodeUtils";
@@ -85,30 +80,28 @@ export class SummarizerNode implements IRootSummarizerNode {
 	 * Use createRootSummarizerNode to create root node, or createChild to create child nodes.
 	 */
 	public constructor(
-		baseLogger: ITelemetryLoggerExt,
+		baseLogger: ITelemetryBaseLogger,
 		private readonly summarizeInternalFn: SummarizeInternalFn,
 		config: ISummarizerNodeConfig,
 		private _changeSequenceNumber: number,
 		/** Undefined means created without summary */
 		private _latestSummary?: SummaryNode,
 		private readonly initialSummary?: IInitialSummary,
-		protected wipSummaryLogger?: ITelemetryLoggerExt,
+		protected wipSummaryLogger?: ITelemetryBaseLogger,
 		/** A unique id of this node to be logged when sending telemetry. */
 		protected telemetryNodeId?: string,
 	) {
 		this.canReuseHandle = config.canReuseHandle ?? true;
 		// All logs posted by the summarizer node should include the telemetryNodeId.
-		this.logger = ChildLogger.create(baseLogger, undefined /* namespace */, {
-			all: {
-				id: {
-					tag: TelemetryDataTag.CodeArtifact,
-					value: this.telemetryNodeId,
-				},
+		this.logger = createChildLogger({
+			logger: baseLogger,
+			properties: {
+				all: tagCodeArtifacts({ id: this.telemetryNodeId }),
 			},
 		});
 	}
 
-	public startSummary(referenceSequenceNumber: number, summaryLogger: ITelemetryLoggerExt) {
+	public startSummary(referenceSequenceNumber: number, summaryLogger: ITelemetryBaseLogger) {
 		assert(
 			this.wipSummaryLogger === undefined,
 			0x19f /* "wipSummaryLogger should not be set yet in startSummary" */,
@@ -372,31 +365,21 @@ 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 (e.g., loaded from a service summary),
-	 * we skip the update. Otherwise, we fetch the latest snapshot and update latest summary based off of that.
-	 *
-	 * @returns A RefreshSummaryResult type which returns information based on the following three scenarios:
+	 * 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.
 	 *
-	 * 1. The latest summary was not updated.
-	 *
-	 * 2. The latest summary was updated and the summary corresponding to the params was being tracked.
-	 *
-	 * 3. The latest summary was updated but the summary corresponding to the params was not tracked. In this
-	 * case, the latest summary is updated based on the downloaded snapshot which is also returned.
+	 * @returns true if the summary is tracked by this node, false otherwise.
 	 */
 	public async refreshLatestSummary(
-		proposalHandle: string | undefined,
+		proposalHandle: string,
 		summaryRefSeq: number,
-		fetchLatestSnapshot: () => Promise<IFetchSnapshotResult>,
-		readAndParseBlob: ReadAndParseBlob,
-		correlatedSummaryLogger: ITelemetryLoggerExt,
-	): Promise<RefreshSummaryResult> {
+	): Promise<IRefreshSummaryResult> {
 		const eventProps: {
 			proposalHandle: string | undefined;
 			summaryRefSeq: number;
 			referenceSequenceNumber: number;
-			latestSummaryUpdated?: boolean;
-			wasSummaryTracked?: boolean;
+			isSummaryTracked?: boolean;
+			pendingSummaryFound?: boolean;
 		} = {
 			proposalHandle,
 			summaryRefSeq,
@@ -417,75 +400,22 @@ export class SummarizerNode implements IRootSummarizerNode {
 					});
 				}
 
-				if (proposalHandle !== undefined) {
-					const maybeSummaryNode = this.pendingSummaries.get(proposalHandle);
+				let isSummaryTracked = false;
+				let isSummaryNewer = false;
 
-					if (maybeSummaryNode !== undefined) {
-						this.refreshLatestSummaryFromPending(
-							proposalHandle,
-							maybeSummaryNode.referenceSequenceNumber,
-						);
-						eventProps.wasSummaryTracked = true;
-						eventProps.latestSummaryUpdated = true;
-						event.end(eventProps);
-						return {
-							latestSummaryUpdated: true,
-							wasSummaryTracked: true,
-							summaryRefSeq,
-						};
-					}
-
-					const props = {
-						summaryRefSeq,
-						pendingSize: this.pendingSummaries.size ?? undefined,
-					};
-					this.logger.sendTelemetryEvent({
-						eventName: "PendingSummaryNotFound",
-						proposalHandle,
-						referenceSequenceNumber: this.referenceSequenceNumber,
-						details: JSON.stringify(props),
-					});
+				if (summaryRefSeq > this.referenceSequenceNumber) {
+					isSummaryNewer = true;
 				}
-
-				// If the summary for which refresh is called is older than the latest tracked summary, ignore it.
-				if (this.referenceSequenceNumber >= summaryRefSeq) {
-					eventProps.latestSummaryUpdated = false;
-					event.end(eventProps);
-					return { latestSummaryUpdated: false };
-				}
-
-				// Fetch the latest snapshot and refresh state from it. Note that we need to use the reference sequence number
-				// of the fetched snapshot and not the "summaryRefSeq" that was passed in.
-				const { snapshotTree, snapshotRefSeq: fetchedSnapshotRefSeq } =
-					await fetchLatestSnapshot();
-
-				// Possible re-entrancy. We may have updated latest summary state while fetching the snapshot. If the fetched
-				// snapshot is older than the latest tracked summary, ignore it.
-				if (this.referenceSequenceNumber >= fetchedSnapshotRefSeq) {
-					eventProps.latestSummaryUpdated = false;
-					event.end(eventProps);
-					return { latestSummaryUpdated: false };
+				const maybeSummaryNode = this.pendingSummaries.get(proposalHandle);
+				if (maybeSummaryNode !== undefined) {
+					this.refreshLatestSummaryFromPending(
+						proposalHandle,
+						maybeSummaryNode.referenceSequenceNumber,
+					);
+					isSummaryTracked = true;
 				}
-
-				await this.refreshLatestSummaryFromSnapshot(
-					fetchedSnapshotRefSeq,
-					snapshotTree,
-					undefined,
-					EscapedPath.create(""),
-					correlatedSummaryLogger,
-					readAndParseBlob,
-				);
-
-				eventProps.latestSummaryUpdated = true;
-				eventProps.wasSummaryTracked = false;
-				eventProps.summaryRefSeq = fetchedSnapshotRefSeq;
-				event.end(eventProps);
-				return {
-					latestSummaryUpdated: true,
-					wasSummaryTracked: false,
-					snapshotTree,
-					summaryRefSeq: fetchedSnapshotRefSeq,
-				};
+				event.end({ ...eventProps, isSummaryNewer, pendingSummaryFound: isSummaryTracked });
+				return { isSummaryTracked, isSummaryNewer };
 			},
 			{ start: true, end: true, cancel: "error" },
 		);
@@ -527,59 +457,6 @@ export class SummarizerNode implements IRootSummarizerNode {
 		}
 	}
 
-	protected async refreshLatestSummaryFromSnapshot(
-		referenceSequenceNumber: number,
-		snapshotTree: ISnapshotTree,
-		basePath: EscapedPath | undefined,
-		localPath: EscapedPath,
-		correlatedSummaryLogger: ITelemetryLoggerExt,
-		readAndParseBlob: ReadAndParseBlob,
-	): Promise<void> {
-		// Possible re-entrancy. If we have already seen a summary later than this one, ignore it.
-		if (this.referenceSequenceNumber >= referenceSequenceNumber) {
-			return;
-		}
-
-		this.refreshLatestSummaryCore(referenceSequenceNumber);
-
-		this._latestSummary = new SummaryNode({
-			referenceSequenceNumber,
-			basePath,
-			localPath,
-		});
-
-		const pathParts: string[] = [];
-		const { childrenTree, childrenPathPart } = parseSummaryForSubtrees(snapshotTree);
-		if (childrenPathPart !== undefined) {
-			pathParts.push(childrenPathPart);
-		}
-
-		if (pathParts.length > 0) {
-			this._latestSummary.additionalPath = EscapedPath.createAndConcat(pathParts);
-		}
-
-		// Propagate update to all child nodes
-		const pathForChildren = this._latestSummary.fullPathForChildren;
-		await Promise.all(
-			Array.from(this.children)
-				.filter(([id]) => {
-					// Assuming subtrees missing from snapshot are newer than the snapshot,
-					// but might be nice to assert this using earliest seq for node.
-					return childrenTree.trees[id] !== undefined;
-				})
-				.map(async ([id, child]) => {
-					return child.refreshLatestSummaryFromSnapshot(
-						referenceSequenceNumber,
-						childrenTree.trees[id],
-						pathForChildren,
-						EscapedPath.create(id),
-						correlatedSummaryLogger,
-						readAndParseBlob,
-					);
-				}),
-		);
-	}
-
 	private refreshLatestSummaryCore(referenceSequenceNumber: number): void {
 		for (const [key, value] of this.pendingSummaries) {
 			if (value.referenceSequenceNumber < referenceSequenceNumber) {
@@ -809,10 +686,9 @@ export class SummarizerNode implements IRootSummarizerNode {
 		const error = new LoggingError(eventProps.eventName, {
 			...eventProps,
 			referenceSequenceNumber: this.wipReferenceSequenceNumber,
-			id: {
-				tag: TelemetryDataTag.CodeArtifact,
-				value: this.telemetryNodeId,
-			},
+			...tagCodeArtifacts({
+				id: this.telemetryNodeId,
+			}),
 		});
 		this.logger.sendErrorEvent(eventProps, error);
 		throw error;

package/src/summary/summarizerNode/summarizerNodeUtils.ts

@@ -6,40 +6,12 @@
 import { ITelemetryLoggerExt, TelemetryDataTag } from "@fluidframework/telemetry-utils";
 import { ISnapshotTree, ISummaryTree, SummaryObject } from "@fluidframework/protocol-definitions";
 import { channelsTreeName, ISummaryTreeWithStats } from "@fluidframework/runtime-definitions";
-import { ReadAndParseBlob } from "@fluidframework/runtime-utils";
 
-/**
- * Return type of refreshSummaryAck function. There can be three different scenarios based on the passed params:
- *
- * 1. The latest summary was not updated.
- *
- * 2. The latest summary was updated and the summary corresponding to the params was tracked by this client.
- *
- * 3. The latest summary was updated but the summary corresponding to the params was not tracked. In this case, the
- * latest snapshot is fetched and the latest summary state is updated based on it.
- */
-export type RefreshSummaryResult =
-	| {
-			latestSummaryUpdated: false;
-	  }
-	| {
-			latestSummaryUpdated: true;
-			wasSummaryTracked: true;
-			summaryRefSeq: number;
-	  }
-	| {
-			latestSummaryUpdated: true;
-			wasSummaryTracked: false;
-			snapshotTree: ISnapshotTree;
-			summaryRefSeq: number;
-	  };
-
-/**
- * Result of snapshot fetch during refreshing latest summary state.
- */
-export interface IFetchSnapshotResult {
-	snapshotTree: ISnapshotTree;
-	snapshotRefSeq: number;
+export interface IRefreshSummaryResult {
+	/** Tells whether this summary is tracked by this client. */
+	isSummaryTracked: boolean;
+	/** Tells whether this summary is newer than the latest one tracked by this client. */
+	isSummaryNewer: boolean;
 }
 
 /**
@@ -70,12 +42,9 @@ export interface ISummarizerNodeRootContract {
 	completeSummary(proposalHandle: string, validate: boolean): void;
 	clearSummary(): void;
 	refreshLatestSummary(
-		proposalHandle: string | undefined,
+		proposalHandle: string,
 		summaryRefSeq: number,
-		fetchLatestSnapshot: () => Promise<IFetchSnapshotResult>,
-		readAndParseBlob: ReadAndParseBlob,
-		correlatedSummaryLogger: ITelemetryLoggerExt,
-	): Promise<RefreshSummaryResult>;
+	): Promise<IRefreshSummaryResult>;
 }
 
 /** Path for nodes in a tree with escaped special characters */