@fluidframework/odsp-driver 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.225277

package/src/prefetchLatestSnapshot.ts

@@ -3,108 +3,170 @@
  * Licensed under the MIT License.
  */
 
-import { default as AbortController } from "abort-controller";
-import { ITelemetryBaseLogger } from "@fluidframework/common-definitions";
-import { assert } from "@fluidframework/common-utils";
+import { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
+import { performance } from "@fluid-internal/client-utils";
+import { assert, Deferred } from "@fluidframework/core-utils";
 import { IResolvedUrl } from "@fluidframework/driver-definitions";
 import {
-    IOdspResolvedUrl,
-    IPersistedCache,
-    ISnapshotOptions,
-    OdspResourceTokenFetchOptions,
-    TokenFetcher,
-    IOdspUrlParts,
+	IOdspResolvedUrl,
+	IPersistedCache,
+	ISnapshotOptions,
+	OdspResourceTokenFetchOptions,
+	TokenFetcher,
+	IOdspUrlParts,
+	getKeyForCacheEntry,
 } from "@fluidframework/odsp-driver-definitions";
-import { ChildLogger, PerformanceEvent } from "@fluidframework/telemetry-utils";
+import { createChildLogger, PerformanceEvent } from "@fluidframework/telemetry-utils";
 import {
-    createCacheSnapshotKey,
-    createOdspLogger,
-    getOdspResolvedUrl,
-    toInstrumentedOdspTokenFetcher,
+	createCacheSnapshotKey,
+	createOdspLogger,
+	getOdspResolvedUrl,
+	toInstrumentedOdspTokenFetcher,
 } from "./odspUtils";
-import { downloadSnapshot, fetchSnapshotWithRedeem, SnapshotFormatSupportType } from "./fetchSnapshot";
+import {
+	downloadSnapshot,
+	fetchSnapshotWithRedeem,
+	SnapshotFormatSupportType,
+} from "./fetchSnapshot";
 import { IVersionedValueWithEpoch } from "./contracts";
+import { IPrefetchSnapshotContents } from "./odspCache";
+import { OdspDocumentServiceFactory } from "./odspDocumentServiceFactory";
 
 /**
  * Function to prefetch the snapshot and cached it in the persistant cache, so that when the container is loaded
  * the cached latest snapshot could be used and removes the network call from the critical path.
+ *
  * @param resolvedUrl - Resolved url to fetch the snapshot.
  * @param getStorageToken - function that can provide the storage token for a given site. This is
- *  is also referred to as the "VROOM" token in SPO.
+ * is also referred to as the "VROOM" token in SPO.
  * @param persistedCache - Cache to store the fetched snapshot.
  * @param forceAccessTokenViaAuthorizationHeader - whether to force passing given token via authorization header.
  * @param logger - Logger to have telemetry events.
  * @param hostSnapshotFetchOptions - Options to fetch the snapshot if any. Otherwise default will be used.
  * @param enableRedeemFallback - True to have the sharing link redeem fallback in case the Trees Latest/Redeem
- *  1RT call fails with redeem error. During fallback it will first redeem the sharing link and then make
- *  the Trees latest call.
- *  @deprecated - This will be replaced with snapshotFormatFetchType.
+ * 1RT call fails with redeem error. During fallback it will first redeem the sharing link and then make
+ * the Trees latest call.
+ * Note: this can be considered deprecated - it will be replaced with `snapshotFormatFetchType`.
  * @param fetchBinarySnapshotFormat - Control if we want to fetch binary format snapshot.
  * @param snapshotFormatFetchType - Snapshot format to fetch.
- * @returns - True if the snapshot is cached, false otherwise.
+ * @param odspDocumentServiceFactory - factory to access the non persistent cache and store the prefetch promise.
+ *
+ * @returns `true` if the snapshot is cached, `false` otherwise.
+ * @alpha
  */
 export async function prefetchLatestSnapshot(
-    resolvedUrl: IResolvedUrl,
-    getStorageToken: TokenFetcher<OdspResourceTokenFetchOptions>,
-    persistedCache: IPersistedCache,
-    forceAccessTokenViaAuthorizationHeader: boolean,
-    logger: ITelemetryBaseLogger,
-    hostSnapshotFetchOptions: ISnapshotOptions | undefined,
-    enableRedeemFallback: boolean = true,
-    fetchBinarySnapshotFormat?: boolean,
-    snapshotFormatFetchType?: SnapshotFormatSupportType,
+	resolvedUrl: IResolvedUrl,
+	getStorageToken: TokenFetcher<OdspResourceTokenFetchOptions>,
+	persistedCache: IPersistedCache,
+	forceAccessTokenViaAuthorizationHeader: boolean,
+	logger: ITelemetryBaseLogger,
+	hostSnapshotFetchOptions: ISnapshotOptions | undefined,
+	enableRedeemFallback: boolean = true,
+	fetchBinarySnapshotFormat?: boolean,
+	snapshotFormatFetchType?: SnapshotFormatSupportType,
+	odspDocumentServiceFactory?: OdspDocumentServiceFactory,
 ): Promise<boolean> {
-    const odspLogger = createOdspLogger(ChildLogger.create(logger, "PrefetchSnapshot"));
-    const odspResolvedUrl = getOdspResolvedUrl(resolvedUrl);
+	const odspLogger = createOdspLogger(
+		createChildLogger({ logger, namespace: "PrefetchSnapshot" }),
+	);
+	const odspResolvedUrl = getOdspResolvedUrl(resolvedUrl);
 
-    const resolvedUrlData: IOdspUrlParts = {
-        siteUrl: odspResolvedUrl.siteUrl,
-        driveId: odspResolvedUrl.driveId,
-        itemId: odspResolvedUrl.itemId,
-    };
-    const storageTokenFetcher = toInstrumentedOdspTokenFetcher(
-        odspLogger,
-        resolvedUrlData,
-        getStorageToken,
-        true /* throwOnNullToken */,
-    );
+	const resolvedUrlData: IOdspUrlParts = {
+		siteUrl: odspResolvedUrl.siteUrl,
+		driveId: odspResolvedUrl.driveId,
+		itemId: odspResolvedUrl.itemId,
+	};
+	const storageTokenFetcher = toInstrumentedOdspTokenFetcher(
+		odspLogger,
+		resolvedUrlData,
+		getStorageToken,
+		true /* throwOnNullToken */,
+	);
 
-    const snapshotDownloader = async (
-        finalOdspResolvedUrl: IOdspResolvedUrl,
-        storageToken: string,
-        snapshotOptions: ISnapshotOptions | undefined,
-        controller?: AbortController,
-    ) => {
-        return downloadSnapshot(
-            finalOdspResolvedUrl, storageToken, odspLogger, snapshotOptions, snapshotFormatFetchType, controller);
-    };
-    const snapshotKey = createCacheSnapshotKey(odspResolvedUrl);
-    let cacheP: Promise<void> | undefined;
-    const putInCache = async (valueWithEpoch: IVersionedValueWithEpoch) => {
-        cacheP = persistedCache.put(
-            snapshotKey,
-            valueWithEpoch,
-        );
-        return cacheP;
-    };
-    const removeEntries = async () => persistedCache.removeEntries(snapshotKey.file);
-    return PerformanceEvent.timedExecAsync(
-        odspLogger,
-        { eventName: "PrefetchLatestSnapshot" },
-        async () => {
-            await fetchSnapshotWithRedeem(
-                    odspResolvedUrl,
-                    storageTokenFetcher,
-                    hostSnapshotFetchOptions,
-                    forceAccessTokenViaAuthorizationHeader,
-                    odspLogger,
-                    snapshotDownloader,
-                    putInCache,
-                    removeEntries,
-                    enableRedeemFallback,
-                );
-            assert(cacheP !== undefined, 0x1e7 /* "caching was not performed!" */);
-            await cacheP;
-            return true;
-    }).catch(async (error) => false);
+	const snapshotDownloader = async (
+		finalOdspResolvedUrl: IOdspResolvedUrl,
+		storageToken: string,
+		snapshotOptions: ISnapshotOptions | undefined,
+		controller?: AbortController,
+	) => {
+		return downloadSnapshot(
+			finalOdspResolvedUrl,
+			storageToken,
+			odspLogger,
+			snapshotOptions,
+			undefined,
+			controller,
+		);
+	};
+	const snapshotKey = createCacheSnapshotKey(odspResolvedUrl);
+	let cacheP: Promise<void> | undefined;
+	let snapshotEpoch: string | undefined;
+	const putInCache = async (valueWithEpoch: IVersionedValueWithEpoch) => {
+		snapshotEpoch = valueWithEpoch.fluidEpoch;
+		cacheP = persistedCache.put(snapshotKey, valueWithEpoch);
+		return cacheP;
+	};
+	const removeEntries = async () => persistedCache.removeEntries(snapshotKey.file);
+	return PerformanceEvent.timedExecAsync(
+		odspLogger,
+		{ eventName: "PrefetchLatestSnapshot" },
+		async () => {
+			const prefetchStartTime = performance.now();
+			// Add the deferred promise to the cache, so that it can be leveraged while loading the container.
+			const snapshotContentsWithEpochP = new Deferred<IPrefetchSnapshotContents>();
+			const nonPersistentCacheKey = getKeyForCacheEntry(snapshotKey);
+			const snapshotNonPersistentCache =
+				odspDocumentServiceFactory?.snapshotPrefetchResultCache;
+			snapshotNonPersistentCache?.add(
+				nonPersistentCacheKey,
+				async () => snapshotContentsWithEpochP.promise,
+			);
+			await fetchSnapshotWithRedeem(
+				odspResolvedUrl,
+				storageTokenFetcher,
+				hostSnapshotFetchOptions,
+				forceAccessTokenViaAuthorizationHeader,
+				odspLogger,
+				snapshotDownloader,
+				putInCache,
+				removeEntries,
+				enableRedeemFallback,
+			)
+				.then(async (value) => {
+					assert(
+						!!snapshotEpoch,
+						0x585 /* prefetched snapshot should have a valid epoch */,
+					);
+					snapshotContentsWithEpochP.resolve({
+						...value,
+						fluidEpoch: snapshotEpoch,
+						prefetchStartTime,
+					});
+					assert(cacheP !== undefined, 0x1e7 /* "caching was not performed!" */);
+					await cacheP;
+					// Schedule it to remove from cache after 5s.
+					// 1. While it's in snapshotNonPersistentCache: Load flow will use this value and will not attempt
+					// to fetch snapshot from network again. That's the best from perf POV, but cache will not be
+					// updated if we keep it in this cache, thus we want to eventually remove snapshot from this cache.
+					// 2. After it's removed from snapshotNonPersistentCache: snapshot is present in persistent cache,
+					// so we sill still use it (in accordance with cache policy controlled by host). But load flow will
+					// also fetch snapshot (in parallel) from storage and update cache. This is fine long term,
+					// but is an extra cost (unneeded network call). However since it is 5s older, new network call
+					// will update the snapshot in cache.
+					setTimeout(() => {
+						snapshotNonPersistentCache?.remove(nonPersistentCacheKey);
+					}, 5000);
+				})
+				.catch((err) => {
+					// Remove it from the non persistent cache if an error occured.
+					snapshotNonPersistentCache?.remove(nonPersistentCacheKey);
+					snapshotContentsWithEpochP.reject(err);
+					throw err;
+				});
+			return true;
+		},
+	).catch(async (error) => {
+		odspLogger.sendErrorEvent({ eventName: "PrefetchLatestSnapshotError" }, error);
+		return false;
+	});
 }

package/src/retryErrorsStorageAdapter.ts

@@ -3,98 +3,113 @@
  * Licensed under the MIT License.
  */
 
-import { LoggingError } from "@fluidframework/telemetry-utils";
+import { LoggingError, ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
 import {
-    IDocumentStorageService,
-    IDocumentStorageServicePolicies,
-    ISummaryContext,
+	FetchSource,
+	IDocumentStorageService,
+	IDocumentStorageServicePolicies,
+	ISummaryContext,
 } from "@fluidframework/driver-definitions";
 import {
-    ICreateBlobResponse,
-    ISnapshotTree,
-    ISummaryHandle,
-    ISummaryTree,
-    IVersion,
+	ICreateBlobResponse,
+	ISnapshotTree,
+	ISummaryHandle,
+	ISummaryTree,
+	IVersion,
 } from "@fluidframework/protocol-definitions";
-import { IDisposable, ITelemetryLogger } from "@fluidframework/common-definitions";
+import { IDisposable } from "@fluidframework/core-interfaces";
 import { runWithRetry } from "./retryUtils";
 
 export class RetryErrorsStorageAdapter implements IDocumentStorageService, IDisposable {
-    private _disposed = false;
-    constructor(
-        private readonly internalStorageService: IDocumentStorageService,
-        private readonly logger: ITelemetryLogger,
-    ) {
-    }
+	private _disposed = false;
+	constructor(
+		private readonly internalStorageService: IDocumentStorageService,
+		private readonly logger: ITelemetryLoggerExt,
+	) {}
 
-    public get policies(): IDocumentStorageServicePolicies | undefined {
-        return this.internalStorageService.policies;
-    }
-    public get disposed() { return this._disposed; }
-    public dispose() {
-        this._disposed = true;
-    }
+	public get policies(): IDocumentStorageServicePolicies | undefined {
+		return this.internalStorageService.policies;
+	}
+	public get disposed() {
+		return this._disposed;
+	}
+	public dispose() {
+		this._disposed = true;
+	}
 
-    public get repositoryUrl(): string {
-        return this.internalStorageService.repositoryUrl;
-    }
+	public get repositoryUrl(): string {
+		return this.internalStorageService.repositoryUrl;
+	}
 
-    public async getSnapshotTree(version?: IVersion): Promise<ISnapshotTree | null> {
-        return this.runWithRetry(
-            async () => this.internalStorageService.getSnapshotTree(version),
-            "storage_getSnapshotTree",
-        );
-    }
+	// eslint-disable-next-line @rushstack/no-new-null
+	public async getSnapshotTree(version?: IVersion): Promise<ISnapshotTree | null> {
+		return this.runWithRetry(
+			async () => this.internalStorageService.getSnapshotTree(version),
+			"storage_getSnapshotTree",
+		);
+	}
 
-    public async readBlob(id: string): Promise<ArrayBufferLike> {
-        return this.runWithRetry(
-            async () => this.internalStorageService.readBlob(id),
-            "storage_readBlob",
-        );
-    }
+	public async readBlob(id: string): Promise<ArrayBufferLike> {
+		return this.runWithRetry(
+			async () => this.internalStorageService.readBlob(id),
+			"storage_readBlob",
+		);
+	}
 
-    public async getVersions(versionId: string | null, count: number): Promise<IVersion[]> {
-        return this.runWithRetry(
-            async () => this.internalStorageService.getVersions(versionId, count),
-            "storage_getVersions",
-        );
-    }
+	public async getVersions(
+		// eslint-disable-next-line @rushstack/no-new-null
+		versionId: string | null,
+		count: number,
+		scenarioName?: string,
+		fetchSource?: FetchSource,
+	): Promise<IVersion[]> {
+		return this.runWithRetry(
+			async () =>
+				this.internalStorageService.getVersions(
+					versionId,
+					count,
+					scenarioName,
+					fetchSource,
+				),
+			"storage_getVersions",
+		);
+	}
 
-    public async uploadSummaryWithContext(summary: ISummaryTree, context: ISummaryContext): Promise<string> {
-        // Creation flow with attachment blobs - need to do retries!
-        return this.runWithRetry(
-            async () => this.internalStorageService.uploadSummaryWithContext(summary, context),
-            "storage_uploadSummaryWithContext",
-        );
-    }
+	public async uploadSummaryWithContext(
+		summary: ISummaryTree,
+		context: ISummaryContext,
+	): Promise<string> {
+		// Creation flow with attachment blobs - need to do retries!
+		return this.runWithRetry(
+			async () => this.internalStorageService.uploadSummaryWithContext(summary, context),
+			"storage_uploadSummaryWithContext",
+		);
+	}
 
-    public async downloadSummary(handle: ISummaryHandle): Promise<ISummaryTree> {
-        return this.runWithRetry(
-            async () => this.internalStorageService.downloadSummary(handle),
-            "storage_downloadSummary",
-        );
-    }
+	public async downloadSummary(handle: ISummaryHandle): Promise<ISummaryTree> {
+		return this.runWithRetry(
+			async () => this.internalStorageService.downloadSummary(handle),
+			"storage_downloadSummary",
+		);
+	}
 
-    public async createBlob(file: ArrayBufferLike): Promise<ICreateBlobResponse> {
-        return this.runWithRetry(
-            async () => this.internalStorageService.createBlob(file),
-            "storage_createBlob",
-        );
-    }
+	public async createBlob(file: ArrayBufferLike): Promise<ICreateBlobResponse> {
+		return this.runWithRetry(
+			async () => this.internalStorageService.createBlob(file),
+			"storage_createBlob",
+		);
+	}
 
-    private checkStorageDisposed() {
-        if (this._disposed) {
-            // pre-0.58 error message: storageServiceDisposedCannotRetry
-            throw new LoggingError("Storage Service is disposed. Cannot retry", { canRetry: false });
-        }
-    }
+	private checkStorageDisposed() {
+		if (this._disposed) {
+			// pre-0.58 error message: storageServiceDisposedCannotRetry
+			throw new LoggingError("Storage Service is disposed. Cannot retry", {
+				canRetry: false,
+			});
+		}
+	}
 
-    private async runWithRetry<T>(api: () => Promise<T>, callName: string): Promise<T> {
-        return runWithRetry(
-            api,
-            callName,
-            this.logger,
-            () => this.checkStorageDisposed(),
-        );
-    }
+	private async runWithRetry<T>(api: () => Promise<T>, callName: string): Promise<T> {
+		return runWithRetry(api, callName, this.logger, () => this.checkStorageDisposed());
+	}
 }

package/src/retryUtils.ts

@@ -3,9 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryLogger } from "@fluidframework/common-definitions";
-import { delay, performance } from "@fluidframework/common-utils";
-import { canRetryOnError } from "@fluidframework/driver-utils";
+import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
+import { performance } from "@fluid-internal/client-utils";
+import { delay } from "@fluidframework/core-utils";
+import { canRetryOnError, getRetryDelayFromError } from "@fluidframework/driver-utils";
 import { OdspErrorType } from "@fluidframework/odsp-driver-definitions";
 import { Odsp409Error } from "./epochTracker";
 
@@ -13,62 +14,84 @@ import { Odsp409Error } from "./epochTracker";
  * This method retries only for retriable coherency and service read only errors.
  */
 export async function runWithRetry<T>(
-    api: () => Promise<T>,
-    callName: string,
-    logger: ITelemetryLogger,
-    checkDisposed?: () => void,
+	api: () => Promise<T>,
+	callName: string,
+	logger: ITelemetryLoggerExt,
+	checkDisposed?: () => void,
 ): Promise<T> {
-    let retryAfter = 1000;
-    const start = performance.now();
-    let lastError: any;
-    for (let attempts = 1; ; attempts++) {
-        if (checkDisposed !== undefined) {
-            checkDisposed();
-        }
-        try {
-            const result = await api();
-            if (attempts > 1) {
-                logger.sendTelemetryEvent(
-                    {
-                        eventName: "MultipleRetries",
-                        callName,
-                        attempts,
-                        duration: performance.now() - start,
-                    },
-                    lastError);
-            }
-            return result;
-        } catch (error: any) {
-            const canRetry = canRetryOnError(error);
+	let retryAfter = 1000;
+	const start = performance.now();
+	let lastError: any;
+	for (let attempts = 1; ; attempts++) {
+		if (checkDisposed !== undefined) {
+			checkDisposed();
+		}
+		try {
+			const result = await api();
+			if (attempts > 1) {
+				logger.sendTelemetryEvent(
+					{
+						eventName: "MultipleRetries",
+						callName,
+						attempts,
+						duration: performance.now() - start,
+					},
+					lastError,
+				);
+			}
+			return result;
+		} catch (error: any) {
+			const canRetry = canRetryOnError(error);
 
-            const coherencyError = error?.[Odsp409Error] === true;
-            const serviceReadonlyError = error?.errorType === OdspErrorType.serviceReadOnly;
-            // Retry for retriable 409 coherency errors or serviceReadOnly errors.
-            if (!(coherencyError || serviceReadonlyError || canRetry)) {
-                throw error;
-            }
+			const coherencyError = error?.[Odsp409Error] === true;
+			const serviceReadonlyError = error?.errorType === OdspErrorType.serviceReadOnly;
 
-            // SPO itself does number of retries internally before returning 409 to client.
-            // That multiplied to 5 suggests need to reconsider current design, as client spends
-            // too much time / bandwidth doing the same thing without any progress.
-            if (attempts === 5) {
-                logger.sendErrorEvent(
-                    {
-                        eventName: coherencyError ?
-                            "CoherencyErrorTooManyRetries" : "ServiceReadonlyErrorTooManyRetries",
-                        callName,
-                        attempts,
-                        duration: performance.now() - start, // record total wait time.
-                    },
-                    error);
-                // Fail hard.
-                error.canRetry = false;
-                throw error;
-            }
+			// logging the first failed retry instead of every attempt. We want to avoid filling telemetry
+			// when we have tight loop of retrying in offline mode, but we also want to know what caused
+			// the failure in the first place
+			if (attempts === 1) {
+				logger.sendTelemetryEvent(
+					{
+						eventName: `${callName}_firstFailed`,
+						callName,
+						attempts,
+						duration: performance.now() - start, // record total wait time.
+					},
+					error,
+				);
+			}
 
-            await delay(Math.floor(retryAfter));
-            retryAfter += retryAfter / 4 * (1 + Math.random());
-            lastError = error;
-        }
-    }
+			// Retry for retriable 409 coherency errors or serviceReadOnly errors. These errors are always retriable
+			// unless someone specifically set canRetry = false on the error like in fetchSnapshot() flow. So in
+			// that case don't retry.
+			if (!((coherencyError || serviceReadonlyError) && canRetry)) {
+				throw error;
+			}
+
+			// SPO itself does number of retries internally before returning 409 to client.
+			// That multiplied to 5 suggests need to reconsider current design, as client spends
+			// too much time / bandwidth doing the same thing without any progress.
+			if (attempts === 5) {
+				logger.sendErrorEvent(
+					{
+						eventName: coherencyError
+							? "CoherencyErrorTooManyRetries"
+							: "ServiceReadonlyErrorTooManyRetries",
+						callName,
+						attempts,
+						duration: performance.now() - start, // record total wait time.
+					},
+					error,
+				);
+				// Fail hard.
+				error.canRetry = false;
+				throw error;
+			}
+
+			retryAfter = getRetryDelayFromError(error) ?? retryAfter;
+			await delay(Math.floor(retryAfter));
+			retryAfter += (retryAfter / 4) * (1 + Math.random());
+			lastError = error;
+		}
+	}
 }

package/src/socketModule.ts

@@ -0,0 +1,8 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { io } from "socket.io-client";
+
+export const SocketIOClientStatic = io;