Mercurial > hg > nginx-site
view xml/en/docs/stream/ngx_stream_js_module.xml @ 2769:16f6fa718be2
Updated TLSv1.3 support notes.
Previous notes described some early development snapshot of OpenSSL 1.1.1
with disabled TLSv1.3 by default. It was then enabled in the first alpha.
Further, the updated text covers later major releases such as OpenSSL 3.0.
author | Sergey Kandaurov <pluknet@nginx.com> |
---|---|
date | Thu, 30 Sep 2021 16:29:20 +0300 |
parents | 42fb92e582db |
children | a2852750c379 |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_stream_js_module" link="/en/docs/stream/ngx_stream_js_module.html" lang="en" rev="28"> <section id="summary"> <para> The <literal>ngx_stream_js_module</literal> module is used to implement handlers in <link doc="../njs/index.xml">njs</link> — a subset of the JavaScript language. </para> <para> Download and install instructions are available <link doc="../njs/install.xml">here</link>. </para> </section> <section id="example" name="Example Configuration"> <para> The example works since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>. <example> 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; } } } </example> </para> <para> The <path>stream.js</path> file: <example> 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. // Injects 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}; </example> </para> </section> <section id="directives" name="Directives"> <directive name="js_access"> <syntax><value>function</value> | <value>module.function</value></syntax> <default/> <context>stream</context> <context>server</context> <para> Sets an njs function which will be called at the <link doc="stream_processing.xml" id="access_phase">access</link> phase. Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, a module function can be referenced. </para> </directive> <directive name="js_filter"> <syntax><value>function</value> | <value>module.function</value></syntax> <default/> <context>stream</context> <context>server</context> <para> Sets a data filter. Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, a module function can be referenced. </para> </directive> <directive name="js_import"> <syntax><value>module.js</value> | <value>export_name from module.js</value></syntax> <default/> <context>stream</context> <appeared-in>0.4.0</appeared-in> <para> Imports a module that implements location and variable handlers in njs. The <literal>export_name</literal> is used as a namespace to access module functions. If the <literal>export_name</literal> is not specified, the module name will be used as a namespace. <example> js_import stream.js; </example> Here, the module name <literal>stream</literal> is used as a namespace while accessing exports. If the imported module exports <literal>foo()</literal>, <literal>stream.foo</literal> is used to refer to it. </para> <para> Several <literal>js_import</literal> directives can be specified. </para> </directive> <directive name="js_include"> <syntax><value>file</value></syntax> <default/> <context>stream</context> <para> Specifies a file that implements server and variable handlers in njs: <example> nginx.conf: js_include stream.js; js_set $js_addr address; server { listen 127.0.0.1:12345; return $js_addr; } stream.js: function address(s) { return s.remoteAddress; } </example> </para> <para> The directive is deprecated since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, the <link id="js_import"/> directive should be used instead. </para> </directive> <directive name="js_path"> <syntax> <value>path</value></syntax> <default/> <context>stream</context> <appeared-in>0.3.0</appeared-in> <para> Sets an additional path for njs modules. </para> </directive> <directive name="js_preread"> <syntax><value>function</value> | <value>module.function</value></syntax> <default/> <context>stream</context> <context>server</context> <para> Sets an njs function which will be called at the <link doc="stream_processing.xml" id="preread_phase">preread</link> phase. Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, a module function can be referenced. </para> </directive> <directive name="js_set"> <syntax> <value>$variable</value> <value>function</value> | <value>module.function</value></syntax> <default/> <context>stream</context> <para> Sets an njs <literal>function</literal> for the specified <literal>variable</literal>. Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, a module function can be referenced. </para> <para> The function is called when the variable is referenced for the first time for a given request. The exact moment depends on a <link doc="stream_processing.xml">phase</link> at which the variable is referenced. This can be used to perform some logic not related to variable evaluation. For example, if the variable is referenced only in the <link doc="ngx_stream_log_module.xml" id="log_format"/> directive, its handler will not be executed until the log phase. This handler can be used to do some cleanup right before the request is freed. </para> <para> <note> As the <literal>js_set</literal> handler returns its result immediately, it supports only synchronous callbacks. Thus, asynchronous callbacks such as <link doc="../njs/reference.xml" id="ngx_fetch">ngx.fetch()</link> or <link doc="../njs/reference.xml" id="settimeout">setTimeout()</link> are not supported. </note> </para> </directive> <directive name="js_var"> <syntax><value>$variable</value> [<value>value</value>]</syntax> <default/> <context>stream</context> <appeared-in>0.5.3</appeared-in> <para> Declares a <link doc="../njs/reference.xml" id="r_variables">writable</link> variable. The value can contain text, variables, and their combination. </para> </directive> </section> <section id="properties" name="Session Object Properties"> <para> Each stream njs handler receives one argument, a stream session <link doc="../njs/reference.xml" id="stream">object</link>. </para> </section> </module>