模块 ngx_http_js_module

这ngx_http_js_modulemodule 用于实现 location 和变量处理程序 在新泽西州 — 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};

将 njs 函数设置为响应正文筛选器。 为响应正文的每个数据块调用 filter 函数 替换为以下参数：

r

HTTP 请求对象

data

传入数据块 可以是字符串或 Buffer 取决于buffer_type价值 默认情况下是一个字符串。 从 0.8.5 开始，datavalue 被隐式转换为有效的 UTF-8 字符串 默认情况下。 对于二进制数据，buffer_type价值 应设置为buffer.

flags

具有以下属性的对象：

last

布尔值，如果 data 是最后一个缓冲区，则为 true。

filter 函数可以传递自己的修改版本 到下一个主体过滤器中，通过调用r.sendBuffer(). 例如，要转换响应正文中的所有小写字母：

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

停止筛选（以下数据块将传递到客户端 无需调用js_body_filter),r.done()可以使用。

如果 filter 函数更改了响应正文的长度，则 需要清除 “Content-Length” 响应标头 （如有）js_header_filter强制执行分块传输编码。

由于js_body_filter处理器 立即返回其结果，则支持 仅限同步作。 因此，不支持 r.subrequest（） 或 setTimeout（） 等异步作。

可以在 if 块中指定该Directives 从 0.7.7 开始。

将 njs 函数设置为位置内容处理程序。 从 0.4.0 开始， 可以引用 Module 函数。

可以在 if 块中指定该Directives 从 0.7.7 开始。

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。

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

由于js_header_filter处理器 立即返回其结果，则支持 仅限同步作。 因此，不支持 r.subrequest（） 或 setTimeout（） 等异步作。

可以在 if 块中指定该Directives 从 0.7.7 开始。

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

js_import http.js;

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

几个js_import可以指定Directives。

可以在server和location水平 从 0.7.7 开始。

指定在 njs 中实现位置和变量处理程序的文件：

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

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

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

为 njs 模块设置附加路径。

可以在server和location水平 从 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。

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

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

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

由于js_set处理器 立即返回其结果，则支持 仅限同步作。 因此，不支持 r.subrequest（） 或 setTimeout（） 等异步作。

可以在server和location水平 从 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));
    }

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

可以在server和location水平 从 0.7.7 开始。

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