# JS 该模块用于在 njs 中实现处理程序——njs 是 JavaScript 语言的一个子集。 在我们的仓库中,该模块以 [动态方式](https://cn.angie.software//angie/docs/installation/index.md#install-dynamicmodules) 构建,并作为名为 `angie-module-njs` 或 `angie-pro-module-njs` 的独立软件包提供。 #### NOTE 还提供了名为 `...-njs-light` 的轻量级版本软件包;但是,它不能与常规版本同时使用。 ## 配置示例 ```nginx 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` 文件: ```javascript 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. // Inject 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}; ``` ## 指令 ### js_access | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_access` function | module.function; | |--------------------------------------------------------------------------------------|-------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 设置一个 njs 函数,该函数将在 [访问阶段](https://cn.angie.software//angie/docs/configuration/processing.md#stream-sessions) 被调用。可以引用模块函数。 该函数在流会话第一次到达 [访问阶段](https://cn.angie.software//angie/docs/configuration/processing.md#stream-sessions) 时被调用一次。该函数使用以下参数调用: | `s` | [流会话](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session) 对象 | |-------|-----------------------------------------------------------------------------------------------------| 在此阶段,可以执行初始化或使用 [s.on()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#s-on) 方法为每个传入的数据块注册回调,直到调用以下方法之一: [s.done()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-s-done)、[s.decline()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-s-decline)、[s.allow()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-s-allow)。一旦调用其中一个方法,流会话处理就会切换到 [下一阶段](https://cn.angie.software//angie/docs/configuration/processing.md#stream-sessions),并且所有当前的 [s.on()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#s-on) 回调都会被丢弃。 ### js_context_reuse | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_context_reuse` number; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | `js_context_reuse 128;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 设置 QuickJS 引擎可重用的 JS 上下文的最大数量。每个上下文用于单个流会话。完成的上下文会被放入可重用上下文池中。如果池已满,则销毁该上下文。 ### js_engine | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_engine` `njs` | `qjs`; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | `js_engine njs;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 设置用于 njs 脚本的 JavaScript 引擎。`njs` 参数设置 njs 引擎,这也是默认使用的引擎。`qjs` 参数设置 QuickJS 引擎。 ### js_fetch_buffer_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_buffer_size` size; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `js_fetch_buffer_size 16k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 设置用于 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 读取和写入的缓冲区大小。 ### js_fetch_ciphers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_ciphers` ciphers; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `js_fetch_ciphers HIGH:!aNULL:!MD5;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 指定用于 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) HTTPS 连接的启用加密套件。加密套件以 OpenSSL 库理解的格式指定。 加密套件列表取决于安装的 OpenSSL 版本。 可以使用 `openssl ciphers` 命令查看完整列表。 ### js_fetch_max_response_buffer_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_max_response_buffer_size` size; | |--------------------------------------------------------------------------------------|---------------------------------------------| | 默认值 | `js_fetch_max_response_buffer_size 1m;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 设置使用 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 接收的响应的最大大小。 ### js_fetch_protocols | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_protocols` [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; | |--------------------------------------------------------------------------------------|-----------------------------------------------------------------------| | 默认值 | `js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 启用用于 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) HTTPS 连接的指定协议。 ### js_fetch_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_timeout` time; | |--------------------------------------------------------------------------------------|----------------------------| | 默认值 | `js_fetch_timeout 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 定义 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 读取和写入的超时时间。超时仅在两次连续的读/写操作之间设置,而不是针对整个响应。如果在此时间内没有数据传输,连接将被关闭。 ### js_fetch_trusted_certificate | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_trusted_certificate` file; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 指定一个包含 PEM 格式受信任 CA 证书的文件,用于验证 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 的 HTTPS 证书。 ### js_fetch_verify | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_verify` `on` | `off`; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | `js_fetch_verify on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 启用或禁用使用 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 对 HTTPS 服务器证书的验证。 ### js_fetch_verify_depth | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_verify_depth` number; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | `js_fetch_verify_depth 100;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 设置使用 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 在 HTTPS 服务器证书链中的验证深度。 ### js_fetch_keepalive | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_keepalive` connections; | |--------------------------------------------------------------------------------------|-------------------------------------| | 默认值 | `js_fetch_keepalive 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 激活到目标服务器的连接缓存。当该值大于 `0` 时,为 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 启用保持活动连接。 connections 参数设置每个工作进程缓存中保留的到目标服务器的空闲保持活动连接的最大数量。当超过此数量时,最近最少使用的连接将被关闭。 示例: ```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 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_keepalive_requests` number; | |--------------------------------------------------------------------------------------|-----------------------------------------| | 默认值 | `js_fetch_keepalive_requests 1000;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 设置通过一个与 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 的保持活动连接可以处理的最大请求数。达到最大请求数后,连接将被关闭。 定期关闭连接对于释放每个连接的内存分配是必要的。因此,使用过高的最大请求数可能导致过度的内存使用,不建议这样做。 ### js_fetch_keepalive_time | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_keepalive_time` time; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | `js_fetch_keepalive_time 1h;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 限制通过一个与 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 的保持活动连接可以处理请求的最长时间。达到此时间后,连接将在后续请求处理完成后关闭。 ### js_fetch_keepalive_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_fetch_keepalive_timeout` time; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `js_fetch_keepalive_timeout 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 设置与 [Fetch API](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 到目标服务器的空闲保持活动连接保持打开的超时时间。 ### js_filter | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_filter` function | module.function; | |--------------------------------------------------------------------------------------|-------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 设置数据过滤器。可以引用模块函数。 过滤器函数在流会话到达 [内容阶段](https://cn.angie.software//angie/docs/configuration/processing.md#stream-sessions) 时被调用一次。过滤器函数使用以下参数调用: | `s` | [流会话](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session) 对象 | |-------|-----------------------------------------------------------------------------------------------------| 在此阶段,可以执行初始化或使用 [s.on()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#s-on) 方法为每个传入的数据块注册回调。可以使用 [s.off()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#s-off) 方法注销回调并停止过滤。 #### NOTE 由于 js_filter 处理程序立即返回其结果,因此它仅支持同步操作。因此,不支持异步操作,如 [ngx.fetch()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 或 [setTimeout()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-timers)。 ### js_import | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_import` module.js | export_name from module.js; | |--------------------------------------------------------------------------------------|-------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 导入一个在 njs 中实现位置和变量处理程序的模块。export_name 用作访问模块函数的命名空间。如果未指定 export_name,则模块名称将用作命名空间。 ```nginx js_import stream.js; ``` 这里,模块名称 stream 在访问导出时用作命名空间。如果导入的模块导出 foo(),则使用 stream.foo 来访问它。 可以指定多个 js_import 指令。 ### js_path | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_path` path; | |--------------------------------------------------------------------------------------|-------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 为 njs 模块设置附加路径。 ### js_periodic | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_periodic` module.function [`interval=`\\ time] [`jitter=`\\ number] [`worker_affinity=`\\ mask]; | |--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server | 指定定期运行的内容处理程序。该处理程序接收会话对象作为其第一个参数,它还可以访问全局对象,如 `ngx`。 可选的 `interval` 参数设置两次连续运行之间的间隔,默认为 5 秒。 可选的 `jitter` 参数设置位置内容处理程序将被随机延迟的时间,默认情况下没有延迟。 默认情况下,:samp:js_handler 在工作进程 0 上执行。可选的 `worker_affinity` 参数允许指定应在其中执行位置内容处理程序的特定工作进程。每个工作进程集由允许的工作进程的位掩码表示。`all` 掩码允许处理程序在所有工作进程中执行。 示例: ```nginx example.conf: 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; } ``` ```javascript example.js: async function handler(s) { let reply = await ngx.fetch('https://example.com/'); let body = await reply.text(); ngx.log(ngx.INFO, body); } ``` ### js_preload_object | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_preload_object` name.json | name from file.json; | |--------------------------------------------------------------------------------------|--------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 在配置时预加载不可变对象。name 用作全局变量的名称,通过该变量可以在 njs 代码中访问该对象。如果未指定 name,则将使用文件名。 ```nginx js_preload_object map.json; ``` 这里,\`map\` 在访问预加载对象时用作名称。 可以指定多个 js_preload_object 指令。 ### js_preread | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_preread` function | module.function; | |--------------------------------------------------------------------------------------|--------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 设置将在 [预读阶段](https://cn.angie.software//angie/docs/configuration/processing.md#stream-sessions) 调用的 njs 函数。可以引用模块函数。 该函数在流会话首次到达 [预读阶段](https://cn.angie.software//angie/docs/configuration/processing.md#stream-sessions) 时被调用一次。该函数使用以下参数调用: | `s` | [流会话](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session) 对象 | |-------|-----------------------------------------------------------------------------------------------------| 在此阶段,可以执行初始化或使用 [s.on()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#s-on) 方法为每个传入的数据块注册回调,直到调用以下方法之一:[s.done()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-s-done)、[s.decline()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-s-decline)、[s.allow()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-s-allow)。当调用这些方法之一时,流会话切换到 [下一阶段](https://cn.angie.software//angie/docs/configuration/processing.md#stream-sessions),并且所有当前的 [s.on()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#s-on) 回调都将被丢弃。 #### NOTE 由于 js_preread 处理程序立即返回其结果,因此它仅支持同步操作。因此,不支持异步操作,如 [ngx.fetch()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 或 [setTimeout()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-timers)。然而,在 [预读阶段](https://cn.angie.software//angie/docs/configuration/processing.md#stream-sessions) 的 [s.on()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#s-on) 回调中支持异步操作。 ### js_set | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_set` $variable function | module.function [`nocache`]; | |--------------------------------------------------------------------------------------|--------------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 为指定的变量设置一个 njs 函数。可以引用模块函数。 当变量在给定请求中首次被引用时,该函数会被调用。确切的时刻取决于引用变量的 [阶段](https://cn.angie.software//angie/docs/configuration/processing.md#stream-sessions)。这可以用于执行一些与变量求值无关的逻辑。例如,如果变量仅在 [log_format](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_log.md#s-log-format) 指令中被引用,其处理程序将不会执行,直到日志阶段。此处理程序可用于在请求被释放之前进行一些清理工作。 从 njs 0.8.6 开始,当提供可选参数 `nocache` 时,处理程序在每次被引用时都会被调用。由于 rewrite 模块当前的限制,当 `nocache` 变量被 set 指令引用时,其处理程序应始终返回固定长度的值。 #### NOTE 由于 js_set 处理程序会立即返回其结果,因此它仅支持同步操作。因此,不支持异步操作,如 [ngx.fetch()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) 或 [setTimeout()](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-timers)。 ### js_shared_dict_zone | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_shared_dict_zone` `zone=`name:size [`timeout=`time] [`type=``string` | `number`] [`evict`] [`state=`file]; | |--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream | 设置共享内存区域的名称和大小,该区域保存在工作进程之间共享的键值字典。 | `type` | 可选参数,允许将值类型重新定义为 `number`,默认情况下共享字典使用 `string` 作为键和值 | |-----------|--------------------------------------------------------| | `timeout` | 可选参数,设置从区域中删除所有共享字典条目的时间 | | `evict` | 可选参数,当区域存储耗尽时删除最旧的键值对 | | `state` | 可选参数,指定一个以 JSON 格式保存共享字典状态的文件,使其在 nginx 重启后保持持久化 | 示例: ```nginx example.conf: # 创建一个 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; ``` ```javascript 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 delete(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 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `js_var` $variable [value]; | |--------------------------------------------------------------------------------------|-------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server | 声明一个 [可写](https://cn.angie.software//angie/docs/configuration/njs-reference.md#s-variables) 变量。值可以包含文本、变量及其组合。 ## 会话对象属性 每个 stream njs 处理程序接收一个参数,即 [stream 会话](https://cn.angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session) 对象。