Skip to content

Allow for specifying schema in "proxy" #1937

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

Open
sadym-chromium wants to merge 4 commits into
base: master
Choose a base branch
from
+93 −6
Open

Allow for specifying schema in "proxy" #1937

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
089060d
another approach
sadym-chromium Dec 23, 2025
29b39d9
example
sadym-chromium Dec 23, 2025
affe31f
Merge branch 'master' into sadym/proxy-3
sadym-chromium Feb 17, 2026
a9dfbbc
schema -> protocol
sadym-chromium Feb 17, 2026
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
99 changes: 93 additions & 6 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1618,13 +1618,24 @@ <h3>Proxy</h3>
<td>Any <a>URL</a>.
</tr>

<tr>
<td><dfn><code>proxyPerProtocol</code></dfn>
<td>JSON <a>Object</a> representing <a>proxy per protocol specifiers</a>
<td>Setting the specific <a>proxy specifier</a> per scheme or
"<code>default</code>" for all other not specified schemes when the
<a><code>proxyType</code></a> is "<code>manual</code>".
<td>A <a>valid proxy per protocol specifiers</a> mutually exclusive with other
scheme-specific proxy configurations ("<code>httpProxy</code>",
"<code>sslProxy</code>", "<code>socksProxy</code>").

@whimboo whimboo Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We probably should have a processing algorithm as for other parts of the spec to actually enforce mutual exclusivity with httpProxy/sslProxy/socksProxy, validate incoming values, or handle unknown/unsupported schemes. Without this, implementations have no normative guidance on what to do.

</tr>

<tr>
<td><code>httpProxy</code>
<td>string
<td>Defines the proxy <a>host</a> 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>host and optional port</a> for scheme "<code>http</code>". Mutually
exclusive with <a><code>proxyPerProtocol</code></a>.
</tr>

<tr>
Expand All @@ -1640,28 +1651,104 @@ <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>host and optional port</a> for scheme "<code>https</code>". Mutually
exclusive with <a><code>proxyPerProtocol</code></a>.
</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>A <a>host and optional port</a> with an <a>undefined</a> scheme. Mutually
exclusive with <a><code>proxyPerProtocol</code></a>.
</tr>

<tr>
<td><code>socksVersion</code>
<td>number
<td>Defines the <a>SOCKS proxy</a> version
when the <a><code>proxyType</code></a> is "<code>manual</code>".
<td>Any <a>integer</a> between 0 and 255 inclusive.
<td>Any <a>integer</a> between 0 and 255 inclusive. Mutually exclusive with
<a><code>proxyPerProtocol</code></a>.
</tr>

</table>

<p>A <dfn>proxy per protocol specifiers</dfn> is a JSON <a>Object</a> where each
key represents either a scheme to be proxied or a string
"<code>default</code>" for proxying traffic with not specified schemes, and
value is <a>proxy specifier</a> to be used as a proxy server for the traffic
with the given scheme. For example, the configuration below would proxy
HTTP traffic to "proxy.example.com:443" over HTTPS, HTTPS traffic to
"proxy.example.com:1080" over SOCKS4, and all other traffic to
"proxy.example.com:443" over SOCKS5:

<pre>
{
"http": {
"host": "proxy.example.com",
"port": 443,
"protocol": "https"
},
"https": {
"host": "proxy.example.com",
"port": 1080,
"protocol": "socks4"
},
"default": {
"host": "proxy.example.com",
"port": 443,
"protocol": "socks5"

@whimboo whimboo Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

If an implementation (e.g. Safari) cannot route "https" traffic through a SOCKS5 proxy, there is no specified error code or behavior.

}
}
</pre>

<p>A <a>proxy per protocol specifiers</a> is considered to be a
<dfn>valid proxy per protocol specifiers</dfn>, if each of it's

@whimboo whimboo Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
<dfn>valid proxy per protocol specifiers</dfn>, if each of it's
<dfn>valid proxy per protocol specifiers</dfn>, if each of its

<a>own property</a> is a non-empty <a>String</a>, and each of it's keys is a

@whimboo whimboo Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
<a>own property</a> is a non-empty <a>String</a>, and each of it's keys is a
<a>own property</a> is a non-empty <a>String</a>, and each of its keys is a

<a>valid proxy specifier</a>.

<p>A <dfn>proxy specifier</dfn> is a JSON <a>Object</a> with the following keys:
<table class=simple>
<thead>
<tr>
<th>Key
<th>Value Type
<th>Description
<th>Valid values
</tr>

<tr>
<td><code>host</code>
<td>string
<td>Defines the proxy server <a>host</a>.
<td>A valid <a>host</a> with optional
<a data-lt="includes credentials">credentials</a>.
</tr>

<tr>
<td><code>port</code>

@whimboo whimboo Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Many proxy protocols have well-known default ports. Making port mandatory is stricter than any existing proxy field. Should we have it optional?

<td>integer
<td>Defines the proxy server <a>port</a>.
<td>A valid <a>port</a>.
</tr>

<tr>
<td><code>protocol</code>
<td>string
<td>Defines the protocol to communicate with the proxy server.
<td>"<code>http</code>", "<code>ssl</code>", "<code>socks4</code>",
"<code>socks5</code>" or other implementation-specific proxy protocol.
</tr>
</table>

<p>A <a>proxy specifier</a> is considered to be a
<dfn>valid proxy specifier</dfn>, if it is a JSON <a>Object</a> and contains
<a>own properties</a> for each of the <a>proxy specifier</a>'s table's, and
each property contains a valid value, as defined in the
<a>proxy specifier</a>'s 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
Expand Down