Allow custom config fetcher implementations

Author: adams85

src/AutoPollConfigService.ts

@@ -1,6 +1,5 @@
 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";
@@ -18,9 +17,9 @@ export class AutoPollConfigService extends ConfigServiceBase<AutoPollOptions> im
   private readonly pollExpirationMs: number;
   readonly readyPromise: Promise<ClientCacheState>;
 
-  constructor(configFetcher: IConfigFetcher, options: AutoPollOptions) {
+  constructor(options: AutoPollOptions) {
 
-    super(configFetcher, options);
+    super(options);
 
     this.pollIntervalMs = options.pollIntervalSeconds * 1000;
     // Due to the inaccuracy of the timer, some tolerance should be allowed when checking for

src/ConfigCatClient.ts

@@ -1,12 +1,9 @@
 import { AutoPollConfigService } from "./AutoPollConfigService";
-import type { IConfigCache } from "./ConfigCatCache";
-import type { ConfigCatClientOptions, OptionsBase, OptionsForPollingMode } from "./ConfigCatClientOptions";
+import type { ConfigCatClientOptions, IConfigCatKernel, OptionsBase, OptionsForPollingMode } from "./ConfigCatClientOptions";
 import { AutoPollOptions, LazyLoadOptions, ManualPollOptions, PollingMode } from "./ConfigCatClientOptions";
 import type { LoggerWrapper } from "./ConfigCatLogger";
-import type { IConfigFetcher } from "./ConfigFetcher";
 import type { IConfigService } from "./ConfigServiceBase";
 import { ClientCacheState, RefreshResult } from "./ConfigServiceBase";
-import type { IEventEmitter } from "./EventEmitter";
 import { nameOfOverrideBehaviour, OverrideBehaviour } from "./FlagOverrides";
 import type { HookEvents, Hooks, IProvidesHooks } from "./Hooks";
 import { LazyLoadConfigService } from "./LazyLoadConfigService";
@@ -170,18 +167,10 @@ export interface IConfigCatClientSnapshot {
   getValueDetails<T extends SettingValue>(key: string, defaultValue: T, user?: IUser): IEvaluationDetails<SettingTypeOf<T>>;
 }
 
-export interface IConfigCatKernel {
-  configFetcher: IConfigFetcher;
-  sdkType: string;
-  sdkVersion: string;
-  defaultCacheFactory?: (options: OptionsBase) => IConfigCache;
-  eventEmitterFactory?: () => IEventEmitter;
-}
-
 export class ConfigCatClientCache {
   private readonly instances: Record<string, [WeakRef<ConfigCatClient>, object]> = {};
 
-  getOrCreate(options: ConfigCatClientOptions, configCatKernel: IConfigCatKernel): [ConfigCatClient, boolean] {
+  getOrCreate(options: ConfigCatClientOptions): [ConfigCatClient, boolean] {
     let instance: ConfigCatClient | undefined;
 
     const cachedInstance = this.instances[options.sdkKey];
@@ -194,7 +183,7 @@ export class ConfigCatClientCache {
     }
 
     const token = {};
-    instance = new ConfigCatClient(options, configCatKernel, token);
+    instance = new ConfigCatClient(options, token);
     const weakRefCtor = isWeakRefAvailable() ? WeakRef : getWeakRefStub();
     this.instances[options.sdkKey] = [new weakRefCtor(instance), token];
     return [instance, false];
@@ -250,20 +239,17 @@ export class ConfigCatClient implements IConfigCatClient {
       throw new Error(invalidSdkKeyError);
     }
 
-    const optionsClass =
-      pollingMode === PollingMode.AutoPoll ? AutoPollOptions
-      : pollingMode === PollingMode.ManualPoll ? ManualPollOptions
-      : pollingMode === PollingMode.LazyLoad ? LazyLoadOptions
+    const actualOptions =
+      pollingMode === PollingMode.AutoPoll ? new AutoPollOptions(sdkKey, configCatKernel, options)
+      : pollingMode === PollingMode.ManualPoll ? new ManualPollOptions(sdkKey, configCatKernel, options)
+      : pollingMode === PollingMode.LazyLoad ? new LazyLoadOptions(sdkKey, configCatKernel, options)
       : throwError(new Error("Invalid 'pollingMode' value"));
 
-    const actualOptions = new optionsClass(sdkKey, configCatKernel.sdkType, configCatKernel.sdkVersion, options,
-      configCatKernel.defaultCacheFactory, configCatKernel.eventEmitterFactory);
-
     if (actualOptions.flagOverrides?.behaviour !== OverrideBehaviour.LocalOnly && !isValidSdkKey(sdkKey, actualOptions.baseUrlOverriden)) {
       throw new Error(invalidSdkKeyError);
     }
 
-    const [instance, instanceAlreadyCreated] = clientInstanceCache.getOrCreate(actualOptions, configCatKernel);
+    const [instance, instanceAlreadyCreated] = clientInstanceCache.getOrCreate(actualOptions);
 
     if (instanceAlreadyCreated && options) {
       actualOptions.logger.clientIsAlreadyCreated(sdkKey);
@@ -274,7 +260,6 @@ export class ConfigCatClient implements IConfigCatClient {
 
   constructor(
     options: ConfigCatClientOptions,
-    configCatKernel: IConfigCatKernel,
     private readonly cacheToken?: object) {
 
     if (!options) {
@@ -285,14 +270,6 @@ export class ConfigCatClient implements IConfigCatClient {
 
     this.options.logger.debug("Initializing ConfigCatClient. Options: " + JSON.stringify(this.options));
 
-    if (!configCatKernel) {
-      throw new Error("Invalid 'configCatKernel' value");
-    }
-
-    if (!configCatKernel.configFetcher) {
-      throw new Error("Invalid 'configCatKernel.configFetcher' value");
-    }
-
     // To avoid possible memory leaks, the components of the client should not hold a strong reference to the hooks object (see also SafeHooksWrapper).
     this.hooks = options.yieldHooks();
 
@@ -304,9 +281,9 @@ export class ConfigCatClient implements IConfigCatClient {
 
     if (options.flagOverrides?.behaviour !== OverrideBehaviour.LocalOnly) {
       this.configService =
-        options instanceof AutoPollOptions ? new AutoPollConfigService(configCatKernel.configFetcher, options)
-        : options instanceof ManualPollOptions ? new ManualPollConfigService(configCatKernel.configFetcher, options)
-        : options instanceof LazyLoadOptions ? new LazyLoadConfigService(configCatKernel.configFetcher, options)
+        options instanceof AutoPollOptions ? new AutoPollConfigService(options)
+        : options instanceof ManualPollOptions ? new ManualPollConfigService(options)
+        : options instanceof LazyLoadOptions ? new LazyLoadConfigService(options)
         : throwError(new Error("Invalid 'options' value"));
     } else {
       this.hooks.emit("clientReady", ClientCacheState.HasLocalOverrideFlagDataOnly);

src/ConfigCatClientOptions.ts

@@ -2,6 +2,7 @@ import type { IConfigCache, IConfigCatCache } from "./ConfigCatCache";
 import { ExternalConfigCache, InMemoryConfigCache } from "./ConfigCatCache";
 import type { IConfigCatLogger } from "./ConfigCatLogger";
 import { ConfigCatConsoleLogger, LoggerWrapper } from "./ConfigCatLogger";
+import type { IConfigCatConfigFetcher } from "./ConfigFetcher";
 import type { IEventEmitter } from "./EventEmitter";
 import { NullEventEmitter } from "./EventEmitter";
 import type { FlagOverrides } from "./FlagOverrides";
@@ -66,6 +67,14 @@ export interface IOptions {
    */
   cache?: IConfigCatCache | null;
 
+  /**
+   * The config fetcher implementation to use for performing ConfigCat config fetch operations.
+   *
+   * If not set, a default implementation will be used depending on the current platform.
+   * If you want to use custom a config fetcher, you can provide an implementation of `IConfigCatConfigFetcher`.
+   */
+  configFetcher?: IConfigCatConfigFetcher | null;
+
   /** The flag override to use. If not set, no flag override will be used. */
   flagOverrides?: FlagOverrides | null;
 
@@ -123,6 +132,14 @@ export type OptionsForPollingMode<TMode extends PollingMode | undefined> =
   TMode extends undefined ? IAutoPollOptions :
   never;
 
+export interface IConfigCatKernel {
+  sdkType: string;
+  sdkVersion: string;
+  eventEmitterFactory?: () => IEventEmitter;
+  defaultCacheFactory?: (options: OptionsBase) => IConfigCache;
+  configFetcherFactory: (options: OptionsBase) => IConfigCatConfigFetcher;
+}
+
 /* eslint-disable @typescript-eslint/no-inferrable-types */
 
 export abstract class OptionsBase {
@@ -145,6 +162,8 @@ export abstract class OptionsBase {
 
   cache: IConfigCache;
 
+  configFetcher: IConfigCatConfigFetcher;
+
   flagOverrides?: FlagOverrides;
 
   defaultUser?: IUser;
@@ -153,9 +172,7 @@ export abstract class OptionsBase {
 
   hooks: SafeHooksWrapper;
 
-  constructor(sdkKey: string, clientVersion: string, options?: IOptions | null,
-    defaultCacheFactory?: ((options: OptionsBase) => IConfigCache) | null,
-    eventEmitterFactory?: (() => IEventEmitter) | null) {
+  constructor(sdkKey: string, kernel: IConfigCatKernel, clientVersion: string, options?: IOptions | null) {
 
     if (!sdkKey) {
       throw new Error("Invalid 'sdkKey' value");
@@ -175,7 +192,7 @@ export abstract class OptionsBase {
         break;
     }
 
-    const eventEmitter = eventEmitterFactory?.() ?? new NullEventEmitter();
+    const eventEmitter = kernel.eventEmitterFactory?.() ?? new NullEventEmitter();
     const hooks = new Hooks(eventEmitter);
     const hooksWeakRef = new (isWeakRefAvailable() ? WeakRef : getWeakRefStub())(hooks);
     this.hooks = <SafeHooksWrapper & { hooksWeakRef: WeakRef<Hooks> }>{
@@ -188,10 +205,12 @@ export abstract class OptionsBase {
 
     let logger: IConfigCatLogger | null | undefined;
     let cache: IConfigCatCache | null | undefined;
+    let configFetcher: IConfigCatConfigFetcher | null | undefined;
 
     if (options) {
       logger = options.logger;
       cache = options.cache;
+      configFetcher = options.configFetcher;
 
       if (options.requestTimeoutMs) {
         if (options.requestTimeoutMs < 0) {
@@ -225,7 +244,9 @@ export abstract class OptionsBase {
 
     this.cache = cache
       ? new ExternalConfigCache(cache, this.logger)
-      : (defaultCacheFactory ? defaultCacheFactory(this) : new InMemoryConfigCache());
+      : (kernel.defaultCacheFactory ? kernel.defaultCacheFactory(this) : new InMemoryConfigCache());
+
+    this.configFetcher = configFetcher ?? kernel.configFetcherFactory(this);
   }
 
   yieldHooks(): Hooks {
@@ -250,11 +271,9 @@ export class AutoPollOptions extends OptionsBase {
 
   maxInitWaitTimeSeconds: number = 5;
 
-  constructor(sdkKey: string, sdkType: string, sdkVersion: string, options?: IAutoPollOptions | null,
-    defaultCacheFactory?: ((options: OptionsBase) => IConfigCache) | null,
-    eventEmitterFactory?: (() => IEventEmitter) | null) {
+  constructor(sdkKey: string, kernel: IConfigCatKernel, options?: IAutoPollOptions | null) {
 
-    super(sdkKey, sdkType + "/a-" + sdkVersion, options, defaultCacheFactory, eventEmitterFactory);
+    super(sdkKey, kernel, kernel.sdkType + "/a-" + kernel.sdkVersion, options);
 
     if (options) {
 
@@ -282,23 +301,19 @@ export class AutoPollOptions extends OptionsBase {
 }
 
 export class ManualPollOptions extends OptionsBase {
-  constructor(sdkKey: string, sdkType: string, sdkVersion: string, options?: IManualPollOptions | null,
-    defaultCacheFactory?: ((options: OptionsBase) => IConfigCache) | null,
-    eventEmitterFactory?: (() => IEventEmitter) | null) {
+  constructor(sdkKey: string, kernel: IConfigCatKernel, options?: IManualPollOptions | null) {
 
-    super(sdkKey, sdkType + "/m-" + sdkVersion, options, defaultCacheFactory, eventEmitterFactory);
+    super(sdkKey, kernel, kernel.sdkType + "/m-" + kernel.sdkVersion, options);
   }
 }
 
 export class LazyLoadOptions extends OptionsBase {
 
   cacheTimeToLiveSeconds: number = 60;
 
-  constructor(sdkKey: string, sdkType: string, sdkVersion: string, options?: ILazyLoadingOptions | null,
-    defaultCacheFactory?: ((options: OptionsBase) => IConfigCache) | null,
-    eventEmitterFactory?: (() => IEventEmitter) | null) {
+  constructor(sdkKey: string, kernel: IConfigCatKernel, options?: ILazyLoadingOptions | null) {
 
-    super(sdkKey, sdkType + "/l-" + sdkVersion, options, defaultCacheFactory, eventEmitterFactory);
+    super(sdkKey, kernel, kernel.sdkType + "/l-" + kernel.sdkVersion, options);
 
     if (options) {
       if (options.cacheTimeToLiveSeconds != null) {

src/ConfigFetcher.ts

@@ -1,4 +1,3 @@
-import type { OptionsBase } from "./ConfigCatClientOptions";
 import type { ProjectConfig } from "./ProjectConfig";
 
 export const enum FetchStatus {
@@ -28,11 +27,56 @@ export class FetchResult {
   }
 }
 
-export interface IFetchResponse {
-  statusCode: number;
-  reasonPhrase: string;
-  eTag?: string;
-  body?: string;
+/** The request parameters for a ConfigCat config fetch operation. */
+export class FetchRequest {
+  constructor(
+    /** The URL of the config. */
+    readonly url: string,
+    /**
+     * The value of the `ETag` HTTP response header received during the last successful request (if any).
+     * If available, should be included in the HTTP request, either in the `If-None-Match` header or in the `ccetag` query string parameter.
+     *
+     * @remarks In browser runtime environments the `If-None-Match` header should be avoided because that may cause unnecessary CORS preflight requests.
+     */
+    readonly lastETag: string | undefined,
+    /** Additional HTTP request headers. Should be included in every HTTP request. */
+    readonly headers: ReadonlyArray<[name: string, value: string]>,
+    /** The request timeout to apply, configured via `IOptions.requestTimeoutMs`. */
+    readonly timeoutMs: number
+  ) {
+  }
+}
+
+/** The response data of a ConfigCat config fetch operation. */
+export class FetchResponse {
+  /** The value of the `ETag` HTTP response header. */
+  readonly eTag?: string;
+
+  protected readonly rayId?: string;
+
+  constructor(
+    /** The HTTP status code. */
+    readonly statusCode: number,
+    /** The HTTP reason phrase. */
+    readonly reasonPhrase: string,
+    /** The HTTP response headers. */
+    headers: ReadonlyArray<[name: string, value: string]>,
+    /** The response body. */
+    readonly body?: string
+  ) {
+    let eTag: string | undefined, rayId: string | undefined;
+
+    for (const [name, value] of headers) {
+      const normalizedName = name.toLowerCase();
+      if (eTag == null && normalizedName === "etag") {
+        this.eTag = eTag = value;
+        if (rayId != null) break;
+      } else if (rayId == null && normalizedName === "cf-ray") {
+        this.rayId = rayId = value;
+        if (eTag != null) break;
+      }
+    }
+  }
 }
 
 export type FetchErrorCauses = {
@@ -74,6 +118,13 @@ export class FetchError<TCause extends keyof FetchErrorCauses = keyof FetchError
   }
 }
 
-export interface IConfigFetcher {
-  fetchLogic(options: OptionsBase, lastEtag: string | null): Promise<IFetchResponse>;
+/** Defines the interface used by the ConfigCat SDK to perform ConfigCat config fetch operations. */
+export interface IConfigCatConfigFetcher {
+  /**
+   * Fetches the JSON content of the requested config asynchronously.
+   * @param request The fetch request.
+   * @returns A promise that fulfills the fetch response.
+   * @throws {FetchErrorException} The fetch operation failed.
+   */
+  fetchAsync(request: FetchRequest): Promise<FetchResponse>;
 }