Mercurial > hg > nginx-site
view xml/ru/docs/njs/reference.xml @ 2652:eb508d8c1c31
Linux packages: added RHEL/CentOS 7 aarch64/arm64.
author | Konstantin Pavlov <thresh@nginx.com> |
---|---|
date | Wed, 10 Feb 2021 14:36:24 +0300 |
parents | 7da360f50017 |
children |
line wrap: on
line source
<?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="59"> <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>. Метод устарел начиная с <link doc="changes.xml" id="njs0.4.4">0.4.4</link>, вместо него следует использовать метод <literal>Buffer.from</literal>: <example> >> Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]).toString() 'buffer' >> Buffer.from('YnVmZmVy', 'base64').toString() '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="textdecoder" name="Text Decoder"> <para> Объект <literal>TextDecoder</literal> создаёт поток кодовых точек из потока данных (<link doc="changes.xml" id="njs0.4.3">0.4.3</link>). </para> <para> <list type="tag"> <tag-name><literal>TextDecoder([[<value>кодировка</value>], <value>options</value>])</literal></tag-name> <tag-desc> Создаёт новый объект <literal>TextDecoder</literal> для указанной <literal>кодировки</literal>, на данный момент поддерживается только UTF-8. Параметр <literal>options</literal> является словарём <literal>TextDecoderOption</literal> со свойствами: <list type="tag"> <tag-name><literal>fatal</literal></tag-name> <tag-desc> логический флаг, указывающий, что <link id="textdecoder_decode"><literal>TextDecoder.decode()</literal></link> должен вызывать исключение <value>TypeError</value> в случае, если найдена ошибка кодирования, по умолчанию <literal>false</literal>. </tag-desc> </list> </tag-desc> <tag-name id="textdecoder_encoding"><literal>TextDecoder.prototype.encoding</literal></tag-name> <tag-desc> Возвращает строку с именем кодировки, используемой <link id="textdecoder"><literal>TextDecoder()</literal></link>, только чтение. </tag-desc> <tag-name id="textdecoder_fatal"><literal>TextDecoder.prototype.fatal</literal></tag-name> <tag-desc> логический флаг, <literal>true</literal>, если генерируется ошибка для невалидных символов, только чтение. </tag-desc> <tag-name id="textdecoder_ignorebom"><literal>TextDecoder.prototype.ignoreBOM</literal></tag-name> <tag-desc> логический флаг, <literal>true</literal>, если игнорируется маркер порядка следования байтов, только чтение. </tag-desc> <tag-name id="textdecoder_decode"><literal>TextDecoder.prototype.decode(<value>буфер</value>, [<value>options</value>])</literal></tag-name> <tag-desc> Возвращает строку с текстом, декодированным из <literal>буфера</literal> при помощи <link id="textdecoder"><literal>TextDecoder()</literal></link>. Буфером может быть <literal>ArrayBuffer</literal>. Параметром <literal>options</literal> является словарь <literal>TextDecodeOptions</literal> со свойствами: <list type="tag"> <tag-name><literal>stream</literal></tag-name> <tag-desc> логический флаг, указывающий, что при последующих вызовах <literal>decode()</literal> должны последовать дополнительные данные: <literal>true</literal>, если данные обрабатываются блоками, и <literal>false</literal> для последнего блока или если данные не передаются блоками. По умолчанию <literal>false</literal>. </tag-desc> </list> <example> >> (new TextDecoder()).decode(new Uint8Array([206,177,206,178])) αβ </example> </tag-desc> </list> </para> </section> <section id="textencoder" name="Text Encoder"> <para> Объект <literal>TextEncoder</literal> создаёт поток данных в кодировке UTF-8 из потока кодовых точек (<link doc="changes.xml" id="njs0.4.3">0.4.3</link>). </para> <para> <list type="tag"> <tag-name><literal>TextEncoder()</literal></tag-name> <tag-desc> Возвращает только что созданный <literal>TextEncoder</literal>, который создаёт поток данных в кодировке UTF-8. </tag-desc> <tag-name id="textencoder_encode"><literal>TextEncoder.prototype.encode(<value>строка</value>)</literal></tag-name> <tag-desc> Кодирует <literal>строку</literal> в <literal>Uint8Array</literal>, содержащий текст в кодировке UTF-8. </tag-desc> <tag-name id="textencoder_encodeinto"><literal>TextEncoder.prototype.encodeInto(<value>строка</value>, <value>uint8Array</value>)</literal></tag-name> <tag-desc> Преобразует <literal>строку</literal> в UTF-8, сохраняет результат в целевом <literal>Uint8Array</literal> и возвращает объект словаря, отражающий прогресс кодирования, со свойствами: <list type="tag"> <tag-name><literal>read</literal></tag-name> <tag-desc> количество блоков кода UTF-16 из исходной строки, преобразованных в UTF-8 </tag-desc> <tag-name><literal>written</literal></tag-name> <tag-desc> количество байтов, преобразованных в целевом <literal>Uint8Array</literal> </tag-desc> </list> </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 id="crypto_hash_update"><literal>hash.update(<value>данные</value>)</literal></tag-name> <tag-desc> Обновляет содержимое хэша с передаваемыми <value>данными</value>. </tag-desc> <tag-name id="crypto_hash_digest"><literal>hash.digest([<value>кодировка</value>])</literal></tag-name> <tag-desc> Подсчитывает дайджест всех данных, передаваемых при помощи <literal>hash.update()</literal>. Кодировка может быть <literal>hex</literal>, <literal>base64</literal> и <literal>base64url</literal>. Если кодировка не указана, то будет возвращен объект буфера (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>). <note> До версии <link doc="changes.xml" id="njs0.4.4">0.4.4</link> вместо объекта буфера возвращалась байтовая строка. </note> </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 id="crypto_hmac_update"><literal>hmac.update(<value>данные</value>)</literal></tag-name> <tag-desc> Обновляет содержимое HMAC с передаваемыми <value>данными</value>. </tag-desc> <tag-name id="crypto_hmac_digest"><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)) <file data> </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>Данными</literal> могут быть строка или объект буфера (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>. Если файл не существует, то он будет создан. Параметр <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>. Кодировка может быть <literal>utf8</literal> и <literal>буфер</literal> (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>). </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 doc="changes.xml" id="njs0.4.4">0.4.4</link>). <note> До версии <link doc="changes.xml" id="njs0.4.4">0.4.4</link> возвращалась <link id="string_tobytes">байтовая строка</link> в случае, если не была указана кодировка. </note> Иначе ожидается, что <literal>options</literal> является объектом с ключами: <list type="tag"> <tag-name><literal>кодировка</literal></tag-name> <tag-desc> кодировка, по умолчанию не указана. Кодировка может быть <literal>utf8</literal>, <literal>hex</literal> (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>), <literal>base64</literal> (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>), <literal>base64url</literal> (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>). </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 = file.slice(0,2).toString('hex') === '1f8b'; 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>Данными</literal> могут быть строка или объект буфера (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>. Если файл не существует, то он будет создан. Если файл существует, то он будет заменён. Параметр <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> является представлением записи каталога— файлом или подкаталогом . В случае, если <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>—возвращает <literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает блочное устройство </listitem> <listitem> <literal>dirent.isCharacterDevice()</literal>—возвращает <literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает символьное устройство. </listitem> <listitem> <literal>dirent.isDirectory()</literal>—возвращает <literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает каталог файловой системы. </listitem> <listitem> <literal>dirent.isFIFO()</literal>—возвращает <literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает FIFO-канал. </listitem> <listitem> <literal>dirent.isFile()</literal>—возвращает <literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает обычный файл. </listitem> <listitem> <literal>dirent.isSocket()</literal>—возвращает <literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает сокет. </listitem> <listitem> <literal>dirent.isSymbolicLink()</literal>—возвращает <literal>true</literal>, если объект <literal>fs.Dirent</literal> описывает символическую ссылку. </listitem> <listitem> <literal>dirent.name</literal>— имя файла, на которое ссылается объект <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>—указывает, что файл может быть видимым для для вызывающего процесса, используется по умолчанию, если режим не указан </listitem> <listitem> <literal>R_OK</literal>—указывает, что файл может читаться вызывающим процессом </listitem> <listitem> <literal>W_OK</literal>—указывает, что файл может записываться вызывающим процессом </listitem> <listitem> <literal>X_OK</literal>—указывает, что файл может выполняться вызывающим процессом </listitem> </list> </para> </section> <section id="njs_api_fs_flags" name="Флаги файловой системы"> <para> Опция <literal>флаг</literal> может принимать следующие значения: <list type= "bullet" compact="no"> <listitem> <literal>a</literal>—открытие файла для добавления данных. Если файл не существует, то он будет создан </listitem> <listitem> <literal>ax</literal>—то же, что и <literal>a</literal>, но завершится неудачей, если файл существует </listitem> <listitem> <literal>a+</literal>—открытие файла для чтения и добавления данных. Если файл не существует, то он будет создан </listitem> <listitem> <literal>ax+</literal>—то же, что и <literal>a+</literal>, но завершится неудачей, если файл существует </listitem> <listitem> <literal>as</literal>—открытие файла для добавления данных в синхронном режиме. Если файл не существует, то он будет создан </listitem> <listitem> <literal>as+</literal>—открытие файла для чтения и добавления данных в синхронном режиме. Если файл не существует, то он будет создан </listitem> <listitem> <literal>r</literal>— открытие файла для чтения. Если файл не существует, то возникнет исключение </listitem> <listitem> <literal>r+</literal>—открытие файла для чтения и записи. Если файл не существует, то возникнет исключение </listitem> <listitem> <literal>rs+</literal>—открытие файла для чтения и записи в синхронном режиме. Указывает операционной системе не использовать кэш локальной файловой системы </listitem> <listitem> <literal>w</literal>—открытие файла для записи. Если файл не существует, то он будет создан. Если файл существует, то он будет заменён. </listitem> <listitem> <literal>wx</literal>—то же, что и <literal>w</literal>, но завершится неудачей, если файл существует </listitem> <listitem> <literal>w+</literal>—открытие файла для чтения и записи. Если файл не существует, то он будет создан. Если файл существует, то он будет заменён. </listitem> <listitem> <literal>wx+</literal>—то же, что и <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>&</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&abc=xyz&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>&</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&baz=qux&baz=quux&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>