@fluidframework/driver-utils 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

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

@@ -1,603 +0,0 @@
-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 { ISnapshot } from '@fluidframework/driver-definitions';
-import { ISnapshotFetchOptions } from '@fluidframework/driver-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 { ITelemetryBaseProperties } from '@fluidframework/core-interfaces';
-import { ITelemetryErrorEventExt } from '@fluidframework/telemetry-utils';
-import { ITelemetryLoggerExt } from '@fluidframework/telemetry-utils';
-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';
-import { LoggingError } from '@fluidframework/telemetry-utils';
-
-/**
- * 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.
- * @internal
- */
-export declare function applyStorageCompression(documentServiceFactory: IDocumentServiceFactory, config?: ICompressionStorageConfig | boolean): IDocumentServiceFactory;
-
-/**
- * Basic implementation of an attachment ITreeEntry
- * @internal
- */
-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);
-}
-
-/**
- * @internal
- */
-export declare class AuthorizationError extends LoggingError implements IAuthorizationError, IFluidErrorBase {
-    readonly claims: string | undefined;
-    readonly tenantId: string | undefined;
-    readonly errorType: "authorizationError";
-    readonly canRetry = false;
-    constructor(message: string, claims: string | undefined, tenantId: string | undefined, props: DriverErrorTelemetryProps);
-}
-
-/**
- * @internal
- */
-export declare const blobHeadersBlobName = ".metadata.blobHeaders";
-
-/**
- * Basic implementation of a blob ITreeEntry
- * @internal
- */
-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
- * @internal
- */
-export declare function buildSnapshotTree(entries: ITreeEntry[], blobMap: Map<string, ArrayBufferLike>): ISnapshotTree;
-
-/**
- * Calculates time to wait for after an error based on the error and wait time for previous iteration.
- * 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 60s.
- * @param delayMs - wait time for previous iteration
- * @param error - error based on which we decide wait time.
- * @returns Wait time to wait for.
- * @internal
- */
-export declare function calculateMaxWaitTime(delayMs: number, error: unknown): number;
-
-/**
- * @privateRemarks ADO #1385: To be moved to packages/protocol-base/src/protocol.ts
- * @internal
- */
-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
- * @internal
- */
-export declare const canRetryOnError: (error: any) => boolean;
-
-/**
- * Defines the current layout of an .app + .protocol summary tree
- * this is used internally for create new, and single commit summary
- * @internal
- */
-export declare interface CombinedAppAndProtocolSummary extends ISummaryTree {
-    tree: {
-        [".app"]: ISummaryTree;
-        [".protocol"]: ISummaryTree;
-    };
-}
-
-/**
- * Converts ISummaryTree to ITree format.
- * @param summaryTree - summary tree in ISummaryTree format
- * @internal
- */
-export declare function convertSummaryTreeToSnapshotITree(summaryTree: ISummaryTree): ITree;
-
-/**
- * @internal
- */
-export declare function createGenericNetworkError(message: string, retryInfo: {
-    canRetry: boolean;
-    retryAfterMs?: number;
-}, props: DriverErrorTelemetryProps): ThrottlingError | GenericNetworkError;
-
-/**
- * @internal
- */
-export declare const createWriteError: (message: string, props: DriverErrorTelemetryProps) => NonRetryableError<"writeError">;
-
-/**
- * @internal
- */
-export declare class DeltaStreamConnectionForbiddenError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
-    static readonly errorType: "deltaStreamConnectionForbidden";
-    readonly errorType: "deltaStreamConnectionForbidden";
-    readonly canRetry = false;
-    readonly storageOnlyReason: string | undefined;
-    constructor(message: string, props: DriverErrorTelemetryProps, storageOnlyReason?: string);
-}
-
-/**
- * @internal
- */
-export declare class DocumentStorageServiceProxy implements IDocumentStorageService {
-    protected readonly internalStorageService: IDocumentStorageService;
-    private _policies;
-    set policies(policies: IDocumentStorageServicePolicies | undefined);
-    get policies(): IDocumentStorageServicePolicies | undefined;
-    constructor(internalStorageService: IDocumentStorageService);
-    getSnapshotTree(version?: IVersion, scenarioName?: string): Promise<ISnapshotTree | null>;
-    getSnapshot(snapshotFetchOptions?: ISnapshotFetchOptions): Promise<ISnapshot>;
-    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
- * @internal
- */
-export declare type DriverErrorTelemetryProps = ITelemetryBaseProperties & {
-    driverVersion: string | undefined;
-};
-
-/**
- * @internal
- */
-export declare const emptyMessageStream: IStream<ISequencedDocumentMessage[]>;
-
-/**
- * FluidInvalidSchema error class.
- * @internal
- */
-export declare class FluidInvalidSchemaError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
-    readonly errorType: "fluidInvalidSchema";
-    readonly canRetry = false;
-    constructor(message: string, props: DriverErrorTelemetryProps);
-}
-
-/**
- * Generic network error class.
- * @internal
- */
-export declare class GenericNetworkError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
-    readonly canRetry: boolean;
-    /**
-     * {@inheritDoc @fluidframework/telemetry-utils#IFluidErrorBase.errorType}
-     */
-    readonly errorType: "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.
- * @internal
- */
-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.
- * @internal
- */
-export declare function getQuorumValuesFromProtocolSummary(protocolSummary: ISummaryTree): [string, ICommittedProposal][];
-
-/**
- * Check retryAfterSeconds property on error and convert to ms
- * @internal
- */
-export declare const getRetryDelayFromError: (error: any) => number | undefined;
-
-/**
- * Check retryAfterSeconds property on error
- * @internal
- */
-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
- * https://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.
- * @internal
- */
-export declare class InsecureUrlResolver implements IUrlResolver {
-    private readonly hostUrl;
-    private readonly ordererUrl;
-    private readonly storageUrl;
-    private readonly deltaStreamUrl;
-    private readonly tenantId;
-    private readonly bearer;
-    private readonly isForNodeTest;
-    private readonly cache;
-    constructor(hostUrl: string, ordererUrl: string, storageUrl: string, deltaStreamUrl: 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.
- * @internal
- */
-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;
-}
-
-/**
- * Validates the current layout of an .app + .protocol summary tree
- * this is used internally for create new, and single commit summary
- * @internal
- */
-export declare function isCombinedAppAndProtocolSummary(summary: ISummaryTree | undefined, ...optionalRootTrees: string[]): summary is CombinedAppAndProtocolSummary;
-
-/**
- * Utility API to check if the type of snapshot contents is `ISnapshot`.
- * @internal
- * @param obj - obj whose type needs to be identified.
- */
-export declare function isInstanceOfISnapshot(obj: ISnapshotTree | ISnapshot | undefined): obj is ISnapshot;
-
-/**
- * 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")
- * @internal
- */
-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
- * @internal
- */
-export declare function isRuntimeMessage(message: {
-    type: string;
-}): boolean;
-
-/**
- * @internal
- */
-export declare class LocationRedirectionError extends LoggingError implements ILocationRedirectionError, IFluidErrorBase {
-    readonly redirectUrl: IResolvedUrl;
-    readonly errorType: "locationRedirection";
-    readonly canRetry = false;
-    constructor(message: string, redirectUrl: IResolvedUrl, props: DriverErrorTelemetryProps);
-}
-
-/**
- * @internal
- */
-export declare function logNetworkFailure(logger: ITelemetryLoggerExt, event: ITelemetryErrorEventExt, error?: any): void;
-
-/**
- * @privateRemarks ADO #1385: staging code changes across layers.
- * Eventually to be replaced by MessageType.accept
- * @internal
- */
-export declare enum MessageType2 {
-    Accept = "accept"
-}
-
-/**
- * @internal
- */
-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);
-}
-
-/**
- * @internal
- */
-export declare class NonRetryableError<T extends string> extends NetworkErrorBasic<T> {
-    readonly errorType: T;
-    constructor(message: string, errorType: T, props: DriverErrorTelemetryProps);
-}
-
-/**
- * @internal
- */
-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
- * @internal
- */
-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: ITelemetryBaseProperties) => 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;
-}
-
-/**
- * @internal
- */
-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
- * @internal
- */
-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>>;
-}
-
-/**
- * @alpha
- */
-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`.
- * @internal
- */
-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
- * @internal
- */
-export declare function requestOps(get: (from: number, to: number, telemetryProps: ITelemetryBaseProperties) => Promise<IDeltasFetchResult>, concurrency: number, fromTotal: number, toTotal: number | undefined, payloadSize: number, logger: ITelemetryLoggerExt, signal?: AbortSignal, scenarioName?: string): IStream<ISequencedDocumentMessage[]>;
-
-/**
- * @internal
- */
-export declare class RetryableError<T extends string> extends NetworkErrorBasic<T> {
-    readonly errorType: T;
-    constructor(message: string, errorType: T, props: DriverErrorTelemetryProps);
-}
-
-/**
- * @internal
- */
-export declare function runWithRetry<T>(api: (cancel?: AbortSignal) => Promise<T>, fetchCallName: string, logger: ITelemetryLoggerExt, progress: IProgress): Promise<T>;
-
-/**
- * @internal
- */
-export declare function streamFromMessages(messagesArg: Promise<ISequencedDocumentMessage[]>): IStream<ISequencedDocumentMessage[]>;
-
-/**
- * @internal
- */
-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
- * @internal
- */
-export declare class ThrottlingError extends LoggingError implements IThrottlingWarning, IFluidErrorBase {
-    readonly retryAfterSeconds: number;
-    readonly errorType: "throttlingError";
-    readonly canRetry = true;
-    constructor(message: string, retryAfterSeconds: number, props: DriverErrorTelemetryProps);
-}
-
-/**
- * Basic implementation of a tree ITreeEntry
- * @internal
- */
-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.
- * @internal
- */
-export declare class UsageError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
-    readonly errorType: "usageError";
-    readonly canRetry = false;
-    constructor(message: string);
-}
-
-export { }