Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_js_module.xml @ 2849:8eda939a57e5
Linux packages: added RHEL 9.
author | Konstantin Pavlov <thresh@nginx.com> |
---|---|
date | Mon, 23 May 2022 14:16:07 +0400 |
parents | a3aee2697d4e |
children | 986e1f930e3b |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Модуль ngx_http_js_module" link="/ru/docs/http/ngx_http_js_module.html" lang="ru" rev="35"> <section id="summary"> <para> Модуль <literal>ngx_http_js_module</literal> позволяет задавать обработчики location и переменных на <link doc="../njs/index.xml">njs</link> — подмножестве языка JavaScript. </para> <para> Инструкция по сборке и установке доступны <link doc="../njs/install.xml">здесь</link>. </para> </section> <section id="example" name="Пример конфигурации"> <para> Пример работает начиная с версии <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>. <example> http { js_import http.js; js_set $foo http.foo; js_set $summary http.summary; js_set $hash http.hash; resolver 10.0.0.1; server { listen 8000; location / { add_header X-Foo $foo; js_content http.baz; } location = /summary { return 200 $summary; } location = /hello { js_content http.hello; } # начиная с версии 0.7.0 location = /fetch { js_content http.fetch; js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem; } # начиная с версии 0.7.0 location = /crypto { add_header Hash $hash; return 200; } } } </example> </para> <para> Файл <path>http.js</path>: <example> function foo(r) { r.log("hello from foo() handler"); return "foo"; } function summary(r) { var a, s, h; s = "JS summary\n\n"; s += "Method: " + r.method + "\n"; s += "HTTP version: " + r.httpVersion + "\n"; s += "Host: " + r.headersIn.host + "\n"; s += "Remote Address: " + r.remoteAddress + "\n"; s += "URI: " + r.uri + "\n"; s += "Headers:\n"; for (h in r.headersIn) { s += " header '" + h + "' is '" + r.headersIn[h] + "'\n"; } s += "Args:\n"; for (a in r.args) { s += " arg '" + a + "' is '" + r.args[a] + "'\n"; } return s; } function baz(r) { r.status = 200; r.headersOut.foo = 1234; r.headersOut['Content-Type'] = "text/plain; charset=utf-8"; r.headersOut['Content-Length'] = 15; r.sendHeader(); r.send("nginx"); r.send("java"); r.send("script"); r.finish(); } function hello(r) { r.return(200, "Hello world!"); } // начиная с версии 0.7.0 async function fetch(r) { let results = await Promise.all([ngx.fetch('https://nginx.org/'), ngx.fetch('https://nginx.org/en/')]); r.return(200, JSON.stringify(results, undefined, 4)); } // начиная с версии 0.7.0 async function hash(r) { let hash = await crypto.subtle.digest('SHA-512', r.headersIn.host); r.setReturnValue(Buffer.from(hash).toString('hex')); } export default {foo, summary, baz, hello, fetch, hash}; </example> </para> </section> <section id="directives" name="Директивы"> <directive name="js_body_filter"> <syntax><value>функция</value> | <value>модуль.функция</value> [<value>buffer_type</value>=<value>строка</value> | <value>буфер</value>]</syntax> <default/> <context>location</context> <context>limit_except</context> <appeared-in>0.5.2</appeared-in> <para> Задаёт функцию njs в качестве фильтра тела ответа. Функция фильтра вызывается для каждого блока данных тела ответа со следующими аргументами: <list type="tag"> <tag-name><literal>r</literal></tag-name> <tag-desc> объект <link doc="../njs/reference.xml" id="http">HTTP request</link> </tag-desc> <tag-name><literal>data</literal></tag-name> <tag-desc> входящий блок данных может быть строкой или буфером в зависимости от значения <literal>buffer_type</literal>, по умолчанию является строкой. </tag-desc> <tag-name><literal>flags</literal></tag-name> <tag-desc> объект со следующими свойствами: <list type="tag"> <tag-name><literal>last</literal></tag-name> <tag-desc> логическое значение, true, если данные являются последним буфером. </tag-desc> </list> </tag-desc> </list> </para> <para> Функция фильтра может передавать свою модифицированную версию входящего блока данных следующему фильтру тела ответа при помощи вызова <link doc="../njs/reference.xml" id="r_sendbuffer"><literal>r.sendBuffer()</literal></link>. Пример преобразования букв в нижний регистр в теле ответа: <example> function filter(r, data, flags) { r.sendBuffer(data.toLowerCase(), flags); } </example> Для отмены фильтра (блоки данных будут передаваться клиенту без вызова <literal>js_body_filter</literal>), можно использовать <link doc="../njs/reference.xml" id="r_done"><literal>r.done()</literal></link>. </para> <para> Если функция фильтра изменяет длину тела ответа, то необходимо очистить заголовок ответа <header>Content-Length</header> (если присутствует) в <link id="js_header_filter"><literal>js_header_filter</literal></link>, чтобы применить поблочное кодирование. </para> <para> <note> Так как обработчик <literal>js_body_filter</literal> должен сразу возвращать результат, то поддерживаются только синхронные операции, Таким образом, асинхронные операции, например <link doc="../njs/reference.xml" id="r_subrequest">r.subrequest()</link> или <link doc="../njs/reference.xml" id="settimeout">setTimeout()</link>, не поддерживаются. </note> </para> </directive> <directive name="js_content"> <syntax><value>функция</value> | <value>модуль.функция</value></syntax> <default/> <context>location</context> <context>limit_except</context> <para> Задаёт функцию njs в качестве обработчика содержимого location. Начиная с версии <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link> можно ссылаться на функцию модуля. </para> </directive> <directive name="js_fetch_buffer_size"> <syntax><value>размер</value></syntax> <default>16k</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>0.7.4</appeared-in> <para> Задаёт <value>размер</value> буфера, который будет использоваться для чтения и записи для <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>. </para> </directive> <directive name="js_fetch_ciphers"> <syntax><value>шифры</value></syntax> <default>HIGH:!aNULL:!MD5</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>0.7.0</appeared-in> <para> Описывает разрешённые шифры для HTTPS-запросов при помощи <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL. </para> <para> Полный список можно посмотреть с помощью команды “<command>openssl ciphers</command>”. </para> </directive> <directive name="js_fetch_max_response_buffer_size"> <syntax><value>размер</value></syntax> <default>1m</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>0.7.4</appeared-in> <para> Задаёт максимальный <value>размер</value> ответа, полученного при помощи <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>. </para> </directive> <directive name="js_fetch_protocols"> <syntax> [<literal>TLSv1</literal>] [<literal>TLSv1.1</literal>] [<literal>TLSv1.2</literal>] [<literal>TLSv1.3</literal>]</syntax> <default>TLSv1 TLSv1.1 TLSv1.2</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>0.7.0</appeared-in> <para> Разрешает указанные протоколы для HTTPS-запросов при помощи <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>. </para> </directive> <directive name="js_fetch_timeout"> <syntax><value>время</value></syntax> <default>60s</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>0.7.4</appeared-in> <para> Задаёт таймаут при чтении и записи при помощи <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени данные не передавались, соединение закрывается. </para> </directive> <directive name="js_fetch_trusted_certificate"> <syntax><value>файл</value></syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <appeared-in>0.7.0</appeared-in> <para> Задаёт <value>файл</value> с доверенными сертификатами CA в формате PEM, используемыми при <link doc="../njs/reference.xml" id="fetch_verify">проверке</link> HTTPS-сертификата при помощи <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>. </para> </directive> <directive name="js_fetch_verify"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>on</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>0.7.4</appeared-in> <para> Разрешает или запрещает проверку сертификата HTTPS-сервера при помощи <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>. </para> </directive> <directive name="js_fetch_verify_depth"> <syntax><value>число</value></syntax> <default>100</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>0.7.0</appeared-in> <para> Устанавливает глубину проверки в цепочке HTTPS-сертификатов при помощи <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>. </para> </directive> <directive name="js_header_filter"> <syntax><value>функция</value> | <value>модуль.функция</value></syntax> <default/> <context>location</context> <context>limit_except</context> <appeared-in>0.5.1</appeared-in> <para> Задаёт функцию njs в качестве фильтра заголовка ответа. Директива позволяет менять произвольные поля заголовка ответа. </para> <para> <note> Так как обработчик <literal>js_header_filter</literal> должен сразу возвращать результат, то поддерживаются только синхронные операции, Таким образом, асинхронные операции, например <link doc="../njs/reference.xml" id="r_subrequest">r.subrequest()</link> или <link doc="../njs/reference.xml" id="settimeout">setTimeout()</link>, не поддерживаются. </note> </para> </directive> <directive name="js_import"> <syntax><value>модуль.js</value> | <value>имя_экспорта from модуль.js</value></syntax> <default/> <context>http</context> <appeared-in>0.4.0</appeared-in> <para> Импортирует модуль, позволяющий задавать обработчики location и переменных на njs. <literal>Имя_экспорта</literal> является пространством имён при доступе к функциям модуля. Если <literal>имя_экспорта</literal> не задано, то пространством имён будет являться имя модуля. <example> js_import http.js; </example> В примере при доступе к экспорту в качестве пространства имён используется имя модуля <literal>http</literal>. Если импортируемый модуль экспортирует <literal>foo()</literal>, то для доступа используется <literal>http.foo</literal>. </para> <para> Директив <literal>js_import</literal> может быть несколько. </para> </directive> <directive name="js_include"> <syntax><value>файл</value></syntax> <default/> <context>http</context> <para> Задаёт файл, позволяющий задавать обработчики location и переменных на njs: <example> nginx.conf: js_include http.js; location /version { js_content version; } http.js: function version(r) { r.return(200, njs.version); } </example> </para> <para> Директива устарела в версии <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link> и была удалена в версии <link doc="../njs/changes.xml" id="njs0.7.1">0.7.1</link>. Вместо неё следует использовать директиву <link id="js_import"/>. </para> </directive> <directive name="js_path"> <syntax> <value>путь</value></syntax> <default/> <context>http</context> <appeared-in>0.3.0</appeared-in> <para> Задаёт дополнительный путь для модулей njs. </para> </directive> <directive name="js_set"> <syntax> <value>$переменная</value> <value>функция</value> | <value>модуль.функция</value></syntax> <default/> <context>http</context> <para> Задаёт <literal>функцию</literal> njs для указанной <literal>переменной</literal>. Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link> можно ссылаться на функцию модуля. </para> <para> Функция вызывается в момент первого обращения к переменной для данного запроса. Точный момент вызова функции зависит от <link doc="../dev/development_guide.xml" id="http_phases">фазы</link>, в которой происходит обращение к переменной. Это можно использовать для реализации дополнительной логики, не относящейся к вычислению переменной. Например, если переменная указана в директиве <link doc="ngx_http_log_module.xml" id="log_format"/>, то её обработчик не будет выполняться до фазы записи в лог. Этот обработчик также может использоваться для выполнения процедур непосредственно перед освобождением запроса. </para> <para> <note> Так как обработчик <literal>js_set</literal> должен сразу возвращать результат, то поддерживаются только синхронные операции, Таким образом, асинхронные операции, например <link doc="../njs/reference.xml" id="r_subrequest">r.subrequest()</link> или <link doc="../njs/reference.xml" id="settimeout">setTimeout()</link>, не поддерживаются. </note> </para> </directive> <directive name="js_var"> <syntax><value>$переменная</value> [<value>значение</value>]</syntax> <default/> <context>http</context> <appeared-in>0.5.3</appeared-in> <para> Объявляет <link doc="../njs/reference.xml" id="r_variables">перезаписываемую</link> переменную. В качестве значения можно использовать текст, переменные и их комбинации. Переменная не перезаписывается после перенаправления, в отличие от переменных, созданных при помощи директивы <link doc="ngx_http_rewrite_module.xml" id="set"/>. </para> </directive> </section> <section id="arguments" name="Аргумент запроса"> <para> Каждый HTTP-обработчик njs получает один аргумент, <link doc="../njs/reference.xml" id="http">объект</link> запроса. </para> </section> </module>