feat: add proxy support (#14)

Author: shazron

.gitignore

@@ -5,3 +5,4 @@ launch.json
 package-lock.json
 /node_modules/
 junit.xml
+test-report.html

README.md

@@ -1,5 +1,5 @@
 <!--
-Copyright 2019 Adobe. All rights reserved.
+Copyright 2021 Adobe. All rights reserved.
 This file is licensed to you under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License. You may obtain a copy
 of the License at http://www.apache.org/licenses/LICENSE-2.0
@@ -10,12 +10,20 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 -->
 
+<!--
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+DO NOT update README.md, it is generated.
+Modify 'docs/readme_template.md', then run `npm run generate-docs`.
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+-->
+
 [![Version](https://img.shields.io/npm/v/@adobe/aio-lib-core-networking.svg)](https://npmjs.org/package/@adobe/aio-lib-core-networking)
 [![Downloads/week](https://img.shields.io/npm/dw/@adobe/aio-lib-core-networking.svg)](https://npmjs.org/package/@adobe/aio-lib-core-networking)
 [![Node.js CI](https://github.com/adobe/aio-lib-core-networking/actions/workflows/node.js.yml/badge.svg)](https://github.com/adobe/aio-lib-core-networking/actions/workflows/node.js.yml)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) 
 [![Codecov Coverage](https://img.shields.io/codecov/c/github/adobe/aio-lib-core-networking/master.svg?style=flat-square)](https://codecov.io/gh/adobe/aio-lib-core-networking/)
 
+
 # Adobe I/O Core Networking Lib
 
 ### Installing
@@ -28,15 +36,17 @@ $ npm install @adobe/aio-lib-core-networking
 1) Initialize the SDK
 
 ```javascript
-const fetchRetry = require('@adobe/aio-lib-core-networking')
-
+const { HttpExponentialBackoff, createFetch } = require('@adobe/aio-lib-core-networking')
+const fetchRetry = new HttpExponentialBackoff()
+const proxyFetch = createFetch()
 ```
 
 2) Call methods using the initialized SDK
 
 ```javascript
 
-const fetchRetry = require('@adobe/aio-lib-core-networking')
+const { HttpExponentialBackoff, createFetch } = require('@adobe/aio-lib-core-networking')
+const fetchRetry = new HttpExponentialBackoff()
 async function sdkTest() {
 
   return new Promise((resolve, reject) => {
@@ -54,44 +64,154 @@ async function sdkTest() {
   }) 
 }
 
-```
-
-<a name="module_@adobe/aio-lib-core-networking"></a>
-
-## @adobe/aio-lib-core-networking
-
-* [@adobe/aio-lib-core-networking](#module_@adobe/aio-lib-core-networking)
-    * [~HttpExponentialBackoff](#module_@adobe/aio-lib-core-networking..HttpExponentialBackoff)
-        * [.exponentialBackoff(url, requestOptions, retryOptions, retryOn, retryDelay)](#module_@adobe/aio-lib-core-networking..HttpExponentialBackoff+exponentialBackoff) ⇒ <code>Promise.&lt;Response&gt;</code>
+let proxyFetch 
+// this will get the proxy settings from the the HTTP_PROXY or HTTPS_PROXY environment variables, if set
+proxyFetch = createFetch()
 
-<a name="module_@adobe/aio-lib-core-networking..HttpExponentialBackoff"></a>
+// this will use the passed in proxy settings. Embed basic auth in the url, if required
+proxyFetch = createFetch({ proxyUrl: 'http://my.proxy:8080' })
 
-### Working of HttpExponentialBackoff
+// if the proxy settings are not passed in, and not available in the HTTP_PROXY or HTTPS_PROXY environment variables, it falls back to a simple fetch
+const simpleFetch = createFetch()
+```
 
-![image not available](docs/sequenceDiagram.jpeg?s=50)
+## Classes
 
-### @adobe/aio-lib-core-networking~HttpExponentialBackoff
+<dl>
+<dt><a href="#HttpExponentialBackoff">HttpExponentialBackoff</a></dt>
+<dd><p>This class provides methods to implement fetch with retries.
+The retries use exponential backoff strategy
+with defaults set to max of 3 retries and initial Delay as 100ms</p>
+</dd>
+<dt><a href="#ProxyFetch">ProxyFetch</a></dt>
+<dd><p>This provides a wrapper for fetch that facilitates proxy auth authorization.</p>
+</dd>
+</dl>
+
+## Functions
+
+<dl>
+<dt><a href="#createFetch">createFetch([proxyAuthOptions])</a> ⇒ <code>function</code></dt>
+<dd><p>Return the appropriate Fetch function depending on proxy settings.</p>
+</dd>
+</dl>
+
+## Typedefs
+
+<dl>
+<dt><a href="#RetryOptions">RetryOptions</a> : <code>object</code></dt>
+<dd><p>Fetch Retry Options</p>
+</dd>
+<dt><a href="#ProxyAuthOptions">ProxyAuthOptions</a> : <code>object</code></dt>
+<dd><p>Proxy Auth Options</p>
+</dd>
+</dl>
+
+<a name="HttpExponentialBackoff"></a>
+
+## HttpExponentialBackoff
 This class provides methods to implement fetch with retries.
 The retries use exponential backoff strategy
 with defaults set to max of 3 retries and initial Delay as 100ms
 
-**Kind**: inner class of [<code>@adobe/aio-lib-core-networking</code>](#module_@adobe/aio-lib-core-networking)  
-<a name="module_@adobe/aio-lib-core-networking..HttpExponentialBackoff+exponentialBackoff"></a>
+**Kind**: global class  
+<a name="HttpExponentialBackoff+exponentialBackoff"></a>
 
-#### httpExponentialBackoff.exponentialBackoff(url, requestOptions, retryOptions, retryOn, retryDelay) ⇒ <code>Promise.&lt;Response&gt;</code>
+### httpExponentialBackoff.exponentialBackoff(url, requestOptions, [retryOptions], [retryOn], [retryDelay]) ⇒ <code>Promise.&lt;Response&gt;</code>
 This function will retry connecting to a url end-point, with
 exponential backoff. Returns a Promise.
 
-**Kind**: instance method of [<code>HttpExponentialBackoff</code>](#module_@adobe/aio-lib-core-networking..HttpExponentialBackoff)  
+**Kind**: instance method of [<code>HttpExponentialBackoff</code>](#HttpExponentialBackoff)  
 **Returns**: <code>Promise.&lt;Response&gt;</code> - Promise object representing the http response  
 
 | Param | Type | Description |
 | --- | --- | --- |
 | url | <code>string</code> | endpoint url |
-| requestOptions | <code>object</code> | request options which includes the HTTP method, headers, timeout, etc. |
-| retryOptions | <code>object</code> | retry options with options being maxRetries and initialDelayInMillis |
-| retryOn | <code>function</code> \| <code>Array</code> | Optional Function or Array. If provided, will be used instead of the default |
-| retryDelay | <code>function</code> \| <code>number</code> | Optional Function or number. If provided, will be used instead of the default |
+| requestOptions | <code>object</code> \| <code>Request</code> | request options |
+| [retryOptions] | [<code>RetryOptions</code>](#RetryOptions) | (optional) retry options |
+| [retryOn] | <code>function</code> \| <code>Array</code> | (optional) Function or Array. If provided, will be used instead of the default |
+| [retryDelay] | <code>function</code> \| <code>number</code> | (optional) Function or number. If provided, will be used instead of the default |
+
+<a name="ProxyFetch"></a>
+
+## ProxyFetch
+This provides a wrapper for fetch that facilitates proxy auth authorization.
+
+**Kind**: global class  
+
+* [ProxyFetch](#ProxyFetch)
+    * [new ProxyFetch(authOptions)](#new_ProxyFetch_new)
+    * [.proxyAgent()](#ProxyFetch+proxyAgent) ⇒ <code>http.Agent</code>
+    * [.fetch(resource, options)](#ProxyFetch+fetch) ⇒ <code>Promise.&lt;Response&gt;</code>
+
+<a name="new_ProxyFetch_new"></a>
+
+### new ProxyFetch(authOptions)
+Initialize this class with Proxy auth options
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| authOptions | [<code>ProxyAuthOptions</code>](#ProxyAuthOptions) | the auth options to connect with |
+
+<a name="ProxyFetch+proxyAgent"></a>
+
+### proxyFetch.proxyAgent() ⇒ <code>http.Agent</code>
+Returns the http.Agent used for this proxy
+
+**Kind**: instance method of [<code>ProxyFetch</code>](#ProxyFetch)  
+**Returns**: <code>http.Agent</code> - a http.Agent for basic auth proxy  
+<a name="ProxyFetch+fetch"></a>
+
+### proxyFetch.fetch(resource, options) ⇒ <code>Promise.&lt;Response&gt;</code>
+Fetch function, using the configured NTLM Auth options.
+
+**Kind**: instance method of [<code>ProxyFetch</code>](#ProxyFetch)  
+**Returns**: <code>Promise.&lt;Response&gt;</code> - Promise object representing the http response  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| resource | <code>string</code> \| <code>Request</code> | the url or Request object to fetch from |
+| options | <code>object</code> | the fetch options |
+
+<a name="createFetch"></a>
+
+## createFetch([proxyAuthOptions]) ⇒ <code>function</code>
+Return the appropriate Fetch function depending on proxy settings.
+
+**Kind**: global function  
+**Returns**: <code>function</code> - the Fetch API function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [proxyAuthOptions] | [<code>ProxyAuthOptions</code>](#ProxyAuthOptions) | the proxy auth options |
+
+<a name="RetryOptions"></a>
+
+## RetryOptions : <code>object</code>
+Fetch Retry Options
+
+**Kind**: global typedef  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| maxRetries | <code>number</code> | the maximum number of retries to try (default:3) |
+| initialDelayInMillis | <code>number</code> | the initial delay in milliseconds (default:100ms) |
+| proxy | [<code>ProxyAuthOptions</code>](#ProxyAuthOptions) | the (optional) proxy auth options |
+
+<a name="ProxyAuthOptions"></a>
+
+## ProxyAuthOptions : <code>object</code>
+Proxy Auth Options
+
+**Kind**: global typedef  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| proxyUrl | <code>string</code> | the proxy's url |
+| rejectUnauthorized | <code>boolean</code> | set to false to not reject unauthorized server certs |
 
 ### Debug Logs
 

docs/readme_template.md

@@ -1,5 +1,5 @@
 <!--
-Copyright 2019 Adobe. All rights reserved.
+Copyright 2021 Adobe. All rights reserved.
 This file is licensed to you under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License. You may obtain a copy
 of the License at http://www.apache.org/licenses/LICENSE-2.0
@@ -10,13 +10,21 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 -->
 
-[![Version](https://img.shields.io/npm/v/@CNA/aio-lib-core-networking.svg)](https://npmjs.org/package/@CNA/aio-lib-core-networking)
-[![Downloads/week](https://img.shields.io/npm/dw/@CNA/aio-lib-core-networking.svg)](https://npmjs.org/package/@CNA/aio-lib-core-networking)
-[![Build Status](https://travis-ci.com/CNA/aio-lib-core-networking.svg?branch=master)](https://travis-ci.com/CNA/aio-lib-core-networking)
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Greenkeeper badge](https://badges.greenkeeper.io/CNA/aio-lib-core-networking.svg)](https://greenkeeper.io/)
-[![Codecov Coverage](https://img.shields.io/codecov/c/github/CNA/aio-lib-core-networking/master.svg?style=flat-square)](https://codecov.io/gh/CNA/aio-lib-core-networking/)
+<!--
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+DO NOT update README.md, it is generated.
+Modify 'docs/readme_template.md', then run `npm run generate-docs`.
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+-->
+
+[![Version](https://img.shields.io/npm/v/@adobe/aio-lib-core-networking.svg)](https://npmjs.org/package/@adobe/aio-lib-core-networking)
+[![Downloads/week](https://img.shields.io/npm/dw/@adobe/aio-lib-core-networking.svg)](https://npmjs.org/package/@adobe/aio-lib-core-networking)
+[![Node.js CI](https://github.com/adobe/aio-lib-core-networking/actions/workflows/node.js.yml/badge.svg)](https://github.com/adobe/aio-lib-core-networking/actions/workflows/node.js.yml)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) 
+[![Codecov Coverage](https://img.shields.io/codecov/c/github/adobe/aio-lib-core-networking/master.svg?style=flat-square)](https://codecov.io/gh/adobe/aio-lib-core-networking/)
 
-# Adobe I/O ??? Lib
+
+# Adobe I/O Core Networking Lib
 
 ### Installing
 
@@ -28,39 +36,48 @@ $ npm install @adobe/aio-lib-core-networking
 1) Initialize the SDK
 
 ```javascript
-const sdk = require('@adobe/aio-lib-core-networking')
-
-async function sdkTest() {
-  //initialize sdk
-  const client = await sdk.init('<tenant>', 'x-api-key', '<valid auth token>')
-}
+const { HttpExponentialBackoff, createFetch } = require('@adobe/aio-lib-core-networking')
+const fetchRetry = new HttpExponentialBackoff()
+const proxyFetch = createFetch()
 ```
 
 2) Call methods using the initialized SDK
 
 ```javascript
-const sdk = require('@adobe/aio-lib-core-networking')
 
+const { HttpExponentialBackoff, createFetch } = require('@adobe/aio-lib-core-networking')
+const fetchRetry = new HttpExponentialBackoff()
 async function sdkTest() {
-  // initialize sdk
-  const client = await sdk.init('<tenant>', 'x-api-key', '<valid auth token>')
-
-  // call methods
-  try {
-    // get profiles by custom filters
-    const result = await client.getSomething({})
-    console.log(result)
-
-  } catch (e) {
-    console.error(e)
-  }
+
+  return new Promise((resolve, reject) => {
+    fetchRetry.exponentialBackoff(url, requestOptions, retryOptions, retryOn, retryDelay)
+    .then((response) => {
+      if (!response.ok) {
+        throw Error(reduceError(response))
+      }
+      resolve(response.json())
+    })
+    .catch(err => {
+      reject(
+        new codes.ERROR_GET_SOMETHING({ sdkDetails, messageValues: err }))
+    })
+  }) 
 }
+
+let proxyFetch 
+// this will get the proxy settings from the the HTTP_PROXY or HTTPS_PROXY environment variables, if set
+proxyFetch = createFetch()
+
+// this will use the passed in proxy settings. Embed basic auth in the url, if required
+proxyFetch = createFetch({ proxyUrl: 'http://my.proxy:8080' })
+
+// if the proxy settings are not passed in, and not available in the HTTP_PROXY or HTTPS_PROXY environment variables, it falls back to a simple fetch
+const simpleFetch = createFetch()
 ```
 
 {{>main-index~}}
 {{>all-docs~}}
 
-
 ### Debug Logs
 
 ```bash

package.json

@@ -4,14 +4,19 @@
   },
   "bundleDependencies": false,
   "dependencies": {
-    "node-fetch": "^2.6.0",
+    "@adobe/aio-lib-core-config": "^2.0.1",
     "@adobe/aio-lib-core-errors": "^3.0.0",
     "@adobe/aio-lib-core-logging": "1.1.0",
-    "fetch-retry": "^3.0.1"
+    "fetch-retry": "^3.0.1",
+    "http-proxy-agent": "^4.0.1",
+    "https-proxy-agent": "2.2.4",
+    "node-fetch": "^2.6.4",
+    "proxy-from-env": "^1.1.0"
   },
   "deprecated": false,
   "description": "Adobe I/O Lib Core Networking",
   "devDependencies": {
+    "@adobe/aio-lib-test-proxy": "^1.0.0",
     "@adobe/eslint-config-aio-lib-config": "^1.2.0",
     "babel-runtime": "^6.26.0",
     "dotenv": "^8.1.0",
@@ -24,16 +29,18 @@
     "eslint-plugin-node": "^11.0.0",
     "eslint-plugin-promise": "^4.2.1",
     "eslint-plugin-standard": "^4.0.0",
+    "fetch-mock": "^9.0.0",
     "jest": "^25.1.0",
     "jest-fetch-mock": "^3.0.1",
+    "jest-html-reporter": "^3.4.1",
     "jest-junit": "^10.0.0",
     "jest-plugin-fs": "^2.9.0",
     "jsdoc": "^3.6.3",
     "jsdoc-to-markdown": "^5.0.0",
     "openapi-schema-validator": "^3.0.3",
+    "query-string": "^7.0.1",
     "stdout-stderr": "^0.1.9",
-    "tsd-jsdoc": "^2.4.0",
-    "fetch-mock": "^9.0.0"
+    "tsd-jsdoc": "^2.4.0"
   },
   "homepage": "https://github.com/adobe/aio-lib-core-networking",
   "license": "Apache-2.0",
@@ -47,7 +54,11 @@
     "lint": "eslint src test",
     "test": "npm run lint && npm run unit-tests",
     "typings": "jsdoc -t node_modules/tsd-jsdoc/dist -r src/*.js -d .",
-    "unit-tests": "jest --config test/jest.config.js --maxWorkers=2"
+    "unit-tests": "jest --config test/jest.config.js --runInBand"
   },
-  "version": "1.0.1"
+  "version": "1.0.1",
+  "engineStrict": true,
+  "engines": {
+    "node": ">=12.0.0"
+  }
 }