@fluidframework/container-runtime 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.224419

package/lib/gc/gcHelpers.d.mts

@@ -0,0 +1,71 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ISnapshotTree } from "@fluidframework/protocol-definitions";
+import { IGarbageCollectionData, IGarbageCollectionDetailsBase } from "@fluidframework/runtime-definitions";
+import { GCFeatureMatrix, GCVersion, IGCMetadata } from "./gcDefinitions.mjs";
+import { IGarbageCollectionSnapshotData, IGarbageCollectionState } from "./gcSummaryDefinitions.mjs";
+export declare function getGCVersion(metadata?: IGCMetadata): GCVersion;
+/**
+ * Indicates whether Sweep is allowed for this document based on the persisted GC Feature Matrix and current gcGeneration.
+ * This applies to the entire Sweep Phase the same - both Tombstone Enforcement (i.e. should loading a Tombstone fail?) and Deletion.
+ *
+ * In order to protect old documents that were created at a time when known bugs exist that violate GC's invariants
+ * such that enforcing GC Sweep would cause legitimate data loss, the container author may increment the generation value for Sweep
+ * such that containers created with a different value will not be subjected to GC Sweep.
+ *
+ * If no generation is provided, Sweep will be enabled for all documents.
+ *
+ * For backwards compatibility, the current generation value is also compared against the persisted gcTombstoneGeneration if present.
+ *
+ * @param featureMatrix - The GC Feature Matrix, containing the persisted generation value
+ * @param currentGeneration - The current app-provided gcGeneration value
+ * @returns true if GC Sweep should be allowed for this document
+ */
+export declare function shouldAllowGcSweep(featureMatrix: GCFeatureMatrix, currentGeneration: number | undefined): boolean;
+/**
+ * Sorts the given GC state as per the id of the GC nodes. It also sorts the outbound routes array of each node.
+ */
+export declare function generateSortedGCState(gcState: IGarbageCollectionState): IGarbageCollectionState;
+/**
+ * Concatenates the given GC states and returns the concatenated GC state.
+ */
+export declare function concatGarbageCollectionStates(gcState1: IGarbageCollectionState, gcState2: IGarbageCollectionState): IGarbageCollectionState;
+/**
+ * Helper function that clones the GC data.
+ * @param gcData - The GC data to clone.
+ * @returns a clone of the given GC data.
+ */
+export declare function cloneGCData(gcData: IGarbageCollectionData): IGarbageCollectionData;
+/**
+ * Concatenates the given GC data and returns the concatenated GC data.
+ */
+export declare function concatGarbageCollectionData(gcData1: IGarbageCollectionData, gcData2: IGarbageCollectionData): IGarbageCollectionData;
+/**
+ * Gets the base garbage collection state from the given snapshot tree. It contains GC state, deleted nodes and
+ * tombstones. The GC state may be written into multiple blobs. Merge the GC state from all such blobs into one.
+ */
+export declare function getGCDataFromSnapshot(gcSnapshotTree: ISnapshotTree, readAndParseBlob: <T>(id: string) => Promise<T>): Promise<IGarbageCollectionSnapshotData>;
+/**
+ * Helper function that unpacks the GC details of the children from a given node's GC details.
+ * @param gcDetails - The GC details of a node.
+ * @returns A map of GC details of each children of the the given node.
+ */
+export declare function unpackChildNodesGCDetails(gcDetails: IGarbageCollectionDetailsBase): Map<string, IGarbageCollectionDetailsBase>;
+/**
+ * Trims the leading and trailing slashes from the given string.
+ * @param str - A string that may contain leading and / or trailing slashes.
+ * @returns A new string without leading and trailing slashes.
+ */
+export declare function trimLeadingAndTrailingSlashes(str: string): string;
+/**
+ * Utility to implement compat behaviors given an unknown message type
+ * The parameters are typed to support compile-time enforcement of handling all known types/behaviors
+ *
+ * @param _unknownGCMessageType - Typed as never to ensure all known types have been
+ * handled before calling this function (e.g. in a switch statement).
+ * @param compatBehavior - Typed redundantly with CompatModeBehavior to ensure handling is added when updating that type
+ */
+export declare function compatBehaviorAllowsGCMessageType(_unknownGCMessageType: never, compatBehavior: "Ignore" | "FailToProcess" | undefined): boolean;
+//# sourceMappingURL=gcHelpers.d.ts.map

package/lib/gc/gcHelpers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcHelpers.d.ts","sourceRoot":"","sources":["../../src/gc/gcHelpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;OAGI,EAAE,aAAa,EAAE,MAAM,sCAAsC;OAC7D,EAIN,sBAAsB,EACtB,6BAA6B,EAC7B,MAAM,qCAAqC;OACrC,EAAE,eAAe,EAAE,SAAS,EAAE,WAAW,EAAE;OAC3C,EAEN,8BAA8B,EAC9B,uBAAuB,EACvB;AAED,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,SAAS,CAM9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CACjC,aAAa,EAAE,eAAe,EAC9B,iBAAiB,EAAE,MAAM,GAAG,SAAS,GACnC,OAAO,CAUT;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CAS/F;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC5C,QAAQ,EAAE,uBAAuB,EACjC,QAAQ,EAAE,uBAAuB,GAC/B,uBAAuB,CAsCzB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAQlF;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,sBAAsB,0BAY/B;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAC1C,cAAc,EAAE,aAAa,EAC7B,gBAAgB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,8BAA8B,CAAC,CAgCzC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,6BAA6B,8CA0DjF;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,UAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAChD,qBAAqB,EAAE,KAAK,EAC5B,cAAc,EAAE,QAAQ,GAAG,eAAe,GAAG,SAAS,GACpD,OAAO,CAGT"}

package/lib/gc/gcHelpers.mjs

@@ -0,0 +1,222 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { assert } from "@fluidframework/core-utils";
+import { gcBlobPrefix, gcDeletedBlobKey, gcTombstoneBlobKey, } from "@fluidframework/runtime-definitions";
+export function getGCVersion(metadata) {
+    if (!metadata) {
+        // Force to 0/disallowed in prior versions
+        return 0;
+    }
+    return metadata.gcFeature ?? 0;
+}
+/**
+ * Indicates whether Sweep is allowed for this document based on the persisted GC Feature Matrix and current gcGeneration.
+ * This applies to the entire Sweep Phase the same - both Tombstone Enforcement (i.e. should loading a Tombstone fail?) and Deletion.
+ *
+ * In order to protect old documents that were created at a time when known bugs exist that violate GC's invariants
+ * such that enforcing GC Sweep would cause legitimate data loss, the container author may increment the generation value for Sweep
+ * such that containers created with a different value will not be subjected to GC Sweep.
+ *
+ * If no generation is provided, Sweep will be enabled for all documents.
+ *
+ * For backwards compatibility, the current generation value is also compared against the persisted gcTombstoneGeneration if present.
+ *
+ * @param featureMatrix - The GC Feature Matrix, containing the persisted generation value
+ * @param currentGeneration - The current app-provided gcGeneration value
+ * @returns true if GC Sweep should be allowed for this document
+ */
+export function shouldAllowGcSweep(featureMatrix, currentGeneration) {
+    // If no Generation value is provided for this session, default to true
+    if (currentGeneration === undefined) {
+        return true;
+    }
+    // tombstoneGeneration is the predecessor and needs to be supported for back-compat reasons
+    const targetGeneration = featureMatrix.tombstoneGeneration ?? featureMatrix.gcGeneration;
+    return currentGeneration === targetGeneration;
+}
+/**
+ * Sorts the given GC state as per the id of the GC nodes. It also sorts the outbound routes array of each node.
+ */
+export function generateSortedGCState(gcState) {
+    const sortableArray = Object.entries(gcState.gcNodes);
+    sortableArray.sort(([a], [b]) => a.localeCompare(b));
+    const sortedGCState = { gcNodes: {} };
+    for (const [nodeId, nodeData] of sortableArray) {
+        nodeData.outboundRoutes.sort();
+        sortedGCState.gcNodes[nodeId] = nodeData;
+    }
+    return sortedGCState;
+}
+/**
+ * Concatenates the given GC states and returns the concatenated GC state.
+ */
+export function concatGarbageCollectionStates(gcState1, gcState2) {
+    const combinedGCNodes = {};
+    for (const [nodeId, nodeData] of Object.entries(gcState1.gcNodes)) {
+        combinedGCNodes[nodeId] = {
+            outboundRoutes: Array.from(nodeData.outboundRoutes),
+            unreferencedTimestampMs: nodeData.unreferencedTimestampMs,
+        };
+    }
+    for (const [nodeId, nodeData] of Object.entries(gcState2.gcNodes)) {
+        let combineNodeData = combinedGCNodes[nodeId];
+        if (combineNodeData === undefined) {
+            combineNodeData = {
+                outboundRoutes: Array.from(nodeData.outboundRoutes),
+                unreferencedTimestampMs: nodeData.unreferencedTimestampMs,
+            };
+        }
+        else {
+            // Validate that same node doesn't have different unreferenced timestamp.
+            if (nodeData.unreferencedTimestampMs !== undefined &&
+                combineNodeData.unreferencedTimestampMs !== undefined) {
+                assert(nodeData.unreferencedTimestampMs === combineNodeData.unreferencedTimestampMs, 0x5d7 /* Two entries for the same GC node with different unreferenced timestamp */);
+            }
+            combineNodeData = {
+                outboundRoutes: [
+                    ...new Set([...nodeData.outboundRoutes, ...combineNodeData.outboundRoutes]),
+                ],
+                unreferencedTimestampMs: nodeData.unreferencedTimestampMs ?? combineNodeData.unreferencedTimestampMs,
+            };
+        }
+        combinedGCNodes[nodeId] = combineNodeData;
+    }
+    return { gcNodes: combinedGCNodes };
+}
+/**
+ * Helper function that clones the GC data.
+ * @param gcData - The GC data to clone.
+ * @returns a clone of the given GC data.
+ */
+export function cloneGCData(gcData) {
+    const clonedGCNodes = {};
+    for (const [id, outboundRoutes] of Object.entries(gcData.gcNodes)) {
+        clonedGCNodes[id] = Array.from(outboundRoutes);
+    }
+    return {
+        gcNodes: clonedGCNodes,
+    };
+}
+/**
+ * Concatenates the given GC data and returns the concatenated GC data.
+ */
+export function concatGarbageCollectionData(gcData1, gcData2) {
+    const combinedGCData = cloneGCData(gcData1);
+    for (const [id, routes] of Object.entries(gcData2.gcNodes)) {
+        if (combinedGCData.gcNodes[id] === undefined) {
+            combinedGCData.gcNodes[id] = Array.from(routes);
+        }
+        else {
+            const combinedRoutes = [...routes, ...combinedGCData.gcNodes[id]];
+            combinedGCData.gcNodes[id] = [...new Set(combinedRoutes)];
+        }
+    }
+    return combinedGCData;
+}
+/**
+ * Gets the base garbage collection state from the given snapshot tree. It contains GC state, deleted nodes and
+ * tombstones. The GC state may be written into multiple blobs. Merge the GC state from all such blobs into one.
+ */
+export async function getGCDataFromSnapshot(gcSnapshotTree, readAndParseBlob) {
+    let rootGCState = { gcNodes: {} };
+    let tombstones;
+    let deletedNodes;
+    for (const key of Object.keys(gcSnapshotTree.blobs)) {
+        // Update deleted nodes blob.
+        if (key === gcDeletedBlobKey) {
+            deletedNodes = await readAndParseBlob(gcSnapshotTree.blobs[key]);
+            continue;
+        }
+        // Update tombstone blob.
+        if (key === gcTombstoneBlobKey) {
+            tombstones = await readAndParseBlob(gcSnapshotTree.blobs[key]);
+            continue;
+        }
+        // Skip blobs that do not start with the GC prefix.
+        if (!key.startsWith(gcBlobPrefix)) {
+            continue;
+        }
+        const blobId = gcSnapshotTree.blobs[key];
+        if (blobId === undefined) {
+            continue;
+        }
+        const gcState = await readAndParseBlob(blobId);
+        assert(gcState !== undefined, 0x5d8 /* GC blob missing from snapshot */);
+        // Merge the GC state of this blob into the root GC state.
+        rootGCState = concatGarbageCollectionStates(rootGCState, gcState);
+    }
+    return { gcState: rootGCState, tombstones, deletedNodes };
+}
+/**
+ * Helper function that unpacks the GC details of the children from a given node's GC details.
+ * @param gcDetails - The GC details of a node.
+ * @returns A map of GC details of each children of the the given node.
+ */
+export function unpackChildNodesGCDetails(gcDetails) {
+    const childGCDetailsMap = new Map();
+    // If GC data is not available, bail out.
+    if (gcDetails.gcData === undefined) {
+        return childGCDetailsMap;
+    }
+    const gcNodes = gcDetails.gcData.gcNodes;
+    for (const [id, outboundRoutes] of Object.entries(gcNodes)) {
+        // Skip self-node since only children GC data is to be generated.
+        if (id === "/") {
+            continue;
+        }
+        assert(id.startsWith("/"), 0x5d9 /* node id should always be an absolute route */);
+        const childId = id.split("/")[1];
+        let childGCNodeId = id.slice(childId.length + 1);
+        // GC node id always begins with "/". Handle the special case where a child's id in the parent's GC nodes is
+        // of format `/root`. In this case, the childId is root and childGCNodeId is "". Make childGCNodeId = "/".
+        if (childGCNodeId === "") {
+            childGCNodeId = "/";
+        }
+        let childGCDetails = childGCDetailsMap.get(childId);
+        if (childGCDetails === undefined) {
+            childGCDetails = { gcData: { gcNodes: {} }, usedRoutes: [] };
+        }
+        // gcData should not undefined as its always at least initialized as  empty above.
+        assert(childGCDetails.gcData !== undefined, 0x5da /* Child GC data should have been initialized */);
+        childGCDetails.gcData.gcNodes[childGCNodeId] = [...new Set(outboundRoutes)];
+        childGCDetailsMap.set(childId, childGCDetails);
+    }
+    if (gcDetails.usedRoutes === undefined) {
+        return childGCDetailsMap;
+    }
+    // Remove the node's self used route, if any, and generate the children used routes.
+    const usedRoutes = gcDetails.usedRoutes.filter((route) => route !== "" && route !== "/");
+    for (const route of usedRoutes) {
+        assert(route.startsWith("/"), 0x5db /* Used route should always be an absolute route */);
+        const childId = route.split("/")[1];
+        const childUsedRoute = route.slice(childId.length + 1);
+        const childGCDetails = childGCDetailsMap.get(childId);
+        assert(childGCDetails?.usedRoutes !== undefined, 0x5dc /* This should have be initialized when generate GC nodes above */);
+        childGCDetails.usedRoutes.push(childUsedRoute);
+        childGCDetailsMap.set(childId, childGCDetails);
+    }
+    return childGCDetailsMap;
+}
+/**
+ * Trims the leading and trailing slashes from the given string.
+ * @param str - A string that may contain leading and / or trailing slashes.
+ * @returns A new string without leading and trailing slashes.
+ */
+export function trimLeadingAndTrailingSlashes(str) {
+    return str.replace(/^\/+|\/+$/g, "");
+}
+/**
+ * Utility to implement compat behaviors given an unknown message type
+ * The parameters are typed to support compile-time enforcement of handling all known types/behaviors
+ *
+ * @param _unknownGCMessageType - Typed as never to ensure all known types have been
+ * handled before calling this function (e.g. in a switch statement).
+ * @param compatBehavior - Typed redundantly with CompatModeBehavior to ensure handling is added when updating that type
+ */
+export function compatBehaviorAllowsGCMessageType(_unknownGCMessageType, compatBehavior) {
+    // undefined defaults to same behavior as "FailToProcess"
+    return compatBehavior === "Ignore";
+}
+//# sourceMappingURL=gcHelpers.mjs.map

package/lib/gc/gcHelpers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcHelpers.mjs","sourceRoot":"","sources":["../../src/gc/gcHelpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;OAEI,EAAE,MAAM,EAAE,MAAM,4BAA4B;OAE5C,EACN,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,GAGlB,MAAM,qCAAqC;AAQ5C,MAAM,UAAU,YAAY,CAAC,QAAsB;IAClD,IAAI,CAAC,QAAQ,EAAE;QACd,0CAA0C;QAC1C,OAAO,CAAC,CAAC;KACT;IACD,OAAO,QAAQ,CAAC,SAAS,IAAI,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CACjC,aAA8B,EAC9B,iBAAqC;IAErC,uEAAuE;IACvE,IAAI,iBAAiB,KAAK,SAAS,EAAE;QACpC,OAAO,IAAI,CAAC;KACZ;IAED,2FAA2F;IAC3F,MAAM,gBAAgB,GAAG,aAAa,CAAC,mBAAmB,IAAI,aAAa,CAAC,YAAY,CAAC;IAEzF,OAAO,iBAAiB,KAAK,gBAAgB,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgC;IACrE,MAAM,aAAa,GAA2C,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9F,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,aAAa,GAA4B,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC/D,KAAK,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,aAAa,EAAE;QAC/C,QAAQ,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QAC/B,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;KACzC;IACD,OAAO,aAAa,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAC5C,QAAiC,EACjC,QAAiC;IAEjC,MAAM,eAAe,GAAiD,EAAE,CAAC;IACzE,KAAK,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE;QAClE,eAAe,CAAC,MAAM,CAAC,GAAG;YACzB,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC;YACnD,uBAAuB,EAAE,QAAQ,CAAC,uBAAuB;SACzD,CAAC;KACF;IAED,KAAK,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE;QAClE,IAAI,eAAe,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,eAAe,KAAK,SAAS,EAAE;YAClC,eAAe,GAAG;gBACjB,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC;gBACnD,uBAAuB,EAAE,QAAQ,CAAC,uBAAuB;aACzD,CAAC;SACF;aAAM;YACN,yEAAyE;YACzE,IACC,QAAQ,CAAC,uBAAuB,KAAK,SAAS;gBAC9C,eAAe,CAAC,uBAAuB,KAAK,SAAS,EACpD;gBACD,MAAM,CACL,QAAQ,CAAC,uBAAuB,KAAK,eAAe,CAAC,uBAAuB,EAC5E,KAAK,CAAC,4EAA4E,CAClF,CAAC;aACF;YACD,eAAe,GAAG;gBACjB,cAAc,EAAE;oBACf,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,cAAc,EAAE,GAAG,eAAe,CAAC,cAAc,CAAC,CAAC;iBAC3E;gBACD,uBAAuB,EACtB,QAAQ,CAAC,uBAAuB,IAAI,eAAe,CAAC,uBAAuB;aAC5E,CAAC;SACF;QACD,eAAe,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC;KAC1C;IACD,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAA8B;IACzD,MAAM,aAAa,GAA+B,EAAE,CAAC;IACrD,KAAK,MAAM,CAAC,EAAE,EAAE,cAAc,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE;QAClE,aAAa,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;KAC/C;IACD,OAAO;QACN,OAAO,EAAE,aAAa;KACtB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAC1C,OAA+B,EAC/B,OAA+B;IAE/B,MAAM,cAAc,GAA2B,WAAW,CAAC,OAAO,CAAC,CAAC;IACpE,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE;QAC3D,IAAI,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,SAAS,EAAE;YAC7C,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;SAChD;aAAM;YACN,MAAM,cAAc,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;YAClE,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;SAC1D;KACD;IACD,OAAO,cAAc,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAC1C,cAA6B,EAC7B,gBAA+C;IAE/C,IAAI,WAAW,GAA4B,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC3D,IAAI,UAAgC,CAAC;IACrC,IAAI,YAAkC,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE;QACpD,6BAA6B;QAC7B,IAAI,GAAG,KAAK,gBAAgB,EAAE;YAC7B,YAAY,GAAG,MAAM,gBAAgB,CAAW,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YAC3E,SAAS;SACT;QAED,yBAAyB;QACzB,IAAI,GAAG,KAAK,kBAAkB,EAAE;YAC/B,UAAU,GAAG,MAAM,gBAAgB,CAAW,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YACzE,SAAS;SACT;QAED,mDAAmD;QACnD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE;YAClC,SAAS;SACT;QAED,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,MAAM,KAAK,SAAS,EAAE;YACzB,SAAS;SACT;QACD,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAA0B,MAAM,CAAC,CAAC;QACxE,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACzE,0DAA0D;QAC1D,WAAW,GAAG,6BAA6B,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;KAClE;IACD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAAwC;IACjF,MAAM,iBAAiB,GAA+C,IAAI,GAAG,EAAE,CAAC;IAEhF,yCAAyC;IACzC,IAAI,SAAS,CAAC,MAAM,KAAK,SAAS,EAAE;QACnC,OAAO,iBAAiB,CAAC;KACzB;IAED,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC;IACzC,KAAK,MAAM,CAAC,EAAE,EAAE,cAAc,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE;QAC3D,iEAAiE;QACjE,IAAI,EAAE,KAAK,GAAG,EAAE;YACf,SAAS;SACT;QAED,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACnF,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACjC,IAAI,aAAa,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACjD,4GAA4G;QAC5G,0GAA0G;QAC1G,IAAI,aAAa,KAAK,EAAE,EAAE;YACzB,aAAa,GAAG,GAAG,CAAC;SACpB;QAED,IAAI,cAAc,GAAG,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,cAAc,KAAK,SAAS,EAAE;YACjC,cAAc,GAAG,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;SAC7D;QACD,kFAAkF;QAClF,MAAM,CACL,cAAc,CAAC,MAAM,KAAK,SAAS,EACnC,KAAK,CAAC,gDAAgD,CACtD,CAAC;QACF,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;QAC5E,iBAAiB,CAAC,GAAG,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;KAC/C;IAED,IAAI,SAAS,CAAC,UAAU,KAAK,SAAS,EAAE;QACvC,OAAO,iBAAiB,CAAC;KACzB;IAED,oFAAoF;IACpF,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,EAAE,IAAI,KAAK,KAAK,GAAG,CAAC,CAAC;IACzF,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE;QAC/B,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACzF,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAEvD,MAAM,cAAc,GAAG,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,CACL,cAAc,EAAE,UAAU,KAAK,SAAS,EACxC,KAAK,CAAC,kEAAkE,CACxE,CAAC;QAEF,cAAc,CAAC,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC/C,iBAAiB,CAAC,GAAG,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;KAC/C;IACD,OAAO,iBAAiB,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAAC,GAAW;IACxD,OAAO,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iCAAiC,CAChD,qBAA4B,EAC5B,cAAsD;IAEtD,yDAAyD;IACzD,OAAO,cAAc,KAAK,QAAQ,CAAC;AACpC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils\";\nimport { ISnapshotTree } from \"@fluidframework/protocol-definitions\";\nimport {\n\tgcBlobPrefix,\n\tgcDeletedBlobKey,\n\tgcTombstoneBlobKey,\n\tIGarbageCollectionData,\n\tIGarbageCollectionDetailsBase,\n} from \"@fluidframework/runtime-definitions\";\nimport { GCFeatureMatrix, GCVersion, IGCMetadata } from \"./gcDefinitions\";\nimport {\n\tIGarbageCollectionNodeData,\n\tIGarbageCollectionSnapshotData,\n\tIGarbageCollectionState,\n} from \"./gcSummaryDefinitions\";\n\nexport function getGCVersion(metadata?: IGCMetadata): GCVersion {\n\tif (!metadata) {\n\t\t// Force to 0/disallowed in prior versions\n\t\treturn 0;\n\t}\n\treturn metadata.gcFeature ?? 0;\n}\n\n/**\n * Indicates whether Sweep is allowed for this document based on the persisted GC Feature Matrix and current gcGeneration.\n * This applies to the entire Sweep Phase the same - both Tombstone Enforcement (i.e. should loading a Tombstone fail?) and Deletion.\n *\n * In order to protect old documents that were created at a time when known bugs exist that violate GC's invariants\n * such that enforcing GC Sweep would cause legitimate data loss, the container author may increment the generation value for Sweep\n * such that containers created with a different value will not be subjected to GC Sweep.\n *\n * If no generation is provided, Sweep will be enabled for all documents.\n *\n * For backwards compatibility, the current generation value is also compared against the persisted gcTombstoneGeneration if present.\n *\n * @param featureMatrix - The GC Feature Matrix, containing the persisted generation value\n * @param currentGeneration - The current app-provided gcGeneration value\n * @returns true if GC Sweep should be allowed for this document\n */\nexport function shouldAllowGcSweep(\n\tfeatureMatrix: GCFeatureMatrix,\n\tcurrentGeneration: number | undefined,\n): boolean {\n\t// If no Generation value is provided for this session, default to true\n\tif (currentGeneration === undefined) {\n\t\treturn true;\n\t}\n\n\t// tombstoneGeneration is the predecessor and needs to be supported for back-compat reasons\n\tconst targetGeneration = featureMatrix.tombstoneGeneration ?? featureMatrix.gcGeneration;\n\n\treturn currentGeneration === targetGeneration;\n}\n\n/**\n * Sorts the given GC state as per the id of the GC nodes. It also sorts the outbound routes array of each node.\n */\nexport function generateSortedGCState(gcState: IGarbageCollectionState): IGarbageCollectionState {\n\tconst sortableArray: [string, IGarbageCollectionNodeData][] = Object.entries(gcState.gcNodes);\n\tsortableArray.sort(([a], [b]) => a.localeCompare(b));\n\tconst sortedGCState: IGarbageCollectionState = { gcNodes: {} };\n\tfor (const [nodeId, nodeData] of sortableArray) {\n\t\tnodeData.outboundRoutes.sort();\n\t\tsortedGCState.gcNodes[nodeId] = nodeData;\n\t}\n\treturn sortedGCState;\n}\n\n/**\n * Concatenates the given GC states and returns the concatenated GC state.\n */\nexport function concatGarbageCollectionStates(\n\tgcState1: IGarbageCollectionState,\n\tgcState2: IGarbageCollectionState,\n): IGarbageCollectionState {\n\tconst combinedGCNodes: { [id: string]: IGarbageCollectionNodeData } = {};\n\tfor (const [nodeId, nodeData] of Object.entries(gcState1.gcNodes)) {\n\t\tcombinedGCNodes[nodeId] = {\n\t\t\toutboundRoutes: Array.from(nodeData.outboundRoutes),\n\t\t\tunreferencedTimestampMs: nodeData.unreferencedTimestampMs,\n\t\t};\n\t}\n\n\tfor (const [nodeId, nodeData] of Object.entries(gcState2.gcNodes)) {\n\t\tlet combineNodeData = combinedGCNodes[nodeId];\n\t\tif (combineNodeData === undefined) {\n\t\t\tcombineNodeData = {\n\t\t\t\toutboundRoutes: Array.from(nodeData.outboundRoutes),\n\t\t\t\tunreferencedTimestampMs: nodeData.unreferencedTimestampMs,\n\t\t\t};\n\t\t} else {\n\t\t\t// Validate that same node doesn't have different unreferenced timestamp.\n\t\t\tif (\n\t\t\t\tnodeData.unreferencedTimestampMs !== undefined &&\n\t\t\t\tcombineNodeData.unreferencedTimestampMs !== undefined\n\t\t\t) {\n\t\t\t\tassert(\n\t\t\t\t\tnodeData.unreferencedTimestampMs === combineNodeData.unreferencedTimestampMs,\n\t\t\t\t\t0x5d7 /* Two entries for the same GC node with different unreferenced timestamp */,\n\t\t\t\t);\n\t\t\t}\n\t\t\tcombineNodeData = {\n\t\t\t\toutboundRoutes: [\n\t\t\t\t\t...new Set([...nodeData.outboundRoutes, ...combineNodeData.outboundRoutes]),\n\t\t\t\t],\n\t\t\t\tunreferencedTimestampMs:\n\t\t\t\t\tnodeData.unreferencedTimestampMs ?? combineNodeData.unreferencedTimestampMs,\n\t\t\t};\n\t\t}\n\t\tcombinedGCNodes[nodeId] = combineNodeData;\n\t}\n\treturn { gcNodes: combinedGCNodes };\n}\n\n/**\n * Helper function that clones the GC data.\n * @param gcData - The GC data to clone.\n * @returns a clone of the given GC data.\n */\nexport function cloneGCData(gcData: IGarbageCollectionData): IGarbageCollectionData {\n\tconst clonedGCNodes: { [id: string]: string[] } = {};\n\tfor (const [id, outboundRoutes] of Object.entries(gcData.gcNodes)) {\n\t\tclonedGCNodes[id] = Array.from(outboundRoutes);\n\t}\n\treturn {\n\t\tgcNodes: clonedGCNodes,\n\t};\n}\n\n/**\n * Concatenates the given GC data and returns the concatenated GC data.\n */\nexport function concatGarbageCollectionData(\n\tgcData1: IGarbageCollectionData,\n\tgcData2: IGarbageCollectionData,\n) {\n\tconst combinedGCData: IGarbageCollectionData = cloneGCData(gcData1);\n\tfor (const [id, routes] of Object.entries(gcData2.gcNodes)) {\n\t\tif (combinedGCData.gcNodes[id] === undefined) {\n\t\t\tcombinedGCData.gcNodes[id] = Array.from(routes);\n\t\t} else {\n\t\t\tconst combinedRoutes = [...routes, ...combinedGCData.gcNodes[id]];\n\t\t\tcombinedGCData.gcNodes[id] = [...new Set(combinedRoutes)];\n\t\t}\n\t}\n\treturn combinedGCData;\n}\n\n/**\n * Gets the base garbage collection state from the given snapshot tree. It contains GC state, deleted nodes and\n * tombstones. The GC state may be written into multiple blobs. Merge the GC state from all such blobs into one.\n */\nexport async function getGCDataFromSnapshot(\n\tgcSnapshotTree: ISnapshotTree,\n\treadAndParseBlob: <T>(id: string) => Promise<T>,\n): Promise<IGarbageCollectionSnapshotData> {\n\tlet rootGCState: IGarbageCollectionState = { gcNodes: {} };\n\tlet tombstones: string[] | undefined;\n\tlet deletedNodes: string[] | undefined;\n\tfor (const key of Object.keys(gcSnapshotTree.blobs)) {\n\t\t// Update deleted nodes blob.\n\t\tif (key === gcDeletedBlobKey) {\n\t\t\tdeletedNodes = await readAndParseBlob<string[]>(gcSnapshotTree.blobs[key]);\n\t\t\tcontinue;\n\t\t}\n\n\t\t// Update tombstone blob.\n\t\tif (key === gcTombstoneBlobKey) {\n\t\t\ttombstones = await readAndParseBlob<string[]>(gcSnapshotTree.blobs[key]);\n\t\t\tcontinue;\n\t\t}\n\n\t\t// Skip blobs that do not start with the GC prefix.\n\t\tif (!key.startsWith(gcBlobPrefix)) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst blobId = gcSnapshotTree.blobs[key];\n\t\tif (blobId === undefined) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst gcState = await readAndParseBlob<IGarbageCollectionState>(blobId);\n\t\tassert(gcState !== undefined, 0x5d8 /* GC blob missing from snapshot */);\n\t\t// Merge the GC state of this blob into the root GC state.\n\t\trootGCState = concatGarbageCollectionStates(rootGCState, gcState);\n\t}\n\treturn { gcState: rootGCState, tombstones, deletedNodes };\n}\n\n/**\n * Helper function that unpacks the GC details of the children from a given node's GC details.\n * @param gcDetails - The GC details of a node.\n * @returns A map of GC details of each children of the the given node.\n */\nexport function unpackChildNodesGCDetails(gcDetails: IGarbageCollectionDetailsBase) {\n\tconst childGCDetailsMap: Map<string, IGarbageCollectionDetailsBase> = new Map();\n\n\t// If GC data is not available, bail out.\n\tif (gcDetails.gcData === undefined) {\n\t\treturn childGCDetailsMap;\n\t}\n\n\tconst gcNodes = gcDetails.gcData.gcNodes;\n\tfor (const [id, outboundRoutes] of Object.entries(gcNodes)) {\n\t\t// Skip self-node since only children GC data is to be generated.\n\t\tif (id === \"/\") {\n\t\t\tcontinue;\n\t\t}\n\n\t\tassert(id.startsWith(\"/\"), 0x5d9 /* node id should always be an absolute route */);\n\t\tconst childId = id.split(\"/\")[1];\n\t\tlet childGCNodeId = id.slice(childId.length + 1);\n\t\t// GC node id always begins with \"/\". Handle the special case where a child's id in the parent's GC nodes is\n\t\t// of format `/root`. In this case, the childId is root and childGCNodeId is \"\". Make childGCNodeId = \"/\".\n\t\tif (childGCNodeId === \"\") {\n\t\t\tchildGCNodeId = \"/\";\n\t\t}\n\n\t\tlet childGCDetails = childGCDetailsMap.get(childId);\n\t\tif (childGCDetails === undefined) {\n\t\t\tchildGCDetails = { gcData: { gcNodes: {} }, usedRoutes: [] };\n\t\t}\n\t\t// gcData should not undefined as its always at least initialized as  empty above.\n\t\tassert(\n\t\t\tchildGCDetails.gcData !== undefined,\n\t\t\t0x5da /* Child GC data should have been initialized */,\n\t\t);\n\t\tchildGCDetails.gcData.gcNodes[childGCNodeId] = [...new Set(outboundRoutes)];\n\t\tchildGCDetailsMap.set(childId, childGCDetails);\n\t}\n\n\tif (gcDetails.usedRoutes === undefined) {\n\t\treturn childGCDetailsMap;\n\t}\n\n\t// Remove the node's self used route, if any, and generate the children used routes.\n\tconst usedRoutes = gcDetails.usedRoutes.filter((route) => route !== \"\" && route !== \"/\");\n\tfor (const route of usedRoutes) {\n\t\tassert(route.startsWith(\"/\"), 0x5db /* Used route should always be an absolute route */);\n\t\tconst childId = route.split(\"/\")[1];\n\t\tconst childUsedRoute = route.slice(childId.length + 1);\n\n\t\tconst childGCDetails = childGCDetailsMap.get(childId);\n\t\tassert(\n\t\t\tchildGCDetails?.usedRoutes !== undefined,\n\t\t\t0x5dc /* This should have be initialized when generate GC nodes above */,\n\t\t);\n\n\t\tchildGCDetails.usedRoutes.push(childUsedRoute);\n\t\tchildGCDetailsMap.set(childId, childGCDetails);\n\t}\n\treturn childGCDetailsMap;\n}\n\n/**\n * Trims the leading and trailing slashes from the given string.\n * @param str - A string that may contain leading and / or trailing slashes.\n * @returns A new string without leading and trailing slashes.\n */\nexport function trimLeadingAndTrailingSlashes(str: string) {\n\treturn str.replace(/^\\/+|\\/+$/g, \"\");\n}\n\n/**\n * Utility to implement compat behaviors given an unknown message type\n * The parameters are typed to support compile-time enforcement of handling all known types/behaviors\n *\n * @param _unknownGCMessageType - Typed as never to ensure all known types have been\n * handled before calling this function (e.g. in a switch statement).\n * @param compatBehavior - Typed redundantly with CompatModeBehavior to ensure handling is added when updating that type\n */\nexport function compatBehaviorAllowsGCMessageType(\n\t_unknownGCMessageType: never,\n\tcompatBehavior: \"Ignore\" | \"FailToProcess\" | undefined,\n): boolean {\n\t// undefined defaults to same behavior as \"FailToProcess\"\n\treturn compatBehavior === \"Ignore\";\n}\n"]}

package/lib/gc/gcReferenceGraphAlgorithm.d.mts

@@ -0,0 +1,16 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IGCResult } from "./gcDefinitions.mjs";
+/**
+ * Runs garbage collection on the given reference graph.
+ * @param referenceGraph - The reference graph to run GC on. It's a list of nodes where each node has an id and set of
+ * routes to other nodes in the graph.
+ * @param rootIds - The ids of root nodes that are considered referenced.
+ * @returns the ids of referenced nodes and the ids of deleted nodes in the referenced graph.
+ */
+export declare function runGarbageCollection(referenceGraph: {
+    [id: string]: string[];
+}, rootIds: string[]): IGCResult;
+//# sourceMappingURL=gcReferenceGraphAlgorithm.d.ts.map

package/lib/gc/gcReferenceGraphAlgorithm.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcReferenceGraphAlgorithm.d.ts","sourceRoot":"","sources":["../../src/gc/gcReferenceGraphAlgorithm.ts"],"names":[],"mappings":"AAAA;;;GAGG;OAEI,EAAE,SAAS,EAAE;AAEpB;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,cAAc,EAAE;IAAE,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAAE,EAC1C,OAAO,EAAE,MAAM,EAAE,GACf,SAAS,CAkCX"}

package/lib/gc/gcReferenceGraphAlgorithm.mjs

@@ -0,0 +1,45 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Runs garbage collection on the given reference graph.
+ * @param referenceGraph - The reference graph to run GC on. It's a list of nodes where each node has an id and set of
+ * routes to other nodes in the graph.
+ * @param rootIds - The ids of root nodes that are considered referenced.
+ * @returns the ids of referenced nodes and the ids of deleted nodes in the referenced graph.
+ */
+export function runGarbageCollection(referenceGraph, rootIds) {
+    // This set keeps track of nodes that we have visited. It is used to detect cycles in the graph.
+    const visited = new Set();
+    // This tracks the ids of referenced nodes. The nodes corresponding to rootIds are always considered
+    // referenced so we start with those.
+    const referencedIds = [...rootIds];
+    for (const id of referencedIds) {
+        // If we have already seen this node, ignore and continue. Else, add it to visited list.
+        if (visited.has(id)) {
+            continue;
+        }
+        visited.add(id);
+        // Get the node for the referenced id and add its outbound routes to referencedIds since they are
+        // also referenced.
+        const routes = referenceGraph[id];
+        if (routes !== undefined) {
+            referencedIds.push(...routes);
+        }
+    }
+    const referencedNodeIds = [];
+    const deletedNodeIds = [];
+    for (const id of Object.keys(referenceGraph)) {
+        // The nodes from the reference graph whose ids are in the visited list are referenced.
+        // The rest of the nodes are deleted.
+        if (visited.has(id)) {
+            referencedNodeIds.push(id);
+        }
+        else {
+            deletedNodeIds.push(id);
+        }
+    }
+    return { referencedNodeIds, deletedNodeIds };
+}
+//# sourceMappingURL=gcReferenceGraphAlgorithm.mjs.map

package/lib/gc/gcReferenceGraphAlgorithm.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcReferenceGraphAlgorithm.mjs","sourceRoot":"","sources":["../../src/gc/gcReferenceGraphAlgorithm.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CACnC,cAA0C,EAC1C,OAAiB;IAEjB,gGAAgG;IAChG,MAAM,OAAO,GAAgB,IAAI,GAAG,EAAE,CAAC;IAEvC,oGAAoG;IACpG,qCAAqC;IACrC,MAAM,aAAa,GAAa,CAAC,GAAG,OAAO,CAAC,CAAC;IAC7C,KAAK,MAAM,EAAE,IAAI,aAAa,EAAE;QAC/B,wFAAwF;QACxF,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;YACpB,SAAS;SACT;QACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEhB,iGAAiG;QACjG,mBAAmB;QACnB,MAAM,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,SAAS,EAAE;YACzB,aAAa,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;SAC9B;KACD;IAED,MAAM,iBAAiB,GAAa,EAAE,CAAC;IACvC,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE;QAC7C,uFAAuF;QACvF,qCAAqC;QACrC,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;YACpB,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;SAC3B;aAAM;YACN,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;SACxB;KACD;IACD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;AAC9C,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { IGCResult } from \"./gcDefinitions\";\n\n/**\n * Runs garbage collection on the given reference graph.\n * @param referenceGraph - The reference graph to run GC on. It's a list of nodes where each node has an id and set of\n * routes to other nodes in the graph.\n * @param rootIds - The ids of root nodes that are considered referenced.\n * @returns the ids of referenced nodes and the ids of deleted nodes in the referenced graph.\n */\nexport function runGarbageCollection(\n\treferenceGraph: { [id: string]: string[] },\n\trootIds: string[],\n): IGCResult {\n\t// This set keeps track of nodes that we have visited. It is used to detect cycles in the graph.\n\tconst visited: Set<string> = new Set();\n\n\t// This tracks the ids of referenced nodes. The nodes corresponding to rootIds are always considered\n\t// referenced so we start with those.\n\tconst referencedIds: string[] = [...rootIds];\n\tfor (const id of referencedIds) {\n\t\t// If we have already seen this node, ignore and continue. Else, add it to visited list.\n\t\tif (visited.has(id)) {\n\t\t\tcontinue;\n\t\t}\n\t\tvisited.add(id);\n\n\t\t// Get the node for the referenced id and add its outbound routes to referencedIds since they are\n\t\t// also referenced.\n\t\tconst routes = referenceGraph[id];\n\t\tif (routes !== undefined) {\n\t\t\treferencedIds.push(...routes);\n\t\t}\n\t}\n\n\tconst referencedNodeIds: string[] = [];\n\tconst deletedNodeIds: string[] = [];\n\tfor (const id of Object.keys(referenceGraph)) {\n\t\t// The nodes from the reference graph whose ids are in the visited list are referenced.\n\t\t// The rest of the nodes are deleted.\n\t\tif (visited.has(id)) {\n\t\t\treferencedNodeIds.push(id);\n\t\t} else {\n\t\t\tdeletedNodeIds.push(id);\n\t\t}\n\t}\n\treturn { referencedNodeIds, deletedNodeIds };\n}\n"]}

package/lib/gc/gcSummaryDefinitions.d.mts

@@ -0,0 +1,52 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IGarbageCollectionData } from "@fluidframework/runtime-definitions";
+/**
+ * The garbage collection data of each node in the reference graph. Each node's GC data is written in the summary
+ * in this format.
+ */
+export interface IGarbageCollectionNodeData {
+    /**
+     * The set of routes to other nodes in the graph.
+     */
+    outboundRoutes: string[];
+    /**
+     * If the node is unreferenced, the timestamp of when it was marked unreferenced.
+     */
+    unreferencedTimestampMs?: number;
+}
+/**
+ * The garbage collection state of the reference graph. It contains a list of all the nodes in the graph and their
+ * GC data. The GC data is written in the summary in this format.
+ */
+export interface IGarbageCollectionState {
+    gcNodes: {
+        [id: string]: IGarbageCollectionNodeData;
+    };
+}
+/**
+ * The GC data that is read from a snapshot. It contains the Garbage CollectionState state and tombstone state.
+ */
+export interface IGarbageCollectionSnapshotData {
+    /** The garbage collection state. It is a list of nodes in the container and their GC data. */
+    gcState: IGarbageCollectionState | undefined;
+    /** A list of nodes that have been tombstoned by GC. */
+    tombstones: string[] | undefined;
+    /** A list of nodes that have been deleted by GC. */
+    deletedNodes: string[] | undefined;
+}
+/**
+ * @deprecated IGarbageCollectionState is written in the root of the summary now.
+ * Legacy GC details from when the GC details were written at the data store's summary tree.
+ */
+export interface IGarbageCollectionSummaryDetailsLegacy {
+    /** A list of routes to Fluid objects that are used in this node. */
+    usedRoutes?: string[];
+    /** The GC data of this node. */
+    gcData?: IGarbageCollectionData;
+    /** If this node is unreferenced, the time when it was marked as such. */
+    unrefTimestamp?: number;
+}
+//# sourceMappingURL=gcSummaryDefinitions.d.ts.map

package/lib/gc/gcSummaryDefinitions.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcSummaryDefinitions.d.ts","sourceRoot":"","sources":["../../src/gc/gcSummaryDefinitions.ts"],"names":[],"mappings":"AAAA;;;GAGG;OAEI,EAAE,sBAAsB,EAAE,MAAM,qCAAqC;AAE5E;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IAC1C;;OAEG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;OAEG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE;QAAE,CAAC,EAAE,EAAE,MAAM,GAAG,0BAA0B,CAAA;KAAE,CAAC;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC9C,8FAA8F;IAC9F,OAAO,EAAE,uBAAuB,GAAG,SAAS,CAAC;IAC7C,uDAAuD;IACvD,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACjC,oDAAoD;IACpD,YAAY,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,sCAAsC;IACtD,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,gCAAgC;IAChC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/lib/gc/gcSummaryDefinitions.mjs

@@ -0,0 +1,6 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export {};
+//# sourceMappingURL=gcSummaryDefinitions.mjs.map

package/lib/gc/gcSummaryDefinitions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcSummaryDefinitions.mjs","sourceRoot":"","sources":["../../src/gc/gcSummaryDefinitions.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { IGarbageCollectionData } from \"@fluidframework/runtime-definitions\";\n\n/**\n * The garbage collection data of each node in the reference graph. Each node's GC data is written in the summary\n * in this format.\n */\nexport interface IGarbageCollectionNodeData {\n\t/**\n\t * The set of routes to other nodes in the graph.\n\t */\n\toutboundRoutes: string[];\n\t/**\n\t * If the node is unreferenced, the timestamp of when it was marked unreferenced.\n\t */\n\tunreferencedTimestampMs?: number;\n}\n\n/**\n * The garbage collection state of the reference graph. It contains a list of all the nodes in the graph and their\n * GC data. The GC data is written in the summary in this format.\n */\nexport interface IGarbageCollectionState {\n\tgcNodes: { [id: string]: IGarbageCollectionNodeData };\n}\n\n/**\n * The GC data that is read from a snapshot. It contains the Garbage CollectionState state and tombstone state.\n */\nexport interface IGarbageCollectionSnapshotData {\n\t/** The garbage collection state. It is a list of nodes in the container and their GC data. */\n\tgcState: IGarbageCollectionState | undefined;\n\t/** A list of nodes that have been tombstoned by GC. */\n\ttombstones: string[] | undefined;\n\t/** A list of nodes that have been deleted by GC. */\n\tdeletedNodes: string[] | undefined;\n}\n\n/**\n * @deprecated IGarbageCollectionState is written in the root of the summary now.\n * Legacy GC details from when the GC details were written at the data store's summary tree.\n */\nexport interface IGarbageCollectionSummaryDetailsLegacy {\n\t/** A list of routes to Fluid objects that are used in this node. */\n\tusedRoutes?: string[];\n\t/** The GC data of this node. */\n\tgcData?: IGarbageCollectionData;\n\t/** If this node is unreferenced, the time when it was marked as such. */\n\tunrefTimestamp?: number;\n}\n"]}

package/lib/gc/gcSummaryStateTracker.d.mts

@@ -0,0 +1,94 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ISummarizeResult } from "@fluidframework/runtime-definitions";
+import { IRefreshSummaryResult } from "../summary/index.mjs";
+import { IGarbageCollectorConfigs, IGCStats } from "./gcDefinitions.mjs";
+import { IGarbageCollectionSnapshotData, IGarbageCollectionState } from "./gcSummaryDefinitions.mjs";
+export declare const gcStateBlobKey: string;
+/**
+ * The GC data that is tracked for a summary.
+ */
+export interface IGCSummaryTrackingData {
+    serializedGCState: string | undefined;
+    serializedTombstones: string | undefined;
+    serializedDeletedNodes: string | undefined;
+}
+/**
+ * Encapsulates the garbage collection state that is tracked across summaries.
+ * It maintains the GC state as per the latest summary in by the server. It updates state when a summary tracked by this
+ * client is acked by the server or from a snapshot is downloaded from the server.
+ * On summarize, it decides whether to write new state or re-use previous summary's state.
+ */
+export declare class GCSummaryStateTracker {
+    private readonly configs;
+    private latestSummaryGCVersion;
+    private latestSummaryData;
+    private pendingSummaryData;
+    private wasGCRunInLatestSummary;
+    updatedDSCountSinceLastSummary: number;
+    constructor(configs: Pick<IGarbageCollectorConfigs, "shouldRunGC" | "tombstoneMode" | "gcVersionInBaseSnapshot" | "gcVersionInEffect">, wasGCRunInBaseSnapshot: boolean);
+    /**
+     * Tells whether the GC state needs to be reset. This can happen under 3 conditions:
+     *
+     * 1. The base snapshot contains GC state but GC is disabled. This will happen the first time GC is disabled after
+     * it was enabled before. GC state needs to be removed from summary and all nodes should be marked referenced.
+     *
+     * 2. The base snapshot does not have GC state but GC is enabled. This will happen the very first time GC runs on
+     * a document and the first time GC is enabled after is was disabled before.
+     *
+     * 3. GC is enabled and the latest summary state is refreshed from a snapshot that had GC disabled and vice-versa.
+     *
+     * Note that the state will be reset only once for the first summary generated after this returns true. After that,
+     * this will return false.
+     */
+    get doesGCStateNeedReset(): boolean;
+    /**
+     * Tells whether the GC state needs to be reset in the next summary. We need to do this if:
+     *
+     * 1. GC was enabled and is now disabled. The GC state needs to be removed and everything becomes referenced.
+     *
+     * 2. GC was disabled and is now enabled. The GC state needs to be regenerated and added to summary.
+     *
+     * 3. GC is enabled and the latest summary state is refreshed from a snapshot that had GC disabled and vice-versa.
+     *
+     * 4. The GC version in the latest summary is different from the current GC version. This can happen if:
+     *
+     * 4.1. The summary this client loaded with has data from a different GC version.
+     *
+     * 4.2. This client's latest summary was updated from a snapshot that has a different GC version.
+     */
+    get doesSummaryStateNeedReset(): boolean;
+    /**
+     * Called during GC initialization. Initialize the latest summary data from the base snapshot data.
+     */
+    initializeBaseState(baseSnapshotData: IGarbageCollectionSnapshotData | undefined): void;
+    /**
+     * Summarizes three component of the GC data - GC state, tombstones and deleted nodes.
+     * It does incremental summary, i.e., it writes summary tree / summary blob only for the component that changed.
+     * For components that did not change, a summary handle is returned that points to the previous successful summary.
+     * If none of the components changed, it returns a summary handle for the entire GC data.
+     */
+    summarize(fullTree: boolean, trackState: boolean, gcState: IGarbageCollectionState, deletedNodes: Set<string>, tombstones: string[]): ISummarizeResult | undefined;
+    /**
+     * Builds the GC summary tree which contains GC state, deleted nodes and tombstones.
+     * If trackState is false, all of GC state, deleted nodes and tombstones are written as summary blobs.
+     * If trackState is true, only states that changed are written. Rest are written as handles.
+     * @param serializedGCState - The GC state serialized as string.
+     * @param serializedTombstones - The tombstone state serialized as string.
+     * @param serializedDeletedNodes - Deleted nodes serialized as string.
+     * @param trackState - Whether we are tracking GC state across summaries.
+     * @returns the GC summary tree.
+     */
+    private buildGCSummaryTree;
+    /**
+     * Called to refresh the latest summary state. This happens when either a pending summary is acked.
+     */
+    refreshLatestSummary(result: IRefreshSummaryResult): Promise<void>;
+    /**
+     * Called to update the state from a GC run's stats. Used to update the count of data stores whose state updated.
+     */
+    updateStateFromGCRunStats(stats: IGCStats): void;
+}
+//# sourceMappingURL=gcSummaryStateTracker.d.ts.map

package/lib/gc/gcSummaryStateTracker.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcSummaryStateTracker.d.ts","sourceRoot":"","sources":["../../src/gc/gcSummaryStateTracker.ts"],"names":[],"mappings":"AAAA;;;GAGG;OAGI,EAKN,gBAAgB,EAEhB,MAAM,qCAAqC;OAErC,EAAE,qBAAqB,EAAE;OACzB,EAAa,wBAAwB,EAAE,QAAQ,EAAE;OAEjD,EAAE,8BAA8B,EAAE,uBAAuB,EAAE;AAElE,eAAO,MAAM,cAAc,QAAyB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,sBAAsB,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB;IAkBhC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhBzB,OAAO,CAAC,sBAAsB,CAAY;IAG1C,OAAO,CAAC,iBAAiB,CAAqC;IAE9D,OAAO,CAAC,kBAAkB,CAAqC;IAG/D,OAAO,CAAC,uBAAuB,CAAU;IAIlC,8BAA8B,EAAE,MAAM,CAAK;gBAIhC,OAAO,EAAE,IAAI,CAC7B,wBAAwB,EACxB,aAAa,GAAG,eAAe,GAAG,yBAAyB,GAAG,mBAAmB,CACjF,EAED,sBAAsB,EAAE,OAAO;IAShC;;;;;;;;;;;;;OAaG;IACH,IAAW,oBAAoB,IAAI,OAAO,CAEzC;IAED;;;;;;;;;;;;;;OAcG;IACH,IAAW,yBAAyB,IAAI,OAAO,CAM9C;IAED;;OAEG;IACI,mBAAmB,CAAC,gBAAgB,EAAE,8BAA8B,GAAG,SAAS;IAevF;;;;;OAKG;IACI,SAAS,CACf,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,uBAAuB,EAChC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,EACzB,UAAU,EAAE,MAAM,EAAE,GAClB,gBAAgB,GAAG,SAAS;IAiE/B;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IAqD1B;;OAEG;IACU,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB/E;;OAEG;IACI,yBAAyB,CAAC,KAAK,EAAE,QAAQ;CAGhD"}