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