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

package/src/createNewContainerOnExistingFile.ts

@@ -0,0 +1,93 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ISummaryTree } from "@fluidframework/protocol-definitions";
+import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
+import { UsageError } from "@fluidframework/driver-utils";
+import {
+	IFileEntry,
+	InstrumentedStorageTokenFetcher,
+	IOdspResolvedUrl,
+} from "@fluidframework/odsp-driver-definitions";
+import { IWriteSummaryResponse } from "./contracts";
+import { createCacheSnapshotKey, getOrigin, IExistingFileInfo } from "./odspUtils";
+import { ISnapshotContents } from "./odspPublicUtils";
+import { createOdspUrl } from "./createOdspUrl";
+import { getApiRoot } from "./odspUrlHelper";
+import { EpochTracker } from "./epochTracker";
+import { OdspDriverUrlResolver } from "./odspDriverUrlResolver";
+import {
+	convertCreateNewSummaryTreeToTreeAndBlobs,
+	convertSummaryIntoContainerSnapshot,
+	createNewFluidContainerCore,
+} from "./createNewUtils";
+import { ClpCompliantAppHeader } from "./contractsPublic";
+
+/**
+ * Creates a new Fluid container on an existing file.
+ *
+ * @remarks This requires service's capability to manage Fluid container inside an existing file.
+ *
+ * @example
+ *
+ * This enables a scenario where Fluid data is not stored as a standalone file but in a way that is managed
+ * by an existing file. For example, SharePoint Pages is able to store Fluid container in an
+ * "alternative file partition" where the main File stub is an ASPX page.
+ */
+export async function createNewContainerOnExistingFile(
+	getStorageToken: InstrumentedStorageTokenFetcher,
+	fileInfo: IExistingFileInfo,
+	logger: ITelemetryLoggerExt,
+	createNewSummary: ISummaryTree | undefined,
+	epochTracker: EpochTracker,
+	fileEntry: IFileEntry,
+	createNewCaching: boolean,
+	forceAccessTokenViaAuthorizationHeader: boolean,
+	isClpCompliantApp?: boolean,
+): Promise<IOdspResolvedUrl> {
+	if (createNewSummary === undefined) {
+		throw new UsageError("createNewSummary must exist to create a new container");
+	}
+
+	const baseUrl = `${getApiRoot(getOrigin(fileInfo.siteUrl))}/drives/${fileInfo.driveId}/items/${
+		fileInfo.itemId
+	}`;
+
+	const containerSnapshot = convertSummaryIntoContainerSnapshot(createNewSummary);
+
+	const initialUrl = `${baseUrl}/opStream/snapshots/snapshot`;
+
+	const { id: summaryHandle } = await createNewFluidContainerCore<IWriteSummaryResponse>({
+		containerSnapshot,
+		getStorageToken,
+		logger,
+		initialUrl,
+		forceAccessTokenViaAuthorizationHeader,
+		epochTracker,
+		telemetryName: "CreateNewContainerOnExistingFile",
+		fetchType: "uploadSummary",
+	});
+
+	const odspUrl = createOdspUrl({ ...fileInfo, dataStorePath: "/" });
+	const resolver = new OdspDriverUrlResolver();
+	const odspResolvedUrl = await resolver.resolve({
+		url: odspUrl,
+		headers: { [ClpCompliantAppHeader.isClpCompliantApp]: isClpCompliantApp },
+	});
+	fileEntry.docId = odspResolvedUrl.hashedDocumentId;
+	fileEntry.resolvedUrl = odspResolvedUrl;
+
+	if (createNewCaching) {
+		// converting summary and getting sequence number
+		const snapshot: ISnapshotContents = convertCreateNewSummaryTreeToTreeAndBlobs(
+			createNewSummary,
+			summaryHandle,
+		);
+		// caching the converted summary
+		await epochTracker.put(createCacheSnapshotKey(odspResolvedUrl), snapshot);
+	}
+
+	return odspResolvedUrl;
+}

package/src/createNewModule.ts

@@ -0,0 +1,7 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { createNewFluidFile } from "./createFile";
+export { createNewContainerOnExistingFile } from "./createNewContainerOnExistingFile";

package/src/createNewUtils.ts

@@ -4,69 +4,279 @@
  */
 
 import { v4 as uuid } from "uuid";
-import { ISummaryTree, SummaryType } from "@fluidframework/protocol-definitions";
-import { getDocAttributesFromProtocolSummary } from "@fluidframework/driver-utils";
-import { stringToBuffer, unreachableCase } from "@fluidframework/common-utils";
+import {
+	ISummaryBlob,
+	ISummaryTree,
+	SummaryType,
+	ISnapshotTree,
+} from "@fluidframework/protocol-definitions";
+import {
+	getDocAttributesFromProtocolSummary,
+	isCombinedAppAndProtocolSummary,
+} from "@fluidframework/driver-utils";
+import { stringToBuffer, Uint8ArrayToString } from "@fluid-internal/client-utils";
+import { unreachableCase } from "@fluidframework/core-utils";
+import { getGitType } from "@fluidframework/protocol-base";
+import { ITelemetryLoggerExt, PerformanceEvent } from "@fluidframework/telemetry-utils";
+import { InstrumentedStorageTokenFetcher } from "@fluidframework/odsp-driver-definitions";
+import {
+	IOdspSummaryPayload,
+	IOdspSummaryTree,
+	OdspSummaryTreeEntry,
+	OdspSummaryTreeValue,
+} from "./contracts";
+import { getWithRetryForTokenRefresh, maxUmpPostBodySize } from "./odspUtils";
 import { ISnapshotContents } from "./odspPublicUtils";
-import { ISnapshotTreeEx } from "./contracts";
+import { EpochTracker, FetchType } from "./epochTracker";
+import { getUrlAndHeadersWithAuth } from "./getUrlAndHeadersWithAuth";
+import { runWithRetry } from "./retryUtils";
 
 /**
  * Converts a summary(ISummaryTree) taken in detached container to snapshot tree and blobs
  */
-export function convertCreateNewSummaryTreeToTreeAndBlobs(summary: ISummaryTree, treeId: string): ISnapshotContents {
-    const protocolSummary = summary.tree[".protocol"] as ISummaryTree;
-    const documentAttributes = getDocAttributesFromProtocolSummary(protocolSummary);
-    const sequenceNumber = documentAttributes.sequenceNumber;
-    const blobs = new Map<string, ArrayBuffer>();
-    const snapshotTree = convertCreateNewSummaryTreeToTreeAndBlobsCore(summary, blobs);
-    snapshotTree.id = treeId;
-    const snapshotTreeValue: ISnapshotContents = {
-        snapshotTree,
-        blobs,
-        ops: [],
-        sequenceNumber,
-        latestSequenceNumber: sequenceNumber,
-    };
-
-    return snapshotTreeValue;
+export function convertCreateNewSummaryTreeToTreeAndBlobs(
+	summary: ISummaryTree,
+	treeId: string,
+): ISnapshotContents {
+	const protocolSummary = summary.tree[".protocol"] as ISummaryTree;
+	const documentAttributes = getDocAttributesFromProtocolSummary(protocolSummary);
+	const sequenceNumber = documentAttributes.sequenceNumber;
+	const blobs = new Map<string, ArrayBuffer>();
+	const snapshotTree = convertCreateNewSummaryTreeToTreeAndBlobsCore(summary, blobs);
+	snapshotTree.id = treeId;
+	const snapshotTreeValue: ISnapshotContents = {
+		snapshotTree,
+		blobs,
+		ops: [],
+		sequenceNumber,
+		latestSequenceNumber: sequenceNumber,
+	};
+
+	return snapshotTreeValue;
 }
 
 function convertCreateNewSummaryTreeToTreeAndBlobsCore(
-    summary: ISummaryTree,
-    blobs: Map<string, ArrayBuffer>,
+	summary: ISummaryTree,
+	blobs: Map<string, ArrayBuffer>,
 ) {
-    const treeNode: ISnapshotTreeEx = {
-        blobs: {},
-        trees: {},
-        commits: {},
-        unreferenced: summary.unreferenced,
-    };
-    const keys = Object.keys(summary.tree);
-    for (const key of keys) {
-        const summaryObject = summary.tree[key];
-
-        switch (summaryObject.type) {
-            case SummaryType.Tree: {
-                treeNode.trees[key] =
-                    convertCreateNewSummaryTreeToTreeAndBlobsCore(summaryObject, blobs);
-                break;
-            }
-            case SummaryType.Blob: {
-                const contentBuffer = typeof summaryObject.content === "string" ?
-                    stringToBuffer(summaryObject.content, "utf8") : summaryObject.content;
-                const blobId = uuid();
-                treeNode.blobs[key] = blobId;
-                blobs.set(blobId, contentBuffer);
-                break;
-            }
-            case SummaryType.Handle:
-            case SummaryType.Attachment: {
-                throw new Error(`No ${summaryObject.type} should be present for detached summary!`);
-            }
-            default: {
-                unreachableCase(summaryObject, `Unknown tree type ${(summaryObject as any).type}`);
-            }
-        }
-    }
-    return treeNode;
+	const treeNode: ISnapshotTree = {
+		blobs: {},
+		trees: {},
+		unreferenced: summary.unreferenced,
+	};
+	const keys = Object.keys(summary.tree);
+	for (const key of keys) {
+		const summaryObject = summary.tree[key];
+
+		switch (summaryObject.type) {
+			case SummaryType.Tree: {
+				treeNode.trees[key] = convertCreateNewSummaryTreeToTreeAndBlobsCore(
+					summaryObject,
+					blobs,
+				);
+				break;
+			}
+			case SummaryType.Blob: {
+				const contentBuffer =
+					typeof summaryObject.content === "string"
+						? stringToBuffer(summaryObject.content, "utf8")
+						: summaryObject.content;
+				const blobId = uuid();
+				treeNode.blobs[key] = blobId;
+				blobs.set(blobId, contentBuffer);
+				break;
+			}
+			case SummaryType.Handle:
+			case SummaryType.Attachment: {
+				throw new Error(`No ${summaryObject.type} should be present for detached summary!`);
+			}
+			default: {
+				unreachableCase(summaryObject, `Unknown tree type ${(summaryObject as any).type}`);
+			}
+		}
+	}
+	return treeNode;
+}
+
+export function convertSummaryIntoContainerSnapshot(createNewSummary: ISummaryTree) {
+	if (!isCombinedAppAndProtocolSummary(createNewSummary)) {
+		throw new Error("App and protocol summary required for create new path!!");
+	}
+	const appSummary = createNewSummary.tree[".app"];
+	const protocolSummary = createNewSummary.tree[".protocol"];
+	const documentAttributes = getDocAttributesFromProtocolSummary(protocolSummary);
+	const attributesSummaryBlob: ISummaryBlob = {
+		type: SummaryType.Blob,
+		content: JSON.stringify(documentAttributes),
+	};
+	protocolSummary.tree.attributes = attributesSummaryBlob;
+	const convertedCreateNewSummary: ISummaryTree = {
+		type: SummaryType.Tree,
+		tree: {
+			".protocol": protocolSummary,
+			".app": appSummary,
+		},
+	};
+	const snapshotTree = convertSummaryToSnapshotTreeForCreateNew(convertedCreateNewSummary);
+	const snapshot: IOdspSummaryPayload = {
+		entries: snapshotTree.entries ?? [],
+		message: "app",
+		sequenceNumber: documentAttributes.sequenceNumber,
+		type: "container",
+	};
+	return snapshot;
+}
+
+/**
+ * Converts a summary tree to ODSP tree
+ */
+function convertSummaryToSnapshotTreeForCreateNew(summary: ISummaryTree): IOdspSummaryTree {
+	const snapshotTree: IOdspSummaryTree = {
+		type: "tree",
+		entries: [],
+	};
+
+	const keys = Object.keys(summary.tree);
+	for (const key of keys) {
+		const summaryObject = summary.tree[key];
+
+		let value: OdspSummaryTreeValue;
+		// Tracks if an entry is unreferenced. Currently, only tree entries can be marked as unreferenced. If the
+		// property is not present, the tree entry is considered referenced. If the property is present and is true,
+		// the tree entry is considered unreferenced.
+		let unreferenced: true | undefined;
+
+		switch (summaryObject.type) {
+			case SummaryType.Tree: {
+				value = convertSummaryToSnapshotTreeForCreateNew(summaryObject);
+				unreferenced = summaryObject.unreferenced;
+				break;
+			}
+			case SummaryType.Blob: {
+				const content =
+					typeof summaryObject.content === "string"
+						? summaryObject.content
+						: Uint8ArrayToString(summaryObject.content, "base64");
+				const encoding = typeof summaryObject.content === "string" ? "utf-8" : "base64";
+
+				value = {
+					type: "blob",
+					content,
+					encoding,
+				};
+				break;
+			}
+			case SummaryType.Handle: {
+				throw new Error("No handle should be present for first summary!!");
+			}
+			default: {
+				throw new Error(`Unknown tree type ${summaryObject.type}`);
+			}
+		}
+
+		const entry: OdspSummaryTreeEntry = {
+			path: encodeURIComponent(key),
+			type: getGitType(summaryObject),
+			value,
+			unreferenced,
+		};
+		snapshotTree.entries?.push(entry);
+	}
+
+	return snapshotTree;
+}
+
+export async function createNewFluidContainerCore<T>(args: {
+	containerSnapshot: IOdspSummaryPayload;
+	getStorageToken: InstrumentedStorageTokenFetcher;
+	logger: ITelemetryLoggerExt;
+	initialUrl: string;
+	forceAccessTokenViaAuthorizationHeader: boolean;
+	epochTracker: EpochTracker;
+	telemetryName: string;
+	fetchType: FetchType;
+	validateResponseCallback?: (content: T) => void;
+}): Promise<T> {
+	const {
+		containerSnapshot,
+		getStorageToken,
+		logger,
+		initialUrl,
+		forceAccessTokenViaAuthorizationHeader,
+		epochTracker,
+		telemetryName,
+		fetchType,
+		validateResponseCallback,
+	} = args;
+
+	return getWithRetryForTokenRefresh(async (options) => {
+		const storageToken = await getStorageToken(options, telemetryName);
+
+		return PerformanceEvent.timedExecAsync(
+			logger,
+			{ eventName: telemetryName },
+			async (event) => {
+				const snapshotBody = JSON.stringify(containerSnapshot);
+				let url: string;
+				let headers: { [index: string]: string };
+				let addInBody = false;
+				const formBoundary = uuid();
+				let postBody = `--${formBoundary}\r\n`;
+				postBody += `Authorization: Bearer ${storageToken}\r\n`;
+				postBody += `X-HTTP-Method-Override: POST\r\n`;
+				postBody += `Content-Type: application/json\r\n`;
+				postBody += `_post: 1\r\n`;
+				postBody += `\r\n${snapshotBody}\r\n`;
+				postBody += `\r\n--${formBoundary}--`;
+
+				if (postBody.length <= maxUmpPostBodySize) {
+					const urlObj = new URL(initialUrl);
+					urlObj.searchParams.set("ump", "1");
+					url = urlObj.href;
+					headers = {
+						"Content-Type": `multipart/form-data;boundary=${formBoundary}`,
+					};
+					addInBody = true;
+				} else {
+					const parts = getUrlAndHeadersWithAuth(
+						initialUrl,
+						storageToken,
+						forceAccessTokenViaAuthorizationHeader,
+					);
+					url = parts.url;
+					headers = {
+						...parts.headers,
+						"Content-Type": "application/json",
+					};
+					postBody = snapshotBody;
+				}
+
+				const fetchResponse = await runWithRetry(
+					async () =>
+						epochTracker.fetchAndParseAsJSON<T>(
+							url,
+							{
+								body: postBody,
+								headers,
+								method: "POST",
+							},
+							fetchType,
+							addInBody,
+						),
+					telemetryName,
+					logger,
+				);
+
+				validateResponseCallback?.(fetchResponse.content);
+
+				event.end({
+					headers: Object.keys(headers).length !== 0 ? true : undefined,
+					attempts: options.refresh ? 2 : 1,
+					...fetchResponse.propsToLog,
+				});
+
+				return fetchResponse.content;
+			},
+		);
+	});
 }

package/src/createOdspCreateContainerRequest.ts

@@ -4,7 +4,8 @@
  */
 import { IRequest } from "@fluidframework/core-interfaces";
 import { DriverHeader } from "@fluidframework/driver-definitions";
-import { ShareLinkTypes } from "@fluidframework/odsp-driver-definitions";
+import { ShareLinkTypes, ISharingLinkKind } from "@fluidframework/odsp-driver-definitions";
+import { buildOdspShareLinkReqParams } from "./odspUtils";
 
 /**
  * Create the request object with url and headers for creating a new file on OneDrive Sharepoint
@@ -12,24 +13,27 @@ import { ShareLinkTypes } from "@fluidframework/odsp-driver-definitions";
  * @param driveId - drive identifier
  * @param filePath - path where file needs to be created
  * @param fileName - name of the new file to be created
- * @param createLinkType - type of sharing link you would like to create for this file
+ * @param createShareLinkType - type of sharing link you would like to create for this file. ShareLinkTypes
+ * will be deprecated soon, so for any new implementation please provide createShareLinkType of type ShareLink
+ * @alpha
  */
 export function createOdspCreateContainerRequest(
-    siteUrl: string,
-    driveId: string,
-    filePath: string,
-    fileName: string,
-    createLinkType?: ShareLinkTypes,
+	siteUrl: string,
+	driveId: string,
+	filePath: string,
+	fileName: string,
+	createShareLinkType?: ShareLinkTypes | ISharingLinkKind,
 ): IRequest {
-    const createNewRequest: IRequest = {
-        url: `${siteUrl}?driveId=${encodeURIComponent(
-            driveId,
-        )}&path=${encodeURIComponent(filePath)}${createLinkType ? `&createLinkType=${createLinkType}` : ""}`,
-        headers: {
-            [DriverHeader.createNew]: {
-                fileName,
-            },
-        },
-    };
-    return createNewRequest;
+	const shareLinkRequestParams = buildOdspShareLinkReqParams(createShareLinkType);
+	const createNewRequest: IRequest = {
+		url: `${siteUrl}?driveId=${encodeURIComponent(driveId)}&path=${encodeURIComponent(
+			filePath,
+		)}${shareLinkRequestParams ? `&${shareLinkRequestParams}` : ""}`,
+		headers: {
+			[DriverHeader.createNew]: {
+				fileName,
+			},
+		},
+	};
+	return createNewRequest;
 }

package/src/createOdspUrl.ts

@@ -12,19 +12,18 @@ import { OdspFluidDataStoreLocator } from "./contractsPublic";
 /**
  * Encodes ODC/SPO information into a URL format that can be handled by the Loader
  * @param l -The property bag of necessary properties to locate a Fluid data store and craft a url for it
+ * @alpha
  */
-export function createOdspUrl(
-    l: OdspFluidDataStoreLocator,
-): string {
-    let odspUrl = `${l.siteUrl}?driveId=${encodeURIComponent(l.driveId)}&itemId=${encodeURIComponent(
-        l.itemId,
-    )}&path=${encodeURIComponent(l.dataStorePath)}`;
-    if (l.containerPackageName) {
-        odspUrl += `&containerPackageName=${encodeURIComponent(l.containerPackageName)}`;
-    }
-    if (l.fileVersion) {
-        odspUrl += `&fileVersion=${encodeURIComponent(l.fileVersion)}`;
-    }
+export function createOdspUrl(l: OdspFluidDataStoreLocator): string {
+	let odspUrl = `${l.siteUrl}?driveId=${encodeURIComponent(
+		l.driveId,
+	)}&itemId=${encodeURIComponent(l.itemId)}&path=${encodeURIComponent(l.dataStorePath)}`;
+	if (l.containerPackageName) {
+		odspUrl += `&containerPackageName=${encodeURIComponent(l.containerPackageName)}`;
+	}
+	if (l.fileVersion) {
+		odspUrl += `&fileVersion=${encodeURIComponent(l.fileVersion)}`;
+	}
 
-    return odspUrl;
+	return odspUrl;
 }