@fluidframework/odsp-driver 0.52.1 → 0.53.0-46105

package/src/createFile.ts

@@ -4,12 +4,7 @@
  */
 
 import { assert, Uint8ArrayToString } from "@fluidframework/common-utils";
-import { getDocAttributesFromProtocolSummary } from "@fluidframework/driver-utils";
-import {
-    fetchIncorrectResponse,
-    invalidFileNameStatusCode,
-    throwOdspNetworkError,
-} from "@fluidframework/odsp-doclib-utils";
+import { getDocAttributesFromProtocolSummary, NonRetryableError } from "@fluidframework/driver-utils";
 import { getGitType } from "@fluidframework/protocol-base";
 import { SummaryType, ISummaryTree, ISummaryBlob } from "@fluidframework/protocol-definitions";
 import { ITelemetryLogger } from "@fluidframework/common-definitions";
@@ -18,7 +13,9 @@ import {
     IFileEntry,
     InstrumentedStorageTokenFetcher,
     IOdspResolvedUrl,
+    OdspErrorType,
 } from "@fluidframework/odsp-driver-definitions";
+import { DriverErrorType } from "@fluidframework/driver-definitions";
 import {
     IOdspSummaryTree,
     OdspSummaryTreeValue,
@@ -61,7 +58,8 @@ export async function createNewFluidFile(
 ): Promise<IOdspResolvedUrl> {
     // Check for valid filename before the request to create file is actually made.
     if (isInvalidFileName(newFileInfo.filename)) {
-        throwOdspNetworkError("invalidFilename", invalidFileNameStatusCode);
+        throw new NonRetryableError(
+            "createNewInvalidFilename", "Invalid filename", OdspErrorType.invalidFileNameError);
     }
 
     let itemId: string;
@@ -144,7 +142,10 @@ export async function createNewEmptyFluidFile(
 
                 const content = fetchResponse.content;
                 if (!content || !content.id) {
-                    throwOdspNetworkError("couldNotParseItemFromVroomResponse", fetchIncorrectResponse);
+                    throw new NonRetryableError(
+                        "createEmptyFileNoItemId",
+                        "ODSP CreateFile call returned no item ID",
+                        DriverErrorType.incorrectServerResponse);
                 }
                 event.end({
                     headers: Object.keys(headers).length !== 0 ? true : undefined,
@@ -199,7 +200,10 @@ export async function createNewFluidFileFromSummary(
 
                 const content = fetchResponse.content;
                 if (!content || !content.itemId) {
-                    throwOdspNetworkError("couldNotParseItemFromVroomResponse", fetchIncorrectResponse);
+                    throw new NonRetryableError(
+                        "createFileNoItemId",
+                        "ODSP CreateFile call returned no item ID",
+                        DriverErrorType.incorrectServerResponse);
                 }
                 event.end({
                     headers: Object.keys(headers).length !== 0 ? true : undefined,

package/src/epochTracker.ts

@@ -6,8 +6,7 @@
 import { v4 as uuid } from "uuid";
 import { assert, Deferred } from "@fluidframework/common-utils";
 import { ITelemetryLogger } from "@fluidframework/common-definitions";
-import { fluidEpochMismatchError, throwOdspNetworkError } from "@fluidframework/odsp-doclib-utils";
-import { ThrottlingError, RateLimiter } from "@fluidframework/driver-utils";
+import { ThrottlingError, RateLimiter, NonRetryableError } from "@fluidframework/driver-utils";
 import { IConnected } from "@fluidframework/protocol-definitions";
 import {
     snapshotKey,
@@ -34,6 +33,8 @@ export type FetchTypeInternal = FetchType | "cache";
 
 export const Odsp409Error = "Odsp409Error";
 
+export const defaultCacheExpiryTimeoutMs: number = 2 * 24 * 60 * 60 * 1000;
+
 /**
  * This class is a wrapper around fetch calls. It adds epoch to the request made so that the
  * server can match it with its epoch value in order to match the version.
@@ -75,16 +76,37 @@ export class EpochTracker implements IPersistedFileCache {
         entry: IEntry,
     ): Promise<any> {
         try {
+            // Return undefined so that the ops/snapshots are grabbed from the server instead of the cache
             const value: IVersionedValueWithEpoch = await this.cache.get(this.fileEntryFromEntry(entry));
+            // Version mismatch between what the runtime expects and what it recieved.
+            // The cached value should not be used
             if (value === undefined || value.version !== persistedCacheValueVersion) {
                 return undefined;
             }
             assert(value.fluidEpoch !== undefined, 0x1dc /* "all entries have to have epoch" */);
             if (this._fluidEpoch === undefined) {
                 this.setEpoch(value.fluidEpoch, true, "cache");
+            // Epoch mismatch, the cached value is considerably different from what the current state of
+            // the runtime and should not be used
             } else if (this._fluidEpoch !== value.fluidEpoch) {
                 return undefined;
             }
+            // Expire the cached snapshot if it's older than the defaultCacheExpiryTimeoutMs and immediately
+            // expire all old caches that do not have cacheEntryTime
+            if (entry.type === snapshotKey) {
+                const cacheTime = value.value?.cacheEntryTime;
+                const currentTime = Date.now();
+                if (cacheTime === undefined || currentTime - cacheTime >= defaultCacheExpiryTimeoutMs) {
+                    this.logger.sendTelemetryEvent(
+                        {
+                            eventName: "odspVersionsCacheExpired",
+                            duration: currentTime - cacheTime,
+                            maxCacheAgeMs: defaultCacheExpiryTimeoutMs,
+                        });
+                    await this.removeEntries();
+                    return undefined;
+                }
+            }
             // eslint-disable-next-line @typescript-eslint/no-unsafe-return
             return value.value;
         } catch (error) {
@@ -95,6 +117,11 @@ export class EpochTracker implements IPersistedFileCache {
 
     public async put(entry: IEntry, value: any) {
         assert(this._fluidEpoch !== undefined, 0x1dd /* "no epoch" */);
+        // For snapshots, the value should have the cacheEntryTime. This will be used to expire snapshots older
+        // than the defaultCacheExpiryTimeoutMs.
+        if (entry.type === snapshotKey) {
+            value.cacheEntryTime = value.cacheEntryTime ?? Date.now();
+        }
         const data: IVersionedValueWithEpoch = {
             value,
             version: persistedCacheValueVersion,
@@ -143,9 +170,9 @@ export class EpochTracker implements IPersistedFileCache {
         fetchType: FetchType,
         addInBody: boolean = false,
     ): Promise<IOdspResponse<T>> {
-        const clientCorelationId = this.formatClientCorelationId();
+        const clientCorrelationId = this.formatClientCorrelationId();
         // Add epoch in fetch request.
-        this.addEpochInRequest(fetchOptions, addInBody, clientCorelationId);
+        this.addEpochInRequest(fetchOptions, addInBody, clientCorrelationId);
         let epochFromResponse: string | undefined;
         return this.rateLimiter.schedule(
             async () => fetchAndParseAsJSONHelper<T>(url, fetchOptions),
@@ -154,7 +181,7 @@ export class EpochTracker implements IPersistedFileCache {
             this.validateEpochFromResponse(epochFromResponse, fetchType);
             response.commonSpoHeaders = {
                 ...response.commonSpoHeaders,
-                "X-RequestStats": clientCorelationId,
+                "X-RequestStats": clientCorrelationId,
             };
             return response;
         }).catch(async (error) => {
@@ -166,7 +193,7 @@ export class EpochTracker implements IPersistedFileCache {
             await this.checkForEpochError(error, epochFromResponse, fetchType);
             throw error;
         }).catch((error) => {
-            const fluidError = normalizeError(error, {props: {"X-RequestStats": clientCorelationId}});
+            const fluidError = normalizeError(error, { props: { XRequestStatsHeader: clientCorrelationId }});
             throw fluidError;
         });
     }
@@ -184,9 +211,9 @@ export class EpochTracker implements IPersistedFileCache {
         fetchType: FetchType,
         addInBody: boolean = false,
     ) {
-        const clientCorelationId = this.formatClientCorelationId();
+        const clientCorrelationId = this.formatClientCorrelationId();
         // Add epoch in fetch request.
-        this.addEpochInRequest(fetchOptions, addInBody, clientCorelationId);
+        this.addEpochInRequest(fetchOptions, addInBody, clientCorrelationId);
         let epochFromResponse: string | undefined;
         return this.rateLimiter.schedule(
             async () => fetchArray(url, fetchOptions),
@@ -195,7 +222,7 @@ export class EpochTracker implements IPersistedFileCache {
             this.validateEpochFromResponse(epochFromResponse, fetchType);
             response.commonSpoHeaders = {
                 ...response.commonSpoHeaders,
-                "X-RequestStats": clientCorelationId,
+                "X-RequestStats": clientCorrelationId,
             };
             return response;
         }).catch(async (error) => {
@@ -207,7 +234,7 @@ export class EpochTracker implements IPersistedFileCache {
             await this.checkForEpochError(error, epochFromResponse, fetchType);
             throw error;
         }).catch((error) => {
-            const fluidError = normalizeError(error, {props: {"X-RequestStats": clientCorelationId}});
+            const fluidError = normalizeError(error, { props: { XRequestStatsHeader: clientCorrelationId }});
             throw fluidError;
         });
     }
@@ -215,11 +242,11 @@ export class EpochTracker implements IPersistedFileCache {
     private addEpochInRequest(
         fetchOptions: RequestInit,
         addInBody: boolean,
-        clientCorelationId: string,
+        clientCorrelationId: string,
     ) {
         if (addInBody) {
             const headers: {[key: string]: string} = {};
-            headers["X-RequestStats"] = clientCorelationId;
+            headers["X-RequestStats"] = clientCorrelationId;
             if (this.fluidEpoch !== undefined) {
                 headers["x-fluid-epoch"] = this.fluidEpoch;
             }
@@ -232,7 +259,7 @@ export class EpochTracker implements IPersistedFileCache {
                 assert(fetchOptions.headers !== undefined, 0x282 /* "Headers should be present now" */);
                 fetchOptions.headers[key] = val;
             };
-            addHeader("X-RequestStats", clientCorelationId);
+            addHeader("X-RequestStats", clientCorrelationId);
             if (this.fluidEpoch !== undefined) {
                 addHeader("x-fluid-epoch", this.fluidEpoch);
             }
@@ -257,7 +284,7 @@ export class EpochTracker implements IPersistedFileCache {
         fetchOptions.body = formParams.join("\r\n");
     }
 
-    private formatClientCorelationId() {
+    private formatClientCorrelationId() {
         return `driverId=${this.driverId}, RequestNumber=${this.networkCallNumber++}`;
     }
 
@@ -266,7 +293,10 @@ export class EpochTracker implements IPersistedFileCache {
         fetchType: FetchTypeInternal,
         fromCache: boolean = false,
     ) {
-        this.checkForEpochErrorCore(epochFromResponse);
+        const error = this.checkForEpochErrorCore(epochFromResponse);
+        if (error !== undefined) {
+            throw error;
+        }
         if (epochFromResponse !== undefined) {
             if (this._fluidEpoch === undefined) {
                 this.setEpoch(epochFromResponse, fromCache, fetchType);
@@ -281,10 +311,8 @@ export class EpochTracker implements IPersistedFileCache {
         fromCache: boolean = false,
     ) {
         if (isFluidError(error) && error.errorType === DriverErrorType.fileOverwrittenInStorage) {
-            try {
-                // This will only throw if it is an epoch error.
-                this.checkForEpochErrorCore(epochFromResponse);
-            } catch (epochError) {
+            const epochError = this.checkForEpochErrorCore(epochFromResponse);
+            if (epochError !== undefined) {
                 assert(isFluidError(epochError),
                     0x21f /* "epochError expected to be thrown by throwOdspNetworkError and of known type" */);
                 epochError.addTelemetryProperties({
@@ -309,7 +337,9 @@ export class EpochTracker implements IPersistedFileCache {
         // initializes this value. Sometimes response does not contain epoch as it is still in
         // implementation phase at server side. In that case also, don't compare it with our epoch value.
         if (this.fluidEpoch && epochFromResponse && (this.fluidEpoch !== epochFromResponse)) {
-            throwOdspNetworkError("epochMismatch", fluidEpochMismatchError);
+            // This is similar in nature to how fluidEpochMismatchError (409) is handled.
+            // Difference - client detected mismatch, instead of server detecting it.
+            return new NonRetryableError("epochMismatch", "Epoch mismatch", DriverErrorType.fileOverwrittenInStorage);
         }
     }
 

package/src/fetchSnapshot.ts

@@ -104,7 +104,14 @@ export async function fetchSnapshotWithRedeem(
             }, error);
             await redeemSharingLink(odspResolvedUrl, storageTokenFetcher, logger);
             const odspResolvedUrlWithoutShareLink: IOdspResolvedUrl =
-            { ...odspResolvedUrl, shareLinkInfo: { ...odspResolvedUrl.shareLinkInfo, sharingLinkToRedeem: undefined } };
+                { ...odspResolvedUrl, sharingLinkToRedeem: undefined };
+
+            if(odspResolvedUrlWithoutShareLink.shareLinkInfo) {
+                odspResolvedUrlWithoutShareLink.shareLinkInfo = {
+                    ...odspResolvedUrlWithoutShareLink.shareLinkInfo,
+                    sharingLinkToRedeem: undefined,
+                };
+            }
 
             return fetchLatestSnapshotCore(
                 odspResolvedUrlWithoutShareLink,
@@ -140,10 +147,10 @@ async function redeemSharingLink(
             eventName: "RedeemShareLink",
         },
         async () => getWithRetryForTokenRefresh(async (tokenFetchOptions) => {
-                assert(!!odspResolvedUrl.shareLinkInfo?.sharingLinkToRedeem,
+                assert(!!odspResolvedUrl.sharingLinkToRedeem,
                     0x1ed /* "Share link should be present" */);
                 const storageToken = await storageTokenFetcher(tokenFetchOptions, "RedeemShareLink");
-                const encodedShareUrl = getEncodedShareUrl(odspResolvedUrl.shareLinkInfo.sharingLinkToRedeem);
+                const encodedShareUrl = getEncodedShareUrl(odspResolvedUrl.sharingLinkToRedeem);
                 const redeemUrl = `${odspResolvedUrl.siteUrl}/_api/v2.0/shares/${encodedShareUrl}`;
                 const { url, headers } = getUrlAndHeadersWithAuth(redeemUrl, storageToken);
                 headers.prefer = "redeemSharingLink";
@@ -349,8 +356,8 @@ async function fetchSnapshotContentsCoreV1(
             }
         });
     }
-    if (odspResolvedUrl.shareLinkInfo?.sharingLinkToRedeem) {
-        formParams.push(`sl: ${odspResolvedUrl.shareLinkInfo.sharingLinkToRedeem}`);
+    if (odspResolvedUrl.sharingLinkToRedeem) {
+        formParams.push(`sl: ${odspResolvedUrl.sharingLinkToRedeem}`);
     }
     formParams.push(`_post: 1`);
     formParams.push(`\r\n--${formBoundary}--`);
@@ -396,9 +403,9 @@ async function fetchSnapshotContentsCoreV2(
     const fullUrl = `${odspResolvedUrl.siteUrl}/_api/v2.1/drives/${odspResolvedUrl.driveId}/items/${
         odspResolvedUrl.itemId}/opStream/attachments/latest/content`;
     const queryParams = { ...snapshotOptions };
-    if (odspResolvedUrl.shareLinkInfo?.sharingLinkToRedeem) {
+    if (odspResolvedUrl.sharingLinkToRedeem) {
         // eslint-disable-next-line @typescript-eslint/dot-notation
-        queryParams["sl"] = odspResolvedUrl.shareLinkInfo.sharingLinkToRedeem;
+        queryParams["sl"] = odspResolvedUrl.sharingLinkToRedeem;
     }
     const queryString = getQueryString(queryParams);
     const { url, headers } = getUrlAndHeadersWithAuth(`${fullUrl}${queryString}`, storageToken);
@@ -460,7 +467,7 @@ export async function downloadSnapshot(
 }
 
 function isRedeemSharingLinkError(odspResolvedUrl: IOdspResolvedUrl, error: any) {
-    if (odspResolvedUrl.shareLinkInfo?.sharingLinkToRedeem !== undefined
+    if (odspResolvedUrl.sharingLinkToRedeem !== undefined
         && (typeof error === "object" && error !== null)
         && (error.errorType === DriverErrorType.authorizationError
         || error.errorType === DriverErrorType.fileNotFoundOrAccessDeniedError)) {

package/src/getFileLink.ts

@@ -5,9 +5,9 @@
 
 import { ITelemetryLogger } from "@fluidframework/common-definitions";
 import { assert, delay } from "@fluidframework/common-utils";
-import { canRetryOnError, getRetryDelayFromError } from "@fluidframework/driver-utils";
+import { canRetryOnError, getRetryDelayFromError, NonRetryableError } from "@fluidframework/driver-utils";
 import { PerformanceEvent } from "@fluidframework/telemetry-utils";
-import { fetchIncorrectResponse, throwOdspNetworkError } from "@fluidframework/odsp-doclib-utils";
+import { DriverErrorType } from "@fluidframework/driver-definitions";
 import {
     IOdspUrlParts,
     OdspResourceTokenFetchOptions,
@@ -120,7 +120,10 @@ async function getFileLinkCore(
                 const directUrl = sharingInfo?.d?.directUrl;
                 if (typeof directUrl !== "string") {
                     // This will retry once in getWithRetryForTokenRefresh
-                    throwOdspNetworkError("malformedGetSharingInformationResponse", fetchIncorrectResponse);
+                    throw new NonRetryableError(
+                        "getFileLinkCoreMalformedResponse",
+                        "Malformed GetSharingInformation response",
+                        DriverErrorType.incorrectServerResponse);
                 }
                 return directUrl;
             });
@@ -171,7 +174,10 @@ async function getFileItemLite(
                 const responseJson = await response.content.json();
                 if (!isFileItemLite(responseJson)) {
                     // This will retry once in getWithRetryForTokenRefresh
-                    throwOdspNetworkError("malformedGetFileItemLiteResponse", fetchIncorrectResponse);
+                    throw new NonRetryableError(
+                        "getFileItemLiteMalformedResponse",
+                        "Malformed getFileItemLite response",
+                        DriverErrorType.incorrectServerResponse);
                 }
                 return responseJson;
             });

package/src/odspDeltaStorageService.ts

@@ -41,6 +41,7 @@ export class OdspDeltaStorageService {
         from: number,
         to: number,
         telemetryProps: ITelemetryProperties,
+        fetchReason?: string,
     ): Promise<IDeltasFetchResult> {
         return getWithRetryForTokenRefresh(async (options) => {
             // Note - this call ends up in getSocketStorageDiscovery() and can refresh token
@@ -52,6 +53,9 @@ export class OdspDeltaStorageService {
             let postBody = `--${formBoundary}\r\n`;
             postBody += `Authorization: Bearer ${storageToken}\r\n`;
             postBody += `X-HTTP-Method-Override: GET\r\n`;
+            if (fetchReason !== undefined) {
+                postBody += `fetchReason: ${fetchReason}\r\n`;
+            }
 
             postBody += `_post: 1\r\n`;
             postBody += `\r\n--${formBoundary}--`;
@@ -123,7 +127,8 @@ export class OdspDeltaStorageWithCache implements IDocumentDeltaStorageService {
         private readonly getFromStorage: (
             from: number,
             to: number,
-            telemetryProps: ITelemetryProperties) => Promise<IDeltasFetchResult>,
+            telemetryProps: ITelemetryProperties,
+            fetchReason?: string) => Promise<IDeltasFetchResult>,
         private readonly getCached: (from: number, to: number) => Promise<ISequencedDocumentMessage[]>,
         private readonly requestFromSocket: (from: number, to: number) => void,
         private readonly opsReceived: (ops: ISequencedDocumentMessage[]) => void,
@@ -151,7 +156,8 @@ export class OdspDeltaStorageWithCache implements IDocumentDeltaStorageService {
         fromTotal: number,
         toTotal: number | undefined,
         abortSignal?: AbortSignal,
-        cachedOnly?: boolean)
+        cachedOnly?: boolean,
+        fetchReason?: string)
     {
         // We do not control what's in the cache. Current API assumes that fetchMessages() keeps banging on
         // storage / cache until it gets ops it needs. This would result in deadlock if fixed range is asked from
@@ -198,7 +204,7 @@ export class OdspDeltaStorageWithCache implements IDocumentDeltaStorageService {
                 return { messages: [], partialResult: false };
             }
 
-            const ops = await this.getFromStorage(from, to, telemetryProps);
+            const ops = await this.getFromStorage(from, to, telemetryProps, fetchReason);
             this.validateMessages("storage", ops.messages, from);
             opsFromStorage += ops.messages.length;
             this.opsReceived(ops.messages);
@@ -220,6 +226,7 @@ export class OdspDeltaStorageWithCache implements IDocumentDeltaStorageService {
             this.batchSize,
             this.logger,
             abortSignal,
+            fetchReason,
         );
 
         return streamObserver(stream, (result) => {

package/src/odspDocumentDeltaConnection.ts

@@ -20,6 +20,7 @@ import { v4 as uuid } from "uuid";
 import { IOdspSocketError, IGetOpsResponse, IFlushOpsResponse } from "./contracts";
 import { EpochTracker } from "./epochTracker";
 import { errorObjectFromSocketError } from "./odspError";
+import { pkgVersion } from "./packageVersion";
 
 const protocolVersions = ["^0.4.0", "^0.3.0", "^0.2.0", "^0.1.0"];
 const feature_get_ops = "api_get_ops";
@@ -226,6 +227,7 @@ export class OdspDocumentDeltaConnection extends DocumentDeltaConnection {
             versions: protocolVersions,
             nonce: uuid(),
             epoch: epochTracker.fluidEpoch,
+            relayUserAgent: [client.details.environment, ` driverVersion:${pkgVersion}`].join(";"),
         };
 
         // Reference to this client supporting get_ops flow.

package/src/odspDocumentService.ts

@@ -14,8 +14,8 @@ import {
     IDocumentStorageService,
     IDocumentServicePolicies,
 } from "@fluidframework/driver-definitions";
-import { DeltaStreamConnectionForbiddenError } from "@fluidframework/driver-utils";
-import { fetchTokenErrorCode, IFacetCodes, throwOdspNetworkError } from "@fluidframework/odsp-doclib-utils";
+import { DeltaStreamConnectionForbiddenError, NonRetryableError } from "@fluidframework/driver-utils";
+import { IFacetCodes } from "@fluidframework/odsp-doclib-utils";
 import {
     IClient,
     ISequencedDocumentMessage,
@@ -26,6 +26,7 @@ import {
     IEntry,
     HostStoragePolicy,
     InstrumentedStorageTokenFetcher,
+    OdspErrorType,
 } from "@fluidframework/odsp-driver-definitions";
 import { HostStoragePolicyInternal, ISocketStorageDiscovery } from "./contracts";
 import { IOdspCache } from "./odspCache";
@@ -211,7 +212,7 @@ export class OdspDocumentService implements IDocumentService {
             this.logger,
             batchSize,
             concurrency,
-            async (from, to, telemetryProps) => service.get(from, to, telemetryProps),
+            async (from, to, telemetryProps, fetchReason) => service.get(from, to, telemetryProps, fetchReason),
             async (from, to) => {
                 const res = await this.opsCache?.get(from, to);
                 return res as ISequencedDocumentMessage[] ?? [];
@@ -270,7 +271,10 @@ export class OdspDocumentService implements IDocumentService {
 
             const finalWebsocketToken = websocketToken ?? (websocketEndpoint.socketToken || null);
             if (finalWebsocketToken === null) {
-                throwOdspNetworkError("pushTokenIsNull", fetchTokenErrorCode);
+                throw new NonRetryableError(
+                    "pushTokenIsNull",
+                    "Websocket token is null",
+                    OdspErrorType.fetchTokenError);
             }
             try {
                 const connection = await this.connectToDeltaStreamWithRetry(

package/src/odspDocumentStorageManager.ts

@@ -17,9 +17,9 @@ import {
     ISummaryContext,
     IDocumentStorageService,
     LoaderCachingPolicy,
+    DriverErrorType,
 } from "@fluidframework/driver-definitions";
-import { RateLimiter } from "@fluidframework/driver-utils";
-import { throwOdspNetworkError } from "@fluidframework/odsp-doclib-utils";
+import { RateLimiter, NonRetryableError } from "@fluidframework/driver-utils";
 import {
     IOdspResolvedUrl,
     ISnapshotOptions,
@@ -313,9 +313,6 @@ export class OdspDocumentStorageService implements IDocumentStorageService {
             this.blobCache.setBlob(blobId, blob);
         }
 
-        if (!this.attributesBlobHandles.has(blobId)) {
-            return blob;
-        }
         return blob;
     }
 
@@ -406,22 +403,31 @@ export class OdspDocumentStorageService implements IDocumentStorageService {
                 { eventName: "ObtainSnapshot" },
                 async (event: PerformanceEvent) => {
                     const props = {};
-                    let cachedSnapshot: ISnapshotContents | undefined;
+                    let retrievedSnapshot: ISnapshotContents | undefined;
+                    // Here's the logic to grab the persistent cache snapshot implemented by the host
+                    // Epoch tracker is responsible for communicating with the persistent cache, handling epochs and cache versions
                     const cachedSnapshotP: Promise<ISnapshotContents | undefined> =
                         this.epochTracker.get(createCacheSnapshotKey(this.odspResolvedUrl))
-                            .then((snapshotCachedEntry: ISnapshotCachedEntry) => {
+                            .then(async (snapshotCachedEntry: ISnapshotCachedEntry) => {
                                 if (snapshotCachedEntry !== undefined) {
                                     // If the cached entry does not contain the entry time, then assign it a default of 30 days old.
-                                    // eslint-disable-next-line @typescript-eslint/dot-notation
-                                    props["cacheEntryAge"] = Date.now() - (snapshotCachedEntry.cacheEntryTime ??
+                                    const age = Date.now() - (snapshotCachedEntry.cacheEntryTime ??
                                         (Date.now() - 30 * 24 * 60 * 60 * 1000));
+
+                                    // Record the cache age
+                                    // eslint-disable-next-line @typescript-eslint/dot-notation
+                                    props["cacheEntryAge"] = age;
                                 }
+
                                 return snapshotCachedEntry;
                         });
 
+                    // Based on the concurrentSnapshotFetch policy:
+                    // Either retrieve both the network and cache snapshots concurrently and pick the first to return,
+                    // or grab the cache value and then the network value if the cache value returns undefined.
                     let method: string;
                     if (this.hostPolicy.concurrentSnapshotFetch && !this.hostPolicy.summarizerClient) {
-                        const snapshotP = this.fetchSnapshot(hostSnapshotOptions);
+                        const networkSnapshotP = this.fetchSnapshot(hostSnapshotOptions);
 
                         // Ensure that failures on both paths are ignored initially.
                         // I.e. if cache fails for some reason, we will proceed with network result.
@@ -429,20 +435,20 @@ export class OdspDocumentStorageService implements IDocumentStorageService {
                         // do want to attempt to succeed with cached data!
                         const promiseRaceWinner = await promiseRaceWithWinner([
                             cachedSnapshotP.catch(() => undefined),
-                            snapshotP.catch(() => undefined),
+                            networkSnapshotP.catch(() => undefined),
                         ]);
-                        cachedSnapshot = promiseRaceWinner.value;
+                        retrievedSnapshot = promiseRaceWinner.value;
                         method = promiseRaceWinner.index === 0 ? "cache" : "network";
 
-                        if (cachedSnapshot === undefined) {
+                        if (retrievedSnapshot === undefined) {
                             // if network failed -> wait for cache ( then return network failure)
                             // If cache returned empty or failed -> wait for network (success of failure)
                             if (promiseRaceWinner.index === 1) {
-                                cachedSnapshot = await cachedSnapshotP;
+                                retrievedSnapshot = await cachedSnapshotP;
                                 method = "cache";
                             }
-                            if (cachedSnapshot === undefined) {
-                                cachedSnapshot = await snapshotP;
+                            if (retrievedSnapshot === undefined) {
+                                retrievedSnapshot = await networkSnapshotP;
                                 method = "network";
                             }
                         }
@@ -450,12 +456,12 @@ export class OdspDocumentStorageService implements IDocumentStorageService {
                         // Note: There's a race condition here - another caller may come past the undefined check
                         // while the first caller is awaiting later async code in this block.
 
-                        cachedSnapshot = await cachedSnapshotP;
+                        retrievedSnapshot = await cachedSnapshotP;
 
-                        method = cachedSnapshot !== undefined ? "cache" : "network";
+                        method = retrievedSnapshot !== undefined ? "cache" : "network";
 
-                        if (cachedSnapshot === undefined) {
-                            cachedSnapshot = await this.fetchSnapshot(hostSnapshotOptions);
+                        if (retrievedSnapshot === undefined) {
+                            retrievedSnapshot = await this.fetchSnapshot(hostSnapshotOptions);
                         }
                     }
                     if (method === "network") {
@@ -463,12 +469,11 @@ export class OdspDocumentStorageService implements IDocumentStorageService {
                         props["cacheEntryAge"] = undefined;
                     }
                     event.end({ ...props, method });
-                    return cachedSnapshot;
+                    return retrievedSnapshot;
                 },
-                {end: true, cancel: "error"},
             );
 
-            // Successful call, redirect future calls to getVersion only!
+            // Successful call, make network calls only
             this.firstVersionCall = false;
 
             this._snapshotSequenceNumber = odspSnapshotCacheValue.sequenceNumber;
@@ -503,10 +508,16 @@ export class OdspDocumentStorageService implements IDocumentStorageService {
             );
             const versionsResponse = response.content;
             if (!versionsResponse) {
-                throwOdspNetworkError("getVersionsReturnedNoResponse", 400);
+                throw new NonRetryableError(
+                    "getVersionsReturnedNoResponse",
+                    "No response from /versions endpoint",
+                    DriverErrorType.genericNetworkError);
             }
             if (!Array.isArray(versionsResponse.value)) {
-                throwOdspNetworkError("getVersionsReturnedNonArrayResponse", 400);
+                throw new NonRetryableError(
+                    "getVersionsReturnedNonArrayResponse",
+                    "Incorrect response from /versions endpoint",
+                    DriverErrorType.genericNetworkError);
             }
             return versionsResponse.value.map((version) => {
                 // Parse the date from the message
@@ -678,19 +689,28 @@ export class OdspDocumentStorageService implements IDocumentStorageService {
 
     private checkSnapshotUrl() {
         if (!this.snapshotUrl) {
-            throwOdspNetworkError("methodNotSupportedBecauseNoSnapshotUrlWasProvided", 400);
+            throw new NonRetryableError(
+                "noSnapshotUrlProvided",
+                "Method failed because no snapshot url was available",
+                DriverErrorType.genericError);
         }
     }
 
     private checkAttachmentPOSTUrl() {
         if (!this.attachmentPOSTUrl) {
-            throwOdspNetworkError("methodNotSupportedBecauseNoAttachmentPOSTUrlWasProvided", 400);
+            throw new NonRetryableError(
+                "noAttachmentPOSTUrlProvided",
+                "Method failed because no attachment POST url was available",
+                DriverErrorType.genericError);
         }
     }
 
     private checkAttachmentGETUrl() {
         if (!this.attachmentGETUrl) {
-            throwOdspNetworkError("methodNotSupportedBecauseNoAttachmentGETUrlWasProvided", 400);
+            throw new NonRetryableError(
+                "noAttachmentGETUrlWasProvided",
+                "Method failed because no attachment GET url was available",
+                DriverErrorType.genericError);
         }
     }