@fluidframework/container-loader 2.0.0-dev.4.4.0.162574 → 2.0.0-dev.5.3.2.178189

package/src/deltaManager.ts

@@ -5,12 +5,8 @@
 
 import { default as AbortController } from "abort-controller";
 import { v4 as uuid } from "uuid";
-import {
-	ITelemetryLogger,
-	IEventProvider,
-	ITelemetryProperties,
-	ITelemetryErrorEvent,
-} from "@fluidframework/common-definitions";
+import { IEventProvider } from "@fluidframework/common-definitions";
+import { ITelemetryProperties, ITelemetryErrorEvent } from "@fluidframework/core-interfaces";
 import {
 	IDeltaHandlerStrategy,
 	IDeltaManager,
@@ -21,7 +17,13 @@ import {
 	IConnectionDetailsInternal,
 } from "@fluidframework/container-definitions";
 import { assert, TypedEventEmitter } from "@fluidframework/common-utils";
-import { normalizeError, logIfFalse, safeRaiseEvent } from "@fluidframework/telemetry-utils";
+import {
+	normalizeError,
+	logIfFalse,
+	safeRaiseEvent,
+	isFluidError,
+	ITelemetryLoggerExt,
+} from "@fluidframework/telemetry-utils";
 import {
 	IDocumentDeltaStorageService,
 	IDocumentService,
@@ -41,6 +43,7 @@ import {
 	DataCorruptionError,
 	extractSafePropertiesFromMessage,
 	DataProcessingError,
+	UsageError,
 } from "@fluidframework/container-utils";
 import { IConnectionManagerFactoryArgs, IConnectionManager } from "./contracts";
 import { DeltaQueue } from "./deltaQueue";
@@ -60,6 +63,15 @@ export interface IDeltaManagerInternalEvents extends IDeltaManagerEvents {
 	(event: "throttled", listener: (error: IThrottlingWarning) => void);
 	(event: "closed" | "disposed", listener: (error?: ICriticalContainerError) => void);
 	(event: "connect", listener: (details: IConnectionDetailsInternal, opsBehind?: number) => void);
+	(event: "establishingConnection", listener: (reason: string) => void);
+	(event: "cancelEstablishingConnection", listener: (reason: string) => void);
+}
+
+/**
+ * Batching makes assumptions about what might be on the metadata. This interface codifies those assumptions, but does not validate them.
+ */
+interface IBatchMetadata {
+	batch?: boolean;
 }
 
 /**
@@ -285,13 +297,16 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 
 		if (batch.length === 1) {
 			assert(
-				batch[0].metadata?.batch === undefined,
+				(batch[0].metadata as IBatchMetadata)?.batch === undefined,
 				0x3c9 /* no batch markup on single message */,
 			);
 		} else {
-			assert(batch[0].metadata?.batch === true, 0x3ca /* no start batch markup */);
 			assert(
-				batch[batch.length - 1].metadata?.batch === false,
+				(batch[0].metadata as IBatchMetadata)?.batch === true,
+				0x3ca /* no start batch markup */,
+			);
+			assert(
+				(batch[batch.length - 1].metadata as IBatchMetadata)?.batch === false,
 				0x3cb /* no end batch markup */,
 			);
 		}
@@ -340,7 +355,7 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 
 	constructor(
 		private readonly serviceProvider: () => IDocumentService | undefined,
-		private readonly logger: ITelemetryLogger,
+		private readonly logger: ITelemetryLoggerExt,
 		private readonly _active: () => boolean,
 		createConnectionManager: (props: IConnectionManagerFactoryArgs) => TConnectionManager,
 	) {
@@ -365,6 +380,8 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 			pongHandler: (latency: number) => this.emit("pong", latency),
 			readonlyChangeHandler: (readonly?: boolean) =>
 				safeRaiseEvent(this, this.logger, "readonly", readonly),
+			establishConnectionHandler: (reason: string) => this.establishingConnection(reason),
+			cancelConnectionHandler: (reason: string) => this.cancelEstablishingConnection(reason),
 		};
 
 		this.connectionManager = createConnectionManager(props);
@@ -404,6 +421,14 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 		// - inbound & inboundSignal are resumed in attachOpHandler() when we have handler setup
 	}
 
+	private cancelEstablishingConnection(reason: string) {
+		this.emit("cancelEstablishingConnection", reason);
+	}
+
+	private establishingConnection(reason: string) {
+		this.emit("establishingConnection", reason);
+	}
+
 	private connectHandler(connection: IConnectionDetailsInternal) {
 		this.refreshDelayInfo(this.deltaStreamDelayId);
 
@@ -453,10 +478,6 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 		}
 	}
 
-	public dispose() {
-		throw new Error("Not implemented.");
-	}
-
 	/**
 	 * Sets the sequence number from which inbound messages should be returned
 	 */
@@ -644,23 +665,51 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 	/**
 	 * Closes the connection and clears inbound & outbound queues.
 	 *
-	 * @param doDispose - should the DeltaManager treat this close call as a dispose?
-	 * Differences between close and dispose:
-	 * - dispose will emit "disposed" event while close emits "closed"
-	 * - dispose will remove all listeners
-	 * - dispose can be called after closure, but not vis versa
+	 * Differences from dispose:
+	 * - close will trigger readonly notification
+	 * - close emits "closed"
+	 * - close cannot be called after dispose
 	 */
-	public close(error?: ICriticalContainerError, doDispose?: boolean): void {
+	public close(error?: ICriticalContainerError): void {
 		if (this._closed) {
-			if (doDispose === true) {
-				this.disposeInternal(error);
-			}
 			return;
 		}
 		this._closed = true;
 
-		this.connectionManager.dispose(error, doDispose !== true);
+		this.connectionManager.dispose(error, true /* switchToReadonly */);
+		this.clearQueues();
+		this.emit("closed", error);
+	}
 
+	/**
+	 * Disposes the connection and clears the inbound & outbound queues.
+	 *
+	 * Differences from close:
+	 * - dispose will emit "disposed"
+	 * - dispose will remove all listeners
+	 * - dispose can be called after closure
+	 */
+	public dispose(error?: Error | ICriticalContainerError): void {
+		if (this._disposed) {
+			return;
+		}
+		if (error !== undefined && !isFluidError(error)) {
+			throw new UsageError("Error must be a Fluid error");
+		}
+
+		this._disposed = true;
+		this._closed = true; // We consider "disposed" as a further state than "closed"
+
+		this.connectionManager.dispose(error, false /* switchToReadonly */);
+		this.clearQueues();
+
+		// This needs to be the last thing we do (before removing listeners), as it causes
+		// Container to dispose context and break ability of data stores / runtime to "hear" from delta manager.
+		this.emit("disposed", error);
+		this.removeAllListeners();
+	}
+
+	private clearQueues() {
 		this.closeAbortController.abort();
 
 		this._inbound.clear();
@@ -673,26 +722,6 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 
 		// Drop pending messages - this will ensure catchUp() does not go into infinite loop
 		this.pending = [];
-
-		if (doDispose === true) {
-			this.disposeInternal(error);
-		} else {
-			this.emit("closed", error);
-			this.disposeInternal(error); // ! TODO: remove this call when Container close no longer disposes
-		}
-	}
-
-	private disposeInternal(error?: ICriticalContainerError): void {
-		if (this._disposed) {
-			return;
-		}
-		this._disposed = true;
-
-		// This needs to be the last thing we do (before removing listeners), as it causes
-		// Container to dispose context and break ability of data stores / runtime to "hear"
-		// from delta manager, including notification (above) about readonly state.
-		this.emit("disposed", error);
-		this.removeAllListeners();
 	}
 
 	public refreshDelayInfo(id: string) {

package/src/deltaQueue.ts

@@ -20,8 +20,8 @@ export class DeltaQueue<T>
 	private readonly q = new Deque<T>();
 
 	/**
-	 * Tracks the number of pause requests for the queue
-	 * The DeltaQueue is create initially paused.
+	 * Tracks the number of pause requests for the queue.
+	 * The DeltaQueue is created initially paused.
 	 */
 	private pauseCount = 1;
 
@@ -58,7 +58,6 @@ export class DeltaQueue<T>
 
 	/**
 	 * @param worker - A callback to process a delta.
-	 * @param logger - For logging telemetry.
 	 */
 	constructor(private readonly worker: (delta: T) => void) {
 		super();

package/src/disposal.ts

@@ -0,0 +1,25 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IDisposable } from "@fluidframework/common-definitions";
+
+/**
+ * Returns a wrapper around the provided function, which will only invoke the inner function if the provided
+ * {@link @fluidframework/common-definitions#IDisposable | disposable} object has not yet been disposed.
+ *
+ * @throws Will throw an error if the item has already been disposed.
+ */
+export function doIfNotDisposed<T>(
+	disposable: IDisposable,
+	f: (...args: any[]) => T,
+): (...args: any[]) => T {
+	return (...args: any[]): T => {
+		if (disposable.disposed) {
+			throw new Error("Already disposed");
+		} else {
+			return f(...args);
+		}
+	};
+}

package/src/index.ts

@@ -4,14 +4,7 @@
  */
 
 export { ConnectionState } from "./connectionState";
-export {
-	IContainerConfig,
-	IContainerExperimental,
-	IContainerLoadOptions,
-	IPendingContainerState,
-	waitContainerToCatchUp,
-} from "./container";
-export { ISerializableBlobContents } from "./containerStorageAdapter";
+export { IContainerExperimental, waitContainerToCatchUp } from "./container";
 export {
 	ICodeDetailsLoader,
 	IDetachedBlobStorage,

package/src/loader.ts

@@ -4,8 +4,19 @@
  */
 
 import { v4 as uuid } from "uuid";
-import { ITelemetryBaseLogger, ITelemetryLogger } from "@fluidframework/common-definitions";
 import {
+	ITelemetryLoggerExt,
+	ChildLogger,
+	DebugLogger,
+	IConfigProviderBase,
+	loggerToMonitoringContext,
+	mixinMonitoringContext,
+	MonitoringContext,
+	PerformanceEvent,
+	sessionStorageConfigProvider,
+} from "@fluidframework/telemetry-utils";
+import {
+	ITelemetryBaseLogger,
 	FluidObject,
 	IFluidRouter,
 	IRequest,
@@ -22,24 +33,13 @@ import {
 	IProvideFluidCodeDetailsComparer,
 	IFluidCodeDetails,
 } from "@fluidframework/container-definitions";
-import {
-	ChildLogger,
-	DebugLogger,
-	IConfigProviderBase,
-	loggerToMonitoringContext,
-	mixinMonitoringContext,
-	MonitoringContext,
-	PerformanceEvent,
-	sessionStorageConfigProvider,
-} from "@fluidframework/telemetry-utils";
 import {
 	IDocumentServiceFactory,
 	IDocumentStorageService,
-	IFluidResolvedUrl,
+	IResolvedUrl,
 	IUrlResolver,
 } from "@fluidframework/driver-definitions";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
-import { ensureFluidResolvedUrl } from "@fluidframework/driver-utils";
 import { Container, IPendingContainerState } from "./container";
 import { IParsedUrl, parseUrl } from "./utils";
 import { pkgVersion } from "./packageVersion";
@@ -53,8 +53,15 @@ function canUseCache(request: IRequest): boolean {
 	return request.headers[LoaderHeader.cache] !== false;
 }
 
+function ensureResolvedUrlDefined(
+	resolved: IResolvedUrl | undefined,
+): asserts resolved is IResolvedUrl {
+	if (resolved === undefined) {
+		throw new Error(`Object is not a IResolveUrl.`);
+	}
+}
 /**
- * @deprecated - In the next release RelativeLoader will no longer be exported. It is an internal class that should not be used directly.
+ * @internal
  */
 export class RelativeLoader implements ILoader {
 	constructor(
@@ -71,15 +78,18 @@ export class RelativeLoader implements ILoader {
 			if (canUseCache(request)) {
 				return this.container;
 			} else {
-				const resolvedUrl = this.container.resolvedUrl;
-				ensureFluidResolvedUrl(resolvedUrl);
-				const container = await Container.load(this.loader as Loader, {
-					canReconnect: request.headers?.[LoaderHeader.reconnect],
-					clientDetailsOverride: request.headers?.[LoaderHeader.clientDetails],
-					resolvedUrl: { ...resolvedUrl },
-					version: request.headers?.[LoaderHeader.version] ?? undefined,
-					loadMode: request.headers?.[LoaderHeader.loadMode],
-				});
+				ensureResolvedUrlDefined(this.container.resolvedUrl);
+				const container = await this.container.clone(
+					{
+						resolvedUrl: { ...this.container.resolvedUrl },
+						version: request.headers?.[LoaderHeader.version] ?? undefined,
+						loadMode: request.headers?.[LoaderHeader.loadMode],
+					},
+					{
+						canReconnect: request.headers?.[LoaderHeader.reconnect],
+						clientDetailsOverride: request.headers?.[LoaderHeader.clientDetails],
+					},
+				);
 				return container;
 			}
 		}
@@ -237,12 +247,18 @@ export interface ILoaderServices {
 	/**
 	 * The logger downstream consumers should construct their loggers from
 	 */
-	readonly subLogger: ITelemetryLogger;
+	readonly subLogger: ITelemetryLoggerExt;
 
 	/**
 	 * Blobs storage for detached containers.
 	 */
 	readonly detachedBlobStorage?: IDetachedBlobStorage;
+
+	/**
+	 * Optional property for allowing the container to use a custom
+	 * protocol implementation for handling the quorum and/or the audience.
+	 */
+	readonly protocolHandlerBuilder?: ProtocolHandlerBuilder;
 }
 
 /**
@@ -266,7 +282,7 @@ export async function requestResolvedObjectFromContainer(
 	container: IContainer,
 	headers?: IRequestHeader,
 ): Promise<IResponse> {
-	ensureFluidResolvedUrl(container.resolvedUrl);
+	ensureResolvedUrlDefined(container.resolvedUrl);
 	const parsedUrl = parseUrl(container.resolvedUrl.url);
 
 	if (parsedUrl === undefined) {
@@ -289,37 +305,45 @@ export class Loader implements IHostLoader {
 	private readonly containers = new Map<string, Promise<Container>>();
 	public readonly services: ILoaderServices;
 	private readonly mc: MonitoringContext;
-	private readonly protocolHandlerBuilder: ProtocolHandlerBuilder | undefined;
 
 	constructor(loaderProps: ILoaderProps) {
-		const scope: FluidObject<ILoader> = { ...loaderProps.scope };
-		if (loaderProps.options?.provideScopeLoader !== false) {
-			scope.ILoader = this;
-		}
+		const {
+			urlResolver,
+			documentServiceFactory,
+			codeLoader,
+			options,
+			scope,
+			logger,
+			detachedBlobStorage,
+			configProvider,
+			protocolHandlerBuilder,
+		} = loaderProps;
+
 		const telemetryProps = {
 			loaderId: uuid(),
 			loaderVersion: pkgVersion,
 		};
 
 		const subMc = mixinMonitoringContext(
-			DebugLogger.mixinDebugLogger("fluid:telemetry", loaderProps.logger, {
+			DebugLogger.mixinDebugLogger("fluid:telemetry", logger, {
 				all: telemetryProps,
 			}),
 			sessionStorageConfigProvider.value,
-			loaderProps.configProvider,
+			configProvider,
 		);
 
 		this.services = {
-			urlResolver: loaderProps.urlResolver,
-			documentServiceFactory: loaderProps.documentServiceFactory,
-			codeLoader: loaderProps.codeLoader,
-			options: loaderProps.options ?? {},
-			scope,
+			urlResolver,
+			documentServiceFactory,
+			codeLoader,
+			options: options ?? {},
+			scope:
+				options?.provideScopeLoader !== false ? { ...scope, ILoader: this } : { ...scope },
+			detachedBlobStorage,
+			protocolHandlerBuilder,
 			subLogger: subMc.logger,
-			detachedBlobStorage: loaderProps.detachedBlobStorage,
 		};
 		this.mc = loggerToMonitoringContext(ChildLogger.create(this.services.subLogger, "Loader"));
-		this.protocolHandlerBuilder = loaderProps.protocolHandlerBuilder;
 	}
 
 	public get IFluidRouter(): IFluidRouter {
@@ -327,15 +351,11 @@ export class Loader implements IHostLoader {
 	}
 
 	public async createDetachedContainer(codeDetails: IFluidCodeDetails): Promise<IContainer> {
-		const container = await Container.createDetached(
-			this,
-			codeDetails,
-			this.protocolHandlerBuilder,
-		);
+		const container = await Container.createDetached(this.services, codeDetails);
 
 		if (this.cachingEnabled) {
 			container.once("attached", () => {
-				ensureFluidResolvedUrl(container.resolvedUrl);
+				ensureResolvedUrlDefined(container.resolvedUrl);
 				const parsedUrl = parseUrl(container.resolvedUrl.url);
 				if (parsedUrl !== undefined) {
 					this.addToContainerCache(parsedUrl.id, Promise.resolve(container));
@@ -347,7 +367,7 @@ export class Loader implements IHostLoader {
 	}
 
 	public async rehydrateDetachedContainerFromSnapshot(snapshot: string): Promise<IContainer> {
-		return Container.rehydrateDetachedFromSnapshot(this, snapshot, this.protocolHandlerBuilder);
+		return Container.rehydrateDetachedFromSnapshot(this.services, snapshot);
 	}
 
 	public async resolve(request: IRequest, pendingLocalState?: string): Promise<IContainer> {
@@ -404,7 +424,7 @@ export class Loader implements IHostLoader {
 		pendingLocalState?: IPendingContainerState,
 	): Promise<{ container: Container; parsed: IParsedUrl }> {
 		const resolvedAsFluid = await this.services.urlResolver.resolve(request);
-		ensureFluidResolvedUrl(resolvedAsFluid);
+		ensureResolvedUrlDefined(resolvedAsFluid);
 
 		// Parse URL into data stores
 		const parsed = parseUrl(resolvedAsFluid.url);
@@ -423,11 +443,18 @@ export class Loader implements IHostLoader {
 			}
 		}
 
-		const { canCache, fromSequenceNumber } = this.parseHeader(parsed, request);
-		const shouldCache = pendingLocalState !== undefined ? false : canCache;
+		request.headers ??= {};
+		// If set in both query string and headers, use query string.  Also write the value from the query string into the header either way.
+		request.headers[LoaderHeader.version] =
+			parsed.version ?? request.headers[LoaderHeader.version];
+		const canCache =
+			this.cachingEnabled &&
+			request.headers[LoaderHeader.cache] !== false &&
+			pendingLocalState === undefined;
+		const fromSequenceNumber = request.headers[LoaderHeader.sequenceNumber] ?? -1;
 
 		let container: Container;
-		if (shouldCache) {
+		if (canCache) {
 			const key = this.getKeyForContainerCache(request, parsed);
 			const maybeContainer = await this.containers.get(key);
 			if (maybeContainer !== undefined) {
@@ -461,48 +488,23 @@ export class Loader implements IHostLoader {
 		return this.services.options.cache !== false;
 	}
 
-	private canCacheForRequest(headers: IRequestHeader): boolean {
-		return this.cachingEnabled && headers[LoaderHeader.cache] !== false;
-	}
-
-	private parseHeader(parsed: IParsedUrl, request: IRequest) {
-		let fromSequenceNumber = -1;
-
-		request.headers = request.headers ?? {};
-
-		const headerSeqNum = request.headers[LoaderHeader.sequenceNumber];
-		if (headerSeqNum !== undefined) {
-			fromSequenceNumber = headerSeqNum;
-		}
-
-		// If set in both query string and headers, use query string
-		request.headers[LoaderHeader.version] =
-			parsed.version ?? request.headers[LoaderHeader.version];
-
-		const canCache = this.canCacheForRequest(request.headers);
-
-		return {
-			canCache,
-			fromSequenceNumber,
-		};
-	}
-
 	private async loadContainer(
 		request: IRequest,
-		resolved: IFluidResolvedUrl,
+		resolvedUrl: IResolvedUrl,
 		pendingLocalState?: IPendingContainerState,
 	): Promise<Container> {
 		return Container.load(
-			this,
 			{
-				canReconnect: request.headers?.[LoaderHeader.reconnect],
-				clientDetailsOverride: request.headers?.[LoaderHeader.clientDetails],
-				resolvedUrl: resolved,
+				resolvedUrl,
 				version: request.headers?.[LoaderHeader.version] ?? undefined,
 				loadMode: request.headers?.[LoaderHeader.loadMode],
+				pendingLocalState,
+			},
+			{
+				canReconnect: request.headers?.[LoaderHeader.reconnect],
+				clientDetailsOverride: request.headers?.[LoaderHeader.clientDetails],
+				...this.services,
 			},
-			pendingLocalState,
-			this.protocolHandlerBuilder,
 		);
 	}
 }