[PATCH] Documented behaviour of a single server in upstream with keepalive

[Sergey Kandaurov]

> On 4 Oct 2022, at 00:21, Yaroslav Zhuravlev <yar at nginx.com> wrote:
> 
> xml/en/docs/http/ngx_http_fastcgi_module.xml  |  6 ++++--
> xml/en/docs/http/ngx_http_grpc_module.xml     |  6 ++++--
> xml/en/docs/http/ngx_http_proxy_module.xml    |  8 +++++---
> xml/en/docs/http/ngx_http_upstream_module.xml |  7 ++++++-
> 4 files changed, 19 insertions(+), 8 deletions(-)
> 
> 
> # HG changeset patch
> # User Yaroslav Zhuravlev <yar at nginx.com>
> # Date 1663861151 -3600
> #      Thu Sep 22 16:39:11 2022 +0100
> # Node ID aa3505dc76f13086703543cb079a13e48c57386e
> # Parent  9708787aafc70744296baceb2aa0092401a4ef34
> Documented behaviour of a single server in upstream with keepalive.

Translation needed.

> 
> diff --git a/xml/en/docs/http/ngx_http_fastcgi_module.xml b/xml/en/docs/http/ngx_http_fastcgi_module.xml
> --- a/xml/en/docs/http/ngx_http_fastcgi_module.xml
> +++ b/xml/en/docs/http/ngx_http_fastcgi_module.xml
> @@ -10,7 +10,7 @@
> <module name="Module ngx_http_fastcgi_module"
>         link="/en/docs/http/ngx_http_fastcgi_module.html"
>         lang="en"
> -        rev="53">
> +        rev="54">
> 
> <section id="summary">
> 
> @@ -1071,7 +1071,9 @@
> <list type="tag">
> 
> <tag-name><literal>error</literal></tag-name>
> -<tag-desc>an error occurred while establishing a connection with the
> +<tag-desc>an error occurred while establishing
> +or <link doc="ngx_http_upstream_module.xml" id="keepalive">reusing</link>
> +a connection with the
> server, passing a request to it, or reading the response header;</tag-desc>
> 
> <tag-name><literal>timeout</literal></tag-name>
> diff --git a/xml/en/docs/http/ngx_http_grpc_module.xml b/xml/en/docs/http/ngx_http_grpc_module.xml
> --- a/xml/en/docs/http/ngx_http_grpc_module.xml
> +++ b/xml/en/docs/http/ngx_http_grpc_module.xml
> @@ -10,7 +10,7 @@
> <module name="Module ngx_http_grpc_module"
>         link="/en/docs/http/ngx_http_grpc_module.html"
>         lang="en"
> -        rev="8">
> +        rev="9">
> 
> <section id="summary">
> 
> @@ -215,7 +215,9 @@
> <list type="tag">
> 
> <tag-name><literal>error</literal></tag-name>
> -<tag-desc>an error occurred while establishing a connection with the
> +<tag-desc>an error occurred while establishing
> +or <link doc="ngx_http_upstream_module.xml" id="keepalive">reusing</link>
> +a connection with the
> server, passing a request to it, or reading the response header;</tag-desc>
> 
> <tag-name><literal>timeout</literal></tag-name>
> diff --git a/xml/en/docs/http/ngx_http_proxy_module.xml b/xml/en/docs/http/ngx_http_proxy_module.xml
> --- a/xml/en/docs/http/ngx_http_proxy_module.xml
> +++ b/xml/en/docs/http/ngx_http_proxy_module.xml
> @@ -10,7 +10,7 @@
> <module name="Module ngx_http_proxy_module"
>         link="/en/docs/http/ngx_http_proxy_module.html"
>         lang="en"
> -        rev="75">
> +        rev="76">
> 
> <section id="summary">
> 
> @@ -1288,8 +1288,10 @@
> <list type="tag">
> 
> <tag-name><literal>error</literal></tag-name>
> -<tag-desc>an error occurred while establishing a connection with the
> -server, passing a request to it, or reading the response header;</tag-desc>
> +<tag-desc>an error occurred while establishing
> +or <link doc="ngx_http_upstream_module.xml" id="keepalive">reusing</link>
> +a connection with the
> +server, passing a request to it, reading the response header;</tag-desc>

change in this line is superfluous

> 
> <tag-name><literal>timeout</literal></tag-name>
> <tag-desc>a timeout has occurred while establishing a connection with the
> diff --git a/xml/en/docs/http/ngx_http_upstream_module.xml b/xml/en/docs/http/ngx_http_upstream_module.xml
> --- a/xml/en/docs/http/ngx_http_upstream_module.xml
> +++ b/xml/en/docs/http/ngx_http_upstream_module.xml
> @@ -10,7 +10,7 @@
> <module name="Module ngx_http_upstream_module"
>         link="/en/docs/http/ngx_http_upstream_module.html"
>         lang="en"
> -        rev="88">
> +        rev="89">
> 
> <section id="summary">
> 
> @@ -351,6 +351,11 @@
> If there is only a single server in a group, <literal>max_fails</literal>,
> <literal>fail_timeout</literal> and <literal>slow_start</literal> parameters
> are ignored, and such a server will never be considered unavailable.
> +If an error occurred while trying to reuse a
> +<link id="keepalive">keepalive</link> connection
> +with a single server, and the request is allowed to be passed to the
> +<link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream">next server</link>
> +on error, such server will be selected again.
> </note>
> </para>
> 

Overall, it's a good attempt to describe a specific behaviour seen
in the single server / keepalive / next upstream configuration.
It pops up when nginx sends a request in a cached keepalive
connection that enters the process of shutdown by backend.

-- 
Sergey Kandaurov