Reference
nginx objects HTTP Request Stream Session Core Object 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 theerror
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 syntaxheadersIn.foo
orheadersIn['Foo']
r.headersOut{}
-
outgoing headers object, writable.
For example, the
Foo
header can be accessed with the syntaxheadersOut.foo
orheadersOut['Foo']
r.httpVersion
- HTTP version, read-only
r.log(
string
)-
writes a
string
to the error log on theinfo
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 clientIt 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 thewarning
level of logging r.uri
- current URI, read-only
r.subrequest(
uri
[,options
[,callback
]])-
creates a subrequest with the given
uri
andoptions
, and installs an optional completioncallback
.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 theerror
level of logging s.log(
string
)-
writes a sent
string
to the error log on theinfo
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 specifiedevent
(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)
, wheredata
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
s.variables{}
- nginx variables object, read-only
s.warn(
string
)-
writes a sent
string
to the error log on thewarning
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 codeStarting from njs 0.2.4, the s.deny() method should be used instead.
s.AGAIN
-
the
AGAIN
return codeStarting 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 codeStarting 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 codeStarting 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
ordownload
) should be used to handle data to or from client. s.OK
-
the
OK
return codeStarting from njs 0.2.4, the s.allow() method should be used instead.
Core
Object
The Object
constructor corresponds to a standard JS object.
Object.entries(
object
)-
returns an array of all enumerable property
[key, value]
pairs of the givenobject
(0.2.7). Object.values(
object
)-
returns an array of all enumerable property values
of the given
object
(0.2.7).
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 */
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
, andbase64url
.>> 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 an integer between 0 and 1-less-than the length of the string. If no index is provided, the default is0
, 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
position
;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, otherwisefalse
. The optionallength
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, otherwisefalse
. The optionalposition
parameter is the position within the string at which to begin search forsearchString
. 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 atfromIndex
. Returns-1
if the value is not found. ThefromIndex
is an integer, default value is 0. IffromIndex
is lower than 0 or greater than String.prototype.length, the search starts at index
0
andString.prototype.length
.>> 'abcdef'.indexOf('de', 2) 3
String.prototype.lastIndexOf(
searchString
[,fromIndex
])-
Returns the position of the last occurrence
of the
searchString
, searching backwards fromfromIndex
. Returns-1
if the value is not found. IfsearchString
is empty, thenfromIndex
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 padstring
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 padstring
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 aregexp
) replaced by astring
or afunction
.>> '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
andend
or fromstart
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 optionallimit
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, otherwisefalse
. The optionalposition
parameter is the position in this string at which to begin search forsearchString
. 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
fromstart
or fromstart
to the end of the string.>> 'abcdefghijklmno'.substr(3, 5) 'defgh'
String.prototype.substring(
start
[,end
])-
Returns the part of the string between
start
andend
or fromstart
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 tohex
,base64
, orbase64url
.>> 'αβγδ'.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 optionalreviver
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 JSONobject
orarray
that will be converted. If the value has atoJSON()
method, it defines how the object will be serialized. The optionalreplacer
parameter is afunction
orarray
that transforms results. The optionalspace
parameter is astring
ornumber
. If it is anumber
, it indicates the number of white spaces placed before a result (no more than 10). If it is astring
, it is used as a white space (or first 10 characters of it). If omitted or isnull
, 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({ 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 bemd5
,sha1
, andsha256
. crypto.createHmac(
algorithm
,secret key
)-
Creates and returns an HMAC object
that uses the given
algorithm
andsecret key
. The algorighm can bemd5
,sha1
, andsha256
.
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 behex
,base64
, andbase64url
. 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 behex
,base64
, andbase64url
. 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 ofmilliseconds
. One or more optionalarguments
can be passed to the specified function. Returns atimeout
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 providedfilename
. If the file does not exist, it will be created. Theoptions
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
. Theoptions
parameter holdsstring
that specifies encoding. If not specified, a byte string is returned. Ifutf8
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 providedfilename
. If the file does not exist, it will be created, if the file exists, it will be replaced. Theoptions
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 asa
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 asa+
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 asw
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 asw+
but fails if the file already exists