Prepare v9.4.0 release (#112)

* Take another approach to avoid errors when options is logged while containing circular references + prevent internals leaking into the log

* Fix a minor bug in setting type mismatch check (type mismatch should also be reported for allowed flag override values)

* Fix a minor bug in FetchError (name property should be set to the class name)

* Fix a minor bug in formatting errors (some JS runtimes doesn't include the error message in the stack trace)

* Fix edge case bug in parseFloatStrict

* Use monotonic clock for scheduling poll iterations in Auto Poll mode for improved precision and resistance to system/user clock adjustments

* Use monotonic clock in tests for measuring elapsed time

* Refresh internal cache in offline mode too + don't report failure when refreshing in offline mode if an external cache is configured

* Make clientReady consistent with other SDKs in Auto Poll + offline mode

* Eliminate redundant sync with external cache in AutoPollConfigService.getConfig + improve clientReady

* Eliminate race condition between initial and user-initiated cache sync ups

* Also report configCached when new config is synced from external cache

* Deduplicate config refresh instead of fetch operation only

* Correct intellisense docs of a few config service-related APIs

* Include SDK Key in error fetchFailedDueToInvalidSdkKey (1100) + mask SDK Key except for the last 6 characters

* npm run lint:fix

* Bump version

Author: adams85

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "configcat-common",
-  "version": "9.3.1",
+  "version": "9.4.0",
   "description": "ConfigCat is a configuration as a service that lets you manage your features and configurations without actually deploying new code.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package.json

@@ -1,10 +1,9 @@
 import type { AutoPollOptions } from "./ConfigCatClientOptions";
-import type { LoggerWrapper } from "./ConfigCatLogger";
 import type { IConfigFetcher } from "./ConfigFetcher";
 import type { IConfigService, RefreshResult } from "./ConfigServiceBase";
 import { ClientCacheState, ConfigServiceBase } from "./ConfigServiceBase";
 import type { ProjectConfig } from "./ProjectConfig";
-import { AbortToken, delay } from "./Utils";
+import { AbortToken, delay, getMonotonicTimeMs } from "./Utils";
 
 export const POLL_EXPIRATION_TOLERANCE_MS = 500;
 
@@ -32,9 +31,10 @@ export class AutoPollConfigService extends ConfigServiceBase<AutoPollOptions> im
     if (options.maxInitWaitTimeSeconds !== 0) {
       this.initialized = false;
 
-      // This promise will be resolved when
-      // 1. the cache contains a valid config at startup (see startRefreshWorker) or
-      // 2. config json is fetched the first time, regardless of success or failure (see onConfigUpdated).
+      // This promise will be resolved as soon as
+      // 1. a cache sync operation completes, and the obtained config is up-to-date (see getConfig and startRefreshWorker),
+      // 2. or, in case the client is online and the internal cache is still empty or expired after the initial cache sync-up,
+      //    the first config fetch operation completes, regardless of success or failure (see onConfigFetched).
       const initSignalPromise = new Promise<void>(resolve => this.signalInitialization = resolve);
 
       // This promise will be resolved when either initialization ready is signalled by signalInitialization() or maxInitWaitTimeSeconds pass.
@@ -53,9 +53,7 @@ export class AutoPollConfigService extends ConfigServiceBase<AutoPollOptions> im
       return this.getCacheState(this.options.cache.getInMemory());
     });
 
-    if (!options.offline) {
-      this.startRefreshWorker(initialCacheSyncUp, this.stopToken);
-    }
+    this.startRefreshWorker(initialCacheSyncUp, this.stopToken);
   }
 
   private async waitForInitializationAsync(initSignalPromise: Promise<void>): Promise<boolean> {
@@ -76,30 +74,22 @@ export class AutoPollConfigService extends ConfigServiceBase<AutoPollOptions> im
   async getConfig(): Promise<ProjectConfig> {
     this.options.logger.debug("AutoPollConfigService.getConfig() called.");
 
-    function logSuccess(logger: LoggerWrapper) {
-      logger.debug("AutoPollConfigService.getConfig() - returning value from cache.");
-    }
-
-    let cachedConfig: ProjectConfig;
-    if (!this.isOffline && !this.initialized) {
-      cachedConfig = await this.options.cache.get(this.cacheKey);
-      if (!cachedConfig.isExpired(this.pollIntervalMs)) {
-        logSuccess(this.options.logger);
-        return cachedConfig;
-      }
+    let cachedConfig = await this.syncUpWithCache();
 
+    if (!cachedConfig.isExpired(this.pollIntervalMs)) {
+      this.signalInitialization();
+    }
+    else if (!this.isOffline && !this.initialized) {
       this.options.logger.debug("AutoPollConfigService.getConfig() - cache is empty or expired, waiting for initialization.");
       await this.initializationPromise;
-    }
-
-    cachedConfig = await this.options.cache.get(this.cacheKey);
-    if (!cachedConfig.isExpired(this.pollIntervalMs)) {
-      logSuccess(this.options.logger);
+      cachedConfig = this.options.cache.getInMemory();
     }
     else {
       this.options.logger.debug("AutoPollConfigService.getConfig() - cache is empty or expired.");
+      return cachedConfig;
     }
 
+    this.options.logger.debug("AutoPollConfigService.getConfig() - returning value from cache.");
     return cachedConfig;
   }
 
@@ -121,30 +111,28 @@ export class AutoPollConfigService extends ConfigServiceBase<AutoPollOptions> im
     this.signalInitialization();
   }
 
-  protected setOnlineCore(): void {
-    this.startRefreshWorker(null, this.stopToken);
-  }
-
-  protected setOfflineCore(): void {
+  protected goOnline(): void {
+    // We need to restart the polling loop because going from offline to online should trigger a refresh operation
+    // immediately instead of waiting for the next tick (which might not happen until much later).
     this.stopRefreshWorker();
     this.stopToken = new AbortToken();
+    this.startRefreshWorker(null, this.stopToken);
   }
 
   private async startRefreshWorker(initialCacheSyncUp: ProjectConfig | Promise<ProjectConfig> | null, stopToken: AbortToken) {
     this.options.logger.debug("AutoPollConfigService.startRefreshWorker() called.");
 
-    let isFirstIteration = true;
     while (!stopToken.aborted) {
       try {
-        const scheduledNextTimeMs = new Date().getTime() + this.pollIntervalMs;
+        const scheduledNextTimeMs = getMonotonicTimeMs() + this.pollIntervalMs;
         try {
-          await this.refreshWorkerLogic(isFirstIteration, initialCacheSyncUp);
+          await this.refreshWorkerLogic(initialCacheSyncUp);
         }
         catch (err) {
           this.options.logger.autoPollConfigServiceErrorDuringPolling(err);
         }
 
-        const realNextTimeMs = scheduledNextTimeMs - new Date().getTime();
+        const realNextTimeMs = scheduledNextTimeMs - getMonotonicTimeMs();
         if (realNextTimeMs > 0) {
           await delay(realNextTimeMs, stopToken);
         }
@@ -153,7 +141,6 @@ export class AutoPollConfigService extends ConfigServiceBase<AutoPollOptions> im
         this.options.logger.autoPollConfigServiceErrorDuringPolling(err);
       }
 
-      isFirstIteration = false;
       initialCacheSyncUp = null; // allow GC to collect the Promise and its result
     }
   }
@@ -163,24 +150,24 @@ export class AutoPollConfigService extends ConfigServiceBase<AutoPollOptions> im
     this.stopToken.abort();
   }
 
-  private async refreshWorkerLogic(isFirstIteration: boolean, initialCacheSyncUp: ProjectConfig | Promise<ProjectConfig> | null) {
+  private async refreshWorkerLogic(initialCacheSyncUp: ProjectConfig | Promise<ProjectConfig> | null) {
     this.options.logger.debug("AutoPollConfigService.refreshWorkerLogic() - called.");
 
-    const latestConfig = await (initialCacheSyncUp ?? this.options.cache.get(this.cacheKey));
+    const latestConfig = await (initialCacheSyncUp ?? this.syncUpWithCache());
     if (latestConfig.isExpired(this.pollExpirationMs)) {
       // Even if the service gets disposed immediately, we allow the first refresh for backward compatibility,
       // i.e. to not break usage patterns like this:
       // ```
-      // client.getValueAsync("SOME_KEY", false).then(value => { /* ... */ }, user);
+      // client.getValueAsync("SOME_KEY", false, user).then(value => { /* ... */ });
       // client.dispose();
       // ```
-      if (isFirstIteration ? !this.isOfflineExactly : !this.isOffline) {
+      if (initialCacheSyncUp ? !this.isOfflineExactly : !this.isOffline) {
         await this.refreshConfigCoreAsync(latestConfig);
+        return; // postpone signalling initialization until `onConfigFetched`
       }
     }
-    else if (isFirstIteration) {
-      this.signalInitialization();
-    }
+
+    this.signalInitialization();
   }
 
   getCacheState(cachedConfig: ProjectConfig): ClientCacheState {

src/AutoPollConfigService.ts

@@ -19,10 +19,13 @@ export interface IConfigCatCache {
   get(key: string): Promise<string | null | undefined> | string | null | undefined;
 }
 
+/** @remarks Unchanged config is returned as is, changed config is wrapped in an array so we can distinguish between the two cases. */
+export type CacheSyncResult = ProjectConfig | [changedConfig: ProjectConfig];
+
 export interface IConfigCache {
   set(key: string, config: ProjectConfig): Promise<void> | void;
 
-  get(key: string): Promise<ProjectConfig> | ProjectConfig;
+  get(key: string): Promise<CacheSyncResult> | CacheSyncResult;
 
   getInMemory(): ProjectConfig;
 }
@@ -59,7 +62,7 @@ export class ExternalConfigCache implements IConfigCache {
         this.cachedConfig = config;
       }
       else {
-        // We may have empty entries with timestamp > 0 (see the flooding prevention logic in ConfigServiceBase.fetchLogicAsync).
+        // We may have empty entries with timestamp > 0 (see the flooding prevention logic in ConfigServiceBase.fetchAsync).
         // In such cases we want to preserve the timestamp locally but don't want to store those entries into the external cache.
         this.cachedSerializedConfig = void 0;
         this.cachedConfig = config;
@@ -73,41 +76,51 @@ export class ExternalConfigCache implements IConfigCache {
     }
   }
 
-  private updateCachedConfig(externalSerializedConfig: string | null | undefined): void {
+  private updateCachedConfig(externalSerializedConfig: string | null | undefined): CacheSyncResult {
     if (externalSerializedConfig == null || externalSerializedConfig === this.cachedSerializedConfig) {
-      return;
+      return this.cachedConfig;
     }
 
-    this.cachedConfig = ProjectConfig.deserialize(externalSerializedConfig);
+    const externalConfig = ProjectConfig.deserialize(externalSerializedConfig);
+    const hasChanged = !ProjectConfig.contentEquals(externalConfig, this.cachedConfig);
+    this.cachedConfig = externalConfig;
     this.cachedSerializedConfig = externalSerializedConfig;
+    return hasChanged ? [this.cachedConfig] : this.cachedConfig;
   }
 
-  get(key: string): Promise<ProjectConfig> {
+  get(key: string): Promise<CacheSyncResult> | CacheSyncResult {
+    let cacheSyncResult: CacheSyncResult;
+
     try {
       const cacheGetResult = this.cache.get(key);
 
       // Take the async path only when the IConfigCatCache.get operation is asynchronous.
       if (isPromiseLike(cacheGetResult)) {
         return (async (cacheGetPromise) => {
+          let cacheSyncResult: CacheSyncResult;
+
           try {
-            this.updateCachedConfig(await cacheGetPromise);
+            cacheSyncResult = this.updateCachedConfig(await cacheGetPromise);
           }
           catch (err) {
+            cacheSyncResult = this.cachedConfig;
             this.logger.configServiceCacheReadError(err);
           }
-          return this.cachedConfig;
+
+          return cacheSyncResult;
         })(cacheGetResult);
       }
 
       // Otherwise, keep the code flow synchronous so the config services can sync up
       // with the cache in their ctors synchronously (see ConfigServiceBase.syncUpWithCache).
-      this.updateCachedConfig(cacheGetResult);
+      cacheSyncResult = this.updateCachedConfig(cacheGetResult);
     }
     catch (err) {
+      cacheSyncResult = this.cachedConfig;
       this.logger.configServiceCacheReadError(err);
     }
 
-    return Promise.resolve(this.cachedConfig);
+    return cacheSyncResult;
   }
 
   getInMemory(): ProjectConfig {

src/ConfigCatCache.ts

@@ -3,10 +3,12 @@ import type { IConfigCache } from "./ConfigCatCache";
 import type { ConfigCatClientOptions, OptionsBase, OptionsForPollingMode } from "./ConfigCatClientOptions";
 import { AutoPollOptions, LazyLoadOptions, ManualPollOptions, PollingMode } from "./ConfigCatClientOptions";
 import type { LoggerWrapper } from "./ConfigCatLogger";
+import { LogLevel } from "./ConfigCatLogger";
 import type { IConfigFetcher } from "./ConfigFetcher";
 import type { IConfigService } from "./ConfigServiceBase";
 import { ClientCacheState, RefreshResult } from "./ConfigServiceBase";
 import type { IEventEmitter } from "./EventEmitter";
+import type { FlagOverrides } from "./FlagOverrides";
 import { OverrideBehaviour } from "./FlagOverrides";
 import type { HookEvents, Hooks, IProvidesHooks } from "./Hooks";
 import { LazyLoadConfigService } from "./LazyLoadConfigService";
@@ -16,7 +18,8 @@ import type { IConfig, PercentageOption, ProjectConfig, Setting, SettingValue }
 import type { IEvaluationDetails, IRolloutEvaluator, SettingTypeOf } from "./RolloutEvaluator";
 import { RolloutEvaluator, checkSettingsAvailable, evaluate, evaluateAll, evaluationDetailsFromDefaultValue, getTimestampAsDate, handleInvalidReturnValue, isAllowedValue } from "./RolloutEvaluator";
 import type { User } from "./User";
-import { errorToString, isArray, stringifyCircularJSON, throwError } from "./Utils";
+import { getUserAttributes } from "./User";
+import { errorToString, isArray, isObject, shallowClone, throwError } from "./Utils";
 
 /** ConfigCat SDK client. */
 export interface IConfigCatClient extends IProvidesHooks {
@@ -79,20 +82,38 @@ export interface IConfigCatClient extends IProvidesHooks {
   getKeyAndValueAsync(variationId: string): Promise<SettingKeyValue | null>;
 
   /**
-   * Refreshes the locally cached config by fetching the latest version from the remote server.
+   * Updates the internally cached config by synchronizing with the external cache (if any),
+   * then by fetching the latest version from the ConfigCat CDN (provided that the client is online).
    * @returns A promise that fulfills with the refresh result.
    */
   forceRefreshAsync(): Promise<RefreshResult>;
 
   /**
-   * Waits for the client initialization.
-   * @returns A promise that fulfills with the client's initialization state.
+   * Waits for the client to reach the ready state, i.e. to complete initialization.
+   *
+   * @remarks Ready state is reached as soon as the initial sync with the external cache (if any) completes.
+   * If this does not produce up-to-date config data, and the client is online (i.e. HTTP requests are allowed),
+   * the first config fetch operation is also awaited in Auto Polling mode before ready state is reported.
+   *
+   * That is, reaching the ready state usually means the client is ready to evaluate feature flags and settings.
+   * However, please note that this is not guaranteed. In case of initialization failure or timeout, the internal cache
+   * may be empty or expired even after the ready state is reported. You can verify this by checking the return value.
+   *
+   * @returns A promise that fulfills with the state of the internal cache at the time initialization was completed.
    */
   waitForReady(): Promise<ClientCacheState>;
 
   /**
    * Captures the current state of the client.
    * The resulting snapshot can be used to synchronously evaluate feature flags and settings based on the captured state.
+   *
+   * @remarks The operation captures the internally cached config data. It does not attempt to update it by synchronizing with
+   * the external cache or by fetching the latest version from the ConfigCat CDN.
+   *
+   * Therefore, it is recommended to use snapshots in conjunction with the Auto Polling mode, where the SDK automatically
+   * updates the internal cache in the background.
+   *
+   * For other polling modes, you will need to manually initiate a cache update by invoking `forceRefreshAsync`.
    */
   snapshot(): IConfigCatClientSnapshot;
 
@@ -118,7 +139,7 @@ export interface IConfigCatClient extends IProvidesHooks {
   setOnline(): void;
 
   /**
-   * Configures the client to not initiate HTTP requests and work using the locally cached config only.
+   * Configures the client to not initiate HTTP requests but work using the cache only.
    */
   setOffline(): void;
 
@@ -130,9 +151,10 @@ export interface IConfigCatClient extends IProvidesHooks {
 
 /** Represents the state of `IConfigCatClient` captured at a specific point in time. */
 export interface IConfigCatClientSnapshot {
+  /** The state of the internal cache at the time the snapshot was created. */
   readonly cacheState: ClientCacheState;
 
-  /** The latest config which has been fetched from the remote server. */
+  /** The internally cached config at the time the snapshot was created. */
   readonly fetchedConfig: IConfig | null;
 
   /**
@@ -280,7 +302,9 @@ export class ConfigCatClient implements IConfigCatClient {
 
     this.options = options;
 
-    this.options.logger.debug("Initializing ConfigCatClient. Options: " + stringifyCircularJSON(this.options));
+    if (options.logger.isEnabled(LogLevel.Debug)) {
+      options.logger.debug("Initializing ConfigCatClient. Options: " + JSON.stringify(getSerializableOptions(options)));
+    }
 
     if (!configCatKernel) {
       throw new Error("Invalid 'configCatKernel' value");
@@ -551,7 +575,7 @@ export class ConfigCatClient implements IConfigCatClient {
       }
     }
     else {
-      return RefreshResult.failure("Client is configured to use the LocalOnly override behavior, which prevents making HTTP requests.");
+      return RefreshResult.failure("Client is configured to use the LocalOnly override behavior, which prevents synchronization with external cache and making HTTP requests.");
     }
   }
 
@@ -798,6 +822,19 @@ function ensureAllowedValue(value: NonNullable<SettingValue>): NonNullable<Setti
   return isAllowedValue(value) ? value : handleInvalidReturnValue(value);
 }
 
+export function getSerializableOptions(options: ConfigCatClientOptions): Record<string, unknown> {
+  return shallowClone(options, (key, value) => {
+    if (key === "defaultUser") {
+      return getUserAttributes(value as User);
+    }
+    if (key === "flagOverrides") {
+      return shallowClone(value as FlagOverrides, (_, value) => isObject(value) ? value.toString() : value);
+    }
+    // NOTE: Prevent internals from leaking into logs and avoid errors because of circular references in user-provided objects.
+    return isObject(value) ? value.toString() : value;
+  });
+}
+
 /* GC finalization support */
 
 // Defines the interface of the held value which is passed to ConfigCatClient.finalize by FinalizationRegistry.