@fluidframework/container-loader 2.0.0-dev-rc.1.0.0.228517 → 2.0.0-dev-rc.1.0.0.232845

package/src/containerContext.ts

@@ -16,7 +16,7 @@ import {
 	IBatchMessage,
 } from "@fluidframework/container-definitions";
 import { FluidObject } from "@fluidframework/core-interfaces";
-import { IDocumentStorageService } from "@fluidframework/driver-definitions";
+import { IDocumentStorageService, ISnapshot } from "@fluidframework/driver-definitions";
 import {
 	IClientDetails,
 	IDocumentMessage,
@@ -99,6 +99,7 @@ export class ContainerContext implements IContainerContext {
 		public readonly existing: boolean,
 		public readonly taggedLogger: ITelemetryLoggerExt,
 		public readonly pendingLocalState?: unknown,
+		public readonly snapshotWithContents?: ISnapshot,
 	) {}
 
 	public getLoadedFromVersion(): IVersion | undefined {

package/src/containerStorageAdapter.ts

@@ -13,6 +13,8 @@ import {
 	IDocumentService,
 	IDocumentStorageService,
 	IDocumentStorageServicePolicies,
+	ISnapshot,
+	ISnapshotFetchOptions,
 	ISummaryContext,
 } from "@fluidframework/driver-definitions";
 import { UsageError } from "@fluidframework/driver-utils";
@@ -101,18 +103,9 @@ export class ContainerStorageAdapter implements IDocumentStorageService, IDispos
 		}
 	}
 
-	public loadSnapshotForRehydratingContainer(snapshotTree: ISnapshotTreeWithBlobContents) {
-		this.getBlobContents(snapshotTree);
-	}
-
-	private getBlobContents(snapshotTree: ISnapshotTreeWithBlobContents) {
-		if (snapshotTree.blobsContents !== undefined) {
-			for (const [id, value] of Object.entries(snapshotTree.blobsContents ?? {})) {
-				this.blobContents[id] = value;
-			}
-		}
-		for (const [_, tree] of Object.entries(snapshotTree.trees)) {
-			this.getBlobContents(tree);
+	public loadSnapshotFromSnapshotBlobs(snapshotBlobs: ISerializableBlobContents) {
+		for (const [id, value] of Object.entries(snapshotBlobs)) {
+			this.blobContents[id] = value;
 		}
 	}
 
@@ -136,6 +129,15 @@ export class ContainerStorageAdapter implements IDocumentStorageService, IDispos
 		return this._storageService.getSnapshotTree(version, scenarioName);
 	}
 
+	public async getSnapshot(snapshotFetchOptions?: ISnapshotFetchOptions): Promise<ISnapshot> {
+		if (this._storageService.getSnapshot !== undefined) {
+			return this._storageService.getSnapshot(snapshotFetchOptions);
+		}
+		throw new UsageError(
+			"getSnapshot api should exist in internal storage in ContainerStorageAdapter",
+		);
+	}
+
 	public async readBlob(id: string): Promise<ArrayBufferLike> {
 		const maybeBlob = this.blobContents[id];
 		if (maybeBlob !== undefined) {
@@ -208,6 +210,7 @@ class BlobOnlyStorage implements IDocumentStorageService {
 
 	/* eslint-disable @typescript-eslint/unbound-method */
 	public getSnapshotTree: () => Promise<ISnapshotTree | null> = this.notCalled;
+	public getSnapshot: () => Promise<ISnapshot> = this.notCalled;
 	public getVersions: () => Promise<IVersion[]> = this.notCalled;
 	public write: () => Promise<IVersion> = this.notCalled;
 	public uploadSummaryWithContext: () => Promise<string> = this.notCalled;

package/src/loader.ts

@@ -108,7 +108,7 @@ export interface IFluidModuleWithDetails {
 }
 
 /**
- * @deprecated ICodeDetailsLoader interface is moved to {@link @fluidframework/container-definition#ICodeDetailsLoader}
+ * @deprecated ICodeDetailsLoader interface is moved to {@link @fluidframework/container-definitions#ICodeDetailsLoader}
  * to have code loading modules in one package. #8193
  * Fluid code loader resolves a code module matching the document schema, i.e. code details, such as
  * a package name and package version range.

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-loader";
-export const pkgVersion = "2.0.0-dev-rc.1.0.0.228517";
+export const pkgVersion = "2.0.0-dev-rc.1.0.0.232845";

package/src/protocolTreeDocumentStorageService.ts

@@ -27,6 +27,7 @@ export class ProtocolTreeStorageService implements IDocumentStorageService, IDis
 	}
 
 	getSnapshotTree = this.internalStorageService.getSnapshotTree.bind(this.internalStorageService);
+	getSnapshot = this.internalStorageService.getSnapshot?.bind(this.internalStorageService);
 	getVersions = this.internalStorageService.getVersions.bind(this.internalStorageService);
 	createBlob = this.internalStorageService.createBlob.bind(this.internalStorageService);
 	readBlob = this.internalStorageService.readBlob.bind(this.internalStorageService);

package/src/retriableDocumentStorageService.ts

@@ -8,6 +8,8 @@ import {
 	FetchSource,
 	IDocumentStorageService,
 	IDocumentStorageServicePolicies,
+	ISnapshot,
+	ISnapshotFetchOptions,
 	ISummaryContext,
 } from "@fluidframework/driver-definitions";
 import {
@@ -18,7 +20,7 @@ import {
 	IVersion,
 } from "@fluidframework/protocol-definitions";
 import { IDisposable } from "@fluidframework/core-interfaces";
-import { GenericError, ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
+import { GenericError, ITelemetryLoggerExt, UsageError } from "@fluidframework/telemetry-utils";
 import { runWithRetry } from "@fluidframework/driver-utils";
 
 export class RetriableDocumentStorageService implements IDocumentStorageService, IDisposable {
@@ -64,6 +66,21 @@ export class RetriableDocumentStorageService implements IDocumentStorageService,
 		);
 	}
 
+	public async getSnapshot(snapshotFetchOptions?: ISnapshotFetchOptions): Promise<ISnapshot> {
+		return this.runWithRetry(
+			async () =>
+				this.internalStorageServiceP.then(async (s) => {
+					if (s.getSnapshot !== undefined) {
+						return s.getSnapshot(snapshotFetchOptions);
+					}
+					throw new UsageError(
+						"getSnapshot api should exist on internal storage in RetriableDocStorageService class",
+					);
+				}),
+			"storage_getSnapshot",
+		);
+	}
+
 	public async readBlob(id: string): Promise<ArrayBufferLike> {
 		return this.runWithRetry(
 			async () => this.internalStorageServiceP.then(async (s) => s.readBlob(id)),

package/src/utils.ts

@@ -5,16 +5,18 @@
 
 import { parse } from "url";
 import { v4 as uuid } from "uuid";
-import { stringToBuffer, Uint8ArrayToArrayBuffer } from "@fluid-internal/client-utils";
-import { assert, unreachableCase } from "@fluidframework/core-utils";
+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 } from "@fluidframework/telemetry-utils";
+import { LoggingError, UsageError } from "@fluidframework/telemetry-utils";
 import {
 	CombinedAppAndProtocolSummary,
 	DeltaStreamConnectionForbiddenError,
 	isCombinedAppAndProtocolSummary,
 } from "@fluidframework/driver-utils";
 import { DriverErrorTypes } from "@fluidframework/driver-definitions";
+import { ISerializableBlobContents } from "./containerStorageAdapter";
+import { IPendingDetachedContainerState } from "./container";
 
 // This is used when we rehydrate a container from the snapshot. Here we put the blob contents
 // in separate property: blobContents.
@@ -101,21 +103,17 @@ export function combineAppAndProtocolSummary(
 }
 
 /**
- * Converts summary tree (for upload) to snapshot tree (for download).
- * Summary tree blobs contain contents, but snapshot tree blobs normally
- * contain IDs pointing to storage. This will create 2 blob entries in the
- * snapshot tree for each blob in the summary tree. One will be the regular
- * path pointing to a uniquely generated ID. Then there will be another
- * entry with the path as that uniquely generated ID, and value as the
- * blob contents as a base-64 string.
- * @param summary - summary to convert
+ * Converts a summary to snapshot tree and separate its blob contents
+ * to align detached container format with IPendingContainerState
+ * @param summary - ISummaryTree
  */
-function convertSummaryToSnapshotWithEmbeddedBlobContents(
-	summary: ISummaryTree,
-): ISnapshotTreeWithBlobContents {
-	const treeNode: ISnapshotTreeWithBlobContents = {
+function convertSummaryToSnapshotAndBlobs(summary: ISummaryTree): {
+	tree: ISnapshotTree;
+	blobs: ISerializableBlobContents;
+} {
+	let blobContents: ISerializableBlobContents = {};
+	const treeNode: ISnapshotTree = {
 		blobs: {},
-		blobsContents: {},
 		trees: {},
 		id: uuid(),
 		unreferenced: summary.unreferenced,
@@ -126,8 +124,9 @@ function convertSummaryToSnapshotWithEmbeddedBlobContents(
 
 		switch (summaryObject.type) {
 			case SummaryType.Tree: {
-				treeNode.trees[key] =
-					convertSummaryToSnapshotWithEmbeddedBlobContents(summaryObject);
+				const { tree, blobs } = convertSummaryToSnapshotAndBlobs(summaryObject);
+				treeNode.trees[key] = tree;
+				blobContents = { ...blobContents, ...blobs };
 				break;
 			}
 			case SummaryType.Attachment:
@@ -136,11 +135,11 @@ function convertSummaryToSnapshotWithEmbeddedBlobContents(
 			case SummaryType.Blob: {
 				const blobId = uuid();
 				treeNode.blobs[key] = blobId;
-				const contentBuffer =
-					typeof summaryObject.content === "string"
-						? stringToBuffer(summaryObject.content, "utf8")
-						: Uint8ArrayToArrayBuffer(summaryObject.content);
-				treeNode.blobsContents[blobId] = contentBuffer;
+				const contentString: string =
+					summaryObject.content instanceof Uint8Array
+						? Uint8ArrayToString(summaryObject.content)
+						: summaryObject.content;
+				blobContents[blobId] = contentString;
 				break;
 			}
 			case SummaryType.Handle:
@@ -153,42 +152,38 @@ function convertSummaryToSnapshotWithEmbeddedBlobContents(
 			}
 		}
 	}
-	return treeNode;
+	return { tree: treeNode, blobs: blobContents };
 }
 
 /**
- * Combine and convert protocol and app summary tree to format which is readable by container while rehydrating.
+ * Converts summary parts into a SnapshotTree and its blob contents.
  * @param protocolSummaryTree - Protocol Summary Tree
  * @param appSummaryTree - App Summary Tree
  */
-export function convertProtocolAndAppSummaryToSnapshotTree(
+function convertProtocolAndAppSummaryToSnapshotAndBlobs(
 	protocolSummaryTree: ISummaryTree,
 	appSummaryTree: ISummaryTree,
-): ISnapshotTreeWithBlobContents {
-	// Shallow copy is fine, since we are doing a deep clone below.
+): { tree: ISnapshotTree; blobs: ISerializableBlobContents } {
 	const combinedSummary: ISummaryTree = {
 		type: SummaryType.Tree,
 		tree: { ...appSummaryTree.tree },
 	};
 
 	combinedSummary.tree[".protocol"] = protocolSummaryTree;
-	const snapshotTreeWithBlobContents =
-		convertSummaryToSnapshotWithEmbeddedBlobContents(combinedSummary);
+	const snapshotTreeWithBlobContents = convertSummaryToSnapshotAndBlobs(combinedSummary);
 	return snapshotTreeWithBlobContents;
 }
 
-// This function converts the snapshot taken in detached container(by serialize api) to snapshotTree with which
-// a detached container can be rehydrated.
-export const getSnapshotTreeFromSerializedContainer = (
+export const getSnapshotTreeAndBlobsFromSerializedContainer = (
 	detachedContainerSnapshot: ISummaryTree,
-): ISnapshotTreeWithBlobContents => {
+): { tree: ISnapshotTree; blobs: ISerializableBlobContents } => {
 	assert(
 		isCombinedAppAndProtocolSummary(detachedContainerSnapshot),
-		0x1e0 /* "Protocol and App summary trees should be present" */,
+		"Protocol and App summary trees should be present",
 	);
 	const protocolSummaryTree = detachedContainerSnapshot.tree[".protocol"];
 	const appSummaryTree = detachedContainerSnapshot.tree[".app"];
-	const snapshotTreeWithBlobContents = convertProtocolAndAppSummaryToSnapshotTree(
+	const snapshotTreeWithBlobContents = convertProtocolAndAppSummaryToSnapshotAndBlobs(
 		protocolSummaryTree,
 		appSummaryTree,
 	);
@@ -199,6 +194,35 @@ export function getProtocolSnapshotTree(snapshot: ISnapshotTree): ISnapshotTree
 	return ".protocol" in snapshot.trees ? snapshot.trees[".protocol"] : snapshot;
 }
 
+export const combineSnapshotTreeAndSnapshotBlobs = (
+	baseSnapshot: ISnapshotTree,
+	snapshotBlobs: ISerializableBlobContents,
+): ISnapshotTreeWithBlobContents => {
+	const blobsContents: { [path: string]: ArrayBufferLike } = {};
+
+	// Process blobs in the current level
+	for (const [, id] of Object.entries(baseSnapshot.blobs)) {
+		if (snapshotBlobs[id]) {
+			blobsContents[id] = stringToBuffer(snapshotBlobs[id], "utf8");
+		}
+	}
+
+	// Recursively process trees in the current level
+	const trees: { [path: string]: ISnapshotTreeWithBlobContents } = {};
+	for (const [path, tree] of Object.entries(baseSnapshot.trees)) {
+		trees[path] = combineSnapshotTreeAndSnapshotBlobs(tree, snapshotBlobs);
+	}
+
+	// Create a new snapshot tree with blob contents and processed trees
+	const snapshotTreeWithBlobContents: ISnapshotTreeWithBlobContents = {
+		...baseSnapshot,
+		blobsContents,
+		trees,
+	};
+
+	return snapshotTreeWithBlobContents;
+};
+
 export function isDeltaStreamConnectionForbiddenError(
 	error: any,
 ): error is DeltaStreamConnectionForbiddenError {
@@ -208,3 +232,71 @@ export function isDeltaStreamConnectionForbiddenError(
 		error?.errorType === DriverErrorTypes.deltaStreamConnectionForbidden
 	);
 }
+
+/**
+ * Validates format in parsed string get from detached container
+ * serialization using IPendingDetachedContainerState format.
+ */
+function isPendingDetachedContainerState(
+	detachedContainerState: IPendingDetachedContainerState,
+): detachedContainerState is IPendingDetachedContainerState {
+	if (
+		detachedContainerState?.attached === undefined ||
+		detachedContainerState?.baseSnapshot === undefined ||
+		detachedContainerState?.snapshotBlobs === undefined ||
+		detachedContainerState?.hasAttachmentBlobs === undefined
+	) {
+		return false;
+	}
+	return true;
+}
+
+export function getDetachedContainerStateFromSerializedContainer(
+	serializedContainer: string,
+): IPendingDetachedContainerState {
+	const hasBlobsSummaryTree = ".hasAttachmentBlobs";
+	const parsedContainerState = JSON.parse(serializedContainer);
+	if (isPendingDetachedContainerState(parsedContainerState)) {
+		return parsedContainerState;
+	} else if (isCombinedAppAndProtocolSummary(parsedContainerState)) {
+		const { tree, blobs } =
+			getSnapshotTreeAndBlobsFromSerializedContainer(parsedContainerState);
+		const detachedContainerState: IPendingDetachedContainerState = {
+			attached: false,
+			baseSnapshot: tree,
+			snapshotBlobs: blobs,
+			hasAttachmentBlobs: parsedContainerState.tree[hasBlobsSummaryTree] !== undefined,
+		};
+		return detachedContainerState;
+	} else {
+		throw new UsageError("Cannot rehydrate detached container. Incorrect format");
+	}
+}
+
+/**
+ * Ensures only a single instance of the provided async function is running.
+ * If there are multiple calls they will all get the same promise to wait on.
+ */
+export const runSingle = <A extends any[], R>(func: (...args: A) => Promise<R>) => {
+	let running:
+		| {
+				args: A;
+				result: Promise<R>;
+		  }
+		| undefined;
+	// don't mark this function async, so we return the same promise,
+	// rather than one that is wrapped due to async
+	// eslint-disable-next-line @typescript-eslint/promise-function-async
+	return (...args: A) => {
+		if (running !== undefined) {
+			if (!compareArrays(running.args, args)) {
+				return Promise.reject(
+					new UsageError("Subsequent calls cannot use different arguments."),
+				);
+			}
+			return running.result;
+		}
+		running = { args, result: func(...args).finally(() => (running = undefined)) };
+		return running.result;
+	};
+};