Модуль ngx_stream_js_module

• Пример конфигурации
• Директивы
• js_access
• 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_filter
• js_import
• js_include
• 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 {
    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() отбрасываются.

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

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

Полный список можно просмотреть, используя команду “openssl ciphers”.

Устанавливает максимальный размер буфера ответа, полученного с помощью Fetch API.

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

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

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

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

Устанавливает глубину проверки в цепочке HTTPS-сертификатов сервера с помощью 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.

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

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

Устанавливает дополнительный путь для njs-модулей.

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

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

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

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

По умолчанию, js_handler выполняется в процессе рабочего процесса 0. Необязательный параметр worker_affinity позволяет указать конкретные рабочие процессы, в которых должен выполняться обработчик содержимого местоположения. Каждый набор рабочих процессов представлен маской битов разрешенных рабочих процессов. Маска 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, её обработчик не будет выполнен до стадии логгирования. Этот обработчик может использоваться для выполнения очистки непосредственно перед освобождением запроса.

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

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

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

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

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

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

Пример:

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;

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

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

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

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

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