Merge branch 'main' into zhiyuanliang/secret-refresh

zhiyuanliang-ms · web-flow · commit 027faa25713a · 2025-07-02T10:25:46.000+08:00
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@azure/app-configuration-provider",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "The JavaScript configuration provider for Azure App Configuration",
   "main": "dist/index.js",
   "module": "./dist-esm/index.js",
diff --git a/src/AzureAppConfigurationImpl.ts b/src/AzureAppConfigurationImpl.ts
@@ -1,7 +1,20 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { AppConfigurationClient, ConfigurationSetting, ConfigurationSettingId, GetConfigurationSettingOptions, GetConfigurationSettingResponse, ListConfigurationSettingsOptions, featureFlagPrefix, isFeatureFlag, isSecretReference } from "@azure/app-configuration";
+import {
+    AppConfigurationClient,
+    ConfigurationSetting,
+    ConfigurationSettingId,
+    GetConfigurationSettingOptions,
+    GetConfigurationSettingResponse,
+    ListConfigurationSettingsOptions,
+    featureFlagPrefix,
+    isFeatureFlag,
+    isSecretReference,
+    GetSnapshotOptions,
+    GetSnapshotResponse,
+    KnownSnapshotComposition
+} from "@azure/app-configuration";
 import { isRestError } from "@azure/core-rest-pipeline";
 import { AzureAppConfiguration, ConfigurationObjectConstructionOptions } from "./AzureAppConfiguration.js";
 import { AzureAppConfigurationOptions } from "./AzureAppConfigurationOptions.js";
@@ -30,7 +43,14 @@ import { FM_PACKAGE_NAME, AI_MIME_PROFILE, AI_CHAT_COMPLETION_MIME_PROFILE } fro
 import { parseContentType, isJsonContentType, isFeatureFlagContentType, isSecretReferenceContentType } from "./common/contentType.js";
 import { AzureKeyVaultKeyValueAdapter } from "./keyvault/AzureKeyVaultKeyValueAdapter.js";
 import { RefreshTimer } from "./refresh/RefreshTimer.js";
-import { RequestTracingOptions, getConfigurationSettingWithTrace, listConfigurationSettingsWithTrace, requestTracingEnabled } from "./requestTracing/utils.js";
+import {
+    RequestTracingOptions,
+    getConfigurationSettingWithTrace,
+    listConfigurationSettingsWithTrace,
+    getSnapshotWithTrace,
+    listConfigurationSettingsForSnapshotWithTrace,
+    requestTracingEnabled
+} from "./requestTracing/utils.js";
 import { FeatureFlagTracingOptions } from "./requestTracing/FeatureFlagTracingOptions.js";
 import { AIConfigurationTracingOptions } from "./requestTracing/AIConfigurationTracingOptions.js";
 import { KeyFilter, LabelFilter, SettingSelector } from "./types.js";
@@ -41,9 +61,6 @@ import { InvalidOperationError, ArgumentError, isFailoverableError, isInputError
 const MIN_DELAY_FOR_UNHANDLED_FAILURE = 5_000; // 5 seconds
 
 type PagedSettingSelector = SettingSelector & {
-    /**
-     * Key: page eTag, Value: feature flag configurations
-     */
     pageEtags?: string[];
 };
 
@@ -468,26 +485,49 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
             );
 
             for (const selector of selectorsToUpdate) {
-                const listOptions: ListConfigurationSettingsOptions = {
-                    keyFilter: selector.keyFilter,
-                    labelFilter: selector.labelFilter
-                };
-
-                const pageEtags: string[] = [];
-                const pageIterator = listConfigurationSettingsWithTrace(
-                    this.#requestTraceOptions,
-                    client,
-                    listOptions
-                ).byPage();
-                for await (const page of pageIterator) {
-                    pageEtags.push(page.etag ?? "");
-                    for (const setting of page.items) {
-                        if (loadFeatureFlag === isFeatureFlag(setting)) {
-                            loadedSettings.push(setting);
+                if (selector.snapshotName === undefined) {
+                    const listOptions: ListConfigurationSettingsOptions = {
+                        keyFilter: selector.keyFilter,
+                        labelFilter: selector.labelFilter
+                    };
+                    const pageEtags: string[] = [];
+                    const pageIterator = listConfigurationSettingsWithTrace(
+                        this.#requestTraceOptions,
+                        client,
+                        listOptions
+                    ).byPage();
+
+                    for await (const page of pageIterator) {
+                        pageEtags.push(page.etag ?? "");
+                        for (const setting of page.items) {
+                            if (loadFeatureFlag === isFeatureFlag(setting)) {
+                                loadedSettings.push(setting);
+                            }
+                        }
+                    }
+                    selector.pageEtags = pageEtags;
+                } else { // snapshot selector
+                    const snapshot = await this.#getSnapshot(selector.snapshotName);
+                    if (snapshot === undefined) {
+                        throw new InvalidOperationError(`Could not find snapshot with name ${selector.snapshotName}.`);
+                    }
+                    if (snapshot.compositionType != KnownSnapshotComposition.Key) {
+                        throw new InvalidOperationError(`Composition type for the selected snapshot with name ${selector.snapshotName} must be 'key'.`);
+                    }
+                    const pageIterator = listConfigurationSettingsForSnapshotWithTrace(
+                        this.#requestTraceOptions,
+                        client,
+                        selector.snapshotName
+                    ).byPage();
+
+                    for await (const page of pageIterator) {
+                        for (const setting of page.items) {
+                            if (loadFeatureFlag === isFeatureFlag(setting)) {
+                                loadedSettings.push(setting);
+                            }
                         }
                     }
                 }
-                selector.pageEtags = pageEtags;
             }
 
             if (loadFeatureFlag) {
@@ -678,6 +718,9 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
     async #checkConfigurationSettingsChange(selectors: PagedSettingSelector[]): Promise<boolean> {
         const funcToExecute = async (client) => {
             for (const selector of selectors) {
+                if (selector.snapshotName) { // skip snapshot selector
+                    continue;
+                }
                 const listOptions: ListConfigurationSettingsOptions = {
                     keyFilter: selector.keyFilter,
                     labelFilter: selector.labelFilter,
@@ -729,6 +772,29 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
         return response;
     }
 
+    async #getSnapshot(snapshotName: string, customOptions?: GetSnapshotOptions): Promise<GetSnapshotResponse | undefined> {
+        const funcToExecute = async (client) => {
+            return getSnapshotWithTrace(
+                this.#requestTraceOptions,
+                client,
+                snapshotName,
+                customOptions
+            );
+        };
+
+        let response: GetSnapshotResponse | undefined;
+        try {
+            response = await this.#executeWithFailoverPolicy(funcToExecute);
+        } catch (error) {
+            if (isRestError(error) && error.statusCode === 404) {
+                response = undefined;
+            } else {
+                throw error;
+            }
+        }
+        return response;
+    }
+
     // Only operations related to Azure App Configuration should be executed with failover policy.
     async #executeWithFailoverPolicy(funcToExecute: (client: AppConfigurationClient) => Promise<any>): Promise<any> {
         let clientWrappers = await this.#clientManager.getClients();
@@ -893,11 +959,11 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
     }
 }
 
-function getValidSelectors(selectors: SettingSelector[]): SettingSelector[] {
-    // below code deduplicates selectors by keyFilter and labelFilter, the latter selector wins
+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);
+        const existingSelectorIndex = uniqueSelectors.findIndex(s => s.keyFilter === selector.keyFilter && s.labelFilter === selector.labelFilter && s.snapshotName === selector.snapshotName);
         if (existingSelectorIndex >= 0) {
             uniqueSelectors.splice(existingSelectorIndex, 1);
         }
@@ -906,14 +972,20 @@ function getValidSelectors(selectors: SettingSelector[]): SettingSelector[] {
 
     return uniqueSelectors.map(selectorCandidate => {
         const selector = { ...selectorCandidate };
-        if (!selector.keyFilter) {
-            throw new ArgumentError("Key filter cannot 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.snapshotName) {
+            if (selector.keyFilter || selector.labelFilter) {
+                throw new ArgumentError("Key or label filter should not be used for a snapshot.");
+            }
+        } else {
+            if (!selector.keyFilter) {
+                throw new ArgumentError("Key filter cannot 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.");
+            }
         }
         return selector;
     });
@@ -924,7 +996,7 @@ function getValidKeyValueSelectors(selectors?: SettingSelector[]): SettingSelect
         // Default selector: key: *, label: \0
         return [{ keyFilter: KeyFilter.Any, labelFilter: LabelFilter.Null }];
     }
-    return getValidSelectors(selectors);
+    return getValidSettingSelectors(selectors);
 }
 
 function getValidFeatureFlagSelectors(selectors?: SettingSelector[]): SettingSelector[] {
@@ -933,7 +1005,9 @@ function getValidFeatureFlagSelectors(selectors?: SettingSelector[]): SettingSel
         return [{ keyFilter: `${featureFlagPrefix}${KeyFilter.Any}`, labelFilter: LabelFilter.Null }];
     }
     selectors.forEach(selector => {
-        selector.keyFilter = `${featureFlagPrefix}${selector.keyFilter}`;
+        if (selector.keyFilter) {
+            selector.keyFilter = `${featureFlagPrefix}${selector.keyFilter}`;
+        }
     });
-    return getValidSelectors(selectors);
+    return getValidSettingSelectors(selectors);
 }
diff --git a/src/requestTracing/utils.ts b/src/requestTracing/utils.ts
@@ -1,7 +1,8 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { AppConfigurationClient, ConfigurationSettingId, GetConfigurationSettingOptions, ListConfigurationSettingsOptions } from "@azure/app-configuration";
+import { OperationOptions } from "@azure/core-client";
+import { AppConfigurationClient, ConfigurationSettingId, GetConfigurationSettingOptions, ListConfigurationSettingsOptions, GetSnapshotOptions, ListConfigurationSettingsForSnapshotOptions } from "@azure/app-configuration";
 import { AzureAppConfigurationOptions } from "../AzureAppConfigurationOptions.js";
 import { FeatureFlagTracingOptions } from "./FeatureFlagTracingOptions.js";
 import { AIConfigurationTracingOptions } from "./AIConfigurationTracingOptions.js";
@@ -53,15 +54,7 @@ export function listConfigurationSettingsWithTrace(
     client: AppConfigurationClient,
     listOptions: ListConfigurationSettingsOptions
 ) {
-    const actualListOptions = { ...listOptions };
-    if (requestTracingOptions.enabled) {
-        actualListOptions.requestOptions = {
-            customHeaders: {
-                [CORRELATION_CONTEXT_HEADER_NAME]: createCorrelationContextHeader(requestTracingOptions)
-            }
-        };
-    }
-
+    const actualListOptions = applyRequestTracing(requestTracingOptions, listOptions);
     return client.listConfigurationSettings(actualListOptions);
 }
 
@@ -71,20 +64,43 @@ export function getConfigurationSettingWithTrace(
     configurationSettingId: ConfigurationSettingId,
     getOptions?: GetConfigurationSettingOptions,
 ) {
-    const actualGetOptions = { ...getOptions };
+    const actualGetOptions = applyRequestTracing(requestTracingOptions, getOptions);
+    return client.getConfigurationSetting(configurationSettingId, actualGetOptions);
+}
+
+export function getSnapshotWithTrace(
+    requestTracingOptions: RequestTracingOptions,
+    client: AppConfigurationClient,
+    snapshotName: string,
+    getOptions?: GetSnapshotOptions
+) {
+    const actualGetOptions = applyRequestTracing(requestTracingOptions, getOptions);
+    return client.getSnapshot(snapshotName, actualGetOptions);
+}
 
+export function listConfigurationSettingsForSnapshotWithTrace(
+    requestTracingOptions: RequestTracingOptions,
+    client: AppConfigurationClient,
+    snapshotName: string,
+    listOptions?: ListConfigurationSettingsForSnapshotOptions
+) {
+    const actualListOptions = applyRequestTracing(requestTracingOptions, listOptions);
+    return client.listConfigurationSettingsForSnapshot(snapshotName, actualListOptions);
+}
+
+function applyRequestTracing<T extends OperationOptions>(requestTracingOptions: RequestTracingOptions, operationOptions?: T) {
+    const actualOptions = { ...operationOptions };
     if (requestTracingOptions.enabled) {
-        actualGetOptions.requestOptions = {
+        actualOptions.requestOptions = {
             customHeaders: {
                 [CORRELATION_CONTEXT_HEADER_NAME]: createCorrelationContextHeader(requestTracingOptions)
             }
         };
     }
-
-    return client.getConfigurationSetting(configurationSettingId, actualGetOptions);
+    return actualOptions;
 }
 
-export function createCorrelationContextHeader(requestTracingOptions: RequestTracingOptions): string {
+function createCorrelationContextHeader(requestTracingOptions: RequestTracingOptions): string {
     /*
     RequestType: 'Startup' during application starting up, 'Watch' after startup completed.
     Host: identify with defined envs
@@ -231,4 +247,3 @@ export function isWebWorker() {
 
     return workerGlobalScopeDefined && importScriptsAsGlobalFunction && isNavigatorDefinedAsExpected;
 }
-
diff --git a/src/types.ts b/src/types.ts
@@ -17,7 +17,7 @@ export type SettingSelector = {
      * For all other cases the characters: asterisk `*`, comma `,`, and backslash `\` are reserved. Reserved characters must be escaped using a backslash (\).
      * e.g. the key filter `a\\b\,\*c*` returns all key-values whose key starts with `a\b,*c`.
      */
-    keyFilter: string,
+    keyFilter?: string,
 
     /**
      * The label filter to apply when querying Azure App Configuration for key-values.
@@ -29,6 +29,15 @@ export type SettingSelector = {
      * @defaultValue `LabelFilter.Null`, matching key-values without a label.
      */
     labelFilter?: string
+
+    /**
+     * The name of snapshot to load from App Configuration.
+     *
+     * @remarks
+     * Snapshot is a set of key-values selected from the App Configuration store based on the composition type and filters. Once created, it is stored as an immutable entity that can be referenced by name.
+     * If snapshot name is used in a selector, no key and label filter should be used for it. Otherwise, an exception will be thrown.
+     */
+    snapshotName?: string
 };
 
 /**
diff --git a/src/version.ts b/src/version.ts
@@ -1,4 +1,4 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-export const VERSION = "2.0.2";
+export const VERSION = "2.1.0";
diff --git a/test/featureFlag.test.ts b/test/featureFlag.test.ts
@@ -5,7 +5,7 @@ import * as chai from "chai";
 import * as chaiAsPromised from "chai-as-promised";
 import { featureFlagContentType } from "@azure/app-configuration";
 import { load } from "./exportedApi.js";
-import { MAX_TIME_OUT, createMockedConnectionString, createMockedEndpoint, createMockedFeatureFlag, createMockedKeyValue, mockAppConfigurationClientListConfigurationSettings, restoreMocks } from "./utils/testHelper.js";
+import { MAX_TIME_OUT, mockAppConfigurationClientGetSnapshot, mockAppConfigurationClientListConfigurationSettingsForSnapshot, createMockedConnectionString, createMockedEndpoint, createMockedFeatureFlag, createMockedKeyValue, mockAppConfigurationClientListConfigurationSettings, restoreMocks } from "./utils/testHelper.js";
 chai.use(chaiAsPromised);
 const expect = chai.expect;
 
@@ -337,4 +337,25 @@ describe("feature flags", function () {
         expect(featureFlag.telemetry.metadata.ETag).equals("ETag");
         expect(featureFlag.telemetry.metadata.FeatureFlagReference).equals(`${createMockedEndpoint()}/kv/.appconfig.featureflag/Telemetry_2?label=Test`);
     });
+
+    it("should load feature flags from snapshot", async () => {
+        const snapshotName = "Test";
+        mockAppConfigurationClientGetSnapshot(snapshotName, {compositionType: "key"});
+        mockAppConfigurationClientListConfigurationSettingsForSnapshot(snapshotName, [[createMockedFeatureFlag("TestFeature", { enabled: true })]]);
+        const connectionString = createMockedConnectionString();
+        const settings = await load(connectionString, {
+            featureFlagOptions: {
+                enabled: true,
+                selectors: [ { snapshotName: snapshotName } ]
+            }
+        });
+        expect(settings).not.undefined;
+        expect(settings.get("feature_management")).not.undefined;
+        const featureFlags = settings.get<any>("feature_management").feature_flags;
+        expect((featureFlags as []).length).equals(1);
+        const featureFlag = featureFlags[0];
+        expect(featureFlag.id).equals("TestFeature");
+        expect(featureFlag.enabled).equals(true);
+        restoreMocks();
+    });
 });
diff --git a/test/load.test.ts b/test/load.test.ts
diff --git a/test/utils/testHelper.ts b/test/utils/testHelper.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@azure/app-configuration-provider",`
`3`		`- "version": "2.0.2",`
	`3`	`+ "version": "2.1.0",`
`4`	`4`	`"description": "The JavaScript configuration provider for Azure App Configuration",`
`5`	`5`	`"main": "dist/index.js",`
`6`	`6`	`"module": "./dist-esm/index.js",`