@fluidframework/container-loader 2.0.0-dev.5.2.0.169897 → 2.0.0-dev.6.4.0.191258

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 "@fluid-internal/client-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,35 +3,36 @@
  * Licensed under the MIT License.
  */
 
-import { default as AbortController } from "abort-controller";
 import { v4 as uuid } from "uuid";
 import {
+	IThrottlingWarning,
 	IEventProvider,
 	ITelemetryProperties,
 	ITelemetryErrorEvent,
-} from "@fluidframework/common-definitions";
+} 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 { TypedEventEmitter } from "@fluid-internal/client-utils";
+import { assert } from "@fluidframework/core-utils";
 import {
+	DataProcessingError,
+	extractSafePropertiesFromMessage,
 	normalizeError,
 	logIfFalse,
 	safeRaiseEvent,
 	isFluidError,
 	ITelemetryLoggerExt,
+	DataCorruptionError,
+	UsageError,
 } from "@fluidframework/telemetry-utils";
 import {
 	IDocumentDeltaStorageService,
 	IDocumentService,
-	DriverErrorType,
-	IAnyDriverError,
+	DriverErrorTypes,
 } from "@fluidframework/driver-definitions";
 import {
 	IDocumentMessage,
@@ -41,21 +42,21 @@ import {
 	ConnectionMode,
 } from "@fluidframework/protocol-definitions";
 import { NonRetryableError, isRuntimeMessage, MessageType2 } from "@fluidframework/driver-utils";
+
 import {
-	ThrottlingWarning,
-	DataCorruptionError,
-	extractSafePropertiesFromMessage,
-	DataProcessingError,
-	UsageError,
-} from "@fluidframework/container-utils";
-import { IConnectionManagerFactoryArgs, IConnectionManager } from "./contracts";
+	IConnectionDetailsInternal,
+	IConnectionManager,
+	IConnectionManagerFactoryArgs,
+	IConnectionStateChangeReason,
+} from "./contracts";
 import { DeltaQueue } from "./deltaQueue";
 import { OnlyValidTermValue } from "./protocol";
+import { ThrottlingWarning } from "./error";
 
 export interface IConnectionArgs {
 	mode?: ConnectionMode;
 	fetchOpsFromStorage?: boolean;
-	reason: string;
+	reason: IConnectionStateChangeReason;
 }
 
 /**
@@ -66,8 +67,33 @@ 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);
+	(event: "establishingConnection", listener: (reason: IConnectionStateChangeReason) => void);
+	(
+		event: "cancelEstablishingConnection",
+		listener: (reason: IConnectionStateChangeReason) => 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;
+}
+
+/**
+ * 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;
 }
 
 /**
@@ -89,6 +115,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.
@@ -293,13 +330,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 */,
 			);
 		}
@@ -313,6 +353,7 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 		return {
 			sequenceNumber: this.lastSequenceNumber,
 			opsSize: this.opsSize > 0 ? this.opsSize : undefined,
+			deltaManagerState: this._disposed ? "disposed" : this._closed ? "closed" : "open",
 			...this.connectionManager.connectionProps,
 		};
 	}
@@ -366,15 +407,17 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 			reconnectionDelayHandler: (delayMs: number, error: unknown) =>
 				this.emitDelayInfo(this.deltaStreamDelayId, delayMs, error),
 			closeHandler: (error: any) => this.close(error),
-			disconnectHandler: (reason: string, error?: IAnyDriverError) =>
-				this.disconnectHandler(reason, error),
+			disconnectHandler: (reason: IConnectionStateChangeReason) =>
+				this.disconnectHandler(reason),
 			connectHandler: (connection: IConnectionDetailsInternal) =>
 				this.connectHandler(connection),
 			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),
+			establishConnectionHandler: (reason: IConnectionStateChangeReason) =>
+				this.establishingConnection(reason),
+			cancelConnectionHandler: (reason: IConnectionStateChangeReason) =>
+				this.cancelEstablishingConnection(reason),
 		};
 
 		this.connectionManager = createConnectionManager(props);
@@ -414,11 +457,11 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 		// - inbound & inboundSignal are resumed in attachOpHandler() when we have handler setup
 	}
 
-	private cancelEstablishingConnection(reason: string) {
+	private cancelEstablishingConnection(reason: IConnectionStateChangeReason) {
 		this.emit("cancelEstablishingConnection", reason);
 	}
 
-	private establishingConnection(reason: string) {
+	private establishingConnection(reason: IConnectionStateChangeReason) {
 		this.emit("establishingConnection", reason);
 	}
 
@@ -478,7 +521,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;
@@ -552,7 +595,7 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 		// on the wire, we might be always behind.
 		// See comment at the end of "connect" handler
 		if (fetchOpsFromStorage) {
-			this.fetchMissingDeltas(args.reason);
+			this.fetchMissingDeltas(args.reason.text);
 		}
 
 		this.connectionManager.connect(args.reason, args.mode);
@@ -617,7 +660,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);
 			}
 		};
@@ -625,7 +669,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
@@ -649,6 +697,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" */);
@@ -703,7 +759,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();
@@ -724,9 +781,9 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 		}
 	}
 
-	private disconnectHandler(reason: string, error?: IAnyDriverError) {
+	private disconnectHandler(reason: IConnectionStateChangeReason) {
 		this.messageBuffer.length = 0;
-		this.emit("disconnect", reason, error);
+		this.emit("disconnect", reason);
 	}
 
 	/**
@@ -886,7 +943,7 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 							// pre-0.58 error message: twoMessagesWithSameSeqNumAndDifferentPayload
 							"Found two messages with the same sequenceNumber but different payloads. Likely to be a " +
 								"service issue",
-							DriverErrorType.fileOverwrittenInStorage,
+							DriverErrorTypes.fileOverwrittenInStorage,
 							{
 								clientId: this.connectionManager.clientId,
 								sequenceNumber: message.sequenceNumber,

package/src/deltaQueue.ts

@@ -4,7 +4,8 @@
  */
 
 import { IDeltaQueue, IDeltaQueueEvents } from "@fluidframework/container-definitions";
-import { assert, performance, TypedEventEmitter } from "@fluidframework/common-utils";
+import { assert } from "@fluidframework/core-utils";
+import { performance, TypedEventEmitter } from "@fluid-internal/client-utils";
 import Deque from "double-ended-queue";
 
 export interface IDeltaQueueWriter<T> {

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/core-interfaces";
+
+/**
+ * Returns a wrapper around the provided function, which will only invoke the inner function if the provided
+ * {@link @fluidframework/core-interfaces#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/error.ts

@@ -0,0 +1,44 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ITelemetryProperties, IThrottlingWarning } from "@fluidframework/core-interfaces";
+import { ContainerErrorTypes } from "@fluidframework/container-definitions";
+import {
+	IFluidErrorBase,
+	ITelemetryLoggerExt,
+	LoggingError,
+	wrapErrorAndLog,
+} from "@fluidframework/telemetry-utils";
+
+/**
+ * Warning emitted when requests to storage are being throttled.
+ */
+export class ThrottlingWarning extends LoggingError implements IThrottlingWarning, IFluidErrorBase {
+	/**
+	 * {@inheritDoc @fluidframework/telemetry-utils#IFluidErrorBase.errorType}
+	 */
+	public readonly errorType = ContainerErrorTypes.throttlingError;
+
+	private constructor(
+		message: string,
+		readonly retryAfterSeconds: number,
+		props?: ITelemetryProperties,
+	) {
+		super(message, props);
+	}
+
+	/**
+	 * Wrap the given error as a ThrottlingWarning
+	 * Only preserves the error message, and applies the given retry after to the new warning object
+	 */
+	public static wrap(
+		error: unknown,
+		retryAfterSeconds: number,
+		logger: ITelemetryLoggerExt,
+	): IThrottlingWarning {
+		const newErrorFn = (errMsg: string) => new ThrottlingWarning(errMsg, retryAfterSeconds);
+		return wrapErrorAndLog(error, newErrorFn, logger);
+	}
+}