support feature flags

src/AzureAppConfigurationImpl.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { AppConfigurationClient, ConfigurationSetting, ConfigurationSettingId, GetConfigurationSettingOptions, GetConfigurationSettingResponse, ListConfigurationSettingsOptions, isFeatureFlag } from "@azure/app-configuration";
+import { AppConfigurationClient, ConfigurationSetting, ConfigurationSettingId, FeatureFlagValue, GetConfigurationSettingOptions, GetConfigurationSettingResponse, ListConfigurationSettingsOptions, featureFlagPrefix, isFeatureFlag, parseFeatureFlag } from "@azure/app-configuration";
 import { RestError } from "@azure/core-rest-pipeline";
 import { AzureAppConfiguration, ConfigurationObjectConstructionOptions } from "./AzureAppConfiguration";
 import { AzureAppConfigurationOptions } from "./AzureAppConfigurationOptions";
@@ -14,6 +14,7 @@ import { RefreshTimer } from "./refresh/RefreshTimer";
 import { CorrelationContextHeaderName } from "./requestTracing/constants";
 import { createCorrelationContextHeader, requestTracingEnabled } from "./requestTracing/utils";
 import { KeyFilter, LabelFilter, SettingSelector } from "./types";
+import { featureFlagsKeyName, featureManagementKeyName } from "./featureManagement/constants";
 
 export class AzureAppConfigurationImpl implements AzureAppConfiguration {
     /**
@@ -41,6 +42,10 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
     #sentinels: ConfigurationSettingId[] = [];
     #refreshTimer: RefreshTimer;
 
+    // Feature flags
+    #featureFlagRefreshInterval: number = DefaultRefreshIntervalInMs;
+    #featureFlagRefreshTimer: RefreshTimer;
+
     constructor(
         client: AppConfigurationClient,
         options: AzureAppConfigurationOptions | undefined
@@ -85,13 +90,27 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
             this.#refreshTimer = new RefreshTimer(this.#refreshInterval);
         }
 
-        // TODO: should add more adapters to process different type of values
-        // feature flag, others
+        // feature flag options
+        if (options?.featureFlagOptions?.enabled && options.featureFlagOptions.refresh?.enabled) {
+            const { refreshIntervalInMs } = options.featureFlagOptions.refresh;
+
+            // custom refresh interval
+            if (refreshIntervalInMs !== undefined) {
+                if (refreshIntervalInMs < MinimumRefreshIntervalInMs) {
+                    throw new Error(`The feature flag refresh interval cannot be less than ${MinimumRefreshIntervalInMs} milliseconds.`);
+                } else {
+                    this.#featureFlagRefreshInterval = refreshIntervalInMs;
+                }
+            }
+
+            this.#featureFlagRefreshTimer = new RefreshTimer(this.#featureFlagRefreshInterval);
+        }
+
         this.#adapters.push(new AzureKeyVaultKeyValueAdapter(options?.keyVaultOptions));
         this.#adapters.push(new JsonKeyValueAdapter());
     }
 
-    // ReadonlyMap APIs
+    // #region ReadonlyMap APIs
     get<T>(key: string): T | undefined {
         return this.#configMap.get(key);
     }
@@ -123,11 +142,20 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
     [Symbol.iterator](): IterableIterator<[string, any]> {
         return this.#configMap[Symbol.iterator]();
     }
+    // #endregion
 
     get #refreshEnabled(): boolean {
         return !!this.#options?.refreshOptions?.enabled;
     }
 
+    get #featureFlagEnabled(): boolean {
+        return !!this.#options?.featureFlagOptions?.enabled;
+    }
+
+    get #featureFlagRefreshEnabled(): boolean {
+        return this.#featureFlagEnabled && !!this.#options?.featureFlagOptions?.refresh?.enabled;
+    }
+
     async #loadSelectedKeyValues(): Promise<ConfigurationSetting[]> {
         const loadedSettings: ConfigurationSetting[] = [];
 
@@ -195,17 +223,58 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
             keyValues.push([key, value]);
         }
 
-        this.#configMap.clear(); // clear existing key-values in case of configuration setting deletion
+        this.#clearLoadedKeyValues(); // clear existing key-values in case of configuration setting deletion
         for (const [k, v] of keyValues) {
             this.#configMap.set(k, v);
         }
     }
 
+    async #clearLoadedKeyValues() {
+        for(const key of this.#configMap.keys()) {
+            if (key !== featureManagementKeyName) {
+                this.#configMap.delete(key);
+            }
+        }
+    }
+
+    async #loadFeatureFlags() {
+        const featureFlags: FeatureFlagValue[] = [];
+        const featureFlagSelectors = getValidSelectors(this.#options?.featureFlagOptions?.selectors);
+        for (const selector of featureFlagSelectors) {
+            const listOptions: ListConfigurationSettingsOptions = {
+                keyFilter: `${featureFlagPrefix}${selector.keyFilter}`,
+                labelFilter: selector.labelFilter
+            };
+            if (this.#requestTracingEnabled) {
+                listOptions.requestOptions = {
+                    customHeaders: {
+                        [CorrelationContextHeaderName]: createCorrelationContextHeader(this.#options, this.#isInitialLoadCompleted)
+                    }
+                }
+            }
+
+            const settings = this.#client.listConfigurationSettings(listOptions);
+
+            for await (const setting of settings) {
+                if (isFeatureFlag(setting)) {
+                    const flag = parseFeatureFlag(setting);
+                    featureFlags.push(flag.value)
+                }
+            }
+        }
+
+        // feature_management is a reserved key, and feature_flags is an array of feature flags
+        this.#configMap.set(featureManagementKeyName, { [featureFlagsKeyName]: featureFlags });
+    }
+
     /**
      * Load the configuration store for the first time.
      */
     async load() {
         await this.#loadSelectedAndWatchedKeyValues();
+        if (this.#featureFlagEnabled) {
+            await this.#loadFeatureFlags();
+        }
         // Mark all settings have loaded at startup.
         this.#isInitialLoadCompleted = true;
     }
@@ -257,10 +326,19 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
      * Refresh the configuration store.
      */
     async refresh(): Promise<void> {
-        if (!this.#refreshEnabled) {
-            throw new Error("Refresh is not enabled.");
+        if (!this.#refreshEnabled && !this.#featureFlagRefreshEnabled) {
+            throw new Error("Refresh is not enabled for key-values and feature flags.");
         }
 
+        if (this.#refreshEnabled) {
+            await this.#refreshKeyValues();
+        }
+        if (this.#featureFlagRefreshEnabled) {
+            await this.#refreshFeatureFlags();
+        }
+    }
+
+    async #refreshKeyValues(): Promise<void> {
         // if still within refresh interval/backoff, return
         if (!this.#refreshTimer.canRefresh()) {
             return Promise.resolve();
@@ -298,9 +376,25 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
         }
     }
 
+    async #refreshFeatureFlags(): Promise<void> {
+        // if still within refresh interval/backoff, return
+        if (!this.#featureFlagRefreshTimer.canRefresh()) {
+            return Promise.resolve();
+        }
+
+        try {
+            await this.#loadFeatureFlags();
+            this.#featureFlagRefreshTimer.reset();
+        } catch (error) {
+            // if refresh failed, backoff
+            this.#featureFlagRefreshTimer.backoff();
+            throw error;
+        }
+    }
+
     onRefresh(listener: () => any, thisArg?: any): Disposable {
         if (!this.#refreshEnabled) {
-            throw new Error("Refresh is not enabled.");
+            throw new Error("Refresh is not enabled for key-values.");
         }
 
         const boundedListener = listener.bind(thisArg);

src/AzureAppConfigurationOptions.ts

@@ -5,6 +5,7 @@ import { AppConfigurationClientOptions } from "@azure/app-configuration";
 import { KeyVaultOptions } from "./keyvault/KeyVaultOptions";
 import { RefreshOptions } from "./RefreshOptions";
 import { SettingSelector } from "./types";
+import { FeatureFlagOptions } from "./featureManagement/FeatureFlagOptions";
 
 export const MaxRetries = 2;
 export const MaxRetryDelayInMs = 60000;
@@ -36,8 +37,14 @@ export interface AzureAppConfigurationOptions {
      * Specifies options used to resolve Vey Vault references.
      */
     keyVaultOptions?: KeyVaultOptions;
+
     /**
      * Specifies options for dynamic refresh key-values.
      */
     refreshOptions?: RefreshOptions;
+
+    /**
+     * Specifies options used to configure feature flags.
+     */
+    featureFlagOptions?: FeatureFlagOptions;
 }

src/RefreshOptions.ts

@@ -25,3 +25,17 @@ export interface RefreshOptions {
      */
     watchedSettings?: WatchedSetting[];
 }
+
+export interface FeatureFlagRefreshOptions {
+    /**
+     * Specifies whether the provider should automatically refresh when the configuration is changed.
+     */
+    enabled: boolean;
+
+    /**
+     * Specifies the minimum time that must elapse before checking the server for any new changes.
+     * Default value is 10 seconds. Must be greater than 1 second.
+     * Any refresh operation triggered will not update the value for a key until after the interval.
+     */
+    refreshIntervalInMs?: number;
+}

src/featureManagement/FeatureFlagOptions.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { FeatureFlagRefreshOptions } from "../RefreshOptions";
+import { SettingSelector } from "../types";
+
+/**
+ * Options used to configure feature flags.
+ */
+export interface FeatureFlagOptions {
+    /**
+     * Specifies whether feature flag support is enabled.
+     */
+    enabled: boolean;
+
+    /**
+     * Specifies the selectors used to filter feature flags.
+     *
+     * @remarks
+     * keyFilter of selector will be prefixed with "appconfig.featureflag/" when request is sent.
+     * If no selectors are specified then no feature flags will be retrieved.
+     */
+    selectors?: SettingSelector[];
+
+    /**
+     * Specifies how feature flag refresh is configured. All selected feature flags will be watched for changes.
+     */
+    refresh?: FeatureFlagRefreshOptions;
+}

src/featureManagement/constants.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+export const featureManagementKeyName = "feature_management";
+export const featureFlagsKeyName = "feature_flags";

test/featureFlag.test.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as chai from "chai";
+import * as chaiAsPromised from "chai-as-promised";
+import { load } from "./exportedApi";
+import { createMockedConnectionString, createMockedFeatureFlag, createMockedKeyValue, mockAppConfigurationClientListConfigurationSettings, restoreMocks } from "./utils/testHelper";
+chai.use(chaiAsPromised);
+const expect = chai.expect;
+
+const mockedKVs = [{
+    key: "app.settings.fontColor",
+    value: "red",
+}].map(createMockedKeyValue).concat([
+    createMockedFeatureFlag("Beta", true),
+    createMockedFeatureFlag("Alpha_1", true),
+    createMockedFeatureFlag("Alpha2", false),
+]);
+
+describe("feature flags", function () {
+    this.timeout(10000);
+
+    before(() => {
+        mockAppConfigurationClientListConfigurationSettings(mockedKVs);
+    });
+
+    after(() => {
+        restoreMocks();
+    })
+    it("should load feature flags if enabled", async () => {
+        const connectionString = createMockedConnectionString();
+        const settings = await load(connectionString, {
+            featureFlagOptions: {
+                enabled: true
+            }
+        });
+        expect(settings).not.undefined;
+        expect(settings.get("feature_management")).not.undefined;
+        expect(settings.get<any>("feature_management").feature_flags).not.undefined;
+    });
+
+    it("should not load feature flags if disabled", async () => {
+        const connectionString = createMockedConnectionString();
+        const settings = await load(connectionString, {
+            featureFlagOptions: {
+                enabled: false
+            }
+        });
+        expect(settings).not.undefined;
+        expect(settings.get("feature_management")).undefined;
+    });
+
+    it("should not load feature flags if not specified", async () => {
+        const connectionString = createMockedConnectionString();
+        const settings = await load(connectionString);
+        expect(settings).not.undefined;
+        expect(settings.get("feature_management")).undefined;
+    });
+
+    it("should load feature flags with custom selector", async () => {
+        const connectionString = createMockedConnectionString();
+        const settings = await load(connectionString, {
+            featureFlagOptions: {
+                enabled: true,
+                selectors: [{
+                    keyFilter: "Alpha*"
+                }]
+            }
+        });
+        expect(settings).not.undefined;
+        expect(settings.get("feature_management")).not.undefined;
+        const featureFlags = settings.get<any>("feature_management").feature_flags;
+        expect(featureFlags).not.undefined;
+        expect((featureFlags as []).length).equals(2);
+    });
+
+});