@fluidframework/container-runtime 2.0.0-dev.3.1.0.125672 → 2.0.0-dev.4.2.0.153917

package/lib/gc/gcHelpers.js

@@ -0,0 +1,254 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { assert } from "@fluidframework/common-utils";
+import { gcBlobPrefix, gcDeletedBlobKey, gcTombstoneBlobKey, } from "@fluidframework/runtime-definitions";
+import { packagePathToTelemetryProperty } from "@fluidframework/runtime-utils";
+import { disableTombstoneKey, runSweepKey, throwOnTombstoneLoadKey, throwOnTombstoneUsageKey, } from "./gcDefinitions";
+export function getGCVersion(metadata) {
+    var _a;
+    if (!metadata) {
+        // Force to 0/disallowed in prior versions
+        return 0;
+    }
+    return (_a = metadata.gcFeature) !== null && _a !== void 0 ? _a : 0;
+}
+/**
+ * Consolidates info / logic for logging when we encounter unexpected usage of GC'd objects. For example, when a
+ * tombstoned or deleted object is loaded.
+ */
+export function sendGCUnexpectedUsageEvent(mc, event, packagePath, error) {
+    event.pkg = packagePathToTelemetryProperty(packagePath);
+    event.tombstoneFlags = JSON.stringify({
+        DisableTombstone: mc.config.getBoolean(disableTombstoneKey),
+        ThrowOnTombstoneUsage: mc.config.getBoolean(throwOnTombstoneUsageKey),
+        ThrowOnTombstoneLoad: mc.config.getBoolean(throwOnTombstoneLoadKey),
+    });
+    event.sweepFlags = JSON.stringify({
+        EnableSweepFlag: mc.config.getBoolean(runSweepKey),
+    });
+    mc.logger.sendTelemetryEvent(event, error);
+}
+/**
+ * Indicates whether Tombstone Enforcement is allowed for this document based on the current/persisted
+ * TombstoneGeneration values
+ *
+ * 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 Tombstone (Failing on Tombstone load/usage) would cause legitimate data loss,
+ * the container author may increment the generation value for Tombstone such that containers created
+ * with a different value will not be subjected to GC enforcement.
+ *
+ * If no generation is provided at runtime, this defaults to return true to maintain expected default behavior
+ *
+ * @param persistedGeneration - The persisted tombstoneGeneration value
+ * @param currentGeneration - The current app-provided tombstoneGeneration value
+ * @returns true if GC Tombstone enforcement (Fail on Tombstone load/usage) should be allowed for this document
+ */
+export function shouldAllowGcTombstoneEnforcement(persistedGeneration, currentGeneration) {
+    // If no Generation value is provided for this session, then we should default to letting Tombstone feature behave as intended.
+    if (currentGeneration === undefined) {
+        return true;
+    }
+    return persistedGeneration === currentGeneration;
+}
+/**
+ * Indicates whether Sweep is allowed for this document based on the GC Feature Matrix and current SweepGeneration
+ *
+ * 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 disabled.
+ * Passing 0 is a special case: Sweep will be enabled for any document with gcSweepGeneration OR gcTombstoneGeneration as 0.
+ *
+ * @param persistedGenerations - The persisted sweep/tombstone generations from the GC Feature Matrix
+ * @param currentGeneration - The current app-provided sweepGeneration value
+ * @returns true if GC Sweep should be allowed for this document
+ */
+export function shouldAllowGcSweep(persistedGenerations, currentGeneration) {
+    // If no Generation value is provided for this session, default to false
+    if (currentGeneration === undefined) {
+        return false;
+    }
+    // 0 is a special case: It matches both SweepGeneration and TombstoneGeneration
+    // This is an optimistic measure to maximize coverage of GC Sweep if no bumps to TombstoneGeneration are needed before enabling Sweep.
+    if (currentGeneration === 0) {
+        return (persistedGenerations.sweepGeneration === 0 ||
+            persistedGenerations.tombstoneGeneration === 0);
+    }
+    return persistedGenerations.sweepGeneration === currentGeneration;
+}
+/**
+ * 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) {
+    var _a;
+    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: (_a = nodeData.unreferencedTimestampMs) !== null && _a !== void 0 ? _a : 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 === null || childGCDetails === void 0 ? void 0 : 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, "");
+}
+//# sourceMappingURL=gcHelpers.js.map

package/lib/gc/gcHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcHelpers.js","sourceRoot":"","sources":["../../src/gc/gcHelpers.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { ITelemetryGenericEvent } from \"@fluidframework/common-definitions\";\nimport { assert } from \"@fluidframework/common-utils\";\nimport { ISnapshotTree } from \"@fluidframework/protocol-definitions\";\nimport {\n\tgcBlobPrefix,\n\tgcDeletedBlobKey,\n\tgcTombstoneBlobKey,\n\tIGarbageCollectionData,\n\tIGarbageCollectionDetailsBase,\n} from \"@fluidframework/runtime-definitions\";\nimport { packagePathToTelemetryProperty } from \"@fluidframework/runtime-utils\";\nimport { MonitoringContext } from \"@fluidframework/telemetry-utils\";\nimport {\n\tdisableTombstoneKey,\n\tGCFeatureMatrix,\n\tGCVersion,\n\tIGCMetadata,\n\trunSweepKey,\n\tthrowOnTombstoneLoadKey,\n\tthrowOnTombstoneUsageKey,\n} 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 * Consolidates info / logic for logging when we encounter unexpected usage of GC'd objects. For example, when a\n * tombstoned or deleted object is loaded.\n */\nexport function sendGCUnexpectedUsageEvent(\n\tmc: MonitoringContext,\n\tevent: ITelemetryGenericEvent & {\n\t\tcategory: \"error\" | \"generic\";\n\t\tgcTombstoneEnforcementAllowed: boolean | undefined;\n\t},\n\tpackagePath: readonly string[] | undefined,\n\terror?: unknown,\n) {\n\tevent.pkg = packagePathToTelemetryProperty(packagePath);\n\tevent.tombstoneFlags = JSON.stringify({\n\t\tDisableTombstone: mc.config.getBoolean(disableTombstoneKey),\n\t\tThrowOnTombstoneUsage: mc.config.getBoolean(throwOnTombstoneUsageKey),\n\t\tThrowOnTombstoneLoad: mc.config.getBoolean(throwOnTombstoneLoadKey),\n\t});\n\tevent.sweepFlags = JSON.stringify({\n\t\tEnableSweepFlag: mc.config.getBoolean(runSweepKey),\n\t});\n\n\tmc.logger.sendTelemetryEvent(event, error);\n}\n\n/**\n * Indicates whether Tombstone Enforcement is allowed for this document based on the current/persisted\n * TombstoneGeneration values\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 Tombstone (Failing on Tombstone load/usage) would cause legitimate data loss,\n * the container author may increment the generation value for Tombstone such that containers created\n * with a different value will not be subjected to GC enforcement.\n *\n * If no generation is provided at runtime, this defaults to return true to maintain expected default behavior\n *\n * @param persistedGeneration - The persisted tombstoneGeneration value\n * @param currentGeneration - The current app-provided tombstoneGeneration value\n * @returns true if GC Tombstone enforcement (Fail on Tombstone load/usage) should be allowed for this document\n */\nexport function shouldAllowGcTombstoneEnforcement(\n\tpersistedGeneration: number | undefined,\n\tcurrentGeneration: number | undefined,\n): boolean {\n\t// If no Generation value is provided for this session, then we should default to letting Tombstone feature behave as intended.\n\tif (currentGeneration === undefined) {\n\t\treturn true;\n\t}\n\treturn persistedGeneration === currentGeneration;\n}\n\n/**\n * Indicates whether Sweep is allowed for this document based on the GC Feature Matrix and current SweepGeneration\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 disabled.\n * Passing 0 is a special case: Sweep will be enabled for any document with gcSweepGeneration OR gcTombstoneGeneration as 0.\n *\n * @param persistedGenerations - The persisted sweep/tombstone generations from the GC Feature Matrix\n * @param currentGeneration - The current app-provided sweepGeneration value\n * @returns true if GC Sweep should be allowed for this document\n */\nexport function shouldAllowGcSweep(\n\tpersistedGenerations: Pick<GCFeatureMatrix, \"sweepGeneration\" | \"tombstoneGeneration\">,\n\tcurrentGeneration: number | undefined,\n): boolean {\n\t// If no Generation value is provided for this session, default to false\n\tif (currentGeneration === undefined) {\n\t\treturn false;\n\t}\n\n\t// 0 is a special case: It matches both SweepGeneration and TombstoneGeneration\n\t// This is an optimistic measure to maximize coverage of GC Sweep if no bumps to TombstoneGeneration are needed before enabling Sweep.\n\tif (currentGeneration === 0) {\n\t\treturn (\n\t\t\tpersistedGenerations.sweepGeneration === 0 ||\n\t\t\tpersistedGenerations.tombstoneGeneration === 0\n\t\t);\n\t}\n\n\treturn persistedGenerations.sweepGeneration === currentGeneration;\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"]}

package/lib/gc/gcReferenceGraphAlgorithm.d.ts

@@ -0,0 +1,16 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IGCResult } from "./gcDefinitions";
+/**
+ * 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.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcReferenceGraphAlgorithm.d.ts","sourceRoot":"","sources":["../../src/gc/gcReferenceGraphAlgorithm.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;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.js

@@ -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.js.map

package/lib/gc/gcReferenceGraphAlgorithm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcReferenceGraphAlgorithm.js","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.ts

@@ -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.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcSummaryDefinitions.d.ts","sourceRoot":"","sources":["../../src/gc/gcSummaryDefinitions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAE7E;;;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.js

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

package/lib/gc/gcSummaryDefinitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcSummaryDefinitions.js","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.ts

@@ -0,0 +1,93 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ISummarizeResult } from "@fluidframework/runtime-definitions";
+import { ReadAndParseBlob } from "@fluidframework/runtime-utils";
+import { RefreshSummaryResult } from "../summary";
+import { GCVersion } from "./gcDefinitions";
+import { IGarbageCollectionSnapshotData, IGarbageCollectionState } from "./gcSummaryDefinitions";
+import { IGarbageCollectorConfigs } from ".";
+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;
+    readonly currentGCVersion: GCVersion;
+    private latestSummaryGCVersion;
+    private latestSummaryData;
+    private pendingSummaryData;
+    private wasGCRunInLatestSummary;
+    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): 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 or a snapshot
+     * is downloaded and should be used to update the state.
+     */
+    refreshLatestSummary(proposalHandle: string | undefined, result: RefreshSummaryResult, readAndParseBlob: ReadAndParseBlob): Promise<IGarbageCollectionSnapshotData | undefined>;
+}
+//# sourceMappingURL=gcSummaryStateTracker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gcSummaryStateTracker.d.ts","sourceRoot":"","sources":["../../src/gc/gcSummaryStateTracker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAKN,gBAAgB,EAEhB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAc,gBAAgB,EAAsB,MAAM,+BAA+B,CAAC;AACjG,OAAO,EAA+C,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,8BAA8B,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjG,OAAO,EAAE,wBAAwB,EAAE,MAAM,GAAG,CAAC;AAE7C,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;IAgBhC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAdzB,SAAgB,gBAAgB,EAAE,SAAS,CAAkC;IAE7E,OAAO,CAAC,sBAAsB,CAAY;IAG1C,OAAO,CAAC,iBAAiB,CAAqC;IAE9D,OAAO,CAAC,kBAAkB,CAAqC;IAG/D,OAAO,CAAC,uBAAuB,CAAU;gBAIvB,OAAO,EAAE,IAAI,CAC7B,wBAAwB,EACxB,aAAa,GAAG,eAAe,GAAG,yBAAyB,GAAG,mBAAmB,CACjF,EAED,sBAAsB,EAAE,OAAO;IAQhC;;;;;;;;;;;;;OAaG;IACH,IAAW,oBAAoB,IAAI,OAAO,CAEzC;IAED;;;;;;;;;;;;;;OAcG;IACH,IAAW,yBAAyB,IAAI,OAAO,CAK9C;IAED;;OAEG;IACI,mBAAmB,CAAC,gBAAgB,EAAE,8BAA8B;IAW3E;;;;;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;;;OAGG;IACU,oBAAoB,CAChC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,MAAM,EAAE,oBAAoB,EAC5B,gBAAgB,EAAE,gBAAgB,GAChC,OAAO,CAAC,8BAA8B,GAAG,SAAS,CAAC;CA2DtD"}