@fluidframework/container-loader 2.61.0 → 2.62.0

package/src/connectionManager.ts

@@ -3,17 +3,13 @@
  * Licensed under the MIT License.
  */
 
-import { TypedEventEmitter, performanceNow } from "@fluid-internal/client-utils";
+import { performanceNow } from "@fluid-internal/client-utils";
 import type { ICriticalContainerError } from "@fluidframework/container-definitions";
 import type {
 	IDeltaQueue,
 	ReadOnlyInfo,
 } from "@fluidframework/container-definitions/internal";
-import {
-	type IDisposable,
-	type ITelemetryBaseProperties,
-	LogLevel,
-} from "@fluidframework/core-interfaces";
+import { type ITelemetryBaseProperties, LogLevel } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import type {
 	ConnectionMode,
@@ -22,7 +18,6 @@ import type {
 } from "@fluidframework/driver-definitions";
 import {
 	type IDocumentDeltaConnection,
-	type IDocumentDeltaConnectionEvents,
 	type IDocumentService,
 	DriverErrorTypes,
 	type IAnyDriverError,
@@ -32,7 +27,6 @@ import {
 	type INackContent,
 	type ISequencedDocumentSystemMessage,
 	type ISignalClient,
-	type ITokenClaims,
 	MessageType,
 	ScopeType,
 	type ISequencedDocumentMessage,
@@ -67,6 +61,7 @@ import {
 	ReconnectMode,
 } from "./contracts.js";
 import { DeltaQueue } from "./deltaQueue.js";
+import { FrozenDeltaStream, isFrozenDeltaStreamConnection } from "./frozenServices.js";
 import { SignalType } from "./protocol.js";
 import { isDeltaStreamConnectionForbiddenError } from "./utils.js";
 
@@ -90,85 +85,6 @@ function getNackReconnectInfo(
 	);
 }
 
-/**
- * Implementation of IDocumentDeltaConnection that does not support submitting
- * or receiving ops. Used in storage-only mode.
- */
-const clientNoDeltaStream: IClient = {
-	mode: "read",
-	details: { capabilities: { interactive: true } },
-	permission: [],
-	user: { id: "storage-only client" }, // we need some "fake" ID here.
-	scopes: [],
-};
-const clientIdNoDeltaStream: string = "storage-only client";
-
-class NoDeltaStream
-	extends TypedEventEmitter<IDocumentDeltaConnectionEvents>
-	implements IDocumentDeltaConnection, IDisposable
-{
-	clientId = clientIdNoDeltaStream;
-	// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-	claims = {
-		scopes: [ScopeType.DocRead],
-	} as ITokenClaims;
-	mode: ConnectionMode = "read";
-	existing: boolean = true;
-	maxMessageSize: number = 0;
-	version: string = "";
-	initialMessages: ISequencedDocumentMessage[] = [];
-	initialSignals: ISignalMessage[] = [];
-	initialClients: ISignalClient[] = [
-		{ client: clientNoDeltaStream, clientId: clientIdNoDeltaStream },
-	];
-	serviceConfiguration: IClientConfiguration = {
-		maxMessageSize: 0,
-		blockSize: 0,
-	};
-	checkpointSequenceNumber?: number | undefined = undefined;
-	/**
-	 * Connection which is not connected to socket.
-	 * @param storageOnlyReason - Reason on why the connection to delta stream is not allowed.
-	 * @param readonlyConnectionReason - reason/error if any which lead to using NoDeltaStream.
-	 */
-	constructor(
-		public readonly storageOnlyReason?: string,
-		public readonly readonlyConnectionReason?: IConnectionStateChangeReason,
-	) {
-		super();
-	}
-	submit(messages: IDocumentMessage[]): void {
-		this.emit(
-			"nack",
-			this.clientId,
-			messages.map((operation) => {
-				return {
-					operation,
-					content: { message: "Cannot submit with storage-only connection", code: 403 },
-				};
-			}),
-		);
-	}
-	submitSignal(message: unknown): void {
-		this.emit("nack", this.clientId, {
-			operation: message,
-			content: { message: "Cannot submit signal with storage-only connection", code: 403 },
-		});
-	}
-
-	private _disposed = false;
-	public get disposed(): boolean {
-		return this._disposed;
-	}
-	public dispose(): void {
-		this._disposed = true;
-	}
-}
-
-function isNoDeltaStreamConnection(connection: unknown): connection is NoDeltaStream {
-	return connection instanceof NoDeltaStream;
-}
-
 const waitForOnline = async (): Promise<void> => {
 	// Only wait if we have a strong signal that we're offline - otherwise assume we're online.
 	if (globalThis.navigator?.onLine === false && globalThis.addEventListener !== undefined) {
@@ -377,7 +293,7 @@ export class ConnectionManager implements IConnectionManager {
 	public get readOnlyInfo(): ReadOnlyInfo {
 		let storageOnly: boolean = false;
 		let storageOnlyReason: string | undefined;
-		if (isNoDeltaStreamConnection(this.connection)) {
+		if (isFrozenDeltaStreamConnection(this.connection)) {
 			storageOnly = true;
 			storageOnlyReason = this.connection.storageOnlyReason;
 		}
@@ -589,7 +505,7 @@ export class ConnectionManager implements IConnectionManager {
 		let connection: IDocumentDeltaConnection | undefined;
 
 		if (docService.policies?.storageOnly === true) {
-			connection = new NoDeltaStream();
+			connection = new FrozenDeltaStream();
 			this.setupNewSuccessfulConnection(connection, "read", reason);
 			assert(this.pendingConnection === undefined, 0x2b3 /* "logic error" */);
 			return;
@@ -661,7 +577,7 @@ export class ConnectionManager implements IConnectionManager {
 					LogLevel.verbose,
 				);
 				if (isDeltaStreamConnectionForbiddenError(origError)) {
-					connection = new NoDeltaStream(origError.storageOnlyReason, {
+					connection = new FrozenDeltaStream(origError.storageOnlyReason, {
 						text: origError.message,
 						error: origError,
 					});
@@ -673,7 +589,7 @@ export class ConnectionManager implements IConnectionManager {
 				) {
 					// If we get out of storage error from calling joinsession, then use the NoDeltaStream object so
 					// that user can at least load the container.
-					connection = new NoDeltaStream(undefined, {
+					connection = new FrozenDeltaStream(undefined, {
 						text: origError.message,
 						error: origError,
 					});
@@ -931,7 +847,9 @@ export class ConnectionManager implements IConnectionManager {
 		this.set_readonlyPermissions(
 			readonlyPermission,
 			oldReadonlyValue,
-			isNoDeltaStreamConnection(connection) ? connection.readonlyConnectionReason : undefined,
+			isFrozenDeltaStreamConnection(connection)
+				? connection.readonlyConnectionReason
+				: undefined,
 		);
 
 		if (this._disposed) {

package/src/container.ts

@@ -380,7 +380,7 @@ interface IContainerLifecycleEvents extends IEvent {
 
 export class Container
 	extends EventEmitterWithErrorHandling<IContainerEvents>
-	implements IContainer, IContainerExperimental
+	implements IContainer, ContainerAlpha
 {
 	/**
 	 * Load an existing container.
@@ -2558,14 +2558,22 @@ export class Container
 
 /**
  * IContainer interface that includes experimental features still under development.
- * @internal
+ * @alpha @legacy @sealed
  */
-export interface IContainerExperimental extends IContainer {
+export interface ContainerAlpha extends IContainer {
 	/**
 	 * Get pending state from container. WARNING: misuse of this API can result in duplicate op
 	 * submission and potential document corruption. The blob returned MUST be deleted if and when this
 	 * container emits a "connected" event.
 	 * @returns serialized blob that can be passed to Loader.resolve()
 	 */
-	getPendingLocalState?(): Promise<string>;
+	getPendingLocalState(): Promise<string>;
+}
+
+/**
+ * Converts types to their alpha counterparts to expose alpha functionality.
+ * @legacy @alpha
+ */
+export function asLegacyAlpha(base: IContainer): ContainerAlpha {
+	return base as ContainerAlpha;
 }

package/src/createAndLoadContainerUtils.ts

@@ -21,6 +21,7 @@ import type {
 	IUrlResolver,
 } from "@fluidframework/driver-definitions/internal";
 
+import { FrozenDocumentServiceFactory } from "./frozenServices.js";
 import { Loader } from "./loader.js";
 import type { ProtocolHandlerBuilder } from "./protocol.js";
 
@@ -173,3 +174,68 @@ export async function loadExistingContainer(
 		loadExistingContainerProps.pendingLocalState,
 	);
 }
+
+/**
+ * Properties required to load a frozen container from pending state.
+ * @legacy @alpha
+ */
+export interface ILoadFrozenContainerFromPendingStateProps {
+	/**
+	 * The code loader handles loading the necessary code for running a container once it is loaded.
+	 */
+	readonly codeLoader: ICodeDetailsLoader;
+
+	/**
+	 * The url resolver used by the loader for resolving external urls into Fluid urls.
+	 */
+	readonly urlResolver: IUrlResolver;
+
+	/**
+	 * The request to resolve the container.
+	 */
+	readonly request: IRequest;
+
+	/**
+	 * Pending local state to be applied to the container.
+	 */
+	readonly pendingLocalState: string;
+
+	/**
+	 * A property bag of options/policies used by various layers to control features.
+	 */
+	readonly options?: IContainerPolicies | undefined;
+
+	/**
+	 * Scope is provided to all container and is a set of shared services for container's to integrate with their host environment.
+	 */
+	readonly scope?: FluidObject | undefined;
+
+	/**
+	 * The logger that all telemetry should be pushed to.
+	 */
+	readonly logger?: ITelemetryBaseLogger | undefined;
+
+	/**
+	 * The configuration provider which may be used to control features.
+	 */
+	readonly configProvider?: IConfigProviderBase | undefined;
+
+	/**
+	 * Client details provided in the override will be merged over the default client.
+	 */
+	readonly clientDetailsOverride?: IClientDetails | undefined;
+}
+
+/**
+ * Loads a frozen container from pending local state.
+ * @param props - Properties required to load a frozen container from pending state.
+ * @legacy @alpha
+ */
+export async function loadFrozenContainerFromPendingState(
+	props: ILoadFrozenContainerFromPendingStateProps,
+): Promise<IContainer> {
+	return loadExistingContainer({
+		...props,
+		documentServiceFactory: new FrozenDocumentServiceFactory(),
+	});
+}

package/src/frozenServices.ts

@@ -0,0 +1,162 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TypedEventEmitter } from "@fluid-internal/client-utils";
+import type { IDisposable } from "@fluidframework/core-interfaces";
+import {
+	ScopeType,
+	type ConnectionMode,
+	type IClient,
+	type IClientConfiguration,
+	type IDocumentDeltaConnection,
+	type IDocumentDeltaConnectionEvents,
+	type IDocumentDeltaStorageService,
+	type IDocumentMessage,
+	type IDocumentService,
+	type IDocumentServiceEvents,
+	type IDocumentServiceFactory,
+	type IDocumentServicePolicies,
+	type IDocumentStorageService,
+	type IResolvedUrl,
+	type ISequencedDocumentMessage,
+	type ISignalClient,
+	type ISignalMessage,
+	type ITokenClaims,
+} from "@fluidframework/driver-definitions/internal";
+
+import type { IConnectionStateChangeReason } from "./contracts.js";
+
+export class FrozenDocumentServiceFactory implements IDocumentServiceFactory {
+	async createDocumentService(resolvedUrl: IResolvedUrl): Promise<IDocumentService> {
+		return new FrozenDocumentService(resolvedUrl);
+	}
+	async createContainer(): Promise<IDocumentService> {
+		throw new Error("The FrozenDocumentServiceFactory cannot be used to create containers.");
+	}
+}
+
+class FrozenDocumentService
+	extends TypedEventEmitter<IDocumentServiceEvents>
+	implements IDocumentService
+{
+	constructor(public readonly resolvedUrl: IResolvedUrl) {
+		super();
+	}
+
+	public readonly policies: IDocumentServicePolicies = {
+		storageOnly: true,
+	};
+	async connectToStorage(): Promise<IDocumentStorageService> {
+		return frozenDocumentStorageService;
+	}
+	async connectToDeltaStorage(): Promise<IDocumentDeltaStorageService> {
+		return frozenDocumentDeltaStorageService;
+	}
+	async connectToDeltaStream(client: IClient): Promise<IDocumentDeltaConnection> {
+		return new FrozenDeltaStream();
+	}
+	dispose(): void {}
+}
+
+const frozenDocumentStorageServiceHandler = (): never => {
+	throw new Error("Operations are not supported on the FrozenDocumentStorageService.");
+};
+const frozenDocumentStorageService: IDocumentStorageService = {
+	getSnapshotTree: frozenDocumentStorageServiceHandler,
+	getSnapshot: frozenDocumentStorageServiceHandler,
+	getVersions: frozenDocumentStorageServiceHandler,
+	createBlob: frozenDocumentStorageServiceHandler,
+	readBlob: frozenDocumentStorageServiceHandler,
+	uploadSummaryWithContext: frozenDocumentStorageServiceHandler,
+	downloadSummary: frozenDocumentStorageServiceHandler,
+};
+
+const frozenDocumentDeltaStorageService: IDocumentDeltaStorageService = {
+	fetchMessages: () => ({
+		read: async () => ({
+			done: true,
+		}),
+	}),
+};
+
+const clientFrozenDeltaStream: IClient = {
+	mode: "read",
+	details: { capabilities: { interactive: true } },
+	permission: [],
+	user: { id: "storage-only client" }, // we need some "fake" ID here.
+	scopes: [],
+};
+const clientIdFrozenDeltaStream: string = "storage-only client";
+
+/**
+ * Implementation of IDocumentDeltaConnection that does not support submitting
+ * or receiving ops. Used in storage-only mode and in frozen loads.
+ */
+export class FrozenDeltaStream
+	extends TypedEventEmitter<IDocumentDeltaConnectionEvents>
+	implements IDocumentDeltaConnection, IDisposable
+{
+	clientId = clientIdFrozenDeltaStream;
+	// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+	claims = {
+		scopes: [ScopeType.DocRead],
+	} as ITokenClaims;
+	mode: ConnectionMode = "read";
+	existing: boolean = true;
+	maxMessageSize: number = 0;
+	version: string = "";
+	initialMessages: ISequencedDocumentMessage[] = [];
+	initialSignals: ISignalMessage[] = [];
+	initialClients: ISignalClient[] = [
+		{ client: clientFrozenDeltaStream, clientId: clientIdFrozenDeltaStream },
+	];
+	serviceConfiguration: IClientConfiguration = {
+		maxMessageSize: 0,
+		blockSize: 0,
+	};
+	checkpointSequenceNumber?: number | undefined = undefined;
+	/**
+	 * Connection which is not connected to socket.
+	 * @param storageOnlyReason - Reason on why the connection to delta stream is not allowed.
+	 * @param readonlyConnectionReason - reason/error if any which lead to using FrozenDeltaStream.
+	 */
+	constructor(
+		public readonly storageOnlyReason?: string,
+		public readonly readonlyConnectionReason?: IConnectionStateChangeReason,
+	) {
+		super();
+	}
+	submit(messages: IDocumentMessage[]): void {
+		this.emit(
+			"nack",
+			this.clientId,
+			messages.map((operation) => {
+				return {
+					operation,
+					content: { message: "Cannot submit with storage-only connection", code: 403 },
+				};
+			}),
+		);
+	}
+	submitSignal(message: unknown): void {
+		this.emit("nack", this.clientId, {
+			operation: message,
+			content: { message: "Cannot submit signal with storage-only connection", code: 403 },
+		});
+	}
+
+	private _disposed = false;
+	public get disposed(): boolean {
+		return this._disposed;
+	}
+	public dispose(): void {
+		this._disposed = true;
+	}
+}
+export function isFrozenDeltaStreamConnection(
+	connection: unknown,
+): connection is FrozenDeltaStream {
+	return connection instanceof FrozenDeltaStream;
+}

package/src/index.ts

@@ -4,15 +4,17 @@
  */
 
 export { ConnectionState } from "./connectionState.js";
-export { type IContainerExperimental, waitContainerToCatchUp } from "./container.js";
+export { type ContainerAlpha, waitContainerToCatchUp, asLegacyAlpha } from "./container.js";
 export {
 	createDetachedContainer,
 	loadExistingContainer,
 	rehydrateDetachedContainer,
+	loadFrozenContainerFromPendingState,
 	type ICreateAndLoadContainerProps,
 	type ICreateDetachedContainerProps,
 	type ILoadExistingContainerProps,
 	type IRehydrateDetachedContainerProps,
+	type ILoadFrozenContainerFromPendingStateProps,
 } from "./createAndLoadContainerUtils.js";
 export {
 	type ICodeDetailsLoader,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-loader";
-export const pkgVersion = "2.61.0";
+export const pkgVersion = "2.62.0";