Skip to content

Allow for specifying schema in "proxy" #1922

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
sadym-chromium wants to merge 13 commits into
base: master
Choose a base branch
from
Draft

Allow for specifying schema in "proxy" #1922

Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
d64580f
Inline "proxy" string configuration with Chromium implementation
sadym-chromium Aug 29, 2025
4a7ee1b
restrict proxy schema
sadym-chromium Aug 29, 2025
e6a351f
roll back socksProxy
sadym-chromium Aug 29, 2025
73f2d59
schemas
sadym-chromium Sep 12, 2025
3d84a8f
Update index.html
sadym-chromium Oct 1, 2025
1e0853d
s/schema/scheme
sadym-chromium Oct 1, 2025
b0a959b
`socksVersion` defines the protocol version for `socks` protocol
sadym-chromium Oct 1, 2025
b22e68f
default proxy protocol to the protocol to proxy
sadym-chromium Dec 9, 2025
63e21ca
fix note
sadym-chromium Dec 9, 2025
1cc6648
proxy specifier
sadym-chromium Dec 23, 2025
d43a0ee
proxy configuration
sadym-chromium Dec 23, 2025
df77dbc
remove detecting protocol by port
sadym-chromium Dec 23, 2025
e370abf
default port
sadym-chromium Dec 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 41 additions & 21 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1621,10 +1621,9 @@ <h3>Proxy</h3>
<tr>
<td><code>httpProxy</code>
<td>string
<td>Defines the proxy <a>host</a> for HTTP traffic when
<td>Defines the proxy configuration for HTTP traffic when
the <a><code>proxyType</code></a> is "<code>manual</code>".
<td>A <a>host and optional port</a> for
scheme "<code>http</code>".
<td>A <a>proxy specifier</a> for "<code>http</code>".
</tr>

<tr>
Expand All @@ -1638,36 +1637,57 @@ <h3>Proxy</h3>
<tr>
<td><code>sslProxy</code>
<td>string
<td>Defines the proxy <a>host</a> for encrypted TLS traffic
<td>Defines the proxy configuration for encrypted TLS traffic
when the <a><code>proxyType</code></a> is "<code>manual</code>".
<td>A <a>host and optional port</a> for
scheme "<code>https</code>".
<td>A <a>proxy specifier</a> "<code>https</code>".
</tr>

<tr>
<td><code>socksProxy</code>
<td>string
<td>Defines the proxy <a>host</a> for a <a>SOCKS proxy</a>
when the <a><code>proxyType</code></a> is "<code>manual</code>".
<td>A <a>host and optional port</a> with an <a>undefined</a> scheme.
<td>Defines the proxy configuration for SOCKS traffic when the
<a><code>proxyType</code></a> is "<code>manual</code>".
<td>A <a>proxy specifier</a> for "<code>socks</code>".
</tr>

<tr>
<td><code>socksVersion</code>
Copy link
Contributor

@whimboo whimboo Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@sadym-chromium sadym-chromium Sep 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@sadym-chromium sadym-chromium Sep 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@sadym-chromium sadym-chromium Sep 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@whimboo whimboo Sep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@sadym-chromium sadym-chromium Oct 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@sadym-chromium sadym-chromium Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

<td>number
<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 specifier</a>'s
<a>proxy scheme</a> is "<code>socks</code>".
Copy link
Contributor

@whimboo whimboo Dec 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@sadym-chromium sadym-chromium Dec 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

<td>Any <a>integer</a> between 0 and 255 inclusive.
</tr>

</table>

<p>A <dfn>host and optional port</dfn> for a <var>scheme</var> is
defined as being a valid <a>host</a>, optionally followed by a colon
and a valid <a>port</a>. The <a>host</a> may
<a data-lt="includes credentials">include credentials</a>. If the
port is omitted and <var>scheme</var> has a <a>default port</a>,
this is the implied port. Otherwise, the port is left undefined.
<p>A <dfn>proxy specifier</dfn> for <a>proxy scheme</a> <var>protocol</var> can
be either "<code>direct</code>" or a string consists of an optional
<a>proxy scheme</a> <var>scheme</var> followed by the string
"<code>://</code>", a valid <a>host</a> <var>host</var>, and optionally a
colon followed by a valid <a>port</a> <var>port</var>.

<p class=note>The <var>scheme</var> can be different from <var>protocol</var>.
If so, it means that the <var>protocol</var> traffic will be proxied via
<var>scheme</var>.

<ol>
<li><p>If <var>scheme</var> is omitted, let <var>scheme</var> be null.

<li><p>If <var>scheme</var> is null, let <var>scheme</var> be
<var>protocol</var>.

<li><p>If <var>scheme</var> is "<code>http</code>" or "<code>https</code>",
the <var>host</var> may
<a data-lt="includes credentials">include credentials</a>.

<li><p>If the <var>port</var> is omitted and <var>scheme</var> has a
<a>default port</a>, then <a>remote end</a> should use this port. Otherwise,
the <var>port</var> is left undefined.
</ol>

<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>".
Copy link
Contributor

@whimboo whimboo Dec 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@sadym-chromium sadym-chromium Dec 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@jgraham jgraham Dec 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this is incredibly poorly defined to begin with, but I think it's unclear from the specification text what the new semantics actually are.

If we want this to actually work, I think it's worth spending the time to define the right data structures to represent the configuration, even if it's a larger lift.

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.


<p>A <a><code>proxyType</code></a> of "<code>direct</code>" indicates
that the browser should not use a proxy at all.
Expand Down Expand Up @@ -1720,10 +1740,10 @@ <h3>Proxy</h3>
<a>own property</a> for "<code>proxyAutoconfigUrl</code>" return
an <a>error</a> with <a>error code</a> <a>invalid argument</a>.

<li><p>If <var>proxy</var> has an <a>own property</a> for
"<code>socksProxy</code>" and does not have an <a>own property</a>
for "<code>socksVersion</code>" return an <a>error</a> with <a>error
code</a> <a>invalid argument</a>.
<li><p>If <var>proxy</var> contains <a>proxy specifier</a> with
<a>proxy scheme</a> "<code>socks</code>" and does not have an
<a>own property</a> for "<code>socksVersion</code>", return an <a>error</a>
with <a>error code</a> <a>invalid argument</a>.

<li><p>Return <a>success</a> with data <var>proxy</var>.
</ol>
Expand Down