@fluidframework/container-loader 2.100.0 → 2.101.0

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.