global-agent 3.0.0 → 4.0.0

package/{dist/classes/Agent.js.flow → src/classes/Agent.ts}

@@ -1,14 +1,14 @@
-// @flow
-
+import type * as http from 'http';
+import type * as https from 'https';
+import net from 'net';
 import {
   serializeError,
 } from 'serialize-error';
-import {
-  boolean,
-} from 'boolean';
 import Logger from '../Logger';
 import type {
   AgentType,
+  ConnectionCallbackType,
+  ConnectionConfigurationType,
   GetUrlProxyMethodType,
   IsProxyConfiguredMethodType,
   MustUrlUseProxyMethodType,
@@ -21,46 +21,134 @@ const log = Logger.child({
 
 let requestId = 0;
 
-class Agent {
-  defaultPort: number;
+type AgentRequestOptions = {
+  host?: string,
+  path?: string,
+  port: number,
+};
+
+type HttpRequestOptions = AgentRequestOptions & Omit<http.RequestOptions, keyof AgentRequestOptions> & {
+  secureEndpoint: false,
+};
+
+type HttpsRequestOptions = AgentRequestOptions & Omit<https.RequestOptions, keyof AgentRequestOptions> & {
+  secureEndpoint: true,
+};
 
-  protocol: ProtocolType;
+type RequestOptions = HttpRequestOptions | HttpsRequestOptions;
 
-  fallbackAgent: AgentType;
+abstract class Agent {
+  public defaultPort: number;
 
-  isProxyConfigured: IsProxyConfiguredMethodType;
+  public protocol: ProtocolType;
 
-  mustUrlUseProxy: MustUrlUseProxyMethodType;
+  public fallbackAgent: AgentType;
 
-  getUrlProxy: GetUrlProxyMethodType;
+  public isProxyConfigured: IsProxyConfiguredMethodType;
 
-  socketConnectionTimeout: number;
+  public mustUrlUseProxy: MustUrlUseProxyMethodType;
 
-  constructor (
+  public getUrlProxy: GetUrlProxyMethodType;
+
+  public socketConnectionTimeout: number;
+
+  public ca: string[] | string | undefined;
+
+  public constructor (
     isProxyConfigured: IsProxyConfiguredMethodType,
     mustUrlUseProxy: MustUrlUseProxyMethodType,
     getUrlProxy: GetUrlProxyMethodType,
     fallbackAgent: AgentType,
     socketConnectionTimeout: number,
+    ca: string[] | string | undefined,
   ) {
     this.fallbackAgent = fallbackAgent;
     this.isProxyConfigured = isProxyConfigured;
     this.mustUrlUseProxy = mustUrlUseProxy;
     this.getUrlProxy = getUrlProxy;
     this.socketConnectionTimeout = socketConnectionTimeout;
+    this.ca = ca;
+  }
+
+  /**
+   * This method can be used to append new ca certificates to existing ca certificates
+   *
+   * @param {string[] | string} ca a ca certificate or an array of ca certificates
+   */
+  public addCACertificates (ca: string[] | string) {
+    if (!ca) {
+      log.error('Invalid input ca certificate');
+    } else if (this.ca) {
+      if (typeof ca === typeof this.ca) {
+        // concat valid ca certificates with the existing certificates,
+        if (typeof this.ca === 'string') {
+          this.ca = this.ca.concat(ca as string);
+        } else {
+          this.ca = this.ca.concat(ca as string[]);
+        }
+      } else {
+        log.error('Input ca certificate type mismatched with existing ca certificate type');
+      }
+    } else {
+      this.ca = ca;
+    }
+  }
+
+  /**
+   * This method clears existing CA Certificates.
+   * It sets ca to undefined
+   */
+  public clearCACertificates () {
+    this.ca = undefined;
   }
 
-  addRequest (request: *, configuration: *) {
+  /**
+   * Evaluate value for tls reject unauthorized variable
+   */
+  public getRejectUnauthorized () {
+    // eslint-disable-next-line node/no-process-env
+    const rejectUnauthorized = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+    let returnValue = true;
+    if (typeof rejectUnauthorized === 'boolean') {
+      returnValue = rejectUnauthorized;
+    } else if (typeof rejectUnauthorized === 'number') {
+      returnValue = rejectUnauthorized === 1;
+    } else if (typeof rejectUnauthorized === 'string') {
+      returnValue = ['true', 't', 'yes', 'y', 'on', '1'].includes(rejectUnauthorized.trim().toLowerCase());
+    }
+
+    return returnValue;
+  }
+
+  public abstract createConnection (configuration: ConnectionConfigurationType, callback: ConnectionCallbackType): void;
+
+  public addRequest (request: http.ClientRequest, configuration: RequestOptions) {
     let requestUrl;
 
     // It is possible that addRequest was constructed for a proxied request already, e.g.
     // "request" package does this when it detects that a proxy should be used
     // https://github.com/request/request/blob/212570b6971a732b8dd9f3c73354bcdda158a737/request.js#L402
     // https://gist.github.com/gajus/e2074cd3b747864ffeaabbd530d30218
-    if (request.path.startsWith('http://') || request.path.startsWith('https://')) {
+    if (request.path.startsWith('http://') ?? request.path.startsWith('https://')) {
       requestUrl = request.path;
+    } else if (request.method === 'CONNECT') {
+      requestUrl = 'https://' + request.path;
     } else {
-      requestUrl = this.protocol + '//' + (configuration.hostname || configuration.host) + (configuration.port === 80 || configuration.port === 443 ? '' : ':' + configuration.port) + request.path;
+      requestUrl = this.protocol + '//' + (configuration.hostname ?? configuration.host) + (configuration.port === 80 ?? configuration.port === 443 ? '' : ':' + configuration.port) + request.path;
+    }
+
+    // If a request should go to a local socket, proxying it through an HTTP
+    // server does not make sense as the information about the target socket
+    // will be lost and the proxy won't be able to correctly handle the request.
+    if (configuration.socketPath) {
+      log.trace({
+        destination: configuration.socketPath,
+      }, 'not proxying request; destination is a socket');
+
+      // @ts-expect-error seems like we are using wrong type for fallbackAgent.
+      this.fallbackAgent.addRequest(request, configuration);
+
+      return;
     }
 
     if (!this.isProxyConfigured()) {
@@ -68,7 +156,7 @@ class Agent {
         destination: requestUrl,
       }, 'not proxying request; GLOBAL_AGENT.HTTP_PROXY is not configured');
 
-      // $FlowFixMe It appears that Flow is missing the method description.
+      // @ts-expect-error seems like we are using wrong type for fallbackAgent.
       this.fallbackAgent.addRequest(request, configuration);
 
       return;
@@ -79,7 +167,7 @@ class Agent {
         destination: requestUrl,
       }, 'not proxying request; url matches GLOBAL_AGENT.NO_PROXY');
 
-      // $FlowFixMe It appears that Flow is missing the method description.
+      // @ts-expect-error seems like we are using wrong type for fallbackAgent.
       this.fallbackAgent.addRequest(request, configuration);
 
       return;
@@ -103,13 +191,13 @@ class Agent {
       requestId: currentRequestId,
     }, 'proxying request');
 
-    request.on('error', (error) => {
+    request.on('error', (error: Error) => {
       log.error({
         error: serializeError(error),
       }, 'request error');
     });
 
-    request.once('response', (response) => {
+    request.once('response', (response: http.IncomingMessage) => {
       log.trace({
         headers: response.headers,
         requestId: currentRequestId,
@@ -120,8 +208,8 @@ class Agent {
     request.shouldKeepAlive = false;
 
     const connectionConfiguration = {
-      host: configuration.hostname || configuration.host,
-      port: configuration.port || 80,
+      host: configuration.hostname ?? configuration.host ?? '',
+      port: configuration.port ?? 80,
       proxy,
       tls: {},
     };
@@ -133,9 +221,13 @@ class Agent {
     // > are also accepted:
     // >   ca, cert, ciphers, clientCertEngine, crl, dhparam, ecdhCurve, honorCipherOrder,
     // >   key, passphrase, pfx, rejectUnauthorized, secureOptions, secureProtocol, servername, sessionIdContext.
-    if (this.protocol === 'https:') {
+    if (configuration.secureEndpoint) {
+      // Determine servername - Node.js doesn't allow IP addresses as servername
+      const host = configuration.servername ?? connectionConfiguration.host;
+      const servername = net.isIP(host) ? undefined : host;
+
       connectionConfiguration.tls = {
-        ca: configuration.ca,
+        ca: configuration.ca ?? this.ca,
         cert: configuration.cert,
         ciphers: configuration.ciphers,
         clientCertEngine: configuration.clientCertEngine,
@@ -146,24 +238,14 @@ class Agent {
         key: configuration.key,
         passphrase: configuration.passphrase,
         pfx: configuration.pfx,
-        rejectUnauthorized: configuration.rejectUnauthorized,
+        rejectUnauthorized: configuration.rejectUnauthorized ?? this.getRejectUnauthorized(),
         secureOptions: configuration.secureOptions,
         secureProtocol: configuration.secureProtocol,
-        servername: configuration.servername || connectionConfiguration.host,
+        servername,
         sessionIdContext: configuration.sessionIdContext,
       };
-
-      // This is not ideal because there is no way to override this setting using `tls` configuration if `NODE_TLS_REJECT_UNAUTHORIZED=0`.
-      // However, popular HTTP clients (such as https://github.com/sindresorhus/got) come with pre-configured value for `rejectUnauthorized`,
-      // which makes it impossible to override that value globally and respect `rejectUnauthorized` for specific requests only.
-      //
-      // eslint-disable-next-line no-process-env
-      if (typeof process.env.NODE_TLS_REJECT_UNAUTHORIZED === 'string' && boolean(process.env.NODE_TLS_REJECT_UNAUTHORIZED) === false) {
-        connectionConfiguration.tls.rejectUnauthorized = false;
-      }
     }
 
-    // $FlowFixMe It appears that Flow is missing the method description.
     this.createConnection(connectionConfiguration, (error, socket) => {
       log.trace({
         target: connectionConfiguration,
@@ -194,10 +276,10 @@ class Agent {
 
       if (error) {
         request.emit('error', error);
-      } else {
+      } else if (socket) {
         log.debug('created socket');
 
-        socket.on('error', (socketError) => {
+        socket.on('error', (socketError: Error) => {
           log.error({
             error: serializeError(socketError),
           }, 'socket error');

package/src/classes/HttpProxyAgent.ts

@@ -0,0 +1,45 @@
+import net from 'net';
+import type {
+  AgentType,
+  ConnectionCallbackType,
+  ConnectionConfigurationType,
+  GetUrlProxyMethodType,
+  IsProxyConfiguredMethodType,
+  MustUrlUseProxyMethodType,
+} from '../types';
+import Agent from './Agent';
+
+class HttpProxyAgent extends Agent {
+  // @see https://github.com/sindresorhus/eslint-plugin-unicorn/issues/169#issuecomment-486980290
+  public constructor (
+    isProxyConfigured: IsProxyConfiguredMethodType,
+    mustUrlUseProxy: MustUrlUseProxyMethodType,
+    getUrlProxy: GetUrlProxyMethodType,
+    fallbackAgent: AgentType,
+    socketConnectionTimeout: number,
+    ca: string[] | string | undefined,
+  ) {
+    super(
+      isProxyConfigured,
+      mustUrlUseProxy,
+      getUrlProxy,
+      fallbackAgent,
+      socketConnectionTimeout,
+      ca,
+    );
+
+    this.protocol = 'http:';
+    this.defaultPort = 80;
+  }
+
+  public createConnection (configuration: ConnectionConfigurationType, callback: ConnectionCallbackType) {
+    const socket = net.connect(
+      configuration.proxy.port,
+      configuration.proxy.hostname,
+    );
+
+    callback(null, socket);
+  }
+}
+
+export default HttpProxyAgent;

package/src/classes/HttpsProxyAgent.ts

@@ -0,0 +1,83 @@
+import net from 'net';
+import tls from 'tls';
+import type {
+  AgentType,
+  ConnectionCallbackType,
+  ConnectionConfigurationType,
+  GetUrlProxyMethodType,
+  IsProxyConfiguredMethodType,
+  MustUrlUseProxyMethodType,
+} from '../types';
+import Agent from './Agent';
+
+class HttpsProxyAgent extends Agent {
+  public constructor (
+    isProxyConfigured: IsProxyConfiguredMethodType,
+    mustUrlUseProxy: MustUrlUseProxyMethodType,
+    getUrlProxy: GetUrlProxyMethodType,
+    fallbackAgent: AgentType,
+    socketConnectionTimeout: number,
+    ca: string[] | string | undefined,
+  ) {
+    super(
+      isProxyConfigured,
+      mustUrlUseProxy,
+      getUrlProxy,
+      fallbackAgent,
+      socketConnectionTimeout,
+      ca,
+    );
+
+    this.protocol = 'https:';
+    this.defaultPort = 443;
+  }
+
+  public createConnection (configuration: ConnectionConfigurationType, callback: ConnectionCallbackType) {
+    const socket = net.connect(
+      configuration.proxy.port,
+      configuration.proxy.hostname,
+    );
+
+    socket.on('error', (error) => {
+      callback(error);
+    });
+
+    socket.once('data', (data) => {
+      // Proxies with HTTPS as protocal are not allowed by parseProxyUrl(), so it should be safe to assume that the response is plain text
+      const statusLine = data.toString().split('\r\n')[0];
+      const statusLineExp = /^HTTP\/(\d)\.(\d) (\d{3}) ?(.*)$/;
+
+      const statusCode = statusLineExp.exec(statusLine)?.[3];
+
+      if (typeof statusCode === 'string' && Number(statusCode) >= 400) {
+        const error = new Error(`Proxy server refused connecting to '${configuration.host}:${configuration.port}' (${statusLine})`);
+        socket.destroy();
+        callback(error);
+
+        return;
+      }
+
+      const secureSocket = tls.connect({
+        ...configuration.tls,
+        socket,
+      });
+
+      callback(null, secureSocket);
+    });
+
+    let connectMessage = '';
+
+    connectMessage += 'CONNECT ' + configuration.host + ':' + configuration.port + ' HTTP/1.1\r\n';
+    connectMessage += 'Host: ' + configuration.host + ':' + configuration.port + '\r\n';
+
+    if (configuration.proxy.authorization) {
+      connectMessage += 'Proxy-Authorization: Basic ' + Buffer.from(configuration.proxy.authorization).toString('base64') + '\r\n';
+    }
+
+    connectMessage += '\r\n';
+
+    socket.write(connectMessage);
+  }
+}
+
+export default HttpsProxyAgent;

package/src/classes/index.ts

@@ -0,0 +1,9 @@
+export {
+  default as Agent,
+} from './Agent';
+export {
+  default as HttpProxyAgent,
+} from './HttpProxyAgent';
+export {
+  default as HttpsProxyAgent,
+} from './HttpsProxyAgent';

package/src/{errors.js → errors.ts}

@@ -1,13 +1,9 @@
-// @flow
-
-/* eslint-disable fp/no-class, fp/no-this */
-
 import ExtendableError from 'es6-error';
 
 export class UnexpectedStateError extends ExtendableError {
-  code: string;
+  public code: string;
 
-  constructor (message: string, code: string = 'UNEXPECTED_STATE_ERROR') {
+  public constructor (message: string, code: string = 'UNEXPECTED_STATE_ERROR') {
     super(message);
 
     this.code = code;

package/src/factories/{createGlobalProxyAgent.js → createGlobalProxyAgent.ts}

@@ -1,11 +1,9 @@
-// @flow
-
 import http from 'http';
 import https from 'https';
 import {
-  boolean as parseBoolean,
-} from 'boolean';
-import semver from 'semver';
+  omitUndefined,
+} from 'omit-undefined';
+import semverGte from 'semver/functions/gte';
 import Logger from '../Logger';
 import {
   HttpProxyAgent,
@@ -14,15 +12,18 @@ import {
 import {
   UnexpectedStateError,
 } from '../errors';
+import type {
+  ProxyAgentConfigurationInputType,
+  ProxyAgentConfigurationType,
+} from '../types';
 import {
   bindHttpMethod,
   isUrlMatchingNoProxy,
   parseProxyUrl,
 } from '../utilities';
-import type {
-  ProxyAgentConfigurationInputType,
-  ProxyAgentConfigurationType,
-} from '../types';
+import {
+  parseBoolean,
+} from '../utilities/parseBoolean';
 import createProxyController from './createProxyController';
 
 const httpGet = http.get;
@@ -37,27 +38,11 @@ const log = Logger.child({
 const defaultConfigurationInput = {
   environmentVariableNamespace: undefined,
   forceGlobalAgent: undefined,
-  socketConnectionTimeout: 60000,
-};
-
-const omitUndefined = (subject) => {
-  const keys = Object.keys(subject);
-
-  const result = {};
-
-  for (const key of keys) {
-    const value = subject[key];
-
-    if (value !== undefined) {
-      result[key] = value;
-    }
-  }
-
-  return result;
+  socketConnectionTimeout: 60_000,
 };
 
 const createConfiguration = (configurationInput: ProxyAgentConfigurationInputType): ProxyAgentConfigurationType => {
-  // eslint-disable-next-line no-process-env
+  // eslint-disable-next-line node/no-process-env
   const environment = process.env;
 
   const defaultConfiguration = {
@@ -66,7 +51,6 @@ const createConfiguration = (configurationInput: ProxyAgentConfigurationInputTyp
     socketConnectionTimeout: typeof environment.GLOBAL_AGENT_SOCKET_CONNECTION_TIMEOUT === 'string' ? Number.parseInt(environment.GLOBAL_AGENT_SOCKET_CONNECTION_TIMEOUT, 10) : defaultConfigurationInput.socketConnectionTimeout,
   };
 
-  // $FlowFixMe
   return {
     ...defaultConfiguration,
     ...omitUndefined(configurationInput),
@@ -78,22 +62,22 @@ export default (configurationInput: ProxyAgentConfigurationInputType = defaultCo
 
   const proxyController = createProxyController();
 
-  // eslint-disable-next-line no-process-env
-  proxyController.HTTP_PROXY = process.env[configuration.environmentVariableNamespace + 'HTTP_PROXY'] || null;
+  // eslint-disable-next-line node/no-process-env
+  proxyController.HTTP_PROXY = process.env[configuration.environmentVariableNamespace + 'HTTP_PROXY'] ?? null;
 
-  // eslint-disable-next-line no-process-env
-  proxyController.HTTPS_PROXY = process.env[configuration.environmentVariableNamespace + 'HTTPS_PROXY'] || null;
+  // eslint-disable-next-line node/no-process-env
+  proxyController.HTTPS_PROXY = process.env[configuration.environmentVariableNamespace + 'HTTPS_PROXY'] ?? null;
 
-  // eslint-disable-next-line no-process-env
-  proxyController.NO_PROXY = process.env[configuration.environmentVariableNamespace + 'NO_PROXY'] || null;
+  // eslint-disable-next-line node/no-process-env
+  proxyController.NO_PROXY = process.env[configuration.environmentVariableNamespace + 'NO_PROXY'] ?? null;
 
   log.info({
     configuration,
     state: proxyController,
   }, 'global agent has been initialized');
 
-  const mustUrlUseProxy = (getProxy) => {
-    return (url) => {
+  const mustUrlUseProxy = (getProxy: () => string | null) => {
+    return (url: string): boolean => {
       if (!getProxy()) {
         return false;
       }
@@ -106,7 +90,7 @@ export default (configurationInput: ProxyAgentConfigurationInputType = defaultCo
     };
   };
 
-  const getUrlProxy = (getProxy) => {
+  const getUrlProxy = (getProxy: () => string | null) => {
     return () => {
       const proxy = getProxy();
 
@@ -123,15 +107,16 @@ export default (configurationInput: ProxyAgentConfigurationInputType = defaultCo
   };
 
   const BoundHttpProxyAgent = class extends HttpProxyAgent {
-    constructor () {
+    public constructor () {
       super(
         () => {
-          return getHttpProxy();
+          return Boolean(getHttpProxy());
         },
         mustUrlUseProxy(getHttpProxy),
         getUrlProxy(getHttpProxy),
         http.globalAgent,
         configuration.socketConnectionTimeout,
+        configuration.ca,
       );
     }
   };
@@ -139,19 +124,20 @@ export default (configurationInput: ProxyAgentConfigurationInputType = defaultCo
   const httpAgent = new BoundHttpProxyAgent();
 
   const getHttpsProxy = () => {
-    return proxyController.HTTPS_PROXY || proxyController.HTTP_PROXY;
+    return proxyController.HTTPS_PROXY ?? proxyController.HTTP_PROXY;
   };
 
   const BoundHttpsProxyAgent = class extends HttpsProxyAgent {
-    constructor () {
+    public constructor () {
       super(
         () => {
-          return getHttpsProxy();
+          return Boolean(getHttpsProxy());
         },
         mustUrlUseProxy(getHttpsProxy),
         getUrlProxy(getHttpsProxy),
         https.globalAgent,
         configuration.socketConnectionTimeout,
+        configuration.ca,
       );
     }
   };
@@ -160,12 +146,12 @@ export default (configurationInput: ProxyAgentConfigurationInputType = defaultCo
 
   // Overriding globalAgent was added in v11.7.
   // @see https://nodejs.org/uk/blog/release/v11.7.0/
-  if (semver.gte(process.version, 'v11.7.0')) {
+  if (semverGte(process.version, 'v11.7.0')) {
     // @see https://github.com/facebook/flow/issues/7670
-    // $FlowFixMe
+    // @ts-expect-error Node.js version compatibility
     http.globalAgent = httpAgent;
 
-    // $FlowFixMe
+    // @ts-expect-error Node.js version compatibility
     https.globalAgent = httpsAgent;
   }
 
@@ -177,17 +163,17 @@ export default (configurationInput: ProxyAgentConfigurationInputType = defaultCo
   //
   // We still want to override http(s).globalAgent when possible to enable logic
   // in `bindHttpMethod`.
-  if (semver.gte(process.version, 'v10.0.0')) {
-    // $FlowFixMe
+  if (semverGte(process.version, 'v10.0.0')) {
+    // @ts-expect-error seems like we are using wrong type for httpAgent
     http.get = bindHttpMethod(httpGet, httpAgent, configuration.forceGlobalAgent);
 
-    // $FlowFixMe
+    // @ts-expect-error seems like we are using wrong type for httpAgent
     http.request = bindHttpMethod(httpRequest, httpAgent, configuration.forceGlobalAgent);
 
-    // $FlowFixMe
+    // @ts-expect-error seems like we are using wrong type for httpAgent
     https.get = bindHttpMethod(httpsGet, httpsAgent, configuration.forceGlobalAgent);
 
-    // $FlowFixMe
+    // @ts-expect-error seems like we are using wrong type for httpAgent
     https.request = bindHttpMethod(httpsRequest, httpsAgent, configuration.forceGlobalAgent);
   } else {
     log.warn('attempt to initialize global-agent in unsupported Node.js version was ignored');

package/{dist/factories/createProxyController.js.flow → src/factories/createProxyController.ts}

@@ -1,12 +1,10 @@
-// @flow
-
 import Logger from '../Logger';
 
-type ProxyControllerType = {|
+type ProxyController = {
   HTTP_PROXY: string | null,
   HTTPS_PROXY: string | null,
   NO_PROXY: string | null,
-|};
+};
 
 const log = Logger.child({
   namespace: 'createProxyController',
@@ -18,7 +16,7 @@ const KNOWN_PROPERTY_NAMES = [
   'NO_PROXY',
 ];
 
-export default (): ProxyControllerType => {
+export default (): ProxyController => {
   // eslint-disable-next-line fp/no-proxy
   return new Proxy({
     HTTP_PROXY: null,
@@ -26,10 +24,15 @@ export default (): ProxyControllerType => {
     NO_PROXY: null,
   }, {
     set: (subject, name, value) => {
+      if (typeof name !== 'string') {
+        throw new TypeError('Unexpected object member.');
+      }
+
       if (!KNOWN_PROPERTY_NAMES.includes(name)) {
         throw new Error('Cannot set an unmapped property "' + name + '".');
       }
 
+      // @ts-expect-error string cannot be used to index an object
       subject[name] = value;
 
       log.info({

package/src/factories/index.ts

@@ -0,0 +1,6 @@
+export {
+  default as createGlobalProxyAgent,
+} from './createGlobalProxyAgent';
+export {
+  default as createProxyController,
+} from './createProxyController';

package/src/index.ts

@@ -0,0 +1,6 @@
+export {
+  bootstrap,
+} from './routines';
+export {
+  createGlobalProxyAgent,
+} from './factories';