<!-- review: finished -->

<a id="stream-js"></a>

# JS

Позволяет задавать обработчики на njs — подмножестве языка JavaScript.

В наших репозиториях модуль собран [динамически](https://angie.software//angie/docs/installation/index.md#install-dynamicmodules) и
доступен отдельным пакетом `angie-module-njs` или `angie-pro-module-njs`;
подключить его можно с помощью директивы [load_module](https://angie.software//angie/docs/configuration/modules/core.md#load-module).

#### NOTE
Также доступна упрощенная версия пакета под названием `...-njs-light`;
однако она несовместима с обычной версией и не может
использоваться одновременно с ней.

<a id="configuration-example-100"></a>

## Пример конфигурации

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

Файл `stream.js`:

```javascript
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-заголовка в запрос клиента

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

<a id="directives-88"></a>

## Директивы

<a id="index-0"></a>

<a id="s-js-access"></a>

### js_access

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_access` функция | модуль.функция;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию                                                                             | —                                       |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                          |

Задает функцию njs, которая будет вызываться в [access-фазе](https://angie.software//angie/docs/configuration/processing.md#stream-sessions). Можно ссылаться на функцию модуля.

Функция вызывается однократно при первом достижении сессией [access-фазе](https://angie.software//angie/docs/configuration/processing.md#stream-sessions). Функция вызывается со следующими аргументами:

| `s`   | объект [stream-сессии](https://angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session)   |
|-------|----------------------------------------------------------------------------------------------------------------|

В этой фазе может происходить инициализация, также при помощи метода [s.on()](https://angie.software//angie/docs/configuration/njs-reference.md#s-on) может регистрироваться вызов для каждого входящего блока данных пока не будет вызван один из методов: [s.done()](https://angie.software//angie/docs/configuration/njs-reference.md#njs-s-done), [s.decline()](https://angie.software//angie/docs/configuration/njs-reference.md#njs-s-decline), [s.allow()](https://angie.software//angie/docs/configuration/njs-reference.md#njs-s-allow). При вызове любого из этих методов обработка сессии переходит на [следующую фазу](https://angie.software//angie/docs/configuration/processing.md#stream-sessions) и все текущие вызовы [s.on()](https://angie.software//angie/docs/configuration/njs-reference.md#s-on) сбрасываются.

<a id="index-1"></a>

<a id="s-js-context-reuse"></a>

### js_context_reuse

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_context_reuse` число;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию                                                                             | `js_context_reuse 128;`     |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server              |

Устанавливает максимальное количество контекстов JS для повторного использования движком QuickJS. Каждый контекст используется для одной потоковой сессии. Завершенный контекст помещается в пул повторно используемых контекстов. Если пул заполнен, контекст уничтожается.

<a id="index-2"></a>

<a id="s-js-engine"></a>

### js_engine

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_engine` `njs` | `qjs`;   |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию                                                                             | `js_engine njs;`             |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server               |

Устанавливает движок JavaScript для использования в скриптах njs. Параметр `njs` задает движок njs, также используемый по умолчанию. Параметр `qjs` задает движок QuickJS.

<a id="index-3"></a>

<a id="s-js-fetch-buffer-size"></a>

### js_fetch_buffer_size

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_buffer_size` размер;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию                                                                             | `js_fetch_buffer_size 16k;`      |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                   |

Задает размер буфера, который будет использоваться для чтения и записи для [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).

<a id="index-4"></a>

<a id="s-js-fetch-ciphers"></a>

### js_fetch_ciphers

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_ciphers` шифры;            |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию                                                                             | `js_fetch_ciphers HIGH:!aNULL:!MD5;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                       |

Описывает разрешенные шифры для HTTPS-соединений при помощи [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.

Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.

<a id="index-5"></a>

<a id="s-js-fetch-max-response-buffer-size"></a>

### js_fetch_max_response_buffer_size

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_max_response_buffer_size` размер;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию                                                                             | `js_fetch_max_response_buffer_size 1m;`       |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                                |

Задает максимальный размер ответа, полученного при помощи [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).

<a id="index-6"></a>

<a id="s-js-fetch-protocols"></a>

### js_fetch_protocols

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_protocols` [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| По умолчанию                                                                             | `js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;`                           |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                                                        |

Разрешает указанные протоколы для HTTPS-соединений при помощи [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).

<a id="index-7"></a>

<a id="s-js-fetch-timeout"></a>

### js_fetch_timeout

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_timeout` время;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию                                                                             | `js_fetch_timeout 60s;`     |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server              |

Задает таймаут при чтении и записи при помощи [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени данные не передавались, соединение закрывается.

<a id="index-8"></a>

<a id="s-js-fetch-trusted-certificate"></a>

### js_fetch_trusted_certificate

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_trusted_certificate` файл;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию                                                                             | —                                      |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                         |

Задает файл с доверенными сертификатами CA в формате PEM, используемыми при проверке HTTPS-сертификата при помощи [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).

<a id="index-9"></a>

<a id="s-js-fetch-verify"></a>

### js_fetch_verify

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_verify` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию                                                                             | `js_fetch_verify on;`             |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                    |

Разрешает или запрещает проверку сертификата HTTPS-сервера при помощи [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).

<a id="index-10"></a>

<a id="s-js-fetch-verify-depth"></a>

### js_fetch_verify_depth

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_verify_depth` число;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию                                                                             | `js_fetch_verify_depth 100;`     |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                   |

Устанавливает глубину проверки в цепочке HTTPS-сертификатов при помощи [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).

<a id="index-11"></a>

<a id="s-js-fetch-keepalive"></a>

### js_fetch_keepalive

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive` соединения;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию                                                                             | `js_fetch_keepalive 0;`            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                     |

Активирует кэш соединений к серверам назначения. Когда значение больше `0`, включает keepalive-соединения для [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).

Параметр соединения задает максимальное количество неактивных keepalive-соединений к серверам назначения, которые сохраняются в кэше каждого рабочего процесса. Когда это число превышено, закрываются наименее недавно использованные соединения.

Пример:

```nginx
server {
    listen 12345;
    js_fetch_keepalive 32;
    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
    js_preread main.fetch_handler;
}
```

<a id="index-12"></a>

<a id="s-js-fetch-keepalive-requests"></a>

### js_fetch_keepalive_requests

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive_requests` число;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию                                                                             | `js_fetch_keepalive_requests 1000;`    |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                         |

Задает максимальное количество запросов, которые могут обрабатываться через одно keepalive-соединение с [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). После выполнения максимального количества запросов соединение закрывается.

Периодическое закрытие соединений необходимо для освобождения выделенной памяти для каждого соединения. Поэтому использование слишком большого максимального количества запросов может привести к чрезмерному использованию памяти и не рекомендуется.

<a id="index-13"></a>

<a id="s-js-fetch-keepalive-time"></a>

### js_fetch_keepalive_time

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive_time` время;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию                                                                             | `js_fetch_keepalive_time 1h;`      |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                     |

Ограничивает максимальное время, в течение которого запросы могут обрабатываться через одно keepalive-соединение с [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). По достижении этого времени соединение закрывается после обработки следующего запроса.

<a id="index-14"></a>

<a id="s-js-fetch-keepalive-timeout"></a>

### js_fetch_keepalive_timeout

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive_timeout` время;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию                                                                             | `js_fetch_keepalive_timeout 60s;`     |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                        |

Задает таймаут, в течение которого неактивное keepalive-соединение к серверу назначения остается открытым при помощи [Fetch API](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).

<a id="index-15"></a>

<a id="s-js-filter"></a>

### js_filter

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_filter` функция | модуль.функция;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию                                                                             | —                                       |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                          |

Задает фильтр данных. Можно ссылаться на функцию модуля.

Функция фильтра вызывается однократно при первом достижении сессией [content-фазы](https://angie.software//angie/docs/configuration/processing.md#stream-sessions). Функция фильтра вызывается со следующими аргументами:

| `s`   | объект [stream-сессии](https://angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session)   |
|-------|----------------------------------------------------------------------------------------------------------------|

В этой фазе может происходить инициализация, также при помощи метода [s.on()](https://angie.software//angie/docs/configuration/njs-reference.md#s-on) может регистрироваться вызов для каждого входящего блока данных. Для отмены регистрации вызова и отмены фильтра можно использовать метод [s.off()](https://angie.software//angie/docs/configuration/njs-reference.md#s-off).

#### NOTE
Так как обработчик js_filter должен сразу возвращать результат, то поддерживаются только синхронные операции. Таким образом, асинхронные операции, например [ngx.fetch()](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) или [setTimeout()](https://angie.software//angie/docs/configuration/njs-reference.md#njs-timers), не поддерживаются.

<a id="index-16"></a>

<a id="s-js-import"></a>

### js_import

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_import` модуль.js | имя_экспорта from модуль.js;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------|
| По умолчанию                                                                             | —                                                      |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                                         |

Импортирует модуль, позволяющий задавать обработчики location и переменных на njs. Имя_экспорта является пространством имен при доступе к функциям модуля. Если имя_экспорта не задано, то пространством имен будет являться имя модуля.

```nginx
js_import stream.js;
```

В примере при доступе к экспорту в качестве пространства имен используется имя модуля stream. Если импортируемый модуль экспортирует foo(), то для доступа используется stream.foo.

Директив js_import может быть несколько.

<a id="index-17"></a>

<a id="s-js-path"></a>

### js_path

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_path` путь;   |
|------------------------------------------------------------------------------------------|-------------------|
| По умолчанию                                                                             | —                 |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server    |

Задает дополнительный путь для модулей njs.

<a id="index-18"></a>

<a id="s-js-periodic"></a>

### js_periodic

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_periodic` модуль.функция [`interval=`\\ время] [`jitter=`\\ число] [`worker_affinity=`\\ маска];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| По умолчанию                                                                             | —                                                                                                      |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | server                                                                                                 |

Задает обработчик содержимого для запуска через регулярные интервалы. Обработчик получает объект сеанса в качестве первого аргумента, он также имеет доступ к глобальным объектам, таким как `ngx`.

Необязательный параметр `interval` задает интервал между двумя последовательными запусками, по умолчанию — 5 секунд.

Необязательный параметр `jitter` задает время, в течение которого обработчик содержимого location будет случайно задержан, по умолчанию задержки нет.

По умолчанию `js_handler` выполняется в рабочем процессе 0. Необязательный параметр `worker_affinity` позволяет указать определенные рабочие процессы, в которых должен выполняться обработчик содержимого location. Каждый набор рабочих процессов представлен битовой маской разрешенных рабочих процессов. Маска `all` позволяет выполнять обработчик во всех рабочих процессах.

Пример:

```nginx
example.conf:

location @periodics {
    # запуск с интервалом в 1 минуту в рабочем процессе 0
    js_periodic main.handler interval=60s;

    # запуск с интервалом в 1 минуту во всех рабочих процессах
    js_periodic main.handler interval=60s worker_affinity=all;

    # запуск с интервалом в 1 минуту в рабочих процессах 1 и 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;
}
```

```javascript
example.js:

async function handler(s) {
    let reply = await ngx.fetch('https://example.com/');
    let body = await reply.text();

    ngx.log(ngx.INFO, body);
}
```

<a id="index-19"></a>

<a id="s-js-preload-object"></a>

### js_preload_object

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_preload_object` имя.json | имя from файл.json;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------|
| По умолчанию                                                                             | —                                                    |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                                       |

Предварительно загружает неизменяемый объект во время конфигурации. Имя используется в качестве имени глобальной переменной, через которую объект доступен в коде njs. Если имя не указано, то будет использоваться имя файла.

```nginx
js_preload_object map.json;
```

В примере map используется в качестве имени во время доступа к предварительно загруженному объекту.

Директив js_preload_object может быть несколько.

<a id="index-20"></a>

<a id="s-js-preread"></a>

### js_preread

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_preread` функция | модуль.функция;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию                                                                             | —                                        |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                           |

Задает функцию njs, которая будет вызываться в [preread-фазе](https://angie.software//angie/docs/configuration/processing.md#stream-sessions). Можно ссылаться на функцию модуля.

Функция вызывается однократно при первом достижении сессией [preread-фазы](https://angie.software//angie/docs/configuration/processing.md#stream-sessions). Функция вызывается со следующими аргументами:

| `s`   | объект [stream-сессии](https://angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session)   |
|-------|----------------------------------------------------------------------------------------------------------------|

В этой фазе может происходить инициализация, также при помощи метода [s.on()](https://angie.software//angie/docs/configuration/njs-reference.md#s-on) может регистрироваться вызов для каждого входящего блока данных пока не будет вызван один из методов: [s.done()](https://angie.software//angie/docs/configuration/njs-reference.md#njs-s-done), [s.decline()](https://angie.software//angie/docs/configuration/njs-reference.md#njs-s-decline), [s.allow()](https://angie.software//angie/docs/configuration/njs-reference.md#njs-s-allow). При вызове любого из этих методов обработка сессии переходит [на следующую фазу](https://angie.software//angie/docs/configuration/processing.md#stream-sessions) и все текущие вызовы [s.on()](https://angie.software//angie/docs/configuration/njs-reference.md#s-on) сбрасываются.

#### NOTE
Так как обработчик js_preread должен сразу возвращать результат, то поддерживаются только синхронные операции. Таким образом, асинхронные операции, например [ngx.fetch()](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) или [setTimeout()](https://angie.software//angie/docs/configuration/njs-reference.md#njs-timers), не поддерживаются. Тем не менее асинхронные операции поддерживаются в вызовах [s.on()](https://angie.software//angie/docs/configuration/njs-reference.md#s-on) в [preread-фазе](https://angie.software//angie/docs/configuration/processing.md#stream-sessions).

<a id="index-21"></a>

<a id="s-js-set"></a>

### js_set

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_set` $переменная функция | модуль.функция [`nocache`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| По умолчанию                                                                             | —                                                            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                                               |

Задает функцию njs для указанной переменной. Можно ссылаться на функцию модуля.

Функция вызывается в момент первого обращения к переменной для данного запроса. Точный момент вызова функции зависит от [фазы](https://angie.software//angie/docs/configuration/processing.md#stream-sessions), в которой происходит обращение к переменной. Это можно использовать для реализации дополнительной логики, не относящейся к вычислению переменной. Например, если переменная указана в директиве [log_format](https://angie.software//angie/docs/configuration/modules/stream/stream_log.md#s-log-format), то ее обработчик не будет выполняться до фазы записи в лог. Этот обработчик также может использоваться для выполнения процедур непосредственно перед освобождением запроса.

Начиная с njs 0.8.6, если указан необязательный аргумент `nocache`, обработчик вызывается каждый раз при обращении к нему. Из-за текущих ограничений модуля rewrite, когда переменная `nocache` используется директивой set, ее обработчик должен всегда возвращать значение фиксированной длины.

#### NOTE
Так как обработчик js_set должен сразу возвращать результат, то поддерживаются только синхронные операции. Таким образом, асинхронные операции, например [ngx.fetch()](https://angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) или [setTimeout()](https://angie.software//angie/docs/configuration/njs-reference.md#njs-timers), не поддерживаются.

<a id="index-22"></a>

<a id="s-js-shared-dict-zone"></a>

### js_shared_dict_zone

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_shared_dict_zone` `zone=`имя:размер [`timeout=`время] [`type=``string` | `number`] [`evict`] [`state=`файл];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| По умолчанию                                                                             | —                                                                                                                  |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream                                                                                                             |

Задает имя и размер зоны разделяемой памяти, в которой хранится словарь ключей и значений, разделяемый между рабочими процессами.

| `type`    | Необязательный параметр, позволяет изменить тип значения на числовой<br/>(`number`); по умолчанию в качестве ключа и значения<br/>используется строка (`string`).   |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | Необязательный параметр, задает время, по завершении которого все записи в словаре удаляются из зоны.                                                               |
| `evict`   | Необязательный параметр, удаляет самую старую пару "ключ-значение" при переполнении зоны.                                                                           |
| `state`   | необязательный параметр, указывает файл, который хранит состояние разделяемого словаря в формате JSON и делает его постоянным при перезапусках nginx                |

Пример:

```nginx
example.conf:
# Создается словарь размером 1Мб со строковыми значениями,
# пары "ключ-значение" удаляются при отсутствии активности в течение 60 секунд:
js_shared_dict_zone zone=foo:1M timeout=60s;

# Создается словарь размером 512Кб со строковыми значениями,
# удаляется самая старая пара "ключ-значение" при переполнении зоны:
js_shared_dict_zone zone=bar:512K timeout=30s evict;

# Создается постоянный словарь размером 32Кб с числовыми значениями:
js_shared_dict_zone zone=num:32k type=number;

# Создается словарь размером 1Мб со строковыми значениями и постоянным состоянием:
js_shared_dict_zone zone=persistent:1M state=/tmp/dict.json;
```

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

<a id="index-23"></a>

<a id="s-js-var"></a>

### js_var

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_var` $переменная [значение];   |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию                                                                             | —                                  |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                     |

Объявляет [перезаписываемую](https://angie.software//angie/docs/configuration/njs-reference.md#s-variables) переменную. В качестве значения можно использовать текст, переменные и их комбинации.

<a id="session-object-properties"></a>

## Свойства объекта сессии

Каждый stream-обработчик njs получает один аргумент, объект [stream-сессии](https://angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session).