@fluidframework/container-loader 2.0.0-rc.3.0.2 → 2.0.0-rc.4.0.0

package/dist/retriableDocumentStorageService.js.map

@@ -1 +1 @@
-{"version":3,"file":"retriableDocumentStorageService.js","sourceRoot":"","sources":["../src/retriableDocumentStorageService.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { IDisposable } from \"@fluidframework/core-interfaces\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport {\n\tFetchSource,\n\tIDocumentStorageService,\n\tIDocumentStorageServicePolicies,\n\tISnapshot,\n\tISnapshotFetchOptions,\n\tISummaryContext,\n} from \"@fluidframework/driver-definitions/internal\";\nimport { runWithRetry } from \"@fluidframework/driver-utils/internal\";\nimport {\n\tICreateBlobResponse,\n\tISnapshotTree,\n\tISummaryHandle,\n\tISummaryTree,\n\tIVersion,\n} from \"@fluidframework/protocol-definitions\";\nimport { ITelemetryLoggerExt } from \"@fluidframework/telemetry-utils\";\nimport { GenericError, UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nexport class RetriableDocumentStorageService implements IDocumentStorageService, IDisposable {\n\tprivate _disposed = false;\n\tprivate internalStorageService: IDocumentStorageService | undefined;\n\tconstructor(\n\t\tprivate readonly internalStorageServiceP: Promise<IDocumentStorageService>,\n\t\tprivate readonly logger: ITelemetryLoggerExt,\n\t) {\n\t\tthis.internalStorageServiceP.then((s) => (this.internalStorageService = s)).catch(() => {});\n\t}\n\n\tpublic get policies(): IDocumentStorageServicePolicies | undefined {\n\t\tif (this.internalStorageService) {\n\t\t\treturn this.internalStorageService.policies;\n\t\t}\n\t\tthrow new Error(\"storage service not yet instantiated\");\n\t}\n\tpublic get disposed() {\n\t\treturn this._disposed;\n\t}\n\tpublic dispose() {\n\t\tthis._disposed = true;\n\t}\n\n\tpublic async getSnapshotTree(\n\t\tversion?: IVersion,\n\t\tscenarioName?: string,\n\t): Promise<ISnapshotTree | null> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () =>\n\t\t\t\tthis.internalStorageServiceP.then(async (s) =>\n\t\t\t\t\ts.getSnapshotTree(version, scenarioName),\n\t\t\t\t),\n\t\t\t\"storage_getSnapshotTree\",\n\t\t);\n\t}\n\n\tpublic async getSnapshot(snapshotFetchOptions?: ISnapshotFetchOptions): Promise<ISnapshot> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () =>\n\t\t\t\tthis.internalStorageServiceP.then(async (s) => {\n\t\t\t\t\tif (s.getSnapshot !== undefined) {\n\t\t\t\t\t\treturn s.getSnapshot(snapshotFetchOptions);\n\t\t\t\t\t}\n\t\t\t\t\tthrow new UsageError(\n\t\t\t\t\t\t\"getSnapshot api should exist on internal storage in RetriableDocStorageService class\",\n\t\t\t\t\t);\n\t\t\t\t}),\n\t\t\t\"storage_getSnapshot\",\n\t\t);\n\t}\n\n\tpublic async readBlob(id: string): Promise<ArrayBufferLike> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () => this.internalStorageServiceP.then(async (s) => s.readBlob(id)),\n\t\t\t\"storage_readBlob\",\n\t\t);\n\t}\n\n\tpublic async getVersions(\n\t\tversionId: string | null,\n\t\tcount: number,\n\t\tscenarioName?: string,\n\t\tfetchSource?: FetchSource,\n\t): Promise<IVersion[]> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () =>\n\t\t\t\tthis.internalStorageServiceP.then(async (s) =>\n\t\t\t\t\ts.getVersions(versionId, count, scenarioName, fetchSource),\n\t\t\t\t),\n\t\t\t\"storage_getVersions\",\n\t\t);\n\t}\n\n\tpublic async uploadSummaryWithContext(\n\t\tsummary: ISummaryTree,\n\t\tcontext: ISummaryContext,\n\t): Promise<string> {\n\t\t// Not using retry loop here. Couple reasons:\n\t\t// 1. If client lost connectivity, then retry loop will result in uploading stale summary\n\t\t//    by stale summarizer after connectivity comes back. It will cause failures for this client and for\n\t\t//    real (new) summarizer. This problem in particular should be solved in future by supplying abort handle\n\t\t//    on all APIs and caller (ContainerRuntime.submitSummary) aborting call on loss of connectivity\n\t\t// 2. Similar, if we get 429 with retryAfter = 10 minutes, it's likely not the right call to retry summary\n\t\t//    upload in 10 minutes - it's better to keep processing ops and retry later. Though caller needs to take\n\t\t//    retryAfter into account!\n\t\t// But retry loop is required for creation flow (Container.attach)\n\t\tassert(\n\t\t\t(context.referenceSequenceNumber === 0) === (context.ackHandle === undefined),\n\t\t\t0x251 /* \"creation summary has to have seq=0 && handle === undefined\" */,\n\t\t);\n\t\tif (context.referenceSequenceNumber !== 0) {\n\t\t\treturn this.internalStorageServiceP.then(async (s) =>\n\t\t\t\ts.uploadSummaryWithContext(summary, context),\n\t\t\t);\n\t\t}\n\n\t\t// Creation flow with attachment blobs - need to do retries!\n\t\treturn this.runWithRetry(\n\t\t\tasync () =>\n\t\t\t\tthis.internalStorageServiceP.then(async (s) =>\n\t\t\t\t\ts.uploadSummaryWithContext(summary, context),\n\t\t\t\t),\n\t\t\t\"storage_uploadSummaryWithContext\",\n\t\t);\n\t}\n\n\tpublic async downloadSummary(handle: ISummaryHandle): Promise<ISummaryTree> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () => this.internalStorageServiceP.then(async (s) => s.downloadSummary(handle)),\n\t\t\t\"storage_downloadSummary\",\n\t\t);\n\t}\n\n\tpublic async createBlob(file: ArrayBufferLike): Promise<ICreateBlobResponse> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () => this.internalStorageServiceP.then(async (s) => s.createBlob(file)),\n\t\t\t\"storage_createBlob\",\n\t\t);\n\t}\n\n\tprivate checkStorageDisposed(callName: string, error: unknown) {\n\t\tif (this._disposed) {\n\t\t\tthis.logger.sendTelemetryEvent(\n\t\t\t\t{\n\t\t\t\t\teventName: `${callName}_abortedStorageDisposed`,\n\t\t\t\t\tfetchCallName: callName, // fetchCallName matches logs in runWithRetry.ts\n\t\t\t\t},\n\t\t\t\terror,\n\t\t\t);\n\t\t\t// pre-0.58 error message: storageServiceDisposedCannotRetry\n\t\t\tthrow new GenericError(\"Storage Service is disposed. Cannot retry\", {\n\t\t\t\tcanRetry: false,\n\t\t\t});\n\t\t}\n\t\treturn;\n\t}\n\n\tprivate async runWithRetry<T>(api: () => Promise<T>, callName: string): Promise<T> {\n\t\treturn runWithRetry(api, callName, this.logger, {\n\t\t\tonRetry: (_delayInMs: number, error: unknown) =>\n\t\t\t\tthis.checkStorageDisposed(callName, error),\n\t\t});\n\t}\n}\n"]}
+{"version":3,"file":"retriableDocumentStorageService.js","sourceRoot":"","sources":["../src/retriableDocumentStorageService.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { IDisposable } from \"@fluidframework/core-interfaces\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport {\n\tFetchSource,\n\tIDocumentStorageService,\n\tIDocumentStorageServicePolicies,\n\tISnapshot,\n\tISnapshotFetchOptions,\n\tISummaryContext,\n} from \"@fluidframework/driver-definitions/internal\";\nimport { runWithRetry } from \"@fluidframework/driver-utils/internal\";\nimport {\n\tICreateBlobResponse,\n\tISnapshotTree,\n\tISummaryHandle,\n\tISummaryTree,\n\tIVersion,\n} from \"@fluidframework/protocol-definitions\";\nimport {\n\tITelemetryLoggerExt,\n\tGenericError,\n\tUsageError,\n} from \"@fluidframework/telemetry-utils/internal\";\n\nexport class RetriableDocumentStorageService implements IDocumentStorageService, IDisposable {\n\tprivate _disposed = false;\n\tprivate internalStorageService: IDocumentStorageService | undefined;\n\tconstructor(\n\t\tprivate readonly internalStorageServiceP: Promise<IDocumentStorageService>,\n\t\tprivate readonly logger: ITelemetryLoggerExt,\n\t) {\n\t\tthis.internalStorageServiceP.then((s) => (this.internalStorageService = s)).catch(() => {});\n\t}\n\n\tpublic get policies(): IDocumentStorageServicePolicies | undefined {\n\t\tif (this.internalStorageService) {\n\t\t\treturn this.internalStorageService.policies;\n\t\t}\n\t\tthrow new Error(\"storage service not yet instantiated\");\n\t}\n\tpublic get disposed() {\n\t\treturn this._disposed;\n\t}\n\tpublic dispose() {\n\t\tthis._disposed = true;\n\t}\n\n\tpublic async getSnapshotTree(\n\t\tversion?: IVersion,\n\t\tscenarioName?: string,\n\t): Promise<ISnapshotTree | null> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () =>\n\t\t\t\tthis.internalStorageServiceP.then(async (s) =>\n\t\t\t\t\ts.getSnapshotTree(version, scenarioName),\n\t\t\t\t),\n\t\t\t\"storage_getSnapshotTree\",\n\t\t);\n\t}\n\n\tpublic async getSnapshot(snapshotFetchOptions?: ISnapshotFetchOptions): Promise<ISnapshot> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () =>\n\t\t\t\tthis.internalStorageServiceP.then(async (s) => {\n\t\t\t\t\tif (s.getSnapshot !== undefined) {\n\t\t\t\t\t\treturn s.getSnapshot(snapshotFetchOptions);\n\t\t\t\t\t}\n\t\t\t\t\tthrow new UsageError(\n\t\t\t\t\t\t\"getSnapshot api should exist on internal storage in RetriableDocStorageService class\",\n\t\t\t\t\t);\n\t\t\t\t}),\n\t\t\t\"storage_getSnapshot\",\n\t\t);\n\t}\n\n\tpublic async readBlob(id: string): Promise<ArrayBufferLike> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () => this.internalStorageServiceP.then(async (s) => s.readBlob(id)),\n\t\t\t\"storage_readBlob\",\n\t\t);\n\t}\n\n\tpublic async getVersions(\n\t\tversionId: string | null,\n\t\tcount: number,\n\t\tscenarioName?: string,\n\t\tfetchSource?: FetchSource,\n\t): Promise<IVersion[]> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () =>\n\t\t\t\tthis.internalStorageServiceP.then(async (s) =>\n\t\t\t\t\ts.getVersions(versionId, count, scenarioName, fetchSource),\n\t\t\t\t),\n\t\t\t\"storage_getVersions\",\n\t\t);\n\t}\n\n\tpublic async uploadSummaryWithContext(\n\t\tsummary: ISummaryTree,\n\t\tcontext: ISummaryContext,\n\t): Promise<string> {\n\t\t// Not using retry loop here. Couple reasons:\n\t\t// 1. If client lost connectivity, then retry loop will result in uploading stale summary\n\t\t//    by stale summarizer after connectivity comes back. It will cause failures for this client and for\n\t\t//    real (new) summarizer. This problem in particular should be solved in future by supplying abort handle\n\t\t//    on all APIs and caller (ContainerRuntime.submitSummary) aborting call on loss of connectivity\n\t\t// 2. Similar, if we get 429 with retryAfter = 10 minutes, it's likely not the right call to retry summary\n\t\t//    upload in 10 minutes - it's better to keep processing ops and retry later. Though caller needs to take\n\t\t//    retryAfter into account!\n\t\t// But retry loop is required for creation flow (Container.attach)\n\t\tassert(\n\t\t\t(context.referenceSequenceNumber === 0) === (context.ackHandle === undefined),\n\t\t\t0x251 /* \"creation summary has to have seq=0 && handle === undefined\" */,\n\t\t);\n\t\tif (context.referenceSequenceNumber !== 0) {\n\t\t\treturn this.internalStorageServiceP.then(async (s) =>\n\t\t\t\ts.uploadSummaryWithContext(summary, context),\n\t\t\t);\n\t\t}\n\n\t\t// Creation flow with attachment blobs - need to do retries!\n\t\treturn this.runWithRetry(\n\t\t\tasync () =>\n\t\t\t\tthis.internalStorageServiceP.then(async (s) =>\n\t\t\t\t\ts.uploadSummaryWithContext(summary, context),\n\t\t\t\t),\n\t\t\t\"storage_uploadSummaryWithContext\",\n\t\t);\n\t}\n\n\tpublic async downloadSummary(handle: ISummaryHandle): Promise<ISummaryTree> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () => this.internalStorageServiceP.then(async (s) => s.downloadSummary(handle)),\n\t\t\t\"storage_downloadSummary\",\n\t\t);\n\t}\n\n\tpublic async createBlob(file: ArrayBufferLike): Promise<ICreateBlobResponse> {\n\t\treturn this.runWithRetry(\n\t\t\tasync () => this.internalStorageServiceP.then(async (s) => s.createBlob(file)),\n\t\t\t\"storage_createBlob\",\n\t\t);\n\t}\n\n\tprivate checkStorageDisposed(callName: string, error: unknown) {\n\t\tif (this._disposed) {\n\t\t\tthis.logger.sendTelemetryEvent(\n\t\t\t\t{\n\t\t\t\t\teventName: `${callName}_abortedStorageDisposed`,\n\t\t\t\t\tfetchCallName: callName, // fetchCallName matches logs in runWithRetry.ts\n\t\t\t\t},\n\t\t\t\terror,\n\t\t\t);\n\t\t\t// pre-0.58 error message: storageServiceDisposedCannotRetry\n\t\t\tthrow new GenericError(\"Storage Service is disposed. Cannot retry\", {\n\t\t\t\tcanRetry: false,\n\t\t\t});\n\t\t}\n\t\treturn;\n\t}\n\n\tprivate async runWithRetry<T>(api: () => Promise<T>, callName: string): Promise<T> {\n\t\treturn runWithRetry(api, callName, this.logger, {\n\t\t\tonRetry: (_delayInMs: number, error: unknown) =>\n\t\t\t\tthis.checkStorageDisposed(callName, error),\n\t\t});\n\t}\n}\n"]}

package/dist/serializedStateManager.d.ts

@@ -5,9 +5,14 @@
 import { IGetPendingLocalStateProps, IRuntime } from "@fluidframework/container-definitions/internal";
 import { IDocumentStorageService, IResolvedUrl, ISnapshot } from "@fluidframework/driver-definitions/internal";
 import { ISequencedDocumentMessage, ISnapshotTree, IVersion } from "@fluidframework/protocol-definitions";
-import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
 import { MonitoringContext } from "@fluidframework/telemetry-utils/internal";
+import type { ITelemetryBaseLogger, IEventProvider, IEvent } from "@fluidframework/core-interfaces";
 import { ISerializableBlobContents } from "./containerStorageAdapter.js";
+/**
+ * This is very similar to {@link @fluidframework/protocol-definitions/internal#ISnapshot}, but the difference is
+ * that the blobs of ISnapshot are of type ArrayBufferLike, while the blobs of this interface are serializable because
+ * they are already converted to string.
+ */
 export interface SnapshotWithBlobs {
     /**
      * Snapshot from which container initially loaded.
@@ -22,18 +27,34 @@ export interface SnapshotWithBlobs {
 /**
  * State saved by a container at close time, to be used to load a new instance
  * of the container to the same state
+ *
+ * This is very similar to {@link @fluidframework/protocol-definitions/internal#ISnapshot}, but the difference is
+ * that the blobs of ISnapshot are of type ArrayBufferLike, while the blobs of this interface are serializable because
+ * they are already converted to string.
+ *
  * @internal
  */
 export interface IPendingContainerState extends SnapshotWithBlobs {
+    /** This container was attached (as opposed to IPendingDetachedContainerState.attached which is false) */
     attached: true;
+    /**
+     * Runtime-specific state that will be needed to properly rehydrate
+     * (it's included in ContainerContext passed to instantiateRuntime)
+     */
     pendingRuntimeState: unknown;
+    /**
+     * Any group snapshots (aka delay-loaded) we've downloaded from the service for this container
+     */
+    loadedGroupIdSnapshots?: Record<string, ISnapshotInfo>;
     /**
      * All ops since base snapshot sequence number up to the latest op
      * seen when the container was closed. Used to apply stashed (saved pending)
      * ops at the same sequence number at which they were made.
      */
     savedOps: ISequencedDocumentMessage[];
+    /** The Container's URL in the service, needed to hook up the driver during rehydration */
     url: string;
+    /** If the Container was connected when serialized, its clientId. Used as the initial clientId upon rehydration, until reconnected. */
     clientId?: string;
 }
 /**
@@ -42,41 +63,99 @@ export interface IPendingContainerState extends SnapshotWithBlobs {
  * @internal
  */
 export interface IPendingDetachedContainerState extends SnapshotWithBlobs {
+    /** This container was not attached (as opposed to IPendingContainerState.attached which is true) */
     attached: false;
+    /** Indicates whether we expect the rehydrated container to have non-empty Detached Blob Storage */
     hasAttachmentBlobs: boolean;
+    /**
+     * Runtime-specific state that will be needed to properly rehydrate
+     * (it's included in ContainerContext passed to instantiateRuntime)
+     */
     pendingRuntimeState?: unknown;
 }
 export interface ISnapshotInfo extends SnapshotWithBlobs {
     snapshotSequenceNumber: number;
+    snapshotFetchedTime?: number | undefined;
+}
+export type ISerializedStateManagerDocumentStorageService = Pick<IDocumentStorageService, "getSnapshot" | "getSnapshotTree" | "getVersions" | "readBlob"> & {
+    loadedGroupIdSnapshots: Record<string, ISnapshot>;
+};
+interface ISerializerEvent extends IEvent {
+    (event: "saved", listener: (dirty: boolean) => void): void;
 }
+/**
+ * Helper class to manage the state of the container needed for proper serialization.
+ *
+ * It holds the pendingLocalState the container was rehydrated from (if any),
+ * as well as the snapshot to be used for serialization.
+ * It also keeps track of container dirty state and which local ops have been processed
+ */
 export declare class SerializedStateManager {
     private readonly pendingLocalState;
     private readonly storageAdapter;
     private readonly _offlineLoadEnabled;
-    private readonly newSnapshotFetched?;
+    private readonly containerDirty;
     private readonly processedOps;
-    private snapshot;
     private readonly mc;
+    private snapshot;
     private latestSnapshot;
-    private refreshSnapshot;
-    constructor(pendingLocalState: IPendingContainerState | undefined, subLogger: ITelemetryLoggerExt, storageAdapter: Pick<IDocumentStorageService, "readBlob" | "getSnapshotTree" | "getSnapshot" | "getVersions">, _offlineLoadEnabled: boolean, newSnapshotFetched?: (() => void) | undefined);
+    private refreshSnapshotP;
+    private readonly lastSavedOpSequenceNumber;
+    /**
+     * @param pendingLocalState - The pendingLocalState being rehydrated, if any (undefined when loading directly from storage)
+     * @param subLogger - Container's logger to use as parent for our logger
+     * @param storageAdapter - Storage adapter for fetching snapshots
+     * @param _offlineLoadEnabled - Is serializing/rehydrating containers allowed?
+     * @param containerEvent - Source of the "saved" event when the container has all its pending state uploaded
+     * @param containerDirty - Is the container "dirty"? That's the opposite of "saved" - there is pending state that may not have been received yet by the service.
+     */
+    constructor(pendingLocalState: IPendingContainerState | undefined, subLogger: ITelemetryBaseLogger, storageAdapter: ISerializedStateManagerDocumentStorageService, _offlineLoadEnabled: boolean, containerEvent: IEventProvider<ISerializerEvent>, containerDirty: () => boolean);
     get offlineLoadEnabled(): boolean;
+    /**
+     * Promise that will resolve (or reject) once we've tried to download the latest snapshot(s) from storage
+     */
+    get waitForInitialRefresh(): Promise<void> | undefined;
+    /**
+     * Called whenever an incoming op is processed by the Container
+     */
     addProcessedOp(message: ISequencedDocumentMessage): void;
+    /**
+     * This wraps the basic functionality of fetching the snapshot for this container during Container load.
+     *
+     * If we have pendingLocalState, we get the snapshot from there.
+     * Otherwise, fetch it from storage (according to specifiedVersion if provided)
+     *
+     * @param specifiedVersion - If a version is specified and we don't have pendingLocalState, fetch this version from storage
+     * @param supportGetSnapshotApi - a boolean indicating whether to use the fetchISnapshot or fetchISnapshotTree.
+     * @returns The snapshot to boot the container from
+     */
     fetchSnapshot(specifiedVersion: string | undefined, supportGetSnapshotApi: boolean): Promise<{
-        baseSnapshot: ISnapshotTree;
+        baseSnapshot: ISnapshotTree | ISnapshot;
         version: IVersion | undefined;
     }>;
+    /**
+     * 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 refreshLatestSnapshot;
     /**
      * Updates class snapshot and processedOps if we have a new snapshot and it's among processedOps range.
      */
     private updateSnapshotAndProcessedOpsMaybe;
     /**
+     * When the Container attaches, we need to stash the initial snapshot (a form of the attach summary).
      * This method is only meant to be used by Container.attach() to set the initial
      * base snapshot when attaching.
-     * @param snapshot - snapshot and blobs collected while attaching
+     * @param snapshot - snapshot and blobs collected while attaching (a form of the attach summary)
      */
     setInitialSnapshot(snapshot: SnapshotWithBlobs | undefined): void;
-    getPendingLocalStateCore(props: IGetPendingLocalStateProps, clientId: string | undefined, runtime: Pick<IRuntime, "getPendingLocalState">, resolvedUrl: IResolvedUrl): Promise<string>;
+    /**
+     * Assembles and serializes the {@link IPendingContainerState} for the container,
+     * to be stored and used to rehydrate the container at a later time.
+     */
+    getPendingLocalState(props: IGetPendingLocalStateProps, clientId: string | undefined, runtime: Pick<IRuntime, "getPendingLocalState">, resolvedUrl: IResolvedUrl): Promise<string>;
 }
 /**
  * Retrieves the most recent snapshot and returns its info.
@@ -86,7 +165,7 @@ export declare class SerializedStateManager {
  * @param supportGetSnapshotApi - a boolean indicating whether to use the fetchISnapshot or fetchISnapshotTree.
  * @returns a SnapshotInfo object containing the snapshot tree, snapshot blobs and its sequence number.
  */
-export declare function getLatestSnapshotInfo(mc: MonitoringContext, storageAdapter: Pick<IDocumentStorageService, "getSnapshot" | "getSnapshotTree" | "getVersions" | "readBlob">, supportGetSnapshotApi: boolean): Promise<ISnapshotInfo | undefined>;
+export declare function getLatestSnapshotInfo(mc: MonitoringContext, storageAdapter: ISerializedStateManagerDocumentStorageService, supportGetSnapshotApi: boolean): Promise<ISnapshotInfo | undefined>;
 /**
  * Fetches an ISnapshot from a storage adapter based on the specified version.
  *
@@ -111,4 +190,5 @@ export declare function fetchISnapshotTree(mc: MonitoringContext, storageAdapter
     snapshot?: ISnapshotTree;
     version?: IVersion | undefined;
 }>;
+export {};
 //# sourceMappingURL=serializedStateManager.d.ts.map

package/dist/serializedStateManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializedStateManager.d.ts","sourceRoot":"","sources":["../src/serializedStateManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"serializedStateManager.d.ts","sourceRoot":"","sources":["../src/serializedStateManager.ts"],"names":[],"mappings":"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"}

package/dist/serializedStateManager.js

@@ -5,41 +5,85 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchISnapshotTree = exports.fetchISnapshot = exports.getLatestSnapshotInfo = exports.SerializedStateManager = void 0;
+const client_utils_1 = require("@fluid-internal/client-utils");
 const internal_1 = require("@fluidframework/core-utils/internal");
-const internal_2 = require("@fluidframework/driver-utils/internal");
-const internal_3 = require("@fluidframework/telemetry-utils/internal");
+const internal_2 = require("@fluidframework/driver-definitions/internal");
+const internal_3 = require("@fluidframework/driver-utils/internal");
+const internal_4 = require("@fluidframework/telemetry-utils/internal");
 const containerStorageAdapter_js_1 = require("./containerStorageAdapter.js");
 const utils_js_1 = require("./utils.js");
+/**
+ * Helper class to manage the state of the container needed for proper serialization.
+ *
+ * It holds the pendingLocalState the container was rehydrated from (if any),
+ * as well as the snapshot to be used for serialization.
+ * It also keeps track of container dirty state and which local ops have been processed
+ */
 class SerializedStateManager {
-    constructor(pendingLocalState, subLogger, storageAdapter, _offlineLoadEnabled, newSnapshotFetched) {
+    /**
+     * @param pendingLocalState - The pendingLocalState being rehydrated, if any (undefined when loading directly from storage)
+     * @param subLogger - Container's logger to use as parent for our logger
+     * @param storageAdapter - Storage adapter for fetching snapshots
+     * @param _offlineLoadEnabled - Is serializing/rehydrating containers allowed?
+     * @param containerEvent - Source of the "saved" event when the container has all its pending state uploaded
+     * @param containerDirty - Is the container "dirty"? That's the opposite of "saved" - there is pending state that may not have been received yet by the service.
+     */
+    constructor(pendingLocalState, subLogger, storageAdapter, _offlineLoadEnabled, containerEvent, containerDirty) {
         this.pendingLocalState = pendingLocalState;
         this.storageAdapter = storageAdapter;
         this._offlineLoadEnabled = _offlineLoadEnabled;
-        this.newSnapshotFetched = newSnapshotFetched;
+        this.containerDirty = containerDirty;
         this.processedOps = [];
-        this.mc = (0, internal_3.createChildMonitoringContext)({
+        this.lastSavedOpSequenceNumber = 0;
+        this.mc = (0, internal_4.createChildMonitoringContext)({
             logger: subLogger,
             namespace: "serializedStateManager",
         });
+        if (pendingLocalState && pendingLocalState.savedOps.length > 0) {
+            const savedOpsSize = pendingLocalState.savedOps.length;
+            this.lastSavedOpSequenceNumber =
+                pendingLocalState.savedOps[savedOpsSize - 1].sequenceNumber;
+        }
+        containerEvent.once("saved", () => this.updateSnapshotAndProcessedOpsMaybe());
     }
     get offlineLoadEnabled() {
         return this._offlineLoadEnabled;
     }
+    /**
+     * Promise that will resolve (or reject) once we've tried to download the latest snapshot(s) from storage
+     */
+    get waitForInitialRefresh() {
+        return this.refreshSnapshotP;
+    }
+    /**
+     * Called whenever an incoming op is processed by the Container
+     */
     addProcessedOp(message) {
         if (this.offlineLoadEnabled) {
             this.processedOps.push(message);
             this.updateSnapshotAndProcessedOpsMaybe();
         }
     }
+    /**
+     * This wraps the basic functionality of fetching the snapshot for this container during Container load.
+     *
+     * If we have pendingLocalState, we get the snapshot from there.
+     * Otherwise, fetch it from storage (according to specifiedVersion if provided)
+     *
+     * @param specifiedVersion - If a version is specified and we don't have pendingLocalState, fetch this version from storage
+     * @param supportGetSnapshotApi - a boolean indicating whether to use the fetchISnapshot or fetchISnapshotTree.
+     * @returns The snapshot to boot the container from
+     */
     async fetchSnapshot(specifiedVersion, supportGetSnapshotApi) {
         if (this.pendingLocalState === undefined) {
-            const { baseSnapshot, version } = await getSnapshotTree(this.mc, this.storageAdapter, supportGetSnapshotApi, specifiedVersion);
+            const { baseSnapshot, version } = await getSnapshot(this.mc, this.storageAdapter, supportGetSnapshotApi, specifiedVersion);
+            const baseSnapshotTree = (0, internal_3.getSnapshotTree)(baseSnapshot);
             // non-interactive clients will not have any pending state we want to save
             if (this.offlineLoadEnabled) {
-                const snapshotBlobs = await (0, containerStorageAdapter_js_1.getBlobContentsFromTree)(baseSnapshot, this.storageAdapter);
-                const attributes = await (0, utils_js_1.getDocumentAttributes)(this.storageAdapter, baseSnapshot);
+                const snapshotBlobs = await (0, containerStorageAdapter_js_1.getBlobContentsFromTree)(baseSnapshotTree, this.storageAdapter);
+                const attributes = await (0, utils_js_1.getDocumentAttributes)(this.storageAdapter, baseSnapshotTree);
                 this.snapshot = {
-                    baseSnapshot,
+                    baseSnapshot: baseSnapshotTree,
                     snapshotBlobs,
                     snapshotSequenceNumber: attributes.sequenceNumber,
                 };
@@ -54,19 +98,66 @@ class SerializedStateManager {
                 snapshotBlobs,
                 snapshotSequenceNumber: attributes.sequenceNumber,
             };
-            this.refreshSnapshot ?? (this.refreshSnapshot = (async () => {
-                this.latestSnapshot = await getLatestSnapshotInfo(this.mc, this.storageAdapter, supportGetSnapshotApi);
-                this.newSnapshotFetched?.();
-                this.updateSnapshotAndProcessedOpsMaybe();
-            })());
-            return { baseSnapshot, version: undefined };
+            if (this.refreshSnapshotP === undefined &&
+                this.mc.config.getBoolean("Fluid.Container.enableOfflineSnapshotRefresh") === true) {
+                // Don't block on the refresh snapshot call - it is for the next time we serialize, not booting this incarnation
+                this.refreshSnapshotP = this.refreshLatestSnapshot(supportGetSnapshotApi);
+                this.refreshSnapshotP.catch((e) => {
+                    this.mc.logger.sendErrorEvent({
+                        eventName: "RefreshLatestSnapshotFailed",
+                        error: e,
+                    });
+                });
+            }
+            const blobContents = new Map();
+            for (const [id, value] of Object.entries(snapshotBlobs)) {
+                blobContents.set(id, (0, client_utils_1.stringToBuffer)(value, "utf8"));
+            }
+            const iSnapshot = {
+                sequenceNumber: this.snapshot.snapshotSequenceNumber,
+                snapshotTree: baseSnapshot,
+                blobContents,
+                latestSequenceNumber: undefined,
+                ops: [],
+                snapshotFormatV: 1,
+            };
+            return { baseSnapshot: iSnapshot, version: undefined };
         }
     }
+    /**
+     * 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)
+     */
+    async refreshLatestSnapshot(supportGetSnapshotApi) {
+        this.latestSnapshot = await getLatestSnapshotInfo(this.mc, this.storageAdapter, supportGetSnapshotApi);
+        // 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) {
+            (0, internal_1.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: internal_2.FetchSource.noCache,
+            });
+            (0, internal_1.assert)(snapshot !== undefined, 0x973 /* Snapshot should exist */);
+        }
+        this.updateSnapshotAndProcessedOpsMaybe();
+    }
     /**
      * Updates class snapshot and processedOps if we have a new snapshot and it's among processedOps range.
      */
     updateSnapshotAndProcessedOpsMaybe() {
-        if (this.latestSnapshot === undefined || this.processedOps.length === 0) {
+        if (this.latestSnapshot === undefined ||
+            this.processedOps.length === 0 ||
+            this.processedOps[this.processedOps.length - 1].sequenceNumber <
+                this.lastSavedOpSequenceNumber ||
+            this.containerDirty()) {
             // can't refresh latest snapshot until we have processed the ops up to it.
             // Pending state would be behind the latest snapshot.
             return;
@@ -103,9 +194,10 @@ class SerializedStateManager {
         }
     }
     /**
+     * When the Container attaches, we need to stash the initial snapshot (a form of the attach summary).
      * This method is only meant to be used by Container.attach() to set the initial
      * base snapshot when attaching.
-     * @param snapshot - snapshot and blobs collected while attaching
+     * @param snapshot - snapshot and blobs collected while attaching (a form of the attach summary)
      */
     setInitialSnapshot(snapshot) {
         if (this.offlineLoadEnabled) {
@@ -120,27 +212,47 @@ class SerializedStateManager {
             this.snapshot = { ...snapshot, snapshotSequenceNumber: attributes.sequenceNumber };
         }
     }
-    async getPendingLocalStateCore(props, clientId, runtime, resolvedUrl) {
-        return internal_3.PerformanceEvent.timedExecAsync(this.mc.logger, {
+    /**
+     * Assembles and serializes the {@link IPendingContainerState} for the container,
+     * to be stored and used to rehydrate the container at a later time.
+     */
+    async getPendingLocalState(props, clientId, runtime, resolvedUrl) {
+        return internal_4.PerformanceEvent.timedExecAsync(this.mc.logger, {
             eventName: "getPendingLocalState",
             notifyImminentClosure: props.notifyImminentClosure,
             processedOpsSize: this.processedOps.length,
             clientId,
         }, async () => {
             if (!this.offlineLoadEnabled) {
-                throw new internal_3.UsageError("Can't get pending local state unless offline load is enabled");
+                throw new internal_4.UsageError("Can't get pending local state unless offline load is enabled");
             }
             (0, internal_1.assert)(this.snapshot !== undefined, 0x8e5 /* no base data */);
-            const pendingRuntimeState = await runtime.getPendingLocalState(props);
+            const pendingRuntimeState = await runtime.getPendingLocalState({
+                ...props,
+                snapshotSequenceNumber: this.snapshot.snapshotSequenceNumber,
+                sessionExpiryTimerStarted: this.snapshot.snapshotFetchedTime,
+            });
+            // This conversion is required because ArrayBufferLike doesn't survive JSON.stringify
+            const loadedGroupIdSnapshots = {};
+            let hasGroupIdSnapshots = false;
+            const groupIdSnapshots = Object.entries(this.storageAdapter.loadedGroupIdSnapshots);
+            if (groupIdSnapshots.length > 0) {
+                for (const [groupId, snapshot] of groupIdSnapshots) {
+                    hasGroupIdSnapshots = true;
+                    loadedGroupIdSnapshots[groupId] = (0, utils_js_1.convertSnapshotToSnapshotInfo)(snapshot);
+                }
+            }
             const pendingState = {
                 attached: true,
                 pendingRuntimeState,
                 baseSnapshot: this.snapshot.baseSnapshot,
                 snapshotBlobs: this.snapshot.snapshotBlobs,
+                loadedGroupIdSnapshots: hasGroupIdSnapshots
+                    ? loadedGroupIdSnapshots
+                    : undefined,
                 savedOps: this.processedOps,
                 url: resolvedUrl.url,
-                // no need to save this if there is no pending runtime state
-                clientId: pendingRuntimeState !== undefined ? clientId : undefined,
+                clientId,
             };
             return JSON.stringify(pendingState);
         });
@@ -156,12 +268,19 @@ exports.SerializedStateManager = SerializedStateManager;
  * @returns a SnapshotInfo object containing the snapshot tree, snapshot blobs and its sequence number.
  */
 async function getLatestSnapshotInfo(mc, storageAdapter, supportGetSnapshotApi) {
-    return internal_3.PerformanceEvent.timedExecAsync(mc.logger, { eventName: "GetLatestSnapshotInfo" }, async () => {
-        const { baseSnapshot } = await getSnapshotTree(mc, storageAdapter, supportGetSnapshotApi, undefined);
-        const snapshotBlobs = await (0, containerStorageAdapter_js_1.getBlobContentsFromTree)(baseSnapshot, storageAdapter);
-        const attributes = await (0, utils_js_1.getDocumentAttributes)(storageAdapter, baseSnapshot);
+    return internal_4.PerformanceEvent.timedExecAsync(mc.logger, { eventName: "GetLatestSnapshotInfo" }, async () => {
+        const { baseSnapshot } = await getSnapshot(mc, storageAdapter, supportGetSnapshotApi, undefined);
+        const baseSnapshotTree = (0, internal_3.getSnapshotTree)(baseSnapshot);
+        const snapshotFetchedTime = Date.now();
+        const snapshotBlobs = await (0, containerStorageAdapter_js_1.getBlobContentsFromTree)(baseSnapshotTree, storageAdapter);
+        const attributes = await (0, utils_js_1.getDocumentAttributes)(storageAdapter, baseSnapshotTree);
         const snapshotSequenceNumber = attributes.sequenceNumber;
-        return { baseSnapshot, snapshotBlobs, snapshotSequenceNumber };
+        return {
+            baseSnapshot: baseSnapshotTree,
+            snapshotBlobs,
+            snapshotSequenceNumber,
+            snapshotFetchedTime,
+        };
     }).catch(() => undefined);
 }
 exports.getLatestSnapshotInfo = getLatestSnapshotInfo;
@@ -174,15 +293,12 @@ exports.getLatestSnapshotInfo = getLatestSnapshotInfo;
  * @param specifiedVersion - An optional version string specifying the version of the snapshot tree to fetch.
  * @returns - An ISnapshotTree and its version.
  */
-async function getSnapshotTree(mc, storageAdapter, supportGetSnapshotApi, specifiedVersion) {
+async function getSnapshot(mc, storageAdapter, supportGetSnapshotApi, specifiedVersion) {
     const { snapshot, version } = supportGetSnapshotApi
         ? await fetchISnapshot(mc, storageAdapter, specifiedVersion)
         : await fetchISnapshotTree(mc, storageAdapter, specifiedVersion);
-    const baseSnapshot = (0, internal_2.isInstanceOfISnapshot)(snapshot)
-        ? snapshot.snapshotTree
-        : snapshot;
-    (0, internal_1.assert)(baseSnapshot !== undefined, 0x8e4 /* Snapshot should exist */);
-    return { baseSnapshot, version };
+    (0, internal_1.assert)(snapshot !== undefined, 0x8e4 /* Snapshot should exist */);
+    return { baseSnapshot: snapshot, version };
 }
 /**
  * Fetches an ISnapshot from a storage adapter based on the specified version.