@fluidframework/container-loader 2.0.0-rc.3.0.2 → 2.0.0-rc.4.0.0

package/src/containerContext.ts

@@ -7,13 +7,13 @@ import {
 	AttachState,
 	IAudience,
 	ICriticalContainerError,
-	IDeltaManager,
 } from "@fluidframework/container-definitions";
 import {
 	IBatchMessage,
 	IContainerContext,
 	ILoader,
 	ILoaderOptions,
+	IDeltaManager,
 } from "@fluidframework/container-definitions/internal";
 import { type FluidObject } from "@fluidframework/core-interfaces";
 import { type ISignalEnvelope } from "@fluidframework/core-interfaces/internal";
@@ -28,7 +28,7 @@ import {
 	IVersion,
 	MessageType,
 } from "@fluidframework/protocol-definitions";
-import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
+import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 
 /**
  * {@inheritDoc @fluidframework/container-definitions#IContainerContext}

package/src/containerStorageAdapter.ts

@@ -24,11 +24,16 @@ import {
 	ISummaryTree,
 	IVersion,
 } from "@fluidframework/protocol-definitions";
-import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
+import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 
 import { IDetachedBlobStorage } from "./loader.js";
 import { ProtocolTreeStorageService } from "./protocolTreeDocumentStorageService.js";
 import { RetriableDocumentStorageService } from "./retriableDocumentStorageService.js";
+import type {
+	ISerializedStateManagerDocumentStorageService,
+	ISnapshotInfo,
+} from "./serializedStateManager.js";
+import { convertSnapshotInfoToSnapshot, getDocumentAttributes } from "./utils.js";
 
 /**
  * Stringified blobs from a summary/snapshot tree.
@@ -42,7 +47,9 @@ export interface ISerializableBlobContents {
  * This class wraps the actual storage and make sure no wrong apis are called according to
  * container attach state.
  */
-export class ContainerStorageAdapter implements IDocumentStorageService, IDisposable {
+export class ContainerStorageAdapter
+	implements ISerializedStateManagerDocumentStorageService, IDocumentStorageService, IDisposable
+{
 	private _storageService: IDocumentStorageService & Partial<IDisposable>;
 
 	private _summarizeProtocolTree: boolean | undefined;
@@ -53,11 +60,20 @@ export class ContainerStorageAdapter implements IDocumentStorageService, IDispos
 		return this._summarizeProtocolTree === true;
 	}
 
+	private _loadedGroupIdSnapshots: Record<string, ISnapshot> = {};
+	/**
+	 * Any loading group id (virtualized) snapshot download from storage will be stored here.
+	 */
+	public get loadedGroupIdSnapshots(): Record<string, ISnapshot> {
+		return this._loadedGroupIdSnapshots;
+	}
+
 	/**
 	 * An adapter that ensures we're using detachedBlobStorage up until we connect to a real service, and then
 	 * after connecting to a real service augments it with retry and combined summary tree enforcement.
 	 * @param detachedBlobStorage - The detached blob storage to use up until we connect to a real service
 	 * @param logger - Telemetry logger
+	 * @param loadingGroupIdSnapshotsFromPendingState - in offline mode, any loading group snapshots we've downloaded from the service that were stored in the pending state
 	 * @param addProtocolSummaryIfMissing - a callback to permit the container to inspect the summary we're about to
 	 * upload, and fix it up with a protocol tree if needed
 	 * @param forceEnableSummarizeProtocolTree - Enforce uploading a protocol summary regardless of the service's policy
@@ -69,6 +85,7 @@ export class ContainerStorageAdapter implements IDocumentStorageService, IDispos
 		 * ArrayBufferLikes or utf8 encoded strings, containing blobs from a snapshot
 		 */
 		private readonly blobContents: { [id: string]: ArrayBufferLike | string } = {},
+		private loadingGroupIdSnapshotsFromPendingState: Record<string, ISnapshotInfo> | undefined,
 		private readonly addProtocolSummaryIfMissing: (summaryTree: ISummaryTree) => ISummaryTree,
 		forceEnableSummarizeProtocolTree: boolean | undefined,
 	) {
@@ -110,6 +127,10 @@ export class ContainerStorageAdapter implements IDocumentStorageService, IDispos
 		}
 	}
 
+	public clearPendingState() {
+		this.loadingGroupIdSnapshotsFromPendingState = undefined;
+	}
+
 	public get policies(): IDocumentStorageServicePolicies | undefined {
 		// back-compat 0.40 containerRuntime requests policies even in detached container if storage is present
 		// and storage is always present in >=0.41.
@@ -127,12 +148,46 @@ export class ContainerStorageAdapter implements IDocumentStorageService, IDispos
 	}
 
 	public async getSnapshot(snapshotFetchOptions?: ISnapshotFetchOptions): Promise<ISnapshot> {
-		if (this._storageService.getSnapshot !== undefined) {
-			return this._storageService.getSnapshot(snapshotFetchOptions);
+		let snapshot: ISnapshot;
+		if (
+			this.loadingGroupIdSnapshotsFromPendingState !== undefined &&
+			snapshotFetchOptions?.loadingGroupIds !== undefined
+		) {
+			const localSnapshot =
+				this.loadingGroupIdSnapshotsFromPendingState[
+					snapshotFetchOptions.loadingGroupIds[0]
+				];
+			assert(localSnapshot !== undefined, 0x970 /* Local snapshot must be present */);
+			const attributes = await getDocumentAttributes(this, localSnapshot.baseSnapshot);
+			snapshot = convertSnapshotInfoToSnapshot(localSnapshot, attributes.sequenceNumber);
+		} else {
+			if (this._storageService.getSnapshot === undefined) {
+				throw new UsageError(
+					"getSnapshot api should exist in internal storage in ContainerStorageAdapter",
+				);
+			}
+			snapshot = await this._storageService.getSnapshot(snapshotFetchOptions);
 		}
-		throw new UsageError(
-			"getSnapshot api should exist in internal storage in ContainerStorageAdapter",
+
+		// Track the latest snapshot for each loading group id
+		const loadingGroupIds = snapshotFetchOptions?.loadingGroupIds;
+		assert(
+			snapshot.sequenceNumber !== undefined,
+			0x971 /* Snapshot must have sequence number */,
 		);
+		if (loadingGroupIds !== undefined) {
+			for (const loadingGroupId of loadingGroupIds) {
+				// Do we actually want to update the stored snapshot?
+				// What if the incoming snapshot is way newer than the stored snapshot?
+				// We only want to update the stored snapshot if the incoming snapshot is newer (stored sequence number < incoming sequence number)
+				const storedSeqNum =
+					this._loadedGroupIdSnapshots[loadingGroupId]?.sequenceNumber ?? -1;
+				if (storedSeqNum < snapshot.sequenceNumber) {
+					this._loadedGroupIdSnapshots[loadingGroupId] = snapshot;
+				}
+			}
+		}
+		return snapshot;
 	}
 
 	public async readBlob(id: string): Promise<ArrayBufferLike> {

package/src/contracts.ts

@@ -3,13 +3,14 @@
  * Licensed under the MIT License.
  */
 
+import { ICriticalContainerError } from "@fluidframework/container-definitions";
 import {
-	IConnectionDetails,
-	ICriticalContainerError,
 	IDeltaQueue,
 	ReadOnlyInfo,
-} from "@fluidframework/container-definitions";
-import { IFluidCodeDetails, isFluidPackage } from "@fluidframework/container-definitions/internal";
+	IFluidCodeDetails,
+	isFluidPackage,
+	IConnectionDetails,
+} from "@fluidframework/container-definitions/internal";
 import { IErrorBase, ITelemetryBaseProperties } from "@fluidframework/core-interfaces";
 import { IContainerPackageInfo } from "@fluidframework/driver-definitions/internal";
 import {

package/src/debugLogger.ts

@@ -9,8 +9,8 @@ import {
 	ITelemetryBaseLogger,
 	ITelemetryBaseProperties,
 } from "@fluidframework/core-interfaces";
-import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
 import {
+	ITelemetryLoggerExt,
 	ITelemetryLoggerPropertyBags,
 	createMultiSinkLogger,
 	eventNamespaceSeparator,

package/src/deltaManager.ts

@@ -3,13 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { TypedEventEmitter } from "@fluid-internal/client-utils";
 import {
 	ICriticalContainerError,
 	IDeltaManager,
 	IDeltaManagerEvents,
 	IDeltaQueue,
-} from "@fluidframework/container-definitions";
+} from "@fluidframework/container-definitions/internal";
 import {
 	IEventProvider,
 	type ITelemetryBaseEvent,
@@ -17,10 +16,10 @@ import {
 } from "@fluidframework/core-interfaces";
 import { IThrottlingWarning } from "@fluidframework/core-interfaces/internal";
 import { assert } from "@fluidframework/core-utils/internal";
-import { DriverErrorTypes } from "@fluidframework/driver-definitions";
 import {
 	IDocumentDeltaStorageService,
 	IDocumentService,
+	DriverErrorTypes,
 } from "@fluidframework/driver-definitions/internal";
 import {
 	MessageType2,
@@ -38,8 +37,6 @@ import {
 	type ITelemetryErrorEventExt,
 	type ITelemetryGenericEventExt,
 	ITelemetryLoggerExt,
-} from "@fluidframework/telemetry-utils";
-import {
 	DataCorruptionError,
 	DataProcessingError,
 	UsageError,
@@ -47,6 +44,7 @@ import {
 	isFluidError,
 	normalizeError,
 	safeRaiseEvent,
+	EventEmitterWithErrorHandling,
 } from "@fluidframework/telemetry-utils/internal";
 import { v4 as uuid } from "uuid";
 
@@ -149,7 +147,7 @@ function logIfFalse(
  * messages in order regardless of possible network conditions or timings causing out of order delivery.
  */
 export class DeltaManager<TConnectionManager extends IConnectionManager>
-	extends TypedEventEmitter<IDeltaManagerInternalEvents>
+	extends EventEmitterWithErrorHandling<IDeltaManagerInternalEvents>
 	implements
 		IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>,
 		IEventProvider<IDeltaManagerInternalEvents>
@@ -411,7 +409,16 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 		private readonly _active: () => boolean,
 		createConnectionManager: (props: IConnectionManagerFactoryArgs) => TConnectionManager,
 	) {
-		super();
+		super((name, error) => {
+			this.logger.sendErrorEvent(
+				{
+					eventName: "DeltaManagerEventHandlerException",
+					name: typeof name === "string" ? name : undefined,
+				},
+				error,
+			);
+			this.close(normalizeError(error));
+		});
 		const props: IConnectionManagerFactoryArgs = {
 			incomingOpHandler: (messages: ISequencedDocumentMessage[], reason: string) => {
 				try {
@@ -550,7 +557,7 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 		minSequenceNumber: number,
 		snapshotSequenceNumber: number,
 		handler: IDeltaHandlerStrategy,
-		prefetchType: "sequenceNumber" | "cached" | "all" | "none" = "none",
+		prefetchType: "cached" | "all" | "none" = "none",
 		lastProcessedSequenceNumber: number = snapshotSequenceNumber,
 	) {
 		this.initSequenceNumber = snapshotSequenceNumber;

package/src/deltaQueue.ts

@@ -4,7 +4,7 @@
  */
 
 import { TypedEventEmitter, performance } from "@fluid-internal/client-utils";
-import { IDeltaQueue, IDeltaQueueEvents } from "@fluidframework/container-definitions";
+import { IDeltaQueue, IDeltaQueueEvents } from "@fluidframework/container-definitions/internal";
 import { assert } from "@fluidframework/core-utils/internal";
 import Deque from "double-ended-queue";
 

package/src/error.ts

@@ -6,9 +6,9 @@
 import { ContainerErrorTypes } from "@fluidframework/container-definitions/internal";
 import { ITelemetryBaseProperties } from "@fluidframework/core-interfaces";
 import { IThrottlingWarning } from "@fluidframework/core-interfaces/internal";
-import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
 import {
 	IFluidErrorBase,
+	ITelemetryLoggerExt,
 	LoggingError,
 	wrapErrorAndLog,
 } from "@fluidframework/telemetry-utils/internal";

package/src/index.ts

@@ -14,6 +14,7 @@ export {
 	ILoaderServices,
 	Loader,
 } from "./loader.js";
+export { loadContainerPaused } from "./loadPaused.js";
 export {
 	isLocationRedirectionError,
 	resolveWithLocationRedirectionHandling,

package/src/loadPaused.ts

@@ -0,0 +1,140 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ILoader, LoaderHeader } from "@fluidframework/container-definitions/internal";
+import { IRequest } from "@fluidframework/core-interfaces";
+import { GenericError } from "@fluidframework/telemetry-utils/internal";
+import type { IErrorBase } from "@fluidframework/core-interfaces";
+
+/* eslint-disable jsdoc/check-indentation */
+
+/**
+ * Loads container and leaves it in a state where it does not process any ops.
+ * Container instance returned by this function is in special mode where some functionality that is available in normal use will not work correctly
+ * with instance of container returned by this function. Some examples:
+ * 1. calling IContainer.connect() will have very little impact on this container as it will not process ops.
+ * 2. functionality like waitContainerToCatchUp() or waiting for ops in any other way would hand infinitely, as this container is not processing ops
+ * 3. No changes can be made to this container - they will be lost.
+ *
+ * If sequence number is provided, loads up to this sequence number and stops there, otherwise stops immediately after loading snapshot.
+ * In all cases, container is returned disconnected & paused, or an exception is thrown
+ * Notes:
+ * 1. Ignores LoaderHeader.loadMode headers. Container is always returned with ops applied upt to provided sequence number,
+ *    or no ops applied at all (if sequence number is not provided)
+ * 2. This call can hang infinitately if disconnected from internet (or hit some other conditions, like 429 storm).
+ *    Compare to Container.load() experience (with default settings) - it either returns failure right away, or succeeds, with
+ *    ops fetching / delta connection happening in parallel / after container load flow, and thus providing an object (Container instance) to observe
+ *    network connectivity issues / ability to cancel (IContainer.disconnect) or close container (IContainer.close)
+ *    This flow needs to fetch ops (potentially connecting to delta connection), and any retriable errors on this path result in infinite retry.
+ *    If you need to cancel that process, consider supplying AbortSignal parameter.
+ * @param loader - loader instance to use to load container
+ * @param request - request identifying container instance / load parameters. LoaderHeader.loadMode headers are ignored (see above)
+ * @param loadToSequenceNumber - optional sequence number. If provided, ops are processed up to this sequence number.
+ * @param signal - optional abort signal that can be used to cancel waiting for the ops.
+ * @returns IContainer instance
+ *
+ * @internal
+ */
+export async function loadContainerPaused(
+	loader: ILoader,
+	request: IRequest,
+	loadToSequenceNumber?: number,
+	signal?: AbortSignal,
+) {
+	const container = await loader.resolve({
+		url: request.url,
+		headers: {
+			...request.headers,
+			// ensure we do not process any ops, such that we can examine container before ops starts to flow.
+			[LoaderHeader.loadMode]: { opsBeforeReturn: undefined, deltaConnection: "none" },
+		},
+	});
+
+	// Force readonly mode - this will ensure we don't receive an error for the lack of join op
+	container.forceReadonly?.(true);
+
+	const dm = container.deltaManager;
+	const lastProcessedSequenceNumber = dm.initialSequenceNumber;
+
+	const pauseContainer = () => {
+		void dm.inbound.pause();
+		void dm.outbound.pause();
+	};
+
+	// Happy path - we are already there.
+	if (
+		loadToSequenceNumber === undefined ||
+		lastProcessedSequenceNumber === loadToSequenceNumber
+	) {
+		// If we have already reached the desired sequence number, call pauseContainer() to pause immediately.
+		pauseContainer();
+		return container;
+	}
+
+	// If we are trying to pause at a specific sequence number, ensure the latest snapshot is not newer than the desired sequence number.
+	if (lastProcessedSequenceNumber > loadToSequenceNumber) {
+		const error = new GenericError(
+			"Cannot satisfy request to pause the container at the specified sequence number. Most recent snapshot is newer than the specified sequence number.",
+		);
+		container.close(error);
+		throw error;
+	}
+
+	let opHandler: () => void;
+	let onAbort: () => void;
+	let onClose: (error?: IErrorBase) => void;
+
+	const promise = new Promise<void>((resolve, rejectArg) => {
+		onAbort = () => rejectArg(new GenericError("Canceled due to cancellation request."));
+		onClose = (error?: IErrorBase) => rejectArg(error);
+
+		// We need to setup a listener to stop op processing once we reach the desired sequence number (if specified).
+		opHandler = () => {
+			// If there is a specified sequence number, keep processing until we reach it.
+			if (
+				loadToSequenceNumber !== undefined &&
+				dm.lastSequenceNumber >= loadToSequenceNumber
+			) {
+				// Pause op processing once we have processed the desired number of ops.
+				pauseContainer();
+				resolve();
+			}
+		};
+
+		// If we have not yet reached the desired sequence number, setup a listener to pause once we reach it.
+		signal?.addEventListener("abort", onAbort);
+		container.on("op", opHandler);
+		container.on("closed", onClose);
+	});
+
+	// There are no guarantees on when ops will land in storage.
+	// No guarantees that driver implements ops caching (i.e. ops observed in previous session can be served from cache)
+	// or that browser will provide caching capabilities / keep the data (localStorage).
+	// Thus, we have to ensure we connect to delta storage in order to make forward progress with ops.
+	// We also instructed not to fetch / apply any ops from storage above (to be able to install callback above before ops are processed),
+	// connect() call will fetch ops as needed.
+	container.connect();
+
+	// Wait for the ops to be processed.
+	await promise
+		.catch((error) => {
+			container.close(error);
+			throw error;
+		})
+		.finally(() => {
+			// There is not much value in leaving delta connection on. We are not processing ops, we also can't advance to "connected" state because of it.
+			// We are not sending ops (due to forceReadonly() call above). We are holding collab window and any consensus-based processes.
+			// It's better not to have connection in such case, as there are only nagatives, and no positives.
+			container.disconnect();
+
+			container.off("op", opHandler);
+			container.off("closed", onClose);
+			signal?.removeEventListener("abort", onAbort);
+		});
+
+	return container;
+}
+
+/* eslint-enable jsdoc/check-indentation */

package/src/loader.ts

@@ -26,11 +26,10 @@ import {
 	IUrlResolver,
 } from "@fluidframework/driver-definitions/internal";
 import { IClientDetails } from "@fluidframework/protocol-definitions";
-import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
 import {
+	ITelemetryLoggerExt,
 	MonitoringContext,
 	PerformanceEvent,
-	UsageError,
 	createChildMonitoringContext,
 	mixinMonitoringContext,
 	sessionStorageConfigProvider,
@@ -42,7 +41,10 @@ import { DebugLogger } from "./debugLogger.js";
 import { pkgVersion } from "./packageVersion.js";
 import { ProtocolHandlerBuilder } from "./protocol.js";
 import type { IPendingContainerState } from "./serializedStateManager.js";
-import { tryParseCompatibleResolvedUrl } from "./utils.js";
+import {
+	getAttachedContainerStateFromSerializedContainer,
+	tryParseCompatibleResolvedUrl,
+} from "./utils.js";
 
 function ensureResolvedUrlDefined(
 	resolved: IResolvedUrl | undefined,
@@ -336,7 +338,7 @@ export class Loader implements IHostLoader {
 		return PerformanceEvent.timedExecAsync(this.mc.logger, { eventName }, async () => {
 			return this.resolveCore(
 				request,
-				pendingLocalState !== undefined ? JSON.parse(pendingLocalState) : undefined,
+				getAttachedContainerStateFromSerializedContainer(pendingLocalState),
 			);
 		});
 	}
@@ -369,24 +371,6 @@ export class Loader implements IHostLoader {
 		// If set in both query string and headers, use query string.  Also write the value from the query string into the header either way.
 		request.headers[LoaderHeader.version] =
 			parsed.version ?? request.headers[LoaderHeader.version];
-		const fromSequenceNumber = request.headers[LoaderHeader.sequenceNumber] as
-			| number
-			| undefined;
-		const opsBeforeReturn = request.headers[LoaderHeader.loadMode]?.opsBeforeReturn as
-			| string
-			| undefined;
-
-		if (
-			opsBeforeReturn === "sequenceNumber" &&
-			(fromSequenceNumber === undefined || fromSequenceNumber < 0)
-		) {
-			// If opsBeforeReturn is set to "sequenceNumber", then fromSequenceNumber should be set to a non-negative integer.
-			throw new UsageError("sequenceNumber must be set to a non-negative integer");
-		} else if (opsBeforeReturn !== "sequenceNumber" && fromSequenceNumber !== undefined) {
-			// If opsBeforeReturn is not set to "sequenceNumber", then fromSequenceNumber should be undefined (default value).
-			// In this case, we should throw an error since opsBeforeReturn is not explicitly set to "sequenceNumber".
-			throw new UsageError('opsBeforeReturn must be set to "sequenceNumber"');
-		}
 
 		return this.loadContainer(request, resolvedAsFluid, pendingLocalState);
 	}
@@ -402,7 +386,6 @@ export class Loader implements IHostLoader {
 				version: request.headers?.[LoaderHeader.version] ?? undefined,
 				loadMode: request.headers?.[LoaderHeader.loadMode],
 				pendingLocalState,
-				loadToSequenceNumber: request.headers?.[LoaderHeader.sequenceNumber],
 			},
 			{
 				canReconnect: request.headers?.[LoaderHeader.reconnect],

package/src/location-redirection-utilities/resolveWithLocationRedirection.ts

@@ -4,10 +4,10 @@
  */
 
 import { IRequest, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
-import { DriverErrorTypes } from "@fluidframework/driver-definitions";
 import {
 	ILocationRedirectionError,
 	IUrlResolver,
+	DriverErrorTypes,
 } from "@fluidframework/driver-definitions/internal";
 import { createChildLogger } from "@fluidframework/telemetry-utils/internal";
 

package/src/packageVersion.ts

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

package/src/protocol.ts

@@ -61,6 +61,10 @@ export class ProtocolHandler extends ProtocolOpHandler implements IProtocolHandl
 			sendProposal,
 		);
 
+		for (const [clientId, member] of this.quorum.getMembers()) {
+			audience.addMember(clientId, member.client);
+		}
+
 		// Join / leave signals are ignored for "write" clients in favor of join / leave ops
 		this.quorum.on("addMember", (clientId, details) =>
 			audience.addMember(clientId, details.client),

package/src/retriableDocumentStorageService.ts

@@ -21,8 +21,11 @@ import {
 	ISummaryTree,
 	IVersion,
 } from "@fluidframework/protocol-definitions";
-import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
-import { GenericError, UsageError } from "@fluidframework/telemetry-utils/internal";
+import {
+	ITelemetryLoggerExt,
+	GenericError,
+	UsageError,
+} from "@fluidframework/telemetry-utils/internal";
 
 export class RetriableDocumentStorageService implements IDocumentStorageService, IDisposable {
 	private _disposed = false;