javascript/node/selenium-webdriver/lib/proxy.js

// Licensed to the Software Freedom Conservancy (SFC) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The SFC licenses this file
// 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
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

/**
 * @fileoverview Defines functions for configuring a webdriver proxy:
 *
 *     const proxy = require('selenium-webdriver/proxy');
 *     const {Capabilities} = require('selenium-webdriver');
 *
 *     let capabilities = new Capabilities();
 *     capabilities.setProxy(proxy.manual({http: 'host:1234'});
 */

'use strict'

/**
 * Supported {@linkplain Config proxy configuration} types.
 *
 * @enum {string}
 */
const Type = {
  AUTODETECT: 'autodetect',
  DIRECT: 'direct',
  MANUAL: 'manual',
  PAC: 'pac',
  SYSTEM: 'system',
}

/**
 * Describes how a proxy should be configured for a WebDriver session.
 * @record
 */
function Config() {}

/**
 * The proxy type.
 * @type {Type}
 */
Config.prototype.proxyType

/**
 * Describes how to configure a PAC proxy.
 * @record
 * @extends {Config}
 */
function PacConfig() {}

/**
 * URL for the PAC file to use.
 *
 * @type {string}
 */
PacConfig.prototype.proxyAutoconfigUrl

/**
 * Record object that defines a manual proxy configuration. Manual
 * configurations can be easily created using either the
 * {@link ./proxy.manual proxy.manual()} or {@link ./proxy.socks proxy.socks()}
 * factory method.
 *
 * @record
 * @extends {Config}
 */
function ManualConfig() {}

/**
 * The proxy host for FTP requests.
 *
 * @type {(string|undefined)}
 */
ManualConfig.prototype.ftpProxy

/**
 * The proxy host for HTTP requests.
 *
 * @type {(string|undefined)}
 */
ManualConfig.prototype.httpProxy

/**
 * An array of hosts which should bypass all proxies.
 *
 * @type {(Array<string>|undefined)}
 */
ManualConfig.prototype.noProxy

/**
 * The proxy host for HTTPS requests.
 *
 * @type {(string|undefined)}
 */
ManualConfig.prototype.sslProxy

/**
 * Defines the host and port for the SOCKS proxy to use.
 *
 * @type {(number|undefined)}
 */
ManualConfig.prototype.socksProxy

/**
 * Defines the SOCKS proxy version. Must be a number in the range [0, 255].
 *
 * @type {(number|undefined)}
 */
ManualConfig.prototype.socksVersion

// PUBLIC API

/** @const */ exports.Config = Config
/** @const */ exports.ManualConfig = ManualConfig
/** @const */ exports.PacConfig = PacConfig
/** @const */ exports.Type = Type

/**
 * Configures WebDriver to bypass all browser proxies.
 * @return {!Config} A new proxy configuration object.
 */
function direct() {
  return { proxyType: Type.DIRECT }
}

/**
 * Manually configures the browser proxy.  The following options are
 * supported:
 *
 * - `ftp`: Proxy host to use for FTP requests
 * - `http`: Proxy host to use for HTTP requests
 * - `https`: Proxy host to use for HTTPS requests
 * - `bypass`: A list of hosts requests should directly connect to,
 *     bypassing any other proxies for that request. May be specified as a
 *     comma separated string, or a list of strings.
 *
 * Behavior is undefined for FTP, HTTP, and HTTPS requests if the
 * corresponding key is omitted from the configuration options.
 *
 * @param {{ftp: (string|undefined),
 *          http: (string|undefined),
 *          https: (string|undefined),
 *          bypass: (Array<string>|undefined)}} options Proxy
 *     configuration options.
 * @return {!ManualConfig} A new proxy configuration object.
 */
function manual({ ftp, http, https, bypass }) {
  return {
    proxyType: Type.MANUAL,
    ftpProxy: ftp,
    httpProxy: http,
    sslProxy: https,
    noProxy: bypass,
  }
}

/**
 * Creates a proxy configuration for a socks proxy.
 *
 * __Example:__
 *
 *     const {Capabilities} = require('selenium-webdriver');
 *     const proxy = require('selenium-webdriver/lib/proxy');
 *
 *     let capabilities = new Capabilities();
 *     capabilities.setProxy(proxy.socks('localhost:1234'));
 *
 *     // Or, to include authentication.
 *     capabilities.setProxy(proxy.socks('bob:password@localhost:1234'));
 *
 *
 * @param {string} socksProxy The proxy host, in the form `hostname:port`.
 * @param {number=} socksVersion The SOCKS proxy version.
 * @return {!ManualConfig} A new proxy configuration object.
 * @see https://en.wikipedia.org/wiki/SOCKS
 */
function socks(socksProxy, socksVersion = undefined) {
  return /** @type {!Config} */ ({
    proxyType: Type.MANUAL,
    socksProxy,
    socksVersion,
  })
}

/**
 * Configures WebDriver to configure the browser proxy using the PAC file at
 * the given URL.
 * @param {string} proxyAutoconfigUrl URL for the PAC proxy to use.
 * @return {!PacConfig} A new proxy configuration object.
 */
function pac(proxyAutoconfigUrl) {
  return { proxyType: Type.PAC, proxyAutoconfigUrl }
}

/**
 * Configures WebDriver to use the current system's proxy.
 * @return {!Config} A new proxy configuration object.
 */
function system() {
  return { proxyType: Type.SYSTEM }
}

// PUBLIC API

module.exports = {
  system,
  pac,
  socks,
  manual,
  direct,
}