Module ngx_http_js_module
The ngx_http_js_module
module is used to implement
location and variable handlers
in njs —
a subset of the JavaScript language.
Download and install instructions are available here.
Example Configuration
The example works since 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; } } }
The http.js
file:
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};
Directives
Syntax: |
js_body_filter |
---|---|
Default: | — |
Context: |
location , limit_except |
This directive appeared in version 0.5.2.
Sets an njs function as a response body filter. The filter function is called for each data chunk of a response body with the following arguments:
r
- the HTTP request object
data
-
the incoming data chunk,
may be a string or Buffer
depending on the
buffer_type
value, by default is a string. flags
-
an object with the following properties:
last
- a boolean value, true if data is a last buffer.
The filter function can pass its own modified version
of the input data chunk to the next body filter by calling
r.sendBuffer()
.
For example, to transform all the lowercase letters in the response body:
function filter(r, data, flags) { r.sendBuffer(data.toLowerCase(), flags); }
To stop filtering (following data chunks will be passed to client
without calling js_body_filter
),
r.done()
can be used.
If the filter function changes the length of the response body, then
it is required to clear out the “Content-Length” response header
(if any) in
js_header_filter
to enforce chunked transfer encoding.
As the js_body_filter
handler
returns its result immediately, it supports
only synchronous operations.
Thus, asynchronous operations such as
r.subrequest()
or
setTimeout()
are not supported.
Syntax: |
js_content |
---|---|
Default: | — |
Context: |
location , limit_except |
Sets an njs function as a location content handler. Since 0.4.0, a module function can be referenced.
Syntax: |
js_fetch_ciphers |
---|---|
Default: |
js_fetch_ciphers HIGH:!aNULL:!MD5; |
Context: |
http , server , location |
This directive appeared in version 0.7.0.
Specifies the enabled ciphers for HTTPS requests with Fetch API. The ciphers are specified in the format understood by the OpenSSL library.
The full list can be viewed using the
“openssl ciphers
” command.
Syntax: |
js_fetch_protocols
[ |
---|---|
Default: |
js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2; |
Context: |
http , server , location |
This directive appeared in version 0.7.0.
Enables the specified protocols for HTTPS requests with Fetch API.
Syntax: |
js_fetch_trusted_certificate |
---|---|
Default: | — |
Context: |
http , server , location |
This directive appeared in version 0.7.0.
Specifies a file
with trusted CA certificates in the PEM format
used to
verify
the HTTPS certificate
with Fetch API.
Syntax: |
js_fetch_verify_depth |
---|---|
Default: |
js_fetch_verify_depth 100; |
Context: |
http , server , location |
This directive appeared in version 0.7.0.
Sets the verification depth in the HTTPS server certificates chain with Fetch API.
Syntax: |
js_header_filter |
---|---|
Default: | — |
Context: |
location , limit_except |
This directive appeared in version 0.5.1.
Sets an njs function as a response header filter. The directive allows changing arbitrary header fields of a response header.
As the js_header_filter
handler
returns its result immediately, it supports
only synchronous operations.
Thus, asynchronous operations such as
r.subrequest()
or
setTimeout()
are not supported.
Syntax: |
js_import |
---|---|
Default: | — |
Context: |
http |
This directive appeared in version 0.4.0.
Imports a module that implements location and variable handlers in njs.
The export_name
is used as a namespace
to access module functions.
If the export_name
is not specified,
the module name will be used as a namespace.
js_import http.js;
Here, the module name http
is used as a namespace
while accessing exports.
If the imported module exports foo()
,
http.foo
is used to refer to it.
Several js_import
directives can be specified.
Syntax: |
js_include |
---|---|
Default: | — |
Context: |
http |
Specifies a file that implements location and variable handlers in njs:
nginx.conf: js_include http.js; location /version { js_content version; } http.js: function version(r) { r.return(200, njs.version); }
The directive is deprecated since 0.4.0, the js_import directive should be used instead.
Syntax: |
js_path
|
---|---|
Default: | — |
Context: |
http |
This directive appeared in version 0.3.0.
Sets an additional path for njs modules.
Syntax: |
js_set
|
---|---|
Default: | — |
Context: |
http |
Sets an njs function
for the specified variable
.
Since 0.4.0,
a module function can be referenced.
The function is called when the variable is referenced for the first time for a given request. The exact moment depends on a phase 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 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.
As the js_set
handler
returns its result immediately, it supports
only synchronous operations.
Thus, asynchronous operations such as
r.subrequest()
or
setTimeout()
are not supported.
Syntax: |
js_var |
---|---|
Default: | — |
Context: |
http |
This directive appeared in version 0.5.3.
Declares a writable variable. The value can contain text, variables, and their combination. The variable is not overwritten after a redirect unlike variables created with the set directive.
Request Argument
Each HTTP njs handler receives one argument, a request object.