@fluidframework/odsp-driver 3.0.2 → 3.1.0

package/lib/requestHeaders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestHeaders.js","sourceRoot":"","sources":["../src/requestHeaders.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC;IACtC,eAAe;IACf,cAAc;IACd,eAAe;IACf,wBAAwB;IACxB,gBAAgB;CAChB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CACjC,cAA4D;IAE5D,IAAI,cAAc,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9E,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,MAAM,aAAa,GAAG,MAAM,CAAC,WAAW,CACvC,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,MAAM,CACpC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAC3D,CACD,CAAC;IACF,OAAO,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAClC,WAAyD,EACzD,cAAuC;IAEvC,MAAM,eAAe,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;IACxD,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,cAAc,CAAC;IACvB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IAC5C,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QAClC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;YACxD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACxB,CAAC;IACF,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nconst driverOwnedHeaderNames = new Set([\n\t\"authorization\",\n\t\"content-type\",\n\t\"x-fluid-epoch\",\n\t\"x-http-method-override\",\n\t\"x-requeststats\",\n]);\n\n/**\n * Creates an immutable snapshot of host-provided per-session headers after removing names owned by\n * the ODSP driver. The factory, URL resolver, epoch tracker, and Socket.IO connection use the\n * returned value so later host mutations cannot change an active document session or override\n * authentication and protocol headers.\n */\nexport function copyRequestHeaders(\n\trequestHeaders: Readonly<Record<string, string>> | undefined,\n): Readonly<Record<string, string>> | undefined {\n\tif (requestHeaders === undefined || Object.keys(requestHeaders).length === 0) {\n\t\treturn undefined;\n\t}\n\tconst copiedHeaders = Object.fromEntries(\n\t\tObject.entries(requestHeaders).filter(\n\t\t\t([name]) => !driverOwnedHeaderNames.has(name.toLowerCase()),\n\t\t),\n\t);\n\treturn Object.keys(copiedHeaders).length === 0 ? undefined : Object.freeze(copiedHeaders);\n}\n\n/**\n * Adds sanitized host headers to one ODSP request. Request-specific headers are applied last, so\n * driver-generated values win case-insensitive collisions. ODSP fetch paths use this helper for\n * snapshot, delta, blob, share-link, file-link, and version requests; Socket.IO applies the copied\n * headers separately as Node.js `extraHeaders`.\n */\nexport function mergeRequestHeaders(\n\thostHeaders: Readonly<Record<string, string>> | undefined,\n\trequestHeaders: HeadersInit | undefined,\n): HeadersInit | undefined {\n\tconst safeHostHeaders = copyRequestHeaders(hostHeaders);\n\tif (safeHostHeaders === undefined) {\n\t\treturn requestHeaders;\n\t}\n\n\tconst merged = new Headers(safeHostHeaders);\n\tif (requestHeaders !== undefined) {\n\t\tfor (const [key, value] of new Headers(requestHeaders)) {\n\t\t\tmerged.set(key, value);\n\t\t}\n\t}\n\treturn Object.fromEntries(merged);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/odsp-driver",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Socket storage implementation for SPO and ODC",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -66,22 +66,22 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~3.0.2",
-    "@fluidframework/core-interfaces": "~3.0.2",
-    "@fluidframework/core-utils": "~3.0.2",
-    "@fluidframework/driver-base": "~3.0.2",
-    "@fluidframework/driver-definitions": "~3.0.2",
-    "@fluidframework/driver-utils": "~3.0.2",
-    "@fluidframework/odsp-doclib-utils": "~3.0.2",
-    "@fluidframework/odsp-driver-definitions": "~3.0.2",
-    "@fluidframework/telemetry-utils": "~3.0.2",
+    "@fluid-internal/client-utils": "~3.1.0",
+    "@fluidframework/core-interfaces": "~3.1.0",
+    "@fluidframework/core-utils": "~3.1.0",
+    "@fluidframework/driver-base": "~3.1.0",
+    "@fluidframework/driver-definitions": "~3.1.0",
+    "@fluidframework/driver-utils": "~3.1.0",
+    "@fluidframework/odsp-doclib-utils": "~3.1.0",
+    "@fluidframework/odsp-driver-definitions": "~3.1.0",
+    "@fluidframework/telemetry-utils": "~3.1.0",
     "socket.io-client": "^4.8.3",
     "uuid": "^11.1.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@biomejs/biome": "~2.4.5",
-    "@fluid-internal/mocha-test-setup": "~3.0.2",
+    "@fluid-internal/mocha-test-setup": "~3.1.0",
     "@fluid-tools/build-cli": "^0.67.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.67.0",

package/src/epochTracker.ts

@@ -51,6 +51,7 @@ import {
 	getOdspResolvedUrl,
 } from "./odspUtils.js";
 import { pkgVersion as driverVersion } from "./packageVersion.js";
+import { copyRequestHeaders, mergeRequestHeaders } from "./requestHeaders.js";
 
 /**
  * @legacy
@@ -100,6 +101,7 @@ export const Odsp409Error = "Odsp409Error";
  */
 export class EpochTracker implements IPersistedFileCache {
 	private _fluidEpoch: string | undefined;
+	private readonly requestHeaders: Readonly<Record<string, string>> | undefined;
 
 	private readonly snapshotCacheExpiryTimeoutMs: number;
 	public readonly rateLimiter: RateLimiter;
@@ -112,8 +114,10 @@ export class EpochTracker implements IPersistedFileCache {
 		protected readonly fileEntry: IFileEntry,
 		protected readonly logger: ITelemetryLoggerExt,
 		protected readonly clientIsSummarizer?: boolean,
+		requestHeaders?: Readonly<Record<string, string>>,
 	) {
 		this.loggerInternal = extractTelemetryLoggerExt(logger);
+		this.requestHeaders = copyRequestHeaders(requestHeaders);
 
 		// Limits the max number of concurrent requests to 24.
 		this.rateLimiter = new RateLimiter(24);
@@ -298,6 +302,7 @@ export class EpochTracker implements IPersistedFileCache {
 		const clientCorrelationId = this.formatClientCorrelationId(fetchReason);
 		// Add epoch in fetch request.
 		this.addEpochInRequest(fetchOptions, addInBody, clientCorrelationId);
+		fetchOptions.headers = mergeRequestHeaders(this.requestHeaders, fetchOptions.headers);
 		let epochFromResponse: string | undefined;
 		return this.rateLimiter
 			.schedule(async () => fetcher(url, fetchOptions))
@@ -523,8 +528,9 @@ export class EpochTrackerWithRedemption extends EpochTracker {
 		protected readonly fileEntry: IFileEntry,
 		logger: TelemetryLoggerExt,
 		protected readonly clientIsSummarizer?: boolean,
+		requestHeaders?: Readonly<Record<string, string>>,
 	) {
-		super(cache, fileEntry, toITelemetryLoggerExt(logger), clientIsSummarizer);
+		super(cache, fileEntry, toITelemetryLoggerExt(logger), clientIsSummarizer, requestHeaders);
 		// Handles the rejected promise within treesLatestDeferral.
 		this.treesLatestDeferral.promise.catch(() => {});
 	}
@@ -656,12 +662,14 @@ export function createOdspCacheAndTracker(
 	fileEntry: IFileEntry,
 	logger: TelemetryLoggerExt,
 	clientIsSummarizer?: boolean,
+	requestHeaders?: Readonly<Record<string, string>>,
 ): ICacheAndTracker {
 	const epochTracker = new EpochTrackerWithRedemption(
 		persistedCacheArg,
 		fileEntry,
 		logger,
 		clientIsSummarizer,
+		requestHeaders,
 	);
 	return {
 		cache: {

package/src/fetchSnapshot.ts

@@ -68,6 +68,7 @@ import {
 	type TokenFetchOptionsEx,
 } from "./odspUtils.js";
 import { pkgVersion } from "./packageVersion.js";
+import { mergeRequestHeaders } from "./requestHeaders.js";
 
 /**
  * Enum to support different types of snapshot formats.
@@ -131,6 +132,7 @@ export async function fetchSnapshotWithRedeem(
 	removeEntries: () => Promise<void>,
 	loadingGroupIds: string[] | undefined,
 	enableRedeemFallback?: boolean,
+	requestHeaders?: Readonly<Record<string, string>>,
 ): Promise<ISnapshot> {
 	// back-compat: This block to be removed with #8784 when we only consume/consider odsp resolvers that are >= 0.51
 	// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
@@ -154,7 +156,7 @@ export async function fetchSnapshotWithRedeem(
 			// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
 			if (enableRedeemFallback && isRedeemSharingLinkError(odspResolvedUrl, error)) {
 				// Execute the redeem fallback
-				await redeemSharingLink(odspResolvedUrl, storageTokenFetcher, logger);
+				await redeemSharingLink(odspResolvedUrl, storageTokenFetcher, logger, requestHeaders);
 
 				const shareLinkInfo = { ...odspResolvedUrl.shareLinkInfo };
 				delete shareLinkInfo.sharingLinkToRedeem;
@@ -205,7 +207,12 @@ export async function fetchSnapshotWithRedeem(
 						...getOdspResolvedUrl(error.redirectUrl),
 						shareLinkInfo: odspResolvedUrl.shareLinkInfo,
 					};
-					await redeemSharingLink(redirectedResolvedUrl, storageTokenFetcher, logger);
+					await redeemSharingLink(
+						redirectedResolvedUrl,
+						storageTokenFetcher,
+						logger,
+						requestHeaders,
+					);
 				} catch (redeemError) {
 					logger.sendErrorEvent({ eventName: "RedirectRedeemFallbackError" }, redeemError);
 				}
@@ -236,6 +243,7 @@ async function redeemSharingLink(
 	odspResolvedUrl: IOdspResolvedUrl,
 	getAuthHeader: InstrumentedStorageTokenFetcher,
 	logger: TelemetryLoggerExt,
+	requestHeaders?: Readonly<Record<string, string>>,
 ): Promise<void> {
 	await PerformanceEvent.timedExecAsync(
 		logger,
@@ -272,7 +280,10 @@ async function redeemSharingLink(
 					);
 					const headers = getHeadersWithAuth(authHeader);
 					headers.prefer = isRedemptionNonDurable ? "nonDurableRedeem" : "redeemSharingLink";
-					await fetchAndParseAsJSONHelper(url, { headers, method });
+					await fetchAndParseAsJSONHelper(url, {
+						headers: mergeRequestHeaders(requestHeaders, headers),
+						method,
+					});
 				});
 			}
 
@@ -735,6 +746,7 @@ export const downloadSnapshot = mockify(
 		controller?: AbortController,
 		epochTracker?: EpochTracker,
 		scenarioName?: string,
+		requestHeaders?: Readonly<Record<string, string>>,
 	): Promise<ISnapshotRequestAndResponseOptions> => {
 		// back-compat: This block to be removed with #8784 when we only consume/consider odsp resolvers that are >= 0.51
 		// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
@@ -791,7 +803,7 @@ export const downloadSnapshot = mockify(
 		const { body, headers } = getFormBodyAndHeaders(odspResolvedUrl, authHeader, header);
 		const fetchOptions = {
 			body,
-			headers,
+			headers: mergeRequestHeaders(requestHeaders, headers),
 			signal: controller?.signal,
 			method,
 		};
@@ -806,6 +818,7 @@ export const downloadSnapshot = mockify(
 				headers.accept = `application/json, application/ms-fluid; v=${currentReadVersion}`;
 			}
 		}
+		fetchOptions.headers = mergeRequestHeaders(requestHeaders, headers);
 
 		const odspResponse = await (epochTracker?.fetch(
 			url,

package/src/getFileLink.ts

@@ -27,6 +27,7 @@ import {
 	toInstrumentedOdspStorageTokenFetcher,
 } from "./odspUtils.js";
 import { pkgVersion as driverVersion } from "./packageVersion.js";
+import { copyRequestHeaders, mergeRequestHeaders } from "./requestHeaders.js";
 import { runWithRetry as runWithRetryForCoherencyAndServiceReadOnlyErrors } from "./retryUtils.js";
 
 // Store cached responses for the lifetime of web session as file link remains the same for given file item
@@ -48,7 +49,9 @@ export const getFileLink = mockify(
 		getToken: TokenFetcher<OdspResourceTokenFetchOptions>,
 		resolvedUrl: IOdspResolvedUrl,
 		logger: TelemetryLoggerExt,
+		requestHeaders?: Readonly<Record<string, string>>,
 	): Promise<string> => {
+		const immutableRequestHeaders = copyRequestHeaders(requestHeaders);
 		const cacheKey = `${resolvedUrl.siteUrl}_${resolvedUrl.driveId}_${resolvedUrl.itemId}`;
 		const maybeFileLinkCacheEntry = fileLinkCache.get(cacheKey);
 		if (maybeFileLinkCacheEntry !== undefined) {
@@ -63,7 +66,12 @@ export const getFileLink = mockify(
 					async () =>
 						runWithRetryForCoherencyAndServiceReadOnlyErrors(
 							async () =>
-								getFileLinkWithLocationRedirectionHandling(getToken, resolvedUrl, logger),
+								getFileLinkWithLocationRedirectionHandling(
+									getToken,
+									resolvedUrl,
+									logger,
+									immutableRequestHeaders,
+								),
 							"getFileLinkCore",
 							logger,
 						),
@@ -121,6 +129,7 @@ async function getFileLinkWithLocationRedirectionHandling(
 	getToken: TokenFetcher<OdspResourceTokenFetchOptions>,
 	resolvedUrl: IOdspResolvedUrl,
 	logger: TelemetryLoggerExt,
+	requestHeaders?: Readonly<Record<string, string>>,
 ): Promise<string> {
 	// We can have chains of location redirection one after the other, so have a for loop
 	// so that we can keep handling the same type of error. Set max number of redirection to 5.
@@ -128,7 +137,7 @@ async function getFileLinkWithLocationRedirectionHandling(
 	let locationRedirected = false;
 	for (let count = 1; count <= 5; count++) {
 		try {
-			const fileItem = await getFileItemLite(getToken, resolvedUrl, logger);
+			const fileItem = await getFileItemLite(getToken, resolvedUrl, logger, requestHeaders);
 			// Sometimes the siteUrl in the actual file is different from the siteUrl in the resolvedUrl due to location
 			// redirection. This creates issues in the getSharingInformation call. So we need to update the siteUrl in the
 			// resolvedUrl to the siteUrl in the fileItem which is the updated siteUrl.
@@ -142,7 +151,7 @@ async function getFileLinkWithLocationRedirectionHandling(
 				});
 				renameTenantInOdspResolvedUrl(resolvedUrl, newSiteDomain);
 			}
-			return await getFileLinkCore(getToken, resolvedUrl, logger, fileItem);
+			return await getFileLinkCore(getToken, resolvedUrl, logger, fileItem, requestHeaders);
 		} catch (error: unknown) {
 			lastError = error;
 			// If the getSharingLink call fails with the 401/403/404 error, then it could be due to that the file has moved
@@ -167,6 +176,7 @@ async function getFileLinkCore(
 	odspUrlParts: IOdspUrlParts,
 	logger: TelemetryLoggerExt,
 	fileItem: FileItemLite,
+	requestHeaders?: Readonly<Record<string, string>>,
 ): Promise<string> {
 	// ODSP link requires extra call to return link that is resistant to file being renamed or moved to different folder
 	return PerformanceEvent.timedExecAsync(
@@ -202,11 +212,11 @@ async function getFileLinkCore(
 				const headers = getHeadersWithAuth(authHeader);
 				const requestInit = {
 					method,
-					headers: {
+					headers: mergeRequestHeaders(requestHeaders, {
 						"Content-Type": "application/json;odata=verbose",
-						"Accept": "application/json;odata=verbose",
+						Accept: "application/json;odata=verbose",
 						...headers,
-					},
+					}),
 				};
 				const response = await fetchHelper(url, requestInit);
 				additionalProps = response.propsToLog;
@@ -263,6 +273,7 @@ async function getFileItemLite(
 	getToken: TokenFetcher<OdspResourceTokenFetchOptions>,
 	odspUrlParts: IOdspUrlParts,
 	logger: TelemetryLoggerExt,
+	requestHeaders?: Readonly<Record<string, string>>,
 ): Promise<FileItemLite> {
 	return PerformanceEvent.timedExecAsync(
 		logger,
@@ -290,7 +301,10 @@ async function getFileItemLite(
 				);
 
 				const headers = getHeadersWithAuth(authHeader);
-				const requestInit = { method, headers };
+				const requestInit = {
+					method,
+					headers: mergeRequestHeaders(requestHeaders, headers),
+				};
 				const response = await fetchHelper(url, requestInit);
 				additionalProps = response.propsToLog;
 

package/src/odspDelayLoadedDeltaStream.ts

@@ -559,6 +559,7 @@ export class OdspDelayLoadedDeltaStream {
 			this.epochTracker,
 			this.socketReferenceKeyPrefix,
 			connectionId,
+			this.hostPolicy.hostProvidedRequestHeaders,
 		);
 		const duration = performanceNow() - startTime;
 		// This event happens rather often, so it adds up to cost of telemetry.

package/src/odspDocumentDeltaConnection.ts

@@ -32,6 +32,7 @@ import type { EpochTracker } from "./epochTracker.js";
 import { errorObjectFromSocketError } from "./odspError.js";
 import { pkgVersion } from "./packageVersion.js";
 import { SocketIOClientStatic } from "./socketModule.js";
+import { copyRequestHeaders } from "./requestHeaders.js";
 
 const protocolVersions = ["^0.4.0", "^0.3.0", "^0.2.0", "^0.1.0"];
 const feature_get_ops = "api_get_ops";
@@ -259,6 +260,7 @@ export class OdspDocumentDeltaConnection extends DocumentDeltaConnection {
 		epochTracker: EpochTracker,
 		socketReferenceKeyPrefix: string | undefined,
 		connectionId: string = uuid(),
+		requestHeaders?: Readonly<Record<string, string>>,
 	): Promise<OdspDocumentDeltaConnection> {
 		const mc = loggerToMonitoringContext(telemetryLogger);
 
@@ -269,6 +271,7 @@ export class OdspDocumentDeltaConnection extends DocumentDeltaConnection {
 
 		// do not include the specific tenant/doc id in the ref key when multiplexing
 		// this will allow multiple documents to share the same websocket connection
+		const immutableRequestHeaders = copyRequestHeaders(requestHeaders);
 		const key = socketReferenceKeyPrefix ? `${socketReferenceKeyPrefix},${url}` : url;
 		const socketReferenceKey = enableMultiplexing ? key : `${key},${tenantId},${documentId}`;
 
@@ -279,6 +282,7 @@ export class OdspDocumentDeltaConnection extends DocumentDeltaConnection {
 			enableMultiplexing,
 			tenantId,
 			documentId,
+			immutableRequestHeaders,
 		);
 
 		const socket = socketReference.socket;
@@ -388,6 +392,7 @@ export class OdspDocumentDeltaConnection extends DocumentDeltaConnection {
 		enableMultiplexing: boolean,
 		tenantId: string,
 		documentId: string,
+		requestHeaders?: Readonly<Record<string, string>>,
 	): SocketReference {
 		// eslint-disable-next-line unicorn/no-array-method-this-argument
 		const existingSocketReference = SocketReference.find(key);
@@ -403,6 +408,7 @@ export class OdspDocumentDeltaConnection extends DocumentDeltaConnection {
 			reconnection: false,
 			transports: ["websocket"],
 			timeout: timeoutMs,
+			...(requestHeaders === undefined ? {} : { extraHeaders: requestHeaders }),
 		});
 
 		return new SocketReference(key, socket);

package/src/odspDocumentServiceFactory.ts

@@ -90,6 +90,7 @@ export function createOdspDocumentServiceFactory(
 							clientIsSummarizer,
 							persistedCache,
 							getStorageToken: options.getStorageToken,
+							requestHeaders: this.requestHeaders,
 							createDocumentService: async (url, odspLogger, cacheAndTracker, isSummarizer) =>
 								this.createDocumentServiceCore(url, odspLogger, cacheAndTracker, isSummarizer),
 						});

package/src/odspDocumentServiceFactoryCore.ts

@@ -55,6 +55,7 @@ import {
 	toInstrumentedOdspStorageTokenFetcher,
 	toInstrumentedOdspTokenFetcher,
 } from "./odspUtils.js";
+import { copyRequestHeaders } from "./requestHeaders.js";
 
 /**
  * An ODSP document service factory that supports point-in-time (sequence-number-based) loading.
@@ -104,6 +105,8 @@ export interface IOdspPointInTimeDocumentServiceImplementationProps {
 	readonly persistedCache: IPersistedCache;
 	/** Fetches storage access tokens for ODSP requests. */
 	readonly getStorageToken: TokenFetcher<OdspResourceTokenFetchOptions>;
+	/** Host-owned attribution metadata for ODSP requests. */
+	readonly requestHeaders?: Readonly<Record<string, string>>;
 	/**
 	 * Creates an ODSP document service for a resolved URL.
 	 *
@@ -141,6 +144,8 @@ export class OdspDocumentServiceFactoryCore
 {
 	private readonly nonPersistentCache: INonPersistentCache = new NonPersistentCache();
 	private readonly socketReferenceKeyPrefix?: string;
+	private readonly hostPolicy: HostStoragePolicy;
+	public readonly requestHeaders?: Readonly<Record<string, string>>;
 
 	public get snapshotPrefetchResultCache(): PromiseCache<string, IPrefetchSnapshotContents> {
 		return this.nonPersistentCache.snapshotPrefetchResultCache;
@@ -231,6 +236,7 @@ export class OdspDocumentServiceFactoryCore
 			fileEntry,
 			odspLogger,
 			clientIsSummarizer,
+			this.requestHeaders,
 		);
 
 		return PerformanceEvent.timedExecAsync(
@@ -307,9 +313,14 @@ export class OdspDocumentServiceFactoryCore
 			| TokenFetcher<OdspResourceTokenFetchOptions>
 			| undefined,
 		protected persistedCache: IPersistedCache = new LocalPersistentCache(),
-		private readonly hostPolicy: HostStoragePolicy = {},
+		hostPolicy: HostStoragePolicy = {},
 	) {
-		if (this.hostPolicy.isolateSocketCache === true) {
+		this.requestHeaders = copyRequestHeaders(hostPolicy.hostProvidedRequestHeaders);
+		this.hostPolicy =
+			this.requestHeaders === undefined
+				? hostPolicy
+				: { ...hostPolicy, hostProvidedRequestHeaders: this.requestHeaders };
+		if (this.hostPolicy.isolateSocketCache === true || this.requestHeaders !== undefined) {
 			// create the key to separate the socket reuse cache
 			this.socketReferenceKeyPrefix = uuid();
 		}
@@ -396,6 +407,7 @@ export class OdspDocumentServiceFactoryCore
 				},
 				extLogger,
 				clientIsSummarizer,
+				this.requestHeaders,
 			);
 
 		const storageTokenFetcher = toInstrumentedOdspStorageTokenFetcher(

package/src/odspDocumentStorageManager.ts

@@ -284,6 +284,7 @@ export class OdspDocumentStorageService extends OdspDocumentStorageServiceBase {
 						hostSnapshotOptions,
 						snapshotFetchOptions.loadingGroupIds,
 						snapshotFetchOptions.scenarioName,
+						true /* avoidPrefetchSnapshotCache */,
 					);
 					method = "networkOnly";
 				} else {
@@ -355,6 +356,7 @@ export class OdspDocumentStorageService extends OdspDocumentStorageServiceBase {
 							hostSnapshotOptions,
 							snapshotFetchOptions.loadingGroupIds,
 							snapshotFetchOptions.scenarioName,
+							false /* avoidPrefetchSnapshotCache */,
 						);
 
 						// Ensure that failures on both paths are ignored initially.
@@ -412,6 +414,7 @@ export class OdspDocumentStorageService extends OdspDocumentStorageServiceBase {
 								hostSnapshotOptions,
 								snapshotFetchOptions.loadingGroupIds,
 								snapshotFetchOptions.scenarioName,
+								false /* avoidPrefetchSnapshotCache */,
 							);
 						}
 					}
@@ -553,11 +556,13 @@ export class OdspDocumentStorageService extends OdspDocumentStorageServiceBase {
 		hostSnapshotOptions: ISnapshotOptions | undefined,
 		loadingGroupIds: string[] | undefined,
 		scenarioName?: string,
+		avoidPrefetchSnapshotCache: boolean = false,
 	): Promise<ISnapshot | IPrefetchSnapshotContents> {
 		return this.fetchSnapshotFromNetworkCore(
 			hostSnapshotOptions,
 			loadingGroupIds,
 			scenarioName,
+			avoidPrefetchSnapshotCache,
 		).catch((error) => {
 			// Issue #5895:
 			// If we are offline, this error is retryable. But that means that RetriableDocumentStorageService
@@ -576,10 +581,13 @@ export class OdspDocumentStorageService extends OdspDocumentStorageServiceBase {
 		hostSnapshotOptions: ISnapshotOptions | undefined,
 		loadingGroupIds: string[] | undefined,
 		scenarioName?: string,
+		avoidPrefetchSnapshotCache: boolean = false,
 	): Promise<ISnapshot | IPrefetchSnapshotContents> {
-		// Don't look into cache, if the host specifically tells us so. Also, if request is
-		// for initial snapshot, don't consult the prefetch cache.
-		if (!this.hostPolicy.avoidPrefetchSnapshotCache && this.firstSnapshotFetchCall) {
+		if (
+			!avoidPrefetchSnapshotCache &&
+			!this.hostPolicy.avoidPrefetchSnapshotCache &&
+			this.firstSnapshotFetchCall
+		) {
 			const prefetchCacheKey = getKeyForCacheEntry(
 				createCacheSnapshotKey(
 					this.odspResolvedUrl,
@@ -668,6 +676,7 @@ export class OdspDocumentStorageService extends OdspDocumentStorageServiceBase {
 				removeEntries,
 				loadingGroupIds,
 				this.hostPolicy.enableRedeemFallback,
+				this.hostPolicy.hostProvidedRequestHeaders,
 			);
 			return odspSnapshot;
 			// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -709,6 +718,7 @@ export class OdspDocumentStorageService extends OdspDocumentStorageServiceBase {
 					removeEntries,
 					loadingGroupIds,
 					this.hostPolicy.enableRedeemFallback,
+					this.hostPolicy.hostProvidedRequestHeaders,
 				);
 				return odspSnapshot;
 			}

package/src/odspDriverUrlResolverForShareLink.ts

@@ -21,6 +21,7 @@ import type { TelemetryLoggerExt } from "@fluidframework/telemetry-utils/interna
 import { type OdspFluidDataStoreLocator, SharingLinkHeader } from "./contractsPublic.js";
 import { createOdspUrl } from "./createOdspUrl.js";
 import { getFileLink } from "./getFileLink.js";
+import { copyRequestHeaders } from "./requestHeaders.js";
 import { OdspDriverUrlResolver } from "./odspDriverUrlResolver.js";
 import {
 	getLocatorFromOdspUrl,
@@ -48,6 +49,11 @@ export interface ShareLinkFetcherProps {
 	 * Identity type determining the shape of share link as it differs for Enterprise and Consumer users.
 	 */
 	identityType: IdentityType;
+	/**
+	 * Host-owned attribution metadata for ODSP requests made while resolving share links.
+	 * Driver-owned headers take precedence on case-insensitive collisions.
+	 */
+	requestHeaders?: Readonly<Record<string, string>>;
 }
 
 /**
@@ -90,6 +96,7 @@ export class OdspDriverUrlResolverForShareLink implements IUrlResolver {
 			this.shareLinkFetcherProps = {
 				...shareLinkFetcherProps,
 				tokenFetcher: shareLinkFetcherProps.tokenFetcher,
+				requestHeaders: copyRequestHeaders(shareLinkFetcherProps.requestHeaders),
 			};
 		}
 	}
@@ -209,6 +216,7 @@ export class OdspDriverUrlResolverForShareLink implements IUrlResolver {
 			this.shareLinkFetcherProps.tokenFetcher,
 			resolvedUrl,
 			this.logger,
+			this.shareLinkFetcherProps.requestHeaders,
 		).catch((error) => {
 			// This should imply that error is a non-retriable error.
 			this.logger.sendErrorEvent({ eventName: "FluidFileUrlError" }, error);

package/src/odspVersionManager/DEV.md

@@ -571,7 +571,11 @@ The injected implementation:
    document services: a **recoverable** one bound to that base version (its storage is the base
    snapshot) and a **live** one (its delta storage supplies the ops to replay). Both are created via
    `createDocumentServiceCore` with a **single shared** `EpochTracker` (the same one the version
-   manager reads through) — this is the structural lineage guard; see the next question.
+   manager reads through) — this is the structural lineage guard; see the next question. The
+   point-in-time storage wrapper forces the recoverable service's initial snapshot read to bypass
+   both the persistent latest-snapshot cache and the in-memory snapshot-prefetch cache so the
+   selected base cannot be replaced by a newer cached live snapshot. Both loader snapshot paths
+   (`getSnapshot` and the legacy `getVersions` + `getSnapshotTree` path) apply this rule.
 3. Return an `OdspPointInTimeDocumentService` composing the two.
 
 It lives in this package rather than a generic wrapping driver (e.g. `@fluidframework/replay-driver`)

package/src/odspVersionManager/odspFileVersionFetcher.ts

@@ -28,6 +28,7 @@ import { convertOdspSnapshotToSnapshotTreeAndBlobs } from "../odspSnapshotParser
 import { getApiRoot } from "../odspUrlHelper.js";
 import { fetchArray, getWithRetryForTokenRefresh } from "../odspUtils.js";
 import { pkgVersion as driverVersion } from "../packageVersion.js";
+import { mergeRequestHeaders } from "../requestHeaders.js";
 
 /**
  * A single ODSP file version, as listed by the file's version history.
@@ -96,6 +97,7 @@ export interface OdspFileVersionFetcherProps {
 	readonly getAuthHeader: InstrumentedStorageTokenFetcher;
 	readonly epochTracker: EpochTracker;
 	readonly logger: TelemetryLoggerExt;
+	readonly requestHeaders?: Readonly<Record<string, string>>;
 }
 
 /**
@@ -104,7 +106,7 @@ export interface OdspFileVersionFetcherProps {
 export function createOdspFileVersionFetcher(
 	props: OdspFileVersionFetcherProps,
 ): IOdspFileVersionFetcher {
-	const { urlParts, getAuthHeader, epochTracker, logger } = props;
+	const { urlParts, getAuthHeader, epochTracker, logger, requestHeaders } = props;
 	const { siteUrl, driveId, itemId } = urlParts;
 
 	const listFileVersions = async (): Promise<OdspFileVersionRef[]> =>
@@ -209,7 +211,10 @@ export function createOdspFileVersionFetcher(
 				scenarioName,
 			);
 			const headers = getHeadersWithAuth(token);
-			const response = await fetchArray(url, { method, headers });
+			const response = await fetchArray(url, {
+				method,
+				headers: mergeRequestHeaders(requestHeaders, headers),
+			});
 			return response.headers.get("x-fluid-epoch") ?? undefined;
 		});
 

package/src/packageVersion.ts

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

package/src/pointInTimeDriver/createPointInTimeDocumentService.ts

@@ -51,6 +51,7 @@ async function createVersionManager(
 	logger: TelemetryLoggerExt,
 	epochTracker: EpochTracker,
 	getStorageToken: IOdspPointInTimeDocumentServiceImplementationProps["getStorageToken"],
+	requestHeaders?: Readonly<Record<string, string>>,
 ): Promise<IOdspVersionManager> {
 	const urlParts: IOdspUrlParts = {
 		siteUrl: odspResolvedUrl.siteUrl,
@@ -67,6 +68,7 @@ async function createVersionManager(
 		getAuthHeader,
 		epochTracker,
 		logger,
+		requestHeaders,
 	});
 }
 
@@ -120,6 +122,7 @@ export async function createPointInTimeDocumentServiceCore(
 		clientIsSummarizer,
 		persistedCache,
 		getStorageToken,
+		requestHeaders,
 		createDocumentService,
 	}: IOdspPointInTimeDocumentServiceImplementationProps,
 	dependencies: IPointInTimeDocumentServiceDependencies = {},
@@ -137,12 +140,13 @@ export async function createPointInTimeDocumentServiceCore(
 		},
 		extLogger,
 		clientIsSummarizer,
+		requestHeaders,
 	);
 
 	const versionManager = await (
 		dependencies.createVersionManager ??
 		(async (url, versionLogger, epochTracker) =>
-			createVersionManager(url, versionLogger, epochTracker, getStorageToken))
+			createVersionManager(url, versionLogger, epochTracker, getStorageToken, requestHeaders))
 	)(odspResolvedUrl, extLogger, cacheAndTracker.epochTracker);
 	const baseResult = await versionManager.findBaseForSeq(targetSequenceNumber);
 	if (baseResult.kind === "noBaseVersion") {