@fluidframework/container-loader 2.118.1 → 3.0.1

package/src/loaderLayerCompatState.ts

@@ -5,6 +5,7 @@
 
 import {
 	generation,
+	defaultLayerCompatDetails,
 	LayerCompatibilityPolicyWindowMonths,
 	type ILayerCompatDetails,
 	type ILayerCompatSupportRequirements,
@@ -44,6 +45,18 @@ export const loaderCompatDetailsForRuntime: ILayerCompatDetails = {
 	supportedFeatures: new Set<string>(),
 };
 
+/**
+ * Loader's compatibility details that is validated against the Driver layer's requirements.
+ * @internal
+ */
+export const loaderCompatDetailsForDriver: ILayerCompatDetails = {
+	...loaderCoreCompatDetails,
+	/**
+	 * The features supported by the Loader layer across the Loader / Driver boundary.
+	 */
+	supportedFeatures: new Set<string>(),
+};
+
 /**
  * The requirements that the Runtime layer must meet to be compatible with this Loader.
  * @internal
@@ -51,13 +64,14 @@ export const loaderCompatDetailsForRuntime: ILayerCompatDetails = {
 export const runtimeSupportRequirementsForLoader: ILayerCompatSupportRequirements = {
 	/**
 	 * Minimum generation that Runtime must be at to be compatible with this Loader. This is calculated
-	 * based on the LayerCompatibilityPolicyWindowMonths.LoaderRuntime value which defines how many months old can
-	 * the Runtime layer be compared to the Loader layer for them to still be considered compatible.
+	 * based on the LayerCompatibilityPolicyWindowMonths.NewLoaderOldRuntime value which defines how many months
+	 * old can the Runtime layer be compared to the Loader layer for them to still be considered compatible.
 	 * The minimum valid generation value is 0.
 	 */
 	minSupportedGeneration: Math.max(
 		0,
-		loaderCoreCompatDetails.generation - LayerCompatibilityPolicyWindowMonths.LoaderRuntime,
+		loaderCoreCompatDetails.generation -
+			LayerCompatibilityPolicyWindowMonths.NewLoaderOldRuntime,
 	),
 	/**
 	 * The features that the Runtime must support to be compatible with Loader.
@@ -72,13 +86,14 @@ export const runtimeSupportRequirementsForLoader: ILayerCompatSupportRequirement
 export const driverSupportRequirementsForLoader: ILayerCompatSupportRequirements = {
 	/**
 	 * Minimum generation that Driver must be at to be compatible with this Loader. This is calculated
-	 * based on the LayerCompatibilityPolicyWindowMonths.LoaderDriver value which defines how many months old can
-	 * the Driver layer be compared to the Loader layer for them to still be considered compatible.
+	 * based on the LayerCompatibilityPolicyWindowMonths.NewLoaderOldDriver value which defines how many months
+	 * old can the Driver layer be compared to the Loader layer for them to still be considered compatible.
 	 * The minimum valid generation value is 0.
 	 */
 	minSupportedGeneration: Math.max(
 		0,
-		loaderCoreCompatDetails.generation - LayerCompatibilityPolicyWindowMonths.LoaderDriver,
+		loaderCoreCompatDetails.generation -
+			LayerCompatibilityPolicyWindowMonths.NewLoaderOldDriver,
 	),
 	/**
 	 * The features that the Driver must support to be compatible with Loader.
@@ -95,13 +110,19 @@ export function validateRuntimeCompatibility(
 	mc: MonitoringContext,
 ): void {
 	validateLayerCompatibility(
-		"loader",
-		"runtime",
-		loaderCompatDetailsForRuntime,
-		runtimeSupportRequirementsForLoader,
-		maybeRuntimeCompatDetails,
-		() => {} /* disposeFn - no op. This will be handled by the caller */,
-		mc,
+		/* validatingLayer */ {
+			layer: "loader",
+			packageInfo: loaderCoreCompatDetails,
+			compatSupportRequirements: runtimeSupportRequirementsForLoader,
+		},
+		/* targetLayer */ {
+			layer: "runtime",
+			compatDetails: maybeRuntimeCompatDetails,
+		},
+		{
+			disposeFn: () => {} /* no op. This will be handled by the caller */,
+			mc,
+		},
 	);
 }
 
@@ -115,12 +136,56 @@ export function validateDriverCompatibility(
 	mc: MonitoringContext,
 ): void {
 	validateLayerCompatibility(
-		"loader",
-		"driver",
-		loaderCompatDetailsForRuntime,
-		driverSupportRequirementsForLoader,
-		maybeDriverCompatDetails,
-		disposeFn,
-		mc,
+		/* validatingLayer */ {
+			layer: "loader",
+			packageInfo: loaderCoreCompatDetails,
+			compatSupportRequirements: driverSupportRequirementsForLoader,
+		},
+		/* targetLayer */ {
+			layer: "driver",
+			compatDetails: maybeDriverCompatDetails,
+		},
+		{ disposeFn, mc },
+	);
+}
+
+/**
+ * Validates that the Loader layer is compatible with the Driver.
+ *
+ * @remarks
+ * This is the reverse of {@link validateDriverCompatibility} and is intentionally a separate function because it
+ * does not follow the standard layer-validation pattern. Normally each layer validates the layer it holds a
+ * reference to - the Loader validates the Driver, the Runtime validates the Loader, and so on. The Driver, however,
+ * has no reference to the Loader and therefore cannot run this validation itself. To still enforce compatibility in
+ * both directions across the Driver / Loader boundary, the Driver publishes the requirements it has for the Loader
+ * (via ILayerCompatSupportRequirements) and the Loader validates itself against them here, on the Driver's behalf.
+ *
+ * @param maybeDriverCompatDetails - The Driver's compatibility details, used only to attribute the version /
+ * generation of the Driver in telemetry if the Loader is found to be incompatible.
+ * @param maybeDriverCompatRequirements - The requirements the Driver has for the Loader. Older Drivers may not
+ * publish these, in which case there is nothing to validate in this direction.
+ *
+ * @internal
+ */
+export function validateLoaderCompatibilityWithDriver(
+	maybeDriverCompatDetails: ILayerCompatDetails | undefined,
+	maybeDriverCompatRequirements: ILayerCompatSupportRequirements | undefined,
+	disposeFn: (error?: ICriticalContainerError) => void,
+	mc: MonitoringContext,
+): void {
+	if (maybeDriverCompatRequirements === undefined) {
+		return;
+	}
+	validateLayerCompatibility(
+		/* validatingLayer */ {
+			layer: "driver",
+			packageInfo: maybeDriverCompatDetails ?? defaultLayerCompatDetails,
+			compatSupportRequirements: maybeDriverCompatRequirements,
+		},
+		/* targetLayer */ {
+			layer: "loader",
+			compatDetails: loaderCompatDetailsForDriver,
+		},
+		{ disposeFn, mc },
 	);
 }

package/src/packageVersion.ts

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

package/src/pendingLocalStateStore.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import type { FluidIterableIterator } from "@fluidframework/core-interfaces";
 import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -140,7 +141,7 @@ export class PendingLocalStateStore<TKey> {
 	/**
 	 * Returns an iterator over [key, serializedState] pairs.
 	 */
-	entries(): Iterator<[TKey, string]> {
+	entries(): FluidIterableIterator<[TKey, string]> {
 		const iterator = this.#pendingStates.entries();
 		return {
 			next: (): IteratorResult<[TKey, string]> => {
@@ -151,20 +152,23 @@ export class PendingLocalStateStore<TKey> {
 				}
 				return { done, value: [value[0], JSON.stringify(value[1])] };
 			},
+			[Symbol.iterator](): FluidIterableIterator<[TKey, string]> {
+				return this;
+			},
 		};
 	}
 
 	/**
 	 * Returns an iterator over the stored keys.
 	 */
-	keys(): IterableIterator<TKey> {
+	keys(): FluidIterableIterator<TKey> {
 		return this.#pendingStates.keys();
 	}
 
 	/**
 	 * Makes the store iterable with `for...of` loops.
 	 */
-	[Symbol.iterator](): Iterator<[TKey, string]> {
+	[Symbol.iterator](): FluidIterableIterator<[TKey, string]> {
 		return this.entries();
 	}
 }

package/src/serializedStateManager.ts

@@ -75,6 +75,12 @@ export interface IPendingContainerState extends SnapshotWithBlobs {
 	 * This container was attached (as opposed to IPendingDetachedContainerState.attached which is false)
 	 */
 	attached: true;
+	/**
+	 * Indicates that blob payloads are omitted and must be read from live storage.
+	 *
+	 * Undefined for existing and self-contained pending state.
+	 */
+	blobContentsMode?: "reference";
 	/**
 	 * Runtime-specific state that will be needed to properly rehydrate
 	 * (it's included in ContainerContext passed to instantiateRuntime)

package/src/utils.ts

@@ -6,7 +6,7 @@
 import {
 	bufferToString,
 	stringToBuffer,
-	Uint8ArrayToArrayBuffer,
+	AnyUint8ArrayToArrayBuffer,
 } from "@fluid-internal/client-utils";
 import { assert, compareArrays, unreachableCase } from "@fluidframework/core-utils/internal";
 import { type ISummaryTree, SummaryType } from "@fluidframework/driver-definitions";
@@ -75,7 +75,7 @@ export interface IParsedUrl {
  * Utility api to parse the IResolvedUrl.url into specific parts like querystring, path to get
  * deep link info etc.
  * Warning - This function may not be compatible with any Url Resolver's resolved url. It works
- * with urls of type: protocol://<string>/.../..?<querystring>
+ * with urls of type: `protocol://{host}/.../..?{queryString}`
  * @param url - This is the IResolvedUrl.url part of the resolved url.
  * @returns The IParsedUrl representing the input URL, or undefined if the format was not supported
  * @legacy @beta
@@ -172,7 +172,7 @@ function convertSummaryToISnapshot(
 				blobContents.set(
 					blobId,
 					summaryObject.content instanceof Uint8Array
-						? Uint8ArrayToArrayBuffer(summaryObject.content)
+						? AnyUint8ArrayToArrayBuffer(summaryObject.content)
 						: stringToBuffer(summaryObject.content, "utf8"),
 				);
 

package/tsconfig.json

@@ -1,5 +1,5 @@
 {
-	"extends": "../../../common/build/build-common/tsconfig.node16.json",
+	"extends": "../../../common/build/build-common/tsconfig.node20.json",
 	"include": ["src/**/*"],
 	"exclude": ["src/test/**/*"],
 	"compilerOptions": {

package/internal.d.ts

@@ -1,11 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/*
- * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outFileLegacyAlpha legacyAlpha --outDir ./lib --node10TypeCompat" in @fluid-tools/build-cli.
- */
-
-export * from "./lib/index.js";

package/legacy/alpha.d.ts

@@ -1,11 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/*
- * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outFileLegacyAlpha legacyAlpha --outDir ./lib --node10TypeCompat" in @fluid-tools/build-cli.
- */
-
-export * from "../lib/legacyAlpha.js";

package/legacy.d.ts

@@ -1,11 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/*
- * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outFileLegacyAlpha legacyAlpha --outDir ./lib --node10TypeCompat" in @fluid-tools/build-cli.
- */
-
-export * from "./lib/legacy.js";