@fluidframework/container-loader 2.0.0-internal.5.3.2 → 2.0.0-internal.6.0.0

package/src/contracts.ts

@@ -5,19 +5,20 @@
 
 import { ITelemetryProperties } from "@fluidframework/core-interfaces";
 import {
-	IDeltaQueue,
-	ReadOnlyInfo,
-	IConnectionDetailsInternal,
+	IConnectionDetails,
 	ICriticalContainerError,
+	IDeltaQueue,
 	IFluidCodeDetails,
 	isFluidPackage,
+	ReadOnlyInfo,
 } from "@fluidframework/container-definitions";
 import {
 	ConnectionMode,
-	IDocumentMessage,
-	ISequencedDocumentMessage,
 	IClientConfiguration,
 	IClientDetails,
+	IDocumentMessage,
+	ISequencedDocumentMessage,
+	ISignalClient,
 	ISignalMessage,
 } from "@fluidframework/protocol-definitions";
 import { IAnyDriverError, IContainerPackageInfo } from "@fluidframework/driver-definitions";
@@ -28,6 +29,16 @@ export enum ReconnectMode {
 	Enabled = "Enabled",
 }
 
+/**
+ * Internal version of IConnectionDetails with props are only exposed internally
+ */
+export interface IConnectionDetailsInternal extends IConnectionDetails {
+	mode: ConnectionMode;
+	version: string;
+	initialClients: ISignalClient[];
+	reason: string;
+}
+
 /**
  * Connection manager (implements this interface) is responsible for maintaining connection
  * to relay service.

package/src/debugLogger.ts

@@ -0,0 +1,113 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	ITelemetryBaseEvent,
+	ITelemetryBaseLogger,
+	ITelemetryProperties,
+} from "@fluidframework/core-interfaces";
+import { performance } from "@fluidframework/common-utils";
+import { debug as registerDebug, IDebugger } from "debug";
+import {
+	ITelemetryLoggerExt,
+	ITelemetryLoggerPropertyBags,
+	createMultiSinkLogger,
+	eventNamespaceSeparator,
+	formatTick,
+} from "@fluidframework/telemetry-utils";
+
+/**
+ * Implementation of debug logger
+ */
+export class DebugLogger implements ITelemetryBaseLogger {
+	/**
+	 * Mix in debug logger with another logger.
+	 * Returned logger will output events to both newly created debug logger, as well as base logger
+	 * @param namespace - Telemetry event name prefix to add to all events
+	 * @param properties - Base properties to add to all events
+	 * @param propertyGetters - Getters to add additional properties to all events
+	 * @param baseLogger - Base logger to output events (in addition to debug logger being created). Can be undefined.
+	 */
+	public static mixinDebugLogger(
+		namespace: string,
+		baseLogger?: ITelemetryBaseLogger,
+		properties?: ITelemetryLoggerPropertyBags,
+	): ITelemetryLoggerExt {
+		// Setup base logger upfront, such that host can disable it (if needed)
+		const debug = registerDebug(namespace);
+
+		// Create one for errors that is always enabled
+		// It can be silenced by replacing console.error if the debug namespace is not enabled.
+		const debugErr = registerDebug(namespace);
+		debugErr.log = function (...args) {
+			if (debug.enabled === true) {
+				// if the namespace is enabled, just use the default logger
+				registerDebug.log(...args);
+			} else {
+				// other wise, use the console logger (which could be replaced and silenced)
+				console.error(...args);
+			}
+		};
+		debugErr.enabled = true;
+
+		return createMultiSinkLogger({
+			namespace,
+			loggers: [baseLogger, new DebugLogger(debug, debugErr)],
+			properties,
+			tryInheritProperties: true,
+		});
+	}
+
+	private constructor(private readonly debug: IDebugger, private readonly debugErr: IDebugger) {}
+
+	/**
+	 * Send an event to debug loggers
+	 *
+	 * @param event - the event to send
+	 */
+	public send(event: ITelemetryBaseEvent): void {
+		const newEvent: ITelemetryProperties = { ...event };
+		const isError = newEvent.category === "error";
+		let logger = isError ? this.debugErr : this.debug;
+
+		// Use debug's coloring schema for base of the event
+		const index = event.eventName.lastIndexOf(eventNamespaceSeparator);
+		const name = event.eventName.substring(index + 1);
+		if (index > 0) {
+			logger = logger.extend(event.eventName.substring(0, index));
+		}
+		newEvent.eventName = undefined;
+
+		let tick = "";
+		tick = `tick=${formatTick(performance.now())}`;
+
+		// Extract stack to put it last, but also to avoid escaping '\n' in it by JSON.stringify below
+		const stack = newEvent.stack ?? "";
+		newEvent.stack = undefined;
+
+		// Watch out for circular references - they can come from two sources
+		// 1) error object - we do not control it and should remove it and retry
+		// 2) properties supplied by telemetry caller - that's a bug that should be addressed!
+		let payload: string;
+		try {
+			payload = JSON.stringify(newEvent);
+		} catch (error) {
+			newEvent.error = undefined;
+			payload = JSON.stringify(newEvent);
+		}
+
+		if (payload === "{}") {
+			payload = "";
+		}
+
+		// Force errors out, to help with diagnostics
+		if (isError) {
+			logger.enabled = true;
+		}
+
+		// Print multi-line.
+		logger(`${name} ${payload} ${tick} ${stack}`);
+	}
+}

package/src/deltaManager.ts

@@ -3,18 +3,15 @@
  * Licensed under the MIT License.
  */
 
-import { default as AbortController } from "abort-controller";
 import { v4 as uuid } from "uuid";
 import { IEventProvider } from "@fluidframework/common-definitions";
 import { ITelemetryProperties, ITelemetryErrorEvent } from "@fluidframework/core-interfaces";
 import {
-	IDeltaHandlerStrategy,
+	ICriticalContainerError,
 	IDeltaManager,
 	IDeltaManagerEvents,
 	IDeltaQueue,
-	ICriticalContainerError,
 	IThrottlingWarning,
-	IConnectionDetailsInternal,
 } from "@fluidframework/container-definitions";
 import { assert, TypedEventEmitter } from "@fluidframework/common-utils";
 import {
@@ -45,7 +42,11 @@ import {
 	DataProcessingError,
 	UsageError,
 } from "@fluidframework/container-utils";
-import { IConnectionManagerFactoryArgs, IConnectionManager } from "./contracts";
+import {
+	IConnectionDetailsInternal,
+	IConnectionManager,
+	IConnectionManagerFactoryArgs,
+} from "./contracts";
 import { DeltaQueue } from "./deltaQueue";
 import { OnlyValidTermValue } from "./protocol";
 
@@ -74,6 +75,21 @@ interface IBatchMetadata {
 	batch?: boolean;
 }
 
+/**
+ * Interface used to define a strategy for handling incoming delta messages
+ */
+export interface IDeltaHandlerStrategy {
+	/**
+	 * Processes the message.
+	 */
+	process: (message: ISequencedDocumentMessage) => void;
+
+	/**
+	 * Processes the signal.
+	 */
+	processSignal: (message: ISignalMessage) => void;
+}
+
 /**
  * Determines if message was sent by client, not service
  */
@@ -93,6 +109,17 @@ function isClientMessage(message: ISequencedDocumentMessage | IDocumentMessage):
 	}
 }
 
+/**
+ * Type is used to cast AbortController to represent new version of DOM API and prevent build issues
+ * TODO: Remove when typescript version of the repo contains the AbortSignal.reason property (AB#5045)
+ */
+type AbortControllerReal = AbortController & { abort(reason?: any): void };
+/**
+ * Type is used to cast AbortSignal to represent new version of DOM API and prevent build issues
+ * TODO: Remove when typescript version of the repo contains the AbortSignal.reason property (AB#5045)
+ */
+type AbortSignalReal = AbortSignal & { reason: any };
+
 /**
  * Manages the flow of both inbound and outbound messages. This class ensures that shared objects receive delta
  * messages in order regardless of possible network conditions or timings causing out of order delivery.
@@ -485,7 +512,7 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 		minSequenceNumber: number,
 		sequenceNumber: number,
 		handler: IDeltaHandlerStrategy,
-		prefetchType: "cached" | "all" | "none" = "none",
+		prefetchType: "sequenceNumber" | "cached" | "all" | "none" = "none",
 	) {
 		this.initSequenceNumber = sequenceNumber;
 		this.lastProcessedSequenceNumber = sequenceNumber;
@@ -624,7 +651,8 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 			// This is useless for known ranges (to is defined) as it means request is over either way.
 			// And it will cancel unbound request too early, not allowing us to learn where the end of the file is.
 			if (!opsFromFetch && cancelFetch(op)) {
-				controller.abort();
+				// TODO: Remove when typescript version of the repo contains the AbortSignal.reason property (AB#5045)
+				(controller as AbortControllerReal).abort("DeltaManager getDeltas fetch cancelled");
 				this._inbound.off("push", opListener);
 			}
 		};
@@ -632,7 +660,11 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 		try {
 			this._inbound.on("push", opListener);
 			assert(this.closeAbortController.signal.onabort === null, 0x1e8 /* "reentrancy" */);
-			this.closeAbortController.signal.onabort = () => controller.abort();
+			this.closeAbortController.signal.onabort = () =>
+				// TODO: Remove when typescript version of the repo contains the AbortSignal.reason property (AB#5045)
+				(controller as AbortControllerReal).abort(
+					(this.closeAbortController.signal as AbortSignalReal).reason,
+				);
 
 			const stream = this.deltaStorage.fetchMessages(
 				from, // inclusive
@@ -656,6 +688,14 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 				}
 			}
 		} finally {
+			if (controller.signal.aborted) {
+				this.logger.sendTelemetryEvent({
+					eventName: "DeltaManager_GetDeltasAborted",
+					fetchReason,
+					// TODO: Remove when typescript version of the repo contains the AbortSignal.reason property (AB#5045)
+					reason: (controller.signal as AbortSignalReal).reason,
+				});
+			}
 			this.closeAbortController.signal.onabort = null;
 			this._inbound.off("push", opListener);
 			assert(!opsFromFetch, 0x289 /* "logic error" */);
@@ -710,7 +750,8 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 	}
 
 	private clearQueues() {
-		this.closeAbortController.abort();
+		// TODO: Remove when typescript version of the repo contains the AbortSignal.reason property (AB#5045)
+		(this.closeAbortController as AbortControllerReal).abort("DeltaManager is closed");
 
 		this._inbound.clear();
 		this._inboundSignal.clear();

package/src/loader.ts

@@ -6,14 +6,12 @@
 import { v4 as uuid } from "uuid";
 import {
 	ITelemetryLoggerExt,
-	ChildLogger,
-	DebugLogger,
 	IConfigProviderBase,
-	loggerToMonitoringContext,
 	mixinMonitoringContext,
 	MonitoringContext,
 	PerformanceEvent,
 	sessionStorageConfigProvider,
+	createChildMonitoringContext,
 } from "@fluidframework/telemetry-utils";
 import {
 	ITelemetryBaseLogger,
@@ -39,18 +37,15 @@ import {
 	IResolvedUrl,
 	IUrlResolver,
 } from "@fluidframework/driver-definitions";
-import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
+import { UsageError } from "@fluidframework/container-utils";
 import { Container, IPendingContainerState } from "./container";
 import { IParsedUrl, parseUrl } from "./utils";
 import { pkgVersion } from "./packageVersion";
 import { ProtocolHandlerBuilder } from "./protocol";
+import { DebugLogger } from "./debugLogger";
 
 function canUseCache(request: IRequest): boolean {
-	if (request.headers === undefined) {
-		return true;
-	}
-
-	return request.headers[LoaderHeader.cache] !== false;
+	return request.headers?.[LoaderHeader.cache] === true;
 }
 
 function ensureResolvedUrlDefined(
@@ -69,6 +64,9 @@ export class RelativeLoader implements ILoader {
 		private readonly loader: ILoader | undefined,
 	) {}
 
+	/**
+	 * @deprecated - Will be removed in future major release. Migrate all usage of IFluidRouter to the Container's IFluidRouter/request.
+	 */
 	public get IFluidRouter(): IFluidRouter {
 		return this;
 	}
@@ -100,6 +98,9 @@ export class RelativeLoader implements ILoader {
 		return this.loader.resolve(request);
 	}
 
+	/**
+	 * @deprecated - Will be removed in future major release. Migrate all usage of IFluidRouter to the Container's IFluidRouter/request.
+	 */
 	public async request(request: IRequest): Promise<IResponse> {
 		if (request.url.startsWith("/")) {
 			const container = await this.resolve(request);
@@ -343,9 +344,15 @@ export class Loader implements IHostLoader {
 			protocolHandlerBuilder,
 			subLogger: subMc.logger,
 		};
-		this.mc = loggerToMonitoringContext(ChildLogger.create(this.services.subLogger, "Loader"));
+		this.mc = createChildMonitoringContext({
+			logger: this.services.subLogger,
+			namespace: "Loader",
+		});
 	}
 
+	/**
+	 * @deprecated - Will be removed in future major release. Migrate all usage of IFluidRouter to the Container's IFluidRouter/request.
+	 */
 	public get IFluidRouter(): IFluidRouter {
 		return this;
 	}
@@ -381,6 +388,9 @@ export class Loader implements IHostLoader {
 		});
 	}
 
+	/**
+	 * @deprecated - Will be removed in future major release. Migrate all usage of IFluidRouter to the Container's IFluidRouter/request.
+	 */
 	public async request(request: IRequest): Promise<IResponse> {
 		return PerformanceEvent.timedExecAsync(
 			this.mc.logger,
@@ -407,16 +417,23 @@ export class Loader implements IHostLoader {
 		this.containers.set(key, containerP);
 		containerP
 			.then((container) => {
-				// If the container is closed or becomes closed after we resolve it, remove it from the cache.
-				if (container.closed) {
+				// If the container is closed/disposed or becomes closed/disposed after we resolve it,
+				// remove it from the cache.
+				if (container.closed || container.disposed) {
 					this.containers.delete(key);
 				} else {
 					container.once("closed", () => {
 						this.containers.delete(key);
 					});
+					container.once("disposed", () => {
+						this.containers.delete(key);
+					});
 				}
 			})
-			.catch((error) => {});
+			.catch((error) => {
+				// If an error occured while resolving the container request, then remove it from the cache.
+				this.containers.delete(key);
+			});
 	}
 
 	private async resolveCore(
@@ -447,11 +464,29 @@ export class Loader implements IHostLoader {
 		// 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 cacheHeader = request.headers[LoaderHeader.cache];
 		const canCache =
-			this.cachingEnabled &&
-			request.headers[LoaderHeader.cache] !== false &&
+			// Take header value if present, else use ILoaderOptions.cache value
+			(cacheHeader !== undefined ? cacheHeader === true : this.cachingEnabled) &&
 			pendingLocalState === undefined;
-		const fromSequenceNumber = request.headers[LoaderHeader.sequenceNumber] ?? -1;
+		const fromSequenceNumber = request.headers[LoaderHeader.sequenceNumber] as
+			| number
+			| undefined;
+		const opsBeforeReturn = request.headers[LoaderHeader.loadMode]?.opsBeforeReturn as
+			| string
+			| undefined;
+
+		if (
+			opsBeforeReturn === "sequenceNumber" &&
+			(fromSequenceNumber === undefined || fromSequenceNumber < 0)
+		) {
+			// If opsBeforeReturn is set to "sequenceNumber", then fromSequenceNumber should be set to a non-negative integer.
+			throw new UsageError("sequenceNumber must be set to a non-negative integer");
+		} else if (opsBeforeReturn !== "sequenceNumber" && fromSequenceNumber !== undefined) {
+			// If opsBeforeReturn is not set to "sequenceNumber", then fromSequenceNumber should be undefined (default value).
+			// In this case, we should throw an error since opsBeforeReturn is not explicitly set to "sequenceNumber".
+			throw new UsageError('opsBeforeReturn must be set to "sequenceNumber"');
+		}
 
 		let container: Container;
 		if (canCache) {
@@ -468,24 +503,11 @@ export class Loader implements IHostLoader {
 			container = await this.loadContainer(request, resolvedAsFluid, pendingLocalState);
 		}
 
-		if (container.deltaManager.lastSequenceNumber <= fromSequenceNumber) {
-			await new Promise<void>((resolve, reject) => {
-				function opHandler(message: ISequencedDocumentMessage) {
-					if (message.sequenceNumber > fromSequenceNumber) {
-						resolve();
-						container.removeListener("op", opHandler);
-					}
-				}
-
-				container.on("op", opHandler);
-			});
-		}
-
 		return { container, parsed };
 	}
 
 	private get cachingEnabled() {
-		return this.services.options.cache !== false;
+		return this.services.options.cache === true;
 	}
 
 	private async loadContainer(
@@ -499,6 +521,7 @@ export class Loader implements IHostLoader {
 				version: request.headers?.[LoaderHeader.version] ?? undefined,
 				loadMode: request.headers?.[LoaderHeader.loadMode],
 				pendingLocalState,
+				loadToSequenceNumber: request.headers?.[LoaderHeader.sequenceNumber],
 			},
 			{
 				canReconnect: request.headers?.[LoaderHeader.reconnect],

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-loader";
-export const pkgVersion = "2.0.0-internal.5.3.2";
+export const pkgVersion = "2.0.0-internal.6.0.0";

package/src/protocol.ts

@@ -49,7 +49,6 @@ export class ProtocolHandler extends ProtocolOpHandler implements IProtocolHandl
 		super(
 			attributes.minimumSequenceNumber,
 			attributes.sequenceNumber,
-			OnlyValidTermValue,
 			quorumSnapshot.members,
 			quorumSnapshot.proposals,
 			quorumSnapshot.values,

package/src/quorum.ts

@@ -2,19 +2,9 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { assert } from "@fluidframework/common-utils";
 import { IFluidCodeDetails } from "@fluidframework/core-interfaces";
 import { ICommittedProposal } from "@fluidframework/protocol-definitions";
 
-export function getCodeDetailsFromQuorumValues(
-	quorumValues: [string, ICommittedProposal][],
-): IFluidCodeDetails {
-	const qValuesMap = new Map(quorumValues);
-	const proposal = qValuesMap.get("code");
-	assert(proposal !== undefined, 0x2dc /* "Cannot find code proposal" */);
-	return proposal?.value as IFluidCodeDetails;
-}
-
 export function initQuorumValuesFromCodeDetails(
 	source: IFluidCodeDetails,
 ): [string, ICommittedProposal][] {

package/src/utils.ts

@@ -14,6 +14,7 @@ import {
 import { ISummaryTree, ISnapshotTree, SummaryType } from "@fluidframework/protocol-definitions";
 import { LoggingError } from "@fluidframework/telemetry-utils";
 import {
+	CombinedAppAndProtocolSummary,
 	DeltaStreamConnectionForbiddenError,
 	isCombinedAppAndProtocolSummary,
 } from "@fluidframework/driver-utils";
@@ -51,6 +52,34 @@ export function parseUrl(url: string): IParsedUrl | undefined {
 		: undefined;
 }
 
+/**
+ * Combine the app summary and protocol summary in 1 tree.
+ * @param appSummary - Summary of the app.
+ * @param protocolSummary - Summary of the protocol.
+ * @internal
+ */
+export function combineAppAndProtocolSummary(
+	appSummary: ISummaryTree,
+	protocolSummary: ISummaryTree,
+): CombinedAppAndProtocolSummary {
+	assert(
+		!isCombinedAppAndProtocolSummary(appSummary),
+		0x5a8 /* app summary is already a combined tree! */,
+	);
+	assert(
+		!isCombinedAppAndProtocolSummary(protocolSummary),
+		0x5a9 /* protocol summary is already a combined tree! */,
+	);
+	const createNewSummary: CombinedAppAndProtocolSummary = {
+		type: SummaryType.Tree,
+		tree: {
+			".protocol": protocolSummary,
+			".app": appSummary,
+		},
+	};
+	return createNewSummary;
+}
+
 /**
  * Converts summary tree (for upload) to snapshot tree (for download).
  * Summary tree blobs contain contents, but snapshot tree blobs normally