@fluidframework/driver-utils Package

Interfaces

Interface	Description
IAnyDriverError	Interface describing errors and warnings raised by any driver code. Not expected to be implemented by a class or an object literal, but rather used in place of any or unknown in various function signatures that pass errors around. "Any" in the interface name is a nod to the fact that errorType has lost its type constraint. It will be either DriverErrorType or the specific driver's specialized error type enum, but we can't reference a specific driver's error type enum in this code.
IProgress	Interface describing an object passed to various network APIs. It allows caller to control cancellation, as well as learn about any delays.
ISummaryTreeAssemblerProps	Summary tree assembler props

Classes

Class	Description
AuthorizationError
BlobAggregationStorage
BlobCacheStorageService	IDocumentStorageService adapter with pre-cached blobs.
DeltaStreamConnectionForbiddenError
DocumentStorageServiceProxy
EmptyDocumentDeltaStorageService	Implementation of IDocumentDeltaStorageService that will always return an empty message queue when fetching messages
GenericNetworkError	Generic network error class.
InsecureUrlResolver	As the name implies this is not secure and should not be used in production. It simply makes the example easier to get up and running. In our example we run a simple web server via webpack-dev-server. This defines a URL format of the form http://localhost:8080//. We then need to map that to a Fluid based URL. These are of the form fluid://orderingUrl///. The tenantId/documentId pair defines the 'full' document ID the service makes use of. The path is then an optional part of the URL that the document interprets and maps to a data store. It's exactly similar to how a web service works or a router inside of a single page app framework.
MultiDocumentServiceFactory
MultiUrlResolver
NetworkErrorBasic
NonRetryableError
ParallelRequests	Helper class to organize parallel fetching of data It can be used to concurrently do many requests, while consuming data in the right order. Take a look at UT for examples.
PrefetchDocumentStorageService
Queue	Helper queue class to allow async push / pull It's essentially a pipe allowing multiple writers, and single reader
RateLimiter
RetryableError
SnapshotExtractor
SummaryTreeAssembler	Summary tree assembler (without stats collection).
ThrottlingError	Throttling error class - used to communicate all throttling errors
UsageError	Error indicating an API is being used improperly resulting in an invalid operation.

Enumerations

Enum	Description
OnlineStatus

Types

TypeAlias	Description
DriverErrorTelemetryProps	Telemetry props with driver-specific required properties

Functions

Function	Return Type	Description
buildSnapshotTree(entries, blobMap)	ISnapshotTree	Build a tree hierarchy base on an array of ITreeEntry
combineAppAndProtocolSummary(appSummary, protocolSummary)	ISummaryTree	Combine the app summary and protocol summary in 1 tree.
configurableUrlResolver(resolversList, request)	Promise<IResolvedUrl | undefined>	Resolver that takes a list of url resolvers and then try each of them to resolve the url.
convertSnapshotAndBlobsToSummaryTree(snapshot, blobs)	ISummaryTree	Helper function that converts ISnapshotTree and blobs to ISummaryTree
convertSummaryTreeToSnapshotITree(summaryTree)	ITree	Converts ISummaryTree to ITree format.
createGenericNetworkError(message, retryInfo, props)	ThrottlingError | GenericNetworkError
ensureFluidResolvedUrl(resolved)	asserts resolved is IFluidResolvedUrl
getDocAttributesFromProtocolSummary(protocolSummary)	IDocumentAttributes	Extract the attributes from the protocol summary.
getQuorumValuesFromProtocolSummary(protocolSummary)	[string, ICommittedProposal][]	Extract quorum values from the protocol summary.
isClientMessage(message)	boolean
isOnline()	OnlineStatus
isRuntimeMessage(message)	boolean
isUnpackedRuntimeMessage(message)	boolean
logNetworkFailure(logger, event, error)	void
readAndParse(storage, id)	Promise<T>	Read a blob from IDocumentStorageService and JSON.parse it into object of type T
requestOps(get, concurrency, fromTotal, toTotal, payloadSize, logger, signal, scenarioName)	IStream<ISequencedDocumentMessage[]>	Request ops from storage
runWithRetry(api, fetchCallName, logger, progress)	Promise<T>
streamFromMessages(messagesArg)	IStream<ISequencedDocumentMessage[]>
streamObserver(stream, handler)	IStream<T>
waitForConnectedState(minDelay)	Promise<void>	Wait for browser to get to connected state. If connected, waits minimum of minDelay anyway (between network retries) If disconnected, polls every 30 seconds anyway, to make sure we are not getting stuck because of wrong signal Note that browsers will have false positives (like having Hyper-V adapter on machine, or machine connected to router that is not connected to internet) But there should be no false negatives. The only exception - Opera returns false when user enters "Work Offline" mode, regardless of actual connectivity.

Variables

Variable	Type	Description
canRetryOnError	(error: any) => boolean	Check if a connection error can be retried. Unless explicitly allowed, retry is disallowed. I.e. asserts or unexpected exceptions in our code result in container failure.
createWriteError	(message: string, props: DriverErrorTelemetryProps) => NonRetryableError<DriverErrorType.writeError>
emptyMessageStream	IStream<ISequencedDocumentMessage[]>
getRetryDelayFromError	(error: any) => number | undefined	Check retryAfterSeconds property on error and convert to ms
getRetryDelaySecondsFromError	(error: any) => number | undefined	Check retryAfterSeconds property on error
isFluidResolvedUrl	(resolved: IResolvedUrl | undefined) => resolved is IFluidResolvedUrl

Function Details

buildSnapshotTree

Build a tree hierarchy base on an array of ITreeEntry

Signature

export declare function buildSnapshotTree(entries: ITreeEntry[], blobMap: Map<string, ArrayBufferLike>): ISnapshotTree;

Parameters

Parameter	Type	Description
entries	ITreeEntry[]	an array of ITreeEntry to flatten
blobMap	Map<string, ArrayBufferLike>	a map of blob's sha1 to content that gets filled with content from entries NOTE: blobMap's validity is contingent on the returned promise's resolution

Returns

the hierarchical tree

Return type: ISnapshotTree

combineAppAndProtocolSummary

Combine the app summary and protocol summary in 1 tree.

Signature

export declare function combineAppAndProtocolSummary(appSummary: ISummaryTree, protocolSummary: ISummaryTree): ISummaryTree;

Parameters

Parameter	Type	Description
appSummary	ISummaryTree	Summary of the app.
protocolSummary	ISummaryTree	Summary of the protocol.

Returns

Return type: ISummaryTree

configurableUrlResolver

Resolver that takes a list of url resolvers and then try each of them to resolve the url.

Signature

export declare function configurableUrlResolver(resolversList: IUrlResolver[], request: IRequest): Promise<IResolvedUrl | undefined>;

Parameters

Parameter	Type	Description
resolversList	IUrlResolver[]	List of url resolvers to be used to resolve the request.
request	IRequest	Request to be resolved.

Returns

Return type: Promise<IResolvedUrl | undefined>

convertSnapshotAndBlobsToSummaryTree

Helper function that converts ISnapshotTree and blobs to ISummaryTree

Signature

export declare function convertSnapshotAndBlobsToSummaryTree(snapshot: ISnapshotTree, blobs: Map<string, ArrayBuffer>): ISummaryTree;

Parameters

Parameter	Type	Description
snapshot	ISnapshotTree	Source snapshot tree
blobs	Map<string, ArrayBuffer>	Blobs cache

Returns

Converted snapshot in ISummaryTree format

Return type: ISummaryTree

convertSummaryTreeToSnapshotITree

Converts ISummaryTree to ITree format.

Signature

export declare function convertSummaryTreeToSnapshotITree(summaryTree: ISummaryTree): ITree;

Parameters

Parameter	Type	Description
summaryTree	ISummaryTree	summary tree in ISummaryTree format

Returns

Return type: ITree

createGenericNetworkError

Signature

export declare function createGenericNetworkError(message: string, retryInfo: {
    canRetry: boolean;
    retryAfterMs?: number;
}, props: DriverErrorTelemetryProps): ThrottlingError | GenericNetworkError;

Parameters

Parameter	Type	Description
message	string
retryInfo	{ canRetry: boolean; retryAfterMs?: number; }
props	DriverErrorTelemetryProps

Returns

Return type: ThrottlingError | GenericNetworkError

ensureFluidResolvedUrl

Signature

export declare function ensureFluidResolvedUrl(resolved: IResolvedUrl | undefined): asserts resolved is IFluidResolvedUrl;

Parameters

Parameter	Type	Description
resolved	IResolvedUrl | undefined

Returns

Return type: asserts resolved is IFluidResolvedUrl

getDocAttributesFromProtocolSummary

Extract the attributes from the protocol summary.

Signature

export declare function getDocAttributesFromProtocolSummary(protocolSummary: ISummaryTree): IDocumentAttributes;

Parameters

Parameter	Type	Description
protocolSummary	ISummaryTree	protocol summary from which the values are to be extracted.

Returns

Return type: IDocumentAttributes

getQuorumValuesFromProtocolSummary

Extract quorum values from the protocol summary.

Signature

export declare function getQuorumValuesFromProtocolSummary(protocolSummary: ISummaryTree): [string, ICommittedProposal][];

Parameters

Parameter	Type	Description
protocolSummary	ISummaryTree	protocol summary from which the values are to be extracted.

Returns

Return type: [string, ICommittedProposal][]

isClientMessage

Signature

export declare function isClientMessage(message: ISequencedDocumentMessage | IDocumentMessage): boolean;

Parameters

Parameter	Type	Description
message	ISequencedDocumentMessage | IDocumentMessage	message

Returns

whether or not the message type is one listed below "op" "summarize" "propose" "reject" "noop"

Return type: boolean

isOnline

Signature

export declare function isOnline(): OnlineStatus;

Returns

Return type: OnlineStatus

isRuntimeMessage

Signature

export declare function isRuntimeMessage(message: ISequencedDocumentMessage | IDocumentMessage): boolean;

Parameters

Parameter	Type	Description
message	ISequencedDocumentMessage | IDocumentMessage	message

Returns

whether or not the message type is one listed below "op" "summarize"

Return type: boolean

isUnpackedRuntimeMessage

Signature

export declare function isUnpackedRuntimeMessage(message: ISequencedDocumentMessage): boolean;

Parameters

Parameter	Type	Description
message	ISequencedDocumentMessage	message

Returns

whether or not the message type is one listed below (legacy) "component" "attach" "chunkedOp" "blobAttach" "rejoin" "alias" "op"

Return type: boolean

logNetworkFailure

Signature

export declare function logNetworkFailure(logger: ITelemetryLogger, event: ITelemetryErrorEvent, error?: any): void;

Parameters

Parameter	Modifiers	Type	Description
logger		ITelemetryLogger
event		ITelemetryErrorEvent
error	optional	any

readAndParse

Read a blob from IDocumentStorageService and JSON.parse it into object of type T

Signature

export declare function readAndParse<T>(storage: Pick<IDocumentStorageService, "readBlob">, id: string): Promise<T>;

Type Parameters

Parameter	Description
T

Parameters

Parameter	Type	Description
storage	Pick<IDocumentStorageService, "readBlob">	the IDocumentStorageService to read from
id	string	the id of the blob to read and parse

Returns

the object that we decoded and JSON.parse

Return type: Promise<T>

requestOps

Request ops from storage

Signature

export declare function requestOps(get: (from: number, to: number, telemetryProps: ITelemetryProperties) => Promise<IDeltasFetchResult>, concurrency: number, fromTotal: number, toTotal: number | undefined, payloadSize: number, logger: ITelemetryLogger, signal?: AbortSignal, scenarioName?: string): IStream<ISequencedDocumentMessage[]>;

Parameters

Parameter	Modifiers	Type	Description
get		(from: number, to: number, telemetryProps: ITelemetryProperties) => Promise<IDeltasFetchResult>	Getter callback to get individual batches
concurrency		number	Number of concurrent requests to make
fromTotal		number	starting sequence number to fetch (inclusive)
toTotal		number | undefined	max (exclusive) sequence number to fetch
payloadSize		number	Payload size
logger		ITelemetryLogger	Logger to log progress and errors
signal	optional	AbortSignal	Cancelation signal
scenarioName	optional	string	Reason for fetching ops

Returns

• Messages fetched

Return type: IStream<ISequencedDocumentMessage[]>

runWithRetry

Signature

export declare function runWithRetry<T>(api: (cancel?: AbortSignal) => Promise<T>, fetchCallName: string, logger: ITelemetryLogger, progress: IProgress): Promise<T>;

Type Parameters

Parameter	Description
T

Parameters

Parameter	Type	Description
api	(cancel?: AbortSignal) => Promise<T>
fetchCallName	string
logger	ITelemetryLogger
progress	IProgress

Returns

Return type: Promise<T>

streamFromMessages

Signature

export declare function streamFromMessages(messagesArg: Promise<ISequencedDocumentMessage[]>): IStream<ISequencedDocumentMessage[]>;

Parameters

Parameter	Type	Description
messagesArg	Promise<ISequencedDocumentMessage[]>

Returns

Return type: IStream<ISequencedDocumentMessage[]>

streamObserver

Signature

export declare function streamObserver<T>(stream: IStream<T>, handler: (value: IStreamResult<T>) => void): IStream<T>;

Type Parameters

Parameter	Description
T

Parameters

Parameter	Type	Description
stream	IStream<T>
handler	(value: IStreamResult<T>) => void

Returns

Return type: IStream<T>

waitForConnectedState

Wait for browser to get to connected state. If connected, waits minimum of minDelay anyway (between network retries) If disconnected, polls every 30 seconds anyway, to make sure we are not getting stuck because of wrong signal Note that browsers will have false positives (like having Hyper-V adapter on machine, or machine connected to router that is not connected to internet) But there should be no false negatives. The only exception - Opera returns false when user enters "Work Offline" mode, regardless of actual connectivity.

Signature

export declare function waitForConnectedState(minDelay: number): Promise<void>;

Parameters

Parameter	Type	Description
minDelay	number

Returns

Return type: Promise<void>

Variable Details

canRetryOnError

Check if a connection error can be retried. Unless explicitly allowed, retry is disallowed. I.e. asserts or unexpected exceptions in our code result in container failure.

Signature

canRetryOnError: (error: any) => boolean

Type: (error: any) => boolean

createWriteError

Signature

createWriteError: (message: string, props: DriverErrorTelemetryProps) => NonRetryableError<DriverErrorType.writeError>

Type: (message: string, props: DriverErrorTelemetryProps) => NonRetryableError<DriverErrorType.writeError>

emptyMessageStream

Signature

emptyMessageStream: IStream<ISequencedDocumentMessage[]>

Type: IStream<ISequencedDocumentMessage[]>

getRetryDelayFromError

Check retryAfterSeconds property on error and convert to ms

Signature

getRetryDelayFromError: (error: any) => number | undefined

Type: (error: any) => number | undefined

getRetryDelaySecondsFromError

Check retryAfterSeconds property on error

Signature

getRetryDelaySecondsFromError: (error: any) => number | undefined

Type: (error: any) => number | undefined

isFluidResolvedUrl

Signature

isFluidResolvedUrl: (resolved: IResolvedUrl | undefined) => resolved is IFluidResolvedUrl

Type: (resolved: IResolvedUrl | undefined) => resolved is IFluidResolvedUrl