Allow for protocol schema in proxy configuration

Currently the "Valid values" of proxy configuration's httpProxy, sslProxy and socksProxy are host and optional port. This makes impossible scenarios of proxying HTTP requests via HTTPS proxy.

Consider allow scheme in proxy configuration's httpProxy, sslProxy and socksProxy valid values.

You can specify a proxy as secure-proxy.example.com:443 so that there is no need to have to specify the schema. So I think this is all fine.

You can specify a proxy as secure-proxy.example.com:443 so that there is no need to have to specify the schema. So I think this is all fine.

I'm not sure if the specific port would automatically force to use the specific protocol, especially if it is a custom port like 12345.

@jgraham

I've asked @jgraham as well why we didn't initially add a schema but we cannot remember.

So the interesting part is that no-one yet brought up an issue with a proxy regarding schema selection. Maybe that's really a niche thing that users have in place for their automation? Do you have an example where this is currently broken and needs to be fixed outside of a unit test for wpt?

If there is a use case we could definitely get a schema like property added, which probably should be optional so that we can keep backward compatibility.

Puppeteer allows for a string value in BrowserContextOptions. proxyServer. This string is equivalent of --proxy-server CLI argument, which allows for such scenarios:

Manual proxy settings can succinctly describe setups like:

Use proxy http://foo:8080 for all requests

Use proxy http://foo:8080 for all requests except those to a google.com subdomain.

Use proxy http://foo:8080 for all https:// requests, and proxy socsk5://mysocks:90 for everything else

So Chrome and Puppeteer supports proxy settings like http=https://foo:443;socks=socks5://mysocks:1080.

@whimboo

@whimboo @jgraham here is the proposed solution: #1922

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

The full IRC log of that discussion

<tidoust> Topic: Allow for specifying schema in "proxy"
<tidoust> github: https://github.com//issues/1920
<tidoust> sadym: We don't support a core feature supported in Chrome. You can proxy http over http, ssl over ssl, or socks over specific versions. But in Chrome, we can proxy http over https for example. That makes me propose a change in the API for the schema which allows schema to be provided for the proxy value.
<tidoust> ... I wanted to get feedback.
<jgraham> q?
<tidoust> jgraham: If it's supported in Gecko, it seems reasonable to be in WebDriver. It may be reasonable to have it in WebDriver even if it's not, provided that we can return something like "not supported".
<tidoust> sadym: It's kind of a breaking change due to where you specify the schema, but we can sort that out offline.

So these are 3 approaches:

Let's discuss which one we want to pursuit and I will wrap it up. I believe the last one provides the most flexibility, so that users can test all kinds of configurations they want.

@jgraham

As @jgraham wrote at #1922 (comment):

It seems like we more or less have two things: a source protocol (http, https, etc. or "all") and a destination proxy configuration, which consists of a proxy type, and a host address (host/ip and port) for the server.

I think the assumption that the meaning is clear just from a URL-like serialization of the destination proxy is unfounded. In particular there doesn't seem to be a socks scheme (or socks4 or socks5) at https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml and although it seems to be reasonably common that this serialization as a URL with a socks scheme works, I think we should perhaps be more explicit, unless we have something we can cite.

It's notably that no socks scheme seems to be standardised, or on a path to standardisation.

I'd strongly suggest against us using/supporting a non-standard scheme, even if there is precedent in implementations for this.

As far as I can tell, the origin might be cURL, which also accepts socks4a and socks5h as variants. Chrome's behaviour for the socks5 scheme seems to match cURL's behaviour for the socks5h scheme. I think this further shows the challenges of supporting such non-standard schemes.

Puppeteer is free to do whatever it wants — it can certainly accept such URLs and then parse them itself, passing them over WebDriver BiDi via their structured representations.

Puppeteer is free to do whatever it wants — it can certainly accept such URLs and then parse them itself, passing them over WebDriver BiDi via their structured representations.

Keeping socks protocol aside, let's focus on these scenarios:

proxy ssl via http;
proxy http to one and ssl to another proxy server.

These scenarios are supported by Chromium, and AFAIK by Safari and Firefox. However they are not configurable via WebDriver. In order to enable these scenarios, the WebDriver spec should be updated.

Alternative approach: #1936

The Browser Testing and Tools Working Group just discussed Proxy configuration.

The full IRC log of that discussion

<jgraham> Topic: Proxy configuration
<jgraham> github: https://github.com//issues/1920
<jgraham> sadym: We want to enable scenarios that are supported by all the browsers, different proxies for different traffic, different proxies for diffrerent protocols e.g. http via SSL, some traffic to one proxy some to another. Have proposed some solutions there. Are the scenarios mentioned supported by all browsers? Do we want to enable it? What the best
<jgraham> way to do it?
<tidoust> scribe+
<tidoust> jgraham: My concern is that it assumes that some schemes exist such as socks or socks5 that don't currently exist.
<tidoust> ... But the principle seems fine to me.
<jgraham> sadym: The updated protocol allows passing either a string or a detailed JSON object, like for unhandledPromptBehaviour
<jgraham> sadym: That would avoid defining a socks schema, so that should address the concern and be more extensible
<jgraham> jgraham: This addresses the concerns I had about coining new protocols or schemes. Historically the spec has been underdefined here, so if possible we should clean it up and have explicit outs for implementations that don't support specific configurations.
<jgraham> q?
<whimboo> q+
<jgraham> ack whimboo
<jgraham> whimboo: As long as we don't have compatibility issues I'm fine with these changes. If some browsers don't support all configurations that's fine. The cross-protocol configuration sounds good.
<jgraham> gsnedders: We need to make sure there are outs for implementations that don't support configuring certain schemes
<jgraham> action item to review the PR

Keeping socks protocol aside, let's focus on these scenarios:

proxy ssl via http;

proxy http to one and ssl to another proxy server.

These scenarios are supported by Chromium, and AFAIK by Safari and Firefox. However they are not configurable via WebDriver. In order to enable these scenarios, the WebDriver spec should be updated.

Safari doesn't support configuring any proxy via WebDriver, currently.

That said, the recommended API for proxy configuration for URLSessionConfiguration only supports a single HTTP CONNECT proxy (via init(httpCONNECTProxy:tlsOptions:)), effectively forcing the same proxy to be used for both HTTP and HTTPS.

The Browser Testing and Tools Working Group just discussed Proxy configuration.

The full IRC log of that discussion

<AutomatedTester> topic: Proxy configuration
<AutomatedTester> github: https://github.com//issues/1920
<AutomatedTester> sadym: we discussed this in the last meeting. I would like the PR to be reviewed. It uses the existing description of what proxy values
<AutomatedTester> ... it's an extension of the existing wording. I tried to update the wording but it didn't make much sense
<AutomatedTester> q?

Alternative approach: #1936

As it looks like the latest approach is actually #1937.

Navigation Menu

Repository navigation

Allow for protocol schema in proxy configuration #1920

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Allow for protocol schema in proxy configuration #1920

Description

Activity

whimboo commented on Aug 22, 2025

sadym-chromium commented on Aug 22, 2025

whimboo commented on Aug 28, 2025

sadym-chromium commented on Aug 28, 2025

sadym-chromium commented on Aug 29, 2025

css-meeting-bot commented on Sep 10, 2025

sadym-chromium commented on Dec 23, 2025

gsnedders commented on Dec 23, 2025

sadym-chromium commented on Dec 24, 2025

sadym-chromium commented on Jan 14, 2026

css-meeting-bot commented on Jan 14, 2026

gsnedders commented on Jan 14, 2026

css-meeting-bot commented on Feb 11, 2026

whimboo commented on Jul 8, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions