@fluidframework/odsp-driver 2.111.0 → 2.112.0

package/src/odspVersionManager/odspFileVersionFetcher.ts

@@ -0,0 +1,138 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * An {@link IOdspFileVersionFetcher} backed by the ODSP REST APIs:
+ * - 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.
+ */
+
+import type {
+	IOdspUrlParts,
+	InstrumentedStorageTokenFetcher,
+} from "@fluidframework/odsp-driver-definitions/internal";
+import type { TelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
+
+import { currentReadVersion, parseCompactSnapshotResponse } from "../compactSnapshotParser.js";
+import type { IOdspSnapshot } from "../contracts.js";
+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 type { OdspFileVersionRef, IOdspFileVersionFetcher } from "./odspVersionManager.js";
+
+/**
+ * Raw shape of a OneDrive/SharePoint driveItem version (an entry in the `/versions` response).
+ * @see https://learn.microsoft.com/en-us/onedrive/developer/rest-api/resources/driveitemversion
+ */
+interface IDriveItemVersion {
+	/** The version's label, e.g. "42.0". */
+	readonly id: string;
+	readonly lastModifiedDateTime: string;
+}
+
+/** A single page of the driveItem `/versions` response. */
+interface IDriveItemVersionsPage {
+	readonly value?: IDriveItemVersion[];
+	/** Absolute URL of the next page, present only while more versions remain. */
+	readonly "@odata.nextLink"?: string;
+}
+
+/**
+ * Inputs needed to make authenticated requests against a specific ODSP file.
+ */
+export interface OdspFileVersionFetcherProps {
+	readonly urlParts: IOdspUrlParts;
+	readonly getAuthHeader: InstrumentedStorageTokenFetcher;
+	readonly epochTracker: EpochTracker;
+	readonly logger: TelemetryLoggerExt;
+}
+
+/**
+ * Create an {@link IOdspFileVersionFetcher} that talks to a specific ODSP file.
+ */
+export function createOdspFileVersionFetcher(
+	props: OdspFileVersionFetcherProps,
+): IOdspFileVersionFetcher {
+	const { urlParts, getAuthHeader, epochTracker, logger } = props;
+	const { siteUrl, driveId, itemId } = urlParts;
+
+	const listFileVersions = async (): Promise<OdspFileVersionRef[]> =>
+		getWithRetryForTokenRefresh(async (options) => {
+			const method = "GET";
+			const versions: OdspFileVersionRef[] = [];
+			// The file's version history (distinct from the driver's snapshot list), from the same API
+			// root as the snapshot call so consumer (ODC) and enterprise (SPO) hosts are handled alike.
+			// A long history is paged, so follow `@odata.nextLink` until it is absent; otherwise a base
+			// version beyond the first page would be missed and wrongly reported as "no base version".
+			let url = `${getApiRoot(new URL(siteUrl))}/drives/${driveId}/items/${itemId}/versions`;
+			do {
+				const token = await getAuthHeader(
+					{ ...options, request: { url, method } },
+					"FileVersions",
+				);
+				const headers = getHeadersWithAuth(token);
+				const response = await epochTracker.fetchAndParseAsJSON<{
+					value?: IDriveItemVersion[];
+				}>(url, { method, headers }, "versions");
+				const page = response.content as IDriveItemVersionsPage;
+				// The API returns versions newest-first.
+				for (const version of page.value ?? []) {
+					versions.push({
+						versionId: version.id,
+						lastModifiedDateTime: version.lastModifiedDateTime,
+					});
+				}
+				url = page["@odata.nextLink"] ?? "";
+			} while (url);
+			return versions;
+		});
+
+	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.
+			const url = `${getApiRoot(new URL(siteUrl))}/drives/${driveId}/items/${itemId}/versions/${encodeURIComponent(
+				versionId,
+			)}/opStream/snapshots/trees/latest?blobs=2`;
+			const method = "GET";
+			const token = await getAuthHeader(
+				{ ...options, request: { url, method } },
+				"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.
+			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") ?? "";
+			let sequenceNumber: number | undefined;
+			if (contentType.includes("application/json")) {
+				// JSON framing: read it with the driver's JSON snapshot parser.
+				const snapshotJson = (await response.content.json()) as IOdspSnapshot;
+				sequenceNumber =
+					convertOdspSnapshotToSnapshotTreeAndBlobs(snapshotJson).sequenceNumber;
+			} else {
+				// 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;
+			}
+			// 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`);
+			}
+			return sequenceNumber;
+		});
+
+	return { listFileVersions, resolveSequenceNumber };
+}

package/src/odspVersionManager/odspVersionManager.ts

@@ -0,0 +1,170 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Selects the ODSP file version whose snapshot sits at or before a target Fluid sequence number —
+ * the base to load or replay from when materializing a document at a point in time.
+ *
+ * The selection logic depends on an injected {@link IOdspFileVersionFetcher}, so it is independent of
+ * how versions are enumerated and resolved (real ODSP, a test double, or an alternative backend).
+ */
+
+import {
+	createOdspFileVersionFetcher,
+	type OdspFileVersionFetcherProps,
+} 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;
+}
+
+/**
+ * An ODSP file version together with its resolved Fluid sequence number.
+ */
+export interface ResolvedVersion extends OdspFileVersionRef {
+	/**
+	 * The Fluid sequence number the version's snapshot represents.
+	 */
+	readonly sequenceNumber: number;
+}
+
+/**
+ * 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.
+ */
+export type BaseForSeq =
+	| {
+			/** A recoverable version with `sequenceNumber <= target` was found. */
+			readonly kind: "found";
+			readonly base: ResolvedVersion;
+	  }
+	| {
+			/** No recoverable version has `sequenceNumber <= target` (target predates retained history). */
+			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.
+ */
+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.
+	 */
+	findBaseForSeq(target: number): Promise<BaseForSeq>;
+}
+
+/**
+ * Default {@link IOdspVersionManager}. Caches the version list and resolved sequence numbers. The
+ * resolution strategy (eager, newest-to-oldest, stopping at the first usable base) is hidden behind
+ * {@link findBaseForSeq} and can change without affecting callers.
+ */
+export class OdspVersionManager implements IOdspVersionManager {
+	private versionsCache: Promise<OdspFileVersionRef[]> | undefined;
+	private readonly seqByVersion = new Map<string, Promise<number>>();
+
+	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();
+		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);
+			oldestResolvedSeq =
+				oldestResolvedSeq === undefined
+					? sequenceNumber
+					: Math.min(oldestResolvedSeq, sequenceNumber);
+			if (sequenceNumber <= target) {
+				return { kind: "found", base: { ...version, sequenceNumber } };
+			}
+		}
+		return { kind: "noBaseVersion", oldestResolvedSeq };
+	}
+
+	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
+		// preserved by Promise.all regardless of completion order.
+		return Promise.all(
+			versions.map(async (version) => ({
+				...version,
+				sequenceNumber: 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> {
+		// 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;
+	}
+}
+
+/**
+ * Create an {@link IOdspVersionManager} for a specific ODSP file, wired to the real ODSP REST APIs.
+ */
+export function createOdspVersionManager(
+	props: OdspFileVersionFetcherProps,
+): IOdspVersionManager {
+	return new OdspVersionManager(createOdspFileVersionFetcher(props));
+}

package/src/packageVersion.ts

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