docs: document proxy behavior and verify with a test (#221)

README.md

@@ -247,7 +247,6 @@ main();
 The parameters for the JWT auth client including how to use it with a `.pem` file are explained in [samples/jwt.js](samples/jwt.js).
 
 #### Loading credentials from environment variables
-
 Instead of loading credentials from a key file, you can also provide them using an environment variable and the `GoogleAuth.fromJSON()` method.  This is particularly convenient for systems that deploy directly from source control (Heroku, App Engine, etc).
 
 Start by exporting your credentials:
@@ -291,6 +290,13 @@ async function main() {
 
 main().catch(console.error);
 ```
+#### Using a Proxy
+You can use the following environment variables to proxy HTTP and HTTPS requests:
+
+- HTTP_PROXY / http_proxy
+- HTTPS_PROXY / https_proxy
+
+When HTTP_PROXY / http_proxy are set, they will be used to proxy non-SSL requests that do not have an explicit proxy configuration option present. Similarly, HTTPS_PROXY / https_proxy will be respected for SSL requests that do not have an explicit proxy configuration option. It is valid to define a proxy in one of the environment variables, but then override it for a specific request, using the proxy configuration option.
 
 ### Questions/problems?
 

test/test.transporters.ts

@@ -15,7 +15,7 @@
  */
 
 import * as assert from 'assert';
-import {AxiosRequestConfig} from 'axios';
+import {AxiosProxyConfig, AxiosRequestConfig} from 'axios';
 import * as nock from 'nock';
 
 import {DefaultTransporter, RequestError} from '../src/transporters';
@@ -99,3 +99,52 @@ describe('Transporters', () => {
         });
   });
 });
+
+describe('transporter proxy', () => {
+  let savedEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    savedEnv = process.env;
+    process.env = {};
+  });
+
+  afterEach(() => {
+    process.env = savedEnv;
+  });
+
+  it('should use the http proxy if one is configured', async () => {
+    process.env['http_proxy'] = 'http://han:solo@proxy-server:1234';
+    const transporter = new DefaultTransporter();
+    nock('http://proxy-server:1234')
+        .get('http://example.com/fake', undefined, {
+          reqheaders: {
+            'host': 'example.com',
+            'accept': /.*/g,
+            'user-agent': /google-api-nodejs-client\/.*/g,
+            'proxy-authorization': /.*/g
+          }
+        })
+        .reply(200);
+    const url = 'http://example.com/fake';
+    const result = await transporter.request({url});
+    assert.equal(result.status, 200);
+  });
+
+  it('should use the https proxy if one is configured', async () => {
+    process.env['https_proxy'] = 'https://han:solo@proxy-server:1234';
+    const transporter = new DefaultTransporter();
+    nock('https://proxy-server:1234')
+        .get('https://example.com/fake', undefined, {
+          reqheaders: {
+            'host': 'example.com',
+            'accept': /.*/g,
+            'user-agent': /google-api-nodejs-client\/.*/g,
+            'proxy-authorization': /.*/g
+          }
+        })
+        .reply(200);
+    const url = 'https://example.com/fake';
+    const result = await transporter.request({url});
+    assert.equal(result.status, 200);
+  });
+});