[PATCH 4 of 7] Documented lingering close in mail proxy

[Maxim Dounin]

# HG changeset patch
# User Maxim Dounin <mdounin at mdounin.ru>
# Date 1751860828 -10800
#      Mon Jul 07 07:00:28 2025 +0300
# Node ID 52042c2613a020b951bbf3e2bd77513a79b8f7a2
# Parent  b27605822bd1debade53f18223b604974e156127
Documented lingering close in mail proxy.

diff --git a/xml/en/docs/mail/ngx_mail_core_module.xml b/xml/en/docs/mail/ngx_mail_core_module.xml
--- a/xml/en/docs/mail/ngx_mail_core_module.xml
+++ b/xml/en/docs/mail/ngx_mail_core_module.xml
@@ -10,7 +10,7 @@
 <module name="Module ngx_mail_core_module"
         link="/en/docs/mail/ngx_mail_core_module.html"
         lang="en"
-        rev="25">
+        rev="26">
 
 <section id="summary">
 
@@ -116,6 +116,72 @@ after which further transmission to the 
 </directive>
 
 
+<directive name="lingering_close">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>on</default>
+<context>mail</context>
+<context>server</context>
+<appeared-in>1.29.0</appeared-in>
+
+<para>
+Controls how nginx closes client connections
+in case of errors, notably
+<link doc="ngx_mail_auth_http_module.xml">authentication errors</link>.
+</para>
+
+<para>
+The default value “<literal>on</literal>” instructs nginx to
+<link id="lingering_timeout">wait for</link> and
+<link id="lingering_time">process</link> additional data from the client
+before fully closing the connection.
+</para>
+
+<para>
+The value “<literal>off</literal>” tells nginx to do not wait for
+more data and close the connection immediately.
+</para>
+
+</directive>
+
+
+<directive name="lingering_time">
+<syntax><value>time</value></syntax>
+<default>30s</default>
+<context>mail</context>
+<context>server</context>
+<appeared-in>1.29.0</appeared-in>
+
+<para>
+When <link id="lingering_close"/> is in effect,
+this directive specifies the maximum time during which nginx
+will process (read and ignore) additional data coming from the client.
+After that, the connection will be closed, even if there will be
+more data.
+</para>
+
+</directive>
+
+
+<directive name="lingering_timeout">
+<syntax><value>time</value></syntax>
+<default>5s</default>
+<context>mail</context>
+<context>server</context>
+<appeared-in>1.29.0</appeared-in>
+
+<para>
+When <link id="lingering_close"/> is in effect, this directive specifies
+the maximum waiting time for more client data to arrive.
+If data are not received during this time, the connection is closed.
+Otherwise, the data are read and ignored, and nginx starts waiting
+for more data again.
+The “wait-read-ignore” cycle is repeated, but no longer than specified by the
+<link id="lingering_time"/> directive.
+</para>
+
+</directive>
+
+
 <directive name="listen">
 <syntax>
     <value>address</value>:<value>port</value>
diff --git a/xml/ru/docs/mail/ngx_mail_core_module.xml b/xml/ru/docs/mail/ngx_mail_core_module.xml
--- a/xml/ru/docs/mail/ngx_mail_core_module.xml
+++ b/xml/ru/docs/mail/ngx_mail_core_module.xml
@@ -10,7 +10,7 @@
 <module name="Модуль ngx_mail_core_module"
         link="/ru/docs/mail/ngx_mail_core_module.html"
         lang="ru"
-        rev="25">
+        rev="26">
 
 <section id="summary">
 
@@ -117,6 +117,74 @@ limit_rate_after 100m;
 </directive>
 
 
+<directive name="lingering_close">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>on</default>
+<context>mail</context>
+<context>server</context>
+<context>location</context>
+<appeared-in>1.29.0</appeared-in>
+
+<para>
+Управляет закрытием соединений с клиентами
+в случае ошибок, в частности
+<link doc="ngx_mail_auth_http_module.xml">ошибок аутентификации</link>.
+</para>
+
+<para>
+Со значением по умолчанию “<literal>on</literal>” nginx будет
+<link id="lingering_timeout">ждать</link> и
+<link id="lingering_time">обрабатывать</link> дополнительные данные,
+поступающие от клиента, перед полным закрытием соединения.
+</para>
+
+<para>
+Со значением “<literal>off</literal>” nginx не будет ждать поступления
+дополнительных данных и сразу же закроет соединение.
+</para>
+
+</directive>
+
+
+<directive name="lingering_time">
+<syntax><value>время</value></syntax>
+<default>30s</default>
+<context>mail</context>
+<context>server</context>
+<appeared-in>1.29.0</appeared-in>
+
+<para>
+Если действует <link id="lingering_close"/>,
+эта директива задаёт максимальное время, в течение которого nginx
+будет обрабатывать (читать и игнорировать) дополнительные данные,
+поступающие от клиента.
+По прошествии этого времени соединение будет закрыто, даже если
+будут ещё данные.
+</para>
+
+</directive>
+
+
+<directive name="lingering_timeout">
+<syntax><value>время</value></syntax>
+<default>5s</default>
+<context>mail</context>
+<context>server</context>
+<appeared-in>1.29.0</appeared-in>
+
+<para>
+Если действует <link id="lingering_close"/>, эта директива задаёт
+максимальное время ожидания поступления дополнительных данных от клиента.
+Если в течение этого времени данные не были получены, соединение закрывается.
+В противном случае данные читаются и игнорируются, и nginx снова
+ждёт поступления данных.
+Цикл “ждать-читать-игнорировать” повторяется, но не дольше чем задано
+директивой <link id="lingering_time"/>.
+</para>
+
+</directive>
+
+
 <directive name="listen">
 <syntax>
     <value>адрес</value>:<value>порт</value>