@fluidframework/container-loader 2.20.0 → 2.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/container-loader",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Fluid container loader",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -119,13 +119,13 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.20.0",
-    "@fluidframework/container-definitions": "~2.20.0",
-    "@fluidframework/core-interfaces": "~2.20.0",
-    "@fluidframework/core-utils": "~2.20.0",
-    "@fluidframework/driver-definitions": "~2.20.0",
-    "@fluidframework/driver-utils": "~2.20.0",
-    "@fluidframework/telemetry-utils": "~2.20.0",
+    "@fluid-internal/client-utils": "~2.21.0",
+    "@fluidframework/container-definitions": "~2.21.0",
+    "@fluidframework/core-interfaces": "~2.21.0",
+    "@fluidframework/core-utils": "~2.21.0",
+    "@fluidframework/driver-definitions": "~2.21.0",
+    "@fluidframework/driver-utils": "~2.21.0",
+    "@fluidframework/telemetry-utils": "~2.21.0",
     "@types/events_pkg": "npm:@types/events@^3.0.0",
     "@ungap/structured-clone": "^1.2.0",
     "debug": "^4.3.4",
@@ -136,14 +136,14 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/client-utils": "~2.20.0",
-    "@fluid-internal/mocha-test-setup": "~2.20.0",
-    "@fluid-private/test-loader-utils": "~2.20.0",
+    "@fluid-internal/client-utils": "~2.21.0",
+    "@fluid-internal/mocha-test-setup": "~2.21.0",
+    "@fluid-private/test-loader-utils": "~2.21.0",
     "@fluid-tools/build-cli": "^0.51.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.51.0",
-    "@fluidframework/container-loader-previous": "npm:@fluidframework/container-loader@2.13.0",
-    "@fluidframework/eslint-config-fluid": "^5.6.0",
+    "@fluidframework/container-loader-previous": "npm:@fluidframework/container-loader@2.20.0",
+    "@fluidframework/eslint-config-fluid": "^5.7.3",
     "@microsoft/api-extractor": "7.47.8",
     "@types/debug": "^4.1.5",
     "@types/double-ended-queue": "^2.1.0",
@@ -199,7 +199,7 @@
     "ci:build:api-reports:current": "api-extractor run --config api-extractor/api-extractor.current.json",
     "ci:build:api-reports:legacy": "api-extractor run --config api-extractor/api-extractor.legacy.json",
     "ci:build:docs": "api-extractor run",
-    "clean": "rimraf --glob dist lib \"*.d.ts\" \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
+    "clean": "rimraf --glob dist lib {alpha,beta,internal,legacy}.d.ts \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
     "eslint": "eslint --format stylish src",
     "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
     "format": "npm run format:biome",

package/src/connectionManager.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { TypedEventEmitter, performance } from "@fluid-internal/client-utils";
+import { TypedEventEmitter, performanceNow } from "@fluid-internal/client-utils";
 import { ICriticalContainerError } from "@fluidframework/container-definitions";
 import { IDeltaQueue, ReadOnlyInfo } from "@fluidframework/container-definitions/internal";
 import {
@@ -583,7 +583,7 @@ export class ConnectionManager implements IConnectionManager {
 
 		let delayMs = InitialReconnectDelayInMs;
 		let connectRepeatCount = 0;
-		const connectStartTime = performance.now();
+		const connectStartTime = performanceNow();
 		let lastError: unknown;
 
 		const abortController = new AbortController();
@@ -604,7 +604,7 @@ export class ConnectionManager implements IConnectionManager {
 				this.logger.sendTelemetryEvent({
 					eventName: "ConnectionAttemptCancelled",
 					attempts: connectRepeatCount,
-					duration: formatTick(performance.now() - connectStartTime),
+					duration: formatTick(performanceNow() - connectStartTime),
 					connectionEstablished: false,
 				});
 				return;
@@ -675,7 +675,7 @@ export class ConnectionManager implements IConnectionManager {
 						attempts: connectRepeatCount,
 						delay: delayMs, // milliseconds
 						eventName: "DeltaConnectionFailureToConnect",
-						duration: formatTick(performance.now() - connectStartTime),
+						duration: formatTick(performanceNow() - connectStartTime),
 					},
 					origError,
 				);
@@ -688,7 +688,7 @@ export class ConnectionManager implements IConnectionManager {
 					return;
 				}
 
-				const waitStartTime = performance.now();
+				const waitStartTime = performanceNow();
 				const retryDelayFromError = getRetryDelayFromError(origError);
 				// If the error told us to wait or browser signals us that we are offline, then calculate the time we
 				// want to wait for before retrying. then we wait for that time. If the error didn't tell us to wait,
@@ -714,7 +714,7 @@ export class ConnectionManager implements IConnectionManager {
 				await waitForOnline();
 				this.logger.sendPerformanceEvent({
 					eventName: "WaitBetweenConnectionAttempts",
-					duration: performance.now() - waitStartTime,
+					duration: performanceNow() - waitStartTime,
 					details: JSON.stringify({
 						retryDelayFromError,
 						delayMs,
@@ -730,7 +730,7 @@ export class ConnectionManager implements IConnectionManager {
 				{
 					eventName: "MultipleDeltaConnectionFailures",
 					attempts: connectRepeatCount,
-					duration: formatTick(performance.now() - connectStartTime),
+					duration: formatTick(performanceNow() - connectStartTime),
 				},
 				lastError,
 			);
@@ -742,7 +742,7 @@ export class ConnectionManager implements IConnectionManager {
 			this.logger.sendTelemetryEvent({
 				eventName: "ConnectionAttemptCancelled",
 				attempts: connectRepeatCount,
-				duration: formatTick(performance.now() - connectStartTime),
+				duration: formatTick(performanceNow() - connectStartTime),
 				connectionEstablished: true,
 			});
 			return;

package/src/container.ts

@@ -5,7 +5,11 @@
 
 /* eslint-disable unicorn/consistent-function-scoping */
 
-import { TypedEventEmitter, performance } from "@fluid-internal/client-utils";
+import {
+	TypedEventEmitter,
+	performanceNow,
+	type ILayerCompatDetails,
+} from "@fluid-internal/client-utils";
 import {
 	AttachState,
 	IAudience,
@@ -123,6 +127,7 @@ import {
 	getPackageName,
 } from "./contracts.js";
 import { DeltaManager, IConnectionArgs } from "./deltaManager.js";
+import { validateRuntimeCompatibility } from "./layerCompatState.js";
 // eslint-disable-next-line import/no-deprecated
 import { IDetachedBlobStorage, ILoaderOptions, RelativeLoader } from "./loader.js";
 import {
@@ -617,7 +622,7 @@ export class Container
 	private readonly clientsWhoShouldHaveLeft = new Set<string>();
 	private _containerMetadata: Readonly<Record<string, string>> = {};
 
-	private setAutoReconnectTime = performance.now();
+	private setAutoReconnectTime = performanceNow();
 
 	private noopHeuristic: NoopHeuristic | undefined;
 
@@ -803,7 +808,7 @@ export class Container
 			protocolHandlerBuilder,
 		} = createProps;
 
-		this.connectionTransitionTimes[ConnectionState.Disconnected] = performance.now();
+		this.connectionTransitionTimes[ConnectionState.Disconnected] = performanceNow();
 		const pendingLocalState = loadProps?.pendingLocalState;
 
 		this._canReconnect = canReconnect ?? true;
@@ -891,7 +896,7 @@ export class Container
 							: this.deltaManager?.lastMessage?.clientId,
 					dmLastMsgClientSeq: () => this.deltaManager?.lastMessage?.clientSequenceNumber,
 					connectionStateDuration: () =>
-						performance.now() - this.connectionTransitionTimes[this.connectionState],
+						performanceNow() - this.connectionTransitionTimes[this.connectionState],
 				},
 			},
 		});
@@ -935,7 +940,7 @@ export class Container
 						mode,
 						category: this._lifecycleState === "loading" ? "generic" : category,
 						duration:
-							performance.now() - this.connectionTransitionTimes[ConnectionState.CatchingUp],
+							performanceNow() - this.connectionTransitionTimes[ConnectionState.CatchingUp],
 						...(details === undefined ? {} : { details: JSON.stringify(details) }),
 					});
 
@@ -1031,10 +1036,10 @@ export class Container
 			document.addEventListener !== null;
 		// keep track of last time page was visible for telemetry (on interactive clients only)
 		if (isDomAvailable && interactive) {
-			this.lastVisible = document.hidden ? performance.now() : undefined;
+			this.lastVisible = document.hidden ? performanceNow() : undefined;
 			this.visibilityEventHandler = (): void => {
 				if (document.hidden) {
-					this.lastVisible = performance.now();
+					this.lastVisible = performanceNow();
 				} else {
 					// settimeout so this will hopefully fire after disconnect event if being hidden caused it
 					setTimeout(() => {
@@ -1411,7 +1416,7 @@ export class Container
 			return;
 		}
 
-		const now = performance.now();
+		const now = performanceNow();
 		const duration = now - this.setAutoReconnectTime;
 		this.setAutoReconnectTime = now;
 
@@ -1629,7 +1634,7 @@ export class Container
 		dmLastProcessedSeqNumber: number;
 		dmLastKnownSeqNumber: number;
 	}> {
-		const timings: Record<string, number> = { phase1: performance.now() };
+		const timings: Record<string, number> = { phase1: performanceNow() };
 		this.service = await this.createDocumentService(async () =>
 			this.serviceFactory.createDocumentService(
 				resolvedUrl,
@@ -1662,7 +1667,7 @@ export class Container
 			state: AttachState.Attached,
 		};
 
-		timings.phase2 = performance.now();
+		timings.phase2 = performanceNow();
 
 		// Fetch specified snapshot.
 		const { baseSnapshot, version } =
@@ -1722,7 +1727,7 @@ export class Container
 			this.protocolHandler.audience.setCurrentClientId(pendingLocalState?.clientId);
 		}
 
-		timings.phase3 = performance.now();
+		timings.phase3 = performanceNow();
 		const codeDetails = this.getCodeDetailsFromQuorum();
 		await this.instantiateRuntime(
 			codeDetails,
@@ -1785,7 +1790,7 @@ export class Container
 			throw new Error("Container was closed while load()");
 		}
 
-		timings.end = performance.now();
+		timings.end = performanceNow();
 		this.subLogger.sendTelemetryEvent(
 			{
 				eventName: "LoadStagesTimings",
@@ -2152,7 +2157,7 @@ export class Container
 		reason?: IConnectionStateChangeReason,
 	): void {
 		// Log actual event
-		const time = performance.now();
+		const time = performanceNow();
 		this.connectionTransitionTimes[value] = time;
 		const duration = time - this.connectionTransitionTimes[oldState];
 
@@ -2191,7 +2196,7 @@ export class Container
 				opsBehind,
 				online: OnlineStatus[isOnline()],
 				lastVisible:
-					this.lastVisible === undefined ? undefined : performance.now() - this.lastVisible,
+					this.lastVisible === undefined ? undefined : performanceNow() - this.lastVisible,
 				checkpointSequenceNumber,
 				quorumSize: this._protocolHandler?.quorum.getMembers().size,
 				audienceSize: this._protocolHandler?.audience.getMembers().size,
@@ -2461,11 +2466,19 @@ export class Container
 			snapshot,
 		);
 
-		this._runtime = await PerformanceEvent.timedExecAsync(
+		const runtime = await PerformanceEvent.timedExecAsync(
 			this.subLogger,
 			{ eventName: "InstantiateRuntime" },
 			async () => runtimeFactory.instantiateRuntime(context, existing),
 		);
+
+		const maybeRuntimeCompatDetails = runtime as FluidObject<ILayerCompatDetails>;
+		validateRuntimeCompatibility(maybeRuntimeCompatDetails.ILayerCompatDetails, (error) =>
+			this.dispose(error),
+		);
+
+		this._runtime = runtime;
+
 		this._lifecycleEvents.emit("runtimeInstantiated");
 
 		this._loadedCodeDetails = codeDetails;

package/src/containerContext.ts

@@ -3,6 +3,10 @@
  * Licensed under the MIT License.
  */
 
+import type {
+	ILayerCompatDetails,
+	IProvideLayerCompatDetails,
+} from "@fluid-internal/client-utils";
 import {
 	AttachState,
 	IAudience,
@@ -30,10 +34,15 @@ import {
 } from "@fluidframework/driver-definitions/internal";
 import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 
+import { LoaderCompatDetails } from "./layerCompatState.js";
+
 /**
  * {@inheritDoc @fluidframework/container-definitions#IContainerContext}
  */
-export class ContainerContext implements IContainerContext {
+export class ContainerContext implements IContainerContext, IProvideLayerCompatDetails {
+	/**
+	 * @deprecated - This has been replaced by ILayerCompatDetails.
+	 */
 	public readonly supportedFeatures: ReadonlyMap<string, unknown> = new Map([
 		/**
 		 * This version of the loader accepts `referenceSequenceNumber`, provided by the container runtime,
@@ -62,6 +71,10 @@ export class ContainerContext implements IContainerContext {
 		return this._getConnected();
 	}
 
+	public get ILayerCompatDetails(): ILayerCompatDetails {
+		return LoaderCompatDetails;
+	}
+
 	constructor(
 		public readonly options: ILoaderOptions,
 		public readonly scope: FluidObject,

package/src/debugLogger.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { performance } from "@fluid-internal/client-utils";
+import { performanceNow } from "@fluid-internal/client-utils";
 import {
 	ITelemetryBaseEvent,
 	ITelemetryBaseLogger,
@@ -88,7 +88,7 @@ export class DebugLogger implements ITelemetryBaseLogger {
 		newEvent.eventName = undefined;
 
 		let tick = "";
-		tick = `tick=${formatTick(performance.now())}`;
+		tick = `tick=${formatTick(performanceNow())}`;
 
 		// Extract stack to put it last, but also to avoid escaping '\n' in it by JSON.stringify below
 		const stack = newEvent.stack ?? "";

package/src/deltaQueue.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { TypedEventEmitter, performance } from "@fluid-internal/client-utils";
+import { TypedEventEmitter, performanceNow } from "@fluid-internal/client-utils";
 import {
 	IDeltaQueue,
 	IDeltaQueueEvents,
@@ -153,7 +153,7 @@ export class DeltaQueue<T>
 		count: number;
 		duration: number;
 	} {
-		const start = performance.now();
+		const start = performanceNow();
 		let count = 0;
 
 		// For grouping to work we must process all local messages immediately and in the single turn.
@@ -169,7 +169,7 @@ export class DeltaQueue<T>
 			this.emit("op", next);
 		}
 
-		const duration = performance.now() - start;
+		const duration = performanceNow() - start;
 		if (this.q.length === 0) {
 			this.emit("idle", count, duration);
 		}

package/src/layerCompatState.ts

@@ -0,0 +1,75 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	checkLayerCompatibility,
+	type ILayerCompatDetails,
+	type ILayerCompatSupportRequirements,
+} from "@fluid-internal/client-utils";
+import type { ICriticalContainerError } from "@fluidframework/container-definitions";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import { pkgVersion } from "./packageVersion.js";
+
+/**
+ * Loader's compatibility details that is exposed to the Runtime layer.
+ */
+export const LoaderCompatDetails: ILayerCompatDetails = {
+	/**
+	 * The package version of the Loader layer.
+	 */
+	pkgVersion,
+	/**
+	 * The current generation of the Loader layer.
+	 */
+	generation: 1,
+	/**
+	 * The features supported by the Loader layer across the Loader / Runtime boundary.
+	 */
+	supportedFeatures: new Set<string>(),
+};
+
+/**
+ * The requirements that the Runtime layer must meet to be compatible with this Loader.
+ */
+export const RuntimeSupportRequirements: ILayerCompatSupportRequirements = {
+	/**
+	 * Minimum generation that Runtime must be at to be compatible with Loader. Note that 0 is used here for
+	 * Runtime layers before the introduction of the layer compatibility enforcement.
+	 */
+	minSupportedGeneration: 0,
+	/**
+	 * The features that the Runtime must support to be compatible with Loader.
+	 */
+	requiredFeatures: [],
+};
+
+/**
+ * Validates that the Runtime layer is compatible with the Loader.
+ */
+export function validateRuntimeCompatibility(
+	maybeRuntimeCompatDetails: ILayerCompatDetails | undefined,
+	disposeFn: (error?: ICriticalContainerError) => void,
+): void {
+	const layerCheckResult = checkLayerCompatibility(
+		RuntimeSupportRequirements,
+		maybeRuntimeCompatDetails,
+	);
+	if (!layerCheckResult.isCompatible) {
+		const error = new UsageError("Loader is not compatible with Runtime", {
+			errorDetails: JSON.stringify({
+				loaderVersion: LoaderCompatDetails.pkgVersion,
+				runtimeVersion: maybeRuntimeCompatDetails?.pkgVersion,
+				loaderGeneration: LoaderCompatDetails.generation,
+				runtimeGeneration: maybeRuntimeCompatDetails?.generation,
+				minSupportedGeneration: RuntimeSupportRequirements.minSupportedGeneration,
+				isGenerationCompatible: layerCheckResult.isGenerationCompatible,
+				unsupportedFeatures: layerCheckResult.unsupportedFeatures,
+			}),
+		});
+		disposeFn(error);
+		throw error;
+	}
+}

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-loader";
-export const pkgVersion = "2.20.0";
+export const pkgVersion = "2.21.0";

package/src/protocol/quorum.ts

@@ -221,14 +221,6 @@ export class QuorumProposals
 		return this.values.get(key)?.value;
 	}
 
-	/**
-	 * Returns additional data about the approved consensus value
-	 * @deprecated Removed in recent protocol-definitions.  Use get() instead.
-	 */
-	public getApprovalData(key: string): ICommittedProposal | undefined {
-		return this.values.get(key);
-	}
-
 	/**
 	 * Proposes a new value. Returns a promise that will either:
 	 * - Resolve when the proposal is accepted
@@ -505,14 +497,6 @@ export class Quorum extends TypedEventEmitter<IQuorum["on"]> implements IQuorum
 		return this.quorumProposals.get(key);
 	}
 
-	/**
-	 * Returns additional data about the approved consensus value
-	 * @deprecated Removed in recent protocol-definitions.  Use get() instead.
-	 */
-	public getApprovalData(key: string): ICommittedProposal | undefined {
-		return this.quorumProposals.getApprovalData(key);
-	}
-
 	/**
 	 * Adds a new client to the quorum
 	 */