Support tag filter

package.json

@@ -25,7 +25,7 @@
     "dev": "rollup --config --watch",
     "lint": "eslint src/ test/",
     "fix-lint": "eslint src/ test/ --fix",
-    "test": "mocha out/test/load.test.{js,cjs,mjs} --parallel"
+    "test": "mocha out/test/*.test.{js,cjs,mjs} --parallel"
   },
   "repository": {
     "type": "git",

src/AzureAppConfigurationImpl.ts

@@ -395,6 +395,9 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
                     if (isInputError(error)) {
                         throw error;
                     }
+                    if (isRestError(error) && !isFailoverableError(error)) {
+                        throw error;
+                    }
                     if (abortSignal.aborted) {
                         return;
                     }

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"});

test/load.test.ts

@@ -81,12 +81,24 @@ const mockedKVs = [{
     tags: {"tag1": "someValue", "tag2": "someValue"}
 }, {
     key: "keyWithTag1",
-    value: "someValue",
+    value: "someValue1",
     tags: {"tag1": "someValue"}
 }, {
     key: "keyWithTag2",
-    value: "someValue",
+    value: "someValue2",
     tags: {"tag2": "someValue"}
+}, {
+    key: "keyWithNullTag",
+    value: "valueWithNullTag",
+    tags: {"nullTag": "\0"}
+}, {
+    key: "keyWithEscapedComma",
+    value: "valueWithEscapedComma",
+    tags: {"tag": "value\\,with\\,commas"}
+}, {
+    key: "keyWithEmptyTag",
+    value: "valueWithEmptyTag",
+    tags: {"emptyTag": ""}
 }
 ].map(createMockedKeyValue);
 
@@ -188,7 +200,7 @@ describe("load", function () {
             }]
         });
         expect(loadWithTag1.has("keyWithTag1")).true;
-        expect(loadWithTag1.get("keyWithTag1")).eq("someValue");
+        expect(loadWithTag1.get("keyWithTag1")).eq("someValue1");
         expect(loadWithTag1.has("keyWithTag2")).false;
         expect(loadWithTag1.has("keyWithMultipleTags")).true;
         expect(loadWithTag1.get("keyWithMultipleTags")).eq("someValue");
@@ -205,6 +217,53 @@ describe("load", function () {
         expect(loadWithMultipleTags.get("keyWithMultipleTags")).eq("someValue");
     });
 
+    it("should filter by nullTag to load key values with null tag", async () => {
+        const connectionString = createMockedConnectionString();
+        const loadWithNullTag = await load(connectionString, {
+            selectors: [{
+                keyFilter: "*",
+                tagFilters: ["nullTag=\0"]
+            }]
+        });
+
+        // Should include only key values with nullTag=\0
+        expect(loadWithNullTag.has("keyWithNullTag")).true;
+        expect(loadWithNullTag.get("keyWithNullTag")).eq("valueWithNullTag");
+
+        // Should exclude key values with other tags
+        expect(loadWithNullTag.has("keyWithEmptyTag")).false;
+    });
+
+    it("should filter by tags with escaped comma characters", async () => {
+        const connectionString = createMockedConnectionString();
+        const loadWithEscapedComma = await load(connectionString, {
+            selectors: [{
+                keyFilter: "*",
+                tagFilters: ["tag=value\\,with\\,commas"]
+            }]
+        });
+
+        expect(loadWithEscapedComma.has("keyWithEscapedComma")).true;
+        expect(loadWithEscapedComma.get("keyWithEscapedComma")).eq("valueWithEscapedComma");
+    });
+
+    it("should filter by empty tag value to load key values with empty tag", async () => {
+        const connectionString = createMockedConnectionString();
+        const loadWithEmptyTag = await load(connectionString, {
+            selectors: [{
+                keyFilter: "*",
+                tagFilters: ["emptyTag="]
+            }]
+        });
+
+        // Should include key values with emptyTag=""
+        expect(loadWithEmptyTag.has("keyWithEmptyTag")).true;
+        expect(loadWithEmptyTag.get("keyWithEmptyTag")).eq("valueWithEmptyTag");
+
+        // Should exclude key values with other tags
+        expect(loadWithEmptyTag.has("keyWithNullTag")).false;
+    });
+
     it("should also work with other ReadonlyMap APIs", async () => {
         const connectionString = createMockedConnectionString();
         const settings = await load(connectionString, {
@@ -319,12 +378,40 @@ describe("load", function () {
         const loadWithInvalidTagFilter = load(connectionString, {
             selectors: [{
                 keyFilter: "*",
-                tagFilters: ["testTag"]
+                tagFilters: ["emptyTag"]
             }]
         });
         return expect(loadWithInvalidTagFilter).to.eventually.rejectedWith("Tag filter must follow the format \"tagName=tagValue\"");
     });
 
+    it("should throw exception when too many tag filters are provided", async () => {
+        const connectionString = createMockedConnectionString();
+
+        // Create a list with more than the maximum allowed tag filters (assuming max is 5)
+        const tooManyTagFilters = [
+            "Environment=Development",
+            "Team=Backend",
+            "Priority=High",
+            "Version=1.0",
+            "Stage=Testing",
+            "Region=EastUS" // This should exceed the limit
+        ];
+        try {
+            await load(connectionString, {
+                selectors: [{
+                    keyFilter: "*",
+                    tagFilters: tooManyTagFilters
+                }]
+            });
+        } catch (error) {
+            expect(error.message).eq("Failed to load.");
+            expect(error.cause.message).eq("Invalid request parameter 'tags'. Maximum number of tag filters is 5.");
+            return;
+        }
+        // we should never reach here, load should throw an error
+        throw new Error("Expected load to throw.");
+    });
+
     it("should override config settings with same key but different label", async () => {
         const connectionString = createMockedConnectionString();
         const settings = await load(connectionString, {

test/refresh.test.ts

@@ -39,7 +39,8 @@ describe("dynamic refresh", function () {
         mockedKVs = [
             { value: "red", key: "app.settings.fontColor" },
             { value: "40", key: "app.settings.fontSize" },
-            { value: "30", key: "app.settings.fontSize", label: "prod" }
+            { value: "30", key: "app.settings.fontSize", label: "prod" },
+            { value: "someValue", key: "TestTagKey", tags: { "env": "dev" } }
         ].map(createMockedKeyValue);
         mockAppConfigurationClientListConfigurationSettings([mockedKVs], listKvCallback);
         mockAppConfigurationClientGetConfigurationSetting(mockedKVs, getKvCallback);
@@ -435,6 +436,34 @@ describe("dynamic refresh", function () {
         expect(getKvRequestCount).eq(1);
         expect(settings.get("app.settings.fontColor")).eq("blue");
     });
+
+    it("should refresh key values using tag filters", async () => {
+        const connectionString = createMockedConnectionString();
+        const settings = await load(connectionString, {
+            selectors: [{
+                keyFilter: "*",
+                tagFilters: ["env=dev"]
+            }],
+            refreshOptions: {
+                enabled: true,
+                refreshIntervalInMs: 2000
+            }
+        });
+
+        expect(settings).not.undefined;
+
+        // Verify only dev-tagged items are loaded
+        expect(settings.get("TestTagKey")).eq("someValue");
+
+        // Change the dev-tagged key value
+        updateSetting("TestTagKey", "newValue");
+
+        await sleepInMs(2 * 1000 + 1);
+        await settings.refresh();
+
+        // Verify changes are reflected
+        expect(settings.get("TestTagKey")).eq("newValue");
+    });
 });
 
 describe("dynamic refresh feature flags", function () {
@@ -549,4 +578,50 @@ describe("dynamic refresh feature flags", function () {
         expect(getKvRequestCount).eq(0);
         expect(refreshSuccessfulCount).eq(1); // change in feature flags, because page etags are different.
     });
+
+    it("should refresh feature flags using tag filters", async () => {
+        mockedKVs = [
+            createMockedFeatureFlag("DevFeature", { enabled: true }, { tags: { "env": "dev" } }),
+            createMockedFeatureFlag("ProdFeature", { enabled: false }, { tags: { "env": "prod" } })
+        ];
+        mockAppConfigurationClientListConfigurationSettings([mockedKVs], listKvCallback);
+        mockAppConfigurationClientGetConfigurationSetting(mockedKVs, getKvCallback);
+
+        const connectionString = createMockedConnectionString();
+        const settings = await load(connectionString, {
+            featureFlagOptions: {
+                enabled: true,
+                selectors: [{
+                    keyFilter: "*",
+                    tagFilters: ["env=dev"]
+                }],
+                refresh: {
+                    enabled: true,
+                    refreshIntervalInMs: 2000
+                }
+            }
+        });
+
+        expect(settings).not.undefined;
+
+        const featureManagement = settings.get<any>("feature_management");
+        expect(featureManagement).not.undefined;
+        expect(featureManagement.feature_flags).not.undefined;
+        expect(featureManagement.feature_flags.length).eq(1);
+        expect(featureManagement.feature_flags[0].id).eq("DevFeature");
+        expect(featureManagement.feature_flags[0].enabled).eq(true);
+
+        // Change the dev-tagged feature flag
+        updateSetting(".appconfig.featureflag/DevFeature", JSON.stringify({
+            "id": "DevFeature",
+            "enabled": false
+        }));
+
+        await sleepInMs(2 * 1000 + 1);
+        await settings.refresh();
+
+        const updatedFeatureManagement = settings.get<any>("feature_management");
+        expect(updatedFeatureManagement.feature_flags[0].id).eq("DevFeature");
+        expect(updatedFeatureManagement.feature_flags[0].enabled).eq(false);
+    });
 });

test/utils/testHelper.ts

@@ -27,6 +27,11 @@ function _filterKVs(unfilteredKvs: ConfigurationSetting[], listOptions: any) {
     const keyFilter = listOptions?.keyFilter ?? "*";
     const labelFilter = listOptions?.labelFilter ?? "*";
     const tagsFilter = listOptions?.tagsFilter ?? [];
+
+    if (tagsFilter.length > 5) {
+        throw new RestError("Invalid request parameter 'tags'. Maximum number of tag filters is 5.", { statusCode: 400 });
+    }
+
     return unfilteredKvs.filter(kv => {
         const keyMatched = keyFilter.endsWith("*") ? kv.key.startsWith(keyFilter.slice(0, -1)) : kv.key === keyFilter;
         let labelMatched = false;