@fluidframework/container-runtime 2.0.0-dev-rc.5.0.0.263932 → 2.0.0-dev-rc.5.0.0.267932

package/src/summary/summarizerTypes.ts

@@ -4,13 +4,15 @@
  */
 
 import { IDeltaManager, ContainerWarning } from "@fluidframework/container-definitions/internal";
-import { IEvent, IEventProvider, ITelemetryBaseProperties } from "@fluidframework/core-interfaces";
 import {
-	IDocumentMessage,
-	ISequencedDocumentMessage,
-	ISummaryTree,
-} from "@fluidframework/protocol-definitions";
-import { ISummaryStats } from "@fluidframework/runtime-definitions";
+	IEvent,
+	IEventProvider,
+	ITelemetryBaseProperties,
+	ITelemetryBaseLogger,
+} from "@fluidframework/core-interfaces";
+import { ISequencedDocumentMessage, ISummaryTree } from "@fluidframework/driver-definitions";
+import { IDocumentMessage } from "@fluidframework/driver-definitions/internal";
+import { ISummaryStats } from "@fluidframework/runtime-definitions/internal";
 import {
 	ITelemetryLoggerExt,
 	ITelemetryLoggerPropertyBag,
@@ -90,7 +92,7 @@ export interface IConnectableRuntime {
  * @alpha
  */
 export interface ISummarizerRuntime extends IConnectableRuntime {
-	readonly logger: ITelemetryLoggerExt;
+	readonly baseLogger: ITelemetryBaseLogger;
 	/** clientId of parent (non-summarizing) container that owns summarizer container */
 	readonly summarizerClientId: string | undefined;
 	readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
@@ -113,13 +115,6 @@ export interface ISummarizerRuntime extends IConnectableRuntime {
 export interface ISummarizeOptions {
 	/** True to generate the full tree with no handle reuse optimizations; defaults to false */
 	readonly fullTree?: boolean;
-	/**
-	 * True to ask the server what the latest summary is first; defaults to false
-	 *
-	 * @deprecated Summarize will not refresh latest snapshot state anymore. Instead it updates the cache and closes.
-	 * It's expected a new summarizer client will be created, likely by the same parent.
-	 */
-	readonly refreshLatestAck?: boolean;
 }
 
 /**
@@ -183,14 +178,22 @@ export interface IGeneratedSummaryStats extends ISummaryStats {
 	readonly summaryNumber: number;
 }
 
+/**
+ * Type for summarization failures that are retriable.
+ * @alpha
+ */
+export interface IRetriableFailureError extends Error {
+	readonly retryAfterSeconds?: number;
+}
+
 /**
  * Base results for all submitSummary attempts.
  * @alpha
  */
 export interface IBaseSummarizeResult {
 	readonly stage: "base";
-	/** Error object related to failed summarize attempt. */
-	readonly error: Error | undefined;
+	/** Retriable error object related to failed summarize attempt. */
+	readonly error: IRetriableFailureError | undefined;
 	/** Reference sequence number as of the generate summary attempt. */
 	readonly referenceSequenceNumber: number;
 	readonly minimumSequenceNumber: number;
@@ -208,8 +211,6 @@ export interface IGenerateSummaryTreeResult extends Omit<IBaseSummarizeResult, "
 	readonly summaryStats: IGeneratedSummaryStats;
 	/** Time it took to generate the summary tree and stats. */
 	readonly generateDuration: number;
-	/** True if the full tree regeneration with no handle reuse optimizations was forced. */
-	readonly forcedFullTree: boolean;
 }
 
 /**
@@ -265,19 +266,11 @@ export type SubmitSummaryResult =
  */
 export type SummaryStage = SubmitSummaryResult["stage"] | "unknown";
 
-/**
- * Type for summarization failures that are retriable.
- * @alpha
- */
-export interface IRetriableFailureResult {
-	readonly retryAfterSeconds?: number;
-}
-
 /**
  * The data in summarizer result when submit summary stage fails.
  * @alpha
  */
-export interface SubmitSummaryFailureData extends IRetriableFailureResult {
+export interface SubmitSummaryFailureData {
 	stage: SummaryStage;
 }
 
@@ -300,7 +293,7 @@ export interface IAckSummaryResult {
 /**
  * @alpha
  */
-export interface INackSummaryResult extends IRetriableFailureResult {
+export interface INackSummaryResult {
 	readonly summaryNackOp: ISummaryNackMessage;
 	readonly ackNackDuration: number;
 }
@@ -317,7 +310,7 @@ export type SummarizeResultPart<TSuccess, TFailure = undefined> =
 			success: false;
 			data: TFailure | undefined;
 			message: string;
-			error: any;
+			error: IRetriableFailureError;
 	  };
 
 /**
@@ -535,10 +528,6 @@ type ISummarizeTelemetryRequiredProperties =
 type ISummarizeTelemetryOptionalProperties =
 	/** Number of attempts within the last time window, used for calculating the throttle delay. */
 	| "summaryAttempts"
-	/** Number of attempts within the current phase (currently capped at 2 ) */
-	| "summaryAttemptsPerPhase"
-	/** One-based count of phases we've attempted (used to index into an array of ISummarizeOptions */
-	| "summaryAttemptPhase"
 	/** Summarization may be attempted multiple times. This tells whether this is the final summarization attempt */
 	| "finalAttempt"
 	| keyof ISummarizeOptions;

package/src/summary/summaryCollection.ts

@@ -7,14 +7,14 @@ import { TypedEventEmitter } from "@fluid-internal/client-utils";
 import { IDeltaManager } from "@fluidframework/container-definitions/internal";
 import { IDisposable, IEvent } from "@fluidframework/core-interfaces";
 import { assert, Deferred } from "@fluidframework/core-utils/internal";
+import { ISequencedDocumentMessage } from "@fluidframework/driver-definitions";
 import {
 	IDocumentMessage,
-	ISequencedDocumentMessage,
 	ISummaryAck,
 	ISummaryContent,
 	ISummaryNack,
 	MessageType,
-} from "@fluidframework/protocol-definitions";
+} from "@fluidframework/driver-definitions/internal";
 import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 
 /**

package/src/summary/summaryFormat.ts

@@ -4,18 +4,20 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import { IDocumentStorageService } from "@fluidframework/driver-definitions/internal";
+import { ISequencedDocumentMessage, SummaryType } from "@fluidframework/driver-definitions";
+import {
+	IDocumentStorageService,
+	ISnapshotTree,
+} from "@fluidframework/driver-definitions/internal";
 import {
 	blobHeadersBlobName as blobNameForBlobHeaders,
 	readAndParse,
 } from "@fluidframework/driver-utils/internal";
 import {
-	ISequencedDocumentMessage,
-	ISnapshotTree,
-	SummaryType,
-} from "@fluidframework/protocol-definitions";
-import { ISummaryTreeWithStats } from "@fluidframework/runtime-definitions";
-import { channelsTreeName, gcTreeKey } from "@fluidframework/runtime-definitions/internal";
+	ISummaryTreeWithStats,
+	channelsTreeName,
+	gcTreeKey,
+} from "@fluidframework/runtime-definitions/internal";
 
 import { IGCMetadata } from "../gc/index.js";
 

package/src/summary/summaryGenerator.ts

@@ -11,9 +11,8 @@ import {
 	IPromiseTimerResult,
 	Timer,
 } from "@fluidframework/core-utils/internal";
-import { DriverErrorTypes } from "@fluidframework/driver-definitions/internal";
+import { DriverErrorTypes, MessageType } from "@fluidframework/driver-definitions/internal";
 import { getRetryDelaySecondsFromError } from "@fluidframework/driver-utils/internal";
-import { MessageType } from "@fluidframework/protocol-definitions";
 import {
 	isFluidError,
 	ITelemetryLoggerExt,
@@ -35,6 +34,7 @@ import {
 	SubmitSummaryResult,
 	SummarizeResultPart,
 	SummaryGeneratorTelemetry,
+	type IRetriableFailureError,
 } from "./summarizerTypes.js";
 import { IClientSummaryWatcher } from "./summaryCollection.js";
 
@@ -127,8 +127,10 @@ const summarizeErrors = {
 	disconnect: "Summary cancelled due to summarizer or main client disconnect",
 } as const;
 
+export type SummarizeErrorCode = keyof typeof summarizeErrors;
+
 // Helper functions to report failures and return.
-export const getFailMessage = (errorCode: keyof typeof summarizeErrors) =>
+export const getFailMessage = (errorCode: SummarizeErrorCode) =>
 	`${errorCode}: ${summarizeErrors[errorCode]}`;
 
 export class SummarizeResultBuilder {
@@ -150,7 +152,7 @@ export class SummarizeResultBuilder {
 	 */
 	public fail(
 		message: string,
-		error: any,
+		error: IRetriableFailureError,
 		submitFailureResult?: SubmitSummaryFailureData,
 		nackSummaryResult?: INackSummaryResult,
 	) {
@@ -184,8 +186,7 @@ export class SummarizeResultBuilder {
 /**
  * Errors type for errors hit during summary that may be retriable.
  */
-export class RetriableSummaryError extends LoggingError {
-	public readonly canRetry = this.retryAfterSeconds !== undefined;
+export class RetriableSummaryError extends LoggingError implements IRetriableFailureError {
 	constructor(
 		message: string,
 		public readonly retryAfterSeconds?: number,
@@ -221,9 +222,8 @@ export class SummaryGenerator {
 	/**
 	 * Generates summary and listens for broadcast and ack/nack.
 	 * Returns true for ack, false for nack, and undefined for failure or timeout.
-	 * @param reason - reason for summarizing
-	 * @param options - refreshLatestAck to fetch summary ack info from server,
-	 * fullTree to generate tree without any summary handles even if unchanged
+	 * @param summaryOptions - options controlling how the summary is generated or submitted.
+	 * @param resultsBuilder - optional, result builder to use to build pass or fail result.
 	 */
 	public summarize(
 		summaryOptions: ISubmitSummaryOptions,
@@ -273,8 +273,8 @@ export class SummaryGenerator {
 		 * be provided. For op broadcast failures, only errors / properties should be provided.
 		 */
 		const fail = (
-			errorCode: keyof typeof summarizeErrors,
-			error?: Error,
+			errorCode: SummarizeErrorCode,
+			error: IRetriableFailureError,
 			properties?: SummaryGeneratorTelemetry,
 			submitFailureResult?: SubmitSummaryFailureData,
 			nackSummaryResult?: INackSummaryResult,
@@ -294,11 +294,9 @@ export class SummaryGenerator {
 					...properties,
 					reason,
 					category,
-					retryAfterSeconds:
-						submitFailureResult?.retryAfterSeconds ??
-						nackSummaryResult?.retryAfterSeconds,
+					retryAfterSeconds: error.retryAfterSeconds,
 				},
-				error ?? reason,
+				error,
 			); // disconnect & summaryAckTimeout do not have proper error.
 
 			resultsBuilder.fail(reason, error, submitFailureResult, nackSummaryResult);
@@ -330,9 +328,11 @@ export class SummaryGenerator {
 			);
 
 			if (summaryData.stage !== "submit") {
-				return fail("submitSummaryFailure", summaryData.error, summarizeTelemetryProps, {
+				const errorCode: SummarizeErrorCode = "submitSummaryFailure";
+				const retriableError =
+					summaryData.error ?? new RetriableSummaryError(getFailMessage(errorCode));
+				return fail(errorCode, retriableError, summarizeTelemetryProps, {
 					stage: summaryData.stage,
-					retryAfterSeconds: getRetryDelaySecondsFromError(summaryData.error),
 				});
 			}
 
@@ -346,7 +346,7 @@ export class SummaryGenerator {
 			 * state change of multiple data stores. So, the total number of data stores that are summarized should not
 			 * exceed the number of ops since last summary + number of data store whose reference state changed.
 			 */
-			if (!submitSummaryOptions.fullTree && !summaryData.forcedFullTree) {
+			if (!submitSummaryOptions.fullTree) {
 				const { summarizedDataStoreCount, gcStateUpdatedDataStoreCount = 0 } =
 					summaryData.summaryStats;
 				if (
@@ -368,11 +368,14 @@ export class SummaryGenerator {
 		} catch (error) {
 			return fail(
 				"submitSummaryFailure",
-				wrapError(error, (message) => new LoggingError(message)),
+				wrapError(
+					error,
+					(message) =>
+						new RetriableSummaryError(message, getRetryDelaySecondsFromError(error)),
+				),
 				undefined /* properties */,
 				{
 					stage: "unknown",
-					retryAfterSeconds: getRetryDelaySecondsFromError(error),
 				},
 			);
 		} finally {
@@ -393,10 +396,17 @@ export class SummaryGenerator {
 				cancellationToken,
 			);
 			if (waitBroadcastResult.result === "cancelled") {
-				return fail("disconnect");
+				const errorCode: SummarizeErrorCode = "disconnect";
+				return fail(errorCode, new RetriableSummaryError(getFailMessage(errorCode)));
 			}
 			if (waitBroadcastResult.result !== "done") {
-				return fail("summaryOpWaitTimeout");
+				// The summary op may not have been received within the timeout due to a transient error. So,
+				// fail with a retriable error to re-attempt the summary if possible.
+				const errorCode: SummarizeErrorCode = "summaryOpWaitTimeout";
+				return fail(
+					errorCode,
+					new RetriableSummaryError(getFailMessage(errorCode), 0 /* retryAfterSeconds */),
+				);
 			}
 			const summarizeOp = waitBroadcastResult.value;
 
@@ -422,10 +432,17 @@ export class SummaryGenerator {
 				cancellationToken,
 			);
 			if (waitAckNackResult.result === "cancelled") {
-				return fail("disconnect");
+				const errorCode: SummarizeErrorCode = "disconnect";
+				return fail(errorCode, new RetriableSummaryError(getFailMessage(errorCode)));
 			}
 			if (waitAckNackResult.result !== "done") {
-				return fail("summaryAckWaitTimeout");
+				const errorCode: SummarizeErrorCode = "summaryAckWaitTimeout";
+				// The summary ack may not have been received within the timeout due to a transient error. So,
+				// fail with a retriable error to re-attempt the summary if possible.
+				return fail(
+					errorCode,
+					new RetriableSummaryError(getFailMessage(errorCode), 0 /* retryAfterSeconds */),
+				);
 			}
 			const ackNackOp = waitAckNackResult.value;
 			this.pendingAckTimer.clear();
@@ -469,11 +486,16 @@ export class SummaryGenerator {
 				const errorMessage = summaryNack?.message;
 				const retryAfterSeconds = summaryNack?.retryAfter;
 
+				const errorCode: SummarizeErrorCode = "summaryNack";
+
 				// pre-0.58 error message prefix: summaryNack
-				const error = new LoggingError(`Received summaryNack`, {
+				const error = new RetriableSummaryError(
+					getFailMessage(errorCode),
 					retryAfterSeconds,
-					errorMessage,
-				});
+					{
+						errorMessage,
+					},
+				);
 
 				assert(
 					getRetryDelaySecondsFromError(error) === retryAfterSeconds,
@@ -481,11 +503,11 @@ export class SummaryGenerator {
 				);
 				// This will only set resultsBuilder.receivedSummaryAckOrNack, as other promises are already set.
 				return fail(
-					"summaryNack",
+					errorCode,
 					error,
 					{ ...summarizeTelemetryProps, nackRetryAfter: retryAfterSeconds },
 					undefined /* submitFailureResult */,
-					{ summaryNackOp: ackNackOp, ackNackDuration, retryAfterSeconds },
+					{ summaryNackOp: ackNackOp, ackNackDuration },
 				);
 			}
 		} finally {