Support tag filter

package.json

@@ -55,7 +55,7 @@
     "uuid": "^9.0.1"
   },
   "dependencies": {
-    "@azure/app-configuration": "^1.6.1",
+    "@azure/app-configuration": "^1.8.0",
     "@azure/identity": "^4.2.1",
     "@azure/keyvault-secrets": "^4.7.0",
     "jsonc-parser": "^3.3.1"

src/AzureAppConfigurationImpl.ts

@@ -491,7 +491,8 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
                 if (selector.snapshotName === undefined) {
                     const listOptions: ListConfigurationSettingsOptions = {
                         keyFilter: selector.keyFilter,
-                        labelFilter: selector.labelFilter
+                        labelFilter: selector.labelFilter,
+                        tagsFilter: selector.tagFilters
                     };
                     const pageEtags: string[] = [];
                     const pageIterator = listConfigurationSettingsWithTrace(
@@ -727,6 +728,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
                 const listOptions: ListConfigurationSettingsOptions = {
                     keyFilter: selector.keyFilter,
                     labelFilter: selector.labelFilter,
+                    tagsFilter: selector.tagFilters,
                     pageEtags: selector.pageEtags
                 };
 
@@ -966,7 +968,11 @@ function getValidSettingSelectors(selectors: SettingSelector[]): SettingSelector
     // below code deduplicates selectors, the latter selector wins
     const uniqueSelectors: SettingSelector[] = [];
     for (const selector of selectors) {
-        const existingSelectorIndex = uniqueSelectors.findIndex(s => s.keyFilter === selector.keyFilter && s.labelFilter === selector.labelFilter && s.snapshotName === selector.snapshotName);
+        const existingSelectorIndex = uniqueSelectors.findIndex(
+            s => s.keyFilter === selector.keyFilter &&
+                s.labelFilter === selector.labelFilter &&
+                s.snapshotName === selector.snapshotName &&
+                areTagFiltersEqual(s.tagFilters, selector.tagFilters));
         if (existingSelectorIndex >= 0) {
             uniqueSelectors.splice(existingSelectorIndex, 1);
         }
@@ -976,8 +982,8 @@ function getValidSettingSelectors(selectors: SettingSelector[]): SettingSelector
     return uniqueSelectors.map(selectorCandidate => {
         const selector = { ...selectorCandidate };
         if (selector.snapshotName) {
-            if (selector.keyFilter || selector.labelFilter) {
-                throw new ArgumentError("Key or label filter should not be used for a snapshot.");
+            if (selector.keyFilter || selector.labelFilter || selector.tagFilters) {
+                throw new ArgumentError("Key, label or tag filters should not be specified while selecting a snapshot.");
             }
         } else {
             if (!selector.keyFilter) {
@@ -989,11 +995,31 @@ function getValidSettingSelectors(selectors: SettingSelector[]): SettingSelector
             if (selector.labelFilter.includes("*") || selector.labelFilter.includes(",")) {
                 throw new ArgumentError("The characters '*' and ',' are not supported in label filters.");
             }
+            if (selector.tagFilters) {
+                validateTagFilters(selector.tagFilters);
+            }
         }
         return selector;
     });
 }
 
+function areTagFiltersEqual(tagsA?: string[], tagsB?: string[]): boolean {
+    if (!tagsA && !tagsB) {
+        return true;
+    }
+    if (!tagsA || !tagsB) {
+        return false;
+    }
+    if (tagsA.length !== tagsB.length) {
+        return false;
+    }
+
+    const sortedStringA = [...tagsA].sort().join("\n");
+    const sortedStringB = [...tagsB].sort().join("\n");
+
+    return sortedStringA === sortedStringB;
+}
+
 function getValidKeyValueSelectors(selectors?: SettingSelector[]): SettingSelector[] {
     if (selectors === undefined || selectors.length === 0) {
         // Default selector: key: *, label: \0
@@ -1014,3 +1040,12 @@ function getValidFeatureFlagSelectors(selectors?: SettingSelector[]): SettingSel
     });
     return getValidSettingSelectors(selectors);
 }
+
+function validateTagFilters(tagFilters: string[]): void {
+    for (const tagFilter of tagFilters) {
+        const res = tagFilter.split("=");
+        if (res[0] === "" || res.length !== 2) {
+            throw new Error(`Invalid tag filter: ${tagFilter}. Tag filter must follow the format "tagName=tagValue".`);
+        }
+    }
+}

src/types.ts

@@ -30,6 +30,16 @@ export type SettingSelector = {
      */
     labelFilter?: string
 
+    /**
+     * The tag filter to apply when querying Azure App Configuration for key-values.
+     *
+     * @remarks
+     * Each tag filter must follow the format "tagName=tagValue". Only those key-values will be loaded whose tags match all the tags provided here.
+     * Built in tag filter value is `TagFilter.Null`, which indicates the tag has no value. For example, `tagName=${TagFilter.Null}` will match all key-values with the tag "tagName" that has no value.
+     * Up to 5 tag filters can be provided. If no tag filters are provided, key-values will not be filtered based on tags.
+     */
+    tagFilters?: string[]
+
     /**
      * The name of snapshot to load from App Configuration.
      *
@@ -59,3 +69,13 @@ export enum LabelFilter {
      */
     Null = "\0"
 }
+
+/**
+ * TagFilter is used to filter key-values based on tags.
+ */
+export enum TagFilter {
+    /**
+     * Represents empty tag value.
+     */
+    Null = ""
+}

test/featureFlag.test.ts

@@ -55,6 +55,9 @@ const mockedKVs = [{
     createMockedFeatureFlag("FlagWithTestLabel", { enabled: true }, {label: "Test"}),
     createMockedFeatureFlag("Alpha_1", { enabled: true }),
     createMockedFeatureFlag("Alpha_2", { enabled: false }),
+    createMockedFeatureFlag("DevFeatureFlag", { enabled: true }, { tags: { "environment": "dev" } }),
+    createMockedFeatureFlag("ProdFeatureFlag", { enabled: false }, { tags: { "environment": "prod" } }),
+    createMockedFeatureFlag("TaggedFeature", { enabled: true }, { tags: { "team": "backend", "priority": "high" } }),
     createMockedFeatureFlag("Telemetry_1", { enabled: true, telemetry: { enabled: true } }, { etag: "ETag"}),
     createMockedFeatureFlag("Telemetry_2", { enabled: true, telemetry: { enabled: true } }, { etag: "ETag", label: "Test"}),
     createMockedFeatureFlag("NoPercentileAndSeed", {
@@ -338,6 +341,78 @@ describe("feature flags", function () {
         expect(featureFlag.telemetry.metadata.FeatureFlagReference).equals(`${createMockedEndpoint()}/kv/.appconfig.featureflag/Telemetry_2?label=Test`);
     });
 
+    it("should load feature flags using tag filters", async () => {
+        const connectionString = createMockedConnectionString();
+
+        // Test filtering by environment=dev tag
+        const settingsWithDevTag = await load(connectionString, {
+            featureFlagOptions: {
+                enabled: true,
+                selectors: [{
+                    keyFilter: "*",
+                    tagFilters: ["environment=dev"]
+                }]
+            }
+        });
+
+        expect(settingsWithDevTag).not.undefined;
+        expect(settingsWithDevTag.get("feature_management")).not.undefined;
+        let featureFlags = settingsWithDevTag.get<any>("feature_management").feature_flags;
+        expect(featureFlags).not.undefined;
+        expect((featureFlags as []).length).equals(1);
+        expect(featureFlags[0].id).equals("DevFeatureFlag");
+        expect(featureFlags[0].enabled).equals(true);
+
+        // Test filtering by environment=prod tag
+        const settingsWithProdTag = await load(connectionString, {
+            featureFlagOptions: {
+                enabled: true,
+                selectors: [{
+                    keyFilter: "*",
+                    tagFilters: ["environment=prod"]
+                }]
+            }
+        });
+
+        featureFlags = settingsWithProdTag.get<any>("feature_management").feature_flags;
+        expect(featureFlags).not.undefined;
+        expect((featureFlags as []).length).equals(1);
+        expect(featureFlags[0].id).equals("ProdFeatureFlag");
+        expect(featureFlags[0].enabled).equals(false);
+
+        // Test filtering by multiple tags (team=backend AND priority=high)
+        const settingsWithMultipleTags = await load(connectionString, {
+            featureFlagOptions: {
+                enabled: true,
+                selectors: [{
+                    keyFilter: "*",
+                    tagFilters: ["team=backend", "priority=high"]
+                }]
+            }
+        });
+
+        featureFlags = settingsWithMultipleTags.get<any>("feature_management").feature_flags;
+        expect(featureFlags).not.undefined;
+        expect((featureFlags as []).length).equals(1);
+        expect(featureFlags[0].id).equals("TaggedFeature");
+        expect(featureFlags[0].enabled).equals(true);
+
+        // Test filtering by non-existent tag
+        const settingsWithNonExistentTag = await load(connectionString, {
+            featureFlagOptions: {
+                enabled: true,
+                selectors: [{
+                    keyFilter: "*",
+                    tagFilters: ["nonexistent=tag"]
+                }]
+            }
+        });
+
+        featureFlags = settingsWithNonExistentTag.get<any>("feature_management").feature_flags;
+        expect(featureFlags).not.undefined;
+        expect((featureFlags as []).length).equals(0);
+    });
+
     it("should load feature flags from snapshot", async () => {
         const snapshotName = "Test";
         mockAppConfigurationClientGetSnapshot(snapshotName, {compositionType: "key"});