@fluidframework/routerlicious-driver 2.0.0-dev.2.3.0.115467 → 2.0.0-dev.4.1.0.148229

package/src/shreddedSummaryDocumentStorageService.ts

@@ -4,27 +4,24 @@
  */
 
 import type { ITelemetryLogger } from "@fluidframework/common-definitions";
+import { stringToBuffer, Uint8ArrayToString } from "@fluidframework/common-utils";
 import {
-    stringToBuffer,
-    Uint8ArrayToString,
-} from "@fluidframework/common-utils";
-import {
-    IDocumentStorageService,
-    ISummaryContext,
-    IDocumentStorageServicePolicies,
+	IDocumentStorageService,
+	ISummaryContext,
+	IDocumentStorageServicePolicies,
 } from "@fluidframework/driver-definitions";
 import { buildHierarchy } from "@fluidframework/protocol-base";
 import {
-    ICreateBlobResponse,
-    ISnapshotTreeEx,
-    ISummaryHandle,
-    ISummaryTree,
-    IVersion,
+	ICreateBlobResponse,
+	ISnapshotTreeEx,
+	ISummaryHandle,
+	ISummaryTree,
+	IVersion,
 } from "@fluidframework/protocol-definitions";
 import {
-    GitManager,
-    ISummaryUploadManager,
-    SummaryTreeUploadManager,
+	GitManager,
+	ISummaryUploadManager,
+	SummaryTreeUploadManager,
 } from "@fluidframework/server-services-client";
 import { PerformanceEvent } from "@fluidframework/telemetry-utils";
 import { IRouterliciousDriverPolicies } from "./policies";
@@ -40,183 +37,194 @@ const isNode = typeof window === "undefined";
  * Downloads summaries piece-by-piece on-demand, or up-front when prefetch is enabled.
  */
 export class ShreddedSummaryDocumentStorageService implements IDocumentStorageService {
-    // The values of this cache is useless. We only need the keys. So we are always putting
-    // empty strings as values.
-    protected readonly blobsShaCache = new Map<string, string>();
-    private readonly blobCache: ICache<ArrayBufferLike> | undefined;
-    private readonly snapshotTreeCache: ICache<ISnapshotTreeVersion> | undefined;
-
-    public get repositoryUrl(): string {
-        return "";
-    }
-
-    private async getSummaryUploadManager(): Promise<ISummaryUploadManager> {
-        const manager = await this.getStorageManager();
-        return new SummaryTreeUploadManager(
-            new RetriableGitManager(manager, this.logger),
-            this.blobsShaCache,
-            this.getPreviousFullSnapshot.bind(this),
-        );
-    }
-
-    constructor(
-        protected readonly id: string,
-        protected readonly manager: GitManager,
-        protected readonly logger: ITelemetryLogger,
-        public readonly policies: IDocumentStorageServicePolicies = {},
-        driverPolicies?: IRouterliciousDriverPolicies,
-        blobCache?: ICache<ArrayBufferLike>,
-        snapshotTreeCache?: ICache<ISnapshotTreeVersion>,
-        private readonly getStorageManager: (disableCache?: boolean) => Promise<GitManager> = async () => this.manager,
-    ) {
-        if (driverPolicies?.enableRestLess === true || isNode) {
-            this.blobCache = blobCache ?? new InMemoryCache();
-            this.snapshotTreeCache = snapshotTreeCache ?? new InMemoryCache();
-        }
-    }
-
-    public async getVersions(versionId: string | null, count: number): Promise<IVersion[]> {
-        const id = versionId ? versionId : this.id;
-        const commits = await PerformanceEvent.timedExecAsync(
-            this.logger,
-            {
-                eventName: "getVersions",
-                versionId: id,
-                count,
-            },
-            async () => {
-                const manager = await this.getStorageManager();
-                return manager.getCommits(id, count);
-            },
-        );
-        return commits.map((commit) => ({
-            date: commit.commit.author.date,
-            id: commit.sha,
-            treeId: commit.commit.tree.sha,
-        }));
-    }
-
-    public async getSnapshotTree(version?: IVersion): Promise<ISnapshotTreeEx | null> {
-        let requestVersion = version;
-        if (!requestVersion) {
-            const versions = await this.getVersions(this.id, 1);
-            if (versions.length === 0) {
-                return null;
-            }
-
-            requestVersion = versions[0];
-        }
-
-        const cachedSnapshotTree = await this.snapshotTreeCache?.get(this.getCacheKey(requestVersion.treeId));
-        if (cachedSnapshotTree) {
-            return cachedSnapshotTree.snapshotTree as ISnapshotTreeEx;
-        }
-
-        const rawTree = await PerformanceEvent.timedExecAsync(
-            this.logger,
-            {
-                eventName: "getSnapshotTree",
-                treeId: requestVersion.treeId,
-            },
-            async (event) => {
-                const manager = await this.getStorageManager();
-                const response = await manager.getTree(requestVersion!.treeId);
-                event.end({
-                    size: response.tree.length,
-                });
-                return response;
-            },
-        );
-        const tree = buildHierarchy(rawTree, this.blobsShaCache, true);
-        await this.snapshotTreeCache?.put(
-            this.getCacheKey(tree.id),
-            { id: requestVersion.id, snapshotTree: tree },
-        );
-        return tree;
-    }
-
-    public async readBlob(blobId: string): Promise<ArrayBufferLike> {
-        const cachedBlob = await this.blobCache?.get(this.getCacheKey(blobId));
-        if (cachedBlob) {
-            return cachedBlob;
-        }
-
-        const value = await PerformanceEvent.timedExecAsync(
-            this.logger,
-            {
-                eventName: "readBlob",
-                blobId,
-            },
-            async (event) => {
-                const manager = await this.getStorageManager();
-                const response = await manager.getBlob(blobId);
-                event.end({
-                    size: response.size,
-                });
-                return response;
-            },
-        );
-        this.blobsShaCache.set(value.sha, "");
-        const bufferContent = stringToBuffer(value.content, value.encoding);
-        await this.blobCache?.put(this.getCacheKey(value.sha), bufferContent);
-        return bufferContent;
-    }
-
-    public async uploadSummaryWithContext(summary: ISummaryTree, context: ISummaryContext): Promise<string> {
-        const summaryHandle = await PerformanceEvent.timedExecAsync(
-            this.logger,
-            {
-                eventName: "uploadSummaryWithContext",
-                proposalHandle: context.proposalHandle,
-                ackHandle: context.ackHandle,
-                referenceSequenceNumber: context.referenceSequenceNumber,
-            },
-            async () => {
-                const summaryUploadManager = await this.getSummaryUploadManager();
-                return summaryUploadManager.writeSummaryTree(summary, context.ackHandle ?? "", "channel");
-            },
-        );
-        return summaryHandle;
-    }
-
-    public async downloadSummary(handle: ISummaryHandle): Promise<ISummaryTree> {
-        throw new Error("NOT IMPLEMENTED!");
-    }
-
-    public async createBlob(file: ArrayBufferLike): Promise<ICreateBlobResponse> {
-        const uint8ArrayFile = new Uint8Array(file);
-        return PerformanceEvent.timedExecAsync(
-            this.logger,
-            {
-                eventName: "createBlob",
-                size: uint8ArrayFile.length,
-            },
-            async (event) => {
-                const manager = await this.getStorageManager();
-                const response = await manager.createBlob(
-                    Uint8ArrayToString(
-                        uint8ArrayFile, "base64"),
-                    "base64").then((r) => ({ id: r.sha, url: r.url }));
-                event.end({
-                    blobId: response.id,
-                });
-                return response;
-            },
-        );
-    }
-
-    private async getPreviousFullSnapshot(parentHandle: string): Promise<ISnapshotTreeEx | null | undefined> {
-        return parentHandle
-            ? this.getVersions(parentHandle, 1)
-                .then(async (versions) => {
-                    // Clear the cache as the getSnapshotTree call will fill the cache.
-                    this.blobsShaCache.clear();
-                    return this.getSnapshotTree(versions[0]);
-                })
-            : undefined;
-    }
-
-    private getCacheKey(blobId: string): string {
-        return `${this.id}:${blobId}`;
-    }
+	// The values of this cache is useless. We only need the keys. So we are always putting
+	// empty strings as values.
+	protected readonly blobsShaCache = new Map<string, string>();
+	private readonly blobCache: ICache<ArrayBufferLike> | undefined;
+	private readonly snapshotTreeCache: ICache<ISnapshotTreeVersion> | undefined;
+
+	public get repositoryUrl(): string {
+		return "";
+	}
+
+	private async getSummaryUploadManager(): Promise<ISummaryUploadManager> {
+		const manager = await this.getStorageManager();
+		return new SummaryTreeUploadManager(
+			new RetriableGitManager(manager, this.logger),
+			this.blobsShaCache,
+			this.getPreviousFullSnapshot.bind(this),
+		);
+	}
+
+	constructor(
+		protected readonly id: string,
+		protected readonly manager: GitManager,
+		protected readonly logger: ITelemetryLogger,
+		public readonly policies: IDocumentStorageServicePolicies,
+		driverPolicies?: IRouterliciousDriverPolicies,
+		blobCache?: ICache<ArrayBufferLike>,
+		snapshotTreeCache?: ICache<ISnapshotTreeVersion>,
+		private readonly getStorageManager: (
+			disableCache?: boolean,
+		) => Promise<GitManager> = async () => this.manager,
+	) {
+		if (driverPolicies?.enableRestLess === true || isNode) {
+			this.blobCache = blobCache ?? new InMemoryCache();
+			this.snapshotTreeCache = snapshotTreeCache ?? new InMemoryCache();
+		}
+	}
+
+	public async getVersions(versionId: string | null, count: number): Promise<IVersion[]> {
+		const id = versionId ? versionId : this.id;
+		const commits = await PerformanceEvent.timedExecAsync(
+			this.logger,
+			{
+				eventName: "getVersions",
+				versionId: id,
+				count,
+			},
+			async () => {
+				const manager = await this.getStorageManager();
+				return manager.getCommits(id, count);
+			},
+		);
+		return commits.map((commit) => ({
+			date: commit.commit.author.date,
+			id: commit.sha,
+			treeId: commit.commit.tree.sha,
+		}));
+	}
+
+	public async getSnapshotTree(version?: IVersion): Promise<ISnapshotTreeEx | null> {
+		let requestVersion = version;
+		if (!requestVersion) {
+			const versions = await this.getVersions(this.id, 1);
+			if (versions.length === 0) {
+				return null;
+			}
+
+			requestVersion = versions[0];
+		}
+
+		const cachedSnapshotTree = await this.snapshotTreeCache?.get(
+			this.getCacheKey(requestVersion.treeId),
+		);
+		if (cachedSnapshotTree) {
+			return cachedSnapshotTree.snapshotTree as ISnapshotTreeEx;
+		}
+
+		const rawTree = await PerformanceEvent.timedExecAsync(
+			this.logger,
+			{
+				eventName: "getSnapshotTree",
+				treeId: requestVersion.treeId,
+			},
+			async (event) => {
+				const manager = await this.getStorageManager();
+				const response = await manager.getTree(requestVersion!.treeId);
+				event.end({
+					size: response.tree.length,
+				});
+				return response;
+			},
+		);
+		const tree = buildHierarchy(rawTree, this.blobsShaCache, true);
+		await this.snapshotTreeCache?.put(this.getCacheKey(tree.id), {
+			id: requestVersion.id,
+			snapshotTree: tree,
+		});
+		return tree;
+	}
+
+	public async readBlob(blobId: string): Promise<ArrayBufferLike> {
+		const cachedBlob = await this.blobCache?.get(this.getCacheKey(blobId));
+		if (cachedBlob) {
+			return cachedBlob;
+		}
+
+		const value = await PerformanceEvent.timedExecAsync(
+			this.logger,
+			{
+				eventName: "readBlob",
+				blobId,
+			},
+			async (event) => {
+				const manager = await this.getStorageManager();
+				const response = await manager.getBlob(blobId);
+				event.end({
+					size: response.size,
+				});
+				return response;
+			},
+		);
+		this.blobsShaCache.set(value.sha, "");
+		const bufferContent = stringToBuffer(value.content, value.encoding);
+		await this.blobCache?.put(this.getCacheKey(value.sha), bufferContent);
+		return bufferContent;
+	}
+
+	public async uploadSummaryWithContext(
+		summary: ISummaryTree,
+		context: ISummaryContext,
+	): Promise<string> {
+		const summaryHandle = await PerformanceEvent.timedExecAsync(
+			this.logger,
+			{
+				eventName: "uploadSummaryWithContext",
+				proposalHandle: context.proposalHandle,
+				ackHandle: context.ackHandle,
+				referenceSequenceNumber: context.referenceSequenceNumber,
+			},
+			async () => {
+				const summaryUploadManager = await this.getSummaryUploadManager();
+				return summaryUploadManager.writeSummaryTree(
+					summary,
+					context.ackHandle ?? "",
+					"channel",
+				);
+			},
+		);
+		return summaryHandle;
+	}
+
+	public async downloadSummary(handle: ISummaryHandle): Promise<ISummaryTree> {
+		throw new Error("NOT IMPLEMENTED!");
+	}
+
+	public async createBlob(file: ArrayBufferLike): Promise<ICreateBlobResponse> {
+		const uint8ArrayFile = new Uint8Array(file);
+		return PerformanceEvent.timedExecAsync(
+			this.logger,
+			{
+				eventName: "createBlob",
+				size: uint8ArrayFile.length,
+			},
+			async (event) => {
+				const manager = await this.getStorageManager();
+				const response = await manager
+					.createBlob(Uint8ArrayToString(uint8ArrayFile, "base64"), "base64")
+					.then((r) => ({ id: r.sha, url: r.url }));
+				event.end({
+					blobId: response.id,
+				});
+				return response;
+			},
+		);
+	}
+
+	private async getPreviousFullSnapshot(
+		parentHandle: string,
+	): Promise<ISnapshotTreeEx | null | undefined> {
+		return parentHandle
+			? this.getVersions(parentHandle, 1).then(async (versions) => {
+					// Clear the cache as the getSnapshotTree call will fill the cache.
+					this.blobsShaCache.clear();
+					return this.getSnapshotTree(versions[0]);
+			  })
+			: undefined;
+	}
+
+	private getCacheKey(blobId: string): string {
+		return `${this.id}:${blobId}`;
+	}
 }

package/src/tokens.ts

@@ -6,23 +6,28 @@
 import { ITokenClaims } from "@fluidframework/protocol-definitions";
 
 /**
- * The ITokenService abstracts the discovery of claims contained within a token
+ * Abstracts the discovery of claims contained within a token.
  */
 export interface ITokenService {
-    extractClaims(token: string): ITokenClaims;
+	/**
+	 * Extracts the {@link @fluidframework/protocol-definitions#ITokenClaims | token claims} from the provided
+	 * {@link https://jwt.io/introduction/ | JSON Web Token (JWT)} string representation.
+	 */
+	extractClaims(token: string): ITokenClaims;
 }
 
 export interface ITokenResponse {
-    /**
-     * {@link https://jwt.io/introduction/ | JSON Web Token (JWT)} value.
-     */
-    jwt: string;
+	/**
+	 * {@link https://jwt.io/introduction/ | JSON Web Token (JWT)} value.
+	 */
+	jwt: string;
 
-    /**
-     * Flag indicating whether token was obtained from local cache.
-     * Undefined indicates that the source of the token could not be determined.
-     */
-    fromCache?: boolean;
+	/**
+	 * A flag indicating whether token was obtained from local cache.
+	 *
+	 * @remarks `undefined` indicates that the source of the token could not be determined.
+	 */
+	fromCache?: boolean;
 }
 
 /**
@@ -30,39 +35,59 @@ export interface ITokenResponse {
  * The hosting application is responsible for providing an implementation.
  */
 export interface ITokenProvider {
-    /**
-     * Fetches the orderer token from host.
-     * @param tenantId - Tenant ID.
-     * @param documentId - Optional. Document ID is only required for document-scoped requests.
-     * @param refresh - Optional flag indicating whether token fetch must bypass local cache.
-     * @returns TokenResponse object representing token value along with flag indicating
-     * whether token came from cache.
-     */
-    fetchOrdererToken(tenantId: string, documentId?: string, refresh?: boolean): Promise<ITokenResponse>;
+	/**
+	 * Fetches the orderer token from host.
+	 *
+	 * @param tenantId - Tenant ID.
+	 * @param documentId - Optional. Document ID is only required for document-scoped requests.
+	 * @param refresh - Optional flag indicating whether token fetch must bypass local cache.
+	 * This likely indicates that some previous request failed authorization due to an expired token,
+	 * and so a fresh token is required.
+	 *
+	 * Default: `false`.
+	 *
+	 * NOTE: This parameter will be made required in the future.
+	 */
+	fetchOrdererToken(
+		tenantId: string,
+		documentId?: string,
+		refresh?: boolean,
+	): Promise<ITokenResponse>;
 
-    /**
-     * Fetches the storage token from host.
-     * @param tenantId - Tenant ID.
-     * @param documentId - Document ID.
-     * @param refresh - Optional flag indicating whether token fetch must bypass local cache.
-     * @returns TokenResponse object representing token value along with flag indicating
-     * whether token came from cache.
-     */
-    fetchStorageToken(tenantId: string, documentId: string, refresh?: boolean): Promise<ITokenResponse>;
+	/**
+	 * Fetches the storage token from host.
+	 *
+	 * @param tenantId - Tenant ID.
+	 * @param documentId - Document ID.
+	 * @param refresh - Optional flag indicating whether token fetch must bypass local cache.
+	 * This likely indicates that some previous request failed authorization due to an expired token,
+	 * and so a fresh token is required.
+	 *
+	 * Default: `false`.
+	 *
+	 * NOTE: This parameter will be made required in the future.
+	 */
+	fetchStorageToken(
+		tenantId: string,
+		documentId: string,
+		refresh?: boolean,
+	): Promise<ITokenResponse>;
 
-    /**
-     * A callback triggered directly after creating the document. In this callback the client has the opportunity, to
-     * verify against an authorization service, if the user who claims to create the document is the same user who
-     * created it.
-     *
-     * @remarks Notes:
-     * * Using the callback may have performance impact on the document creation process.
-     * * Any exceptions thrown in the callback would fail the creation workflow
-     * (see {@link RouterliciousDocumentServiceFactory.createContainer} for more details).
-     *
-     * @param documentId - Document ID.
-     * @param creationToken - A special token that doesn't provide any kind of access, but it has the user's payload
-     * and document id. It can be used to validate the identity of the document creator.
-     */
-    documentPostCreateCallback?(documentId: string, creationToken: string): Promise<void>;
+	/**
+	 * A callback triggered directly after creating the document. In this callback the client has the opportunity, to
+	 * verify against an authorization service, if the user who claims to create the document is the same user who
+	 * created it.
+	 *
+	 * @remarks Notes:
+	 *
+	 * * Using the callback may have performance impact on the document creation process.
+	 *
+	 * * Any exceptions thrown in the callback would fail the creation workflow
+	 * (see {@link RouterliciousDocumentServiceFactory.createContainer} for more details).
+	 *
+	 * @param documentId - Document ID.
+	 * @param creationToken - A special token that doesn't provide any kind of access, but it has the user's payload
+	 * and document id. It can be used to validate the identity of the document creator.
+	 */
+	documentPostCreateCallback?(documentId: string, creationToken: string): Promise<void>;
 }

package/src/treeUtils.ts

@@ -0,0 +1,107 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert, IsoBuffer } from "@fluidframework/common-utils";
+import {
+	SummaryType,
+	ISnapshotTree,
+	ISummaryTree,
+	SummaryObject,
+} from "@fluidframework/protocol-definitions";
+
+/**
+ * Summary tree assembler props
+ */
+export interface ISummaryTreeAssemblerProps {
+	/**
+	 * Indicates that this tree is unreferenced. If this is not present, the tree is considered referenced.
+	 */
+	unreferenced?: true;
+}
+
+/**
+ * Summary tree assembler (without stats collection).
+ */
+export class SummaryTreeAssembler {
+	private attachmentCounter: number = 0;
+	private readonly summaryTree: { [path: string]: SummaryObject } = {};
+
+	constructor(private readonly props?: ISummaryTreeAssemblerProps) {}
+
+	/**
+	 * Get final summary
+	 */
+	public get summary(): ISummaryTree {
+		return {
+			type: SummaryType.Tree,
+			tree: { ...this.summaryTree },
+			unreferenced: this.props?.unreferenced,
+		};
+	}
+
+	/**
+	 * Add blob to summary
+	 */
+	public addBlob(key: string, content: string | Uint8Array): void {
+		this.summaryTree[key] = {
+			type: SummaryType.Blob,
+			content,
+		};
+	}
+
+	/**
+	 * Add handle to summary
+	 */
+	public addHandle(
+		key: string,
+		handleType: SummaryType.Tree | SummaryType.Blob | SummaryType.Attachment,
+		handle: string,
+	): void {
+		this.summaryTree[key] = {
+			type: SummaryType.Handle,
+			handleType,
+			handle,
+		};
+	}
+
+	/**
+	 * Add tree to summary
+	 */
+	public addTree(key: string, summary: ISummaryTree): void {
+		this.summaryTree[key] = summary;
+	}
+
+	/**
+	 * Add attachment to summary
+	 */
+	public addAttachment(id: string) {
+		this.summaryTree[this.attachmentCounter++] = { id, type: SummaryType.Attachment };
+	}
+}
+
+/**
+ * Helper function that converts ISnapshotTree and blobs to ISummaryTree
+ * @param snapshot - Source snapshot tree
+ * @param blobs - Blobs cache
+ * @returns Converted snapshot in ISummaryTree format
+ */
+export function convertSnapshotAndBlobsToSummaryTree(
+	snapshot: ISnapshotTree,
+	blobs: Map<string, ArrayBuffer>,
+): ISummaryTree {
+	const assembler = new SummaryTreeAssembler({
+		unreferenced: snapshot.unreferenced,
+	});
+	for (const [path, id] of Object.entries(snapshot.blobs)) {
+		const blob = blobs.get(id);
+		assert(blob !== undefined, 0x2dd /* "Cannot find blob for a given id" */);
+		assembler.addBlob(path, IsoBuffer.from(blob).toString("utf-8"));
+	}
+	for (const [key, tree] of Object.entries(snapshot.trees)) {
+		const subtree = convertSnapshotAndBlobsToSummaryTree(tree, blobs);
+		assembler.addTree(key, subtree);
+	}
+	return assembler.summary;
+}