<?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>