@fluidframework/container-runtime 2.33.2 → 2.40.0

package/src/dataStoreContext.ts

@@ -15,7 +15,6 @@ import {
 	FluidObject,
 	IDisposable,
 	ITelemetryBaseProperties,
-	type IErrorBase,
 	type IEvent,
 } from "@fluidframework/core-interfaces";
 import {
@@ -52,7 +51,6 @@ import {
 	IFluidDataStoreContext,
 	IFluidDataStoreContextDetached,
 	IFluidDataStoreRegistry,
-	IFluidParentContext,
 	IGarbageCollectionDetailsBase,
 	IProvideFluidDataStoreFactory,
 	ISummarizeInternalResult,
@@ -64,6 +62,7 @@ import {
 	type IPendingMessagesState,
 	type IRuntimeMessageCollection,
 	type IFluidDataStoreFactory,
+	type IFluidParentContext,
 } from "@fluidframework/runtime-definitions/internal";
 import {
 	addBlobToSummary,
@@ -81,6 +80,7 @@ import {
 	tagCodeArtifacts,
 } from "@fluidframework/telemetry-utils/internal";
 
+import type { IFluidParentContextPrivate } from "./channelCollection.js";
 import { BaseDeltaManagerProxy } from "./deltaManagerProxies.js";
 import {
 	runtimeCompatDetailsForDataStore,
@@ -94,7 +94,6 @@ import {
 	getAttributesFormatVersion,
 	getFluidDataStoreAttributes,
 	hasIsolatedChannels,
-	summarizerClientType,
 	wrapSummaryInChannelsTree,
 } from "./summary/index.js";
 
@@ -117,9 +116,6 @@ export function createAttributesBlob(
 	return new BlobTreeEntry(dataStoreAttributesBlobName, JSON.stringify(attributes));
 }
 
-/**
- * @internal
- */
 export interface ISnapshotDetails {
 	pkg: readonly string[];
 	isRootDataStore: boolean;
@@ -131,7 +127,6 @@ export interface ISnapshotDetails {
  * This is interface that every context should implement.
  * This interface is used for context's parent - ChannelCollection.
  * It should not be exposed to any other users of context.
- * @internal
  */
 export interface IFluidDataStoreContextInternal extends IFluidDataStoreContext {
 	getAttachSummary(telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;
@@ -147,11 +142,10 @@ export interface IFluidDataStoreContextInternal extends IFluidDataStoreContext {
 
 /**
  * Properties necessary for creating a FluidDataStoreContext
- * @internal
  */
 export interface IFluidDataStoreContextProps {
 	readonly id: string;
-	readonly parentContext: IFluidParentContext;
+	readonly parentContext: IFluidParentContextPrivate;
 	readonly storage: IDocumentStorageService;
 	readonly scope: FluidObject;
 	readonly createSummarizerNodeFn: CreateChildSummarizerNodeFn;
@@ -161,7 +155,6 @@ export interface IFluidDataStoreContextProps {
 
 /**
  * Properties necessary for creating a local FluidDataStoreContext
- * @internal
  */
 export interface ILocalFluidDataStoreContextProps extends IFluidDataStoreContextProps {
 	readonly pkg: Readonly<string[]> | undefined;
@@ -171,7 +164,6 @@ export interface ILocalFluidDataStoreContextProps extends IFluidDataStoreContext
 
 /**
  * Properties necessary for creating a local FluidDataStoreContext
- * @internal
  */
 export interface ILocalDetachedFluidDataStoreContextProps
 	extends ILocalFluidDataStoreContextProps {
@@ -180,7 +172,6 @@ export interface ILocalDetachedFluidDataStoreContextProps
 
 /**
  * Properties necessary for creating a remote FluidDataStoreContext
- * @internal
  */
 export interface IRemoteFluidDataStoreContextProps extends IFluidDataStoreContextProps {
 	readonly snapshot: ISnapshotTree | ISnapshot | undefined;
@@ -189,7 +180,6 @@ export interface IRemoteFluidDataStoreContextProps extends IFluidDataStoreContex
 // back-compat: To be removed in the future.
 // Added in "2.0.0-rc.2.0.0" timeframe (to support older builds).
 /**
- * @internal
  */
 export interface IFluidDataStoreContextEvents extends IEvent {
 	(event: "attaching" | "attached", listener: () => void);
@@ -233,23 +223,19 @@ class ContextDeltaManagerProxy extends BaseDeltaManagerProxy {
 	}
 
 	/**
-	 * Called by the owning datastore context to configure the readonly
-	 * state of the delta manger that is project down to the datastore
+	 * Called by the owning datastore context to emit the readonly
+	 * event on the delta manger that is projected down to the datastore
 	 * runtime. This state may not align with that of the true delta
 	 * manager if the context wishes to control the read only state
 	 * differently than the delta manager itself.
 	 */
-	public setReadonly(
-		readonly: boolean,
-		readonlyConnectionReason?: { reason: string; error?: IErrorBase },
-	): void {
-		this.emit("readonly", readonly, readonlyConnectionReason);
+	public emitReadonly(): void {
+		this.emit("readonly", this.isReadOnly());
 	}
 }
 
 /**
  * Represents the context for the store. This context is passed to the store runtime.
- * @internal
  */
 export abstract class FluidDataStoreContext
 	extends TypedEventEmitter<IFluidDataStoreContextEvents>
@@ -281,7 +267,10 @@ export abstract class FluidDataStoreContext
 		return this._contextDeltaManagerProxy;
 	}
 
-	public isReadOnly = (): boolean => this.parentContext.isReadOnly?.() ?? false;
+	private isStagingMode: boolean = false;
+	public isReadOnly = (): boolean =>
+		(this.isStagingMode && this.channel?.policies?.readonlyInStagingMode !== false) ||
+		this.parentContext.isReadOnly();
 
 	public get connected(): boolean {
 		return this.parentContext.connected;
@@ -424,7 +413,7 @@ export abstract class FluidDataStoreContext
 
 	public readonly id: string;
 	private readonly _containerRuntime: IContainerRuntimeBase;
-	private readonly parentContext: IFluidParentContext;
+	private readonly parentContext: IFluidParentContextPrivate;
 	public readonly storage: IDocumentStorageService;
 	public readonly scope: FluidObject;
 	// Represents the group to which the data store belongs too.
@@ -688,11 +677,28 @@ export abstract class FluidDataStoreContext
 		this.channel!.setConnectionState(connected, clientId);
 	}
 
-	public notifyReadOnlyState(readonly: boolean): void {
+	public notifyReadOnlyState(): void {
 		this.verifyNotClosed("notifyReadOnlyState", false /* checkTombstone */);
 
-		this.channel?.notifyReadOnlyState?.(readonly);
-		this._contextDeltaManagerProxy.setReadonly(readonly);
+		// These two calls achieve the same purpose, and are both needed for a time for back compat
+		this.channel?.notifyReadOnlyState?.(this.isReadOnly());
+		this._contextDeltaManagerProxy.emitReadonly();
+	}
+
+	/**
+	 * Updates the readonly state of the data store based on the staging mode.
+	 *
+	 * @param staging - A boolean indicating whether the container is in staging mode.
+	 * If true, the data store is set to readonly unless explicitly allowed by its policies.
+	 */
+	public notifyStagingMode(staging: boolean): void {
+		// If the `readonlyInStagingMode` policy is not explicitly set to `false`,
+		// the data store is treated as readonly in staging mode.
+		const oldReadOnlyState = this.isReadOnly();
+		this.isStagingMode = staging;
+		if (this.isReadOnly() !== oldReadOnlyState) {
+			this.notifyReadOnlyState();
+		}
 	}
 
 	/**
@@ -877,8 +883,8 @@ export abstract class FluidDataStoreContext
 	public submitMessage(type: string, content: unknown, localOpMetadata: unknown): void {
 		this.verifyNotClosed("submitMessage");
 		assert(!!this.channel, 0x146 /* "Channel must exist when submitting message" */);
-		// Summarizer clients should not submit messages.
-		this.identifyLocalChangeInSummarizer("DataStoreMessageSubmittedInSummarizer", type);
+		// Readonly clients should not submit messages.
+		this.identifyLocalChangeIfReadonly("DataStoreMessageWhileReadonly", type);
 
 		this.parentContext.submitMessage(type, content, localOpMetadata);
 	}
@@ -1036,9 +1042,14 @@ export abstract class FluidDataStoreContext
 		return {};
 	}
 
-	public reSubmit(type: string, contents: unknown, localOpMetadata: unknown): void {
+	public reSubmit(
+		type: string,
+		contents: unknown,
+		localOpMetadata: unknown,
+		squash: boolean,
+	): void {
 		assert(!!this.channel, 0x14b /* "Channel must exist when resubmitting ops" */);
-		this.channel.reSubmit(type, contents, localOpMetadata);
+		this.channel.reSubmit(type, contents, localOpMetadata, squash);
 	}
 
 	public rollback(type: string, contents: unknown, localOpMetadata: unknown): void {
@@ -1109,19 +1120,16 @@ export abstract class FluidDataStoreContext
 	}
 
 	/**
-	 * Summarizer client should not have local changes. These changes can become part of the summary and can break
+	 * Readonly client, including summarizer, should not have local changes. These changes can become part of the summary and can break
 	 * eventual consistency. For example, the next summary (say at ref seq# 100) may contain these changes whereas
 	 * other clients that are up-to-date till seq# 100 may not have them yet.
 	 */
-	protected identifyLocalChangeInSummarizer(eventName: string, type?: string): void {
-		if (
-			this.clientDetails.type !== summarizerClientType ||
-			this.localChangesTelemetryCount <= 0
-		) {
+	protected identifyLocalChangeIfReadonly(eventName: string, type?: string): void {
+		if (!this.isReadOnly() || this.localChangesTelemetryCount <= 0) {
 			return;
 		}
 
-		// Log a telemetry if there are local changes in the summarizer. This will give us data on how often
+		// Log a telemetry if there are local changes in readonly. This will give us data on how often
 		// this is happening and which data stores do this. The eventual goal is to disallow local changes
 		// in the summarizer and the data will help us plan this.
 		this.mc.logger.sendTelemetryEvent({
@@ -1129,6 +1137,8 @@ export abstract class FluidDataStoreContext
 			type,
 			isSummaryInProgress: this.summarizerNode.isSummaryInProgress?.(),
 			stack: generateStack(30),
+			readonly: this.isReadOnly(),
+			isStagingMode: this.isStagingMode,
 		});
 		this.localChangesTelemetryCount--;
 	}
@@ -1330,7 +1340,7 @@ export class LocalFluidDataStoreContextBase extends FluidDataStoreContext {
 		);
 
 		// Summarizer client should not create local data stores.
-		this.identifyLocalChangeInSummarizer("DataStoreCreatedInSummarizer");
+		this.identifyLocalChangeIfReadonly("DataStoreCreatedWhileReadonly");
 
 		this.snapshotTree = props.snapshotTree;
 	}

package/src/index.ts

@@ -31,6 +31,7 @@ export {
 	ChannelCollectionFactory,
 	AllowTombstoneRequestHeaderKey,
 } from "./channelCollection.js";
+export type { MinimumVersionForCollab } from "./compatUtils.js";
 export {
 	GCNodeType,
 	IGCMetadata,
@@ -109,16 +110,3 @@ export {
 	DefaultSummaryConfiguration,
 } from "./summary/index.js";
 export { IChunkedOp, unpackRuntimeMessage } from "./opLifecycle/index.js";
-export { ChannelCollection } from "./channelCollection.js";
-export {
-	IFluidDataStoreContextInternal,
-	ISnapshotDetails,
-	LocalFluidDataStoreContext,
-	LocalFluidDataStoreContextBase,
-	FluidDataStoreContext,
-	IFluidDataStoreContextProps,
-	ILocalFluidDataStoreContextProps,
-	ILocalDetachedFluidDataStoreContextProps,
-	IFluidDataStoreContextEvents,
-} from "./dataStoreContext.js";
-export { DataStoreContexts } from "./dataStoreContexts.js";

package/src/opLifecycle/index.ts

@@ -27,6 +27,7 @@ export {
 	ensureContentsDeserialized,
 } from "./opSerialization.js";
 export {
+	BatchResubmitInfo,
 	estimateSocketSize,
 	localBatchToOutboundBatch,
 	Outbox,

package/src/opLifecycle/outbox.ts

@@ -66,10 +66,27 @@ export interface IOutboxParameters {
 	readonly logger: ITelemetryBaseLogger;
 	readonly groupingManager: OpGroupingManager;
 	readonly getCurrentSequenceNumbers: () => BatchSequenceNumbers;
-	readonly reSubmit: (message: PendingMessageResubmitData) => void;
+	readonly reSubmit: (message: PendingMessageResubmitData, squash: boolean) => void;
 	readonly opReentrancy: () => boolean;
 }
 
+/**
+ * Info needed to correctly resubmit a batch
+ */
+export interface BatchResubmitInfo {
+	/**
+	 * If defined, indicates the Batch ID of the batch being resubmitted.
+	 * This must be preserved on the new batch about to be submitted so they can be correlated/deduped in case both are sent.
+	 */
+	batchId?: string;
+	/**
+	 * Indicates whether or not this batch is "staged", meaning it should not be sent to the ordering service yet
+	 * This is important on resubmit because we may be in Staging Mode for new changes,
+	 * but resubmitting a non-staged change from before entering Staging Mode
+	 */
+	staged: boolean;
+}
+
 /**
  * Temporarily increase the stack limit while executing the provided action.
  * If a negative value is provided for `length`, no stack frames will be collected.
@@ -335,37 +352,33 @@ export class Outbox {
 	 * This method is expected to be called at the end of a batch.
 	 *
 	 * @throws If called from a reentrant context, or if the batch being flushed is too large.
-	 * @param resubmittingBatchId - If defined, indicates this is a resubmission of a batch
-	 * with the given Batch ID, which must be preserved
-	 * @param resubmittingStagedBatch - If defined, indicates this is a resubmission of a batch that is staged,
-	 * meaning it should not be sent to the ordering service yet.
+	 * @param resubmitInfo - Key information when flushing a resubmitted batch. Undefined means this is not resubmit.
 	 */
-	public flush(resubmittingBatchId?: BatchId, resubmittingStagedBatch?: boolean): void {
+	public flush(resubmitInfo?: BatchResubmitInfo): void {
 		assert(
 			!this.isContextReentrant(),
 			0xb7b /* Flushing must not happen while incoming changes are being processed */,
 		);
-
-		this.flushAll(resubmittingBatchId, resubmittingStagedBatch);
+		this.flushAll(resubmitInfo);
 	}
 
-	private flushAll(resubmittingBatchId?: BatchId, resubmittingStagedBatch?: boolean): void {
+	private flushAll(resubmitInfo?: BatchResubmitInfo): void {
 		const allBatchesEmpty =
 			this.idAllocationBatch.empty && this.blobAttachBatch.empty && this.mainBatch.empty;
 		if (allBatchesEmpty) {
-			// If we're resubmitting and all batches are empty, we need to flush an empty batch.
-			// Note that we currently resubmit one batch at a time, so on resubmit, 2 of the 3 batches will *always* be empty.
+			// If we're resubmitting with a batchId and all batches are empty, we need to flush an empty batch.
+			// Note that we currently resubmit one batch at a time, so on resubmit, 1 of the 2 batches will *always* be empty.
 			// It's theoretically possible that we don't *need* to resubmit this empty batch, and in those cases, it'll safely be ignored
 			// by the rest of the system, including remote clients.
 			// In some cases we *must* resubmit the empty batch (to match up with a non-empty version tracked locally by a container fork), so we do it always.
-			if (resubmittingBatchId) {
-				this.flushEmptyBatch(resubmittingBatchId, resubmittingStagedBatch === true);
+			if (resubmitInfo?.batchId !== undefined) {
+				this.flushEmptyBatch(resubmitInfo.batchId, resubmitInfo.staged);
 			}
 			return;
 		}
 
 		// Don't use resubmittingBatchId for idAllocationBatch.
-		// ID Allocation messages are not directly resubmitted so we don't want to reuse the batch ID.
+		// ID Allocation messages are not directly resubmitted so don't pass the resubmitInfo
 		this.flushInternal({
 			batchManager: this.idAllocationBatch,
 			// Note: For now, we will never stage ID Allocation messages.
@@ -374,13 +387,11 @@ export class Outbox {
 		this.flushInternal({
 			batchManager: this.blobAttachBatch,
 			disableGroupedBatching: true,
-			resubmittingBatchId,
-			resubmittingStagedBatch,
+			resubmitInfo,
 		});
 		this.flushInternal({
 			batchManager: this.mainBatch,
-			resubmittingBatchId,
-			resubmittingStagedBatch,
+			resubmitInfo,
 		});
 	}
 
@@ -416,25 +427,19 @@ export class Outbox {
 	private flushInternal(params: {
 		batchManager: BatchManager;
 		disableGroupedBatching?: boolean;
-		resubmittingBatchId?: BatchId; // undefined if not resubmitting
-		resubmittingStagedBatch?: boolean; // undefined if not resubmitting
+		resubmitInfo?: BatchResubmitInfo; // undefined if not resubmitting
 	}): void {
-		const {
-			batchManager,
-			disableGroupedBatching = false,
-			resubmittingBatchId,
-			resubmittingStagedBatch,
-		} = params;
+		const { batchManager, disableGroupedBatching = false, resubmitInfo } = params;
 		if (batchManager.empty) {
 			return;
 		}
 
-		const rawBatch = batchManager.popBatch(resubmittingBatchId);
+		const rawBatch = batchManager.popBatch(resubmitInfo?.batchId);
 
 		// When resubmitting, we respect the staged state of the original batch.
 		// In this case rawBatch.staged will match the state of inStagingMode when
 		// the resubmit occurred, which is not relevant.
-		const staged = resubmittingStagedBatch ?? rawBatch.staged === true;
+		const staged = resubmitInfo?.staged ?? rawBatch.staged === true;
 
 		const groupingEnabled =
 			!disableGroupedBatching && this.params.groupingManager.groupedBatchingEnabled();
@@ -490,12 +495,16 @@ export class Outbox {
 		assert(batchManager.options.canRebase, 0x9a7 /* BatchManager does not support rebase */);
 
 		this.rebasing = true;
+		const squash = false;
 		for (const message of rawBatch.messages) {
-			this.params.reSubmit({
-				runtimeOp: message.runtimeOp,
-				localOpMetadata: message.localOpMetadata,
-				opMetadata: message.metadata,
-			});
+			this.params.reSubmit(
+				{
+					runtimeOp: message.runtimeOp,
+					localOpMetadata: message.localOpMetadata,
+					opMetadata: message.metadata,
+				},
+				squash,
+			);
 		}
 
 		if (this.batchRebasesToReport > 0) {

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-runtime";
-export const pkgVersion = "2.33.2";
+export const pkgVersion = "2.40.0";

package/src/pendingStateManager.ts

@@ -22,13 +22,13 @@ import {
 } from "./messageTypes.js";
 import { asBatchMetadata, asEmptyBatchLocalOpMetadata } from "./metadata.js";
 import {
-	BatchId,
 	LocalBatchMessage,
 	getEffectiveBatchId,
 	BatchStartInfo,
 	InboundMessageResult,
 	serializeOp,
 	type LocalEmptyBatchPlaceholder,
+	type BatchResubmitInfo,
 } from "./opLifecycle/index.js";
 
 /**
@@ -114,11 +114,21 @@ export type PendingMessageResubmitData = Pick<
 	runtimeOp: LocalContainerRuntimeMessage;
 };
 
+export interface PendingBatchResubmitMetadata extends BatchResubmitInfo {
+	/**
+	 * Whether changes in this batch should be squashed when resubmitting.
+	 */
+	squash: boolean;
+}
+
 export interface IRuntimeStateHandler {
 	connected(): boolean;
 	clientId(): string | undefined;
 	applyStashedOp(serializedOp: string): Promise<unknown>;
-	reSubmitBatch(batch: PendingMessageResubmitData[], batchId: BatchId, staged: boolean): void;
+	reSubmitBatch(
+		batch: PendingMessageResubmitData[],
+		metadata: PendingBatchResubmitMetadata,
+	): void;
 	isActiveConnection: () => boolean;
 	isAttached: () => boolean;
 }
@@ -211,6 +221,24 @@ function toSerializableForm(
 	};
 }
 
+interface ReplayPendingStateOptions {
+	/**
+	 * If true, only replay staged batches. This is used when we are exiting staging mode and want to rebase and submit the staged batches.
+	 * Default: false
+	 */
+	onlyStagedBatches: boolean;
+	/**
+	 * @param squash - If true, edits should be squashed when resubmitting.
+	 * Default: false
+	 */
+	squash: boolean;
+}
+
+const defaultReplayPendingStatesOptions: ReplayPendingStateOptions = {
+	onlyStagedBatches: false,
+	squash: false,
+};
+
 /**
  * PendingStateManager is responsible for maintaining the messages that have not been sent or have not yet been
  * acknowledged by the server. It also maintains the batch information for both automatically and manually flushed
@@ -683,11 +711,12 @@ export class PendingStateManager implements IDisposable {
 	 * Called when the Container's connection state changes. If the Container gets connected, it replays all the pending
 	 * states in its queue. This includes triggering resubmission of unacked ops.
 	 * ! Note: successfully resubmitting an op that has been successfully sequenced is not possible due to checks in the ConnectionStateHandler (Loader layer)
-	 * @param onlyStagedBatches - If true, only replay staged batches. This is used when we are exiting staging mode and want to rebase and submit the staged batches.
 	 */
-	public replayPendingStates(onlyStagedBatches?: boolean): void {
+	public replayPendingStates(optionsParam?: ReplayPendingStateOptions): void {
+		const options = { ...defaultReplayPendingStatesOptions, ...optionsParam };
+		const { onlyStagedBatches, squash } = options;
 		assert(
-			this.stateHandler.connected(),
+			this.stateHandler.connected() || onlyStagedBatches === true,
 			0x172 /* "The connection state is not consistent with the runtime" */,
 		);
 
@@ -741,7 +770,7 @@ export class PendingStateManager implements IDisposable {
 
 			if (asEmptyBatchLocalOpMetadata(pendingMessage.localOpMetadata)?.emptyBatch === true) {
 				// Resubmit no messages, with the batchId. Will result in another empty batch marker.
-				this.stateHandler.reSubmitBatch([], batchId, staged);
+				this.stateHandler.reSubmitBatch([], { batchId, staged, squash });
 				continue;
 			}
 
@@ -766,8 +795,7 @@ export class PendingStateManager implements IDisposable {
 							opMetadata: pendingMessage.opMetadata,
 						},
 					],
-					batchId,
-					staged,
+					{ batchId, staged, squash },
 				);
 				continue;
 			}
@@ -807,7 +835,7 @@ export class PendingStateManager implements IDisposable {
 				);
 			}
 
-			this.stateHandler.reSubmitBatch(batch, batchId, staged);
+			this.stateHandler.reSubmitBatch(batch, { batchId, staged, squash });
 		}
 
 		// pending ops should no longer depend on previous sequenced local ops after resubmit
@@ -825,17 +853,6 @@ export class PendingStateManager implements IDisposable {
 		}
 	}
 
-	/**
-	 * Clears the 'staged' flag off all pending messages.
-	 */
-	public clearStagingFlags(): void {
-		for (const message of this.pendingMessages.toArray()) {
-			if (message.batchInfo.staged) {
-				message.batchInfo.staged = false;
-			}
-		}
-	}
-
 	/**
 	 * Pops all staged batches, invoking the callback on each one in order (LIFO)
 	 */