@fluidframework/container-loader 2.0.0-internal.5.4.0 → 2.0.0-internal.6.1.0

package/src/deltaManager.ts

@@ -7,13 +7,11 @@ 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 {
@@ -27,7 +25,6 @@ import {
 	IDocumentDeltaStorageService,
 	IDocumentService,
 	DriverErrorType,
-	IAnyDriverError,
 } from "@fluidframework/driver-definitions";
 import {
 	IDocumentMessage,
@@ -44,14 +41,19 @@ import {
 	DataProcessingError,
 	UsageError,
 } from "@fluidframework/container-utils";
-import { IConnectionManagerFactoryArgs, IConnectionManager } from "./contracts";
+import {
+	IConnectionDetailsInternal,
+	IConnectionManager,
+	IConnectionManagerFactoryArgs,
+	IConnectionStateChangeReason,
+} from "./contracts";
 import { DeltaQueue } from "./deltaQueue";
 import { OnlyValidTermValue } from "./protocol";
 
 export interface IConnectionArgs {
 	mode?: ConnectionMode;
 	fetchOpsFromStorage?: boolean;
-	reason: string;
+	reason: IConnectionStateChangeReason;
 }
 
 /**
@@ -62,8 +64,11 @@ 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,
+	);
 }
 
 /**
@@ -73,6 +78,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
  */
@@ -330,6 +350,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,
 		};
 	}
@@ -383,15 +404,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);
@@ -431,11 +454,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);
 	}
 
@@ -495,7 +518,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;
@@ -569,7 +592,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);
@@ -755,9 +778,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);
 	}
 
 	/**

package/src/loader.ts

@@ -37,7 +37,7 @@ 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";
@@ -45,11 +45,7 @@ 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(
@@ -68,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;
 	}
@@ -99,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);
@@ -348,6 +350,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 get IFluidRouter(): IFluidRouter {
 		return this;
 	}
@@ -383,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,
@@ -456,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) {
@@ -477,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(
@@ -508,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.4.0";
+export const pkgVersion = "2.0.0-internal.6.1.0";

package/src/protocol.ts

@@ -4,6 +4,7 @@
  */
 
 import { IAudienceOwner } from "@fluidframework/container-definitions";
+import { canBeCoalescedByService } from "@fluidframework/driver-utils";
 import {
 	IProtocolHandler as IBaseProtocolHandler,
 	IQuorumSnapshot,
@@ -11,8 +12,12 @@ import {
 } from "@fluidframework/protocol-base";
 import {
 	IDocumentAttributes,
+	IProcessMessageResult,
+	ISequencedClient,
+	ISequencedDocumentMessage,
 	ISignalClient,
 	ISignalMessage,
+	MessageType,
 } from "@fluidframework/protocol-definitions";
 
 // "term" was an experimental feature that is being removed.  The only safe value to use is 1.
@@ -44,12 +49,12 @@ export class ProtocolHandler extends ProtocolOpHandler implements IProtocolHandl
 		attributes: IDocumentAttributes,
 		quorumSnapshot: IQuorumSnapshot,
 		sendProposal: (key: string, value: any) => number,
-		readonly audience: IAudienceOwner,
+		public readonly audience: IAudienceOwner,
+		private readonly shouldClientHaveLeft: (clientId: string) => boolean,
 	) {
 		super(
 			attributes.minimumSequenceNumber,
 			attributes.sequenceNumber,
-			OnlyValidTermValue,
 			quorumSnapshot.members,
 			quorumSnapshot.proposals,
 			quorumSnapshot.values,
@@ -66,6 +71,32 @@ export class ProtocolHandler extends ProtocolOpHandler implements IProtocolHandl
 		}
 	}
 
+	public processMessage(
+		message: ISequencedDocumentMessage,
+		local: boolean,
+	): IProcessMessageResult {
+		const client: ISequencedClient | undefined = this.quorum.getMember(message.clientId);
+
+		// Check and report if we're getting messages from a clientId that we previously
+		// flagged as shouldHaveLeft, or from a client that's not in the quorum but should be
+		if (message.clientId != null) {
+			if (client === undefined && message.type !== MessageType.ClientJoin) {
+				// pre-0.58 error message: messageClientIdMissingFromQuorum
+				throw new Error("Remote message's clientId is missing from the quorum");
+			}
+
+			// Here checking canBeCoalescedByService is used as an approximation of "is benign to process despite being unexpected".
+			// It's still not good to see these messages from unexpected clientIds, but since they don't harm the integrity of the
+			// document we don't need to blow up aggressively.
+			if (this.shouldClientHaveLeft(message.clientId) && !canBeCoalescedByService(message)) {
+				// pre-0.58 error message: messageClientIdShouldHaveLeft
+				throw new Error("Remote message's clientId already should have left");
+			}
+		}
+
+		return super.processMessage(message, local);
+	}
+
 	public processSignal(message: ISignalMessage) {
 		const innerContent = message.content as { content: any; type: string };
 		switch (innerContent.type) {

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