@fluidframework/odsp-driver 2.21.0 → 2.22.0

package/src/getFileLink.ts

@@ -20,6 +20,7 @@ import {
 } from "@fluidframework/telemetry-utils/internal";
 
 import { getHeadersWithAuth } from "./getUrlAndHeadersWithAuth.js";
+import { mockify } from "./mockify.js";
 import {
 	fetchHelper,
 	getWithRetryForTokenRefresh,
@@ -42,64 +43,66 @@ const fileLinkCache = new Map<string, Promise<string>>();
  * @param logger - used to log results of operation, including any error
  * @returns Promise which resolves to file link url when successful; otherwise, undefined.
  */
-export async function getFileLink(
-	getToken: TokenFetcher<OdspResourceTokenFetchOptions>,
-	resolvedUrl: IOdspResolvedUrl,
-	logger: ITelemetryLoggerExt,
-): Promise<string> {
-	const cacheKey = `${resolvedUrl.siteUrl}_${resolvedUrl.driveId}_${resolvedUrl.itemId}`;
-	const maybeFileLinkCacheEntry = fileLinkCache.get(cacheKey);
-	if (maybeFileLinkCacheEntry !== undefined) {
-		return maybeFileLinkCacheEntry;
-	}
+export const getFileLink = mockify(
+	async (
+		getToken: TokenFetcher<OdspResourceTokenFetchOptions>,
+		resolvedUrl: IOdspResolvedUrl,
+		logger: ITelemetryLoggerExt,
+	): Promise<string> => {
+		const cacheKey = `${resolvedUrl.siteUrl}_${resolvedUrl.driveId}_${resolvedUrl.itemId}`;
+		const maybeFileLinkCacheEntry = fileLinkCache.get(cacheKey);
+		if (maybeFileLinkCacheEntry !== undefined) {
+			return maybeFileLinkCacheEntry;
+		}
 
-	const fileLinkGenerator = async function (): Promise<string> {
-		let fileLinkCore: string;
-		try {
-			let retryCount = 0;
-			fileLinkCore = await runWithRetry(
-				async () =>
-					runWithRetryForCoherencyAndServiceReadOnlyErrors(
-						async () =>
-							getFileLinkWithLocationRedirectionHandling(getToken, resolvedUrl, logger),
-						"getFileLinkCore",
-						logger,
-					),
-				"getShareLink",
-				logger,
-				{
-					// TODO: use a stronger type
-					// eslint-disable-next-line @typescript-eslint/no-explicit-any
-					onRetry(delayInMs: number, error: any) {
-						retryCount++;
-						if (retryCount === 5) {
-							if (error !== undefined && typeof error === "object") {
-								// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-								error.canRetry = false;
+		const fileLinkGenerator = async function (): Promise<string> {
+			let fileLinkCore: string;
+			try {
+				let retryCount = 0;
+				fileLinkCore = await runWithRetry(
+					async () =>
+						runWithRetryForCoherencyAndServiceReadOnlyErrors(
+							async () =>
+								getFileLinkWithLocationRedirectionHandling(getToken, resolvedUrl, logger),
+							"getFileLinkCore",
+							logger,
+						),
+					"getShareLink",
+					logger,
+					{
+						// TODO: use a stronger type
+						// eslint-disable-next-line @typescript-eslint/no-explicit-any
+						onRetry(delayInMs: number, error: any) {
+							retryCount++;
+							if (retryCount === 5) {
+								if (error !== undefined && typeof error === "object") {
+									// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+									error.canRetry = false;
+									throw error;
+								}
 								throw error;
 							}
-							throw error;
-						}
+						},
 					},
-				},
-			);
-		} catch (error) {
-			// Delete from the cache to permit retrying later.
-			fileLinkCache.delete(cacheKey);
-			throw error;
-		}
+				);
+			} catch (error) {
+				// Delete from the cache to permit retrying later.
+				fileLinkCache.delete(cacheKey);
+				throw error;
+			}
 
-		// We are guaranteed to run the getFileLinkCore at least once with successful result (which must be a string)
-		assert(
-			fileLinkCore !== undefined,
-			0x292 /* "Unexpected undefined result from getFileLinkCore" */,
-		);
-		return fileLinkCore;
-	};
-	const fileLink = fileLinkGenerator();
-	fileLinkCache.set(cacheKey, fileLink);
-	return fileLink;
-}
+			// We are guaranteed to run the getFileLinkCore at least once with successful result (which must be a string)
+			assert(
+				fileLinkCore !== undefined,
+				0x292 /* "Unexpected undefined result from getFileLinkCore" */,
+			);
+			return fileLinkCore;
+		};
+		const fileLink = fileLinkGenerator();
+		fileLinkCache.set(cacheKey, fileLink);
+		return fileLink;
+	},
+);
 
 /**
  * Handles location redirection while fulfilling the getFileLink call. We don't want browser to handle

package/src/mockify.ts

@@ -0,0 +1,67 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * A special key used to store the original function in a {@link Mockable | mockable} function.
+ * @remarks Use {@link mockify | `mockify.key`} as a convenient way to access this key.
+ */
+export const mockifyMockKey = Symbol("`mockify` mock function key");
+
+/**
+ * A function that can be mocked after being decorated by {@link mockify | mockify()}.
+ */
+export interface Mockable<T extends (...args: any[]) => unknown> {
+	(...args: Parameters<T>): ReturnType<T>;
+	[mockifyMockKey]: T;
+}
+
+/**
+ * Decorates a function to allow it to be mocked.
+ * @param fn - The function that will become mockable.
+ * @returns A function with a {@link mockifyMockKey | special property } that can be overwritten to mock the original function.
+ * By default, this property is set to the original function.
+ * If overwritten with a new function, the new function will be called instead of the original.
+ * @example
+ * ```typescript
+ * const original = () => console.log("original");
+ * const mockable = mockify(original);
+ * mockable(); // logs "original"
+ * mockable[mockify.key] = () => console.log("mocked");
+ * mockable(); // logs "mocked"
+ * mockable[mockify.key] = original;
+ * mockable(); // logs "original"
+ * ```
+ *
+ * This pattern is useful for mocking top-level exported functions in a module.
+ * For example,
+ * ```typescript
+ * export function fn() { /* ... * / }
+ * ```
+ * becomes
+ * ```typescript
+ * import { mockify } from "./mockify.js";
+ * export const fn = mockify(() => { /* ... * / });
+ * ```
+ * and can now be mocked by another module that imports it.
+ * ```typescript
+ * import * as sinon from "sinon";
+ * import { mockify } from "./mockify.js";
+ * import { fn } from "./module.js";
+ * sinon.stub(fn, mockify.key).callsFake(() => {
+ *   // ... mock function implementation ...
+ * });
+ * // ...
+ * sinon.restore();
+ * ```
+ */
+export function mockify<T extends (...args: any[]) => unknown>(fn: T): Mockable<T> {
+	const mockable = (...args: Parameters<T>): ReturnType<T> => {
+		return mockable[mockifyMockKey](...args) as ReturnType<T>;
+	};
+	mockable[mockifyMockKey] = fn;
+	return mockable;
+}
+
+mockify.key = mockifyMockKey;

package/src/odspUtils.ts

@@ -54,7 +54,6 @@ import {
 	wrapError,
 } from "@fluidframework/telemetry-utils/internal";
 
-import { fetch } from "./fetch.js";
 import { storeLocatorInOdspUrl } from "./odspFluidFileLink.js";
 // eslint-disable-next-line import/no-deprecated
 import { ISnapshotContents } from "./odspPublicUtils.js";
@@ -137,10 +136,9 @@ export async function fetchHelper(
 ): Promise<IOdspResponse<Response>> {
 	const start = performanceNow();
 
-	// Node-fetch and dom have conflicting typing, force them to work by casting for now
 	return fetch(requestInfo, requestInit).then(
 		async (fetchResponse) => {
-			const response = fetchResponse as unknown as Response;
+			const response = fetchResponse;
 			// Let's assume we can retry.
 			if (!response) {
 				throw new NonRetryableError(
@@ -221,6 +219,8 @@ export async function fetchHelper(
 		},
 	);
 }
+// This allows `fetch` to be mocked (e.g. with sinon `stub()`)
+fetchHelper.fetch = fetch;
 
 /**
  * A utility function to fetch and parse as JSON with support for retries

package/src/packageVersion.ts

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

package/src/socketModule.ts

@@ -5,6 +5,6 @@
 
 import { io } from "socket.io-client";
 
-// Import is required for side-effects.
-// eslint-disable-next-line unicorn/prefer-export-from
-export const SocketIOClientStatic = io;
+import { mockify, type Mockable } from "./mockify.js";
+
+export const SocketIOClientStatic: Mockable<typeof io> = mockify(io);

package/src/vroom.ts

@@ -16,6 +16,7 @@ import {
 import { v4 as uuid } from "uuid";
 
 import { EpochTracker } from "./epochTracker.js";
+import { mockify } from "./mockify.js";
 import { getApiRoot } from "./odspUrlHelper.js";
 import { TokenFetchOptionsEx } from "./odspUtils.js";
 import { runWithRetry } from "./retryUtils.js";
@@ -42,100 +43,102 @@ interface IJoinSessionBody {
  * This is optional and used only when collab session is being joined by client acting in app-only mode (i.e. without user context).
  * If not specified client display name is extracted from the access token that is used to join session.
  */
-export async function fetchJoinSession(
-	urlParts: IOdspUrlParts,
-	path: string,
-	method: "GET" | "POST",
-	logger: ITelemetryLoggerExt,
-	getAuthHeader: InstrumentedStorageTokenFetcher,
-	epochTracker: EpochTracker,
-	requestSocketToken: boolean,
-	options: TokenFetchOptionsEx,
-	disableJoinSessionRefresh: boolean | undefined,
-	isRefreshingJoinSession: boolean,
-	displayName: string | undefined,
-): Promise<ISocketStorageDiscovery> {
-	const apiRoot = getApiRoot(new URL(urlParts.siteUrl));
-	const url = `${apiRoot}/drives/${urlParts.driveId}/items/${urlParts.itemId}/${path}?ump=1`;
-	const authHeader = await getAuthHeader(
-		{ ...options, request: { url, method } },
-		"JoinSession",
-	);
+export const fetchJoinSession = mockify(
+	async (
+		urlParts: IOdspUrlParts,
+		path: string,
+		method: "GET" | "POST",
+		logger: ITelemetryLoggerExt,
+		getAuthHeader: InstrumentedStorageTokenFetcher,
+		epochTracker: EpochTracker,
+		requestSocketToken: boolean,
+		options: TokenFetchOptionsEx,
+		disableJoinSessionRefresh: boolean | undefined,
+		isRefreshingJoinSession: boolean,
+		displayName: string | undefined,
+	): Promise<ISocketStorageDiscovery> => {
+		const apiRoot = getApiRoot(new URL(urlParts.siteUrl));
+		const url = `${apiRoot}/drives/${urlParts.driveId}/items/${urlParts.itemId}/${path}?ump=1`;
+		const authHeader = await getAuthHeader(
+			{ ...options, request: { url, method } },
+			"JoinSession",
+		);
 
-	const tokenRefreshProps = options.refresh
-		? { hasClaims: !!options.claims, hasTenantId: !!options.tenantId }
-		: {};
-	const details: ITelemetryBaseProperties = {
-		refreshedToken: options.refresh,
-		requestSocketToken,
-		...tokenRefreshProps,
-		refreshingSession: isRefreshingJoinSession,
-	};
-
-	return PerformanceEvent.timedExecAsync(
-		logger,
-		{
-			eventName: "JoinSession",
-			attempts: options.refresh ? 2 : 1,
-			details: JSON.stringify(details),
+		const tokenRefreshProps = options.refresh
+			? { hasClaims: !!options.claims, hasTenantId: !!options.tenantId }
+			: {};
+		const details: ITelemetryBaseProperties = {
+			refreshedToken: options.refresh,
+			requestSocketToken,
 			...tokenRefreshProps,
-		},
-		async (event) => {
-			const formBoundary = uuid();
-			let postBody = `--${formBoundary}\r\n`;
-			postBody += `Authorization: ${authHeader}\r\n`;
-			postBody += `X-HTTP-Method-Override: POST\r\n`;
-			postBody += `Content-Type: application/json\r\n`;
-			if (!disableJoinSessionRefresh) {
-				postBody += `prefer: FluidRemoveCheckAccess\r\n`;
-			}
-			postBody += `_post: 1\r\n`;
+			refreshingSession: isRefreshingJoinSession,
+		};
 
-			let requestBody: IJoinSessionBody | undefined;
-			if (requestSocketToken) {
-				requestBody = { ...requestBody, requestSocketToken: true };
-			}
-			if (displayName) {
-				requestBody = { ...requestBody, displayName };
-			}
-			if (requestBody) {
-				postBody += `\r\n${JSON.stringify(requestBody)}\r\n`;
-			}
-			postBody += `\r\n--${formBoundary}--`;
-			const headers: { [index: string]: string } = {
-				"Content-Type": `multipart/form-data;boundary=${formBoundary}`,
-			};
+		return PerformanceEvent.timedExecAsync(
+			logger,
+			{
+				eventName: "JoinSession",
+				attempts: options.refresh ? 2 : 1,
+				details: JSON.stringify(details),
+				...tokenRefreshProps,
+			},
+			async (event) => {
+				const formBoundary = uuid();
+				let postBody = `--${formBoundary}\r\n`;
+				postBody += `Authorization: ${authHeader}\r\n`;
+				postBody += `X-HTTP-Method-Override: POST\r\n`;
+				postBody += `Content-Type: application/json\r\n`;
+				if (!disableJoinSessionRefresh) {
+					postBody += `prefer: FluidRemoveCheckAccess\r\n`;
+				}
+				postBody += `_post: 1\r\n`;
 
-			const response = await runWithRetry(
-				async () =>
-					epochTracker.fetchAndParseAsJSON<ISocketStorageDiscovery>(
-						url,
-						{ method, headers, body: postBody },
-						"joinSession",
-						true,
-					),
-				"joinSession",
-				logger,
-			);
+				let requestBody: IJoinSessionBody | undefined;
+				if (requestSocketToken) {
+					requestBody = { ...requestBody, requestSocketToken: true };
+				}
+				if (displayName) {
+					requestBody = { ...requestBody, displayName };
+				}
+				if (requestBody) {
+					postBody += `\r\n${JSON.stringify(requestBody)}\r\n`;
+				}
+				postBody += `\r\n--${formBoundary}--`;
+				const headers: { [index: string]: string } = {
+					"Content-Type": `multipart/form-data;boundary=${formBoundary}`,
+				};
 
-			const socketUrl = response.content.deltaStreamSocketUrl;
-			// expecting socketUrl to be something like https://{hostName}/...
-			const webSocketHostName = socketUrl.split("/")[2];
+				const response = await runWithRetry(
+					async () =>
+						epochTracker.fetchAndParseAsJSON<ISocketStorageDiscovery>(
+							url,
+							{ method, headers, body: postBody },
+							"joinSession",
+							true,
+						),
+					"joinSession",
+					logger,
+				);
 
-			// TODO SPO-specific telemetry
-			event.end({
-				...response.propsToLog,
-				// pushV2 websocket urls will contain pushf
-				pushv2: socketUrl.includes("pushf"),
-				webSocketHostName,
-				refreshSessionDurationSeconds: response.content.refreshSessionDurationSeconds,
-			});
+				const socketUrl = response.content.deltaStreamSocketUrl;
+				// expecting socketUrl to be something like https://{hostName}/...
+				const webSocketHostName = socketUrl.split("/")[2];
 
-			if (response.content.runtimeTenantId && !response.content.tenantId) {
-				response.content.tenantId = response.content.runtimeTenantId;
-			}
+				// TODO SPO-specific telemetry
+				event.end({
+					...response.propsToLog,
+					// pushV2 websocket urls will contain pushf
+					pushv2: socketUrl.includes("pushf"),
+					webSocketHostName,
+					refreshSessionDurationSeconds: response.content.refreshSessionDurationSeconds,
+				});
 
-			return response.content;
-		},
-	);
-}
+				if (response.content.runtimeTenantId && !response.content.tenantId) {
+					response.content.tenantId = response.content.runtimeTenantId;
+				}
+
+				return response.content;
+			},
+		);
+	},
+);