@fluidframework/odsp-driver 3.0.1 → 3.1.0

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.1";
+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") {

package/src/pointInTimeDriver/odspPointInTimeDocumentService.ts

@@ -4,16 +4,45 @@
  */
 
 import { TypedEventEmitter } from "@fluid-internal/client-utils";
-import type {
-	IClient,
-	IDocumentDeltaConnection,
-	IDocumentDeltaStorageService,
-	IDocumentService,
-	IDocumentServiceEvents,
-	IDocumentServicePolicies,
-	IDocumentStorageService,
-	IResolvedUrl,
+import {
+	FetchSource,
+	type IClient,
+	type IDocumentDeltaConnection,
+	type IDocumentDeltaStorageService,
+	type IDocumentService,
+	type IDocumentServiceEvents,
+	type IDocumentServicePolicies,
+	type IDocumentStorageService,
+	type IResolvedUrl,
+	type ISnapshot,
+	type ISnapshotFetchOptions,
+	type IVersion,
 } from "@fluidframework/driver-definitions/internal";
+import { DocumentStorageServiceProxy } from "@fluidframework/driver-utils/internal";
+
+/**
+ * Forces point-in-time snapshot reads to bypass caches while forwarding all other storage operations
+ * to the selected historical document service.
+ */
+class PointInTimeDocumentStorageService extends DocumentStorageServiceProxy {
+	public override async getSnapshot(
+		snapshotFetchOptions?: ISnapshotFetchOptions,
+	): Promise<ISnapshot> {
+		return super.getSnapshot({
+			...snapshotFetchOptions,
+			fetchSource: FetchSource.noCache,
+		});
+	}
+
+	public override async getVersions(
+		// eslint-disable-next-line @rushstack/no-new-null -- IDocumentStorageService is a legacy API that requires null.
+		versionId: string | null,
+		count: number,
+		scenarioName?: string,
+	): Promise<IVersion[]> {
+		return super.getVersions(versionId, count, scenarioName, FetchSource.noCache);
+	}
+}
 
 /**
  * A read-only document service that materializes a document at a target sequence number by combining
@@ -64,7 +93,8 @@ export class OdspPointInTimeDocumentService
 	}
 
 	public async connectToStorage(): Promise<IDocumentStorageService> {
-		return this.recoverableDocumentService.connectToStorage();
+		const storage = await this.recoverableDocumentService.connectToStorage();
+		return new PointInTimeDocumentStorageService(storage);
 	}
 
 	public async connectToDeltaStorage(): Promise<IDocumentDeltaStorageService> {

package/src/prefetchLatestSnapshot.ts

@@ -113,6 +113,9 @@ export async function prefetchLatestSnapshot(
 			odspLogger,
 			undefined,
 			controller,
+			undefined,
+			undefined,
+			odspDocumentServiceFactory?.requestHeaders,
 		);
 	};
 	const snapshotKey = createCacheSnapshotKey(odspResolvedUrl, useGroupIdsForSnapshotFetch);
@@ -150,6 +153,7 @@ export async function prefetchLatestSnapshot(
 				removeEntries,
 				loadingGroupIds,
 				enableRedeemFallback,
+				odspDocumentServiceFactory?.requestHeaders,
 			)
 				.then(async (value) => {
 					assert(!!snapshotEpoch, 0x585 /* prefetched snapshot should have a valid epoch */);

package/src/requestHeaders.ts

@@ -0,0 +1,56 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+const driverOwnedHeaderNames = new Set([
+	"authorization",
+	"content-type",
+	"x-fluid-epoch",
+	"x-http-method-override",
+	"x-requeststats",
+]);
+
+/**
+ * Creates an immutable snapshot of host-provided per-session headers after removing names owned by
+ * the ODSP driver. The factory, URL resolver, epoch tracker, and Socket.IO connection use the
+ * returned value so later host mutations cannot change an active document session or override
+ * authentication and protocol headers.
+ */
+export function copyRequestHeaders(
+	requestHeaders: Readonly<Record<string, string>> | undefined,
+): Readonly<Record<string, string>> | undefined {
+	if (requestHeaders === undefined || Object.keys(requestHeaders).length === 0) {
+		return undefined;
+	}
+	const copiedHeaders = Object.fromEntries(
+		Object.entries(requestHeaders).filter(
+			([name]) => !driverOwnedHeaderNames.has(name.toLowerCase()),
+		),
+	);
+	return Object.keys(copiedHeaders).length === 0 ? undefined : Object.freeze(copiedHeaders);
+}
+
+/**
+ * Adds sanitized host headers to one ODSP request. Request-specific headers are applied last, so
+ * driver-generated values win case-insensitive collisions. ODSP fetch paths use this helper for
+ * snapshot, delta, blob, share-link, file-link, and version requests; Socket.IO applies the copied
+ * headers separately as Node.js `extraHeaders`.
+ */
+export function mergeRequestHeaders(
+	hostHeaders: Readonly<Record<string, string>> | undefined,
+	requestHeaders: HeadersInit | undefined,
+): HeadersInit | undefined {
+	const safeHostHeaders = copyRequestHeaders(hostHeaders);
+	if (safeHostHeaders === undefined) {
+		return requestHeaders;
+	}
+
+	const merged = new Headers(safeHostHeaders);
+	if (requestHeaders !== undefined) {
+		for (const [key, value] of new Headers(requestHeaders)) {
+			merged.set(key, value);
+		}
+	}
+	return Object.fromEntries(merged);
+}

package/src/zipItDataRepresentationUtils.ts

@@ -541,7 +541,6 @@ export class NodeCore {
 
 		length = 0;
 		const input = buffer.buffer;
-		assert(input.byteOffset === 0, 0x3e8 /* code below assumes no offset */);
 
 		for (const el of stringsToResolve) {
 			for (let it = el.startPos; it < el.endPos; it++) {