@fluidframework/container-loader 2.93.0 → 2.101.0

package/src/connectionManager.ts

@@ -63,7 +63,11 @@ import {
 	ReconnectMode,
 } from "./contracts.js";
 import { DeltaQueue } from "./deltaQueue.js";
-import { FrozenDeltaStream, isFrozenDeltaStreamConnection } from "./frozenServices.js";
+import {
+	FrozenDeltaStream,
+	isFrozenDeltaStreamConnection,
+	isWritableFrozenDeltaStreamConnection,
+} from "./frozenServices.js";
 import { SignalType } from "./protocol.js";
 import { isDeltaStreamConnectionForbiddenError } from "./utils.js";
 
@@ -344,6 +348,7 @@ export class ConnectionManager implements IConnectionManager {
 		reconnectAllowed: boolean,
 		private readonly logger: ITelemetryLoggerExt,
 		private readonly props: IConnectionManagerFactoryArgs,
+		private maxInitialConnectionAttempts?: number,
 	) {
 		this.clientDetails = this.client.details;
 		this.defaultReconnectionMode = this.client.mode;
@@ -581,9 +586,9 @@ export class ConnectionManager implements IConnectionManager {
 					LogLevel.verbose,
 				);
 				if (isDeltaStreamConnectionForbiddenError(origError)) {
-					connection = new FrozenDeltaStream(origError.storageOnlyReason, {
-						text: origError.message,
-						error: origError,
+					connection = new FrozenDeltaStream({
+						storageOnlyReason: origError.storageOnlyReason,
+						readonlyConnectionReason: { text: origError.message, error: origError },
 					});
 					requestedMode = "read";
 					break;
@@ -591,11 +596,10 @@ export class ConnectionManager implements IConnectionManager {
 					isFluidError(origError) &&
 					origError.errorType === DriverErrorTypes.outOfStorageError
 				) {
-					// If we get out of storage error from calling joinsession, then use the NoDeltaStream object so
+					// If we get out of storage error from calling joinsession, then use the FrozenDeltaStream object so
 					// that user can at least load the container.
-					connection = new FrozenDeltaStream(undefined, {
-						text: origError.message,
-						error: origError,
+					connection = new FrozenDeltaStream({
+						readonlyConnectionReason: { text: origError.message, error: origError },
 					});
 					requestedMode = "read";
 					break;
@@ -622,6 +626,17 @@ export class ConnectionManager implements IConnectionManager {
 
 				lastError = origError;
 
+				// When maxInitialConnectionAttempts is set, do not retry beyond the allowed attempts.
+				// The consumer will own the retry policy.
+				if (
+					this.maxInitialConnectionAttempts !== undefined &&
+					connectRepeatCount >= this.maxInitialConnectionAttempts
+				) {
+					const error = normalizeError(origError, { props: fatalConnectErrorProp });
+					this.props.closeHandler(error);
+					throw error;
+				}
+
 				// We will not perform retries if the container disconnected and the ReconnectMode is set to Disabled or Never
 				// so break out of the re-connecting while-loop after first attempt
 				if (this.reconnectMode !== ReconnectMode.Enabled) {
@@ -688,6 +703,11 @@ export class ConnectionManager implements IConnectionManager {
 			return;
 		}
 
+		// Clear the max connection attempts limit now that a connection has been established.
+		// The limit is only intended to scope initial connection retries;
+		// once connected, normal reconnect behavior should apply.
+		this.maxInitialConnectionAttempts = undefined;
+
 		this.setupNewSuccessfulConnection(connection, requestedMode, reason);
 	}
 
@@ -1072,6 +1092,25 @@ export class ConnectionManager implements IConnectionManager {
 
 	public sendMessages(messages: IDocumentMessage[]): void {
 		assert(this.connected, 0x2b4 /* "not connected on sending ops!" */);
+		// WritableFrozenDeltaStream short-circuit: writable-frozen containers
+		// (`loadFrozenContainerFromPendingState({ readOnly: false })`) attach a
+		// WritableFrozenDeltaStream as the live connection. Its `mode` is "read" (advertising
+		// "write" would imply quorum membership we cannot honor), so a runtime submit
+		// would otherwise fall into the read-mode reconnect branch below. That branch
+		// schedules `reconnect("write")`, which under `ReconnectMode.Never`
+		// (`allowReconnect: false`) calls `closeHandler` and closes the container — the
+		// opposite of what writable-frozen wants. Drop the messages here: the runtime's
+		// outbox keeps them in `pendingStateManager` so `getPendingLocalState()` can
+		// capture them, which is the entire point of the writable-frozen flow.
+		//
+		// Match only the writable variant (a sibling class, not a subclass) so the read-only
+		// `FrozenDeltaStream` retains its `submit` 403-nack tripwire — a stray submit on a
+		// storage-only frozen connection signals an upstream invariant break and should
+		// remain observable. The read-only variant shouldn't reach here in normal flow anyway
+		// (its `storageOnly` policy keeps the runtime from submitting).
+		if (isWritableFrozenDeltaStreamConnection(this.connection)) {
+			return;
+		}
 		// If connection is "read" or implicit "read" (got leave op for "write" connection),
 		// then op can't make it through - we will get a nack if op is sent.
 		// We can short-circuit this process.

package/src/connectionStateHandler.ts

@@ -5,6 +5,7 @@
 
 import type { IDeltaManager } from "@fluidframework/container-definitions/internal";
 import type { ITelemetryBaseProperties } from "@fluidframework/core-interfaces";
+import { LogLevel } from "@fluidframework/core-interfaces";
 import { assert, Timer } from "@fluidframework/core-utils/internal";
 import type { IClient, ISequencedClient } from "@fluidframework/driver-definitions";
 import type { IAnyDriverError } from "@fluidframework/driver-definitions/internal";
@@ -687,15 +688,19 @@ export class ConnectionStateHandler implements IConnectionStateHandler {
 				this.prevClientLeftTimer.restart();
 			} else {
 				// Adding this event temporarily so that we can get help debugging if something goes wrong.
-				this.handler.logger.sendTelemetryEvent({
-					eventName: "noWaitOnDisconnected",
-					details: JSON.stringify({
-						clientId: this._clientId,
-						inQuorum: currentClientInQuorum,
-						waitingForLeaveOp: this.waitingForLeaveOp,
-						hadOutstandingOps: this.handler.shouldClientJoinWrite(),
-					}),
-				});
+				this.handler.logger.sendTelemetryEvent(
+					{
+						eventName: "noWaitOnDisconnected",
+						details: JSON.stringify({
+							clientId: this._clientId,
+							inQuorum: currentClientInQuorum,
+							waitingForLeaveOp: this.waitingForLeaveOp,
+							hadOutstandingOps: this.handler.shouldClientJoinWrite(),
+						}),
+					},
+					undefined, // error
+					LogLevel.info,
+				);
 			}
 		}
 

package/src/container.ts

@@ -84,7 +84,7 @@ import {
 } from "@fluidframework/driver-utils/internal";
 import {
 	type TelemetryEventCategory,
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 	EventEmitterWithErrorHandling,
 	GenericError,
 	type IFluidErrorBase,
@@ -94,6 +94,7 @@ import {
 	connectedEventName,
 	createChildLogger,
 	createChildMonitoringContext,
+	extractTelemetryLoggerExt,
 	formatTick,
 	normalizeError,
 	raiseConnectedEvent,
@@ -429,7 +430,7 @@ export class Container
 	private readonly codeLoader: ICodeDetailsLoader;
 	private readonly options: ILoaderOptions;
 	private readonly scope: FluidObject;
-	private readonly subLogger: ITelemetryLoggerExt;
+	private readonly subLogger: TelemetryLoggerExt;
 	private readonly detachedBlobStorage: MemoryDetachedBlobStorage | undefined;
 	private readonly protocolHandlerBuilder: InternalProtocolHandlerBuilder;
 	private readonly signalAudience = new Audience();
@@ -858,7 +859,7 @@ export class Container
 				logger: this.mc.logger,
 				// WARNING: logger on this context should not including getters like containerConnectionState above (on this.subLogger),
 				// as that will result in attempt to dereference this.connectionStateHandler from this call while it's still undefined.
-				mc: loggerToMonitoringContext(subLogger),
+				mc: loggerToMonitoringContext(extractTelemetryLoggerExt(subLogger)),
 				connectionStateChanged: (value, oldState, reason) => {
 					this.logConnectionStateChangeTelemetry(value, oldState, reason);
 					if (this.loaded) {
@@ -1069,6 +1070,7 @@ export class Container
 
 				this.connectionStateHandler.dispose();
 				this.serializedStateManager.dispose();
+				this._runtime?.close?.();
 			} catch (newError) {
 				this.mc.logger.sendErrorEvent({ eventName: "ContainerCloseException" }, newError);
 			}
@@ -1103,6 +1105,8 @@ export class Container
 						eventName: "ContainerDispose",
 						// Only log error if container isn't closed
 						category: !this.closed && error !== undefined ? "error" : "generic",
+						isDirty: this.isDirty,
+						lastSequenceNumber: this._deltaManager.lastSequenceNumber,
 					},
 					error,
 				);
@@ -1609,7 +1613,11 @@ export class Container
 			this.connectToDeltaStream(connectionArgs);
 		}
 
-		this.storageAdapter.connectToService(this.service);
+		// When DisableLoadConnectionRetries is enabled, use no internal retries.
+		// The consumer will own the retry policy.
+		const disableLoadRetries =
+			this.mc.config.getBoolean("Fluid.Container.DisableLoadConnectionRetries") === true;
+		this.storageAdapter.connectToService(this.service, disableLoadRetries ? 0 : undefined);
 
 		this.attachmentData = {
 			state: AttachState.Attached,
@@ -1994,6 +2002,8 @@ export class Container
 
 	private createDeltaManager(): DeltaManager<ConnectionManager> {
 		const serviceProvider = (): IDocumentService | undefined => this.service;
+		const disableLoadConnectionRetries =
+			this.mc.config.getBoolean("Fluid.Container.DisableLoadConnectionRetries") === true;
 		const deltaManager = new DeltaManager<ConnectionManager>(
 			serviceProvider,
 			createChildLogger({ logger: this.subLogger, namespace: "DeltaManager" }),
@@ -2006,6 +2016,7 @@ export class Container
 					this._canReconnect,
 					createChildLogger({ logger: this.subLogger, namespace: "ConnectionManager" }),
 					props,
+					disableLoadConnectionRetries ? 1 : undefined /* maxInitialConnectionAttempts */,
 				),
 		);
 
@@ -2386,6 +2397,9 @@ export class Container
 				this.subLogger,
 				{ eventName: "CodeLoad" },
 				async () => this.codeLoader.load(codeDetails),
+				undefined, // markers
+				undefined, // sampleThreshold
+				LogLevel.info,
 			);
 
 			this._loadedModule = {

package/src/containerStorageAdapter.ts

@@ -36,13 +36,32 @@ import type {
 import { convertSnapshotInfoToSnapshot } from "./utils.js";
 
 /**
- * Stringified blobs from a summary/snapshot tree.
+ * Stringified blobs from a summary/snapshot tree, keyed by blob id.
+ * Values are **UTF-8-encoded** — this is the right encoding for JSON or
+ * other text the runtime authors and consumes through this map. For
+ * arbitrary binary payloads (e.g. attachment blob contents), use
+ * {@link IBase64BlobContents} instead; a UTF-8 round-trip silently
+ * corrupts non-UTF-8 byte sequences with replacement characters.
  * @internal
  */
 export interface ISerializableBlobContents {
 	[id: string]: string;
 }
 
+/**
+ * Stringified blobs inlined in a summary/snapshot tree, keyed by blob id.
+ * Values are **base64-encoded** raw bytes. Used for attachment-blob
+ * payloads, which may carry arbitrary binary data (images, encrypted
+ * blobs, etc.). Mirrors the encoding used by the runtime's own
+ * pending-blob serializer in `BlobManager`. Structurally identical to
+ * {@link ISerializableBlobContents}; the two types exist to keep the
+ * encoding contract visible at every call site.
+ * @internal
+ */
+export interface IBase64BlobContents {
+	[id: string]: string;
+}
+
 /**
  * This class wraps the actual storage and make sure no wrong apis are called according to
  * container attach state.
@@ -104,7 +123,7 @@ export class ContainerStorageAdapter
 		this.disposed = true;
 	}
 
-	public connectToService(service: IDocumentService): void {
+	public connectToService(service: IDocumentService, maxRetries?: number): void {
 		if (!(this._storageService instanceof BlobOnlyStorage)) {
 			return;
 		}
@@ -113,6 +132,7 @@ export class ContainerStorageAdapter
 		const retriableStorage = (this._storageService = new RetriableDocumentStorageService(
 			storageServiceP,
 			this.logger,
+			maxRetries,
 		));
 
 		// A storage service wrapper which intercept calls to uploadSummaryWithContext and ensure they include

package/src/createAndLoadContainerUtils.ts

@@ -19,11 +19,16 @@ import type {
 import type { IClientDetails } from "@fluidframework/driver-definitions";
 import type {
 	IDocumentServiceFactory,
+	ISequencedDocumentMessage,
+	ISnapshot,
+	ISnapshotTree,
 	IUrlResolver,
 } from "@fluidframework/driver-definitions/internal";
-import { DriverHeader } from "@fluidframework/driver-definitions/internal";
+import { DriverHeader, FetchSource } from "@fluidframework/driver-definitions/internal";
+import { getSnapshotTree } from "@fluidframework/driver-utils/internal";
 import {
 	GenericError,
+	UsageError,
 	normalizeError,
 	createChildMonitoringContext,
 	mixinMonitoringContext,
@@ -33,16 +38,28 @@ import {
 } from "@fluidframework/telemetry-utils/internal";
 import { v4 as uuid } from "uuid";
 
+import {
+	captureReferencedAttachmentBlobs,
+	extractBlobAttachReferences,
+	inlineAttachmentBlobsByReference,
+	parseGcSnapshotData,
+	readReferencedSnapshotBlobs,
+	snapshotHasLoadingGroups,
+	unreferencedAttachmentBlobLocalIds,
+	type IBlobAttachReference,
+} from "./captureReferencedContents.js";
 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 { IPendingContainerState } from "./serializedStateManager.js";
 import type {
 	LoadSummarizerSummaryResult,
 	OnDemandSummaryResults,
 	SummarizeOnDemandResults,
 } from "./summarizerResultTypes.js";
+import { getDocumentAttributes } from "./utils.js";
 
 interface OnDemandSummarizeResultsPromises {
 	readonly summarySubmitted: Promise<SummarizeOnDemandResults["summarySubmitted"]>;
@@ -229,6 +246,34 @@ export interface ILoadFrozenContainerFromPendingStateProps
 	 * Pending local state to be applied to the container.
 	 */
 	readonly pendingLocalState: string;
+
+	/**
+	 * Controls whether the frozen container is surfaced as read-only.
+	 *
+	 * Defaults to `true`. When `true`, the container reports `readOnlyInfo.readonly === true`
+	 * with `storageOnly === true`, matching the historical behavior of frozen loads.
+	 *
+	 * When `false`, the container loads as writable so the runtime will accept DDS submissions.
+	 * The connection itself stays `Connected`: the connection manager recognizes the synthetic
+	 * frozen delta stream and drops outbound messages at the network layer, so no read→write
+	 * reconnect is attempted. Local DDS state continues to update via optimistic apply, and
+	 * submitted ops accumulate in the runtime's pending-state manager. Use this when callers
+	 * want to accrue and capture pending state without publishing it.
+	 *
+	 * @remarks
+	 * The flag uses negative polarity (`readOnly`) rather than a positive opt-in (`writable`)
+	 * to align with `IContainer.readOnlyInfo.readonly`, which is the established surface for
+	 * read/write state on a loaded container. A future positive-polarity option can layer on
+	 * top of this without breaking callers, but flipping the polarity now would split readers
+	 * between two conventions for the same concept.
+	 *
+	 * Subsystem behavior is unchanged from the read-only frozen path regardless of `readOnly`:
+	 * storage operations still throw (only `readBlob` is supported); summarizer / id-compressor
+	 * never fire because no acks arrive; the quorum is whatever was captured in pending state
+	 * and gains no members during the writable-frozen lifetime. The only behavioral delta is
+	 * that the runtime accepts DDS submissions and accumulates them in `pendingStateManager`.
+	 */
+	readonly readOnly?: boolean;
 }
 
 /**
@@ -241,10 +286,192 @@ export async function loadFrozenContainerFromPendingState(
 ): Promise<IContainer> {
 	return loadExistingContainer({
 		...props,
-		documentServiceFactory: createFrozenDocumentServiceFactory(props.documentServiceFactory),
+		documentServiceFactory: createFrozenDocumentServiceFactory(
+			props.documentServiceFactory,
+			props.readOnly,
+		),
 	});
 }
 
+/**
+ * Properties for {@link captureFullContainerState}.
+ * @legacy @alpha
+ */
+export interface ICaptureFullContainerStateProps {
+	/**
+	 * The url resolver used to resolve the request into a Fluid resolved url.
+	 */
+	readonly urlResolver: IUrlResolver;
+	/**
+	 * The document service factory used to construct the driver services
+	 * against which the state is captured.
+	 */
+	readonly documentServiceFactory: IDocumentServiceFactory;
+	/**
+	 * The request identifying the container whose state is to be captured.
+	 */
+	readonly request: IRequest;
+	/**
+	 * Optional logger for driver-side telemetry.
+	 */
+	readonly logger?: ITelemetryBaseLogger | undefined;
+}
+
+/**
+ * Captures the current state of an attached container using only driver-level
+ * services, without instantiating a runtime or loading a full container. The
+ * returned string is a serialized pending container state in the same wire
+ * format produced by a live container's pending-state serialization, and can
+ * be handed to {@link loadExistingContainer} as `pendingLocalState`.
+ *
+ * The output is a self-contained view of the container's referenced graph:
+ * the latest snapshot, inlined contents of every blob reachable through
+ * referenced subtrees, inlined contents of every referenced attachment blob
+ * keyed by storage id, and all ops with sequence numbers after the base
+ * snapshot's sequence number (as read from its attributes blob).
+ *
+ * Reachability respects GC. Snapshot subtrees flagged `unreferenced: true`
+ * are skipped (their contents are not inlined). Attachment blobs that GC has
+ * marked unreferenced, tombstoned, or deleted are skipped. When the snapshot
+ * has no GC tree (GC disabled or pre-GC document), no filtering is applied.
+ *
+ * Blob reads on load hit the `ContainerStorageAdapter` cache populated from
+ * the captured `snapshotBlobs` map, so a frozen loader can serve the full
+ * referenced graph without a live storage service.
+ *
+ * `pendingRuntimeState` is `undefined` — no runtime is instantiated — so the
+ * output cannot carry DDS-level in-flight changes. It is intended for state
+ * relay, inspection, and durable-state snapshot use cases.
+ *
+ * Containers that declare loading groups are not yet supported: the function
+ * throws `UsageError` if any referenced subtree carries a `groupId`. Group
+ * snapshots would need a separate prefetch + serialization path; until there
+ * is a known consumer and end-to-end coverage, the capture refuses rather
+ * than silently producing pending state that omits group data.
+ *
+ * Note: if a new snapshot lands between the snapshot fetch and the ops fetch,
+ * the returned state may not reflect the very latest snapshot, but remains
+ * internally consistent: ops are anchored to the snapshot that was captured.
+ *
+ * No `mixinMonitoringContext` / `configProvider` is wired here, deliberately
+ * diverging from the sibling entry points in this file. The function reads
+ * no feature flags and instantiates no runtime, so there is nothing for a
+ * monitoring context to gate or attribute. If a future change introduces
+ * config-gated behavior or runtime-attributed telemetry, add the wiring
+ * back together with that change.
+ * @legacy @alpha
+ */
+export async function captureFullContainerState({
+	urlResolver,
+	documentServiceFactory,
+	request,
+	logger,
+}: ICaptureFullContainerStateProps): Promise<string> {
+	const resolvedUrl = await urlResolver.resolve(request);
+	if (resolvedUrl === undefined) {
+		throw new UsageError("Failed to resolve request to a Fluid URL");
+	}
+
+	const documentService = await documentServiceFactory.createDocumentService(
+		resolvedUrl,
+		logger,
+	);
+	try {
+		const storage = await documentService.connectToStorage();
+
+		const versions = await storage.getVersions(
+			// `null` signals "latest"
+			// eslint-disable-next-line unicorn/no-null
+			null,
+			1,
+			"captureFullContainerState",
+			FetchSource.noCache,
+		);
+		const version = versions[0];
+		const snapshot: ISnapshot | ISnapshotTree | undefined =
+			storage.getSnapshot === undefined
+				? ((await storage.getSnapshotTree(version, "captureFullContainerState")) ?? undefined)
+				: await storage.getSnapshot({
+						cacheSnapshot: false,
+						versionId: version?.id,
+						scenarioName: "captureFullContainerState",
+					});
+		if (snapshot === undefined) {
+			throw new GenericError("Failed to fetch snapshot for captureFullContainerState");
+		}
+
+		const baseSnapshot = getSnapshotTree(snapshot);
+		if (snapshotHasLoadingGroups(baseSnapshot)) {
+			throw new UsageError(
+				"captureFullContainerState does not yet support containers with loading groups",
+			);
+		}
+		const attributes = await getDocumentAttributes(storage, baseSnapshot);
+		const gcData = await parseGcSnapshotData(baseSnapshot, storage);
+		// Structural snapshot blobs (JSON/text the runtime authored) are
+		// UTF-8-encoded; attachment blobs may carry arbitrary binary bytes
+		// and are base64-encoded. Keep them on separate fields of the
+		// pending state so the load side can apply the matching decoder
+		// without ambiguity. See IPendingContainerState.attachmentBlobContents.
+		const [snapshotBlobs, attachmentBlobContents] = await Promise.all([
+			readReferencedSnapshotBlobs(snapshot, storage), // utf8 encoded
+			captureReferencedAttachmentBlobs(baseSnapshot, storage, gcData), // base64 encoded
+		]);
+
+		const deltaStorage = await documentService.connectToDeltaStorage();
+		const opsStream = deltaStorage.fetchMessages(
+			attributes.sequenceNumber + 1,
+			undefined,
+			undefined,
+			false,
+			"captureFullContainerState",
+		);
+		const savedOps: ISequencedDocumentMessage[] = [];
+		const postSnapshotBlobReferences: IBlobAttachReference[] = [];
+		let opsResult = await opsStream.read();
+		while (!opsResult.done) {
+			for (const op of opsResult.value) {
+				savedOps.push(op);
+				// Blobs uploaded after the base snapshot are not in its
+				// `.blobs` redirect table, so `captureReferencedAttachmentBlobs`
+				// did not see them. The wire-format BlobAttach op carries
+				// `(localId, storageId)` in its metadata; collect those here so
+				// we can backfill the bytes before sealing the artifact.
+				const refs = extractBlobAttachReferences(op);
+				if (refs.length > 0) {
+					postSnapshotBlobReferences.push(...refs);
+				}
+			}
+			opsResult = await opsStream.read();
+		}
+
+		if (postSnapshotBlobReferences.length > 0) {
+			const added = await inlineAttachmentBlobsByReference(
+				postSnapshotBlobReferences,
+				storage,
+				unreferencedAttachmentBlobLocalIds(gcData),
+				attachmentBlobContents,
+			);
+			Object.assign(attachmentBlobContents, added);
+		}
+
+		const pendingState: IPendingContainerState = {
+			attached: true,
+			baseSnapshot,
+			snapshotBlobs,
+			attachmentBlobContents:
+				Object.keys(attachmentBlobContents).length === 0 ? undefined : attachmentBlobContents,
+			loadedGroupIdSnapshots: undefined,
+			pendingRuntimeState: undefined,
+			savedOps,
+			url: resolvedUrl.url,
+		};
+		return JSON.stringify(pendingState);
+	} finally {
+		documentService.dispose();
+	}
+}
+
 /**
  * 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.