DocumentsSchemaController Class
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).
To use, import via @fluidframework/container-runtime/legacy.
For more information about our API support guarantees, see here.
Signature
/** @sealed */
export declare class DocumentsSchemaController
Constructors
| Constructor | Alerts | Description |
|---|---|---|
| (constructor)(existing, snapshotSequenceNumber, documentMetadataSchema, features, onSchemaChange) | Alpha |
Constructs DocumentsSchemaController that controls current schema and processes around it, including changes in schema. |
Properties
| Property | Alerts | Type | Description |
|---|---|---|---|
| sessionSchema | Alpha |
IDocumentSchemaCurrent |
Constructor Details
(constructor)
Constructs DocumentsSchemaController that controls current schema and processes around it, including changes in schema.
To use, import via @fluidframework/container-runtime/alpha.
For more information about our API support guarantees, see here.
Signature
constructor(existing: boolean, snapshotSequenceNumber: number, documentMetadataSchema: IDocumentSchema | undefined, features: IDocumentSchemaFeatures, onSchemaChange: (schema: IDocumentSchemaCurrent) => void);
Parameters
| Parameter | Type | Description |
|---|---|---|
| existing | boolean | Is the document existing document, or a new doc. |
| snapshotSequenceNumber | number | |
| documentMetadataSchema | IDocumentSchema | undefined | current document's schema, if present. |
| features | IDocumentSchemaFeatures | features of the document schema that current session wants to see enabled. |
| onSchemaChange | (schema: IDocumentSchemaCurrent) => void | callback that is called whenever schema is changed (not called on creation / load, only when processing document schema change ops) |
Property Details
sessionSchema
To use, import via @fluidframework/container-runtime/alpha.
For more information about our API support guarantees, see here.
Signature
sessionSchema: IDocumentSchemaCurrent;
Type: IDocumentSchemaCurrent