@microsoft/applicationinsights-core-js 2.8.0-beta.2202-07 → 2.8.0-beta.2203-03

package/src/JavaScriptSDK/BaseCore.ts

@@ -13,24 +13,33 @@ import { INotificationManager } from "../JavaScriptSDK.Interfaces/INotificationM
 import { INotificationListener } from "../JavaScriptSDK.Interfaces/INotificationListener";
 import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
 import { IProcessTelemetryContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
-import { createProcessTelemetryContext, createTelemetryProxyChain } from "./ProcessTelemetryContext";
-import { initializePlugins, sortPlugins } from "./TelemetryHelpers";
-import { LoggingSeverity } from "../JavaScriptSDK.Enums/LoggingEnums";
+import { createProcessTelemetryContext, createProcessTelemetryUnloadContext, createTelemetryProxyChain } from "./ProcessTelemetryContext";
+import { initializePlugins, sortPlugins, _getPluginState } from "./TelemetryHelpers";
+import { eLoggingSeverity, _eInternalMessageId } from "../JavaScriptSDK.Enums/LoggingEnums";
 import { IPerfManager } from "../JavaScriptSDK.Interfaces/IPerfManager";
 import { getGblPerfMgr, PerfManager } from "./PerfManager";
 import { ICookieMgr } from "../JavaScriptSDK.Interfaces/ICookieMgr";
 import { createCookieMgr } from "./CookieMgr";
-import { arrForEach, isNullOrUndefined, toISOString, getSetValue, setValue, throwError, isNotTruthy, isFunction, objFreeze, proxyFunctions } from "./HelperFuncs";
+import { arrForEach, isNullOrUndefined, toISOString, getSetValue, setValue, throwError, isNotTruthy, isFunction, objFreeze, proxyFunctionAs, proxyFunctions } from "./HelperFuncs";
 import { strExtensionConfig, strIKey } from "./Constants";
 import { DiagnosticLogger, _InternalLogMessage } from "./DiagnosticLogger";
 import { getDebugListener } from "./DbgExtensionUtils";
 import { ITelemetryPluginChain } from "../JavaScriptSDK.Interfaces/ITelemetryPluginChain";
-import { ChannelControllerPriority, createChannelControllerPlugin, createChannelQueues, IChannelController, _IInternalChannels } from "./ChannelController";
+import { ChannelControllerPriority, createChannelControllerPlugin, createChannelQueues, IChannelController, IInternalChannelController, _IInternalChannels } from "./ChannelController";
 import { ITelemetryInitializerHandler, TelemetryInitializerFunction } from "../JavaScriptSDK.Interfaces/ITelemetryInitializers";
 import { TelemetryInitializerPlugin } from "./TelemetryInitializerPlugin";
+import { createUniqueNamespace } from "./DataCacheHelper";
+import { createUnloadHandlerContainer, IUnloadHandlerContainer, UnloadHandler } from "./UnloadHandlerContainer";
+import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
+import { TelemetryUnloadReason } from "../JavaScriptSDK.Enums/TelemetryUnloadReason";
+import { SendRequestReason } from "../JavaScriptSDK.Enums/SendRequestReason";
+import { strAddNotificationListener, strDisabled, strEventsDiscarded, strEventsSendRequest, strEventsSent, strRemoveNotificationListener, strTeardown } from "./InternalConstants";
 
 const strValidationError = "Plugins must provide initialize method";
 const strNotificationManager = "_notificationManager";
+const strSdkUnloadingError = "SDK is still unloading...";
+const strSdkNotInitialized = "SDK is not initialized";
+const strPluginUnloadFailed = "Failed to unload plugin";
 
 /**
  * Helper to create the default performance manager
@@ -80,6 +89,29 @@ function _validateExtensions(logger: IDiagnosticLogger, channelPriority: number,
     };
 }
 
+function _isPluginPresent(thePlugin: IPlugin, plugins: IPlugin[]) {
+    let exists = false;
+
+    arrForEach(plugins, (plugin) => {
+        if (plugin === thePlugin) {
+            exists = true;
+            return -1;
+        }
+    });
+
+    return exists;
+}
+
+function _createDummyNotificationManager(): INotificationManager {
+    return objCreateFn({
+        [strAddNotificationListener]: (listener: INotificationListener) => { },
+        [strRemoveNotificationListener]: (listener: INotificationListener) => { },
+        [strEventsSent]: (events: ITelemetryItem[]) => { },
+        [strEventsDiscarded]: (events: ITelemetryItem[], reason: number) => { },
+        [strEventsSendRequest]: (sendReason: number, isAsync: boolean) => { }
+    });
+}
+
 export class BaseCore implements IAppInsightsCore {
     public static defaultConfig: IConfiguration;
     public config: IConfiguration;
@@ -102,8 +134,11 @@ export class BaseCore implements IAppInsightsCore {
         let _channelControl: IChannelController;
         let _channelConfig: IChannelControls[][];
         let _channelQueue: _IInternalChannels[];
+        let _isUnloading: boolean;
         let _telemetryInitializerPlugin: TelemetryInitializerPlugin;
         let _internalLogsEventName: string;
+        let _evtNamespace: string;
+        let _unloadHandlers: IUnloadHandlerContainer;
         let _debugListener: INotificationListener;
 
         /**
@@ -119,6 +154,10 @@ export class BaseCore implements IAppInsightsCore {
             _self.isInitialized = () => _isInitialized;
 
             _self.initialize = (config: IConfiguration, extensions: IPlugin[], logger?: IDiagnosticLogger, notificationManager?: INotificationManager): void => {
+                if (_isUnloading) {
+                    throwError(strSdkUnloadingError);
+                }
+        
                 // Make sure core is only initialized once
                 if (_self.isInitialized()) {
                     throwError("Core should not be initialized more than once");
@@ -140,8 +179,7 @@ export class BaseCore implements IAppInsightsCore {
                 config.extensions = isNullOrUndefined(config.extensions) ? [] : config.extensions;
         
                 // add notification to the extensions in the config so other plugins can access it
-                let extConfig = getSetValue(config, strExtensionConfig);
-                extConfig.NotificationManager = notificationManager;
+                _initExtConfig(config);
 
                 if (logger) {
                     _self.logger = logger;
@@ -181,29 +219,21 @@ export class BaseCore implements IAppInsightsCore {
                 // Common Schema 4.0
                 setValue(telemetryItem, "ver", "4.0", null, isNullOrUndefined);
         
-                if (_self.isInitialized()) {
+                if (!_isUnloading && _self.isInitialized()) {
                     // Process the telemetry plugin chain
-                    _self.getProcessTelContext().processNext(telemetryItem);
+                    _createTelCtx().processNext(telemetryItem);
                 } else {
                     // Queue events until all extensions are initialized
                     _eventQueue.push(telemetryItem);
                 }
             };
         
-            _self.getProcessTelContext = (): IProcessTelemetryContext => {
-                return createProcessTelemetryContext(_getPluginChain(), _self.config, _self);
-            };
+            _self.getProcessTelContext = _createTelCtx;
 
             _self.getNotifyMgr = (): INotificationManager => {
                 if (!_notificationManager) {
                     // Create Dummy notification manager
-                    _notificationManager = objCreateFn({
-                        addNotificationListener: (listener: INotificationListener) => { },
-                        removeNotificationListener: (listener: INotificationListener) => { },
-                        eventsSent: (events: ITelemetryItem[]) => { },
-                        eventsDiscarded: (events: ITelemetryItem[], reason: number) => { },
-                        eventsSendRequest: (sendReason: number, isAsync: boolean) => { }
-                    });
+                    _notificationManager = _createDummyNotificationManager();
 
                     // For backward compatibility only
                     _self[strNotificationManager] = _notificationManager;
@@ -218,9 +248,9 @@ export class BaseCore implements IAppInsightsCore {
              * called.
              * @param {INotificationListener} listener - An INotificationListener object.
              */
-             _self.addNotificationListener = (listener: INotificationListener): void => {
+             _self[strAddNotificationListener] = (listener: INotificationListener): void => {
                  if (_notificationManager) {
-                     _notificationManager.addNotificationListener(listener);
+                     _notificationManager[strAddNotificationListener](listener);
                  }
             };
         
@@ -228,9 +258,9 @@ export class BaseCore implements IAppInsightsCore {
              * Removes all instances of the listener.
              * @param {INotificationListener} listener - INotificationListener to remove.
              */
-            _self.removeNotificationListener = (listener: INotificationListener): void => {
+            _self[strRemoveNotificationListener] = (listener: INotificationListener): void => {
                 if (_notificationManager) {
-                    _notificationManager.removeNotificationListener(listener);
+                    _notificationManager[strRemoveNotificationListener](listener);
                 }
             }
         
@@ -270,7 +300,7 @@ export class BaseCore implements IAppInsightsCore {
                     _eventQueue = [];
 
                     arrForEach(eventQueue, (event: ITelemetryItem) => {
-                        _self.getProcessTelContext().processNext(event);
+                        _createTelCtx().processNext(event);
                     });
                 }
             };
@@ -309,13 +339,108 @@ export class BaseCore implements IAppInsightsCore {
             // Add addTelemetryInitializer
             proxyFunctions(_self, () => _telemetryInitializerPlugin, [ "addTelemetryInitializer" ]);
 
+            _self.unload = (isAsync: boolean = true, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void => {
+                if (!_isInitialized) {
+                    // The SDK is not initialized
+                    throwError(strSdkNotInitialized);
+                }
+
+                // Check if the SDK still unloading so throw
+                if (_isUnloading) {
+                    // The SDK is already unloading
+                    throwError(strSdkUnloadingError);
+                }
+
+                let unloadState: ITelemetryUnloadState = {
+                    reason: TelemetryUnloadReason.SdkUnload,
+                    isAsync: isAsync,
+                    flushComplete: false
+                }
+
+                let processUnloadCtx = createProcessTelemetryUnloadContext(_getPluginChain(), _self.config, _self);
+                processUnloadCtx.onComplete(() => {
+                    _initDefaults();
+                    unloadComplete && unloadComplete(unloadState);
+                }, _self);
+
+                function _doUnload(flushComplete: boolean) {
+                    unloadState.flushComplete = flushComplete;
+                    _isUnloading = true;
+
+                    // Run all of the unload handlers first (before unloading the plugins)
+                    _unloadHandlers.run(processUnloadCtx, unloadState);
+                    
+                    // Stop polling the internal logs
+                    _self.stopPollingInternalLogs();
+
+                    // Start unloading the components, from this point onwards the SDK should be considered to be in an unstable state
+                    processUnloadCtx.processNext(unloadState);
+                }
+
+                if (_channelControl) {
+                    _channelControl.flush(isAsync, _doUnload, SendRequestReason.SdkUnload, cbTimeout);
+                } else {
+                    _doUnload(true);
+                }
+            };
+
             _self.getPlugin = _getPlugin;
 
+            _self.addPlugin = <T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, isAsync: boolean = true, addCb?: (added?: boolean) => void): void => {
+                if (!plugin) {
+                    addCb && addCb(false);
+                    _logOrThrowError(strValidationError);
+                    return;
+                }
+
+                let existingPlugin = _getPlugin(plugin.identifier);
+                if (existingPlugin && !replaceExisting) {
+                    addCb && addCb(false);
+
+                    _logOrThrowError("Plugin [" + plugin.identifier + "] is already loaded!");
+                    return;
+                }
+
+                function _addPlugin(removed: boolean) {
+                    _configExtensions.push(plugin);
+
+                    // Re-Initialize the plugin chain
+                    _initPluginChain(_self.config);
+                    addCb && addCb(true);
+                }
+
+                if (existingPlugin) {
+                    let removedPlugins: IPlugin[] = [existingPlugin.plugin];
+                    let unloadState: ITelemetryUnloadState = {
+                        reason: TelemetryUnloadReason.PluginReplace,
+                        isAsync: isAsync
+                    };
+
+                    _removePlugins(removedPlugins, unloadState, (removed) => {
+                        if (!removed) {
+                            // Previous plugin was successfully removed or was not installed
+                            addCb && addCb(false);
+                        } else {
+                            _addPlugin(true);
+                        }
+                    });
+                } else {
+                    _addPlugin(false);
+                }
+            };
+
+            _self.evtNamespace = (): string => {
+                return _evtNamespace;
+            };
+
+            // Create the addUnloadCb
+            proxyFunctionAs(_self, "addUnloadCb", () => _unloadHandlers, "add");
+
             function _initDefaults() {
                 _isInitialized = false;
 
                 // Use a default logger so initialization errors are not dropped on the floor with full logging
-                _self.logger = new DiagnosticLogger({ loggingLevelConsole: LoggingSeverity.CRITICAL });
+                _self.logger = new DiagnosticLogger({ loggingLevelConsole: eLoggingSeverity.CRITICAL });
                 _self.config = null;
                 _self._extensions = [];
 
@@ -331,7 +456,14 @@ export class BaseCore implements IAppInsightsCore {
                 _channelControl = null;
                 _channelConfig = null;
                 _channelQueue = null;
+                _isUnloading = false;
                 _internalLogsEventName = null;
+                _evtNamespace = createUniqueNamespace("AIBaseCore", true);
+                _unloadHandlers = createUnloadHandlerContainer();
+            }
+
+            function _createTelCtx(): IProcessTelemetryContext {
+                return createProcessTelemetryContext(_getPluginChain(), _self.config, _self);
             }
 
             // Initialize or Re-initialize the plugins
@@ -347,7 +479,25 @@ export class BaseCore implements IAppInsightsCore {
 
                 // Initialize the Channel Queues and the channel plugins first
                 _channelQueue = objFreeze(createChannelQueues(_channelConfig, allExtensions, config, _self));
-                _channelControl = createChannelControllerPlugin(_channelQueue, _self);
+                if (_channelControl) {
+                    // During add / remove of a plugin this may get called again, so don't re-add if already present
+                    // But we also want the controller as the last, so remove if already present
+                    // And reusing the existing instance, just in case an installed plugin has a reference and
+                    // is using it.
+                    let idx = allExtensions.indexOf(_channelControl);
+                    if (idx !== -1) {
+                        allExtensions.splice(idx, 1);
+                    }
+
+                    idx = _coreExtensions.indexOf(_channelControl);
+                    if (idx !== -1) {
+                        _coreExtensions.splice(idx, 1);
+                    }
+
+                    (_channelControl as IInternalChannelController)._setQueue(_channelQueue);
+                } else {
+                    _channelControl = createChannelControllerPlugin(_channelQueue, _self);
+                }
 
                 // Add on "channelController" as the last "plugin"
                 allExtensions.push(_channelControl);
@@ -359,7 +509,7 @@ export class BaseCore implements IAppInsightsCore {
                 // Initialize the controls
                 _channelControl.initialize(config, _self, allExtensions);
                 
-                initializePlugins(_self.getProcessTelContext(), allExtensions);
+                initializePlugins(_createTelCtx(), allExtensions);
 
                 // Now reset the extensions to just those being managed by Basecore
                 _self._extensions = objFreeze(sortPlugins(_coreExtensions || [])).slice();
@@ -370,15 +520,43 @@ export class BaseCore implements IAppInsightsCore {
                 let thePlugin: IPlugin = null;
 
                 arrForEach(_self._extensions, (ext: any) => {
-                    if (ext.identifier === pluginIdentifier) {
+                    if (ext.identifier === pluginIdentifier && ext !== _channelControl && ext !== _telemetryInitializerPlugin) {
                         thePlugin = ext;
                         return -1;
                     }
                 });
 
+                if (!thePlugin && _channelControl) {
+                    // Check the channel Controller
+                    thePlugin = _channelControl.getChannel(pluginIdentifier);
+                }
+
                 if (thePlugin) {
                     theExt = {
-                        plugin: thePlugin as T
+                        plugin: thePlugin as T,
+                        setEnabled: (enabled: boolean) => {
+                            _getPluginState(thePlugin)[strDisabled] = !enabled;
+                        },
+                        isEnabled: () => {
+                            let pluginState = _getPluginState(thePlugin);
+                            return !pluginState[strTeardown] && !pluginState[strDisabled];
+                        },
+                        remove: (isAsync: boolean = true, removeCb?: (removed?: boolean) => void): void => {
+                            let pluginsToRemove: IPlugin[] = [thePlugin];
+                            let unloadState: ITelemetryUnloadState = {
+                                reason: TelemetryUnloadReason.PluginUnload,
+                                isAsync: isAsync
+                            };
+
+                            _removePlugins(pluginsToRemove, unloadState, (removed) => {
+                                if (removed) {
+                                    // Re-Initialize the plugin chain
+                                    _initPluginChain(_self.config);
+                                }
+
+                                removeCb && removeCb(removed);
+                            });
+                        }
                     }
                 }
 
@@ -389,8 +567,11 @@ export class BaseCore implements IAppInsightsCore {
                 if (!_pluginChain) {
                     // copy the collection of extensions
                     let extensions = (_coreExtensions || []).slice();
-            
-                    extensions.push(_telemetryInitializerPlugin);
+
+                    // During add / remove this may get called again, so don't readd if already present
+                    if (extensions.indexOf(_telemetryInitializerPlugin) === -1) {
+                        extensions.push(_telemetryInitializerPlugin);
+                    }
 
                     _pluginChain = createTelemetryProxyChain(sortPlugins(extensions), _self.config, _self);
                 }
@@ -398,6 +579,55 @@ export class BaseCore implements IAppInsightsCore {
                 return _pluginChain;
             }
 
+            function _removePlugins(thePlugins: IPlugin[], unloadState: ITelemetryUnloadState, removeComplete: (removed: boolean) => void) {
+
+                if (thePlugins && thePlugins.length > 0) {
+                    let unloadChain = createTelemetryProxyChain(thePlugins, _self.config, _self);
+                    let unloadCtx = createProcessTelemetryUnloadContext(unloadChain, _self.config, _self);
+
+                    unloadCtx.onComplete(() => {
+                        let removed = false;
+
+                        // Remove the listed config extensions
+                        let newConfigExtensions: IPlugin[] = [];
+                        arrForEach(_configExtensions, (plugin, idx) => {
+                            if (!_isPluginPresent(plugin, thePlugins)) {
+                                newConfigExtensions.push(plugin);
+                            } else {
+                                removed = true;
+                            }
+                        });
+
+                        _configExtensions = newConfigExtensions;
+
+                        // Re-Create the channel config
+                        let newChannelConfig: IChannelControls[][] = [];
+                        if (_channelConfig) {
+                            arrForEach(_channelConfig, (queue, idx) => {
+                                let newQueue: IChannelControls[] = [];
+                                arrForEach(queue, (channel) => {
+                                    if (!_isPluginPresent(channel, thePlugins)) {
+                                        newQueue.push(channel);
+                                    } else {
+                                        removed = true;
+                                    }
+                                });
+
+                                newChannelConfig.push(newQueue);
+                            });
+
+                            _channelConfig = newChannelConfig;
+                        }
+
+                        removeComplete && removeComplete(removed);
+                    });
+
+                    unloadCtx.processNext(unloadState);
+                } else {
+                    removeComplete(false);
+                }
+            }
+
             function _flushInternalLogs() {
                 let queue: _InternalLogMessage[] = _self.logger ? _self.logger.queue : [];
                 if (queue) {
@@ -420,13 +650,13 @@ export class BaseCore implements IAppInsightsCore {
 
                 if (config.disableDbgExt === true && _debugListener) {
                     // Remove any previously loaded debug listener
-                    _notificationManager.removeNotificationListener(_debugListener);
+                    _notificationManager[strRemoveNotificationListener](_debugListener);
                     _debugListener = null;
                 }
 
                 if (_notificationManager && !_debugListener && config.disableDbgExt !== true) {
                     _debugListener = getDebugListener(config);
-                    _notificationManager.addNotificationListener(_debugListener);
+                    _notificationManager[strAddNotificationListener](_debugListener);
                 }
             }
 
@@ -441,6 +671,21 @@ export class BaseCore implements IAppInsightsCore {
                     setValue(_self.config, "createPerfMgr", _createPerfManager);
                 }
             }
+
+            function _initExtConfig(config: IConfiguration) {
+                let extConfig = getSetValue(config, strExtensionConfig);
+                extConfig.NotificationManager = _notificationManager;
+            }
+
+            function _logOrThrowError(message: string) {
+                let logger = _self.logger;
+                if (logger) {
+                    // there should always be a logger
+                    logger.throwInternal(eLoggingSeverity.WARNING, _eInternalMessageId.PluginException, message);
+                } else {
+                    throwError(message);
+                }
+            }
         });
     }
 
@@ -539,10 +784,44 @@ export class BaseCore implements IAppInsightsCore {
         // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
     }
 
+    /**
+     * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered
+     * to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous
+     * unload call return `true` stating that all plugins reported that they also unloaded, the recommended
+     * approach is to create a new instance and initialize that instance.
+     * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
+     * to successfully remove any global references or they may just be completing the unload process asynchronously.
+     */
+    public unload(isAsync?: boolean, unloadComplete?: () => void): void {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+        return null;
+    }
+
     public getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T> {
         // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
         return null;
     }
+
+    public addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+    }
+
+    /**
+     * Returns the unique event namespace that should be used
+     */
+    public evtNamespace(): string {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+        return null;
+    }
+
+    /**
+     * Add an unload handler that will be called when the SDK is being unloaded
+     * @param handler - the handler
+     */
+    public addUnloadCb(handler: UnloadHandler): void {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+    }
+
     protected releaseQueue() {
         // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
     }