@fluidframework/container-loader 1.0.1 → 1.1.0

package/src/container.ts

@@ -7,7 +7,7 @@
 import merge from "lodash/merge";
 import { v4 as uuid } from "uuid";
 import {
-    IDisposable,
+    IDisposable, ITelemetryProperties,
 } from "@fluidframework/common-definitions";
 import { assert, performance, unreachableCase } from "@fluidframework/common-utils";
 import {
@@ -53,7 +53,8 @@ import {
 } from "@fluidframework/driver-utils";
 import {
     isSystemMessage,
-    ProtocolOpHandler,
+    IProtocolHandler,
+    ProtocolOpHandlerWithClientValidation,
 } from "@fluidframework/protocol-base";
 import {
     IClient,
@@ -98,7 +99,7 @@ import { DeltaManager, IConnectionArgs } from "./deltaManager";
 import { DeltaManagerProxy } from "./deltaManagerProxy";
 import { ILoaderOptions, Loader, RelativeLoader } from "./loader";
 import { pkgVersion } from "./packageVersion";
-import { ConnectionStateHandler, ILocalSequencedClient } from "./connectionStateHandler";
+import { ConnectionStateHandler } from "./connectionStateHandler";
 import { RetriableDocumentStorageService } from "./retriableDocumentStorageService";
 import { ProtocolTreeStorageService } from "./protocolTreeDocumentStorageService";
 import { BlobOnlyStorage, ContainerStorageAdapter } from "./containerStorageAdapter";
@@ -262,7 +263,6 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
             container.mc.logger,
             { eventName: "Load" },
             async (event) => new Promise<Container>((resolve, reject) => {
-                container._lifecycleState = "loading";
                 const version = loadOptions.version;
 
                 const defaultMode: IContainerLoadMode = { opsBeforeReturn: "cached" };
@@ -314,7 +314,6 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
             container.mc.logger,
             { eventName: "CreateDetached" },
             async (_event) => {
-                container._lifecycleState = "loading";
                 await container.createDetached(codeDetails);
                 return container;
             },
@@ -337,7 +336,6 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
             { eventName: "RehydrateDetachedFromSnapshot" },
             async (_event) => {
                 const deserializedSummary = JSON.parse(snapshot) as ISummaryTree;
-                container._lifecycleState = "loading";
                 await container.rehydrateDetachedFromSnapshot(deserializedSummary);
                 return container;
             },
@@ -352,19 +350,14 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
 
     private readonly mc: MonitoringContext;
 
-    private _lifecycleState: "created" | "loading" | "loaded" | "closing" | "closed" = "created";
-
-    private get loaded(): boolean {
-        return (this._lifecycleState !== "created" && this._lifecycleState !== "loading");
-    }
-
-    private set loaded(t: boolean) {
-        assert(t, 0x27d /* "Setting loaded state to false is not supported" */);
-        assert(this._lifecycleState !== "created", 0x27e /* "Must go through loading state before loaded" */);
+    private _lifecycleState: "loading" | "loaded" | "closing" | "closed" = "loading";
 
+    private setLoaded() {
         // It's conceivable the container could be closed when this is called
         // Only transition states if currently loading
         if (this._lifecycleState === "loading") {
+            // Propagate current connection state through the system.
+            this.propagateConnectionState();
             this._lifecycleState = "loaded";
         }
     }
@@ -400,7 +393,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         }
         return this._context;
     }
-    private _protocolHandler: ProtocolOpHandler | undefined;
+    private _protocolHandler: IProtocolHandler | undefined;
     private get protocolHandler() {
         if (this._protocolHandler === undefined) {
             throw new Error("Attempted to access protocolHandler before it was defined");
@@ -608,16 +601,18 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
                     this.logConnectionStateChangeTelemetry(value, oldState, reason),
                 shouldClientJoinWrite: () => this._deltaManager.connectionManager.shouldJoinWrite(),
                 maxClientLeaveWaitTime: this.loader.services.options.maxClientLeaveWaitTime,
-                logConnectionIssue: (eventName: string) => {
+                logConnectionIssue: (eventName: string, details?: ITelemetryProperties) => {
                     // We get here when socket does not receive any ops on "write" connection, including
                     // its own join op. Attempt recovery option.
                     this._deltaManager.logConnectionIssue({
                         eventName,
                         duration: performance.now() - this.connectionTransitionTimes[ConnectionState.CatchingUp],
+                        ...(details === undefined ? {} : { details: JSON.stringify(details) }),
                     });
                 },
                 connectionStateChanged: () => {
-                    if (this.loaded) {
+                    // Fire events only if container is fully loaded and not closed
+                    if (this._lifecycleState === "loaded") {
                         this.propagateConnectionState();
                     }
                 },
@@ -708,16 +703,34 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
     }
 
     public close(error?: ICriticalContainerError) {
-        if (this.closed) {
-            return;
-        }
+        // 1. Ensure that close sequence is exactly the same no matter if it's initiated by host or by DeltaManager
+        // 2. We need to ensure that we deliver disconnect event to runtime properly. See connectionStateChanged
+        //    handler. We only deliver events if container fully loaded. Transitioning from "loading" ->
+        //    "closing" will lose that info (can also solve by tracking extra state).
+        this._deltaManager.close(error);
+        assert(this.connectionState === ConnectionState.Disconnected,
+            0x0cf /* "disconnect event was not raised!" */);
 
-        try {
-            this._lifecycleState = "closing";
+        assert(this._lifecycleState === "closed", 0x314 /* Container properly closed */);
+    }
+
+    private closeCore(error?: ICriticalContainerError) {
+        assert(!this.closed, 0x315 /* re-entrancy */);
 
+        try {
             // Ensure that we raise all key events even if one of these throws
             try {
-                this._deltaManager.close(error);
+                // Raise event first, to ensure we capture _lifecycleState before transition.
+                // This gives us a chance to know what errors happened on open vs. on fully loaded container.
+                this.mc.logger.sendTelemetryEvent(
+                    {
+                        eventName: "ContainerClose",
+                        category: error === undefined ? "generic" : "error",
+                    },
+                    error,
+                );
+
+                this._lifecycleState = "closing";
 
                 this._protocolHandler?.close();
 
@@ -725,9 +738,6 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
 
                 this._context?.dispose(error !== undefined ? new Error(error.message) : undefined);
 
-                assert(this.connectionState === ConnectionState.Disconnected,
-                    0x0cf /* "disconnect event was not raised!" */);
-
                 this._storageService?.dispose();
 
                 // Notify storage about critical errors. They may be due to disconnect between client & server knowledge
@@ -738,14 +748,6 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
                 this.mc.logger.sendErrorEvent({ eventName: "ContainerCloseException" }, exception);
             }
 
-            this.mc.logger.sendTelemetryEvent(
-                {
-                    eventName: "ContainerClose",
-                    category: error === undefined ? "generic" : "error",
-                },
-                error,
-            );
-
             this.emit("closed", error);
 
             this.removeAllListeners();
@@ -766,11 +768,13 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         assert(this.resolvedUrl !== undefined && this.resolvedUrl.type === "fluid",
             0x0d2 /* "resolved url should be valid Fluid url" */);
         assert(!!this._protocolHandler, 0x2e3 /* "Must have a valid protocol handler instance" */);
+        assert(this._protocolHandler.attributes.term !== undefined,
+            0x30b /* Must have a valid protocol handler instance */);
         const pendingState: IPendingContainerState = {
             pendingRuntimeState: this.context.getPendingLocalState(),
             url: this.resolvedUrl.url,
-            protocol: this._protocolHandler.getProtocolState(),
-            term: this._protocolHandler.term,
+            protocol: this.protocolHandler.getProtocolState(),
+            term: this._protocolHandler.attributes.term,
             clientId: this.clientId,
         };
 
@@ -1167,11 +1171,8 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
             pendingLocalState?.pendingRuntimeState,
         );
 
-        // Propagate current connection state through the system.
-        this.propagateConnectionState();
-
         // Internal context is fully loaded at this point
-        this.loaded = true;
+        this.setLoaded();
 
         // We might have hit some failure that did not manifest itself in exception in this flow,
         // do not start op processing in such case - static version of Container.load() will handle it correctly.
@@ -1243,9 +1244,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
             false, // existing
         );
 
-        this.propagateConnectionState();
-
-        this.loaded = true;
+        this.setLoaded();
     }
 
     private async rehydrateDetachedFromSnapshot(detachedContainerSnapshot: ISummaryTree) {
@@ -1280,9 +1279,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
             snapshotTree,
         );
 
-        this.loaded = true;
-
-        this.propagateConnectionState();
+        this.setLoaded();
     }
 
     private async connectStorageService(): Promise<void> {
@@ -1338,7 +1335,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         attributes: IDocumentAttributes,
         storage: IDocumentStorageService,
         snapshot: ISnapshotTree | undefined,
-    ): Promise<ProtocolOpHandler> {
+    ): Promise<IProtocolHandler> {
         let members: [string, ISequencedClient][] = [];
         let proposals: [number, ISequencedProposal, string[]][] = [];
         let values: [string, any][] = [];
@@ -1366,8 +1363,8 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         members: [string, ISequencedClient][],
         proposals: [number, ISequencedProposal, string[]][],
         values: [string, any][],
-    ): Promise<ProtocolOpHandler> {
-        const protocol = new ProtocolOpHandler(
+    ): Promise<IProtocolHandler> {
+        const protocol = new ProtocolOpHandlerWithClientValidation(
             attributes.minimumSequenceNumber,
             attributes.sequenceNumber,
             attributes.term,
@@ -1412,19 +1409,11 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
     }
 
     private captureProtocolSummary(): ISummaryTree {
-        const quorumSnapshot = this.protocolHandler.quorum.snapshot();
-
-        // Save attributes for the document
-        const documentAttributes: IDocumentAttributes = {
-            minimumSequenceNumber: this.protocolHandler.minimumSequenceNumber,
-            sequenceNumber: this.protocolHandler.sequenceNumber,
-            term: this.protocolHandler.term,
-        };
-
+        const quorumSnapshot = this.protocolHandler.snapshot();
         const summary: ISummaryTree = {
             tree: {
                 attributes: {
-                    content: JSON.stringify(documentAttributes),
+                    content: JSON.stringify(this.protocolHandler.attributes),
                     type: SummaryType.Blob,
                 },
                 quorumMembers: {
@@ -1539,7 +1528,7 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         });
 
         deltaManager.on("closed", (error?: ICriticalContainerError) => {
-            this.close(error);
+            this.closeCore(error);
         });
 
         return deltaManager;
@@ -1629,11 +1618,13 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
         }
 
         const state = this.connectionState === ConnectionState.Connected;
-        if (!this.context.disposed) {
+
+        // Both protocol and context should not be undefined if we got so far.
+
+        if (this._context?.disposed === false) {
             this.context.setConnectionState(state, this.clientId);
         }
-        assert(this.protocolHandler !== undefined, 0x0dc /* "Protocol handler should be set here" */);
-        this.protocolHandler.quorum.setConnectionState(state, this.clientId);
+        this.protocolHandler.setConnectionState(state, this.clientId);
         raiseConnectedEvent(this.mc.logger, this, state, this.clientId);
 
         if (logOpsOnReconnect) {
@@ -1682,36 +1673,22 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
     }
 
     private processRemoteMessage(message: ISequencedDocumentMessage): IProcessMessageResult {
-        // 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) {
-            let errorMsg: string | undefined;
-            const client: ILocalSequencedClient | undefined =
-                this.getQuorum().getMember(message.clientId);
-            if (client === undefined && message.type !== MessageType.ClientJoin) {
-                // pre-0.58 error message: messageClientIdMissingFromQuorum
-                errorMsg = "Remote message's clientId is missing from the quorum";
-            } else if (client?.shouldHaveLeft === true && message.type !== MessageType.NoOp) {
-                // pre-0.58 error message: messageClientIdShouldHaveLeft
-                errorMsg = "Remote message's clientId already should have left";
-            }
-            if (errorMsg !== undefined) {
-                const error = new DataCorruptionError(
-                    errorMsg,
-                    extractSafePropertiesFromMessage(message));
-                this.close(normalizeError(error));
-            }
-        }
-
         const local = this.clientId === message.clientId;
 
+        // Allow the protocol handler to process the message
+        let result: IProcessMessageResult = { immediateNoOp: false };
+        try {
+            result = this.protocolHandler.processMessage(message, local);
+        } catch (error) {
+            this.close(wrapError(error, (errorMessage) =>
+                new DataCorruptionError(errorMessage, extractSafePropertiesFromMessage(message))));
+        }
+
         // Forward non system messages to the loaded runtime for processing
         if (!isSystemMessage(message)) {
             this.context.process(message, local, undefined);
         }
 
-        // Allow the protocol handler to process the message
-        const result = this.protocolHandler.processMessage(message, local);
         // Inactive (not in quorum or not writers) clients don't take part in the minimum sequence number calculation.
         if (this.activeConnection()) {
             if (this.collabWindowTracker === undefined) {
@@ -1728,8 +1705,8 @@ export class Container extends EventEmitterWithErrorHandling<IContainerEvents> i
                             0x241 /* "disconnect should result in stopSequenceNumberUpdate() call" */);
                         this.submitMessage(type, contents);
                     },
-                    this.serviceConfiguration?.noopTimeFrequency,
-                    this.serviceConfiguration?.noopCountFrequency,
+                    this.serviceConfiguration.noopTimeFrequency,
+                    this.serviceConfiguration.noopCountFrequency,
                 );
             }
             this.collabWindowTracker.scheduleSequenceNumberUpdate(message, result.immediateNoOp === true);

package/src/containerStorageAdapter.ts

@@ -53,8 +53,8 @@ export class ContainerStorageAdapter implements IDocumentStorageService {
         return this.storageGetter().repositoryUrl;
     }
 
-    public async getSnapshotTree(version?: IVersion): Promise<ISnapshotTree | null> {
-        return this.storageGetter().getSnapshotTree(version);
+    public async getSnapshotTree(version?: IVersion, scenarioName?: string): Promise<ISnapshotTree | null> {
+        return this.storageGetter().getSnapshotTree(version, scenarioName);
     }
 
     public async readBlob(id: string): Promise<ArrayBufferLike> {
@@ -65,8 +65,8 @@ export class ContainerStorageAdapter implements IDocumentStorageService {
         return this.storageGetter().readBlob(id);
     }
 
-    public async getVersions(versionId: string | null, count: number): Promise<IVersion[]> {
-        return this.storageGetter().getVersions(versionId, count);
+    public async getVersions(versionId: string | null, count: number, scenarioName?: string): Promise<IVersion[]> {
+        return this.storageGetter().getVersions(versionId, count, scenarioName);
     }
 
     public async uploadSummaryWithContext(summary: ISummaryTree, context: ISummaryContext): Promise<string> {

package/src/contracts.ts

@@ -163,7 +163,7 @@ export interface IConnectionManagerFactoryArgs {
 
 /**
  *
- * @param codeDetails- Data structure used to describe the code to load on the Fluid document
+ * @param codeDetails- - Data structure used to describe the code to load on the Fluid document
  * @returns The name of the Fluid package
  */
 export const getPackageName = (codeDetails: IFluidCodeDetails | undefined): IContainerPackageInfo => {

package/src/deltaManager.ts

@@ -267,8 +267,14 @@ export class DeltaManager<TConnectionManager extends IConnectionManager>
     ) {
         super();
         const props: IConnectionManagerFactoryArgs = {
-            incomingOpHandler: (messages: ISequencedDocumentMessage[], reason: string) =>
-                this.enqueueMessages(messages, reason),
+            incomingOpHandler: (messages: ISequencedDocumentMessage[], reason: string) => {
+                try {
+                    this.enqueueMessages(messages, reason);
+                } catch (error) {
+                    this.logger.sendErrorEvent({ eventName: "EnqueueMessages_Exception" }, error);
+                    this.close(normalizeError(error));
+                }
+            },
             signalHandler: (message: ISignalMessage) => this._inboundSignal.push(message),
             reconnectionDelayHandler: (delayMs: number, error: unknown) =>
                 this.emitDelayInfo(this.deltaStreamDelayId, delayMs, error),

package/src/deltaQueue.ts

@@ -85,9 +85,13 @@ export class DeltaQueue<T>
     }
 
     public push(task: T) {
-        this.q.push(task);
-        this.emit("push", task);
-        this.ensureProcessing();
+        try {
+            this.q.push(task);
+            this.emit("push", task);
+            this.ensureProcessing();
+        } catch (error) {
+            this.emit("error", error);
+        }
     }
 
     public async pause(): Promise<void> {

package/src/packageVersion.ts

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

package/src/retriableDocumentStorageService.ts

@@ -40,9 +40,9 @@ export class RetriableDocumentStorageService implements IDocumentStorageService,
         return this.internalStorageService.repositoryUrl;
     }
 
-    public async getSnapshotTree(version?: IVersion): Promise<ISnapshotTree | null> {
+    public async getSnapshotTree(version?: IVersion, scenarioName?: string): Promise<ISnapshotTree | null> {
         return this.runWithRetry(
-            async () => this.internalStorageService.getSnapshotTree(version),
+            async () => this.internalStorageService.getSnapshotTree(version, scenarioName),
             "storage_getSnapshotTree",
         );
     }
@@ -54,9 +54,9 @@ export class RetriableDocumentStorageService implements IDocumentStorageService,
         );
     }
 
-    public async getVersions(versionId: string | null, count: number): Promise<IVersion[]> {
+    public async getVersions(versionId: string | null, count: number, scenarioName?: string): Promise<IVersion[]> {
         return this.runWithRetry(
-            async () => this.internalStorageService.getVersions(versionId, count),
+            async () => this.internalStorageService.getVersions(versionId, count, scenarioName),
             "storage_getVersions",
         );
     }

package/src/utils.ts

@@ -12,6 +12,7 @@ import {
     unreachableCase,
 } from "@fluidframework/common-utils";
 import { ISummaryTree, ISnapshotTree, SummaryType } from "@fluidframework/protocol-definitions";
+import { LoggingError } from "@fluidframework/telemetry-utils";
 
 // This is used when we rehydrate a container from the snapshot. Here we put the blob contents
 // in separate property: blobContents.
@@ -35,7 +36,7 @@ export interface IParsedUrl {
 export function parseUrl(url: string): IParsedUrl | undefined {
     const parsed = parse(url, true);
     if (typeof parsed.pathname !== "string") {
-        throw new Error("Failed to parse pathname");
+        throw new LoggingError("Failed to parse pathname");
     }
     const query = parsed.search ?? "";
     const regex = /^\/([^/]*\/[^/]*)(\/?.*)$/;
@@ -86,7 +87,7 @@ function convertSummaryToSnapshotWithEmbeddedBlobContents(
                 break;
             }
             case SummaryType.Handle:
-                throw new Error("No handles should be there in summary in detached container!!");
+                throw new LoggingError("No handles should be there in summary in detached container!!");
                 break;
             default: {
                 unreachableCase(summaryObject, `Unknown tree type ${(summaryObject as any).type}`);