stream_js
module#
The module is used to implement handlers in njs — a subset of the JavaScript language.
Example Configuration#
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.deny();
return;
}
s.allow();
}
export default {bar, preread, req_line, header_inject, access};
Directives#
js_access#
- Syntax:
js_access
function | module.function;- Default:
—
- Context:
stream, server
Sets an njs function which will be called at the access phase. Module functions can be referenced.
The function is called once at the moment when the stream session reaches the access phase for the first time. The function is called with the following arguments:
|
the stream session object |
At this phase, it is possible to perform initialization or register a callback with the s.on() method for each incoming data chunk until one of the following methods are called: s.done(), s.decline(), s.allow(). As soon as one of these methods is called, the stream session processing switches to the next phase and all current s.on() callbacks are dropped.
js_fetch_buffer_size#
- Syntax:
js_fetch_buffer_size
size;- Default:
js_fetch_buffer_size 16k;
- Context:
stream, server
Sets the size of the buffer used for reading and writing with Fetch API.
js_fetch_ciphers#
- Syntax:
js_fetch_ciphers
ciphers;- Default:
js_fetch_ciphers HIGH:!aNULL:!MD5;
- Context:
stream, server
Specifies the enabled ciphers for HTTPS connections with Fetch API. The ciphers are specified in the format understood by the OpenSSL library.
The full list can be viewed using the “openssl ciphers” command.
js_fetch_max_response_buffer_size#
- Syntax:
js_fetch_max_response_buffer_size
size;- Default:
js_fetch_max_response_buffer_size 1m;
- Context:
stream, server
Sets the maximum size of the response received with Fetch API.
js_fetch_protocols#
- Syntax:
js_fetch_protocols
[TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];- Default:
js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;
- Context:
stream, server
Enables the specified protocols for HTTPS connections with Fetch API.
js_fetch_timeout#
- Syntax:
js_fetch_timeout
time;- Default:
js_fetch_timeout 60s;
- Context:
stream, server
Defines a timeout for reading and writing for Fetch API. The timeout is set only between two successive read/write operations, not for the whole response. If no data is transmitted within this time, the connection is closed.
js_fetch_trusted_certificate#
- Syntax:
js_fetch_trusted_certificate
file;- Default:
—
- Context:
stream, server
Specifies a file with trusted CA certificates in the PEM format used to verify the HTTPS certificate with Fetch API.
js_fetch_verify#
- Syntax:
js_fetch_verify
on | off;- Default:
js_fetch_verify on;
- Context:
stream, server
Enables or disables verification of the HTTPS server certificate with Fetch API.
js_fetch_verify_depth#
- Syntax:
js_fetch_verify_depth
number;- Default:
js_fetch_verify_depth 100;
- Context:
stream, server
Sets the verification depth in the HTTPS server certificates chain with Fetch API.
js_filter#
- Syntax:
js_filter
function | module.function;- Default:
—
- Context:
stream, server
Sets a data filter. Module functions can be referenced.
The filter function is called once at the moment when the stream session reaches the content phase. The filter function is called with the following arguments:
|
the stream session object |
At this phase, it is possible to perform initialization or register a callback with the s.on() method for each incoming data chunk. The s.off() method may be used to unregister a callback and stop filtering.
Note
As the js_filter handler returns its result immediately, it supports only synchronous operations. Thus, asynchronous operations such as ngx.fetch() or setTimeout() are not supported.
js_import#
- Syntax:
js_import
module.js | export_name from module.js;- Default:
—
- Context:
stream, server
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
Several js_import directives can be specified.
js_path#
- Syntax:
js_path
path;- Default:
—
- Context:
stream, server
Sets an additional path for njs modules.
js_preload_object#
- Syntax:
js_preload_object
name.json | name from file.json;- Default:
—
- Context:
stream, server
Preloads an immutable object at configure time. The name is used as a name of the global variable though which the object is available in njs code. If the name is not specified, the file name will be used instead.
js_preload_object map.json;
Here, the map is used as a name while accessing the preloaded object.
Several js_preload_object directives can be specified.
js_preread#
- Syntax:
js_preread
function | module.function;- Default:
—
- Context:
stream, server
Sets an njs function which will be called at the preread phase. Module functions can be referenced.
The function is called once at the moment when the stream session reaches the preread phase for the first time. The function is called with the following arguments:
|
the stream session object |
At this phase, it is possible to perform initialization or register a callback with the s.on() method for each incoming data chunk until one of the following methods are called: s.done(), s.decline(), s.allow(). When one of these methods is called, the stream session switches to the next phase and all current s.on() callbacks are dropped.
Note
As the js_preread handler returns its result immediately, it supports only synchronous callbacks. Thus, asynchronous callbacks such as ngx.fetch() or setTimeout() are not supported. Nevertheless, asynchronous operations are supported in s.on() callbacks in the preread phase.
js_set#
- Syntax:
js_set
$variable function | module.function;- Default:
—
- Context:
stream, server
Sets an njs function for the specified variable. Module functions can be referenced.
The function is called when the variable is referenced for the first time for a given request. The exact moment depends on a phase at which the variable is referenced. This can be used to perform some logic not related to variable evaluation. For example, if the variable is referenced only in the log_format directive, its handler will not be executed until the log phase. This handler can be used to do some cleanup right before the request is freed.
Note
As the js_set handler returns its result immediately, it supports only synchronous callbacks. Thus, asynchronous callbacks such as ngx.fetch() or setTimeout() are not supported.
js_var#
- Syntax:
js_var
$variable [value];- Default:
—
- Context:
stream, server
Declares a writable variable. The value can contain text, variables, and their combination.
Session Object Properties#
Each stream njs handler receives one argument, a stream-session object.