@fluidframework/container-loader 2.70.0-361248 → 2.70.0

package/src/container.ts

@@ -145,6 +145,7 @@ import {
 	type ProtocolHandlerBuilder,
 	type ProtocolHandlerInternal,
 	protocolHandlerShouldProcessSignal,
+	wrapProtocolHandlerBuilder,
 } from "./protocol.js";
 import { initQuorumValuesFromCodeDetails } from "./quorum.js";
 import {
@@ -498,6 +499,7 @@ export class Container
 	private readonly subLogger: ITelemetryLoggerExt;
 	private readonly detachedBlobStorage: MemoryDetachedBlobStorage | undefined;
 	private readonly protocolHandlerBuilder: InternalProtocolHandlerBuilder;
+	private readonly signalAudience = new Audience();
 	private readonly client: IClient;
 
 	private readonly mc: MonitoringContext;
@@ -557,12 +559,19 @@ export class Container
 			// Ideally, we should supply pendingLocalState?.clientId here as well, not in constructor, but it does not matter (at least today)
 			this.connectionStateHandler.initProtocol(this.protocolHandler);
 
-			// Propagate current connection state through the system.
-			const readonly = this.readOnlyInfo.readonly ?? false;
 			// This call does not look like needed any more, with delaying all connection-related events past loaded phase.
 			// Yet, there could be some customer code that would break if we do not deliver it.
 			// Will be removed in further PRs with proper changeset.
-			this.setContextConnectedState(false /* connected */, readonly);
+			const runtime = this._runtime;
+			if (
+				runtime !== undefined &&
+				// Check for older runtime that may need this call
+				!("setConnectionStatus" in runtime) &&
+				runtime.disposed === false
+			) {
+				runtime.setConnectionState(false /* canSendOps */, this.clientId);
+			}
+
 			// Deliver delayed calls to DeltaManager - we ignored "connect" events while loading.
 			const cm = this._deltaManager.connectionManager;
 			if (cm.connected) {
@@ -810,6 +819,7 @@ export class Container
 		validateDriverCompatibility(
 			maybeDriverCompatDetails.ILayerCompatDetails,
 			(error) => {} /* disposeFn */, // There is nothing to dispose here, so just ignore the error.
+			subLogger,
 		);
 
 		this.connectionTransitionTimes[ConnectionState.Disconnected] = performanceNow();
@@ -826,20 +836,22 @@ export class Container
 		// Tracking alternative ways to handle this in AB#4129.
 		this.options = { ...options };
 		this.scope = scope;
-		this.protocolHandlerBuilder =
+		this.protocolHandlerBuilder = wrapProtocolHandlerBuilder(
 			protocolHandlerBuilder ??
-			((
-				attributes: IDocumentAttributes,
-				quorumSnapshot: IQuorumSnapshot,
-				sendProposal: (key: string, value: unknown) => number,
-			): ProtocolHandlerInternal =>
-				new ProtocolHandler(
-					attributes,
-					quorumSnapshot,
-					sendProposal,
-					new Audience(),
-					(clientId: string) => this.clientsWhoShouldHaveLeft.has(clientId),
-				));
+				((
+					attributes: IDocumentAttributes,
+					quorumSnapshot: IQuorumSnapshot,
+					sendProposal: (key: string, value: unknown) => number,
+				): ProtocolHandlerInternal =>
+					new ProtocolHandler(
+						attributes,
+						quorumSnapshot,
+						sendProposal,
+						new Audience(),
+						(clientId: string) => this.clientsWhoShouldHaveLeft.has(clientId),
+					)),
+			this.signalAudience,
+		);
 
 		// Note that we capture the createProps here so we can replicate the creation call when we want to clone.
 		this.clone = async (
@@ -2117,10 +2129,7 @@ export class Container
 
 		deltaManager.on("readonly", (readonly) => {
 			if (this.loaded) {
-				this.setContextConnectedState(
-					this.connectionState === ConnectionState.Connected,
-					readonly,
-				);
+				this.setConnectionStatus(readonly);
 			}
 			this.emit("readonly", readonly);
 		});
@@ -2222,8 +2231,20 @@ export class Container
 			const clientId = this.connectionStateHandler.clientId;
 			assert(clientId !== undefined, 0x96e /* there has to be clientId */);
 			this.protocolHandler.audience.setCurrentClientId(clientId);
+			this.signalAudience.setCurrentClientId(clientId);
+		} else if (this.connectionState === ConnectionState.CatchingUp) {
+			// Signal-based Audience does not wait for ops. So provide clientId
+			// as soon as possible.
+			const clientId = this.connectionStateHandler.pendingClientId;
+			assert(clientId !== undefined, 0xc89 /* catching up without clientId */);
+			this.signalAudience.setCurrentClientId(clientId);
 		}
 
+		this.setConnectionStatus(
+			/* readonly */ this.readOnlyInfo.readonly ?? false,
+			/* onlyCallSetConnectionStateIfConnectedOrDisconnected */ true,
+		);
+
 		// We communicate only transitions to Connected & Disconnected states, skipping all other states.
 		// This can be changed in the future, for example we likely should add "CatchingUp" event on Container.
 		if (
@@ -2235,7 +2256,6 @@ export class Container
 
 		// Both protocol and context should not be undefined if we got so far.
 
-		this.setContextConnectedState(connected, this.readOnlyInfo.readonly ?? false);
 		this.protocolHandler.setConnectionState(connected, this.clientId);
 		raiseConnectedEvent(
 			this.mc.logger,
@@ -2448,6 +2468,7 @@ export class Container
 				storage: this.storageAdapter,
 				quorum: this.protocolHandler.quorum,
 				audience: this.protocolHandler.audience,
+				signalAudience: this.signalAudience,
 				loader,
 				submitFn: (type, contents, batch, metadata) =>
 					this.submitContainerMessage(type, contents, batch, metadata),
@@ -2481,7 +2502,10 @@ export class Container
 
 			// Validate that the Runtime is compatible with this Loader.
 			const maybeRuntimeCompatDetails = runtime as FluidObject<ILayerCompatDetails>;
-			validateRuntimeCompatibility(maybeRuntimeCompatDetails.ILayerCompatDetails);
+			validateRuntimeCompatibility(
+				maybeRuntimeCompatDetails.ILayerCompatDetails,
+				this.mc.logger,
+			);
 
 			this._runtime = runtime;
 			this._lifecycleEvents.emit("runtimeInstantiated");
@@ -2501,18 +2525,92 @@ export class Container
 	};
 
 	/**
-	 * Set the connected state of the ContainerContext
-	 * This controls the "connected" state of the ContainerRuntime as well
-	 * @param connected - Is the container currently connected?
+	 * Send the connected status to the runtime.
 	 * @param readonly - Is the container in readonly mode?
+	 * @param onlyCallSetConnectionStateIfConnectedOrDisconnected - If true, only
+	 * call older `setConnectionState` on the runtime if the connection state is
+	 * either Connected or Disconnected. This exists to preserve older behavior
+	 * where the runtime was only notified of these two states.
 	 */
-	private setContextConnectedState(connected: boolean, readonly: boolean): void {
+	private setConnectionStatus(
+		readonly: boolean,
+		onlyCallSetConnectionStateIfConnectedOrDisconnected: boolean = false,
+	): void {
 		if (this._runtime?.disposed === false && this.loaded) {
-			this.runtime.setConnectionState(
-				connected &&
-					!readonly /* container can send ops if connected to service and not in readonly mode */,
-				this.clientId,
-			);
+			const setConnectionStatus = this.runtime.setConnectionStatus?.bind(this.runtime);
+			if (setConnectionStatus === undefined) {
+				if (
+					!onlyCallSetConnectionStateIfConnectedOrDisconnected ||
+					this.connectionState === ConnectionState.Connected ||
+					this.connectionState === ConnectionState.Disconnected
+				) {
+					this.runtime.setConnectionState(
+						this.connectionState === ConnectionState.Connected &&
+							!readonly /* container can send ops if connected to service and not in readonly mode */,
+						this.clientId,
+					);
+				}
+			} else {
+				const pendingClientConnectionId = this.connectionStateHandler.pendingClientId;
+				const connectionState = this.connectionState;
+				switch (connectionState) {
+					case ConnectionState.EstablishingConnection: {
+						setConnectionStatus({
+							connectionState,
+							canSendOps: false,
+							readonly,
+						});
+
+						break;
+					}
+					case ConnectionState.CatchingUp: {
+						// When catching up, we have a pending clientId, but it
+						// is not usable for ops. Send clientId with canSendOps false.
+						assert(
+							pendingClientConnectionId !== undefined,
+							0xc8a /* catching up without clientId */,
+						);
+						setConnectionStatus({
+							connectionState,
+							pendingClientConnectionId,
+							canSendOps: false,
+							readonly,
+						});
+
+						break;
+					}
+					case ConnectionState.Connected: {
+						// When connected, we have an active clientId. Pass it along
+						// with canSendOps true/false based on readonly.
+						const clientConnectionId = this.clientId;
+						assert(clientConnectionId !== undefined, 0xc8b /* connected without clientId */);
+						assert(
+							clientConnectionId === pendingClientConnectionId,
+							0xc8c /* connected with different clientId than pending */,
+						);
+						setConnectionStatus({
+							connectionState,
+							clientConnectionId,
+							canSendOps: !readonly,
+							readonly,
+						});
+
+						break;
+					}
+					case ConnectionState.Disconnected: {
+						setConnectionStatus({
+							connectionState,
+							priorPendingClientConnectionId: pendingClientConnectionId,
+							priorConnectedClientConnectionId: this.clientId,
+							canSendOps: false,
+							readonly,
+						});
+
+						break;
+					}
+					// No default
+				}
+			}
 		}
 	}
 

package/src/containerContext.ts

@@ -102,6 +102,7 @@ export class ContainerContext
 	public readonly storage: IContainerStorageService;
 	public readonly quorum: IQuorumClients;
 	public readonly audience: IAudience;
+	public readonly signalAudience: IAudience;
 	public readonly loader: ILoader;
 	public readonly submitFn: (
 		type: MessageType,
@@ -182,6 +183,7 @@ export class ContainerContext
 		this.storage = config.storage;
 		this.quorum = config.quorum;
 		this.audience = config.audience;
+		this.signalAudience = config.signalAudience;
 		this.loader = config.loader;
 		this.submitFn = config.submitFn;
 		this.submitSummaryFn = config.submitSummaryFn;

package/src/containerStorageAdapter.ts

@@ -10,7 +10,7 @@ import type {
 } from "@fluidframework/container-definitions/internal";
 import type { IDisposable } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
-import type { ISummaryHandle, ISummaryTree } from "@fluidframework/driver-definitions";
+import type { ISummaryTree } from "@fluidframework/driver-definitions";
 import type {
 	FetchSource,
 	IDocumentService,
@@ -247,16 +247,6 @@ export class ContainerStorageAdapter
 	public async createBlob(file: ArrayBufferLike): Promise<ICreateBlobResponse> {
 		return this._storageService.createBlob(file);
 	}
-
-	/**
-	 * {@link IRuntimeStorageService.downloadSummary}.
-	 *
-	 * @deprecated This API is deprecated and will be removed in a future release. No replacement is planned as
-	 * it is unused in the Runtime and below layers.
-	 */
-	public async downloadSummary(handle: ISummaryHandle): Promise<ISummaryTree> {
-		return this._storageService.downloadSummary(handle);
-	}
 }
 
 /**

package/src/index.ts

@@ -54,3 +54,4 @@ export type {
 	QuorumClientsSnapshot,
 	QuorumProposalsSnapshot,
 } from "./protocol/index.js";
+export { PendingLocalStateStore } from "./pendingLocalStateStore.js";

package/src/loaderLayerCompatState.ts

@@ -3,13 +3,15 @@
  * Licensed under the MIT License.
  */
 
-import {
-	checkLayerCompatibility,
-	type ILayerCompatDetails,
-	type ILayerCompatSupportRequirements,
+import type {
+	ILayerCompatDetails,
+	ILayerCompatSupportRequirements,
 } from "@fluid-internal/client-utils";
 import type { ICriticalContainerError } from "@fluidframework/container-definitions";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import {
+	validateLayerCompatibility,
+	type ITelemetryLoggerExt,
+} from "@fluidframework/telemetry-utils/internal";
 
 import { pkgVersion } from "./packageVersion.js";
 
@@ -78,25 +80,17 @@ export const driverSupportRequirementsForLoader: ILayerCompatSupportRequirements
  */
 export function validateRuntimeCompatibility(
 	maybeRuntimeCompatDetails: ILayerCompatDetails | undefined,
+	logger: ITelemetryLoggerExt,
 ): void {
-	const layerCheckResult = checkLayerCompatibility(
+	validateLayerCompatibility(
+		"loader",
+		"runtime",
+		loaderCompatDetailsForRuntime,
 		runtimeSupportRequirementsForLoader,
 		maybeRuntimeCompatDetails,
+		() => {} /* disposeFn - no op. This will be handled by the caller */,
+		logger,
 	);
-	if (!layerCheckResult.isCompatible) {
-		const error = new UsageError("Loader is not compatible with Runtime", {
-			errorDetails: JSON.stringify({
-				loaderVersion: loaderCompatDetailsForRuntime.pkgVersion,
-				runtimeVersion: maybeRuntimeCompatDetails?.pkgVersion,
-				loaderGeneration: loaderCompatDetailsForRuntime.generation,
-				runtimeGeneration: maybeRuntimeCompatDetails?.generation,
-				minSupportedGeneration: runtimeSupportRequirementsForLoader.minSupportedGeneration,
-				isGenerationCompatible: layerCheckResult.isGenerationCompatible,
-				unsupportedFeatures: layerCheckResult.unsupportedFeatures,
-			}),
-		});
-		throw error;
-	}
 }
 
 /**
@@ -106,24 +100,15 @@ export function validateRuntimeCompatibility(
 export function validateDriverCompatibility(
 	maybeDriverCompatDetails: ILayerCompatDetails | undefined,
 	disposeFn: (error?: ICriticalContainerError) => void,
+	logger: ITelemetryLoggerExt,
 ): void {
-	const layerCheckResult = checkLayerCompatibility(
+	validateLayerCompatibility(
+		"loader",
+		"driver",
+		loaderCompatDetailsForRuntime,
 		driverSupportRequirementsForLoader,
 		maybeDriverCompatDetails,
+		disposeFn,
+		logger,
 	);
-	if (!layerCheckResult.isCompatible) {
-		const error = new UsageError("Loader is not compatible with Driver", {
-			errorDetails: JSON.stringify({
-				loaderVersion: loaderCoreCompatDetails.pkgVersion,
-				driverVersion: maybeDriverCompatDetails?.pkgVersion,
-				loaderGeneration: loaderCoreCompatDetails.generation,
-				driverGeneration: maybeDriverCompatDetails?.generation,
-				minSupportedGeneration: driverSupportRequirementsForLoader.minSupportedGeneration,
-				isGenerationCompatible: layerCheckResult.isGenerationCompatible,
-				unsupportedFeatures: layerCheckResult.unsupportedFeatures,
-			}),
-		});
-		disposeFn(error);
-		throw error;
-	}
 }

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-loader";
-export const pkgVersion = "2.70.0-361248";
+export const pkgVersion = "2.70.0";

package/src/pendingLocalStateStore.ts

@@ -0,0 +1,160 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import type {
+	IPendingContainerState,
+	SerializedSnapshotInfo,
+} from "./serializedStateManager.js";
+import { getAttachedContainerStateFromSerializedContainer } from "./utils.js";
+
+/**
+ * A Map-like store for managing pending local container states from attached containers.
+ * Optimizes storage by deduplicating shared resources across stored states.
+ *
+ * @example
+ * ```typescript
+ * const store = new PendingLocalStateStore<string>();
+ *
+ * // Store pending state
+ * const pendingState = await attachedContainer.getPendingLocalState();
+ * store.set("session1", pendingState);
+ *
+ * // Load from stored state
+ * const restored = store.get("session1");
+ * const newContainer = await loadFrozenContainerFromPendingState({
+ *   pendingLocalState: restored,
+ *   // ... other loader options
+ * });
+ * ```
+ *
+ * @remarks
+ * Only use with attached containers from the same URL. Only store strings
+ * returned by `container.getPendingLocalState()`.
+ *
+ * @typeParam TKey - The type of keys used to identify stored states
+ *
+ * @legacy @alpha
+ */
+export class PendingLocalStateStore<TKey> {
+	#firstUrl: string | undefined;
+	readonly #pendingStates = new Map<TKey, IPendingContainerState>();
+	readonly #savedOps: Record<number, ISequencedDocumentMessage> = {};
+	readonly #blobs: Record<string, string> = {};
+	readonly #loadingGroups: Record<string, SerializedSnapshotInfo> = {};
+
+	/**
+	 * Removes all stored pending states.
+	 */
+	clear(): void {
+		return this.#pendingStates.clear();
+	}
+
+	/**
+	 * Removes the pending state for the specified key.
+	 *
+	 * @param key - The key to remove
+	 * @returns `true` if the state existed and was removed, `false` otherwise
+	 */
+	delete(key: TKey): boolean {
+		return this.#pendingStates.delete(key);
+	}
+
+	/**
+	 * Retrieves the serialized pending state for the specified key.
+	 *
+	 * @param key - The key to retrieve
+	 * @returns The serialized state as a JSON string, or `undefined` if not found
+	 */
+	get(key: TKey): string | undefined {
+		return JSON.stringify(this.#pendingStates.get(key));
+	}
+
+	/**
+	 * Checks whether a pending state exists for the specified key.
+	 */
+	has(key: TKey): boolean {
+		return this.#pendingStates.has(key);
+	}
+
+	/**
+	 * Stores a pending state from `container.getPendingLocalState()`.
+	 *
+	 * @param key - The key to associate with the state
+	 * @param pendingLocalState - String returned by `getPendingLocalState()` from an attached container
+	 * @returns This store instance for method chaining
+	 *
+	 * @throws When storing states from different container URLs
+	 */
+	set(key: TKey, pendingLocalState: string): this {
+		const state = getAttachedContainerStateFromSerializedContainer(pendingLocalState);
+		const { savedOps, snapshotBlobs, loadedGroupIdSnapshots, url } = state;
+
+		this.#firstUrl ??= url;
+		if (this.#firstUrl !== url) {
+			throw new UsageError("PendingLocalStateStore can only be used with a single container.");
+		}
+
+		for (let i = 0; i < savedOps.length; i++) {
+			savedOps[i] = this.#savedOps[savedOps[i].sequenceNumber] ??= savedOps[i];
+		}
+		for (const [id, blob] of Object.entries(snapshotBlobs)) {
+			snapshotBlobs[id] = this.#blobs[id] ??= blob;
+		}
+		if (loadedGroupIdSnapshots !== undefined) {
+			for (const [id, lg] of Object.entries(loadedGroupIdSnapshots)) {
+				if (
+					this.#loadingGroups[id] === undefined ||
+					lg.snapshotSequenceNumber < this.#loadingGroups[id].snapshotSequenceNumber
+				) {
+					loadedGroupIdSnapshots[id] = this.#loadingGroups[id] = lg;
+				}
+			}
+		}
+
+		this.#pendingStates.set(key, state);
+		return this;
+	}
+
+	/**
+	 * Gets the number of stored pending states.
+	 */
+	get size(): number {
+		return this.#pendingStates.size;
+	}
+
+	/**
+	 * Returns an iterator over [key, serializedState] pairs.
+	 */
+	entries(): Iterator<[TKey, string]> {
+		const iterator = this.#pendingStates.entries();
+		return {
+			next: (): IteratorResult<[TKey, string]> => {
+				// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+				const { done, value } = iterator.next();
+				if (done === true) {
+					return { done, value: undefined };
+				}
+				return { done, value: [value[0], JSON.stringify(value[1])] };
+			},
+		};
+	}
+
+	/**
+	 * Returns an iterator over the stored keys.
+	 */
+	keys(): IterableIterator<TKey> {
+		return this.#pendingStates.keys();
+	}
+
+	/**
+	 * Makes the store iterable with `for...of` loops.
+	 */
+	[Symbol.iterator](): Iterator<[TKey, string]> {
+		return this.entries();
+	}
+}

package/src/protocol.ts

@@ -213,3 +213,52 @@ export function protocolHandlerShouldProcessSignal(
 	}
 	return false;
 }
+
+export function wrapProtocolHandlerBuilder(
+	builder: ProtocolHandlerBuilder,
+	signalAudience: IAudienceOwner,
+): InternalProtocolHandlerBuilder {
+	return (
+		attributes: IDocumentAttributes,
+		snapshot: IQuorumSnapshot,
+		sendProposal: (key: string, value: unknown) => number,
+	): ProtocolHandlerInternal => {
+		const baseHandler = builder(attributes, snapshot, sendProposal);
+		// Create proxy handler with an overridden processSignal method.
+		// Use a Proxy since base may use [dynamic] property getters.
+		return new Proxy(baseHandler, {
+			get(target, prop, receiver) {
+				if (prop === "processSignal") {
+					return (message: AudienceSignal) => {
+						const innerContent = message.content;
+						switch (innerContent.type) {
+							case SignalType.Clear: {
+								const members = signalAudience.getMembers();
+								for (const clientId of members.keys()) {
+									signalAudience.removeMember(clientId);
+								}
+								break;
+							}
+							case SignalType.ClientJoin: {
+								const newClient = innerContent.content;
+								signalAudience.addMember(newClient.clientId, newClient.client);
+								break;
+							}
+							case SignalType.ClientLeave: {
+								const leftClientId = innerContent.content;
+								signalAudience.removeMember(leftClientId);
+								break;
+							}
+							default: {
+								break;
+							}
+						}
+						target.processSignal(message);
+					};
+				}
+				// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+				return Reflect.get(target, prop, receiver);
+			},
+		});
+	};
+}

package/src/utils.ts

@@ -380,6 +380,12 @@ export function getDetachedContainerStateFromSerializedContainer(
  * Blindly parses the given string into {@link IPendingContainerState} format.
  * This is the inverse of the JSON.stringify call in {@link SerializedStateManager.getPendingLocalState}
  */
+export function getAttachedContainerStateFromSerializedContainer(
+	serializedContainer: string,
+): IPendingContainerState;
+export function getAttachedContainerStateFromSerializedContainer(
+	serializedContainer: string | undefined,
+): IPendingContainerState | undefined;
 export function getAttachedContainerStateFromSerializedContainer(
 	serializedContainer: string | undefined,
 ): IPendingContainerState | undefined {