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

[Yaroslav Zhuravlev]

> On 10 Oct 2022, at 00:55, Maxim Dounin <mdounin at mdounin.ru> wrote:
> 
> 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".
> 
> [...]

Thank you, these parts were removed from the patch.

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

Thanks, updated:

# HG changeset patch
# User Yaroslav Zhuravlev <yar at nginx.com>
# Date 1663861151 -3600
#      Thu Sep 22 16:39:11 2022 +0100
# Node ID 3b878f0c18cc277bfccb6095afd2cc7dc0cdec0f
# Parent  9708787aafc70744296baceb2aa0092401a4ef34
Documented behaviour of a single server in upstream with keepalive.

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">
 
@@ -350,7 +350,13 @@
 <note>
 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.
+are ignored, and such server will never be considered unavailable.
+If an error occurs
+while passing a request through
+a <link id="keepalive">keepalive</link> connection to such 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, the server will be selected again.
 </note>
 </para>
 
diff --git a/xml/ru/docs/http/ngx_http_upstream_module.xml b/xml/ru/docs/http/ngx_http_upstream_module.xml
--- a/xml/ru/docs/http/ngx_http_upstream_module.xml
+++ b/xml/ru/docs/http/ngx_http_upstream_module.xml
@@ -10,7 +10,7 @@
 <module name="Модуль ngx_http_upstream_module"
         link="/ru/docs/http/ngx_http_upstream_module.html"
         lang="ru"
-        rev="88">
+        rev="89">
 
 <section id="summary">
 
@@ -355,6 +355,12 @@
 Если в группе только один сервер, параметры <literal>max_fails</literal>,
 <literal>fail_timeout</literal> и <literal>slow_start</literal>
 игнорируются и такой сервер никогда не будет считаться недоступным.
+Если при отправке запроса по
+<link id="keepalive">постоянному</link> соединению к такому серверу
+происходит ошибка
+и разрешена передача запроса
+<link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream">следующему
+серверу</link> в случае ошибки, то сервер будет выбран снова.
 </note>
 </para>
 

> 
> -- 
> Maxim Dounin
> http://mdounin.ru/
> _______________________________________________
> nginx-devel mailing list -- nginx-devel at nginx.org
> To unsubscribe send an email to nginx-devel-leave at nginx.org