From 30bef173edcde9f348b77765f78eca9a9f155d67 Mon Sep 17 00:00:00 2001 From: Brian Pane Date: Fri, 26 Jan 2018 06:49:53 +0000 Subject: [PATCH 1/3] document the direct-response feature envoyproxy/envoy issue: [2315](https://github.com/envoyproxy/envoy/issues/2315) Signed-off-by: Brian Pane --- docs/root/intro/arch_overview/http_routing.rst | 2 ++ envoy/api/v2/route/route.proto | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/root/intro/arch_overview/http_routing.rst b/docs/root/intro/arch_overview/http_routing.rst index 5b514d1ca..def4a1d5d 100644 --- a/docs/root/intro/arch_overview/http_routing.rst +++ b/docs/root/intro/arch_overview/http_routing.rst @@ -24,6 +24,8 @@ request. The router filter supports the following features: level. * :ref:`Path `/:ref:`host ` redirection at the route level. +* :ref:`Direct HTTP responses `, + preconfigured responses generated by Envoy without proxying, at the route level. * :ref:`Explicit host rewriting `. * :ref:`Automatic host rewriting ` based on the DNS name of the selected upstream host. diff --git a/envoy/api/v2/route/route.proto b/envoy/api/v2/route/route.proto index ae13c4f4c..38582f227 100644 --- a/envoy/api/v2/route/route.proto +++ b/envoy/api/v2/route/route.proto @@ -167,7 +167,7 @@ message Route { // Return a redirect. RedirectAction redirect = 3; - // [#not-implemented-hide:] Return an arbitrary HTTP response directly, without proxying. + // Return an arbitrary HTTP response directly, without proxying. DirectResponseAction direct_response = 7; } From 01da2e5df7e2df2efdb8c98fe25dc4802fb86262 Mon Sep 17 00:00:00 2001 From: Brian Pane Date: Fri, 26 Jan 2018 18:49:41 +0000 Subject: [PATCH 2/3] fix doc build error and add more documentation on how direct responses work Signed-off-by: Brian Pane --- .../root/intro/arch_overview/http_routing.rst | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/root/intro/arch_overview/http_routing.rst b/docs/root/intro/arch_overview/http_routing.rst index def4a1d5d..9d94abfdb 100644 --- a/docs/root/intro/arch_overview/http_routing.rst +++ b/docs/root/intro/arch_overview/http_routing.rst @@ -24,8 +24,8 @@ request. The router filter supports the following features: level. * :ref:`Path `/:ref:`host ` redirection at the route level. -* :ref:`Direct HTTP responses `, - preconfigured responses generated by Envoy without proxying, at the route level. +* :ref:`Direct (non-proxied) HTTP responses ` + at the route level. * :ref:`Explicit host rewriting `. * :ref:`Automatic host rewriting ` based on the DNS name of the selected upstream host. @@ -94,3 +94,27 @@ an upstream host. In the future Envoy will likely support true HTTP/2 priority o connection. The currently supported priorities are *default* and *high*. + +.. _arch_overview_http_routing_direct_response: + +Direct responses +---------------- + +Envoy supports the sending of "direct" responses. These are preconfigured HTTP responses +that do not require proxying to an upstream server. + +There are two ways to specify a direct response in a Route: + +* Set the :ref:`direct_response ` field. + This works for all HTTP response statuses. +* Set the :ref:`redirect ` field. This works for + redirect response statuses only, but it simplifies the setting of the *Location* header. + +A direct response has an HTTP status code and an optional body. The Route configuration +can specify the response body inline or specify the pathname of a file containing the +body. If the Route configuration specifies a file pathname, Envoy will read the file +upon configuration load and cache the contents. Regardless of whether the body is +provided inline or in a file, the body length must be less than or equal to 4KB. + +If **response_headers_to_add** has been set for the Route or the enclosing Virtual Host, +Envoy will include the specified headers in the direct HTTP response. From dcd859eff2ae9f55a03e7546714e044c11599839 Mon Sep 17 00:00:00 2001 From: Brian Pane Date: Fri, 26 Jan 2018 21:52:01 +0000 Subject: [PATCH 3/3] Move 4KB limit to an "attention:" block Signed-off-by: Brian Pane --- docs/root/intro/arch_overview/http_routing.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/root/intro/arch_overview/http_routing.rst b/docs/root/intro/arch_overview/http_routing.rst index 9d94abfdb..2d7924da3 100644 --- a/docs/root/intro/arch_overview/http_routing.rst +++ b/docs/root/intro/arch_overview/http_routing.rst @@ -113,8 +113,14 @@ There are two ways to specify a direct response in a Route: A direct response has an HTTP status code and an optional body. The Route configuration can specify the response body inline or specify the pathname of a file containing the body. If the Route configuration specifies a file pathname, Envoy will read the file -upon configuration load and cache the contents. Regardless of whether the body is -provided inline or in a file, the body length must be less than or equal to 4KB. +upon configuration load and cache the contents. + +.. attention:: + + If a response body is specified, it must be no more than 4KB in size, regardless of + whether it is provided inline or in a file. Envoy currently holds the entirety of the + body in memory, so the 4KB limit is intended to keep the proxy's memory footprint + from growing too large. If **response_headers_to_add** has been set for the Route or the enclosing Virtual Host, Envoy will include the specified headers in the direct HTTP response.