connect: docs and cleanup

api/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto

@@ -232,7 +232,7 @@ message HttpConnectionManager {
  // Determines if upgrades are enabled or disabled by default. Defaults to true.
  // This can be overridden on a per-route basis with :ref:`cluster
  // <envoy_api_field_route.RouteAction.upgrade_configs>` as documented in the
- // :ref:`upgrade documentation <arch_overview_websocket>`.
+ // :ref:`upgrade documentation <arch_overview_upgrades>`.
  google.protobuf.BoolValue enabled = 3;
  }
 

api/envoy/config/route/v3/route_components.proto

@@ -393,7 +393,6 @@ message RouteMatch {
  google.protobuf.BoolValue validated = 2;
  }
 
- // [#not-implemented-hide:]
  // An extensible message for matching CONNECT requests.
  message ConnectMatcher {
  }
@@ -427,14 +426,15 @@ message RouteMatch {
  // stripping. This needs more thought.]
  type.matcher.v3.RegexMatcher safe_regex = 10 [(validate.rules).message = {required: true}];
 
- // [#not-implemented-hide:]
  // If this is used as the matcher, the matcher will only match CONNECT requests.
  // Note that this will not match HTTP/2 upgrade-style CONNECT requests
  // (WebSocket and the like) as they are normalized in Envoy as HTTP/1.1 style
  // upgrades.
  // This is the only way to match CONNECT requests for HTTP/1.1. For HTTP/2,
  // where CONNECT requests may have a path, the path matchers will work if
  // there is a path present.
+ // Note that CONNECT support is currently considered alpha in Envoy.
+ // [#comment:TODO(htuch): Replace the above comment with an alpha tag.
  ConnectMatcher connect_matcher = 12;
  }
 
@@ -721,7 +721,6 @@ message RouteAction {
  option (udpa.annotations.versioning).previous_message_type =
  "envoy.api.v2.route.RouteAction.UpgradeConfig";
 
- // [#not-implemented-hide:]
  // Configuration for sending data upstream as a raw data payload. This is used for
  // CONNECT requests, when forwarding CONNECT payload as raw TCP.
  message ConnectConfig {
@@ -738,9 +737,10 @@ message RouteAction {
  // Determines if upgrades are available on this route. Defaults to true.
  google.protobuf.BoolValue enabled = 2;
 
- // [#not-implemented-hide:]
  // Configuration for sending data upstream as a raw data payload. This is used for
  // CONNECT requests, when forwarding CONNECT payload as raw TCP.
+ // Note that CONNECT support is currently considered alpha in Envoy.
+ // [#comment:TODO(htuch): Replace the above comment with an alpha tag.
  ConnectConfig connect_config = 3;
  }
 

api/envoy/config/route/v4alpha/route_components.proto

@@ -394,7 +394,6 @@ message RouteMatch {
  google.protobuf.BoolValue validated = 2;
  }
 
- // [#not-implemented-hide:]
  // An extensible message for matching CONNECT requests.
  message ConnectMatcher {
  option (udpa.annotations.versioning).previous_message_type =
@@ -430,14 +429,15 @@ message RouteMatch {
  // stripping. This needs more thought.]
  type.matcher.v4alpha.RegexMatcher safe_regex = 10 [(validate.rules).message = {required: true}];
 
- // [#not-implemented-hide:]
  // If this is used as the matcher, the matcher will only match CONNECT requests.
  // Note that this will not match HTTP/2 upgrade-style CONNECT requests
  // (WebSocket and the like) as they are normalized in Envoy as HTTP/1.1 style
  // upgrades.
  // This is the only way to match CONNECT requests for HTTP/1.1. For HTTP/2,
  // where CONNECT requests may have a path, the path matchers will work if
  // there is a path present.
+ // Note that CONNECT support is currently considered alpha in Envoy.
+ // [#comment:TODO(htuch): Replace the above comment with an alpha tag.
  ConnectMatcher connect_matcher = 12;
  }
 
@@ -724,7 +724,6 @@ message RouteAction {
  option (udpa.annotations.versioning).previous_message_type =
  "envoy.config.route.v3.RouteAction.UpgradeConfig";
 
- // [#not-implemented-hide:]
  // Configuration for sending data upstream as a raw data payload. This is used for
  // CONNECT requests, when forwarding CONNECT payload as raw TCP.
  message ConnectConfig {
@@ -744,9 +743,10 @@ message RouteAction {
  // Determines if upgrades are available on this route. Defaults to true.
  google.protobuf.BoolValue enabled = 2;
 
- // [#not-implemented-hide:]
  // Configuration for sending data upstream as a raw data payload. This is used for
  // CONNECT requests, when forwarding CONNECT payload as raw TCP.
+ // Note that CONNECT support is currently considered alpha in Envoy.
+ // [#comment:TODO(htuch): Replace the above comment with an alpha tag.
  ConnectConfig connect_config = 3;
  }
 

api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto

@@ -231,7 +231,7 @@ message HttpConnectionManager {
  // Determines if upgrades are enabled or disabled by default. Defaults to true.
  // This can be overridden on a per-route basis with :ref:`cluster
  // <envoy_api_field_config.route.v3.RouteAction.upgrade_configs>` as documented in the
- // :ref:`upgrade documentation <arch_overview_websocket>`.
+ // :ref:`upgrade documentation <arch_overview_upgrades>`.
  google.protobuf.BoolValue enabled = 3;
  }
 

api/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto

@@ -231,7 +231,7 @@ message HttpConnectionManager {
  // Determines if upgrades are enabled or disabled by default. Defaults to true.
  // This can be overridden on a per-route basis with :ref:`cluster
  // <envoy_api_field_config.route.v4alpha.RouteAction.upgrade_configs>` as documented in the
- // :ref:`upgrade documentation <arch_overview_websocket>`.
+ // :ref:`upgrade documentation <arch_overview_upgrades>`.
  google.protobuf.BoolValue enabled = 3;
  }
 

docs/root/intro/arch_overview/http/upgrades.rst

@@ -1,4 +1,4 @@
-.. _arch_overview_websocket:
+.. _arch_overview_upgrades:
 
 HTTP upgrades
 ===========================
@@ -62,44 +62,43 @@ a GET method on the final Envoy-Upstream hop.
 Note that the HTTP/2 upgrade path has very strict HTTP/1.1 compliance, so will not proxy WebSocket
 upgrade requests or responses with bodies.
 
-.. TODO(alyssawilk) unhide this when unhiding config
-.. CONNECT support
-.. ^^^^^^^^^^^^^^^
-
-.. Envoy CONNECT support is off by default (Envoy will send an internally generated 403 in response to
-.. CONNECT requests). CONNECT support can be enabled via the upgrade options described above, setting
-.. the upgrade value to the special keyword "CONNECT".
-
-.. While for HTTP/2, CONNECT request may have a path, in general and for HTTP/1.1 CONNECT requests do
-.. not have a path, and can only be matched using a
-.. :ref:`connect_matcher <envoy_api_field_route.RouteMatch.connect_matcher>`
-..
-.. Envoy can handle CONNECT in one of two ways, either proxying the CONNECT headers through as if they
-.. were any other request, and letting the upstream terminate the CONNECT request, or by terminating the
-.. CONNECT request, and forwarding the payload as raw TCP data. When CONNECT upgrade configuration is
-.. set up, the default behavior is to proxy the CONNECT request, treating it like any other request using
-.. the upgrade path.
-.. If termination is desired, this can be accomplished by setting
-.. :ref:`connect_config <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.UpgradeConfig.connect_config>`
-.. If it that message is present for CONNECT requests, the router filter will strip the request headers,
-.. and forward the HTTP payload upstream. On receipt of initial TCP data from upstream, the router
-.. will synthesize 200 response headers, and then forward the TCP data as the HTTP response body.
-
-.. .. warning::
-.. This mode of CONNECT support can create major security holes if configured correctly, as the upstream
-.. will be forwarded *unsanitized* headers if they are in the body payload. Please use with caution
-
-.. Tunneling TCP over HTTP/2
-.. ^^^^^^^^^^^^^^^^^^^^^^^^^
-.. Envoy also has support for transforming raw TCP into HTTP/2 CONNECT requests. This can be used to
-.. proxy multiplexed TCP over pre-warmed secure connections and amortize the cost of any TLS handshake.
-.. An example set up proxying SMTP would look something like this
-..
-.. [SMTP Upstream] --- raw SMTP --- [L2 Envoy] --- SMTP tunneled over HTTP/2 --- [L1 Envoy] --- raw SMTP --- [Client]
-..
-.. Examples of such a set up can be found in the Envoy example config `directory <https://github.com/envoyproxy/envoy/tree/master/configs/>`
-.. If you run `bazel-bin/source/exe/envoy-static --config-path configs/encapsulate_in_connect.yaml --base-id 1`
-.. and `bazel-bin/source/exe/envoy-static --config-path configs/terminate_connect.yaml`
-.. you will be running two Envoys, the first listening for TCP traffic on port 10000 and encapsulating it in an HTTP/2
-.. CONNECT request, and the second listening for HTTP/2 on 10001, stripping the CONNECT headers, and forwarding the
-.. original TCP upstream, in this case to google.com.
+CONNECT support
+^^^^^^^^^^^^^^^
+
+Envoy CONNECT support is off by default (Envoy will send an internally generated 403 in response to
+CONNECT requests). CONNECT support can be enabled via the upgrade options described above, setting
+the upgrade value to the special keyword "CONNECT".
+
+While for HTTP/2, CONNECT request may have a path, in general and for HTTP/1.1 CONNECT requests do
+not have a path, and can only be matched using a
+:ref:`connect_matcher <envoy_v3_api_msg_config.route.v3.RouteMatch.ConnectMatcher>`
+
+Envoy can handle CONNECT in one of two ways, either proxying the CONNECT headers through as if they
+were any other request, and letting the upstream terminate the CONNECT request, or by terminating the
+CONNECT request, and forwarding the payload as raw TCP data. When CONNECT upgrade configuration is
+set up, the default behavior is to proxy the CONNECT request, treating it like any other request using
+the upgrade path.
+If termination is desired, this can be accomplished by setting
+:ref:`connect_config <envoy_v3_api_field_config.route.v3.RouteAction.UpgradeConfig.connect_config>`
+If it that message is present for CONNECT requests, the router filter will strip the request headers,
+and forward the HTTP payload upstream. On receipt of initial TCP data from upstream, the router
+will synthesize 200 response headers, and then forward the TCP data as the HTTP response body.
+
+.. warning::
+ This mode of CONNECT support can create major security holes if configured correctly, as the upstream
+ will be forwarded *unsanitized* headers if they are in the body payload. Please use with caution
+
+Tunneling TCP over HTTP/2
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Envoy also has support for transforming raw TCP into HTTP/2 CONNECT requests. This can be used to
+proxy multiplexed TCP over pre-warmed secure connections and amortize the cost of any TLS handshake.
+An example set up proxying SMTP would look something like this
+
+[SMTP Upstream] --- raw SMTP --- [L2 Envoy] --- SMTP tunneled over HTTP/2 --- [L1 Envoy] --- raw SMTP --- [Client]
+
+Examples of such a set up can be found in the Envoy example config :repo:`directory <configs/>`
+If you run `bazel-bin/source/exe/envoy-static --config-path configs/encapsulate_in_connect.yaml --base-id 1`
+and `bazel-bin/source/exe/envoy-static --config-path configs/terminate_connect.yaml`
+you will be running two Envoys, the first listening for TCP traffic on port 10000 and encapsulating it in an HTTP/2
+CONNECT request, and the second listening for HTTP/2 on 10001, stripping the CONNECT headers, and forwarding the
+original TCP upstream, in this case to google.com.

docs/root/version_history/current.rst

@@ -21,6 +21,7 @@ Changes
 * gzip filter: added option to set zlib's next output buffer size.
 * health checks: allow configuring health check transport sockets by specifying :ref:`transport socket match criteria <envoy_v3_api_field_config.core.v3.HealthCheck.transport_socket_match_criteria>`.
 * http: added :ref:`stripping port from host header <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.strip_matching_host_port>` support.
+* http: added support for proxying CONNECT requests, terminating CONNECT requests, and converting raw TCP streams into HTTP/2 CONNECT requests. See :ref:`upgrade documentation<arch_overview_upgrades>` for details.
 * http: fixed a bug where in some cases slash was moved from path to query string when :ref:`merging of adjacent slashes<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.merge_slashes>` is enabled.
 * http: fixed a bug where the upgrade header was not cleared on responses to non-upgrade requests.
  Can be reverted temporarily by setting runtime feature `envoy.reloadable_features.fix_upgrade_response` to false.

docs/root/version_history/v1.4.0.rst

@@ -14,7 +14,7 @@ Changes
 * Hot restart :repo:`compile time flag </bazel#hot-restart>` added.
 * Original destination :ref:`cluster <arch_overview_service_discovery_types_original_destination>`
  and :ref:`load balancer <arch_overview_load_balancing_types_original_destination>` added.
-* :ref:`WebSocket <arch_overview_websocket>` is now supported.
+* :ref:`WebSocket <arch_overview_upgrades>` is now supported.
 * Virtual cluster priorities have been hard removed without deprecation as we are reasonably sure
  no one is using this feature.
 * Route `validate_clusters` option added.

test/integration/protocol_integration_test.cc

@@ -1789,8 +1789,6 @@ TEST_P(DownstreamProtocolIntegrationTest, ConnectIsBlocked) {
  Http::TestRequestHeaderMapImpl{{":method", "CONNECT"}, {":authority", "host.com:80"}});
 
  if (downstreamProtocol() == Http::CodecClient::Type::HTTP1) {
- // TODO(alyssawilk) either reinstate prior behavior, or include a release
- // note with this PR.
  // Because CONNECT requests for HTTP/1 do not include a path, they will fail
  // to find a route match and return a 404.
  response->waitForEndStream();