Merge pull request #315 from splitio/add_getOptions

Add `getOptions` method

Author: EmilianoSanchez

CHANGES.txt

@@ -1,4 +1,6 @@
-1.15.1 (May 28, 2024)
+1.16.0 (June 13, 2024)
+ - Added the `getOptions` method to the `IPlatform` interface to allow the SDK to pass request options to the `fetch` function and `EventSource` constructor when fetching data from the Split servers. The method is optional and, if provided, it is called twice: first for the `fetch` options and then for the `EventSource` options.
+   Useful for advanced use cases like configuring a proxy or validating certificates in NodeJS.
  - Updated the Redis storage to lazily import the `ioredis` dependency when the storage is created. This prevents errors when the SDK is imported or bundled in a .mjs file, as `ioredis` is a CommonJS module.
  - Bugfixing - Restored some input validation error logs that were removed in version 1.12.0. The logs inform the user when the `getTreatment(s)` methods are called with an invalid value as feature flag name or flag set name.
  - Bugfixing - Fixed localhost mode for client-side SDKs to emit SDK_UPDATE when mocked feature flags are updated in the `features` property of the config object (Related to issue https://github.com/splitio/javascript-browser-client/issues/119).

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@splitsoftware/splitio-commons",
-  "version": "1.15.1-rc.1",
+  "version": "1.15.1-rc.3",
   "description": "Split JavaScript SDK common components",
   "main": "cjs/index.js",
   "module": "esm/index.js",

package.json

@@ -49,6 +49,7 @@ const fullParamsForSyncSDK = {
   platform: {
     getEventSource: jest.fn(),
     getFetch: jest.fn(),
+    getOptions: jest.fn(),
     EventEmitter
   },
   splitApiFactory: jest.fn(),

src/sdkFactory/__tests__/index.spec.ts

@@ -17,11 +17,15 @@ export interface IPlatform {
   /**
    * If provided, it is used to retrieve the Fetch API for HTTP requests. Otherwise, the global fetch is used.
    */
-  getFetch?: () => (IFetch | undefined)
+  getFetch?: (settings: ISettings) => (IFetch | undefined)
+  /**
+   * If provided, it is used to pass additional options to fetch and eventsource calls.
+   */
+  getOptions?: (settings: ISettings) => object
   /**
    * If provided, it is used to retrieve the EventSource constructor for streaming support.
    */
-  getEventSource?: () => (IEventSourceConstructor | undefined)
+  getEventSource?: (settings: ISettings) => (IEventSourceConstructor | undefined)
   /**
    * EventEmitter constructor, like NodeJS.EventEmitter or a polyfill.
    */

src/sdkFactory/types.ts

@@ -22,15 +22,15 @@ function userKeyToQueryParam(userKey: string) {
  */
 export function splitApiFactory(
   settings: ISettings,
-  platform: Pick<IPlatform, 'getFetch'>,
+  platform: IPlatform,
   telemetryTracker: ITelemetryTracker
 ): ISplitApi {
 
   const urls = settings.urls;
   const filterQueryString = settings.sync.__splitFiltersValidation && settings.sync.__splitFiltersValidation.queryString;
   const SplitSDKImpressionsMode = settings.sync.impressionsMode;
   const flagSpecVersion = settings.sync.flagSpecVersion;
-  const splitHttpClient = splitHttpClientFactory(settings, platform.getFetch);
+  const splitHttpClient = splitHttpClientFactory(settings, platform);
 
   return {
     // @TODO throw errors if health check requests fail, to log them in the Synchronizer

src/services/splitApi.ts

@@ -10,12 +10,13 @@ const messageNoFetch = 'Global fetch API is not available.';
  * Factory of Split HTTP clients, which are HTTP clients with predefined headers for Split endpoints.
  *
  * @param settings SDK settings, used to access authorizationKey, logger instance and metadata (SDK version, ip and hostname) to set additional headers
- * @param getFetch retrieves the Fetch API for HTTP requests
+ * @param platform object containing environment-specific dependencies
  */
-export function splitHttpClientFactory(settings: ISettings, getFetch?: IPlatform['getFetch']): ISplitHttpClient {
+export function splitHttpClientFactory(settings: ISettings, { getOptions, getFetch }: IPlatform): ISplitHttpClient {
 
   const { log, core: { authorizationKey }, version, runtime: { ip, hostname } } = settings;
-  const fetch = getFetch && getFetch();
+  const options = getOptions && getOptions(settings);
+  const fetch = getFetch && getFetch(settings);
 
   // if fetch is not available, log Error
   if (!fetch) log.error(ERROR_CLIENT_CANNOT_GET_READY, [messageNoFetch]);
@@ -32,11 +33,11 @@ export function splitHttpClientFactory(settings: ISettings, getFetch?: IPlatform
 
   return function httpClient(url: string, reqOpts: IRequestOptions = {}, latencyTracker: (error?: NetworkError) => void = () => { }, logErrorsAsInfo: boolean = false): Promise<IResponse> {
 
-    const request = {
+    const request = objectAssign({
       headers: reqOpts.headers ? objectAssign({}, headers, reqOpts.headers) : headers,
       method: reqOpts.method || 'GET',
       body: reqOpts.body
-    };
+    }, options);
 
     // using `fetch(url, options)` signature to work with unfetch, a lightweight ponyfill of fetch API.
     return fetch ? fetch(url, request)

src/services/splitHttpClient.ts

@@ -18,11 +18,12 @@ const EXPECTED_HEADERS = {
 
 test('SSClient / instance creation throws error if EventSource is not provided', () => {
   expect(() => { new SSEClient(settings); }).toThrow(Error);
-  expect(() => { new SSEClient(settings, false, () => undefined); }).toThrow(Error);
+  expect(() => { new SSEClient(settings, false, {}); }).toThrow(Error);
+  expect(() => { new SSEClient(settings, false, { getEventSource: () => undefined }); }).toThrow(Error);
 });
 
 test('SSClient / instance creation success if EventSource is provided', () => {
-  const instance = new SSEClient(settings, false, () => EventSourceMock);
+  const instance = new SSEClient(settings, false, { getEventSource: () => EventSourceMock });
   expect(instance.eventSource).toBe(EventSourceMock);
 });
 
@@ -35,7 +36,7 @@ test('SSClient / setEventHandler, open and close methods', () => {
   };
 
   // instance SSEClient
-  const instance = new SSEClient(settings, false, () => EventSourceMock);
+  const instance = new SSEClient(settings, false, { getEventSource: () => EventSourceMock });
   instance.setEventHandler(handler);
 
   // open connection
@@ -81,13 +82,13 @@ test('SSClient / setEventHandler, open and close methods', () => {
 
 test('SSClient / open method: URL with metadata query params', () => {
 
-  const instance = new SSEClient(settings, false, () => EventSourceMock);
+  const instance = new SSEClient(settings, false, { getEventSource: () => EventSourceMock });
   instance.open(authDataSample);
 
   const EXPECTED_BROWSER_URL = EXPECTED_URL + `&SplitSDKVersion=${settings.version}&SplitSDKClientKey=${EXPECTED_HEADERS.SplitSDKClientKey}`;
 
   expect(instance.connection.url).toBe(EXPECTED_BROWSER_URL); // URL is properly set for streaming connection
-  expect(instance.connection.__eventSourceInitDict).toBe(undefined); // No headers are passed for streaming connection
+  expect(instance.connection.__eventSourceInitDict).toEqual({}); // No headers are passed for streaming connection
 });
 
 test('SSClient / open method: URL and metadata headers with IP and Hostname', () => {
@@ -99,7 +100,7 @@ test('SSClient / open method: URL and metadata headers with IP and Hostname', ()
       hostname: 'some hostname'
     }
   };
-  const instance = new SSEClient(settingsWithRuntime, true, () => EventSourceMock);
+  const instance = new SSEClient(settingsWithRuntime, true, { getEventSource: () => EventSourceMock });
   instance.open(authDataSample);
 
   expect(instance.connection.url).toBe(EXPECTED_URL); // URL is properly set for streaming connection
@@ -114,9 +115,23 @@ test('SSClient / open method: URL and metadata headers with IP and Hostname', ()
 
 test('SSClient / open method: URL and metadata headers without IP and Hostname', () => {
 
-  const instance = new SSEClient(settings, true, () => EventSourceMock);
+  const instance = new SSEClient(settings, true, { getEventSource: () => EventSourceMock });
   instance.open(authDataSample);
 
   expect(instance.connection.url).toBe(EXPECTED_URL); // URL is properly set for streaming connection
   expect(instance.connection.__eventSourceInitDict).toEqual({ headers: EXPECTED_HEADERS }); // Headers are properly set for streaming connection
 });
+
+test('SSClient / open method: URL, metadata headers and options', () => {
+  const platform = { getEventSource: jest.fn(() => EventSourceMock), getOptions: jest.fn(() => ({ withCredentials: true })) };
+
+  const instance = new SSEClient(settings, true, platform);
+  instance.open(authDataSample);
+
+  expect(instance.connection.url).toBe(EXPECTED_URL); // URL is properly set for streaming connection
+  expect(instance.connection.__eventSourceInitDict).toEqual({ headers: EXPECTED_HEADERS, withCredentials: true }); // Headers and options are properly set for streaming connection
+
+  // Assert that getEventSource and getOptions were called once with settings
+  expect(platform.getEventSource.mock.calls).toEqual([[settings]]);
+  expect(platform.getOptions.mock.calls).toEqual([[settings]]);
+});

src/sync/streaming/SSEClient/__tests__/index.spec.ts

@@ -1,6 +1,8 @@
+import { IPlatform } from '../../../sdkFactory/types';
 import { IEventSourceConstructor } from '../../../services/types';
 import { ISettings } from '../../../types';
 import { isString } from '../../../utils/lang';
+import { objectAssign } from '../../../utils/lang/objectAssign';
 import { IAuthTokenPushEnabled } from '../AuthClient/types';
 import { ISSEClient, ISseEventHandler } from './types';
 
@@ -39,24 +41,26 @@ export class SSEClient implements ISSEClient {
   handler?: ISseEventHandler;
   useHeaders?: boolean;
   headers: Record<string, string>;
+  options?: object;
 
   /**
    * SSEClient constructor.
    *
    * @param settings Validated settings.
    * @param useHeaders True to send metadata as headers or false to send as query params. If `true`, the provided EventSource must support headers.
-   * @param getEventSource Function to get the EventSource constructor.
-   * @throws 'EventSource API is not available. ' if EventSource is not available.
+   * @param platform object containing environment-specific dependencies
+   * @throws 'EventSource API is not available.' if EventSource is not available.
    */
-  constructor(settings: ISettings, useHeaders?: boolean, getEventSource?: () => (IEventSourceConstructor | undefined)) {
-    this.eventSource = getEventSource && getEventSource();
+  constructor(settings: ISettings, useHeaders: boolean, { getEventSource, getOptions }: IPlatform) {
+    this.eventSource = getEventSource && getEventSource(settings);
     // if eventSource is not available, throw an exception
-    if (!this.eventSource) throw new Error('EventSource API is not available. ');
+    if (!this.eventSource) throw new Error('EventSource API is not available.');
 
     this.streamingUrl = settings.urls.streaming + '/sse';
     // @TODO get `useHeaders` flag from `getEventSource`, to use EventSource headers on client-side SDKs when possible.
     this.useHeaders = useHeaders;
     this.headers = buildSSEHeaders(settings);
+    this.options = getOptions && getOptions(settings);
   }
 
   setEventHandler(handler: ISseEventHandler) {
@@ -84,8 +88,8 @@ export class SSEClient implements ISSEClient {
       // For client-side SDKs, SplitSDKClientKey and SplitSDKClientKey metadata is passed as query params,
       // because native EventSource implementations for browser doesn't support headers.
       this.useHeaders ? url : url + `&SplitSDKVersion=${this.headers.SplitSDKVersion}&SplitSDKClientKey=${this.headers.SplitSDKClientKey}`,
-      // @ts-ignore. For server-side SDKs, metadata is passed via headers. EventSource must support headers, like 'eventsource' package for Node.
-      this.useHeaders ? { headers: this.headers } : undefined
+      // For server-side SDKs, metadata is passed via headers. EventSource must support headers, like 'eventsource' package for Node.
+      objectAssign(this.useHeaders ? { headers: this.headers } : {}, this.options)
     );
 
     if (this.handler) { // no need to check if SSEClient is used only by PushManager

src/sync/streaming/SSEClient/index.ts

@@ -42,7 +42,7 @@ export function pushManagerFactory(
   let sseClient: ISSEClient;
   try {
     // `useHeaders` false for client-side, even if the platform EventSource supports headers (e.g., React Native).
-    sseClient = new SSEClient(settings, userKey ? false : true, platform.getEventSource);
+    sseClient = new SSEClient(settings, userKey ? false : true, platform);
   } catch (e) {
     log.warn(STREAMING_FALLBACK, [e]);
     return;