1
// Licensed to the Software Freedom Conservancy (SFC) under one
2
// or more contributor license agreements.  See the NOTICE file
3
// distributed with this work for additional information
4
// regarding copyright ownership.  The SFC licenses this file
5
// to you under the Apache License, Version 2.0 (the
6
// "License"); you may not use this file except in compliance
7
// with the License.  You may obtain a copy of the License at
8
//
9
//   http://www.apache.org/licenses/LICENSE-2.0
10
//
11
// Unless required by applicable law or agreed to in writing,
12
// software distributed under the License is distributed on an
13
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14
// KIND, either express or implied.  See the License for the
15
// specific language governing permissions and limitations
16
// under the License.
17

18
/**
19
 * @fileoverview Defines functions for configuring a webdriver proxy:
20
 *
21
 *     const proxy = require('selenium-webdriver/proxy');
22
 *     const {Capabilities} = require('selenium-webdriver');
23
 *
24
 *     let capabilities = new Capabilities();
25
 *     capabilities.setProxy(proxy.manual({http: 'host:1234'});
26
 */
27

28
'use strict'
29

30
/**
31
 * Supported {@linkplain Config proxy configuration} types.
32
 *
33
 * @enum {string}
34
 */
35
const Type = {
36
  AUTODETECT: 'autodetect',
37
  DIRECT: 'direct',
38
  MANUAL: 'manual',
39
  PAC: 'pac',
40
  SYSTEM: 'system',
41
}
42

43
/**
44
 * Describes how a proxy should be configured for a WebDriver session.
45
 * @record
46
 */
47
function Config() {}
48

49
/**
50
 * The proxy type.
51
 * @type {Type}
52
 */
53
Config.prototype.proxyType
54

55
/**
56
 * Describes how to configure a PAC proxy.
57
 * @record
58
 * @extends {Config}
59
 */
60
function PacConfig() {}
61

62
/**
63
 * URL for the PAC file to use.
64
 *
65
 * @type {string}
66
 */
67
PacConfig.prototype.proxyAutoconfigUrl
68

69
/**
70
 * Record object that defines a manual proxy configuration. Manual
71
 * configurations can be easily created using either the
72
 * {@link ./proxy.manual proxy.manual()} or {@link ./proxy.socks proxy.socks()}
73
 * factory method.
74
 *
75
 * @record
76
 * @extends {Config}
77
 */
78
function ManualConfig() {}
79

80
/**
81
 * The proxy host for FTP requests.
82
 *
83
 * @type {(string|undefined)}
84
 */
85
ManualConfig.prototype.ftpProxy
86

87
/**
88
 * The proxy host for HTTP requests.
89
 *
90
 * @type {(string|undefined)}
91
 */
92
ManualConfig.prototype.httpProxy
93

94
/**
95
 * An array of hosts which should bypass all proxies.
96
 *
97
 * @type {(Array<string>|undefined)}
98
 */
99
ManualConfig.prototype.noProxy
100

101
/**
102
 * The proxy host for HTTPS requests.
103
 *
104
 * @type {(string|undefined)}
105
 */
106
ManualConfig.prototype.sslProxy
107

108
/**
109
 * Defines the host and port for the SOCKS proxy to use.
110
 *
111
 * @type {(number|undefined)}
112
 */
113
ManualConfig.prototype.socksProxy
114

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

122
// PUBLIC API
123

124
/** @const */ exports.Config = Config
125
/** @const */ exports.ManualConfig = ManualConfig
126
/** @const */ exports.PacConfig = PacConfig
127
/** @const */ exports.Type = Type
128

129
/**
130
 * Configures WebDriver to bypass all browser proxies.
131
 * @return {!Config} A new proxy configuration object.
132
 */
133
function direct() {
134
  return { proxyType: Type.DIRECT }
135
}
136

137
/**
138
 * Manually configures the browser proxy.  The following options are
139
 * supported:
140
 *
141
 * - `ftp`: Proxy host to use for FTP requests
142
 * - `http`: Proxy host to use for HTTP requests
143
 * - `https`: Proxy host to use for HTTPS requests
144
 * - `bypass`: A list of hosts requests should directly connect to,
145
 *     bypassing any other proxies for that request. May be specified as a
146
 *     comma separated string, or a list of strings.
147
 *
148
 * Behavior is undefined for FTP, HTTP, and HTTPS requests if the
149
 * corresponding key is omitted from the configuration options.
150
 *
151
 * @param {{ftp: (string|undefined),
152
 *          http: (string|undefined),
153
 *          https: (string|undefined),
154
 *          bypass: (Array<string>|undefined)}} options Proxy
155
 *     configuration options.
156
 * @return {!ManualConfig} A new proxy configuration object.
157
 */
158
function manual({ ftp, http, https, bypass }) {
159
  if (ftp !== undefined) {
160
    console.warn('ftpProxy is deprecated and will be removed in the future')
161
  }
162
  return {
163
    proxyType: Type.MANUAL,
164
    ftpProxy: ftp,
165
    httpProxy: http,
166
    sslProxy: https,
167
    noProxy: bypass,
168
  }
169
}
170

171
/**
172
 * Creates a proxy configuration for a socks proxy.
173
 *
174
 * __Example:__
175
 *
176
 *     const {Capabilities} = require('selenium-webdriver');
177
 *     const proxy = require('selenium-webdriver/lib/proxy');
178
 *
179
 *     let capabilities = new Capabilities();
180
 *     capabilities.setProxy(proxy.socks('localhost:1234'));
181
 *
182
 *     // Or, to include authentication.
183
 *     capabilities.setProxy(proxy.socks('bob:password@localhost:1234'));
184
 *
185
 *
186
 * @param {string} socksProxy The proxy host, in the form `hostname:port`.
187
 * @param {number=} socksVersion The SOCKS proxy version.
188
 * @return {!ManualConfig} A new proxy configuration object.
189
 * @see https://en.wikipedia.org/wiki/SOCKS
190
 */
191
function socks(socksProxy, socksVersion = undefined) {
192
  return /** @type {!Config} */ ({
193
    proxyType: Type.MANUAL,
194
    socksProxy,
195
    socksVersion,
196
  })
197
}
198

199
/**
200
 * Configures WebDriver to configure the browser proxy using the PAC file at
201
 * the given URL.
202
 * @param {string} proxyAutoconfigUrl URL for the PAC proxy to use.
203
 * @return {!PacConfig} A new proxy configuration object.
204
 */
205
function pac(proxyAutoconfigUrl) {
206
  return { proxyType: Type.PAC, proxyAutoconfigUrl }
207
}
208

209
/**
210
 * Configures WebDriver to use the current system's proxy.
211
 * @return {!Config} A new proxy configuration object.
212
 */
213
function system() {
214
  return { proxyType: Type.SYSTEM }
215
}
216

217
// PUBLIC API
218

219
module.exports = {
220
  system,
221
  pac,
222
  socks,
223
  manual,
224
  direct,
225
}
226

227