Packages > @fluidframework/runtime-definitions

@fluidframework/runtime-definitions Package

Interfaces

Interface Alerts Description
DetachedAttributionKey ALPHA AttributionKey associated with content that was inserted while the container was in a detached state.
IContainerRuntimeBase ALPHA A reduced set of functionality of IContainerRuntime that a data store context/data store runtime will need TODO: this should be merged into IFluidDataStoreContext
IContainerRuntimeBaseEvents ALPHA
IDataStore ALPHA Exposes some functionality/features of a data store: - Handle to the data store's entryPoint - Fluid router for the data store - Can be assigned an alias
IdCreationRange ALPHA

Data describing a range of session-local IDs (from a remote or local session).

A range is composed of local IDs that were generated.

IExperimentalIncrementalSummaryContext ALPHA - Can be deleted/changed at any time Contains the necessary information to allow DDSes to do incremental summaries
IFluidDataStoreChannel ALPHA

Minimal interface a data store runtime needs to provide for IFluidDataStoreContext to bind to control.

Functionality include attach, snapshot, op/signal processing, request routes, expose an entryPoint, and connection state notifications

IFluidDataStoreContext ALPHA Represents the context for the data store. It is used by the data store runtime to get information and call functionality to the container.
IFluidDataStoreContextDetached ALPHA
IFluidDataStoreContextEvents ALPHA
IFluidDataStoreFactory ALPHA IFluidDataStoreFactory create data stores. It is associated with an identifier (its type member) and usually provided to consumers using this mapping through a data store registry.
IFluidDataStoreRegistry ALPHA An association of identifiers to data store registry entries, where the entries can be used to create data stores.
IGarbageCollectionData ALPHA Garbage collection data returned by nodes in a Container. Used for running GC in the Container.
IGarbageCollectionDetailsBase ALPHA GC details provided to each node during creation.
IIdCompressor ALPHA

A distributed UUID generator and compressor.

Generates arbitrary non-colliding v4 UUIDs, called stable IDs, for multiple "sessions" (which can be distributed across the network), providing each session with the ability to map these UUIDs to numbers.

A session is a unique identifier that denotes a single compressor. New IDs are created through a single compressor API which should then sent in ranges to the server for total ordering (and are subsequently relayed to other clients). When a new ID is created it is said to be created by the compressor's "local" session.

For each stable ID created, two numeric IDs are provided by the compressor:

1. A session-local ID, which is stable for the lifetime of the session (which could be longer than that of the compressor object, as it may be serialized for offline usage). Available as soon as the stable ID is allocated. These IDs are session-unique and are thus only safely usable within the scope of the compressor that created it.

2. A final ID, which is stable across serialization and deserialization of an IdCompressor. Available as soon as the range containing the corresponding session-local ID is totally ordered (via consensus) with respect to other sessions' allocations. Final IDs are known to and publicly usable by any compressor that has received them.

Compressors will allocate UUIDs in non-random ways to reduce entropy allowing for optimized storage of the data needed to map the UUIDs to the numbers.

The following invariants are upheld by IdCompressor:

1. Session-local IDs will always decompress to the same UUIDs for the lifetime of the session.

2. Final IDs will always decompress to the same UUIDs.

3. After a server-processed range of session-local IDs (from any session) is received by a compressor, any of those session-local IDs may be translated by the compressor into the corresponding final ID. For any given session-local ID, this translation will always yield the same final ID.

4. A UUID will always compress into the same session-local ID for the lifetime of the session.

Session-local IDs are sent across the wire in efficiently-represented ranges. These ranges are created by querying the compressor, and *must* be ordered (i.e. sent to the server) in the order they are created in order to preserve the above invariants.

Session-local IDs can be used immediately after creation, but will eventually (after being sequenced) have a corresponding final ID. This could make reasoning about equality of those two forms difficult. For example, if a cache is keyed off of a session-local ID but is later queried using the final ID (which is semantically equal, as it decompresses to the same UUID/string) it will produce a cache miss. In order to make using collections of both remotely created and locally created IDs easy, regardless of whether the session-local IDs have been finalized, the compressor defines two "spaces" of IDs:

1. Session space: in this space, all IDs are normalized to their "most local form". This means that all IDs created by the local session will be in local form, regardless of if they have been finalized. Remotely created IDs, which could only have been received after finalizing and will never have a local form for the compressor, will of course be final IDs. This space should be used with consumer APIs and data structures, as the lifetime of the IDs is guaranteed to be the same as the compressor object. Care must be taken to not use these IDs across compressor objects, as the local IDs are specific to the compressor that created them.

2. Op space: in this space, all IDs are normalized to their "most final form". This means that all IDs except session-local IDs that have not yet been finalized will be in final ID form. This space is useful for serialization in ops (e.g. references), as other clients that receive them need not do any work to normalize them to *their* session-space in the common case. Note that IDs in op space may move out of Op space over time, namely, when a session-local ID in this space becomes finalized, and thereafter has a "more final form". Consequentially, it may be useful to restrict parameters of a persisted type to this space (to optimize perf), but it is potentially incorrect to use this type for a runtime variable. This is an asymmetry that does not affect session space, as local IDs are always as "local as possible".

These two spaces naturally define a rule: consumers of compressed IDs should use session-space IDs, but serialized forms such as ops should use op-space IDs.

IIdCompressorCore ALPHA
IInboundSignalMessage ALPHA Represents ISignalMessage with its type.
IProvideFluidDataStoreFactory ALPHA
IProvideFluidDataStoreRegistry ALPHA
ISummarizeInternalResult ALPHA Contains the same data as ISummaryResult but in order to avoid naming collisions, the data store summaries are wrapped around an array of labels identified by pathPartsForChildren.
ISummarizeResult ALPHA Represents a summary at a current sequence number.
ISummarizerNode ALPHA
ISummarizerNodeConfig ALPHA
ISummarizerNodeConfigWithGC ALPHA
ISummarizerNodeWithGC ALPHA

Extends the functionality of ISummarizerNode to support garbage collection. It adds / updates the following APIs:

usedRoutes: The routes in this node that are currently in use.

getGCData: A new API that can be used to get the garbage collection data for this node.

summarize: Added a trackState flag which indicates whether the summarizer node should track the state of the summary or not.

createChild: Added the following params:

- getGCDataFn: This gets the GC data from the caller. This must be provided in order for getGCData to work.

- getInitialGCDetailsFn: This gets the initial GC details from the caller.

deleteChild: Deletes a child node.

isReferenced: This tells whether this node is referenced in the document or not.

updateUsedRoutes: Used to notify this node of routes that are currently in use in it.

ISummaryStats ALPHA Contains the aggregation data from a Tree/Subtree.
ISummaryTreeWithStats ALPHA Represents the summary tree for a node along with the statistics for that tree. For example, for a given data store, it contains the data for data store along with a subtree for each of its DDS. Any component that implements IChannelContext, IFluidDataStoreChannel or extends SharedObject will be taking part of the summarization process.
ITelemetryContext ALPHA Contains telemetry data relevant to summarization workflows. This object is expected to be modified directly by various summarize methods.
LocalAttributionKey ALPHA AttributionKey associated with content that has been made locally but not yet acked by the server.
OpAttributionKey ALPHA AttributionKey representing a reference to some op in the op stream. Content associated with this key aligns with content modified by that op.

Enumerations

Enum Alerts Description
CreateSummarizerNodeSource ALPHA
FlushMode ALPHA Runtime flush mode handling

Types

TypeAlias Alerts Description
AliasResult ALPHA

Encapsulates the return codes of the aliasing API.

'Success' - the datastore has been successfully aliased. It can now be used. 'Conflict' - there is already a datastore bound to the provided alias. To acquire it's entry point, use the IContainerRuntime.getAliasedDataStoreEntryPoint function. The current datastore should be discarded and will be garbage collected. The current datastore cannot be aliased to a different value. 'AlreadyAliased' - the datastore has already been previously bound to another alias name.

AttributionKey ALPHA Can be indexed into the ContainerRuntime in order to retrieve AttributionInfo.
CreateChildSummarizerNodeFn ALPHA
CreateChildSummarizerNodeParam ALPHA
FluidDataStoreRegistryEntry ALPHA A single registry entry that may be used to create data stores It has to have either factory or registry, or both.
NamedFluidDataStoreRegistryEntries ALPHA An iterable identifier/registry entry pair list
NamedFluidDataStoreRegistryEntry ALPHA An associated pair of an identifier and registry entry. Registry entries may be dynamically loaded.
OpSpaceCompressedId ALPHA A compressed ID that has been normalized into "op space". Serialized/persisted structures (e.g. ops) should use op-space IDs as a performance optimization, as they require less normalizing when received by a remote client due to the fact that op space for a given compressor is session space for all other compressors.
SerializedIdCompressor ALPHA The serialized contents of an IdCompressor, suitable for persistence in a summary.
SerializedIdCompressorWithNoSession ALPHA The serialized contents of an IdCompressor, suitable for persistence in a summary.
SerializedIdCompressorWithOngoingSession ALPHA The serialized contents of an IdCompressor, suitable for persistence in a summary.
SessionId ALPHA A StableId which is suitable for use as a session identifier
SessionSpaceCompressedId ALPHA A compressed ID that has been normalized into "session space" (see IdCompressor for more). Consumer-facing APIs and data structures should use session-space IDs as their lifetime and equality is stable and tied to the scope of the session (i.e. compressor) that produced them.
StableId ALPHA A version 4, variant 1 uuid (https://datatracker.ietf.org/doc/html/rfc4122). A 128-bit Universally Unique IDentifier. Represented here with a string of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where x is a lowercase hex digit.
SummarizeInternalFn ALPHA
VisibilityState ALPHA

Variables

Variable Alerts Modifiers Description
IFluidDataStoreFactory ALPHA readonly
IFluidDataStoreRegistry ALPHA readonly
VisibilityState ALPHA readonly This tells the visibility state of a Fluid object. It basically tracks whether the object is not visible, visible locally within the container only or visible globally to all clients.

Type Details

AliasResult (ALPHA)

Encapsulates the return codes of the aliasing API.

‘Success’ - the datastore has been successfully aliased. It can now be used. ‘Conflict’ - there is already a datastore bound to the provided alias. To acquire it’s entry point, use the IContainerRuntime.getAliasedDataStoreEntryPoint function. The current datastore should be discarded and will be garbage collected. The current datastore cannot be aliased to a different value. ‘AlreadyAliased’ - the datastore has already been previously bound to another alias name.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type AliasResult = "Success" | "Conflict" | "AlreadyAliased";

AttributionKey (ALPHA)

Can be indexed into the ContainerRuntime in order to retrieve AttributionInfo.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type AttributionKey = OpAttributionKey | DetachedAttributionKey | LocalAttributionKey;

CreateChildSummarizerNodeFn (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type CreateChildSummarizerNodeFn = (summarizeInternal: SummarizeInternalFn, getGCDataFn: (fullGC?: boolean) => Promise<IGarbageCollectionData>, 
getBaseGCDetailsFn?: () => Promise<IGarbageCollectionDetailsBase>) => ISummarizerNodeWithGC;

CreateChildSummarizerNodeParam (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type CreateChildSummarizerNodeParam = {
    type: CreateSummarizerNodeSource.FromSummary;
} | {
    type: CreateSummarizerNodeSource.FromAttach;
    sequenceNumber: number;
    snapshot: ITree;
} | {
    type: CreateSummarizerNodeSource.Local;
};

FluidDataStoreRegistryEntry (ALPHA)

A single registry entry that may be used to create data stores It has to have either factory or registry, or both.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FluidDataStoreRegistryEntry = Readonly<Partial<IProvideFluidDataStoreRegistry & IProvideFluidDataStoreFactory>>;

NamedFluidDataStoreRegistryEntries (ALPHA)

An iterable identifier/registry entry pair list

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type NamedFluidDataStoreRegistryEntries = Iterable<NamedFluidDataStoreRegistryEntry>;

NamedFluidDataStoreRegistryEntry (ALPHA)

An associated pair of an identifier and registry entry. Registry entries may be dynamically loaded.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type NamedFluidDataStoreRegistryEntry = [string, Promise<FluidDataStoreRegistryEntry>];

OpSpaceCompressedId (ALPHA)

A compressed ID that has been normalized into “op space”. Serialized/persisted structures (e.g. ops) should use op-space IDs as a performance optimization, as they require less normalizing when received by a remote client due to the fact that op space for a given compressor is session space for all other compressors.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type OpSpaceCompressedId = number & {
    readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
};

SerializedIdCompressor (ALPHA)

The serialized contents of an IdCompressor, suitable for persistence in a summary.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type SerializedIdCompressor = string & {
    readonly _serializedIdCompressor: "8c73c57c-1cf4-4278-8915-6444cb4f6af5";
};

SerializedIdCompressorWithNoSession (ALPHA)

The serialized contents of an IdCompressor, suitable for persistence in a summary.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type SerializedIdCompressorWithNoSession = SerializedIdCompressor & {
    readonly _noLocalState: "3aa2e1e8-cc28-4ea7-bc1a-a11dc3f26dfb";
};

SerializedIdCompressorWithOngoingSession (ALPHA)

The serialized contents of an IdCompressor, suitable for persistence in a summary.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type SerializedIdCompressorWithOngoingSession = SerializedIdCompressor & {
    readonly _hasLocalState: "1281acae-6d14-47e7-bc92-71c8ee0819cb";
};

SessionId (ALPHA)

A StableId which is suitable for use as a session identifier

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type SessionId = StableId & {
    readonly SessionId: "4498f850-e14e-4be9-8db0-89ec00997e58";
};

SessionSpaceCompressedId (ALPHA)

A compressed ID that has been normalized into “session space” (see IdCompressor for more). Consumer-facing APIs and data structures should use session-space IDs as their lifetime and equality is stable and tied to the scope of the session (i.e. compressor) that produced them.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type SessionSpaceCompressedId = number & {
    readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e";
};

StableId (ALPHA)

A version 4, variant 1 uuid (https://datatracker.ietf.org/doc/html/rfc4122) . A 128-bit Universally Unique IDentifier. Represented here with a string of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where x is a lowercase hex digit.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type StableId = string & {
    readonly StableId: "53172b0d-a3d5-41ea-bd75-b43839c97f5a";
};

SummarizeInternalFn (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type SummarizeInternalFn = (fullTree: boolean, trackState: boolean, telemetryContext?: ITelemetryContext, incrementalSummaryContext?: IExperimentalIncrementalSummaryContext) => Promise<ISummarizeInternalResult>;

VisibilityState (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type VisibilityState = (typeof VisibilityState)[keyof typeof VisibilityState];

Variable Details

IFluidDataStoreFactory (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

IFluidDataStoreFactory: keyof IProvideFluidDataStoreFactory

IFluidDataStoreRegistry (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

IFluidDataStoreRegistry: keyof IProvideFluidDataStoreRegistry

VisibilityState (ALPHA)

This tells the visibility state of a Fluid object. It basically tracks whether the object is not visible, visible locally within the container only or visible globally to all clients.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

VisibilityState: {
    NotVisible: string;
    LocallyVisible: string;
    GloballyVisible: string;
}