Support dynamic refresh

.eslintrc

@@ -40,5 +40,6 @@
                 "avoidEscape": true
             }
         ],
-    },
+        "@typescript-eslint/no-explicit-any": "off"
+    }
 }

examples/refresh.mjs

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as dotenv from "dotenv";
+import { promisify } from "util";
+dotenv.config();
+const sleepInMs = promisify(setTimeout);
+
+/**
+ * This example retrives all settings with key following pattern "app.settings.*", i.e. starting with "app.settings.".
+ * With the option `trimKeyPrefixes`, it trims the prefix "app.settings." from keys for simplicity.
+ * Value of config "app.settings.message" will be printed.
+ *
+ * Below environment variables are required for this example:
+ * - APPCONFIG_CONNECTION_STRING
+ */
+
+import { load } from "@azure/app-configuration-provider";
+const connectionString = process.env.APPCONFIG_CONNECTION_STRING;
+const settings = await load(connectionString, {
+    selectors: [{
+        keyFilter: "app.settings.*"
+    }],
+    trimKeyPrefixes: ["app.settings."],
+    refreshOptions: {
+        watchedSettings: [{ key: "app.settings.sentinel" }],
+        refreshIntervalInMs: 10 * 1000 // Default value is 30 seconds, shorted for this sample
+    }
+});
+
+console.log("Update the `message` in your App Configuration store using Azure portal or CLI.")
+console.log("First, update the `message` value, and then update the `sentinel` key value.")
+
+// eslint-disable-next-line no-constant-condition
+while (true) {
+    // Refreshing the configuration setting
+    await settings.refresh();
+
+    // Current value of message
+    console.log(settings.get("message"));
+
+    // Waiting before the next refresh
+    await sleepInMs(5000);
+}

src/AzureAppConfiguration.ts

@@ -1,6 +1,19 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+import { Disposable } from "./common/disposable";
+
 export type AzureAppConfiguration = {
-    // methods for advanced features, e.g. refresh()
-} & ReadonlyMap<string, unknown>;
+    /**
+     * API to trigger refresh operation.
+     */
+    refresh(): Promise<void>;
+
+    /**
+     * API to register callback listeners, which will be called only when a refresh operation successfully updates key-values.
+     *
+     * @param listener Callback funtion to be registered.
+     * @param thisArg Optional. Value to use as this when executing callback.
+     */
+    onRefresh(listener: () => any, thisArg?: any): Disposable;
+} & ReadonlyMap<string, any>;

src/AzureAppConfigurationImpl.ts

@@ -1,16 +1,19 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { AppConfigurationClient, ConfigurationSetting, ListConfigurationSettingsOptions } from "@azure/app-configuration";
+import { AppConfigurationClient, ConfigurationSetting, ConfigurationSettingId, ListConfigurationSettingsOptions } from "@azure/app-configuration";
 import { AzureAppConfiguration } from "./AzureAppConfiguration";
 import { AzureAppConfigurationOptions } from "./AzureAppConfigurationOptions";
 import { IKeyValueAdapter } from "./IKeyValueAdapter";
 import { JsonKeyValueAdapter } from "./JsonKeyValueAdapter";
 import { KeyFilter } from "./KeyFilter";
 import { LabelFilter } from "./LabelFilter";
 import { AzureKeyVaultKeyValueAdapter } from "./keyvault/AzureKeyVaultKeyValueAdapter";
-import { CorrelationContextHeaderName } from "./requestTracing/constants";
+import { CorrelationContextHeaderName, RequestType } from "./requestTracing/constants";
 import { createCorrelationContextHeader, requestTracingEnabled } from "./requestTracing/utils";
+import { DefaultRefreshIntervalInMs, MinimumRefreshIntervalInMs } from "./RefreshOptions";
+import { LinkedList } from "./common/linkedList";
+import { Disposable } from "./common/disposable";
 
 export class AzureAppConfigurationImpl extends Map<string, unknown> implements AzureAppConfiguration {
     private adapters: IKeyValueAdapter[] = [];
@@ -20,7 +23,11 @@ export class AzureAppConfigurationImpl extends Map<string, unknown> implements A
      */
     private sortedTrimKeyPrefixes: string[] | undefined;
     private readonly requestTracingEnabled: boolean;
-    private correlationContextHeader: string | undefined;
+    // Refresh
+    private refreshIntervalInMs: number | undefined;
+    private onRefreshListeners: LinkedList<() => any> | undefined;
+    private lastUpdateTimestamp: number;
+    private sentinels: ConfigurationSettingId[] | undefined;
 
     constructor(
         private client: AppConfigurationClient,
@@ -29,20 +36,41 @@ export class AzureAppConfigurationImpl extends Map<string, unknown> implements A
         super();
         // Enable request tracing if not opt-out
         this.requestTracingEnabled = requestTracingEnabled();
-        if (this.requestTracingEnabled) {
-            this.enableRequestTracing();
-        }
 
         if (options?.trimKeyPrefixes) {
             this.sortedTrimKeyPrefixes = [...options.trimKeyPrefixes].sort((a, b) => b.localeCompare(a));
         }
+
+        if (options?.refreshOptions) {
+            this.onRefreshListeners = new LinkedList();
+            this.refreshIntervalInMs = DefaultRefreshIntervalInMs;
+
+            const refreshIntervalInMs = this.options?.refreshOptions?.refreshIntervalInMs;
+            if (refreshIntervalInMs !== undefined) {
+                if (refreshIntervalInMs < MinimumRefreshIntervalInMs) {
+                    throw new Error(`The refresh interval time cannot be less than ${MinimumRefreshIntervalInMs} milliseconds.`);
+                } else {
+                    this.refreshIntervalInMs = refreshIntervalInMs;
+                }
+            }
+
+            this.sentinels = options.refreshOptions.watchedSettings?.map(setting => {
+                const key = setting.key;
+                const label = setting.label;
+                if (key.includes("*") || label?.includes("*")) {
+                    throw new Error("Wildcard key or label filters are not supported for refresh.");
+                }
+                return { key, label };
+            });
+        }
+
         // TODO: should add more adapters to process different type of values
         // feature flag, others
         this.adapters.push(new AzureKeyVaultKeyValueAdapter(options?.keyVaultOptions));
         this.adapters.push(new JsonKeyValueAdapter());
     }
 
-    public async load() {
+    public async load(requestType: RequestType = RequestType.Startup) {
         const keyValues: [key: string, value: unknown][] = [];
 
         // validate selectors
@@ -55,23 +83,80 @@ export class AzureAppConfigurationImpl extends Map<string, unknown> implements A
             };
             if (this.requestTracingEnabled) {
                 listOptions.requestOptions = {
-                    customHeaders: this.customHeaders()
+                    customHeaders: this.customHeaders(requestType)
                 }
             }
 
             const settings = this.client.listConfigurationSettings(listOptions);
 
             for await (const setting of settings) {
                 if (setting.key) {
-                    const [key, value] = await this.processAdapters(setting);
-                    const trimmedKey = this.keyWithPrefixesTrimmed(key);
-                    keyValues.push([trimmedKey, value]);
+                    const keyValuePair = await this.processKeyValues(setting);
+                    keyValues.push(keyValuePair);
+                }
+                // update etag of sentinels
+                const matchedSentinel = this.sentinels?.find(s => s.key === setting.key && (s.label ?? null) === setting.label); // Workaround: as undefined label represents the same with null.
+                if (matchedSentinel) {
+                    matchedSentinel.etag = setting.etag;
                 }
             }
         }
         for (const [k, v] of keyValues) {
             this.set(k, v);
         }
+        this.lastUpdateTimestamp = Date.now();
+    }
+
+    public async refresh(): Promise<void> {
+        // if no refreshOptions set, return
+        if (this.sentinels === undefined || this.sentinels.length === 0 || this.refreshIntervalInMs === undefined) {
+            return Promise.resolve();
+        }
+        // if still within refresh interval, return
+        const now = Date.now();
+        if (now < this.lastUpdateTimestamp + this.refreshIntervalInMs) {
+            return Promise.resolve();
+        }
+
+        // try refresh if any of watched settings is changed.
+        let needRefresh = false;
+        for (const sentinel of this.sentinels) {
+            const response = await this.client.getConfigurationSetting(sentinel, {
+                onlyIfChanged: true
+                // TODO: do we trace this request by adding custom headers?
+            });
+            if (response.statusCode !== 304) { // TODO: can be more robust, e.g. === 200?
+                // sentinel changed.
+                sentinel.etag = response.etag;// update etag of the sentinel
+                needRefresh = true;
+                break;
+            }
+        }
+        if (needRefresh) {
+            await this.load(RequestType.Watch);
+            // run callbacks in async
+            if (this.onRefreshListeners !== undefined) {
+                for (const listener of this.onRefreshListeners) {
+                    listener();
+                }
+            }
+        }
+    }
+
+    public onRefresh(listener: () => any, thisArg?: any): Disposable {
+        if (this.onRefreshListeners === undefined) {
+            // TODO: Add unit tests
+            throw new Error("Illegal operation because refreshOptions is not provided on loading.");
+        }
+        const boundedListener = listener.bind(thisArg);
+        const remove = this.onRefreshListeners.push(boundedListener);
+        return new Disposable(remove);
+    }
+
+    private async processKeyValues(setting: ConfigurationSetting<string>): Promise<[string, unknown]> {
+        const [key, value] = await this.processAdapters(setting);
+        const trimmedKey = this.keyWithPrefixesTrimmed(key);
+        return [trimmedKey, value];
     }
 
     private async processAdapters(setting: ConfigurationSetting<string>): Promise<[string, unknown]> {
@@ -94,17 +179,13 @@ export class AzureAppConfigurationImpl extends Map<string, unknown> implements A
         return key;
     }
 
-    private enableRequestTracing() {
-        this.correlationContextHeader = createCorrelationContextHeader(this.options);
-    }
-
-    private customHeaders() {
+    private customHeaders(requestType: RequestType) {
         if (!this.requestTracingEnabled) {
             return undefined;
         }
 
         const headers = {};
-        headers[CorrelationContextHeaderName] = this.correlationContextHeader;
+        headers[CorrelationContextHeaderName] = createCorrelationContextHeader(this.options, requestType);
         return headers;
     }
 }

src/AzureAppConfigurationOptions.ts

@@ -3,6 +3,7 @@
 
 import { AppConfigurationClientOptions } from "@azure/app-configuration";
 import { AzureAppConfigurationKeyVaultOptions } from "./keyvault/AzureAppConfigurationKeyVaultOptions";
+import { RefreshOptions } from "./RefreshOptions";
 
 export const MaxRetries = 2;
 export const MaxRetryDelayInMs = 60000;
@@ -31,4 +32,8 @@ export interface AzureAppConfigurationOptions {
     trimKeyPrefixes?: string[];
     clientOptions?: AppConfigurationClientOptions;
     keyVaultOptions?: AzureAppConfigurationKeyVaultOptions;
+    /**
+     * Specifies options for dynamic refresh key-values.
+     */
+    refreshOptions?: RefreshOptions;
 }

src/RefreshOptions.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { WatchedSetting } from "./WatchedSetting";
+
+export const DefaultRefreshIntervalInMs = 30 * 1000;
+export const MinimumRefreshIntervalInMs = 1 * 1000;
+
+export interface RefreshOptions {
+    /**
+     * Specifies the interval for refresh to really update the values.
+     * Default value is 30 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;
+
+    /**
+     * Specifies settings to be watched, to determine whether the provider triggers a refresh.
+     */
+    watchedSettings: WatchedSetting[];
+}

src/WatchedSetting.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+export interface WatchedSetting {
+    key: string;
+    label?: string;
+}

src/common/disposable.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+export class Disposable {
+    private disposed = false;
+    constructor(private callOnDispose: () => any) { }
+
+    dispose() {
+        if (!this.disposed) {
+            this.callOnDispose();
+        }
+        this.disposed = true;
+    }
+
+}