Mercurial > hg > nginx-site
changeset 2295:a1d0238ffb61
Updated HTTP and stream objects in Russian njs reference.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 27 Nov 2018 19:04:53 +0300 |
parents | 58df9b14b8ec |
children | e2e71f9477a8 |
files | xml/ru/docs/njs/reference.xml |
diffstat | 1 files changed, 247 insertions(+), 76 deletions(-) [+] |
line wrap: on
line diff
--- 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>