@fluidframework/container-loader 2.0.0-dev-rc.2.0.0.246488 → 2.0.0-dev-rc.3.0.0.250606

package/src/retriableDocumentStorageService.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { IDisposable } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils";
 import {
 	FetchSource,
@@ -12,6 +13,7 @@ import {
 	ISnapshotFetchOptions,
 	ISummaryContext,
 } from "@fluidframework/driver-definitions";
+import { runWithRetry } from "@fluidframework/driver-utils";
 import {
 	ICreateBlobResponse,
 	ISnapshotTree,
@@ -19,9 +21,7 @@ import {
 	ISummaryTree,
 	IVersion,
 } from "@fluidframework/protocol-definitions";
-import { IDisposable } from "@fluidframework/core-interfaces";
 import { GenericError, ITelemetryLoggerExt, UsageError } from "@fluidframework/telemetry-utils";
-import { runWithRetry } from "@fluidframework/driver-utils";
 
 export class RetriableDocumentStorageService implements IDocumentStorageService, IDisposable {
 	private _disposed = false;

package/src/serializedStateManager.ts

@@ -3,12 +3,19 @@
  * Licensed under the MIT License.
  */
 
+import { IGetPendingLocalStateProps, IRuntime } from "@fluidframework/container-definitions";
+import { assert } from "@fluidframework/core-utils";
+import {
+	IDocumentStorageService,
+	IResolvedUrl,
+	ISnapshot,
+} from "@fluidframework/driver-definitions";
+import { isInstanceOfISnapshot } from "@fluidframework/driver-utils";
 import {
 	ISequencedDocumentMessage,
 	ISnapshotTree,
 	IVersion,
 } from "@fluidframework/protocol-definitions";
-import { IGetPendingLocalStateProps, IRuntime } from "@fluidframework/container-definitions";
 import {
 	ITelemetryLoggerExt,
 	MonitoringContext,
@@ -16,24 +23,51 @@ import {
 	UsageError,
 	createChildMonitoringContext,
 } from "@fluidframework/telemetry-utils";
-import { assert } from "@fluidframework/core-utils";
-import {
-	IDocumentStorageService,
-	IResolvedUrl,
-	ISnapshot,
-} from "@fluidframework/driver-definitions";
-import { isInstanceOfISnapshot } from "@fluidframework/driver-utils";
 import { ISerializableBlobContents, getBlobContentsFromTree } from "./containerStorageAdapter.js";
-import { IPendingContainerState } from "./container.js";
+
+export interface SnapshotWithBlobs {
+	/**
+	 * Snapshot from which container initially loaded.
+	 */
+	baseSnapshot: ISnapshotTree;
+	/**
+	 * Serializable blobs from the base snapshot. Used to load offline since
+	 * storage is not available.
+	 */
+	snapshotBlobs: ISerializableBlobContents;
+}
+/**
+ * State saved by a container at close time, to be used to load a new instance
+ * of the container to the same state
+ * @internal
+ */
+export interface IPendingContainerState extends SnapshotWithBlobs {
+	attached: true;
+	pendingRuntimeState: unknown;
+	/**
+	 * All ops since base snapshot sequence number up to the latest op
+	 * seen when the container was closed. Used to apply stashed (saved pending)
+	 * ops at the same sequence number at which they were made.
+	 */
+	savedOps: ISequencedDocumentMessage[];
+	url: string;
+	clientId?: string;
+}
+
+/**
+ * State saved by a container in detached state, to be used to load a new instance
+ * of the container to the same state (rehydrate)
+ * @internal
+ */
+export interface IPendingDetachedContainerState extends SnapshotWithBlobs {
+	attached: false;
+	hasAttachmentBlobs: boolean;
+	pendingRuntimeState?: unknown;
+}
 
 export class SerializedStateManager {
 	private readonly processedOps: ISequencedDocumentMessage[] = [];
-	private snapshot:
-		| {
-				tree: ISnapshotTree;
-				blobs: ISerializableBlobContents;
-		  }
-		| undefined;
+	private snapshot: SnapshotWithBlobs | undefined;
 	private readonly mc: MonitoringContext;
 
 	constructor(
@@ -61,104 +95,32 @@ export class SerializedStateManager {
 		}
 	}
 
-	private async getVersion(version: string | null): Promise<IVersion | undefined> {
-		const versions = await this.storageAdapter.getVersions(version, 1);
-		return versions[0];
-	}
-
 	public async fetchSnapshot(
 		specifiedVersion: string | undefined,
-		supportGetSnapshotApi: boolean | undefined,
+		supportGetSnapshotApi: boolean,
 	) {
-		const { snapshot, version } =
-			this.pendingLocalState === undefined
-				? await this.fetchSnapshotCore(specifiedVersion, supportGetSnapshotApi)
-				: { snapshot: this.pendingLocalState.baseSnapshot, version: undefined };
-		const snapshotTree: ISnapshotTree | undefined = isInstanceOfISnapshot(snapshot)
-			? snapshot.snapshotTree
-			: snapshot;
-		if (this.pendingLocalState) {
-			this.snapshot = {
-				tree: this.pendingLocalState.baseSnapshot,
-				blobs: this.pendingLocalState.snapshotBlobs,
-			};
-		} else {
-			assert(snapshotTree !== undefined, 0x8e4 /* Snapshot should exist */);
+		if (this.pendingLocalState === undefined) {
+			const { snapshot, version } = supportGetSnapshotApi
+				? await fetchISnapshot(this.mc, this.storageAdapter, specifiedVersion)
+				: await fetchISnapshotTree(this.mc, this.storageAdapter, specifiedVersion);
+			const baseSnapshot: ISnapshotTree | undefined = isInstanceOfISnapshot(snapshot)
+				? snapshot.snapshotTree
+				: snapshot;
+			assert(baseSnapshot !== undefined, 0x8e4 /* Snapshot should exist */);
 			// non-interactive clients will not have any pending state we want to save
 			if (this.offlineLoadEnabled) {
-				const blobs = await getBlobContentsFromTree(snapshotTree, this.storageAdapter);
-				this.snapshot = { tree: snapshotTree, blobs };
-			}
-		}
-		return { snapshotTree, version };
-	}
-
-	private async fetchSnapshotCore(
-		specifiedVersion: string | undefined,
-		supportGetSnapshotApi: boolean | undefined,
-	): Promise<{ snapshot?: ISnapshot | ISnapshotTree; version?: IVersion }> {
-		if (
-			this.mc.config.getBoolean("Fluid.Container.UseLoadingGroupIdForSnapshotFetch") ===
-				true &&
-			supportGetSnapshotApi === true
-		) {
-			const snapshot =
-				(await this.storageAdapter.getSnapshot?.({
-					versionId: specifiedVersion,
-				})) ?? undefined;
-			const version: IVersion | undefined =
-				snapshot?.snapshotTree.id === undefined
-					? undefined
-					: {
-							id: snapshot.snapshotTree.id,
-							treeId: snapshot.snapshotTree.id,
-					  };
-
-			if (snapshot === undefined && specifiedVersion !== undefined) {
-				this.mc.logger.sendErrorEvent({
-					eventName: "getSnapshotTreeFailed",
-					id: specifiedVersion,
-				});
-				// Not sure if this should be here actually
-			} else if (snapshot !== undefined && version?.id === undefined) {
-				this.mc.logger.sendErrorEvent({
-					eventName: "getSnapshotFetchedTreeWithoutVersionId",
-					hasVersion: version !== undefined, // if hasVersion is true, this means that the contract with the service was broken.
-				});
+				const snapshotBlobs = await getBlobContentsFromTree(
+					baseSnapshot,
+					this.storageAdapter,
+				);
+				this.snapshot = { baseSnapshot, snapshotBlobs };
 			}
-			return { snapshot, version };
-		}
-		return this.fetchSnapshotTree(specifiedVersion);
-	}
-
-	/**
-	 * Get the most recent snapshot, or a specific version.
-	 * @param specifiedVersion - The specific version of the snapshot to retrieve
-	 * @returns The snapshot requested, or the latest snapshot if no version was specified, plus version ID
-	 */
-	private async fetchSnapshotTree(
-		specifiedVersion: string | undefined,
-	): Promise<{ snapshot?: ISnapshotTree; version?: IVersion | undefined }> {
-		const version = await this.getVersion(specifiedVersion ?? null);
-
-		if (version === undefined && specifiedVersion !== undefined) {
-			// We should have a defined version to load from if specified version requested
-			this.mc.logger.sendErrorEvent({
-				eventName: "NoVersionFoundWhenSpecified",
-				id: specifiedVersion,
-			});
-		}
-		const snapshot = (await this.storageAdapter.getSnapshotTree(version)) ?? undefined;
-
-		if (snapshot === undefined && version !== undefined) {
-			this.mc.logger.sendErrorEvent({ eventName: "getSnapshotTreeFailed", id: version.id });
-		} else if (snapshot !== undefined && version?.id === undefined) {
-			this.mc.logger.sendErrorEvent({
-				eventName: "getSnapshotFetchedTreeWithoutVersionId",
-				hasVersion: version !== undefined, // if hasVersion is true, this means that the contract with the service was broken.
-			});
+			return { baseSnapshot, version };
+		} else {
+			const { baseSnapshot, snapshotBlobs } = this.pendingLocalState;
+			this.snapshot = { baseSnapshot, snapshotBlobs };
+			return { baseSnapshot, version: undefined };
 		}
-		return { snapshot, version };
 	}
 
 	/**
@@ -166,14 +128,7 @@ export class SerializedStateManager {
 	 * base snapshot when attaching.
 	 * @param snapshot - snapshot and blobs collected while attaching
 	 */
-	public setSnapshot(
-		snapshot:
-			| {
-					tree: ISnapshotTree;
-					blobs: ISerializableBlobContents;
-			  }
-			| undefined,
-	) {
+	public setSnapshot(snapshot: SnapshotWithBlobs | undefined) {
 		this.snapshot = snapshot;
 	}
 
@@ -202,8 +157,8 @@ export class SerializedStateManager {
 				const pendingState: IPendingContainerState = {
 					attached: true,
 					pendingRuntimeState,
-					baseSnapshot: this.snapshot.tree,
-					snapshotBlobs: this.snapshot.blobs,
+					baseSnapshot: this.snapshot.baseSnapshot,
+					snapshotBlobs: this.snapshot.snapshotBlobs,
 					savedOps: this.processedOps,
 					url: resolvedUrl.url,
 					// no need to save this if there is no pending runtime state
@@ -215,3 +170,65 @@ export class SerializedStateManager {
 		);
 	}
 }
+
+export async function fetchISnapshot(
+	mc: MonitoringContext,
+	storageAdapter: Pick<IDocumentStorageService, "getSnapshot">,
+	specifiedVersion: string | undefined,
+): Promise<{ snapshot?: ISnapshot | ISnapshotTree; version?: IVersion }> {
+	const snapshot = await storageAdapter.getSnapshot?.({ versionId: specifiedVersion });
+	const version: IVersion | undefined =
+		snapshot?.snapshotTree.id === undefined
+			? undefined
+			: {
+					id: snapshot.snapshotTree.id,
+					treeId: snapshot.snapshotTree.id,
+			  };
+
+	if (snapshot === undefined && specifiedVersion !== undefined) {
+		mc.logger.sendErrorEvent({
+			eventName: "getSnapshotTreeFailed",
+			id: specifiedVersion,
+		});
+		// Not sure if this should be here actually
+	} else if (snapshot !== undefined && version?.id === undefined) {
+		mc.logger.sendErrorEvent({
+			eventName: "getSnapshotFetchedTreeWithoutVersionId",
+			hasVersion: version !== undefined, // if hasVersion is true, this means that the contract with the service was broken.
+		});
+	}
+	return { snapshot, version };
+}
+
+/**
+ * Get the most recent snapshot, or a specific version.
+ * @param specifiedVersion - The specific version of the snapshot to retrieve
+ * @returns The snapshot requested, or the latest snapshot if no version was specified, plus version ID
+ */
+export async function fetchISnapshotTree(
+	mc: MonitoringContext,
+	storageAdapter: Pick<IDocumentStorageService, "getSnapshotTree" | "getVersions">,
+	specifiedVersion: string | undefined,
+): Promise<{ snapshot?: ISnapshotTree; version?: IVersion | undefined }> {
+	const versions = await storageAdapter.getVersions(specifiedVersion ?? null, 1);
+	const version = versions[0];
+
+	if (version === undefined && specifiedVersion !== undefined) {
+		// We should have a defined version to load from if specified version requested
+		mc.logger.sendErrorEvent({
+			eventName: "NoVersionFoundWhenSpecified",
+			id: specifiedVersion,
+		});
+	}
+	const snapshot = (await storageAdapter.getSnapshotTree(version)) ?? undefined;
+
+	if (snapshot === undefined && version !== undefined) {
+		mc.logger.sendErrorEvent({ eventName: "getSnapshotTreeFailed", id: version.id });
+	} else if (snapshot !== undefined && version?.id === undefined) {
+		mc.logger.sendErrorEvent({
+			eventName: "getSnapshotFetchedTreeWithoutVersionId",
+			hasVersion: version !== undefined, // if hasVersion is true, this means that the contract with the service was broken.
+		});
+	}
+	return { snapshot, version };
+}

package/src/utils.ts

@@ -3,19 +3,28 @@
  * Licensed under the MIT License.
  */
 
-import { v4 as uuid } from "uuid";
 import { Uint8ArrayToString, stringToBuffer } from "@fluid-internal/client-utils";
 import { assert, compareArrays, unreachableCase } from "@fluidframework/core-utils";
-import { ISummaryTree, ISnapshotTree, SummaryType } from "@fluidframework/protocol-definitions";
-import { LoggingError, UsageError } from "@fluidframework/telemetry-utils";
+import { DriverErrorTypes, IDocumentStorageService } from "@fluidframework/driver-definitions";
 import {
 	CombinedAppAndProtocolSummary,
 	DeltaStreamConnectionForbiddenError,
 	isCombinedAppAndProtocolSummary,
+	readAndParse,
 } from "@fluidframework/driver-utils";
-import { DriverErrorTypes } from "@fluidframework/driver-definitions";
+import {
+	IDocumentAttributes,
+	ISnapshotTree,
+	ISummaryTree,
+	SummaryType,
+} from "@fluidframework/protocol-definitions";
+import { LoggingError, UsageError } from "@fluidframework/telemetry-utils";
+import { v4 as uuid } from "uuid";
 import { ISerializableBlobContents } from "./containerStorageAdapter.js";
-import { IPendingDetachedContainerState } from "./container.js";
+import type {
+	IPendingDetachedContainerState,
+	SnapshotWithBlobs,
+} from "./serializedStateManager.js";
 
 // This is used when we rehydrate a container from the snapshot. Here we put the blob contents
 // in separate property: blobContents.
@@ -111,10 +120,7 @@ export function combineAppAndProtocolSummary(
  * to align detached container format with IPendingContainerState
  * @param summary - ISummaryTree
  */
-function convertSummaryToSnapshotAndBlobs(summary: ISummaryTree): {
-	tree: ISnapshotTree;
-	blobs: ISerializableBlobContents;
-} {
+function convertSummaryToSnapshotAndBlobs(summary: ISummaryTree): SnapshotWithBlobs {
 	let blobContents: ISerializableBlobContents = {};
 	const treeNode: ISnapshotTree = {
 		blobs: {},
@@ -129,9 +135,9 @@ function convertSummaryToSnapshotAndBlobs(summary: ISummaryTree): {
 
 		switch (summaryObject.type) {
 			case SummaryType.Tree: {
-				const { tree, blobs } = convertSummaryToSnapshotAndBlobs(summaryObject);
-				treeNode.trees[key] = tree;
-				blobContents = { ...blobContents, ...blobs };
+				const innerSnapshot = convertSummaryToSnapshotAndBlobs(summaryObject);
+				treeNode.trees[key] = innerSnapshot.baseSnapshot;
+				blobContents = { ...blobContents, ...innerSnapshot.snapshotBlobs };
 				break;
 			}
 			case SummaryType.Attachment:
@@ -157,7 +163,8 @@ function convertSummaryToSnapshotAndBlobs(summary: ISummaryTree): {
 			}
 		}
 	}
-	return { tree: treeNode, blobs: blobContents };
+	const pendingSnapshot = { baseSnapshot: treeNode, snapshotBlobs: blobContents };
+	return pendingSnapshot;
 }
 
 /**
@@ -168,7 +175,7 @@ function convertSummaryToSnapshotAndBlobs(summary: ISummaryTree): {
 function convertProtocolAndAppSummaryToSnapshotAndBlobs(
 	protocolSummaryTree: ISummaryTree,
 	appSummaryTree: ISummaryTree,
-): { tree: ISnapshotTree; blobs: ISerializableBlobContents } {
+): SnapshotWithBlobs {
 	const combinedSummary: ISummaryTree = {
 		type: SummaryType.Tree,
 		tree: { ...appSummaryTree.tree },
@@ -181,7 +188,7 @@ function convertProtocolAndAppSummaryToSnapshotAndBlobs(
 
 export const getSnapshotTreeAndBlobsFromSerializedContainer = (
 	detachedContainerSnapshot: ISummaryTree,
-): { tree: ISnapshotTree; blobs: ISerializableBlobContents } => {
+): SnapshotWithBlobs => {
 	assert(
 		isCombinedAppAndProtocolSummary(detachedContainerSnapshot),
 		0x8e6 /* Protocol and App summary trees should be present */,
@@ -264,12 +271,12 @@ export function getDetachedContainerStateFromSerializedContainer(
 	if (isPendingDetachedContainerState(parsedContainerState)) {
 		return parsedContainerState;
 	} else if (isCombinedAppAndProtocolSummary(parsedContainerState)) {
-		const { tree, blobs } =
+		const { baseSnapshot, snapshotBlobs } =
 			getSnapshotTreeAndBlobsFromSerializedContainer(parsedContainerState);
 		const detachedContainerState: IPendingDetachedContainerState = {
 			attached: false,
-			baseSnapshot: tree,
-			snapshotBlobs: blobs,
+			baseSnapshot,
+			snapshotBlobs,
 			hasAttachmentBlobs: parsedContainerState.tree[hasBlobsSummaryTree] !== undefined,
 		};
 		return detachedContainerState;
@@ -305,3 +312,25 @@ export const runSingle = <A extends any[], R>(func: (...args: A) => Promise<R>)
 		return running.result;
 	};
 };
+
+export async function getDocumentAttributes(
+	storage: Pick<IDocumentStorageService, "readBlob">,
+	tree: ISnapshotTree | undefined,
+): Promise<IDocumentAttributes> {
+	if (tree === undefined) {
+		return {
+			minimumSequenceNumber: 0,
+			sequenceNumber: 0,
+		};
+	}
+
+	// Backward compatibility: old docs would have ".attributes" instead of "attributes"
+	const attributesHash =
+		".protocol" in tree.trees
+			? tree.trees[".protocol"].blobs.attributes
+			: tree.blobs[".attributes"];
+
+	const attributes = await readAndParse<IDocumentAttributes>(storage, attributesHash);
+
+	return attributes;
+}