Allow for specifying schema in "proxy" #1922

sadym-chromium · 2025-08-29T14:32:56Z

Addressing #1920.

Currently, WebDriver capabilities allow for configuring proxy by protocol. Meaning the protocol traffic can be proxied via the same protocol proxy.

Chromium can proxy traffic via different proxy protocols, and can configure which proxy to use for which protocol. In Chromium, the possible proxy schemas are http, https, socks4, socks5. Also user can configure separately proxy for HTTP, HTTPS and all other requests (SOCKS).

In order to allow for such configurations, we propose the following:

Allow for schemas (http, https, socks, socks4, socks5) in the proxy url.

Here is the details list of options can be provided in the capabilities:

`http` proxy

The list of cases, when the proxy is connected with HTTP protocol:

(existing) httpProxy: proxy.com. The traffic type is used, as not scheme, nor port were set.
(existing) httpProxy: proxy.com:123. The traffic type is used, as scheme was not set, and the port is not standard for any supported proxy protocol.
(new) sslProxy: http://proxy.com. The scheme has priority over traffic type.
(new) socksProxy: http://proxy.com. The scheme has priority over traffic type. socksVersion is not required.
(new) sslProxy: http://proxy.com:443. The scheme has priority over port and traffic type.
(new) socksProxy: http://proxy.com:443. The scheme has priority over port and traffic type. socksVersion is not required.
(new) sslProxy: proxy.com:80. The port has priority over traffic type.
(new) socksProxy: proxy.com:80. The port has priority over traffic type. socksVersion is not required.

`https` proxy

The list of cases, when the proxy is connected with SSL protocol:

(existing) httpsProxy: proxy.com. The traffic type is used, as not scheme, nor port were set.
(existing) httpsProxy: proxy.com:123. The traffic type is used, as scheme was not set, and the port is not standard for any supported proxy protocol.
(new) httpProxy: https://proxy.com. The scheme has priority over traffic type.
(new) socksProxy: https://proxy.com. The scheme has priority over traffic type. socksVersion is not required.
(new) httpProxy: https://proxy.com:80. The scheme has priority over port and traffic type.
(new) socksProxy: https://proxy.com:80. The scheme has priority over port and traffic type. socksVersion is not required.
(new) httpProxy: proxy.com:443. The port has priority over traffic type.
(new) socksProxy: proxy.com:443. The port has priority over traffic type. socksVersion is not required.

`socks` proxy

The list of cases, when the proxy is connected with SOCKS protocol:

(existing) socksProxy: proxy.com + socksVersion: 4/5. The traffic type is used, as not scheme, nor port were set.
(existing) socksProxy: proxy.com:123 + socksVersion: 4/5. The traffic type is used, as scheme was not set, and the port is not standard for any supported proxy protocol.
(new) httpProxy: socks://proxy.com + socksVersion: 4/5. The scheme has priority over traffic type.
(new) httpProxy: socks4://proxy.com. The scheme has priority over traffic type. socksVersion is part of scheme.
(new) httpProxy: socks5://proxy.com. The scheme has priority over traffic type. socksVersion is part of scheme.
(new) sslProxy: socks://proxy.com + socksVersion: 4/5. The scheme has priority over traffic type.
(new) sslProxy: socks4://proxy.com. The scheme has priority over traffic type. socksVersion is part of scheme.
(new) sslProxy: socks5://proxy.com. The scheme has priority over traffic type. socksVersion is part of scheme.
(new) httpProxy: socks://proxy.com:80 + socksVersion: 4/5. The scheme has priority over port and traffic type.
(new) httpProxy: socks4://proxy.com:80. The scheme has priority over port and traffic type. socksVersion is part of scheme.
(new) httpProxy: socks5://proxy.com:80. The scheme has priority over port and traffic type. socksVersion is part of scheme.
(new) sslProxy: socks://proxy.com:80 + socksVersion: 4/5. The scheme has priority over port and traffic type.
(new) sslProxy: socks4://proxy.com:80. The scheme has priority over port and traffic type. socksVersion is part of scheme.
(new) sslProxy: socks5://proxy.com:80. The scheme has priority over port and traffic type. socksVersion is part of scheme.
(new) httpProxy: proxy.com:1080 + socksVersion: 4/5. The port has priority over traffic type.
(new) sslProxy: proxy.com:1080 + socksVersion: 4/5. The port has priority over traffic type.

Preview | Diff

OrKoN

LGTM

whimboo · 2025-09-02T06:19:11Z

index.html

 </tr>

- <tr>
-  <td><code>socksVersion</code>


Is there a reason why you removed the socksVersion field? I thought that for socks proxies it is a mandatory field. Also if clients specify this field we would run into a backward incompatible change.

The key change is that the "socksProxy" field sets how to proxy ALL the socks connections, not only of the specific version.

WRT backward compatibility, we can figure things out if we agree on what we want to achieve.

From the Chromium perspective, the socksVersion does not make actually sense.

Removing the socks version will cause a backward incompatible change, means it will break clients using that field. We probably should fine a way to deprecate if it is really not needed. But note that when defining a socks proxy in Firefox you need to specify the version. So I don't think that we can get rid of it.

I see. I re-worked the PR so that the socksVersion can be used together with socks:// scheme.

We can default socksVersion to 5 to ease the API. @whimboo WDYT?

index.html

whimboo · 2025-09-02T06:25:05Z

index.html

+  undefined.
+
+<p>A <dfn>proxy schema</dfn> is defined as being one of the following strings:
+ "<code>http</code>", "<code>https</code>", "<code>socks4</code>",


Neither socks4 nor socks5 is a valid schema as supported by Firefox. For socks proxy there is usually no schema at all when specifying the host. Does Chrome support that? Also note the other comment above regarding the backward incompatible change.

As documented here, Chrome supports proxy via HTTP, SSL, SOCKS 4 and SOCKS 5:

http://proxy:8080 uses HTTP.

https://proxy:8080 uses SSL.

socks4://proxy:8080 uses SOCKS 4.

socks5://proxy:8080 uses SOCKS 5.

socks://proxy:8080 uses SOCKS 5, as schema "socks" is alias for schema "socks5".

Neither socks4 nor socks5 is a valid schema as supported by Firefox. For socks proxy there is usually no schema at all when specifying the host. Does Chrome support that? Also note the other comment above regarding the backward incompatible change.

Does it mean that Firefox cannot proxy SOCKS 5 via SOCKS 4 and vice versa?

sadym-chromium · 2025-09-16T11:30:46Z

@whimboo WDYT?

whimboo · 2025-09-30T19:02:43Z

index.html

 </tr>

- <tr>
-  <td><code>socksVersion</code>


Removing the socks version will cause a backward incompatible change, means it will break clients using that field. We probably should fine a way to deprecate if it is really not needed. But note that when defining a socks proxy in Firefox you need to specify the version. So I don't think that we can get rid of it.

index.html

whimboo · 2025-09-30T20:08:40Z

index.html

+  <var>scheme</var> is omitted, the <var>scheme</var> is implied to be
+  "<code>http</code>". If the port is omitted and <var>scheme</var> has a


Could we at least try to figure out the right scheme (if not given) in case a default port has been set for the proxy? Using host:443 should most likely be a HTTPS proxy, or? If the port is not given, I assume that we could fallback to HTTP (HTTPS proxies still seem to be used rarely).

Should we add a note to indicate any change to the former version of the spec?

Should we add a note to indicate any change to the former version of the spec?

Do you have an idea of proper wording?

sadym-chromium · 2025-10-21T11:39:47Z

@whimboo WDYT?

sadym-chromium · 2025-11-28T10:14:25Z

@whimboo could you please take another look?

whimboo

Sorry for taking so long with my review. Inline you can find some comments so that we can continue the discussion.

index.html

whimboo · 2025-12-09T09:17:11Z

index.html

-  <td>Defines the <a>SOCKS proxy</a> version
-   when the <a><code>proxyType</code></a> is "<code>manual</code>".
+  <td>Defines the <a>SOCKS proxy</a> version when the <a>proxy url</a>'s
+   <a>proxy scheme</a> is "<code>socks</code>".


Similar to my comment above. It would be a backward compatibility breaking change when we now introduce a socks scheme.

Updated algorithm. The socksVersion is required, if any of the proxies has socks schema, or if the socksProxy don't have schema.

whimboo · 2025-12-09T09:21:26Z

index.html

+
+ <li><p>If the <var>scheme</var> is omitted and the <var>port</var> is 443,
+  the <var>scheme</var> is implied to be "<code>https</code>". Otherwise, the
+  <var>scheme</var> is implied to be "<code>http</code>".


This paragraph should only apply to HTTP or HTTPS proxies but not for a proxy URL as specified for a socks proxy.

whimboo · 2025-12-09T09:24:02Z

index.html

+
+<p>A <dfn>proxy scheme</dfn> is defined as being one of the following strings:
+ "<code>http</code>", "<code>https</code>", "<code>socks</code>",
+ "<code>socks4</code>", "<code>socks5</code>".


I still think that is a backward incompatible given that we didn't use a scheme for socks so far and I'm unsure how clients actually specify the socks proxy.

@jgraham maybe you have some additional feedback.

I updated the algorithm.

Old users omitted schema in proxy url, and expected the traffic to be proxied to the same protocol.

Now, the schema defaults to the protocol to proxy. So this the behavior for them is not changed.

However, if the user WANTS to specify schema, now they can do it.

Co-authored-by: Henrik Skupin <mail@hskupin.info>

css-meeting-bot · 2025-12-10T17:46:44Z

The Browser Testing and Tools Working Group just discussed Allow for specifying schema in "proxy".

The full IRC log of that discussion

<AutomatedTester> topic: Allow for specifying schema in "proxy"
<AutomatedTester> github: https://github.com//pull/1922
<AutomatedTester> sadym: what is specified in the spec isn't what chromium does, chromium does a lot more
<AutomatedTester> ... I have reworked the proposal and it is backwards compatiable
<AutomatedTester> ... please look and consider this for merging
<AutomatedTester> q?

whimboo · 2025-12-17T10:06:42Z

index.html

+ <li><p>If <var>proxy</var> contains <a>proxy url</a> with <a>proxy scheme</a>
+  "<code>socks</code>" and does not have an <a>own property</a>


Is there a reason why you recently replaced has an <a>own property</a> for "<code>socksProxy</code>"? For a socks proxy configuration we should only check the requirement for the socks versionwhen a socks proxy was actually specified. Also to what wouldproxy contains proxy url` point to? It's not a key but a value for some other possible proxy config - a http proxy with socks scheme should not be considered here, right?

I extended the description of the issue with detailed list of possible capabilities. This line was changed in order to fulfill new scenarios under "socks proxy" section. Otherwise the socks version to be used to connect to the proxy would be undefined. E.g.

httpProxy: socks://proxy.com + socksVersion: 4/5.

If we restrict the scheme to socks, that would restrict all the traffic to be proxied via the same socks protocol version. So you wouldn't be able to proxy http traffic via socks5, while ssl traffic via sock4. Even though this seems quite niche scenario, such a restriction seems quite artificial.

sadym-chromium added the needs-discussion label Aug 29, 2025

sadym-chromium force-pushed the sadym/proxy branch from 8b7b4d2 to 5b447f9 Compare August 29, 2025 14:58

sadym-chromium requested a review from OrKoN August 29, 2025 15:01

sadym-chromium changed the title ~~Align "proxy" string configuration with Chromium implementation~~ Allow for "proxy" schemas Aug 29, 2025

sadym-chromium changed the title ~~Allow for "proxy" schemas~~ Allow for specifying schema in "proxy" Aug 29, 2025

sadym-chromium mentioned this pull request Aug 29, 2025

Allow for protocol schema in proxy configuration #1920

Open

sadym-chromium marked this pull request as ready for review August 29, 2025 15:33

OrKoN approved these changes Sep 1, 2025

View reviewed changes

whimboo requested changes Sep 2, 2025

View reviewed changes

sadym-chromium requested a review from whimboo September 16, 2025 11:29

whimboo requested changes Sep 30, 2025

View reviewed changes

sadym-chromium force-pushed the sadym/proxy branch from f9c0242 to 7104d77 Compare October 1, 2025 08:34

sadym-chromium requested a review from whimboo October 1, 2025 11:49

whimboo requested changes Dec 9, 2025

View reviewed changes

sadym-chromium and others added 7 commits December 9, 2025 10:42

Inline "proxy" string configuration with Chromium implementation

d64580f

restrict proxy schema

4a7ee1b

roll back socksProxy

e6a351f

schemas

73f2d59

Update index.html

3d84a8f

Co-authored-by: Henrik Skupin <mail@hskupin.info>

s/schema/scheme

1e0853d

socksVersion defines the protocol version for socks protocol

b0a959b

sadym-chromium force-pushed the sadym/proxy branch from d4a1533 to b0a959b Compare December 9, 2025 09:42

sadym-chromium added 2 commits December 9, 2025 12:38

default proxy protocol to the protocol to proxy

b22e68f

fix note

63e21ca

sadym-chromium requested a review from whimboo December 12, 2025 13:31

whimboo reviewed Dec 17, 2025

View reviewed changes

sadym-chromium requested a review from whimboo December 17, 2025 12:59

		<var>scheme</var> is omitted, the <var>scheme</var> is implied to be
		"<code>http</code>". If the port is omitted and <var>scheme</var> has a

		<li><p>If <var>proxy</var> contains <a>proxy url</a> with <a>proxy scheme</a>
		"<code>socks</code>" and does not have an <a>own property</a>

Allow for specifying schema in "proxy" #1922

Are you sure you want to change the base?

Allow for specifying schema in "proxy" #1922

Uh oh!

Conversation

sadym-chromium commented Aug 29, 2025 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

http proxy

https proxy

socks proxy

Uh oh!

OrKoN left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sadym-chromium Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sadym-chromium commented Sep 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sadym-chromium commented Oct 21, 2025

Uh oh!

sadym-chromium commented Nov 28, 2025

Uh oh!

whimboo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

css-meeting-bot commented Dec 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

sadym-chromium commented Aug 29, 2025 •

edited by pr-preview bot

Loading

`http` proxy

`https` proxy

`socks` proxy

sadym-chromium Sep 12, 2025 •

edited

Loading