@fluidframework/container-runtime 2.31.1 → 2.33.0-333010

package/src/summary/index.ts

@@ -3,31 +3,6 @@
  * Licensed under the MIT License.
  */
 
-export {
-	IOrderedClientCollection,
-	IOrderedClientElection,
-	ISerializedElection,
-	ITrackedClient,
-	OrderedClientCollection,
-	OrderedClientElection,
-} from "./orderedClientElection.js";
-export {
-	defaultMaxAttemptsForSubmitFailures,
-	RunningSummarizer,
-} from "./runningSummarizer.js";
-export {
-	ICancellableSummarizerController,
-	neverCancelledSummaryToken,
-	RunWhileConnectedCoordinator,
-} from "./runWhileConnectedCoordinator.js";
-export { Summarizer } from "./summarizer.js";
-export {
-	ISummarizerClientElection,
-	ISummarizerClientElectionEvents,
-	SummarizerClientElection,
-	summarizerClientType,
-} from "./summarizerClientElection.js";
-export { SummarizeHeuristicData, SummarizeHeuristicRunner } from "./summarizerHeuristics.js";
 export {
 	createRootSummarizerNode,
 	createRootSummarizerNodeWithGC,
@@ -36,6 +11,7 @@ export {
 	IRootSummarizerNodeWithGC,
 } from "./summarizerNode/index.js";
 export {
+	summarizerClientType,
 	IConnectableRuntime,
 	IGeneratedSummaryStats,
 	IRefreshSummaryAckOptions,
@@ -43,19 +19,14 @@ export {
 	ISummarizeAttempt,
 	ISummarizeHeuristicData,
 	ISummarizer,
-	ISummarizeResults,
 	ISummarizerInternalsProvider,
 	ISummarizerRuntime,
 	ISummaryCancellationToken,
 	SubmitSummaryResult,
-	EnqueueSummarizeResult,
-	IAckSummaryResult,
 	IBaseSummarizeResult,
-	IBroadcastSummaryResult,
 	ICancellationToken,
 	IEnqueueSummarizeOptions,
 	IGenerateSummaryTreeResult,
-	INackSummaryResult,
 	IOnDemandSummarizeOptions,
 	ISubmitSummaryOpResult,
 	ISummarizeOptions,
@@ -71,6 +42,14 @@ export {
 	type ISummaryConfigurationHeuristics,
 	type ISummaryBaseConfiguration,
 } from "./summarizerTypes.js";
+export {
+	IOrderedClientCollection,
+	IOrderedClientElection,
+	ISerializedElection,
+	ITrackedClient,
+	OrderedClientCollection,
+	OrderedClientElection,
+} from "./orderedClientElection.js";
 export {
 	IAckedSummary,
 	ISummaryCollectionOpEvents,
@@ -83,6 +62,11 @@ export {
 	OpActionEventListener,
 	OpActionEventName,
 } from "./summaryCollection.js";
+export {
+	ISummarizerClientElection,
+	ISummarizerClientElectionEvents,
+	SummarizerClientElection,
+} from "./summarizerClientElection.js";
 export {
 	aliasBlobName,
 	chunksBlobName,
@@ -125,7 +109,11 @@ export {
 	IDocumentSchemaChangeMessage,
 	IDocumentSchemaFeatures,
 } from "./documentSchema.js";
-export { getFailMessage, RetriableSummaryError, SummarizeReason } from "./summaryGenerator.js";
+export {
+	getFailMessage,
+	RetriableSummaryError,
+	SummarizeReason,
+} from "./summarizerUtils.js";
 export {
 	IConnectedEvents,
 	IConnectedState,
@@ -133,3 +121,19 @@ export {
 	SummaryManager,
 	SummaryManagerState,
 } from "./summaryManager.js";
+export {
+	defaultMaxAttempts,
+	defaultMaxAttemptsForSubmitFailures,
+	ICancellableSummarizerController,
+	neverCancelledSummaryToken,
+	RunWhileConnectedCoordinator,
+	Summarizer,
+	IBroadcastSummaryResult,
+	ISummarizeResults,
+	EnqueueSummarizeResult,
+	IAckSummaryResult,
+	INackSummaryResult,
+	RunningSummarizer,
+	SummarizeHeuristicData,
+	SummarizeHeuristicRunner,
+} from "./summaryDelayLoadedModule/index.js";

package/src/summary/orderedClientElection.ts

@@ -16,7 +16,7 @@ import {
 	createChildLogger,
 } from "@fluidframework/telemetry-utils/internal";
 
-import { summarizerClientType } from "./summarizerClientElection.js";
+import { summarizerClientType } from "./index.js";
 
 // helper types for recursive readonly.
 // eslint-disable-next-line @typescript-eslint/ban-types

package/src/summary/summarizerClientElection.ts

@@ -14,10 +14,9 @@ import {
 	ISerializedElection,
 	ITrackedClient,
 } from "./orderedClientElection.js";
+import { summarizerClientType } from "./summarizerTypes.js";
 import { ISummaryCollectionOpEvents } from "./summaryCollection.js";
 
-export const summarizerClientType = "summarizer";
-
 export interface ISummarizerClientElectionEvents extends IEvent {
 	(event: "electedSummarizerChanged", handler: () => void): void;
 }

package/src/summary/summarizerTypes.ts

@@ -27,12 +27,13 @@ import {
 	ITelemetryLoggerPropertyBag,
 } from "@fluidframework/telemetry-utils/internal";
 
-import {
-	ISummaryAckMessage,
-	ISummaryNackMessage,
-	ISummaryOpMessage,
-} from "./summaryCollection.js";
-import { SummarizeReason } from "./summaryGenerator.js";
+import type { SummarizeReason } from "./summarizerUtils.js";
+import type {
+	EnqueueSummarizeResult,
+	ISummarizeResults,
+} from "./summaryDelayLoadedModule/index.js";
+
+export const summarizerClientType = "summarizer";
 
 /**
  * Similar to AbortSignal, but using promise instead of events
@@ -359,33 +360,6 @@ export interface SubmitSummaryFailureData {
 	stage: SummaryStage;
 }
 
-/**
- * @legacy
- * @alpha
- */
-export interface IBroadcastSummaryResult {
-	readonly summarizeOp: ISummaryOpMessage;
-	readonly broadcastDuration: number;
-}
-
-/**
- * @legacy
- * @alpha
- */
-export interface IAckSummaryResult {
-	readonly summaryAckOp: ISummaryAckMessage;
-	readonly ackNackDuration: number;
-}
-
-/**
- * @legacy
- * @alpha
- */
-export interface INackSummaryResult {
-	readonly summaryNackOp: ISummaryNackMessage;
-	readonly ackNackDuration: number;
-}
-
 /**
  * @legacy
  * @alpha
@@ -402,64 +376,6 @@ export type SummarizeResultPart<TSuccess, TFailure = undefined> =
 			error: IRetriableFailureError;
 	  };
 
-/**
- * @legacy
- * @alpha
- */
-export interface ISummarizeResults {
-	/**
-	 * Resolves when we generate, upload, and submit the summary.
-	 */
-	readonly summarySubmitted: Promise<
-		SummarizeResultPart<SubmitSummaryResult, SubmitSummaryFailureData>
-	>;
-	/**
-	 * Resolves when we observe our summarize op broadcast.
-	 */
-	readonly summaryOpBroadcasted: Promise<SummarizeResultPart<IBroadcastSummaryResult>>;
-	/**
-	 * Resolves when we receive a summaryAck or summaryNack.
-	 */
-	readonly receivedSummaryAckOrNack: Promise<
-		SummarizeResultPart<IAckSummaryResult, INackSummaryResult>
-	>;
-}
-
-/**
- * @legacy
- * @alpha
- */
-export type EnqueueSummarizeResult =
-	| (ISummarizeResults & {
-			/**
-			 * Indicates that another summarize attempt is not already enqueued,
-			 * and this attempt has been enqueued.
-			 */
-			readonly alreadyEnqueued?: undefined;
-	  })
-	| (ISummarizeResults & {
-			/**
-			 * Indicates that another summarize attempt was already enqueued.
-			 */
-			readonly alreadyEnqueued: true;
-			/**
-			 * Indicates that the other enqueued summarize attempt was abandoned,
-			 * and this attempt has been enqueued enqueued.
-			 */
-			readonly overridden: true;
-	  })
-	| {
-			/**
-			 * Indicates that another summarize attempt was already enqueued.
-			 */
-			readonly alreadyEnqueued: true;
-			/**
-			 * Indicates that the other enqueued summarize attempt remains enqueued,
-			 * and this attempt has not been enqueued.
-			 */
-			readonly overridden?: undefined;
-	  };
-
 /**
  * @legacy
  * @alpha

package/src/summary/summarizerUtils.ts

@@ -0,0 +1,132 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { SummarizerStopReason } from "@fluidframework/container-runtime-definitions/internal";
+import { ITelemetryBaseProperties } from "@fluidframework/core-interfaces";
+import { IPromiseTimerResult } from "@fluidframework/core-utils/internal";
+import { LoggingError } from "@fluidframework/telemetry-utils/internal";
+
+import { ISummaryCancellationToken, type IRetriableFailureError } from "./summarizerTypes.js";
+
+export type raceTimerResult<T> =
+	| { result: "done"; value: T }
+	| { result: IPromiseTimerResult["timerResult"] }
+	| { result: "cancelled" };
+
+/**
+ * Wait for a promise or PromiseTimer to elapse.
+ */
+export async function raceTimer<T>(
+	promise: Promise<T>,
+	timer: Promise<IPromiseTimerResult>,
+
+	cancellationToken?: ISummaryCancellationToken,
+): Promise<raceTimerResult<T>> {
+	const promises: Promise<raceTimerResult<T>>[] = [
+		promise.then((value) => ({ result: "done", value }) as const),
+		timer.then(({ timerResult: result }) => ({ result }) as const),
+	];
+	if (cancellationToken !== undefined) {
+		promises.push(
+			cancellationToken.waitCancelled.then(() => ({ result: "cancelled" }) as const),
+		);
+	}
+	return Promise.race(promises);
+}
+
+/**
+ * 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, otherwise `false`.
+ */
+export function stopReasonCanRunLastSummary(stopReason: SummarizerStopReason): boolean {
+	return stopReason === "parentNotConnected";
+}
+
+export type SummarizeReason =
+	/**
+	 * Attempt to summarize after idle timeout has elapsed.
+	 * Idle timer restarts whenever an op is received. So this
+	 * triggers only after some amount of time has passed with
+	 * no ops being received.
+	 */
+	| "idle"
+	/**
+	 * Attempt to summarize after a maximum time since last
+	 * successful summary has passed. This measures time since
+	 * last summary ack op was processed.
+	 */
+	| "maxTime"
+	/**
+	 * Attempt to summarize after a maximum number of ops have
+	 * passed since the last successful summary. This compares
+	 * op sequence numbers with the reference sequence number
+	 * of the summarize op corresponding to the last summary
+	 * ack op.
+	 */
+	| "maxOps"
+	/**
+	 * Special case to attempt to summarize one last time before the
+	 * summarizer client closes itself. This is to prevent cases where
+	 * the summarizer client never gets a chance to summarize, because
+	 * there are too many outstanding ops and/or parent client cannot
+	 * stay connected long enough for summarizer client to catch up.
+	 */
+	| "lastSummary"
+	/**
+	 * On-demand summary requested with specified reason.
+	 */
+	| `onDemand;${string}`
+	/**
+	 * Enqueue summarize attempt with specified reason.
+	 */
+	| `enqueue;${string}`;
+
+const summarizeErrors = {
+	/**
+	 * Error encountered while generating the summary tree, uploading
+	 * it to storage, or submitting the op. It could be a result of
+	 * the client becoming disconnected while generating or an actual error.
+	 */
+	submitSummaryFailure: "Error while generating, uploading, or submitting summary",
+	/**
+	 * The summaryAckWaitTimeout time has elapsed before receiving the summarize op
+	 * sent by this summarize attempt. It is expected to be broadcast quickly.
+	 */
+	summaryOpWaitTimeout: "Timeout while waiting for summarize op broadcast",
+	/**
+	 * The summaryAckWaitTimeout time has elapsed before receiving either a
+	 * summaryAck or summaryNack op from the server in response to this
+	 * summarize attempt. It is expected that the server should respond.
+	 */
+	summaryAckWaitTimeout: "Timeout while waiting for summaryAck/summaryNack op",
+	/**
+	 * The server responded with a summaryNack op, thus rejecting this
+	 * summarize attempt.
+	 */
+	summaryNack: "Server rejected summary via summaryNack op",
+
+	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: SummarizeErrorCode): string =>
+	`${errorCode}: ${summarizeErrors[errorCode]}`;
+
+/**
+ * Errors type for errors hit during summary that may be retriable.
+ */
+export class RetriableSummaryError extends LoggingError implements IRetriableFailureError {
+	constructor(
+		message: string,
+		public readonly retryAfterSeconds?: number,
+		props?: ITelemetryBaseProperties,
+	) {
+		super(message, props);
+	}
+}

package/src/summary/summaryDelayLoadedModule/index.ts

@@ -0,0 +1,28 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+	defaultMaxAttempts,
+	defaultMaxAttemptsForSubmitFailures,
+	Summarizer,
+} from "./summarizer.js";
+export {
+	ICancellableSummarizerController,
+	neverCancelledSummaryToken,
+	RunWhileConnectedCoordinator,
+} from "./runWhileConnectedCoordinator.js";
+
+export {
+	EnqueueSummarizeResult,
+	IAckSummaryResult,
+	INackSummaryResult,
+	IBroadcastSummaryResult,
+	ISummarizeResults,
+} from "./summaryResultTypes.js";
+export { RunningSummarizer } from "./runningSummarizer.js";
+export {
+	SummarizeHeuristicData,
+	SummarizeHeuristicRunner,
+} from "./summarizerHeuristics.js";

package/src/summary/{runWhileConnectedCoordinator.ts → summaryDelayLoadedModule/runWhileConnectedCoordinator.ts}

@@ -6,7 +6,7 @@
 import type { SummarizerStopReason } from "@fluidframework/container-runtime-definitions/internal";
 import { assert, Deferred } from "@fluidframework/core-utils/internal";
 
-import { IConnectableRuntime, ISummaryCancellationToken } from "./summarizerTypes.js";
+import { IConnectableRuntime, ISummaryCancellationToken } from "../summarizerTypes.js";
 
 /**
  * Similar to AbortController, but using promise instead of events

package/src/summary/{runningSummarizer.ts → summaryDelayLoadedModule/runningSummarizer.ts}

@@ -26,52 +26,37 @@ import {
 	type ITelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 
-import { opSize } from "../opProperties.js";
-
-import { SummarizeHeuristicRunner } from "./summarizerHeuristics.js";
+import { opSize } from "../../opProperties.js";
 import type {
-	ISummaryConfiguration,
-	EnqueueSummarizeResult,
 	IEnqueueSummarizeOptions,
 	IOnDemandSummarizeOptions,
 	IRefreshSummaryAckOptions,
+	IRetriableFailureError,
 	ISubmitSummaryOptions,
 	ISummarizeHeuristicData,
 	ISummarizeHeuristicRunner,
 	ISummarizeOptions,
-	ISummarizeResults,
+	ISummarizerRuntime,
 	ISummarizeRunnerTelemetry,
 	ISummarizeTelemetryProperties,
-	ISummarizerRuntime,
 	ISummaryCancellationToken,
+	ISummaryConfiguration,
 	SubmitSummaryResult,
-	IRetriableFailureError,
-} from "./summarizerTypes.js";
+} from "../summarizerTypes.js";
+import { raceTimer, RetriableSummaryError, type SummarizeReason } from "../summarizerUtils.js";
 import {
 	IAckedSummary,
 	IClientSummaryWatcher,
 	SummaryCollection,
-} from "./summaryCollection.js";
-import {
-	RetriableSummaryError,
-	SummarizeReason,
-	SummarizeResultBuilder,
-	SummaryGenerator,
-	raceTimer,
-} from "./summaryGenerator.js";
+} from "../summaryCollection.js";
 
-const maxSummarizeAckWaitTime = 10 * 60 * 1000; // 10 minutes
+import { defaultMaxAttempts, defaultMaxAttemptsForSubmitFailures } from "./summarizer.js";
+import { SummarizeHeuristicRunner } from "./summarizerHeuristics.js";
+import { SummaryGenerator } from "./summaryGenerator.js";
+import { SummarizeResultBuilder } from "./summaryResultBuilder.js";
+import type { EnqueueSummarizeResult, ISummarizeResults } from "./summaryResultTypes.js";
 
-/**
- * The maximum number of summarization attempts that will be done by default in case of failures
- * that can be retried.
- */
-export const defaultMaxAttempts = 2;
-/**
- * The default value for maximum number of summarization attempts that will be done for summarization failures where
- * submit fails and the failure can be retried.
- */
-export const defaultMaxAttemptsForSubmitFailures = 5;
+const maxSummarizeAckWaitTime = 10 * 60 * 1000; // 10 minutes
 
 /**
  * An instance of RunningSummarizer manages the heuristics for summarizing.

package/src/summary/{summarizer.ts → summaryDelayLoadedModule/summarizer.ts}

@@ -19,25 +19,36 @@ import {
 	wrapErrorAndLog,
 } from "@fluidframework/telemetry-utils/internal";
 
-import { ICancellableSummarizerController } from "./runWhileConnectedCoordinator.js";
-import { RunningSummarizer } from "./runningSummarizer.js";
-import { SummarizeHeuristicData } from "./summarizerHeuristics.js";
 import {
-	EnqueueSummarizeResult,
 	IConnectableRuntime,
 	IEnqueueSummarizeOptions,
 	IOnDemandSummarizeOptions,
 	ISummarizeHeuristicData,
-	ISummarizeResults,
 	ISummarizer,
 	ISummarizerInternalsProvider,
 	ISummarizerRuntime,
 	ISummarizingWarning,
 	type IRetriableFailureError,
 	type ISummaryConfiguration,
-} from "./summarizerTypes.js";
-import { SummaryCollection } from "./summaryCollection.js";
-import { SummarizeResultBuilder } from "./summaryGenerator.js";
+} from "../summarizerTypes.js";
+import { SummaryCollection } from "../summaryCollection.js";
+
+import { ICancellableSummarizerController } from "./runWhileConnectedCoordinator.js";
+import { RunningSummarizer } from "./runningSummarizer.js";
+import { SummarizeHeuristicData } from "./summarizerHeuristics.js";
+import { SummarizeResultBuilder } from "./summaryResultBuilder.js";
+import type { EnqueueSummarizeResult, ISummarizeResults } from "./summaryResultTypes.js";
+
+/**
+ * The maximum number of summarization attempts that will be done by default in case of failures
+ * that can be retried.
+ */
+export const defaultMaxAttempts = 2;
+/**
+ * The default value for maximum number of summarization attempts that will be done for summarization failures where
+ * submit fails and the failure can be retried.
+ */
+export const defaultMaxAttemptsForSubmitFailures = 5;
 
 export class SummarizingWarning
 	extends LoggingError

package/src/summary/{summarizerHeuristics.ts → summaryDelayLoadedModule/summarizerHeuristics.ts}

@@ -6,14 +6,14 @@
 import { Timer } from "@fluidframework/core-utils/internal";
 import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 
-import type { ISummaryConfigurationHeuristics } from "./summarizerTypes.js";
+import type { ISummaryConfigurationHeuristics } from "../summarizerTypes.js";
 import {
 	ISummarizeAttempt,
 	ISummarizeHeuristicData,
 	ISummarizeHeuristicRunner,
 	ISummaryHeuristicStrategy,
-} from "./summarizerTypes.js";
-import { SummarizeReason } from "./summaryGenerator.js";
+} from "../summarizerTypes.js";
+import { SummarizeReason } from "../summarizerUtils.js";
 
 /**
  * Simple implementation of class for tracking summarize heuristic data.