<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_stream_js_module"
        link="/ru/docs/stream/ngx_stream_js_module.html"
        lang="ru"
        rev="28">

<section id="summary">

<para>
Модуль <literal>ngx_stream_js_module</literal> позволяет задавать
обработчики на <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>
stream {
    js_import stream.js;

    js_set $bar stream.bar;
    js_set $req_line stream.req_line;

    server {
        listen 12345;

        js_preread stream.preread;
        return     $req_line;
    }

    server {
        listen 12346;

        js_access  stream.access;
        proxy_pass 127.0.0.1:8000;
        js_filter  stream.header_inject;
    }
}

http {
    server {
        listen 8000;
        location / {
            return 200 $http_foo\n;
        }
    }
}
</example>
</para>

<para>
Файл <path>stream.js</path>:
<example>
var line = '';

function bar(s) {
    var v = s.variables;
    s.log("hello from bar() handler!");
    return "bar-var" + v.remote_port + "; pid=" + v.pid;
}

function preread(s) {
    s.on('upload', function (data, flags) {
        var n = data.indexOf('\n');
        if (n != -1) {
            line = data.substr(0, n);
            s.done();
        }
    });
}

function req_line(s) {
    return line;
}

// Чтение строки HTTP-запроса.
// Получение байт в 'req' до того как
// будет прочитана строка запроса.
// Добавление HTTP-заголовка в запрос клиента

var my_header =  'Foo: foo';
function header_inject(s) {
    var req = '';
    s.on('upload', function(data, flags) {
        req += data;
        var n = req.search('\n');
        if (n != -1) {
            var rest = req.substr(n + 1);
            req = req.substr(0, n + 1);
            s.send(req + my_header + '\r\n' + rest, flags);
            s.off('upload');
        }
    });
}

function access(s) {
    if (s.remoteAddress.match('^192.*')) {
        s.deny();
        return;
    }

    s.allow();
}

export default {bar, preread, req_line, header_inject, access};
</example>
</para>

</section>


<section id="directives" name="Директивы">

<directive name="js_access">
<syntax><value>функция</value> | <value>модуль.функция</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

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

</directive>


<directive name="js_filter">
<syntax><value>функция</value> | <value>модуль.функция</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

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

</directive>


<directive name="js_import">
<syntax><value>модуль.js</value> |
<value>имя_экспорта из модуль.js</value></syntax>
<default/>
<context>stream</context>
<appeared-in>0.4.0</appeared-in>

<para>
Импортирует модуль, позволяющий задавать обработчики location и переменных
на njs.
<literal>Имя_экспорта</literal> является пространством имён
при доступе к функциям модуля.
Если <literal>имя_экспорта</literal> не задано,
то пространством имён будет являться имя модуля.
<example>
js_import stream.js;
</example>
В примере при доступе к экспорту в качестве
пространства имён используется имя модуля <literal>stream</literal>.
Если импортируемый модуль экспортирует <literal>foo()</literal>,
то для доступа используется <literal>stream.foo</literal>.
</para>

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

</directive>


<directive name="js_include">
<syntax><value>файл</value></syntax>
<default/>
<context>stream</context>

<para>
Задаёт файл, который позволяет задавать обработчики server и переменных на njs:
<example>
nginx.conf:
js_include stream.js;
js_set     $js_addr address;
server {
    listen 127.0.0.1:12345;
    return $js_addr;
}

stream.js:
function address(s) {
    return s.remoteAddress;
}
</example>
</para>

<para>
Директива устарела начиная с
<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
вместо неё следует использовать директиву <link id="js_import"/>.
</para>

</directive>


<directive name="js_preread">
<syntax><value>функция</value> | <value>модуль.функция</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

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

</directive>


<directive name="js_path">
<syntax>
<value>путь</value></syntax>
<default/>
<context>stream</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>stream</context>

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

<para>
Функция вызывается в момент
первого обращения к переменной для данного запроса.
Точный момент вызова функции зависит от
<link doc="stream_processing.xml">фазы</link>,
в которой происходит обращение к переменной.
Это можно использовать для реализации дополнительной логики,
не относящейся к вычислению переменной.
Например, если переменная указана
в директиве <link doc="ngx_stream_log_module.xml" id="log_format"/>,
то её обработчик не будет выполняться до фазы записи в лог.
Этот обработчик также может использоваться для выполнения процедур
непосредственно перед освобождением запроса.
</para>

<para>
<note>
Так как обработчик <literal>js_set</literal>
должен сразу возвращать результат,
то поддерживаются только синхронные вызовы.
Таким образом, асинхронные вызовы, например
<link doc="../njs/reference.xml" id="ngx_fetch">ngx.fetch()</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>stream</context>
<appeared-in>0.5.3</appeared-in>

<para>
Объявляет
<link doc="../njs/reference.xml" id="r_variables">перезаписываемую</link>
переменную.
В качестве значения можно использовать текст, переменные и их комбинации.
</para>

</directive>

</section>


<section id="properties" name="Свойства объекта сессии">

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

</section>

</module>