feat(container-loader): add readOnly option to loadFrozenContainerFromPendingState

.changeset/frozen-container-readonly-option.md

@@ -0,0 +1,13 @@
+---
+"@fluidframework/container-loader": minor
+"__section": feature
+---
+Add readOnly option to loadFrozenContainerFromPendingState
+
+`loadFrozenContainerFromPendingState` and `createFrozenDocumentServiceFactory` now accept an optional `readOnly` parameter (default `true`, preserving existing behavior).
+
+When `readOnly: false`, the frozen container loads as writable so the runtime accepts DDS submissions. The container stays `Connected` against the synthetic `FrozenDeltaStream`: `ConnectionManager.sendMessages` recognizes it as the live connection and short-circuits before the read-mode reconnect branch, dropping outbound messages at the connection-manager layer. Submitted ops accumulate in the runtime's pending-state manager so `getPendingLocalState()` can capture them.
+
+Use `readOnly: false` when the caller wants to load a frozen container, apply additional local changes, and capture the resulting pending state via `getPendingLocalState()`.
+
+Also: `FrozenDeltaStream.submitSignal` is now a silent no-op for both variants. The pre-existing read-only-variant behavior was a 403 nack on signals; this PR drops it for both variants because (a) for the writable variant a stray signal would close or reconnect the container, and (b) signals are ephemeral and dropping them is the correct behavior with no upstream. `FrozenDeltaStream.submit` continues to nack defensively.

packages/loader/container-loader/api-report/container-loader.legacy.alpha.api.md

@@ -24,7 +24,7 @@ export interface ContainerAlpha extends IContainer {
 export function createDetachedContainer(createDetachedContainerProps: ICreateDetachedContainerProps): Promise<IContainer>;
 
 // @alpha @legacy
-export function createFrozenDocumentServiceFactory(factory?: IDocumentServiceFactory | Promise<IDocumentServiceFactory>): IDocumentServiceFactory;
+export function createFrozenDocumentServiceFactory(factory?: IDocumentServiceFactory | Promise<IDocumentServiceFactory>, readOnly?: boolean): IDocumentServiceFactory;
 
 // @beta @legacy (undocumented)
 export interface IBaseProtocolHandler {
@@ -106,6 +106,7 @@ export interface ILoadExistingContainerProps extends ICreateAndLoadContainerProp
 // @alpha @legacy
 export interface ILoadFrozenContainerFromPendingStateProps extends ILoadExistingContainerProps {
     readonly pendingLocalState: string;
+    readonly readOnly?: boolean;
 }
 
 // @alpha @legacy

packages/loader/container-loader/src/connectionManager.ts

@@ -582,9 +582,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;
@@ -594,9 +594,8 @@ 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 FrozenDeltaStream(undefined, {
-						text: origError.message,
-						error: origError,
+					connection = new FrozenDeltaStream({
+						readonlyConnectionReason: { text: origError.message, error: origError },
 					});
 					requestedMode = "read";
 					break;
@@ -1089,6 +1088,21 @@ export class ConnectionManager implements IConnectionManager {
 
 	public sendMessages(messages: IDocumentMessage[]): void {
 		assert(this.connected, 0x2b4 /* "not connected on sending ops!" */);
+		// FrozenDeltaStream short-circuit: writable-frozen containers
+		// (`loadFrozenContainerFromPendingState({ readOnly: false })`) attach a
+		// FrozenDeltaStream 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. The
+		// read-only variant should never reach here (its `storageOnly` policy keeps the
+		// runtime from submitting), but covering it too is harmless defense-in-depth.
+		if (this.connection instanceof FrozenDeltaStream) {
+			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.

packages/loader/container-loader/src/createAndLoadContainerUtils.ts

@@ -229,6 +229,28 @@ 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.
+	 */
+	readonly readOnly?: boolean;
 }
 
 /**
@@ -241,7 +263,10 @@ export async function loadFrozenContainerFromPendingState(
 ): Promise<IContainer> {
 	return loadExistingContainer({
 		...props,
-		documentServiceFactory: createFrozenDocumentServiceFactory(props.documentServiceFactory),
+		documentServiceFactory: createFrozenDocumentServiceFactory(
+			props.documentServiceFactory,
+			props.readOnly,
+		),
 	});
 }