@fluidframework/odsp-driver 0.58.1000 → 0.58.2000

package/src/odspDocumentService.ts

@@ -7,8 +7,10 @@ import { ITelemetryLogger } from "@fluidframework/common-definitions";
 import { performance } from "@fluidframework/common-utils";
 import {
     ChildLogger,
+    IFluidErrorBase,
     loggerToMonitoringContext,
     MonitoringContext,
+    normalizeError,
 } from "@fluidframework/telemetry-utils";
 import {
     IDocumentDeltaConnection,
@@ -33,6 +35,7 @@ import {
     InstrumentedStorageTokenFetcher,
     OdspErrorType,
 } from "@fluidframework/odsp-driver-definitions";
+import type { io as SocketIOClientStatic } from "socket.io-client";
 import { HostStoragePolicyInternal, ISocketStorageDiscovery } from "./contracts";
 import { IOdspCache } from "./odspCache";
 import { OdspDeltaStorageService, OdspDeltaStorageWithCache } from "./odspDeltaStorageService";
@@ -73,7 +76,7 @@ export class OdspDocumentService implements IDocumentService {
         getStorageToken: InstrumentedStorageTokenFetcher,
         getWebsocketToken: ((options: TokenFetchOptions) => Promise<string | null>) | undefined,
         logger: ITelemetryLogger,
-        socketIoClientFactory: () => Promise<SocketIOClientStatic>,
+        socketIoClientFactory: () => Promise<typeof SocketIOClientStatic>,
         cache: IOdspCache,
         hostPolicy: HostStoragePolicy,
         epochTracker: EpochTracker,
@@ -123,7 +126,7 @@ export class OdspDocumentService implements IDocumentService {
         private readonly getStorageToken: InstrumentedStorageTokenFetcher,
         private readonly getWebsocketToken: ((options: TokenFetchOptions) => Promise<string | null>) | undefined,
         logger: ITelemetryLogger,
-        private readonly socketIoClientFactory: () => Promise<SocketIOClientStatic>,
+        private readonly socketIoClientFactory: () => Promise<typeof SocketIOClientStatic>,
         private readonly cache: IOdspCache,
         hostPolicy: HostStoragePolicy,
         private readonly epochTracker: EpochTracker,
@@ -223,6 +226,18 @@ export class OdspDocumentService implements IDocumentService {
         );
     }
 
+    /** Annotate the given error indicating which connection step failed */
+    private annotateConnectionError(
+        error: any,
+        failedConnectionStep: string,
+        separateTokenRequest: boolean,
+    ): IFluidErrorBase {
+        return normalizeError(error, { props: {
+            failedConnectionStep,
+            separateTokenRequest,
+        }});
+    }
+
     /**
      * Connects to a delta stream endpoint for emitting ops.
      *
@@ -238,23 +253,31 @@ export class OdspDocumentService implements IDocumentService {
                 ? Promise.resolve(null)
                 : this.getWebsocketToken!(options);
 
+            const annotateAndRethrowConnectionError = (step: string) => (error: any) => {
+                throw this.annotateConnectionError(error, step, !requestWebsocketTokenFromJoinSession);
+            };
+
             const joinSessionPromise = this.joinSession(requestWebsocketTokenFromJoinSession, options);
             const [websocketEndpoint, websocketToken, io] =
                 await Promise.all([
-                    joinSessionPromise,
-                    websocketTokenPromise,
-                    this.socketIoClientFactory(),
+                    joinSessionPromise.catch(annotateAndRethrowConnectionError("joinSession")),
+                    websocketTokenPromise.catch(annotateAndRethrowConnectionError("getWebsocketToken")),
+                    this.socketIoClientFactory().catch(annotateAndRethrowConnectionError("socketIoClientFactory")),
                 ]);
 
             const finalWebsocketToken = websocketToken ?? (websocketEndpoint.socketToken || null);
             if (finalWebsocketToken === null) {
-                throw new NonRetryableError(
-                    "Websocket token is null",
-                    OdspErrorType.fetchTokenError,
-                    { driverVersion });
+                throw this.annotateConnectionError(
+                    new NonRetryableError(
+                        "Websocket token is null",
+                        OdspErrorType.fetchTokenError,
+                        { driverVersion },
+                    ),
+                    "getWebsocketToken",
+                    !requestWebsocketTokenFromJoinSession);
             }
             try {
-                const connection = await this.connectToDeltaStreamWithRetry(
+                const connection = await this.createDeltaConnection(
                     websocketEndpoint.tenantId,
                     websocketEndpoint.id,
                     finalWebsocketToken,
@@ -278,10 +301,15 @@ export class OdspDocumentService implements IDocumentService {
                 return connection;
             } catch (error) {
                 this.cache.sessionJoinCache.remove(this.joinSessionKey);
+
+                const normalizedError = this.annotateConnectionError(
+                    error,
+                    "createDeltaConnection",
+                    !requestWebsocketTokenFromJoinSession);
                 if (typeof error === "object" && error !== null) {
-                    error.socketDocumentId = websocketEndpoint.id;
+                    normalizedError.addTelemetryProperties({socketDocumentId: websocketEndpoint.id});
                 }
-                throw error;
+                throw normalizedError;
             }
         });
     }
@@ -357,16 +385,16 @@ export class OdspDocumentService implements IDocumentService {
         };
 
         const getResponseAndRefreshAfterDeltaMs = async () => {
-            let response = await this.cache.sessionJoinCache.addOrGet(this.joinSessionKey, executeFetch);
+            let _response = await this.cache.sessionJoinCache.addOrGet(this.joinSessionKey, executeFetch);
             // If the response does not contain refreshSessionDurationSeconds, then treat it as old flow and let the
             // cache entry to be treated as expired after 1 hour.
-            response.joinSessionResponse.refreshSessionDurationSeconds =
-                response.joinSessionResponse.refreshSessionDurationSeconds ?? 3600;
+            _response.joinSessionResponse.refreshSessionDurationSeconds =
+                _response.joinSessionResponse.refreshSessionDurationSeconds ?? 3600;
             return {
-                ...response,
+                ..._response,
                 refreshAfterDeltaMs: this.calculateJoinSessionRefreshDelta(
-                    response.entryTime, response.joinSessionResponse.refreshSessionDurationSeconds),
-            }
+                    _response.entryTime, _response.joinSessionResponse.refreshSessionDurationSeconds),
+            };
         };
         let response = await getResponseAndRefreshAfterDeltaMs();
         // This means that the cached entry has expired(This should not be possible if the response is fetched
@@ -390,8 +418,8 @@ export class OdspDocumentService implements IDocumentService {
                                 ...props,
                             },
                             error,
-                        )
-                    });;
+                        );
+                    });
             } else {
                 // Logging just for informational purposes to help with debugging as this is a new feature.
                 this.mc.logger.sendErrorEvent({
@@ -409,21 +437,20 @@ export class OdspDocumentService implements IDocumentService {
     }
 
     /**
-     * Connects to a delta stream endpoint
-     * If url #1 fails to connect, tries url #2 if applicable
+     * Creats a connection to the given delta stream endpoint
      *
      * @param tenantId - the ID of the tenant
      * @param documentId - document ID
-     * @param token - authorization token for storage service
+     * @param token - authorization token for delta service
      * @param io - websocket library
      * @param client - information about the client
      * @param webSocketUrl - websocket URL
      */
-    private async connectToDeltaStreamWithRetry(
+    private async createDeltaConnection(
         tenantId: string,
         documentId: string,
         token: string | null,
-        io: SocketIOClientStatic,
+        io: typeof SocketIOClientStatic,
         client: IClient,
         webSocketUrl: string,
     ): Promise<OdspDocumentDeltaConnection> {

package/src/odspDocumentServiceFactoryCore.ts

@@ -22,7 +22,9 @@ import {
     IPersistedCache,
     HostStoragePolicy,
     IFileEntry,
+    IOdspUrlParts,
 } from "@fluidframework/odsp-driver-definitions";
+import type { io as SocketIOClientStatic } from "socket.io-client";
 import { v4 as uuid } from "uuid";
 import {
     LocalPersistentCache,
@@ -57,6 +59,11 @@ export class OdspDocumentServiceFactoryCore implements IDocumentServiceFactory {
         ensureFluidResolvedUrl(createNewResolvedUrl);
 
         let odspResolvedUrl = getOdspResolvedUrl(createNewResolvedUrl);
+        const resolvedUrlData: IOdspUrlParts = {
+            siteUrl: odspResolvedUrl.siteUrl,
+            driveId: odspResolvedUrl.driveId,
+            itemId: odspResolvedUrl.itemId,
+        };
         const [, queryString] = odspResolvedUrl.url.split("?");
 
         const searchParams = new URLSearchParams(queryString);
@@ -94,7 +101,7 @@ export class OdspDocumentServiceFactoryCore implements IDocumentServiceFactory {
                 odspResolvedUrl = await createNewFluidFile(
                     toInstrumentedOdspTokenFetcher(
                         odspLogger,
-                        odspResolvedUrl,
+                        resolvedUrlData,
                         this.getStorageToken,
                         true /* throwOnNullToken */,
                     ),
@@ -127,7 +134,7 @@ export class OdspDocumentServiceFactoryCore implements IDocumentServiceFactory {
     constructor(
         private readonly getStorageToken: TokenFetcher<OdspResourceTokenFetchOptions>,
         private readonly getWebsocketToken: TokenFetcher<OdspResourceTokenFetchOptions> | undefined,
-        private readonly getSocketIOClient: () => Promise<SocketIOClientStatic>,
+        private readonly getSocketIOClient: () => Promise<typeof SocketIOClientStatic>,
         protected persistedCache: IPersistedCache = new LocalPersistentCache(),
         private readonly hostPolicy: HostStoragePolicy = {},
     ) {
@@ -150,6 +157,11 @@ export class OdspDocumentServiceFactoryCore implements IDocumentServiceFactory {
         cacheAndTrackerArg?: ICacheAndTracker,
     ): Promise<IDocumentService> {
         const odspResolvedUrl = getOdspResolvedUrl(resolvedUrl);
+        const resolvedUrlData: IOdspUrlParts = {
+            siteUrl: odspResolvedUrl.siteUrl,
+            driveId: odspResolvedUrl.driveId,
+            itemId: odspResolvedUrl.itemId,
+        };
         const cacheAndTracker = cacheAndTrackerArg ?? createOdspCacheAndTracker(
             this.persistedCache,
             this.nonPersistentCache,
@@ -158,7 +170,7 @@ export class OdspDocumentServiceFactoryCore implements IDocumentServiceFactory {
 
         const storageTokenFetcher = toInstrumentedOdspTokenFetcher(
             odspLogger,
-            odspResolvedUrl,
+            resolvedUrlData,
             this.getStorageToken,
             true /* throwOnNullToken */,
         );
@@ -167,7 +179,7 @@ export class OdspDocumentServiceFactoryCore implements IDocumentServiceFactory {
             ? undefined
             : async (options: TokenFetchOptions) => toInstrumentedOdspTokenFetcher(
                 odspLogger,
-                odspResolvedUrl,
+                resolvedUrlData,
                 this.getWebsocketToken!,
                 false /* throwOnNullToken */,
             )(options, "GetWebsocketToken");

package/src/odspDriverUrlResolver.ts

@@ -167,13 +167,13 @@ export class OdspDriverUrlResolver implements IUrlResolver {
         // back-compat: IFluidCodeDetails usage to be removed in 0.58.0
         let containerPackageName;
         if (packageInfoSource && "name" in packageInfoSource) {
-            containerPackageName = packageInfoSource.name
+            containerPackageName = packageInfoSource.name;
         } else if (isFluidPackage(packageInfoSource?.package)) {
-            containerPackageName = packageInfoSource?.package.name
+            containerPackageName = packageInfoSource?.package.name;
         } else {
-            containerPackageName = packageInfoSource?.package
+            containerPackageName = packageInfoSource?.package;
         }
-        containerPackageName = containerPackageName ?? odspResolvedUrl.codeHint?.containerPackageName
+        containerPackageName = containerPackageName ?? odspResolvedUrl.codeHint?.containerPackageName;
 
         return createOdspUrl({
             ... odspResolvedUrl,

package/src/odspDriverUrlResolverForShareLink.ts

@@ -11,15 +11,11 @@ import {
     IUrlResolver,
 } from "@fluidframework/driver-definitions";
 import { ITelemetryBaseLogger, ITelemetryLogger } from "@fluidframework/common-definitions";
-import { NonRetryableError } from "@fluidframework/driver-utils";
-import { PerformanceEvent } from "@fluidframework/telemetry-utils";
 import {
     IOdspResolvedUrl,
     IdentityType,
-    isTokenFromCache,
     OdspResourceTokenFetchOptions,
     TokenFetcher,
-    OdspErrorType,
 } from "@fluidframework/odsp-driver-definitions";
 import {
     getLocatorFromOdspUrl,
@@ -32,7 +28,6 @@ import { createOdspUrl } from "./createOdspUrl";
 import { OdspDriverUrlResolver } from "./odspDriverUrlResolver";
 import { getOdspResolvedUrl, createOdspLogger } from "./odspUtils";
 import { getFileLink } from "./getFileLink";
-import { pkgVersion as driverVersion } from "./packageVersion";
 
 /**
  * Properties passed to the code responsible for fetching share link for a file.
@@ -77,7 +72,7 @@ export class OdspDriverUrlResolverForShareLink implements IUrlResolver {
         if (shareLinkFetcherProps) {
             this.shareLinkFetcherProps = {
                 ...shareLinkFetcherProps,
-                tokenFetcher: this.toInstrumentedTokenFetcher(this.logger, shareLinkFetcherProps.tokenFetcher),
+                tokenFetcher: shareLinkFetcherProps.tokenFetcher,
             };
         }
     }
@@ -157,27 +152,6 @@ export class OdspDriverUrlResolverForShareLink implements IUrlResolver {
         return url.href;
     }
 
-    private toInstrumentedTokenFetcher(
-        logger: ITelemetryLogger,
-        tokenFetcher: TokenFetcher<OdspResourceTokenFetchOptions>,
-    ): TokenFetcher<OdspResourceTokenFetchOptions> {
-        return async (options: OdspResourceTokenFetchOptions) => {
-            return PerformanceEvent.timedExecAsync(
-                logger,
-                { eventName: "GetSharingLinkToken" },
-                async (event) => tokenFetcher(options).then((tokenResponse) => {
-                    if (tokenResponse === null) {
-                        throw new NonRetryableError(
-                            "Token callback returned null for share link",
-                            OdspErrorType.fetchTokenError,
-                            { driverVersion });
-                    }
-                    event.end({ fromCache: isTokenFromCache(tokenResponse) });
-                    return tokenResponse;
-                }));
-        };
-    }
-
     private async getShareLinkPromise(resolvedUrl: IOdspResolvedUrl): Promise<string> {
         if (this.shareLinkFetcherProps === undefined) {
             throw new Error("Failed to get share link because share link fetcher props are missing");
@@ -226,13 +200,13 @@ export class OdspDriverUrlResolverForShareLink implements IUrlResolver {
         // back-compat: IFluidCodeDetails usage to be removed in 0.58.0
         let containerPackageName;
         if (packageInfoSource && "name" in packageInfoSource) {
-            containerPackageName = packageInfoSource.name
+            containerPackageName = packageInfoSource.name;
         } else if (isFluidPackage(packageInfoSource?.package)) {
-            containerPackageName = packageInfoSource?.package.name
+            containerPackageName = packageInfoSource?.package.name;
         } else {
-            containerPackageName = packageInfoSource?.package
+            containerPackageName = packageInfoSource?.package;
         }
-        containerPackageName = containerPackageName ?? odspResolvedUrl.codeHint?.containerPackageName
+        containerPackageName = containerPackageName ?? odspResolvedUrl.codeHint?.containerPackageName;
 
         storeLocatorInOdspUrl(shareLinkUrl, {
             siteUrl: odspResolvedUrl.siteUrl,

package/src/odspError.ts

@@ -10,6 +10,7 @@ import { IOdspSocketError } from "./contracts";
  * Returns network error based on error object from ODSP socket (IOdspSocketError)
  */
 export function errorObjectFromSocketError(socketError: IOdspSocketError, handler: string) {
+    // pre-0.58 error message prefix: OdspSocketError
     const message = `ODSP socket error (${handler}): ${socketError.message}`;
     const error = createOdspNetworkError(
         message,

package/src/odspUtils.ts

@@ -32,6 +32,7 @@ import {
     ICacheEntry,
     snapshotKey,
     InstrumentedStorageTokenFetcher,
+    IOdspUrlParts,
 } from "@fluidframework/odsp-driver-definitions";
 import { fetch } from "./fetch";
 import { pkgVersion as driverVersion } from "./packageVersion";
@@ -109,12 +110,14 @@ export async function fetchHelper(
         // Let's assume we can retry.
         if (!response) {
             throw new NonRetryableError(
+                // pre-0.58 error message: No response from fetch call
                 "No response from ODSP fetch call",
                 DriverErrorType.incorrectServerResponse,
                 { driverVersion });
         }
         if (!response.ok || response.status < 200 || response.status >= 300) {
             throwOdspNetworkError(
+                // pre-0.58 error message prefix: odspFetchError
                 `ODSP fetch error [${response.status}]`, response.status, response, await response.text());
         }
 
@@ -152,9 +155,11 @@ export async function fetchHelper(
         //
         if (online === OnlineStatus.Offline) {
             throw new RetryableError(
+                // pre-0.58 error message prefix: Offline
                 `ODSP fetch failure (Offline): ${errorText}`, DriverErrorType.offlineError, { driverVersion });
         } else {
             throw new RetryableError(
+                // pre-0.58 error message prefix: Fetch error
                 `ODSP fetch failure: ${errorText}`, DriverErrorType.fetchFailure, { driverVersion });
         }
     });
@@ -201,6 +206,7 @@ export async function fetchAndParseAsJSONHelper<T>(
         // succeeds on retry.
         // So do not log error object itself.
         throwOdspNetworkError(
+            // pre-0.58 error message: errorWhileParsingFetchResponse
             "Error while parsing fetch response",
             fetchIncorrectResponse,
             content, // response
@@ -271,7 +277,7 @@ export function evalBlobsAndTrees(snapshot: IOdspSnapshot) {
 
 export function toInstrumentedOdspTokenFetcher(
     logger: ITelemetryLogger,
-    resolvedUrl: IOdspResolvedUrl,
+    resolvedUrlParts: IOdspUrlParts,
     tokenFetcher: TokenFetcher<OdspResourceTokenFetchOptions>,
     throwOnNullToken: boolean,
 ): InstrumentedStorageTokenFetcher {
@@ -290,9 +296,7 @@ export function toInstrumentedOdspTokenFetcher(
             },
             async (event) => tokenFetcher({
                 ...options,
-                siteUrl: resolvedUrl.siteUrl,
-                driveId: resolvedUrl.driveId,
-                itemId: resolvedUrl.itemId,
+                ...resolvedUrlParts,
             }).then((tokenResponse) => {
                 const token = tokenFromResponse(tokenResponse);
                 // This event alone generates so many events that is materially impacts cost of telemetry
@@ -305,6 +309,7 @@ export function toInstrumentedOdspTokenFetcher(
                 }
                 if (token === null && throwOnNullToken) {
                     throw new NonRetryableError(
+                        // pre-0.58 error message: Token is null for ${name} call
                         `The Host-provided token fetcher for ${name} call returned null`,
                         OdspErrorType.fetchTokenError,
                         { method: name, driverVersion });

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/odsp-driver";
-export const pkgVersion = "0.58.1000";
+export const pkgVersion = "0.58.2000";

package/src/prefetchLatestSnapshot.ts

@@ -13,6 +13,7 @@ import {
     ISnapshotOptions,
     OdspResourceTokenFetchOptions,
     TokenFetcher,
+    IOdspUrlParts,
 } from "@fluidframework/odsp-driver-definitions";
 import { ChildLogger, PerformanceEvent } from "@fluidframework/telemetry-utils";
 import {
@@ -52,9 +53,14 @@ export async function prefetchLatestSnapshot(
     const odspLogger = createOdspLogger(ChildLogger.create(logger, "PrefetchSnapshot"));
     const odspResolvedUrl = getOdspResolvedUrl(resolvedUrl);
 
+    const resolvedUrlData: IOdspUrlParts = {
+        siteUrl: odspResolvedUrl.siteUrl,
+        driveId: odspResolvedUrl.driveId,
+        itemId: odspResolvedUrl.itemId,
+    };
     const storageTokenFetcher = toInstrumentedOdspTokenFetcher(
         odspLogger,
-        odspResolvedUrl,
+        resolvedUrlData,
         getStorageToken,
         true /* throwOnNullToken */,
     );

package/src/retryErrorsStorageAdapter.ts

@@ -92,6 +92,7 @@ export class RetryErrorsStorageAdapter implements IDocumentStorageService, IDisp
 
     private checkStorageDisposed() {
         if (this._disposed) {
+            // pre-0.58 error message: storageServiceDisposedCannotRetry
             throw new LoggingError("Storage Service is disposed. Cannot retry", { canRetry: false });
         }
     }

package/src/vroom.ts

@@ -4,7 +4,7 @@
  */
 
 import { v4 as uuid } from "uuid";
-import { ITelemetryLogger } from "@fluidframework/common-definitions";
+import { ITelemetryLogger, ITelemetryProperties } from "@fluidframework/common-definitions";
 import { PerformanceEvent } from "@fluidframework/telemetry-utils";
 import { InstrumentedStorageTokenFetcher, IOdspUrlParts } from "@fluidframework/odsp-driver-definitions";
 import { ISocketStorageDiscovery } from "./contracts";
@@ -47,14 +47,21 @@ export async function fetchJoinSession(
 ): Promise<ISocketStorageDiscovery> {
     const token = await getStorageToken(options, "JoinSession");
 
-    const extraProps = options.refresh
+    const tokenRefreshProps = options.refresh
         ? { hasClaims: !!options.claims, hasTenantId: !!options.tenantId }
         : {};
+    const details: ITelemetryProperties = {
+        refreshedToken: options.refresh,
+        requestSocketToken,
+        ...tokenRefreshProps,
+    };
+
     return PerformanceEvent.timedExecAsync(
         logger, {
             eventName: "JoinSession",
             attempts: options.refresh ? 2 : 1,
-            ...extraProps,
+            details: JSON.stringify(details),
+            ...tokenRefreshProps,
         },
         async (event) => {
             const siteOrigin = getOrigin(urlParts.siteUrl);