@fluidframework/driver-utils 2.0.0-dev.6.4.0.192049 → 2.0.0-dev.7.2.0.204906

package/dist/driver-utils-public.d.ts

@@ -0,0 +1,574 @@
+import { FetchSource } from '@fluidframework/driver-definitions';
+import { IAttachment } from '@fluidframework/protocol-definitions';
+import { IAuthorizationError } from '@fluidframework/driver-definitions';
+import { IBlob } from '@fluidframework/protocol-definitions';
+import { ICommittedProposal } from '@fluidframework/protocol-definitions';
+import { ICreateBlobResponse } from '@fluidframework/protocol-definitions';
+import { IDeltasFetchResult } from '@fluidframework/driver-definitions';
+import { IDocumentAttributes } from '@fluidframework/protocol-definitions';
+import { IDocumentMessage } from '@fluidframework/protocol-definitions';
+import { IDocumentServiceFactory } from '@fluidframework/driver-definitions';
+import { IDocumentStorageService } from '@fluidframework/driver-definitions';
+import { IDocumentStorageServicePolicies } from '@fluidframework/driver-definitions';
+import { IDriverErrorBase } from '@fluidframework/driver-definitions';
+import { IFluidErrorBase } from '@fluidframework/telemetry-utils';
+import { ILocationRedirectionError } from '@fluidframework/driver-definitions';
+import { IRequest } from '@fluidframework/core-interfaces';
+import { IResolvedUrl } from '@fluidframework/driver-definitions';
+import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
+import { ISnapshotTree } from '@fluidframework/protocol-definitions';
+import { IStream } from '@fluidframework/driver-definitions';
+import { IStreamResult } from '@fluidframework/driver-definitions';
+import { ISummaryContext } from '@fluidframework/driver-definitions';
+import { ISummaryHandle } from '@fluidframework/protocol-definitions';
+import { ISummaryTree } from '@fluidframework/protocol-definitions';
+import { ITelemetryErrorEvent } from '@fluidframework/core-interfaces';
+import { ITelemetryLoggerExt } from '@fluidframework/telemetry-utils';
+import { ITelemetryProperties } from '@fluidframework/core-interfaces';
+import { IThrottlingWarning } from '@fluidframework/driver-definitions';
+import { ITree } from '@fluidframework/protocol-definitions';
+import { ITreeEntry } from '@fluidframework/protocol-definitions';
+import { IUrlResolver } from '@fluidframework/driver-definitions';
+import { IVersion } from '@fluidframework/protocol-definitions';
+import { LoaderCachingPolicy } from '@fluidframework/driver-definitions';
+
+/**
+ * This method optionally applies compression to the given document service factory. The compression
+ * must be enabled by setting the config to true or by passing a compression config object.
+ * @param documentServiceFactory - The document service factory to apply compression to.
+ * @param config - The compression configuration.
+ * @returns The document service factory possibly with compression applied.
+ * @public
+ */
+export declare function applyStorageCompression(documentServiceFactory: IDocumentServiceFactory, config?: ICompressionStorageConfig | boolean): IDocumentServiceFactory;
+
+/**
+ * Basic implementation of an attachment ITreeEntry
+ * @public
+ */
+export declare class AttachmentTreeEntry {
+    readonly path: string;
+    readonly id: string;
+    readonly mode = FileMode.File;
+    readonly type = TreeEntry.Attachment;
+    readonly value: IAttachment;
+    /**
+     * Creates an attachment ITreeEntry
+     * @param path - path of entry
+     * @param id - id of external blob attachment
+     */
+    constructor(path: string, id: string);
+}
+
+/**
+ * @public
+ */
+export declare class AuthorizationError extends LoggingError implements IAuthorizationError, IFluidErrorBase {
+    readonly claims: string | undefined;
+    readonly tenantId: string | undefined;
+    readonly errorType = DriverErrorType.authorizationError;
+    readonly canRetry = false;
+    constructor(message: string, claims: string | undefined, tenantId: string | undefined, props: DriverErrorTelemetryProps);
+}
+
+/**
+ * @public
+ */
+export declare const blobHeadersBlobName = ".metadata.blobHeaders";
+
+/**
+ * Basic implementation of a blob ITreeEntry
+ * @public
+ */
+export declare class BlobTreeEntry {
+    readonly path: string;
+    readonly mode = FileMode.File;
+    readonly type = TreeEntry.Blob;
+    readonly value: IBlob;
+    /**
+     * Creates a blob ITreeEntry
+     * @param path - path of entry
+     * @param contents - blob contents
+     * @param encoding - encoding of contents; defaults to utf-8
+     */
+    constructor(path: string, contents: string, encoding?: "utf-8" | "base64");
+}
+
+/**
+ * Build a tree hierarchy base on an array of ITreeEntry
+ *
+ * @param entries - an array of ITreeEntry to flatten
+ * @param blobMap - 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
+ * @public
+ */
+export declare function buildSnapshotTree(entries: ITreeEntry[], blobMap: Map<string, ArrayBufferLike>): ISnapshotTree;
+
+/**
+ * In case endpoint(service or socket) is not reachable, then we maybe offline or may have got some transient error
+ * not related to endpoint, in that case we want to try at faster pace and hence the max wait is lesser 8s as compared
+ * to when endpoint is reachable in which case it is 30s.
+ * @param error - error based on which we decide max wait time.
+ * @returns Max wait time.
+ * @public
+ */
+export declare function calculateMaxWaitTime(error: unknown): number;
+
+/**
+ * @privateRemarks ADO #1385: To be moved to packages/protocol-base/src/protocol.ts
+ * @public
+ */
+export declare function canBeCoalescedByService(message: ISequencedDocumentMessage | IDocumentMessage): 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.
+ * @param error - The error to inspect for ability to retry
+ * @public
+ */
+export declare const canRetryOnError: (error: any) => boolean;
+
+/* Excluded from this release type: CombinedAppAndProtocolSummary */
+
+/**
+ * Converts ISummaryTree to ITree format.
+ * @param summaryTree - summary tree in ISummaryTree format
+ * @public
+ */
+export declare function convertSummaryTreeToSnapshotITree(summaryTree: ISummaryTree): ITree;
+
+/**
+ * @public
+ */
+export declare function createGenericNetworkError(message: string, retryInfo: {
+    canRetry: boolean;
+    retryAfterMs?: number;
+}, props: DriverErrorTelemetryProps): ThrottlingError | GenericNetworkError;
+
+/**
+ * @public
+ */
+export declare const createWriteError: (message: string, props: DriverErrorTelemetryProps) => NonRetryableError<"writeError">;
+
+/**
+ * @public
+ */
+export declare class DeltaStreamConnectionForbiddenError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
+    static readonly errorType = DriverErrorType.deltaStreamConnectionForbidden;
+    readonly errorType = DriverErrorType.deltaStreamConnectionForbidden;
+    readonly canRetry = false;
+    readonly storageOnlyReason: string | undefined;
+    constructor(message: string, props: DriverErrorTelemetryProps, storageOnlyReason?: string);
+}
+
+/**
+ * @public
+ */
+export declare class DocumentStorageServiceProxy implements IDocumentStorageService {
+    protected readonly internalStorageService: IDocumentStorageService;
+    private _policies;
+    set policies(policies: IDocumentStorageServicePolicies | undefined);
+    get policies(): IDocumentStorageServicePolicies | undefined;
+    get repositoryUrl(): string;
+    constructor(internalStorageService: IDocumentStorageService);
+    getSnapshotTree(version?: IVersion, scenarioName?: string): Promise<ISnapshotTree | null>;
+    getVersions(versionId: string | null, count: number, scenarioName?: string, fetchSource?: FetchSource): Promise<IVersion[]>;
+    uploadSummaryWithContext(summary: ISummaryTree, context: ISummaryContext): Promise<string>;
+    downloadSummary(handle: ISummaryHandle): Promise<ISummaryTree>;
+    createBlob(file: ArrayBufferLike): Promise<ICreateBlobResponse>;
+    readBlob(blobId: string): Promise<ArrayBufferLike>;
+}
+
+/**
+ * Telemetry props with driver-specific required properties
+ * @public
+ */
+export declare type DriverErrorTelemetryProps = ITelemetryProperties & {
+    driverVersion: string | undefined;
+};
+
+/**
+ * @public
+ */
+export declare const emptyMessageStream: IStream<ISequencedDocumentMessage[]>;
+
+/**
+ * FluidInvalidSchema error class.
+ * @public
+ */
+export declare class FluidInvalidSchemaError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
+    readonly errorType = DriverErrorType.fluidInvalidSchema;
+    readonly canRetry = false;
+    constructor(message: string, props: DriverErrorTelemetryProps);
+}
+
+/**
+ * Generic network error class.
+ * @public
+ */
+export declare class GenericNetworkError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
+    readonly canRetry: boolean;
+    readonly errorType = DriverErrorType.genericNetworkError;
+    constructor(message: string, canRetry: boolean, props: DriverErrorTelemetryProps);
+}
+
+/**
+ * Extract the attributes from the protocol summary.
+ * @param protocolSummary - protocol summary from which the values are to be extracted.
+ * @public
+ */
+export declare function getDocAttributesFromProtocolSummary(protocolSummary: ISummaryTree): IDocumentAttributes;
+
+/**
+ * Extract quorum values from the protocol summary.
+ * @param protocolSummary - protocol summary from which the values are to be extracted.
+ * @public
+ */
+export declare function getQuorumValuesFromProtocolSummary(protocolSummary: ISummaryTree): [string, ICommittedProposal][];
+
+/**
+ * Check retryAfterSeconds property on error and convert to ms
+ * @public
+ * */
+export declare const getRetryDelayFromError: (error: any) => number | undefined;
+
+/**
+ * Check retryAfterSeconds property on error
+ * @public
+ * */
+export declare const getRetryDelaySecondsFromError: (error: any) => number | undefined;
+
+/**
+ * @public
+ */
+export declare interface ICompressionStorageConfig {
+    algorithm: SummaryCompressionAlgorithm;
+    minSizeToCompress: number;
+}
+
+/**
+ * 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/<documentId>/<path>.
+ *
+ * We then need to map that to a Fluid based URL. These are of the form
+ * fluid://orderingUrl/<tenantId>/<documentId>/<path>.
+ *
+ * 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.
+ * @public
+ */
+export declare class InsecureUrlResolver implements IUrlResolver {
+    private readonly hostUrl;
+    private readonly ordererUrl;
+    private readonly storageUrl;
+    private readonly tenantId;
+    private readonly bearer;
+    private readonly isForNodeTest;
+    private readonly cache;
+    constructor(hostUrl: string, ordererUrl: string, storageUrl: string, tenantId: string, bearer: string, isForNodeTest?: boolean);
+    resolve(request: IRequest): Promise<IResolvedUrl | undefined>;
+    private resolveHelper;
+    getAbsoluteUrl(resolvedUrl: IResolvedUrl, relativeUrl: string): Promise<string>;
+    createCreateNewRequest(fileName?: string): IRequest;
+}
+
+/**
+ * Interface describing an object passed to various network APIs.
+ * It allows caller to control cancellation, as well as learn about any delays.
+ * @public
+ */
+export declare interface IProgress {
+    /**
+     * Abort signal used to cancel operation.
+     *
+     * @remarks Note that most of the layers do not use this signal yet. We need to change that over time.
+     * Please consult with API documentation / implementation.
+     * Note that  number of layers may not check this signal while holding this request in a queue,
+     * so it may take a while it takes effect. This can be improved in the future.
+     *
+     * The layers in question are:
+     *
+     * - driver (RateLimiter)
+     *
+     * - runWithRetry
+     */
+    cancel?: AbortSignal;
+    /**
+     * Called whenever api returns cancellable error and the call is going to be retried.
+     * Any exception thrown from this call back result in cancellation of operation
+     * and propagation of thrown exception.
+     * @param delayInMs - delay before next retry. This value will depend on internal back-off logic,
+     * as well as information provided by service (like 429 error asking to wait for some time before retry)
+     * @param error - error object returned from the call.
+     */
+    onRetry?(delayInMs: number, error: any): void;
+}
+
+/* Excluded from this release type: isCombinedAppAndProtocolSummary */
+
+/**
+ * It tells if we have local connection only - we might not have connection to web.
+ * No solution for node.js (other than resolve dns names / ping specific sites)
+ * Can also use window.addEventListener("online" / "offline")
+ * @public
+ */
+export declare function isOnline(): OnlineStatus;
+
+/**
+ * Tells if message was sent by container runtime
+ * @privateRemarks ADO #1385: To be moved to container-definitions
+ * @returns whether the message is a runtime message
+ * @public
+ */
+export declare function isRuntimeMessage(message: {
+    type: string;
+}): boolean;
+
+/**
+ * @public
+ */
+export declare class LocationRedirectionError extends LoggingError implements ILocationRedirectionError, IFluidErrorBase {
+    readonly redirectUrl: IResolvedUrl;
+    readonly errorType = DriverErrorType.locationRedirection;
+    readonly canRetry = false;
+    constructor(message: string, redirectUrl: IResolvedUrl, props: DriverErrorTelemetryProps);
+}
+
+/* Excluded from this release type: LoggingError */
+
+/**
+ * @public
+ */
+export declare function logNetworkFailure(logger: ITelemetryLoggerExt, event: ITelemetryErrorEvent, error?: any): void;
+
+/**
+ * @privateRemarks ADO #1385: staging code changes across layers.
+ * Eventually to be replaced by MessageType.accept
+ * @public
+ */
+export declare enum MessageType2 {
+    Accept = "accept"
+}
+
+/**
+ * @public
+ */
+export declare class NetworkErrorBasic<T extends string> extends LoggingError implements IFluidErrorBase {
+    readonly errorType: T;
+    readonly canRetry: boolean;
+    constructor(message: string, errorType: T, canRetry: boolean, props: DriverErrorTelemetryProps);
+}
+
+/**
+ * @public
+ */
+export declare class NonRetryableError<T extends string> extends NetworkErrorBasic<T> {
+    readonly errorType: T;
+    constructor(message: string, errorType: T, props: DriverErrorTelemetryProps);
+}
+
+/**
+ * @public
+ */
+export declare enum OnlineStatus {
+    Offline = 0,
+    Online = 1,
+    Unknown = 2
+}
+
+/**
+ * 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.
+ * @param concurrency - level of concurrency
+ * @param from - starting point of fetching data (inclusive)
+ * @param to - ending point of fetching data. exclusive, or undefined if unknown
+ * @param payloadSize - batch size
+ * @param logger - logger to use
+ * @param requestCallback - callback to request batches
+ * @returns Queue that can be used to retrieve data
+ * @public
+ */
+export declare class ParallelRequests<T> {
+    private to;
+    private readonly payloadSize;
+    private readonly logger;
+    private readonly requestCallback;
+    private readonly responseCallback;
+    private latestRequested;
+    private nextToDeliver;
+    private readonly results;
+    private workingState;
+    private requestsInFlight;
+    private readonly endEvent;
+    private requests;
+    private readonly knewTo;
+    private get working();
+    get canceled(): boolean;
+    constructor(from: number, to: number | undefined, payloadSize: number, logger: ITelemetryLoggerExt, requestCallback: (request: number, from: number, to: number, strongTo: boolean, props: ITelemetryProperties) => Promise<{
+        partial: boolean;
+        cancel: boolean;
+        payload: T[];
+    }>, responseCallback: (payload: T[]) => void);
+    cancel(): void;
+    run(concurrency: number): Promise<void>;
+    private done;
+    private fail;
+    private dispatch;
+    private getNextChunk;
+    private addRequest;
+    private addRequestCore;
+}
+
+/**
+ * @public
+ */
+export declare class PrefetchDocumentStorageService extends DocumentStorageServiceProxy {
+    private readonly prefetchCache;
+    private prefetchEnabled;
+    get policies(): {
+        caching: LoaderCachingPolicy;
+        maximumCacheDurationMs?: 432000000 | undefined;
+    } | undefined;
+    getSnapshotTree(version?: IVersion): Promise<ISnapshotTree | null>;
+    readBlob(blobId: string): Promise<ArrayBufferLike>;
+    stopPrefetch(): void;
+    private cachedRead;
+    private prefetchTree;
+    private prefetchTreeCore;
+}
+
+/**
+ * Helper queue class to allow async push / pull
+ * It's essentially a pipe allowing multiple writers, and single reader
+ * @public
+ */
+export declare class Queue<T> implements IStream<T> {
+    private readonly queue;
+    private deferred;
+    private done;
+    pushValue(value: T): void;
+    pushError(error: any): void;
+    pushDone(): void;
+    protected pushCore(value: Promise<IStreamResult<T>>): void;
+    read(): Promise<IStreamResult<T>>;
+}
+
+/**
+ * @public
+ */
+export declare class RateLimiter {
+    private maxRequests;
+    private readonly tasks;
+    constructor(maxRequests: number);
+    get waitQueueLength(): number;
+    protected readonly release: () => void;
+    protected acquire(): Promise<void>;
+    schedule<T>(work: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Read a blob from {@link @fluidframework/driver-definitions#IDocumentStorageService} and
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse | JSON.parse}
+ * it into object of type `T`.
+ *
+ * @param storage - The `DocumentStorageService` to read from.
+ * @param id - The ID of the blob to read and parse.
+ *
+ * @typeParam T - Output type matching JSON format of inpyt blob data.
+ *
+ * @returns The object that we decoded and parsed via `JSON.parse`.
+ * @public
+ */
+export declare function readAndParse<T>(storage: Pick<IDocumentStorageService, "readBlob">, id: string): Promise<T>;
+
+/**
+ * Request ops from storage
+ * @param get - Getter callback to get individual batches
+ * @param concurrency - Number of concurrent requests to make
+ * @param fromTotal - starting sequence number to fetch (inclusive)
+ * @param toTotal - max (exclusive) sequence number to fetch
+ * @param payloadSize - Payload size
+ * @param logger - Logger to log progress and errors
+ * @param signal - Cancelation signal
+ * @param scenarioName - Reason for fetching ops
+ * @returns Messages fetched
+ * @public
+ */
+export declare function requestOps(get: (from: number, to: number, telemetryProps: ITelemetryProperties) => Promise<IDeltasFetchResult>, concurrency: number, fromTotal: number, toTotal: number | undefined, payloadSize: number, logger: ITelemetryLoggerExt, signal?: AbortSignal, scenarioName?: string): IStream<ISequencedDocumentMessage[]>;
+
+/**
+ * @public
+ */
+export declare class RetryableError<T extends string> extends NetworkErrorBasic<T> {
+    readonly errorType: T;
+    constructor(message: string, errorType: T, props: DriverErrorTelemetryProps);
+}
+
+/**
+ * @public
+ */
+export declare function runWithRetry<T>(api: (cancel?: AbortSignal) => Promise<T>, fetchCallName: string, logger: ITelemetryLoggerExt, progress: IProgress): Promise<T>;
+
+/**
+ * @public
+ */
+export declare function streamFromMessages(messagesArg: Promise<ISequencedDocumentMessage[]>): IStream<ISequencedDocumentMessage[]>;
+
+/**
+ * @public
+ */
+export declare function streamObserver<T>(stream: IStream<T>, handler: (value: IStreamResult<T>) => void): IStream<T>;
+
+/**
+ * @public
+ */
+export declare enum SummaryCompressionAlgorithm {
+    None = 0,
+    LZ4 = 1
+}
+
+/**
+ * Throttling error class - used to communicate all throttling errors
+ * @public
+ */
+export declare class ThrottlingError extends LoggingError implements IThrottlingWarning, IFluidErrorBase {
+    readonly retryAfterSeconds: number;
+    readonly errorType = DriverErrorType.throttlingError;
+    readonly canRetry = true;
+    constructor(message: string, retryAfterSeconds: number, props: DriverErrorTelemetryProps);
+}
+
+/**
+ * Basic implementation of a tree ITreeEntry
+ * @public
+ */
+export declare class TreeTreeEntry {
+    readonly path: string;
+    readonly value: ITree;
+    readonly mode = FileMode.Directory;
+    readonly type = TreeEntry.Tree;
+    /**
+     * Creates a tree ITreeEntry
+     * @param path - path of entry
+     * @param value - subtree
+     */
+    constructor(path: string, value: ITree);
+}
+
+/**
+ * Error indicating an API is being used improperly resulting in an invalid operation.
+ * @public
+ */
+export declare class UsageError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
+    readonly errorType = DriverErrorType.usageError;
+    readonly canRetry = false;
+    constructor(message: string);
+}
+
+export { }