@fluidframework/datastore 2.0.0-dev-rc.1.0.0.228517 → 2.0.0-dev-rc.2.0.0.245554

package/dist/dataStoreRuntime.js

@@ -14,10 +14,10 @@ const protocol_definitions_1 = require("@fluidframework/protocol-definitions");
 const runtime_definitions_1 = require("@fluidframework/runtime-definitions");
 const runtime_utils_1 = require("@fluidframework/runtime-utils");
 const uuid_1 = require("uuid");
-const channelContext_1 = require("./channelContext");
-const localChannelContext_1 = require("./localChannelContext");
-const remoteChannelContext_1 = require("./remoteChannelContext");
-const fluidHandle_1 = require("./fluidHandle");
+const channelContext_js_1 = require("./channelContext.js");
+const localChannelContext_js_1 = require("./localChannelContext.js");
+const remoteChannelContext_js_1 = require("./remoteChannelContext.js");
+const fluidHandle_js_1 = require("./fluidHandle.js");
 /**
  * @alpha
  */
@@ -138,7 +138,7 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
                 // container from snapshot where we load detached container from a snapshot, isLocalDataStore would be
                 // true. In this case create a RehydratedLocalChannelContext.
                 if (dataStoreContext.isLocalDataStore) {
-                    channelContext = new localChannelContext_1.RehydratedLocalChannelContext(path, this.sharedObjectRegistry, this, this.dataStoreContext, this.dataStoreContext.storage, this.logger, (content, localOpMetadata) => this.submitChannelOp(path, content, localOpMetadata), (address) => this.setChannelDirty(address), (srcHandle, outboundHandle) => this.addedGCOutboundReference(srcHandle, outboundHandle), tree.trees[path]);
+                    channelContext = new localChannelContext_js_1.RehydratedLocalChannelContext(path, this.sharedObjectRegistry, this, this.dataStoreContext, this.dataStoreContext.storage, this.logger, (content, localOpMetadata) => this.submitChannelOp(path, content, localOpMetadata), (address) => this.setChannelDirty(address), (srcHandle, outboundHandle) => this.addedGCOutboundReference(srcHandle, outboundHandle), tree.trees[path]);
                     // This is the case of rehydrating a detached container from snapshot. Now due to delay loading of
                     // data store, if the data store is loaded after the container is attached, then we missed making
                     // the channel visible. So do it now. Otherwise, add it to local channel context queue, so
@@ -151,14 +151,14 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
                     }
                 }
                 else {
-                    channelContext = new remoteChannelContext_1.RemoteChannelContext(this, dataStoreContext, dataStoreContext.storage, (content, localOpMetadata) => this.submitChannelOp(path, content, localOpMetadata), (address) => this.setChannelDirty(address), (srcHandle, outboundHandle) => this.addedGCOutboundReference(srcHandle, outboundHandle), path, tree.trees[path], this.sharedObjectRegistry, undefined /* extraBlobs */, this.dataStoreContext.getCreateChildSummarizerNodeFn(path, {
+                    channelContext = new remoteChannelContext_js_1.RemoteChannelContext(this, dataStoreContext, dataStoreContext.storage, (content, localOpMetadata) => this.submitChannelOp(path, content, localOpMetadata), (address) => this.setChannelDirty(address), (srcHandle, outboundHandle) => this.addedGCOutboundReference(srcHandle, outboundHandle), path, tree.trees[path], this.sharedObjectRegistry, undefined /* extraBlobs */, this.dataStoreContext.getCreateChildSummarizerNodeFn(path, {
                         type: runtime_definitions_1.CreateSummarizerNodeSource.FromSummary,
                     }));
                 }
                 this.contexts.set(path, channelContext);
             });
         }
-        this.entryPoint = new fluidHandle_1.FluidObjectHandle(new core_utils_1.LazyPromise(async () => provideEntryPoint(this)), "", this.objectsRoutingContext);
+        this.entryPoint = new fluidHandle_js_1.FluidObjectHandle(new core_utils_1.LazyPromise(async () => provideEntryPoint(this)), "", this.objectsRoutingContext);
         this.attachListener();
         this._attachState = dataStoreContext.attachState;
         /**
@@ -233,6 +233,20 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
         }
         return context.getChannel();
     }
+    /**
+     * Validate user provided channel ID
+     * Channel ID has limitations. "/" is not allowed as IDs in storage can not have slashes - we parse tree paths and use "/" as separator.
+     * IDs cannot start with "_" as it could result in collision of IDs with auto-assigned (by FF) short IDs.
+     * @param id - channel ID.
+     */
+    validateChannelId(id) {
+        if (id.includes("/")) {
+            throw new telemetry_utils_1.UsageError(`Id cannot contain slashes: ${id}`);
+        }
+        if (id.startsWith("_")) {
+            throw new telemetry_utils_1.UsageError(`Id cannot start with underscore: ${id}`);
+        }
+    }
     /**
      * Api which allows caller to create the channel first and then add it to the runtime.
      * The channel type should be present in the registry, otherwise the runtime would reject
@@ -242,9 +256,7 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
      */
     addChannel(channel) {
         const id = channel.id;
-        if (id.includes("/")) {
-            throw new telemetry_utils_1.UsageError(`Id cannot contain slashes: ${id}`);
-        }
+        this.validateChannelId(id);
         this.verifyNotClosed();
         (0, core_utils_1.assert)(!this.contexts.has(id), 0x865 /* addChannel() with existing ID */);
         const type = channel.attributes.type;
@@ -256,9 +268,30 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
         // Channels (DDS) should not be created in summarizer client.
         this.identifyLocalChangeInSummarizer("DDSCreatedInSummarizer", id, type);
     }
-    createChannel(id = (0, uuid_1.v4)(), type) {
-        if (id.includes("/")) {
-            throw new telemetry_utils_1.UsageError(`Id cannot contain slashes: ${id}`);
+    createChannel(idArg, type) {
+        let id;
+        if (idArg !== undefined) {
+            id = idArg;
+            this.validateChannelId(id);
+        }
+        else {
+            // We use three non-overlapping namespaces:
+            // - detached state: even numbers
+            // - attached state: odd numbers
+            // - uuids
+            // In first two cases we will encode result as strings in more compact form, with leading underscore,
+            // to ensure no overlap with user-provided DDS names (see validateChannelId())
+            if (this.visibilityState !== runtime_definitions_1.VisibilityState.GloballyVisible) {
+                // container is detached, only one client observes content, no way to hit collisions with other clients.
+                id = (0, runtime_utils_1.encodeCompactIdToString)(2 * this.contexts.size, "_");
+            }
+            else {
+                // Due to back-compat, we could not depend yet on generateDocumentUniqueId() being there.
+                // We can remove the need to leverage uuid() as fall-back in couple releases.
+                const res = this.dataStoreContext.containerRuntime.generateDocumentUniqueId?.() ?? (0, uuid_1.v4)();
+                id = typeof res === "number" ? (0, runtime_utils_1.encodeCompactIdToString)(2 * res + 1, "_") : res;
+            }
+            (0, core_utils_1.assert)(!id.includes("/"), 0x8fc /* slash */);
         }
         this.verifyNotClosed();
         (0, core_utils_1.assert)(!this.contexts.has(id), 0x179 /* "createChannel() with existing ID" */);
@@ -275,7 +308,7 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
     }
     createChannelContext(channel) {
         this.notBoundedChannelContextSet.add(channel.id);
-        const context = new localChannelContext_1.LocalChannelContext(channel, this, this.dataStoreContext, this.dataStoreContext.storage, this.logger, (content, localOpMetadata) => this.submitChannelOp(channel.id, content, localOpMetadata), (address) => this.setChannelDirty(address), (srcHandle, outboundHandle) => this.addedGCOutboundReference(srcHandle, outboundHandle));
+        const context = new localChannelContext_js_1.LocalChannelContext(channel, this, this.dataStoreContext, this.dataStoreContext.storage, this.logger, (content, localOpMetadata) => this.submitChannelOp(channel.id, content, localOpMetadata), (address) => this.setChannelDirty(address), (srcHandle, outboundHandle) => this.addedGCOutboundReference(srcHandle, outboundHandle));
         this.contexts.set(channel.id, context);
     }
     /**
@@ -288,7 +321,7 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
         this.notBoundedChannelContextSet.delete(channel.id);
         // If our data store is attached, then attach the channel.
         if (this.isAttached) {
-            this.attachChannel(channel);
+            this.makeChannelLocallyVisible(channel);
             return;
         }
         /**
@@ -360,7 +393,7 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
     createRemoteChannelContext(attachMessage, summarizerNodeParams) {
         const flatBlobs = new Map();
         const snapshotTree = (0, driver_utils_1.buildSnapshotTree)(attachMessage.snapshot.entries, flatBlobs);
-        return new remoteChannelContext_1.RemoteChannelContext(this, this.dataStoreContext, this.dataStoreContext.storage, (content, localContentMetadata) => this.submitChannelOp(attachMessage.id, content, localContentMetadata), (address) => this.setChannelDirty(address), (srcHandle, outboundHandle) => this.addedGCOutboundReference(srcHandle, outboundHandle), attachMessage.id, snapshotTree, this.sharedObjectRegistry, flatBlobs, this.dataStoreContext.getCreateChildSummarizerNodeFn(attachMessage.id, summarizerNodeParams), attachMessage.type);
+        return new remoteChannelContext_js_1.RemoteChannelContext(this, this.dataStoreContext, this.dataStoreContext.storage, (content, localContentMetadata) => this.submitChannelOp(attachMessage.id, content, localContentMetadata), (address) => this.setChannelDirty(address), (srcHandle, outboundHandle) => this.addedGCOutboundReference(srcHandle, outboundHandle), attachMessage.id, snapshotTree, this.sharedObjectRegistry, flatBlobs, this.dataStoreContext.getCreateChildSummarizerNodeFn(attachMessage.id, summarizerNodeParams), attachMessage.type);
     }
     process(message, local, localOpMetadata) {
         this.verifyNotClosed();
@@ -370,6 +403,12 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
                 case DataStoreMessageType.Attach: {
                     const attachMessage = message.contents;
                     const id = attachMessage.id;
+                    // We need to process the GC Data for both local and remote attach messages
+                    (0, runtime_utils_1.processAttachMessageGCData)(attachMessage.snapshot, (nodeId, toPath) => {
+                        // Note: nodeId will be "/" unless and until we support sub-DDS GC Nodes
+                        const fromPath = `/${this.id}/${id}${nodeId === "/" ? "" : nodeId}`;
+                        this.dataStoreContext.addedGCOutboundRoute?.(fromPath, toPath);
+                    });
                     // If a non-local operation then go and create the object
                     // Otherwise mark it as officially attached.
                     if (local) {
@@ -526,6 +565,45 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
         return summaryBuilder.getSummaryTree();
     }
     getAttachSummary(telemetryContext) {
+        const summaryBuilder = new runtime_utils_1.SummaryTreeBuilder();
+        this.visitLocalBoundContextsDuringAttach((contextId, context) => {
+            let summaryTree;
+            if (context.isLoaded) {
+                const contextSummary = context.getAttachSummary(telemetryContext);
+                (0, core_utils_1.assert)(contextSummary.summary.type === protocol_definitions_1.SummaryType.Tree, 0x180 /* "getAttachSummary should always return a tree" */);
+                summaryTree = { stats: contextSummary.stats, summary: contextSummary.summary };
+            }
+            else {
+                // If this channel is not yet loaded, then there should be no changes in the snapshot from which
+                // it was created as it is detached container. So just use the previous snapshot.
+                (0, core_utils_1.assert)(!!this.dataStoreContext.baseSnapshot, 0x181 /* "BaseSnapshot should be there as detached container loaded from snapshot" */);
+                summaryTree = (0, runtime_utils_1.convertSnapshotTreeToSummaryTree)(this.dataStoreContext.baseSnapshot.trees[contextId]);
+            }
+            summaryBuilder.addWithStats(contextId, summaryTree);
+        });
+        return summaryBuilder.getSummaryTree();
+    }
+    /**
+     * Get the GC Data for the initial state being attached so remote clients can learn of this DataStore's outbound routes
+     */
+    getAttachGCData(telemetryContext) {
+        const gcDataBuilder = new runtime_utils_1.GCDataBuilder();
+        this.visitLocalBoundContextsDuringAttach((contextId, context) => {
+            if (context.isLoaded) {
+                const contextGCData = context.getAttachGCData(telemetryContext);
+                // Incorporate the GC Data for this context
+                gcDataBuilder.prefixAndAddNodes(contextId, contextGCData.gcNodes);
+            }
+            // else: Rehydrating detached container case. GC doesn't run until the container is attached, so nothing to do here.
+        });
+        this.updateGCNodes(gcDataBuilder);
+        return gcDataBuilder.getGCData();
+    }
+    /**
+     * Helper method for preparing to attach this dataStore.
+     * Runs the callback for each bound context to incorporate its data however the caller specifies
+     */
+    visitLocalBoundContextsDuringAttach(visitor) {
         /**
          * back-compat 0.59.1000 - getAttachSummary() is called when making a data store globally visible (previously
          * attaching state). Ideally, attachGraph() should have already be called making it locally visible. However,
@@ -544,29 +622,14 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
         // assert(this.visibilityState === VisibilityState.LocallyVisible,
         //  "The data store should be locally visible when generating attach summary",
         // );
-        const summaryBuilder = new runtime_utils_1.SummaryTreeBuilder();
-        // Craft the .attributes file for each shared object
         for (const [contextId, context] of this.contexts) {
-            if (!(context instanceof localChannelContext_1.LocalChannelContextBase)) {
+            if (!(context instanceof localChannelContext_js_1.LocalChannelContextBase)) {
                 throw new telemetry_utils_1.LoggingError("Should only be called with local channel handles");
             }
             if (!this.notBoundedChannelContextSet.has(contextId)) {
-                let summaryTree;
-                if (context.isLoaded) {
-                    const contextSummary = context.getAttachSummary(telemetryContext);
-                    (0, core_utils_1.assert)(contextSummary.summary.type === protocol_definitions_1.SummaryType.Tree, 0x180 /* "getAttachSummary should always return a tree" */);
-                    summaryTree = { stats: contextSummary.stats, summary: contextSummary.summary };
-                }
-                else {
-                    // If this channel is not yet loaded, then there should be no changes in the snapshot from which
-                    // it was created as it is detached container. So just use the previous snapshot.
-                    (0, core_utils_1.assert)(!!this.dataStoreContext.baseSnapshot, 0x181 /* "BaseSnapshot should be there as detached container loaded from snapshot" */);
-                    summaryTree = (0, runtime_utils_1.convertSnapshotTreeToSummaryTree)(this.dataStoreContext.baseSnapshot.trees[contextId]);
-                }
-                summaryBuilder.addWithStats(contextId, summaryTree);
+                visitor(contextId, context);
             }
         }
-        return summaryBuilder.getSummaryTree();
     }
     submitMessage(type, content, localOpMetadata) {
         this.submit(type, content, localOpMetadata);
@@ -588,9 +651,10 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
         return this.deferredAttached.promise;
     }
     /**
-     * Attach channel should only be called after the data store has been attached
+     * Assuming this DataStore is already attached, this will make the given channel locally visible
+     * by submitting its attach op.
      */
-    attachChannel(channel) {
+    makeChannelLocallyVisible(channel) {
         this.verifyNotClosed();
         // If this handle is already attached no need to attach again.
         if (channel.handle.isAttached) {
@@ -599,7 +663,10 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
         channel.handle.attachGraph();
         (0, core_utils_1.assert)(this.isAttached, 0x182 /* "Data store should be attached to attach the channel." */);
         (0, core_utils_1.assert)(this.visibilityState === runtime_definitions_1.VisibilityState.GloballyVisible, 0x2d0 /* "Data store should be globally visible to attach channels." */);
-        const summarizeResult = (0, channelContext_1.summarizeChannel)(channel, true /* fullTree */, false /* trackState */);
+        const summarizeResult = (0, channelContext_js_1.summarizeChannel)(channel, true /* fullTree */, false /* trackState */);
+        // We need to include the channel's GC Data so remote clients can learn of this channel's outbound routes
+        const gcData = channel.getGCData(/* fullGC: */ true);
+        (0, runtime_utils_1.addBlobToSummary)(summarizeResult, runtime_definitions_1.gcDataBlobKey, JSON.stringify(gcData));
         // Attach message needs the summary in ITree format. Convert the ISummaryTree into an ITree.
         const snapshot = (0, runtime_utils_1.convertSummaryTreeToITree)(summarizeResult.summary);
         const message = {
@@ -709,33 +776,15 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
     }
     attachListener() {
         this.setMaxListeners(Number.MAX_SAFE_INTEGER);
-        this.dataStoreContext.once("attaching", () => {
-            /**
-             * back-compat 0.59.1000 - Ideally, attachGraph() should have already been called making the data store
-             * locally visible. However, before visibility state was added, this may not have been the case and data
-             * store can move to "attaching" state in 2 scenarios:
-             * 1) Before attachGraph() is called - When a data store is created and bound in an attached container.
-             * 2) After attachGraph() is called - When a detached container is attached.
-             *
-             * The basic idea is that all local object should become locally visible before they are globally visible.
-             */
-            this.attachGraph();
-            this._attachState = container_definitions_1.AttachState.Attaching;
-            (0, core_utils_1.assert)(this.visibilityState === runtime_definitions_1.VisibilityState.LocallyVisible, 0x2d1 /* "Data store should be locally visible before it can become globally visible." */);
-            // Mark the data store globally visible and make its child channels visible as well.
-            this.visibilityState = runtime_definitions_1.VisibilityState.GloballyVisible;
-            this.localChannelContextQueue.forEach((channel) => {
-                channel.makeVisible();
-            });
-            this.localChannelContextQueue.clear();
-            // This promise resolution will be moved to attached event once we fix the scheduler.
-            this.deferredAttached.resolve();
-            this.emit("attaching");
+        // back-compat, to be removed in the future.
+        // Added in "2.0.0-rc.2.0.0" timeframe.
+        this.dataStoreContext.once?.("attaching", () => {
+            this.setAttachState(container_definitions_1.AttachState.Attaching);
         });
-        this.dataStoreContext.once("attached", () => {
-            (0, core_utils_1.assert)(this.visibilityState === runtime_definitions_1.VisibilityState.GloballyVisible, 0x2d2 /* "Data store should be globally visible when its attached." */);
-            this._attachState = container_definitions_1.AttachState.Attached;
-            this.emit("attached");
+        // back-compat, to be removed in the future.
+        // Added in "2.0.0-rc.2.0.0" timeframe.
+        this.dataStoreContext.once?.("attached", () => {
+            this.setAttachState(container_definitions_1.AttachState.Attached);
         });
     }
     verifyNotClosed() {
@@ -767,6 +816,40 @@ class FluidDataStoreRuntime extends client_utils_1.TypedEventEmitter {
         });
         this.localChangesTelemetryCount--;
     }
+    setAttachState(attachState) {
+        switch (attachState) {
+            case container_definitions_1.AttachState.Attaching:
+                /**
+                 * back-compat 0.59.1000 - Ideally, attachGraph() should have already been called making the data store
+                 * locally visible. However, before visibility state was added, this may not have been the case and data
+                 * store can move to "attaching" state in 2 scenarios:
+                 * 1) Before attachGraph() is called - When a data store is created and bound in an attached container.
+                 * 2) After attachGraph() is called - When a detached container is attached.
+                 *
+                 * The basic idea is that all local object should become locally visible before they are globally visible.
+                 */
+                this.attachGraph();
+                this._attachState = container_definitions_1.AttachState.Attaching;
+                (0, core_utils_1.assert)(this.visibilityState === runtime_definitions_1.VisibilityState.LocallyVisible, 0x2d1 /* "Data store should be locally visible before it can become globally visible." */);
+                // Mark the data store globally visible and make its child channels visible as well.
+                this.visibilityState = runtime_definitions_1.VisibilityState.GloballyVisible;
+                this.localChannelContextQueue.forEach((channel) => {
+                    channel.makeVisible();
+                });
+                this.localChannelContextQueue.clear();
+                // This promise resolution will be moved to attached event once we fix the scheduler.
+                this.deferredAttached.resolve();
+                this.emit("attaching");
+                break;
+            case container_definitions_1.AttachState.Attached:
+                (0, core_utils_1.assert)(this.visibilityState === runtime_definitions_1.VisibilityState.GloballyVisible, 0x2d2 /* "Data store should be globally visible when its attached." */);
+                this._attachState = container_definitions_1.AttachState.Attached;
+                this.emit("attached");
+                break;
+            default:
+                (0, core_utils_1.unreachableCase)(attachState, "unreached");
+        }
+    }
 }
 exports.FluidDataStoreRuntime = FluidDataStoreRuntime;
 /**