Справочник

Этот перевод может быть устаревшим. Смотрите английскую версию для ознакомления с последними изменениями.
Объекты nginx
     HTTP-запрос
     Stream-сессия

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

Объекты nginx

HTTP-запрос

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

r.args{}
объект аргументов запроса, только чтение
r.error(строка)
записывает строку в лог-файл ошибок на уровне лога error
r.finish()
завершает отправку ответа клиенту
r.headersIn{}
объект входящих заголовков, только чтение.

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

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.
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, только чтение
r.warn(строка)
записывает строку в лог-файл ошибок на уровне лога warning
r.uri
текущий URI, только чтение
r.subrequest(uri[, options[, callback]])
создаёт подзапрос с заданными uri и options и устанавливает необязательный callback завершения.

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

args
строка с аргументами
body
тело запроса
method
метод HTTP

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

Stream-сессия

Объект 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, только чтение
s.warn(строка)
записывает отправленную строку в лог-файл ошибок на уровне лога warning

Устаревшие свойства

Данные свойства были удалены в njs версии 0.2.4 и не имеют обратной совместимости с существующим кодом njs.

s.ABORT
код ABORT
Начиная с версии njs 0.2.4 необходимо использовать метод s.deny().
s.AGAIN
код AGAIN
Начиная с версии njs 0.2.4 соответствующее поведение достигается, если не вызываются s.allow(), s.deny(), s.decline(), s.done() и callback зарегистрирован.
s.buffer
текущий буфер, доступен для записи
Начиная с версии njs 0.2.4 для записи необходимо использовать метод s.send(). Для чтения текущий буфер доступен в качестве первого аргумента callback'а event.
s.DECLINED
код DECLINED
Начиная с версии njs 0.2.4 необходимо использовать метод s.decline().
s.eof
логическое свойство, true, если текущий буфер является последним буфером, только чтение
Начиная с версии njs 0.2.4 необходимо использовать свойство flags.last.
s.ERROR
код ERROR
Начиная с версии njs 0.2.4 для сообщения об ошибке используется соответствующее исключение.
s.fromUpstream
логическое свойство, true, если текущий буфер является буфером от проксируемого сервера к клиенту, только чтение
Начиная с версии njs 0.2.4 необходимо использовать соответствующее событие (upload или download) для обработки данных к клиенту или от клиента.
s.OK
код OK
Начиная с версии njs 0.2.4 необходимо использовать метод s.allow().