模块 ngx_http_js_module

示例配置
指令
     js_body_filter
     js_content
     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_header_filter
     js_import
     js_include
     js_path
     js_periodic
     js_preload_object
     js_set
     js_shared_dict_zone
     js_var
请求参数

ngx_http_js_module模块用于在njs中实现位置和变量处理程序 — njs是JavaScript语言的一个子集。

下载和安装说明可以在这里找到。

示例配置

该示例自0.4.0版本起可用。

http {
    js_import http.js;

    js_set $foo     http.foo;
    js_set $summary http.summary;
    js_set $hash    http.hash;

    resolver 10.0.0.1;

    server {
        listen 8000;

        location / {
            add_header X-Foo $foo;
            js_content http.baz;
        }

        location = /summary {
            return 200 $summary;
        }

        location = /hello {
            js_content http.hello;
        }

        # since 0.7.0
        location = /fetch {
            js_content                   http.fetch;
            js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
        }

        # since 0.7.0
        location = /crypto {
            add_header Hash $hash;
            return     200;
        }
    }
}

http.js文件:

function foo(r) {
    r.log("hello from foo() handler");
    return "foo";
}

function summary(r) {
    var a, s, h;

    s = "JS summary\n\n";

    s += "Method: " + r.method + "\n";
    s += "HTTP version: " + r.httpVersion + "\n";
    s += "Host: " + r.headersIn.host + "\n";
    s += "Remote Address: " + r.remoteAddress + "\n";
    s += "URI: " + r.uri + "\n";

    s += "Headers:\n";
    for (h in r.headersIn) {
        s += "  header '" + h + "' is '" + r.headersIn[h] + "'\n";
    }

    s += "Args:\n";
    for (a in r.args) {
        s += "  arg '" + a + "' is '" + r.args[a] + "'\n";
    }

    return s;
}

function baz(r) {
    r.status = 200;
    r.headersOut.foo = 1234;
    r.headersOut['Content-Type'] = "text/plain; charset=utf-8";
    r.headersOut['Content-Length'] = 15;
    r.sendHeader();
    r.send("nginx");
    r.send("java");
    r.send("script");

    r.finish();
}

function hello(r) {
    r.return(200, "Hello world!");
}

// since 0.7.0
async function fetch(r) {
    let results = await Promise.all([ngx.fetch('https://nginx.org/'),
                                     ngx.fetch('https://nginx.org/en/')]);

    r.return(200, JSON.stringify(results, undefined, 4));
}

// since 0.7.0
async function hash(r) {
    let hash = await crypto.subtle.digest('SHA-512', r.headersIn.host);
    r.setReturnValue(Buffer.from(hash).toString('hex'));
}

export default {foo, summary, baz, hello, fetch, hash};

指令

语法: js_body_filter function | module.function [buffer_type=string | buffer];
默认:
上下文: locationif in locationlimit_except

此指令出现在0.5.2版本中。

将njs函数设置为响应体过滤器。对于响应体的每个数据块,过滤器函数会被调用并带有以下参数:

r
HTTP请求对象
data
传入的数据块,可能是字符串或Buffer,具体取决于buffer_type的值,默认情况下是字符串。
flags
一个包含以下属性的对象:
last
布尔值,如果data是最后一个缓冲区,则为真。

过滤器函数可以通过调用 r.sendBuffer() 将其自己修改过的输入数据块传递给下一个 body 过滤器。例如,要转换响应体中的所有小写字母:

function filter(r, data, flags) {
    r.sendBuffer(data.toLowerCase(), flags);
}

要停止过滤(后续数据块将被传递给客户端而不调用 js_body_filter),可以使用 r.done()

如果过滤器函数更改了响应体的长度,则需要在 js_header_filter 中清除 “Content-Length” 响应头(如果有的话),以强制使用分块传输编码。

由于 js_body_filter 处理程序立即返回其结果,因此仅支持同步操作。因此,不支持异步操作,如 r.subrequest()setTimeout()

0.7.7 版本以来,该指令可以在 if 块内指定。

语法: js_content function | module.function;
默认值:
上下文: location, if in location, limit_except

将 njs 函数设置为位置内容处理程序。自 0.4.0 版本以来,可以引用模块函数。

0.7.7 版本以来,该指令可以在 if 块内指定。

语法: js_fetch_buffer_size size;
默认值:
js_fetch_buffer_size 16k;
上下文: http, server, location

该指令出现在版本 0.7.4 中。

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

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

该指令出现在版本 0.7.0 中。

指定使用 Fetch API 进行 HTTPS 请求时启用的密码。密码的格式由 OpenSSL 库理解。

可以使用 “openssl ciphers” 命令查看完整列表。

语法: js_fetch_max_response_buffer_size size;
默认:
js_fetch_max_response_buffer_size 1m;
上下文: http, server, location

该指令出现在版本 0.7.4 中。

设置使用 Fetch API 接收的响应的最大 size

语法: js_fetch_protocols [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
默认:
js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;
上下文: http, server, location

该指令出现在版本 0.7.0 中。

启用 HTTPS 请求的指定协议,使用 Fetch API

语法: js_fetch_timeout time;
默认:
js_fetch_timeout 60s;
上下文: http, server, location

该指令出现在版本 0.7.4 中。

定义用于 Fetch API 的读取和写入的超时。该超时仅在两次连续读取/写入操作之间设置,而不是针对整个响应。如果在此时间内未传输任何数据,则关闭连接。

语法: js_fetch_trusted_certificate file;
默认:
上下文: http, server, location

该指令出现在版本 0.7.0 中。

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

语法: js_fetch_verify on | off;
默认:
js_fetch_verify on;
上下文: http, server, location

该指令出现在版本 0.7.4 中。

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

语法: js_fetch_verify_depth number;
默认:
js_fetch_verify_depth 100;
上下文: http, server, location

该指令出现在版本 0.7.0 中。

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

语法: js_header_filter function | module.function;
默认:
上下文: location, if in location, limit_except

此指令于版本0.5.1中出现。

将一个njs函数设置为响应头过滤器。该指令允许更改响应头的任意字段。

由于js_header_filter处理程序立即返回其结果,因此仅支持同步操作。因此,不支持异步操作,如r.subrequest()setTimeout()

0.7.7起,该指令可以在if块内指定。

语法: js_import module.js | export_name from module.js;
默认:
上下文: http, server, location

此指令于版本0.4.0中出现。

导入一个实现njs中位置和变量处理程序的模块。使用export_name作为访问模块函数的命名空间。如果未指定export_name,则将使用模块名称作为命名空间。

js_import http.js;

在这里,模块名称http用作访问导出的命名空间。如果导入的模块导出foo(),则使用http.foo来引用它。

可以指定多个js_import指令。

0.7.7起,该指令可以在serverlocation级别上指定。

语法: js_include file;
默认:
上下文: http

指定一个实现njs中位置和变量处理程序的文件:

nginx.conf:
js_include http.js;
location   /version {
    js_content version;
}

http.js:
function version(r) {
    r.return(200, njs.version);
}

该指令在版本0.4.0中已被废弃,并在版本0.7.1中被移除。应使用js_import指令。

语法: js_path path;
默认:
上下文: http, server, location

此指令于版本0.3.0中出现。

为njs模块设置额外路径。

0.7.7起,该指令可以在serverlocation级别上指定。

语法: js_periodic 函数 | 模块.函数 [间隔=时间] [抖动=数字] [工作线程关联=掩码];
默认:
上下文: 位置

此指令出现在版本 0.8.1 中。

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

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

可选的抖动参数设置位置内容处理程序将被随机延迟的时间范围,默认情况下没有延迟。

默认情况下,js_handler 在工作进程 0 上执行。可选的工作线程关联参数允许指定应在其中执行位置内容处理程序的特定工作进程。每个工作进程集由允许的工作进程位掩码表示。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);
}

语法: js_preload_object 名称.json | 名称 from 文件.json;
默认:
上下文: http, 服务器, 位置

此指令出现在版本 0.7.8 中。

在配置时间预加载一个不可变对象名称 用作 njs 代码中可用于访问对象的全局变量的名称。如果未指定名称,则将使用文件名。

js_preload_object map.json;

这里,map 用作访问预加载对象的名称。

可以指定多个js_preload_object 指令。

语法: js_set $变量 函数 | 模块.函数;
默认:
上下文: http, 服务器, 位置

为指定的变量 设置一个 njs 函数。自0.4.0 以来,可以引用模块函数。

当首次为给定请求引用变量时,将调用该函数。确切的时机取决于引用变量的阶段。这可用于执行与变量评估无关的一些逻辑。例如,如果变量仅在log_format 指令中引用,则其处理程序将在日志阶段之前不会执行。此处理程序可用于在释放请求之前进行一些清理。

由于 js_set 处理程序会立即返回其结果,因此仅支持同步操作。因此,不支持异步操作,如 r.subrequest()setTimeout()

0.7.7 版开始,该指令可以在 serverlocation 级别上指定。

语法: js_shared_dict_zone zone=名称:大小 [timeout=时间] [type=string|number] [evict];
默认值:
上下文: http

此指令出现在版本 0.8.0 中。

设置保留在工作进程之间共享的键值 字典 的共享内存区的 名称大小

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

可选的 timeout 参数设置所有共享字典条目在区域中被删除之后的时间。

当区域存储耗尽时,可选的 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));
    }

语法: js_var $variable [value];
默认值:
上下文: http, server, location

此指令出现在版本 0.5.3 中。

声明一个 可写 变量。值可以包含文本、变量及其组合。与使用 set 指令创建的变量不同,重定向后不会覆盖该变量。

0.7.7 版开始,该指令可以在 serverlocation 级别上指定。

请求参数

每个 HTTP njs 处理程序接收一个参数,即请求 对象