@fluidframework/container-runtime 2.41.0-338186 → 2.41.0

package/lib/containerRuntime.js

@@ -2,10 +2,10 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { Trace, TypedEventEmitter } from "@fluid-internal/client-utils";
+import { createEmitter, Trace, TypedEventEmitter } from "@fluid-internal/client-utils";
 import { AttachState } from "@fluidframework/container-definitions";
 import { isIDeltaManagerFull } from "@fluidframework/container-definitions/internal";
-import { assert, Deferred, LazyPromise, PromiseCache, delay, } from "@fluidframework/core-utils/internal";
+import { assert, Deferred, Lazy, LazyPromise, PromiseCache, delay, fail, } from "@fluidframework/core-utils/internal";
 import { SummaryType } from "@fluidframework/driver-definitions";
 import { FetchSource, MessageType } from "@fluidframework/driver-definitions/internal";
 import { readAndParse } from "@fluidframework/driver-utils/internal";
@@ -497,7 +497,7 @@ export class ContainerRuntime extends TypedEventEmitter {
     }
     /**
      * Invokes the given callback and expects that no ops are submitted
-     * until execution finishes. If an op is submitted, an error will be raised.
+     * until execution finishes. If an op is submitted, it will be marked as reentrant.
      *
      * @param callback - the callback to be invoked
      */
@@ -569,7 +569,7 @@ export class ContainerRuntime extends TypedEventEmitter {
         // Once it loads, it will process all such ops and we will stop accumulating further ops - ops will be processes as they come in.
         this.pendingIdCompressorOps = [];
         this.batchRunner = new BatchRunCounter();
-        this.flushTaskExists = false;
+        this.flushScheduled = false;
         this.consecutiveReconnects = 0;
         this.dataModelChangeRunner = new RunCounter();
         this._disposed = false;
@@ -582,6 +582,7 @@ export class ContainerRuntime extends TypedEventEmitter {
         this.snapshotCacheForLoadingGroupIds = new PromiseCache({
             expiry: { policy: "absolute", durationMs: 60000 },
         });
+        this.extensions = new Map();
         this.notifyReadOnlyState = (readonly) => this.channelCollection.notifyReadOnlyState(readonly);
         /**
          * Enter Staging Mode, such that ops submitted to the ContainerRuntime will not be sent to the ordering service.
@@ -615,9 +616,7 @@ export class ContainerRuntime extends TypedEventEmitter {
                         assert(runtimeOp !== undefined, 0xb82 /* Staged batches expected to have runtimeOp defined */);
                         this.rollback(runtimeOp, localOpMetadata);
                     });
-                    if (this.attachState === AttachState.Attached) {
-                        this.updateDocumentDirtyState(this.pendingMessagesCount !== 0);
-                    }
+                    this.updateDocumentDirtyState();
                 }),
                 commitChanges: (optionsParam) => {
                     const options = { ...defaultStagingCommitOptions, ...optionsParam };
@@ -634,6 +633,15 @@ export class ContainerRuntime extends TypedEventEmitter {
             return this.stageControls;
         };
         this.readAndParseBlob = async (id) => readAndParse(this.storage, id);
+        // While internal, ContainerRuntime has not been converted to use the new events support.
+        // Recreate the required events (new pattern) with injected, wrapper new emitter.
+        // It is lazily create to avoid listeners (old events) that ultimately go nowhere.
+        this.lazyEventsForExtensions = new Lazy(() => {
+            const eventEmitter = createEmitter();
+            this.on("connected", (clientId) => eventEmitter.emit("connected", clientId));
+            this.on("disconnected", () => eventEmitter.emit("disconnected"));
+            return eventEmitter;
+        });
         const { options, clientDetails, connected, baseSnapshot, submitFn, submitBatchFn, submitSummaryFn, submitSignalFn, disposeFn, closeFn, deltaManager, quorum, audience, pendingLocalState, supportedFeatures, snapshotWithContents, } = context;
         // In old loaders without dispose functionality, closeFn is equivalent but will also switch container to readonly mode
         this.disposeFn = disposeFn ?? closeFn;
@@ -662,7 +670,23 @@ export class ContainerRuntime extends TypedEventEmitter {
         this.submitSummaryFn =
             submitSummaryFn ??
                 ((summaryOp, refseq) => submitFn(MessageType.Summarize, summaryOp, false));
-        this.submitSignalFn = submitSignalFn;
+        const sequenceAndSubmitSignal = (envelope, targetClientId) => {
+            if (targetClientId === undefined) {
+                this.signalTelemetryManager.applyTrackingToBroadcastSignalEnvelope(envelope);
+            }
+            submitSignalFn(envelope, targetClientId);
+        };
+        this.submitSignalFn = (envelope, targetClientId) => {
+            if (envelope.address?.startsWith("/")) {
+                throw new Error("General path based addressing is not implemented");
+            }
+            sequenceAndSubmitSignal(envelope, targetClientId);
+        };
+        this.submitExtensionSignal = (id, addressChain, message) => {
+            this.verifyNotClosed();
+            const envelope = createNewSignalEnvelope(`/ext/${id}/${addressChain.join("/")}`, message.type, message.content);
+            sequenceAndSubmitSignal(envelope, message.targetClientId);
+        };
         // TODO: After IContainerContext.options is removed, we'll just create a new blank object {} here.
         // Values are generally expected to be set from the runtime side.
         this.options = options ?? {};
@@ -694,8 +718,8 @@ export class ContainerRuntime extends TypedEventEmitter {
             this.mc.logger.sendTelemetryEvent({
                 eventName: "Attached",
                 details: {
-                    dirtyContainer: this.dirtyContainer,
-                    hasPendingMessages: this.hasPendingMessages(),
+                    lastEmittedDirty: this.lastEmittedDirty,
+                    currentDirtyState: this.computeCurrentDirtyState(),
                 },
             });
         });
@@ -862,9 +886,6 @@ export class ContainerRuntime extends TypedEventEmitter {
             // verifyNotClosed is called in FluidDataStoreContext, which is *the* expected caller.
             const envelope1 = content;
             const envelope2 = createNewSignalEnvelope(envelope1.address, type, envelope1.contents);
-            if (targetClientId === undefined) {
-                this.signalTelemetryManager.applyTrackingToBroadcastSignalEnvelope(envelope2);
-            }
             this.submitSignalFn(envelope2, targetClientId);
         };
         let snapshot = getSummaryForDatastores(baseSnapshot, metadata);
@@ -958,9 +979,9 @@ export class ContainerRuntime extends TypedEventEmitter {
         const closeSummarizerDelayOverride = this.mc.config.getNumber("Fluid.ContainerRuntime.Test.CloseSummarizerDelayOverrideMs");
         this.closeSummarizerDelayMs =
             closeSummarizerDelayOverride ?? defaultCloseSummarizerDelayMs;
-        this.dirtyContainer =
-            this.attachState !== AttachState.Attached || this.hasPendingMessages();
-        context.updateDirtyContainerState(this.dirtyContainer);
+        // We haven't emitted dirty/saved yet, but this is the baseline so we know to emit when it changes
+        this.lastEmittedDirty = this.computeCurrentDirtyState();
+        context.updateDirtyContainerState(this.lastEmittedDirty);
         if (!this.skipSafetyFlushDuringProcessStack) {
             // Reference Sequence Number may have just changed, and it must be consistent across a batch,
             // so we should flush now to clear the way for the next ops.
@@ -1428,32 +1449,29 @@ export class ContainerRuntime extends TypedEventEmitter {
         if (!this.canSendOps()) {
             return;
         }
-        // We need to temporary clear the dirty flags and disable
-        // dirty state change events to detect whether replaying ops
-        // has any effect.
-        // Save the old state, reset to false, disable event emit
-        const oldState = this.dirtyContainer;
-        this.dirtyContainer = false;
+        // Replaying is an internal operation and we don't want to generate noise while doing it.
+        // So temporarily disable dirty state change events, and save the old state.
+        // When we're done, we'll emit the event if the state changed.
+        const oldState = this.lastEmittedDirty;
         assert(this.emitDirtyDocumentEvent, 0x127 /* "dirty document event not set on replay" */);
         this.emitDirtyDocumentEvent = false;
-        let newState;
         try {
             // Any ID Allocation ops that failed to submit after the pending state was queued need to have
             // the corresponding ranges resubmitted (note this call replaces the typical resubmit flow).
             // Since we don't submit ID Allocation ops when staged, any outstanding ranges would be from
             // before staging mode so we can simply say staged: false.
             this.submitIdAllocationOpIfNeeded({ resubmitOutstandingRanges: true, staged: false });
+            this.scheduleFlush();
             // replay the ops
             this.pendingStateManager.replayPendingStates();
         }
         finally {
-            // Save the new start and restore the old state, re-enable event emit
-            newState = this.dirtyContainer;
-            this.dirtyContainer = oldState;
+            // Restore the old state, re-enable event emit
+            this.lastEmittedDirty = oldState;
             this.emitDirtyDocumentEvent = true;
         }
-        // Officially transition from the old state to the new state.
-        this.updateDocumentDirtyState(newState);
+        // This will emit an event if the state changed relative to before replay
+        this.updateDocumentDirtyState();
     }
     /**
      * Parse an op's type and actual content from given serialized content
@@ -1715,6 +1733,8 @@ export class ContainerRuntime extends TypedEventEmitter {
      * @param groupedBatch - true if these messages are part of a grouped op batch.
      */
     processInboundMessages(messagesWithMetadata, locationInBatch, local, savedOp, runtimeBatch, groupedBatch) {
+        // This message could have been the last pending local (dirtyable) message, in which case we need to update dirty state to "saved"
+        this.updateDocumentDirtyState();
         if (locationInBatch.batchStart) {
             const firstMessage = messagesWithMetadata[0]?.message;
             assert(firstMessage !== undefined, 0xa31 /* Batch must have at least one message */);
@@ -1809,11 +1829,6 @@ export class ContainerRuntime extends TypedEventEmitter {
             message.minimumSequenceNumber = this.deltaManager.minimumSequenceNumber;
         }
         this._processedClientSequenceNumber = message.clientSequenceNumber;
-        // If there are no more pending messages after processing a local message,
-        // the document is no longer dirty.
-        if (!this.hasPendingMessages()) {
-            this.updateDocumentDirtyState(false);
-        }
         // The DeltaManager used to do this, but doesn't anymore as of Loader v2.4
         // Anyone listening to our "op" event would expect the contents to be parsed per this same logic
         if (typeof message.contents === "string" &&
@@ -1835,11 +1850,6 @@ export class ContainerRuntime extends TypedEventEmitter {
      *
      */
     validateAndProcessRuntimeMessages(message, messagesContent, local, savedOp) {
-        // If there are no more pending messages after processing a local message,
-        // the document is no longer dirty.
-        if (!this.hasPendingMessages()) {
-            this.updateDocumentDirtyState(false);
-        }
         // Get the contents without the localOpMetadata because not all message types know about localOpMetadata.
         const contents = messagesContent.map((c) => c.contents);
         switch (message.type) {
@@ -1915,20 +1925,44 @@ export class ContainerRuntime extends TypedEventEmitter {
         if (message.clientId === this.clientId) {
             this.signalTelemetryManager.trackReceivedSignal(envelope, this.mc.logger, this.consecutiveReconnects);
         }
-        if (envelope.address === undefined) {
+        const fullAddress = envelope.address;
+        if (fullAddress === undefined) {
             // No address indicates a container signal message.
             this.emit("signal", transformed, local);
             return;
         }
-        // Due to a mismatch between different layers in terms of
-        // what is the interface of passing signals, we need to adjust
-        // the signal envelope before sending it to the datastores to be processed
-        const envelope2 = {
-            address: envelope.address,
-            contents: transformed.content,
-        };
-        transformed.content = envelope2;
-        this.channelCollection.processSignal(transformed, local);
+        this.routeNonContainerSignal(fullAddress, transformed, local);
+    }
+    routeNonContainerSignal(address, signalMessage, local) {
+        // channelCollection signals are identified by no starting `/` in address.
+        if (!address.startsWith("/")) {
+            // Due to a mismatch between different layers in terms of
+            // what is the interface of passing signals, we need to adjust
+            // the signal envelope before sending it to the datastores to be processed
+            const envelope = {
+                address,
+                contents: signalMessage.content,
+            };
+            signalMessage.content = envelope;
+            this.channelCollection.processSignal(signalMessage, local);
+            return;
+        }
+        const addresses = address.split("/");
+        if (addresses.length > 2 && addresses[1] === "ext") {
+            const id = addresses[2];
+            const entry = this.extensions.get(id);
+            if (entry !== undefined) {
+                entry.extension.processSignal?.(addresses.slice(3), signalMessage, local);
+                return;
+            }
+        }
+        assert(!local, 0xba0 /* No recipient found for local signal */);
+        this.mc.logger.sendTelemetryEvent({
+            eventName: "SignalAddressNotFound",
+            ...tagCodeArtifacts({
+                address,
+            }),
+        });
     }
     /**
      * Flush the current batch of ops to the ordering service for sequencing
@@ -1938,6 +1972,7 @@ export class ContainerRuntime extends TypedEventEmitter {
      * @param resubmitInfo - If defined, indicates this is a resubmission of a batch with the given Batch info needed for resubmit.
      */
     flush(resubmitInfo) {
+        this.flushScheduled = false;
         try {
             assert(!this.batchRunner.running, 0x24c /* "Cannot call `flush()` while manually accumulating a batch (e.g. under orderSequentially) */);
             this.outbox.flush(resubmitInfo);
@@ -1958,7 +1993,6 @@ export class ContainerRuntime extends TypedEventEmitter {
      */
     orderSequentially(callback) {
         let checkpoint;
-        const checkpointDirtyState = this.dirtyContainer;
         // eslint-disable-next-line import/no-deprecated
         let stageControls;
         if (this.mc.config.getBoolean("Fluid.ContainerRuntime.EnableRollback")) {
@@ -1979,10 +2013,7 @@ export class ContainerRuntime extends TypedEventEmitter {
                     // This will throw and close the container if rollback fails
                     try {
                         checkpoint.rollback((message) => this.rollback(message.runtimeOp, message.localOpMetadata));
-                        // reset the dirty state after rollback to what it was before to keep it consistent
-                        if (this.dirtyContainer !== checkpointDirtyState) {
-                            this.updateDocumentDirtyState(checkpointDirtyState);
-                        }
+                        this.updateDocumentDirtyState();
                         stageControls?.discardChanges();
                         stageControls = undefined;
                     }
@@ -2063,12 +2094,6 @@ export class ContainerRuntime extends TypedEventEmitter {
         // container runtime's ability to send ops depend on the actual readonly state of the delta manager.
         return (this.connected && !this.innerDeltaManager.readOnlyInfo.readonly && !this.imminentClosure);
     }
-    /**
-     * Typically ops are batched and later flushed together, but in some cases we want to flush immediately.
-     */
-    currentlyBatching() {
-        return this.flushMode !== FlushMode.Immediate || this.batchRunner.running;
-    }
     getQuorum() {
         return this._quorum;
     }
@@ -2080,36 +2105,17 @@ export class ContainerRuntime extends TypedEventEmitter {
      * either were not sent out to delta stream or were not yet acknowledged.
      */
     get isDirty() {
-        return this.dirtyContainer;
+        // Rather than recomputing the dirty state in this moment,
+        // just regurgitate the last emitted dirty state.
+        return this.lastEmittedDirty;
     }
-    isContainerMessageDirtyable({ type, contents, }) {
-        // Certain container runtime messages should not mark the container dirty such as the old built-in
-        // AgentScheduler and Garbage collector messages.
-        switch (type) {
-            case ContainerMessageType.Attach: {
-                const attachMessage = contents;
-                if (attachMessage.id === agentSchedulerId) {
-                    return false;
-                }
-                break;
-            }
-            case ContainerMessageType.FluidDataStoreOp: {
-                const envelope = contents;
-                if (envelope.address === agentSchedulerId) {
-                    return false;
-                }
-                break;
-            }
-            case ContainerMessageType.IdAllocation:
-            case ContainerMessageType.DocumentSchemaChange:
-            case ContainerMessageType.GC: {
-                return false;
-            }
-            default: {
-                break;
-            }
-        }
-        return true;
+    /**
+     * Returns true if the container is dirty: not attached, or no pending user messages (could be some "non-dirtyable" ones though)
+     */
+    computeCurrentDirtyState() {
+        return (this.attachState !== AttachState.Attached ||
+            this.pendingStateManager.hasPendingUserChanges() ||
+            this.outbox.containsUserChanges());
     }
     /**
      * Submits the signal to be sent to other clients.
@@ -2126,9 +2132,6 @@ export class ContainerRuntime extends TypedEventEmitter {
     submitSignal(type, content, targetClientId) {
         this.verifyNotClosed();
         const envelope = createNewSignalEnvelope(undefined /* address */, type, content);
-        if (targetClientId === undefined) {
-            this.signalTelemetryManager.applyTrackingToBroadcastSignalEnvelope(envelope);
-        }
         this.submitSignalFn(envelope, targetClientId);
     }
     setAttachState(attachState) {
@@ -2139,9 +2142,7 @@ export class ContainerRuntime extends TypedEventEmitter {
             assert(this.attachState === AttachState.Attached, 0x12e /* "Container Context should already be in attached state" */);
             this.emit("attached");
         }
-        if (attachState === AttachState.Attached && !this.hasPendingMessages()) {
-            this.updateDocumentDirtyState(false);
-        }
+        this.updateDocumentDirtyState();
         this.channelCollection.setAttachState(attachState);
     }
     /**
@@ -2709,18 +2710,20 @@ export class ContainerRuntime extends TypedEventEmitter {
     hasPendingMessages() {
         return this.pendingMessagesCount !== 0;
     }
-    updateDocumentDirtyState(dirty) {
-        if (this.attachState === AttachState.Attached) {
-            // Other way is not true = see this.isContainerMessageDirtyable()
-            assert(!dirty || this.hasPendingMessages(), 0x3d3 /* if doc is dirty, there has to be pending ops */);
-        }
-        else {
-            assert(dirty, 0x3d2 /* Non-attached container is dirty */);
-        }
-        if (this.dirtyContainer === dirty) {
+    /**
+     * Emit "dirty" or "saved" event based on the current dirty state of the document.
+     * This must be called every time the states underlying the dirty state change.
+     *
+     * @privateRemarks - It's helpful to think of this as an event handler registered
+     * for hypothetical "changed" events for PendingStateManager, Outbox, and Container Attach machinery.
+     * But those events don't exist so we manually call this wherever we know those changes happen.
+     */
+    updateDocumentDirtyState() {
+        const dirty = this.computeCurrentDirtyState();
+        if (this.lastEmittedDirty === dirty) {
             return;
         }
-        this.dirtyContainer = dirty;
+        this.lastEmittedDirty = dirty;
         if (this.emitDirtyDocumentEvent) {
             this.emit(dirty ? "dirty" : "saved");
         }
@@ -2818,14 +2821,7 @@ export class ContainerRuntime extends TypedEventEmitter {
             else {
                 this.outbox.submit(message);
             }
-            // Note: Technically, the system "always" batches - if this case is true we'll just have a single-message batch.
-            const flushImmediatelyOnSubmit = !this.currentlyBatching();
-            if (flushImmediatelyOnSubmit) {
-                this.flush();
-            }
-            else {
-                this.scheduleFlush();
-            }
+            this.scheduleFlush();
         }
         catch (error) {
             const dpe = DataProcessingError.wrapIfUnrecognized(error, "ContainerRuntime.submit", {
@@ -2834,27 +2830,26 @@ export class ContainerRuntime extends TypedEventEmitter {
             this.closeFn(dpe);
             throw dpe;
         }
-        if (this.isContainerMessageDirtyable(containerRuntimeMessage)) {
-            this.updateDocumentDirtyState(true);
-        }
+        this.updateDocumentDirtyState();
     }
     scheduleFlush() {
-        if (this.flushTaskExists) {
+        if (this.flushScheduled) {
             return;
         }
-        this.flushTaskExists = true;
-        // TODO: hoist this out of the function scope to save unnecessary allocations
-        // eslint-disable-next-line unicorn/consistent-function-scoping -- Separate `flush` method already exists in outer scope
-        const flush = () => {
-            this.flushTaskExists = false;
-            this.flush();
-        };
+        this.flushScheduled = true;
         switch (this.flushMode) {
+            case FlushMode.Immediate: {
+                // When in Immediate flush mode, flush immediately unless we are intentionally batching multiple ops (e.g. via orderSequentially)
+                if (!this.batchRunner.running) {
+                    this.flush();
+                }
+                break;
+            }
             case FlushMode.TurnBased: {
                 // When in TurnBased flush mode the runtime will buffer operations in the current turn and send them as a single
                 // batch at the end of the turn
-                // eslint-disable-next-line @typescript-eslint/no-floating-promises
-                Promise.resolve().then(flush);
+                // eslint-disable-next-line @typescript-eslint/no-floating-promises -- Container will close if flush throws
+                Promise.resolve().then(() => this.flush());
                 break;
             }
             // FlushModeExperimental is experimental and not exposed directly in the runtime APIs
@@ -2862,12 +2857,11 @@ export class ContainerRuntime extends TypedEventEmitter {
                 // When in Async flush mode, the runtime will accumulate all operations across JS turns and send them as a single
                 // batch when all micro-tasks are complete.
                 // Compared to TurnBased, this flush mode will capture more ops into the same batch.
-                setTimeout(flush, 0);
+                setTimeout(() => this.flush(), 0);
                 break;
             }
             default: {
-                assert(this.batchRunner.running, 0x587 /* Unreachable unless manually accumulating a batch */);
-                break;
+                fail(0x587 /* Unreachable unless manually accumulating a batch */);
             }
         }
     }
@@ -3138,6 +3132,29 @@ export class ContainerRuntime extends TypedEventEmitter {
             return this.summaryManager.enqueueSummarize(options);
         }
     }
+    acquireExtension(id, factory, ...useContext) {
+        let entry = this.extensions.get(id);
+        if (entry === undefined) {
+            const runtime = {
+                isConnected: () => this.connected,
+                getClientId: () => this.clientId,
+                events: this.lazyEventsForExtensions.value,
+                logger: this.baseLogger,
+                submitAddressedSignal: (addressChain, message) => {
+                    this.submitExtensionSignal(id, addressChain, message);
+                },
+                getQuorum: this.getQuorum.bind(this),
+                getAudience: this.getAudience.bind(this),
+            };
+            entry = new factory(runtime, ...useContext);
+            this.extensions.set(id, entry);
+        }
+        else {
+            assert(entry instanceof factory, 0xba1 /* Extension entry is not of the expected type */);
+            entry.extension.onNewUse(...useContext);
+        }
+        return entry.interface;
+    }
     get groupedBatchingEnabled() {
         return this.sessionSchema.opGroupingEnabled === true;
     }
@@ -3149,4 +3166,33 @@ export function createNewSignalEnvelope(address, type, content) {
     };
     return newEnvelope;
 }
+export function isContainerMessageDirtyable({ type, contents, }) {
+    // Certain container runtime messages should not mark the container dirty such as the old built-in
+    // AgentScheduler and Garbage collector messages.
+    switch (type) {
+        case ContainerMessageType.Attach: {
+            const attachMessage = contents;
+            if (attachMessage.id === agentSchedulerId) {
+                return false;
+            }
+            break;
+        }
+        case ContainerMessageType.FluidDataStoreOp: {
+            const envelope = contents;
+            if (envelope.address === agentSchedulerId) {
+                return false;
+            }
+            break;
+        }
+        case ContainerMessageType.IdAllocation:
+        case ContainerMessageType.DocumentSchemaChange:
+        case ContainerMessageType.GC: {
+            return false;
+        }
+        default: {
+            break;
+        }
+    }
+    return true;
+}
 //# sourceMappingURL=containerRuntime.js.map