@fluidframework/container-runtime 2.0.0-dev-rc.2.0.0.246488 → 2.0.0-dev-rc.3.0.0.250606

package/lib/container-runtime-alpha.d.ts

@@ -99,6 +99,10 @@ export declare enum ContainerMessageType {
      * See the [IdCompressor README](./id-compressor/README.md) for more details.
      */
     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.
@@ -119,7 +123,7 @@ export declare class ContainerRuntime extends TypedEventEmitter<IContainerRuntim
     readonly logger: ITelemetryLoggerExt;
     private readonly _storage;
     private readonly createIdCompressor;
-    private readonly idCompressorMode;
+    private readonly documentsSchemaController;
     private readonly requestHandler?;
     private readonly summaryConfiguration;
     /**
@@ -169,9 +173,16 @@ export declare class ContainerRuntime extends TypedEventEmitter<IContainerRuntim
     get IFluidDataStoreRegistry(): IFluidDataStoreRegistry;
     private readonly _getAttachState;
     get attachState(): AttachState;
+    get documentSchema(): {
+        explicitSchemaControl?: true | undefined;
+        compressionLz4?: true | undefined;
+        idCompressorMode?: IdCompressorMode;
+        opGroupingEnabled?: true | undefined;
+    };
     private _idCompressor;
     private pendingIdCompressorOps;
     private readonly skipSavedCompressorOps;
+    get idCompressorMode(): IdCompressorMode;
     /**
      * See IContainerRuntimeBase.idCompressor() for details.
      */
@@ -180,7 +191,7 @@ export declare class ContainerRuntime extends TypedEventEmitter<IContainerRuntim
      * True if we have ID compressor loading in-flight (async operation). Useful only for
      * this.idCompressorMode === "delayed" mode
      */
-    protected compressorLoadInitiated: boolean;
+    protected _loadIdCompressor: Promise<void> | undefined;
     /**
      * See IContainerRuntimeBase.generateDocumentUniqueId() for details.
      */
@@ -311,7 +322,8 @@ export declare class ContainerRuntime extends TypedEventEmitter<IContainerRuntim
      */
     private readonly snapshotCacheForLoadingGroupIds;
     /***/
-    protected constructor(context: IContainerContext, registry: IFluidDataStoreRegistry, metadata: IContainerRuntimeMetadata | undefined, electedSummarizerData: ISerializedElection | undefined, chunks: [string, string[]][], dataStoreAliasMap: [string, string][], runtimeOptions: Readonly<Required<IContainerRuntimeOptions>>, containerScope: FluidObject, logger: ITelemetryLoggerExt, existing: boolean, blobManagerSnapshot: IBlobManagerLoadInfo, _storage: IDocumentStorageService, createIdCompressor: () => Promise<IIdCompressor & IIdCompressorCore>, idCompressorMode: IdCompressorMode, provideEntryPoint: (containerRuntime: IContainerRuntime) => Promise<FluidObject>, requestHandler?: ((request: IRequest, runtime: IContainerRuntime) => Promise<IResponse>) | undefined, summaryConfiguration?: ISummaryConfiguration);
+    protected constructor(context: IContainerContext, registry: IFluidDataStoreRegistry, metadata: IContainerRuntimeMetadata | undefined, electedSummarizerData: ISerializedElection | undefined, chunks: [string, string[]][], dataStoreAliasMap: [string, string][], runtimeOptions: Readonly<Required<IContainerRuntimeOptions>>, containerScope: FluidObject, logger: ITelemetryLoggerExt, existing: boolean, blobManagerSnapshot: IBlobManagerLoadInfo, _storage: IDocumentStorageService, createIdCompressor: () => Promise<IIdCompressor & IIdCompressorCore>, documentsSchemaController: DocumentsSchemaController, featureGatesForTelemetry: Record<string, boolean | number | undefined>, provideEntryPoint: (containerRuntime: IContainerRuntime) => Promise<FluidObject>, requestHandler?: ((request: IRequest, runtime: IContainerRuntime) => Promise<IResponse>) | undefined, summaryConfiguration?: ISummaryConfiguration);
+    onSchemaChange(schema: IDocumentSchemaCurrent): void;
     getCreateChildSummarizerNodeFn(id: string, createParam: CreateChildSummarizerNodeParam): (summarizeInternal: SummarizeInternalFn, getGCDataFn: (fullGC?: boolean) => Promise<IGarbageCollectionData>) => ISummarizerNodeWithGC;
     deleteChildSummarizerNode(id: string): void;
     makeLocallyVisible(): void;
@@ -369,6 +381,7 @@ export declare class ContainerRuntime extends TypedEventEmitter<IContainerRuntim
      */
     private parseLocalOpContent;
     private applyStashedOp;
+    private loadIdCompressor;
     setConnectionState(connected: boolean, clientId?: string): void;
     private setConnectionStateCore;
     notifyOpReplay(message: ISequencedDocumentMessage): Promise<void>;
@@ -622,6 +635,15 @@ export declare class ContainerRuntime extends TypedEventEmitter<IContainerRuntim
 
 /* Excluded from this release type: ContainerRuntimeMessage */
 
+/**
+ * Current version known properties that define document schema
+ * This must be bumped whenever the format of document schema or protocol for changing the current document schema changes.
+ * Ex: adding a new configuration property (under IDocumentSchema.runtime) does not require changing this version.
+ * Ex: Changing the 'document schema acceptance' mechanism from convert-and-swap to one requiring consensus does require changing this version.
+ * @alpha
+ */
+export declare const currentDocumentVersionSchema = 1;
+
 /* Excluded from this release type: DataStoreContexts */
 
 /**
@@ -631,6 +653,102 @@ export declare const DefaultSummaryConfiguration: ISummaryConfiguration;
 
 /* Excluded from this release type: detectOutboundReferences */
 
+/** @alpha */
+export declare const disabledCompressionConfig: ICompressionRuntimeOptions;
+
+/**
+ * Descripe allowed type for properties in document schema.
+ * Please note that for all property types we should use undefined to indicate that particular capability is off.
+ * Using false, or some string value (like "off") will result in clients who do not understand that property failing, whereas
+ * we want them to continue to collaborate alongside clients who support that capability, but such capability is shipping dark for now.
+ * @alpha
+ */
+export declare type DocumentSchemaValueType = string | true | number | undefined;
+
+/**
+ * Controller of document schema.
+ *
+ * Recommended pre-reading: https://github.com/microsoft/FluidFramework/blob/main/packages/dds/SchemaVersioning.md
+ *
+ * This class manages current document schema and transitions between document schemas.
+ * At the moment, it only focuses on subset of document schema, specifically - how FluidFramework runtime serializes data
+ * (summary and op format), features & capabilities that a version of runtime has to support and understand in
+ * order to collaborate on a document.
+ * New features that modify document format have to be included in document schema definition.
+ * Usage of such features could only happen after document schema has been updated to reflect such feature.
+ *
+ * This formality allows clients that do not understand such features to fail right away when they observe
+ * document schema listing capabilities that such client does not understand.
+ * Old clients will fail in predictable way. This allows us to
+ * 1) Immediately see such issues and adjust if features are enabled too early, before changes have been saturated.
+ * 2) There is no way to get to 100% saturation with new code. Even if we have 99.99% saturation, there are
+ *    still 0.01% of clients who will fail. Failing early and predictably ensures they have no chance to limp along
+ *    and potentially corrupt the document. This is especially true for summarizer client, who could simply "undo"
+ *    changes it does not understands.
+ *
+ * It's important to note how it overlaps with feature gates and safe velocity.
+ * If new feature was in use, that resulted in a number of documents referencing such feature in document schema.
+ * But, developers (through code deployment or feature gates) could disable usage of such features.
+ * That will stop a process of further document schema changes (for documents that were not using such feature).
+ * And documents that already list such capability in their schema will continue to do so. Later ensures that old
+ * clients who do not understand such feature will continue to fail to open such documents, as such documents very
+ * likely contain data in a new format.
+ *
+ * Users of this class need to use DocumentsSchemaController.sessionSchema to determine what features can be used.
+ *
+ * There are two modes this class can operate:
+ * 1) Legacy mode. In such mode it does not issue any ops to change document schema. Any changes happen implicitly,
+ *    right away, and new features are available right away
+ * 2) Non-legacy mode. In such mode any changes to schema require an op roundtrip. This class will manage such transitions.
+ *    However code should assume that any new features that were not enabled in a given document will not be available
+ *    for a given session. That's because this session may never send any ops (including read-only documents). Or it may
+ *    fail to convert schema.
+ *    This class promises eventual movement forward. I.e. if new feature is allowed (let's say - through feature gates),
+ *    then eventually all documents that are modified will have that feature reflected in their schema. It could require
+ *    multiple reloads / new sessions to get there (depends on if code reacts to schema changes right away, or only consults
+ *    schema on document load).
+ *
+ * How schemas are changed (in non-legacy mode):
+ * If a client needs to change a schema, it will attempt to do so as part of normal ops sending process.
+ * Changes happen in CAS (Compare-and-swap) fashion, i.e. client tells current schema and schema it wants to change to.
+ * When a number of clients race to change a schema, then only one of them will win, all others will fail because they will
+ * reference old schema that is no longer in effect.
+ * Clients can retry, but current implementation is simply - they will not (and will rely on next session / reload to do
+ * recalc and decide if schema needs to be changed or not).
+ *
+ * @alpha
+ */
+export declare class DocumentsSchemaController {
+    private readonly onSchemaChange;
+    private explicitSchemaControl;
+    private sendOp;
+    private documentSchema;
+    private readonly desiredSchema;
+    private futureSchema;
+    sessionSchema: IDocumentSchemaCurrent;
+    /**
+     * Constructs DocumentsSchemaController that controls current schema and processes around it, including changes in schema.
+     * @param explicitSchemaControl - Tells if schema changes are done implicitly (without ops - legacy behavior), or go through formal schema change ops process.
+     * @param existing - Is the document existing document, or a new doc.
+     * @param documentMetadataSchema - current document's schema, if present.
+     * @param compressionAlgorithm - desired compression algorith to use
+     * @param idCompressorModeArg - desired ID compressor mode to use
+     * @param opGroupingEnabled - true if it's desired to use op grouping.
+     */
+    constructor(existing: boolean, documentMetadataSchema: IDocumentSchema | undefined, features: IDocumentSchemaFeatures, onSchemaChange: (schema: IDocumentSchemaCurrent) => void);
+    summarizeDocumentSchema(refSeq: number): IDocumentSchemaCurrent | undefined;
+    onMessageSent(send: (content: IDocumentSchemaChangeMessage) => void): void;
+    /**
+     * Process document schema change message
+     * @param content - content of the message
+     * @param local - whether op is local
+     * @param sequenceNumber - sequence number of the op
+     * @returns - true if schema was accepted, otherwise false (rejected due to failed CAS)
+     */
+    processDocumentSchemaOp(content: IDocumentSchemaChangeMessage, local: boolean, sequenceNumber: number): boolean;
+    onDisconnect(): void;
+}
+
 /**
  * @alpha
  */
@@ -819,16 +937,17 @@ export declare interface IConnectableRuntime {
  */
 export declare interface IContainerRuntimeMetadata extends ICreateContainerMetadata, IGCMetadata {
     readonly summaryFormatVersion: 1;
+    /** @deprecated - used by old (prior to 2.0 RC3) runtimes */
+    readonly message?: ISummaryMetadataMessage;
     /** The last message processed at the time of summary. Only primitive property types are added to the summary. */
-    readonly message: ISummaryMetadataMessage | undefined;
+    readonly lastMessage?: ISummaryMetadataMessage;
     /** True if channels are not isolated in .channels subtrees, otherwise isolated. */
     readonly disableIsolatedChannels?: true;
     /** The summary number for a container's summary. Incremented on summaries throughout its lifetime. */
     readonly summaryNumber?: number;
     /** GUID to identify a document in telemetry */
     readonly telemetryDocumentId?: string;
-    /** True if the runtime IdCompressor is enabled */
-    readonly idCompressorMode?: IdCompressorMode;
+    readonly documentSchema?: IDocumentSchema;
 }
 
 /**
@@ -862,7 +981,7 @@ export declare interface IContainerRuntimeOptions {
      * If specified, when in FlushMode.TurnBased, if the size of the ops between JS turns exceeds this value,
      * an error will be thrown and the container will close.
      *
-     * If unspecified, the limit is 950 * 1024.
+     * If unspecified, the limit is 700Kb.
      *
      * 'Infinity' will disable any limit.
      *
@@ -909,6 +1028,14 @@ export declare interface IContainerRuntimeOptions {
      * @experimental Not ready for use.
      */
     readonly enableGroupedBatching?: boolean;
+    /**
+     * When this property is set to true, it requires runtime to control is document schema properly through ops
+     * The benefit of this mode is that clients who do not understand schema will fail in predictable way, with predictable message,
+     * and will not attempt to limp along, which could cause data corruptions and crashes in random places.
+     * When this property is not set (or set to false), runtime operates in legacy mode, where new features (modifying document schema)
+     * are engaged as they become available, without giving legacy clients any chance to fail predictably.
+     */
+    readonly explicitSchemaControl?: boolean;
 }
 
 /**
@@ -928,12 +1055,81 @@ export declare interface ICreateContainerMetadata {
  * "delayed" - ID compressor bundle is loaded only on establishing of first delta connection, i.e. it does not impact boot of cotnainer.
  * In such mode IContainerRuntime.idCompressor is not made available (unless previous sessions of same document had it "On").
  * The only thing that is available is IContainerRuntime.generateDocumentUniqueId() that provides opportunistically short IDs.
- * "off" - ID compressor is not laoded (unless it is "on" due to previous session for same document having it "on").
+ * undefined - ID compressor is not loaded.
  * While IContainerRuntime.generateDocumentUniqueId() is available, it will produce long IDs that are do not compress well.
  *
  * @alpha
  */
-export declare type IdCompressorMode = "on" | "delayed" | "off";
+export declare type IdCompressorMode = "on" | "delayed" | undefined;
+
+/**
+ * Document schema information.
+ * Describes overall shape of document schema, including unknown (to this version) properties.
+ *
+ * Used by runtime to make a call if it can understand document schema.
+ * If it can't, it should not continue with document and immediately fail, preventing random (cryptic) failures
+ * down the road and potentially corrupting documents.
+ * For now this structure and appropriate interpretation / behavior is focused only on runtime features.
+ * In the future that could be interpolated to more areas, including DDSs used, and even possibly - application
+ * schema.
+ *
+ * Runtime will ignore any properties at the root that it does not understand (i.e. IDocumentSchema.app), but will
+ * stop (and fail session) on any unknown properties within "runtime" sub-tree.
+ *
+ * In most cases values preserved in the document will not dictate if such features should be enabled in a given session.
+ * I.e. if compression is mentioned in document schema, this means that runtime version that opens such document must know
+ * how to interpret such ops, but does not need to actually use compression itself. That said, some options could be
+ * sticky, i.e. influence feature selection for all runtimes opening a document. ID compression is one such example.
+ * Currently there is no mechanism to remove feature from this property bag, i.e. once compression was used, even if it's
+ * disabled (through feature gate or code deployment), all existing documents that used compression will continue to fail
+ * if opened by clients who do not support compression.
+ *
+ * For now we are limiting it to just plain properties, and only really simple types, but that can be changed in the future.
+ *
+ * @alpha
+ */
+export declare interface IDocumentSchema {
+    version: number;
+    refSeq: number;
+    runtime: Record<string, DocumentSchemaValueType>;
+}
+
+/**
+ * Content of the type=ContainerMessageType.DocumentSchemaChange ops.
+ * The meaning of refSeq field is different in such messages (compared to other usages of IDocumentSchemaCurrent)
+ * ContainerMessageType.DocumentSchemaChange messages use CAS (Compare-and-swap) semantics, and convey
+ * regSeq of last known schema change (known to a client proposing schema change).
+ * @see ContainerRuntimeDocumentSchemaMessage
+ * @alpha
+ */
+export declare type IDocumentSchemaChangeMessage = IDocumentSchema;
+
+/**
+ * Current document schema.
+ * @alpha
+ */
+export declare type IDocumentSchemaCurrent = {
+    version: 1;
+    refSeq: number;
+    runtime: {
+        [P in keyof IDocumentSchemaFeatures]?: IDocumentSchemaFeatures[P] extends boolean ? true : IDocumentSchemaFeatures[P];
+    };
+};
+
+/**
+ * Settings that this session would like to have, based on options and feature gates.
+ *
+ * WARNING: This type is used to infer IDocumentSchemaCurrent type!
+ * Any changes here (including renaming of properties) are potentially changing document format and should be considered carefully!
+ *
+ * @alpha
+ */
+export declare interface IDocumentSchemaFeatures {
+    explicitSchemaControl: boolean;
+    compressionLz4: boolean;
+    idCompressorMode: IdCompressorMode;
+    opGroupingEnabled: boolean;
+}
 
 /**
  * Options to use when enqueueing a summarize attempt.
@@ -1563,8 +1759,6 @@ export declare type OpActionEventName = MessageType.Summarize | MessageType.Summ
 
 /* Excluded from this release type: RuntimeHeaders */
 
-/* Excluded from this release type: RuntimeMessage */
-
 /**
  * The data in summarizer result when submit summary stage fails.
  * @alpha

package/lib/container-runtime-beta.d.ts

@@ -88,12 +88,20 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: CreateChildSummarizerNodeParam */
 
+/* Excluded from this release type: currentDocumentVersionSchema */
+
 /* Excluded from this release type: DataStoreContexts */
 
 /* Excluded from this release type: DefaultSummaryConfiguration */
 
 /* Excluded from this release type: detectOutboundReferences */
 
+/* Excluded from this release type: disabledCompressionConfig */
+
+/* Excluded from this release type: DocumentSchemaValueType */
+
+/* Excluded from this release type: DocumentsSchemaController */
+
 /* Excluded from this release type: EnqueueSummarizeResult */
 
 /* Excluded from this release type: FluidDataStoreContext */
@@ -152,6 +160,14 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: IdCompressorMode */
 
+/* Excluded from this release type: IDocumentSchema */
+
+/* Excluded from this release type: IDocumentSchemaChangeMessage */
+
+/* Excluded from this release type: IDocumentSchemaCurrent */
+
+/* Excluded from this release type: IDocumentSchemaFeatures */
+
 /* Excluded from this release type: IDocumentStorageService */
 
 /* Excluded from this release type: IEnqueueSummarizeOptions */
@@ -288,8 +304,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: RuntimeHeaders */
 
-/* Excluded from this release type: RuntimeMessage */
-
 /* Excluded from this release type: SubmitSummaryFailureData */
 
 /* Excluded from this release type: SubmitSummaryResult */

package/lib/container-runtime-public.d.ts

@@ -88,12 +88,20 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: CreateChildSummarizerNodeParam */
 
+/* Excluded from this release type: currentDocumentVersionSchema */
+
 /* Excluded from this release type: DataStoreContexts */
 
 /* Excluded from this release type: DefaultSummaryConfiguration */
 
 /* Excluded from this release type: detectOutboundReferences */
 
+/* Excluded from this release type: disabledCompressionConfig */
+
+/* Excluded from this release type: DocumentSchemaValueType */
+
+/* Excluded from this release type: DocumentsSchemaController */
+
 /* Excluded from this release type: EnqueueSummarizeResult */
 
 /* Excluded from this release type: FluidDataStoreContext */
@@ -152,6 +160,14 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: IdCompressorMode */
 
+/* Excluded from this release type: IDocumentSchema */
+
+/* Excluded from this release type: IDocumentSchemaChangeMessage */
+
+/* Excluded from this release type: IDocumentSchemaCurrent */
+
+/* Excluded from this release type: IDocumentSchemaFeatures */
+
 /* Excluded from this release type: IDocumentStorageService */
 
 /* Excluded from this release type: IEnqueueSummarizeOptions */
@@ -288,8 +304,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: RuntimeHeaders */
 
-/* Excluded from this release type: RuntimeMessage */
-
 /* Excluded from this release type: SubmitSummaryFailureData */
 
 /* Excluded from this release type: SubmitSummaryResult */