@fluidframework/odsp-driver 2.113.1 → 2.115.0

package/src/pointInTimeDriver/odspPointInTimeDocumentServiceFactory.ts

@@ -6,18 +6,24 @@
 import type { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import type {
 	IDocumentService,
+	IDocumentServiceFactory,
 	IPersistedCache,
 	IResolvedUrl,
 } from "@fluidframework/driver-definitions/internal";
 import type {
 	HostStoragePolicy,
+	IOdspResolvedUrl,
 	IOdspUrlParts,
 	OdspResourceTokenFetchOptions,
 	TokenFetcher,
 } from "@fluidframework/odsp-driver-definitions/internal";
-import { UsageError, createChildLogger } from "@fluidframework/telemetry-utils/internal";
+import {
+	UsageError,
+	createChildLogger,
+	type TelemetryLoggerExt,
+} from "@fluidframework/telemetry-utils/internal";
 
-import { createOdspCacheAndTracker } from "../epochTracker.js";
+import { createOdspCacheAndTracker, type EpochTracker } from "../epochTracker.js";
 import { NonPersistentCache } from "../odspCache.js";
 import { OdspDocumentServiceFactoryCore } from "../odspDocumentServiceFactoryCore.js";
 import { OdspDriverUrlResolver } from "../odspDriverUrlResolver.js";
@@ -34,24 +40,49 @@ import {
 import { OdspPointInTimeDocumentService } from "./odspPointInTimeDocumentService.js";
 
 /**
- * ODSP document service factory that additionally supports point-in-time (sequence-number-based)
- * loading.
+ * An ODSP document service factory that supports point-in-time (sequence-number-based) loading.
  *
  * @remarks
- * This extends {@link OdspDocumentServiceFactoryCore} with the ability to materialize a read-only
- * document service at a requested Fluid sequence number. The loader detects this capability via the
- * presence of {@link OdspPointInTimeDocumentServiceFactory.createPointInTimeDocumentService}, so
- * hosts that want to load a container to a target sequence number must construct this factory
- * (rather than the legacy `OdspDocumentServiceFactory`) and pass it to the loader.
+ * The loader detects this capability structurally, so hosts can pass this factory directly to
+ * `loadContainerToSequenceNumber`.
  *
- * @internal
+ * @legacy @alpha
  */
-export class OdspPointInTimeDocumentServiceFactory extends OdspDocumentServiceFactoryCore {
+export interface IPointInTimeDocumentServiceFactory extends IDocumentServiceFactory {
+	/**
+	 * Creates a document service that materializes the document at the requested sequence number.
+	 *
+	 * @param resolvedUrl - The resolved ODSP document URL.
+	 * @param targetSequenceNumber - The sequence number at which to materialize the document.
+	 * @param logger - Optional telemetry logger.
+	 * @param clientIsSummarizer - Whether the requesting client is a summarizer.
+	 * @returns A read-only document service materialized at the requested sequence number.
+	 */
+	createPointInTimeDocumentService(
+		resolvedUrl: IResolvedUrl,
+		targetSequenceNumber: number,
+		logger?: ITelemetryBaseLogger,
+		clientIsSummarizer?: boolean,
+	): Promise<IDocumentService>;
+}
+
+class OdspPointInTimeDocumentServiceFactory
+	extends OdspDocumentServiceFactoryCore
+	implements IPointInTimeDocumentServiceFactory
+{
 	/**
 	 * The storage token fetcher, captured here because the base class keeps it private.
 	 */
 	private readonly getStorageTokenForVersions: TokenFetcher<OdspResourceTokenFetchOptions>;
 
+	/**
+	 * Creates a point-in-time-capable ODSP document service factory.
+	 *
+	 * @param getStorageToken - Fetches storage access tokens.
+	 * @param getWebsocketToken - Fetches websocket access tokens, or `undefined` when unavailable.
+	 * @param persistedCache - Optional persisted ODSP cache.
+	 * @param hostPolicy - Optional host storage policy.
+	 */
 	constructor(
 		getStorageToken: TokenFetcher<OdspResourceTokenFetchOptions>,
 		getWebsocketToken: TokenFetcher<OdspResourceTokenFetchOptions> | undefined,
@@ -66,6 +97,12 @@ export class OdspPointInTimeDocumentServiceFactory extends OdspDocumentServiceFa
 	 * Creates a document service that reads its snapshot from the closest file version at or before
 	 * the target and its deltas from the live document, materializing a requested sequence number
 	 * through replay.
+	 *
+	 * @param resolvedUrl - The resolved ODSP document URL.
+	 * @param targetSequenceNumber - The sequence number at which to materialize the document.
+	 * @param logger - Optional telemetry logger.
+	 * @param clientIsSummarizer - Whether the requesting client is a summarizer.
+	 * @returns A read-only document service materialized at the requested sequence number.
 	 */
 	public async createPointInTimeDocumentService(
 		resolvedUrl: IResolvedUrl,
@@ -73,11 +110,37 @@ export class OdspPointInTimeDocumentServiceFactory extends OdspDocumentServiceFa
 		logger?: ITelemetryBaseLogger,
 		clientIsSummarizer?: boolean,
 	): Promise<IDocumentService> {
-		const versionManager = await this.createVersionManager(
-			resolvedUrl,
-			logger,
+		const odspLogger = createOdspLogger(logger);
+		const extLogger = createChildLogger({ logger: odspLogger });
+		const odspResolvedUrl = getOdspResolvedUrl(resolvedUrl);
+
+		// Build ONE cache-and-tracker and thread its EpochTracker through every read this method
+		// makes: the version-history reads that pick the base, the recoverable base snapshot, and the
+		// live op stream. This shared tracker IS the lineage guard.
+		//
+		// ODSP stamps each response with the file's epoch; an EpochTracker instance pins itself to the
+		// first epoch it sees and throws on any later divergence (see setEpoch / checkForEpochError in
+		// epochTracker.ts).
+		//
+		// A fresh NonPersistentCache keeps this read-only historical load isolated from the factory's
+		// shared cache, so a base file version's snapshot can never leak into a normal live load.
+		const cacheAndTracker = createOdspCacheAndTracker(
+			this.persistedCache,
+			new NonPersistentCache(),
+			{
+				resolvedUrl: odspResolvedUrl,
+				docId: odspResolvedUrl.hashedDocumentId,
+				fileVersion: odspResolvedUrl.fileVersion,
+			},
+			extLogger,
 			clientIsSummarizer,
 		);
+
+		const versionManager = this.createVersionManager(
+			odspResolvedUrl,
+			extLogger,
+			cacheAndTracker.epochTracker,
+		);
 		const baseResult = await versionManager.findBaseForSeq(targetSequenceNumber);
 		if (baseResult.kind === "noBaseVersion") {
 			const oldestResolvedSequenceDetail =
@@ -93,14 +156,18 @@ export class OdspPointInTimeDocumentServiceFactory extends OdspDocumentServiceFa
 			resolvedUrl,
 			baseResult.base.versionId,
 		);
-		const recoverableDocumentService = await this.createDocumentService(
+		// Both services are created via createDocumentServiceCore with the shared cacheAndTracker, so
+		// their reads validate against the same epoch - see the lineage-guard note above.
+		const recoverableDocumentService = await this.createDocumentServiceCore(
 			recoverableResolvedUrl,
-			logger,
+			odspLogger,
+			cacheAndTracker,
 			clientIsSummarizer,
 		);
-		const liveDocumentService = await this.createDocumentService(
+		const liveDocumentService = await this.createDocumentServiceCore(
 			resolvedUrl,
-			logger,
+			odspLogger,
+			cacheAndTracker,
 			clientIsSummarizer,
 		);
 		return new OdspPointInTimeDocumentService(
@@ -116,49 +183,32 @@ export class OdspPointInTimeDocumentServiceFactory extends OdspDocumentServiceFa
 	 * versions and resolves the closest version at or before a target sequence number.
 	 *
 	 * @remarks
-	 * This wires up the plumbing the version manager needs to talk to ODSP: it resolves the URL to
-	 * its ODSP parts (site/drive/item), creates a scoped child logger, an epoch tracker (from a fresh
-	 * NonPersistentCache, since only the tracker is needed for consistency checks), and an
-	 * instrumented storage-token/auth-header fetcher. The resulting manager is used by
-	 * {@link OdspPointInTimeDocumentServiceFactory.createPointInTimeDocumentService} to pick the base
-	 * snapshot for point-in-time loading.
+	 * The caller passes in the shared {@link EpochTracker} so the version-history reads validate
+	 * against the same epoch as the recoverable and live document services - this is the lineage
+	 * guard used by `createPointInTimeDocumentService`.
+	 * The manager itself only needs the URL parts and an instrumented storage-token/auth-header
+	 * fetcher wired to that tracker.
 	 */
-	private async createVersionManager(
-		resolvedUrl: IResolvedUrl,
-		logger?: ITelemetryBaseLogger,
-		clientIsSummarizer?: boolean,
-	): Promise<IOdspVersionManager> {
-		const odspLogger = createOdspLogger(logger);
-		const extLogger = createChildLogger({ logger: odspLogger });
-		const odspResolvedUrl = getOdspResolvedUrl(resolvedUrl);
+	private createVersionManager(
+		odspResolvedUrl: IOdspResolvedUrl,
+		logger: TelemetryLoggerExt,
+		epochTracker: EpochTracker,
+	): IOdspVersionManager {
 		const urlParts: IOdspUrlParts = {
 			siteUrl: odspResolvedUrl.siteUrl,
 			driveId: odspResolvedUrl.driveId,
 			itemId: odspResolvedUrl.itemId,
 		};
-		// Only the epochTracker from the returned cacheAndTracker is used below, so a fresh
-		// NonPersistentCache is sufficient here.
-		const cacheAndTracker = createOdspCacheAndTracker(
-			this.persistedCache,
-			new NonPersistentCache(),
-			{
-				resolvedUrl: odspResolvedUrl,
-				docId: odspResolvedUrl.hashedDocumentId,
-				fileVersion: odspResolvedUrl.fileVersion,
-			},
-			extLogger,
-			clientIsSummarizer,
-		);
 		const getAuthHeader = toInstrumentedOdspStorageTokenFetcher(
-			extLogger,
+			logger,
 			urlParts,
 			this.getStorageTokenForVersions,
 		);
 		return createOdspVersionManager({
 			urlParts,
 			getAuthHeader,
-			epochTracker: cacheAndTracker.epochTracker,
-			logger: extLogger,
+			epochTracker,
+			logger,
 		});
 	}
 
@@ -183,3 +233,28 @@ export class OdspPointInTimeDocumentServiceFactory extends OdspDocumentServiceFa
 		});
 	}
 }
+
+/**
+ * Creates an ODSP document service factory that supports point-in-time loading.
+ *
+ * @param getStorageToken - Fetches storage access tokens.
+ * @param getWebsocketToken - Fetches websocket access tokens, or `undefined` when unavailable.
+ * @param persistedCache - Optional persisted ODSP cache.
+ * @param hostPolicy - Optional host storage policy.
+ * @returns An ODSP document service factory with point-in-time loading capability.
+ *
+ * @legacy @alpha
+ */
+export function getOdspPointInTimeDocumentServiceFactory(
+	getStorageToken: TokenFetcher<OdspResourceTokenFetchOptions>,
+	getWebsocketToken: TokenFetcher<OdspResourceTokenFetchOptions> | undefined,
+	persistedCache?: IPersistedCache,
+	hostPolicy?: HostStoragePolicy,
+): IPointInTimeDocumentServiceFactory {
+	return new OdspPointInTimeDocumentServiceFactory(
+		getStorageToken,
+		getWebsocketToken,
+		persistedCache,
+		hostPolicy,
+	);
+}