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

[Maxim Dounin]

Hello!

On Mon, Oct 03, 2022 at 09:21:52PM +0100, Yaroslav Zhuravlev wrote:

> # 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.
> 
> 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>

That's bullshit.  No errors are reported "while reusing a 
connection".  If there is an already established cached 
connection, it is simply used.  Errors, if any, might happen 
later, while "passing a request to it".

[...]

> 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>

If an error occurs?

The "with a single server" clause looks wrong, we are talking 
about a group with only a single server here.  It probably should 
be either "with such server" or "the server" (probably "... with 
such server ... the server will be ..." would be good enough 
considering the whole sentence).

-- 
Maxim Dounin
http://mdounin.ru/