Documentation of the Chrome-Proxy header

Documents the format and meaning of the Chrome-Proxy header.

BUG=397713

Review URL: https://codereview.chromium.org/722793003

Cr-Commit-Position: refs/heads/master@{#306465}

1 files changed, 114 insertions, 0 deletions

diff --git a/components/data_reduction_proxy/core/common/chrome_proxy_header.txt b/components/data_reduction_proxy/core/common/chrome_proxy_header.txt
new file mode 100644
index 0000000..5a6a81c
--- /dev/null
+++ b/components/data_reduction_proxy/core/common/chrome_proxy_header.txt
@@ -0,0 +1,114 @@
+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