Reference

nginx objects
     HTTP Request
     Stream Session
Core
     Global
     String
     Text Decoder
     Text Encoder
     Timers
Built-in Modules
     Crypto
     File System
     Query String

njs provides objects, methods and properties for extending nginx functionality.

This reference contains only njs specific properties, methods and modules not compliant with ECMAScript. Definitions of njs properties and methods compliant with ECMAScript can be found in ECMAScript specification. List of all njs properties and methods can be found in Compatibility.

nginx objects

HTTP Request

The HTTP request object is available only in the ngx_http_js_module module. All string properties of the object are byte strings.

r.args{}
request arguments object, read-only
r.error(string)
writes a string to the error log on the error level of logging
r.finish()
finishes sending a response to the client
r.headersIn{}
incoming headers object, read-only.

The Foo request header can be accessed with the syntax: headersIn.foo or headersIn['Foo'].

The “Authorization”, “Content-Length”, “Content-Range”, “Content-Type”, “ETag”, “Expect”, “From”, “Host”, “If-Match”, “If-Modified-Since”, “If-None-Match”, “If-Range”, “If-Unmodified-Since”, “Max-Forwards”, “Proxy-Authorization”, “Referer”, “Transfer-Encoding”, and “User-Agent” request headers can have only one field value (0.4.1). Duplicate field values in “Cookie” headers are separated by semicolon (;). Duplicate field values in all other request headers are separated by commas.

r.headersOut{}
outgoing headers object, writable.

The “Foo” response header can be accessed with the syntax: headersOut.foo or headersOut['Foo'].

Field values of multi-value response headers (0.4.0) can be set with the syntax:

r.headersOut['Foo'] = ['a', 'b']

where the output will be:

Foo: a
Foo: b

All previous field values of the “Foo” response header will be deleted.

For standard response headers that accept only a single field value such as “Content-Type”, only the last element of the array will take effect. Field values of the “Set-Cookie” response header are always returned as an array. Duplicate field values in “Age”, “Content-Encoding”, “Content-Length”, “Content-Type”, “ETag”, “Expires”, “Last-Modified”, “Location”, “Retry-After” response headers are ignored. Duplicate field values in all other response headers are separated by commas.

r.httpVersion
HTTP version, read-only
r.internalRedirect(uri)
performs an internal redirect to the specified uri. If the uri starts with the “@” prefix, it is considered a named location. The actual redirect happens after the handler execution is completed.
r.log(string)
writes a string to the error log on the info level of logging
r.method
HTTP method, read-only
r.parent
references the parent request object
r.remoteAddress
client address, read-only
r.rawHeadersIn{}
returns an array of key-value pairs exactly as they were received from the client (0.4.1).

For example, with the following request headers:

Host: localhost
Foo:  bar
foo:  bar2

the output of r.rawHeadersIn will be:

[
    ['Host', 'localhost'],
    ['Foo', 'bar'],
    ['foo', 'bar2']
]

All foo headers can be collected with the syntax:

r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1])

the output will be:

['bar', 'bar2']

Header field names are not converted to lower case, duplicate field values are not merged.

r.rawHeadersOut{}
returns an array of key-value pairs of response headers (0.4.1). Header field names are not converted to lower case, duplicate field values are not merged.
r.requestBody
returns the client request body if it has not been written to a temporary file. To ensure that the client request body is in memory, its size should be limited by client_max_body_size, and a sufficient buffer size should be set using client_body_buffer_size. The property is available only in the js_content directive.
r.responseBody
holds the subrequest response body, read-only. The size of r.responseBody is limited by the subrequest_output_buffer_size directive.
r.return(status[, string])
sends the entire response with the specified status to the client

It is possible to specify either a redirect URL (for codes 301, 302, 303, 307, and 308) or the response body text (for other codes) as the second argument

r.send(string)
sends a part of the response body to the client
r.sendHeader()
sends the HTTP headers to the client
r.status
status, writable
r.subrequest(uri[, options[, callback]])
creates a subrequest with the given uri and options, and installs an optional completion callback.

A subrequest shares its input headers with the client request. To send headers different from original headers to a proxied server, the proxy_set_header directive can be used. To send a completely new set of headers to a proxied server, the proxy_pass_request_headers directive can be used.

If options is a string, then it holds the subrequest arguments string. Otherwise, options is expected to be an object with the following keys:

args
arguments string, by default an empty string is used
body
request body, by default the request body of the parent request object is used
method
HTTP method, by default the GET method is used
detached
boolean flag (0.3.9), if true, the created subrequest is a detached subrequest. Responses to detached subrequests are ignored. Unlike ordinary subrequests, a detached subrequest can be created inside a variable handler. The detached flag and callback argument are mutually exclusive.

The completion callback receives a subrequest response object with methods and properties identical to the parent request object.

Since 0.3.8, if a callback is not provided, the Promise object that resolves to the subrequest response object is returned.

r.uri
current URI in request, normalized, read-only
r.variables{}
nginx variables object, writable (since 0.2.8)
r.warn(string)
writes a string to the error log on the warning level of logging

Stream Session

The stream session object is available only in the ngx_stream_js_module module. All string properties of the object are byte strings.

s.allow()
successfully finalizes the phase handler (0.2.4)
s.decline()
finalizes the phase handler and passes control to the next handler (0.2.4)
s.deny()
finalizes the phase handler with the access error code (0.2.4)
s.done([code])
successfully finalizes the current phase handler or finalizes it with the specified numeric code (0.2.4).
s.error(string)
writes a sent string to the error log on the error level of logging
s.log(string)
writes a sent string to the error log on the info level of logging
s.off(eventName)
unregisters the callback set by the s.on() method (0.2.4)
s.on(event, callback)
registers a callback for the specified event (0.2.4).

An event may be one of the following strings:

upload
new data from a client
download
new data to a client

The completion callback has the following prototype: callback(data, flags), where data is string, flags is an object with the following properties:

last
a boolean value, true if data is a last buffer.

s.remoteAddress
client address, read-only
s.send(data[, options])
sends the data to the client (0.2.4). The options is an object used to override nginx buffer flags derived from an incoming data chunk buffer. The flags can be overridden with the following flags:

last
boolean, true if the buffer is the last buffer
flush
boolean, true if the buffer should have the flush flag

The method can be called multiple times per callback invocation.
s.variables{}
nginx variables object, writable (since 0.2.8)
s.warn(string)
writes a sent string to the error log on the warning level of logging

Core

Global

Process

The process object is a global object that provides information about the current process (0.3.3).

process.argv
Returns an array that contains the command line arguments passed when the current process was launched.
process.env
Returns an object containing the user environment.
By default, nginx removes all environment variables inherited from its parent process except the TZ variable. Use the env directive to preserve some of the inherited variables.
process.pid
Returns the PID of the current process.
process.ppid
Returns the PID of the current parent process.

String

There are two types of strings in njs: a Unicode string (default) and a byte string.

A Unicode string corresponds to an ECMAScript string which contains Unicode characters.

Byte strings contain a sequence of bytes and are used to serialize Unicode strings to external data and deserialize from external sources. For example, the toUTF8() method serializes a Unicode string to a byte string using UTF8 encoding:

>> '£'.toUTF8().toString('hex')
'c2a3'  /* C2 A3 is the UTF8 representation of 00A3 ('£') code point */

The toBytes() method serializes a Unicode string with code points up to 255 into a byte string, otherwise, null is returned:

>> '£'.toBytes().toString('hex')
'a3'  /* a3 is a byte equal to 00A3 ('£') code point  */

String.bytesFrom(array | string, encoding)
Creates a byte string either from an array that contains octets, or from an encoded string (0.2.3). The encoding can be hex, base64, and base64url.
>> String.bytesFrom([0x62, 0x75, 0x66, 0x66, 0x65, 0x72])
'buffer'

>> String.bytesFrom('YnVmZmVy', 'base64')
'buffer'
String.prototype.fromBytes(start[, end])
Returns a new Unicode string from a byte string where each byte is replaced with a corresponding Unicode code point.
String.prototype.fromUTF8(start[, end])
Converts a byte string containing a valid UTF8 string into a Unicode string, otherwise null is returned.
String.prototype.toBytes(start[, end])
Serializes a Unicode string to a byte string. Returns null if a character larger than 255 is found in the string.
String.prototype.toString(encoding)

Encodes a string to hex, base64, or base64url:

>>  'αβγδ'.toString('base64url')
'zrHOss6zzrQ'

Before version 0.4.3, only a byte string could be encoded:

>>  'αβγδ'.toUTF8().toString('base64url')
'zrHOss6zzrQ'

String.prototype.toUTF8(start[, end])
Serializes a Unicode string to a byte string using UTF8 encoding.
>> 'αβγδ'.toUTF8().length
8
>> 'αβγδ'.length
4

Text Decoder

The TextDecoder produces a stream of code points from a stream of bytes (0.4.3).

TextDecoder([[encoding], options])
Creates a new TextDecoder object for specified encoding, currently, only UTF-8 is supported. The options is TextDecoderOptions dictionary with the property:
fatal
boolean flag indicating if TextDecoder.decode() must throw the TypeError exception when a coding error is found, by default is false.
TextDecoder.prototype.encoding
Returns a string with the name of the encoding used by TextDecoder(), read-only.
TextDecoder.prototype.fatal
boolean flag, true if the error mode is fatal, read-only.
TextDecoder.prototype.ignoreBOM
boolean flag, true if the byte order marker is ignored, read-only.
TextDecoder.prototype.decode(buffer, [options])
Returns a string with the text decoded from the buffer by TextDecoder(). The buffer can be ArrayBuffer. The options is TextDecodeOptions dictionary with the property:
stream
boolean flag indicating if additional data will follow in subsequent calls to decode(): true if processing the data in chunks, and false for the final chunk or if the data is not chunked. By default is false.
>> (new TextDecoder()).decode(new Uint8Array([206,177,206,178]))
αβ

Text Encoder

The TextEncoder object produces a byte stream with UTF-8 encoding from a stream of code points (0.4.3).

TextEncoder()
Returns a newly constructed TextEncoder that will generate a byte stream with UTF-8 encoding.
TextEncoder.prototype.encoding
Returns “utf-8”, read-only.
TextEncoder.prototype.encode(string)
Encodes string into a Uint8Array with UTF-8 encoded text.
TextEncoder.prototype.encodeInto(string, uint8Array)
Encodes a string to UTF-8, puts the result into destination Uint8Array, and returns a dictionary object that shows the progress of the encoding. The dictionary object contains two members:
read
the number of UTF-16 units of code from the source string converted to UTF-8
written
the number of bytes modified in the destination Uint8Array

Timers

clearTimeout(timeout)
Cancels a timeout object created by setTimeout().
setTimeout(function, milliseconds[, argument1, argumentN])
Calls a function after a specified number of milliseconds. One or more optional arguments can be passed to the specified function. Returns a timeout object.
function handler(v)
{
    // ...
}

t = setTimeout(handler, 12);

// ...

clearTimeout(t);

Built-in Modules

Crypto

The Crypto module provides cryptographic functionality support. The Crypto module object is returned by require('crypto').

crypto.createHash(algorithm)
Creates and returns a Hash object that can be used to generate hash digests using the given algorithm. The algorithm can be md5, sha1, and sha256.
crypto.createHmac(algorithm, secret key)
Creates and returns an HMAC object that uses the given algorithm and secret key. The algorithm can be md5, sha1, and sha256.

Hash

hash.update(data)
Updates the hash content with the given data.
hash.digest([encoding])
Calculates the digest of all of the data passed using hash.update(). The encoding can be hex, base64, and base64url. If encoding is not provided, a byte string is returned.

>> var cr = require('crypto')
undefined

>> cr.createHash('sha1').update('A').update('B').digest('base64url')
'BtlFlCqiamG-GMPiK_GbvKjdK10'

HMAC

hmac.update(data)
Updates the HMAC content with the given data.
hmac.digest([encoding])
Calculates the HMAC digest of all of the data passed using hmac.update(). The encoding can be hex, base64, and base64url. If encoding is not provided, a byte string is returned.

>> var cr = require('crypto')
undefined

>> cr.createHmac('sha1', 'secret.key').update('AB').digest('base64url')
'Oglm93xn23_MkiaEq_e9u8zk374'

File System

The File System module provides operations with files.

The module object is returned by require('fs'). Since 0.3.9, promissified versions of file system methods are available through require('fs').promises object:

> var fs = require('fs').promises;
undefined
> fs.readFile("/file/path").then((data)=>console.log(data))
<file data>

accessSync(path[, mode])
Synchronously tests permissions for a file or directory specified in the path (0.3.9). If the check fails, an error will be returned, otherwise, the method will return undefined.
mode
by default is fs.constants.F_OK. The mode argument is an optional integer that specifies the accessibility checks to be performed.
try {
    fs.accessSync('/file/path', fs.constants.R_OK | fs.constants.W_OK);
    console.log('has access');
} catch (e) {
    console.log('no access');)
}
appendFileSync(filename, data[, options])
Synchronously appends specified data to a file with provided filename. If the file does not exist, it will be created. The options parameter is expected to be an object with the following keys:
mode
mode option, by default is 0o666
flag
file system flag, by default is a
mkdirSync(path[, options])
Synchronously creates a directory at the specified path (0.4.2). The options parameter is expected to be an integer that specifies the mode, or an object with the following keys:
mode
mode option, by default is 0o777.
readdirSync(path[, options])
Synchronously reads the contents of a directory at the specified path (0.4.2). The options parameter is expected to be a string that specifies encoding or an object with the following keys:
encoding
encoding, by default is not specified. The encoding can be utf8.
withFileTypes
if set to true, the files array will contain fs.Dirent objects, by default is false.
readFileSync(filename[, options])
Synchronously returns the contents of the file with provided filename. The options parameter holds string that specifies encoding. If not specified, a byte string is returned. If utf8 encoding is specified, a Unicode string is returned. Otherwise, options is expected to be an object with the following keys:
encoding
encoding, by default is not specified. The encoding can be utf8
flag
file system flag, by default is r
>> var fs = require('fs')
undefined
>> var file = fs.readFileSync('/file/path.tar.gz')
undefined
>> var gzipped = /^\x1f\x8b/.test(file); gzipped
true
realpathSync(path[, options])
Synchronously computes the canonical pathname by resolving ., .. and symbolic links using realpath(3). The options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use for the path passed to the callback (0.3.9).
renameSync(oldPath, newPath)
Synchronously changes the name or location of a file from oldPath to newPath (0.3.4).
>> var fs = require('fs')
undefined
>> var file = fs.renameSync('hello.txt', 'HelloWorld.txt')
undefined
rmdirSync(path)
Synchronously removes a directory at the specified path (0.4.2).
symlinkSync(target, path)
Synchronously creates the link called path pointing to target using symlink(2) (0.3.9). Relative targets are relative to the link’s parent directory.
unlinkSync(path)
Synchronously unlinks a file by path (0.3.9).
writeFileSync(filename, data[, options])
Synchronously writes data to a file with provided filename. If the file does not exist, it will be created, if the file exists, it will be replaced. The options parameter is expected to be an object with the following keys:
mode
mode option, by default is 0o666
flag
file system flag, by default is w
>> var fs = require('fs')
undefined
>> var file = fs.writeFileSync('hello.txt', 'Hello world')
undefined

fs.Dirent

fs.Dirent is a representation of a directory entry — a file or a subdirectory. When readdirSync() is called with the withFileTypes option, the resulting array contains fs.Dirent objects.

File Access Constants

The access() method can accept the following flags. These flags are exported by fs.constants:

File System Flags

The flag option can accept the following values:

Query String

The Query String module provides support for parsing and formatting URL query strings (0.4.3). The Query String module object is returned by require('querystring').

querystring.decode()
is an alias for querystring.parse().
querystring.encode()
is an alias for querystring.stringify().
querystring.escape(string)

Performs URL encoding of the given string, returns an escaped query string. The method is used by querystring.stringify() and should not be used directly.

querystring.parse(string[, separator[, equal[, options]]])

Parses the query string URL and returns an object.

The separator parameter is a substring for delimiting key and value pairs in the query string, by default is “&”.

The equal parameter is a substring for delimiting keys and values in the query string, by default is “=”.

The options parameter is expected to be an object with the following keys:

decodeURIComponent function
Function used to decode percent-encoded characters in the query string, by default is querystring.unescape()
maxKeys number
the maximum number of keys to parse, by default is 1000. The 0 value removes limitations for counting keys.

By default, percent-encoded characters within the query string are assumed to use the UTF-8 encoding, invalid UTF-8 sequences will be replaced with the U+FFFD replacement character.

For example, for the following query string

'foo=bar&abc=xyz&abc=123'

the output will be:

{
  foo: 'bar',
  abc: ['xyz', '123']
}

querystring.stringify(object[, separator[, equal[, options]]])

Serializes an object and returns a URL query string.

The separator parameter is a substring for delimiting key and value pairs in the query string, by default is “&”.

The equal parameter is a substring for delimiting keys and values in the query string, by default is “=”.

The options parameter is expected to be an object with the following keys:

encodeURIComponent function
The function to use when converting URL-unsafe characters to percent-encoding in the query string, by default is querystring.escape().

By default, characters that require percent-encoding within the query string are encoded as UTF-8. If other encoding is required, then encodeURIComponent option should be specified.

For example, for the following command

querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], 123: '' });

the query string will be:

'foo=bar&baz=qux&baz=quux&123='

querystring.unescape(string)

Performs decoding of URL percent-encoded characters of the string, returns an unescaped query string. The method is used by querystring.parse() and should not be used directly.