Модуль ngx_stream_js_module

• Пример конфигурации
• Директивы
• js_access
• js_context_reuse
• js_engine
• js_fetch_buffer_size
• js_fetch_ciphers
• js_fetch_max_response_buffer_size
• js_fetch_protocols
• js_fetch_timeout
• js_fetch_trusted_certificate
• js_fetch_verify
• js_fetch_verify_depth
• js_fetch_proxy
• js_fetch_keepalive
• js_fetch_keepalive_requests
• js_fetch_keepalive_time
• js_fetch_keepalive_timeout
• js_filter
• js_import
• js_include
• js_load_stream_native_module
• js_path
• js_periodic
• js_preload_object
• js_preread
• js_set
• js_shared_dict_zone
• js_var
• Свойства объекта сеанса

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

Инструкции по загрузке и установке доступны здесь.

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

Пример работает начиная с версии 0.4.0.

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

Файл stream.js:

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

Директивы

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

Функция вызывается один раз, когда сеанс потока впервые достигает фазы доступа. Функции передаются следующие аргументы:

s

объект сеанса потока

На этой фазе можно выполнить инициализацию или зарегистрировать с помощью метода s.on() обратный вызов для каждого входящего фрагмента данных, пока не будет вызван один из следующих методов: s.allow(), s.decline(), s.done(). Как только будет вызван один из этих методов, обработка сеанса потока перейдет к следующей фазе, а все текущие обратные вызовы s.on() будут отменены.

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

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

Движок njs объявлен устаревшим начиная с версии 1.0.0; в новых конфигурациях следует использовать движок qjs (QuickJS).

Задает size буфера, используемого для чтения и записи с помощью Fetch API.

Задает набор шифров для HTTPS-соединений с помощью Fetch API. Шифры указываются в формате, понятном библиотеке OpenSSL.

Полный список можно посмотреть с помощью команды «openssl ciphers».

Задает максимальный size ответа, получаемого с помощью Fetch API.

Включает указанные протоколы для HTTPS-соединений с помощью Fetch API.

Задает тайм-аут чтения и записи для Fetch API. Тайм-аут действует только между двумя последовательными операциями чтения/записи, а не в течение всего времени получения ответа. Если в течение этого времени данные не передаются, соединение закрывается.

Указывает file с доверенными сертификатами CA в формате PEM, используемый для проверки HTTPS-сертификата с помощью Fetch API.

Включает или отключает проверку сертификата HTTPS-сервера с помощью Fetch API.

Задает глубину проверки цепочки сертификатов HTTPS-сервера с помощью Fetch API.

Настраивает URL прямого прокси-сервера для Fetch API. Параметр url поддерживает только схему HTTP и может содержать учетные данные пользователя в формате http://[user:password@]host:port для базовой аутентификации. Поддерживаются как HTTP-, так и HTTPS-соединения с целевыми серверами. Если url пуст, маршрутизация через прокси отключена. Значение параметра может содержать переменные.

Пример:

server {
    listen 12345;
    js_fetch_proxy http://user:pass@proxy.example.com:3128;
    js_preread main.fetch_handler;
}

Активирует кэш соединений с целевыми серверами. Если значение больше 0, для Fetch API включаются постоянные соединения.

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

Пример:

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

Задает максимальное число запросов, которые можно обслужить через одно постоянное соединение с помощью Fetch API. После обработки максимального числа запросов соединение закрывается.

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

Ограничивает максимальное время обработки запросов через одно постоянное соединение с помощью Fetch API. По истечении этого времени соединение закрывается после обработки следующего запроса.

Задает тайм-аут, в течение которого незанятое постоянное соединение с целевым сервером остается открытым для Fetch API.

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

Функции фильтра передаются следующие аргументы:

s

объект сеанса потока

На этой фазе можно выполнить инициализацию или зарегистрировать с помощью метода s.on() обратный вызов для каждого входящего фрагмента данных. Метод s.off() можно использовать для отмены регистрации обратного вызова и остановки фильтрации.

Поскольку обработчик js_filter немедленно возвращает результат, он поддерживает только синхронные операции. Поэтому асинхронные операции, такие как ngx.fetch() или setTimeout(), не поддерживаются.

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

js_import stream.js;

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

Можно указать несколько директив js_import.

Начиная с версии 0.7.7, директиву можно указывать на уровне server.

Указывает файл, реализующий обработчики сервера и переменных в 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;
}

Директива устарела в версии 0.4.0 и была удалена в версии 0.7.1. Вместо нее следует использовать директиву js_import.

Загружает нативный модуль (разделяемую библиотеку) для использования в коде Stream JavaScript. Директива доступна только для QuickJS и не работает при использовании встроенного движка JavaScript njs.

Параметр path задает абсолютный путь к файлу разделяемой библиотеки. Необязательный параметр as name задает псевдоним для импорта модуля в коде JavaScript. Если он не указан, модуль можно импортировать по имени файла.

Пример:

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
}

В коде JavaScript:

// 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);

В целях безопасности эту директиву разрешено использовать только в контексте конфигурации main. Нативные модули выполняются с полными привилегиями процесса; используйте абсолютные пути и тщательно проверяйте код.

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

Начиная с версии 0.7.7, директиву можно указывать на уровне server.

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

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

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

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

Пример:

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

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

js_preload_object map.json;

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

Можно указать несколько директив js_preload_object.

Задает функцию njs, которая будет вызвана на фазе предварительного чтения. Начиная с версии 0.4.0, можно ссылаться на функцию модуля.

Функция вызывается один раз, когда сеанс потока впервые достигает фазы предварительного чтения. Функции передаются следующие аргументы:

s

объект сеанса потока

На этой фазе можно выполнить инициализацию или зарегистрировать с помощью метода s.on() обратный вызов для каждого входящего фрагмента данных, пока не будет вызван один из следующих методов: s.allow(), s.decline(), s.done(). При вызове одного из этих методов сеанс потока переходит к следующей фазе, а все текущие обратные вызовы s.on() отменяются.

Поскольку обработчик js_preread немедленно возвращает результат, он поддерживает только синхронные обратные вызовы. Поэтому асинхронные обратные вызовы, такие как ngx.fetch() или setTimeout(), не поддерживаются. Тем не менее асинхронные операции поддерживаются в обратных вызовах s.on() на фазе предварительного чтения. Дополнительные сведения см. в этом примере.

Задает обработчик njs function для указанной variable. Начиная с версии 0.4.0, можно ссылаться на функцию модуля.

Функция вызывается при первом обращении к переменной для данного запроса. Точный момент зависит от фазы, на которой происходит обращение к переменной. Это можно использовать для выполнения логики, не связанной с вычислением переменной. Например, если переменная используется только в директиве log_format, ее обработчик будет выполнен лишь на фазе журналирования. Этот обработчик можно использовать для очистки непосредственно перед освобождением запроса.

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

Поскольку обработчик js_set немедленно возвращает результат, он поддерживает только синхронные обратные вызовы. Поэтому асинхронные обратные вызовы, такие как ngx.fetch() или setTimeout(), не поддерживаются.

Начиная с версии 0.7.7, директиву можно указывать на уровне server.

Задает name и size разделяемой зоны памяти, в которой хранится общий для рабочих процессов словарь «ключ-значение».

По умолчанию в разделяемом словаре в качестве ключа и значения используются строки. Необязательный параметр type позволяет изменить тип значения на число.

Необязательный параметр timeout задает время в миллисекундах, по истечении которого все записи разделяемого словаря удаляются из зоны. Если для некоторых записей требуется другое время удаления, его можно задать аргументом timeout методов add, incr и set (0.8.5).

Необязательный параметр evict удаляет самую старую пару «ключ-значение», когда место в зоне заканчивается.

Необязательный параметр state задает file, который хранит состояние разделяемого словаря в формате JSON и сохраняет его после перезапуска nginx (0.9.1).

Пример:

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

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

Начиная с версии 0.7.7, директиву можно указывать на уровне server.

Свойства объекта сеанса

Каждый обработчик njs потока получает один аргумент — объект сеанса потока.