@splitsoftware/splitio-commons 0.1.1-canary.6 → 0.1.1-rc.18

package/src/sync/streaming/pushManager.ts

@@ -3,7 +3,6 @@ import { ISSEClient } from './SSEClient/types';
 import { IStorageSync } from '../../storages/types';
 import { IReadinessManager } from '../../readiness/types';
 import { ISegmentsSyncTask, IPollingManager } from '../polling/types';
-import { IUpdateWorker } from './UpdateWorkers/types';
 import objectAssign from 'object-assign';
 import Backoff from '../../utils/Backoff';
 import SSEHandlerFactory from './SSEHandler';
@@ -16,9 +15,14 @@ import SSEClient from './SSEClient';
 import { IFetchAuth } from '../../services/types';
 import { ISettings } from '../../types';
 import { getMatching } from '../../utils/key';
-import { MY_SEGMENTS_UPDATE, PUSH_NONRETRYABLE_ERROR, PUSH_SUBSYSTEM_DOWN, SECONDS_BEFORE_EXPIRATION, SEGMENT_UPDATE, SPLIT_KILL, SPLIT_UPDATE, PUSH_RETRYABLE_ERROR, PUSH_SUBSYSTEM_UP } from './constants';
+import { MY_SEGMENTS_UPDATE, MY_SEGMENTS_UPDATE_V2, PUSH_NONRETRYABLE_ERROR, PUSH_SUBSYSTEM_DOWN, SECONDS_BEFORE_EXPIRATION, SEGMENT_UPDATE, SPLIT_KILL, SPLIT_UPDATE, PUSH_RETRYABLE_ERROR, PUSH_SUBSYSTEM_UP, ControlType } from './constants';
 import { IPlatform } from '../../sdkFactory/types';
-import { STREAMING_FALLBACK, STREAMING_REFRESH_TOKEN, STREAMING_CONNECTING, STREAMING_DISABLED, ERROR_STREAMING_AUTH, STREAMING_DISCONNECTING, STREAMING_RECONNECT } from '../../logger/constants';
+import { STREAMING_FALLBACK, STREAMING_REFRESH_TOKEN, STREAMING_CONNECTING, STREAMING_DISABLED, ERROR_STREAMING_AUTH, STREAMING_DISCONNECTING, STREAMING_RECONNECT, STREAMING_PARSING_MY_SEGMENTS_UPDATE_V2 } from '../../logger/constants';
+import { KeyList, UpdateStrategy } from './SSEHandler/types';
+import { isInBitmap, parseBitmap, parseKeyList } from './mySegmentsV2utils';
+import { ISet, _Set } from '../../utils/lang/sets';
+import { Hash64, hash64 } from '../../utils/murmur3/murmur3_64';
+import { IAuthTokenPushEnabled } from './AuthClient/types';
 
 /**
  * PushManager factory:
@@ -34,11 +38,15 @@ export default function pushManagerFactory(
   settings: ISettings,
 ): IPushManagerCS | undefined {
 
+  // `userKey` is the matching key of main client in client-side SDK.
+  // It can be used to check if running on client-side or server-side SDK.
+  const userKey = settings.core.key ? getMatching(settings.core.key) : undefined; //
   const log = settings.log;
 
   let sseClient: ISSEClient;
   try {
-    sseClient = new SSEClient(settings.urls.streaming, platform.getEventSource);
+    // `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);
   } catch (e) {
     log.warn(STREAMING_FALLBACK, [e]);
     return;
@@ -50,54 +58,67 @@ export default function pushManagerFactory(
   const sseHandler = SSEHandlerFactory(log, pushEmitter);
   sseClient.setEventHandler(sseHandler);
 
+  // init workers
+  const segmentsUpdateWorker = userKey ? new MySegmentsUpdateWorker(pollingManager.segmentsSyncTask) : new SegmentsUpdateWorker(storage.segments, pollingManager.segmentsSyncTask);
+  // For server-side we pass the segmentsSyncTask, used by SplitsUpdateWorker to fetch new segments
+  const splitsUpdateWorker = new SplitsUpdateWorker(storage.splits, pollingManager.splitsSyncTask, readiness.splits, userKey ? undefined : pollingManager.segmentsSyncTask);
+
   // [Only for client-side] map of hashes to user keys, to dispatch MY_SEGMENTS_UPDATE events to the corresponding MySegmentsUpdateWorker
   const userKeyHashes: Record<string, string> = {};
-  const userKey = settings.core.key ? getMatching(settings.core.key) : undefined; // matching key of main client
+  // [Only for client-side] map of user keys to their corresponding hash64 and MySegmentsUpdateWorkers.
+  // Hash64 is used to process MY_SEGMENTS_UPDATE_V2 events and dispatch actions to the corresponding MySegmentsUpdateWorker.
+  const clients: Record<string, { hash64: Hash64, worker: MySegmentsUpdateWorker }> = {};
   if (userKey) {
     const hash = hashUserKey(userKey);
     userKeyHashes[hash] = userKey;
+    clients[userKey] = { hash64: hash64(userKey), worker: segmentsUpdateWorker as MySegmentsUpdateWorker };
   }
 
-  // init workers
-  const segmentsUpdateWorker = userKey ? new MySegmentsUpdateWorker(pollingManager.segmentsSyncTask) : new SegmentsUpdateWorker(storage.segments, pollingManager.segmentsSyncTask);
-  // [Only for server-side] we pass the segmentsSyncTask, used by SplitsUpdateWorker to fetch new segments
-  const splitsUpdateWorker = new SplitsUpdateWorker(storage.splits, pollingManager.splitsSyncTask, readiness.splits, userKey ? undefined : pollingManager.segmentsSyncTask);
-  // [Only for client-side] map of user keys to their corresponding MySegmentsUpdateWorkers. It has a two-fold intention:
-  // - stop workers all together when push is disconnected
-  // - keep the current list of user keys to authenticate
-  const workers: Record<string, IUpdateWorker> = {};
-  if (userKey) workers[userKey] = segmentsUpdateWorker;
-
   // [Only for client-side] variable to flag that a new client was added. It is needed to reconnect streaming.
   let connectForNewClient = false;
 
-  // flag that indicates if `disconnectPush` was called, either by the SyncManager (when the client is destroyed) or by a PUSH_NONRETRYABLE_ERROR error.
+  // flag that indicates if `stop/disconnectPush` was called, either by the SyncManager, when the client is destroyed, or due to a PUSH_NONRETRYABLE_ERROR error.
   // It is used to halt the `connectPush` process if it was in progress.
   let disconnected: boolean | undefined;
+  // flag that indicates a PUSH_NONRETRYABLE_ERROR, condition with which starting pushManager again is ignored.
+  let disabled: boolean | undefined; // `disabled` implies `disconnected === true`
 
   /** PushManager functions related to initialization */
 
   const connectPushRetryBackoff = new Backoff(connectPush, settings.scheduler.pushRetryBackoffBase);
 
-  let timeoutId: ReturnType<typeof setTimeout>;
+  let timeoutIdTokenRefresh: ReturnType<typeof setTimeout>;
+  let timeoutIdSseOpen: ReturnType<typeof setTimeout>;
+
+  function scheduleTokenRefreshAndSse(authData: IAuthTokenPushEnabled) {
+    // clear scheduled tasks if exist
+    if (timeoutIdTokenRefresh) clearTimeout(timeoutIdTokenRefresh);
+    if (timeoutIdSseOpen) clearTimeout(timeoutIdSseOpen);
 
-  function scheduleTokenRefresh(issuedAt: number, expirationTime: number) {
-    // clear scheduled token refresh if exists (needed when resuming PUSH)
-    if (timeoutId) clearTimeout(timeoutId);
+    // Set token refresh 10 minutes before `expirationTime - issuedAt`
+    const decodedToken = authData.decodedToken;
+    const refreshTokenDelay = decodedToken.exp - decodedToken.iat - SECONDS_BEFORE_EXPIRATION;
+    // Default connDelay of 60 secs
+    const connDelay = typeof authData.connDelay === 'number' && authData.connDelay >= 0 ? authData.connDelay : 60;
 
-    // Set token refresh 10 minutes before expirationTime
-    const delayInSeconds = expirationTime - issuedAt - SECONDS_BEFORE_EXPIRATION;
+    log.info(STREAMING_REFRESH_TOKEN, [refreshTokenDelay, connDelay]);
 
-    log.info(STREAMING_REFRESH_TOKEN, [delayInSeconds]);
+    timeoutIdTokenRefresh = setTimeout(connectPush, refreshTokenDelay * 1000);
 
-    timeoutId = setTimeout(connectPush, delayInSeconds * 1000);
+    timeoutIdSseOpen = setTimeout(() => {
+      // halt if disconnected
+      if (disconnected) return;
+      sseClient.open(authData);
+    }, connDelay * 1000);
   }
 
   function connectPush() {
+    // Guard condition in case `stop/disconnectPush` has been called (e.g., calling SDK destroy, or app signal close/background)
+    if (disconnected) return;
+    log.info(STREAMING_CONNECTING, [disconnected === undefined ? '' : 'Re-']);
     disconnected = false;
-    log.info(STREAMING_CONNECTING);
 
-    const userKeys = userKey ? Object.keys(workers) : undefined;
+    const userKeys = userKey ? Object.keys(clients) : undefined;
     authenticate(userKeys).then(
       function (authData) {
         if (disconnected) return;
@@ -111,12 +132,10 @@ export default function pushManagerFactory(
         }
 
         // [Only for client-side] don't open SSE connection if a new shared client was added, since it means that a new authentication is taking place
-        if (userKeys && userKeys.length < Object.keys(workers).length) return;
+        if (userKeys && userKeys.length < Object.keys(clients).length) return;
 
-        // Connect to SSE and schedule refresh token
-        const decodedToken = authData.decodedToken;
-        sseClient.open(authData);
-        scheduleTokenRefresh(decodedToken.iat, decodedToken.exp);
+        // Schedule SSE connection and refresh token
+        scheduleTokenRefreshAndSse(authData);
       }
     ).catch(
       function (error) {
@@ -138,11 +157,15 @@ export default function pushManagerFactory(
 
   // close SSE connection and cancel scheduled tasks
   function disconnectPush() {
+    // Halt disconnecting, just to avoid redundant logs if called multiple times
+    if (disconnected) return;
     disconnected = true;
-    log.info(STREAMING_DISCONNECTING);
+
     sseClient.close();
+    log.info(STREAMING_DISCONNECTING);
 
-    if (timeoutId) clearTimeout(timeoutId);
+    if (timeoutIdTokenRefresh) clearTimeout(timeoutIdTokenRefresh);
+    if (timeoutIdSseOpen) clearTimeout(timeoutIdSseOpen);
     connectPushRetryBackoff.reset();
 
     stopWorkers();
@@ -151,18 +174,23 @@ export default function pushManagerFactory(
   // cancel scheduled fetch retries of Splits, Segments, and MySegments Update Workers
   function stopWorkers() {
     splitsUpdateWorker.backoff.reset();
-    if (userKey) forOwn(workers, worker => worker.backoff.reset());
+    if (userKey) forOwn(clients, ({ worker }) => worker.backoff.reset());
     else segmentsUpdateWorker.backoff.reset();
   }
 
   pushEmitter.on(PUSH_SUBSYSTEM_DOWN, stopWorkers);
 
-  // restart backoff retry counter once push is connected
-  pushEmitter.on(PUSH_SUBSYSTEM_UP, () => { connectPushRetryBackoff.reset(); });
+  // Only required when streaming connects after a PUSH_RETRYABLE_ERROR.
+  // Otherwise it is unnecessary (e.g, STREAMING_RESUMED).
+  pushEmitter.on(PUSH_SUBSYSTEM_UP, () => {
+    connectPushRetryBackoff.reset();
+    stopWorkers();
+  });
 
   /** Fallbacking without retry due to: STREAMING_DISABLED control event, or 'pushEnabled: false', or non-recoverable SSE and Authentication errors */
 
   pushEmitter.on(PUSH_NONRETRYABLE_ERROR, function handleNonRetryableError() {
+    disabled = true;
     // Note: `stopWorkers` is been called twice, but it is not harmful
     disconnectPush();
     pushEmitter.emit(PUSH_SUBSYSTEM_DOWN); // no harm if polling already
@@ -182,21 +210,93 @@ export default function pushManagerFactory(
     pushEmitter.emit(PUSH_SUBSYSTEM_DOWN); // no harm if polling already
   });
 
+  /** STREAMING_RESET notification. Unlike a PUSH_RETRYABLE_ERROR, it doesn't emit PUSH_SUBSYSTEM_DOWN to fallback polling */
+
+  pushEmitter.on(ControlType.STREAMING_RESET, function handleStreamingReset() {
+    if (disconnected) return; // should never happen
+
+    // Minimum required clean-up.
+    // `disconnectPush` cannot be called because it sets `disconnected` and thus `connectPush` will not execute
+    if (timeoutIdTokenRefresh) clearTimeout(timeoutIdTokenRefresh);
+
+    connectPush();
+  });
+
   /** Functions related to synchronization (Queues and Workers in the spec) */
 
   pushEmitter.on(SPLIT_KILL, splitsUpdateWorker.killSplit);
   pushEmitter.on(SPLIT_UPDATE, splitsUpdateWorker.put);
+
   if (userKey) {
     pushEmitter.on(MY_SEGMENTS_UPDATE, function handleMySegmentsUpdate(parsedData, channel) {
       const userKeyHash = channel.split('_')[2];
       const userKey = userKeyHashes[userKeyHash];
-      if (userKey && workers[userKey]) { // check context since it can be undefined if client has been destroyed
-        const mySegmentsUpdateWorker = workers[userKey];
-        mySegmentsUpdateWorker.put(
+      if (userKey && clients[userKey]) { // check existence since it can be undefined if client has been destroyed
+        clients[userKey].worker.put(
           parsedData.changeNumber,
           parsedData.includesPayload ? parsedData.segmentList ? parsedData.segmentList : [] : undefined);
       }
     });
+    pushEmitter.on(MY_SEGMENTS_UPDATE_V2, function handleMySegmentsUpdate(parsedData) {
+      switch (parsedData.u) {
+        case UpdateStrategy.BoundedFetchRequest: {
+          let bitmap: Uint8Array;
+          try {
+            bitmap = parseBitmap(parsedData.d, parsedData.c);
+          } catch (e) {
+            log.warn(STREAMING_PARSING_MY_SEGMENTS_UPDATE_V2, ['BoundedFetchRequest', e]);
+            break;
+          }
+
+          forOwn(clients, ({ hash64, worker }) => {
+            if (isInBitmap(bitmap, hash64.hex)) {
+              worker.put(parsedData.changeNumber); // fetch mySegments
+            }
+          });
+          return;
+        }
+        case UpdateStrategy.KeyList: {
+          let keyList: KeyList, added: ISet<string>, removed: ISet<string>;
+          try {
+            keyList = parseKeyList(parsedData.d, parsedData.c);
+            added = new _Set(keyList.a);
+            removed = new _Set(keyList.r);
+          } catch (e) {
+            log.warn(STREAMING_PARSING_MY_SEGMENTS_UPDATE_V2, ['KeyList', e]);
+            break;
+          }
+
+          forOwn(clients, ({ hash64, worker }) => {
+            const add = added.has(hash64.dec) ? true : removed.has(hash64.dec) ? false : undefined;
+            if (add !== undefined) {
+              worker.put(parsedData.changeNumber, {
+                name: parsedData.segmentName,
+                add
+              });
+            }
+          });
+          return;
+        }
+        case UpdateStrategy.SegmentRemoval:
+          if (!parsedData.segmentName) {
+            log.warn(STREAMING_PARSING_MY_SEGMENTS_UPDATE_V2, ['SegmentRemoval', 'No segment name was provided']);
+            break;
+          }
+
+          forOwn(clients, ({ worker }) =>
+            worker.put(parsedData.changeNumber, {
+              name: parsedData.segmentName,
+              add: false
+            })
+          );
+          return;
+      }
+
+      // `UpdateStrategy.UnboundedFetchRequest` and fallbacks of other cases
+      forOwn(clients, ({ worker }) => {
+        worker.put(parsedData.changeNumber);
+      });
+    });
   } else {
     pushEmitter.on(SEGMENT_UPDATE, (segmentsUpdateWorker as SegmentsUpdateWorker).put);
   }
@@ -206,17 +306,19 @@ export default function pushManagerFactory(
     Object.create(pushEmitter),
     {
       // Expose functionality for starting and stoping push mode:
-      stop: disconnectPush, // `handleNonRetryableError` cannot be used as `stop`, because it emits PUSH_SUBSYSTEM_DOWN event, which start polling.
+      stop: disconnectPush, // `handleNonRetryableError` cannot be used as `stop`, because it emits PUSH_SUBSYSTEM_DOWN event, which starts polling.
 
       start() {
+        // Guard condition to avoid calling `connectPush` again if the `start` method is called multiple times or if push has been disabled.
+        if (disabled || disconnected === false) return;
+        disconnected = false;
         // Run in next event-loop cycle for optimization on client-side: if multiple clients are created in the same cycle than the factory, only one authentication is performed.
         setTimeout(connectPush);
       },
 
       // [Only for client-side]
       add(userKey: string, mySegmentsSyncTask: ISegmentsSyncTask) {
-        const mySegmentsUpdateWorker = new MySegmentsUpdateWorker(mySegmentsSyncTask);
-        workers[userKey] = mySegmentsUpdateWorker;
+        clients[userKey] = { hash64: hash64(userKey), worker: new MySegmentsUpdateWorker(mySegmentsSyncTask) };
 
         const hash = hashUserKey(userKey);
 
@@ -239,6 +341,7 @@ export default function pushManagerFactory(
       remove(userKey: string) {
         const hash = hashUserKey(userKey);
         delete userKeyHashes[hash];
+        delete clients[userKey];
       }
     }
   );

package/src/sync/streaming/types.ts

@@ -1,4 +1,4 @@
-import { IMySegmentsUpdateData } from './SSEHandler/types';
+import { IMySegmentsUpdateData, IMySegmentsUpdateV2Data, ISegmentUpdateData, ISplitUpdateData, ISplitKillData } from './SSEHandler/types';
 import { ITask } from '../types';
 import { IPollingManager, ISegmentsSyncTask } from '../polling/types';
 import { IReadinessManager } from '../../readiness/types';
@@ -6,6 +6,7 @@ import { IFetchAuth } from '../../services/types';
 import { IStorageSync } from '../../storages/types';
 import { IEventEmitter, ISettings } from '../../types';
 import { IPlatform } from '../../sdkFactory/types';
+import { ControlType } from './constants';
 
 // Internal SDK events, subscribed by SyncManager and PushManager
 export type PUSH_SUBSYSTEM_UP = 'PUSH_SUBSYSTEM_UP'
@@ -15,6 +16,7 @@ export type PUSH_RETRYABLE_ERROR = 'PUSH_RETRYABLE_ERROR'
 
 // Update-type push notifications, handled by NotificationProcessor
 export type MY_SEGMENTS_UPDATE = 'MY_SEGMENTS_UPDATE';
+export type MY_SEGMENTS_UPDATE_V2 = 'MY_SEGMENTS_UPDATE_V2';
 export type SEGMENT_UPDATE = 'SEGMENT_UPDATE';
 export type SPLIT_KILL = 'SPLIT_KILL';
 export type SPLIT_UPDATE = 'SPLIT_UPDATE';
@@ -23,33 +25,23 @@ export type SPLIT_UPDATE = 'SPLIT_UPDATE';
 export type CONTROL = 'CONTROL';
 export type OCCUPANCY = 'OCCUPANCY';
 
-export type IPushEvent = PUSH_SUBSYSTEM_UP | PUSH_SUBSYSTEM_DOWN | PUSH_NONRETRYABLE_ERROR | PUSH_RETRYABLE_ERROR | MY_SEGMENTS_UPDATE | SEGMENT_UPDATE | SPLIT_UPDATE | SPLIT_KILL
+export type IPushEvent = PUSH_SUBSYSTEM_UP | PUSH_SUBSYSTEM_DOWN | PUSH_NONRETRYABLE_ERROR | PUSH_RETRYABLE_ERROR | MY_SEGMENTS_UPDATE | MY_SEGMENTS_UPDATE_V2 | SEGMENT_UPDATE | SPLIT_UPDATE | SPLIT_KILL | ControlType.STREAMING_RESET
+
+type IParsedData<T extends IPushEvent> =
+  T extends MY_SEGMENTS_UPDATE ? IMySegmentsUpdateData :
+  T extends MY_SEGMENTS_UPDATE_V2 ? IMySegmentsUpdateV2Data :
+  T extends SEGMENT_UPDATE ? ISegmentUpdateData :
+  T extends SPLIT_UPDATE ? ISplitUpdateData :
+  T extends SPLIT_KILL ? ISplitKillData : undefined;
 
 /**
  * EventEmitter used as Feedback Loop between the SyncManager and PushManager,
  * where the latter pushes messages and the former consumes it
  */
 export interface IPushEventEmitter extends IEventEmitter {
-  once<T extends IPushEvent>(event: T, listener: (...args:
-    T extends MY_SEGMENTS_UPDATE ? [parsedData: IMySegmentsUpdateData, channel: string] :
-    T extends SEGMENT_UPDATE ? [changeNumber: number, segmentName: string] :
-    T extends SPLIT_UPDATE ? [changeNumber: number] :
-    T extends SPLIT_KILL ? [changeNumber: number, splitName: string, defaultTreatment: string] :
-    any[]) => void): this;
-
-  on<T extends IPushEvent>(event: T, listener: (...args:
-    T extends MY_SEGMENTS_UPDATE ? [parsedData: IMySegmentsUpdateData, channel: string] :
-    T extends SEGMENT_UPDATE ? [changeNumber: number, segmentName: string] :
-    T extends SPLIT_UPDATE ? [changeNumber: number] :
-    T extends SPLIT_KILL ? [changeNumber: number, splitName: string, defaultTreatment: string] :
-    any[]) => void): this;
-
-  emit<T extends IPushEvent>(event: T, ...args:
-    T extends MY_SEGMENTS_UPDATE ? [parsedData: IMySegmentsUpdateData, channel: string] :
-    T extends SEGMENT_UPDATE ? [changeNumber: number, segmentName: string] :
-    T extends SPLIT_UPDATE ? [changeNumber: number] :
-    T extends SPLIT_KILL ? [changeNumber: number, splitName: string, defaultTreatment: string] :
-    any[]): boolean;
+  once<T extends IPushEvent>(event: T, listener: (parsedData: IParsedData<T>, channel: T extends MY_SEGMENTS_UPDATE ? string : undefined) => void): this;
+  on<T extends IPushEvent>(event: T, listener: (parsedData: IParsedData<T>, channel: T extends MY_SEGMENTS_UPDATE ? string : undefined) => void): this;
+  emit<T extends IPushEvent>(event: T, parsedData?: IParsedData<T>, channel?: T extends MY_SEGMENTS_UPDATE ? string : undefined): boolean;
 }
 
 /**

package/src/sync/submitters/metricsSyncTask.ts

@@ -45,5 +45,5 @@ export function latenciesSyncTaskFactory(
 ): ISyncTask {
 
   // don't retry metrics.
-  return submitterSyncTaskFactory(log, postMetricsLatencies, latenciesCache, metricsRefreshRate, 'latency metrics', latencyTracker, fromCache<number[]>('latencies'));
+  return submitterSyncTaskFactory(log, postMetricsLatencies, latenciesCache, metricsRefreshRate, 'latency metrics', latencyTracker, fromCache<number[]>('latencies'), 0, true);
 }

package/src/sync/submitters/submitterSyncTask.ts

@@ -17,6 +17,7 @@ export function submitterSyncTaskFactory<TState extends { length?: number }>(
   latencyTracker?: ITimeTracker,
   fromCacheToPayload?: (cacheData: TState) => any,
   maxRetries: number = 0,
+  debugLogs?: boolean
 ): ISyncTask<[], void> {
 
   let retries = 0;
@@ -27,7 +28,7 @@ export function submitterSyncTaskFactory<TState extends { length?: number }>(
     const data = sourceCache.state();
 
     const dataCount: number | '' = typeof data.length === 'number' ? data.length : '';
-    log.info(SUBMITTERS_PUSH, [dataCount, dataName]);
+    log[debugLogs ? 'debug' : 'info'](SUBMITTERS_PUSH, [dataCount, dataName]);
     const latencyTrackerStop = latencyTracker && latencyTracker.start();
 
     const jsonPayload = JSON.stringify(fromCacheToPayload ? fromCacheToPayload(data) : data);

package/src/sync/syncManagerFromFile.ts

@@ -0,0 +1,13 @@
+import { splitsParserFromFileFactory } from './offline/splitsParser/splitsParserFromFile';
+import { syncManagerOfflineFactory } from './syncManagerOffline';
+import { SplitIO } from '../types';
+import { LOCALHOST_MODE } from '../utils/constants';
+
+// Factory of Localhost SyncManager based on yaml file.
+// Requires Node 'fs' and 'path' APIs.
+export function LocalhostFromFile(): SplitIO.LocalhostFactory {
+  const localhost = syncManagerOfflineFactory(splitsParserFromFileFactory);
+  // @ts-ignore
+  localhost.type = LOCALHOST_MODE;
+  return localhost;
+}

package/src/sync/syncManagerFromObject.ts

@@ -0,0 +1,12 @@
+import { splitsParserFromSettingsFactory } from './offline/splitsParser/splitsParserFromSettings';
+import { syncManagerOfflineFactory } from './syncManagerOffline';
+import { SplitIO } from '../types';
+import { LOCALHOST_MODE } from '../utils/constants';
+
+// Factory of Localhost SyncManager based on JS object.
+export function LocalhostFromObject(): SplitIO.LocalhostFactory {
+  const localhost = syncManagerOfflineFactory(splitsParserFromSettingsFactory);
+  // @ts-ignore
+  localhost.type = LOCALHOST_MODE;
+  return localhost;
+}

package/src/sync/syncManagerOffline.ts

@@ -16,7 +16,7 @@ function flush() {
  * @param splitsParser e.g., `splitsParserFromFile`, `splitsParserFromSettings`.
  */
 export function syncManagerOfflineFactory(
-  splitsParser: ISplitsParser
+  splitsParserFactory: () => ISplitsParser
 ): (params: ISyncManagerFactoryParams) => ISyncManagerCS {
 
   /**
@@ -29,7 +29,7 @@ export function syncManagerOfflineFactory(
   }: ISyncManagerFactoryParams): ISyncManagerCS {
 
     return objectAssign(
-      fromObjectSyncTaskFactory(splitsParser, storage, readiness, settings),
+      fromObjectSyncTaskFactory(splitsParserFactory(), storage, readiness, settings),
       {
         // fake flush, that resolves immediately
         flush,
@@ -38,7 +38,7 @@ export function syncManagerOfflineFactory(
         shared(matchingKey: string, readinessManager: IReadinessManager): ISyncManager {
           return {
             start() {
-              // In LOCALHOST mode, shared clients are ready in the next event cycle than created
+              // In LOCALHOST mode, shared clients are ready in the next event-loop cycle than created
               // SDK_READY cannot be emitted directly because this will not update the readiness status
               setTimeout(() => {
                 readinessManager.segments.emit(SDK_SEGMENTS_ARRIVED); // SDK_SPLITS_ARRIVED emitted by main SyncManager

package/src/sync/syncManagerOnline.ts

@@ -75,17 +75,28 @@ export function syncManagerOnlineFactory(
       pollingManager.syncAll();
     }
 
-    let running = false;
+    if (pushManager) {
+      pushManager.on(PUSH_SUBSYSTEM_UP, stopPollingAndSyncAll);
+      pushManager.on(PUSH_SUBSYSTEM_DOWN, startPolling);
+    }
+
+    let running = false; // flag that indicates whether the syncManager has been started (true) or stopped (false)
+    let startFirstTime = true; // flag to distinguish calling the `start` method for the first time, to support pausing and resuming the synchronization
 
     return {
+      pushManager,
 
+      /**
+       * Method used to start the syncManager for the first time, or resume it after being stopped.
+       */
       start() {
         // start syncing splits and segments
         if (pushManager) {
-          pollingManager.syncAll();
-          pushManager.on(PUSH_SUBSYSTEM_UP, stopPollingAndSyncAll);
-          pushManager.on(PUSH_SUBSYSTEM_DOWN, startPolling);
-          // Run in next event-loop cycle as in client-side SyncManager
+          // Doesn't call `syncAll` when the syncManager is resuming
+          if (startFirstTime) {
+            pollingManager.syncAll();
+            startFirstTime = false;
+          }
           pushManager.start();
         } else {
           pollingManager.start();
@@ -96,6 +107,9 @@ export function syncManagerOnlineFactory(
         running = true;
       },
 
+      /**
+       * Method used to stop/pause the syncManager.
+       */
       stop() {
         // stop syncing
         if (pushManager) pushManager.stop();

package/src/sync/syncTask.ts

@@ -3,7 +3,7 @@ import { ILogger } from '../logger/types';
 import { ISyncTask } from './types';
 
 /**
- * Creates a syncTask that handles the periodic execution of a givan task ("start" and "stop" methods).
+ * Creates a syncTask that handles the periodic execution of a given task ("start" and "stop" methods).
  * The task can be executed once calling the "execute" method.
  * NOTE: Multiple calls to "execute" are not queued. Use "isExecuting" method to handle synchronization.
  *

package/src/sync/types.ts

@@ -3,6 +3,7 @@ import { IPlatform } from '../sdkFactory/types';
 import { ISplitApi } from '../services/types';
 import { IStorageSync } from '../storages/types';
 import { ISettings } from '../types';
+import { IPushManager } from './streaming/types';
 
 export interface ITask<Input extends any[] = []> {
   /**
@@ -41,7 +42,8 @@ export interface ITimeTracker {
 /** SyncManager */
 
 export interface ISyncManager extends ITask {
-  flush(): Promise<any>
+  flush(): Promise<any>,
+  pushManager?: IPushManager
 }
 
 export interface ISyncManagerCS extends ISyncManager {

package/src/trackers/impressionObserver/ImpressionObserver.ts

@@ -2,18 +2,16 @@ import { ImpressionDTO } from '../../types';
 import LRUCache from '../../utils/LRUCache';
 import { IImpressionObserver } from './types';
 
-export default class ImpressionObserver implements IImpressionObserver {
-  private cache: LRUCache<string | null, number>;
-  private hasher: (impression: ImpressionDTO) => string | null;
+export default class ImpressionObserver<K extends string | number> implements IImpressionObserver {
+  private cache: LRUCache<K, number>;
+  private hasher: (impression: ImpressionDTO) => K;
 
-  constructor(size: number, hasher: (impression: ImpressionDTO) => string | null) {
+  constructor(size: number, hasher: (impression: ImpressionDTO) => K) {
     this.cache = new LRUCache(size);
     this.hasher = hasher;
   }
 
   testAndSet(impression: ImpressionDTO) {
-    if (!impression) return;
-
     const hash = this.hasher(impression);
     const previous = this.cache.get(hash);
     this.cache.set(hash, impression.time);

package/src/trackers/impressionObserver/buildKey.ts

@@ -1,19 +1,5 @@
 import { ImpressionDTO } from '../../types';
 
-const UNKNOWN = 'UNKNOWN';
-
-function _unknownIfNull(s: any) {
-  return s ? s : UNKNOWN;
-}
-
-function _zeroIfNull(l: any) {
-  return l ? l : 0;
-}
-
-export default function buildKey(impression: ImpressionDTO) {
-  return `${_unknownIfNull(impression.keyName)}
-    :${_unknownIfNull(impression.feature)}
-    :${_unknownIfNull(impression.treatment)}
-    :${_unknownIfNull(impression.label)}
-    :${_zeroIfNull(impression.changeNumber)}`;
+export function buildKey(impression: ImpressionDTO) {
+  return `${impression.keyName}:${impression.feature}:${impression.treatment}:${impression.label}:${impression.changeNumber}`;
 }

package/src/trackers/impressionObserver/impressionObserverCS.ts

@@ -1,10 +1,10 @@
 import ImpressionObserver from './ImpressionObserver';
 import { hash } from '../../utils/murmur3/murmur3';
-import buildKey from './buildKey';
+import { buildKey } from './buildKey';
 import { ImpressionDTO } from '../../types';
 
 export function hashImpression32(impression: ImpressionDTO) {
-  return impression ? hash(buildKey(impression)).toString() : null;
+  return hash(buildKey(impression));
 }
 
 const LAST_SEEN_CACHE_SIZE = 500; // cache up to 500 impression hashes

package/src/trackers/impressionObserver/impressionObserverSS.ts

@@ -1,10 +1,10 @@
 import ImpressionObserver from './ImpressionObserver';
-import { hash128 } from '../../utils/murmur3/murmur3_128';
-import buildKey from './buildKey';
+import { hash128 } from '../../utils/murmur3/murmur3_128_x86';
+import { buildKey } from './buildKey';
 import { ImpressionDTO } from '../../types';
 
 export function hashImpression128(impression: ImpressionDTO) {
-  return impression ? hash128(buildKey(impression)).toString() : null;
+  return hash128(buildKey(impression));
 }
 
 const LAST_SEEN_CACHE_SIZE = 500000; // cache up to 500k impression hashes