IContainerRuntimeBase Interface

A reduced set of functionality of IContainerRuntime that a data store context/data store runtime will need.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/runtime-definitions/legacy.

For more information about our API support guarantees, see here.

Sealed

This type is "sealed," meaning that code outside of the library defining it should not implement or extend it. Future versions of this type may add members or make typing of readonly members more specific.

Signature

/** @sealed */
export interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeBaseEvents>

Extends: IEventProvider<IContainerRuntimeBaseEvents>

Properties

Property	Alerts	Modifiers	Type	Description
baseLogger	Beta	readonly	ITelemetryBaseLogger
clientDetails	Beta	readonly	IClientDetails
disposed	Beta	readonly	boolean
hasStagedChanges	Beta	readonly	boolean	Returns true if there are any staged changes, i.e. changes submitted while in Staging Mode that have not yet been discarded or committed.
inStagingMode	Beta	readonly	boolean	If true, the ContainerRuntime is not submitting any new ops to the ordering service. Ops submitted to the ContainerRuntime while in Staging Mode will be queued in the PendingStateManager, either to be discarded or committed later (via the Stage Controls returned from enterStagingMode).
submitSignal	Beta		(type: string, content: unknown, targetClientId?: string) => void	Submits a container runtime level signal to be sent to other clients.

Methods

Method	Alerts	Return Type	Description
createDataStore(pkg, loadingGroupId)	Beta	Promise<IDataStore>	Creates a data store and returns an object that exposes a handle to the data store's entryPoint, and also serves as the data store's router. The data store is not bound to a container, and in such state is not persisted to storage (file). Storing the entryPoint handle (or any other handle inside the data store, e.g. for DDS) into an already attached DDS (or non-attached DDS that will eventually get attached to storage) will result in this store being attached to storage.
createDetachedDataStore(pkg, loadingGroupId)	Beta	IFluidDataStoreContextDetached	Creates detached data store context. Only after context.attachRuntime() is called, data store initialization is considered complete.
enterStagingMode()	Beta	StageControls	Enter Staging Mode, such that ops submitted to the ContainerRuntime will not be sent to the ordering service. To exit Staging Mode, call either discardChanges or commitChanges on the Stage Controls returned from this method.
generateDocumentUniqueId()	Beta	number | string	Generates a new ID that is guaranteed to be unique across all sessions for this container. It could be in compact form (non-negative integer, opportunistic), but it could also be UUID string. UUIDs generated will have low entropy in groups and will compress well. It can be leveraged anywhere in container where container unique IDs are required, i.e. any place that uses uuid() and stores result in container is likely candidate to start leveraging this API. If you always want to convert to string, instead of doing String(generateDocumentUniqueId()), consider doing encodeCompactIdToString(generateDocumentUniqueId()).
getAbsoluteUrl(relativeUrl)	Beta	Promise<string | undefined>	Get an absolute url for a provided container-relative request. Returns undefined if the container or data store isn't attached to storage.
getAliasedDataStoreEntryPoint(alias)	Beta	Promise<IFluidHandle<FluidObject> | undefined>	Returns the aliased data store's entryPoint, given the alias.
getAudience()	Beta	IAudience	Returns the current audience.
getQuorum()	Beta	IQuorumClients	Returns the current quorum.
getSnapshotForLoadingGroupId(loadingGroupIds, pathParts)	Beta	Promise<{ snapshotTree: ISnapshotTree; sequenceNumber: number; }>	Api to fetch the snapshot from the service for a loadingGroupIds.
orderSequentially(callback)	Beta	void	Invokes the given callback and guarantees that all operations generated within the callback will be ordered sequentially. If the callback throws an error, the container will close and the error will be logged.
uploadBlob(blob, signal)	Beta	Promise<IFluidHandle<ArrayBufferLike>>

Property Details

baseLogger

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly baseLogger: ITelemetryBaseLogger;

Type: ITelemetryBaseLogger

clientDetails

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly clientDetails: IClientDetails;

Type: IClientDetails

disposed

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly disposed: boolean;

Type: boolean

hasStagedChanges

Returns true if there are any staged changes, i.e. changes submitted while in Staging Mode that have not yet been discarded or committed.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly hasStagedChanges: boolean;

Type: boolean

Remarks

This is distinct from isDirty: a container may be dirty due to ordinary unacknowledged local changes without having any staged changes.

inStagingMode

If true, the ContainerRuntime is not submitting any new ops to the ordering service. Ops submitted to the ContainerRuntime while in Staging Mode will be queued in the PendingStateManager, either to be discarded or committed later (via the Stage Controls returned from enterStagingMode).

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly inStagingMode: boolean;

Type: boolean

See Also

enterStagingMode()

submitSignal

Submits a container runtime level signal to be sent to other clients.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

submitSignal: (type: string, content: unknown, targetClientId?: string) => void;

Type: (type: string, content: unknown, targetClientId?: string) => void

Method Details

createDataStore

Creates a data store and returns an object that exposes a handle to the data store's entryPoint, and also serves as the data store's router. The data store is not bound to a container, and in such state is not persisted to storage (file). Storing the entryPoint handle (or any other handle inside the data store, e.g. for DDS) into an already attached DDS (or non-attached DDS that will eventually get attached to storage) will result in this store being attached to storage.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

createDataStore(pkg: string | PackagePath, loadingGroupId?: string): Promise<IDataStore>;

Parameters

Parameter	Modifiers	Type	Description
pkg		string | PackagePath	Package name of the data store factory
loadingGroupId	optional	string	This represents the group of the datastore within a container or its snapshot. When not specified the datastore will belong to a default group. Read more about it in this README

Returns

Return type: Promise<IDataStore>

createDetachedDataStore

Creates detached data store context. Only after context.attachRuntime() is called, data store initialization is considered complete.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

createDetachedDataStore(pkg: readonly string[], loadingGroupId?: string): IFluidDataStoreContextDetached;

Parameters

Parameter	Modifiers	Type	Description
pkg		readonly string[]	Package name of the data store factory
loadingGroupId	optional	string	This represents the group of the datastore within a container or its snapshot. When not specified the datastore will belong to a default group. Read more about it in this README.

Returns

Return type: IFluidDataStoreContextDetached

enterStagingMode

Enter Staging Mode, such that ops submitted to the ContainerRuntime will not be sent to the ordering service. To exit Staging Mode, call either discardChanges or commitChanges on the Stage Controls returned from this method.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

enterStagingMode(): StageControls;

Remarks

Known limitations: - DDS rollback support may be incomplete — discardChanges may throw for some DDS implementations. - Squash-rebase semantics during commitChanges are not yet fully specified.

Returns

Controls for committing or discarding staged changes.

Return type: StageControls

generateDocumentUniqueId

Generates a new ID that is guaranteed to be unique across all sessions for this container. It could be in compact form (non-negative integer, opportunistic), but it could also be UUID string. UUIDs generated will have low entropy in groups and will compress well. It can be leveraged anywhere in container where container unique IDs are required, i.e. any place that uses uuid() and stores result in container is likely candidate to start leveraging this API. If you always want to convert to string, instead of doing String(generateDocumentUniqueId()), consider doing encodeCompactIdToString(generateDocumentUniqueId()).

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

generateDocumentUniqueId(): number | string;

Returns

Return type: number | string

See Also

generateDocumentUniqueId()

getAbsoluteUrl

Get an absolute url for a provided container-relative request. Returns undefined if the container or data store isn't attached to storage.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getAbsoluteUrl(relativeUrl: string): Promise<string | undefined>;

Parameters

Parameter	Type	Description
relativeUrl	string	A relative request within the container

Returns

Return type: Promise<string | undefined>

getAliasedDataStoreEntryPoint

Returns the aliased data store's entryPoint, given the alias.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getAliasedDataStoreEntryPoint(alias: string): Promise<IFluidHandle<FluidObject> | undefined>;

Parameters

Parameter	Type	Description
alias	string	The alias for the data store.

Returns

The data store's entry point (@fluidframework/core-interfaces#IFluidHandle) if it exists and is aliased. Returns undefined if no data store has been assigned the given alias.

Return type: Promise<IFluidHandle<FluidObject> | undefined>

getAudience

Returns the current audience.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getAudience(): IAudience;

Returns

Return type: IAudience

getQuorum

Returns the current quorum.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getQuorum(): IQuorumClients;

Returns

Return type: IQuorumClients

getSnapshotForLoadingGroupId

Api to fetch the snapshot from the service for a loadingGroupIds.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getSnapshotForLoadingGroupId(loadingGroupIds: string[], pathParts: string[]): Promise<{
        snapshotTree: ISnapshotTree;
        sequenceNumber: number;
    }>;

Parameters

Parameter	Type	Description
loadingGroupIds	string[]	LoadingGroupId for which the snapshot is asked for.
pathParts	string[]	Parts of the path, which we want to extract from the snapshot tree.

Returns

snapshotTree and the sequence number of the snapshot.

Return type: Promise<{ snapshotTree: ISnapshotTree; sequenceNumber: number; }>

orderSequentially

Invokes the given callback and guarantees that all operations generated within the callback will be ordered sequentially.

If the callback throws an error, the container will close and the error will be logged.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

orderSequentially(callback: () => void): void;

Remarks

orderSequentially may enter staging mode for the duration of the function. This is necessary for rolling back certain op types.

Parameters

Parameter	Type	Description
callback	() => void

uploadBlob

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

uploadBlob(blob: ArrayBufferLike, signal?: AbortSignal): Promise<IFluidHandle<ArrayBufferLike>>;

Parameters

Parameter	Modifiers	Type	Description
blob		ArrayBufferLike
signal	optional	AbortSignal

Returns

Return type: Promise<IFluidHandle<ArrayBufferLike>>