@launchdarkly/js-sdk-common 2.17.0 → 2.19.0

package/dist/cjs/index.cjs

@@ -117,6 +117,9 @@ class AttributeReference {
         return (this.depth === other.depth &&
             this._components.every((value, index) => value === other.getComponent(index)));
     }
+    get components() {
+        return [...this._components];
+    }
 }
 /**
  * For use as invalid references when deserializing Flag/Segment data.
@@ -316,6 +319,41 @@ function isLegacyUser(context) {
     return !('kind' in context) || context.kind === null || context.kind === undefined;
 }
 
+/**
+ * Given some object to serialize product a canonicalized JSON string.
+ * https://www.rfc-editor.org/rfc/rfc8785.html
+ *
+ * We do not support custom toJSON methods on objects. Objects should be limited to basic types.
+ *
+ * @param object The object to serialize.
+ */
+function canonicalize(object, visited = []) {
+    // For JavaScript the default JSON serialization will produce canonicalized output for basic types.
+    if (object === null || typeof object !== 'object') {
+        return JSON.stringify(object);
+    }
+    if (visited.includes(object)) {
+        throw new Error('Cycle detected');
+    }
+    if (Array.isArray(object)) {
+        const values = object
+            .map((item) => canonicalize(item, [...visited, object]))
+            .map((item) => (item === undefined ? 'null' : item));
+        return `[${values.join(',')}]`;
+    }
+    const values = Object.keys(object)
+        .sort()
+        .map((key) => {
+        const value = canonicalize(object[key], [...visited, object]);
+        if (value !== undefined) {
+            return `${JSON.stringify(key)}:${value}`;
+        }
+        return undefined;
+    })
+        .filter((item) => item !== undefined);
+    return `{${values.join(',')}}`;
+}
+
 // The general strategy for the context is to transform the passed in context
 // as little as possible. We do convert the legacy users to a single kind
 // context, but we do not translate all passed contexts into a rigid structure.
@@ -690,6 +728,28 @@ class Context {
     get legacy() {
         return this._wasLegacy;
     }
+    /**
+     * Get the serialized canonical JSON for this context. This is not filtered for use in events.
+     *
+     * This method will cache the result.
+     *
+     * @returns The serialized canonical JSON or undefined if it cannot be serialized.
+     */
+    canonicalUnfilteredJson() {
+        if (!this.valid) {
+            return undefined;
+        }
+        if (this._cachedCanonicalJson) {
+            return this._cachedCanonicalJson;
+        }
+        try {
+            this._cachedCanonicalJson = canonicalize(Context.toLDContext(this));
+        }
+        catch {
+            // Indicated by undefined being returned.
+        }
+        return this._cachedCanonicalJson;
+    }
 }
 Context.UserKind = DEFAULT_KIND;
 
@@ -891,8 +951,6 @@ class CallbackHandler {
         if (this._disabled) {
             return;
         }
-        // TODO: SDK-1044 track selector for future synchronizer to use
-        // report data up
         this._dataCallback(basis, data);
     }
     async statusHandler(status, err) {
@@ -904,6 +962,11 @@ class CallbackHandler {
 }
 
 // TODO: refactor client-sdk to use this enum
+/**
+ * @experimental
+ * This feature is not stable and not subject to any backwards compatibility guarantees or semantic
+ * versioning.  It is not suitable for production usage.
+ */
 var DataSourceState;
 (function (DataSourceState) {
     // Positive confirmation of connection/data receipt
@@ -1004,6 +1067,43 @@ class DataSourceList {
     }
 }
 
+class LDFileDataSourceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LaunchDarklyFileDataSourceError';
+    }
+}
+class LDPollingError extends Error {
+    constructor(kind, message, status, recoverable = true) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+        this.name = 'LaunchDarklyPollingError';
+        this.recoverable = recoverable;
+    }
+}
+class LDStreamingError extends Error {
+    constructor(kind, message, code, recoverable = true) {
+        super(message);
+        this.kind = kind;
+        this.code = code;
+        this.name = 'LaunchDarklyStreamingError';
+        this.recoverable = recoverable;
+    }
+}
+/**
+ * This is a short term error and will be removed once FDv2 adoption is sufficient.
+ */
+class LDFlagDeliveryFallbackError extends Error {
+    constructor(kind, message, code) {
+        super(message);
+        this.kind = kind;
+        this.code = code;
+        this.name = 'LDFlagDeliveryFallbackError';
+        this.recoverable = false;
+    }
+}
+
 const DEFAULT_FALLBACK_TIME_MS = 2 * 60 * 1000;
 const DEFAULT_RECOVERY_TIME_MS = 5 * 60 * 1000;
 /**
@@ -1014,8 +1114,12 @@ class CompositeDataSource {
     /**
      * @param initializers factories to create {@link DataSystemInitializer}s, in priority order.
      * @param synchronizers factories to create  {@link DataSystemSynchronizer}s, in priority order.
+     * @param fdv1Synchronizers factories to fallback to if we need to fallback to FDv1.
+     * @param _logger for logging
+     * @param _transitionConditions to control automated transition between datasources. Typically only used for testing.
+     * @param _backoff to control delay between transitions. Typically only used for testing.
      */
-    constructor(initializers, synchronizers, _logger, _transitionConditions = {
+    constructor(initializers, synchronizers, fdv1Synchronizers, _logger, _transitionConditions = {
         [DataSourceState.Valid]: {
             durationMS: DEFAULT_RECOVERY_TIME_MS,
             transition: 'recover',
@@ -1051,8 +1155,9 @@ class CompositeDataSource {
         this._initPhaseActive = initializers.length > 0; // init phase if we have initializers
         this._initFactories = new DataSourceList(false, initializers);
         this._syncFactories = new DataSourceList(true, synchronizers);
+        this._fdv1Synchronizers = new DataSourceList(true, fdv1Synchronizers);
     }
-    async start(dataCallback, statusCallback) {
+    async start(dataCallback, statusCallback, selectorGetter) {
         if (!this._stopped) {
             // don't allow multiple simultaneous runs
             this._logger?.info('CompositeDataSource already running. Ignoring call to start.');
@@ -1089,12 +1194,18 @@ class CompositeDataSource {
                         // When we get a status update, we want to fallback if it is an error.  We also want to schedule a transition for some
                         // time in the future if this status remains for some duration (ex: Recover to primary synchronizer after the secondary
                         // synchronizer has been Valid for some time).  These scheduled transitions are configurable in the constructor.
-                        this._logger?.debug(`CompositeDataSource received state ${state} from underlying data source.`);
+                        this._logger?.debug(`CompositeDataSource received state ${state} from underlying data source.  Err is ${err}`);
                         if (err || state === DataSourceState.Closed) {
                             callbackHandler.disable();
-                            if (err.recoverable === false) {
+                            if (err?.recoverable === false) {
                                 // don't use this datasource's factory again
+                                this._logger?.debug(`Culling data source due to err ${err}`);
                                 cullDSFactory?.();
+                                // this error indicates we should fallback to only using FDv1 synchronizers
+                                if (err instanceof LDFlagDeliveryFallbackError) {
+                                    this._logger?.debug(`Falling back to FDv1`);
+                                    this._syncFactories = this._fdv1Synchronizers;
+                                }
                             }
                             sanitizedStatusCallback(state, err);
                             this._consumeCancelToken(cancelScheduledTransition);
@@ -1121,7 +1232,7 @@ class CompositeDataSource {
                             }
                         }
                     });
-                    currentDS.start((basis, data) => callbackHandler.dataHandler(basis, data), (status, err) => callbackHandler.statusHandler(status, err));
+                    currentDS.start((basis, data) => callbackHandler.dataHandler(basis, data), (status, err) => callbackHandler.statusHandler(status, err), selectorGetter);
                 }
                 else {
                     // we don't have a data source to use!
@@ -1142,8 +1253,8 @@ class CompositeDataSource {
             // stop the underlying datasource before transitioning to next state
             currentDS?.stop();
             if (transitionRequest.err && transitionRequest.transition !== 'stop') {
-                // if the transition was due to an error, throttle the transition
-                const delay = this._backoff.fail();
+                // if the transition was due to an error we're not in the initializer phase, throttle the transition. Fallback between initializers is not throttled.
+                const delay = this._initPhaseActive ? 0 : this._backoff.fail();
                 const { promise, cancel: cancelDelay } = this._cancellableDelay(delay);
                 this._cancelTokens.push(cancelDelay);
                 const delayedTransition = promise.then(() => {
@@ -1178,6 +1289,7 @@ class CompositeDataSource {
         this._initPhaseActive = this._initFactories.length() > 0; // init phase if we have initializers;
         this._initFactories.reset();
         this._syncFactories.reset();
+        this._fdv1Synchronizers.reset();
         this._externalTransitionPromise = new Promise((tr) => {
             this._externalTransitionResolve = tr;
         });
@@ -1212,6 +1324,11 @@ class CompositeDataSource {
                 break;
             case 'fallback':
             default:
+                // if asked to fallback after using all init factories, switch to sync factories
+                if (this._initPhaseActive && this._initFactories.pos() >= this._initFactories.length()) {
+                    this._initPhaseActive = false;
+                    this._syncFactories.reset();
+                }
                 if (this._initPhaseActive) {
                     isPrimary = this._initFactories.pos() === 0;
                     factory = this._initFactories.next();
@@ -1303,31 +1420,6 @@ exports.DataSourceErrorKind = void 0;
     DataSourceErrorKind["InvalidData"] = "INVALID_DATA";
 })(exports.DataSourceErrorKind || (exports.DataSourceErrorKind = {}));
 
-class LDFileDataSourceError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'LaunchDarklyFileDataSourceError';
-    }
-}
-class LDPollingError extends Error {
-    constructor(kind, message, status, recoverable = true) {
-        super(message);
-        this.kind = kind;
-        this.status = status;
-        this.name = 'LaunchDarklyPollingError';
-        this.recoverable = recoverable;
-    }
-}
-class LDStreamingError extends Error {
-    constructor(kind, message, code, recoverable = true) {
-        super(message);
-        this.kind = kind;
-        this.code = code;
-        this.name = 'LaunchDarklyStreamingError';
-        this.recoverable = recoverable;
-    }
-}
-
 /* eslint-disable import/prefer-default-export */
 /**
  * Enable / disable Auto environment attributes. When enabled, the SDK will automatically
@@ -1810,7 +1902,7 @@ class ServiceEndpoints {
 }
 // eslint-disable-next-line @typescript-eslint/naming-convention
 ServiceEndpoints.DEFAULT_EVENTS = 'https://events.launchdarkly.com';
-function getWithParams(uri, parameters) {
+function getWithParams(uri, parameters = []) {
     if (parameters.length === 0) {
         return uri;
     }
@@ -1839,7 +1931,7 @@ function getStreamingUri(endpoints, path, parameters) {
  * @param path The path to the resource, devoid of any query parameters or hrefs.
  * @param parameters The query parameters. These query parameters must already have the appropriate encoding applied. This function WILL NOT apply it for you.
  */
-function getPollingUri(endpoints, path, parameters) {
+function getPollingUri(endpoints, path, parameters = []) {
     const canonicalizedPath = canonicalizePath(path);
     const combinedParameters = [...parameters];
     if (endpoints.payloadFilterKey) {
@@ -1854,7 +1946,7 @@ function getPollingUri(endpoints, path, parameters) {
  * @param path The path to the resource, devoid of any query parameters or hrefs.
  * @param parameters The query parameters. These query parameters must already have the appropriate encoding applied. This function WILL NOT apply it for you.
  */
-function getEventsUri(endpoints, path, parameters) {
+function getEventsUri(endpoints, path, parameters = []) {
     const canonicalizedPath = canonicalizePath(path);
     return getWithParams(`${endpoints.events}/${canonicalizedPath}`, parameters);
 }
@@ -2353,7 +2445,9 @@ function counterKey(event) {
  * @internal
  */
 class EventSummarizer {
-    constructor() {
+    constructor(_singleContext = false, _contextFilter) {
+        this._singleContext = _singleContext;
+        this._contextFilter = _contextFilter;
         this._startDate = 0;
         this._endDate = 0;
         this._counters = {};
@@ -2361,6 +2455,9 @@ class EventSummarizer {
     }
     summarizeEvent(event) {
         if (isFeature(event) && !event.excludeFromSummaries) {
+            if (!this._context) {
+                this._context = event.context;
+            }
             const countKey = counterKey(event);
             const counter = this._counters[countKey];
             let kinds = this._contextKinds[event.key];
@@ -2410,14 +2507,19 @@ class EventSummarizer {
             flagSummary.counters.push(counterOut);
             return acc;
         }, {});
-        return {
+        const event = {
             startDate: this._startDate,
             endDate: this._endDate,
             features,
             kind: 'summary',
+            context: this._context !== undefined && this._singleContext
+                ? this._contextFilter?.filter(this._context)
+                : undefined,
         };
+        this._clearSummary();
+        return event;
     }
-    clearSummary() {
+    _clearSummary() {
         this._startDate = 0;
         this._endDate = 0;
         this._counters = {};
@@ -2432,6 +2534,38 @@ class LDInvalidSDKKeyError extends Error {
     }
 }
 
+class MultiEventSummarizer {
+    constructor(_contextFilter, _logger) {
+        this._contextFilter = _contextFilter;
+        this._logger = _logger;
+        this._summarizers = {};
+    }
+    summarizeEvent(event) {
+        if (isFeature(event)) {
+            const key = event.context.canonicalUnfilteredJson();
+            if (!key) {
+                if (event.context.valid) {
+                    // The context appeared valid, but it could not be hashed.
+                    // This is likely because of a cycle in the data.
+                    this._logger?.error('Unable to serialize context, likely the context contains a cycle.');
+                }
+                return;
+            }
+            let summarizer = this._summarizers[key];
+            if (!summarizer) {
+                this._summarizers[key] = new EventSummarizer(true, this._contextFilter);
+                summarizer = this._summarizers[key];
+            }
+            summarizer.summarizeEvent(event);
+        }
+    }
+    getSummaries() {
+        const summarizersToFlush = this._summarizers;
+        this._summarizers = {};
+        return Object.values(summarizersToFlush).map((summarizer) => summarizer.getSummary());
+    }
+}
+
 /**
  * The contents of this file are for event sampling. They are not used for
  * any purpose requiring cryptographic security.
@@ -2452,12 +2586,14 @@ function shouldSample(ratio) {
     return Math.floor(Math.random() * truncated) === 0;
 }
 
+function isMultiEventSummarizer(summarizer) {
+    return summarizer.getSummaries !== undefined;
+}
 class EventProcessor {
-    constructor(_config, clientContext, baseHeaders, _contextDeduplicator, _diagnosticsManager, start = true) {
+    constructor(_config, clientContext, baseHeaders, _contextDeduplicator, _diagnosticsManager, start = true, summariesPerContext = false) {
         this._config = _config;
         this._contextDeduplicator = _contextDeduplicator;
         this._diagnosticsManager = _diagnosticsManager;
-        this._summarizer = new EventSummarizer();
         this._queue = [];
         this._lastKnownPastTime = 0;
         this._droppedEvents = 0;
@@ -2470,6 +2606,12 @@ class EventProcessor {
         this._logger = clientContext.basicConfiguration.logger;
         this._eventSender = new EventSender(clientContext, baseHeaders);
         this._contextFilter = new ContextFilter(_config.allAttributesPrivate, _config.privateAttributes.map((ref) => new AttributeReference(ref)));
+        if (summariesPerContext) {
+            this._summarizer = new MultiEventSummarizer(this._contextFilter, this._logger);
+        }
+        else {
+            this._summarizer = new EventSummarizer();
+        }
         if (start) {
             this.start();
         }
@@ -2521,10 +2663,19 @@ class EventProcessor {
         }
         const eventsToFlush = this._queue;
         this._queue = [];
-        const summary = this._summarizer.getSummary();
-        this._summarizer.clearSummary();
-        if (Object.keys(summary.features).length) {
-            eventsToFlush.push(summary);
+        if (isMultiEventSummarizer(this._summarizer)) {
+            const summaries = this._summarizer.getSummaries();
+            summaries.forEach((summary) => {
+                if (Object.keys(summary.features).length) {
+                    eventsToFlush.push(summary);
+                }
+            });
+        }
+        else {
+            const summary = this._summarizer.getSummary();
+            if (Object.keys(summary.features).length) {
+                eventsToFlush.push(summary);
+            }
         }
         if (!eventsToFlush.length) {
             return;
@@ -2835,7 +2986,7 @@ class PayloadProcessor {
             }
             // at the time of writing this, it was agreed upon that SDKs could assume exactly 1 element in this list.  In the future, a negotiation of protocol version will be required to remove this assumption.
             const payload = data.payloads[0];
-            switch (payload?.code) {
+            switch (payload?.intentCode) {
                 case 'xfer-full':
                     this._tempBasis = true;
                     break;
@@ -2848,6 +2999,7 @@ class PayloadProcessor {
                     break;
                 default:
                     // unrecognized intent code, return
+                    this._logger?.warn(`Unable to process intent code '${payload?.intentCode}'.`);
                     return;
             }
             this._tempId = payload?.id;
@@ -3115,6 +3267,7 @@ var index = /*#__PURE__*/Object.freeze({
     NullEventProcessor: NullEventProcessor,
     PayloadProcessor: PayloadProcessor,
     PayloadStreamReader: PayloadStreamReader,
+    canonicalize: canonicalize,
     initMetadataFromHeaders: initMetadataFromHeaders,
     isLegacyUser: isLegacyUser,
     isMultiKind: isMultiKind,
@@ -3139,6 +3292,7 @@ exports.Function = Function;
 exports.KindValidator = KindValidator;
 exports.LDClientError = LDClientError;
 exports.LDFileDataSourceError = LDFileDataSourceError;
+exports.LDFlagDeliveryFallbackError = LDFlagDeliveryFallbackError;
 exports.LDPollingError = LDPollingError;
 exports.LDStreamingError = LDStreamingError;
 exports.LDTimeoutError = LDTimeoutError;