@microsoft/1ds-post-js 3.1.9 → 3.2.0

package/README.md

@@ -15,7 +15,7 @@ ms.reviewedBy: ramthi
 
 ## npm
 
-Package available [here](https://msasg.visualstudio.com/Shared%20Data/_packaging?_a=package&feed=1DS-SDK&package=%40microsoft%2F1ds-post-js&protocolType=Npm).
+Packages available [here](https://msasg.visualstudio.com/Shared%20Data/_artifacts/feed/1DS-SDK/Npm/%40microsoft%2F1ds-post-js/3.2.0/versions).
 
 ## Basic Usage
 
@@ -65,6 +65,13 @@ appInsightsCore.initialize(coreConfig, []);
 | stringifyObjects | [Optional] During serialization, when an object is identified should the object serialized by true => JSON.stringify(theObject); otherwise theObject.toString(). Defaults to false. | boolean
 | enableCompoundKey | [Optional] Enables support for objects with compound keys which indirectly represent an object eg. event: { "somedata.embeddedvalue": 123 }  where the "key" of the object contains a "." as part of it's name.  Defaults to false. | boolean
 | disableOptimizeObj | [Optional] Switch to disable the v8 `optimizeObject()` calls used to provide better serialization performance. Defaults to false. | boolean
+| transports | [Optional] Either an array or single value identifying the requested `TransportType` (const enum) type that should be used. This is used during initialization to identify the requested send transport, it will be ignored if a httpXHROverride is provided. | number or number[]
+| avoidOptions<br/><sub><i>(Since 3.1.10+)</i></sub><br /><sub>Default: false (Since 3.2.0)<br />Previously true</sub> | [Optional] Avoid adding request headers to the outgoing request that would cause a pre-flight (OPTIONS) request to be sent for each request. | boolean
+| xhrTimeout<br/><sub><i>(Since 3.1.11+)</i></sub>  | [Optional] Specify a timeout (in ms) to apply to requests when sending requests using XHR or fetch() requests only, does not affect sendBeacon() or XDR (XDomainRequest) usage. Defaults to undefined and therefore the runtime defaults (normally zero for browser environments) | number
+| disableXhrSync<br/><sub><i>(Since 3.1.11+)</i></sub> | [Optional] When using [Xhr](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) for sending requests disable sending as synchronous during unload or synchronous flush. __You should enable this feature for IE (when there is no sendBeacon() or fetch (with keep-alive) support) and you have clients that end up blocking the UI during page unloading__. <span style="color:red">This will cause ALL XHR requests to be sent asynchronously which during page unload may result in the lose of telemetry</span>. This does not affect any other request type (fetch(), sendBeacon() or XDR (XDomainRequest)) | boolean<br/>Default: undefined
+| alwaysUseXhrOverride<br /><sub><i>(Since 3.1.11+)</i></sub> | [Optional] By default during unload (or when you specify to use sendBeacon() or sync fetch (with keep-alive) for an event) the SDK ignores any provided httpXhrOverride and attempts to use sendBeacon() or fetch(with keep-alive) when they are available. When this configuration option is true any provided httpXhrOverride will always be used, so any provided httpXhrOverride will also need to "handle" the synchronous unload scenario. | boolean<br /> Default: false
+| maxEventRetryAttempts<br /><sub><i>(Since 3.1.11+)</i></sub> | [Optional] Identifies the number of times any single event will be retried if it receives a failed (retirable) response, this  causes the event to be internally "requeued" and resent in the next batch. As each normal batched send request is retried at least once before starting to increase the internal backoff send interval, normally batched events will generally be attempted the next nearest even number of times. This means that the total number of actual send attempts will almost always be even (setting to 5 will cause 6 requests), unless using manual synchronous flushing (calling flush(false)) which is not subject to request level retry attempts. | number<br/>Default: 6
+| maxUnloadEventRetryAttempts<br /><sub><i>(Since 3.1.11+)</i></sub> | [Optional] Identifies the number of times any single event will be retried if it receives a failed (retriable) response as part of processing / flushing events once a page unload state has been detected, this causes the event to be internally "requeued" and resent in the next batch, which during page unload. Unlike the normal batching process, send requests are never retried, so the value listed here is always the maximum number of attempts for any single event.<br/>Notes: The SDK by default will use the sendBeacon() API if it exists which is treated as a fire and forget successful response, so for environments that support or supply this API the events won't be retried (because they will be deeded to be successfully sent). When an environment (IE) doesn't support sendBeacon(), this will cause multiple synchronous (by default) XMLHttpRequests to be sent, which will block the UI until a response is received. You can disable ALL synchronous XHR requests by setting the 'disableXhrSync' configuration setting and/or changing this value to 0 or 1. | number<br/>Default: 2
 
 ### [IXHROverride](https://1dsdocs.azurewebsites.net/api/webSDK/chnl/post/3.0/f/interfaces/ixhroverride.html)
 
@@ -79,6 +86,8 @@ interface IPayloadData {
     urlString: string;
     data: Uint8Array | string;
     headers?: { [name: string]: string };
+    timeout?: number;            // Optional value supplied by the xhrTimeout configuration option
+    disableXhrSync?: boolean;    // Optional value supplied by the disableXhrSync configuration option
 }
 
 type PayloadPreprocessorFunction = (payload: IPayloadData, callback: (modifiedBuffer: IPayloadData) => void) => void;
@@ -101,15 +110,39 @@ const gzipFn: PayloadPreprocessorFunction = (payload: IPayloadData, cb) => {
 }
 ```
 
-### XHR Override sample using node.js Https module
+### XHR Override
 
-```js
+```ts
+/**
+ * SendPOSTFunction type defines how an HTTP POST request is sent to an ingestion server
+ * @param payload - The payload object that should be sent, contains the url, bytes/string and headers for the request
+ * @param oncomplete - The function to call once the request has completed whether a success, failure or timeout
+ * @param sync - A boolean flag indicating whether the request should be sent as a synchronous request.
+ */
+export type SendPOSTFunction = (payload: IPayloadData, oncomplete: (status: number, headers: { [headerName: string]: string; }, response?: string) => void, sync?: boolean) => void;
+
+/**
+ * The IXHROverride interface overrides the way HTTP requests are sent.
+ */
+export interface IXHROverride {
+    /**
+     * This method sends data to the specified URI using a POST request. If sync is true,
+     * then the request is sent synchronously. The <i>oncomplete</i> function should always be called after the request is
+     * completed (either successfully or timed out or failed due to errors).
+     */
+    sendPOST: SendPOSTFunction;
+}
+```
+
+#### Example using node.js Https module
+
+```ts
 const oneDs = require('@microsoft/1ds-analytics-js');
 const https = require('https');
 
 // XHR override using node.js https module
 var customHttpXHROverride= {
-  sendPOST: (payload, oncomplete) => {
+  sendPOST: (payload: IPayloadData, oncomplete) => {
     var options = {
       method: 'POST',
       headers: {
@@ -127,12 +160,98 @@ var customHttpXHROverride= {
     req.end();
   }
 };
-var postChannelConfig = {
+
+var postChannelConfig: IChannelConfiguration = {
     httpXHROverride: customHttpXHROverride
 };
 
 ```
 
+#### Example always using fetch API
+
+This example is using the [fetch() API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch) for all requests, include synchronous requests and assumes that the browser environment supports the (currently) experimental keepalive option (for chromium).
+
+```ts
+function fetchHttpXHROverride(payload: IPayloadData, onComplete: OnCompleteCallback, sync?: boolean) {
+  let ignoreResponse = false;
+  let responseHandled = false;
+  let requestInit: RequestInit = {
+    body: payload.data,
+    method: Method,
+    headers: payload.headers,
+    [DisabledPropertyName]: true,
+    credentials: "include"
+  };
+
+  if (sync) {
+    // You should validate whether the runtime environment supports this flag and if not you should use either sendBeacon or a synchronous XHR request
+    requestInit.keepalive = true;
+    if (sync) {
+      // As a sync request (during unload), it is unlikely that we will get a chance to process the response so
+      // just like beacon send assume that the events have been accepted and processed
+      ignoreResponse = true;
+    }
+  }
+
+  fetch(payload.urlString, requestInit).then((response) => {
+    let headerMap = {};
+    let responseText = "";
+    if (response.headers) {
+      response.headers.forEach((value: string, name: string) => {
+        headerMap[name] = value;
+      });
+    }
+ 
+    if (response.body) {
+      response.text().then(function(text) {
+        responseText = text;
+      });
+    }
+
+    if (!responseHandled) {
+      responseHandled = true;
+      onComplete(response.status, headerMap, responseText);
+    }
+  }).catch((error) => {
+    // In case there is an error in the request. Set the status to 0
+    // so that the events can be retried later.
+    if (!responseHandled) {
+      responseHandled = true;
+      onComplete(0, {});
+    }
+  });
+
+  // If we are treating this as a synchronous (keepAlive) we need to assume success during unload processing
+  if (ignoreResponse && !responseHandled) {
+    responseHandled = true;
+    onComplete(200, {});
+  }
+
+  // Simulate timeout if a timeout was supplied
+  if (!responseHandled && payload.timeout > 0) {
+    setTimeout(() => {
+      if (!responseHandled) {
+        // Assume a 500 response (which will cause a retry)
+        responseHandled = true;
+        onComplete(500, {});
+      }
+    }, payload.timeout);                    
+  }
+}
+
+let postChannelConfig: IChannelConfiguration = {
+  httpXHROverride: fetchHttpXHROverride,
+
+  // Enable this flag to cause the SDK to ALWAYS call your override otherwise during page unload the SDK will using it's internal
+  // sendPost implementation using sendBeacon() or fetch (with keepalive support) whichever is the first supported
+  //alwaysUseXhrOverride: true,
+
+  // If you want to specify a timeout this value is passed on the payload object as `payload.timeout`
+  //xhrTimeout: 20000,
+};
+
+```
+
 ## IValueSanitizer Paths / Fields which are excluded
 
 To ensure that the service can continue to accept events that are sent from the SDK, some paths and fields are explicitly blocked and are never processed