@fluidframework/odsp-driver 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.224419

package/src/odspFluidFileLink.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { fromBase64ToUtf8, fromUtf8ToBase64 } from "@fluidframework/common-utils";
+import { fromBase64ToUtf8, fromUtf8ToBase64 } from "@fluid-internal/client-utils";
 import { OdspFluidDataStoreLocator } from "./contractsPublic";
 import { OdcFileSiteOrigin, OdcApiSiteOrigin } from "./constants";
 
@@ -22,120 +22,139 @@ const additionalContextParamName = "x";
  * Transforms given Fluid data store locator into string that can be embedded into url
  * @param locator - describes Fluid data store locator info to be encoded
  * @returns string representing encoded Fluid data store locator info
+ * @alpha
  */
 export function encodeOdspFluidDataStoreLocator(locator: OdspFluidDataStoreLocator): string {
-    const siteUrl = new URL(locator.siteUrl);
-    const sitePath = encodeURIComponent(siteUrl.pathname);
-    const driveId = encodeURIComponent(locator.driveId);
-    const itemId = encodeURIComponent(locator.itemId);
-    const dataStorePath = encodeURIComponent(locator.dataStorePath);
-
-    let locatorSerialized = `${sitePathParamName}=${sitePath}&${driveIdParamName}=${driveId}&${
-        itemIdParamName}=${itemId}&${dataStorePathParamName}=${dataStorePath}&${
-        fluidSignatureParamName}=${fluidSignature}`;
-    if (locator.appName) {
-        locatorSerialized += `&${appNameParamName}=${encodeURIComponent(locator.appName)}`;
-    }
-    if (locator.containerPackageName) {
-        locatorSerialized += `&${containerPackageNameParamName}=${encodeURIComponent(locator.containerPackageName)}`;
-    }
-    if (locator.fileVersion) {
-        locatorSerialized += `&${fileVersionParamName}=${encodeURIComponent(locator.fileVersion)}`;
-    }
-    if (locator.context) {
-        locatorSerialized += `&${additionalContextParamName}=${encodeURIComponent(locator.context)}`;
-    }
-
-    return fromUtf8ToBase64(locatorSerialized);
+	const siteUrl = new URL(locator.siteUrl);
+	const sitePath = encodeURIComponent(siteUrl.pathname);
+	const driveId = encodeURIComponent(locator.driveId);
+	const itemId = encodeURIComponent(locator.itemId);
+	const dataStorePath = encodeURIComponent(locator.dataStorePath);
+
+	let locatorSerialized = `${sitePathParamName}=${sitePath}&${driveIdParamName}=${driveId}&${itemIdParamName}=${itemId}&${dataStorePathParamName}=${dataStorePath}&${fluidSignatureParamName}=${fluidSignature}`;
+	if (locator.appName) {
+		locatorSerialized += `&${appNameParamName}=${encodeURIComponent(locator.appName)}`;
+	}
+	if (locator.containerPackageName) {
+		locatorSerialized += `&${containerPackageNameParamName}=${encodeURIComponent(
+			locator.containerPackageName,
+		)}`;
+	}
+	if (locator.fileVersion) {
+		locatorSerialized += `&${fileVersionParamName}=${encodeURIComponent(locator.fileVersion)}`;
+	}
+	if (locator.context) {
+		locatorSerialized += `&${additionalContextParamName}=${encodeURIComponent(
+			locator.context,
+		)}`;
+	}
+
+	return fromUtf8ToBase64(locatorSerialized);
 }
 
 /**
  * Decodes given encoded value representing Fluid data store locator extracted from ODSP Fluid file link
  * @param encodedLocatorValue - encoded Fluid data store locator value which was produced by
- *  encodeOdspFluidDataStoreLocator method
+ * {@link encodeOdspFluidDataStoreLocator} function
  * @param siteOriginUrl - site origin that will be appended to encoded relative path to form absolute file url
+ * @param requireFluidSignature - flag representing if the Fluid signature is expected in the url, default true
  * @returns object representing Fluid data store location in ODSP terms
  */
 function decodeOdspFluidDataStoreLocator(
-    encodedLocatorValue: string,
-    siteOriginUrl: string,
+	encodedLocatorValue: string,
+	siteOriginUrl: string,
+	requireFluidSignature: boolean = true,
 ): OdspFluidDataStoreLocator | undefined {
-    const locatorInfo = new URLSearchParams(fromBase64ToUtf8(encodedLocatorValue));
-
-    const signatureValue = locatorInfo.get(fluidSignatureParamName);
-    if (signatureValue !== "1") {
-        return undefined;
-    }
-
-    const sitePath = locatorInfo.get(sitePathParamName);
-    const driveId = locatorInfo.get(driveIdParamName);
-    const itemId = locatorInfo.get(itemIdParamName);
-    const dataStorePath = locatorInfo.get(dataStorePathParamName);
-    const appName = locatorInfo.get(appNameParamName) ?? undefined;
-    const containerPackageName = locatorInfo.get(containerPackageNameParamName) ?? undefined;
-    const fileVersion = locatorInfo.get(fileVersionParamName) ?? undefined;
-    const context = locatorInfo.get(additionalContextParamName) ?? undefined;
-    // "" is a valid value for dataStorePath so simply check for absence of the param;
-    // file storage locator params must be present and non-empty
-    if (!sitePath || !driveId || !itemId || dataStorePath === null) {
-        return undefined;
-    }
-
-    let siteUrl: URL | undefined;
-    try {
-        siteUrl = new URL(sitePath, siteOriginUrl);
-    } catch {
-        // Ignore failure to parse url as input might be malformed
-    }
-
-    if (!siteUrl) {
-        return undefined;
-    }
-
-    return {
-        siteUrl: siteUrl.href,
-        driveId,
-        itemId,
-        dataStorePath,
-        appName,
-        containerPackageName,
-        fileVersion,
-        context,
-    };
+	const locatorInfo = new URLSearchParams(fromBase64ToUtf8(encodedLocatorValue));
+
+	const signatureValue = locatorInfo.get(fluidSignatureParamName);
+	if (requireFluidSignature && signatureValue !== "1") {
+		return undefined;
+	}
+
+	const sitePath = locatorInfo.get(sitePathParamName);
+	const driveId = locatorInfo.get(driveIdParamName);
+	const itemId = locatorInfo.get(itemIdParamName);
+	const dataStorePath = locatorInfo.get(dataStorePathParamName);
+	const appName = locatorInfo.get(appNameParamName) ?? undefined;
+	const containerPackageName = locatorInfo.get(containerPackageNameParamName) ?? undefined;
+	const fileVersion = locatorInfo.get(fileVersionParamName) ?? undefined;
+	const context = locatorInfo.get(additionalContextParamName) ?? undefined;
+	// "" is a valid value for dataStorePath so simply check for absence of the param;
+	// file storage locator params must be present and non-empty
+	if (!sitePath || !driveId || !itemId || dataStorePath === null) {
+		return undefined;
+	}
+
+	let siteUrl: URL | undefined;
+	try {
+		siteUrl = new URL(sitePath, siteOriginUrl);
+	} catch {
+		// Ignore failure to parse url as input might be malformed
+	}
+
+	if (!siteUrl) {
+		return undefined;
+	}
+
+	return {
+		siteUrl: siteUrl.href,
+		driveId,
+		itemId,
+		dataStorePath,
+		appName,
+		containerPackageName,
+		fileVersion,
+		context,
+	};
 }
 
-// This parameter is provided by host in the resolve request and it contains information about the file
-// like driveId, itemId, siteUrl, datastorePath, packageName etc.
+/**
+ * This parameter is provided by host in the resolve request and it contains information about the file
+ * like driveId, itemId, siteUrl, datastorePath, packageName etc.
+ * @alpha
+ */
 export const locatorQueryParamName = "nav";
 
 /**
  * Embeds Fluid data store locator data into given ODSP url
  * @param url - file url in ODSP format (can be either canonical or share link)
  * @param locator - object representing Fluid data store location in ODSP terms
+ * @alpha
  */
 export function storeLocatorInOdspUrl(url: URL, locator: OdspFluidDataStoreLocator) {
-    const encodedLocatorValue = encodeOdspFluidDataStoreLocator(locator);
-    // IMPORTANT: Do not apply encodeURIComponent to encodedLocatorValue, param value is automatically encoded
-    // when set via URLSearchParams class
-    url.searchParams.set(locatorQueryParamName, encodedLocatorValue);
+	const encodedLocatorValue = encodeOdspFluidDataStoreLocator(locator);
+	// IMPORTANT: Do not apply encodeURIComponent to encodedLocatorValue, param value is automatically encoded
+	// when set via URLSearchParams class
+	url.searchParams.set(locatorQueryParamName, encodedLocatorValue);
 }
 
 /**
  * Extract ODSP Fluid data store locator object from given ODSP url. This extracts things like
  * driveId, ItemId, siteUrl etc from a url where these are encoded in nav query param.
  * @param url - ODSP url representing Fluid file link
+ * @param requireFluidSignature - flag representing if the Fluid signature is expected in the url, default true
  * @returns object representing Fluid data store location in ODSP terms
+ * @alpha
  */
-export function getLocatorFromOdspUrl(url: URL): OdspFluidDataStoreLocator | undefined {
-    // NOTE: No need to apply decodeURIComponent when accessing query params via URLSearchParams class.
-    const encodedLocatorValue = url.searchParams.get(locatorQueryParamName);
-    if (!encodedLocatorValue) {
-        return undefined;
-    }
-
-    // IMPORTANT: ODC deviates from ODSP in that its file link origin is different from vroom api origin.
-    // The following code passes vroom api origin as site origin instead of file origin.
-    const siteOriginUrl = url.origin.toLowerCase() === OdcFileSiteOrigin ? OdcApiSiteOrigin : url.origin;
-
-    return decodeOdspFluidDataStoreLocator(encodedLocatorValue, siteOriginUrl);
+export function getLocatorFromOdspUrl(
+	url: URL,
+	requireFluidSignature: boolean = true,
+): OdspFluidDataStoreLocator | undefined {
+	// NOTE: No need to apply decodeURIComponent when accessing query params via URLSearchParams class.
+	const encodedLocatorValue = url.searchParams.get(locatorQueryParamName);
+	if (!encodedLocatorValue) {
+		return undefined;
+	}
+
+	// IMPORTANT: ODC deviates from ODSP in that its file link origin is different from vroom api origin.
+	// The following code passes vroom api origin as site origin instead of file origin.
+	const siteOriginUrl =
+		url.origin.toLowerCase() === OdcFileSiteOrigin ? OdcApiSiteOrigin : url.origin;
+
+	return decodeOdspFluidDataStoreLocator(
+		encodedLocatorValue,
+		siteOriginUrl,
+		requireFluidSignature,
+	);
 }

package/src/odspLocationRedirection.ts

@@ -0,0 +1,26 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IResolvedUrl } from "@fluidframework/driver-definitions";
+import { IOdspResolvedUrl } from "@fluidframework/odsp-driver-definitions";
+import { getOdspResolvedUrl } from "./odspUtils";
+
+/**
+ * It takes a resolved url with old siteUrl and creates a new resolved url with updated site url domain.
+ * @param resolvedUrl - Previous odsp resolved url with older site url.
+ * @param redirectLocation - Url at which the network call has to be made. It contains new site info.
+ * @returns The resolved url after patching the correct siteUrl.
+ */
+export function patchOdspResolvedUrl(
+	resolvedUrl: IResolvedUrl,
+	redirectLocation: string,
+): IOdspResolvedUrl {
+	const odspResolvedUrl = { ...getOdspResolvedUrl(resolvedUrl) };
+	// Generate the new SiteUrl from the redirection location.
+	const newSiteDomain = new URL(redirectLocation).origin;
+	const newSiteUrl = `${newSiteDomain}${new URL(odspResolvedUrl.siteUrl).pathname}`;
+	odspResolvedUrl.siteUrl = newSiteUrl;
+	return odspResolvedUrl;
+}

package/src/odspPublicUtils.ts

@@ -3,26 +3,32 @@
  * Licensed under the MIT License.
  */
 
-import { hashFile, IsoBuffer } from "@fluidframework/common-utils";
+import { hashFile, IsoBuffer } from "@fluid-internal/client-utils";
 import { ISequencedDocumentMessage, ISnapshotTree } from "@fluidframework/protocol-definitions";
 
+/**
+ * @alpha
+ */
 export async function getHashedDocumentId(driveId: string, itemId: string): Promise<string> {
-    const buffer = IsoBuffer.from(`${driveId}_${itemId}`);
-    return encodeURIComponent(await hashFile(buffer, "SHA-256", "base64"));
+	const buffer = IsoBuffer.from(`${driveId}_${itemId}`);
+	return encodeURIComponent(await hashFile(buffer, "SHA-256", "base64"));
 }
 
+/**
+ * @alpha
+ */
 export interface ISnapshotContents {
-    snapshotTree: ISnapshotTree;
-    blobs: Map<string, ArrayBuffer>;
-    ops: ISequencedDocumentMessage[];
+	snapshotTree: ISnapshotTree;
+	blobs: Map<string, ArrayBuffer>;
+	ops: ISequencedDocumentMessage[];
 
-    /**
-     * Sequence number of the snapshot
-     */
-    sequenceNumber: number | undefined;
+	/**
+	 * Sequence number of the snapshot
+	 */
+	sequenceNumber: number | undefined;
 
-    /**
-     * Sequence number for the latest op/snapshot for the file in ODSP
-     */
-    latestSequenceNumber: number | undefined;
+	/**
+	 * Sequence number for the latest op/snapshot for the file in ODSP
+	 */
+	latestSequenceNumber: number | undefined;
 }

package/src/odspSnapshotParser.ts

@@ -3,9 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { assert, stringToBuffer } from "@fluidframework/common-utils";
+import { stringToBuffer } from "@fluid-internal/client-utils";
+import { assert } from "@fluidframework/core-utils";
 import * as api from "@fluidframework/protocol-definitions";
-import { IOdspSnapshot, IOdspSnapshotCommit, ISnapshotTreeEx } from "./contracts";
+import { IOdspSnapshot, IOdspSnapshotCommit } from "./contracts";
 import { ISnapshotContents } from "./odspPublicUtils";
 
 /**
@@ -16,35 +17,34 @@ import { ISnapshotContents } from "./odspPublicUtils";
  * @returns the hierarchical tree
  */
 function buildHierarchy(flatTree: IOdspSnapshotCommit): api.ISnapshotTree {
-    const lookup: { [path: string]: api.ISnapshotTree; } = {};
-    // id is required for root tree as it will be used to determine the version we loaded from.
-    const root: ISnapshotTreeEx = { id: flatTree.id, blobs: {}, commits: {}, trees: {} };
-    lookup[""] = root;
+	const lookup: { [path: string]: api.ISnapshotTree } = {};
+	// id is required for root tree as it will be used to determine the version we loaded from.
+	const root: api.ISnapshotTree = { id: flatTree.id, blobs: {}, trees: {} };
+	lookup[""] = root;
 
-    for (const entry of flatTree.entries) {
-        const lastIndex = entry.path.lastIndexOf("/");
-        const entryPathDir = entry.path.slice(0, Math.max(0, lastIndex));
-        const entryPathBase = entry.path.slice(lastIndex + 1);
+	for (const entry of flatTree.entries) {
+		const lastIndex = entry.path.lastIndexOf("/");
+		const entryPathDir = entry.path.slice(0, Math.max(0, lastIndex));
+		const entryPathBase = entry.path.slice(lastIndex + 1);
 
-        // ODSP snapshots are created breadth-first so we can assume we see tree nodes prior to their contents
-        const node = lookup[entryPathDir];
+		// ODSP snapshots are created breadth-first so we can assume we see tree nodes prior to their contents
+		const node = lookup[entryPathDir];
 
-        // Add in either the blob or tree
-        if (entry.type === "tree") {
-            const newTree: ISnapshotTreeEx = {
-                blobs: {},
-                trees: {},
-                commits: {},
-                unreferenced: entry.unreferenced,
-            };
-            node.trees[decodeURIComponent(entryPathBase)] = newTree;
-            lookup[entry.path] = newTree;
-        } else if (entry.type === "blob") {
-            node.blobs[decodeURIComponent(entryPathBase)] = entry.id;
-        }
-    }
+		// Add in either the blob or tree
+		if (entry.type === "tree") {
+			const newTree: api.ISnapshotTree = {
+				blobs: {},
+				trees: {},
+				unreferenced: entry.unreferenced,
+			};
+			node.trees[decodeURIComponent(entryPathBase)] = newTree;
+			lookup[entry.path] = newTree;
+		} else if (entry.type === "blob") {
+			node.blobs[decodeURIComponent(entryPathBase)] = entry.id;
+		}
+	}
 
-    return root;
+	return root;
 }
 
 /**
@@ -52,26 +52,33 @@ function buildHierarchy(flatTree: IOdspSnapshotCommit): api.ISnapshotTree {
  * @param odspSnapshot - snapshot
  */
 export function convertOdspSnapshotToSnapshotTreeAndBlobs(
-    odspSnapshot: IOdspSnapshot,
+	odspSnapshot: IOdspSnapshot,
 ): ISnapshotContents {
-    const blobsWithBufferContent = new Map<string, ArrayBuffer>();
-    if (odspSnapshot.blobs) {
-        odspSnapshot.blobs.forEach((blob) => {
-            assert(blob.encoding === "base64" || blob.encoding === undefined,
-                0x0a4 /* Unexpected blob encoding type */);
-            blobsWithBufferContent.set(blob.id, stringToBuffer(blob.content, blob.encoding ?? "utf8"));
-        });
-    }
+	const blobsWithBufferContent = new Map<string, ArrayBuffer>();
+	if (odspSnapshot.blobs) {
+		odspSnapshot.blobs.forEach((blob) => {
+			assert(
+				blob.encoding === "base64" || blob.encoding === undefined,
+				0x0a4 /* Unexpected blob encoding type */,
+			);
+			blobsWithBufferContent.set(
+				blob.id,
+				stringToBuffer(blob.content, blob.encoding ?? "utf8"),
+			);
+		});
+	}
 
-    const sequenceNumber = odspSnapshot?.trees[0].sequenceNumber;
+	const sequenceNumber = odspSnapshot?.trees[0].sequenceNumber;
 
-    const val: ISnapshotContents = {
-        blobs: blobsWithBufferContent,
-        ops: odspSnapshot.ops?.map((op) => op.op) ?? [],
-        sequenceNumber,
-        snapshotTree: buildHierarchy(odspSnapshot.trees[0]),
-        latestSequenceNumber: (odspSnapshot.ops && odspSnapshot.ops.length > 0) ?
-            odspSnapshot.ops[odspSnapshot.ops.length - 1].sequenceNumber : sequenceNumber,
-    };
-    return val;
+	const val: ISnapshotContents = {
+		blobs: blobsWithBufferContent,
+		ops: odspSnapshot.ops?.map((op) => op.op) ?? [],
+		sequenceNumber,
+		snapshotTree: buildHierarchy(odspSnapshot.trees[0]),
+		latestSequenceNumber:
+			odspSnapshot.ops && odspSnapshot.ops.length > 0
+				? odspSnapshot.ops[odspSnapshot.ops.length - 1].sequenceNumber
+				: sequenceNumber,
+	};
+	return val;
 }