On demand summarizer for on demand summaries (#25394)

## Description 

This change introduces new public API
`loadSummarizerContainerAndMakeSummary` to load a summarizer client
container to produce an on-demand summary before disposing itself.

We also add new `ISummaryConfigurationWithSummaryOnRequest` summary
config that we check during summarizer initialzation to turn of client
election and internal heurstics.

Author: WillieHabi

packages/framework/aqueduct/package.json

@@ -154,7 +154,14 @@
 		"typescript": "~5.4.5"
 	},
 	"typeValidation": {
-		"broken": {},
+		"broken": {
+			"Interface_BaseContainerRuntimeFactoryProps": {
+				"backCompat": false
+			},
+			"Interface_ContainerRuntimeFactoryWithDefaultDataStoreProps": {
+				"backCompat": false
+			}
+		},
 		"entrypoint": "legacy"
 	}
 }

packages/framework/aqueduct/src/test/types/validateAqueductPrevious.generated.ts

@@ -247,6 +247,7 @@ declare type old_as_current_for_Interface_BaseContainerRuntimeFactoryProps = req
  * typeValidation.broken:
  * "Interface_BaseContainerRuntimeFactoryProps": {"backCompat": false}
  */
+// @ts-expect-error compatibility expected to be broken
 declare type current_as_old_for_Interface_BaseContainerRuntimeFactoryProps = requireAssignableTo<TypeOnly<current.BaseContainerRuntimeFactoryProps>, TypeOnly<old.BaseContainerRuntimeFactoryProps>>
 
 /*
@@ -265,6 +266,7 @@ declare type old_as_current_for_Interface_ContainerRuntimeFactoryWithDefaultData
  * typeValidation.broken:
  * "Interface_ContainerRuntimeFactoryWithDefaultDataStoreProps": {"backCompat": false}
  */
+// @ts-expect-error compatibility expected to be broken
 declare type current_as_old_for_Interface_ContainerRuntimeFactoryWithDefaultDataStoreProps = requireAssignableTo<TypeOnly<current.ContainerRuntimeFactoryWithDefaultDataStoreProps>, TypeOnly<old.ContainerRuntimeFactoryWithDefaultDataStoreProps>>
 
 /*

packages/loader/container-loader/api-report/container-loader.legacy.alpha.api.md

@@ -108,6 +108,9 @@ export interface ILoadFrozenContainerFromPendingStateProps extends ILoadExisting
     readonly pendingLocalState: string;
 }
 
+// @alpha @legacy
+export type ILoadSummarizerContainerProps = Omit<ILoadExistingContainerProps, "pendingLocalState">;
+
 // @beta @legacy
 export interface IParsedUrl {
     id: string;
@@ -178,6 +181,28 @@ export function loadExistingContainer(loadExistingContainerProps: ILoadExistingC
 // @alpha @legacy
 export function loadFrozenContainerFromPendingState(props: ILoadFrozenContainerFromPendingStateProps): Promise<IContainer>;
 
+// @alpha @legacy
+export function loadSummarizerContainerAndMakeSummary(loadSummarizerContainerProps: ILoadSummarizerContainerProps): Promise<LoadSummarizerSummaryResult>;
+
+// @alpha @legacy
+export type LoadSummarizerSummaryResult = {
+    readonly success: true;
+    readonly summaryResults: OnDemandSummaryResults;
+} | {
+    readonly success: false;
+    readonly error: IErrorBase;
+};
+
+// @alpha @legacy
+export interface OnDemandSummaryResults {
+    readonly summaryInfo: {
+        readonly stage?: SummaryStage;
+        readonly handle?: string;
+    };
+    readonly summaryOpBroadcasted: boolean;
+    readonly summarySubmitted: boolean;
+}
+
 // @beta @legacy
 export type ProtocolHandlerBuilder = (attributes: IDocumentAttributes, snapshot: IQuorumSnapshot, sendProposal: (key: string, value: any) => number) => IProtocolHandler;
 
@@ -196,6 +221,9 @@ export function rehydrateDetachedContainer(rehydrateDetachedContainerProps: IReh
 // @beta @legacy
 export function resolveWithLocationRedirectionHandling<T>(api: (request: IRequest) => Promise<T>, request: IRequest, urlResolver: IUrlResolver, logger?: ITelemetryBaseLogger): Promise<T>;
 
+// @alpha @legacy
+export type SummaryStage = "base" | "generate" | "upload" | "submit" | "unknown";
+
 // @beta @legacy
 export function tryParseCompatibleResolvedUrl(url: string): IParsedUrl | undefined;
 

packages/loader/container-loader/src/createAndLoadContainerUtils.ts

@@ -9,6 +9,7 @@ import type {
 	IFluidCodeDetails,
 	IContainerPolicies,
 } from "@fluidframework/container-definitions/internal";
+import { LoaderHeader } from "@fluidframework/container-definitions/internal";
 import type {
 	FluidObject,
 	IConfigProviderBase,
@@ -20,10 +21,44 @@ import type {
 	IDocumentServiceFactory,
 	IUrlResolver,
 } from "@fluidframework/driver-definitions/internal";
+import { DriverHeader } from "@fluidframework/driver-definitions/internal";
+import {
+	GenericError,
+	normalizeError,
+	createChildMonitoringContext,
+	mixinMonitoringContext,
+	sessionStorageConfigProvider,
+	PerformanceEvent,
+	isFluidError,
+} from "@fluidframework/telemetry-utils/internal";
+import { v4 as uuid } from "uuid";
 
+import { DebugLogger } from "./debugLogger.js";
 import { createFrozenDocumentServiceFactory } from "./frozenServices.js";
 import { Loader } from "./loader.js";
+import { pkgVersion } from "./packageVersion.js";
 import type { ProtocolHandlerBuilder } from "./protocol.js";
+import type {
+	LoadSummarizerSummaryResult,
+	OnDemandSummaryResults,
+	SummarizeOnDemandResults,
+} from "./summarizerResultTypes.js";
+
+interface OnDemandSummarizeResultsPromises {
+	readonly summarySubmitted: Promise<SummarizeOnDemandResults["summarySubmitted"]>;
+	readonly summaryOpBroadcasted: Promise<SummarizeOnDemandResults["summaryOpBroadcasted"]>;
+}
+
+interface OnDemandSummarizeOptions {
+	readonly reason?: string;
+	readonly retryOnFailure?: boolean;
+	readonly fullTree?: boolean;
+}
+
+interface SummarizerLike {
+	readonly ISummarizer?: SummarizerLike;
+	summarizeOnDemand(options: OnDemandSummarizeOptions): OnDemandSummarizeResultsPromises;
+}
 
 /**
  * Properties necessary for creating and loading a container.
@@ -103,6 +138,15 @@ export interface ILoadExistingContainerProps extends ICreateAndLoadContainerProp
 	readonly pendingLocalState?: string | undefined;
 }
 
+/**
+ * Props used to load summarizer container.
+ * @legacy @alpha
+ */
+export type ILoadSummarizerContainerProps = Omit<
+	ILoadExistingContainerProps,
+	"pendingLocalState"
+>;
+
 /**
  * Props used to create a detached container.
  * @legacy @beta
@@ -200,3 +244,133 @@ export async function loadFrozenContainerFromPendingState(
 		documentServiceFactory: createFrozenDocumentServiceFactory(props.documentServiceFactory),
 	});
 }
+
+/**
+ * Loads a summarizer container with the required headers, triggers an on-demand summary, and then closes it.
+ * Returns success/failure and an optional error for host-side handling.
+ *
+ * @legacy @alpha
+ */
+export async function loadSummarizerContainerAndMakeSummary(
+	loadSummarizerContainerProps: ILoadSummarizerContainerProps,
+): Promise<LoadSummarizerSummaryResult> {
+	const { logger, configProvider, request: originalRequest } = loadSummarizerContainerProps;
+	const telemetryProps = {
+		loaderId: uuid(),
+		loaderVersion: pkgVersion,
+	};
+
+	const subMc = mixinMonitoringContext(
+		DebugLogger.mixinDebugLogger("fluid:telemetry", logger, {
+			all: telemetryProps,
+		}),
+		sessionStorageConfigProvider.value,
+		configProvider,
+	);
+	const mc = createChildMonitoringContext({
+		logger: subMc.logger,
+		namespace: "SummarizerOnDemand",
+	});
+	return PerformanceEvent.timedExecAsync(
+		mc.logger,
+		{ eventName: "SummarizerOnDemandSummary" },
+		async (event) => {
+			const baseHeaders = originalRequest.headers;
+			const request = {
+				...originalRequest,
+				headers: {
+					...baseHeaders,
+					[LoaderHeader.cache]: false,
+					[LoaderHeader.clientDetails]: {
+						capabilities: { interactive: false },
+						type: "summarizer",
+					},
+					[DriverHeader.summarizingClient]: true,
+					[LoaderHeader.reconnect]: false,
+				},
+			};
+
+			const container = await loadExistingContainer({
+				...loadSummarizerContainerProps,
+				request,
+			});
+
+			let summarySubmitted: SummarizeOnDemandResults["summarySubmitted"];
+			let summaryOpBroadcasted: SummarizeOnDemandResults["summaryOpBroadcasted"];
+			try {
+				if (container.getEntryPoint === undefined) {
+					throw new GenericError("container.getEntryPoint() is undefined");
+				}
+				const fluidObject = (await container.getEntryPoint()) as FluidObject<SummarizerLike>;
+				const summarizer = fluidObject?.ISummarizer;
+				if (summarizer === undefined) {
+					throw new GenericError("Summarizer entry point not available");
+				}
+				// Host controlled feature gate for fullTree
+				// Default value will be false
+				const fullTreeGate =
+					mc.config.getBoolean("Fluid.Summarizer.FullTree.OnDemand") === true;
+
+				const summarizeResults: OnDemandSummarizeResultsPromises =
+					summarizer.summarizeOnDemand({
+						reason: "summaryOnRequest",
+						retryOnFailure: true,
+						fullTree: fullTreeGate,
+					});
+				[summarySubmitted, summaryOpBroadcasted] = await Promise.all([
+					summarizeResults.summarySubmitted,
+					summarizeResults.summaryOpBroadcasted,
+				]);
+
+				const summaryResults: OnDemandSummaryResults = {
+					summarySubmitted: summarySubmitted.success,
+					summaryInfo: summarySubmitted.success
+						? {
+								stage: summarySubmitted.data.stage,
+								handle: summaryOpBroadcasted.success
+									? summaryOpBroadcasted.data.summarizeOp.contents.handle
+									: undefined,
+							}
+						: {},
+					summaryOpBroadcasted: summaryOpBroadcasted.success,
+				};
+
+				if (summarySubmitted.success && summaryOpBroadcasted.success) {
+					event.end({
+						success: true,
+						summarySubmitted: true,
+						summaryOpBroadcasted: true,
+					});
+					return {
+						success: true,
+						summaryResults,
+					};
+				}
+
+				const failureError =
+					summarySubmitted.success === false
+						? summarySubmitted.error
+						: summaryOpBroadcasted.success === false
+							? summaryOpBroadcasted.error
+							: new GenericError("On demand summary failed");
+
+				event.end({
+					success: false,
+					summarySubmitted: summarySubmitted.success,
+					summaryOpBroadcasted: summaryOpBroadcasted.success,
+				});
+				return {
+					success: false,
+					error: failureError,
+				};
+			} catch (error) {
+				event.cancel({ success: false }, error);
+				const caughtError = isFluidError(error) ? error : normalizeError(error);
+				return { success: false, error: caughtError };
+			} finally {
+				container.dispose();
+			}
+		},
+		{ start: true, end: true, cancel: "generic" },
+	);
+}

packages/loader/container-loader/src/index.ts

@@ -11,12 +11,19 @@ export {
 	loadExistingContainer,
 	rehydrateDetachedContainer,
 	loadFrozenContainerFromPendingState,
+	loadSummarizerContainerAndMakeSummary,
 	type ICreateAndLoadContainerProps,
 	type ICreateDetachedContainerProps,
 	type ILoadExistingContainerProps,
+	type ILoadSummarizerContainerProps,
 	type IRehydrateDetachedContainerProps,
 	type ILoadFrozenContainerFromPendingStateProps,
 } from "./createAndLoadContainerUtils.js";
+export type {
+	LoadSummarizerSummaryResult,
+	OnDemandSummaryResults,
+	SummaryStage,
+} from "./summarizerResultTypes.js";
 export {
 	type ICodeDetailsLoader,
 	type IFluidModuleWithDetails,