From d42de648316af462142d21a6fa157692930879dc Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Tue, 4 Apr 2023 17:55:22 -0700 Subject: [PATCH] [HTTP Proxy] Add user guide on how Core performs HTTP proxy determination (#32789) Forked from https://github.com/grpc/proposal/pull/349 --- doc/core/default_http_proxy_mapper.md | 67 +++++++++++++++++++++++++++ tools/doxygen/Doxyfile.core | 1 + tools/doxygen/Doxyfile.core.internal | 1 + 3 files changed, 69 insertions(+) create mode 100644 doc/core/default_http_proxy_mapper.md diff --git a/doc/core/default_http_proxy_mapper.md b/doc/core/default_http_proxy_mapper.md new file mode 100644 index 00000000000..4b0777b5ca3 --- /dev/null +++ b/doc/core/default_http_proxy_mapper.md @@ -0,0 +1,67 @@ +# Default HTTP Proxy Mapper User Guide for gRPC Core (and dependents) + +[A1-http-connect-proxy-support.md](https://github.com/grpc/proposal/blob/master/A1-http-connect-proxy-support.md) +proposed how gRPC supports TCP-level proxies via the HTTP CONNECT request, +defined in [RFC-2817](https://www.rfc-editor.org/rfc/rfc2817). + +**Case 1** in the proposal documents a use-case where all outbound traffic from +an environment must go through a proxy. Configurations for such environments are +usually performed using environment variables such as `http_proxy`. gRPC +supports this by providing a default proxy mapper implementation that allows for +overriding the server name (provided in the channel creation hostname) to +resolve based on such configurations. + +This guide documents gRPC C-Core's default proxy mapper implementation. + +## Working + +### Enabling HTTP Proxy + +C-Core checks the following places to determine the HTTP proxy to use, stopping +at the first one that is set: + +1. `GRPC_ARG_HTTP_PROXY` channel arg +2. `grpc_proxy` environment variable +3. `https_proxy` environment variable +4. `http_proxy` environment variable + +If none of the above are set, then no HTTP proxy will be used. + +The allowed format is an [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) URI +string where the scheme is expected to be "http" and the authority portion is +used to determine the proxy to be used. For example, for an HTTP proxy setting +of `http://username:password@proxy.google.com:443`, `username:password` would be +used as user credentials for proxy authentication as per +[RFC7617](https://www.rfc-editor.org/rfc/rfc7617) and `proxy.google.com:443` +would be the host:port HTTP proxy target. If the port part of the authority is +omitted, a default port of 443 is used. Note that user credential can also be +omitted if the proxy does not need authentication. + +### Disabling HTTP Proxy + +If an HTTP proxy is set, C-Core then checks the following places to exclude +traffic destined to listed hosts from going through the proxy determined above, +again stopping at the first one that is set: + +1. `no_grpc_proxy` environment variable +2. `no_proxy`environment variable + +If none of the above are set, then the previously found HTTP proxy is used. + +The format takes a comma-separated list of names, and if any of these names +matches as a suffix of the server host (provided in the channel target), then +the proxy will not be used for that target. For example, with a `grpc_proxy` +setting of `proxy.google.com` and a `no_grpc_proxy` setting of `example.com, +google.com`, channel targets such as `dns:///foo.google.com:50051` and +`bar.example.com:1234` will not use the proxy, but `baz.googleapis.com:443` +would still use the configured proxy `proxy.google.com`. + +As of [PR#31119](https://github.com/grpc/grpc/pull/31119), CIDR blocks are also +supported in the list of names. For example, a `no_proxy` setting of +`10.10.0.0/24` would not use the proxy for channel targets that mention IP +addresses as the host between the range `10.10.0.0` to `10.10.0.255`. + +### Disabling HTTP Proxy Channel-wide + +The lookup and subsequent usage of an HTTP proxy for a specific channel can also +be disabled by setting the channel arg `GRPC_ARG_ENABLE_HTTP_PROXY` to 0. diff --git a/tools/doxygen/Doxyfile.core b/tools/doxygen/Doxyfile.core index fb8c0ccca2c..97638f2fd97 100644 --- a/tools/doxygen/Doxyfile.core +++ b/tools/doxygen/Doxyfile.core @@ -772,6 +772,7 @@ doc/connection-backoff-interop-test-description.md \ doc/connection-backoff.md \ doc/connectivity-semantics-and-api.md \ doc/core/combiner-explainer.md \ +doc/core/default_http_proxy_mapper.md \ doc/core/epoll-polling-engine.md \ doc/core/grpc-client-server-polling-engine-usage.md \ doc/core/grpc-cq.md \ diff --git a/tools/doxygen/Doxyfile.core.internal b/tools/doxygen/Doxyfile.core.internal index 606d73d1a9c..d1de4b40f24 100644 --- a/tools/doxygen/Doxyfile.core.internal +++ b/tools/doxygen/Doxyfile.core.internal @@ -772,6 +772,7 @@ doc/connection-backoff-interop-test-description.md \ doc/connection-backoff.md \ doc/connectivity-semantics-and-api.md \ doc/core/combiner-explainer.md \ +doc/core/default_http_proxy_mapper.md \ doc/core/epoll-polling-engine.md \ doc/core/grpc-client-server-polling-engine-usage.md \ doc/core/grpc-cq.md \