@fluidframework/container-loader 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.224419

package/src/contracts.ts

@@ -3,31 +3,45 @@
  * Licensed under the MIT License.
  */
 
+import { IErrorBase, ITelemetryProperties } from "@fluidframework/core-interfaces";
 import {
-    ITelemetryProperties,
-} from "@fluidframework/common-definitions";
-import {
-    IDeltaQueue,
-    ReadOnlyInfo,
-    IConnectionDetails,
-    ICriticalContainerError,
-    IFluidCodeDetails,
-    isFluidPackage,
+	IConnectionDetails,
+	ICriticalContainerError,
+	IDeltaQueue,
+	IFluidCodeDetails,
+	isFluidPackage,
+	ReadOnlyInfo,
 } from "@fluidframework/container-definitions";
 import {
-    ConnectionMode,
-    IDocumentMessage,
-    ISequencedDocumentMessage,
-    IClientConfiguration,
-    IClientDetails,
-    ISignalMessage,
+	ConnectionMode,
+	IClientConfiguration,
+	IClientDetails,
+	IDocumentMessage,
+	ISequencedDocumentMessage,
+	ISignalClient,
+	ISignalMessage,
 } from "@fluidframework/protocol-definitions";
 import { IContainerPackageInfo } from "@fluidframework/driver-definitions";
 
 export enum ReconnectMode {
-    Never = "Never",
-    Disabled = "Disabled",
-    Enabled = "Enabled",
+	Never = "Never",
+	Disabled = "Disabled",
+	Enabled = "Enabled",
+}
+
+export interface IConnectionStateChangeReason<T extends IErrorBase = IErrorBase> {
+	text: string;
+	error?: T;
+}
+
+/**
+ * Internal version of IConnectionDetails with props are only exposed internally
+ */
+export interface IConnectionDetailsInternal extends IConnectionDetails {
+	mode: ConnectionMode;
+	version: string;
+	initialClients: ISignalClient[];
+	reason: IConnectionStateChangeReason;
 }
 
 /**
@@ -35,130 +49,152 @@ export enum ReconnectMode {
  * to relay service.
  */
 export interface IConnectionManager {
-    readonly connected: boolean;
-
-    readonly clientId: string | undefined;
-
-    /** The queue of outbound delta messages */
-    readonly outbound: IDeltaQueue<IDocumentMessage[]>;
-
-    /** Details of client */
-    readonly clientDetails: IClientDetails;
-
-    /** Protocol version being used to communicate with the service */
-    readonly version: string;
-
-    /** Max message size allowed to the delta manager */
-    readonly maxMessageSize: number;
-
-    /** Service configuration provided by the service. */
-    readonly serviceConfiguration: IClientConfiguration | undefined;
-
-    readonly readOnlyInfo: ReadOnlyInfo;
-
-    // Various connectivity propetries for telemetry describing type of current connection
-    // Things like connection mode, service info, etc.
-    // Called when connection state changes (connect / disconnect)
-    readonly connectionProps: ITelemetryProperties;
-
-    // Verbose information about connection logged to telemetry in case of issues with
-    // maintaining healphy connection, including op gaps, not receiving join op in time, etc.
-    // Contains details information, like sequence numbers at connection time, initial ops info, etc.
-    readonly connectionVerboseProps: ITelemetryProperties;
-
-    /**
-     * Prepares message to be sent. Fills in clientSequenceNumber.
-     * Called only when active connection is present.
-     */
-    prepareMessageToSend(message: Omit<IDocumentMessage, "clientSequenceNumber">): IDocumentMessage | undefined;
-
-    /**
-     * Called before incomming message is processed. Incomming messages can be comming from connection,
-     * but also could come from storage.
-     * This call allows connection manager to adjust knowledge about acked ops sent on previous connection.
-     * Can be called at any time, including when there is no active connection.
-     */
-    beforeProcessingIncomingOp(message: ISequencedDocumentMessage): void;
-
-    /**
-     * Submits signal to relay service.
-     * Called only when active connection is present.
-     */
-    submitSignal(content: any): void;
-
-    /**
-     * Submits messages to relay service.
-     * Called only when active connection is present.
-     */
-    sendMessages(messages: IDocumentMessage[]): void;
-
-    /**
-     * Initiates connection to relay service (noop if already connected).
-     */
-    connect(connectionMode?: ConnectionMode): void;
-
-    /**
-     * Disposed connection manager
-     */
-    dispose(error?: ICriticalContainerError): void;
-
-    get connectionMode(): ConnectionMode;
+	readonly connected: boolean;
+
+	readonly clientId: string | undefined;
+
+	/** The queue of outbound delta messages */
+	readonly outbound: IDeltaQueue<IDocumentMessage[]>;
+
+	/** Details of client */
+	readonly clientDetails: IClientDetails;
+
+	/** Protocol version being used to communicate with the service */
+	readonly version: string;
+
+	/** Max message size allowed to the delta manager */
+	readonly maxMessageSize: number;
+
+	/** Service configuration provided by the service. */
+	readonly serviceConfiguration: IClientConfiguration | undefined;
+
+	readonly readOnlyInfo: ReadOnlyInfo;
+
+	// Various connectivity properties for telemetry describing type of current connection
+	// Things like connection mode, service info, etc.
+	// Called when connection state changes (connect / disconnect)
+	readonly connectionProps: ITelemetryProperties;
+
+	// Verbose information about connection logged to telemetry in case of issues with
+	// maintaining healthy connection, including op gaps, not receiving join op in time, etc.
+	// Contains details information, like sequence numbers at connection time, initial ops info, etc.
+	readonly connectionVerboseProps: ITelemetryProperties;
+
+	/**
+	 * Prepares message to be sent. Fills in clientSequenceNumber.
+	 * Called only when active connection is present.
+	 */
+	prepareMessageToSend(
+		message: Omit<IDocumentMessage, "clientSequenceNumber">,
+	): IDocumentMessage | undefined;
+
+	/**
+	 * Called before incoming message is processed. Incoming messages can be combing from connection,
+	 * but also could come from storage.
+	 * This call allows connection manager to adjust knowledge about acked ops sent on previous connection.
+	 * Can be called at any time, including when there is no active connection.
+	 */
+	beforeProcessingIncomingOp(message: ISequencedDocumentMessage): void;
+
+	/**
+	 * Submits signal to relay service.
+	 * Called only when active connection is present.
+	 */
+	submitSignal(content: any, targetClientId?: string): void;
+
+	/**
+	 * Submits messages to relay service.
+	 * Called only when active connection is present.
+	 */
+	sendMessages(messages: IDocumentMessage[]): void;
+
+	/**
+	 * Initiates connection to relay service (noop if already connected).
+	 */
+	connect(reason: IConnectionStateChangeReason, connectionMode?: ConnectionMode): void;
+
+	/**
+	 * Disposed connection manager
+	 */
+	dispose(error?: ICriticalContainerError, switchToReadonly?: boolean): void;
+
+	get connectionMode(): ConnectionMode;
 }
 
 /**
  * This interface represents a set of callbacks provided by DeltaManager to IConnectionManager on its creation
- * IConnectionManager instance will use them to communicate to DeltaManager abour various events.
+ * IConnectionManager instance will use them to communicate to DeltaManager about various events.
  */
 export interface IConnectionManagerFactoryArgs {
-    /**
-     * Called by connection manager for each incomming op. Some ops maybe delivered before
-     * connectHandler is called (initial ops on socket connection)
-     */
-    readonly incomingOpHandler: (messages: ISequencedDocumentMessage[], reason: string) => void;
-
-    /**
-     * Called by connection manager for each incoming signals.
-     * Maybe called before connectHandler is called (initial signals on socket connection)
-     */
-    readonly signalHandler: (message: ISignalMessage) => void;
-
-    /**
-     * Called when connection manager experiences delay in connecting to relay service.
-     * This can happen because client is offline, or service is busy and asks to not connect for some time.
-     * Can be called many times while not connected.
-     * Situation is considered resolved when connection is established and connectHandler is called.
-     */
-    readonly reconnectionDelayHandler: (delayMs: number, error: unknown) => void;
-
-    /**
-     * Called by connection manager whwnever critical error happens and container should be closed.
-     * Expects dispose() call in respose to this call.
-     */
-    readonly closeHandler: (error?: any) => void;
-
-    /**
-     * Called whenever connection to relay service is lost.
-     */
-    readonly disconnectHandler: (reason: string) => void;
-
-    /**
-     * Called whenever new connection to rely service is established
-     */
-    readonly connectHandler: (connection: IConnectionDetails) => void;
-
-    /**
-     * Called whenever ping/pong messages are roundtripped on connection.
-     */
-    readonly pongHandler: (latency: number) => void;
-
-    /**
-     * Called whenever connection type changes from writable to read-only or vice versa.
-     * Connection can be read-only if user has no edit permissions, or if container forced
-     * connection to be read-only.
-     * This should not be confused with "read" / "write"connection mode which is internal
-     * optimization.
-     */
-    readonly readonlyChangeHandler: (readonly?: boolean) => void;
+	/**
+	 * Called by connection manager for each incoming op. Some ops maybe delivered before
+	 * connectHandler is called (initial ops on socket connection)
+	 */
+	readonly incomingOpHandler: (messages: ISequencedDocumentMessage[], reason: string) => void;
+
+	/**
+	 * Called by connection manager for each incoming signal.
+	 * May be called before connectHandler is called (due to initial signals on socket connection)
+	 */
+	readonly signalHandler: (signals: ISignalMessage[]) => void;
+
+	/**
+	 * Called when connection manager experiences delay in connecting to relay service.
+	 * This can happen because client is offline, or service is busy and asks to not connect for some time.
+	 * Can be called many times while not connected.
+	 * Situation is considered resolved when connection is established and connectHandler is called.
+	 */
+	readonly reconnectionDelayHandler: (delayMs: number, error: unknown) => void;
+
+	/**
+	 * Called by connection manager whenever critical error happens and container should be closed.
+	 * Expects dispose() call in response to this call.
+	 */
+	readonly closeHandler: (error?: any) => void;
+
+	/**
+	 * Called whenever connection to relay service is lost.
+	 */
+	readonly disconnectHandler: (reason: IConnectionStateChangeReason) => void;
+
+	/**
+	 * Called whenever new connection to rely service is established
+	 */
+	readonly connectHandler: (connection: IConnectionDetailsInternal) => void;
+
+	/**
+	 * Called whenever ping/pong messages are roundtripped on connection.
+	 */
+	readonly pongHandler: (latency: number) => void;
+
+	/**
+	 * Called whenever connection type changes from writable to read-only or vice versa.
+	 *
+	 * @remarks
+	 *
+	 * Connection can be read-only if user has no edit permissions, or if container forced
+	 * connection to be read-only.
+	 * This should not be confused with "read" / "write"connection mode which is internal
+	 * optimization.
+	 *
+	 * @param readonly - Whether or not the container is now read-only.
+	 * `undefined` indicates that user permissions are not yet known.
+	 * @param readonlyConnectionReason - reason/error if any for the change
+	 */
+	readonly readonlyChangeHandler: (
+		readonly?: boolean,
+		readonlyConnectionReason?: IConnectionStateChangeReason,
+	) => void;
+
+	/**
+	 * Called whenever we try to start establishing a new connection.
+	 */
+	readonly establishConnectionHandler: (reason: IConnectionStateChangeReason) => void;
+
+	/**
+	 * Called whenever we cancel the connection in progress.
+	 */
+	readonly cancelConnectionHandler: (reason: IConnectionStateChangeReason) => void;
 }
 
 /**
@@ -166,14 +202,16 @@ export interface IConnectionManagerFactoryArgs {
  * @param codeDetails- - Data structure used to describe the code to load on the Fluid document
  * @returns The name of the Fluid package
  */
-export const getPackageName = (codeDetails: IFluidCodeDetails | undefined): IContainerPackageInfo => {
-    let containerPackageName;
-    if (codeDetails && "name" in codeDetails) {
-        containerPackageName = codeDetails;
-    } else if (isFluidPackage(codeDetails?.package)) {
-        containerPackageName = codeDetails?.package.name;
-    } else {
-        containerPackageName = codeDetails?.package;
-    }
-    return { name: containerPackageName };
+export const getPackageName = (
+	codeDetails: IFluidCodeDetails | undefined,
+): IContainerPackageInfo => {
+	let containerPackageName;
+	if (codeDetails && "name" in codeDetails) {
+		containerPackageName = codeDetails;
+	} else if (isFluidPackage(codeDetails?.package)) {
+		containerPackageName = codeDetails?.package.name;
+	} else {
+		containerPackageName = codeDetails?.package;
+	}
+	return { name: containerPackageName };
 };

package/src/debugLogger.ts

@@ -0,0 +1,123 @@
+/*!
+ * 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 {
+	ITelemetryLoggerExt,
+	ITelemetryLoggerPropertyBags,
+	createMultiSinkLogger,
+	eventNamespaceSeparator,
+	formatTick,
+} from "@fluidframework/telemetry-utils";
+
+// This import style is necessary to ensure the emitted JS code works in both CJS and ESM.
+import debugPkg from "debug";
+const { debug: registerDebug } = debugPkg;
+
+import type { IDebugger } from "debug";
+
+/**
+ * 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.
+		// eslint-disable-next-line @typescript-eslint/no-base-to-string
+		logger(`${name} ${payload} ${tick} ${stack}`);
+	}
+}