add documentation

Signed-off-by: Snow Pettersen <[email protected]>

docs/root/configuration/http_filters/grpc_http1_reverse_bridge_filter.rst

@@ -0,0 +1,35 @@
+.. _config_http_filters_grpc_reverse_bridge:
+
+gRPC HTTP/1.1 reverse bridge
+============================
+
+* gRPC :ref:`architecture overview <arch_overview_grpc>`
+* :ref:`v2 API reference <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpFilter.name>`
+* This filter should be configured with the name *envoy.grpc_http1_reverse_bridge*.
+
+This is a filter that enables converting an incoming gRPC request into a HTTP/1.1 request to allow a server
+that does not understand HTTP/2 or gRPC semantics to handle the request.
+
+The filter works by:
+
+* Checking the content type of the incoming request. If it's a gRPC request, the filter is enabled.
+* The content type is modified to a configurable value. This can be a noop by configuring ``application/grpc``.
+* The gRPC frame header is optionally stripped from the request body. The content length header will be adjusted if so.
+* On receiving a response, the content type of the response is validated and the status code is mapped to a grpc-status
+  which is inserted into the response trailers.
+* The response body is optionally prefixed by the gRPC frame header, again adjusting the content length header if necessary.
+
+Due to being mapped to HTTP/1.1, this filter will only work with unary gRPC calls.
+
+gRPC frame header management
+----------------------------
+
+By setting the withhold_grpc_frame option, the filer will assume that the upstream does not understand any gRPC semantics
+and will convert the request body into a simple binary encoding of the request body and perform the reverse conversion on
+the response body. This ends up simplifying the server side handling of these requests, as they no longer need to be concerned
+with parsing and generating gRPC formatted data.
+
+This works by stripping the gRPC frame header from the request body, while injecting a gRPC frame header in the response.
+
+If this feature is not used, the upstream must be ready to receive HTTP/1.1 requests prefixed with the gRPC frame header and
+respond with gRPC formatted responses.

docs/root/configuration/http_filters/http_filters.rst

@@ -12,6 +12,7 @@ HTTP filters
   ext_authz_filter
   fault_filter
   grpc_http1_bridge_filter
+  grpc_http1_reverse_bridge_filter
   grpc_json_transcoder_filter
   grpc_web_filter
   gzip_filter

docs/root/intro/arch_overview/grpc.rst

@@ -11,12 +11,8 @@ application layer:
 * gRPC makes use of HTTP/2 trailers to convey request status. Envoy is one of very few HTTP proxies
   that correctly supports HTTP/2 trailers and is thus one of the few proxies that can transport
   gRPC requests and responses.
-* The gRPC runtime for some languages is relatively immature. Envoy supports a gRPC :ref:`bridge
-  filter <config_http_filters_grpc_bridge>` that allows gRPC requests to be sent to Envoy over
-  HTTP/1.1. Envoy then translates the requests to HTTP/2 for transport to the target server.
-  The response is translated back to HTTP/1.1.
-* When installed, the bridge filter gathers per RPC statistics in addition to the standard array
-  of global HTTP statistics.
+* The gRPC runtime for some languages is relatively immature. See :ref:`below <_arch_overview_grpc_bridging>`
+  for an overview of filters that can help bring gRPC to more languages.
 * gRPC-Web is supported by a :ref:`filter <config_http_filters_grpc_web>` that allows a gRPC-Web
   client to send requests to Envoy over HTTP/1.1 and get proxied to a gRPC server. It's under
   active development and is expected to be the successor to the gRPC :ref:`bridge filter
@@ -25,6 +21,18 @@ application layer:
   that allows a RESTful JSON API client to send requests to Envoy over HTTP and get proxied to a
   gRPC service.
 
+.._arch_overview_grpc_bridging:
+
+gRPC bridging
+-------------
+Envoy supports two gRPC bridges:
+* :ref:`grpc_http1_bridge filter <config_http_filters_grpc_bridge>` which allows gRPC requests to be sent to Envoy over
+  HTTP/1.1. Envoy then translates the requests to HTTP/2 for transport to the target server. The response is translated back to HTTP/1.1.
+  When installed, the bridge filter gathers per RPC statistics in addition to the standard array of global HTTP statistics.
+* :ref:`grpc_http1_reverse_bridge filter <config_http_filters_grpc_reverse_bridge>` which allows gRPC requests to be sent to Envoy and
+  then translated to HTTP/1.1 when sent to the upstream. The response is then converted back into gRPC when sent to the downstream.
+  This filter can also optionally manage the gRPC frame header, allowing the upstream to not have to be gRPC aware at all.
+
 .. _arch_overview_grpc_services:
 
 gRPC services