njt_stream_js_module

1. 功能描述

njt_stream_js_module 是 NJet 的一个模块，允许你在流（stream）上下文中使用 JavaScript 脚本来处理 TCP 和 UDP 连接。这个模块扩展了 NJet的功能，使你能够编写复杂的逻辑来控制连接的行为，例如访问控制、负载均衡决策、日志记录等。

主要功能:

• JavaScript 脚本支持：在 NJet 流配置中嵌入和执行 JavaScript 代码。
• 事件驱动的 API：提供了多种事件钩子，如 remoteAddr, protocol, serverPort, clientPort 等，用于处理连接的不同阶段。
• 动态控制：通过 JavaScript 脚本实现动态的流量控制和处理逻辑。

2. 依赖模块

njet使用开源仓库编译;njs模块使用社区仓库编译（njt_stream_js_module）

load_module  modules/njt_stream_js_module.so;

3. 指令说明

3.1 js_access

js_access 用于在 NJet的流（stream）模块中定义一个 JavaScript 函数或模块函数，该函数将在访问控制阶段执行。这允许你通过自定义逻辑来决定是否允许连接。

• function：指定要调用的 JavaScript 函数。
• module.function：指定要调用的 JavaScript 模块中的函数。

设置一个将在 access 阶段调用的 njs 函数。js_access用于在 NJet 的流（stream）模块中定义一个 JavaScript 函数或模块函数，该函数将在访问控制阶段执行。这允许你通过自定义逻辑来决定是否允许连接。

3.2 js_context_reuse number

• number：要重用的 JavaScript 上下文数量。默认值是 128。

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

3.3 js_engine

js_engine 指令用于选择使用的 JavaScript 引擎。

• njs：使用 NJet 的内置 JavaScript 引擎 njs。

3.4 js_fetch_buffer_size

js_fetch_buffer_size 用于设置在使用 NJet 的 JavaScript（njs）模块进行 stream 请求时，请求体缓冲区的大小。这个指令影响到 NJet 在处理请求体数据时的内存分配。

• size：指定缓冲区大小，默认是 16KB (16k)。

3.5 js_fetch_ciphers

js_fetch_ciphers 指令用于配置在使用 njs 进行 streams 请求时，允许使用的加密套件列表。这有助于增强安全性，通过限制仅使用安全的加密方法。

• ciphers：指定要使用的加密套件列表，格式遵循 OpenSSL 标准。

3.6 js_fetch_max_response_buffer_size

js_fetch_max_response_buffer_size 用于设置在使用 njs 进行 HTTP 请求时，响应体的最大缓冲区大小。这对于控制NJet 处理大响应体的能力非常重要。

• size：指定最大缓冲区大小，默认是 1MB (1m)。

3.7 js_fetch_protocols

• 可选参数包括TLSv1, TLSv1.1, TLSv1.2, 和 TLSv1.3，默认情况下启用前三个协议版本。

3.8 js_fetch_timeout

js_fetch_timeout 指令用于设置通过 js_fetch 方法进行HTTP请求时的超时时间。这个指令帮助控制请求的响应时间，确保不会因为长时间等待而阻塞服务器资源。

• time：指定超时时间，单位可以是秒（s）、毫秒（ms）等，默认值为 60s。

3.9 js_fetch_trusted_certificate

js_fetch_trusted_certificate 指令用于指定受信任的SSL证书文件。这个指令帮助确保通过 js_fetch 发起的HTTPS请求的安全性.

• file：指定包含受信任证书的文件路径。

3.10 js_fetch_verify

js_fetch_verify 指令用于控制是否启用对 js_fetch 请求的SSL证书验证。这个指令帮助确保通过 js_fetch 发起的HTTPS请求的安全性。

• on：启用SSL证书验证（默认值）。
• off：禁用SSL证书验证。

3.11 js_fetch_verify_depth

js_fetch_verify_depth 指令用于设置SSL证书链验证的最大深度。这个指令帮助控制NJet在验证 js_fetch 请求的SSL证书时允许的最大证书链长度。

• number：指定证书链验证的最大深度，默认值为 100。

3.12 js_fetch_keepalive

此指令用于激活与目标服务器连接的缓存。当该参数值大于 0 时，将启用 keepalive（持久连接）功能。

connections参数设定了在每个工作进程的缓存中所保留的、到目标服务器的最大空闲 keepalive 连接数。当连接数超过此限制时，最近最少使用（LRU）的连接将被关闭。

3.13 js_fetch_keepalive_requests

• Keepalive 连接允许复用同一 TCP 连接处理多个请求，减少频繁建连的开销。但过度复用会导致内存积累（每个连接需占用内存资源）。此指令通过控制单连接的请求上限，平衡性能与资源消耗。

3.14 js_fetch_keepalive_time

这个指令控制一个 keepalive 连接的“总寿命”。无论这个连接是否空闲，只要从它建立开始算起达到了设置的时间（比如1小时），那么在这个连接完成最后一次请求后就会被关闭，防止连接被无限期使用。

3.15 js_fetch_keepalive_timeout

这个指令控制一个 keepalive 连接的“空闲等待时间”。如果一个连接在指定的时间内（比如60秒）没有处理任何请求，即处于空闲状态，那么它将被关闭以释放资源。

3.16 js_filter

js_filter 用于在NJet的（stream）模块中定义一个 JavaScript 函数或模块函数，该函数将在数据过滤阶段执行。这允许你对传输的数据进行处理和修改。

• function：指定要调用的 JavaScript 函数。
• module.function：指定要调用的 JavaScript 模块中的函数。

3.17 js_import

js_import 指令用于导入 JavaScript 模块或导出特定名称的模块，以便在 NJet 配置中使用。

• module.js：直接导入一个 JavaScript 模块。
• export_name from module.js：从模块中导入特定名称的导出对象。

3.18 js_include

js_include 指令用于包含一个 JavaScript 文件，允许你在 NJet 配置中使用该文件中的代码。

file：指定要包含的 JavaScript 文件。

3.19 js_path

js_path 指令用于设置 JavaScript 模块的搜索路径，允许你在 NJet配置中更灵活地管理模块。

• path：指定 JavaScript 模块的搜索路径。

3.20 js_periodic

js_periodic 指令允许您在NJet配置中周期性地执行JavaScript函数或模块中的函数。这对于需要定时更新某些状态或数据的场景非常有用，例如定期清理缓存、更新统计数据等。

function 或 module.function：指定要周期性执行的JavaScript函数或模块中的函数。

interval=time（可选）：指定执行间隔，默认单位是秒（s），也可以使用ms（毫秒）、m（分钟）等。

jitter=number（可选）：添加随机延迟，防止多个工作进程同时执行该函数。jitter 的值表示最大随机延迟的时间范围。

worker_affinity=mask（可选）：指定哪些工作进程将执行此函数。mask 是一个二进制掩码，每一位对应一个工作进程。

3.21 js_preload_object

js_preload_object 指令用于预先加载JSON对象到NJet环境中，这可以提高后续请求处理的速度，尤其是在频繁访问相同数据的情况下。这对于静态配置文件或不常变化的数据特别有用。

• name.json：直接定义JSON对象并命名。
• name from file.json：从文件中加载JSON对象并命名。

3.22 js_preread

js_preread 用于在 NJet 的流（stream）模块中定义一个 JavaScript 函数或模块函数，该函数将在预读阶段执行。这允许你在处理请求之前对数据进行预处理。

• function：指定要调用的 JavaScript 函数。
• module.function：指定要调用的 JavaScript 模块中的函数。

3.23 js_set

js_set 指令用于设置一个NJet变量的值为JavaScript函数的返回结果。这对于动态生成内容或根据条件修改响应非常有用，例如动态生成HTTP头、计算用户角色等。

$variable：指定要设置的NJet变量。

function module.function：指定计算该变量值的JavaScript函数或模块中的函数。

nocache（可选）：禁用缓存，确保每次都重新计算

3.24 js_shared_dict_zone

js_shared_dict_zone 指令用于创建共享字典区，供JavaScript代码在不同请求之间共享数据。这对于需要跨请求保持状态的应用程序非常重要，例如会话管理、计数器等。

• zone=name:size：指定共享字典区的名字和大小。
• timeout=time（可选）：设置条目过期时间。
• type=string|number（可选）：指定存储的数据类型，默认是字符串。
• evict（可选）：当达到容量限制时，启用驱逐策略。

3.25 js_var

js_var 指令用于定义一个 NJet 变量，并可选地为其赋值。这个变量可以在 JavaScript 代码中使用，以便在 NJet 配置和 JavaScript 之间传递数据。

• $variable：要定义的 NJet 变量名。
• [value]：可选参数，为变量赋初始值。