@fluidframework/container-runtime 2.23.0-325054 → 2.30.0

package/src/summary/summarizerTypes.ts

@@ -27,8 +27,6 @@ import {
 	ITelemetryLoggerPropertyBag,
 } from "@fluidframework/telemetry-utils/internal";
 
-import { ISummaryConfigurationHeuristics } from "../containerRuntime.js";
-
 import {
 	ISummaryAckMessage,
 	ISummaryNackMessage,
@@ -39,9 +37,7 @@ import { SummarizeReason } from "./summaryGenerator.js";
 /**
  * Similar to AbortSignal, but using promise instead of events
  * @param T - cancellation reason type
- * @legacy
- * @alpha
- * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
+ * @internal
  */
 export interface ICancellationToken<T> {
 	/**
@@ -57,17 +53,13 @@ export interface ICancellationToken<T> {
 
 /**
  * Similar to AbortSignal, but using promise instead of events
- * @legacy
- * @alpha
- * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
+ * @internal
  */
 export type ISummaryCancellationToken = ICancellationToken<SummarizerStopReason>;
 
 /**
  * Data required to update internal tracking state after receiving a Summary Ack.
- * @legacy
- * @alpha
- * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
+ * @internal
  */
 export interface IRefreshSummaryAckOptions {
 	/**
@@ -89,9 +81,7 @@ export interface IRefreshSummaryAckOptions {
 }
 
 /**
- * @legacy
- * @alpha
- * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
+ * @internal
  */
 export interface ISummarizerInternalsProvider {
 	/**
@@ -114,9 +104,7 @@ export interface ISummarizingWarning extends ContainerWarning {
 }
 
 /**
- * @legacy
- * @alpha
- * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
+ * @internal
  */
 export interface IConnectableRuntime {
 	readonly disposed: boolean;
@@ -126,9 +114,7 @@ export interface IConnectableRuntime {
 }
 
 /**
- * @legacy
- * @alpha
- * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
+ * @internal
  */
 export interface ISummarizerRuntime extends IConnectableRuntime {
 	readonly baseLogger: ITelemetryBaseLogger;
@@ -162,9 +148,7 @@ export interface ISummarizeOptions {
 }
 
 /**
- * @legacy
- * @alpha
- * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
+ * @internal
  */
 export interface ISubmitSummaryOptions extends ISummarizeOptions {
 	/**
@@ -773,3 +757,115 @@ export interface ISummarizeRunnerTelemetry extends ITelemetryLoggerPropertyBag {
 	 */
 	summarizerSuccessfulAttempts: () => number;
 }
+
+/**
+ * @legacy
+ * @alpha
+ */
+export interface ISummaryBaseConfiguration {
+	/**
+	 * Delay before first attempt to spawn summarizing container.
+	 */
+	initialSummarizerDelayMs: number;
+
+	/**
+	 * Defines the maximum allowed time to wait for a pending summary ack.
+	 * The maximum amount of time client will wait for a summarize is the minimum of
+	 * maxSummarizeAckWaitTime (currently 3 * 60 * 1000) and maxAckWaitTime.
+	 */
+	maxAckWaitTime: number;
+	/**
+	 * Defines the maximum number of Ops in between Summaries that can be
+	 * allowed before forcibly electing a new summarizer client.
+	 */
+	maxOpsSinceLastSummary: number;
+}
+
+/**
+ * @legacy
+ * @alpha
+ */
+export interface ISummaryConfigurationHeuristics extends ISummaryBaseConfiguration {
+	state: "enabled";
+	/**
+	 * Defines the maximum allowed time, since the last received Ack, before running the summary
+	 * with reason maxTime.
+	 * For example, say we receive ops one by one just before the idle time is triggered.
+	 * In this case, we still want to run a summary since it's been a while since the last summary.
+	 */
+	maxTime: number;
+	/**
+	 * Defines the maximum number of Ops, since the last received Ack, that can be allowed
+	 * before running the summary with reason maxOps.
+	 */
+	maxOps: number;
+	/**
+	 * Defines the minimum number of Ops, since the last received Ack, that can be allowed
+	 * before running the last summary.
+	 */
+	minOpsForLastSummaryAttempt: number;
+	/**
+	 * Defines the lower boundary for the allowed time in between summarizations.
+	 * Pairs with maxIdleTime to form a range.
+	 * For example, if we only receive 1 op, we don't want to have the same idle time as say 100 ops.
+	 * Based on the boundaries we set in minIdleTime and maxIdleTime, the idle time will change
+	 * linearly depending on the number of ops we receive.
+	 */
+	minIdleTime: number;
+	/**
+	 * Defines the upper boundary for the allowed time in between summarizations.
+	 * Pairs with minIdleTime to form a range.
+	 * For example, if we only receive 1 op, we don't want to have the same idle time as say 100 ops.
+	 * Based on the boundaries we set in minIdleTime and maxIdleTime, the idle time will change
+	 * linearly depending on the number of ops we receive.
+	 */
+	maxIdleTime: number;
+	/**
+	 * Runtime op weight to use in heuristic summarizing.
+	 * This number is a multiplier on the number of runtime ops we process when running summarize heuristics.
+	 * For example: (multiplier) * (number of runtime ops) = weighted number of runtime ops
+	 */
+	runtimeOpWeight: number;
+	/**
+	 * Non-runtime op weight to use in heuristic summarizing
+	 * This number is a multiplier on the number of non-runtime ops we process when running summarize heuristics.
+	 * For example: (multiplier) * (number of non-runtime ops) = weighted number of non-runtime ops
+	 */
+	nonRuntimeOpWeight: number;
+
+	/**
+	 * Number of ops since last summary needed before a non-runtime op can trigger running summary heuristics.
+	 *
+	 * Note: Any runtime ops sent before the threshold is reached will trigger heuristics normally.
+	 * This threshold ONLY applies to non-runtime ops triggering summaries.
+	 *
+	 * For example: Say the threshold is 20. Sending 19 non-runtime ops will not trigger any heuristic checks.
+	 * Sending the 20th non-runtime op will trigger the heuristic checks for summarizing.
+	 */
+	nonRuntimeHeuristicThreshold?: number;
+}
+
+/**
+ * @legacy
+ * @alpha
+ */
+export interface ISummaryConfigurationDisableSummarizer {
+	state: "disabled";
+}
+
+/**
+ * @legacy
+ * @alpha
+ */
+export interface ISummaryConfigurationDisableHeuristics extends ISummaryBaseConfiguration {
+	state: "disableHeuristics";
+}
+
+/**
+ * @legacy
+ * @alpha
+ */
+export type ISummaryConfiguration =
+	| ISummaryConfigurationDisableSummarizer
+	| ISummaryConfigurationDisableHeuristics
+	| ISummaryConfigurationHeuristics;

package/src/summary/summaryFormat.ts

@@ -18,10 +18,8 @@ import {
 } from "@fluidframework/runtime-definitions/internal";
 
 import { blobsTreeName } from "../blobManager/index.js";
-// eslint-disable-next-line import/no-deprecated
 import { IGCMetadata } from "../gc/index.js";
 
-// eslint-disable-next-line import/no-deprecated
 import { IDocumentSchema } from "./documentSchema.js";
 
 /**
@@ -127,11 +125,9 @@ export function hasIsolatedChannels(attributes: ReadFluidDataStoreAttributes): b
 }
 
 /**
- * @legacy
- * @alpha
- * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
+ * @internal
  */
-// eslint-disable-next-line import/no-deprecated
+
 export interface IContainerRuntimeMetadata extends ICreateContainerMetadata, IGCMetadata {
 	readonly summaryFormatVersion: 1;
 	/**
@@ -155,14 +151,11 @@ export interface IContainerRuntimeMetadata extends ICreateContainerMetadata, IGC
 	 */
 	readonly telemetryDocumentId?: string;
 
-	// eslint-disable-next-line import/no-deprecated
 	readonly documentSchema?: IDocumentSchema;
 }
 
 /**
- * @legacy
- * @alpha
- * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
+ * @internal
  */
 export interface ICreateContainerMetadata {
 	/**
@@ -177,9 +170,7 @@ export interface ICreateContainerMetadata {
 
 /**
  * The properties of an ISequencedDocumentMessage to be stored in the metadata blob in summary.
- * @legacy
- * @alpha
- * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
+ * @internal
  */
 export type ISummaryMetadataMessage = Pick<
 	ISequencedDocumentMessage,

package/src/summary/summaryGenerator.ts

@@ -25,13 +25,10 @@ import {
 	IAckSummaryResult,
 	IBroadcastSummaryResult,
 	INackSummaryResult,
-	// eslint-disable-next-line import/no-deprecated
 	IRefreshSummaryAckOptions,
-	// eslint-disable-next-line import/no-deprecated
 	ISubmitSummaryOptions,
 	ISummarizeHeuristicData,
 	ISummarizeResults,
-	// eslint-disable-next-line import/no-deprecated
 	ISummaryCancellationToken,
 	SubmitSummaryFailureData,
 	SubmitSummaryResult,
@@ -52,7 +49,7 @@ export type raceTimerResult<T> =
 export async function raceTimer<T>(
 	promise: Promise<T>,
 	timer: Promise<IPromiseTimerResult>,
-	// eslint-disable-next-line import/no-deprecated
+
 	cancellationToken?: ISummaryCancellationToken,
 ): Promise<raceTimerResult<T>> {
 	const promises: Promise<raceTimerResult<T>>[] = [
@@ -215,12 +212,10 @@ export class SummaryGenerator {
 		private readonly pendingAckTimer: IPromiseTimer,
 		private readonly heuristicData: ISummarizeHeuristicData,
 		private readonly submitSummaryCallback: (
-			// eslint-disable-next-line import/no-deprecated
 			options: ISubmitSummaryOptions,
 		) => Promise<SubmitSummaryResult>,
 		private readonly successfulSummaryCallback: () => void,
 		private readonly refreshLatestSummaryCallback: (
-			// eslint-disable-next-line import/no-deprecated
 			options: IRefreshSummaryAckOptions,
 		) => Promise<void>,
 		private readonly summaryWatcher: Pick<IClientSummaryWatcher, "watchSummary">,
@@ -238,7 +233,6 @@ export class SummaryGenerator {
 	 * @param resultsBuilder - optional, result builder to use to build pass or fail result.
 	 */
 	public summarize(
-		// eslint-disable-next-line import/no-deprecated
 		summaryOptions: ISubmitSummaryOptions,
 		resultsBuilder = new SummarizeResultBuilder(),
 	): ISummarizeResults {
@@ -254,7 +248,6 @@ export class SummaryGenerator {
 	}
 
 	private async summarizeCore(
-		// eslint-disable-next-line import/no-deprecated
 		submitSummaryOptions: ISubmitSummaryOptions,
 		resultsBuilder: SummarizeResultBuilder,
 	): Promise<void> {

package/src/summary/summaryHelpers.ts

@@ -0,0 +1,118 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { type ILoader, LoaderHeader } from "@fluidframework/container-definitions/internal";
+import type { FluidObject, IRequest, IResponse } from "@fluidframework/core-interfaces";
+import { DriverHeader } from "@fluidframework/driver-definitions/internal";
+import { responseToException } from "@fluidframework/runtime-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import { summarizerClientType } from "./summarizerClientElection.js";
+import type {
+	ISummarizer,
+	ISummaryConfiguration,
+	ISummaryConfigurationDisableSummarizer,
+	ISummaryConfigurationHeuristics,
+} from "./summarizerTypes.js";
+
+export const summarizerRequestUrl = "_summarizer";
+
+export function isSummariesDisabled(
+	config: ISummaryConfiguration,
+): config is ISummaryConfigurationDisableSummarizer {
+	return config.state === "disabled";
+}
+
+/**
+ * @legacy
+ * @alpha
+ */
+export const DefaultSummaryConfiguration: ISummaryConfiguration = {
+	state: "enabled",
+
+	minIdleTime: 0,
+
+	maxIdleTime: 30 * 1000, // 30 secs.
+
+	maxTime: 60 * 1000, // 1 min.
+
+	maxOps: 100, // Summarize if 100 weighted ops received since last snapshot.
+
+	minOpsForLastSummaryAttempt: 10,
+
+	maxAckWaitTime: 3 * 60 * 1000, // 3 mins.
+
+	maxOpsSinceLastSummary: 7000,
+
+	initialSummarizerDelayMs: 5 * 1000, // 5 secs.
+
+	nonRuntimeOpWeight: 0.1,
+
+	runtimeOpWeight: 1,
+
+	nonRuntimeHeuristicThreshold: 20,
+};
+
+/**
+ * Returns a function that will create and retrieve a Summarizer.
+ */
+export function formCreateSummarizerFn(loader: ILoader): () => Promise<ISummarizer> {
+	return async () => {
+		const request: IRequest = {
+			headers: {
+				[LoaderHeader.cache]: false,
+				[LoaderHeader.clientDetails]: {
+					capabilities: { interactive: false },
+					type: summarizerClientType,
+				},
+				[DriverHeader.summarizingClient]: true,
+				[LoaderHeader.reconnect]: false,
+			},
+			url: `/${summarizerRequestUrl}`,
+		};
+
+		const resolvedContainer = await loader.resolve(request);
+		let fluidObject: FluidObject<ISummarizer> | undefined;
+
+		// Older containers may not have the "getEntryPoint" API
+		// ! This check will need to stay until LTS of loader moves past 2.0.0-internal.7.0.0
+		if (resolvedContainer.getEntryPoint === undefined) {
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any
+			const response = (await (resolvedContainer as any).request({
+				url: `/${summarizerRequestUrl}`,
+			})) as IResponse;
+			if (response.status !== 200 || response.mimeType !== "fluid/object") {
+				throw responseToException(response, request);
+			}
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+			fluidObject = response.value;
+		} else {
+			fluidObject = await resolvedContainer.getEntryPoint();
+		}
+
+		if (fluidObject?.ISummarizer === undefined) {
+			throw new UsageError("Fluid object does not implement ISummarizer");
+		}
+		return fluidObject.ISummarizer;
+	};
+}
+
+export function validateSummaryHeuristicConfiguration(
+	configuration: ISummaryConfigurationHeuristics,
+): void {
+	// eslint-disable-next-line no-restricted-syntax
+	for (const prop in configuration) {
+		if (typeof configuration[prop] === "number" && configuration[prop] < 0) {
+			throw new UsageError(
+				`Summary heuristic configuration property "${prop}" cannot be less than 0`,
+			);
+		}
+	}
+	if (configuration.minIdleTime > configuration.maxIdleTime) {
+		throw new UsageError(
+			`"minIdleTime" [${configuration.minIdleTime}] cannot be greater than "maxIdleTime" [${configuration.maxIdleTime}]`,
+		);
+	}
+}

package/src/summary/summaryManager.ts

@@ -24,7 +24,6 @@ import {
 
 import { IThrottler } from "../throttler.js";
 
-// eslint-disable-next-line import/no-deprecated
 import { Summarizer } from "./summarizer.js";
 import { ISummarizerClientElection } from "./summarizerClientElection.js";
 import {
@@ -285,7 +284,6 @@ export class SummaryManager
 					// which would happen when we have a high enough number of unsummarized ops.
 					if (
 						startWithInitialDelay ||
-						// eslint-disable-next-line import/no-deprecated
 						!Summarizer.stopReasonCanRunLastSummary(shouldSummarizeState.stopReason)
 					) {
 						this.state = SummaryManagerState.Starting;