2.0.0 (#89)

Author: eli-darkly

CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to the LaunchDarkly client-side JavaScript SDK will be documented in this file. 
 This project adheres to [Semantic Versioning](http://semver.org).
 
+## [2.0.0] - 2018-05-25
+### Changed
+- To reduce the network bandwidth used for analytics events, feature request events are now sent as counters rather than individual events, and user details are now sent only at intervals rather than in each event. These behaviors can be modified through the LaunchDarkly UI and with the new configuration option `inlineUsersInEvents`. For more details, see [Analytics Data Stream Reference](https://docs.launchdarkly.com/v2.0/docs/analytics-data-stream-reference).
+- In every function that takes an optional callback parameter, if you provide a callback, the function will not return a promise; a promise will be returned only if you omit the callback. Previously, it would always return a promise which would be resolved/rejected at the same time that the callback (if any) was called; this caused problems if you had not registered an error handler for the promise.
+- When sending analytics events, if there is a connection error or an HTTP 5xx response, the client will try to send the events again one more time after a one-second delay.
+- Analytics are now sent with an HTTP `POST` request if the browser supports CORS, or via image loading if it does not. Previously, they were always sent via image loading.
+
+### Added
+- The new configuration option `sendEventsOnlyForVariation`, if set to `true`, causes analytics events for feature flags to be sent only when you call `variation`. Otherwise, the default behavior is to also send events when you call `allFlags`, and whenever a changed flag value is detected in streaming mode.
+- The new configuration option `allowFrequentDuplicateEvents`, if set to `true`, turns off throttling for feature flag events. Otherwise, the default behavior is to block the sending of an analytics event if another event with the same flag key, flag value, and user key was generated within the last five minutes.
+
+### Fixed
+- If `identify` is called with a null user, or a user with no key, the function no longer tries to do an HTTP request to the server (which would always fail); instead, it just returns an error.
+
+### Deprecated
+- The configuration options `all_attributes_private` and `private_attribute_names` are deprecated. Use `allAttributesPrivate` and `privateAttributeNames` instead.
+
 ## [1.7.4] - 2018-05-23
 ### Fixed
 - Fixed a bug that caused events _not_ to be sent if `options.sendEvents` was explicitly set to `true`.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldclient-js",
-  "version": "1.7.4",
+  "version": "2.0.0",
   "description": "LaunchDarkly SDK for JavaScript",
   "author": "LaunchDarkly <[email protected]>",
   "license": "Apache-2.0",

src/EventProcessor.js

@@ -1,84 +1,149 @@
+import EventSender from './EventSender';
+import EventSummarizer from './EventSummarizer';
+import UserFilter from './UserFilter';
+import * as errors from './errors';
 import * as utils from './utils';
 
-const MAX_URL_LENGTH = 2000;
+export default function EventProcessor(eventsUrl, environmentId, options = {}, emitter = null, sender = null) {
+  const processor = {};
+  const eventSender = sender || EventSender(eventsUrl, environmentId);
+  const summarizer = EventSummarizer();
+  const userFilter = UserFilter(options);
+  const inlineUsers = !!options.inlineUsersInEvents;
+  let queue = [];
+  let flushInterval;
+  let samplingInterval;
+  let lastKnownPastTime = 0;
+  let disabled = false;
+  let flushTimer;
+
+  function reportArgumentError(message) {
+    utils.onNextTick(() => {
+      emitter && emitter.maybeReportError(new errors.LDInvalidArgumentError(message));
+    });
+  }
 
-function sendEvents(eventsUrl, events, sync) {
-  const src = eventsUrl + '?d=' + utils.base64URLEncode(JSON.stringify(events));
+  if (options.samplingInterval !== undefined && (isNaN(options.samplingInterval) || options.samplingInterval < 0)) {
+    samplingInterval = 0;
+    reportArgumentError('Invalid sampling interval configured. Sampling interval must be an integer >= 0.');
+  } else {
+    samplingInterval = options.samplingInterval || 0;
+  }
 
-  const send = onDone => {
-    const xhr = new XMLHttpRequest();
-    const hasCors = 'withCredentials' in xhr;
+  if (options.flushInterval !== undefined && (isNan(options.flushInterval) || options.flushInterval < 2000)) {
+    flushInterval = 2000;
+    reportArgumentError('Invalid flush interval configured. Must be an integer >= 2000 (milliseconds).');
+  } else {
+    flushInterval = options.flushInterval || 2000;
+  }
 
-    // Detect browser support for CORS
-    if (hasCors) {
-      /* supports cross-domain requests */
-      xhr.open('GET', src, !sync);
+  function shouldSampleEvent() {
+    return samplingInterval === 0 || Math.floor(Math.random() * samplingInterval) === 0;
+  }
 
-      if (!sync) {
-        xhr.addEventListener('load', onDone);
-      }
+  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;
+  }
 
-      xhr.send();
+  // Transform an event from its internal format to the format we use when sending a payload.
+  function makeOutputEvent(e) {
+    const ret = Object.assign({}, e);
+    if (inlineUsers || e.kind === 'identify') {
+      // identify events always have an inline user
+      ret.user = userFilter.filterUser(e.user);
     } else {
-      const img = new Image();
-
-      if (!sync) {
-        img.addEventListener('load', onDone);
-      }
-
-      img.src = src;
+      ret.userKey = e.user.key;
+      delete ret['user'];
     }
-  };
-
-  if (sync) {
-    send();
-  } else {
-    return new Promise(resolve => {
-      send(resolve);
-    });
+    if (e.kind === 'feature') {
+      delete ret['trackEvents'];
+      delete ret['debugEventsUntilDate'];
+    }
+    return ret;
   }
-}
-
-export default function EventProcessor(eventsUrl, eventSerializer) {
-  const processor = {};
-  let queue = [];
-  let initialFlush = true;
 
   processor.enqueue = function(event) {
-    queue.push(event);
-  };
-
-  processor.flush = function(user, sync) {
-    const finalSync = sync === undefined ? false : sync;
-    const serializedQueue = eventSerializer.serializeEvents(queue);
-
-    if (!user) {
-      if (initialFlush) {
-        if (console && console.warn) {
-          console.warn(
-            'Be sure to call `identify` in the LaunchDarkly client: http://docs.launchdarkly.com/docs/running-an-ab-test#include-the-client-side-snippet'
-          );
-        }
+    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);
       }
-      return Promise.resolve();
+    } else {
+      addFullEvent = shouldSampleEvent();
     }
 
-    initialFlush = false;
+    if (addFullEvent) {
+      queue.push(makeOutputEvent(event));
+    }
+    if (addDebugEvent) {
+      const debugEvent = Object.assign({}, event, { kind: 'debug' });
+      delete debugEvent['trackEvents'];
+      delete debugEvent['debugEventsUntilDate'];
+      delete debugEvent['variation'];
+      queue.push(debugEvent);
+    }
+  };
 
-    if (serializedQueue.length === 0) {
+  processor.flush = function(sync) {
+    if (disabled) {
       return Promise.resolve();
     }
-
-    const chunks = utils.chunkUserEventsForUrl(MAX_URL_LENGTH - eventsUrl.length, serializedQueue);
-
-    const results = [];
-    for (let i = 0; i < chunks.length; i++) {
-      results.push(sendEvents(eventsUrl, chunks[i], finalSync));
+    const eventsToSend = queue;
+    const summary = summarizer.getSummary();
+    summarizer.clearSummary();
+    if (summary) {
+      summary.kind = 'summary';
+      eventsToSend.push(summary);
+    }
+    if (eventsToSend.length === 0) {
+      return Promise.resolve();
     }
-
     queue = [];
+    return eventSender.sendEvents(eventsToSend, sync).then(responseInfo => {
+      if (responseInfo) {
+        if (responseInfo.serverTime) {
+          lastKnownPastTime = responseInfo.serverTime;
+        }
+        if (responseInfo.status === 401) {
+          disabled = true;
+          utils.onNextTick(() => {
+            emitter.maybeReportError(
+              new errors.LDUnexpectedResponseError('Received 401 error, no further events will be posted')
+            );
+          });
+        }
+      }
+    });
+  };
+
+  processor.start = function() {
+    const flushTick = () => {
+      processor.flush();
+      flushTimer = setTimeout(flushTick, flushInterval);
+    };
+    flushTimer = setTimeout(flushTick, flushInterval);
+  };
 
-    return sync ? Promise.resolve() : Promise.all(results);
+  processor.stop = function() {
+    clearTimeout(flushTimer);
   };
 
   return processor;

src/EventSender.js

@@ -0,0 +1,87 @@
+import * as utils from './utils';
+
+const MAX_URL_LENGTH = 2000;
+
+export default function EventSender(eventsUrl, environmentId, forceHasCors, imageCreator) {
+  let hasCors;
+  const postUrl = eventsUrl + '/events/bulk/' + environmentId;
+  const imageUrl = eventsUrl + '/a/' + environmentId + '.gif';
+  const sender = {};
+
+  function loadUrlUsingImage(src, onDone) {
+    const img = new Image();
+    if (onDone) {
+      img.addEventListener('load', onDone);
+    }
+    img.src = src;
+  }
+
+  function getResponseInfo(xhr) {
+    const ret = { status: xhr.status };
+    const dateStr = xhr.getResponseHeader('Date');
+    if (dateStr) {
+      const time = Date.parse(dateStr);
+      if (time) {
+        ret.serverTime = time;
+      }
+    }
+    return ret;
+  }
+
+  function sendChunk(events, usePost, sync) {
+    const createImage = imageCreator || loadUrlUsingImage;
+    const send = onDone => {
+      if (usePost) {
+        const xhr = new XMLHttpRequest();
+        xhr.open('POST', postUrl, !sync);
+        xhr.setRequestHeader('Content-Type', 'application/json');
+
+        if (!sync) {
+          xhr.addEventListener('load', () => {
+            onDone(getResponseInfo(xhr));
+          });
+        }
+
+        xhr.send(JSON.stringify(events));
+      } else {
+        const src = imageUrl + '?d=' + utils.base64URLEncode(JSON.stringify(events));
+        createImage(src, sync ? null : onDone);
+      }
+    };
+
+    if (sync) {
+      send();
+    } else {
+      return new Promise(resolve => {
+        send(resolve);
+      });
+    }
+  }
+
+  sender.sendEvents = function(events, sync) {
+    // Detect browser support for CORS (can be overridden by tests)
+    if (hasCors === undefined) {
+      if (forceHasCors === undefined) {
+        hasCors = 'withCredentials' in new XMLHttpRequest();
+      } else {
+        hasCors = forceHasCors;
+      }
+    }
+
+    const finalSync = sync === undefined ? false : sync;
+    let chunks;
+    if (hasCors) {
+      // no need to break up events into chunks if we can send a POST
+      chunks = [events];
+    } else {
+      chunks = utils.chunkUserEventsForUrl(MAX_URL_LENGTH - eventsUrl.length, events);
+    }
+    const results = [];
+    for (let i = 0; i < chunks.length; i++) {
+      results.push(sendChunk(chunks[i], hasCors, finalSync));
+    }
+    return sync ? Promise.resolve() : Promise.all(results);
+  };
+
+  return sender;
+}