@fluidframework/driver-base 2.0.0-dev.2.3.0.115467 → 2.0.0-dev.4.1.0.148229

package/src/documentDeltaConnection.ts

@@ -5,31 +5,32 @@
 
 import { assert } from "@fluidframework/common-utils";
 import {
-    IAnyDriverError,
-    IDocumentDeltaConnection,
-    IDocumentDeltaConnectionEvents,
+	IAnyDriverError,
+	IDocumentDeltaConnection,
+	IDocumentDeltaConnectionEvents,
 } from "@fluidframework/driver-definitions";
 import { createGenericNetworkError } from "@fluidframework/driver-utils";
 import {
-    ConnectionMode,
-    IClientConfiguration,
-    IConnect,
-    IConnected,
-    IDocumentMessage,
-    ISequencedDocumentMessage,
-    ISignalClient,
-    ISignalMessage,
-    ITokenClaims,
-    ScopeType,
+	ConnectionMode,
+	IClientConfiguration,
+	IConnect,
+	IConnected,
+	IDocumentMessage,
+	ISequencedDocumentMessage,
+	ISignalClient,
+	ISignalMessage,
+	ITokenClaims,
+	ScopeType,
 } from "@fluidframework/protocol-definitions";
 import { IDisposable, ITelemetryLogger } from "@fluidframework/common-definitions";
 import {
-    ChildLogger,
-    extractLogSafeErrorProperties,
-    getCircularReplacer,
-    loggerToMonitoringContext,
-    MonitoringContext,
-    EventEmitterWithErrorHandling,
+	ChildLogger,
+	extractLogSafeErrorProperties,
+	getCircularReplacer,
+	loggerToMonitoringContext,
+	MonitoringContext,
+	EventEmitterWithErrorHandling,
+	normalizeError,
 } from "@fluidframework/telemetry-utils";
 import type { Socket } from "socket.io-client";
 // For now, this package is versioned and released in unison with the specific drivers
@@ -39,576 +40,706 @@ import { pkgVersion as driverVersion } from "./packageVersion";
  * Represents a connection to a stream of delta updates
  */
 export class DocumentDeltaConnection
-    extends EventEmitterWithErrorHandling<IDocumentDeltaConnectionEvents>
-    implements IDocumentDeltaConnection, IDisposable {
-    static readonly eventsToForward = ["nack", "op", "signal", "pong"];
-
-    // WARNING: These are critical events that we can't miss, so registration for them has to be in place at all times!
-    // Including before handshake is over, and after that (but before DeltaManager had a chance to put its own handlers)
-    static readonly eventsAlwaysForwarded = ["disconnect", "error"];
-
-    /**
-     * Last known sequence number to ordering service at the time of connection
-     * It may lap actual last sequence number (quite a bit, if container  is very active).
-     * But it's best information for client to figure out how far it is behind, at least
-     * for "read" connections. "write" connections may use own "join" op to similar information,
-     * that is likely to be more up-to-date.
-     */
-    public checkpointSequenceNumber: number | undefined;
-
-    // Listen for ops sent before we receive a response to connect_document
-    protected readonly queuedMessages: ISequencedDocumentMessage[] = [];
-    protected readonly queuedSignals: ISignalMessage[] = [];
-
-    /**
-     * A flag to indicate whether we have our handler attached.  If it's attached, we're queueing incoming ops
-     * to later be retrieved via initialMessages.
-     */
-    private earlyOpHandlerAttached: boolean = false;
-
-    private socketConnectionTimeout: ReturnType<typeof setTimeout> | undefined;
-
-    private _details: IConnected | undefined;
-
-    // Listeners only needed while the connection is in progress
-    private readonly connectionListeners: Map<string, (...args: any[]) => void> = new Map();
-    // Listeners used throughout the lifetime of the DocumentDeltaConnection
-    private readonly trackedListeners: Map<string, (...args: any[]) => void> = new Map();
-
-    protected get hasDetails(): boolean {
-        return !!this._details;
-    }
-
-    public get disposed() {
-        assert(this._disposed || this.socket.connected, 0x244 /* "Socket is closed, but connection is not!" */);
-        return this._disposed;
-    }
-
-    /**
-     * Flag to indicate whether the DocumentDeltaConnection is expected to still be capable of sending messages.
-     * After disconnection, we flip this to prevent any stale messages from being emitted.
-     */
-    protected _disposed: boolean = false;
-    private readonly mc: MonitoringContext;
-
-    /**
-     * @deprecated Implementors should manage their own logger or monitoring context
-     */
-    protected get logger(): ITelemetryLogger {
-        return this.mc.logger;
-    }
-
-    public get details(): IConnected {
-        if (!this._details) {
-            throw new Error("Internal error: calling method before _details is initialized!");
-        }
-        return this._details;
-    }
-
-    /**
-     * @param socket - websocket to be used
-     * @param documentId - ID of the document
-     * @param logger - for reporting telemetry events
-     * @param enableLongPollingDowngrades - allow connection to be downgraded to long-polling on websocket failure
-     */
-    protected constructor(
-        protected readonly socket: Socket,
-        public documentId: string,
-        logger: ITelemetryLogger,
-        private readonly enableLongPollingDowngrades: boolean = false,
-    ) {
-        super((name, error) => {
-            logger.sendErrorEvent(
-                {
-                    eventName: "DeltaConnection:EventException",
-                    name,
-                },
-                error);
-        });
-
-        this.mc = loggerToMonitoringContext(
-            ChildLogger.create(logger, "DeltaConnection"));
-
-        this.on("newListener", (event, listener) => {
-            assert(!this.disposed, 0x20a /* "register for event on disposed object" */);
-
-            // Some events are already forwarded - see this.addTrackedListener() calls in initialize().
-            if (DocumentDeltaConnection.eventsAlwaysForwarded.includes(event)) {
-                assert(this.trackedListeners.has(event), 0x245 /* "tracked listener" */);
-                return;
-            }
-
-            if (!DocumentDeltaConnection.eventsToForward.includes(event)) {
-                throw new Error(`DocumentDeltaConnection: Registering for unknown event: ${event}`);
-            }
-
-            // Whenever listener is added, we should subscribe on same event on socket, so these two things
-            // should be in sync. This currently assumes that nobody unregisters and registers back listeners,
-            // and that there are no "internal" listeners installed (like "error" case we skip above)
-            // Better flow might be to always unconditionally register all handlers on successful connection,
-            // though some logic (naming assert in initialMessages getter) might need to be adjusted (it becomes noop)
-            assert((this.listeners(event).length !== 0) === this.trackedListeners.has(event), 0x20b /* "mismatch" */);
-            if (!this.trackedListeners.has(event)) {
-                this.addTrackedListener(
-                    event,
-                    (...args: any[]) => {
-                        this.emit(event, ...args);
-                    });
-            }
-        });
-    }
-
-    /**
-     * Get the ID of the client who is sending the message
-     *
-     * @returns the client ID
-     */
-    public get clientId(): string {
-        return this.details.clientId;
-    }
-
-    /**
-     * Get the mode of the client
-     *
-     * @returns the client mode
-     */
-    public get mode(): ConnectionMode {
-        return this.details.mode;
-    }
-
-    /**
-     * Get the claims of the client who is sending the message
-     *
-     * @returns client claims
-     */
-    public get claims(): ITokenClaims {
-        return this.details.claims;
-    }
-
-    /**
-     * Get whether or not this is an existing document
-     *
-     * @returns true if the document exists
-     */
-    public get existing(): boolean {
-        return this.details.existing;
-    }
-
-    /**
-     * Get the maximum size of a message before chunking is required
-     *
-     * @returns the maximum size of a message before chunking is required
-     */
-    public get maxMessageSize(): number {
-        return this.details.serviceConfiguration.maxMessageSize;
-    }
-
-    /**
-     * Semver of protocol being used with the service
-     */
-    public get version(): string {
-        return this.details.version;
-    }
-
-    /**
-     * Configuration details provided by the service
-     */
-    public get serviceConfiguration(): IClientConfiguration {
-        return this.details.serviceConfiguration;
-    }
-
-    private checkNotClosed() {
-        assert(!this.disposed, 0x20c /* "connection disposed" */);
-    }
-
-    /**
-     * Get messages sent during the connection
-     *
-     * @returns messages sent during the connection
-     */
-    public get initialMessages(): ISequencedDocumentMessage[] {
-        this.checkNotClosed();
-
-        // If we call this when the earlyOpHandler is not attached, then the queuedMessages may not include the
-        // latest ops.  This could possibly indicate that initialMessages was called twice.
-        assert(this.earlyOpHandlerAttached, 0x08e /* "Potentially missed initial messages" */);
-        // We will lose ops and perf will tank as we need to go to storage to become current!
-        assert(this.listeners("op").length !== 0, 0x08f /* "No op handler is setup!" */);
-
-        this.removeEarlyOpHandler();
-
-        if (this.queuedMessages.length > 0) {
-            // Some messages were queued.
-            // add them to the list of initialMessages to be processed
-            this.details.initialMessages.push(...this.queuedMessages);
-            this.details.initialMessages.sort((a, b) => a.sequenceNumber - b.sequenceNumber);
-            this.queuedMessages.length = 0;
-        }
-        return this.details.initialMessages;
-    }
-
-    /**
-     * Get signals sent during the connection
-     *
-     * @returns signals sent during the connection
-     */
-    public get initialSignals(): ISignalMessage[] {
-        this.checkNotClosed();
-        assert(this.listeners("signal").length !== 0, 0x090 /* "No signal handler is setup!" */);
-
-        this.removeEarlySignalHandler();
-
-        if (this.queuedSignals.length > 0) {
-            // Some signals were queued.
-            // add them to the list of initialSignals to be processed
-            this.details.initialSignals.push(...this.queuedSignals);
-            this.queuedSignals.length = 0;
-        }
-        return this.details.initialSignals;
-    }
-
-    /**
-     * Get initial client list
-     *
-     * @returns initial client list sent during the connection
-     */
-    public get initialClients(): ISignalClient[] {
-        this.checkNotClosed();
-        return this.details.initialClients;
-    }
-
-    protected emitMessages(type: string, messages: IDocumentMessage[][]) {
-        // Although the implementation here disconnects the socket and does not reuse it, other subclasses
-        // (e.g. OdspDocumentDeltaConnection) may reuse the socket.  In these cases, we need to avoid emitting
-        // on the still-live socket.
-        if (!this.disposed) {
-            this.socket.emit(type, this.clientId, messages);
-        }
-    }
-
-    protected submitCore(type: string, messages: IDocumentMessage[]) {
-        this.emitMessages(type, [messages]);
-    }
-
-    /**
-     * Submits a new delta operation to the server
-     *
-     * @param message - delta operation to submit
-     */
-    public submit(messages: IDocumentMessage[]): void {
-        this.checkNotClosed();
-        this.submitCore("submitOp", messages);
-    }
-
-    /**
-     * Submits a new signal to the server
-     *
-     * @param message - signal to submit
-     */
-    public submitSignal(message: IDocumentMessage): void {
-        this.checkNotClosed();
-        this.submitCore("submitSignal", [message]);
-    }
-
-    /**
-     * Disconnect from the websocket and close the websocket too.
-     */
-    protected closeSocket(error: IAnyDriverError) {
-        this.disconnect(error);
-    }
-
-    /**
-     * Disconnect from the websocket, and permanently disable this DocumentDeltaConnection and close the socket.
-     * However the OdspDocumentDeltaConnection differ in dispose as in there we don't close the socket. There is no
-     * multiplexing here, so we need to close the socket here.
-     */
-    public dispose() {
-        this.logger.sendTelemetryEvent({
-            eventName: "ClientClosingDeltaConnection",
-            driverVersion,
-            details: JSON.stringify({ disposed: this._disposed, socketConnected: this.socket.connected }),
-        });
-        this.disconnect(createGenericNetworkError(
-            // pre-0.58 error message: clientClosingConnection
-            "Client closing delta connection", { canRetry: true }, { driverVersion }),
-        );
-    }
-
-    protected disconnect(err: IAnyDriverError) {
-        // Can't check this.disposed here, as we get here on socket closure,
-        // so _disposed & socket.connected might be not in sync while processing
-        // "dispose" event.
-        if (this._disposed) {
-            return;
-        }
-
-        // We set the disposed flag as a part of the contract for overriding the disconnect method. This is used by
-        // DocumentDeltaConnection to determine if emitting messages (ops) on the socket is allowed, which is
-        // important since OdspDocumentDeltaConnection reuses the socket rather than truly disconnecting it. Note that
-        // OdspDocumentDeltaConnection may still send disconnect_document which is allowed; this is only intended
-        // to prevent normal messages from being emitted.
-        this._disposed = true;
-
-        // Let user of connection object know about disconnect. This has to happen in between setting _disposed and
-        // removing all listeners!
-        this.emit("disconnect", err);
-        this.logger.sendTelemetryEvent({
-            eventName: "AfterDisconnectEvent",
-            driverVersion,
-            details: JSON.stringify({
-                socketConnected: this.socket.connected,
-                disconnectListenerCount: this.listenerCount("disconnect"),
-            }),
-        });
-        // user of DeltaConnection should have processed "disconnect" event and removed all listeners. Not clear
-        // if we want to enforce that, as some users (like LocalDocumentService) do not unregister any handlers
-        // assert(this.listenerCount("disconnect") === 0, "'disconnect` events should be processed synchronously");
-
-        this.removeTrackedListeners();
-        this.disconnectCore();
-    }
-
-    /**
-     * Disconnect from the websocket.
-     * @param reason - reason for disconnect
-     */
-    protected disconnectCore() {
-        this.socket.disconnect();
-    }
-
-    protected async initialize(connectMessage: IConnect, timeout: number) {
-        this.socket.on("op", this.earlyOpHandler);
-        this.socket.on("signal", this.earlySignalHandler);
-        this.earlyOpHandlerAttached = true;
-
-        // Socket.io's reconnect_attempt event is unreliable, so we track connect_error count instead.
-        let internalSocketConnectionFailureCount: number = 0;
-        const isInternalSocketReconnectionEnabled = (): boolean => this.socket.io.reconnection();
-        const getMaxInternalSocketReconnectionAttempts = (): number => isInternalSocketReconnectionEnabled()
-            ? this.socket.io.reconnectionAttempts()
-            : 0;
-        const getMaxAllowedInternalSocketConnectionFailures = (): number =>
-            getMaxInternalSocketReconnectionAttempts() + 1;
-
-        this._details = await new Promise<IConnected>((resolve, reject) => {
-            const failAndCloseSocket = (err: IAnyDriverError) => {
-                this.closeSocket(err);
-                reject(err);
-            };
-
-            const failConnection = (err: IAnyDriverError) => {
-                this.disconnect(err);
-                reject(err);
-            };
-            // Listen for connection issues
-            this.addConnectionListener("connect_error", (error) => {
-                internalSocketConnectionFailureCount++;
-                let isWebSocketTransportError = false;
-                try {
-                    const description = error?.description;
-                    if (description && typeof description === "object") {
-                        if (error.type === "TransportError") {
-                            isWebSocketTransportError = true;
-                        }
-                        // That's a WebSocket. Clear it as we can't log it.
-                        description.target = undefined;
-                    }
-                } catch (_e) { }
-
-                // Handle socket transport downgrading when not offline.
-                if (
-                    isWebSocketTransportError &&
-                    this.enableLongPollingDowngrades &&
-                    this.socket.io.opts.transports?.[0] !== "polling") {
-                    // Downgrade transports to polling upgrade mechanism.
-                    this.socket.io.opts.transports = ["polling", "websocket"];
-                    // Don't alter reconnection behavior if already enabled.
-                    if (!isInternalSocketReconnectionEnabled()) {
-                        // Allow single reconnection attempt using polling upgrade mechanism.
-                        this.socket.io.reconnection(true);
-                        this.socket.io.reconnectionAttempts(1);
-                    }
-                }
-
-                // Allow built-in socket.io reconnection handling.
-                if (isInternalSocketReconnectionEnabled() &&
-                    internalSocketConnectionFailureCount < getMaxAllowedInternalSocketConnectionFailures()) {
-                    // Reconnection is enabled and maximum reconnect attempts have not been reached.
-                    return;
-                }
-
-                failAndCloseSocket(this.createErrorObject("connect_error", error));
-            });
-
-            // Listen for timeouts
-            this.addConnectionListener("connect_timeout", () => {
-                failAndCloseSocket(this.createErrorObject("connect_timeout"));
-            });
-
-            this.addConnectionListener("connect_document_success", (response: IConnected) => {
-                // If we sent a nonce and the server supports nonces, check that the nonces match
-                if (connectMessage.nonce !== undefined &&
-                    response.nonce !== undefined &&
-                    response.nonce !== connectMessage.nonce) {
-                    return;
-                }
-
-                const requestedMode = connectMessage.mode;
-                const actualMode = response.mode;
-                const writingPermitted = response.claims.scopes.includes(ScopeType.DocWrite);
-
-                if (writingPermitted) {
-                    // The only time we expect a mismatch in requested/actual is if we lack write permissions
-                    // In this case we will get "read", even if we requested "write"
-                    if (actualMode !== requestedMode) {
-                        failConnection(this.createErrorObject(
-                            "connect_document_success",
-                            "Connected in a different mode than was requested",
-                            false,
-                        ));
-                        return;
-                    }
-                } else {
-                    if (actualMode === "write") {
-                        failConnection(this.createErrorObject(
-                            "connect_document_success",
-                            "Connected in write mode without write permissions",
-                            false,
-                        ));
-                        return;
-                    }
-                }
-
-                this.checkpointSequenceNumber = response.checkpointSequenceNumber;
-
-                this.removeConnectionListeners();
-                resolve(response);
-            });
-
-            // Socket can be disconnected while waiting for Fluid protocol messages
-            // (connect_document_error / connect_document_success), as well as before DeltaManager
-            // had a chance to register its handlers.
-            this.addTrackedListener("disconnect", (reason) => {
-                const err = this.createErrorObject("disconnect", reason);
-                failAndCloseSocket(err);
-            });
-
-            this.addTrackedListener("error", ((error) => {
-                // This includes "Invalid namespace" error, which we consider critical (reconnecting will not help)
-                const err = this.createErrorObject("error", error, error !== "Invalid namespace");
-                // Disconnect socket - required if happened before initial handshake
-                failAndCloseSocket(err);
-            }));
-
-            this.addConnectionListener("connect_document_error", ((error) => {
-                // If we sent a nonce and the server supports nonces, check that the nonces match
-                if (connectMessage.nonce !== undefined &&
-                    error.nonce !== undefined &&
-                    error.nonce !== connectMessage.nonce) {
-                    return;
-                }
-
-                // This is not an socket.io error - it's Fluid protocol error.
-                // In this case fail connection and indicate that we were unable to create connection
-                failConnection(this.createErrorObject("connect_document_error", error));
-            }));
-
-            this.socket.emit("connect_document", connectMessage);
-
-            // Give extra 2 seconds for handshake on top of socket connection timeout
-            this.socketConnectionTimeout = setTimeout(() => {
-                failConnection(this.createErrorObject("orderingServiceHandshakeTimeout"));
-            }, timeout + 2000);
-        });
-
-        assert(!this.disposed, 0x246 /* "checking consistency of socket & _disposed flags" */);
-    }
-
-    protected earlyOpHandler = (documentId: string, msgs: ISequencedDocumentMessage[]) => {
-        this.queuedMessages.push(...msgs);
-    };
-
-    protected earlySignalHandler = (msg: ISignalMessage) => {
-        this.queuedSignals.push(msg);
-    };
-
-    private removeEarlyOpHandler() {
-        this.socket.removeListener("op", this.earlyOpHandler);
-        this.earlyOpHandlerAttached = false;
-    }
-
-    private removeEarlySignalHandler() {
-        this.socket.removeListener("signal", this.earlySignalHandler);
-    }
-
-    private addConnectionListener(event: string, listener: (...args: any[]) => void) {
-        assert(!DocumentDeltaConnection.eventsAlwaysForwarded.includes(event),
-            0x247 /* "Use addTrackedListener instead" */);
-        assert(!DocumentDeltaConnection.eventsToForward.includes(event),
-            0x248 /* "should not subscribe to forwarded events" */);
-        this.socket.on(event, listener);
-        assert(!this.connectionListeners.has(event), 0x20d /* "double connection listener" */);
-        this.connectionListeners.set(event, listener);
-    }
-
-    protected addTrackedListener(event: string, listener: (...args: any[]) => void) {
-        this.socket.on(event, listener);
-        assert(!this.trackedListeners.has(event), 0x20e /* "double tracked listener" */);
-        this.trackedListeners.set(event, listener);
-    }
-
-    private removeTrackedListeners() {
-        for (const [event, listener] of this.trackedListeners.entries()) {
-            this.socket.off(event, listener);
-        }
-        // removeTrackedListeners removes all listeners, including connection listeners
-        this.removeConnectionListeners();
-
-        this.removeEarlyOpHandler();
-        this.removeEarlySignalHandler();
-
-        this.trackedListeners.clear();
-    }
-
-    private removeConnectionListeners() {
-        if (this.socketConnectionTimeout !== undefined) {
-            clearTimeout(this.socketConnectionTimeout);
-        }
-
-        for (const [event, listener] of this.connectionListeners.entries()) {
-            this.socket.off(event, listener);
-        }
-        this.connectionListeners.clear();
-    }
-
-    /**
-     * Error raising for socket.io issues
-     */
-    protected createErrorObject(handler: string, error?: any, canRetry = true): IAnyDriverError {
-        // Note: we suspect the incoming error object is either:
-        // - a string: log it in the message (if not a string, it may contain PII but will print as [object Object])
-        // - an Error object thrown by socket.io engine. Be careful with not recording PII!
-        let message: string;
-        if (error?.type === "TransportError") {
-            // JSON.stringify drops Error.message
-            const messagePrefix = (error?.message !== undefined)
-                ? `${error.message}: `
-                : "";
-
-            // Websocket errors reported by engine.io-client.
-            // They are Error objects with description containing WS error and description = "TransportError"
-            // Please see https://github.com/socketio/engine.io-client/blob/7245b80/lib/transport.ts#L44,
-            message = `${messagePrefix}${JSON.stringify(error, getCircularReplacer())}`;
-        } else {
-            message = extractLogSafeErrorProperties(error, true).message;
-        }
-
-        const errorObj = createGenericNetworkError(
-            `socket.io (${handler}): ${message}`,
-            { canRetry },
-            { driverVersion },
-        );
-
-        return errorObj;
-    }
+	extends EventEmitterWithErrorHandling<IDocumentDeltaConnectionEvents>
+	implements IDocumentDeltaConnection, IDisposable
+{
+	static readonly eventsToForward = ["nack", "op", "signal", "pong"];
+
+	// WARNING: These are critical events that we can't miss, so registration for them has to be in place at all times!
+	// Including before handshake is over, and after that (but before DeltaManager had a chance to put its own handlers)
+	static readonly eventsAlwaysForwarded = ["disconnect", "error"];
+
+	/**
+	 * Last known sequence number to ordering service at the time of connection
+	 * It may lap actual last sequence number (quite a bit, if container  is very active).
+	 * But it's best information for client to figure out how far it is behind, at least
+	 * for "read" connections. "write" connections may use own "join" op to similar information,
+	 * that is likely to be more up-to-date.
+	 */
+	public checkpointSequenceNumber: number | undefined;
+
+	// Listen for ops sent before we receive a response to connect_document
+	protected readonly queuedMessages: ISequencedDocumentMessage[] = [];
+	protected readonly queuedSignals: ISignalMessage[] = [];
+
+	/**
+	 * A flag to indicate whether we have our handler attached.  If it's attached, we're queueing incoming ops
+	 * to later be retrieved via initialMessages.
+	 */
+	private earlyOpHandlerAttached: boolean = false;
+
+	private socketConnectionTimeout: ReturnType<typeof setTimeout> | undefined;
+
+	private _details: IConnected | undefined;
+
+	// Listeners only needed while the connection is in progress
+	private readonly connectionListeners: Map<string, (...args: any[]) => void> = new Map();
+	// Listeners used throughout the lifetime of the DocumentDeltaConnection
+	private readonly trackedListeners: Map<string, (...args: any[]) => void> = new Map();
+
+	protected get hasDetails(): boolean {
+		return !!this._details;
+	}
+
+	public get disposed() {
+		// Increase the stack trace limit temporarily, so as to debug better in case it occurs.
+		// We are seeing this in telemetry and we are unable to figure out why it is happening, so this should help.
+		const originalStackTraceLimit = (Error as any).stackTraceLimit;
+		try {
+			(Error as any).stackTraceLimit = 50;
+			assert(
+				this._disposed || this.socket.connected,
+				0x244 /* "Socket is closed, but connection is not!" */,
+			);
+		} catch (error) {
+			const normalizedError = this.addPropsToError(error);
+			throw normalizedError;
+		} finally {
+			(Error as any).stackTraceLimit = originalStackTraceLimit;
+		}
+		return this._disposed;
+	}
+
+	/**
+	 * Flag to indicate whether the DocumentDeltaConnection is expected to still be capable of sending messages.
+	 * After disconnection, we flip this to prevent any stale messages from being emitted.
+	 */
+	protected _disposed: boolean = false;
+	private readonly mc: MonitoringContext;
+
+	/**
+	 * @deprecated Implementors should manage their own logger or monitoring context
+	 */
+	protected get logger(): ITelemetryLogger {
+		return this.mc.logger;
+	}
+
+	public get details(): IConnected {
+		if (!this._details) {
+			throw new Error("Internal error: calling method before _details is initialized!");
+		}
+		return this._details;
+	}
+
+	/**
+	 * @param socket - websocket to be used
+	 * @param documentId - ID of the document
+	 * @param logger - for reporting telemetry events
+	 * @param enableLongPollingDowngrades - allow connection to be downgraded to long-polling on websocket failure
+	 */
+	protected constructor(
+		protected readonly socket: Socket,
+		public documentId: string,
+		logger: ITelemetryLogger,
+		private readonly enableLongPollingDowngrades: boolean = false,
+		protected readonly connectionId?: string,
+	) {
+		super((name, error) => {
+			logger.sendErrorEvent(
+				{
+					eventName: "DeltaConnection:EventException",
+					name,
+				},
+				error,
+			);
+		});
+
+		this.mc = loggerToMonitoringContext(ChildLogger.create(logger, "DeltaConnection"));
+
+		this.on("newListener", (event, listener) => {
+			assert(!this.disposed, 0x20a /* "register for event on disposed object" */);
+
+			// Some events are already forwarded - see this.addTrackedListener() calls in initialize().
+			if (DocumentDeltaConnection.eventsAlwaysForwarded.includes(event)) {
+				assert(this.trackedListeners.has(event), 0x245 /* "tracked listener" */);
+				return;
+			}
+
+			if (!DocumentDeltaConnection.eventsToForward.includes(event)) {
+				throw new Error(`DocumentDeltaConnection: Registering for unknown event: ${event}`);
+			}
+
+			// Whenever listener is added, we should subscribe on same event on socket, so these two things
+			// should be in sync. This currently assumes that nobody unregisters and registers back listeners,
+			// and that there are no "internal" listeners installed (like "error" case we skip above)
+			// Better flow might be to always unconditionally register all handlers on successful connection,
+			// though some logic (naming assert in initialMessages getter) might need to be adjusted (it becomes noop)
+			assert(
+				(this.listeners(event).length !== 0) === this.trackedListeners.has(event),
+				0x20b /* "mismatch" */,
+			);
+			if (!this.trackedListeners.has(event)) {
+				this.addTrackedListener(event, (...args: any[]) => {
+					this.emit(event, ...args);
+				});
+			}
+		});
+	}
+
+	/**
+	 * Get the ID of the client who is sending the message
+	 *
+	 * @returns the client ID
+	 */
+	public get clientId(): string {
+		return this.details.clientId;
+	}
+
+	/**
+	 * Get the mode of the client
+	 *
+	 * @returns the client mode
+	 */
+	public get mode(): ConnectionMode {
+		return this.details.mode;
+	}
+
+	/**
+	 * Get the claims of the client who is sending the message
+	 *
+	 * @returns client claims
+	 */
+	public get claims(): ITokenClaims {
+		return this.details.claims;
+	}
+
+	/**
+	 * Get whether or not this is an existing document
+	 *
+	 * @returns true if the document exists
+	 */
+	public get existing(): boolean {
+		return this.details.existing;
+	}
+
+	/**
+	 * Get the maximum size of a message before chunking is required
+	 *
+	 * @returns the maximum size of a message before chunking is required
+	 */
+	public get maxMessageSize(): number {
+		return this.details.serviceConfiguration.maxMessageSize;
+	}
+
+	/**
+	 * Semver of protocol being used with the service
+	 */
+	public get version(): string {
+		return this.details.version;
+	}
+
+	/**
+	 * Configuration details provided by the service
+	 */
+	public get serviceConfiguration(): IClientConfiguration {
+		return this.details.serviceConfiguration;
+	}
+
+	private checkNotClosed() {
+		// Increase the stack trace limit temporarily, so as to debug better in case it occurs.
+		// We are seeing this in telemetry and we are unable to figure out why it is happening, so this should help.
+		const originalStackTraceLimit = (Error as any).stackTraceLimit;
+		try {
+			(Error as any).stackTraceLimit = 50;
+			assert(!this.disposed, 0x20c /* "connection disposed" */);
+		} catch (error) {
+			const normalizedError = this.addPropsToError(error);
+			throw normalizedError;
+		} finally {
+			(Error as any).stackTraceLimit = originalStackTraceLimit;
+		}
+	}
+
+	/**
+	 * Get messages sent during the connection
+	 *
+	 * @returns messages sent during the connection
+	 */
+	public get initialMessages(): ISequencedDocumentMessage[] {
+		this.checkNotClosed();
+
+		// If we call this when the earlyOpHandler is not attached, then the queuedMessages may not include the
+		// latest ops.  This could possibly indicate that initialMessages was called twice.
+		assert(this.earlyOpHandlerAttached, 0x08e /* "Potentially missed initial messages" */);
+		// We will lose ops and perf will tank as we need to go to storage to become current!
+		assert(this.listeners("op").length !== 0, 0x08f /* "No op handler is setup!" */);
+
+		this.removeEarlyOpHandler();
+
+		if (this.queuedMessages.length > 0) {
+			// Some messages were queued.
+			// add them to the list of initialMessages to be processed
+			this.details.initialMessages.push(...this.queuedMessages);
+			this.details.initialMessages.sort((a, b) => a.sequenceNumber - b.sequenceNumber);
+			this.queuedMessages.length = 0;
+		}
+		return this.details.initialMessages;
+	}
+
+	/**
+	 * Get signals sent during the connection
+	 *
+	 * @returns signals sent during the connection
+	 */
+	public get initialSignals(): ISignalMessage[] {
+		this.checkNotClosed();
+		assert(this.listeners("signal").length !== 0, 0x090 /* "No signal handler is setup!" */);
+
+		this.removeEarlySignalHandler();
+
+		if (this.queuedSignals.length > 0) {
+			// Some signals were queued.
+			// add them to the list of initialSignals to be processed
+			this.details.initialSignals.push(...this.queuedSignals);
+			this.queuedSignals.length = 0;
+		}
+		return this.details.initialSignals;
+	}
+
+	/**
+	 * Get initial client list
+	 *
+	 * @returns initial client list sent during the connection
+	 */
+	public get initialClients(): ISignalClient[] {
+		this.checkNotClosed();
+		return this.details.initialClients;
+	}
+
+	protected emitMessages(type: string, messages: IDocumentMessage[][]) {
+		// Although the implementation here disconnects the socket and does not reuse it, other subclasses
+		// (e.g. OdspDocumentDeltaConnection) may reuse the socket.  In these cases, we need to avoid emitting
+		// on the still-live socket.
+		if (!this.disposed) {
+			this.socket.emit(type, this.clientId, messages);
+		}
+	}
+
+	protected submitCore(type: string, messages: IDocumentMessage[]) {
+		this.emitMessages(type, [messages]);
+	}
+
+	/**
+	 * Submits a new delta operation to the server
+	 *
+	 * @param message - delta operation to submit
+	 */
+	public submit(messages: IDocumentMessage[]): void {
+		this.checkNotClosed();
+		this.submitCore("submitOp", messages);
+	}
+
+	/**
+	 * Submits a new signal to the server
+	 *
+	 * @param message - signal to submit
+	 */
+	public submitSignal(message: IDocumentMessage): void {
+		this.checkNotClosed();
+		this.submitCore("submitSignal", [message]);
+	}
+
+	/**
+	 * Disconnect from the websocket and close the websocket too.
+	 */
+	private closeSocket(error: IAnyDriverError) {
+		if (this._disposed) {
+			// This would be rare situation due to complexity around socket emitting events.
+			this.logger.sendTelemetryEvent(
+				{
+					eventName: "SocketCloseOnDisposedConnection",
+					driverVersion,
+					details: JSON.stringify({
+						...this.getConnectionDetailsProps(),
+						trackedListenerCount: this.trackedListeners.size,
+					}),
+				},
+				error,
+			);
+			return;
+		}
+		this.closeSocketCore(error);
+	}
+
+	protected closeSocketCore(error: IAnyDriverError) {
+		this.disconnect(error);
+	}
+
+	/**
+	 * Disconnect from the websocket, and permanently disable this DocumentDeltaConnection and close the socket.
+	 * However the OdspDocumentDeltaConnection differ in dispose as in there we don't close the socket. There is no
+	 * multiplexing here, so we need to close the socket here.
+	 */
+	public dispose() {
+		this.logger.sendTelemetryEvent({
+			eventName: "ClientClosingDeltaConnection",
+			driverVersion,
+			details: JSON.stringify({
+				...this.getConnectionDetailsProps(),
+			}),
+		});
+		this.disconnect(
+			createGenericNetworkError(
+				// pre-0.58 error message: clientClosingConnection
+				"Client closing delta connection",
+				{ canRetry: true },
+				{ driverVersion },
+			),
+		);
+	}
+
+	protected disconnect(err: IAnyDriverError) {
+		// Can't check this.disposed here, as we get here on socket closure,
+		// so _disposed & socket.connected might be not in sync while processing
+		// "dispose" event.
+		if (this._disposed) {
+			return;
+		}
+
+		// We set the disposed flag as a part of the contract for overriding the disconnect method. This is used by
+		// DocumentDeltaConnection to determine if emitting messages (ops) on the socket is allowed, which is
+		// important since OdspDocumentDeltaConnection reuses the socket rather than truly disconnecting it. Note that
+		// OdspDocumentDeltaConnection may still send disconnect_document which is allowed; this is only intended
+		// to prevent normal messages from being emitted.
+		this._disposed = true;
+
+		// Remove all listeners listening on the socket. These are listeners on socket and not on this connection
+		// object. Anyway since we have disposed this connection object, nobody should listen to event on socket
+		// anymore.
+		this.removeTrackedListeners();
+
+		// Clear the connection/socket before letting the deltaManager/connection manager know about the disconnect.
+		this.disconnectCore();
+
+		// Let user of connection object know about disconnect.
+		this.emit("disconnect", err);
+		this.logger.sendTelemetryEvent({
+			eventName: "AfterDisconnectEvent",
+			driverVersion,
+			details: JSON.stringify({
+				...this.getConnectionDetailsProps(),
+				disconnectListenerCount: this.listenerCount("disconnect"),
+			}),
+		});
+	}
+
+	/**
+	 * Disconnect from the websocket.
+	 * @param reason - reason for disconnect
+	 */
+	protected disconnectCore() {
+		this.socket.disconnect();
+	}
+
+	protected async initialize(connectMessage: IConnect, timeout: number) {
+		this.socket.on("op", this.earlyOpHandler);
+		this.socket.on("signal", this.earlySignalHandler);
+		this.earlyOpHandlerAttached = true;
+
+		// Socket.io's reconnect_attempt event is unreliable, so we track connect_error count instead.
+		let internalSocketConnectionFailureCount: number = 0;
+		const isInternalSocketReconnectionEnabled = (): boolean => this.socket.io.reconnection();
+		const getMaxInternalSocketReconnectionAttempts = (): number =>
+			isInternalSocketReconnectionEnabled() ? this.socket.io.reconnectionAttempts() : 0;
+		const getMaxAllowedInternalSocketConnectionFailures = (): number =>
+			getMaxInternalSocketReconnectionAttempts() + 1;
+
+		this._details = await new Promise<IConnected>((resolve, reject) => {
+			const failAndCloseSocket = (err: IAnyDriverError) => {
+				try {
+					this.closeSocket(err);
+				} catch (failError) {
+					const normalizedError = this.addPropsToError(failError);
+					this.logger.sendErrorEvent({ eventName: "CloseSocketError" }, normalizedError);
+				}
+				reject(err);
+			};
+
+			const failConnection = (err: IAnyDriverError) => {
+				try {
+					this.disconnect(err);
+				} catch (failError) {
+					const normalizedError = this.addPropsToError(failError);
+					this.logger.sendErrorEvent(
+						{ eventName: "FailConnectionError" },
+						normalizedError,
+					);
+				}
+				reject(err);
+			};
+
+			// Immediately set the connection timeout.
+			// Give extra 2 seconds for handshake on top of socket connection timeout.
+			this.socketConnectionTimeout = setTimeout(() => {
+				failConnection(this.createErrorObject("orderingServiceHandshakeTimeout"));
+			}, timeout + 2000);
+
+			// Listen for connection issues
+			this.addConnectionListener("connect_error", (error) => {
+				internalSocketConnectionFailureCount++;
+				let isWebSocketTransportError = false;
+				try {
+					const description = error?.description;
+					const context = error?.context;
+
+					if (context && typeof context === "object") {
+						const statusText = context.statusText?.code;
+
+						// Self-Signed Certificate ErrorCode Found in error.context
+						if (statusText === "DEPTH_ZERO_SELF_SIGNED_CERT") {
+							failAndCloseSocket(
+								this.createErrorObject("connect_error", error, false),
+							);
+							return;
+						}
+					} else if (description && typeof description === "object") {
+						const errorCode = description.error?.code;
+
+						// Self-Signed Certificate ErrorCode Found in error.description
+						if (errorCode === "DEPTH_ZERO_SELF_SIGNED_CERT") {
+							failAndCloseSocket(
+								this.createErrorObject("connect_error", error, false),
+							);
+							return;
+						}
+
+						if (error.type === "TransportError") {
+							isWebSocketTransportError = true;
+						}
+
+						// That's a WebSocket. Clear it as we can't log it.
+						description.target = undefined;
+					}
+				} catch (_e) {}
+
+				// Handle socket transport downgrading when not offline.
+				if (
+					isWebSocketTransportError &&
+					this.enableLongPollingDowngrades &&
+					this.socket.io.opts.transports?.[0] !== "polling"
+				) {
+					// Downgrade transports to polling upgrade mechanism.
+					this.socket.io.opts.transports = ["polling", "websocket"];
+					// Don't alter reconnection behavior if already enabled.
+					if (!isInternalSocketReconnectionEnabled()) {
+						// Allow single reconnection attempt using polling upgrade mechanism.
+						this.socket.io.reconnection(true);
+						this.socket.io.reconnectionAttempts(1);
+					}
+				}
+
+				// Allow built-in socket.io reconnection handling.
+				if (
+					isInternalSocketReconnectionEnabled() &&
+					internalSocketConnectionFailureCount <
+						getMaxAllowedInternalSocketConnectionFailures()
+				) {
+					// Reconnection is enabled and maximum reconnect attempts have not been reached.
+					return;
+				}
+
+				failAndCloseSocket(this.createErrorObject("connect_error", error));
+			});
+
+			// Listen for timeouts
+			this.addConnectionListener("connect_timeout", () => {
+				failAndCloseSocket(this.createErrorObject("connect_timeout"));
+			});
+
+			this.addConnectionListener("connect_document_success", (response: IConnected) => {
+				// If we sent a nonce and the server supports nonces, check that the nonces match
+				if (
+					connectMessage.nonce !== undefined &&
+					response.nonce !== undefined &&
+					response.nonce !== connectMessage.nonce
+				) {
+					return;
+				}
+
+				const requestedMode = connectMessage.mode;
+				const actualMode = response.mode;
+				const writingPermitted = response.claims.scopes.includes(ScopeType.DocWrite);
+
+				if (writingPermitted) {
+					// The only time we expect a mismatch in requested/actual is if we lack write permissions
+					// In this case we will get "read", even if we requested "write"
+					if (actualMode !== requestedMode) {
+						failConnection(
+							this.createErrorObject(
+								"connect_document_success",
+								"Connected in a different mode than was requested",
+								false,
+							),
+						);
+						return;
+					}
+				} else {
+					if (actualMode === "write") {
+						failConnection(
+							this.createErrorObject(
+								"connect_document_success",
+								"Connected in write mode without write permissions",
+								false,
+							),
+						);
+						return;
+					}
+				}
+
+				this.checkpointSequenceNumber = response.checkpointSequenceNumber;
+
+				this.removeConnectionListeners();
+				resolve(response);
+			});
+
+			// Socket can be disconnected while waiting for Fluid protocol messages
+			// (connect_document_error / connect_document_success), as well as before DeltaManager
+			// had a chance to register its handlers.
+			this.addTrackedListener("disconnect", (reason) => {
+				const err = this.createErrorObject("disconnect", reason);
+				failAndCloseSocket(err);
+			});
+
+			this.addTrackedListener("error", (error) => {
+				// This includes "Invalid namespace" error, which we consider critical (reconnecting will not help)
+				const err = this.createErrorObject("error", error, error !== "Invalid namespace");
+				// Disconnect socket - required if happened before initial handshake
+				failAndCloseSocket(err);
+			});
+
+			this.addConnectionListener("connect_document_error", (error) => {
+				// If we sent a nonce and the server supports nonces, check that the nonces match
+				if (
+					connectMessage.nonce !== undefined &&
+					error.nonce !== undefined &&
+					error.nonce !== connectMessage.nonce
+				) {
+					return;
+				}
+
+				// This is not an socket.io error - it's Fluid protocol error.
+				// In this case fail connection and indicate that we were unable to create connection
+				failConnection(this.createErrorObject("connect_document_error", error));
+			});
+
+			this.socket.emit("connect_document", connectMessage);
+		});
+
+		assert(!this.disposed, 0x246 /* "checking consistency of socket & _disposed flags" */);
+	}
+
+	private addPropsToError(errorToBeNormalized: unknown) {
+		const normalizedError = normalizeError(errorToBeNormalized, {
+			props: {
+				details: JSON.stringify({
+					...this.getConnectionDetailsProps(),
+				}),
+			},
+		});
+		return normalizedError;
+	}
+
+	private getConnectionDetailsProps() {
+		return {
+			disposed: this._disposed,
+			socketConnected: this.socket?.connected,
+			clientId: this._details?.clientId,
+			connectionId: this.connectionId,
+		};
+	}
+
+	protected earlyOpHandler = (documentId: string, msgs: ISequencedDocumentMessage[]) => {
+		this.queuedMessages.push(...msgs);
+	};
+
+	protected earlySignalHandler = (msg: ISignalMessage) => {
+		this.queuedSignals.push(msg);
+	};
+
+	private removeEarlyOpHandler() {
+		this.socket.removeListener("op", this.earlyOpHandler);
+		this.earlyOpHandlerAttached = false;
+	}
+
+	private removeEarlySignalHandler() {
+		this.socket.removeListener("signal", this.earlySignalHandler);
+	}
+
+	private addConnectionListener(event: string, listener: (...args: any[]) => void) {
+		assert(
+			!DocumentDeltaConnection.eventsAlwaysForwarded.includes(event),
+			0x247 /* "Use addTrackedListener instead" */,
+		);
+		assert(
+			!DocumentDeltaConnection.eventsToForward.includes(event),
+			0x248 /* "should not subscribe to forwarded events" */,
+		);
+		this.socket.on(event, listener);
+		assert(!this.connectionListeners.has(event), 0x20d /* "double connection listener" */);
+		this.connectionListeners.set(event, listener);
+	}
+
+	protected addTrackedListener(event: string, listener: (...args: any[]) => void) {
+		this.socket.on(event, listener);
+		assert(!this.trackedListeners.has(event), 0x20e /* "double tracked listener" */);
+		this.trackedListeners.set(event, listener);
+	}
+
+	private removeTrackedListeners() {
+		for (const [event, listener] of this.trackedListeners.entries()) {
+			this.socket.off(event, listener);
+		}
+		// removeTrackedListeners removes all listeners, including connection listeners
+		this.removeConnectionListeners();
+
+		this.removeEarlyOpHandler();
+		this.removeEarlySignalHandler();
+
+		this.trackedListeners.clear();
+	}
+
+	private removeConnectionListeners() {
+		if (this.socketConnectionTimeout !== undefined) {
+			clearTimeout(this.socketConnectionTimeout);
+		}
+
+		for (const [event, listener] of this.connectionListeners.entries()) {
+			this.socket.off(event, listener);
+		}
+		this.connectionListeners.clear();
+	}
+
+	/**
+	 * Error raising for socket.io issues
+	 */
+	protected createErrorObject(handler: string, error?: any, canRetry = true): IAnyDriverError {
+		// Note: we suspect the incoming error object is either:
+		// - a string: log it in the message (if not a string, it may contain PII but will print as [object Object])
+		// - an Error object thrown by socket.io engine. Be careful with not recording PII!
+		let message: string;
+		if (error?.type === "TransportError") {
+			// JSON.stringify drops Error.message
+			const messagePrefix = error?.message !== undefined ? `${error.message}: ` : "";
+
+			// Websocket errors reported by engine.io-client.
+			// They are Error objects with description containing WS error and description = "TransportError"
+			// Please see https://github.com/socketio/engine.io-client/blob/7245b80/lib/transport.ts#L44,
+			message = `${messagePrefix}${JSON.stringify(error, getCircularReplacer())}`;
+		} else {
+			message = extractLogSafeErrorProperties(error, true).message;
+		}
+
+		const errorObj = createGenericNetworkError(
+			`socket.io (${handler}): ${message}`,
+			{ canRetry },
+			{
+				driverVersion,
+				details: JSON.stringify({
+					...this.getConnectionDetailsProps(),
+				}),
+			},
+		);
+
+		return errorObj;
+	}
 }