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

<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>
<note>
Данный пример необходимо использовать с
версией njs <link doc="../changes.xml" id="njs0.2.4">0.2.4</link>.
Для версий njs <link doc="../changes.xml" id="njs0.2.3">0.2.3</link>
и ранее необходимо использовать
<link doc="../examples.xml" id="legacy">этот</link> пример.
</note>
<example>
load_module modules/ngx_stream_js_module.so;
...

stream {
    js_include stream.js;

    js_set $bar bar;
    js_set $req_line req_line;

    server {
        listen 12345;

        js_preread preread;
        return     $req_line;
    }

    server {
        listen 12346;

        js_access  access;
        proxy_pass 127.0.0.1:8000;
        js_filter  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-заголовка в запрос клиента

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

    s.allow();
}
</example>
</para>

</section>


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

<directive name="js_access">
<syntax><value>функция</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

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

</directive>


<directive name="js_filter">
<syntax><value>функция</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Задаёт фильтр данных.
</para>

</directive>


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

<para>
Задаёт файл, который позволяет
задавать обработчики server и переменных на njs.
</para>

</directive>


<directive name="js_preread">
<syntax><value>функция</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

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

</directive>


<directive name="js_set">
<syntax>
<value>$переменная</value> <value>функция</value></syntax>
<default/>
<context>stream</context>

<para>
Задаёт функцию njs для указанной переменной.
</para>

</directive>

</section>


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

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

</section>

</module>