@fluidframework/container-runtime 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.1

package/src/gc/gcConfigs.ts

@@ -7,35 +7,34 @@ import {
 	MonitoringContext,
 	UsageError,
 	validatePrecondition,
-} from "@fluidframework/telemetry-utils";
+} from "@fluidframework/telemetry-utils/internal";
+
 import { IContainerRuntimeMetadata } from "../summary/index.js";
+
 import {
-	nextGCVersion,
+	GCFeatureMatrix,
+	GCVersion,
+	IGCMetadata_Deprecated,
+	IGCRuntimeOptions,
+	IGarbageCollectorConfigs,
 	defaultInactiveTimeoutMs,
 	defaultSessionExpiryDurationMs,
+	defaultSweepGracePeriodMs,
+	disableDatastoreSweepKey,
 	disableTombstoneKey,
-	GCFeatureMatrix,
+	gcDisableDataStoreSweepOptionName,
+	gcDisableThrowOnTombstoneLoadOptionName,
+	gcGenerationOptionName,
 	gcTestModeKey,
-	GCVersion,
-	gcVersionUpgradeToV4Key,
-	IGarbageCollectorConfigs,
-	IGCRuntimeOptions,
 	maxSnapshotCacheExpiryMs,
 	oneDayMs,
 	runGCKey,
 	runSessionExpiryKey,
 	runSweepKey,
-	stableGCVersion,
 	throwOnTombstoneLoadOverrideKey,
 	throwOnTombstoneUsageKey,
-	gcDisableThrowOnTombstoneLoadOptionName,
-	defaultSweepGracePeriodMs,
-	gcGenerationOptionName,
-	IGCMetadata_Deprecated,
-	disableDatastoreSweepKey,
-	gcDisableDataStoreSweepOptionName,
 } from "./gcDefinitions.js";
-import { getGCVersion, shouldAllowGcSweep } from "./gcHelpers.js";
+import { getGCVersion, getGCVersionInEffect, shouldAllowGcSweep } from "./gcHelpers.js";
 
 /**
  * Generates configurations for the Garbage Collector that it uses to determine what to run and how.
@@ -113,9 +112,7 @@ export function generateGCConfigs(
 		createParams.gcOptions[gcGenerationOptionName] /* currentGeneration */,
 	);
 
-	// If version upgrade is not enabled, fall back to the stable GC version.
-	const gcVersionInEffect =
-		mc.config.getBoolean(gcVersionUpgradeToV4Key) === true ? nextGCVersion : stableGCVersion;
+	const gcVersionInEffect = getGCVersionInEffect(mc.config);
 
 	// The GC version is up-to-date if the GC version in effect is at least equal to the GC version in base snapshot.
 	// If it is not up-to-date, there is a newer version of GC out there which is more reliable than this. So, GC

package/src/gc/gcDefinitions.ts

@@ -6,21 +6,21 @@
 import { ICriticalContainerError } from "@fluidframework/container-definitions";
 import { IRequest } from "@fluidframework/core-interfaces";
 import { ISnapshotTree } from "@fluidframework/protocol-definitions";
+import { IGarbageCollectionData, ITelemetryContext } from "@fluidframework/runtime-definitions";
 import {
-	IGarbageCollectionData,
 	IGarbageCollectionDetailsBase,
 	ISummarizeResult,
-	ITelemetryContext,
-} from "@fluidframework/runtime-definitions";
-import { ReadAndParseBlob } from "@fluidframework/runtime-utils";
+} from "@fluidframework/runtime-definitions/internal";
+import { ReadAndParseBlob } from "@fluidframework/runtime-utils/internal";
 import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
+
+import { RuntimeHeaderData } from "../containerRuntime.js";
+import { ContainerRuntimeGCMessage } from "../messageTypes.js";
 import {
 	IContainerRuntimeMetadata,
 	ICreateContainerMetadata,
 	IRefreshSummaryResult,
 } from "../summary/index.js";
-import { RuntimeHeaderData } from "../containerRuntime.js";
-import { ContainerRuntimeGCMessage } from "../messageTypes.js";
 
 /**
  * @alpha
@@ -307,8 +307,6 @@ export interface IGarbageCollectionRuntime {
 	getGCData(fullGC?: boolean): Promise<IGarbageCollectionData>;
 	/** After GC has run, called to notify the runtime of routes that are used in it. */
 	updateUsedRoutes(usedRoutes: readonly string[]): void;
-	/** After GC has run, called to notify the runtime of routes that are unused in it. */
-	updateUnusedRoutes(unusedRoutes: readonly string[]): void;
 	/**
 	 * After GC has run and identified nodes that are sweep ready, called to delete the sweep ready nodes. The runtime
 	 * should return the routes of nodes that were deleted.

package/src/gc/gcHelpers.ts

@@ -3,16 +3,25 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils";
+import { assert } from "@fluidframework/core-utils/internal";
 import { ISnapshotTree } from "@fluidframework/protocol-definitions";
+import { IGarbageCollectionData } from "@fluidframework/runtime-definitions";
 import {
+	IGarbageCollectionDetailsBase,
 	gcBlobPrefix,
 	gcDeletedBlobKey,
 	gcTombstoneBlobKey,
-	IGarbageCollectionData,
-	IGarbageCollectionDetailsBase,
-} from "@fluidframework/runtime-definitions";
-import { GCFeatureMatrix, GCVersion, IGCMetadata } from "./gcDefinitions.js";
+} from "@fluidframework/runtime-definitions/internal";
+import type { IConfigProvider } from "@fluidframework/telemetry-utils/internal";
+
+import {
+	GCFeatureMatrix,
+	GCVersion,
+	IGCMetadata,
+	gcVersionUpgradeToV4Key,
+	nextGCVersion,
+	stableGCVersion,
+} from "./gcDefinitions.js";
 import {
 	IGarbageCollectionNodeData,
 	IGarbageCollectionSnapshotData,
@@ -27,6 +36,14 @@ export function getGCVersion(metadata?: IGCMetadata): GCVersion {
 	return metadata.gcFeature ?? 0;
 }
 
+/** Indicates what GC version is in effect for new GC data being written in this session */
+export function getGCVersionInEffect(configProvider: IConfigProvider): number {
+	// If version upgrade is not enabled, fall back to the stable GC version.
+	return configProvider.getBoolean(gcVersionUpgradeToV4Key) === true
+		? nextGCVersion
+		: stableGCVersion;
+}
+
 /**
  * Indicates whether Sweep is allowed for this document based on the persisted GC Feature Matrix and current gcGeneration.
  * This applies to the entire Sweep Phase the same - both Tombstone Enforcement (i.e. should loading a Tombstone fail?) and Deletion.

package/src/gc/gcSummaryStateTracker.ts

@@ -4,17 +4,19 @@
  */
 
 import { SummaryType } from "@fluidframework/protocol-definitions";
+import { ISummaryTreeWithStats } from "@fluidframework/runtime-definitions";
 import {
+	ISummarizeResult,
 	gcBlobPrefix,
 	gcDeletedBlobKey,
 	gcTombstoneBlobKey,
 	gcTreeKey,
-	ISummarizeResult,
-	ISummaryTreeWithStats,
-} from "@fluidframework/runtime-definitions";
-import { mergeStats, SummaryTreeBuilder } from "@fluidframework/runtime-utils";
+} from "@fluidframework/runtime-definitions/internal";
+import { SummaryTreeBuilder, mergeStats } from "@fluidframework/runtime-utils/internal";
+
 import { IRefreshSummaryResult } from "../summary/index.js";
-import { GCVersion, IGarbageCollectorConfigs, IGCStats } from "./gcDefinitions.js";
+
+import { GCVersion, IGCStats, IGarbageCollectorConfigs } from "./gcDefinitions.js";
 import { generateSortedGCState } from "./gcHelpers.js";
 import { IGarbageCollectionSnapshotData, IGarbageCollectionState } from "./gcSummaryDefinitions.js";
 

package/src/gc/gcTelemetry.ts

@@ -5,24 +5,29 @@
 
 import { IGarbageCollectionData } from "@fluidframework/runtime-definitions";
 import {
-	generateStack,
+	type ITelemetryGenericEventExt,
 	ITelemetryLoggerExt,
+} from "@fluidframework/telemetry-utils";
+import {
 	MonitoringContext,
+	generateStack,
 	tagCodeArtifacts,
-	type ITelemetryGenericEventExt,
-} from "@fluidframework/telemetry-utils";
+} from "@fluidframework/telemetry-utils/internal";
+
 import { RuntimeHeaderData } from "../containerRuntime.js";
 import { ICreateContainerMetadata } from "../summary/index.js";
+
 import {
+	GCFeatureMatrix,
 	GCNodeType,
-	UnreferencedState,
 	IGarbageCollectorConfigs,
+	UnreferencedState,
 	disableTombstoneKey,
-	throwOnTombstoneUsageKey,
-	throwOnTombstoneLoadOverrideKey,
 	runSweepKey,
-	GCFeatureMatrix,
+	throwOnTombstoneLoadOverrideKey,
+	throwOnTombstoneUsageKey,
 } from "./gcDefinitions.js";
+import { getGCVersionInEffect } from "./gcHelpers.js";
 import { UnreferencedStateTracker } from "./gcUnreferencedStateTracker.js";
 
 type NodeUsageType = "Changed" | "Loaded" | "Revived";
@@ -429,6 +434,7 @@ export function sendGCUnexpectedUsageEvent(
 	event.sweepFlags = JSON.stringify({
 		EnableSweepFlag: mc.config.getBoolean(runSweepKey),
 	});
+	event.gcVersion = getGCVersionInEffect(mc.config);
 
 	mc.logger.sendTelemetryEvent(event, error);
 }

package/src/gc/gcUnreferencedStateTracker.ts

@@ -3,8 +3,9 @@
  * Licensed under the MIT License.
  */
 
-import { assert, Timer } from "@fluidframework/core-utils";
-import { validatePrecondition } from "@fluidframework/telemetry-utils";
+import { assert, Timer } from "@fluidframework/core-utils/internal";
+import { validatePrecondition } from "@fluidframework/telemetry-utils/internal";
+
 import { UnreferencedState } from "./gcDefinitions.js";
 
 /** A wrapper around common-utils Timer that requires the timeout when calling start/restart */

package/src/gc/index.ts

@@ -45,6 +45,7 @@ export {
 export {
 	cloneGCData,
 	concatGarbageCollectionStates,
+	getGCVersionInEffect,
 	trimLeadingAndTrailingSlashes,
 	unpackChildNodesGCDetails,
 } from "./gcHelpers.js";

package/src/index.ts

@@ -11,7 +11,6 @@ export {
 	ISummaryConfigurationDisableHeuristics,
 	IContainerRuntimeOptions,
 	isRuntimeMessage,
-	RuntimeMessage,
 	agentSchedulerId,
 	ContainerRuntime,
 	TombstoneResponseHeaderKey,
@@ -20,6 +19,8 @@ export {
 	DefaultSummaryConfiguration,
 	ICompressionRuntimeOptions,
 	CompressionAlgorithms,
+	RuntimeHeaderData,
+	disabledCompressionConfig,
 } from "./containerRuntime.js";
 export {
 	ContainerMessageType,
@@ -97,5 +98,25 @@ export {
 	IRetriableFailureResult,
 	ISummarizeEventProps,
 	IdCompressorMode,
+	IDocumentSchema,
+	DocumentSchemaValueType,
+	IDocumentSchemaCurrent,
+	currentDocumentVersionSchema,
+	DocumentsSchemaController,
+	IDocumentSchemaChangeMessage,
+	IDocumentSchemaFeatures,
 } 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/messageTypes.ts

@@ -3,16 +3,18 @@
  * Licensed under the MIT License.
  */
 
+import type { IdCreationRange } from "@fluidframework/id-compressor/internal";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
 import {
+	IAttachMessage,
 	IEnvelope,
 	InboundAttachMessage,
-	IAttachMessage,
-} from "@fluidframework/runtime-definitions";
-import type { IdCreationRange } from "@fluidframework/id-compressor";
+} from "@fluidframework/runtime-definitions/internal";
+
 import { IDataStoreAliasMessage } from "./dataStore.js";
 import { GarbageCollectionMessage } from "./gc/index.js";
 import { IChunkedOp } from "./opLifecycle/index.js";
+import { IDocumentSchemaChangeMessage } from "./summary/index.js";
 
 /**
  * @alpha
@@ -43,6 +45,11 @@ export enum ContainerMessageType {
 	 */
 	IdAllocation = "idAllocation",
 
+	/**
+	 * An op that changes document schema
+	 */
+	DocumentSchemaChange = "schema",
+
 	/**
 	 * Garbage collection specific op. This is sent by the summarizer client when GC runs. It's used to synchronize GC
 	 * state across all clients.
@@ -131,6 +138,10 @@ export type ContainerRuntimeGCMessage = TypedContainerRuntimeMessage<
 	ContainerMessageType.GC,
 	GarbageCollectionMessage
 >;
+export type ContainerRuntimeDocumentSchemaMessage = TypedContainerRuntimeMessage<
+	ContainerMessageType.DocumentSchemaChange,
+	IDocumentSchemaChangeMessage
+>;
 
 /**
  * Represents an unrecognized TypedContainerRuntimeMessage, e.g. a message from a future version of the container runtime.
@@ -161,7 +172,8 @@ export type InboundContainerRuntimeMessage =
 	| ContainerRuntimeIdAllocationMessage
 	| ContainerRuntimeGCMessage
 	// Inbound messages may include unknown types from other clients, so we include that as a special case here
-	| UnknownContainerRuntimeMessage;
+	| UnknownContainerRuntimeMessage
+	| ContainerRuntimeDocumentSchemaMessage;
 
 /** A {@link TypedContainerRuntimeMessage} that has been generated by the container runtime but is not yet being sent to the server. */
 export type LocalContainerRuntimeMessage =
@@ -174,7 +186,8 @@ export type LocalContainerRuntimeMessage =
 	| ContainerRuntimeIdAllocationMessage
 	| ContainerRuntimeGCMessage
 	// In rare cases (e.g. related to stashed ops) we could have a local message of an unknown type
-	| UnknownContainerRuntimeMessage;
+	| UnknownContainerRuntimeMessage
+	| ContainerRuntimeDocumentSchemaMessage;
 
 /** A {@link TypedContainerRuntimeMessage} that is being sent to the server from the container runtime. */
 export type OutboundContainerRuntimeMessage =
@@ -185,7 +198,8 @@ export type OutboundContainerRuntimeMessage =
 	| ContainerRuntimeRejoinMessage
 	| ContainerRuntimeAliasMessage
 	| ContainerRuntimeIdAllocationMessage
-	| ContainerRuntimeGCMessage;
+	| ContainerRuntimeGCMessage
+	| ContainerRuntimeDocumentSchemaMessage;
 
 /**
  * An unpacked ISequencedDocumentMessage with the inner TypedContainerRuntimeMessage type/contents/etc

package/src/opLifecycle/README.md

@@ -13,6 +13,9 @@
 -   [Note about performance and latency](#note-about-performance-and-latency)
 -   [How it works](#how-it-works)
 -   [How grouped batching works](#how-grouped-batching-works)
+-   [How the overall op flow works](#How-the-overall-op-flow-works)
+    -   [Outbound](#outbound)
+    -   [Inbound](#inbound)
 
 ## Introduction
 
@@ -317,3 +320,89 @@ Ungrouped batch:
 | ClientSeqNum: 1 | ClientSeqNum: 2 | ClientSeqNum: 3 | ClientSeqNum: 4 | ClientSeqNum: 5 |
 +-----------------+-----------------+-----------------+-----------------+-----------------+
 ```
+
+## How the overall op flow works
+
+### Outbound
+
+The outbound view is how ops are accumulated and sent by the runtime with `FlushMode.TurnBased` (default).
+
+```mermaid
+stateDiagram-v2
+	state "* End of JS turn *" as jsTurn
+    state "opGroupingManager.groupBatch" as groupBatch
+    state "opCompressor.compress" as compress
+    state "outbox.flush" as flush
+    state "outbox.flushInternal" as flushInternal
+	state "Send batch over the wire" as post
+	state "Send chunks (partial ops) over the wire" as postChunks
+	state "Store original (uncompressed, unchunked, ungrouped) batch locally" as store
+    state if_compression <<choice>>
+	[*] --> ContainerRuntime.submit
+	ContainerRuntime.submit --> outbox.submitAttach
+	ContainerRuntime.submit --> outbox.submitBlobAttach
+	ContainerRuntime.submit --> outbox.submit
+	outbox.submit --> scheduleFlush
+	outbox.submitAttach --> scheduleFlush
+	outbox.submitBlobAttach --> scheduleFlush
+	scheduleFlush --> jsTurn
+	jsTurn --> flush
+	flush --> outbox.flushInternalMain
+	flush --> outbox.flushInternalAttach
+	flush --> outbox.flushInternalBlobAttach
+	outbox.flushInternalMain --> flushInternal
+	outbox.flushInternalAttach --> flushInternal
+	outbox.flushInternalBlobAttach --> flushInternal
+	flushInternal --> ContainerRuntime.reSubmit: if batch has reentrant ops and should group
+	ContainerRuntime.reSubmit --> flushInternal
+    flushInternal --> groupBatch: if should group
+    groupBatch --> if_compression
+	flushInternal --> if_compression
+    if_compression --> post
+	if_compression --> compress: if compression is enabled
+	compress --> post
+	compress --> opSplitter.split: if the compressed payload is larger than the chunk size
+	opSplitter.split --> post
+	opSplitter.split --> postChunks
+    post --> store
+```
+
+With `FlushMode.Immediate`(deprecated) the difference is that ops are no longer accumulated in batches, but flushed as they are submitted, instead of waiting for the end of the JS turn. All the other components work in the exact same manner with the difference that they operate on batches with length 1.
+
+### Inbound
+
+There is no concept of batch in the inbound view when we receive the ops. Ops are being received and processed one-by-one and the batch is reconstructed in the runtime layer. This requires individual components to maintain their own internal state in order to keep track of the batch.
+
+```mermaid
+stateDiagram-v2
+    [*] --> ContainerRuntime.process
+	ContainerRuntime.process --> remoteMessageProcessor
+    state remoteMessageProcessor {
+        state "process chunk" as processChunk
+        state "return nothing" as returnNothing
+        state "decompress and store" as decompress
+        state if_chunk <<choice>>
+        state if_compressed <<choice>>
+        state if_unrolling <<choice>>
+        state if_grouped <<choice>>
+        [*] --> if_chunk
+        if_chunk --> if_compressed
+        if_chunk --> processChunk: is chunk
+        processChunk --> returnNothing
+        processChunk --> if_compressed: is final chunk
+        if_compressed --> if_unrolling
+        if_compressed --> decompress: is compressed
+        decompress --> if_unrolling
+        if_unrolling --> if_grouped
+        if_unrolling --> unroll: if currently unrolling
+        unroll --> if_grouped
+        if_grouped --> return
+        if_grouped --> ungroup: is grouped batch
+        ungroup --> return
+        return --> [*]
+        returnNothing --> [*]
+    }
+    remoteMessageProcessor --> ContainerRuntime.procesCore
+```
+
+Note that a "system op" originating outside the ContainerRuntime will pass through this flow entirely.

package/src/opLifecycle/batchManager.ts

@@ -4,6 +4,7 @@
  */
 
 import { ICompressionRuntimeOptions } from "../containerRuntime.js";
+
 import { BatchMessage, IBatch, IBatchCheckpoint } from "./definitions.js";
 
 export interface IBatchManagerOptions {

package/src/opLifecycle/definitions.ts

@@ -3,17 +3,15 @@
  * Licensed under the MIT License.
  */
 
-import { IBatchMessage } from "@fluidframework/container-definitions";
-import { ISequencedDocumentMessage, MessageType } from "@fluidframework/protocol-definitions";
+import { IBatchMessage } from "@fluidframework/container-definitions/internal";
+
 import { CompressionAlgorithms } from "../containerRuntime.js";
-import { ContainerMessageType } from "../messageTypes.js";
 
 /**
  * Batch message type used internally by the runtime
  */
 export type BatchMessage = IBatchMessage & {
-	localOpMetadata: unknown;
-	type: ContainerMessageType;
+	localOpMetadata?: unknown;
 	referenceSequenceNumber: number;
 	compression?: CompressionAlgorithms;
 };
@@ -59,7 +57,6 @@ export interface IChunkedOp {
 	chunkId: number;
 	totalChunks: number;
 	contents: string;
-	originalType: MessageType | ContainerMessageType;
 	originalMetadata?: Record<string, unknown>;
 	originalCompression?: string;
 }
@@ -72,18 +69,3 @@ export interface IChunkedOp {
  * will make the processor return `Processed`.
  */
 export type ProcessingState = "Processed" | "Skipped" | "Accepted";
-
-/**
- * Return type for functions which process remote messages
- */
-export interface IMessageProcessingResult {
-	/**
-	 * A shallow copy of the input message if processing happened, or
-	 * the original message otherwise
-	 */
-	readonly message: ISequencedDocumentMessage;
-	/**
-	 * Processing result of the input message.
-	 */
-	readonly state: ProcessingState;
-}

package/src/opLifecycle/index.ts

@@ -4,16 +4,10 @@
  */
 
 export { BatchManager, estimateSocketSize, BatchSequenceNumbers } from "./batchManager.js";
-export {
-	BatchMessage,
-	IBatch,
-	IBatchCheckpoint,
-	IChunkedOp,
-	IMessageProcessingResult,
-} from "./definitions.js";
+export { BatchMessage, IBatch, IBatchCheckpoint, IChunkedOp } from "./definitions.js";
 export { Outbox, getLongStack } from "./outbox.js";
 export { OpCompressor } from "./opCompressor.js";
 export { OpDecompressor } from "./opDecompressor.js";
-export { OpSplitter, splitOp } from "./opSplitter.js";
+export { OpSplitter, splitOp, isChunkedMessage } from "./opSplitter.js";
 export { RemoteMessageProcessor, unpackRuntimeMessage } from "./remoteMessageProcessor.js";
-export { OpGroupingManager } from "./opGroupingManager.js";
+export { OpGroupingManager, OpGroupingManagerConfig, isGroupedBatch } from "./opGroupingManager.js";

package/src/opLifecycle/opCompressor.ts

@@ -3,14 +3,16 @@
  * Licensed under the MIT License.
  */
 
-import { createChildLogger, UsageError } from "@fluidframework/telemetry-utils";
-import { assert } from "@fluidframework/core-utils";
 import { IsoBuffer } from "@fluid-internal/client-utils";
-import { compress } from "lz4js";
 import { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError, createChildLogger } from "@fluidframework/telemetry-utils/internal";
+import { compress } from "lz4js";
+
 import { CompressionAlgorithms } from "../containerRuntime.js";
+
 import { estimateSocketSize } from "./batchManager.js";
-import { IBatch, BatchMessage } from "./definitions.js";
+import { BatchMessage, IBatch } from "./definitions.js";
 
 /**
  * Compresses batches of ops. It generates a single compressed op that contains
@@ -47,7 +49,6 @@ export class OpCompressor {
 		// Add empty placeholder messages to reserve the sequence numbers
 		for (const message of batch.content.slice(1)) {
 			messages.push({
-				type: message.type,
 				localOpMetadata: message.localOpMetadata,
 				metadata: message.metadata,
 				referenceSequenceNumber: message.referenceSequenceNumber,