@fluidframework/container-runtime Package

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.

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!

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.

Controller operates with 4 schemas: - document schema: whatever we loaded from summary metadata + ops. It follows eventuall consistency rules (i.e. like DDS). - desired schema - what client is asking for to have (i.e. all the desired settings, based on runtime options / feature gates). - session schema - current session schema. It's "and" of the above two schemas. - future schema - "or" of document and desires schemas.

"or" & "and" operators are defined individually for each property. For Boolean properties it's literally &&, || operators. But for other properties it's more nuanced.

Whenver document schema does not match future schema, controller will send an op that attempts to changs documents schema to future schema.

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).

Strict type representing result of a submitSummary attempt. The result consists of 4 possible stages, each with its own data. The data is cumulative, so each stage will contain the data from the previous stages. If the final "submitted" stage is not reached, the result may contain the error object.

Stages:

1. "base" - stopped before the summary tree was even generated, and the result only contains the base data

2. "generate" - the summary tree was generated, and the result will contain that tree + stats

3. "upload" - the summary was uploaded to storage, and the result contains the server-provided handle

4. "submit" - the summarize op was submitted, and the result contains the op client sequence number.