@fluidframework/routerlicious-driver 1.4.0-115997 → 2.0.0-dev-rc.1.0.0.224419

package/src/documentStorageService.ts

@@ -3,102 +3,110 @@
  * Licensed under the MIT License.
  */
 
-import type { ITelemetryLogger } from "@fluidframework/common-definitions";
+import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
 import {
-    IDocumentStorageService,
-    IDocumentStorageServicePolicies,
-    LoaderCachingPolicy,
+	IDocumentStorageService,
+	IDocumentStorageServicePolicies,
+	LoaderCachingPolicy,
 } from "@fluidframework/driver-definitions";
+import { ISnapshotTree, IVersion } from "@fluidframework/protocol-definitions";
 import {
-    ISnapshotTree,
-    IVersion,
-} from "@fluidframework/protocol-definitions";
-import {
-    GitManager,
-} from "@fluidframework/server-services-client";
-import { DocumentStorageServiceProxy, PrefetchDocumentStorageService } from "@fluidframework/driver-utils";
+	DocumentStorageServiceProxy,
+	PrefetchDocumentStorageService,
+} from "@fluidframework/driver-utils";
 import { IRouterliciousDriverPolicies } from "./policies";
 import { ICache } from "./cache";
 import { WholeSummaryDocumentStorageService } from "./wholeSummaryDocumentStorageService";
 import { ShreddedSummaryDocumentStorageService } from "./shreddedSummaryDocumentStorageService";
+import { GitManager } from "./gitManager";
 import { ISnapshotTreeVersion } from "./definitions";
+import { INormalizedWholeSnapshot } from "./contracts";
 
 export class DocumentStorageService extends DocumentStorageServiceProxy {
-    private _logTailSha: string | undefined = undefined;
+	private _logTailSha: string | undefined = undefined;
 
-    public get logTailSha(): string | undefined {
-        return this._logTailSha;
-    }
+	public get logTailSha(): string | undefined {
+		return this._logTailSha;
+	}
 
-    private static loadInternalDocumentStorageService(
-        id: string,
-        manager: GitManager,
-        logger: ITelemetryLogger,
-        policies: IDocumentStorageServicePolicies,
-        driverPolicies?: IRouterliciousDriverPolicies,
-        blobCache?: ICache<ArrayBufferLike>,
-        snapshotTreeCache?: ICache<ISnapshotTreeVersion>,
-        noCacheGitManager?: GitManager,
-        getStorageManager?: (disableCache?: boolean) => Promise<GitManager>,
-    ): IDocumentStorageService {
-        const storageService = driverPolicies?.enableWholeSummaryUpload ?
-            new WholeSummaryDocumentStorageService(
-                id,
-                manager,
-                logger,
-                policies,
-                driverPolicies,
-                blobCache,
-                snapshotTreeCache,
-                noCacheGitManager,
-                getStorageManager,
-            ) :
-            new ShreddedSummaryDocumentStorageService(
-                id,
-                manager,
-                logger,
-                policies,
-                driverPolicies,
-                blobCache,
-                snapshotTreeCache,
-                getStorageManager,
-            );
-        // TODO: worth prefetching latest summary making version + snapshot call with WholeSummary storage?
-        if (!driverPolicies?.enableWholeSummaryUpload && policies.caching === LoaderCachingPolicy.Prefetch) {
-            return new PrefetchDocumentStorageService(storageService);
-        }
-        return storageService;
-    }
+	private static loadInternalDocumentStorageService(
+		id: string,
+		manager: GitManager,
+		logger: ITelemetryLoggerExt,
+		policies: IDocumentStorageServicePolicies,
+		driverPolicies?: IRouterliciousDriverPolicies,
+		blobCache?: ICache<ArrayBufferLike>,
+		snapshotTreeCache?: ICache<INormalizedWholeSnapshot>,
+		shreddedSummaryTreeCache?: ICache<ISnapshotTreeVersion>,
+		noCacheGitManager?: GitManager,
+		getStorageManager?: (disableCache?: boolean) => Promise<GitManager>,
+	): IDocumentStorageService {
+		const storageService = driverPolicies?.enableWholeSummaryUpload
+			? new WholeSummaryDocumentStorageService(
+					id,
+					manager,
+					logger,
+					policies,
+					driverPolicies,
+					blobCache,
+					snapshotTreeCache,
+					noCacheGitManager,
+					getStorageManager,
+			  )
+			: new ShreddedSummaryDocumentStorageService(
+					id,
+					manager,
+					logger,
+					policies,
+					driverPolicies,
+					blobCache,
+					shreddedSummaryTreeCache,
+					getStorageManager,
+			  );
+		// TODO: worth prefetching latest summary making version + snapshot call with WholeSummary storage?
+		if (
+			!driverPolicies?.enableWholeSummaryUpload &&
+			policies.caching === LoaderCachingPolicy.Prefetch
+		) {
+			return new PrefetchDocumentStorageService(storageService);
+		}
+		return storageService;
+	}
 
-    constructor(
-        public readonly id: string,
-        public manager: GitManager,
-        logger: ITelemetryLogger,
-        policies: IDocumentStorageServicePolicies = {},
-        driverPolicies?: IRouterliciousDriverPolicies,
-        blobCache?: ICache<ArrayBufferLike>,
-        snapshotTreeCache?: ICache<ISnapshotTreeVersion>,
-        public noCacheGitManager?: GitManager,
-        getStorageManager?: (disableCache?: boolean) => Promise<GitManager>,
-    ) {
-        super(DocumentStorageService.loadInternalDocumentStorageService(
-            id,
-            manager,
-            logger,
-            policies,
-            driverPolicies,
-            blobCache,
-            snapshotTreeCache,
-            noCacheGitManager,
-            getStorageManager,
-        ));
-    }
+	constructor(
+		public readonly id: string,
+		public manager: GitManager,
+		logger: ITelemetryLoggerExt,
+		policies: IDocumentStorageServicePolicies,
+		driverPolicies?: IRouterliciousDriverPolicies,
+		blobCache?: ICache<ArrayBufferLike>,
+		snapshotTreeCache?: ICache<INormalizedWholeSnapshot>,
+		shreddedSummaryTreeCache?: ICache<ISnapshotTreeVersion>,
+		public noCacheGitManager?: GitManager,
+		getStorageManager?: (disableCache?: boolean) => Promise<GitManager>,
+	) {
+		super(
+			DocumentStorageService.loadInternalDocumentStorageService(
+				id,
+				manager,
+				logger,
+				policies,
+				driverPolicies,
+				blobCache,
+				snapshotTreeCache,
+				shreddedSummaryTreeCache,
+				noCacheGitManager,
+				getStorageManager,
+			),
+		);
+	}
 
-    public async getSnapshotTree(version?: IVersion): Promise<ISnapshotTree | null> {
-        const tree = await this.internalStorageService.getSnapshotTree(version);
-        if (tree !== null) {
-            this._logTailSha = ".logTail" in tree.trees ? tree.trees[".logTail"].blobs.logTail : undefined;
-        }
-        return tree;
-    }
+	public async getSnapshotTree(version?: IVersion): Promise<ISnapshotTree | null> {
+		const tree = await this.internalStorageService.getSnapshotTree(version);
+		if (tree !== null) {
+			this._logTailSha =
+				".logTail" in tree.trees ? tree.trees[".logTail"].blobs.logTail : undefined;
+		}
+		return tree;
+	}
 }

package/src/errorUtils.ts

@@ -3,17 +3,57 @@
  * Licensed under the MIT License.
  */
 
-import { DriverError } from "@fluidframework/driver-definitions";
 import {
-    NonRetryableError,
-    GenericNetworkError,
-    createGenericNetworkError,
-    AuthorizationError,
+	DriverError,
+	IDriverErrorBase,
+	DriverErrorTypes,
+} from "@fluidframework/driver-definitions";
+import {
+	NonRetryableError,
+	GenericNetworkError,
+	createGenericNetworkError,
+	AuthorizationError,
 } from "@fluidframework/driver-utils";
+import { IFluidErrorBase } from "@fluidframework/telemetry-utils";
 import { pkgVersion as driverVersion } from "./packageVersion";
 
-export enum R11sErrorType {
-    fileNotFoundOrAccessDeniedError = "fileNotFoundOrAccessDeniedError",
+/**
+ * Routerlicious Error types
+ * Different error types that may be thrown by the routerlicious driver
+ * @internal
+ */
+export const RouterliciousErrorTypes = {
+	// Inherit base driver error types
+	...DriverErrorTypes,
+
+	/**
+	 * SSL Certificate Error.
+	 */
+	sslCertError: "sslCertError",
+} as const;
+/**
+ * @internal
+ */
+export type RouterliciousErrorTypes =
+	(typeof RouterliciousErrorTypes)[keyof typeof RouterliciousErrorTypes];
+
+/**
+ * Routerlicious Error types
+ * Different error types that may be thrown by the routerlicious driver
+ *
+ * @deprecated Use {@link (RouterliciousErrorTypes:variable)} instead.
+ * @internal
+ */
+export enum RouterliciousErrorType {
+	/**
+	 * File not found, or file deleted during session
+	 */
+	fileNotFoundOrAccessDeniedError = "fileNotFoundOrAccessDeniedError",
+
+	/**
+	 * SSL Certificate Error.
+	 */
+	sslCertError = "sslCertError",
 }
 
 /**
@@ -21,96 +61,94 @@ export enum R11sErrorType {
  * Intended to be compatible with output from {@link NetworkError.toJSON}
  */
 export interface IR11sSocketError {
-    /**
-     * An error code number for the error that occurred.
-     * It will be a valid HTTP status code.
-     */
-    code: number;
+	/**
+	 * An error code number for the error that occurred.
+	 * It will be a valid HTTP status code.
+	 */
+	code: number;
 
-    /**
-     * A message about the error that occurred for debugging / logging purposes.
-     * This should not be displayed to the user directly.
-     */
-    message: string;
+	/**
+	 * A message about the error that occurred for debugging / logging purposes.
+	 * This should not be displayed to the user directly.
+	 */
+	message: string;
 
-    /**
-     * Optional Retry-After time in seconds.
-     * The client should wait this many seconds before retrying its request.
-     */
-    retryAfter?: number;
+	/**
+	 * Optional Retry-After time in seconds.
+	 * The client should wait this many seconds before retrying its request.
+	 */
+	retryAfter?: number;
 
-    /**
-     * Optional Retry-After time in milliseconds.
-     * The client should wait this many milliseconds before retrying its request.
-     */
-    retryAfterMs?: number;
+	/**
+	 * Optional Retry-After time in milliseconds.
+	 * The client should wait this many milliseconds before retrying its request.
+	 */
+	retryAfterMs?: number;
 }
 
-export interface IR11sError {
-    readonly errorType: R11sErrorType;
-    readonly message: string;
-    canRetry: boolean;
+export interface IR11sError extends Omit<IDriverErrorBase, "errorType"> {
+	readonly errorType: RouterliciousErrorType;
 }
 
 export type R11sError = DriverError | IR11sError;
 
 export function createR11sNetworkError(
-    errorMessage: string,
-    statusCode?: number,
-    retryAfterMs?: number,
-): R11sError {
-    const props = { statusCode, driverVersion };
-    switch (statusCode) {
-        case undefined:
-            // If a service is temporarily down or a browser resource limit is reached, RestWrapper will throw
-            // a network error with no status code (e.g. err:ERR_CONN_REFUSED or err:ERR_FAILED) and
-            // the error message will start with NetworkError as defined in restWrapper.ts
-            return new GenericNetworkError(
-                errorMessage, errorMessage.startsWith("NetworkError"), props);
-        case 401:
-            // The first 401 is manually retried in RouterliciousRestWrapper with a refreshed token,
-            // so we treat repeat 401s the same as 403.
-        case 403:
-            return new AuthorizationError(
-                errorMessage, undefined, undefined, props);
-        case 404:
-            const errorType = R11sErrorType.fileNotFoundOrAccessDeniedError;
-            return new NonRetryableError(errorMessage, errorType, props);
-        case 429:
-            return createGenericNetworkError(
-                errorMessage, { canRetry: true, retryAfterMs }, props);
-        case 500:
-        case 502:
-            return new GenericNetworkError(errorMessage, true, props);
-        default:
-            const retryInfo = { canRetry: retryAfterMs !== undefined, retryAfterMs };
-            return createGenericNetworkError(errorMessage, retryInfo, props);
-    }
+	errorMessage: string,
+	statusCode: number,
+	retryAfterMs?: number,
+): IFluidErrorBase & R11sError {
+	let error: IFluidErrorBase & R11sError;
+	const props = { statusCode, driverVersion };
+	switch (statusCode) {
+		case 401:
+		// The first 401 is manually retried in RouterliciousRestWrapper with a refreshed token,
+		// so we treat repeat 401s the same as 403.
+		case 403:
+			error = new AuthorizationError(errorMessage, undefined, undefined, props);
+			break;
+		case 404:
+			const errorType = RouterliciousErrorType.fileNotFoundOrAccessDeniedError;
+			error = new NonRetryableError(errorMessage, errorType, props);
+			break;
+		case 429:
+			error = createGenericNetworkError(
+				errorMessage,
+				{ canRetry: true, retryAfterMs },
+				props,
+			);
+			break;
+		case 500:
+		case 502:
+			error = new GenericNetworkError(errorMessage, true, props);
+			break;
+		default:
+			const retryInfo = { canRetry: retryAfterMs !== undefined, retryAfterMs };
+			error = createGenericNetworkError(errorMessage, retryInfo, props);
+			break;
+	}
+	error.addTelemetryProperties({ endpointReached: true });
+	return error;
 }
 
 export function throwR11sNetworkError(
-    errorMessage: string,
-    statusCode?: number,
-    retryAfterMs?: number,
+	errorMessage: string,
+	statusCode: number,
+	retryAfterMs?: number,
 ): never {
-    const networkError = createR11sNetworkError(
-        errorMessage,
-        statusCode,
-        retryAfterMs);
+	const networkError = createR11sNetworkError(errorMessage, statusCode, retryAfterMs);
 
-    // eslint-disable-next-line @typescript-eslint/no-throw-literal
-    throw networkError;
+	// eslint-disable-next-line @typescript-eslint/no-throw-literal
+	throw networkError;
 }
 
 /**
  * Returns network error based on error object from R11s socket (IR11sSocketError)
  */
-export function errorObjectFromSocketError(socketError: IR11sSocketError, handler: string): R11sError {
-    // pre-0.58 error message prefix: R11sSocketError
-    const message = `R11s socket error (${handler}): ${socketError.message}`;
-    return createR11sNetworkError(
-        message,
-        socketError.code,
-        socketError.retryAfterMs,
-    );
+export function errorObjectFromSocketError(
+	socketError: IR11sSocketError,
+	handler: string,
+): R11sError {
+	// pre-0.58 error message prefix: R11sSocketError
+	const message = `R11s socket error (${handler}): ${socketError.message}`;
+	return createR11sNetworkError(message, socketError.code, socketError.retryAfterMs);
 }

package/src/gitManager.ts

@@ -0,0 +1,67 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import * as resources from "@fluidframework/gitresources";
+import {
+	IWholeSummaryPayload,
+	IWriteSummaryResponse,
+} from "@fluidframework/server-services-client";
+import { IGitManager, IHistorian } from "./storageContracts";
+import { IR11sResponse } from "./restWrapper";
+import { IWholeFlatSnapshot } from "./contracts";
+
+export class GitManager implements IGitManager {
+	constructor(private readonly historian: IHistorian) {}
+
+	/**
+	 * Reads the object with the given ID. We defer to the client implementation to do the actual read.
+	 */
+	public async getCommits(
+		sha: string,
+		count: number,
+	): Promise<IR11sResponse<resources.ICommitDetails[]>> {
+		return this.historian.getCommits(sha, count);
+	}
+
+	/**
+	 * Reads the object with the given ID. We defer to the client implementation to do the actual read.
+	 */
+	public async getTree(root: string, recursive = true): Promise<IR11sResponse<resources.ITree>> {
+		return this.historian.getTree(root, recursive);
+	}
+
+	public async getBlob(sha: string): Promise<IR11sResponse<resources.IBlob>> {
+		return this.historian.getBlob(sha);
+	}
+
+	public async createBlob(
+		content: string,
+		encoding: "utf-8" | "base64",
+	): Promise<IR11sResponse<resources.ICreateBlobResponse>> {
+		const blob: resources.ICreateBlobParams = {
+			content,
+			encoding,
+		};
+		return this.historian.createBlob(blob);
+	}
+
+	public async createGitTree(
+		params: resources.ICreateTreeParams,
+	): Promise<IR11sResponse<resources.ITree>> {
+		const treeP = this.historian.createTree(params);
+		return treeP;
+	}
+
+	public async createSummary(
+		summary: IWholeSummaryPayload,
+		initial: boolean = false,
+	): Promise<IR11sResponse<IWriteSummaryResponse>> {
+		return this.historian.createSummary(summary, initial);
+	}
+
+	public async getSnapshot(sha: string): Promise<IR11sResponse<IWholeFlatSnapshot>> {
+		return this.historian.getSnapshot(sha);
+	}
+}

package/src/historian.ts

@@ -0,0 +1,121 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { fromUtf8ToBase64 } from "@fluid-internal/client-utils";
+import * as git from "@fluidframework/gitresources";
+import {
+	IWholeSummaryPayload,
+	IWriteSummaryResponse,
+} from "@fluidframework/server-services-client";
+import { QueryStringType, RestWrapper } from "./restWrapperBase";
+import { IR11sResponse } from "./restWrapper";
+import { IHistorian } from "./storageContracts";
+import { IWholeFlatSnapshot } from "./contracts";
+
+export interface ICredentials {
+	user: string;
+	password: string;
+}
+
+export const getAuthorizationTokenFromCredentials = (credentials: ICredentials): string =>
+	`Basic ${fromUtf8ToBase64(`${credentials.user}:${credentials.password}`)}`;
+
+/**
+ * Implementation of the IHistorian interface that calls out to a REST interface
+ */
+export class Historian implements IHistorian {
+	private readonly defaultQueryString: QueryStringType = {};
+	private readonly cacheBust: boolean;
+
+	constructor(
+		private readonly historianApi: boolean,
+		disableCache: boolean,
+		private readonly restWrapper: RestWrapper,
+	) {
+		if (disableCache && this.historianApi) {
+			this.defaultQueryString.disableCache = disableCache;
+			this.cacheBust = false;
+		} else {
+			this.cacheBust = disableCache;
+		}
+	}
+
+	public async getBlob(sha: string): Promise<IR11sResponse<git.IBlob>> {
+		return this.restWrapper.get<git.IBlob>(
+			`/git/blobs/${encodeURIComponent(sha)}`,
+			this.getQueryString(),
+		);
+	}
+
+	public async createBlob(
+		blob: git.ICreateBlobParams,
+	): Promise<IR11sResponse<git.ICreateBlobResponse>> {
+		return this.restWrapper.post<git.ICreateBlobResponse>(
+			`/git/blobs`,
+			blob,
+			this.getQueryString(),
+		);
+	}
+
+	public async getCommits(
+		sha: string,
+		count: number,
+	): Promise<IR11sResponse<git.ICommitDetails[]>> {
+		return this.restWrapper
+			.get<git.ICommitDetails[]>(`/commits`, this.getQueryString({ count, sha }))
+			.catch(async (error) =>
+				error.statusCode === 400 || error.statusCode === 404
+					? {
+							content: [],
+							headers: new Map(),
+							propsToLog: {},
+							requestUrl: "",
+					  }
+					: Promise.reject<IR11sResponse<git.ICommitDetails[]>>(error),
+			);
+	}
+
+	public async createTree(tree: git.ICreateTreeParams): Promise<IR11sResponse<git.ITree>> {
+		return this.restWrapper.post<git.ITree>(`/git/trees`, tree, this.getQueryString());
+	}
+
+	public async getTree(sha: string, recursive: boolean): Promise<IR11sResponse<git.ITree>> {
+		return this.restWrapper.get<git.ITree>(
+			`/git/trees/${encodeURIComponent(sha)}`,
+			this.getQueryString({ recursive: recursive ? 1 : 0 }),
+		);
+	}
+	public async createSummary(
+		summary: IWholeSummaryPayload,
+		initial?: boolean,
+	): Promise<IR11sResponse<IWriteSummaryResponse>> {
+		return this.restWrapper.post<IWriteSummaryResponse>(
+			`/git/summaries`,
+			summary,
+			this.getQueryString(initial !== undefined ? { initial } : undefined),
+		);
+	}
+
+	public async getSnapshot(sha: string): Promise<IR11sResponse<IWholeFlatSnapshot>> {
+		return this.restWrapper.get<IWholeFlatSnapshot>(
+			`/git/summaries/${sha}`,
+			this.getQueryString(),
+		);
+	}
+
+	private getQueryString(queryString?: QueryStringType): QueryStringType {
+		if (this.cacheBust) {
+			return {
+				cacheBust: Date.now(),
+				...this.defaultQueryString,
+				...queryString,
+			};
+		}
+		return {
+			...this.defaultQueryString,
+			...queryString,
+		};
+	}
+}

package/src/index.ts

@@ -3,11 +3,18 @@
  * Licensed under the MIT License.
  */
 
-export * from "./defaultTokenProvider";
-export * from "./deltaStorageService";
-export * from "./documentService";
-export * from "./documentServiceFactory";
-export * from "./documentStorageService";
-export * from "./nullBlobStorageService";
-export * from "./policies";
-export * from "./tokens";
+// Tokens
+export { DefaultTokenProvider } from "./defaultTokenProvider";
+export { ITokenProvider, ITokenResponse, ITokenService } from "./tokens";
+
+// Errors
+export { RouterliciousErrorType, RouterliciousErrorTypes } from "./errorUtils";
+
+// Factory
+export {
+	DocumentPostCreateError,
+	RouterliciousDocumentServiceFactory,
+} from "./documentServiceFactory";
+
+// Configuration
+export { IRouterliciousDriverPolicies } from "./policies";