@microsoft/applicationinsights-core-js 2.8.0-nightly.2202-06 → 2.8.0-nightly.2204-06

package/src/JavaScriptSDK/RandomHelper.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT License.
 import { getCrypto, getMsCrypto, isIE }  from "./EnvUtils";
 import { dateNow } from "./HelperFuncs";
+import { strEmpty } from "./InternalConstants";
 
 const UInt32Mask = 0x100000000;
 const MaxUInt32 = 0xffffffff;
@@ -52,12 +53,14 @@ export function randomValue(maxValue: number) {
  * @param signed - True to return a signed 32-bit number (-0x80000000..0x7FFFFFFF) otherwise an unsigned one (0x000000..0xFFFFFFFF)
  */
 export function random32(signed?: boolean) {
-    let value;
+    let value = 0;
     let c = getCrypto() || getMsCrypto();
     if (c && c.getRandomValues) {
         // Make sure the number is converted into the specified range (-0x80000000..0x7FFFFFFF)
         value = c.getRandomValues(new Uint32Array(1))[0] & MaxUInt32;
-    } else if (isIE()) {
+    }
+    
+    if (value === 0 && isIE()) {
         // For IE 6, 7, 8 (especially on XP) Math.random is not very random
         if (!_mwcSeeded) {
             // Set the seed for the Mwc algorithm
@@ -67,7 +70,9 @@ export function random32(signed?: boolean) {
         // Don't use Math.random for IE
         // Make sure the number is converted into the specified range (-0x80000000..0x7FFFFFFF)
         value = mwcRandom32() & MaxUInt32;
-    } else {
+    }
+
+    if (value === 0) {
         // Make sure the number is converted into the specified range (-0x80000000..0x7FFFFFFF)
         value = Math.floor((UInt32Mask * Math.random()) | 0);
     }
@@ -112,3 +117,30 @@ export function mwcRandom32(signed?: boolean) {
     return value;
 }
 
+/**
+ * Generate random base64 id string.
+ * The default length is 22 which is 132-bits so almost the same as a GUID but as base64 (the previous default was 5)
+ * @param maxLength - Optional value to specify the length of the id to be generated, defaults to 22
+ */
+export function newId(maxLength = 22): string {
+    const base64chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+    // Start with an initial random number, consuming the value in reverse byte order
+    let number = random32() >>> 0;  // Make sure it's a +ve number
+    let chars = 0;
+    let result = strEmpty;
+    while (result.length < maxLength) {
+        chars ++;
+        result += base64chars.charAt(number & 0x3F);
+        number >>>= 6;              // Zero fill with right shift
+        if (chars === 5) {
+            // 5 base64 characters === 30 bits so we don't have enough bits for another base64 char
+            // So add on another 30 bits and make sure it's +ve
+            number = (((random32() << 2) & 0xFFFFFFFF) | (number & 0x03)) >>> 0;
+            chars = 0;      // We need to reset the number every 5 chars (30 bits)
+        }
+    }
+
+    return result;
+}
+

package/src/JavaScriptSDK/TelemetryHelpers.ts

@@ -3,16 +3,28 @@
 "use strict";
 
 import { IPlugin, ITelemetryPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
-import { _InternalLogMessage } from "./DiagnosticLogger";
-import { _InternalMessageId } from "../JavaScriptSDK.Enums/LoggingEnums";
-import { ProcessTelemetryContext } from "./ProcessTelemetryContext";
+import { IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
 import { ITelemetryPluginChain } from "../JavaScriptSDK.Interfaces/ITelemetryPluginChain";
 import { arrForEach, isFunction } from "./HelperFuncs";
+import { strCore, strDoTeardown, strIsInitialized, strPriority, strProcessTelemetry, strSetNextPlugin, strTeardown } from "./InternalConstants";
+import { createElmNodeData } from "./DataCacheHelper";
+import { IAppInsightsCore } from "../JavaScriptSDK.Interfaces/IAppInsightsCore";
+import { IUnloadableComponent } from "../JavaScriptSDK.Interfaces/IUnloadableComponent";
+import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
 
-let processTelemetry = "processTelemetry";
-let priority = "priority";
-let setNextPlugin = "setNextPlugin";
-let isInitialized = "isInitialized";
+const strDoUnload = "_doUnload";
+export interface IPluginState {
+    core?: IAppInsightsCore;
+    isInitialized?: boolean;
+    tearDown?: boolean;
+    disabled?: boolean;
+}
+
+const pluginStateData = createElmNodeData("plugin");
+
+export function _getPluginState(plugin: IPlugin): IPluginState {
+    return pluginStateData.get<IPluginState>(plugin, "state", {}, true)
+}
 
 /**
  * Initialize the queue of plugins
@@ -21,23 +33,32 @@ let isInitialized = "isInitialized";
  * @param core THe current core instance
  * @param extensions The extensions
  */
-export function initializePlugins(processContext:ProcessTelemetryContext, extensions: IPlugin[]) {
+export function initializePlugins(processContext: IProcessTelemetryContext, extensions: IPlugin[]) {
 
     // Set the next plugin and identified the uninitialized plugins
-    let initPlugins:ITelemetryPlugin[] = [];
-    let lastPlugin:ITelemetryPlugin = null;
-    let proxy:ITelemetryPluginChain = processContext.getNext();
+    let initPlugins: ITelemetryPlugin[] = [];
+    let lastPlugin: ITelemetryPlugin = null;
+    let proxy: ITelemetryPluginChain = processContext.getNext();
+    let pluginState: IPluginState;
     while (proxy) {
         let thePlugin = proxy.getPlugin();
         if (thePlugin) {
             if (lastPlugin &&
-                    isFunction(lastPlugin[setNextPlugin]) &&
-                    isFunction(thePlugin[processTelemetry])) {
+                    isFunction(lastPlugin[strSetNextPlugin]) &&
+                    isFunction(thePlugin[strProcessTelemetry])) {
                 // Set this plugin as the next for the previous one
-                lastPlugin[setNextPlugin](thePlugin);
+                lastPlugin[strSetNextPlugin](thePlugin);
+            }
+
+            let isInitialized = false;
+            if (isFunction(thePlugin[strIsInitialized])) {
+                isInitialized = thePlugin[strIsInitialized]();
+            } else {
+                pluginState = _getPluginState(thePlugin);
+                isInitialized = pluginState[strIsInitialized];
             }
 
-            if (!isFunction(thePlugin[isInitialized]) || !thePlugin[isInitialized]()) {
+            if (!isInitialized) {
                 initPlugins.push(thePlugin);
             }
 
@@ -46,23 +67,35 @@ export function initializePlugins(processContext:ProcessTelemetryContext, extens
         }
     }
 
-    // Now initiatilize the plugins
+    // Now initialize the plugins
     arrForEach(initPlugins, thePlugin => {
+        let core = processContext.core();
+
         thePlugin.initialize(
             processContext.getCfg(),
-            processContext.core(),
+            core,
             extensions,
             processContext.getNext());
+
+        pluginState = _getPluginState(thePlugin);
+
+        // Only add the core to the state if the plugin didn't set it (doesn't extent from BaseTelemetryPlugin)
+        if (!thePlugin[strCore] && !pluginState[strCore]) {
+            pluginState[strCore] = core;
+        }
+
+        pluginState[strIsInitialized] = true;
+        delete pluginState[strTeardown];
     });
 }
 
-export function sortPlugins(plugins:IPlugin[]) {
+export function sortPlugins<T = IPlugin>(plugins:T[]) {
     // Sort by priority
     return plugins.sort((extA, extB) => {
         let result = 0;
-        let bHasProcess = isFunction(extB[processTelemetry]);
-        if (isFunction(extA[processTelemetry])) {
-            result = bHasProcess ? extA[priority] - extB[priority] : 1;
+        let bHasProcess = isFunction(extB[strProcessTelemetry]);
+        if (isFunction(extA[strProcessTelemetry])) {
+            result = bHasProcess ? extA[strPriority] - extB[strPriority] : 1;
         } else if (bHasProcess) {
             result = -1;
         }
@@ -70,4 +103,33 @@ export function sortPlugins(plugins:IPlugin[]) {
         return result;
     });
     // sort complete
+}
+
+/**
+ * Teardown / Unload helper to perform teardown/unloading operations for the provided components synchronously or asynchronously, this will call any
+ * _doTeardown() or _doUnload() functions on the provided components to allow them to finish removal.
+ * @param components - The components you want to unload
+ * @param unloadCtx - This is the context that should be used during unloading.
+ * @param unloadState - The details / state of the unload process, it holds details like whether it should be unloaded synchronously or asynchronously and the reason for the unload.
+ * @param asyncCallback - An optional callback that the plugin must call if it returns true to inform the caller that it has completed any async unload/teardown operations.
+ * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
+ */
+export function unloadComponents(components: any | IUnloadableComponent[], unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState, asyncCallback?: () => void): void | boolean {
+    let idx = 0;
+
+    function _doUnload(): void | boolean {
+        while (idx < components.length) {
+            let component = components[idx++];
+            if (component) {
+                let func = component[strDoUnload] || component[strDoTeardown];
+                if (isFunction(func)) {
+                    if (func.call(component, unloadCtx, unloadState, _doUnload) === true) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+
+    return _doUnload();
 }

package/src/JavaScriptSDK/TelemetryInitializerPlugin.ts

@@ -0,0 +1,111 @@
+// // Copyright (c) Microsoft Corporation. All rights reserved.
+// // Licensed under the MIT License.
+
+import dynamicProto from "@microsoft/dynamicproto-js";
+import { eLoggingSeverity, _eInternalMessageId } from "../JavaScriptSDK.Enums/LoggingEnums";
+import { IProcessTelemetryContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { ITelemetryInitializerContainer, ITelemetryInitializerHandler, TelemetryInitializerFunction } from "../JavaScriptSDK.Interfaces/ITelemetryInitializers";
+import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
+import { BaseTelemetryPlugin } from "./BaseTelemetryPlugin";
+import { _throwInternal } from "./DiagnosticLogger";
+import { dumpObj } from "./EnvUtils";
+import { arrForEach, getExceptionName } from "./HelperFuncs";
+import { strDoTeardown } from "./InternalConstants";
+
+interface _IInternalTelemetryInitializerHandler {
+    id: number;
+    fn: TelemetryInitializerFunction;
+}
+
+export class TelemetryInitializerPlugin extends BaseTelemetryPlugin implements ITelemetryInitializerContainer {
+
+    public identifier: string = "TelemetryInitializerPlugin";
+    priority: number = 199;
+
+    constructor() {
+        super();
+
+        // NOTE!: DON'T set default values here, instead set them in the _initDefaults() function as it is also called during teardown()
+        let _id: number;
+        let _initializers: _IInternalTelemetryInitializerHandler[];
+
+        _initDefaults();
+
+        dynamicProto(TelemetryInitializerPlugin, this, (_self, _base) => {
+
+            _self.addTelemetryInitializer = (telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler => {
+                let theInitializer = {
+                    id: _id++,
+                    fn: telemetryInitializer
+                };
+
+                _initializers.push(theInitializer);
+
+                let handler: ITelemetryInitializerHandler = {
+                    remove: () => {
+                        arrForEach(_initializers, (initializer, idx) => {
+                            if (initializer.id === theInitializer.id) {
+                                _initializers.splice(idx, 1);
+                                return -1;
+                            }
+                        });
+                    }
+                }
+    
+                return handler;
+            }
+
+            _self.processTelemetry = (item: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void => {
+                var doNotSendItem = false;
+                var telemetryInitializersCount = _initializers.length;
+                for (var i = 0; i < telemetryInitializersCount; ++i) {
+                    var telemetryInitializer = _initializers[i];
+                    if (telemetryInitializer) {
+                        try {
+                            if (telemetryInitializer.fn.apply(null, [item]) === false) {
+                                doNotSendItem = true;
+                                break;
+                            }
+                        } catch (e) {
+                            // log error but dont stop executing rest of the telemetry initializers
+                            // doNotSendItem = true;
+                            _throwInternal(
+                                itemCtx.diagLog(),
+                                eLoggingSeverity.CRITICAL,
+                                _eInternalMessageId.TelemetryInitializerFailed,
+                                "One of telemetry initializers failed, telemetry item will not be sent: " + getExceptionName(e),
+                                { exception: dumpObj(e) }, true);
+                        }
+                    }
+                }
+
+                if (!doNotSendItem) {
+                    _self.processNext(item, itemCtx);
+                }
+            };
+
+            _self[strDoTeardown] = () => {
+                _initDefaults();
+            };
+        });
+
+        function _initDefaults() {
+            _id = 0;
+            _initializers = [];
+        }
+    }
+
+    /**
+     * Add a telemetry processor to decorate or drop telemetry events.
+     * @param telemetryInitializer - The Telemetry Initializer function
+     * @returns - A ITelemetryInitializerHandler to enable the initializer to be removed
+     */
+    public addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+        return null;
+    }
+
+    public processTelemetry(env: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+    }
+}

package/src/JavaScriptSDK/UnloadHandlerContainer.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { eLoggingSeverity, _eInternalMessageId } from "../JavaScriptSDK.Enums/LoggingEnums";
+import { IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
+import { _throwInternal } from "./DiagnosticLogger";
+import { dumpObj } from "./EnvUtils";
+import { arrForEach } from "./HelperFuncs";
+
+export type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+
+export interface IUnloadHandlerContainer {
+    add: (handler: UnloadHandler) => void;
+    run: (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void
+}
+
+export function createUnloadHandlerContainer() {
+    let handlers: UnloadHandler[] = [];
+
+    function _addHandler(handler: UnloadHandler) {
+        if (handler) {
+            handlers.push(handler);
+        }
+    }
+
+    function _runHandlers(unloadCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) {
+        arrForEach(handlers, (handler) => {
+            try {
+                handler(unloadCtx, unloadState);
+            } catch (e) {
+                _throwInternal(
+                    unloadCtx.diagLog(),
+                    eLoggingSeverity.WARNING,
+                    _eInternalMessageId.PluginException,
+                    "Unexpected error calling unload handler - " + dumpObj(e));
+            }
+        });
+        handlers = [];
+    }
+
+    return {
+        add: _addHandler,
+        run: _runHandlers
+    }
+}

package/src/JavaScriptSDK.Enums/EnumHelperFuncs.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { objForEachKey, deepFreeze } from "../JavaScriptSDK/HelperFuncs";
+
+export declare type EnumValue<E = any> = { readonly [key in keyof E]: E[key] };
+export declare type EnumMap<E = any, I = E> = { readonly [key in keyof E extends string ? keyof E : never]: key extends string ? key : keyof E } & I;
+
+/**
+ * Create an enum style object which has both the key => value and value => key mappings
+ * @param values - The values to populate on the new object
+ * @returns
+ */
+export function createEnumStyle<E>(values: { [key in keyof E]: E[keyof E] }): EnumValue<E> {
+    let enumClass: any = {};
+    objForEachKey(values, (field, value) => {
+        enumClass[field] = value;
+        enumClass[value] = field;
+    });
+
+    return deepFreeze(enumClass);
+}
+
+/**
+ * Create a 2 index map that maps an enum's key as both the key and value, X["key"] => "key" and X[0] => "keyof 0".
+ * @param values - The values to populate on the new object
+ * @returns
+ */
+export function createEnumMap<E, I = keyof E>(values: { [key in keyof E]: E[keyof E] }): EnumMap<E, I> {
+    let mapClass: any = {};
+    objForEachKey(values, (field, value) => {
+        mapClass[field] = field;
+        mapClass[value] = field;
+    });
+
+    return deepFreeze(mapClass);
+}
+
+/**
+ * Create a 2 index map that maps an enum's key and value to the defined map value, X["key"] => mapValue and X[0] => mapValue.
+ * Generic values
+ * - E = the const enum type (typeof eRequestHeaders);
+ * - V = Identifies the valid values for the keys, this should include both the enum numeric and string key of the type. The
+ * resulting "Value" of each entry identifies the valid values withing the assignments.
+ * @param values - The values to populate on the new object
+ * @returns
+ */
+export function createValueMap<E, V = E>(values: { [key in keyof E]: [ eValue: E[keyof E], mapValue: V[keyof V]] }): V {
+    let mapClass: any = {};
+    objForEachKey(values, (field, value) => {
+        mapClass[field] = value[1];
+        mapClass[value[0]] = value[1];
+    });
+
+    return deepFreeze(mapClass);
+}

package/src/JavaScriptSDK.Enums/EventsDiscardedReason.ts

@@ -1,31 +1,71 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
+
+import { createEnumStyle } from "../JavaScriptSDK.Enums/EnumHelperFuncs";
+
+/**
+ * The eEventsDiscardedReason enumeration contains a set of values that specify the reason for discarding an event.
+ */
+export const enum eEventsDiscardedReason {
+    /**
+     * Unknown.
+     */
+     Unknown = 0,
+     /**
+      * Status set to non-retryable.
+      */
+     NonRetryableStatus = 1,
+     /**
+      * The event is invalid.
+      */
+     InvalidEvent = 2,
+     /**
+      * The size of the event is too large.
+      */
+     SizeLimitExceeded = 3,
+     /**
+      * The server is not accepting events from this instrumentation key.
+      */
+     KillSwitch = 4,
+     /**
+      * The event queue is full.
+      */
+     QueueFull = 5
+ }
+
 /**
  * The EventsDiscardedReason enumeration contains a set of values that specify the reason for discarding an event.
  */
-export const EventsDiscardedReason = {
+export const EventsDiscardedReason = createEnumStyle<typeof eEventsDiscardedReason>({
     /**
      * Unknown.
      */
-    Unknown: 0,
+    Unknown: eEventsDiscardedReason.Unknown,
+
     /**
      * Status set to non-retryable.
      */
-    NonRetryableStatus: 1,
+    NonRetryableStatus: eEventsDiscardedReason.NonRetryableStatus,
+
     /**
      * The event is invalid.
      */
-    InvalidEvent: 2,
+    InvalidEvent: eEventsDiscardedReason.InvalidEvent,
+
     /**
      * The size of the event is too large.
      */
-    SizeLimitExceeded: 3,
+    SizeLimitExceeded: eEventsDiscardedReason.SizeLimitExceeded,
+
     /**
      * The server is not accepting events from this instrumentation key.
      */
-    KillSwitch: 4,
+    KillSwitch: eEventsDiscardedReason.KillSwitch,
+
     /**
      * The event queue is full.
      */
-    QueueFull: 5
-};
+    QueueFull: eEventsDiscardedReason.QueueFull
+});
+
+export type EventsDiscardedReason = number | eEventsDiscardedReason;