# HG changeset patch
# User Yaroslav Zhuravlev <yar@nginx.com>
# Date 1543334693 -10800
# Node ID a1d0238ffb61e6a0acb11946f925d839ba04b6bc
# Parent  58df9b14b8ecc9015ed7c8e20044e5e075099144
Updated HTTP and stream objects in Russian njs reference.

diff -r 58df9b14b8ec -r a1d0238ffb61 xml/ru/docs/njs/reference.xml
--- a/xml/ru/docs/njs/reference.xml	Tue Nov 27 16:49:07 2018 +0300
+++ b/xml/ru/docs/njs/reference.xml	Tue Nov 27 19:04:53 2018 +0300
@@ -21,19 +21,17 @@
 </section>
 
 
-<section id="http" name="HTTP">
+<section id="http_stream" name="Объекты nginx">
+
+
+<section id="http" name="HTTP-запрос">
 
 <para>
 Объект <literal>HTTP</literal> доступен только в
 модуле <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link>.
 Все строки в объекте <literal>HTTP</literal> являются
-<link id="strings">байтовыми строками</link>.
-</para>
-
+<link id="string">байтовыми строками</link>.
 
-<section id="http_request" name="Запрос">
-
-<para>
 <list type="tag">
 
 <tag-name><literal>r.args{}</literal></tag-name>
@@ -54,11 +52,11 @@
 
 <tag-name><literal>r.headersIn{}</literal></tag-name>
 <tag-desc>
-объект исходящих заголовков, только чтение.
+объект входящих заголовков, только чтение.
 <para>
-Например, доступ к заголовку <literal>Header-Name</literal>
-можно получить при помощи синтаксиса <literal>headers['Header-Name']</literal>
-или <literal>headers.Header_name</literal>
+Например, доступ к заголовку <literal>Foo</literal>
+можно получить при помощи синтаксиса <literal>headersIn.foo</literal>
+или <literal>headersIn['Foo']</literal>
 </para>
 </tag-desc>
 
@@ -66,9 +64,9 @@
 <tag-desc>
 объект исходящих заголовков, доступно для записи.
 <para>
-Например, доступ к заголовку <literal>Header-Name</literal>
-можно получить при помощи синтаксиса <literal>headers['Header-Name']</literal>
-или <literal>headers.Header_name</literal>
+Например, доступ к заголовку <literal>Foo</literal>
+можно получить при помощи синтаксиса <literal>headersOut.foo</literal>
+или <literal>headersOut['Foo']</literal>
 </para>
 </tag-desc>
 
@@ -83,6 +81,13 @@
 на уровне лога <literal>info</literal>
 </tag-desc>
 
+<tag-name id="r_internal_redirect"><literal>r.internalRedirect(<value>uri</value>)</literal></tag-name>
+<tag-desc>
+осуществляет внутреннее перенаправление на указанный <literal>uri</literal>.
+Если uri начинается с префикса “<literal>@</literal>”,
+то он считается именованным location.
+</tag-desc>
+
 <tag-name><literal>r.method</literal></tag-name>
 <tag-desc>
 HTTP метод, только чтение
@@ -98,14 +103,22 @@
 адрес клиента, только чтение
 </tag-desc>
 
-<tag-name><literal>r.requestBody</literal></tag-name>
+<tag-name id="r_request_body"><literal>r.requestBody</literal></tag-name>
 <tag-desc>
-хранит тело запроса, только чтение
+возвращает тело запроса клиента, если оно не было
+записано во временный файл.
+Чтобы убедиться, что тело запроса клиента находится в памяти,
+его размер должен быть ограничен
+<link doc="../http/ngx_http_core_module.xml" id="client_max_body_size"/>,
+и также необходимо установить достаточный размер буфера при помощи
+<link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>.
 </tag-desc>
 
 <tag-name><literal>r.responseBody</literal></tag-name>
 <tag-desc>
-хранит тело ответа <link id="subrequest">подзапроса</link>, только чтение
+хранит тело ответа <link id="subrequest">подзапроса</link>, только чтение.
+Размер <literal>r.responseBody</literal> ограничивается директивой
+<link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/>.
 </tag-desc>
 
 <tag-name><literal>r.return(код[, строка])</literal></tag-name>
@@ -126,7 +139,7 @@
 
 <tag-name><literal>r.sendHeader()</literal></tag-name>
 <tag-desc>
-отправляет заголовок HTTP клиенту
+отправляет заголовки HTTP клиенту
 </tag-desc>
 
 <tag-name><literal>r.status</literal></tag-name>
@@ -134,7 +147,7 @@
 статус, доступно для записи
 </tag-desc>
 
-<tag-name><literal>req.variables{}</literal></tag-name>
+<tag-name><literal>r.variables{}</literal></tag-name>
 <tag-desc>
 объект переменных nginx, только чтение
 </tag-desc>
@@ -154,29 +167,27 @@
 <value>options</value>[, <value>callback</value>]])</literal></tag-name>
 <tag-desc>
 создаёт подзапрос с заданными <literal>uri</literal> и
-<literal>options</literal> и
-устанавливает необязательный <literal>callback</literal> завершения.
+<literal>options</literal> и устанавливает
+необязательный <literal>callback</literal> завершения.
 
 <para>
 Если <literal>options</literal> является строкой, то в ней
 содержится срока аргументов подзапроса.
-В противном случае ожидается, что <literal>options</literal> является объектом
-со следующими ключами:
-
+В противном случае ожидается, что <literal>options</literal> является
+объектом со следующими ключами:
 <list type="tag">
 <tag-name><literal>args</literal></tag-name>
 <tag-desc>
 строка с аргументами
 </tag-desc>
-
 <tag-name><literal>body</literal></tag-name>
 <tag-desc>
 тело запроса
 </tag-desc>
 
 <tag-name><literal>method</literal></tag-name>
-<tag-desc
->метод HTTP
+<tag-desc>
+метод HTTP
 </tag-desc>
 
 </list>
@@ -194,77 +205,57 @@
 
 </section>
 
-</section>
 
-
-<section id="stream" name="Stream">
+<section id="stream" name="Stream-сессия">
 
 <para>
-Объект <literal>stream</literal> доступен только в
+Объект stream-сессии доступен только в
 модуле
 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link>.
 Все строки в объекте <literal>stream</literal> являются
-<link id="strings">байтовыми строками</link>.
+<link id="string">байтовыми строками</link>.
 </para>
 
-
-<section id="stream_session" name="Сессия">
+<para>
+<note>
+До версии njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>,
+у объекта stream-сессии были некоторые свойства, которые на данный момент
+<link id="stream_obsolete">удалены</link>.
+</note>
+</para>
 
 <para>
 <list type="tag">
 
-<tag-name><literal>s.remoteAddress</literal></tag-name>
+<tag-name id="s_allow"><literal>s.allow()</literal></tag-name>
 <tag-desc>
-адрес клиента, только чтение
+успешно финализирует обработчик фазы
+(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>)
 </tag-desc>
 
-<tag-name><literal>s.eof</literal></tag-name>
-<tag-desc>
-логическое свойство,
-true, если текущий буфер является последним буфером,
-только чтение
-</tag-desc>
-
-<tag-name><literal>s.fromUpstream</literal></tag-name>
+<tag-name id="s_decline"><literal>s.decline()</literal></tag-name>
 <tag-desc>
-логическое свойство,
-true, если текущий буфер является буфером от проксируемого сервера к клиенту,
-только чтение
-</tag-desc>
-
-<tag-name><literal>s.buffer</literal></tag-name>
-<tag-desc>
-текущий буфер, доступен для записи
+финализирует обработчик фазы и передаёт контроль следующему обработчику
+(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>)
 </tag-desc>
 
-<tag-name><literal>s.variables{}</literal></tag-name>
+<tag-name id="s_deny"><literal>s.deny()</literal></tag-name>
 <tag-desc>
-объект переменных nginx, только чтение
-</tag-desc>
-
-<tag-name><literal>s.OK</literal></tag-name>
-<tag-desc>
-код <literal>OK</literal>
+финализирует обработчик фазы с кодом ошибки доступа
+(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>)
 </tag-desc>
 
-<tag-name><literal>s.DECLINED</literal></tag-name>
+<tag-name id="s_done"><literal>s.done</literal>(<value>[код]</value>)</tag-name>
 <tag-desc>
-код <literal>DECLINED</literal>
+успешно финализирует текущий обработчик фазы
+или финализирует его с указанным числовым кодом
+(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>).
 </tag-desc>
 
-<tag-name><literal>s.AGAIN</literal></tag-name>
-<tag-desc>
-код <literal>AGAIN</literal>
-</tag-desc>
-
-<tag-name><literal>s.ERROR</literal></tag-name>
+<tag-name><literal>s.error(<value>строка</value>)</literal></tag-name>
 <tag-desc>
-код <literal>ERROR</literal>
-</tag-desc>
-
-<tag-name><literal>s.ABORT</literal></tag-name>
-<tag-desc>
-код <literal>ABORT</literal>
+записывает отправленную <literal>строку</literal> в лог-файл ошибок
+на уровне лога <literal>error</literal>
 </tag-desc>
 
 <tag-name><literal>s.log(<value>строка</value>)</literal></tag-name>
@@ -273,16 +264,194 @@
 на уровне лога <literal>info</literal>
 </tag-desc>
 
+<tag-name id="s_off"><literal>s.off(<value>имяСобытия</value>)</literal></tag-name>
+<tag-desc>
+отменяет регистрацию callback'а, установленного методом
+<link id="s_on">s.on()</link>
+(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>)
+</tag-desc>
+
+<tag-name id="s_on"><literal>s.on(<value>событие</value>,
+<value>callback</value>)</literal></tag-name>
+<tag-desc>
+регистрирует <literal>callback</literal> для указанного <literal>события</literal>
+(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>).
+
+<para>
+<literal>Событием</literal> может являться одна из следующих строк:
+<list type="tag">
+<tag-name><literal>upload</literal></tag-name>
+<tag-desc>
+новые данные от клиента
+</tag-desc>
+
+<tag-name><literal>download</literal></tag-name>
+<tag-desc>
+новые данные к клиенту
+</tag-desc>
+
+</list>
+</para>
+
+<para>
+Callback завершения имеет следующий прототип:
+<literal>callback(данные, флаги)</literal>, где
+<literal>данные</literal> являются строкой,
+<literal>флаги</literal> являются объектом
+со следующими свойствами:
+<list type="tag">
+<tag-name id="s_on_callback_last"><literal>last</literal></tag-name>
+<tag-desc>
+логическое свойство,
+true, если данные являются последним буфером.
+</tag-desc>
+
+</list>
+</para>
+</tag-desc>
+
+<tag-name><literal>s.remoteAddress</literal></tag-name>
+<tag-desc>
+адрес клиента, только чтение
+</tag-desc>
+
+<tag-name id="s_send"><literal>s.send(<value>данные</value>[,
+<value>параметры</value>])</literal></tag-name>
+<tag-desc>
+отправляет данные клиенту
+(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>).
+<literal>Параметры</literal> являются объектом, используемым
+для переопределения флагов буфера nginx,
+полученных из буфера входных данных.
+Флаги могут быть переопределены при помощи следующих флагов:
+<para>
+<list type="tag">
+
+<tag-name><literal>last</literal></tag-name>
+<tag-desc>
+логическое свойство,
+true, если буфер является последним буфером
+</tag-desc>
+
+<tag-name><literal>flush</literal></tag-name>
+<tag-desc>
+логическое свойство,
+true, если буфер должен иметь флаг <literal>flush</literal>
+</tag-desc>
+</list>
+</para>
+Метод может быть вызван несколько раз в течение одного вызова callback'a.
+</tag-desc>
+
+<tag-name><literal>s.variables{}</literal></tag-name>
+<tag-desc>
+объект переменных nginx, только чтение
+</tag-desc>
+
 <tag-name><literal>s.warn(<value>строка</value>)</literal></tag-name>
 <tag-desc>
 записывает отправленную <literal>строку</literal> в лог-файл ошибок
 на уровне лога <literal>warning</literal>
 </tag-desc>
 
-<tag-name><literal>s.error(<value>строка</value>)</literal></tag-name>
+</list>
+</para>
+
+<section id="stream_obsolete" name="Устаревшие свойства">
+
+<para>
+Данные свойства были удалены
+в njs версии <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>
+и не имеют обратной совместимости с существующим кодом njs.
+</para>
+
+<para>
+<list type="tag">
+
+<tag-name id="s_abort"><literal>s.ABORT</literal></tag-name>
+<tag-desc>
+код <literal>ABORT</literal>
+<note>
+Начиная с версии njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>
+необходимо использовать метод <link id="s_deny">s.deny()</link>.
+</note>
+</tag-desc>
+
+<tag-name><literal>s.AGAIN</literal></tag-name>
+<tag-desc>
+код <literal>AGAIN</literal>
+<note>
+Начиная с версии njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>
+соответствующее поведение достигается, если не вызываются
+<link id="s_allow">s.allow()</link>,
+<link id="s_deny">s.deny()</link>,
+<link id="s_decline">s.decline()</link>,
+<link id="s_done">s.done()</link>
+и callback зарегистрирован.
+</note>
+</tag-desc>
+
+<tag-name id="s_buffer"><literal>s.buffer</literal></tag-name>
 <tag-desc>
-записывает отправленную <literal>строку</literal> в лог-файл ошибок
-на уровне лога <literal>error</literal>
+текущий буфер, доступен для записи
+<note>
+Начиная с версии njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>
+для записи необходимо использовать метод <link id="s_send">s.send()</link>.
+Для чтения текущий буфер доступен в качестве первого аргумента
+callback'а <literal>event</literal>.
+</note>
+</tag-desc>
+
+<tag-name><literal>s.DECLINED</literal></tag-name>
+<tag-desc>
+код <literal>DECLINED</literal>
+<note>
+Начиная с версии njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>
+необходимо использовать метод <link id="s_decline">s.decline()</link>.
+</note>
+</tag-desc>
+
+<tag-name><literal>s.eof</literal></tag-name>
+<tag-desc>
+логическое свойство,
+true, если текущий буфер является последним буфером,
+только чтение
+<note>
+Начиная с версии njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>
+необходимо использовать свойство <link id="s_on_callback_last">flags.last</link>.
+</note>
+</tag-desc>
+
+<tag-name><literal>s.ERROR</literal></tag-name>
+<tag-desc>
+код <literal>ERROR</literal>
+<note>
+Начиная с версии njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>
+для сообщения об ошибке используется соответствующее исключение.
+</note>
+</tag-desc>
+
+<tag-name><literal>s.fromUpstream</literal></tag-name>
+<tag-desc>
+логическое свойство,
+true, если текущий буфер является буфером от проксируемого сервера к клиенту,
+только чтение
+<note>
+Начиная с версии njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>
+необходимо использовать
+соответствующее <link id="s_on">событие</link>
+(<literal>upload</literal> или <literal>download</literal>)
+для обработки данных к клиенту или от клиента.
+</note>
+</tag-desc>
+
+<tag-name id="s_ok"><literal>s.OK</literal></tag-name>
+<tag-desc>
+код <literal>OK</literal>
+<note>
+Начиная с версии njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>
+необходимо использовать метод <link id="s_allow">s.allow()</link>.
+</note>
 </tag-desc>
 
 </list>
@@ -292,5 +461,7 @@
 
 </section>
 
+</section>
+
 </article>