@fluidframework/odsp-driver 2.113.1 → 2.115.0

package/src/odspVersionManager/odspFileVersionFetcher.ts

@@ -8,8 +8,12 @@
  * - GET /_api/v2.1/.../versions -- enumerate the file's versions.
  * - GET /_api/v2.1/.../versions/{label}/opStream/snapshots/trees/latest?blobs=2 -- fetch a version's
  *   snapshot and read its sequence number, parsed with the driver's snapshot parser.
+ * - GET /_api/v2.1/.../[versions/{label}/]opStream/snapshots/trees/latest?blobs=0 -- read a version's
+ *   or the live document's ODSP epoch (`x-fluid-epoch`) to compare their lineage.
  */
 
+import { NonRetryableError } from "@fluidframework/driver-utils/internal";
+import { OdspErrorTypes } from "@fluidframework/odsp-driver-definitions/internal";
 import type {
 	IOdspUrlParts,
 	InstrumentedStorageTokenFetcher,
@@ -22,9 +26,50 @@ import type { EpochTracker } from "../epochTracker.js";
 import { getHeadersWithAuth } from "../getUrlAndHeadersWithAuth.js";
 import { convertOdspSnapshotToSnapshotTreeAndBlobs } from "../odspSnapshotParser.js";
 import { getApiRoot } from "../odspUrlHelper.js";
-import { getWithRetryForTokenRefresh } from "../odspUtils.js";
+import { fetchArray, getWithRetryForTokenRefresh } from "../odspUtils.js";
+import { pkgVersion as driverVersion } from "../packageVersion.js";
 
-import type { OdspFileVersionRef, IOdspFileVersionFetcher } from "./odspVersionManager.js";
+/**
+ * A single ODSP file version, as listed by the file's version history.
+ */
+export interface OdspFileVersionRef {
+	/**
+	 * The version's label (e.g. `"42.0"`), used to address the version when fetching it.
+	 */
+	readonly versionId: string;
+	/**
+	 * Last-modified timestamp of this version, ISO-8601.
+	 */
+	readonly lastModifiedDateTime: string;
+}
+
+/**
+ * Provides a file's versions and resolves each version's Fluid sequence number. Injected into
+ * the version manager so the selection logic does not depend on how versions are fetched.
+ */
+export interface IOdspFileVersionFetcher {
+	/**
+	 * Enumerate the file's versions, newest-first.
+	 */
+	listFileVersions(): Promise<OdspFileVersionRef[]>;
+	/**
+	 * Resolve a single version's Fluid sequence number. Throws on failure rather than returning a
+	 * wrong value.
+	 */
+	resolveSequenceNumber(versionId: string): Promise<number>;
+	/**
+	 * Read the live document's current ODSP epoch (`x-fluid-epoch`), or `undefined`. Epoch identifies
+	 * the file's binary lineage and changes on a version restore or download-then-reupload; compared
+	 * with {@link IOdspFileVersionFetcher.getRecoverableVersionEpoch} to confirm a base is on the live
+	 * document's lineage.
+	 */
+	getLiveDocumentEpoch(): Promise<string | undefined>;
+	/**
+	 * Read the ODSP epoch of a specific file version, or `undefined`. See
+	 * {@link IOdspFileVersionFetcher.getLiveDocumentEpoch}.
+	 */
+	getRecoverableVersionEpoch(versionId: string): Promise<string | undefined>;
+}
 
 /**
  * Raw shape of a OneDrive/SharePoint driveItem version (an entry in the `/versions` response).
@@ -95,10 +140,8 @@ export function createOdspFileVersionFetcher(
 
 	const resolveSequenceNumber = async (versionId: string): Promise<number> =>
 		getWithRetryForTokenRefresh(async (options) => {
-			// A file version's sequence number lives inside that version's snapshot, so fetch the snapshot
-			// from the version-scoped endpoint. `blobs=2` inlines blob contents so the `.protocol/attributes`
-			// blob (which carries the sequence number) is included; `deltas=1` is intentionally omitted, as
-			// it would bundle the op stream and its op-level sequence numbers.
+			// The sequence number lives in the version snapshot's `.protocol/attributes` blob, so fetch the
+			// version-scoped snapshot with `blobs=2` to inline it. No op stream needed.
 			const url = `${getApiRoot(new URL(siteUrl))}/drives/${driveId}/items/${itemId}/versions/${encodeURIComponent(
 				versionId,
 			)}/opStream/snapshots/trees/latest?blobs=2`;
@@ -108,10 +151,8 @@ export function createOdspFileVersionFetcher(
 				"FileVersionSnapshot",
 			);
 			const headers = getHeadersWithAuth(token);
-			// The server can return the snapshot in one of two equivalent framings: verbose JSON, or
-			// "ms-fluid" — ODSP's compact binary encoding of the same snapshot. Advertise both, and pin the
-			// binary format version (as the driver's own snapshot fetch does) so the server cannot hand back
-			// a binary version this code's parser does not understand.
+			// The snapshot comes back as JSON or "ms-fluid" (ODSP's compact binary form). Accept both and
+			// pin the binary version (as the driver's snapshot fetch does) so the parser can read it.
 			headers.accept = `application/json, application/ms-fluid; v=${currentReadVersion}`;
 			const response = await epochTracker.fetch(url, { method, headers }, "treesLatest");
 			const contentType = response.headers.get("content-type") ?? "";
@@ -121,18 +162,72 @@ export function createOdspFileVersionFetcher(
 				const snapshotJson = (await response.content.json()) as IOdspSnapshot;
 				sequenceNumber =
 					convertOdspSnapshotToSnapshotTreeAndBlobs(snapshotJson).sequenceNumber;
-			} else {
+			} else if (contentType.includes("application/ms-fluid")) {
 				// ms-fluid framing: the compact binary form; read it with the driver's compact-snapshot parser.
 				const bytes = new Uint8Array(await response.content.arrayBuffer());
 				sequenceNumber = parseCompactSnapshotResponse(bytes, logger).sequenceNumber;
+			} else {
+				// Neither framing (e.g. an HTML error page). Throw the driver's typed bad-response error
+				// (like fetchSnapshot.ts): canRetry=false stops the loader re-driving, while the
+				// incorrectServerResponse errorType still earns one wire-retry from getWithRetryForTokenRefresh.
+				throw new NonRetryableError(
+					`ODSP file version ${versionId} snapshot returned an unexpected content-type`,
+					OdspErrorTypes.incorrectServerResponse,
+					{ driverVersion, contentType, accept: headers.accept },
+				);
 			}
-			// A version's snapshot must carry a sequence number; a missing one is surfaced as an error
-			// naming the version, rather than returning a wrong value.
-			if (sequenceNumber === undefined) {
-				throw new Error(`ODSP file version ${versionId} snapshot is missing a sequenceNumber`);
+			// The sequence number must be a non-negative integer; a missing or malformed one throws the same
+			// typed error as above rather than feeding a wrong value into base selection.
+			if (
+				!(
+					typeof sequenceNumber === "number" &&
+					Number.isInteger(sequenceNumber) &&
+					sequenceNumber >= 0
+				)
+			) {
+				throw new NonRetryableError(
+					`ODSP file version ${versionId} snapshot has a missing or invalid sequenceNumber (${String(sequenceNumber)})`,
+					OdspErrorTypes.incorrectServerResponse,
+					{ driverVersion, contentType, accept: headers.accept },
+				);
 			}
 			return sequenceNumber;
 		});
 
-	return { listFileVersions, resolveSequenceNumber };
+	const itemRoot = `${getApiRoot(new URL(siteUrl))}/drives/${driveId}/items/${itemId}`;
+
+	// Reads the `x-fluid-epoch` header from `url`. Deliberately uses the raw fetch helper instead of
+	// `epochTracker.fetch`: the whole point is to COMPARE the base version's epoch against the live
+	// document's epoch, but the shared EpochTracker pins to the first epoch it sees and throws on the
+	// second (divergent) read - so it could never yield two epochs to compare. `fetchArray` also lets
+	// the body (JSON or ms-fluid binary) be consumed and discarded; only the header is needed.
+	const readEpoch = async (url: string, scenarioName: string): Promise<string | undefined> =>
+		getWithRetryForTokenRefresh(async (options) => {
+			const method = "GET";
+			const token = await getAuthHeader(
+				{ ...options, request: { url, method } },
+				scenarioName,
+			);
+			const headers = getHeadersWithAuth(token);
+			const response = await fetchArray(url, { method, headers });
+			return response.headers.get("x-fluid-epoch") ?? undefined;
+		});
+
+	const getLiveDocumentEpoch = async (): Promise<string | undefined> =>
+		// The (unversioned) live snapshot endpoint is a current-file read, so its epoch is the live
+		// document's epoch. `blobs=0` keeps the response to the tree metadata.
+		readEpoch(`${itemRoot}/opStream/snapshots/trees/latest?blobs=0`, "LiveEpoch");
+
+	const getRecoverableVersionEpoch = async (versionId: string): Promise<string | undefined> =>
+		readEpoch(
+			`${itemRoot}/versions/${encodeURIComponent(versionId)}/opStream/snapshots/trees/latest?blobs=0`,
+			"FileVersionEpoch",
+		);
+
+	return {
+		listFileVersions,
+		resolveSequenceNumber,
+		getLiveDocumentEpoch,
+		getRecoverableVersionEpoch,
+	};
 }

package/src/odspVersionManager/odspVersionManager.ts

@@ -11,24 +11,23 @@
  * how versions are enumerated and resolved (real ODSP, a test double, or an alternative backend).
  */
 
+import { PromiseCache } from "@fluidframework/core-utils/internal";
+import { NonRetryableError } from "@fluidframework/driver-utils/internal";
+import { OdspErrorTypes } from "@fluidframework/odsp-driver-definitions/internal";
+
+import { pkgVersion as driverVersion } from "../packageVersion.js";
+
 import {
 	createOdspFileVersionFetcher,
 	type OdspFileVersionFetcherProps,
+	type OdspFileVersionRef,
+	type IOdspFileVersionFetcher,
 } from "./odspFileVersionFetcher.js";
 
-/**
- * A single ODSP file version, as listed by the file's version history.
- */
-export interface OdspFileVersionRef {
-	/**
-	 * The version's label (e.g. `"42.0"`), used to address the version when fetching it.
-	 */
-	readonly versionId: string;
-	/**
-	 * Last-modified timestamp of this version, ISO-8601.
-	 */
-	readonly lastModifiedDateTime: string;
-}
+// Re-exported so consumers (and this module's own index) can keep importing these fetcher-owned
+// types from the version manager. The definitions live in odspFileVersionFetcher.ts so that file
+// does not depend on this one, avoiding a circular dependency between the two modules.
+export type { OdspFileVersionRef, IOdspFileVersionFetcher } from "./odspFileVersionFetcher.js";
 
 /**
  * An ODSP file version together with its resolved Fluid sequence number.
@@ -44,9 +43,11 @@ export interface ResolvedVersion extends OdspFileVersionRef {
  * Result of resolving the base version for a target sequence number.
  *
  * @remarks
- * There is intentionally no `targetIsLive` case: when the target is at/after the newest recoverable
- * version, the greatest version with `seq <= target` IS that newest version, so it is a normal
- * `found`. A consumer may separately choose to load the live file when the target is near the head.
+ * The tip (newest) version is excluded from base selection, so when the target is at or after the head
+ * the base is the newest *sealed* version with `seq <= target` (a normal `found`); if the file's only
+ * version is the tip, the result is `noBaseVersion`. The wired consumer surfaces `noBaseVersion` as a
+ * `UsageError`; loading the live file for a near-head target is a possible future consumer choice, not
+ * current behavior.
  */
 export type BaseForSeq =
 	| {
@@ -55,28 +56,15 @@ export type BaseForSeq =
 			readonly base: ResolvedVersion;
 	  }
 	| {
-			/** No recoverable version has `sequenceNumber <= target` (target predates retained history). */
+			/**
+			 * No sealed version has `sequenceNumber <= target` — the target predates retained history, or
+			 * the only version is the excluded tip.
+			 */
 			readonly kind: "noBaseVersion";
 			/** The oldest sequence number that was resolved while searching, if any. */
 			readonly oldestResolvedSeq?: number;
 	  };
 
-/**
- * Provides a file's versions and resolves each version's Fluid sequence number. Injected into
- * the version manager so the selection logic does not depend on how versions are fetched.
- */
-export interface IOdspFileVersionFetcher {
-	/**
-	 * Enumerate the file's versions, newest-first.
-	 */
-	listFileVersions(): Promise<OdspFileVersionRef[]>;
-	/**
-	 * Resolve a single version's Fluid sequence number. Throws on failure rather than returning a
-	 * wrong value.
-	 */
-	resolveSequenceNumber(versionId: string): Promise<number>;
-}
-
 /**
  * Selects the file version to use as the base for loading or replaying to a target sequence number.
  */
@@ -84,37 +72,44 @@ export interface IOdspVersionManager {
 	/**
 	 * Given a target sequence number, return the closest version at or before it (`found`), or
 	 * `noBaseVersion` if the target predates the oldest retained version.
+	 *
+	 * @remarks
+	 * A `found` base is guaranteed to share the live document's ODSP epoch (lineage): before returning
+	 * it, the chosen base's epoch is compared with the live document's, and a mismatch throws a non-retryable error
+	 * rather than returning a base that cannot be replayed. Op availability is enforced separately and
+	 * lazily as the loader reads the bridging ops.
 	 */
 	findBaseForSeq(target: number): Promise<BaseForSeq>;
 }
 
 /**
- * Default {@link IOdspVersionManager}. Caches the version list and resolved sequence numbers. The
+ * Default {@link IOdspVersionManager}. Caches resolved sequence numbers (which never change); the version
+ * list is re-enumerated on each query rather than cached, since new versions are cut over time. The
  * resolution strategy (eager, newest-to-oldest, stopping at the first usable base) is hidden behind
  * {@link findBaseForSeq} and can change without affecting callers.
  */
+// Exported only so the same-package tests can construct it with a fake IOdspFileVersionFetcher.
+// Deliberately kept out of the folder barrel and the package public index, so it is not public API.
 export class OdspVersionManager implements IOdspVersionManager {
-	private versionsCache: Promise<OdspFileVersionRef[]> | undefined;
-	private readonly seqByVersion = new Map<string, Promise<number>>();
+	// Sealed versions' sequence numbers, memoized so each is resolved at most once per manager instance
+	// (a sealed version's number is fixed once the version exists).
+	private readonly seqCache = new PromiseCache<string, number>();
+	// Sealed versions' ODSP epochs, memoized like their sequence numbers. The live document's epoch is NOT
+	// cached — it can change (restore/reupload), so validateLineageEpoch always reads it fresh.
+	private readonly epochCache = new PromiseCache<string, string | undefined>();
 
 	public constructor(private readonly fetcher: IOdspFileVersionFetcher) {}
 
-	public refresh(): void {
-		this.versionsCache = undefined;
-		this.seqByVersion.clear();
-	}
-
 	public async findBaseForSeq(target: number): Promise<BaseForSeq> {
-		// Recoverable base candidates = every version except the tip (index 0 ≈ the live document).
-		const versions = await this.getVersions();
+		// Re-enumerate the list each call (it changes as new versions are cut).
+		const versions = await this.fetcher.listFileVersions();
+
+		// Start past the tip (index 0): the newest version's sequence number can still advance until a newer
+		// version is cut, so it is treated as the live head rather than a stable base. Scan the remaining
+		// (sealed) versions newest-first and return the first with sequence number <= target — the closest
+		// base — or noBaseVersion, reporting the oldest sequence number seen.
 		const candidates = versions.slice(1);
 
-		// Versions are listed newest-first, and version order is expected to track sequence number, so
-		// the first candidate whose seq is at or before the target is taken as the closest base. Because
-		// any base at or before the target replays forward to the same state, this early stop is an
-		// optimization, not a correctness requirement: if version order and sequence order ever diverge,
-		// a base that is valid but not strictly the closest may be chosen.
-		// Scanning newest-first also yields the newest of versions sharing a sequence number (dedup).
 		let oldestResolvedSeq: number | undefined;
 		for (const version of candidates) {
 			const sequenceNumber = await this.resolveSeq(version.versionId);
@@ -123,40 +118,83 @@ export class OdspVersionManager implements IOdspVersionManager {
 					? sequenceNumber
 					: Math.min(oldestResolvedSeq, sequenceNumber);
 			if (sequenceNumber <= target) {
-				return { kind: "found", base: { ...version, sequenceNumber } };
+				const base = { ...version, sequenceNumber };
+				// Confirm the chosen base shares the live document's lineage before handing it back
+				await this.validateLineageEpoch(base);
+				return { kind: "found", base };
 			}
 		}
 		return { kind: "noBaseVersion", oldestResolvedSeq };
 	}
 
+	private async validateLineageEpoch(base: ResolvedVersion): Promise<void> {
+		// The live document's epoch can change (a restore or download-and-reupload bumps it), so it is
+		// always read fresh. A numbered version's snapshot is immutable, so its epoch never changes and
+		// is cached per versionId (see resolveVersionEpoch).
+		const [liveEpoch, baseEpoch] = await Promise.all([
+			this.fetcher.getLiveDocumentEpoch(),
+			this.resolveVersionEpoch(base.versionId),
+		]);
+		if (liveEpoch === undefined || baseEpoch === undefined) {
+			throw new NonRetryableError(
+				`Cannot verify that ODSP file version ${base.versionId} shares the live document's ` +
+					`lineage: the storage response is missing an epoch (base epoch: ${baseEpoch ?? "unknown"}, ` +
+					`live epoch: ${liveEpoch ?? "unknown"}).`,
+				OdspErrorTypes.incorrectServerResponse,
+				{
+					driverVersion,
+					serverEpoch: liveEpoch,
+					clientEpoch: baseEpoch,
+				},
+			);
+		}
+		if (liveEpoch !== baseEpoch) {
+			throw new NonRetryableError(
+				`ODSP file version ${base.versionId} is on epoch "${baseEpoch}" but the live document is ` +
+					`on epoch "${liveEpoch}". A binary file change (e.g. a version restore or ` +
+					`download-and-reupload) renumbered the op stream, so ops cannot be replayed from this ` +
+					`base onto the live document.`,
+				OdspErrorTypes.fileOverwrittenInStorage,
+				{
+					driverVersion,
+					serverEpoch: liveEpoch,
+					clientEpoch: baseEpoch,
+				},
+			);
+		}
+	}
+
 	public async listVersions(): Promise<ResolvedVersion[]> {
-		const versions = await this.getVersions();
-		// Resolution order does not matter here, so resolve concurrently; the newest-first array order is
+		const versions = await this.fetcher.listFileVersions();
+		// Resolution order does not matter, so resolve concurrently; the newest-first array order is
 		// preserved by Promise.all regardless of completion order.
 		return Promise.all(
-			versions.map(async (version) => ({
+			versions.map(async (version, index) => ({
 				...version,
-				sequenceNumber: await this.resolveSeq(version.versionId),
+				// Resolve the tip (index 0) fresh each call, since its sequence number can still change;
+				// sealed versions come from the cache.
+				sequenceNumber:
+					index === 0
+						? await this.fetcher.resolveSequenceNumber(version.versionId)
+						: await this.resolveSeq(version.versionId),
 			})),
 		);
 	}
 
-	private async getVersions(): Promise<OdspFileVersionRef[]> {
-		// Cache the pending promise, not the awaited value, so concurrent callers share one fetch and a
-		// refresh() that runs while the fetch is in flight is not overwritten when the fetch settles.
-		this.versionsCache ??= this.fetcher.listFileVersions();
-		return this.versionsCache;
+	private async resolveSeq(versionId: string): Promise<number> {
+		// Cached indefinitely (a sealed version's number is fixed); concurrent calls coalesce and a failed
+		// resolution is evicted so a later call retries.
+		return this.seqCache.addOrGet(versionId, async () =>
+			this.fetcher.resolveSequenceNumber(versionId),
+		);
 	}
 
-	private async resolveSeq(versionId: string): Promise<number> {
-		// Cache the pending promise (a version's sequence number never changes) so concurrent callers
-		// coalesce and a refresh() is not clobbered by a fetch that was already in flight.
-		let pending = this.seqByVersion.get(versionId);
-		if (pending === undefined) {
-			pending = this.fetcher.resolveSequenceNumber(versionId);
-			this.seqByVersion.set(versionId, pending);
-		}
-		return pending;
+	private async resolveVersionEpoch(versionId: string): Promise<string | undefined> {
+		// Cached like resolveSeq (a sealed version's epoch is fixed). The live document's epoch is read
+		// fresh instead (see validateLineageEpoch).
+		return this.epochCache.addOrGet(versionId, async () =>
+			this.fetcher.getRecoverableVersionEpoch(versionId),
+		);
 	}
 }
 

package/src/packageVersion.ts

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

package/src/pointInTimeDriver/odspPointInTimeDocumentService.ts

@@ -30,6 +30,11 @@ import type {
  * still catches up from the snapshot's sequence number through delta storage, which is exactly the
  * bounded replay we want. As a result no live delta-stream connection is ever established.
  *
+ * Op availability is enforced by the delta storage stack itself: it validates that fetched batches
+ * are contiguous from the requested start, keeps requesting until the bounded range is fully
+ * delivered, and fails the fetch if the ops never materialize. So a stream that completes has
+ * necessarily served the whole bridge, and no additional checks are needed here.
+ *
  * @internal
  */
 export class OdspPointInTimeDocumentService
@@ -67,15 +72,14 @@ export class OdspPointInTimeDocumentService
 		// The exclusive upper bound needed to include the target op itself.
 		const boundedTo = this.targetSequenceNumber + 1;
 		return {
-			fetchMessages: (from, to, abortSignal, cachedOnly, fetchReason) => {
-				return liveDeltaStorage.fetchMessages(
+			fetchMessages: (from, to, abortSignal, cachedOnly, fetchReason) =>
+				liveDeltaStorage.fetchMessages(
 					from,
 					to === undefined ? boundedTo : Math.min(to, boundedTo),
 					abortSignal,
 					cachedOnly,
 					fetchReason,
-				);
-			},
+				),
 		};
 	}