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 9 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
67 changes: 48 additions & 19 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1623,8 +1623,7 @@ <h3>Proxy</h3>
<td>string
<td>Defines the proxy <a>host</a> for HTTP traffic when
Comment thread
sadym-chromium marked this conversation as resolved.
Outdated
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 url</a> for "<code>http</code>".
Comment thread
sadym-chromium marked this conversation as resolved.
Outdated
</tr>

<tr>
Expand All @@ -1640,34 +1639,64 @@ <h3>Proxy</h3>
<td>string
<td>Defines the proxy <a>host</a> 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 url</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 <a>host</a> for SOCKS traffic when the
Copy link
Copy Markdown
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 don't think it makes sense to talk about "SOCKS traffic". After establishing the proxy the traffic is just whatever data is being transmitted e.g. HTTP or HTTPS.

<a><code>proxyType</code></a> is "<code>manual</code>".
<td>A <a>proxy url</a> for "<code>socks</code>".
</tr>

<tr>
<td><code>socksVersion</code>
Copy link
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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 url</a>'s
<a>proxy scheme</a> is "<code>socks</code>".
Copy link
Copy Markdown
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
Copy Markdown
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 url</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>.
Copy link
Copy Markdown
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.

This is hard to read. Presumably there are three cases:

  • The string literal "direct"
  • A string containing "://", in which case it has the form {scheme}://{host}[:{port}
  • Any other string, in which case it has the form {host}[:{port}].

I think you need to specify in more detail how to parse the input to get the destination scheme, the destination host and destination port.


<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 and <var>port</var> is <code>80</code>,
Comment thread
sadym-chromium marked this conversation as resolved.
Outdated
let <var>scheme</var> be "<code>http</code>".

<li><p>If <var>scheme</var> is null and <var>port</var> is <code>443</code>,
let <var>scheme</var> be "<code>https</code>".

<li><p>If <var>scheme</var> is null and <var>port</var> is <code>1080</code>,
let <var>scheme</var> be "<code>socks</code>".

<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
Comment thread
sadym-chromium marked this conversation as resolved.
<a>default port</a>, this is the implied 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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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 +1749,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 url</a> with <a>proxy scheme</a>
"<code>socks</code>" and does not have an <a>own property</a>
Copy link
Copy Markdown
Contributor

@whimboo whimboo Dec 17, 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 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?

Copy link
Copy Markdown
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.

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.

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