Справочник
Этот перевод может быть устаревшим. Смотрите английскую версию для ознакомления с последними изменениями.
Объекты nginx HTTP-запрос Stream-сессия Core Строка |
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
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().
Core
Строка
В 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'
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') '[@?='