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

src/AzureAppConfigurationImpl.ts

@@ -59,6 +59,8 @@ import { InvalidOperationError, ArgumentError, isFailoverableError, isInputError
 
 const MIN_DELAY_FOR_UNHANDLED_FAILURE = 5_000; // 5 seconds
 
+const MAX_TAG_FILTER_COUNT = 5;
+
 type PagedSettingSelector = SettingSelector & {
     /**
      * Key: page eTag, Value: feature flag configurations
@@ -476,7 +478,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(
@@ -693,6 +696,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
                 const listOptions: ListConfigurationSettingsOptions = {
                     keyFilter: selector.keyFilter,
                     labelFilter: selector.labelFilter,
+                    tagsFilter: selector.tagFilters,
                     pageEtags: selector.pageEtags
                 };
 
@@ -911,7 +915,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);
         }
@@ -921,24 +929,44 @@ 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 filter should not be used for a snapshot.");
             }
         } else {
-            if (!selector.keyFilter) {
-                throw new ArgumentError("Key filter cannot be null or empty.");
+            if (!selector.keyFilter && (!selector.tagFilters || selector.tagFilters.length === 0)) {
+                throw new ArgumentError("Key filter and tag filter cannot both be null or empty.");
             }
             if (!selector.labelFilter) {
                 selector.labelFilter = LabelFilter.Null;
             }
             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
@@ -959,3 +987,15 @@ function getValidFeatureFlagSelectors(selectors?: SettingSelector[]): SettingSel
     });
     return getValidSettingSelectors(selectors);
 }
+
+function validateTagFilters(tagFilters: string[]): void {
+    if (tagFilters.length > MAX_TAG_FILTER_COUNT) {
+        throw new Error(`The number of tag filters cannot exceed ${MAX_TAG_FILTER_COUNT}.`);
+    }
+    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/load.test.ts

@@ -29,10 +29,12 @@ const mockedKVs = [{
 }, {
     key: "TestKey",
     label: "Test",
+    tags: {"testTag": ""},
     value: "TestValue",
 }, {
     key: "TestKey",
     label: "Prod",
+    tags: {"testTag": ""},
     value: "TestValueForProd",
 }, {
     key: "KeyForNullValue",
@@ -73,6 +75,18 @@ const mockedKVs = [{
         }
     }),
     contentType: "application/vnd.microsoft.appconfig.ff+json;charset=utf-8"
+}, {
+    key: "keyWithMultipleTags",
+    value: "someValue",
+    tags: {"tag1": "someValue", "tag2": "someValue"}
+}, {
+    key: "keyWithTag1",
+    value: "someValue",
+    tags: {"tag1": "someValue"}
+}, {
+    key: "keyWithTag2",
+    value: "someValue",
+    tags: {"tag2": "someValue"}
 }
 ].map(createMockedKeyValue);
 
@@ -128,7 +142,7 @@ describe("load", function () {
             selectors: [{
                 labelFilter: "\0"
             }]
-        })).eventually.rejectedWith("Key filter cannot be null or empty.");
+        })).eventually.rejectedWith("Key filter and tag filter cannot both be null or empty.");
     });
 
     it("should throw error given invalid snapshot selector", async () => {
@@ -138,7 +152,7 @@ describe("load", function () {
                 snapshotName: "Test",
                 labelFilter: "\0"
             }]
-        })).eventually.rejectedWith("Key or label filter should not be used for a snapshot.");
+        })).eventually.rejectedWith("Key, label or tag filter should not be used for a snapshot.");
     });
 
     it("should not include feature flags directly in the settings", async () => {
@@ -165,6 +179,30 @@ describe("load", function () {
         expect(settings.get("app.settings.fontFamily")).undefined;
     });
 
+    it("should filter by tags, has(key) and get(key) should work", async () => {
+        const connectionString = createMockedConnectionString();
+        const loadWithTag1 = await load(connectionString, {
+            selectors: [{
+                tagFilters: ["tag1=someValue"]
+            }]
+        });
+        expect(loadWithTag1.has("keyWithTag1")).true;
+        expect(loadWithTag1.get("keyWithTag1")).eq("someValue");
+        expect(loadWithTag1.has("keyWithTag2")).false;
+        expect(loadWithTag1.has("keyWithMultipleTags")).true;
+        expect(loadWithTag1.get("keyWithMultipleTags")).eq("someValue");
+
+        const loadWithMultipleTags = await load(connectionString, {
+            selectors: [{
+                tagFilters: ["tag1=someValue", "tag2=someValue"]
+            }]
+        });
+        expect(loadWithMultipleTags.has("keyWithTag1")).false;
+        expect(loadWithMultipleTags.has("keyWithTag2")).false;
+        expect(loadWithMultipleTags.has("keyWithMultipleTags")).true;
+        expect(loadWithMultipleTags.get("keyWithMultipleTags")).eq("someValue");
+    });
+
     it("should also work with other ReadonlyMap APIs", async () => {
         const connectionString = createMockedConnectionString();
         const settings = await load(connectionString, {
@@ -274,6 +312,16 @@ describe("load", function () {
         return expect(loadWithMultipleLabelFilter).to.eventually.rejectedWith("The characters '*' and ',' are not supported in label filters.");
     });
 
+    it("should throw exception when there is any invalid tag filter", async () => {
+        const connectionString = createMockedConnectionString();
+        const loadWithInvalidTagFilter = load(connectionString, {
+            selectors: [{
+                tagFilters: ["testTag"]
+            }]
+        });
+        return expect(loadWithInvalidTagFilter).to.eventually.rejectedWith("Tag filter must follow the format \"tagName=tagValue\"");
+    });
+
     it("should override config settings with same key but different label", async () => {
         const connectionString = createMockedConnectionString();
         const settings = await load(connectionString, {
@@ -294,13 +342,15 @@ describe("load", function () {
         const settings = await load(connectionString, {
             selectors: [{
                 keyFilter: "Test*",
-                labelFilter: "Prod"
+                labelFilter: "Prod",
+                tagFilters: ["testTag="]
             }, {
                 keyFilter: "Test*",
                 labelFilter: "Test"
             }, {
                 keyFilter: "Test*",
-                labelFilter: "Prod"
+                labelFilter: "Prod",
+                tagFilters: ["testTag="]
             }]
         });
         expect(settings).not.undefined;

test/utils/testHelper.ts

@@ -26,6 +26,7 @@ function _sha256(input) {
 function _filterKVs(unfilteredKvs: ConfigurationSetting[], listOptions: any) {
     const keyFilter = listOptions?.keyFilter ?? "*";
     const labelFilter = listOptions?.labelFilter ?? "*";
+    const tagsFilter = listOptions?.tagsFilter ?? [];
     return unfilteredKvs.filter(kv => {
         const keyMatched = keyFilter.endsWith("*") ? kv.key.startsWith(keyFilter.slice(0, -1)) : kv.key === keyFilter;
         let labelMatched = false;
@@ -38,7 +39,14 @@ function _filterKVs(unfilteredKvs: ConfigurationSetting[], listOptions: any) {
         } else {
             labelMatched = kv.label === labelFilter;
         }
-        return keyMatched && labelMatched;
+        let tagsMatched = true;
+        if (tagsFilter.length > 0) {
+            tagsMatched = tagsFilter.every(tag => {
+                const [tagName, tagValue] = tag.split("=");
+                return kv.tags && kv.tags[tagName] === tagValue;
+            });
+        }
+        return keyMatched && labelMatched && tagsMatched;
     });
 }
 
@@ -233,8 +241,7 @@ const createMockedKeyVaultReference = (key: string, vaultUri: string): Configura
     key,
     contentType: "application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8",
     lastModified: new Date(),
-    tags: {
-    },
+    tags: {},
     etag: uuid.v4(),
     isReadOnly: false,
 });