@launchdarkly/js-client-sdk-common 1.14.0 → 1.15.0

package/dist/cjs/index.cjs

@@ -98,6 +98,143 @@ function makeRequestor(plainContextString, serviceEndpoints, paths, requests, en
     return new Requestor(requests, uri, headers, method, body);
 }
 
+const duplicateExecutionError = new Error('Task has already been executed or shed. This is likely an implementation error. The task will not be executed again.');
+/**
+ * Creates a pending task.
+ * @param task The async function to execute.
+ * @param sheddable Whether the task can be shed from the queue.
+ * @returns A pending task.
+ */
+function makePending(task, _logger, sheddable = false) {
+    let resolveTask;
+    const promise = new Promise((resolve) => {
+        resolveTask = (result, beforeResult) => {
+            try {
+                task.after?.(result, beforeResult);
+            }
+            catch (error) {
+                _logger?.error(`Error in after callback: ${error}`);
+            }
+            resolve(result);
+        };
+    });
+    const beforePromise = task.before ? task.before() : Promise.resolve(undefined);
+    let executedOrShed = false;
+    return {
+        execute: () => {
+            if (executedOrShed) {
+                // This should never happen. If it does, then it represents an implementation error in the SDK.
+                _logger?.error(duplicateExecutionError);
+            }
+            executedOrShed = true;
+            beforePromise
+                .then((beforeResult) => {
+                task
+                    .execute(beforeResult)
+                    .then((result) => resolveTask({ status: 'complete', result }, beforeResult))
+                    .catch((error) => resolveTask({ status: 'error', error }, beforeResult));
+            })
+                .catch((error) => {
+                _logger?.error(error);
+                resolveTask({ status: 'error', error }, undefined);
+            });
+        },
+        shed: () => {
+            if (executedOrShed) {
+                // This should never happen. If it does, then it represents an implementation error in the SDK.
+                _logger?.error(duplicateExecutionError);
+            }
+            executedOrShed = true;
+            beforePromise.then((beforeResult) => {
+                resolveTask({ status: 'shed' }, beforeResult);
+            });
+        },
+        promise,
+        sheddable,
+    };
+}
+/**
+ * An asynchronous task queue with the ability to replace pending tasks.
+ *
+ * This is useful when you have asynchronous operations which much execute in order, and for cases where intermediate
+ * operations can be discarded.
+ *
+ * For instance, the SDK can only have one active context at a time, if you request identification of many contexts,
+ * then the ultimate state will be based on the last request. The intermediate identifies can be discarded.
+ *
+ * This queue will always begin execution of the first item added to the queue, at that point the item itself is not
+ * queued, but active. If another request is made while that item is still active, then it is added to the queue.
+ * A third request would then replace the second request if the second request had not yet become active, and it was
+ * sheddable.
+ *
+ * Once a task is active the queue will complete it. It doesn't cancel tasks that it has started, but it can shed tasks
+ * that have not started.
+ *
+ * TTaskResult Is the return type of the task to be executed. Tasks accept no parameters. So if you need parameters
+ * you should use a lambda to capture them.
+ *
+ * Exceptions from tasks are always handled and the execute method will never reject a promise.
+ *
+ * Queue management should be done synchronously. There should not be asynchronous operations between checking the queue
+ * and acting on the results of said check.
+ */
+function createAsyncTaskQueue(logger) {
+    let activeTask;
+    const queue = [];
+    function checkPending() {
+        // There is an existing active task, so we don't need to do anything.
+        if (activeTask) {
+            return;
+        }
+        // There are pending tasks, so we need to execute the next one.
+        if (queue.length > 0) {
+            const nextTask = queue.shift();
+            activeTask = nextTask.promise.finally(() => {
+                activeTask = undefined;
+                checkPending();
+            });
+            nextTask.execute();
+        }
+    }
+    return {
+        /**
+         * Execute a task using the queue.
+         *
+         * @param task The async function to execute.
+         * @param sheddable Whether the task can be shed from the queue.
+         * @returns A promise that resolves to the result of the task.
+         */
+        execute(task, sheddable = false) {
+            const pending = makePending(task, logger, sheddable);
+            if (!activeTask) {
+                activeTask = pending.promise.finally(() => {
+                    activeTask = undefined;
+                    checkPending();
+                });
+                pending.execute();
+            }
+            else {
+                // If the last pending task is sheddable, we need to shed it before adding the new task.
+                if (queue[queue.length - 1]?.sheddable) {
+                    queue.pop()?.shed();
+                }
+                queue.push(pending);
+            }
+            return pending.promise;
+        },
+        /**
+         * Returns the number of pending tasks in the queue.
+         * Intended for testing purposes only.
+         *
+         * @internal
+         * @returns The number of pending tasks in the queue.
+         */
+        pendingCount() {
+            return queue.length;
+        },
+    };
+}
+
 // eslint-disable-next-line max-classes-per-file
 const validators = {
     logger: jsSdkCommon.TypeValidators.Object,
@@ -1212,6 +1349,7 @@ class LDClientImpl {
         this._eventFactoryDefault = new EventFactory(false);
         this._eventFactoryWithReasons = new EventFactory(true);
         this._eventSendingEnabled = false;
+        this._identifyQueue = createAsyncTaskQueue();
         if (!sdkKey) {
             throw new Error('You must configure the client with a client-side SDK key');
         }
@@ -1277,7 +1415,7 @@ class LDClientImpl {
     }
     getContext() {
         // The LDContext returned here may have been modified by the SDK (for example: adding auto env attributes).
-        // We are returning an LDContext here to maintain a consistent represetnation of context to the consuming
+        // We are returning an LDContext here to maintain a consistent representation of context to the consuming
         // code.  We are returned the unchecked context so that if a consumer identifies with an invalid context
         // and then calls getContext, they get back the same context they provided, without any assertion about
         // validity.
@@ -1286,28 +1424,25 @@ class LDClientImpl {
     getInternalContext() {
         return this._checkedContext;
     }
-    _createIdentifyPromise(timeout, noTimeout) {
+    _createIdentifyPromise() {
         let res;
         let rej;
         const basePromise = new Promise((resolve, reject) => {
             res = resolve;
             rej = reject;
         });
-        if (noTimeout) {
-            return { identifyPromise: basePromise, identifyResolve: res, identifyReject: rej };
-        }
-        const timed = jsSdkCommon.timedPromise(timeout, 'identify');
-        const raced = Promise.race([timed, basePromise]).catch((e) => {
-            if (e.message.includes('timed out')) {
-                this.logger.error(`identify error: ${e}`);
-            }
-            throw e;
-        });
-        return { identifyPromise: raced, identifyResolve: res, identifyReject: rej };
+        return { identifyPromise: basePromise, identifyResolve: res, identifyReject: rej };
     }
     /**
      * Identifies a context to LaunchDarkly. See {@link LDClient.identify}.
      *
+     * If used with the `sheddable` option set to true, then the identify operation will be sheddable. This means that if
+     * multiple identify operations are done, without waiting for the previous one to complete, then intermediate
+     * operations may be discarded.
+     *
+     * It is recommended to use the `identifyResult` method instead when the operation is sheddable. In a future release,
+     * all identify operations will default to being sheddable.
+     *
      * @param pristineContext The LDContext object to be identified.
      * @param identifyOptions Optional configuration. See {@link LDIdentifyOptions}.
      * @returns A Promise which resolves when the flag values for the specified
@@ -1321,39 +1456,95 @@ class LDClientImpl {
      * 3. A network error is encountered during initialization.
      */
     async identify(pristineContext, identifyOptions) {
+        // In order to manage customization in the derived classes it is important that `identify` MUST be implemented in
+        // terms of `identifyResult`. So that the logic of the identification process can be extended in one place.
+        const result = await this.identifyResult(pristineContext, identifyOptions);
+        if (result.status === 'error') {
+            throw result.error;
+        }
+        else if (result.status === 'timeout') {
+            const timeoutError = new jsSdkCommon.LDTimeoutError(`identify timed out after ${result.timeout} seconds.`);
+            this.logger.error(timeoutError.message);
+            throw timeoutError;
+        }
+        // If completed or shed, then we are done.
+    }
+    async identifyResult(pristineContext, identifyOptions) {
         const identifyTimeout = identifyOptions?.timeout ?? DEFAULT_IDENTIFY_TIMEOUT_SECONDS;
         const noTimeout = identifyOptions?.timeout === undefined && identifyOptions?.noTimeout === true;
-        // When noTimeout is specified, and a timeout is not secified, then this condition cannot
+        // When noTimeout is specified, and a timeout is not specified, then this condition cannot
         // be encountered. (Our default would need to be greater)
         if (identifyTimeout > this._highTimeoutThreshold) {
             this.logger.warn('The identify function was called with a timeout greater than ' +
                 `${this._highTimeoutThreshold} seconds. We recommend a timeout of less than ` +
                 `${this._highTimeoutThreshold} seconds.`);
         }
-        let context = await ensureKey(pristineContext, this.platform);
-        if (this.autoEnvAttributes === jsSdkCommon.AutoEnvAttributes.Enabled) {
-            context = await addAutoEnv(context, this.platform, this._config);
-        }
-        const checkedContext = jsSdkCommon.Context.fromLDContext(context);
-        if (!checkedContext.valid) {
-            const error = new Error('Context was unspecified or had no key');
-            this.emitter.emit('error', context, error);
-            return Promise.reject(error);
-        }
-        this._uncheckedContext = context;
-        this._checkedContext = checkedContext;
-        this._eventProcessor?.sendEvent(this._eventFactoryDefault.identifyEvent(this._checkedContext));
-        const { identifyPromise, identifyResolve, identifyReject } = this._createIdentifyPromise(identifyTimeout, noTimeout);
-        this.logger.debug(`Identifying ${JSON.stringify(this._checkedContext)}`);
-        const afterIdentify = this._hookRunner.identify(context, identifyOptions?.timeout);
-        await this.dataManager.identify(identifyResolve, identifyReject, checkedContext, identifyOptions);
-        return identifyPromise.then((res) => {
-            afterIdentify({ status: 'completed' });
-            return res;
-        }, (e) => {
-            afterIdentify({ status: 'error' });
-            throw e;
+        const callSitePromise = this._identifyQueue
+            .execute({
+            before: async () => {
+                let context = await ensureKey(pristineContext, this.platform);
+                if (this.autoEnvAttributes === jsSdkCommon.AutoEnvAttributes.Enabled) {
+                    context = await addAutoEnv(context, this.platform, this._config);
+                }
+                const checkedContext = jsSdkCommon.Context.fromLDContext(context);
+                if (checkedContext.valid) {
+                    const afterIdentify = this._hookRunner.identify(context, identifyOptions?.timeout);
+                    return {
+                        context,
+                        checkedContext,
+                        afterIdentify,
+                    };
+                }
+                return {
+                    context,
+                    checkedContext,
+                };
+            },
+            execute: async (beforeResult) => {
+                const { context, checkedContext } = beforeResult;
+                if (!checkedContext.valid) {
+                    const error = new Error('Context was unspecified or had no key');
+                    this.emitter.emit('error', context, error);
+                    return Promise.reject(error);
+                }
+                this._uncheckedContext = context;
+                this._checkedContext = checkedContext;
+                this._eventProcessor?.sendEvent(this._eventFactoryDefault.identifyEvent(this._checkedContext));
+                const { identifyPromise, identifyResolve, identifyReject } = this._createIdentifyPromise();
+                this.logger.debug(`Identifying ${JSON.stringify(this._checkedContext)}`);
+                await this.dataManager.identify(identifyResolve, identifyReject, checkedContext, identifyOptions);
+                return identifyPromise;
+            },
+            after: async (res, beforeResult) => {
+                if (res.status === 'complete') {
+                    beforeResult?.afterIdentify?.({ status: 'completed' });
+                }
+                else if (res.status === 'shed') {
+                    beforeResult?.afterIdentify?.({ status: 'shed' });
+                }
+                else if (res.status === 'error') {
+                    beforeResult?.afterIdentify?.({ status: 'error' });
+                }
+            },
+        }, identifyOptions?.sheddable ?? false)
+            .then((res) => {
+            if (res.status === 'error') {
+                return { status: 'error', error: res.error };
+            }
+            if (res.status === 'shed') {
+                return { status: 'shed' };
+            }
+            return { status: 'completed' };
+        });
+        if (noTimeout) {
+            return callSitePromise;
+        }
+        const timeoutPromise = new Promise((resolve) => {
+            setTimeout(() => {
+                resolve({ status: 'timeout', timeout: identifyTimeout });
+            }, identifyTimeout * 1000);
         });
+        return Promise.race([callSitePromise, timeoutPromise]);
     }
     on(eventName, listener) {
         this.emitter.on(eventName, listener);
@@ -1650,6 +1841,9 @@ class DataSourceStatusManager {
     }
 }
 
+function reportClosed(logger) {
+    logger?.debug(`Poll completed after the processor was closed. Skipping processing.`);
+}
 /**
  * @internal
  */
@@ -1676,6 +1870,12 @@ class PollingProcessor {
         try {
             const res = await this._requestor.requestPayload();
             try {
+                // If the processor has been stopped, we discard the response.
+                // This response could be for a no longer active context.
+                if (this._stopped) {
+                    reportClosed(this._logger);
+                    return;
+                }
                 const flags = JSON.parse(res);
                 try {
                     this._dataHandler?.(flags);
@@ -1689,6 +1889,12 @@ class PollingProcessor {
             }
         }
         catch (err) {
+            // If the processor has been stopped, we discard this error.
+            // The original caller would consider this connection no longer active.
+            if (this._stopped) {
+                reportClosed(this._logger);
+                return;
+            }
             const requestError = err;
             if (requestError.status !== undefined) {
                 if (!jsSdkCommon.isHttpRecoverable(requestError.status)) {
@@ -1726,6 +1932,12 @@ const reportJsonError = (type, data, logger, errorHandler) => {
     logger?.debug(`Invalid JSON follows: ${data}`);
     errorHandler?.(new jsSdkCommon.LDStreamingError(jsSdkCommon.DataSourceErrorKind.InvalidData, 'Malformed JSON data in event stream'));
 };
+function reportEventClosed(eventName, logger) {
+    logger?.debug(`Received ${eventName} event after processor was closed. Skipping processing.`);
+}
+function reportPingClosed(logger) {
+    logger?.debug('Ping completed after processor was closed. Skipping processing.');
+}
 class StreamingProcessor {
     constructor(_plainContextString, _dataSourceConfig, _listeners, _requests, encoding, _pollingRequestor, _diagnosticsManager, _errorHandler, _logger) {
         this._plainContextString = _plainContextString;
@@ -1736,6 +1948,7 @@ class StreamingProcessor {
         this._diagnosticsManager = _diagnosticsManager;
         this._errorHandler = _errorHandler;
         this._logger = _logger;
+        this._stopped = false;
         let path;
         if (_dataSourceConfig.useReport && !_requests.getEventSourceCapabilities().customMethod) {
             path = _dataSourceConfig.paths.pathPing(encoding, _plainContextString);
@@ -1823,6 +2036,12 @@ class StreamingProcessor {
         };
         this._listeners.forEach(({ deserializeData, processJson }, eventName) => {
             eventSource.addEventListener(eventName, (event) => {
+                // If an event comes in after the processor has been stopped, we skip processing it.
+                // This event could be for a context which is no longer active.
+                if (this._stopped) {
+                    reportEventClosed(eventName, this._logger);
+                    return;
+                }
                 this._logger?.debug(`Received ${eventName} event`);
                 if (event?.data) {
                     this._logConnectionResult(true);
@@ -1845,6 +2064,12 @@ class StreamingProcessor {
             try {
                 const res = await this._pollingRequestor.requestPayload();
                 try {
+                    // If the ping completes after the processor has been stopped, then we discard it.
+                    // This event could be for a context which is no longer active.
+                    if (this._stopped) {
+                        reportPingClosed(this._logger);
+                        return;
+                    }
                     const payload = JSON.parse(res);
                     try {
                         // forward the payload on to the PUT listener
@@ -1861,6 +2086,12 @@ class StreamingProcessor {
                 }
             }
             catch (err) {
+                if (this._stopped) {
+                    // If the ping errors after the processor has been stopped, then we discard it.
+                    // The original caller would consider this connection no longer active.
+                    reportPingClosed(this._logger);
+                    return;
+                }
                 const requestError = err;
                 this._errorHandler?.(new jsSdkCommon.LDPollingError(jsSdkCommon.DataSourceErrorKind.ErrorResponse, requestError.message, requestError.status));
             }
@@ -1869,6 +2100,7 @@ class StreamingProcessor {
     stop() {
         this._eventSource?.close();
         this._eventSource = undefined;
+        this._stopped = true;
     }
     close() {
         this.stop();