模块 ngx_stream_js_module

这ngx_stream_js_modulemodule 用于实现 njs 中的 handlers — 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 开始， 可以引用 Module 函数。

该函数在流会话达到 访问阶段 第一次。 使用以下参数调用该函数：

s

Stream Session 对象

在此阶段，可以执行初始化 或注册回调 这s.on()方法 对于每个传入数据块，直到调用以下方法之一：s.allow(),s.decline(),s.done(). 一旦调用了这些方法之一，流式会话处理 切换到下一阶段和所有电流s.on()回调被丢弃。

js_context_reuse 128;

设置要用于 QuickJS 引擎的 JS 上下文的最大数量。 每个上下文都用于单个流会话。 完成的上下文被放入一个可重用上下文池中。 如果池已满，则销毁上下文。

js_engine njs;

设置用于 njs 脚本的 JavaScript 引擎。 这njsparameter 设置 NJS 引擎，默认情况下也使用。 这qjs参数设置 QuickJS 引擎。

js_fetch_buffer_size 16k;

设置size用于读取和写入的缓冲区 使用 Fetch API。

js_fetch_ciphers HIGH:!aNULL:!MD5;

指定为 HTTPS 连接启用的密码 使用 Fetch API。 密码以 OpenSSL 库理解的格式指定。

完整列表可使用 “openssl ciphers“命令。

js_fetch_max_response_buffer_size 1m;

设置最大值size收到的响应 使用 Fetch API。

js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;

为 HTTPS 连接启用指定的协议 使用 Fetch API。

js_fetch_timeout 60s;

定义读取和写入的超时 以获取 Fetch API。 超时仅在两个连续的读/写作之间设置， 不是为了整个回应。 如果在此时间内未传输任何数据，则连接将关闭。

指定file使用 PEM 格式的受信任 CA 证书 用于验证 HTTPS 证书 使用 Fetch API。

js_fetch_verify on;

启用或禁用 HTTPS 服务器证书的验证 使用 Fetch API。

js_fetch_verify_depth 100;

在 HTTPS 服务器证书链中设置验证深度 使用 Fetch API。

设置数据筛选器。 从 0.4.0 开始， 可以引用 Module 函数。 filter 函数在流会话达到 内容阶段。

使用以下参数调用 filter 函数：

s

Stream Session 对象

在此阶段，可以执行初始化 或注册回调 这s.on()方法。 这s.off()method 可用于取消注册回调并停止筛选。

由于js_filter处理器 立即返回其结果，则支持 仅限同步作。 因此，异步作（例如ngx.fetch()或setTimeout()不受支持。

导入一个在 njs 中实现位置和变量处理程序的模块。 这export_name用作命名空间 以访问模块功能。 如果export_name未指定， 模块名称将用作命名空间。

js_import stream.js;

此处，模块名称stream用作命名空间 在访问导出时。 如果导入的模块导出foo(),stream.foo用于指代它。

几个js_import可以指定Directives。

可以在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;
}

该Directives在 0.4.0 版中过时，并在 0.7.1 版中删除。 应改用 js_import Directives。

为 njs 模块设置附加路径。

可以在server水平 从 0.7.7 开始。

指定要定期运行的内容处理程序。 处理程序接收一个会话对象作为其第一个参数 它还可以访问 NGX 等全局对象。

可选的interval参数 设置两次连续运行之间的间隔， 默认情况下为 5 秒。

可选的jitterparameter 设置时间 位置内容处理程序将随机延迟， 默认情况下，没有延迟。

默认情况下，js_handler在 worker 进程 0 上执行。 可选的worker_affinity参数 允许指定特定的工作进程 位置内容处理程序的位置。 每个 worker 进程集都由允许的工作进程的位掩码表示。 这allmask 允许执行处理程序 在所有工作进程中。

例：

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可以指定Directives。

设置将在预读阶段调用的 njs 函数。 从 0.4.0 开始， 可以引用 Module 函数。

该函数被调用一次 当流会话到达预读阶段时 第一次。 使用以下参数调用该函数：

s

Stream Session 对象

在此阶段，可以执行初始化 或注册回调 这s.on()方法 对于每个传入数据块，直到调用以下方法之一：s.allow(),s.decline(),s.done(). 当调用其中一个方法时， Stream 会话切换到 Next Phase，并且所有当前s.on()回调被丢弃。

由于js_preread处理器 立即返回其结果，则支持 only synchronous callbacks。 因此，异步回调（例如ngx.fetch()或setTimeout()不受支持。 尽管如此，异步作在s.on()preread 阶段的回调。 有关更多信息，请参阅此示例。

设置 njsfunction对于指定的variable. 从 0.4.0 开始， 可以引用 Module 函数。

该函数在 对于给定请求，将首次引用该变量。 确切的时刻取决于引用变量的阶段。 这可以用来执行一些逻辑 与变量评估无关。 例如，如果仅在 log_format Directives中引用变量，则 它的处理程序在 log 阶段之前不会执行。 此处理程序可用于执行一些清理 就在释放请求之前。

从 0.8.6 开始，当 可选参数nocache提供处理程序 每次引用时都会调用。 由于当前限制 的 rewrite 模块中， 当nocache变量由 set Directives引用 其处理程序应始终返回固定长度的值。

由于js_set处理器 立即返回其结果，则支持 only synchronous callbacks。 因此，不支持 ngx.fetch（） 或 setTimeout（） 等异步回调。

可以在server水平 从 0.7.7 开始。

设置name和size共享内存区 这样，就可以保持 在 worker 进程之间共享的键值字典。

默认情况下，共享字典使用字符串作为键和值。 可选的type参数 允许将值类型重新定义为 number。

可选的timeout参数集 以毫秒为单位的时间 之后，所有共享词典条目都将从区域中删除。 如果某些条目需要不同的删除时间，则可以设置 使用timeoutadd、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 开始。

每个 stream njs 处理程序接收一个参数，即 stream session 对象。