Reference

• nginx objects
• HTTP Request
• Stream Session
• Core
• String
• JSON
• Crypto
• Timers
• File System

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

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.

For example, the Foo header can be accessed with the syntax headersIn.foo or headersIn['Foo']

r.headersOut{}

outgoing headers object, writable.

For example, the Foo header can be accessed with the syntax headersOut.foo or headersOut['Foo']

r.httpVersion

HTTP version, read-only

r.log(string)

writes a string to the error log on the info level of logging

r.internalRedirect(uri)

performs an internal redirect to the specified uri. If the uri starts with the “@” prefix, it is considered a named location.

r.method

HTTP method, read-only

r.parent

references the parent request object

r.remoteAddress

client address, read-only

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.

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.variables{}

nginx variables object, read-only

r.warn(string)

writes a string to the error log on the warning level of logging

r.uri

current URI, read-only

r.subrequest(uri[, options[, callback]])

creates a subrequest with the given uri and options, and installs an optional completion callback.

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

body

request body

method

HTTP method

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

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.

Prior to njs 0.2.4, the stream session object had some properties which are currently removed.

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 overriden 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, read-only

s.warn(string)

writes a sent string to the error log on the warning level of logging

Obsolete properties

These properties have been removed in njs 0.2.4 and are not backward compatible with the existing njs code.

s.ABORT

the ABORT return code

Starting from njs 0.2.4, the s.deny() method should be used instead.

s.AGAIN

the AGAIN return code

Starting from njs 0.2.4, the corresponding behavior is achieved if no s.allow(), s.deny(), s.decline(), s.done() is invoked and a callback is registered.

s.buffer

the current buffer, writable

Starting from 0.2.4, the s.send() method should be used for writing. For reading, the current buffer is available as the first argument of the event callback.

s.DECLINED

the DECLINED return code

Starting from njs 0.2.4, the s.decline() method should be used instead.

s.eof

a boolean read-only property, true if the current buffer is the last buffer

Starting from 0.2.4, the flags.last property should be used instead.

s.ERROR

the ERROR return code

Starting from njs 0.2.4, an appropriate exception can be thrown to report an error.

s.fromUpstream

a boolean read-only property, true if the current buffer is from the upstream server to the client

Starting from 0.2.4, a corresponding event (upload or download) should be used to handle data to or from client.

s.OK

the OK return code

Starting from njs 0.2.4, the s.allow() method should be used instead.

Core

String

There are two types of strings: 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. They 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  */

Only byte strings can be converted to different encodings. For example, a string cannot be encoded to hex directly:

>> 'αβγδ'.toString('base64')
TypeError: argument must be a byte string
    at String.prototype.toString (native)
    at main (native)

To convert a Unicode string to hex, first, it should be converted to a byte string and then to hex:

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

String.bytesFrom(array | string, encoding)

(njs specific) 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.fromCharCode(CharCode1[, ...[, CharCodeN]])

Returns a string from one or more Unicode code points.

>> String.fromCharCode(97, 98, 99, 100)
'abcd'

String.fromCodePoint(codePoint1[, ...[, codePoint2]])

Returns a string from one or more Unicode code points.

>> String.fromCodePoint(97, 98, 99, 100)
'abcd'

String.prototype.charAt(index)

Returns a string representing one Unicode code unit at the specified index; empty string if index is out of range. The index can be integer between 0 and 1-less-than the length of the string. If no index is provided, the default is 0, so the first character in the string is returned.

String.prototype.CodePointAt(position)

Returns a number representing the code point value of the character at the given index; undefined if there is no element at position.

>> 'ABCD'.codePointAt(3);
68

String.prototype.concat(string1[, ..., stringN])

Returns a string that contains the concatenation of specified strings.

>> "a".concat("b", "c")
'abc'

String.prototype.endsWith(searchString[, length])

Returns true if a string ends with the characters of a specified string, otherwise false. The optional length parameter is the the length of string. If omitted, the default value is the length of the string.

>> 'abc'.endsWith('abc')
true
>> 'abca'.endsWith('abc')
false

String.prototype.fromBytes(start[, end])

(njs specific) 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])

(njs specific) Converts a byte string containing a valid UTF8 string into a Unicode string, otherwise null is returned.

String.prototype.includes(searchString[, position]))

Returns true if a string is found within another string, otherwise false. The optional position parameter is the position within the string at which to begin search for searchString. Default value is 0.

>> 'abc'.includes('bc')
true

String.prototype.indexOf(searchString[, fromIndex])

Returns the position of the first occurrence of the searchString The search is started at fromIndex. Returns -1 if the value is not found. The fromIndex is an integer, default value is 0. If fromIndex is lower than 0 or greater than String.prototype.length, the search starts at index 0 and String.prototype.length.

>> 'abcdef'.indexOf('de', 2)
3

String.prototype.lastIndexOf(searchString[, fromIndex])

Returns the position of the last occurrence of the searchString, searching backwards from fromIndex. Returns -1 if the value is not found. If searchString is empty, then fromIndex is returned.

>> "nginx".lastIndexOf("gi")
1

String.prototype.length

Returns the length of the string.

>> 'αβγδ'.length
4

String.prototype.match([regexp])

Matches a string against a regexp.

>> 'nginx'.match( /ng/i )
'ng'

String.prototype.padEnd(length [, string])

Returns a string of a specified length with the pad string applied to the end of the specified string (0.2.3).

>> '1234'.padEnd(8, 'abcd')
'1234abcd'

String.prototype.padStart(length [, string])

Returns a string of a specified length with the pad string applied to the start of the specified string (0.2.3).

>> '1234'.padStart(8, 'abcd')
'abcd1234'

String.prototype.repeat(number)

Returns a string with the specified number of copies of the string.

>> 'abc'.repeat(3)
'abcabcabc'

String.prototype.replace([regexp|string[, string|function]])

Returns a new string with matches of a pattern (string or a regexp) replaced by a string or a function.

>> 'abcdefgh'.replace('d', 1)
'abc1efgh'

String.prototype.search([regexp])

Searches for a string using a regexp

>> 'abcdefgh'.search('def')
3

String.prototype.slice(start[, end])

Returns a new string containing a part of an original string between start and end or from start to the end of the string.

>> 'abcdefghijklmno'.slice(NaN, 5)
'abcde'

String.prototype.split(([string|regexp[, limit]]))

Returns match of a string against a regexp. The optional limit parameter is an integer that specifies a limit on the number of splits to be found.

>> 'abc'.split('')
[
 'a',
 'b',
 'c'
]

String.prototype.startsWith(searchString[, position])

Returns true if a string begins with the characters of a specified string, otherwise false. The optional position parameter is the position in this string at which to begin search for searchString. Default value is 0.

>> 'abc'.startsWith('abc')
true
> 'aabc'.startsWith('abc')
false

String.prototype.substr(start[, length])

Returns the part of the string of the specified length from start or from start to the end of the string.

>>  'abcdefghijklmno'.substr(3, 5)
'defgh'

String.prototype.substring(start[, end])

Returns the part of the string between start and end or from start to the end of the string.

>> 'abcdefghijklmno'.substring(3, 5)
'de'

String.prototype.toBytes(start[, end])

(njs specific) Serializes a Unicode string to a byte string. Returns null if a character larger than 255 is found in the string.

String.prototype.toLowerCase()

Converts a string to lower case. The method supports only simple Unicode folding.

>> 'ΑΒΓΔ'.toLowerCase()
'αβγδ'

String.prototype.toString([encoding])

If no encoding is specified, returns a specified Unicode string or byte string as in ECMAScript.

(njs specific) If encoding is specified, encodes a byte string to hex, base64, or base64url.

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

String.prototype.toUpperCase()

Converts a string to upper case. The method supports only simple Unicode folding.

>> 'αβγδ'.toUpperCase()
'ΑΒΓΔ'

String.prototype.toUTF8(start[, end])

(njs specific) Serializes a Unicode string to a byte string using UTF8 encoding.

>> 'αβγδ'.toUTF8().length
8
>> 'αβγδ'.length
4

String.prototype.trim()

Removes whitespaces from both ends of a string.

>> '   abc  '.trim()
'abc'

encodeURI(URI)

encodes a URI by replacing each instance of certain characters by one, two, three, or four escape sequences representing the UTF-8 encoding of the character

>> encodeURI('012αβγδ')
'012%CE%B1%CE%B2%CE%B3%CE%B4'

encodeURIComponent(encodedURIString)

Encodes a URI by replacing each instance of certain characters by one, two, three, or four escape sequences representing the UTF-8 encoding of the character.

>> encodeURIComponent('[@?=')
'%5B%40%3F%3D'

decodeURI(encodedURI)

Decodes a previously encoded URI.

>> decodeURI('012%CE%B1%CE%B2%CE%B3%CE%B4')
'012αβγδ'

decodeURIComponent(decodedURIString)

Decodes an encoded component of a previously encoded URI.

>> decodeURIComponent('%5B%40%3F%3D')
'[@?='

JSON

The JSON object (ES 5.1) provides functions to convert njs values to and from JSON format.

JSON.parse(string[, reviver])

Converts a string that represents JSON data into an njs object ({...}) or array ([...]). The optional reviver parameter is a function (key, value) that will be called for each (key,value) pair and can transform the value.

JSON.stringify(value[, replacer] [, space])

Converts an njs object back to JSON. The obligatory value parameter is generally a JSON object or array that will be converted. If the value has a toJSON() method, it defines how the object will be serialized. The optional replacer parameter is a function or array that transforms results. The optional space parameter is a string or number. If it is a number, it indicates the number of white spaces placed before a result (no more than 10). If it is a string, it is used as a white space (or first 10 characters of it). If omitted or is null, no white space is used.

>> var json = JSON.parse('{"a":1, "b":true}')
>> json.a
1

>> JSON.stringify(json)
'{"a":1,"b":true}'

>> JSON.stringify(json, undefined, 1)
'{\n "a": 1,\n "b": true\n}'

>> JSON.stringify({ x: [10, undefined, function(){}] })
'{"x":[10,null,null]}'

>> JSON.stringify({"a":1, "toJSON": function() {return "xxx"}})
'"xxx"'

# Example with function replacer

>> function replacer(key, value) {return (typeof value === 'string') ? undefined : value}
>>JSON.stringify({a:1, b:"b", c:true}, replacer)
'{"a":1,"c":true}'

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 algorighm 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 algorighm 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'

Timers

clearTimeout(timeout)

Cancels a timeout object created by setTimeout().

setTimeout(function, ms[, arg1, argN])

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);

File System

The File System module provides operations with files. The module object is returned by require('fs').

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

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

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

File System Flags

The flag option can accept the following values:

• a — open a file for appending. The file is created if it does not exist
• ax — the same as a but fails if the file already exists
• a+ — open a file for reading and appending. If the file does not exist, it will be created
• ax+ — the same as a+ but fails if the file already exists
• as — open a file for appending in synchronous mode. If the file does not exist, it will be created
• as+ — open a file for reading and appending in synchronous mode. If the file does not exist, it will be created
• r — open a file for reading. An exception occurs if the file does not exist
• r+ — open a file for reading and writing. An exception occurs if the file does not exist
• rs+ — open a file for reading and writing in synchronous mode. Instructs the operating system to bypass the local file system cache
• w — open a file for writing. If the file does not exist, it will be created. If the file exists, it will be replaced
• wx — the same as w but fails if the file already exists
• w+ — open a file for reading and writing. If the file does not exist, it will be created. If the file exists, it will be replaced
• wx+ — the same as w+ but fails if the file already exists