clarify error type

Author: zhiyuanliang-ms

package.json

@@ -25,7 +25,7 @@
     "dev": "rollup --config --watch",
     "lint": "eslint src/ test/",
     "fix-lint": "eslint src/ test/ --fix",
-    "test": "mocha out/test/*.test.{js,cjs,mjs} --parallel"
+    "test": "mocha out/test/failover.test.{js,cjs,mjs} --parallel"
   },
   "repository": {
     "type": "git",

src/AzureAppConfigurationImpl.ts

@@ -41,6 +41,7 @@ import { FeatureFlagTracingOptions } from "./requestTracing/FeatureFlagTracingOp
 import { KeyFilter, LabelFilter, SettingSelector } from "./types.js";
 import { ConfigurationClientManager } from "./ConfigurationClientManager.js";
 import { getFixedBackoffDuration, calculateDynamicBackoffDuration } from "./failover.js";
+import { FailoverError, OperationError, isFailoverableError } from "./error.js";
 
 type PagedSettingSelector = SettingSelector & {
     /**
@@ -50,7 +51,6 @@ type PagedSettingSelector = SettingSelector & {
 };
 
 const DEFAULT_STARTUP_TIMEOUT = 100 * 1000; // 100 seconds in milliseconds
-const MAX_STARTUP_TIMEOUT = 60 * 60 * 1000; // 60 minutes in milliseconds
 
 export class AzureAppConfigurationImpl implements AzureAppConfiguration {
     /**
@@ -127,10 +127,10 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
             } else {
                 for (const setting of watchedSettings) {
                     if (setting.key.includes("*") || setting.key.includes(",")) {
-                        throw new Error("The characters '*' and ',' are not supported in key of watched settings.");
+                        throw new RangeError("The characters '*' and ',' are not supported in key of watched settings.");
                     }
                     if (setting.label?.includes("*") || setting.label?.includes(",")) {
-                        throw new Error("The characters '*' and ',' are not supported in label of watched settings.");
+                        throw new RangeError("The characters '*' and ',' are not supported in label of watched settings.");
                     }
                     this.#sentinels.push(setting);
                 }
@@ -139,7 +139,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
             // custom refresh interval
             if (refreshIntervalInMs !== undefined) {
                 if (refreshIntervalInMs < MIN_REFRESH_INTERVAL_IN_MS) {
-                    throw new Error(`The refresh interval cannot be less than ${MIN_REFRESH_INTERVAL_IN_MS} milliseconds.`);
+                    throw new RangeError(`The refresh interval cannot be less than ${MIN_REFRESH_INTERVAL_IN_MS} milliseconds.`);
                 } else {
                     this.#kvRefreshInterval = refreshIntervalInMs;
                 }
@@ -157,7 +157,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
                 // custom refresh interval
                 if (refreshIntervalInMs !== undefined) {
                     if (refreshIntervalInMs < MIN_REFRESH_INTERVAL_IN_MS) {
-                        throw new Error(`The feature flag refresh interval cannot be less than ${MIN_REFRESH_INTERVAL_IN_MS} milliseconds.`);
+                        throw new RangeError(`The feature flag refresh interval cannot be less than ${MIN_REFRESH_INTERVAL_IN_MS} milliseconds.`);
                     } else {
                         this.#ffRefreshInterval = refreshIntervalInMs;
                     }
@@ -233,17 +233,29 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
      * Loads the configuration store for the first time.
      */
     async load() {
-        const startupTimeout = this.#options?.startupOptions?.timeoutInMs ?? DEFAULT_STARTUP_TIMEOUT;
-        let timer;
+        const startupTimeout: number = this.#options?.startupOptions?.timeoutInMs ?? DEFAULT_STARTUP_TIMEOUT;
+        const abortController = new AbortController();
+        const abortSignal = abortController.signal;
+        let timeoutId;
         try {
+            // Promise.race will be settled when the first promise in the list is settled
+            // It will not cancel the remaining promises in the list.
+            // To avoid memory leaks, we need to cancel other promises when one promise is settled.
             await Promise.race([
-                new Promise((_, reject) => timer = setTimeout(() => reject(new Error("Load operation timed out.")), startupTimeout)),
-                this.#initialize()
+                this.#initializeWithRetryPolicy(abortSignal),
+                // this promise will be rejected after timeout
+                new Promise((_, reject) => {
+                    timeoutId = setTimeout(() => {
+                        abortController.abort(); // abort the initialization promise
+                        reject(new Error("Load operation timed out."));
+                    },
+                    startupTimeout);
+                })
             ]);
         } catch (error) {
             throw new Error(`Failed to load: ${error.message}`);
         } finally {
-            clearTimeout(timer);
+            clearTimeout(timeoutId); // cancel the timeout promise
         }
     }
 
@@ -254,7 +266,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
         const separator = options?.separator ?? ".";
         const validSeparators = [".", ",", ";", "-", "_", "__", "/", ":"];
         if (!validSeparators.includes(separator)) {
-            throw new Error(`Invalid separator '${separator}'. Supported values: ${validSeparators.map(s => `'${s}'`).join(", ")}.`);
+            throw new RangeError(`Invalid separator '${separator}'. Supported values: ${validSeparators.map(s => `'${s}'`).join(", ")}.`);
         }
 
         // construct hierarchical data object from map
@@ -267,22 +279,22 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
                 const segment = segments[i];
                 // undefined or empty string
                 if (!segment) {
-                    throw new Error(`invalid key: ${key}`);
+                    throw new OperationError(`Failed to construct configuration object: Invalid key: ${key}`);
                 }
                 // create path if not exist
                 if (current[segment] === undefined) {
                     current[segment] = {};
                 }
                 // The path has been occupied by a non-object value, causing ambiguity.
                 if (typeof current[segment] !== "object") {
-                    throw new Error(`Ambiguity occurs when constructing configuration object from key '${key}', value '${value}'. The path '${segments.slice(0, i + 1).join(separator)}' has been occupied.`);
+                    throw new OperationError(`Ambiguity occurs when constructing configuration object from key '${key}', value '${value}'. The path '${segments.slice(0, i + 1).join(separator)}' has been occupied.`);
                 }
                 current = current[segment];
             }
 
             const lastSegment = segments[segments.length - 1];
             if (current[lastSegment] !== undefined) {
-                throw new Error(`Ambiguity occurs when constructing configuration object from key '${key}', value '${value}'. The key should not be part of another key.`);
+                throw new OperationError(`Ambiguity occurs when constructing configuration object from key '${key}', value '${value}'. The key should not be part of another key.`);
             }
             // set value to the last segment
             current[lastSegment] = value;
@@ -295,7 +307,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
      */
     async refresh(): Promise<void> {
         if (!this.#refreshEnabled && !this.#featureFlagRefreshEnabled) {
-            throw new Error("Refresh is not enabled for key-values or feature flags.");
+            throw new OperationError("Refresh is not enabled for key-values or feature flags.");
         }
 
         if (this.#refreshInProgress) {
@@ -314,7 +326,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
      */
     onRefresh(listener: () => any, thisArg?: any): Disposable {
         if (!this.#refreshEnabled && !this.#featureFlagRefreshEnabled) {
-            throw new Error("Refresh is not enabled for key-values or feature flags.");
+            throw new OperationError("Refresh is not enabled for key-values or feature flags.");
         }
 
         const boundedListener = listener.bind(thisArg);
@@ -332,12 +344,11 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
     /**
      * Initializes the configuration provider.
      */
-    async #initialize() {
+    async #initializeWithRetryPolicy(abortSignal: AbortSignal) {
         if (!this.#isInitialLoadCompleted) {
             await this.#inspectFmPackage();
-            const retryEnabled = this.#options?.startupOptions?.retryEnabled ?? true; // enable startup retry by default
             const startTimestamp = Date.now();
-            while (startTimestamp + MAX_STARTUP_TIMEOUT > Date.now()) {
+            while (!abortSignal.aborted) {
                 try {
                     await this.#loadSelectedAndWatchedKeyValues();
                     if (this.#featureFlagEnabled) {
@@ -347,24 +358,17 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
                     this.#isInitialLoadCompleted = true;
                     break;
                 } catch (error) {
-                    if (retryEnabled) {
-                        const timeElapsed = Date.now() - startTimestamp;
-                        let postAttempts = 0;
-                        let backoffDuration = getFixedBackoffDuration(timeElapsed);
-                        if (backoffDuration === undefined) {
-                            postAttempts += 1;
-                            backoffDuration = calculateDynamicBackoffDuration(postAttempts);
-                        }
-                        await new Promise(resolve => setTimeout(resolve, backoffDuration));
-                        console.warn("Failed to load configuration settings at startup. Retrying...");
-                    } else {
-                        throw error;
+                    const timeElapsed = Date.now() - startTimestamp;
+                    let postAttempts = 0;
+                    let backoffDuration = getFixedBackoffDuration(timeElapsed);
+                    if (backoffDuration === undefined) {
+                        postAttempts += 1;
+                        backoffDuration = calculateDynamicBackoffDuration(postAttempts);
                     }
+                    await new Promise(resolve => setTimeout(resolve, backoffDuration));
+                    console.warn("Failed to load configuration settings at startup. Retrying...");
                 }
             }
-            if (!this.#isInitialLoadCompleted) {
-                throw new Error("Load operation exceeded the maximum startup timeout limitation.");
-            }
         }
     }
 
@@ -687,7 +691,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
         }
 
         this.#clientManager.refreshClients();
-        throw new Error("All clients failed to get configuration settings.");
+        throw new FailoverError("All fallback clients failed to get configuration settings.");
     }
 
     async #processKeyValues(setting: ConfigurationSetting<string>): Promise<[string, unknown]> {
@@ -719,7 +723,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
     async #parseFeatureFlag(setting: ConfigurationSetting<string>): Promise<any> {
         const rawFlag = setting.value;
         if (rawFlag === undefined) {
-            throw new Error("The value of configuration setting cannot be undefined.");
+            throw new RangeError("The value of configuration setting cannot be undefined.");
         }
         const featureFlag = JSON.parse(rawFlag);
 
@@ -943,13 +947,13 @@ function getValidSelectors(selectors: SettingSelector[]): SettingSelector[] {
     return uniqueSelectors.map(selectorCandidate => {
         const selector = { ...selectorCandidate };
         if (!selector.keyFilter) {
-            throw new Error("Key filter cannot be null or empty.");
+            throw new RangeError("Key filter cannot be null or empty.");
         }
         if (!selector.labelFilter) {
             selector.labelFilter = LabelFilter.Null;
         }
         if (selector.labelFilter.includes("*") || selector.labelFilter.includes(",")) {
-            throw new Error("The characters '*' and ',' are not supported in label filters.");
+            throw new RangeError("The characters '*' and ',' are not supported in label filters.");
         }
         return selector;
     });
@@ -973,9 +977,3 @@ function getValidFeatureFlagSelectors(selectors?: SettingSelector[]): SettingSel
     });
     return getValidSelectors(selectors);
 }
-
-function isFailoverableError(error: any): boolean {
-    // ENOTFOUND: DNS lookup failed, ENOENT: no such file or directory
-    return isRestError(error) && (error.code === "ENOTFOUND" || error.code === "ENOENT" ||
-        (error.statusCode !== undefined && (error.statusCode === 401 || error.statusCode === 403 || error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500)));
-}

src/ConfigurationClientManager.ts

@@ -8,6 +8,7 @@ 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";
 
 // Configuration client retry options
 const CLIENT_MAX_RETRIES = 2;
@@ -60,7 +61,7 @@ export class ConfigurationClientManager {
                 this.#id = regexMatch[2];
                 this.#secret = regexMatch[3];
             } else {
-                throw new Error(`Invalid connection string. Valid connection strings should match the regex '${ConnectionStringRegex.source}'.`);
+                throw new RangeError(`Invalid connection string. Valid connection strings should match the regex '${ConnectionStringRegex.source}'.`);
             }
             staticClient = new AppConfigurationClient(connectionString, this.#clientOptions);
         } else if ((connectionStringOrEndpoint instanceof URL || typeof connectionStringOrEndpoint === "string") && credentialPassed) {
@@ -77,7 +78,7 @@ export class ConfigurationClientManager {
             this.#credential = credential;
             staticClient = new AppConfigurationClient(this.endpoint.origin, this.#credential, this.#clientOptions);
         } else {
-            throw new Error("A connection string or an endpoint with credential must be specified to create a client.");
+            throw new OperationError("A connection string or an endpoint with credential must be specified to create a client.");
         }
 
         this.#staticClients = [new ConfigurationClientWrapper(this.endpoint.origin, staticClient)];
@@ -150,7 +151,8 @@ export class ConfigurationClientManager {
         let timer;
         try {
             result = await Promise.race([
-                new Promise((_, reject) => timer = setTimeout(() => reject(new Error("SRV record query timed out.")), SRV_QUERY_TIMEOUT)),
+                new Promise((_, reject) => 
+                    timer = setTimeout(() => reject(new Error("SRV record query timed out.")), SRV_QUERY_TIMEOUT)),
                 this.#querySrvTargetHost(host)
             ]);
         } catch (error) {

src/StartupOptions.ts

@@ -2,19 +2,11 @@
 // Licensed under the MIT license.
 
 export interface StartupOptions {
-    /**
-     * Specifies whether to enable retry on startup or not.
-     *
-     * @remarks
-     * If not specified, the default value is true.
-     */
-    retryEnabled?: boolean;
-
     /**
      * The amount of time allowed to load data from Azure App Configuration on startup.
      *
      * @remarks
-     * If not specified, the default value is 100 seconds.
+     * If not specified, the default value is 100 seconds. The maximum allowed value is 1 hour.
      */
     timeoutInMs?: number;
 }

src/error.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { isRestError } from "@azure/core-rest-pipeline";
+
+export class OperationError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "OperationError";
+    }
+}
+
+export class FailoverError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "FailoverError";
+    }
+}
+
+export function isFailoverableError(error: any): boolean {
+    // ENOTFOUND: DNS lookup failed, ENOENT: no such file or directory
+    return isRestError(error) && (error.code === "ENOTFOUND" || error.code === "ENOENT" ||
+        (error.statusCode !== undefined && (error.statusCode === 401 || error.statusCode === 403 || error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500)));
+}
+
+export function isRetriableError(error: any): boolean {
+    if (error instanceof OperationError || 
+        error instanceof RangeError) {
+        return false;
+    }
+    return true;
+}

src/keyvault/AzureKeyVaultKeyValueAdapter.ts

@@ -5,6 +5,7 @@ import { ConfigurationSetting, isSecretReference, parseSecretReference } from "@
 import { IKeyValueAdapter } from "../IKeyValueAdapter.js";
 import { KeyVaultOptions } from "./KeyVaultOptions.js";
 import { SecretClient, parseKeyVaultSecretIdentifier } from "@azure/keyvault-secrets";
+import { OperationError } from "../error.js";
 
 export class AzureKeyVaultKeyValueAdapter implements IKeyValueAdapter {
     /**
@@ -24,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 Error("Configure keyVaultOptions to resolve Key Vault Reference(s).");
+            throw new OperationError("Failed to process the key vault reference. The keyVaultOptions is not configured.");
         }
 
         // precedence: secret clients > credential > secret resolver
@@ -43,7 +44,7 @@ export class AzureKeyVaultKeyValueAdapter implements IKeyValueAdapter {
             return [setting.key, await this.#keyVaultOptions.secretResolver(new URL(sourceId))];
         }
 
-        throw new Error("No key vault credential or secret resolver callback configured, and no matching secret client could be found.");
+        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.");
     }
 
     #getSecretClient(vaultUrl: URL): SecretClient | undefined {

test/clientOptions.test.ts

@@ -48,9 +48,6 @@ describe("custom client options", function () {
                         policy: countPolicy,
                         position: "perRetry"
                     }]
-                },
-                startupOptions: {
-                    retryEnabled: false
                 }
             });
         };
@@ -76,9 +73,6 @@ describe("custom client options", function () {
                     retryOptions: {
                         maxRetries
                     }
-                },
-                startupOptions: {
-                    retryEnabled: false
                 }
             });
         };
@@ -114,9 +108,6 @@ describe("custom client options", function () {
                         policy: countPolicy,
                         position: "perRetry"
                     }]
-                },
-                startupOptions: {
-                    retryEnabled: false
                 }
             });
         };