<?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="52">

<section id="summary">

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

<para>
Справочник содержит описания методов, свойств и модулей,
доступных только в njs и не соответствующих стандарту ECMAScript.
Описания методов и свойств njs,
соответствующих стандарту, доступны в
<link url="http://www.ecma-international.org/ecma-262/">спецификации
ECMAScript</link>.
Список всех методов и свойств njs доступен в разделе
<link doc="compatibility.xml">Совместимость</link>.
</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 id="r_args"><literal>r.args{}</literal></tag-name>
<tag-desc>
объект аргументов запроса, только чтение
</tag-desc>

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

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

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

<para>
Заголовки запроса
<header>Authorization</header>,
<header>Content-Length</header>,
<header>Content-Range</header>,
<header>Content-Type</header>,
<header>ETag</header>,
<header>Expect</header>,
<header>From</header>,
<header>Host</header>,
<header>If-Match</header>,
<header>If-Modified-Since</header>,
<header>If-None-Match</header>,
<header>If-Range</header>,
<header>If-Unmodified-Since</header>,
<header>Max-Forwards</header>,
<header>Proxy-Authorization</header>,
<header>Referer</header>,
<header>Transfer-Encoding</header> и
<header>User-Agent</header>
могут иметь только одно значение поля
(<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
Дубликаты значений поля в заголовке запроса <header>Cookie</header>
разделяются точкой с запятой (<literal>;</literal>).
Дубликаты значений поля во всех остальных заголовках запроса
разделяются запятой.
</para>
</tag-desc>

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

<para>
Значения полей многозначных заголовков ответа
(<link doc="changes.xml" id="njs0.4.0">0.4.0</link>)
можно задать при помощи синтаксиса:
<example>
r.headersOut['Foo'] = ['a', 'b']
</example>
результат:
<example>
Foo: a
Foo: b
</example>
Все предыдущие значения поля заголовка ответа <header>Foo</header>
будут удалены.
</para>

<para>
В стандартных заголовках ответа,
поля которых могут принимать только одно значение, например
<header>Content-Type</header>,
учитывается только последний элемент массива.
Значения поля в заголовке ответа <header>Set-Cookie</header>
всегда возвращаются в виде массива.
Дубликаты значений поля в заголовках ответа
<header>Age</header>,
<header>Content-Encoding</header>,
<header>Content-Length</header>,
<header>Content-Type</header>,
<header>ETag</header>,
<header>Expires</header>,
<header>Last-Modified</header>,
<header>Location</header>,
<header>Retry-After</header>
игнорируются.
Дубликаты значений поля в других заголовках ответов
разделяются при помощи запятой.
</para>
</tag-desc>

<tag-name id="r_http_version"><literal>r.httpVersion</literal></tag-name>
<tag-desc>
версия HTTP, только чтение
</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 id="r_log"><literal>r.log(<value>строка</value>)</literal></tag-name>
<tag-desc>
записывает <literal>строку</literal> в лог-файл ошибок
на уровне лога <literal>info</literal>
</tag-desc>

<tag-name id="r_method"><literal>r.method</literal></tag-name>
<tag-desc>
HTTP метод, только чтение
</tag-desc>

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

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

<tag-name id="r_raw_headers_in"><literal>r.rawHeadersIn{}</literal></tag-name>
<tag-desc>
возвращает массив пар ключей и значений
таким же, каким он был получен от клиента
(<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
<para>
Например для следующих заголовков запроса:
<example>
Host: localhost
Foo:  bar
foo:  bar2
</example>
результат <literal>r.rawHeadersIn</literal>:
<example>
[
    ['Host', 'localhost'],
    ['Foo', 'bar'],
    ['foo', 'bar2']
]
</example>
Значения полей всех заголовков <literal>foo</literal>
можно получить при помощи синтаксиса:
<example>
r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1])
</example>
результат:
<example>
['bar', 'bar2']
</example>
Имена полей заголовков не приводятся к нижнему регистру,
дубликаты значений поля не объединяются.
</para>
</tag-desc>

<tag-name id="r_raw_headers_out"><literal>r.rawHeadersOut{}</literal></tag-name>
<tag-desc>
возвращает массив пар ключей и значений заголовков ответа
(<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
Имена полей заголовков не приводятся к нижнему регистру,
дубликаты значений поля не объединяются.
</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"/>.
Свойство доступно только в директиве
<link doc="../http/ngx_http_js_module.xml" id="js_content"/>.
</tag-desc>

<tag-name id="r_response_body"><literal>r.responseBody</literal></tag-name>
<tag-desc>
хранит тело ответа <link id="r_subrequest">подзапроса</link>, только чтение.
Размер <literal>r.responseBody</literal> ограничивается директивой
<link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/>.
</tag-desc>

<tag-name id="r_return"><literal>r.return(код[, строка])</literal></tag-name>
<tag-desc>
отправляет
клиенту полный ответ с указанным <literal>кодом</literal>
<para>
Можно задать или URL перенаправления
(для кодов 301, 302, 303, 307 и 308),
или текст тела ответа (для остальных кодов) в качестве второго аргумента
</para>
</tag-desc>

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

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

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

<tag-name id="r_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>
<link doc="../dev/development_guide.xml.xml" id="http_subrequests">Подзапрос</link>
использует входящие заголовки клиентского запроса.
Для отправки на проксируемый сервер заголовков, отличных от оригинальных,
может использоваться директива
<link doc="../http/ngx_http_proxy_module.xml" id="proxy_set_header"/>.
Для отправки на проксируемый сервер нового набора заголовков
может использоваться директива
<link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass_request_headers"/>.
</para>

<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, по умолчанию используется метод <literal>GET</literal>
</tag-desc>

<tag-name><literal>detached</literal></tag-name>
<tag-desc>
логический флаг (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>),
если <literal>true</literal>,
то создаваемый подзапрос является независимым подзапросом.
Ответы на независимые подзапросы игнорируются.
В отличие от обычных подзапросов независимый подзапрос
можно создать внутри обработчика переменной.
Флаг <literal>detached</literal> и аргумент <literal>callback</literal>
являются взаимоисключающими.
</tag-desc>

</list>
</para>

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

<para>
Начиная с версии njs <link doc="changes.xml" id="njs0.3.8">0.3.8</link>
если не указан <literal>callback</literal>,
то возвращается объект <literal>Promise</literal>,
который разрешается в объект ответа подзапроса.
</para>
</tag-desc>

<tag-name id="r_uri"><literal>r.uri</literal></tag-name>
<tag-desc>
текущий <link doc="../http/ngx_http_core_module.xml" id="var_uri">URI</link>
запроса в
<link doc="../http/ngx_http_core_module.xml" id="location">нормализованном</link>
виде, только чтение
</tag-desc>

<tag-name id="r_variables"><literal>r.variables{}</literal></tag-name>
<tag-desc>
объект переменных nginx, доступно для записи
(начиная с версии <link doc="changes.xml" id="njs0.2.8">0.2.8</link>)
</tag-desc>

<tag-name id="r_warn"><literal>r.warn(<value>строка</value>)</literal></tag-name>
<tag-desc>
записывает <literal>строку</literal> в лог-файл ошибок
на уровне лога <literal>warning</literal>
</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>
<list type="tag">

<tag-name id="s_allow"><literal>s.allow()</literal></tag-name>
<tag-desc>
успешно финализирует обработчик фазы
(<link doc="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="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="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="changes.xml" id="njs0.2.4">0.2.4</link>).
</tag-desc>

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

<tag-name id="s_log"><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="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="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 id="s_remote_address"><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="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 id="s_variables"><literal>s.variables{}</literal></tag-name>
<tag-desc>
объект переменных nginx, доступно для записи
(начиная с версии <link doc="changes.xml" id="njs0.2.8">0.2.8</link>)
</tag-desc>

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

</list>
</para>

</section>

</section>


<section id="core" name="Core">


<section id="core_global" name="Global">


<section id="process" name="Process">

<para>
Объект <literal>process</literal> является глобальным объектом,
предоставляющим информацию о текущем процессе
(<link doc="changes.xml" id="njs0.3.3">0.3.3</link>).
</para>

<para>
<list type="tag">

<tag-name id="process_argv"><literal>process.argv</literal></tag-name>
<tag-desc>
Возвращает массив, содержащий аргументы командной строки,
передаваемые в момент запуска текущего процесса.
</tag-desc>

<tag-name id="process_env"><literal>process.env</literal></tag-name>
<tag-desc>
Возвращает объект, содержащий переменные окружения пользователя.
<note>
По умолчанию nginx удаляет все переменные окружения, унаследованные
от своего родительского процесса, кроме переменной TZ.
Для сохранения части унаследованных переменных
необходимо использовать директиву <link doc="../ngx_core_module.xml" id="env"/>.
</note>
</tag-desc>

<tag-name id="process_pid"><literal>process.pid</literal></tag-name>
<tag-desc>
Возвращает PID текущего процесса.
</tag-desc>

<tag-name id="process_ppid"><literal>process.ppid</literal></tag-name>
<tag-desc>
Возвращает PID текущего родительского процесса.
</tag-desc>

</list>
</para>

</section>

</section>


<section id="string" name="String">

<para>
В njs существует два типа строк: строка Unicode (по умолчанию) и
байтовая строка.
</para>

<para>
Строка Unicode соответствует строке ECMAScript,
содержащей символы Unicode.
</para>

<para>
Байтовые строки содержат последовательность байт и
используются для сериализации строк Unicode
во внешние данные и десериализации из внешних источников.
Например метод <link id="string_toutf8">toUTF8()</link> сериализует
строку Unicode в байтовую строку используя кодировку UTF8:
<example>
>> '£'.toUTF8().toString('hex')
'c2a3'  /* C2 A3 является UTF8-представлением codepoint 00A3 ('£') */
</example>
Метод <link id="string_tobytes">toBytes()</link> сериализует
строку Unicode с codepoints до 255 в байтовую строку,
в противном случае возвращается <literal>null</literal>:
<example>
>> '£'.toBytes().toString('hex')
'a3'  /* a3 является байтом, равным codepoint 00A3 ('£')  */
</example>

<list type="tag">

<tag-name id="string_bytesfrom"><literal>String.bytesFrom(<value>массив</value>
| <value>строка</value>, <value>кодировка</value>)</literal></tag-name>
<tag-desc>
Создаёт байтовую строку или из массива, содержащего октеты,
или из кодированной строки
(<link doc="changes.xml" id="njs0.2.3">0.2.3</link>).
Кодировкой может быть
<literal>hex</literal>,
<literal>base64</literal> и
<literal>base64url</literal>.
<example>
>> String.bytesFrom([0x62, 0x75, 0x66, 0x66, 0x65, 0x72])
'buffer'

>> String.bytesFrom('YnVmZmVy', 'base64')
'buffer'
</example>
</tag-desc>

<tag-name id="string_frombytes"><literal>String.prototype.fromBytes(<value>начало</value>[,
<value>конец</value>])</literal></tag-name>
<tag-desc>
Возвращает новую строку Unicode из байтовой строки,
в которой каждый байт заменяется соответствующей Unicode codepoint.
</tag-desc>

<tag-name id="string_fromutf8"><literal>String.prototype.fromUTF8(<value>начало</value>[,
<value>конец</value>])</literal></tag-name>
<tag-desc>
Преобразует байтовую строку, содержащую валидную строку UTF8,
в строку Unicode,
иначе возвращается <literal>null</literal>.
</tag-desc>

<tag-name id="string_tobytes"><literal>String.prototype.toBytes(<value>начало</value>[,
<value>конец</value>])</literal></tag-name>
<tag-desc>
Сериализует строку Unicode в байтовую строку.
Возвращает <literal>null</literal>, если в строке найден символ больше, чем 255.
</tag-desc>

<tag-name id="string_tostring"><literal>String.prototype.toString(<value>кодировка</value>)</literal></tag-name>
<tag-desc>
<para>
Кодирует указанную строку в
<literal>hex</literal>,
<literal>base64</literal> или
<literal>base64url</literal>:
<example>
>>  'αβγδ'.toString('base64url')
'zrHOss6zzrQ'
</example>
До версии <link doc="changes.xml" id="njs0.4.3">0.4.3</link>
могла быть кодирована только <link id="string_tobytes">байтовая строка</link>:
<example>
>>  'αβγδ'.toUTF8().toString('base64url')
'zrHOss6zzrQ'
</example>
</para>
</tag-desc>

<tag-name id="string_toutf8"><literal>String.prototype.toUTF8(<value>начало</value>[,
<value>конец</value>])</literal></tag-name>
<tag-desc>
Сериализует строку Unicode
в байтовую строку при помощи кодирования UTF8.
<example>
>> 'αβγδ'.toUTF8().length
8
>> 'αβγδ'.length
4
</example>
</tag-desc>

</list>
</para>

</section>


<section id="njs_api_timers" name="Timers">

<para>
<list type="tag">

<tag-name id="cleartimeout"><literal>clearTimeout(<value>timeout</value>)</literal></tag-name>
<tag-desc>
Отменяет объект <literal>timeout</literal>,
созданный <link id="settimeout"><literal>setTimeout()</literal></link>.
</tag-desc>

<tag-name id="settimeout"><literal>setTimeout(<value>функция</value>,
<value>миллисекунды</value>[,
<value>аргумент1</value>,
<value>аргументN</value>])</literal></tag-name>
<tag-desc>
Вызывает <literal>функцию</literal>
по прошествии указанного количества <literal>миллисекунд</literal>.
Указанной функции можно передать
один или более необязательных <literal>аргументов</literal>.
Возвращает объект <literal>timeout</literal>.
<example>
function handler(v)
{
    // ...
}

t = setTimeout(handler, 12);

// ...

clearTimeout(t);
</example>
</tag-desc>

</list>
</para>

</section>

</section>


<section id="built-in" name="Встроенные модули">

<section id="crypto" name="Crypto">

<para>
Модуль Crypto предоставляет поддержку криптографических функций.
Объект модуля Crypto доступен через <literal>require('crypto')</literal>.
</para>

<para>
<list type="tag">

<tag-name id="crypto_createhash"><literal>crypto.createHash(<value>алгоритм</value>)</literal></tag-name>
<tag-desc>
Создаёт и возвращает объект <link id="crypto_hash">Hash</link>,
который может использоваться для создания hash digests
при помощи указанного <value>алгоритма</value>.
Алгоритмом может быть
<literal>md5</literal>,
<literal>sha1</literal> и
<literal>sha256</literal>.
</tag-desc>

<tag-name id="crypto_createhmac"><literal>crypto.createHmac(<value>алгоритм</value>,
<value>секретный ключ</value>)</literal></tag-name>
<tag-desc>
Создаёт и возвращает объект <link id="crypto_hmac">HMAC</link>, который
использует заданный <value>алгоритм</value> и <value>секретный ключ</value>.
Алгоритм может быть
<literal>md5</literal>,
<literal>sha1</literal> и
<literal>sha256</literal>.
</tag-desc>

</list>
</para>


<section id="crypto_hash" name="Hash">

<para>
<list type="tag">

<tag-name><literal>hash.update(<value>данные</value>)</literal></tag-name>
<tag-desc>
Обновляет содержимое хэша с передаваемыми <value>данными</value>.
</tag-desc>

<tag-name><literal>hash.digest([<value>кодировка</value>])</literal></tag-name>
<tag-desc>
Подсчитывает дайджест всех данных, передаваемых при помощи
<literal>hash.update()</literal>.
Кодировка может быть
<literal>hex</literal>,
<literal>base64</literal> и
<literal>base64url</literal>.
Если кодировка не указана, то будет возвращена байтовая строка.
</tag-desc>

</list>
</para>

<para>
<example>
>> var cr = require('crypto')
undefined

>> cr.createHash('sha1').update('A').update('B').digest('base64url')
'BtlFlCqiamG-GMPiK_GbvKjdK10'
</example>
</para>

</section>


<section id="crypto_hmac" name="HMAC">

<para>
<list type="tag">

<tag-name><literal>hmac.update(<value>данные</value>)</literal></tag-name>
<tag-desc>
Обновляет содержимое HMAC с передаваемыми <value>данными</value>.
</tag-desc>

<tag-name><literal>hmac.digest([<value>кодировка</value>])</literal></tag-name>
<tag-desc>
Подсчитывает HMAC-дайджест всех данных, передаваемых при помощи
<literal>hmac.update()</literal>.
Кодировка может быть
<literal>hex</literal>,
<literal>base64</literal> и
<literal>base64url</literal>.
Если кодировка не указана, то будет возвращена байтовая строка.
</tag-desc>
</list>
</para>

<para>
<example>
>> var cr = require('crypto')
undefined

>> cr.createHmac('sha1', 'secret.key').update('AB').digest('base64url')
'Oglm93xn23_MkiaEq_e9u8zk374'
</example>
</para>

</section>

</section>


<section id="njs_api_fs" name="File System">

<para>
Модуль File System предоставляет набор функций для операций с файлами.
</para>

<para>
Объект модуля доступен через <literal>require('fs')</literal>.
Начиная с версии <link doc="changes.xml" id="njs0.3.9">0.3.9</link>
доступны промисифицированные версии методов file system через
объект <literal>require('fs').promises</literal>:
<example>
> var fs = require('fs').promises;
undefined
> fs.readFile("/file/path").then((data)=>console.log(data))
&lt;file data&gt;
</example>
<list type="tag">

<tag-name id="fs_accesssync"><literal>accessSync(<value>путь</value>[,
<value>mode</value>])</literal></tag-name>
<tag-desc>
Синхронно проверяет разрешения для файла или каталога,
указанного в <literal>пути</literal>
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
Если проверка не удалась, то будет возвращена ошибка,
в противном случае метод возвратит undefined.
<list type="tag">

<tag-name><literal>mode</literal></tag-name>
<tag-desc>
По умолчанию
<link id="access_const"><literal>fs.constants.F_OK</literal></link>.
Является необязательным числом,
которое задаёт выполнение проверок доступа.
<example>
try {
    fs.accessSync('/file/path', fs.constants.R_OK | fs.constants.W_OK);
    console.log('has access');
} catch (e) {
    console.log('no access');)
}
</example>
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_appendfilesync"><literal>appendFileSync(<value>имяФайла</value>,
<value>данные</value>[, <value>options</value>])</literal></tag-name>
<tag-desc>
Синхронно добавляет указанные <literal>данные</literal>
в файл с указанным <literal>именем</literal>.
Если файл не существует, то он будет создан.
Параметр <literal>options</literal> должен быть
объектом со следующими ключами:
<list type="tag">

<tag-name><literal>режим</literal></tag-name>
<tag-desc>
режим, по умолчанию <literal>0o666</literal>
</tag-desc>

<tag-name><literal>флаг</literal></tag-name>
<tag-desc>
<link id="njs_api_fs_flags">флаг</link> файловой системы,
по умолчанию <literal>a</literal>
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_mkdirsync"><literal>mkdirSync(<value>путь</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Синхронно создаёт каталог по указанному <literal>пути</literal>
(<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
Параметр <literal>options</literal> должен быть
<literal>числом</literal>, которое задаёт
<link id="fs_mkdirsync_mode">режим</link>,
или объектом с ключами:
<list type="tag">

<tag-name id="fs_mkdirsync_mode"><literal>режим</literal></tag-name>
<tag-desc>
режим, по умолчанию <literal>0o777</literal>.
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_readdirsync"><literal>readdirSync(<value>путь</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Синхронно читает содержимое каталога
по указанному <literal>пути</literal>
(<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
Параметр <literal>options</literal> должен быть
строкой, определяющей <link id="fs_readdirsync_encoding">кодировку</link>
или объектом с ключами:
<list type="tag">

<tag-name id="fs_readdirsync_encoding"><literal>кодировка</literal></tag-name>
<tag-desc>
кодировка, по умолчанию не указана.
Кодировка может быть <literal>utf8</literal>.
</tag-desc>

<tag-name id="fs_readdirsync_withfiletypes"><literal>withFileTypes</literal></tag-name>
<tag-desc>
если <literal>true</literal>, то массив файлов будет содержать
объекты <link id="fs_dirent"><literal>fs.Dirent</literal></link>,
по умолчанию <literal>false</literal>.
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_readfilesync"><literal>readFileSync(<value>имяФайла</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Синхронно возвращает содержимое файла
с указанным <literal>именем</literal>.
Параметр <literal>options</literal> хранит
<literal>строку</literal>, которая задаёт кодировку.
Если кодировка не указана,
то будет возвращена <link id="string_tobytes">байтовая строка</link>.
Если указана кодировка <literal>utf8</literal>,
то будет возвращена строка Unicode.
Иначе ожидается, что <literal>options</literal> является
объектом с ключами:
<list type="tag">

<tag-name><literal>кодировка</literal></tag-name>
<tag-desc>
кодировка, по умолчанию не указана.
Кодировка может быть <literal>utf8</literal>
</tag-desc>

<tag-name><literal>флаг</literal></tag-name>
<tag-desc>
<link id="njs_api_fs_flags">флаг</link> файловой системы,
по умолчанию <literal>r</literal>
</tag-desc>

</list>
<example>
>> var fs = require('fs')
undefined
>> var file = fs.readFileSync('/file/path.tar.gz')
undefined
>> var gzipped = /^\x1f\x8b/.test(file); gzipped
true
</example>
</tag-desc>

<tag-name id="fs_realpathsync"><literal>realpathSync(<value>путь</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Синхронно вычисляет канонический путь при помощи преобразования
<literal>.</literal>, <literal>..</literal> и символических ссылок используя
<link url="http://man7.org/linux/man-pages/man3/realpath.3.html">realpath(3)</link>.
Аргумент <literal>options</literal> может быть строкой, определяющей кодировку,
или объектом со свойством encoding, определяющим символьную кодировку,
которая используется для передачи пути обратному вызову
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
</tag-desc>

<tag-name id="fs_renamesync"><literal>renameSync(<value>старыйПуть</value>,
<value>новыйПуть</value>)</literal></tag-name>
<tag-desc>
Синхронно меняет имя или местоположение файла.
(<link doc="changes.xml" id="njs0.3.4">0.3.4</link>).
<example>
>> var fs = require('fs')
undefined
>> var file = fs.renameSync('hello.txt', 'HelloWorld.txt')
undefined
</example>
</tag-desc>

<tag-name id="fs_rmdirsync"><literal>rmdirSync(<value>путь</value>)</literal></tag-name>
<tag-desc>
Синхронно удаляет каталог по указанному <literal>пути</literal>
(<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
</tag-desc>

<tag-name id="fs_symlinksync"><literal>symlinkSync(<value>цель</value>,
<value>path</value>)</literal></tag-name>
<tag-desc>
Синхронно создаёт ссылку с именем <literal>путь</literal>,
указывающую на <literal>цель</literal> при помощи
<link url="http://man7.org/linux/man-pages/man2/symlink.2.html">symlink(2)</link>
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
Относительные цели считаются относительно корневого каталога ссылки.
</tag-desc>

<tag-name id="fs_unlinksync"><literal>unlinkSync(<value>путь</value>)</literal></tag-name>
<tag-desc>
Синхронно удаляет файл по указанному <literal>пути</literal>
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
</tag-desc>

<tag-name id="fs_writefilesync"><literal>writeFileSync(<value>имяФайла</value>,
<value>данные</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Синхронно записывает <literal>данные</literal> в файл
с указанным <literal>именем</literal>.
Если файл не существует, то он будет создан.
Если файл существует, то он будет заменён.
Параметр <literal>options</literal> должен быть
объектом с ключами:
<list type="tag">
<tag-name><literal>режим</literal></tag-name>
<tag-desc>
режим, по умолчанию <literal>0o666</literal>
</tag-desc>

<tag-name><literal>флаг</literal></tag-name>
<tag-desc>
<link id="njs_api_fs_flags">флаг</link> файловой системы,
по умолчанию <literal>w</literal>
</tag-desc>

</list>
<example>
>> var fs = require('fs')
undefined
>> var file = fs.writeFileSync('hello.txt', 'Hello world')
undefined
</example>
</tag-desc>

</list>
</para>


<section id="fs_dirent" name="fs.Dirent">

<para>
<literal>fs.Dirent</literal> является представлением записи каталога&mdash;
файлом или подкаталогом .
В случае, если
<link id="fs_readdirsync"><literal>readdirSync()</literal></link>
вызывается с опцией
<link id="fs_readdirsync_withfiletypes"><literal>withFileTypes</literal></link>
получившийся массив содержит объекты <literal>fs.Dirent</literal>.

<list type= "bullet" compact="no">

<listitem>
<literal>dirent.isBlockDevice()</literal>&mdash;возвращает
<literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает
блочное устройство
</listitem>

<listitem>
<literal>dirent.isCharacterDevice()</literal>&mdash;возвращает
<literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает
символьное устройство.
</listitem>

<listitem>
<literal>dirent.isDirectory()</literal>&mdash;возвращает
<literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает
каталог файловой системы.
</listitem>

<listitem>
<literal>dirent.isFIFO()</literal>&mdash;возвращает
<literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает
FIFO-канал.
</listitem>

<listitem>
<literal>dirent.isFile()</literal>&mdash;возвращает
<literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает
обычный файл.
</listitem>

<listitem>
<literal>dirent.isSocket()</literal>&mdash;возвращает
<literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает
сокет.
</listitem>

<listitem>
<literal>dirent.isSymbolicLink()</literal>&mdash;возвращает
<literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает
символическую ссылку.
</listitem>

<listitem>
<literal>dirent.name</literal>&mdash;
имя файла, на которое ссылается объект <literal>fs.Dirent</literal>.
</listitem>

</list>
</para>

</section>


<section id="access_const" name="Константы доступа к файлу">

<para>
Метод <link id="fs_accesssync"><literal>access()</literal></link>
может принимать следующие флаги.
Флаги экспортируются при помощи <literal>fs.constants</literal>:

<list type= "bullet" compact="no">

<listitem>
<literal>F_OK</literal>&mdash;указывает, что файл может
быть видимым для для вызывающего процесса,
используется по умолчанию, если режим не указан
</listitem>

<listitem>
<literal>R_OK</literal>&mdash;указывает, что файл может
читаться вызывающим процессом
</listitem>

<listitem>
<literal>W_OK</literal>&mdash;указывает, что файл может
записываться вызывающим процессом
</listitem>

<listitem>
<literal>X_OK</literal>&mdash;указывает, что файл может
выполняться вызывающим процессом
</listitem>

</list>
</para>

</section>


<section id="njs_api_fs_flags" name="Флаги файловой системы">

<para>
Опция <literal>флаг</literal> может принимать следующие значения:

<list type= "bullet" compact="no">

<listitem>
<literal>a</literal>&mdash;открытие файла для добавления данных.
Если файл не существует, то он будет создан
</listitem>

<listitem>
<literal>ax</literal>&mdash;то же, что и <literal>a</literal>,
но завершится неудачей, если файл существует
</listitem>

<listitem>
<literal>a+</literal>&mdash;открытие файла для чтения и добавления данных.
Если файл не существует, то он будет создан
</listitem>

<listitem>
<literal>ax+</literal>&mdash;то же, что и <literal>a+</literal>,
но завершится неудачей, если файл существует
</listitem>

<listitem>
<literal>as</literal>&mdash;открытие файла для добавления данных
в синхронном режиме.
Если файл не существует, то он будет создан
</listitem>

<listitem>
<literal>as+</literal>&mdash;открытие файла для чтения и добавления данных
в синхронном режиме.
Если файл не существует, то он будет создан
</listitem>

<listitem>
<literal>r</literal>&mdash; открытие файла для чтения.
Если файл не существует, то возникнет исключение
</listitem>

<listitem>
<literal>r+</literal>&mdash;открытие файла для чтения и записи.
Если файл не существует, то возникнет исключение
</listitem>

<listitem>
<literal>rs+</literal>&mdash;открытие файла для чтения и записи
в синхронном режиме.
Указывает операционной системе не использовать кэш локальной файловой системы
</listitem>

<listitem>
<literal>w</literal>&mdash;открытие файла для записи.
Если файл не существует, то он будет создан.
Если файл существует, то он будет заменён.
</listitem>

<listitem>
<literal>wx</literal>&mdash;то же, что и <literal>w</literal>,
но завершится неудачей, если файл существует
</listitem>

<listitem>
<literal>w+</literal>&mdash;открытие файла для чтения и записи.
Если файл не существует, то он будет создан.
Если файл существует, то он будет заменён.
</listitem>

<listitem>
<literal>wx+</literal>&mdash;то же, что и <literal>w+</literal>,
но завершится неудачей, если файл существует
</listitem>

</list>
</para>

</section>

</section>


<section id="querystring" name="Query String">

<para>
Модуль Query String предоставляет поддержку
синтаксического разбора и форматирования строки запроса URL.
(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
Объект модуля Query String доступен через
<literal>require('querystring')</literal>.
</para>

<para>
<list type="tag">

<tag-name id="querystring_decode"><literal>querystring.decode()</literal></tag-name>
<tag-desc>
является псевдонимом для
<link id="querystring_parse"><literal>querystring.parse()</literal></link>.
</tag-desc>

<tag-name id="querystring_encode"><literal>querystring.encode()</literal></tag-name>
<tag-desc>
является псевдонимом для
<link id="querystring_stringify"><literal>querystring.stringify()</literal></link>.
</tag-desc>

<tag-name id="querystring_escape"><literal>querystring.escape(<value>строка</value>)</literal></tag-name>
<tag-desc>
<para>
Кодирует заданную <literal>строку</literal>,
возвращает экранированную строку.
Метод используется методом
<link id="querystring_stringify"><literal>querystring.stringify()</literal></link>
и не должен использоваться напрямую.
</para>
</tag-desc>

<tag-name id="querystring_parse"><literal>querystring.parse(<value>строка</value>[,
<value>separator</value>[,
<value>equal</value>[,
<value>options</value>]]])</literal></tag-name>
<tag-desc>
<para>
Осуществляет синтаксический разбор строки запроса и возвращает объект.
</para>

<para>
Параметр <literal>separator</literal> является подстрокой,
разделяющей в строке запроса пары ключей и значений,
по умолчанию “<literal>&amp;</literal>”.
</para>

<para>
Параметр <literal>equal</literal>  является подстрокой,
разделяющей в строке запроса ключи и значения,
по умолчанию “<literal>=</literal>”.
</para>

<para>
Параметр <literal>options</literal> должен быть
объектом со следующими ключами:
<list type="tag">
<tag-name><literal>decodeURIComponent</literal>
<value>функция</value></tag-name>
<tag-desc>
Функция, используемая
при декодировании процентно-кодированных символов в строке запроса,
по умолчанию
<link id="querystring_unescape"><literal>querystring.unescape()</literal></link>
</tag-desc>

<tag-name><literal>maxKeys</literal>
<value>число</value></tag-name>
<tag-desc>
максимальное число ключей для синтаксического разбора,
по умолчанию <literal>1000</literal>.
Значение <literal>0</literal> удаляет ограничение на подсчёт ключей.
</tag-desc>

</list>
По умолчанию предполагается, что процентно-кодированные символы в строке запроса
используют кодировку UTF-8,
неверная последовательность байтов UTF-8 будет заменена на
<literal>U+FFFD</literal>.
</para>

<para>
Пример для строки запроса:
<example>
'foo=bar&amp;abc=xyz&amp;abc=123'
</example>
результат:
<example>
{
  foo: 'bar',
  abc: ['xyz', '123']
}
</example>
</para>

</tag-desc>

<tag-name id="querystring_stringify"><literal>querystring.stringify(<value>object</value>[,
<value>separator</value>[,
<value>equal</value>[,
<value>options</value>]]])</literal></tag-name>
<tag-desc>
<para>
Осуществляет синтаксический разбор объекта и возвращает строку запроса.
</para>

<para>
Параметр <literal>separator</literal> является подстрокой,
разделяющей в строке запроса пары ключей и значений,
по умолчанию “<literal>&amp;</literal>”.
</para>

<para>
Параметр <literal>equal</literal> является подстрокой,
разделяющей в строке запроса ключи и значения,
по умолчанию “<literal>=</literal>”.
</para>

<para>
Параметр <literal>options</literal> должен быть
объектом со следующими ключами:
<list type="tag">
<tag-name><literal>encodeURIComponent</literal>
<value>функция</value></tag-name>
<tag-desc>
Функция, используемая при декодировании
URL-небезопасных символов в в процентно-кодированные символы в строке запроса,
по умолчанию
<link id="querystring_escape"><literal>querystring.escape()</literal></link>.
</tag-desc>

</list>
</para>

<para>
По умолчанию символы, требующие процентной кодировки внутри строки запроса,
кодируются в UTF-8.
Если требуется другая кодировка, то
необходимо указать опцию <literal>encodeURIComponent</literal>.
</para>

<para>
Пример:
<example>
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], 123: '' });
</example>
результат:
<example>
'foo=bar&amp;baz=qux&amp;baz=quux&amp;123='
</example>
</para>

</tag-desc>

<tag-name id="querystring_unescape"><literal>querystring.unescape(<value>строка</value>)</literal></tag-name>
<tag-desc>
<para>
Осуществляет декодирование процентно-кодированных символов URL
в <literal>строке</literal>,
возвращает неэкранированную строку запроса.
Метод используется методом
<link id="querystring_parse"><literal>querystring.parse()</literal></link>
и не должен использоваться напрямую.
</para>
</tag-desc>

</list>
</para>

</section>

</section>

</article>