launchdarkly-js-sdk-common 4.0.0 → 4.0.1

package/src/EventProcessor.js

@@ -0,0 +1,175 @@
+const EventSender = require('./EventSender');
+const EventSummarizer = require('./EventSummarizer');
+const UserFilter = require('./UserFilter');
+const errors = require('./errors');
+const messages = require('./messages');
+const utils = require('./utils');
+
+function EventProcessor(
+  platform,
+  options,
+  environmentId,
+  diagnosticsAccumulator = null,
+  emitter = null,
+  sender = null
+) {
+  const processor = {};
+  const eventSender = sender || EventSender(platform, environmentId, options);
+  const mainEventsUrl = options.eventsUrl + '/events/bulk/' + environmentId;
+  const summarizer = EventSummarizer();
+  const userFilter = UserFilter(options);
+  const inlineUsers = options.inlineUsersInEvents;
+  const samplingInterval = options.samplingInterval;
+  const eventCapacity = options.eventCapacity;
+  const flushInterval = options.flushInterval;
+  const logger = options.logger;
+  let queue = [];
+  let lastKnownPastTime = 0;
+  let disabled = false;
+  let exceededCapacity = false;
+  let flushTimer;
+
+  function shouldSampleEvent() {
+    return samplingInterval === 0 || Math.floor(Math.random() * samplingInterval) === 0;
+  }
+
+  function shouldDebugEvent(e) {
+    if (e.debugEventsUntilDate) {
+      // The "last known past time" comes from the last HTTP response we got from the server.
+      // In case the client's time is set wrong, at least we know that any expiration date
+      // earlier than that point is definitely in the past.  If there's any discrepancy, we
+      // want to err on the side of cutting off event debugging sooner.
+      return e.debugEventsUntilDate > lastKnownPastTime && e.debugEventsUntilDate > new Date().getTime();
+    }
+    return false;
+  }
+
+  // Transform an event from its internal format to the format we use when sending a payload.
+  function makeOutputEvent(e) {
+    const ret = utils.extend({}, e);
+    if (e.kind === 'alias') {
+      // alias events do not require any transformation
+      return ret;
+    }
+    if (inlineUsers || e.kind === 'identify') {
+      // identify events always have an inline user
+      ret.user = userFilter.filterUser(e.user);
+    } else {
+      ret.userKey = e.user.key;
+      delete ret['user'];
+    }
+    if (e.kind === 'feature') {
+      delete ret['trackEvents'];
+      delete ret['debugEventsUntilDate'];
+    }
+    return ret;
+  }
+
+  function addToOutbox(event) {
+    if (queue.length < eventCapacity) {
+      queue.push(event);
+      exceededCapacity = false;
+    } else {
+      if (!exceededCapacity) {
+        exceededCapacity = true;
+        logger.warn(messages.eventCapacityExceeded());
+      }
+      if (diagnosticsAccumulator) {
+        // For diagnostic events, we track how many times we had to drop an event due to exceeding the capacity.
+        diagnosticsAccumulator.incrementDroppedEvents();
+      }
+    }
+  }
+
+  processor.enqueue = function(event) {
+    if (disabled) {
+      return;
+    }
+    let addFullEvent = false;
+    let addDebugEvent = false;
+
+    // Add event to the summary counters if appropriate
+    summarizer.summarizeEvent(event);
+
+    // Decide whether to add the event to the payload. Feature events may be added twice, once for
+    // the event (if tracked) and once for debugging.
+    if (event.kind === 'feature') {
+      if (shouldSampleEvent()) {
+        addFullEvent = !!event.trackEvents;
+        addDebugEvent = shouldDebugEvent(event);
+      }
+    } else {
+      addFullEvent = shouldSampleEvent();
+    }
+
+    if (addFullEvent) {
+      addToOutbox(makeOutputEvent(event));
+    }
+    if (addDebugEvent) {
+      const debugEvent = utils.extend({}, event, { kind: 'debug' });
+      debugEvent.user = userFilter.filterUser(debugEvent.user);
+      delete debugEvent['trackEvents'];
+      delete debugEvent['debugEventsUntilDate'];
+      addToOutbox(debugEvent);
+    }
+  };
+
+  processor.flush = function() {
+    if (disabled) {
+      return Promise.resolve();
+    }
+    const eventsToSend = queue;
+    const summary = summarizer.getSummary();
+    summarizer.clearSummary();
+    if (summary) {
+      summary.kind = 'summary';
+      eventsToSend.push(summary);
+    }
+    if (diagnosticsAccumulator) {
+      // For diagnostic events, we record how many events were in the queue at the last flush (since "how
+      // many events happened to be in the queue at the moment we decided to send a diagnostic event" would
+      // not be a very useful statistic).
+      diagnosticsAccumulator.setEventsInLastBatch(eventsToSend.length);
+    }
+    if (eventsToSend.length === 0) {
+      return Promise.resolve();
+    }
+    queue = [];
+    logger.debug(messages.debugPostingEvents(eventsToSend.length));
+    return eventSender.sendEvents(eventsToSend, mainEventsUrl).then(responseInfo => {
+      if (responseInfo) {
+        if (responseInfo.serverTime) {
+          lastKnownPastTime = responseInfo.serverTime;
+        }
+        if (!errors.isHttpErrorRecoverable(responseInfo.status)) {
+          disabled = true;
+        }
+        if (responseInfo.status >= 400) {
+          utils.onNextTick(() => {
+            emitter.maybeReportError(
+              new errors.LDUnexpectedResponseError(
+                messages.httpErrorMessage(responseInfo.status, 'event posting', 'some events were dropped')
+              )
+            );
+          });
+        }
+      }
+    });
+  };
+
+  processor.start = function() {
+    const flushTick = () => {
+      processor.flush();
+      flushTimer = setTimeout(flushTick, flushInterval);
+    };
+    flushTimer = setTimeout(flushTick, flushInterval);
+  };
+
+  processor.stop = function() {
+    clearTimeout(flushTimer);
+  };
+
+  return processor;
+}
+
+module.exports = EventProcessor;

package/src/EventSender.js

@@ -0,0 +1,87 @@
+const errors = require('./errors');
+const utils = require('./utils');
+const { v1: uuidv1 } = require('uuid');
+
+const MAX_URL_LENGTH = 2000;
+
+function EventSender(platform, environmentId, options) {
+  const imageUrlPath = '/a/' + environmentId + '.gif';
+  const baseHeaders = utils.extend({ 'Content-Type': 'application/json' }, utils.getLDHeaders(platform, options));
+  const httpFallbackPing = platform.httpFallbackPing; // this will be set for us if we're in the browser SDK
+  const sender = {};
+
+  function getResponseInfo(result) {
+    const ret = { status: result.status };
+    const dateStr = result.header('date');
+    if (dateStr) {
+      const time = Date.parse(dateStr);
+      if (time) {
+        ret.serverTime = time;
+      }
+    }
+    return ret;
+  }
+
+  sender.sendChunk = (events, url, isDiagnostic, usePost) => {
+    const jsonBody = JSON.stringify(events);
+    const payloadId = isDiagnostic ? null : uuidv1();
+
+    function doPostRequest(canRetry) {
+      const headers = isDiagnostic
+        ? baseHeaders
+        : utils.extend({}, baseHeaders, {
+            'X-LaunchDarkly-Event-Schema': '3',
+            'X-LaunchDarkly-Payload-ID': payloadId,
+          });
+      return platform
+        .httpRequest('POST', url, utils.transformHeaders(headers, options), jsonBody)
+        .promise.then(result => {
+          if (!result) {
+            // This was a response from a fire-and-forget request, so we won't have a status.
+            return;
+          }
+          if (result.status >= 400 && errors.isHttpErrorRecoverable(result.status) && canRetry) {
+            return doPostRequest(false);
+          } else {
+            return getResponseInfo(result);
+          }
+        })
+        .catch(() => {
+          if (canRetry) {
+            return doPostRequest(false);
+          }
+          return Promise.reject();
+        });
+    }
+
+    if (usePost) {
+      return doPostRequest(true).catch(() => {});
+    } else {
+      httpFallbackPing && httpFallbackPing(url + imageUrlPath + '?d=' + utils.base64URLEncode(jsonBody));
+      return Promise.resolve(); // we don't wait for this request to complete, it's just a one-way ping
+    }
+  };
+
+  sender.sendEvents = function(events, url, isDiagnostic) {
+    if (!platform.httpRequest) {
+      return Promise.resolve();
+    }
+    const canPost = platform.httpAllowsPost();
+    let chunks;
+    if (canPost) {
+      // no need to break up events into chunks if we can send a POST
+      chunks = [events];
+    } else {
+      chunks = utils.chunkUserEventsForUrl(MAX_URL_LENGTH - url.length, events);
+    }
+    const results = [];
+    for (let i = 0; i < chunks.length; i++) {
+      results.push(sender.sendChunk(chunks[i], url, isDiagnostic, canPost));
+    }
+    return Promise.all(results);
+  };
+
+  return sender;
+}
+
+module.exports = EventSender;

package/src/EventSummarizer.js

@@ -0,0 +1,84 @@
+function EventSummarizer() {
+  const es = {};
+
+  let startDate = 0,
+    endDate = 0,
+    counters = {};
+
+  es.summarizeEvent = function(event) {
+    if (event.kind === 'feature') {
+      const counterKey =
+        event.key +
+        ':' +
+        (event.variation !== null && event.variation !== undefined ? event.variation : '') +
+        ':' +
+        (event.version !== null && event.version !== undefined ? event.version : '');
+      const counterVal = counters[counterKey];
+      if (counterVal) {
+        counterVal.count = counterVal.count + 1;
+      } else {
+        counters[counterKey] = {
+          count: 1,
+          key: event.key,
+          variation: event.variation,
+          version: event.version,
+          value: event.value,
+          default: event.default,
+        };
+      }
+      if (startDate === 0 || event.creationDate < startDate) {
+        startDate = event.creationDate;
+      }
+      if (event.creationDate > endDate) {
+        endDate = event.creationDate;
+      }
+    }
+  };
+
+  es.getSummary = function() {
+    const flagsOut = {};
+    let empty = true;
+    for (const i in counters) {
+      const c = counters[i];
+      let flag = flagsOut[c.key];
+      if (!flag) {
+        flag = {
+          default: c.default,
+          counters: [],
+        };
+        flagsOut[c.key] = flag;
+      }
+      const counterOut = {
+        value: c.value,
+        count: c.count,
+      };
+      if (c.variation !== undefined && c.variation !== null) {
+        counterOut.variation = c.variation;
+      }
+      if (c.version) {
+        counterOut.version = c.version;
+      } else {
+        counterOut.unknown = true;
+      }
+      flag.counters.push(counterOut);
+      empty = false;
+    }
+    return empty
+      ? null
+      : {
+          startDate,
+          endDate,
+          features: flagsOut,
+        };
+  };
+
+  es.clearSummary = function() {
+    startDate = 0;
+    endDate = 0;
+    counters = {};
+  };
+
+  return es;
+}
+
+module.exports = EventSummarizer;

package/src/Identity.js

@@ -0,0 +1,26 @@
+const utils = require('./utils');
+
+function Identity(initialUser, onChange) {
+  const ident = {};
+  let user;
+
+  ident.setUser = function(u) {
+    const previousUser = user && utils.clone(user);
+    user = utils.sanitizeUser(u);
+    if (user && onChange) {
+      onChange(utils.clone(user), previousUser);
+    }
+  };
+
+  ident.getUser = function() {
+    return user ? utils.clone(user) : null;
+  };
+
+  if (initialUser) {
+    ident.setUser(initialUser);
+  }
+
+  return ident;
+}
+
+module.exports = Identity;

package/src/InitializationState.js

@@ -0,0 +1,83 @@
+// This file provides an abstraction of the client's startup state.
+//
+// Startup can either succeed or fail exactly once; calling signalSuccess() or signalFailure()
+// after that point has no effect.
+//
+// On success, we fire both an "initialized" event and a "ready" event. Both the waitForInitialization()
+// promise and the waitUntilReady() promise are resolved in this case.
+//
+// On failure, we fire both a "failed" event (with the error as a parameter) and a "ready" event.
+// The waitForInitialization() promise is rejected, but the waitUntilReady() promise is resolved.
+//
+// To complicate things, we must *not* create the waitForInitialization() promise unless it is
+// requested, because otherwise failures would cause an *unhandled* rejection which can be a
+// serious problem in some environments. So we use a somewhat roundabout system for tracking the
+// initialization state and lazily creating this promise.
+
+const readyEvent = 'ready',
+  successEvent = 'initialized',
+  failureEvent = 'failed';
+
+function InitializationStateTracker(eventEmitter) {
+  let succeeded = false,
+    failed = false,
+    failureValue = null,
+    initializationPromise = null;
+
+  const readyPromise = new Promise(resolve => {
+    const onReady = () => {
+      eventEmitter.off(readyEvent, onReady); // we can't use "once" because it's not available on some JS platforms
+      resolve();
+    };
+    eventEmitter.on(readyEvent, onReady);
+  }).catch(() => {}); // this Promise should never be rejected, but the catch handler is a safety measure
+
+  return {
+    getInitializationPromise: () => {
+      if (initializationPromise) {
+        return initializationPromise;
+      }
+      if (succeeded) {
+        return Promise.resolve();
+      }
+      if (failed) {
+        return Promise.reject(failureValue);
+      }
+      initializationPromise = new Promise((resolve, reject) => {
+        const onSuccess = () => {
+          eventEmitter.off(successEvent, onSuccess);
+          resolve();
+        };
+        const onFailure = err => {
+          eventEmitter.off(failureEvent, onFailure);
+          reject(err);
+        };
+        eventEmitter.on(successEvent, onSuccess);
+        eventEmitter.on(failureEvent, onFailure);
+      });
+      return initializationPromise;
+    },
+
+    getReadyPromise: () => readyPromise,
+
+    signalSuccess: () => {
+      if (!succeeded && !failed) {
+        succeeded = true;
+        eventEmitter.emit(successEvent);
+        eventEmitter.emit(readyEvent);
+      }
+    },
+
+    signalFailure: err => {
+      if (!succeeded && !failed) {
+        failed = true;
+        failureValue = err;
+        eventEmitter.emit(failureEvent, err);
+        eventEmitter.emit(readyEvent);
+      }
+      eventEmitter.maybeReportError(err); // the "error" event can be emitted more than once, unlike the others
+    },
+  };
+}
+
+module.exports = InitializationStateTracker;

package/src/PersistentFlagStore.js

@@ -0,0 +1,50 @@
+const utils = require('./utils');
+
+function PersistentFlagStore(storage, environment, hash, ident) {
+  const store = {};
+
+  function getFlagsKey() {
+    let key = '';
+    const user = ident.getUser();
+    if (user) {
+      key = hash || utils.btoa(JSON.stringify(user));
+    }
+    return 'ld:' + environment + ':' + key;
+  }
+
+  // Returns a Promise which will be resolved with a parsed JSON value if a stored value was available,
+  // or resolved with null if there was no value or if storage was not available.
+  store.loadFlags = () =>
+    storage.get(getFlagsKey()).then(dataStr => {
+      if (dataStr === null || dataStr === undefined) {
+        return null;
+      }
+      try {
+        let data = JSON.parse(dataStr);
+        if (data) {
+          const schema = data.$schema;
+          if (schema === undefined || schema < 1) {
+            data = utils.transformValuesToVersionedValues(data);
+          } else {
+            delete data['$schema'];
+          }
+        }
+        return data;
+      } catch (ex) {
+        return store.clearFlags().then(() => null);
+      }
+    });
+
+  // Resolves with true if successful, or false if storage is unavailable. Never rejects.
+  store.saveFlags = flags => {
+    const data = utils.extend({}, flags, { $schema: 1 });
+    return storage.set(getFlagsKey(), JSON.stringify(data));
+  };
+
+  // Resolves with true if successful, or false if storage is unavailable. Never rejects.
+  store.clearFlags = () => storage.clear(getFlagsKey());
+
+  return store;
+}
+
+module.exports = PersistentFlagStore;

package/src/PersistentStorage.js

@@ -0,0 +1,81 @@
+const messages = require('./messages');
+
+// The localStorageProvider is provided by the platform object. It should have the following
+// methods, each of which should return a Promise:
+// - get(key): Gets the string value, if any, for the given key
+// - set(key, value): Stores a string value for the given key
+// - remove(key): Removes the given key
+//
+// Storage is just a light wrapper of the localStorageProvider, adding error handling and
+// ensuring that we don't call it if it's unavailable. The get method will simply resolve
+// with an undefined value if there is an error or if there is no localStorageProvider.
+// None of the promises returned by Storage will ever be rejected.
+//
+// It is always possible that the underlying platform storage mechanism might fail or be
+// disabled. If so, it's likely that it will keep failing, so we will only log one warning
+// instead of repetitive warnings.
+function PersistentStorage(localStorageProvider, logger) {
+  const storage = {};
+  let loggedError = false;
+
+  const logError = err => {
+    if (!loggedError) {
+      loggedError = true;
+      logger.warn(messages.localStorageUnavailable(err));
+    }
+  };
+
+  storage.isEnabled = () => !!localStorageProvider;
+
+  // Resolves with a value, or undefined if storage is unavailable. Never rejects.
+  storage.get = key =>
+    new Promise(resolve => {
+      if (!localStorageProvider) {
+        resolve(undefined);
+        return;
+      }
+      localStorageProvider
+        .get(key)
+        .then(resolve)
+        .catch(err => {
+          logError(err);
+          resolve(undefined);
+        });
+    });
+
+  // Resolves with true if successful, or false if storage is unavailable. Never rejects.
+  storage.set = (key, value) =>
+    new Promise(resolve => {
+      if (!localStorageProvider) {
+        resolve(false);
+        return;
+      }
+      localStorageProvider
+        .set(key, value)
+        .then(() => resolve(true))
+        .catch(err => {
+          logError(err);
+          resolve(false);
+        });
+    });
+
+  // Resolves with true if successful, or false if storage is unavailable. Never rejects.
+  storage.clear = key =>
+    new Promise(resolve => {
+      if (!localStorageProvider) {
+        resolve(false);
+        return;
+      }
+      localStorageProvider
+        .clear(key)
+        .then(() => resolve(true))
+        .catch(err => {
+          logError(err);
+          resolve(false);
+        });
+    });
+
+  return storage;
+}
+
+module.exports = PersistentStorage;

package/src/Requestor.js

@@ -0,0 +1,111 @@
+const utils = require('./utils');
+const errors = require('./errors');
+const messages = require('./messages');
+const promiseCoalescer = require('./promiseCoalescer');
+
+const jsonContentType = 'application/json';
+
+function getResponseError(result) {
+  if (result.status === 404) {
+    return new errors.LDInvalidEnvironmentIdError(messages.environmentNotFound());
+  } else {
+    return new errors.LDFlagFetchError(messages.errorFetchingFlags(result.statusText || String(result.status)));
+  }
+}
+
+function Requestor(platform, options, environment) {
+  const baseUrl = options.baseUrl;
+  const useReport = options.useReport;
+  const withReasons = options.evaluationReasons;
+  const logger = options.logger;
+
+  const requestor = {};
+
+  const activeRequests = {}; // map of URLs to promiseCoalescers
+
+  function fetchJSON(endpoint, body) {
+    if (!platform.httpRequest) {
+      return new Promise((resolve, reject) => {
+        reject(new errors.LDFlagFetchError(messages.httpUnavailable()));
+      });
+    }
+
+    const method = body ? 'REPORT' : 'GET';
+    const headers = utils.getLDHeaders(platform, options);
+    if (body) {
+      headers['Content-Type'] = jsonContentType;
+    }
+
+    let coalescer = activeRequests[endpoint];
+    if (!coalescer) {
+      coalescer = promiseCoalescer(() => {
+        // this will be called once there are no more active requests for the same endpoint
+        delete activeRequests[endpoint];
+      });
+      activeRequests[endpoint] = coalescer;
+    }
+
+    const req = platform.httpRequest(method, endpoint, utils.transformHeaders(headers, options), body);
+    const p = req.promise.then(
+      result => {
+        if (result.status === 200) {
+          // We're using substring here because using startsWith would require a polyfill in IE.
+          if (
+            result.header('content-type') &&
+            result.header('content-type').substring(0, jsonContentType.length) === jsonContentType
+          ) {
+            return JSON.parse(result.body);
+          } else {
+            const message = messages.invalidContentType(result.header('content-type') || '');
+            return Promise.reject(new errors.LDFlagFetchError(message));
+          }
+        } else {
+          return Promise.reject(getResponseError(result));
+        }
+      },
+      e => Promise.reject(new errors.LDFlagFetchError(messages.networkError(e)))
+    );
+    coalescer.addPromise(p, () => {
+      // this will be called if another request for the same endpoint supersedes this one
+      req.cancel && req.cancel();
+    });
+    return coalescer.resultPromise;
+  }
+
+  // Performs a GET request to an arbitrary path under baseUrl. Returns a Promise which will resolve
+  // with the parsed JSON response, or will be rejected if the request failed.
+  requestor.fetchJSON = function(path) {
+    return fetchJSON(baseUrl + path, null);
+  };
+
+  // Requests the current state of all flags for the given user from LaunchDarkly. Returns a Promise
+  // which will resolve with the parsed JSON response, or will be rejected if the request failed.
+  requestor.fetchFlagSettings = function(user, hash) {
+    let data;
+    let endpoint;
+    let query = '';
+    let body;
+
+    if (useReport) {
+      endpoint = [baseUrl, '/sdk/evalx/', environment, '/user'].join('');
+      body = JSON.stringify(user);
+    } else {
+      data = utils.base64URLEncode(JSON.stringify(user));
+      endpoint = [baseUrl, '/sdk/evalx/', environment, '/users/', data].join('');
+    }
+    if (hash) {
+      query = 'h=' + hash;
+    }
+    if (withReasons) {
+      query = query + (query ? '&' : '') + 'withReasons=true';
+    }
+    endpoint = endpoint + (query ? '?' : '') + query;
+    logger.debug(messages.debugPolling(endpoint));
+
+    return fetchJSON(endpoint, body);
+  };
+
+  return requestor;
+}
+
+module.exports = Requestor;