Docs4dev
Docs
nginx / current / reference / stream-ngx_stream_js_module.html

Module ngx_stream_js_module

Example Configuration
Directives
     js_access
     js_filter
     js_import
     js_include
     js_path
     js_preread
     js_set
Session Object Properties

The ngx_stream_js_module module is used to implement handlers in njs — a subset of the JavaScript language.

Download and install instructions are available here.

Example Configuration

The example works since 0.4.0.

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;
        }
    }
}

The stream.js file:

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

export default {bar, preread, req_line, access};

Directives

Syntax: js_access function | module.function;
Default: —
Context: stream, server

Sets an njs function which will be called at the access phase. Since 0.4.0, a module function can be referenced.

Syntax: js_filter function | module.function;
Default: —
Context: stream, server

Sets a data filter. Since 0.4.0, a module function can be referenced.

Syntax: js_import module.js | export_name from module.js;
Default: —
Context: stream

This directive appeared in version 0.4.0.

Imports a module that implements location and variable handlers in njs. The export_name is used as a namespace to access module functions. If the export_name is not specified, the module name will be used as a namespace.

js_import stream.js;

Here, the module name stream is used as a namespace while accessing exports. If the imported module contains foo(), stream.foo is used to refer to it.

Several js_import directives can be specified.

Syntax: js_include file;
Default: —
Context: stream

Specifies a file that implements server and variable handlers in njs:

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;
}

The directive is deprecated since 0.4.0, the js_import directive should be used instead.

Syntax: js_path path;
Default: —
Context: http

This directive appeared in version 0.3.0.

Sets an additional path for njs modules.

Syntax: js_preread function | module.function;
Default: —
Context: stream, server

Sets an njs function which will be called at the preread phase. Since 0.4.0, a module function can be referenced.

Syntax: js_set $variable function | module.function;
Default: —
Context: stream

Sets an njs function for the specified variable. Since 0.4.0, a module function can be referenced.

Session Object Properties

Each stream njs handler receives one argument, a stream session object.