<?xml version="1.0"?>

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

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

<module name="Module ngx_stream_js_module"
        link="/en/docs/stream/ngx_stream_js_module.html"
        lang="en"
        rev="16">

<section id="summary">

<para>
The <literal>ngx_stream_js_module</literal> module is used to implement
handlers in <link doc="../njs/index.xml">njs</link> —
a subset of the JavaScript language.
</para>

<para>
This module is not built by default.
Download and install instructions are available
<link doc="../njs/install.xml">here</link>.
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<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>
The <path>stream.js</path> file:
<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;
}

// Read HTTP request line.
// Collect bytes in 'req' until
// request line is read.
// Injects HTTP header into a client's request

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.abort();
        return;
    }

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

</section>


<section id="directives" name="Directives">

<directive name="js_access">
<syntax><value>function</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Sets an njs function which will be called at the
<link doc="stream_processing.xml" id="access_phase">access</link> phase.
</para>

</directive>


<directive name="js_filter">
<syntax><value>function</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Sets a data filter.
</para>

</directive>


<directive name="js_include">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>

<para>
Specifies a file that implements server and variable handlers in njs.
</para>

</directive>


<directive name="js_preread">
<syntax><value>function</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Sets an njs function which will be called at the
<link doc="stream_processing.xml" id="preread_phase">preread</link> phase.
</para>

</directive>


<directive name="js_set">
<syntax>
<value>$variable</value> <value>function</value></syntax>
<default/>
<context>stream</context>

<para>
Sets an njs function for the specified variable.
</para>

</directive>

</section>


<section id="properties" name="Session Object Properties">

<para>
Each stream njs handler receives one argument, a stream session
<link doc="../njs/reference.xml" id="stream">object</link>.
</para>

</section>

</module>