Справочник

njs предоставляет объекты, методы и свойства для расширения функциональности nginx.

Объект HTTP доступен только в модуле ngx_http_js_module. Все строки в объекте HTTP являются байтовыми строками.

r.args{}

объект аргументов запроса, только чтение

r.error(строка)

записывает строку в лог-файл ошибок на уровне лога error

r.finish()

завершает отправку ответа клиенту

r.headersIn{}

объект входящих заголовков, только чтение.

Например, доступ к заголовку Foo можно получить при помощи синтаксиса headersIn.foo или headersIn['Foo']

До версии 0.3.6 если заголовок был указан несколько раз, например “Cookie” или “X-Forwarded-For”, то возвращалось только первое значение. Чтобы получить все cookie необходимо использовать r.variables.http_cookie. Чтобы получить имя cookie необходимо использовать r.variables["cookie_имя"].

r.headersOut{}

объект исходящих заголовков, доступно для записи.

Например, доступ к заголовку Foo можно получить при помощи синтаксиса headersOut.foo или headersOut['Foo']

r.httpVersion

версия HTTP, только чтение

r.log(строка)

записывает строку в лог-файл ошибок на уровне лога info

r.internalRedirect(uri)

осуществляет внутреннее перенаправление на указанный uri. Если uri начинается с префикса “@”, то он считается именованным location.

r.method

HTTP метод, только чтение

r.parent

ссылается на родительский объект запроса

r.remoteAddress

адрес клиента, только чтение

r.requestBody

возвращает тело запроса клиента, если оно не было записано во временный файл. Чтобы убедиться, что тело запроса клиента находится в памяти, его размер должен быть ограничен client_max_body_size, и также необходимо установить достаточный размер буфера при помощи client_body_buffer_size. Свойство доступно только в директиве js_content.

r.responseBody

хранит тело ответа подзапроса, только чтение. Размер r.responseBody ограничивается директивой subrequest_output_buffer_size.

r.return(код[, строка])

отправляет клиенту полный ответ с указанным кодом

Можно задать или URL перенаправления (для кодов 301, 302, 303, 307 и 308), или текст тела ответа (для остальных кодов) в качестве второго аргумента

r.send(строка)

отправляет часть тела ответа клиенту

r.sendHeader()

отправляет заголовки HTTP клиенту

r.status

статус, доступно для записи

r.variables{}

объект переменных nginx, доступно для записи (начиная с версии 0.2.8)

r.warn(строка)

записывает строку в лог-файл ошибок на уровне лога warning

r.uri

текущий URI запроса в нормализованном виде, только чтение

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

создаёт подзапрос с заданными uri и options и устанавливает необязательный callback завершения.

Подзапрос использует входящиe заголовки клиентского запроса. Для отправки на проксируемый сервер заголовков, отличных от оригинальных, может использоваться директива proxy_set_header. Для отправки на проксируемый сервер нового набора заголовков может использоваться директива proxy_pass_request_headers.

Если options является строкой, то в ней содержится срока аргументов подзапроса. В противном случае ожидается, что options является объектом со следующими ключами:

args

строка с аргументами, по умолчанию используется пустая строка

body

тело запроса, по умолчанию используется тело запроса родительского объекта запроса

method

метод HTTP, по умолчанию используется метод GET

callback получает объект ответа подзапроса с методами и свойствами, идентичными родительскому объекту запроса.

Объект stream-сессии доступен только в модуле ngx_stream_js_module. Все строки в объекте stream являются байтовыми строками.

До версии njs 0.2.4, у объекта stream-сессии были некоторые свойства, которые на данный момент удалены.

s.allow()

успешно финализирует обработчик фазы (0.2.4)

s.decline()

финализирует обработчик фазы и передаёт контроль следующему обработчику (0.2.4)

s.deny()

финализирует обработчик фазы с кодом ошибки доступа (0.2.4)

s.done([код])

успешно финализирует текущий обработчик фазы или финализирует его с указанным числовым кодом (0.2.4).

s.error(строка)

записывает отправленную строку в лог-файл ошибок на уровне лога error

s.log(строка)

записывает отправленную строку в лог-файл ошибок на уровне лога info

s.off(имяСобытия)

отменяет регистрацию callback'а, установленного методом s.on() (0.2.4)

s.on(событие, callback)

регистрирует callback для указанного события (0.2.4).

Событием может являться одна из следующих строк:

upload

новые данные от клиента

download

новые данные к клиенту

Callback завершения имеет следующий прототип: callback(данные, флаги), где данные являются строкой, флаги являются объектом со следующими свойствами:

last

логическое свойство, true, если данные являются последним буфером.

s.remoteAddress

адрес клиента, только чтение

s.send(данные[, параметры])

отправляет данные клиенту (0.2.4). Параметры являются объектом, используемым для переопределения флагов буфера nginx, полученных из буфера входных данных. Флаги могут быть переопределены при помощи следующих флагов:

last

логическое свойство, true, если буфер является последним буфером

flush

логическое свойство, true, если буфер должен иметь флаг flush

Метод может быть вызван несколько раз в течение одного вызова callback'a.

s.variables{}

объект переменных nginx, доступно для записи (начиная с версии 0.2.8)

s.warn(строка)

записывает отправленную строку в лог-файл ошибок на уровне лога warning

Объект process является глобальным объектом, предоставляющим информацию о текущем процессе (0.3.3).

process.argv

Возвращает массив, содержащий аргументы командной строки, передаваемые в момент запуска текущего процесса.

process.env

Возвращает объект, содержащий переменные окружения пользователя.

По умолчанию nginx удаляет все переменные окружения, унаследованные от своего родительского процесса, кроме переменной TZ. Для сохранения части унаследованных переменных необходимо использовать директиву env.

process.pid

Возвращает PID текущего процесса.

process.ppid

Возвращает PID текущего родительского процесса.

В njs существует два типа строк: строка Unicode (по умолчанию) и байтовая строка.

Строка Unicode соответствует строке ECMAScript, содержащей символы Unicode.

Байтовые строки содержат последовательность байт и используются для сериализации строк Unicode во внешние данные и десериализации из внешних источников. Например метод toUTF8() сериализует строку Unicode в байтовую строку используя кодировку UTF8:

>> '£'.toUTF8().toString('hex')
'c2a3'  /* C2 A3 является UTF8-представлением codepoint 00A3 ('£') */

Метод toBytes() сериализует строку Unicode с codepoints до 255 в байтовую строку, в противном случае возвращается null:

>> '£'.toBytes().toString('hex')
'a3'  /* a3 является байтом, равным codepoint 00A3 ('£')  */

В различные кодировки могут быть преобразованы только байтовые строки. Например строка не может быть кодирована напрямую в hex:

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

Чтобы преобразовать строку Unicode в hex, сначала необходимо её преобразовать в байтовую строку и затем в hex:

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

String.bytesFrom(массив | строка, кодировка)

(только в njs) Создаёт байтовую строку или из массива, содержащего октеты, или из кодированной строки (0.2.3). Кодировкой может быть hex, base64 и base64url.

>> String.bytesFrom([0x62, 0x75, 0x66, 0x66, 0x65, 0x72])
'buffer'

>> String.bytesFrom('YnVmZmVy', 'base64')
'buffer'

String.fromCharCode(CharCode1[, ...[, CharCodeN]])

Возвращает строку из одной или более Unicode codepoints.

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

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

Возвращает строку из одной или более Unicode codepoints.

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

String.prototype.charAt(индекс)

Возвращает строку, представляющую одну кодовую единицу Unicode внутри указанного индекса; пустая строка, если индекс вне диапазона значений. Индекс может быть числом между 0 и длиной строки минус 1. Если индекс не указан, то значение по умолчанию равно 0, т.е. возвращается первый символ в строке.

String.prototype.CodePointAt(позиция)

Возвращает число, представляющее codepoint-значение символа в пределах указанной позиции; undefined, если элемент в позиции отсутствует.

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

String.prototype.concat(строка1[, ..., строкаN])

Возвращает строку, содержающую результат объединения указанных строк.

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

String.prototype.endsWith(ПоисковаяСтрока[, длина])

Возвращает true, если строка заканчивается символами указанной строки, иначе false. Необязательный параметр длина задаёт длину строки. Если ПоисковаяСтрока не указана, значением по умолчанию является длина строки.

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

String.prototype.fromBytes(начало[, конец])

(только в njs) Возвращает новую строку Unicode из байтовой строки, в которой каждый байт заменяется соответствующей Unicode codepoint.

String.prototype.fromUTF8(начало[, конец])

(только в njs) Преобразует байтовую строку, содержащую валидную строку UTF8, в строку Unicode, иначе возвращается null.

String.prototype.includes(поисковаяСтрока[, позиция]))

Возвращает true, если строка ищется внутри другой строки, иначе false. Необязательный параметр позиция задаёт позицию внутри строки, от которой начинается поиск для поисковойСтроки. Значение по умолчанию равно 0.

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

String.prototype.indexOf(поисковаяСтрока[, fromIndex])

Возвращает позицию первого появления поисковойСтроки. Поиск начинается с fromIndex. Возвращает -1, если значение не найдено. fromIndex является числом, значение по умолчанию равно 0. Если fromIndex меньше, чем 0 или больше, чем String.prototype.length, поиск начнётся на индексе 0 и String.prototype.length.

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

String.prototype.lastIndexOf(поисковаяСтрока[, fromIndex])

Возвращает позицию последнего появления of the поисковойСтроки, поиск осуществляется в обратном порядке от fromIndex. Возвращает -1, если значение не найдено. Если значение поисковойСтроки пустое, то возвращается fromIndex.

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

String.prototype.length

Возвращает длину строки.

>> 'αβγδ'.length
4

String.prototype.match([регулярноеВыражение])

Возвращает совпадение при сопоставлении строки с регулярным выражением.

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

String.prototype.padEnd(длина [, строка])

Возвращает строку указанной длины, добавляя строку в конец указанной строки (0.2.3).

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

String.prototype.padStart(длина [, строка])

Возвращает строку указанной длины, добавляя строку к началу указанной строки (0.2.3).

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

String.prototype.repeat(число)

Возвращает строку с указанным числом копий строки.

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

String.prototype.replace([регулярноеВыражение|string[, string|function]])

Возвращает новую строку, которая сопоставляется со строкой или регулярным выражением, и заменяется на строку или функцию.

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

String.prototype.search([регулярноеВыражение])

Осуществляет поиск строки при помощи регулярного выражения.

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

String.prototype.slice(начало[, конец])

Возвращает новую строку, содержащую часть исходной строки между началом и концом или от начала до конца строки.

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

String.prototype.split(([строка|регулярноеВыражение[, лимит]]))

Возвращает совпадение строки регулярному выражению. Необязательный параметр лимит является числом, задающим ограничение на количество найденных подстрок.

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

String.prototype.startsWith(поисковаяСтрока[, позиция])

Возвращает true, если строка начинается с символов указанной строки, иначе false. Необязательный параметр позиция является местом в этой строке, с которого начинается поиск поисковойСтоки. Значение по умолчанию равно 0.

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

String.prototype.substr(начало[, длина])

Возвращает часть строки указанной длины от начала или от начала до конца строки.

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

String.prototype.substring(начало[, конец])

Возвращает часть строки между началом и концом или от от начала до конца строки.

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

String.prototype.toBytes(начало[, конец])

(только в njs) Сериализует строку Unicode в байтовую строку. Возвращает null, если в строке найден символ больше, чем 255.

String.prototype.toLowerCase()

Преобразует строку в нижний регистр. Метод поддерживает только простое свёртывание Unicode.

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

String.prototype.toString([кодировка])

Если кодировка не указана, возвращает указанную строку Unicode string или байтовую строку как в ECMAScript.

(только в njs) Если кодировка указана, кодирует байтовую строку в hex, base64 или base64url.

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

String.prototype.toUpperCase()

Преобразует строку в верхний регистр. Метод поддерживает только простое свёртывание Unicode.

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

String.prototype.toUTF8(начало[, конец])

(только в njs) Сериализует строку Unicode в байтовую строку при помощи кодирования UTF8.

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

String.prototype.trim()

Удаляет пробелы в начале и конце строки.

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

String.prototype.trimEnd()

Удаляет пробелы в конце строки. (0.3.4).

>> '   abc  '.trimEnd()
'   abc'

String.prototype.trimStart()

Удаляет пробелы в начале строки. (0.3.4).

>> '   abc  '.trimStart()
'abc  '

encodeURI(URI)

Кодирует URI путём замены определённых символов на одну, две, три или четыре последовательности, представляющие UTF-8 кодировку символа.

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

encodeURIComponent(encodedURIString)

Кодирует URI путём замены определённых символов на одну, две, три или четыре последовательности, представляющие UTF-8 кодировку символа.

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

decodeURI(encodedURI)

Декодирует ранее кодированный URI.

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

decodeURIComponent(decodedURIString)

Декодирует ранее кодированный URI.

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