全栈攻城狮

Appearance

模块 ngx_stream_js_module ​

提示

来自deepseek解释

原文链接：https://nginx.org/en/docs/stream/ngx_stream_js_module.html

ngx_stream_js_module 模块用于在 njs（JavaScript 语言的一个子集）中实现处理程序。下载和安装说明请参见此处。

示例配置 ​

以下示例自 0.4.0 版本起可用。

nginx
stream {
    # 自 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 文件：

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

// 读取 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};

指令 ​

js_access ​

语法js_access module.function;
默认值—
上下文stream, server

设置一个 njs 函数，该函数将在访问（access）阶段被调用。

自 0.4.0 起，可以引用模块函数。

该函数在 stream 会话首次到达访问阶段时被调用一次。

函数接收以下参数：

在此阶段，可以执行初始化，或通过 s.on() 方法为每个传入数据块注册回调，直到调用了以下方法之一：

一旦调用了这些方法之一，stream 会话处理将切换到下一阶段，所有当前的 s.on() 回调将被丢弃。

js_context_reuse ​

语法js_context_reuse number;
默认值js_context_reuse 128;
上下文stream, server

该指令自 0.8.6 版本起可用。

设置 QuickJS 引擎可重用的 JS 上下文的最大数量。

每个上下文用于单个 stream 会话。完成的上下文会被放入可重用上下文的池中。如果池已满，该上下文将被销毁。

js_engine ​

语法js_engine njs | qjs;
默认值js_engine njs;
上下文stream, server

该指令自 0.8.6 版本起可用。

设置用于 njs 脚本的 JavaScript 引擎。

njs 参数设置 njs 引擎，也是默认值。qjs 参数设置 QuickJS 引擎。

njs 引擎自 1.0.0 起已弃用；新配置应使用 qjs（QuickJS）引擎。

js_fetch_buffer_size ​

语法js_fetch_buffer_size size;
默认值js_fetch_buffer_size 16k;
上下文stream, server

该指令自 0.7.4 版本起可用。

设置 Fetch API 用于读写操作的缓冲区大小。

js_fetch_ciphers ​

语法js_fetch_ciphers ciphers;
默认值js_fetch_ciphers HIGH:!aNULL:!MD5;
上下文stream, server

该指令自 0.7.0 版本起可用。

为 Fetch API 的 HTTPS 连接指定启用的加密套件。

加密套件的格式为 OpenSSL 库所理解的格式。完整列表可使用 openssl ciphers 命令查看。

js_fetch_max_response_buffer_size ​

语法js_fetch_max_response_buffer_size size;
默认值js_fetch_max_response_buffer_size 1m;
上下文stream, server

该指令自 0.7.4 版本起可用。

设置通过 Fetch API 接收的响应的最大大小。

js_fetch_protocols ​

语法js_fetch_protocols [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
默认值js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;
上下文stream, server

该指令自 0.7.0 版本起可用。

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

js_fetch_timeout ​

语法js_fetch_timeout time;
默认值js_fetch_timeout 60s;
上下文stream, server

该指令自 0.7.4 版本起可用。

为 Fetch API 定义读写超时时间。

超时仅设置在两次连续的读/写操作之间，而不是整个响应期间。如果在此时间内没有数据传输，连接将被关闭。

js_fetch_trusted_certificate ​

语法js_fetch_trusted_certificate file;
默认值—
上下文stream, server

该指令自 0.7.0 版本起可用。

指定一个 PEM 格式的可信 CA 证书文件，用于验证 Fetch API 的 HTTPS 证书。

js_fetch_verify ​

语法js_fetch_verify on | off;
默认值js_fetch_verify on;
上下文stream, server

该指令自 0.7.4 版本起可用。

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

js_fetch_verify_depth ​

语法js_fetch_verify_depth number;
默认值js_fetch_verify_depth 100;
上下文stream, server

该指令自 0.7.0 版本起可用。

设置 Fetch API HTTPS 服务器证书链的验证深度。

js_fetch_proxy ​

语法js_fetch_proxy url;
默认值—
上下文stream, server

该指令自 0.9.4 版本起可用。

为 Fetch API 配置正向代理 URL。

该 URL 仅支持 HTTP 协议，并可包含可选的用户凭据，格式为 http://[user:password@]host:port，用于 Basic 认证。

同时支持到目标服务器的 HTTP 和 HTTPS 连接。如果 URL 为空，则禁用代理路由。

参数值可包含变量。

示例：

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

js_fetch_keepalive ​

语法js_fetch_keepalive connections;
默认值js_fetch_keepalive 0;
上下文stream, server

该指令自 0.9.2 版本起可用。

激活到目标服务器的连接缓存。当值大于 0 时，为 Fetch API 启用 keepalive 连接。

connections 参数设置每个工作进程缓存中保留的到目标服务器的空闲 keepalive 连接的最大数量。超过此数量时，最近最少使用的连接将被关闭。

在 Stream 中，缓存为每个 server 配置分别维护。在 stream 级别设置的值会被 server 继承，但每个 server 使用自己的缓存。

缓存的连接会被复用给具有相同协议、主机和端口的请求。启用后，keepalive 假设目标服务器发送有效的 HTTP 响应。

示例：

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

js_fetch_keepalive_requests ​

语法js_fetch_keepalive_requests number;
默认值js_fetch_keepalive_requests 1000;
上下文stream, server

该指令自 0.9.2 版本起可用。

设置一条 keepalive 连接可通过 Fetch API 服务的最大请求数。达到最大请求数后，连接将被关闭。

定期关闭连接对于释放每连接内存分配是必要的。因此，使用过高的最大请求数可能导致内存使用过量，不推荐这样做。

js_fetch_keepalive_time ​

语法js_fetch_keepalive_time time;
默认值js_fetch_keepalive_time 1h;
上下文stream, server

该指令自 0.9.2 版本起可用。

限制通过一条 keepalive 连接处理 Fetch API 请求的最大时间。达到此时间后，连接将在后续请求处理完成后关闭。

js_fetch_keepalive_timeout ​

语法js_fetch_keepalive_timeout time;
默认值js_fetch_keepalive_timeout 60s;
上下文stream, server

该指令自 0.9.2 版本起可用。

设置 Fetch API 到目标服务器的空闲 keepalive 连接保持打开的超时时间。

js_filter ​

语法js_filter module.function;
默认值—
上下文stream, server

设置一个数据过滤器。

自 0.4.0 起，可以引用模块函数。

过滤器函数在 stream 会话到达内容（content）阶段时被调用一次。

函数接收以下参数：

在此阶段，可以执行初始化，或通过 s.on() 方法为每个传入数据块注册回调。

s.off() 方法可用于注销回调并停止过滤。

由于 js_filter 处理程序会立即返回其结果，因此仅支持同步操作。异步操作如 ngx.fetch() 或 setTimeout() 不被支持。

js_import ​

语法js_import module.js | export_name from module.js;
默认值—
上下文stream, server

该指令自 0.4.0 版本起可用。

导入一个实现 njs location 和变量处理程序的模块。

export_name 用作访问模块函数的命名空间。如果未指定 export_name，则使用模块名称作为命名空间。

nginx
js_import stream.js;

此处，模块名称 stream 用作访问导出的命名空间。如果导入的模块导出 foo()，则使用 stream.foo 来引用它。

可以指定多个 js_import 指令。

自 0.7.7 起，该指令可以在 server 级别指定。

js_include ​

语法js_include file;
默认值—
上下文stream

指定一个在 njs 中实现 server 和变量处理程序的文件：

nginx.conf：

nginx
js_include stream.js;
js_set $js_addr address;

server {
    listen 127.0.0.1:12345;
    return $js_addr;
}

stream.js：

js
function address(s) {
    return s.remoteAddress;
}

该指令在版本 0.4.0 中已弃用，并在版本 0.7.1 中移除。应改用 js_import 指令。

js_load_stream_native_module ​

语法js_load_stream_native_module path [as name];
默认值—
上下文main

该指令自 0.9.5 版本起可用。

加载一个原生模块（共享库）供 Stream JavaScript 代码使用。

该指令仅适用于 QuickJS，在使用 njs 内置 JavaScript 引擎时不可用。

path 参数指定共享库文件的绝对路径。可选的 as name 参数为在 JavaScript 代码中导入模块提供别名。如果未指定，则可以使用文件名导入模块。

示例：

nginx
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;
    # ... 其余 stream 配置
}

在 JavaScript 代码中：

js
// 按文件名导入
import * as mylib from 'mylib.so';
// 按别名导入
import * as myalias from 'myalias';

// 使用导出的函数
let result = mylib.add(5, 10);

出于安全原因，该指令仅允许在 main 配置上下文中使用。原生模块以完整的进程权限运行；请使用绝对路径并确保进行适当的代码审查。

js_path ​

语法js_path path;
默认值—
上下文stream, server

该指令自 0.3.0 版本起可用。

为 njs 模块设置额外的路径。

自 0.7.7 起，该指令可以在 server 级别指定。

js_periodic ​

语法js_periodic module.function [interval=time] [jitter=number] [worker_affinity=mask];
默认值—
上下文server

该指令自 0.8.1 版本起可用。

指定一个按固定时间间隔运行的内容处理程序。

该处理程序接收一个会话对象作为其第一个参数，同时也可以访问全局对象如 ngx。

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

可选的 jitter 参数设置 location 内容处理程序将被随机延迟的时间范围，默认为无延迟。

默认情况下，js_handler 在工作进程 0 上执行。可选的 worker_affinity 参数允许指定执行 location 内容处理程序的特定工作进程。

每个工作进程集合由一个允许的工作进程的位掩码表示。all 掩码允许处理程序在所有工作进程中执行。

示例：

example.conf：

nginx
location @periodics {
    # 在工作进程 0 上每 1 分钟运行一次
    js_periodic main.handler interval=60s;

    # 在所有工作进程中每 1 分钟运行一次
    js_periodic main.handler interval=60s worker_affinity=all;

    # 在工作进程 1 和 3 中每 1 分钟运行一次
    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：

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

js_preload_object ​

语法js_preload_object name.json | name from file.json;
默认值—
上下文stream, server

该指令自 0.7.8 版本起可用。

在配置时预加载一个不可变对象。

name 用作全局变量的名称，通过该变量在 njs 代码中访问该对象。如果未指定 name，则使用文件名。

nginx
js_preload_object map.json;

此处，map 用作访问预加载对象的名称。

可以指定多个 js_preload_object 指令。

js_preread ​

语法js_preread module.function;
默认值—
上下文stream, server

设置一个 njs 函数，该函数将在预读取（preread）阶段被调用。

自 0.4.0 起，可以引用模块函数。

该函数在 stream 会话首次到达预读取阶段时被调用一次。

函数接收以下参数：

在此阶段，可以执行初始化，或通过 s.on() 方法为每个传入数据块注册回调，直到调用了以下方法之一：

当调用了这些方法之一时，stream 会话将切换到下一阶段，所有当前的 s.on() 回调将被丢弃。

由于 js_preread 处理程序会立即返回其结果，因此仅支持同步回调。异步回调如 ngx.fetch() 或 setTimeout() 不被支持。

不过，预读取阶段的 s.on() 回调中支持异步操作。

更多信息请参见此示例。

js_set ​

语法js_set $variable module.function [nocache];
默认值—
上下文stream, server

为指定的变量设置一个 njs 函数。

自 0.4.0 起，可以引用模块函数。

该函数在给定会话中首次引用该变量时被调用。确切的时间取决于引用该变量的阶段。

这可用于执行一些与变量求值无关的逻辑。例如，如果变量仅在 log_format 指令中被引用，其处理程序直到日志阶段才会执行。该处理程序可用于在会话释放之前执行一些清理工作。

自 0.8.6 起，如果指定了可选参数 nocache，则每次引用该变量时都会调用处理程序。

由于当前重写（rewrite）模块的限制，当 nocache 变量被 set 指令引用时，其处理程序应始终返回固定长度的值。

由于 js_set 处理程序会立即返回其结果，因此仅支持同步回调。异步回调如 ngx.fetch() 或 setTimeout() 不被支持。

自 0.7.7 起，该指令可以在 server 级别指定。

js_shared_dict_zone ​

语法js_shared_dict_zone zone=name:size [timeout=time] [type=string|number] [evict] [state=file];
默认值—
上下文stream

该指令自 0.8.0 版本起可用。

设置共享内存区域的名称和大小，该区域维护工作进程间共享的键值字典。

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

可选的 timeout 参数设置所有共享字典条目从区域中移除的时间（毫秒）。如果某些条目需要不同的移除时间，可以通过 add、incr 和 set 方法的 timeout 参数设置（0.8.5）。

可选的 evict 参数在区域存储耗尽时移除最旧的键值对。

可选的 state 参数指定一个文件，以 JSON 格式保存共享字典状态，并使其在 nginx 重启后持久化（0.9.1）。

示例：

example.conf：

nginx
# 创建一个 1MB 的字符串值字典，键值对在 60 秒不活动后移除
js_shared_dict_zone zone=foo:1M timeout=60s;

# 创建一个 512KB 的字符串值字典，区域耗尽时强制移除最旧的键值对
js_shared_dict_zone zone=bar:512K timeout=30s evict;

# 创建一个 32KB 的永久数字值字典
js_shared_dict_zone zone=num:32k type=number;

# 创建一个 1MB 的字符串值字典，并持久化状态
js_shared_dict_zone zone=persistent:1M state=/tmp/dict.json;

example.js：

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

js_var ​

语法js_var $variable [value];
默认值—
上下文stream, server

该指令自 0.5.3 版本起可用。

声明一个可写变量。

value 可以包含文本、变量及其组合。

自 0.7.7 起，该指令可以在 server 级别指定。

会话对象属性 ​

每个 Stream njs 处理程序接收一个参数，即 Stream 会话对象。