// 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,

}