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

<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>if in 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>

<para>
<note>
Директива может быть указана внутри
блока <link doc="../http/ngx_http_rewrite_module.xml" id="if">if</link>
начиная с <link doc="../njs/changes.xml" id="njs0.7.7">0.7.7</link>.
</note>
</para>

</directive>


<directive name="js_content">
<syntax><value>функция</value> | <value>модуль.функция</value></syntax>
<default/>
<context>location</context>
<context>if in location</context>
<context>limit_except</context>

<para>
Задаёт функцию njs в качестве обработчика содержимого location.
Начиная с версии <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>
можно ссылаться на функцию модуля.
</para>

<para>
<note>
Директива может быть указана внутри
блока <link doc="../http/ngx_http_rewrite_module.xml" id="if">if</link>
начиная с <link doc="../njs/changes.xml" id="njs0.7.7">0.7.7</link>.
</note>
</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>if in 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>

<para>
<note>
Директива может быть указана внутри
блока <link doc="../http/ngx_http_rewrite_module.xml" id="if">if</link>
начиная с <link doc="../njs/changes.xml" id="njs0.7.7">0.7.7</link>.
</note>
</para>

</directive>


<directive name="js_import">
<syntax><value>модуль.js</value> |
<value>имя_экспорта from модуль.js</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</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>

<para>
<note>
Директива может быть указана
на уровне <literal>server</literal> и <literal>location</literal>
начиная с <link doc="../njs/changes.xml" id="njs0.7.7">0.7.7</link>.
</note>
</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>
<context>server</context>
<context>location</context>
<appeared-in>0.3.0</appeared-in>

<para>
Задаёт дополнительный путь для модулей njs.
</para>

<para>
<note>
Директива может быть указана
на уровне <literal>server</literal> и <literal>location</literal>
начиная с <link doc="../njs/changes.xml" id="njs0.7.7">0.7.7</link>.
</note>
</para>

</directive>


<directive name="js_periodic">
<syntax><value>функция</value> |
        <value>модуль.функция</value>
        [<literal>interval</literal>=<value>время</value>]
        [<literal>jitter</literal>=<value>число</value>]
        [<literal>worker_affinity</literal>=<value>маска</value>]</syntax>
<default/>
<context>location</context>
<appeared-in>0.8.1</appeared-in>

<para>
Задаёт периодичность запуска обработчика содержимого.
В качестве первого аргумента обработчик получает
<link doc="../njs/reference.xml" id="periodic_session">объект сессии</link>,
также у обработчика есть доступ к глобальным объектам таким как
<link doc="../njs/reference.xml" id="ngx">ngx</link>.
</para>

<para>
Необязательный параметр <literal>interval</literal>
задаёт интервал между двумя последовательными запусками,
по умолчанию 5 секунд.
</para>

<para>
Необязательный параметр <literal>jitter</literal>
задаёт время, в пределах которого
случайным образом задерживается каждый запуск,
по умолчанию задержки нет.
</para>

<para>
По умолчанию <literal>js_handler</literal> выполняется для рабочего процесса 0.
Необязательный параметр <literal>worker_affinity</literal>
позволяет указать рабочий процесс,
для которого будет выполняться обработчик содержимого location.
Рабочие процессы задаются битовой маской разрешённых к использованию рабочих
процессов.
Маска <literal>all</literal> позволяет обработчику выполняться
для всех рабочих процессов.
</para>

<para>
Пример:
<example>
example.conf:

location @periodics {
    # интервал выполнения 1 минута для рабочего процесса 0
    js_periodic main.handler interval=60s;

    # интервал выполнения 1 минута для всех рабочих процессов
    js_periodic main.handler interval=60s worker_affinity=all;

    # интервал выполнения 1 минута для рабочих процессов 1 и 3
    js_periodic main.handler interval=60s worker_affinity=0101;

    resolver 10.0.0.1;
    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
}

example.js:

async function handler(s) {
    let reply = await ngx.fetch('https://nginx.org/en/docs/njs/');
    let body = await reply.text();

    ngx.log(ngx.INFO, body);
}
</example>
</para>

</directive>


<directive name="js_preload_object">
<syntax><value>имя.json</value> |
<value>имя</value> from <value>файл.json</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>0.7.8</appeared-in>

<para>
Предварительно загружает
<link doc="../njs/preload_objects.xml">неизменяемый объект</link>
во время конфигурации.
<literal>Имя</literal> используется в качестве имени глобальной переменной,
через которую объект доступен в коде njs.
Если <literal>имя</literal> не указано,
то будет использоваться имя файла.
<example>
js_preload_object map.json;
</example>
В примере <literal>map</literal> используется в качестве имени
во время доступа к предварительно загруженному объекту.
</para>

<para>
Директив <literal>js_preload_object</literal> может быть несколько.
</para>

</directive>


<directive name="js_set">
<syntax>
<value>$переменная</value> <value>функция</value> |
<value>модуль.функция</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</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>

<para>
<note>
Директива может быть указана
на уровне <literal>server</literal> и <literal>location</literal>
начиная с <link doc="../njs/changes.xml" id="njs0.7.7">0.7.7</link>.
</note>
</para>

</directive>


<directive name="js_shared_dict_zone">
<syntax>
    <literal>zone</literal>=<value>имя</value>:<value>размер</value>
    [<literal>timeout</literal>=<value>время</value>]
    [<literal>type</literal>=<literal>строка</literal>|<literal>число</literal>]
    [<literal>evict</literal>]</syntax>
<default/>
<context>http</context>
<appeared-in>0.8.0</appeared-in>

<para>
Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти,
в которой хранится
<link doc="../njs/reference.xml" id="dict">словарь</link> ключей и значений,
разделяемый между рабочими процессами.
</para>

<para>
По умолчанию в качестве ключа и значения используется строка.
Необязательный параметр <literal>type</literal>
позволяет изменить тип значения на число.
</para>

<para>
Необязательный параметр <literal>timeout</literal> задаёт время,
по завершении которого все записи в словаре удаляются из зоны.
</para>

<para>
Необязательный параметр <literal>evict</literal> удаляет самую старую
пару ключ-значение при переполнении зоны.
</para>

<para>
Пример:
<example>
example.conf:
    # Создаётся словарь размером 1Мб со строковыми значениями,
    # пары ключ-значение удаляются при отсутствии активности в течение 60 секунд:
    js_shared_dict_zone zone=foo:1M timeout=60s;

    # Создаётся словарь размером 512Кб со строковыми значениями,
    # удаляется самая старая пара ключ-значение при переполнении зоны:
    js_shared_dict_zone zone=bar:512K timeout=30s evict;

    # Создаётся постоянный словарь размером 32Кб с числовыми значениями:
    js_shared_dict_zone zone=num:32k type=number;

example.js:
    function get(r) {
        r.return(200, ngx.shared.foo.get(r.args.key));
    }

    function set(r) {
        r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));
    }

    function del(r) {
        r.return(200, ngx.shared.bar.delete(r.args.key));
    }

    function increment(r) {
        r.return(200, ngx.shared.num.incr(r.args.key, 2));
    }
</example>
</para>

</directive>


<directive name="js_var">
<syntax><value>$переменная</value> [<value>значение</value>]</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</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>

<para>
<note>
Директива может быть указана
на уровне <literal>server</literal> и <literal>location</literal>
начиная с <link doc="../njs/changes.xml" id="njs0.7.7">0.7.7</link>.
</note>
</para>

</directive>

</section>


<section id="arguments" name="Аргумент запроса">

<para>
Каждый HTTP-обработчик njs получает один аргумент,
<link doc="../njs/reference.xml" id="http">объект</link> запроса.
</para>

</section>

</module>