ngx_stream_js_module.xml

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

<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>
Download and install instructions are available
<link doc="../njs/install.xml">here</link>.
</para>

</section>


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

<para>
The example works since
<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>.
<example>
stream {
    # since 0.9.1
    js_engine qjs;

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

    s.allow();
}

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

</section>


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

<directive name="js_access">
<syntax><value>module.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.
Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
a module function can be referenced.
</para>

<para>
The function is called once at the moment when the stream session reaches
the <link doc="stream_processing.xml" id="access_phase">access</link> phase
for the first time.
The function is called with the following arguments:

<list type="tag">
<tag-name><literal>s</literal></tag-name>
<tag-desc>
the <link doc="../njs/reference.xml" id="stream">Stream Session</link> object
</tag-desc>

</list>
</para>

<para>
At this phase, it is possible to perform initialization
or register a callback with
the <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
method
for each incoming data chunk until one of the following methods are called:
<link doc="../njs/reference.xml" id="s_allow"><literal>s.allow()</literal></link>,
<link doc="../njs/reference.xml" id="s_decline"><literal>s.decline()</literal></link>,
<link doc="../njs/reference.xml" id="s_done"><literal>s.done()</literal></link>.
As soon as one of these methods is called, the stream session processing
switches to the <link doc="stream_processing.xml">next phase</link>
and all current
<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
callbacks are dropped.
</para>

</directive>


<directive name="js_context_reuse">
<syntax><value>number</value></syntax>
<default>128</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.8.6</appeared-in>

<para>
Sets a maximum number of JS context to be reused for
<link doc="../njs/engine.xml">QuickJS engine</link>.
Each context is used for a single stream session.
The finished context is put into a pool of reusable contexts.
If the pool is full, the context is destroyed.
</para>

</directive>


<directive name="js_engine">
<syntax><literal>njs</literal> | <literal>qjs</literal></syntax>
<default>njs</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.8.6</appeared-in>

<para>
Sets a <link doc="../njs/engine.xml">JavaScript engine</link>
to be used for njs scripts.
The <literal>njs</literal> parameter sets the njs engine, also used by default.
The <literal>qjs</literal> parameter sets the QuickJS engine.
</para>

<para>
<note>
The <literal>njs</literal> engine is deprecated
since <link doc="../njs/changes.xml" id="njs1.0.0">1.0.0</link>;
new configurations should use the <literal>qjs</literal>
(<link doc="../njs/engine.xml" id="quickjs_engine">QuickJS</link>) engine.
</note>
</para>

</directive>


<directive name="js_fetch_buffer_size">
<syntax><value>size</value></syntax>
<default>16k</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.7.4</appeared-in>

<para>
Sets the <value>size</value> of the buffer used for reading and writing
with <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
</para>

</directive>


<directive name="js_fetch_ciphers">
<syntax><value>ciphers</value></syntax>
<default>HIGH:!aNULL:!MD5</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.7.0</appeared-in>

<para>
Specifies the enabled ciphers for HTTPS connections
with <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
The ciphers are specified in the format understood by the OpenSSL library.
</para>

<para>
The full list can be viewed using the
“<command>openssl ciphers</command>” command.
</para>

</directive>


<directive name="js_fetch_max_response_buffer_size">
<syntax><value>size</value></syntax>
<default>1m</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.7.4</appeared-in>

<para>
Sets the maximum <value>size</value> of the response received
with <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
</para>

</directive>


<directive name="js_fetch_protocols">
<syntax>
    [<literal>TLSv1</literal>]
    [<literal>TLSv1.1</literal>]
    [<literal>TLSv1.2</literal>]
    [<literal>TLSv1.3</literal>]</syntax>
<default>TLSv1 TLSv1.1 TLSv1.2</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.7.0</appeared-in>

<para>
Enables the specified protocols for HTTPS connections
with <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
</para>

</directive>


<directive name="js_fetch_timeout">
<syntax><value>time</value></syntax>
<default>60s</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.7.4</appeared-in>

<para>
Defines a timeout for reading and writing
for <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
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.
</para>

</directive>


<directive name="js_fetch_trusted_certificate">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>0.7.0</appeared-in>

<para>
Specifies a <value>file</value> with trusted CA certificates in the PEM format
used to
<link doc="../njs/reference.xml" id="fetch_verify">verify</link>
the HTTPS certificate
with <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
</para>

</directive>


<directive name="js_fetch_verify">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.7.4</appeared-in>

<para>
Enables or disables verification of the HTTPS server certificate
with <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
</para>

</directive>


<directive name="js_fetch_verify_depth">
<syntax><value>number</value></syntax>
<default>100</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.7.0</appeared-in>

<para>
Sets the verification depth in the HTTPS server certificates chain
with <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
</para>

</directive>


<directive name="js_fetch_proxy">
<syntax><value>url</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>0.9.4</appeared-in>

<para>
Configures a forward proxy URL
with <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
The <value>url</value> supports the HTTP scheme only
and can contain optional user credentials
in the format <literal>http://[user:password@]host:port</literal>
for Basic authentication.
Supports both HTTP and HTTPS connections to destination servers.
If the <value>url</value> is empty, proxy routing is disabled.
The parameter value can contain variables.
</para>

<para>
Example:
<example>
server {
    listen 12345;
    js_fetch_proxy http://user:[email protected]:3128;
    js_preread main.fetch_handler;
}
</example>
</para>

</directive>


<directive name="js_fetch_keepalive">
<syntax><value>connections</value></syntax>
<default>0</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.9.2</appeared-in>

<para>
Activates the cache for connections to destination servers.
When the value is greater than <literal>0</literal>,
enables keepalive connections for
<link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
</para>

<para>
The <value>connections</value> parameter sets the maximum number of idle
keepalive connections to destination servers that are preserved in the cache
of each worker process.
When this number is exceeded, the least recently used connections are closed.
</para>

<para>
In Stream, the cache is maintained separately for each server configuration.
A value set at the <literal>stream</literal> level is inherited by servers,
but each server uses its own cache.
Cached connections are reused for requests with the same protocol, host,
and port.
</para>

<para>
When enabled, keepalive assumes that destination servers send valid HTTP
responses.
</para>

<para>
Example:
<example>
server {
    listen 12345;
    js_fetch_keepalive 32;
    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
    js_preread main.fetch_handler;
}
</example>
</para>

</directive>


<directive name="js_fetch_keepalive_requests">
<syntax><value>number</value></syntax>
<default>1000</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.9.2</appeared-in>

<para>
Sets the maximum number of requests that can be served through one keepalive
connection with <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
After the maximum number of requests is made, the connection is closed.
</para>

<para>
Closing connections periodically is necessary to free per-connection memory
allocations.
Therefore, using too high maximum number of requests could result in
excessive memory usage and not recommended.
</para>

</directive>


<directive name="js_fetch_keepalive_time">
<syntax><value>time</value></syntax>
<default>1h</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.9.2</appeared-in>

<para>
Limits the maximum time during which requests can be processed through one
keepalive connection with <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
After this time is reached, the connection is closed following the subsequent
request processing.
</para>

</directive>


<directive name="js_fetch_keepalive_timeout">
<syntax><value>time</value></syntax>
<default>60s</default>
<context>stream</context>
<context>server</context>
<appeared-in>0.9.2</appeared-in>

<para>
Sets a timeout during which an idle keepalive connection to a destination server
will stay open with <link doc="../njs/reference.xml" id="ngx_fetch">Fetch API</link>.
</para>

</directive>


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

<para>
Sets a data filter.
Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
a module function can be referenced.
The filter function is called once at the moment when the stream session reaches
the <link doc="stream_processing.xml" id="content_phase">content</link> phase.
</para>

<para>
The filter function is called with the following arguments:
<list type="tag">
<tag-name><literal>s</literal></tag-name>
<tag-desc>
the <link doc="../njs/reference.xml" id="stream">Stream Session</link> object
</tag-desc>

</list>
</para>

<para>
At this phase, it is possible to perform initialization
or register a callback with
the <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
method for each incoming data chunk.
The
<link doc="../njs/reference.xml" id="s_off"><literal>s.off()</literal></link>
method may be used to unregister a callback and stop filtering.
</para>

<para>
<note>
As the <literal>js_filter</literal> handler
returns its result immediately, it supports
only synchronous operations.
Thus, asynchronous operations such as
<link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link>
or
<link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link>
are not supported.
</note>
</para>

</directive>


<directive name="js_import">
<syntax><value>module.js</value> |
<value>export_name from module.js</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>0.4.0</appeared-in>

<para>
Imports a module that implements location and variable handlers in njs.
The <literal>export_name</literal> is used as a namespace
to access module functions.
If the <literal>export_name</literal> is not specified,
the module name will be used as a namespace.
<example>
js_import stream.js;
</example>
Here, the module name <literal>stream</literal> is used as a namespace
while accessing exports.
If the imported module exports <literal>foo()</literal>,
<literal>stream.foo</literal> is used to refer to it.
</para>

<para>
Several <literal>js_import</literal> directives can be specified.
</para>

<para>
<note>
The directive can be specified on the
<literal>server</literal> level
since <link doc="../njs/changes.xml" id="njs0.7.7">0.7.7</link>.
</note>
</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:
<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>
The directive was made obsolete in version
<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>
and was removed in version
<link doc="../njs/changes.xml" id="njs0.7.1">0.7.1</link>.
The <link id="js_import"/> directive should be used instead.
</para>

</directive>


<directive name="js_load_stream_native_module">
<syntax><value>path</value> [<literal>as</literal> <value>name</value>]</syntax>
<default/>
<context>main</context>
<appeared-in>0.9.5</appeared-in>

<para>
Loads a <link doc="../njs/native_modules.xml">native module</link>
(shared library) for use in Stream JavaScript code.
The directive is
<link doc="../njs/engine.xml" id="quickjs_engine">QuickJS</link>-only
and is not available when using the njs built-in JavaScript engine.
</para>

<para>
The <value>path</value> parameter
specifies the absolute path to the shared library file.
The optional <literal>as</literal> <value>name</value> parameter
provides an alias name for importing the module in JavaScript code.
If not specified, the module can be imported using its filename.
</para>

<para>
Example:
<example>
js_load_stream_native_module /path/to/mylib.so;
js_load_stream_native_module /path/to/other.so as myalias;

stream {
    js_import main.js;
    # ... rest of stream configuration
}
</example>
In JavaScript code:
<example>
// Import by filename
import * as mylib from 'mylib.so';

// Import by alias
import * as myalias from 'myalias';

// Use exported functions
let result = mylib.add(5, 10);
</example>
</para>

<para>
<note>
For security reasons, this directive is only allowed
in the <literal>main</literal> configuration context.
Native modules run with full process privileges;
use absolute paths and ensure proper code review.
</note>
</para>

</directive>


<directive name="js_path">
<syntax>
<value>path</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>0.3.0</appeared-in>

<para>
Sets an additional path for njs modules.
</para>

<para>
<note>
The directive can be specified on the
<literal>server</literal> level
since <link doc="../njs/changes.xml" id="njs0.7.7">0.7.7</link>.
</note>
</para>

</directive>


<directive name="js_periodic">
<syntax><value>module.function</value>
        [<literal>interval</literal>=<value>time</value>]
        [<literal>jitter</literal>=<value>number</value>]
        [<literal>worker_affinity</literal>=<value>mask</value>]</syntax>
<default/>
<context>server</context>
<appeared-in>0.8.1</appeared-in>

<para>
Specifies a content handler to run at regular interval.
The handler receives a
<link doc="../njs/reference.xml" id="periodic_session">session object</link>
as its first argument,
it also has access to global objects such as
<link doc="../njs/reference.xml" id="ngx">ngx</link>.
</para>

<para>
The optional <literal>interval</literal> parameter
sets the interval between two consecutive runs,
by default, 5 seconds.
</para>

<para>
The optional <literal>jitter</literal> parameter sets the time within which
the location content handler will be randomly delayed,
by default, there is no delay.
</para>

<para>
By default, the <literal>js_handler</literal> is executed on worker process 0.
The optional <literal>worker_affinity</literal> parameter
allows specifying particular worker processes
where the location content handler should be executed.
Each worker process set is represented by a bitmask of allowed worker processes.
The <literal>all</literal> mask allows the handler to be executed
in all worker processes.
</para>

<para>
Example:
<example>
example.conf:

location @periodics {
    # to be run at 1 minute intervals in worker process 0
    js_periodic main.handler interval=60s;

    # to be run at 1 minute intervals in all worker processes
    js_periodic main.handler interval=60s worker_affinity=all;

    # to be run at 1 minute intervals in worker processes 1 and 3
    js_periodic main.handler interval=60s worker_affinity=0101;

    resolver 10.0.0.1;
    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
}

example.js:

async function handler(s) {
    let reply = await ngx.fetch('https://nginx.org/en/docs/njs/');
    let body = await reply.text();

    ngx.log(ngx.INFO, body);
}
</example>
</para>

</directive>


<directive name="js_preload_object">
<syntax><value>name.json</value> |
<value>name</value> from <value>file.json</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>0.7.8</appeared-in>

<para>
Preloads an
<link doc="../njs/preload_objects.xml">immutable object</link>
at configure time.
The <literal>name</literal> is used as a name of the global variable
though which the object is available in njs code.
If the <literal>name</literal> is not specified,
the file name will be used instead.
<example>
js_preload_object map.json;
</example>
Here, the <literal>map</literal> is used as a name
while accessing the preloaded object.
</para>

<para>
Several <literal>js_preload_object</literal> directives can be specified.
</para>

</directive>


<directive name="js_preread">
<syntax><value>module.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.
Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
a module function can be referenced.
</para>

<para>
The function is called once
at the moment when the stream session reaches the
<link doc="stream_processing.xml" id="preread_phase">preread</link> phase
for the first time.
The function is called with the following arguments:

<list type="tag">
<tag-name><literal>s</literal></tag-name>
<tag-desc>
the <link doc="../njs/reference.xml" id="stream">Stream Session</link> object
</tag-desc>

</list>
</para>

<para>
At this phase, it is possible to perform initialization
or register a callback with
the <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
method
for each incoming data chunk until one of the following methods are called:
<link doc="../njs/reference.xml" id="s_allow"><literal>s.allow()</literal></link>,
<link doc="../njs/reference.xml" id="s_decline"><literal>s.decline()</literal></link>,
<link doc="../njs/reference.xml" id="s_done"><literal>s.done()</literal></link>.
When one of these methods is called,
the stream session switches to the
<link doc="stream_processing.xml">next phase</link>
and all current
<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
callbacks are dropped.
</para>

<para>
<note>
As the <literal>js_preread</literal> handler
returns its result immediately, it supports
only synchronous callbacks.
Thus, asynchronous callbacks such as
<link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link>
or
<link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link>
are not supported.
Nevertheless, asynchronous operations are supported in
<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
callbacks in the
<link doc="stream_processing.xml" id="preread_phase">preread</link> phase.
See
<link url="https://github.com/nginx/njs-examples#authorizing-connections-using-ngx-fetch-as-auth-request-stream-auth-request">this example</link> for more information.
</note>
</para>

</directive>


<directive name="js_set">
<syntax>
    <value>$variable</value>
    <value>module.function</value>
    [<literal>nocache</literal>]</syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Sets an njs <literal>function</literal>
for the specified <literal>variable</literal>.
Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
a module function can be referenced.
</para>

<para>
The function is called when
the variable is referenced for the first time for a given request.
The exact moment depends on a
<link doc="stream_processing.xml">phase</link>
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
<link doc="ngx_stream_log_module.xml" id="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.
</para>

<para>
Since <link doc="../njs/changes.xml" id="njs0.8.6">0.8.6</link>, when
optional argument <literal>nocache</literal> is provided the handler
is called every time it is referenced.
Due to current limitations
of the <link doc="ngx_stream_rewrite_module.xml">rewrite</link> module,
when a <literal>nocache</literal> variable is referenced by the
<link doc="ngx_stream_set_module.xml" id="set">set</link> directive
its handler should always return a fixed-length value.
</para>

<para>
<note>
As the <literal>js_set</literal> handler
returns its result immediately, it supports
only synchronous callbacks.
Thus, asynchronous callbacks such as
<link doc="../njs/reference.xml" id="ngx_fetch">ngx.fetch()</link>
or
<link doc="../njs/reference.xml" id="settimeout">setTimeout()</link>
are not supported.
</note>
</para>

<para>
<note>
The directive can be specified on the
<literal>server</literal> level
since <link doc="../njs/changes.xml" id="njs0.7.7">0.7.7</link>.
</note>
</para>

</directive>


<directive name="js_shared_dict_zone">
<syntax>
    <literal>zone</literal>=<value>name</value>:<value>size</value>
    [<literal>timeout</literal>=<value>time</value>]
    [<literal>type</literal>=<literal>string</literal>|<literal>number</literal>]
    [<literal>evict</literal>]
    [<literal>state</literal>=<value>file</value>]</syntax>
<default/>
<context>stream</context>
<appeared-in>0.8.0</appeared-in>

<para>
Sets the <value>name</value> and <value>size</value> of the shared memory zone
that keeps the
key-value <link doc="../njs/reference.xml" id="dict">dictionary</link>
shared between worker processes.
</para>

<para>
By default the shared dictionary uses a string as a key and a value.
The optional <literal>type</literal> parameter
allows redefining the value type to number.
</para>

<para>
The optional <literal>timeout</literal> parameter sets
the time in milliseconds
after which all shared dictionary entries are removed from the zone.
If some entries require a different removal time, it can be set
with the <literal>timeout</literal> argument of the
<link doc="../njs/reference.xml" id="dict_add">add</link>,
<link doc="../njs/reference.xml" id="dict_incr">incr</link>, and
<link doc="../njs/reference.xml" id="dict_set">set</link>
methods
(<link doc="../njs/changes.xml" id="njs0.8.5">0.8.5</link>).
</para>

<para>
The optional <literal>evict</literal> parameter removes the oldest
key-value pair when the zone storage is exhausted.
</para>

<para>
The optional <literal>state</literal> parameter specifies a <value>file</value>
that keeps the shared dictionary state
in JSON format and makes it persistent across nginx restarts
(<link doc="../njs/changes.xml" id="njs0.9.1">0.9.1</link>).
</para>

<para>
Example:
<example>
example.conf:
    # Creates a 1Mb dictionary with string values,
    # removes key-value pairs after 60 seconds of inactivity:
    js_shared_dict_zone zone=foo:1M timeout=60s;

    # Creates a 512Kb dictionary with string values,
    # forcibly removes oldest key-value pairs when the zone is exhausted:
    js_shared_dict_zone zone=bar:512K timeout=30s evict;

    # Creates a 32Kb permanent dictionary with number values:
    js_shared_dict_zone zone=num:32k type=number;

    # Creates a 1Mb dictionary with string values and persistent state:
    js_shared_dict_zone zone=persistent:1M state=/tmp/dict.json;

example.js:
    function get(r) {
        r.return(200, ngx.shared.foo.get(r.args.key));
    }

    function set(r) {
        r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));
    }

    function del(r) {
        r.return(200, ngx.shared.bar.delete(r.args.key));
    }

    function increment(r) {
        r.return(200, ngx.shared.num.incr(r.args.key, 2));
    }
</example>
</para>

</directive>


<directive name="js_var">
<syntax><value>$variable</value> [<value>value</value>]</syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>0.5.3</appeared-in>

<para>
Declares
a <link doc="../njs/reference.xml" id="r_variables">writable</link>
variable.
The value can contain text, variables, and their combination.
</para>

<para>
<note>
The directive can be specified on the
<literal>server</literal> level
since <link doc="../njs/changes.xml" id="njs0.7.7">0.7.7</link>.
</note>
</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>