Справочник

Объекты nginx
     HTTP-запрос
     Stream-сессия
Core
     Global
     String
     Text Decoder
     Text Encoder
     Timers
Встроенные модули
     Crypto
     File System
     Query String

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

Справочник содержит описания методов, свойств и модулей, доступных только в njs и не соответствующих стандарту ECMAScript. Описания методов и свойств njs, соответствующих стандарту, доступны в спецификации ECMAScript. Список всех методов и свойств njs доступен в разделе Совместимость.

Объекты nginx

HTTP-запрос

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

r.args{}

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

r.error(строка)

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

r.finish()

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

r.headersIn{}

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

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

Заголовки запроса “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” и “User-Agent” могут иметь только одно значение поля (0.4.1). Дубликаты значений поля в заголовке запроса “Cookie” разделяются точкой с запятой (;). Дубликаты значений поля во всех остальных заголовках запроса разделяются запятой.

r.headersOut{}

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

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

Значения полей многозначных заголовков ответа (0.4.0) можно задать при помощи синтаксиса:

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

результат:

Foo: a
Foo: b

Все предыдущие значения поля заголовка ответа “Foo” будут удалены.

В стандартных заголовках ответа, поля которых могут принимать только одно значение, например “Content-Type”, учитывается только последний элемент массива. Значения поля в заголовке ответа “Set-Cookie” всегда возвращаются в виде массива. Дубликаты значений поля в заголовках ответа “Age”, “Content-Encoding”, “Content-Length”, “Content-Type”, “ETag”, “Expires”, “Last-Modified”, “Location”, “Retry-After” игнорируются. Дубликаты значений поля в других заголовках ответов разделяются при помощи запятой.

r.httpVersion

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

r.internalRedirect(uri)

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

r.log(строка)

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

r.method

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

r.parent

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

r.remoteAddress

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

r.rawHeadersIn{}

возвращает массив пар ключей и значений таким же, каким он был получен от клиента (0.4.1).

Например для следующих заголовков запроса:

Host: localhost
Foo:  bar
foo:  bar2

результат r.rawHeadersIn:

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

Значения полей всех заголовков foo можно получить при помощи синтаксиса:

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

результат:

['bar', 'bar2']

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

r.rawHeadersOut{}

возвращает массив пар ключей и значений заголовков ответа (0.4.1). Имена полей заголовков не приводятся к нижнему регистру, дубликаты значений поля не объединяются.

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.subrequest(uri[, options[, callback]])

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

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

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

args: строка с аргументами, по умолчанию используется пустая строка
body: тело запроса, по умолчанию используется тело запроса родительского объекта запроса
method: метод HTTP, по умолчанию используется метод GET
detached: логический флаг (0.3.9), если true, то создаваемый подзапрос является независимым подзапросом. Ответы на независимые подзапросы игнорируются. В отличие от обычных подзапросов независимый подзапрос можно создать внутри обработчика переменной. Флаг detached и аргумент callback являются взаимоисключающими.

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

Начиная с версии njs 0.3.8 если не указан callback, то возвращается объект Promise, который разрешается в объект ответа подзапроса.

r.uri

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

r.variables{}

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

r.warn(строка)

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

Stream-сессия

Объект stream-сессии доступен только в модуле ngx_stream_js_module. Все строки в объекте 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

Core

Global

Process

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

process.argv: Возвращает массив, содержащий аргументы командной строки, передаваемые в момент запуска текущего процесса.
process.env: Возвращает объект, содержащий переменные окружения пользователя.
По умолчанию nginx удаляет все переменные окружения, унаследованные от своего родительского процесса, кроме переменной TZ. Для сохранения части унаследованных переменных необходимо использовать директиву env.
process.pid: Возвращает PID текущего процесса.
process.ppid: Возвращает PID текущего родительского процесса.

String

В 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 ('£')  */

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

Создаёт байтовую строку или из массива, содержащего октеты, или из кодированной строки (0.2.3). Кодировкой может быть hex, base64 и base64url. Метод устарел начиная с 0.4.4, вместо него следует использовать метод Buffer.from:

>> Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]).toString()
'buffer'

>> Buffer.from('YnVmZmVy', 'base64').toString()
'buffer'

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

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

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

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

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

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

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

Кодирует указанную строку в hex, base64 или base64url:

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

До версии 0.4.3 могла быть кодирована только байтовая строка:

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

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

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

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

Text Decoder

Объект TextDecoder создаёт поток кодовых точек из потока данных (0.4.3).

TextDecoder([[кодировка], options])

Создаёт новый объект TextDecoder для указанной кодировки, на данный момент поддерживается только UTF-8. Параметр options является словарём TextDecoderOption со свойствами:

fatal: логический флаг, указывающий, что TextDecoder.decode() должен вызывать исключение TypeError в случае, если найдена ошибка кодирования, по умолчанию false.

TextDecoder.prototype.encoding

Возвращает строку с именем кодировки, используемой TextDecoder(), только чтение.

TextDecoder.prototype.fatal

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

TextDecoder.prototype.ignoreBOM

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

TextDecoder.prototype.decode(буфер, [options])

Возвращает строку с текстом, декодированным из буфера при помощи TextDecoder(). Буфером может быть ArrayBuffer. Параметром options является словарь TextDecodeOptions со свойствами:

stream: логический флаг, указывающий, что при последующих вызовах decode() должны последовать дополнительные данные: true, если данные обрабатываются блоками, и false для последнего блока или если данные не передаются блоками. По умолчанию false.

>> (new TextDecoder()).decode(new Uint8Array([206,177,206,178]))
αβ

Text Encoder

Объект TextEncoder создаёт поток данных в кодировке UTF-8 из потока кодовых точек (0.4.3).

TextEncoder()

Возвращает только что созданный TextEncoder, который создаёт поток данных в кодировке UTF-8.

TextEncoder.prototype.encode(строка)

Кодирует строку в Uint8Array, содержащий текст в кодировке UTF-8.

TextEncoder.prototype.encodeInto(строка, uint8Array)

Преобразует строку в UTF-8, сохраняет результат в целевом Uint8Array и возвращает объект словаря, отражающий прогресс кодирования, со свойствами:

read: количество блоков кода UTF-16 из исходной строки, преобразованных в UTF-8
written: количество байтов, преобразованных в целевом Uint8Array

Timers

clearTimeout(timeout)

Отменяет объект timeout, созданный setTimeout().

setTimeout(функция, миллисекунды[, аргумент1, аргументN])

Вызывает функцию по прошествии указанного количества миллисекунд. Указанной функции можно передать один или более необязательных аргументов. Возвращает объект timeout.

function handler(v)
{
    // ...
}

t = setTimeout(handler, 12);

// ...

clearTimeout(t);

Встроенные модули

Crypto

Модуль Crypto предоставляет поддержку криптографических функций. Объект модуля Crypto доступен через require('crypto').

crypto.createHash(алгоритм): Создаёт и возвращает объект Hash, который может использоваться для создания hash digests при помощи указанного алгоритма. Алгоритмом может быть md5, sha1 и sha256.
crypto.createHmac(алгоритм, секретный ключ): Создаёт и возвращает объект HMAC, который использует заданный алгоритм и секретный ключ. Алгоритм может быть md5, sha1 и sha256.

Hash

hash.update(данные): Обновляет содержимое хэша с передаваемыми данными.
hash.digest([кодировка]): Подсчитывает дайджест всех данных, передаваемых при помощи hash.update(). Кодировка может быть hex, base64 и base64url. Если кодировка не указана, то будет возвращен объект буфера (0.4.4).
До версии 0.4.4 вместо объекта буфера возвращалась байтовая строка.

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

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

HMAC

hmac.update(данные): Обновляет содержимое HMAC с передаваемыми данными.
hmac.digest([кодировка]): Подсчитывает HMAC-дайджест всех данных, передаваемых при помощи hmac.update(). Кодировка может быть hex, base64 и base64url. Если кодировка не указана, то будет возвращена байтовая строка.

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

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

File System

Модуль File System предоставляет набор функций для операций с файлами.

Объект модуля доступен через require('fs'). Начиная с версии 0.3.9 доступны промисифицированные версии методов file system через объект require('fs').promises:

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

accessSync(путь[, mode])

Синхронно проверяет разрешения для файла или каталога, указанного в пути (0.3.9). Если проверка не удалась, то будет возвращена ошибка, в противном случае метод возвратит undefined.

mode

По умолчанию fs.constants.F_OK. Является необязательным числом, которое задаёт выполнение проверок доступа.

try {
    fs.accessSync('/file/path', fs.constants.R_OK | fs.constants.W_OK);
    console.log('has access');
} catch (e) {
    console.log('no access');)
}

appendFileSync(имяФайла, данные[, options])

Синхронно добавляет указанные данные в файл с указанным именем. Данными могут быть строка или объект буфера (0.4.4. Если файл не существует, то он будет создан. Параметр options должен быть объектом со следующими ключами:

режим: режим, по умолчанию 0o666
флаг: флаг файловой системы, по умолчанию a

mkdirSync(путь[, options])

Синхронно создаёт каталог по указанному пути (0.4.2). Параметр options должен быть числом, которое задаёт режим, или объектом с ключами:

режим: режим, по умолчанию 0o777.

readdirSync(путь[, options])

Синхронно читает содержимое каталога по указанному пути (0.4.2). Параметр options должен быть строкой, определяющей кодировку или объектом с ключами:

кодировка: кодировка, по умолчанию utf8. Кодировка может быть utf8 и буфер (0.4.4).
withFileTypes: если true, то массив файлов будет содержать объекты fs.Dirent, по умолчанию false.

readFileSync(имяФайла[, options])

Синхронно возвращает содержимое файла с указанным именем. Параметр options хранит строку, которая задаёт кодировку. Если кодировка указана, то будет возвращена строка, иначе будет возвращён объект буфера (0.4.4).

До версии 0.4.4 возвращалась байтовая строка в случае, если не была указана кодировка.

Иначе ожидается, что options является объектом с ключами:

кодировка: кодировка, по умолчанию не указана. Кодировка может быть utf8, hex (0.4.4), base64 (0.4.4), base64url (0.4.4).
флаг: флаг файловой системы, по умолчанию r

>> var fs = require('fs')
undefined
>> var file = fs.readFileSync('/file/path.tar.gz')
undefined
>> var gzipped = file.slice(0,2).toString('hex') === '1f8b'; gzipped
true

realpathSync(путь[, options])

Синхронно вычисляет канонический путь при помощи преобразования ., .. и символических ссылок используя realpath(3). Аргумент options может быть строкой, определяющей кодировку, или объектом со свойством encoding, определяющим символьную кодировку, которая используется для передачи пути обратному вызову (0.3.9).

renameSync(старыйПуть, новыйПуть)

Синхронно меняет имя или местоположение файла. (0.3.4).

>> var fs = require('fs')
undefined
>> var file = fs.renameSync('hello.txt', 'HelloWorld.txt')
undefined

rmdirSync(путь)

Синхронно удаляет каталог по указанному пути (0.4.2).

symlinkSync(цель, path)

Синхронно создаёт ссылку с именем путь, указывающую на цель при помощи symlink(2) (0.3.9). Относительные цели считаются относительно корневого каталога ссылки.

unlinkSync(путь)

Синхронно удаляет файл по указанному пути (0.3.9).

writeFileSync(имяФайла, данные[, options])

Синхронно записывает данные в файл с указанным именем. Данными могут быть строка или объект буфера (0.4.4. Если файл не существует, то он будет создан. Если файл существует, то он будет заменён. Параметр options должен быть объектом с ключами:

режим: режим, по умолчанию 0o666
флаг: флаг файловой системы, по умолчанию w

>> var fs = require('fs')
undefined
>> var file = fs.writeFileSync('hello.txt', 'Hello world')
undefined

fs.Dirent

fs.Dirent является представлением записи каталога — файлом или подкаталогом . В случае, если readdirSync() вызывается с опцией withFileTypes получившийся массив содержит объекты fs.Dirent.

dirent.isBlockDevice() — возвращает true, если объект fs.Dirent описывает блочное устройство
dirent.isCharacterDevice() — возвращает true, если объект fs.Dirent описывает символьное устройство.
dirent.isDirectory() — возвращает true, если объект fs.Dirent описывает каталог файловой системы.
dirent.isFIFO() — возвращает true, если объект fs.Dirent описывает FIFO-канал.
dirent.isFile() — возвращает true, если объект fs.Dirent описывает обычный файл.
dirent.isSocket() — возвращает true, если объект fs.Dirent описывает сокет.
dirent.isSymbolicLink() — возвращает true, если объект fs.Dirent описывает символическую ссылку.
dirent.name — имя файла, на которое ссылается объект fs.Dirent.

Константы доступа к файлу

Метод access() может принимать следующие флаги. Флаги экспортируются при помощи fs.constants:

F_OK — указывает, что файл может быть видимым для для вызывающего процесса, используется по умолчанию, если режим не указан
R_OK — указывает, что файл может читаться вызывающим процессом
W_OK — указывает, что файл может записываться вызывающим процессом
X_OK — указывает, что файл может выполняться вызывающим процессом

Флаги файловой системы

Опция флаг может принимать следующие значения:

a — открытие файла для добавления данных. Если файл не существует, то он будет создан
ax — то же, что и a, но завершится неудачей, если файл существует
a+ — открытие файла для чтения и добавления данных. Если файл не существует, то он будет создан
ax+ — то же, что и a+, но завершится неудачей, если файл существует
as — открытие файла для добавления данных в синхронном режиме. Если файл не существует, то он будет создан
as+ — открытие файла для чтения и добавления данных в синхронном режиме. Если файл не существует, то он будет создан
r — открытие файла для чтения. Если файл не существует, то возникнет исключение
r+ — открытие файла для чтения и записи. Если файл не существует, то возникнет исключение
rs+ — открытие файла для чтения и записи в синхронном режиме. Указывает операционной системе не использовать кэш локальной файловой системы
w — открытие файла для записи. Если файл не существует, то он будет создан. Если файл существует, то он будет заменён.
wx — то же, что и w, но завершится неудачей, если файл существует
w+ — открытие файла для чтения и записи. Если файл не существует, то он будет создан. Если файл существует, то он будет заменён.
wx+ — то же, что и w+, но завершится неудачей, если файл существует

Query String

Модуль Query String предоставляет поддержку синтаксического разбора и форматирования строки запроса URL. (0.4.3). Объект модуля Query String доступен через require('querystring').

querystring.decode()

является псевдонимом для querystring.parse().

querystring.encode()

является псевдонимом для querystring.stringify().

querystring.escape(строка)

Кодирует заданную строку, возвращает экранированную строку. Метод используется методом querystring.stringify() и не должен использоваться напрямую.

querystring.parse(строка[, separator[, equal[, options]]])

Осуществляет синтаксический разбор строки запроса и возвращает объект.

Параметр separator является подстрокой, разделяющей в строке запроса пары ключей и значений, по умолчанию “&”.

Параметр equal является подстрокой, разделяющей в строке запроса ключи и значения, по умолчанию “=”.

Параметр options должен быть объектом со следующими ключами:

decodeURIComponent функция: Функция, используемая при декодировании процентно-кодированных символов в строке запроса, по умолчанию querystring.unescape()
maxKeys число: максимальное число ключей для синтаксического разбора, по умолчанию 1000. Значение 0 удаляет ограничение на подсчёт ключей.

По умолчанию предполагается, что процентно-кодированные символы в строке запроса используют кодировку UTF-8, неверная последовательность байтов UTF-8 будет заменена на U+FFFD.

Пример для строки запроса:

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

результат:

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

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

Осуществляет синтаксический разбор объекта и возвращает строку запроса.

Параметр separator является подстрокой, разделяющей в строке запроса пары ключей и значений, по умолчанию “&”.

Параметр equal является подстрокой, разделяющей в строке запроса ключи и значения, по умолчанию “=”.

Параметр options должен быть объектом со следующими ключами:

encodeURIComponent функция: Функция, используемая при декодировании URL-небезопасных символов в в процентно-кодированные символы в строке запроса, по умолчанию querystring.escape().

По умолчанию символы, требующие процентной кодировки внутри строки запроса, кодируются в UTF-8. Если требуется другая кодировка, то необходимо указать опцию encodeURIComponent.

Пример:

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

результат:

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

querystring.unescape(строка)

Осуществляет декодирование процентно-кодированных символов URL в строке, возвращает неэкранированную строку запроса. Метод используется методом querystring.parse() и не должен использоваться напрямую.