diff --git a/gateway/src/apicast/policy/request_unbuffered/README.md b/gateway/src/apicast/policy/request_unbuffered/README.md index 5b787df6d..e1d27051d 100644 --- a/gateway/src/apicast/policy/request_unbuffered/README.md +++ b/gateway/src/apicast/policy/request_unbuffered/README.md @@ -5,15 +5,13 @@ When enable this policy will dymanically sets the [`proxy_request_buffering: off`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_request_buffering ) directive per service. - ## Technical details -By default, NGINX reads the entire request body into memory (or buffers large requests into disk) before proxying it to the upstream server. However, reading bodies can become expensive, especially when requests with large payloads are sent. +By default, NGINX reads the entire request body into memory or buffers large requests to disk before forwarding them to the upstream server. Reading bodies can become expensive, especially when sending requests containing large payloads. -For example, when the client sends 10GB, NGINX will buffer the entire 10GB to disk before sending anything to -the upstream server. +For example, when the client sends 10GB, NGINX will buffer the entire 10GB to disk before sending anything to the upstream server. -When `proxy_request_buffering` is in the chain, request buffering will be disabled and the request body will be sent to the proxied server immediately as it received. This can help minimize time spent sending data to a service and disk I/O for requests with big body. However, there are caveats and corner cases applied, [**Caveats**](#caveats) +When the `request_unbuffered` is in the chain, request buffering is disabled, sending the request body to the proxied server immediately upon receiving it. This can help minimize time spent sending data to a service and disk I/O for requests with big body. However, there are caveats and corner cases applied, [**Caveats**](#caveats) The policy also provides a consistent behavior across multiple scenarios like: @@ -30,10 +28,15 @@ The policy also provides a consistent behavior across multiple scenarios like: ## Why don't we also support disable response buffering? -The response buffering is enabled by default in NGINX (the [`proxy_buffering: on`]() directive). It does -this to shield the backend against slow clients ([slowloris attack](https://en.wikipedia.org/wiki/Slowloris_(computer_security))). +The response buffering is enabled by default in NGINX (the [`proxy_buffering: on`]() directive). It does this to shield the backend against slow clients ([slowloris attack](https://en.wikipedia.org/wiki/Slowloris_(computer_security))). + +If the `proxy_buffering` is disabled, the upstream server keeps the connection open until all data is received by the client. NGINX [advises](https://www.nginx.com/blog/avoiding-top-10-nginx-configuration-mistakes/#proxy_buffering-off) against disabling `proxy_buffering` as it will potentially waste upstream server resources. + +## Why does upstream receive a "Content-Length" header when the original request is sent with "Transfer-Encoding: chunked" + +For a request with "small" body that fits into [`client_body_buffer_size`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size) and with header "Transfer-Encoding: chunked", NGINX will always read and know the length of the body. Then it will send the request to upstream with the "Content-Length" header. -If the `proxy_buffering` is disabled, the upstream server will be forced to keep the connection open until all data has been received by the client. Thereforce, NGINX [advises](https://www.nginx.com/blog/avoiding-top-10-nginx-configuration-mistakes/#proxy_buffering-off) against disabling `proxy_buffering` as it will potentially waste upstream server resources. +If a client uses chunked transfer encoding with HTTP/1.0, NGINX will always buffer the request body ## Example configuration @@ -89,11 +92,6 @@ Use with Camel Proxy policy ## Caveats -- Because APIcast allows defining mapping rules based on request content, ie `POST /some_path?a_param={a_value}` - will match a request like `POST "http://apicast_host:8080/some_path"` with a form URL-encoded body like: `a_param=abc` - , requests with `Content-type: application/x-www-form-urlencoded` will always be buffered regardless of the +- APIcast allows defining of mapping rules based on request content. For example, `POST /some_path?a_param={a_value}` will match a request like `POST "http://apicast_host:8080/some_path"` with a form URL-encoded body like: `a_param=abc`, requests with `Content-type: application/x-www-form-urlencoded` will always be buffered regardless of the `request_unbuffered` policy is enabled or not. -- For a request with "small" body that fits into [`client_body_buffer_size`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size) and with header "Transfer-Encoding: chunked", NGINX will always read and know the length of the body. - Then it will send the request to upstream with the "Content-Length" header. -- If a client uses chunked transfer encoding with HTTP/1.0, NGINX will always buffer the request body - Disable request buffering could potentially expose the backend to [slowloris attack](https://en.wikipedia.org/wiki/Slowloris_(computer_security)). Therefore, we recommend to only use this policy when needed.