components/data_reduction_proxy/core/common/chrome_proxy_header.txt

The Chrome-Proxy header is used to convey client credentials and capabilities
to the Data Reduction Proxy and to receive instructions from it.

Background
----------

The Data Reduction Proxy is operated by Google for Chrome. Chrome is
configured to connect to it via TLS at proxy.googlezip.net:443 and via HTTP
at compress.googlezip.net:80. The Data Reduction Proxy only proxies HTTP
traffic from non-incognito tabs.

Chrome-Proxy Response Header
----------------------------

The Data Reduction Proxy uses the Chrome-Proxy response header to instruct
Chrome to bypass the proxy for a period of time and retry the request directly.
It may do so to shed load, when the requested URL is on a blacklist of
malicious or illegal resources, or when the request is for video, which the
proxy does not currently serve. Bypasses may be issued for other reasons as
well.

In order to bypass a proxy and make decisions about when requests should be
proxied and which proxy they should use, some proxies serve PAC scripts
themselves with a low HTTP cache timeout, and dynamically update the scripts
to direct users. This is the current state of the art, but the approach has many
drawbacks. Some clients ignore the HTTP caching headers for the PAC script. The
client's performance suffers because new PAC scripts must be interpreted after
every invalidation. Clients must also store (large) blacklists. Server design is
complicated by needing to decouple a request from the mechanism that would
bypass it (a PAC). Bypass fidelity is coarse meaning that bypass decisions can't
be made on a per-request basis. And bypass decisions must be made before the
request is sent, which isn't always possible, e.g., for domains the proxy hasn't
served before.

Instead, the Data Reduction Proxy sends one of a set of bypass directives in the
"Chrome-Proxy" header if it wants the client not to use it. Upon reception of
this header, the client may decide to retry the request with the proxy disabled
or cancel the request. Chrome cancels instead of retrying  non-idempotent
requests.

The "Chrome-Proxy" response header has the following format:

chrome-proxy           = "Chrome-Proxy" ":" 1#chrome-proxy-directive
chrome-proxy-directive = token [ "=" ( token / quoted-string ) ]

The header uses the definition of 'token' and 'quoted-string' from
https://datatracker.ietf.org/doc/rfc7230/

The directives have the following meanings:

bypass:     Argument syntax: delta-seconds
                             delta-seconds = 1*DIGIT (see: 1.2.1 of rfc7234)
            Bypass the currently configured proxy for specified number of
            seconds. If zero is specified, Chrome should use its default
            proxy bypass timeout, which is a random duration between 1 and 5
            minutes. If the TLS proxy is bypassed, Chrome will downgrade to
            using HTTP to connect to the Data Reduction Proxy. If the HTTP
            proxy is bypassed, Chrome will downgrade to using a DIRECT
            connection.
block:      Argument syntax: delta-seconds
            Bypass all Data Reduction Proxies for the specified number of
            seconds. If zero is specified, Chrome will use the default block
            timeout, which is a random time between 1 and 5 minutes.
block-once: Bypass all Data Reductions Proxies for this request only.

Currently, the directives are mutually exclusive, but the header format does
not require this. With "block-once", no token is expected.

If more than one directive is contained the header, then Chrome reacts to only
the highest priority directive. Priorities from highest to lowest are:
block > bypass > block-once.


Examples that respectively bypass the current proxy for seven seconds, bypass
both the TLS and HTTP proxies for Chrome's default proxy bypass duration, and
bypass the TLS and HTTP proxies only for the current request:

Chrome-Proxy: bypass=7
Chrome-Proxy: block=0
Chrome-Proxy: block-once


The Chrome-Proxy header is NOT hop-by-hop, and thus transparent proxies and
other intermediaries should not modify it. Further, only the Data Reduction
Proxy should add this header to responses.

Chrome-Proxy Request Header
---------------------------

The Chrome-Proxy request header is used to specify client capabilities and
credentials. It has the same form as the response header. The directives have
the following names and meanings:

ps:          Argument syntax: token
             A User-Agent-selected pseudorandom session ID.
sid:         Argument syntax: token
             A credential string.
b:           Argument syntax: 1*DIGIT
             The Chrome build number of the client
p:           Argument syntax: 1*DIGIT
             The Chrome patch number of the client
c:           Argument syntax: "android" / "ios" / "mac" / "win" / "linux" /
                              "chromeos" / "webview" 
             The type of client.

The values of the 'b', 'p', and 'c' directives can often be gleaned from the
user agent string, but not always, so they are sent explicitly. Each request
sent from Chrome to a Data Reduction Proxy contains a Chrome-Proxy header with
values for all five of these directives.

For example, for Chrome 38 on Android with a version 38.0.2125.114 (note the
'ps' and 'sid' values are representative):

Chrome-Proxy: ps=484343-123-4-9484, sid=he9wj3gjd03, b=2125, p=114, c=android