@fluidframework/container-loader 2.80.0 → 2.81.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/container-loader",
-  "version": "2.80.0",
+  "version": "2.81.0",
   "description": "Fluid container loader",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -129,13 +129,13 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.80.0",
-    "@fluidframework/container-definitions": "~2.80.0",
-    "@fluidframework/core-interfaces": "~2.80.0",
-    "@fluidframework/core-utils": "~2.80.0",
-    "@fluidframework/driver-definitions": "~2.80.0",
-    "@fluidframework/driver-utils": "~2.80.0",
-    "@fluidframework/telemetry-utils": "~2.80.0",
+    "@fluid-internal/client-utils": "~2.81.0",
+    "@fluidframework/container-definitions": "~2.81.0",
+    "@fluidframework/core-interfaces": "~2.81.0",
+    "@fluidframework/core-utils": "~2.81.0",
+    "@fluidframework/driver-definitions": "~2.81.0",
+    "@fluidframework/driver-utils": "~2.81.0",
+    "@fluidframework/telemetry-utils": "~2.81.0",
     "@types/events_pkg": "npm:@types/events@^3.0.0",
     "@ungap/structured-clone": "^1.2.0",
     "debug": "^4.3.4",
@@ -146,14 +146,14 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/client-utils": "~2.80.0",
-    "@fluid-internal/mocha-test-setup": "~2.80.0",
-    "@fluid-private/test-loader-utils": "~2.80.0",
-    "@fluid-tools/build-cli": "^0.62.0",
+    "@fluid-internal/client-utils": "~2.81.0",
+    "@fluid-internal/mocha-test-setup": "~2.81.0",
+    "@fluid-private/test-loader-utils": "~2.81.0",
+    "@fluid-tools/build-cli": "^0.63.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.62.0",
-    "@fluidframework/container-loader-previous": "npm:@fluidframework/container-loader@2.74.0",
-    "@fluidframework/eslint-config-fluid": "~2.80.0",
+    "@fluidframework/build-tools": "^0.63.0",
+    "@fluidframework/container-loader-previous": "npm:@fluidframework/container-loader@2.80.0",
+    "@fluidframework/eslint-config-fluid": "~2.81.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/debug": "^4.1.5",
     "@types/double-ended-queue": "^2.1.0",

package/src/connectionManager.ts

@@ -564,6 +564,7 @@ export class ConnectionManager implements IConnectionManager {
 				this.logger.sendTelemetryEvent(
 					{
 						eventName: "ConnectionReceived",
+						// eslint-disable-next-line @typescript-eslint/prefer-optional-chain -- using ?. could change behavior
 						connected: connection !== undefined && connection.disposed === false,
 					},
 					undefined,
@@ -573,6 +574,7 @@ export class ConnectionManager implements IConnectionManager {
 				this.logger.sendTelemetryEvent(
 					{
 						eventName: "ConnectToDeltaStreamException",
+						// eslint-disable-next-line @typescript-eslint/prefer-optional-chain -- using ?. could change behavior
 						connected: connection !== undefined && connection.disposed === false,
 					},
 					undefined,

package/src/container.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-/* eslint-disable unicorn/consistent-function-scoping */
+/* eslint-disable unicorn/consistent-function-scoping, @typescript-eslint/prefer-nullish-coalescing, @typescript-eslint/prefer-optional-chain */
 
 import {
 	TypedEventEmitter,

package/src/deltaManager.ts

@@ -668,6 +668,7 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 			throw new Error("Delta manager is not attached");
 		}
 
+		// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- using ??= could change behavior if value is falsy
 		if (this.deltaStorage === undefined) {
 			this.deltaStorage = await docService.connectToDeltaStorage();
 		}
@@ -964,6 +965,7 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
 					duplicate++;
 				} else if (message.sequenceNumber !== prev + 1) {
 					gap++;
+					// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- using ??= could change behavior if value is falsy
 					if (firstMissing === undefined) {
 						firstMissing = prev + 1;
 					}

package/src/packageVersion.ts

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

package/src/serializedStateManager.ts

@@ -11,7 +11,7 @@ import type {
 	ITelemetryBaseLogger,
 } from "@fluidframework/core-interfaces";
 import type { IDisposable } from "@fluidframework/core-interfaces/internal";
-import { Timer, assert } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 import {
 	FetchSource,
 	type IDocumentStorageService,
@@ -35,6 +35,7 @@ import {
 	type ContainerStorageAdapter,
 	type ISerializableBlobContents,
 } from "./containerStorageAdapter.js";
+import { SnapshotRefresher } from "./snapshotRefresher.js";
 import {
 	convertISnapshotToSnapshotWithBlobs,
 	convertSnapshotToSnapshotInfo,
@@ -127,7 +128,7 @@ export interface SerializedSnapshotInfo extends SnapshotWithBlobs {
 	snapshotSequenceNumber: number;
 }
 
-interface ISnapshotInfo {
+export interface ISnapshotInfo {
 	snapshotSequenceNumber: number;
 	snapshotFetchedTime?: number | undefined;
 	snapshot: ISnapshot | ISnapshotTree;
@@ -144,27 +145,6 @@ interface ISerializerEvent extends IEvent {
 	(event: "saved", listener: (dirty: boolean) => void): void;
 }
 
-class RefreshPromiseTracker {
-	public get hasPromise(): boolean {
-		return this.#promise !== undefined;
-	}
-	public get Promise(): Promise<number> | undefined {
-		return this.#promise;
-	}
-	constructor(private readonly catchHandler: (error: Error) => void) {}
-
-	#promise: Promise<number> | undefined;
-	setPromise(p: Promise<number>): void {
-		if (this.hasPromise) {
-			throw new Error("Cannot set promise while promise exists");
-		}
-		this.#promise = p.finally(() => {
-			this.#promise = undefined;
-		});
-		p.catch(this.catchHandler);
-	}
-}
-
 /**
  * Helper class to manage the state of the container needed for proper serialization.
  *
@@ -177,20 +157,8 @@ export class SerializedStateManager implements IDisposable {
 	private readonly mc: MonitoringContext;
 	private snapshotInfo: ISnapshotInfo | undefined;
 	private latestSnapshot: ISnapshotInfo | undefined;
-	private readonly refreshTracker = new RefreshPromiseTracker(
-		// eslint-disable-next-line unicorn/consistent-function-scoping
-		(error) =>
-			this.mc.logger.sendErrorEvent(
-				{
-					eventName: "RefreshLatestSnapshotFailed",
-				},
-				error,
-			),
-	);
 	private lastSavedOpSequenceNumber: number = 0;
-	private readonly refreshTimer: Timer | undefined;
-	private readonly snapshotRefreshTimeoutMs: number = 60 * 60 * 24 * 1000;
-	readonly #snapshotRefreshEnabled: boolean;
+	private readonly snapshotRefresher: SnapshotRefresher | undefined;
 	#disposed: boolean = false;
 
 	/**
@@ -214,16 +182,17 @@ export class SerializedStateManager implements IDisposable {
 			namespace: "serializedStateManager",
 		});
 
-		this.snapshotRefreshTimeoutMs = snapshotRefreshTimeoutMs ?? this.snapshotRefreshTimeoutMs;
-
-		this.#snapshotRefreshEnabled =
-			this.offlineLoadEnabled &&
-			(this.mc.config.getBoolean("Fluid.Container.enableOfflineSnapshotRefresh") ??
-				this.mc.config.getBoolean("Fluid.Container.enableOfflineFull")) === true;
-
-		this.refreshTimer = this.#snapshotRefreshEnabled
-			? new Timer(this.snapshotRefreshTimeoutMs, () => this.tryRefreshSnapshot())
+		this.snapshotRefresher = this.offlineLoadEnabled
+			? new SnapshotRefresher(
+					subLogger,
+					this.storageAdapter,
+					this.offlineLoadEnabled,
+					this.supportGetSnapshotApi,
+					(snapshot: ISnapshotInfo) => this.handleSnapshotRefreshed(snapshot),
+					snapshotRefreshTimeoutMs,
+				)
 			: undefined;
+
 		containerEvent.on("saved", () => this.updateSnapshotAndProcessedOpsMaybe());
 	}
 	public get disposed(): boolean {
@@ -231,7 +200,7 @@ export class SerializedStateManager implements IDisposable {
 	}
 	dispose(): void {
 		this.#disposed = true;
-		this.refreshTimer?.clear();
+		this.snapshotRefresher?.dispose();
 	}
 
 	private verifyNotDisposed(): void {
@@ -245,8 +214,8 @@ export class SerializedStateManager implements IDisposable {
 	 * only intended to be used for testing purposes.
 	 * @returns The snapshot sequence number associated with the latest fetched snapshot
 	 */
-	public get refreshSnapshotP(): Promise<number | undefined> | undefined {
-		return this.refreshTracker.Promise;
+	public get refreshSnapshotP(): Promise<number> | undefined {
+		return this.snapshotRefresher?.refreshSnapshotP;
 	}
 
 	/**
@@ -288,7 +257,7 @@ export class SerializedStateManager implements IDisposable {
 			const baseSnapshotTree: ISnapshotTree | undefined = getSnapshotTree(snapshot);
 			const attributes = await getDocumentAttributes(this.storageAdapter, baseSnapshotTree);
 			if (this.offlineLoadEnabled) {
-				this.refreshTimer?.start();
+				this.snapshotRefresher?.startTimer();
 				this.snapshotInfo = {
 					snapshot,
 					snapshotSequenceNumber: attributes.sequenceNumber,
@@ -326,60 +295,19 @@ export class SerializedStateManager implements IDisposable {
 					snapshot,
 					snapshotSequenceNumber: attributes.sequenceNumber,
 				};
-				this.tryRefreshSnapshot();
+				this.snapshotRefresher?.tryRefreshSnapshot();
 			}
 			return { snapshot, version: undefined, attributes };
 		}
 	}
 
-	private tryRefreshSnapshot(): void {
-		if (
-			this.#snapshotRefreshEnabled &&
-			!this.#disposed &&
-			!this.refreshTracker.hasPromise &&
-			this.latestSnapshot === undefined
-		) {
-			// Don't block on the refresh snapshot call - it is for the next time we serialize, not booting this incarnation
-			this.refreshTracker.setPromise(this.refreshLatestSnapshot(this.supportGetSnapshotApi()));
-		}
-	}
-
 	/**
-	 * Fetch the latest snapshot for the container, including delay-loaded groupIds if pendingLocalState was provided and contained any groupIds.
-	 * Note that this will update the StorageAdapter's cached snapshots for the groupIds (if present)
-	 *
-	 * @param supportGetSnapshotApi - a boolean indicating whether to use the fetchISnapshot or fetchISnapshotTree (must be true to fetch by groupIds)
+	 * Handles the snapshotRefreshed event from SnapshotRefresher.
+	 * Decides whether to accept the new snapshot based on processed ops.
+	 * @returns The snapshot sequence number if updated, -1 otherwise
 	 */
-	private async refreshLatestSnapshot(supportGetSnapshotApi: boolean): Promise<number> {
-		this.latestSnapshot = await getLatestSnapshotInfo(
-			this.mc,
-			this.storageAdapter,
-			supportGetSnapshotApi,
-		);
-
-		if (this.#disposed) {
-			return -1;
-		}
-
-		// These are loading groupIds that the containerRuntime has requested over its lifetime.
-		// We will fetch the latest snapshot for the groupIds, which will update storageAdapter.loadedGroupIdSnapshots's cache
-		const downloadedGroupIds = Object.keys(this.storageAdapter.loadedGroupIdSnapshots);
-		if (supportGetSnapshotApi && downloadedGroupIds.length > 0) {
-			assert(
-				this.storageAdapter.getSnapshot !== undefined,
-				0x972 /* getSnapshot should exist */,
-			);
-			// (This is a separate network call from above because it requires work for storage to add a special base groupId)
-			const snapshot = await this.storageAdapter.getSnapshot({
-				versionId: undefined,
-				scenarioName: "getLatestSnapshotInfo",
-				cacheSnapshot: false,
-				loadingGroupIds: downloadedGroupIds,
-				fetchSource: FetchSource.noCache,
-			});
-			assert(snapshot !== undefined, 0x973 /* Snapshot should exist */);
-		}
-
+	private handleSnapshotRefreshed(latestSnapshot: ISnapshotInfo): number {
+		this.latestSnapshot = latestSnapshot;
 		return this.updateSnapshotAndProcessedOpsMaybe();
 	}
 
@@ -415,14 +343,14 @@ export class SerializedStateManager implements IDisposable {
 				stashedSnapshotSequenceNumber: this.snapshotInfo?.snapshotSequenceNumber,
 			});
 			this.latestSnapshot = undefined;
-			this.refreshTimer?.restart();
+			this.snapshotRefresher?.clearLatestSnapshot();
 		} else if (snapshotSequenceNumber <= lastProcessedOpSequenceNumber) {
 			// Snapshot seq num is between the first and last processed op.
 			// Remove the ops that are already part of the snapshot
 			this.processedOps.splice(0, snapshotSequenceNumber - firstProcessedOpSequenceNumber + 1);
 			this.snapshotInfo = this.latestSnapshot;
 			this.latestSnapshot = undefined;
-			this.refreshTimer?.restart();
+			this.snapshotRefresher?.clearLatestSnapshot();
 			this.mc.logger.sendTelemetryEvent({
 				eventName: "SnapshotRefreshed",
 				snapshotSequenceNumber,
@@ -448,7 +376,7 @@ export class SerializedStateManager implements IDisposable {
 				snapshotSequenceNumber: snapshot.sequenceNumber ?? 0,
 				snapshotFetchedTime: Date.now(),
 			};
-			this.refreshTimer?.start();
+			this.snapshotRefresher?.startTimer();
 		}
 	}
 

package/src/snapshotRefresher.ts

@@ -0,0 +1,201 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
+import type { IDisposable } from "@fluidframework/core-interfaces/internal";
+import { assert, Timer } from "@fluidframework/core-utils/internal";
+import { FetchSource } from "@fluidframework/driver-definitions/internal";
+import {
+	createChildMonitoringContext,
+	type MonitoringContext,
+} from "@fluidframework/telemetry-utils/internal";
+
+import {
+	getLatestSnapshotInfo,
+	type ISerializedStateManagerDocumentStorageService,
+	type ISnapshotInfo,
+} from "./serializedStateManager.js";
+
+class RefreshPromiseTracker {
+	public get hasPromise(): boolean {
+		return this.#promise !== undefined;
+	}
+	public get promise(): Promise<number> | undefined {
+		return this.#promise;
+	}
+	constructor(private readonly catchHandler: (error: Error) => void) {}
+
+	#promise: Promise<number> | undefined;
+	setPromise(p: Promise<number>): void {
+		if (this.hasPromise) {
+			throw new Error(
+				"Cannot start new snapshot refresh while a refresh is already in progress",
+			);
+		}
+		this.#promise = p.finally(() => {
+			this.#promise = undefined;
+		});
+		p.catch(this.catchHandler);
+	}
+}
+
+/**
+ * Manages periodic refresh of the latest snapshot for a document.
+ *
+ * `SnapshotRefresher` polls the storage service for the most recent snapshot and, when a newer
+ * snapshot is discovered, invokes the provided `onSnapshotRefreshed` callback with the updated
+ * snapshot metadata. It is responsible for:
+ *
+ * - Tracking the most recent snapshot that has been observed.
+ * - Scheduling and managing refresh attempts via an internal timer.
+ * - Emitting telemetry for successful and failed refresh attempts.
+ *
+ * The refresh behavior can be configured via constructor arguments, including whether offline
+ * loading and the `getSnapshot` API are supported, as well as the refresh timeout. Callers
+ * should dispose this instance when snapshot refresh is no longer needed to stop any pending
+ * timers and prevent further refresh attempts.
+ */
+export class SnapshotRefresher implements IDisposable {
+	private readonly mc: MonitoringContext;
+	private latestSnapshot: ISnapshotInfo | undefined;
+	#disposed: boolean = false;
+
+	public get disposed(): boolean {
+		return this.#disposed;
+	}
+
+	private readonly refreshTracker = new RefreshPromiseTracker(
+		// eslint-disable-next-line unicorn/consistent-function-scoping
+		(error) =>
+			this.mc.logger.sendErrorEvent(
+				{
+					eventName: "RefreshLatestSnapshotFailed",
+				},
+				error,
+			),
+	);
+	private readonly refreshTimer: Timer | undefined;
+	private readonly snapshotRefreshTimeoutMs: number = 60 * 60 * 24 * 1000;
+	readonly #snapshotRefreshEnabled: boolean;
+
+	constructor(
+		subLogger: ITelemetryBaseLogger,
+		private readonly storageAdapter: ISerializedStateManagerDocumentStorageService,
+		private readonly offlineLoadEnabled: boolean,
+		private readonly supportGetSnapshotApi: () => boolean,
+		private readonly onSnapshotRefreshed: (snapshot: ISnapshotInfo) => number,
+		snapshotRefreshTimeoutMs?: number,
+	) {
+		this.mc = createChildMonitoringContext({
+			logger: subLogger,
+			namespace: "serializedStateManager",
+		});
+
+		this.snapshotRefreshTimeoutMs = snapshotRefreshTimeoutMs ?? this.snapshotRefreshTimeoutMs;
+
+		this.#snapshotRefreshEnabled =
+			this.offlineLoadEnabled &&
+			(this.mc.config.getBoolean("Fluid.Container.enableOfflineSnapshotRefresh") ??
+				this.mc.config.getBoolean("Fluid.Container.enableOfflineFull")) === true;
+
+		this.refreshTimer = this.#snapshotRefreshEnabled
+			? new Timer(this.snapshotRefreshTimeoutMs, () => this.tryRefreshSnapshot())
+			: undefined;
+	}
+
+	public tryRefreshSnapshot(): void {
+		if (
+			this.#snapshotRefreshEnabled &&
+			!this.#disposed &&
+			!this.refreshTracker.hasPromise &&
+			this.latestSnapshot === undefined
+		) {
+			// Don't block on the refresh snapshot call - it is for the next time we serialize, not booting this incarnation
+			this.refreshTracker.setPromise(this.refreshLatestSnapshot(this.supportGetSnapshotApi()));
+		}
+	}
+
+	/**
+	 * Fetch the latest snapshot for the container, including delay-loaded groupIds if pendingLocalState was provided and contained any groupIds.
+	 * Note that this will update the StorageAdapter's cached snapshots for the groupIds (if present)
+	 *
+	 * @param supportGetSnapshotApi - a boolean indicating whether to use the fetchISnapshot or fetchISnapshotTree (must be true to fetch by groupIds)
+	 */
+	private async refreshLatestSnapshot(supportGetSnapshotApi: boolean): Promise<number> {
+		this.latestSnapshot = await getLatestSnapshotInfo(
+			this.mc,
+			this.storageAdapter,
+			supportGetSnapshotApi,
+		);
+
+		if (this.#disposed) {
+			return -1;
+		}
+
+		// These are loading groupIds that the containerRuntime has requested over its lifetime.
+		// We will fetch the latest snapshot for the groupIds, which will update storageAdapter.loadedGroupIdSnapshots's cache
+		const downloadedGroupIds = Object.keys(this.storageAdapter.loadedGroupIdSnapshots);
+		if (supportGetSnapshotApi && downloadedGroupIds.length > 0) {
+			assert(
+				this.storageAdapter.getSnapshot !== undefined,
+				0x972 /* getSnapshot should exist */,
+			);
+			// (This is a separate network call from above because it requires work for storage to add a special base groupId)
+			const snapshot = await this.storageAdapter.getSnapshot({
+				versionId: undefined,
+				scenarioName: "getLatestSnapshotInfo",
+				cacheSnapshot: false,
+				loadingGroupIds: downloadedGroupIds,
+				fetchSource: FetchSource.noCache,
+			});
+			assert(snapshot !== undefined, 0x973 /* Snapshot should exist */);
+		}
+
+		// Notify the manager about the fetched snapshot - let it decide what to do with it
+		const result =
+			this.latestSnapshot === undefined ? -1 : this.onSnapshotRefreshed(this.latestSnapshot);
+
+		this.refreshTimer?.restart();
+		return result;
+	}
+
+	/**
+	 * Clears the latest snapshot after it's been consumed by the manager.
+	 * This allows the next refresh cycle to proceed.
+	 */
+	public clearLatestSnapshot(): void {
+		this.latestSnapshot = undefined;
+	}
+
+	/**
+	 * Starts the refresh timer.
+	 */
+	public startTimer(): void {
+		this.refreshTimer?.start();
+	}
+
+	/**
+	 * Restarts the refresh timer.
+	 */
+	public restartTimer(): void {
+		this.refreshTimer?.restart();
+	}
+
+	/**
+	 * Gets the current refresh promise for testing purposes.
+	 * @returns The snapshot sequence number promise, or undefined if no refresh is in progress
+	 */
+	public get refreshSnapshotP(): Promise<number> | undefined {
+		return this.refreshTracker.promise;
+	}
+
+	/**
+	 * Disposes the refresher and clears the timer.
+	 */
+	public dispose(): void {
+		this.#disposed = true;
+		this.refreshTimer?.clear();
+	}
+}

package/.eslintrc.cjs

@@ -1,24 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-module.exports = {
-	extends: [require.resolve("@fluidframework/eslint-config-fluid"), "prettier"],
-	parserOptions: {
-		project: ["./tsconfig.json", "./src/test/tsconfig.json"],
-	},
-	rules: {
-		"@fluid-internal/fluid/no-unchecked-record-access": "warn",
-	},
-	overrides: [
-		{
-			// Rules only for test files
-			files: ["*.spec.ts", "src/test/**"],
-			rules: {
-				// Test files are run in node only so additional node libraries can be used.
-				"import-x/no-nodejs-modules": ["error", { allow: ["node:assert"] }],
-			},
-		},
-	],
-};