Skip to main content
Version: v1

ContainerRuntime Class

Represents the runtime of the container. Contains helper functions/state of the container. It will define the store level mappings.

Signature​

export declare class ContainerRuntime extends TypedEventEmitter<IContainerRuntimeEvents> implements IContainerRuntime, IGarbageCollectionRuntime, IRuntime, ISummarizerRuntime, ISummarizerInternalsProvider

Extends: TypedEventEmitter<IContainerRuntimeEvents

Implements: IContainerRuntime, IGarbageCollectionRuntime, IRuntime, ISummarizerRuntime, ISummarizerInternalsProvider

Static Methods​

Method Return Type Description
load(context, registryEntries, requestHandler, runtimeOptions, containerScope, existing) Promise<ContainerRuntime> Load the stores from a snapshot and returns the runtime.

Properties​

Property Type Description
attachState AttachState
clientDetails IClientDetails
clientId string | undefined
closeFn (error?: ICriticalContainerError) => void
connected boolean
deltaManager IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>
disableIsolatedChannels boolean True if generating summaries with isolated channels is explicitly disabled. This only affects how summaries are written, and is the single source of truth for this container.
disposed boolean
enqueueSummarize ISummarizer["enqueueSummarize"]
flushMode FlushMode
IContainerRuntime this
IFluidDataStoreRegistry IFluidDataStoreRegistry
IFluidHandleContext IFluidHandleContext
IFluidRouter this
IFluidTokenProvider IFluidTokenProvider | undefined
isDirty boolean Returns true of container is dirty, i.e. there are some pending local changes that either were not sent out to delta stream or were not yet acknowledged.
logger ITelemetryLogger
options ILoaderOptions
reSubmitFn (type: ContainerMessageType, content: any, localOpMetadata: unknown, opMetadata: Record<string, unknown> | undefined) => void
scope FluidObject
storage IDocumentStorageService
summarizeOnDemand ISummarizer["summarizeOnDemand"]
summarizerClientId string | undefined clientId of parent (non-summarizing) container that owns summarizer container

Methods​

Method Alerts Return Type Description
_createDataStoreWithProps(pkg, props, id, isRoot) Promise<IDataStore>
addedGCOutboundReference(srcHandle, outboundHandle) void Called when a new outbound reference is added to another node. This is used by garbage collection to identify all references added in the system.
collectGarbage(options) Promise<IGCStats> Runs garbage collection and updates the reference / used state of the nodes in the container.
createDataStore(pkg) Promise<IDataStore>
createDetachedDataStore(pkg) IFluidDataStoreContextDetached
createDetachedRootDataStore(pkg, rootDataStoreId) IFluidDataStoreContextDetached
createRootDataStore(pkg, rootDataStoreId) Deprecated Promise<IFluidRouter>
createSummary(blobRedirectTable, telemetryContext) ISummaryTree Create a summary. Used when attaching or serializing a detached container.
deleteUnusedRoutes(unusedRoutes) void When running GC in test mode, this is called to delete objects whose routes are unused. This enables testing scenarios with accessing deleted content.
dispose(error) void
flush() void
getAbsoluteUrl(relativeUrl) Promise<string | undefined>
getAudience() IAudience
getCurrentReferenceTimestampMs() number | undefined Returns a server generated referenced timestamp to be used to track unreferenced nodes by GC.
getGCData(fullGC) Promise<IGarbageCollectionData> Implementation of IGarbageCollectionRuntime::getGCData. Generates and returns the GC data for this container.
getGCNodePackagePath(nodePath) Promise<readonly string[] | undefined> Called by GC to retrieve the package path of the node with the given path. The node should belong to a data store or an attachment blob.
getNodeType(nodePath) GCNodeType Returns the type of the GC node. Currently, there are nodes that belong to the root ("/"), data stores or blob manager.
getPendingLocalState() IPendingRuntimeState
getQuorum() IQuorumClients
getRootDataStore(id, wait) Promise<IFluidRouter>
getSnapshotBlobs() Promise<void>
notifyAttaching(snapshot) void
orderSequentially(callback) void
process(messageArg, local) void
processSignal(message, local) void
refreshLatestSummaryAck(proposalHandle, ackHandle, summaryRefSeq, summaryLogger) Promise<void> Implementation of ISummarizerInternalsProvider.refreshLatestSummaryAck
request(request) Promise<IResponse> Notifies this object about the request made to the container.
resolveHandle(request) Promise<IResponse> Resolves URI representing handle
setAttachState(attachState) void
setConnectionState(connected, clientId) void
setFlushMode(mode) void
submitDataStoreAliasOp(contents, localOpMetadata) void
submitDataStoreOp(id, contents, localOpMetadata) void
submitDataStoreSignal(address, type, content) void
submitSignal(type, content) void Submits the signal to be sent to other clients.
submitSummary(options) Promise<SubmitSummaryResult> Generates the summary tree, uploads it to storage, and then submits the summarize op. This is intended to be called by the summarizer, since it is the implementation of ISummarizerInternalsProvider.submitSummary. It takes care of state management at the container level, including pausing inbound op processing, updating SummarizerNode state tracking, and garbage collection.
summarize(options) Promise<IRootSummaryTreeWithStats> Returns a summary of the runtime at the current sequence number.
updateStateBeforeGC() Promise<void> Implementation of IGarbageCollectionRuntime::updateStateBeforeGC. Before GC runs, called by the garbage collector to update any pending GC state. This is mainly used to notify the garbage collector of references detected since the last GC run. Most references are notified immediately but there can be some for which async operation is required (such as detecting new root data stores).
updateUsedRoutes(usedRoutes, gcTimestamp) void Implementation of IGarbageCollectionRuntime::updateUsedRoutes. After GC has run, called to notify this container's nodes of routes that are used in it.
uploadBlob(blob) Promise<IFluidHandle<ArrayBufferLike>>

Property Details​

attachState​

Signature​
get attachState(): AttachState;

Type: AttachState

clientDetails​

Signature​
get clientDetails(): IClientDetails;

Type: IClientDetails

clientId​

Signature​
get clientId(): string | undefined;

Type: string | undefined

closeFn​

Signature​
get closeFn(): (error?: ICriticalContainerError) => void;

Type: (error?: ICriticalContainerError) => void

connected​

Signature​
get connected(): boolean;

Type: boolean

deltaManager​

Signature​
get deltaManager(): IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;

Type: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>

disableIsolatedChannels​

True if generating summaries with isolated channels is explicitly disabled. This only affects how summaries are written, and is the single source of truth for this container.

Signature​
readonly disableIsolatedChannels: boolean;

Type: boolean

disposed​

Signature​
get disposed(): boolean;

Type: boolean

enqueueSummarize​

Signature​
readonly enqueueSummarize: ISummarizer["enqueueSummarize"];

Type: ISummarizer["enqueueSummarize"]

flushMode​

Signature​
get flushMode(): FlushMode;

Type: FlushMode

IContainerRuntime​

Signature​
get IContainerRuntime(): this;

Type: this

IFluidDataStoreRegistry​

Signature​
get IFluidDataStoreRegistry(): IFluidDataStoreRegistry;

Type: IFluidDataStoreRegistry

IFluidHandleContext​

Signature​
get IFluidHandleContext(): IFluidHandleContext;

Type: IFluidHandleContext

IFluidRouter​

Signature​
get IFluidRouter(): this;

Type: this

IFluidTokenProvider​

Signature​
get IFluidTokenProvider(): IFluidTokenProvider | undefined;

Type: IFluidTokenProvider | undefined

isDirty​

Returns true of container is dirty, i.e. there are some pending local changes that either were not sent out to delta stream or were not yet acknowledged.

Signature​
get isDirty(): boolean;

Type: boolean

logger​

Signature​
readonly logger: ITelemetryLogger;

Type: ITelemetryLogger

options​

Signature​
get options(): ILoaderOptions;

Type: ILoaderOptions

reSubmitFn​

Signature​
get reSubmitFn(): (type: ContainerMessageType, content: any, localOpMetadata: unknown, opMetadata: Record<string, unknown> | undefined) => void;

Type: (type: ContainerMessageType, content: any, localOpMetadata: unknown, opMetadata: Record<string, unknown> | undefined) => void

scope​

Signature​
get scope(): FluidObject;

Type: FluidObject

storage​

Signature​
get storage(): IDocumentStorageService;

Type: IDocumentStorageService

summarizeOnDemand​

Signature​
readonly summarizeOnDemand: ISummarizer["summarizeOnDemand"];

Type: ISummarizer["summarizeOnDemand"]

summarizerClientId​

clientId of parent (non-summarizing) container that owns summarizer container

Signature​
get summarizerClientId(): string | undefined;

Type: string | undefined

Method Details​

_createDataStoreWithProps​

Signature​
_createDataStoreWithProps(pkg: string | string[], props?: any, id?: string, isRoot?: boolean): Promise<IDataStore>;

Parameters​

Parameter Modifiers Type Description
pkg string | string[]
props optional any
id optional string
isRoot optional boolean

Returns​

Return type: Promise<IDataStore>

addedGCOutboundReference​

Called when a new outbound reference is added to another node. This is used by garbage collection to identify all references added in the system.

Signature​
addedGCOutboundReference(srcHandle: IFluidHandle, outboundHandle: IFluidHandle): void;

Parameters​

Parameter Type Description
srcHandle IFluidHandle The handle of the node that added the reference.
outboundHandle IFluidHandle The handle of the outbound node that is referenced.

collectGarbage​

Runs garbage collection and updates the reference / used state of the nodes in the container.

Signature​
collectGarbage(options: {
        logger?: ITelemetryLogger;
        runSweep?: boolean;
        fullGC?: boolean;
    }): Promise<IGCStats>;

Parameters​

Parameter Type Description
options { logger?: ITelemetryLogger; runSweep?: boolean; fullGC?: boolean; }

Returns​

the statistics of the garbage collection run.

Return type: Promise<IGCStats>

createDataStore​

Signature​
createDataStore(pkg: string | string[]): Promise<IDataStore>;

Parameters​

Parameter Type Description
pkg string | string[]

Returns​

Return type: Promise<IDataStore>

createDetachedDataStore​

Signature​
createDetachedDataStore(pkg: Readonly<string[]>): IFluidDataStoreContextDetached;

Parameters​

Parameter Type Description
pkg Readonly<string[]>

Returns​

Return type: IFluidDataStoreContextDetached

createDetachedRootDataStore​

Signature​
createDetachedRootDataStore(pkg: Readonly<string[]>, rootDataStoreId: string): IFluidDataStoreContextDetached;

Parameters​

Parameter Type Description
pkg Readonly<string[]>
rootDataStoreId string

Returns​

Return type: IFluidDataStoreContextDetached

createRootDataStore​

This API is deprecated and will be removed in a future release.
  • will be removed in an upcoming release. See #9660.
Signature​
createRootDataStore(pkg: string | string[], rootDataStoreId: string): Promise<IFluidRouter>;

Parameters​

Parameter Type Description
pkg string | string[]
rootDataStoreId string

Returns​

Return type: Promise<IFluidRouter>

createSummary​

Create a summary. Used when attaching or serializing a detached container.

Signature​
createSummary(blobRedirectTable?: Map<string, string>, telemetryContext?: ITelemetryContext): ISummaryTree;

Parameters​

Parameter Modifiers Type Description
blobRedirectTable optional Map<string, string> A table passed during the attach process. While detached, blob upload is supported using IDs generated locally. After attach, these IDs cannot be used, so this table maps the old local IDs to the new storage IDs so requests can be redirected.
telemetryContext optional ITelemetryContext summary data passed through the layers for telemetry purposes

Returns​

Return type: ISummaryTree

deleteUnusedRoutes​

When running GC in test mode, this is called to delete objects whose routes are unused. This enables testing scenarios with accessing deleted content.

Signature​
deleteUnusedRoutes(unusedRoutes: string[]): void;

Parameters​

Parameter Type Description
unusedRoutes string[] The routes that are unused in all data stores in this Container.

dispose​

Signature​
dispose(error?: Error): void;

Parameters​

Parameter Modifiers Type Description
error optional Error

flush​

Signature​
flush(): void;

getAbsoluteUrl​

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

Parameters​

Parameter Type Description
relativeUrl string

Returns​

Return type: Promise<string | undefined>

getAudience​

Signature​
getAudience(): IAudience;

Returns​

Return type: IAudience

getCurrentReferenceTimestampMs​

Returns a server generated referenced timestamp to be used to track unreferenced nodes by GC.

Signature​
getCurrentReferenceTimestampMs(): number | undefined;

Returns​

Return type: number | undefined

getGCData​

Implementation of IGarbageCollectionRuntime::getGCData. Generates and returns the GC data for this container.

Signature​
getGCData(fullGC?: boolean): Promise<IGarbageCollectionData>;

Parameters​

Parameter Modifiers Type Description
fullGC optional boolean true to bypass optimizations and force full generation of GC data.

Returns​

Return type: Promise<IGarbageCollectionData>

getGCNodePackagePath​

Called by GC to retrieve the package path of the node with the given path. The node should belong to a data store or an attachment blob.

Signature​
getGCNodePackagePath(nodePath: string): Promise<readonly string[] | undefined>;

Parameters​

Parameter Type Description
nodePath string

Returns​

Return type: Promise<readonly string[] | undefined>

getNodeType​

Returns the type of the GC node. Currently, there are nodes that belong to the root ("/"), data stores or blob manager.

Signature​
getNodeType(nodePath: string): GCNodeType;

Parameters​

Parameter Type Description
nodePath string

Returns​

Return type: GCNodeType

getPendingLocalState​

Signature​
getPendingLocalState(): IPendingRuntimeState;

Returns​

Return type: IPendingRuntimeState

getQuorum​

Signature​
getQuorum(): IQuorumClients;

Returns​

Return type: IQuorumClients

getRootDataStore​

Signature​
getRootDataStore(id: string, wait?: boolean): Promise<IFluidRouter>;

Parameters​

Parameter Modifiers Type Description
id string
wait optional boolean

Returns​

Return type: Promise<IFluidRouter>

getSnapshotBlobs​

Signature​
getSnapshotBlobs(): Promise<void>;

Returns​

Return type: Promise<void>

load​

Load the stores from a snapshot and returns the runtime.

Signature​
static load(context: IContainerContext, registryEntries: NamedFluidDataStoreRegistryEntries, requestHandler?: (request: IRequest, runtime: IContainerRuntime) => Promise<IResponse>, runtimeOptions?: IContainerRuntimeOptions, containerScope?: FluidObject, existing?: boolean): Promise<ContainerRuntime>;

Parameters​

Parameter Modifiers Type Description
context IContainerContext Context of the container.
registryEntries NamedFluidDataStoreRegistryEntries Mapping to the stores.
requestHandler optional (request: IRequest, runtime: IContainerRuntime) => Promise<IResponse> Request handlers for the container runtime
runtimeOptions optional IContainerRuntimeOptions Additional options to be passed to the runtime
containerScope optional FluidObject
existing optional boolean (optional) When loading from an existing snapshot. Precedes context.existing if provided

Returns​

Return type: Promise<ContainerRuntime>

notifyAttaching​

Signature​
notifyAttaching(snapshot: ISnapshotTreeWithBlobContents): void;

Parameters​

Parameter Type Description
snapshot ISnapshotTreeWithBlobContents

orderSequentially​

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

Parameters​

Parameter Type Description
callback () => void

process​

Signature​
process(messageArg: ISequencedDocumentMessage, local: boolean): void;

Parameters​

Parameter Type Description
messageArg ISequencedDocumentMessage
local boolean

processSignal​

Signature​
processSignal(message: ISignalMessage, local: boolean): void;

Parameters​

Parameter Type Description
message ISignalMessage
local boolean

refreshLatestSummaryAck​

Implementation of ISummarizerInternalsProvider.refreshLatestSummaryAck

Signature​
refreshLatestSummaryAck(proposalHandle: string | undefined, ackHandle: string, summaryRefSeq: number, summaryLogger: ITelemetryLogger): Promise<void>;

Parameters​

Parameter Type Description
proposalHandle string | undefined
ackHandle string
summaryRefSeq number
summaryLogger ITelemetryLogger

Returns​

Return type: Promise<void>

request​

Notifies this object about the request made to the container.

Signature​
request(request: IRequest): Promise<IResponse>;

Parameters​

Parameter Type Description
request IRequest Request made to the handler.

Returns​

Return type: Promise<IResponse>

resolveHandle​

Resolves URI representing handle

Signature​
resolveHandle(request: IRequest): Promise<IResponse>;

Parameters​

Parameter Type Description
request IRequest Request made to the handler.

Returns​

Return type: Promise<IResponse>

setAttachState​

Signature​
setAttachState(attachState: AttachState.Attaching | AttachState.Attached): void;

Parameters​

Parameter Type Description
attachState AttachState.Attaching | AttachState.Attached

setConnectionState​

Signature​
setConnectionState(connected: boolean, clientId?: string): void;

Parameters​

Parameter Modifiers Type Description
connected boolean
clientId optional string

setFlushMode​

Signature​
setFlushMode(mode: FlushMode): void;

Parameters​

Parameter Type Description
mode FlushMode

submitDataStoreAliasOp​

Signature​
submitDataStoreAliasOp(contents: any, localOpMetadata: unknown): void;

Parameters​

Parameter Type Description
contents any
localOpMetadata unknown

submitDataStoreOp​

Signature​
submitDataStoreOp(id: string, contents: any, localOpMetadata?: unknown): void;

Parameters​

Parameter Modifiers Type Description
id string
contents any
localOpMetadata optional unknown

submitDataStoreSignal​

Signature​
submitDataStoreSignal(address: string, type: string, content: any): void;

Parameters​

Parameter Type Description
address string
type string
content any

submitSignal​

Submits the signal to be sent to other clients.

Signature​
submitSignal(type: string, content: any): void;

Parameters​

Parameter Type Description
type string Type of the signal.
content any Content of the signal.

submitSummary​

Generates the summary tree, uploads it to storage, and then submits the summarize op. This is intended to be called by the summarizer, since it is the implementation of ISummarizerInternalsProvider.submitSummary. It takes care of state management at the container level, including pausing inbound op processing, updating SummarizerNode state tracking, and garbage collection.

Signature​
submitSummary(options: ISubmitSummaryOptions): Promise<SubmitSummaryResult>;

Parameters​

Parameter Type Description
options ISubmitSummaryOptions options controlling how the summary is generated or submitted

Returns​

Return type: Promise<SubmitSummaryResult>

summarize​

Returns a summary of the runtime at the current sequence number.

Signature​
summarize(options: {
        fullTree?: boolean;
        trackState?: boolean;
        summaryLogger?: ITelemetryLogger;
        runGC?: boolean;
        fullGC?: boolean;
        runSweep?: boolean;
    }): Promise<IRootSummaryTreeWithStats>;

Parameters​

Parameter Type Description
options { fullTree?: boolean; trackState?: boolean; summaryLogger?: ITelemetryLogger; runGC?: boolean; fullGC?: boolean; runSweep?: boolean; }

Returns​

Return type: Promise<IRootSummaryTreeWithStats>

updateStateBeforeGC​

Implementation of IGarbageCollectionRuntime::updateStateBeforeGC. Before GC runs, called by the garbage collector to update any pending GC state. This is mainly used to notify the garbage collector of references detected since the last GC run. Most references are notified immediately but there can be some for which async operation is required (such as detecting new root data stores).

Signature​
updateStateBeforeGC(): Promise<void>;

Returns​

Return type: Promise<void>

updateUsedRoutes​

Implementation of IGarbageCollectionRuntime::updateUsedRoutes. After GC has run, called to notify this container's nodes of routes that are used in it.

Signature​
updateUsedRoutes(usedRoutes: string[], gcTimestamp?: number): void;

Parameters​

Parameter Modifiers Type Description
usedRoutes string[] The routes that are used in all nodes in this Container.
gcTimestamp optional number The time when GC was run that generated these used routes. If any node node becomes unreferenced as part of this GC run, this should be used to update the time when it happens.

uploadBlob​

Signature​
uploadBlob(blob: ArrayBufferLike): Promise<IFluidHandle<ArrayBufferLike>>;

Parameters​

Parameter Type Description
blob ArrayBufferLike

Returns​

Return type: Promise<IFluidHandle<ArrayBufferLike>>