<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">

<article name="Справочник"
        link="/ru/docs/njs/reference.html"
        lang="ru"
        rev="1">

<section id="summary">

<para>
<link doc="index.xml">njs</link> предоставляет объекты, методы и свойства
для расширения функциональности nginx.
</para>

</section>


<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="string">байтовыми строками</link>.

<list type="tag">

<tag-name><literal>r.args{}</literal></tag-name>
<tag-desc>
объект аргументов запроса, только чтение
</tag-desc>

<tag-name><literal>r.error(<value>строка</value>)</literal></tag-name>
<tag-desc>
записывает <literal>строку</literal> в лог-файл ошибок
на уровне лога <literal>error</literal>
</tag-desc>

<tag-name><literal>r.finish()</literal></tag-name>
<tag-desc>
завершает отправку ответа клиенту
</tag-desc>

<tag-name><literal>r.headersIn{}</literal></tag-name>
<tag-desc>
объект входящих заголовков, только чтение.
<para>
Например, доступ к заголовку <literal>Foo</literal>
можно получить при помощи синтаксиса <literal>headersIn.foo</literal>
или <literal>headersIn['Foo']</literal>
</para>
</tag-desc>

<tag-name><literal>r.headersOut{}</literal></tag-name>
<tag-desc>
объект исходящих заголовков, доступно для записи.
<para>
Например, доступ к заголовку <literal>Foo</literal>
можно получить при помощи синтаксиса <literal>headersOut.foo</literal>
или <literal>headersOut['Foo']</literal>
</para>
</tag-desc>

<tag-name><literal>r.httpVersion</literal></tag-name>
<tag-desc>
версия HTTP, только чтение
</tag-desc>

<tag-name><literal>r.log(<value>строка</value>)</literal></tag-name>
<tag-desc>
записывает <literal>строку</literal> в лог-файл ошибок
на уровне лога <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 метод, только чтение
</tag-desc>

<tag-name><literal>r.parent</literal></tag-name>
<tag-desc>
ссылается на родительский объект запроса
</tag-desc>

<tag-name><literal>r.remoteAddress</literal></tag-name>
<tag-desc>
адрес клиента, только чтение
</tag-desc>

<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>, только чтение.
Размер <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>
<tag-desc>
отправляет
клиенту полный ответ с указанным <literal>кодом</literal>
<para>
Можно задать или URL перенаправления
(для кодов 301, 302, 303, 307 и 308),
или текст тела ответа (для остальных кодов) в качестве второго аргумента
</para>
</tag-desc>

<tag-name><literal>r.send(<value>строка</value>)</literal></tag-name>
<tag-desc>
отправляет часть тела ответа клиенту
</tag-desc>

<tag-name><literal>r.sendHeader()</literal></tag-name>
<tag-desc>
отправляет заголовки HTTP клиенту
</tag-desc>

<tag-name><literal>r.status</literal></tag-name>
<tag-desc>
статус, доступно для записи
</tag-desc>

<tag-name><literal>r.variables{}</literal></tag-name>
<tag-desc>
объект переменных nginx, только чтение
</tag-desc>

<tag-name><literal>r.warn(<value>строка</value>)</literal></tag-name>
<tag-desc>
записывает <literal>строку</literal> в лог-файл ошибок
на уровне лога <literal>warning</literal>
</tag-desc>

<tag-name><literal>r.uri</literal></tag-name>
<tag-desc>
текущий URI, только чтение
</tag-desc>

<tag-name id="subrequest"><literal>r.subrequest(<value>uri</value>[,
<value>options</value>[, <value>callback</value>]])</literal></tag-name>
<tag-desc>
создаёт подзапрос с заданными <literal>uri</literal> и
<literal>options</literal> и устанавливает
необязательный <literal>callback</literal> завершения.

<para>
Если <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>

</list>
</para>

<para>
<literal>callback</literal> получает
объект ответа подзапроса с методами и свойствами,
идентичными родительскому объекту запроса.
</para>
</tag-desc>

</list>
</para>

</section>


<section id="stream" name="Stream-сессия">

<para>
Объект stream-сессии доступен только в
модуле
<link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link>.
Все строки в объекте <literal>stream</literal> являются
<link id="string">байтовыми строками</link>.
</para>

<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 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 id="s_decline"><literal>s.decline()</literal></tag-name>
<tag-desc>
финализирует обработчик фазы и передаёт контроль следующему обработчику
(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>)
</tag-desc>

<tag-name id="s_deny"><literal>s.deny()</literal></tag-name>
<tag-desc>
финализирует обработчик фазы с кодом ошибки доступа
(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>)
</tag-desc>

<tag-name id="s_done"><literal>s.done</literal>(<value>[код]</value>)</tag-name>
<tag-desc>
успешно финализирует текущий обработчик фазы
или финализирует его с указанным числовым кодом
(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>).
</tag-desc>

<tag-name><literal>s.error(<value>строка</value>)</literal></tag-name>
<tag-desc>
записывает отправленную <literal>строку</literal> в лог-файл ошибок
на уровне лога <literal>error</literal>
</tag-desc>

<tag-name><literal>s.log(<value>строка</value>)</literal></tag-name>
<tag-desc>
записывает отправленную <value>строку</value> в лог-файл ошибок
на уровне лога <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>

</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>
текущий буфер, доступен для записи
<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>
</para>

</section>

</section>

</section>

</article>