handle keyvault error

Author: zhiyuanliang-ms

src/AzureAppConfiguration.ts

@@ -3,6 +3,9 @@
 
 import { Disposable } from "./common/disposable.js";
 
+/**
+ * Azure App Configuration provider.
+ */
 export type AzureAppConfiguration = {
     /**
      * API to trigger refresh operation.

src/AzureAppConfigurationImpl.ts

@@ -482,7 +482,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
             await this.#updateWatchedKeyValuesEtag(loadedSettings);
         }
 
-        // process key-values, watched settings have higher priority
+        // adapt configuration settings to key-values
         for (const setting of loadedSettings) {
             const [key, value] = await this.#processKeyValues(setting);
             keyValues.push([key, value]);
@@ -657,6 +657,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
         return response;
     }
 
+    // Only operations related to Azure App Configuration service should be executed with failover policy.
     async #executeWithFailoverPolicy(funcToExecute: (client: AppConfigurationClient) => Promise<any>): Promise<any> {
         let clientWrappers = await this.#clientManager.getClients();
         if (this.#options?.loadBalancingEnabled && this.#lastSuccessfulEndpoint !== "" && clientWrappers.length > 1) {

src/ConfigurationClientManager.ts

@@ -7,8 +7,7 @@ import { TokenCredential } from "@azure/identity";
 import { AzureAppConfigurationOptions } from "./AzureAppConfigurationOptions.js";
 import { isBrowser, isWebWorker } from "./requestTracing/utils.js";
 import * as RequestTracing from "./requestTracing/constants.js";
-import { shuffleList } from "./common/utils.js";
-import { OperationError } from "./error.js";
+import { instanceOfTokenCredential, shuffleList, getValidUrl } from "./common/utils.js";
 
 // Configuration client retry options
 const CLIENT_MAX_RETRIES = 2;
@@ -82,7 +81,7 @@ export class ConfigurationClientManager {
             this.#credential = credential;
             staticClient = new AppConfigurationClient(this.endpoint.origin, this.#credential, this.#clientOptions);
         } else {
-            throw new OperationError("A connection string or an endpoint with credential must be specified to create a client.");
+            throw new RangeError("A connection string or an endpoint with credential must be specified to create a client.");
         }
 
         this.#staticClients = [new ConfigurationClientWrapper(this.endpoint.origin, staticClient)];
@@ -207,12 +206,12 @@ export class ConfigurationClientManager {
                 });
                 index++;
             }
-        } catch (err) {
-            if (err.code === "ENOTFOUND") {
+        } catch (error) {
+            if (error.code === "ENOTFOUND") {
                 // No more SRV records found, return results.
                 return results;
             } else {
-                throw new Error(`Failed to lookup SRV records: ${err.message}`);
+                throw new Error(`Failed to lookup SRV records: ${error.message}`);
             }
         }
 
@@ -279,20 +278,3 @@ function getClientOptions(options?: AzureAppConfigurationOptions): AppConfigurat
         }
     });
 }
-
-function getValidUrl(endpoint: string): URL {
-    try {
-        return new URL(endpoint);
-    } catch (error) {
-        if (error.code === "ERR_INVALID_URL") {
-            throw new RangeError("Invalid endpoint URL.", { cause: error });
-        } else {
-            throw error;
-        }
-    }
-}
-
-export function instanceOfTokenCredential(obj: unknown) {
-    return obj && typeof obj === "object" && "getToken" in obj && typeof obj.getToken === "function";
-}
-

src/common/utils.ts

@@ -30,3 +30,23 @@ export function shuffleList<T>(array: T[]): T[] {
     }
     return array;
 }
+
+export function getValidUrl(endpoint: string): URL {
+    try {
+        return new URL(endpoint);
+    } catch (error) {
+        if (error.code === "ERR_INVALID_URL") {
+            throw new RangeError("Invalid endpoint URL.", { cause: error });
+        } else {
+            throw error;
+        }
+    }
+}
+
+export function getUrlHost(url: string) {
+    return new URL(url).host;
+}
+
+export function instanceOfTokenCredential(obj: unknown) {
+    return obj && typeof obj === "object" && "getToken" in obj && typeof obj.getToken === "function";
+}

src/error.ts

@@ -2,9 +2,10 @@
 // Licensed under the MIT license.
 
 import { isRestError } from "@azure/core-rest-pipeline";
+import { AuthenticationError } from "@azure/identity";
 
 /**
- * Error thrown when an operation is not allowed to be performed.
+ * Error thrown when an operation cannot be performed by the Azure App Configuration provider.
  */
 export class OperationError extends Error {
     constructor(message: string) {
@@ -31,8 +32,9 @@ export function isFailoverableError(error: any): boolean {
 }
 
 export function isRetriableError(error: any): boolean {
-    if (error instanceof OperationError ||
-        error instanceof RangeError) {
+    if (error instanceof AuthenticationError || // this error occurs when using wrong credential to access the key vault
+        error instanceof RangeError || // this error is caused by misconfiguration of the Azure App Configuration provider
+        error instanceof OperationError) {
         return false;
     }
     return true;

src/keyvault/AzureKeyVaultKeyValueAdapter.ts

@@ -4,8 +4,8 @@
 import { ConfigurationSetting, isSecretReference, parseSecretReference } from "@azure/app-configuration";
 import { IKeyValueAdapter } from "../IKeyValueAdapter.js";
 import { KeyVaultOptions } from "./KeyVaultOptions.js";
+import { getUrlHost } from "../common/utils.js";
 import { SecretClient, parseKeyVaultSecretIdentifier } from "@azure/keyvault-secrets";
-import { OperationError } from "../error.js";
 
 export class AzureKeyVaultKeyValueAdapter implements IKeyValueAdapter {
     /**
@@ -25,7 +25,7 @@ export class AzureKeyVaultKeyValueAdapter implements IKeyValueAdapter {
     async processKeyValue(setting: ConfigurationSetting): Promise<[string, unknown]> {
         // TODO: cache results to save requests.
         if (!this.#keyVaultOptions) {
-            throw new OperationError("Failed to process the key vault reference. The keyVaultOptions is not configured.");
+            throw new RangeError("Failed to process the key vault reference. The keyVaultOptions is not configured.");
         }
 
         // precedence: secret clients > credential > secret resolver
@@ -35,7 +35,7 @@ export class AzureKeyVaultKeyValueAdapter implements IKeyValueAdapter {
 
         const client = this.#getSecretClient(new URL(vaultUrl));
         if (client) {
-            // TODO: what if error occurs when reading a key vault value? Now it breaks the whole load.
+            // If the credential of the secret client is wrong, AuthenticationError will be thrown.
             const secret = await client.getSecret(secretName, { version });
             return [setting.key, secret.value];
         }
@@ -44,14 +44,21 @@ export class AzureKeyVaultKeyValueAdapter implements IKeyValueAdapter {
             return [setting.key, await this.#keyVaultOptions.secretResolver(new URL(sourceId))];
         }
 
-        throw new OperationError("Failed to process the key vault reference. No key vault credential or secret resolver callback configured, and no matching secret client could be found.");
+        // When code reaches here, it means the key vault secret reference is not resolved.
+
+        throw new RangeError("Failed to process the key vault reference. No key vault credential or secret resolver callback is configured.");
     }
 
+    /**
+     * 
+     * @param vaultUrl - The url of the key vault.
+     * @returns 
+     */
     #getSecretClient(vaultUrl: URL): SecretClient | undefined {
         if (this.#secretClients === undefined) {
             this.#secretClients = new Map();
-            for (const c of this.#keyVaultOptions?.secretClients ?? []) {
-                this.#secretClients.set(getHost(c.vaultUrl), c);
+            for (const client of this.#keyVaultOptions?.secretClients ?? []) {
+                this.#secretClients.set(getUrlHost(client.vaultUrl), client);
             }
         }
 
@@ -70,7 +77,3 @@ export class AzureKeyVaultKeyValueAdapter implements IKeyValueAdapter {
         return undefined;
     }
 }
-
-function getHost(url: string) {
-    return new URL(url).host;
-}

src/load.ts

@@ -5,7 +5,8 @@ import { TokenCredential } from "@azure/identity";
 import { AzureAppConfiguration } from "./AzureAppConfiguration.js";
 import { AzureAppConfigurationImpl } from "./AzureAppConfigurationImpl.js";
 import { AzureAppConfigurationOptions } from "./AzureAppConfigurationOptions.js";
-import { ConfigurationClientManager, instanceOfTokenCredential } from "./ConfigurationClientManager.js";
+import { ConfigurationClientManager } from "./ConfigurationClientManager.js";
+import { instanceOfTokenCredential } from "./common/utils.js";
 
 const MIN_DELAY_FOR_UNHANDLED_ERROR: number = 5_000; // 5 seconds
 

test/keyvault.test.ts

@@ -96,7 +96,7 @@ describe("key vault reference", function () {
                 ]
             }
         });
-        return expect(loadKeyVaultPromise).eventually.rejectedWith("Failed to process the key vault reference. No key vault credential or secret resolver callback configured, and no matching secret client could be found.");
+        return expect(loadKeyVaultPromise).eventually.rejectedWith("Failed to process the key vault reference. No key vault credential or secret resolver callback is configured.");
     });
 
     it("should fallback to use default credential when corresponding secret client not provided", async () => {