launchdarkly-js-sdk-common 4.0.0 → 4.0.1

package/src/configuration.js

@@ -0,0 +1,151 @@
+const errors = require('./errors');
+const { validateLogger } = require('./loggers');
+const messages = require('./messages');
+const utils = require('./utils');
+
+// baseOptionDefs should contain an entry for each supported configuration option in the common package.
+// Each entry can have three properties:
+// - "default": the default value if any
+// - "type": a type constraint used if the type can't be inferred from the default value). The allowable
+//   values are "boolean", "string", "number", "array", "object", "function", or several of these OR'd
+//   together with "|" ("function|object").
+// - "minimum": minimum value if any for numeric properties
+//
+// The extraOptionDefs parameter to validate() uses the same format.
+const baseOptionDefs = {
+  baseUrl: { default: 'https://app.launchdarkly.com' },
+  streamUrl: { default: 'https://clientstream.launchdarkly.com' },
+  eventsUrl: { default: 'https://events.launchdarkly.com' },
+  sendEvents: { default: true },
+  streaming: { type: 'boolean' }, // default for this is undefined, which is different from false
+  sendLDHeaders: { default: true },
+  requestHeaderTransform: { type: 'function' },
+  inlineUsersInEvents: { default: false },
+  allowFrequentDuplicateEvents: { default: false },
+  sendEventsOnlyForVariation: { default: false },
+  useReport: { default: false },
+  evaluationReasons: { default: false },
+  eventCapacity: { default: 100, minimum: 1 },
+  flushInterval: { default: 2000, minimum: 2000 },
+  samplingInterval: { default: 0, minimum: 0 },
+  streamReconnectDelay: { default: 1000, minimum: 0 },
+  allAttributesPrivate: { default: false },
+  privateAttributeNames: { default: [] },
+  bootstrap: { type: 'string|object' },
+  diagnosticRecordingInterval: { default: 900000, minimum: 2000 },
+  diagnosticOptOut: { default: false },
+  wrapperName: { type: 'string' },
+  wrapperVersion: { type: 'string' },
+  stateProvider: { type: 'object' }, // not a public option, used internally
+  autoAliasingOptOut: { default: false },
+};
+
+function validate(options, emitter, extraOptionDefs, logger) {
+  const optionDefs = utils.extend({ logger: { default: logger } }, baseOptionDefs, extraOptionDefs);
+
+  const deprecatedOptions = {
+    // As of the latest major version, there are no deprecated options. Next time we deprecate
+    // something, add an item here where the property name is the deprecated name, and the
+    // property value is the preferred name if any, or null/undefined if there is no replacement.
+  };
+
+  function checkDeprecatedOptions(config) {
+    const opts = config;
+    Object.keys(deprecatedOptions).forEach(oldName => {
+      if (opts[oldName] !== undefined) {
+        const newName = deprecatedOptions[oldName];
+        logger && logger.warn(messages.deprecated(oldName, newName));
+        if (newName) {
+          if (opts[newName] === undefined) {
+            opts[newName] = opts[oldName];
+          }
+          delete opts[oldName];
+        }
+      }
+    });
+  }
+
+  function applyDefaults(config) {
+    // This works differently from utils.extend() in that it *will not* override a default value
+    // if the provided value is explicitly set to null. This provides backward compatibility
+    // since in the past we only used the provided values if they were truthy.
+    const ret = utils.extend({}, config);
+    Object.keys(optionDefs).forEach(name => {
+      if (ret[name] === undefined || ret[name] === null) {
+        ret[name] = optionDefs[name] && optionDefs[name].default;
+      }
+    });
+    return ret;
+  }
+
+  function validateTypesAndNames(config) {
+    const ret = utils.extend({}, config);
+    const typeDescForValue = value => {
+      if (value === null) {
+        return 'any';
+      }
+      if (value === undefined) {
+        return undefined;
+      }
+      if (Array.isArray(value)) {
+        return 'array';
+      }
+      const t = typeof value;
+      if (t === 'boolean' || t === 'string' || t === 'number' || t === 'function') {
+        return t;
+      }
+      return 'object';
+    };
+    Object.keys(config).forEach(name => {
+      const value = config[name];
+      if (value !== null && value !== undefined) {
+        const optionDef = optionDefs[name];
+        if (optionDef === undefined) {
+          reportArgumentError(messages.unknownOption(name));
+        } else {
+          const expectedType = optionDef.type || typeDescForValue(optionDef.default);
+          if (expectedType !== 'any') {
+            const allowedTypes = expectedType.split('|');
+            const actualType = typeDescForValue(value);
+            if (allowedTypes.indexOf(actualType) < 0) {
+              if (expectedType === 'boolean') {
+                ret[name] = !!value;
+                reportArgumentError(messages.wrongOptionTypeBoolean(name, actualType));
+              } else {
+                reportArgumentError(messages.wrongOptionType(name, expectedType, actualType));
+                ret[name] = optionDef.default;
+              }
+            } else {
+              if (actualType === 'number' && optionDef.minimum !== undefined && value < optionDef.minimum) {
+                reportArgumentError(messages.optionBelowMinimum(name, value, optionDef.minimum));
+                ret[name] = optionDef.minimum;
+              }
+            }
+          }
+        }
+      }
+    });
+    return ret;
+  }
+
+  function reportArgumentError(message) {
+    utils.onNextTick(() => {
+      emitter && emitter.maybeReportError(new errors.LDInvalidArgumentError(message));
+    });
+  }
+
+  let config = utils.extend({}, options || {});
+
+  checkDeprecatedOptions(config);
+
+  config = applyDefaults(config);
+  config = validateTypesAndNames(config);
+  validateLogger(config.logger);
+
+  return config;
+}
+
+module.exports = {
+  baseOptionDefs,
+  validate,
+};

package/src/diagnosticEvents.js

@@ -0,0 +1,269 @@
+const { v1: uuidv1 } = require('uuid');
+// Note that in the diagnostic events spec, these IDs are to be generated with UUID v4. However,
+// in JS we were already using v1 for unique user keys, so to avoid bringing in two packages we
+// will use v1 here as well.
+
+const { baseOptionDefs } = require('./configuration');
+const messages = require('./messages');
+
+function DiagnosticId(sdkKey) {
+  const ret = {
+    diagnosticId: uuidv1(),
+  };
+  if (sdkKey) {
+    ret.sdkKeySuffix = sdkKey.length > 6 ? sdkKey.substring(sdkKey.length - 6) : sdkKey;
+  }
+  return ret;
+}
+
+// A stateful object holding statistics that will go into diagnostic events.
+
+function DiagnosticsAccumulator(startTime) {
+  let dataSinceDate, droppedEvents, eventsInLastBatch, streamInits;
+
+  function reset(time) {
+    dataSinceDate = time;
+    droppedEvents = 0;
+    eventsInLastBatch = 0;
+    streamInits = [];
+  }
+
+  reset(startTime);
+
+  return {
+    getProps: () => ({
+      dataSinceDate,
+      droppedEvents,
+      eventsInLastBatch,
+      streamInits,
+      // omit deduplicatedUsers for the JS SDKs because they don't deduplicate users
+    }),
+    setProps: props => {
+      dataSinceDate = props.dataSinceDate;
+      droppedEvents = props.droppedEvents || 0;
+      eventsInLastBatch = props.eventsInLastBatch || 0;
+      streamInits = props.streamInits || [];
+    },
+    incrementDroppedEvents: () => {
+      droppedEvents++;
+    },
+    setEventsInLastBatch: n => {
+      eventsInLastBatch = n;
+    },
+    recordStreamInit: (timestamp, failed, durationMillis) => {
+      const info = { timestamp, failed, durationMillis };
+      streamInits.push(info);
+    },
+    reset,
+  };
+}
+
+// An object that maintains information that will go into diagnostic events, and knows how to format
+// those events. It is instantiated by the SDK client, and shared with the event processor.
+//
+// The JS-based SDKs have two modes for diagnostic events. By default, the behavior is basically the
+// same as the server-side SDKs: a "diagnostic-init" event is sent on startup, and then "diagnostic"
+// events with operating statistics are sent periodically. However, in a browser environment this is
+// undesirable because the page may be reloaded frequently. In that case, setting the property
+// "platform.diagnosticUseCombinedEvent" to true enables an alternate mode in which a combination of
+// both kinds of event is sent at intervals, relative to the last time this was done (if any) which
+// is cached in local storage.
+
+function DiagnosticsManager(
+  platform,
+  persistentStorage,
+  accumulator,
+  eventSender,
+  environmentId,
+  config,
+  diagnosticId
+) {
+  const combinedMode = !!platform.diagnosticUseCombinedEvent;
+  const localStorageKey = 'ld:' + environmentId + ':$diagnostics';
+  const diagnosticEventsUrl = config.eventsUrl + '/events/diagnostic/' + environmentId;
+  const periodicInterval = config.diagnosticRecordingInterval;
+  const acc = accumulator;
+  const initialEventSamplingInterval = 4; // used only in combined mode - see start()
+  let streamingEnabled = !!config.streaming;
+  let eventSentTime;
+  let periodicTimer;
+  const manager = {};
+
+  function makeInitProperties() {
+    return {
+      sdk: makeSdkData(),
+      configuration: makeConfigData(),
+      platform: platform.diagnosticPlatformData,
+    };
+  }
+
+  // Send a diagnostic event and do not wait for completion.
+  function sendDiagnosticEvent(event) {
+    config.logger && config.logger.debug(messages.debugPostingDiagnosticEvent(event));
+    eventSender
+      .sendEvents(event, diagnosticEventsUrl, true)
+      .then(() => undefined)
+      .catch(() => undefined);
+  }
+
+  function loadProperties(callback) {
+    if (!persistentStorage.isEnabled()) {
+      return callback(false); // false indicates that local storage is not available
+    }
+    persistentStorage
+      .get(localStorageKey)
+      .then(data => {
+        if (data) {
+          try {
+            const props = JSON.parse(data);
+            acc.setProps(props);
+            eventSentTime = props.dataSinceDate;
+          } catch (e) {
+            // disregard malformed cached data
+          }
+        }
+        callback(true);
+      })
+      .catch(() => {
+        callback(false);
+      });
+  }
+
+  function saveProperties() {
+    if (persistentStorage.isEnabled()) {
+      const props = { ...acc.getProps() };
+      persistentStorage.set(localStorageKey, JSON.stringify(props));
+    }
+  }
+
+  // Creates the initial event that is sent by the event processor when the SDK starts up. This will not
+  // be repeated during the lifetime of the SDK client. In combined mode, we don't send this.
+  function createInitEvent() {
+    return {
+      kind: 'diagnostic-init',
+      id: diagnosticId,
+      creationDate: acc.getProps().dataSinceDate,
+      ...makeInitProperties(),
+    };
+  }
+
+  // Creates a periodic event containing time-dependent stats, and resets the state of the manager with
+  // regard to those stats. In combined mode (browser SDK) this also contains the configuration data.
+  function createPeriodicEventAndReset() {
+    const currentTime = new Date().getTime();
+    let ret = {
+      kind: combinedMode ? 'diagnostic-combined' : 'diagnostic',
+      id: diagnosticId,
+      creationDate: currentTime,
+      ...acc.getProps(),
+    };
+    if (combinedMode) {
+      ret = { ...ret, ...makeInitProperties() };
+    }
+    acc.reset(currentTime);
+    return ret;
+  }
+
+  function sendPeriodicEvent() {
+    sendDiagnosticEvent(createPeriodicEventAndReset());
+    periodicTimer = setTimeout(sendPeriodicEvent, periodicInterval);
+    eventSentTime = new Date().getTime();
+    if (combinedMode) {
+      saveProperties();
+    }
+  }
+
+  function makeSdkData() {
+    const sdkData = { ...platform.diagnosticSdkData };
+    if (config.wrapperName) {
+      sdkData.wrapperName = config.wrapperName;
+    }
+    if (config.wrapperVersion) {
+      sdkData.wrapperVersion = config.wrapperVersion;
+    }
+    return sdkData;
+  }
+
+  function makeConfigData() {
+    const configData = {
+      customBaseURI: config.baseUrl !== baseOptionDefs.baseUrl.default,
+      customStreamURI: config.streamUrl !== baseOptionDefs.streamUrl.default,
+      customEventsURI: config.eventsUrl !== baseOptionDefs.eventsUrl.default,
+      eventsCapacity: config.eventCapacity,
+      eventsFlushIntervalMillis: config.flushInterval,
+      reconnectTimeMillis: config.streamReconnectDelay,
+      streamingDisabled: !streamingEnabled,
+      allAttributesPrivate: !!config.allAttributesPrivate,
+      inlineUsersInEvents: !!config.inlineUsersInEvents,
+      diagnosticRecordingIntervalMillis: config.diagnosticRecordingInterval,
+      // The following extra properties are only provided by client-side JS SDKs:
+      usingSecureMode: !!config.hash,
+      bootstrapMode: !!config.bootstrap,
+      fetchGoalsDisabled: !config.fetchGoals,
+      allowFrequentDuplicateEvents: !!config.allowFrequentDuplicateEvents,
+      sendEventsOnlyForVariation: !!config.sendEventsOnlyForVariation,
+      autoAliasingOptOut: !!config.autoAliasingOptOut,
+    };
+    // Client-side JS SDKs do not have the following properties which other SDKs have:
+    // connectTimeoutMillis
+    // pollingIntervalMillis
+    // samplingInterval
+    // socketTimeoutMillis
+    // startWaitMillis
+    // userKeysCapacity
+    // userKeysFlushIntervalMillis
+    // usingProxy
+    // usingProxyAuthenticator
+    // usingRelayDaemon
+
+    return configData;
+  }
+
+  // Called when the SDK is starting up. Either send an init event immediately, or, in the alternate
+  // mode, check for cached local storage properties and send an event only if we haven't done so
+  // recently.
+  manager.start = () => {
+    if (combinedMode) {
+      loadProperties(localStorageAvailable => {
+        if (localStorageAvailable) {
+          const nextEventTime = (eventSentTime || 0) + periodicInterval;
+          const timeNow = new Date().getTime();
+          if (timeNow >= nextEventTime) {
+            sendPeriodicEvent();
+          } else {
+            periodicTimer = setTimeout(sendPeriodicEvent, nextEventTime - timeNow);
+          }
+        } else {
+          // We don't have the ability to cache anything in local storage, so we don't know if we
+          // recently sent an event before this page load, but we would still prefer not to send one
+          // on *every* page load. So, as a rough heuristic, we'll decide semi-randomly.
+          if (Math.floor(Math.random() * initialEventSamplingInterval) === 0) {
+            sendPeriodicEvent();
+          } else {
+            periodicTimer = setTimeout(sendPeriodicEvent, periodicInterval);
+          }
+        }
+      });
+    } else {
+      sendDiagnosticEvent(createInitEvent());
+      periodicTimer = setTimeout(sendPeriodicEvent, periodicInterval);
+    }
+  };
+
+  manager.stop = () => {
+    periodicTimer && clearTimeout(periodicTimer);
+  };
+
+  // Called when streaming mode is turned on or off dynamically.
+  manager.setStreaming = enabled => {
+    streamingEnabled = enabled;
+  };
+
+  return manager;
+}
+
+module.exports = {
+  DiagnosticId,
+  DiagnosticsAccumulator,
+  DiagnosticsManager,
+};

package/src/errors.js

@@ -0,0 +1,37 @@
+function createCustomError(name) {
+  function CustomError(message, code) {
+    Error.captureStackTrace && Error.captureStackTrace(this, this.constructor);
+    this.message = message;
+    this.code = code;
+  }
+
+  CustomError.prototype = new Error();
+  CustomError.prototype.name = name;
+  CustomError.prototype.constructor = CustomError;
+
+  return CustomError;
+}
+
+const LDUnexpectedResponseError = createCustomError('LaunchDarklyUnexpectedResponseError');
+const LDInvalidEnvironmentIdError = createCustomError('LaunchDarklyInvalidEnvironmentIdError');
+const LDInvalidUserError = createCustomError('LaunchDarklyInvalidUserError');
+const LDInvalidEventKeyError = createCustomError('LaunchDarklyInvalidEventKeyError');
+const LDInvalidArgumentError = createCustomError('LaunchDarklyInvalidArgumentError');
+const LDFlagFetchError = createCustomError('LaunchDarklyFlagFetchError');
+
+function isHttpErrorRecoverable(status) {
+  if (status >= 400 && status < 500) {
+    return status === 400 || status === 408 || status === 429;
+  }
+  return true;
+}
+
+module.exports = {
+  LDUnexpectedResponseError,
+  LDInvalidEnvironmentIdError,
+  LDInvalidUserError,
+  LDInvalidEventKeyError,
+  LDInvalidArgumentError,
+  LDFlagFetchError,
+  isHttpErrorRecoverable,
+};