Справочник

• Объекты nginx
• HTTP-запрос
• Сессия потока
• Периодическая сессия
• Заголовки
• Запрос
• Ответ
• ngx
• ngx.shared
• Встроенные объекты
• Консоль
• crypto
• CryptoKey
• CryptoKeyPair
• njs
• process
• Строка
• Интерфейс веб-API
• Декодер текста
• Кодировщик текста
• Таймеры
• Глобальные функции
• Встроенные модули
• Буфер
• Шифрование
• Система файлов
• Строка запроса
• XML
• zlib

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

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

Объекты nginx

HTTP-запрос

Объект HTTP-запроса доступен только в модуле ngx_http_js_module. До версии 0.8.5 все строковые свойства объекта были байтовыми строками.

r.args{}

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

Строка запроса возвращается в виде объекта. Начиная с 0.7.6, дублирующиеся ключи возвращаются как массив, ключи чувствительны к регистру, и ключи, и значения декодированы по процентам.

Например, строка запроса

'a=1&b=%32&A=3&b=4&B=two%20words'

преобразуется в r.args как:

{a: "1", b: ["2", "4"], A: "3", B: "two words"}

Более сложные сценарии обработки строк запроса можно реализовать с помощью модуля Строка запроса и переменной $args, например:

import qs from 'querystring';

function args(r) {
    return qs.parse(r.variables.args);
}

Объект аргументов вычисляется при первом обращении к r.args. Если требуется только один аргумент, например foo, можно использовать переменные nginx:

r.variables.arg_foo

Здесь объект переменных nginx возвращает первое значение для заданного ключа, не учитывая регистр, без декодирования по процентам.

Чтобы преобразовать r.args обратно в строку, можно использовать метод строки запроса stringify.

r.done()

после вызова этой функции следующие фрагменты данных будут переданы клиенту без вызова js_body_filter (0.5.2). Может быть вызван только из функции js_body_filter

r.error(string)

записывает string в журнал ошибок на уровне ведения журнала error

Поскольку nginx имеет жестко заданный предел длины строки, в журнал записываются только первые 2048 байтов строки.

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{}

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

Если r.headersOut{} является объектом ответа подзапроса, он представляет заголовки ответа. В этом случае значения полей в заголовках ответа «Accept-Ranges», «Connection», «Content-Disposition», «Content-Encoding», «Content-Length», «Content-Range», «Date», «Keep-Alive», «Server», «Transfer-Encoding», «X-Accel-*» могут быть опущены.

Заголовок ответа «Foo» можно получить по синтаксису: headersOut.foo или headersOut['Foo'].

Исходящие заголовки должны быть установлены до отправки заголовка ответа клиенту, в противном случае обновление заголовков будет проигнорировано. Это означает, что r.headersOut{} фактически доступен для записи в:

• обработчике js_content до вызова r.sendHeader() или r.return()
• обработчике js_header_filter

Значения полей многозначных заголовков ответа (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.internal

логическое значение, true для внутренних расположений

r.internalRedirect(uri)

выполняет внутренний переход на указанный uri. Если uri начинается с префикса «@», он считается именованным расположением. В новом расположении вся обработка запроса повторяется, начиная с NGX_HTTP_SERVER_REWRITE_PHASE для обычных расположений и с NGX_HTTP_REWRITE_PHASE для именованных расположений. В результате перенаправление на именованное расположение не проверяет ограничение client_max_body_size. Подробнее см. руководство по разработке. Перенаправленные запросы становятся внутренними и могут получить доступ к внутренним расположениям. Фактическое перенаправление происходит после завершения обработки обработчика.

После перенаправления в целевом расположении запускается новая виртуальная машина njs, а виртуальная машина в исходном расположении останавливается. Значения переменных nginx сохраняются и могут использоваться для передачи информации в целевое расположение. Начиная с 0.5.3, можно использовать переменную, объявленную с помощью директивы js_var для http или stream.

Начиная с 0.7.4, метод принимает экранированные URI.

r.log(string)

записывает string в журнал ошибок на уровне ведения журнала info

Поскольку nginx имеет жестко заданный предел длины строки, в журнал записываются только первые 2048 байтов строки.

r.method

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

r.parent

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

r.remoteAddress

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

r.requestBody

свойство было устаревшим в 0.5.0 и было удалено в 0.8.0. Следует использовать свойство r.requestBuffer или r.requestText.

r.requestBuffer

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

r.requestText

то же, что и r.requestBuffer, но возвращает string. Обратите внимание, что недопустимые в кодировке UTF-8 байты могут быть преобразованы в символ замены.

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.responseBody

свойство было устаревшим в 0.5.0 и было удалено в 0.8.0. Следует использовать свойство r.responseBuffer или r.responseText.

r.responseBuffer

содержит тело ответа подзапроса, только для чтения (начиная с 0.5.0). Размер r.responseBuffer ограничен директивой subrequest_output_buffer_size.

r.responseText

то же, что и r.responseBuffer, но возвращает строку (начиная с 0.5.0). Обратите внимание, что недопустимые в кодировке UTF-8 байты могут быть преобразованы в символ замены.

r.return(status[, string | Buffer])

отправляет весь ответ с указанным status клиенту. Ответ может быть строкой или буфером (0.5.0).

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

r.send(string | Buffer)

отправляет часть тела ответа клиенту. Отправляемые данные могут быть строкой или буфером (0.5.0)

r.sendBuffer(data[, options])

добавляет данные в цепочку фрагментов данных, которые будут переданы следующему фильтру тела (0.5.2). Фактическая передача происходит позже, когда все фрагменты данных текущей цепочки будут обработаны.

Данные могут быть строкой или буфером. options — это объект, используемый для переопределения флагов буфера nginx, полученных из буфера входящих данных. Флаги можно переопределить с помощью следующих флагов:

last

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

flush

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

Метод может быть вызван только из функции js_body_filter.

r.sendHeader()

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

r.setReturnValue(value)

устанавливает возвращаемое значение обработчика js_set (0.7.0). В отличие от обычного оператора return, этот метод следует использовать, когда обработчик является асинхронной функцией JS. Например:

async function js_set(r) {
    const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
    r.setReturnValue(digest);
}

r.status

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

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

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

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

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

args

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

body

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

method

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

detached

флаг булевого типа (0.3.9), если true, создаваемый подзапрос — отделённый подзапрос. Ответы на отделённые подзапросы игнорируются. В отличие от обычных подзапросов, отделённый подзапрос может быть создан внутри обработчика переменной. Флаг detached и аргумент обратного вызова взаимоисключающие.

Завершающий callback получает объект ответа подзапроса subrequest response object с методами и свойствами, идентичными родительскому объекту запроса.

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

Например, для просмотра всех заголовков ответа в подзапросе:

async function handler(r) {
    const reply = await r.subrequest('/path');

    for (const h in reply.headersOut) {
        r.log(`${h}: ${reply.headersOut[h]}`);
    }

    r.return(200);
}

r.uri

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

r.rawVariables{}

nginx переменные как буферы, доступ для записи (с 0.5.0)

r.variables{}

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

Например, для получения переменной $foo, можно использовать один из следующих синтаксисов:

r.variables['foo']
r.variables.foo

nginx обрабатывает переменные, на которые есть ссылка в nginx.conf, и переменные без ссылок по-разному. Когда на переменную есть ссылка, она может быть кешируемой, но когда ссылка отсутствует, она всегда некешируемая. Например, когда переменная $request_id используется только из njs, она имеет новое значение каждый раз при вычислении. Но когда переменная $request_id ссылается, например:

proxy_set_header X-Request-Id $request_id;

r.variables.request_id возвращает то же самое значение каждый раз.

Переменная доступна для записи, если:

• она была создана с помощью директивы js_var для http или stream (с 0.5.3)
• она упоминается в файле конфигурации nginx

Тем не менее, некоторые встроенные переменные по-прежнему не могут быть присвоены значение (например, $http_).

r.warn(string)

записывает string в журнал ошибок на уровне логирования warning

Так как nginx имеет жёстко заданный лимит максимальной длины строки logging, в журнал можно записать только первые 2048 байт строки.

Сессия потока

Объект сессии потока доступен только в модуле ngx_stream_js_module. До 0.8.5 все строковые свойства объекта были байтовыми строками.

s.allow()

псевдоним для s.done(0) (0.2.4)

s.decline()

псевдоним для s.done(-5) (0.2.4)

s.deny()

псевдоним для s.done(403) (0.2.4)

s.done([code])

устанавливает код завершения code для текущего обработчика фазы обработки, по умолчанию 0. Фактическое завершение происходит, когда обработчик JS завершается и обрабатываются все ожидающие события, например, от ngx.fetch() или setTimeout() (0.2.4).

Возможные значения кодов:

• 0 — успешное завершение, передача управления следующей фазе
• -5 — неопределённо, передача управления следующему обработчику текущей фазы (если есть)
• 403 — доступ запрещён

Может быть вызван только из функции обработчика фазы: js_access или js_preread.

s.error(string)

записывает отправленное string в журнал ошибок на уровне error ведения журнала

Так как nginx имеет жёстко заданный максимальный размер строки, в журнал могут быть записаны только первые 2048 байт строки.

s.log(string)

записывает отправленное string в журнал ошибок на уровне info ведения журнала

Так как nginx имеет жёстко заданный максимальный размер строки, в журнал могут быть записаны только первые 2048 байт строки.

s.off(eventName)

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

s.on(event, callback)

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

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

upload

новые данные (строка) от клиента

download

новые данные (строка) клиенту

upstream

новые данные (Buffer) от клиента (с 0.5.0)

downstream

новые данные (Buffer) клиенту (с 0.5.0)

Обратный вызов имеет следующий прототип: callback(data, flags), где data это строка или Buffer (в зависимости от типа события) flags это объект со следующими свойствами:

last

логическое значение, true, если данные — последний буфер.

s.remoteAddress

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

s.rawVariables

переменные nginx переменные в виде Buffers, доступно для записи (с 0.5.0)

s.send(data[, options])

добавляет данные в цепочку фрагментов данных, которые будут переданы в направлении передачи: при загрузке клиенту; при загрузке на upstream-сервер (0.2.4). Фактическая передача происходит позже, когда все фрагменты данных текущей цепочки будут обработаны.

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

last

логическое значение, true, если буфер — последний буфер

flush

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

Метод может быть вызван несколько раз за одно обращение к обратной функции.

s.sendDownstream()

идентичен s.send(), за исключением того, что всегда отправляет данные клиенту (с 0.7.8).

s.sendUpstream()

идентичен s.send(), за исключением того, что всегда отправляет данные клиенту (с 0.7.8).

s.status

код состояния сессии, псевдоним для переменной $status, только для чтения (с 0.5.2)

s.setReturnValue(value)

устанавливает возвращаемое значение обработчика js_set (0.7.0). В отличие от обычного оператора return, этот метод следует использовать, когда обработчик — асинхронная JS-функция. Например:

async function js_set(r) {
    const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
    r.setReturnValue(digest);
}

s.variables{}

объект переменных nginx переменных, доступно для записи (с 0.2.8). Переменная может быть доступна для записи только если она упоминается в конфигурационном файле nginx. Тем не менее, некоторые встроенные переменные по-прежнему не могут быть назначены значение.

s.warn(string)

записывает отправленное string в журнал ошибок на уровне warning ведения журнала

Так как nginx имеет жёстко заданный максимальный размер строки, в журнал могут быть записаны только первые 2048 байт строки.

Периодическое сессия

Объект Periodic Session предоставляется в качестве первого аргумента для обработчика js_periodic для http и stream (с 0.8.1).

PeriodicSession.rawVariables{}

переменные nginx переменные в виде Buffers, доступно для записи.

PeriodicSession.variables{}

объект переменных nginx переменных, доступно для записи.

Заголовки

Интерфейс Headers Fetch API доступен с 0.5.1.

Новый объект Headers может быть создан с помощью конструктора Headers() (с 0.7.10):

Headers([init])

init

Объект, содержащий HTTP-заголовки для предварительной подготовки объекта Headers, может быть string, array пар имя-значение или существующим объектом Headers.

Новый объект Headers может быть создан со следующими свойствами и методами:

append()

Добавляет новое значение в существующий заголовок в объекте Headers, или добавляет заголовок, если он ещё не существует (с 0.7.10).

delete()

Удаляет заголовок из объекта Headers (с 0.7.10).

get()

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

getAll(name)

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

forEach()

Выполняет предоставленную функцию один раз для каждой пары ключ/значение в объекте Headers (с 0.7.10).

has()

Возвращает логическое значение, указывающее, существует ли заголовок с указанным именем.

set()

Устанавливает новое значение для существующего заголовка внутри объекта Headers, или добавляет заголовок, если он ещё не существует (с 0.7.10).

Запрос

Интерфейс Request Fetch API доступен с 0.7.10.

Новый объект Request может быть создан с помощью конструктора Request():

Request[resource[, options]])

Создаёт объект Request для получения данных, который можно передать в дальнейшем методу ngx.fetch(). resource может быть URL или существующим объектом Request. options — это необязательный аргумент, ожидающий объект со следующими ключами:

body

Тело запроса, по умолчанию пустое.

headers

Объект заголовков ответа — объект, содержащий HTTP-заголовки для предварительной подготовки объекта Headers, может быть string, массивом пар «имя-значение» или существующим объектом Headers.

method

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

Новый объект Request можно создать с помощью следующих свойств и методов:

arrayBuffer()

Возвращает Promise, который разрешается с ArrayBuffer.

bodyUsed

Логическое значение, true если тело было использовано в запросе.

cache

Содержит режим кэширования запроса.

credentials

Содержит учётные данные запроса, по умолчанию same-origin.

headers

Объект Headers для чтения, связанный с объектом Request.

json()

Возвращает Promise, который разрешается результатом парсинга тела запроса как JSON.

method

Содержит метод запроса.

mode

Содержит режим запроса.

text()

Возвращает Promise, который разрешается строковым представлением тела запроса.

url

Содержит URL запроса.

Ответ

Интерфейс Response доступен начиная с 0.5.1.

Новый объект Response можно создать, используя конструктор Response() (начиная с 0.7.10):

Response[body[, options]])

Создаёт объект Response. body — это необязательный аргумент, может быть string или buffer, по умолчанию null. options — это необязательный аргумент, ожидающий объект со следующими ключами:

headers

Объект заголовков ответа — объект, содержащий HTTP-заголовки для предварительной подготовки объекта Headers, может быть string, массивом пар «имя-значение» или существующим объектом Headers.

status

Код состояния ответа.

statusText

Сообщение состояния, соответствующее коду состояния.

Новый объект Response() можно создать с помощью следующих свойств и методов:

arrayBuffer()

Принимает поток Response и читает его до конца. Возвращает Promise, который разрешается ArrayBuffer.

bodyUsed

Логическое значение, true если тело было прочитано.

headers

Объект Headers для чтения, связанный с объектом Response.

json()

Принимает поток Response и читает его до конца. Возвращает Promise, который разрешается результатом парсинга тела как JSON.

ok

Логическое значение, true если ответ успешен (коды состояния от 200 до 299).

redirected

Логическое значение, true если ответ является результатом перенаправления.

status

Код состояния ответа.

statusText

Сообщение состояния, соответствующее коду состояния.

text()

Принимает поток Response и читает его до конца. Возвращает Promise, который разрешается строкой.

type

Тип ответа.

url

URL ответа.

ngx

Глобальный объект ngx доступен начиная с 0.5.0.

ngx.build

строка, содержащая необязательное имя сборки nginx, соответствует аргументу --build=name скрипта configure, по умолчанию "" (0.8.0)

ngx.conf_file_path

строка, содержащая путь к текущему конфигурационному файлу nginx (0.8.0)

ngx.conf_prefix

строка, содержащая путь к префиксу конфигурации nginx — каталогу, где nginx в настоящее время ищет конфигурацию (0.7.8)

ngx.error_log_path

строка, содержащая путь к текущему файлу журнала ошибок (0.8.0)

ngx.fetch(resource, [options])

Выполняет запрос для получения resource (0.5.1), который может быть URL или объектом Request (0.7.10). Возвращает Promise , который разрешается объектом Response. С версии 0.7.0 поддерживается схема https://, перенаправления не обрабатываются.

Если URL в resource указан как доменное имя, он определяется с помощью разрешителя. Если указана схема https://, для аутентификации HTTPS-сервера resource необходимо настроить директиву js_fetch_trusted_certificate.

Ожидается, что параметр options будет объектом со следующими ключами:

body

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

buffer_size

размер буфера для чтения ответа, по умолчанию 4096

headers

объект заголовков запроса

max_response_body_size

максимальный размер тела ответа в байтах, по умолчанию 32768

method

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

verify

включает или отключает проверку сертификата HTTPS-сервера, по умолчанию true (0.7.0)

Пример:

let reply = await ngx.fetch('http://nginx.org/');
let body = await reply.text();

r.return(200, body);

ngx.log(level, message)

записывает сообщение в журнал ошибок с указанным уровнем логирования. Параметр level указывает один из уровней логирования, параметр message может быть строкой или буфером. Можно указать следующие уровни логирования: ngx.INFO, ngx.WARN, и ngx.ERR.

Поскольку nginx имеет жёстко заданный максимальный лимит длины строки, в журнал может быть записано только первые 2048 байтов строки.

ngx.prefix

строка, содержащая путь к префиксу nginx — каталогу, хранящему файлы сервера (0.8.0)

ngx.version

строка, содержащая версию nginx, например: 1.25.0 (0.8.0)

ngx.version_number

число, содержащее версию nginx, например: 1025000 (0.8.0)

ngx.worker_id

число, соответствующее внутреннему идентификатору процесса nginx, значение находится в диапазоне от 0 до значения, указанного в директиве worker_processes (0.8.0)

ngx.shared

Глобальный объект ngx.shared доступен с версии 0.8.0.

SharedDict

Объект общего словаря доступен с версии 0.8.0. Имя, тип и размер общего словаря устанавливаются директивой js_shared_dict_zone в http или stream.

Объект SharedDict() имеет следующие свойства и методы:

ngx.shared.SharedDict.add(key, value [,timeout])

Устанавливает значение value для указанного key в словаре только в том случае, если ключ ещё не существует. key — это строка, представляющая ключ добавляемого элемента, value — значение добавляемого элемента.

Необязательный аргумент timeout задаётся в миллисекундах и переопределяет параметр timeout директивы js_shared_dict_zone в http или stream (начиная с 0.8.5). Это может быть полезно, когда ожидается, что у некоторых ключей будут уникальные таймауты.

Возвращает true если значение успешно добавлено в словарь SharedDict, false если ключ уже существует в словаре. Бросает исключение SharedMemoryError, если в словаре SharedDict недостаточно свободного места. Бросает исключение TypeError, если тип value отличается от ожидаемого этим словарем.

ngx.shared.SharedDict.capacity

Возвращает ёмкость словаря SharedDict, соответствует параметру size директивы js_shared_dict_zone в http или stream.

ngx.shared.SharedDict.clear()

Удаляет все элементы из словаря SharedDict.

ngx.shared.SharedDict.delete(key)

Удаляет элемент, связанный с указанным ключом, из словаря SharedDict, true если элемент в словаре существовал и был удалён, false в противном случае.

ngx.shared.SharedDict.freeSpace()

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

ngx.shared.SharedDict.get(key)

Извлекает элемент по его key, возвращает значение, связанное с key, или undefined, если его нет.

ngx.shared.SharedDict.has(key)

Ищет элемент по его key, возвращает true если такой элемент существует, или false в противном случае.

ngx.shared.SharedDict.incr(key,delta[[,init], timeout]))

Увеличивает целое значение, связанное с key, на delta. key — это строка, delta — число, на которое нужно увеличить или уменьшить значение. Если ключ не существует, элемент инициализируется необязательным аргументом init, по умолчанию 0.

Необязательный аргумент timeout задаётся в миллисекундах и переопределяет параметр timeout директивы js_shared_dict_zone в http или stream (начиная с 0.8.5). Это может быть полезно, когда ожидается, что у некоторых ключей будут уникальные таймауты.

Возвращает новое значение. Бросает исключение SharedMemoryError, если в словаре SharedDict недостаточно свободного места. Бросает исключение TypeError, если этот словарь не ожидает чисел.

Этот метод может быть использован только если тип словаря был объявлен с параметром type=number директивы js_shared_dict_zone в http или stream.

ngx.shared.SharedDict.items([maxCount])

Возвращает массив элементов словаря SharedDict (ключ-значение) (начиная с 0.8.1). Параметр maxCount устанавливает максимальное количество извлекаемых элементов, по умолчанию 1024.

ngx.shared.SharedDict.keys([maxCount])

Возвращает массив ключей словаря SharedDict. Параметр maxCount устанавливает максимальное количество извлекаемых ключей, по умолчанию 1024.

ngx.shared.SharedDict.name

Возвращает имя словаря SharedDict, соответствует параметру zone= директивы js_shared_dict_zone в http или stream.

ngx.shared.SharedDict.pop(key)

Удаляет элемент, связанный с указанным key из словаря SharedDict, возвращает значение, связанное с key, или undefined, если его нет.

ngx.shared.SharedDict.replace(key, value)

Заменяет значение value для указанного key только в том случае, если ключ уже существует, возвращает true если значение было успешно заменено, false если ключ не существует в словаре SharedDict. Бросает исключение SharedMemoryError, если в словаре SharedDict недостаточно свободного места. Бросает исключение TypeError, если тип value отличается от ожидаемого этим словарем.

ngx.shared.SharedDict.set(key, value [,timeout])

Устанавливает значение value для указанного key, возвращает этот словарь SharedDict (для цепочки методов).

Необязательный аргумент timeout задаётся в миллисекундах и переопределяет параметр timeout директивы js_shared_dict_zone в http или stream (начиная с 0.8.5). Это может быть полезно, когда ожидается, что у некоторых ключей будут уникальные таймауты.

ngx.shared.SharedDict.size()

Возвращает количество элементов для словаря SharedDict.

ngx.shared.SharedDict.type

Возвращает string или number, соответствующие типу словаря SharedDict, заданному параметром type= директивы js_shared_dict_zone в http или stream.

встроенные объекты

консоль

Объект console доступен в nginx начиная с 0.8.2, в CLI начиная с 0.2.6.

console.error(msg[, msg2 ...])

Выводит одну или несколько сообщений об ошибках. Сообщение может быть строкой или объектом.

console.info(msg[, msg2 ...])

Выводит одно или несколько информационных сообщений. Сообщение может быть строкой или объектом.

console.log(msg[, msg2 ...])

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

console.time(label)

Запускает таймер, который может отслеживать время выполнения операции. Параметр label позволяет именовать разные таймеры. Если вызвана функция console.timeEnd() с тем же именем, будет выведено время, прошедшее с момента запуска таймера, в миллисекундах.

console.timeEnd(label)

Останавливает таймер, ранее запущенный функцией console.time(). Параметр label позволяет именовать разные таймеры.

console.warn(msg[, msg2 ...])

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

криптография

Объект crypto — это глобальный объект, который позволяет использовать криптографические функции (начиная с 0.7.0).

сrypto.getRandomValues(typedArray)

Получает криптографически сильные случайные значения. Возвращает тот же массив, который был передан в качестве typedArray, но с содержанием, заменённым на новые сгенерированные случайные числа. Возможные значения:

typedArray

может быть Int8Array, Int16Array, Uint16Array, Int32Array, или Uint32Array

сrypto.subtle.encrypt(algorithm, key, data)

Шифрует data с использованием предоставленного algorithm и key. Возвращает Promise, который соответствует ArrayBuffer, содержащему зашифрованный текст. Возможные значения:

algorithm

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

• для RSA-OAEP, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в RSA-OAEP:

    crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
    

• для AES-CTR, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в AES-CTR
  • counter — ArrayBuffer, TypedArray, или DataView — начальное значение блока счётчика, должно быть 16 байтами (размер блока AES). Правые биты длины этого блока используются для счётчика, а остальная часть — для nonce. Например, если длина установлена в 64, то первая половина счётчика — nonce, а вторая — используется для счётчика
  • length — количество бит в блоке счётчика, используемых для фактического счётчика. Счётчик должен быть достаточно большим, чтобы не происходило переполнения.
• для AES-CBC, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в AES-CBC
  • iv или вектор инициализации, — ArrayBuffer, TypedArray, или DataView, должен быть 16 байтами, непредсказуемым и предпочтительно криптографически случайным. Однако он не обязательно должен быть секретным, например, он может передаваться без шифрования вместе с зашифрованным текстом.
• для AES-GCM, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в AES-GCM
  • iv или вектор инициализации, — ArrayBuffer, TypedArray, или DataView, должен быть 16 байтами и должен быть уникальным для каждой операции шифрования, выполняемой с данным ключом
  • additionalData (необязательно) — ArrayBuffer, TypedArray, или DataView содержащий дополнительные данные, которые не будут зашифрованы, но будут аутентифицированы вместе с зашифрованными данными. Если additionalData указан, то те же данные должны быть указаны в соответствующем вызове decrypt(); если данные, предоставленные в вызове decrypt(), не совпадают с исходными данными, дешифровка выбросит исключение. Длина в битах additionalData должна быть меньше 2^64 - 1.
  • tagLength (необязательно, по умолчанию 128) — number, который определяет размер в битах тега аутентификации, сгенерированного в операции шифрования и используемого для аутентификации в соответствующей операции дешифрования. Возможные значения: 32, 64, 96, 104, 112, 120, или 128. Спецификация AES-GCM рекомендует, чтобы он был 96, 104, 112, 120, или 128, хотя 32 или 64 бит могут быть приемлемыми в некоторых приложениях.

key

CryptoKey, содержащий ключ, используемый для шифрования

data

ArrayBuffer, TypedArray, или DataView содержащий данные, которые необходимо зашифровать (также известные как открытый текст)

сrypto.subtle.decrypt(algorithm, key, data)

Дешифрует зашифрованные данные. Возвращает Promise с дешифрованными данными. Возможные значения:

algorithm

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

• для RSA-OAEP, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в RSA-OAEP:

    crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
    

• для AES-CTR, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в AES-CTR
  • counter — ArrayBuffer, TypedArray, или DataView — начальное значение блока счётчика, должно быть 16 байтами (размер блока AES). Правые биты длины этого блока используются для счётчика, а остальная часть — для nonce. Например, если длина установлена в 64, то первая половина счётчика — nonce, а вторая — используется для счётчика.
  • length — количество бит в блоке счётчика, используемых для фактического счётчика. Счётчик должен быть достаточно большим, чтобы не происходило переполнения.
• для AES-CBC, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в AES-CBC
  • iv или вектор инициализации, — ArrayBuffer, TypedArray, или DataView, должен быть 16 байтами, непредсказуемым и предпочтительно криптографически случайным. Однако он не обязательно должен быть секретным (например, он может передаваться без шифрования вместе с зашифрованным текстом).
• для AES-GCM, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в AES-GCM
  • iv или вектор инициализации, — ArrayBuffer, TypedArray, или DataView, должен быть 16 байтами и должен быть уникальным для каждой операции шифрования, выполняемой с данным ключом
  • additionalData (необязательно) — ArrayBuffer, TypedArray, или DataView содержащий дополнительные данные, которые не будут зашифрованы, но будут аутентифицированы вместе с зашифрованными данными. Если additionalData указан, то те же данные должны быть указаны в соответствующем вызове decrypt(); если данные, предоставленные в вызове decrypt(), не совпадают с исходными данными, дешифровка выбросит исключение. Длина в битах additionalData должна быть меньше 2^64 - 1.
  • tagLength (необязательно, по умолчанию 128) — number, который определяет размер в битах тега аутентификации, сгенерированного в операции шифрования и используемого для аутентификации в соответствующей операции дешифрования. Возможные значения: 32, 64, 96, 104, 112, 120, или 128. Спецификация AES-GCM рекомендует, чтобы он был 96, 104, 112, 120, или 128, хотя 32 или 64 бит могут быть приемлемыми в некоторых приложениях.

key

CryptoKey, содержащий ключ, используемый для дешифрования. Если используется RSA-OAEP, это свойство privateKey объекта CryptoKeyPair.

data

ArrayBuffer, TypedArray, или DataView содержащий данные, которые необходимо дешифровать (также известные как зашифрованный текст)

сrypto.subtle.deriveBits(algorithm, baseKey, length)

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

algorithm

это объект, определяющий алгоритм вычисления:

• для HKDF, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в HKDF
  • hash — строка с алгоритмом хеширования: SHA-1, SHA-256, SHA-384, или SHA-512
  • salt — ArrayBuffer, TypedArray, или DataView, представляющий случайное или псевдослучайное значение длиной, равной выводу функции digest. В отличие от входного ключа, переданного в deriveKey(), соль не должна храниться в секрете.
  • info — ArrayBuffer, TypedArray, или DataView, представляющий контекстную информацию, специфичную для приложения, используемую для привязки полученного ключа к приложению или контексту и позволяющую получать разные ключи для разных контекстов при использовании одного и того же входного ключа. Это свойство обязательно, но может быть пустым буфером.
• для PBKDF2, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в PBKDF2
  • hash — строка с алгоритмом хеширования: SHA-1, SHA-256, SHA-384, или SHA-512
  • salt — ArrayBuffer, TypedArray, или DataView, представляющее случайное или псевдослучайное значение длиной не менее 16 байт. В отличие от входного ключа, переданного в deriveKey(), соль не должна храниться в секрете.
  • iterations — number, представляющее количество раз, которое функция хеширования будет выполнена в deriveKey()

baseKey

это CryptoKey, представляющий вход в алгоритм вычисления — исходный материал ключа для функции вычисления: например, для PBKDF2 это может быть пароль, импортированный как CryptoKey с использованием сrypto.subtle.importKey()

length

это число, представляющее количество битов для вычисления. Для совместимости с браузерами число должно быть кратным 8

сrypto.subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)

Вычисляет секретный ключ из мастер-ключа. Возможные значения:

algorithm

это объект, определяющий алгоритм вычисления:

• для HKDF, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в HKDF
  • hash — строка с алгоритмом хеширования: SHA-1, SHA-256, SHA-384, или SHA-512
  • salt — ArrayBuffer, TypedArray, или DataView, представляющий случайное или псевдослучайное значение длиной, равной выводу функции digest. В отличие от входного ключа, переданного в deriveKey(), соль не должна храниться в секрете.
  • info — ArrayBuffer, TypedArray, или DataView, представляющий контекстную информацию, специфичную для приложения, используемую для привязки полученного ключа к приложению или контексту и позволяющую получать разные ключи для разных контекстов при использовании одного и того же входного ключа. Это свойство обязательно, но может быть пустым буфером.
• для PBKDF2, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в PBKDF2
  • hash — строка с алгоритмом хеширования: SHA-1, SHA-256, SHA-384, или SHA-512
  • salt — ArrayBuffer, TypedArray, или DataView, представляющее случайное или псевдослучайное значение длиной не менее 16 байт. В отличие от входного ключа, переданного в deriveKey(), соль не должна храниться в секрете.
  • iterations — number, представляющее количество раз, которое функция хеширования будет выполнена в deriveKey()

baseKey

это CryptoKey, представляющий вход в алгоритм вычисления — исходный материал ключа для функции вычисления: например, для PBKDF2 это может быть пароль, импортированный как CryptoKey с использованием сrypto.subtle.importKey().

derivedKeyAlgorithm

это объект, определяющий алгоритм, для которого будет использоваться полученный ключ:

• для HMAC, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в HMAC
  • hash — строка с именем функции хеширования для использования: SHA-1, SHA-256, SHA-384, или SHA-512
  • length (необязательно) — number, представляющее длину ключа в битах. Если не указано, длина ключа равна размеру блока выбранной функции хеширования
• для AES-CTR, AES-CBC, или AES-GCM, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в AES-CTR, AES-CBC, или AES-GCM, в зависимости от используемого алгоритма
  • length — number, представляющее длину ключа для генерации в битах: 128, 192, или 256

extractable

это логическое значение, указывающее, будет ли возможна экспорт ключа

keyUsages

это Array, указывающее, что можно сделать с полученным ключом. Использование ключа должно быть разрешено алгоритмом, установленным в derivedKeyAlgorithm. Возможные значения:

encrypt

ключ для шифрования сообщений

decrypt

ключ для дешифрования сообщений

sign

ключ для подписи сообщений

verify

ключ для проверки подписей

deriveKey

ключ для вычисления нового ключа

deriveBits

ключ для вычисления битов

wrapKey

ключ для упаковки ключа

unwrapKey

ключ для распаковки ключа

сrypto.subtle.digest(algorithm, data)

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

algorithm

это строка, определяющая функцию хеширования для использования: SHA-1 (не для криптографических приложений), SHA-256, SHA-384, или SHA-512

data

это ArrayBuffer, TypedArray, или DataView, содержащий данные для дайджеста

сrypto.subtle.exportKey(format, key)

Экспортирует ключ: принимает ключ в виде объекта CryptoKey и возвращает ключ во внешнем, переносимом формате (с 0.7.10). Если format было jwk, то Promise заполняет объектом JSON, содержащим ключ. В противном случае обещание заполняется ArrayBuffer, содержащим ключ. Возможные значения:

format

строка, описывающая формат данных, в котором должен быть экспортирован ключ, может быть следующим:

raw

формат необработанных данных

pkcs8

формат PKCS #8

spki

формат SubjectPublicKeyInfo

jwk

формат JSON Web Key (JWK) (с 0.7.10)

key

CryptoKey, содержащий ключ для экспорта

сrypto.subtle.generateKey(algorithm, extractable, usage)

Генерирует новый ключ для симметричных алгоритмов или пару ключей для алгоритмов с открытым ключом (с версии 0.7.10). Возвращает объект Promise, содержащий сгенерированный ключ в виде объекта CryptoKey или CryptoKeyPair. Возможные значения:

algorithm

объект-словарь, определяющий тип генерируемого ключа и предоставляющий дополнительные параметры, специфичные для алгоритма:

• для RSASSA-PKCS1-v1_5, RSA-PSS, или RSA-OAEP, передайте объект со следующими ключами:
  • name — строка, которая должна быть установлена в RSASSA-PKCS1-v1_5, RSA-PSS, или RSA-OAEP, в зависимости от используемого алгоритма
  • hash — строка, представляющая имя функции digest, которая должна быть использована; может быть SHA-256, SHA-384, или SHA-512
• для ECDSA, передайте объект со следующими ключами:
  • name — строка, которая должна быть установлена в ECDSA
  • namedCurve — строка, представляющая имя эллиптической кривой для использования; может быть P-256, P-384, или P-521
• для HMAC, передайте объект со следующими ключами:
  • name — строка, которая должна быть установлена в HMAC
  • hash — строка, представляющая имя функции digest, которая должна быть использована; может быть SHA-256, SHA-384, или SHA-512
  • length (необязательно) — число, представляющее длину ключа в битах. Если опущено, длина ключа равна длине дайджеста, сгенерированного выбранной функцией дайджеста.
• для AES-CTR, AES-CBC, или AES-GCM, передайте строку, идентифицирующую алгоритм, или объект вида { "name": "ALGORITHM" }, где ALGORITHM — имя алгоритма

extractable

логическое значение, указывающее, можно ли экспортировать ключ

usage

объект, указывающий возможные действия с ключом:

encrypt

ключ для шифрования сообщений

decrypt

ключ для дешифрования сообщений

sign

ключ для подписи сообщений

verify

ключ для проверки подписей

deriveKey

ключ для вывода нового ключа

deriveBits

ключ для вывода битов

wrapKey

ключ для упаковки ключа

unwrapKey

ключ для распаковки ключа

сrypto.subtle.importKey(format, keyData, algorithm, extractable, keyUsages)

Импортирует ключ: принимает на вход ключ во внешнем, переносимом формате и возвращает объект CryptoKey. Возвращает объект Promise, содержащий импортированный ключ в виде объекта CryptoKey. Возможные значения:

format

строка, описывающая формат данных импортируемого ключа; может быть следующим:

raw

формат исходных данных

pkcs8

формат PKCS #8

spki

формат SubjectPublicKeyInfo

jwk

формат JSON Web Key (JWK) (с версии 0.7.10)

keyData

объект ArrayBuffer, TypedArray, или DataView, содержащий ключ в заданном формате

algorithm

объект-словарь, определяющий тип импортируемого ключа и предоставляющий дополнительные параметры, специфичные для алгоритма:

• для RSASSA-PKCS1-v1_5, RSA-PSS, или RSA-OAEP, передайте объект со следующими ключами:
  • name — строка, которая должна быть установлена в RSASSA-PKCS1-v1_5, RSA-PSS, или RSA-OAEP, в зависимости от используемого алгоритма
  • hash — строка, представляющая имя функции digest, которая должна быть использована; может быть SHA-1, SHA-256, SHA-384, или SHA-512
• для ECDSA, передайте объект со следующими ключами:
  • name — строка, которая должна быть установлена в ECDSA
  • namedCurve — строка, представляющая имя эллиптической кривой для использования; может быть P-256, P-384, или P-521
• для HMAC, передайте объект со следующими ключами:
  • name — строка, которая должна быть установлена в HMAC
  • hash — строка, представляющая имя функции digest, которая должна быть использована; может быть SHA-256, SHA-384, или SHA-512
  • length (необязательно) — число, представляющее длину ключа в битах. Если опущено, длина ключа равна длине дайджеста, сгенерированного выбранной функцией дайджеста.
• для AES-CTR, AES-CBC, или AES-GCM, передайте строку, идентифицирующую алгоритм, или объект вида { "name": "ALGORITHM" }, где ALGORITHM — имя алгоритма
• для PBKDF2, передайте строку PBKDF2
• для HKDF, передайте строку HKDF

extractable

логическое значение, указывающее, можно ли экспортировать ключ

keyUsages

объект, указывающий возможные действия с ключом:

encrypt

ключ для шифрования сообщений

decrypt

ключ для дешифрования сообщений

sign

ключ для подписи сообщений

verify

ключ для проверки подписей

deriveKey

ключ для вывода нового ключа

deriveBits

ключ для вывода битов

wrapKey

ключ для упаковки ключа

unwrapKey

ключ для распаковки ключа

сrypto.subtle.sign(algorithm, key, data)

Возвращает signature в виде объекта Promise, содержащего объект ArrayBuffer с подписью. Возможные значения:

algorithm

строка или объект, определяющие алгоритм подписи и его параметры:

• для RSASSA-PKCS1-v1_5, передайте строку, идентифицирующую алгоритм, или объект вида { "name": "ALGORITHM" }
• для RSA-PSS, передайте объект со следующими ключами:
  • name — строка, которая должна быть установлена в RSA-PSS
  • saltLength — целое число integer, представляющее длину случайной соли в байтах
• для ECDSA, передайте объект со следующими ключами:
  • name — строка, которая должна быть установлена в ECDSA
  • hash — идентификатор алгоритма дайджеста для использования; может быть SHA-256, SHA-384, или SHA-512
• для HMAC, передайте строку, идентифицирующую алгоритм, или объект вида { "name": "ALGORITHM" }

key

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

data

объект ArrayBuffer, TypedArray, или DataView, содержащий данные, подлежащие подписи

сrypto.subtle.verify(algorithm, key, signature, data)

Проверяет цифровую подпись, возвращает Promise, который соответствует булевому значению: true, если подпись действительна, иначе false. Возможные значения:

algorithm

это строка или объект, который определяет используемый алгоритм и его параметры:

• для RSASSA-PKCS1-v1_5, передайте строку, идентифицирующую алгоритм, или объект следующего вида { "name": "ALGORITHM" }
• для RSA-PSS, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в RSA-PSS
  • saltLength — целое число integer, представляющее длину случайной соли для использования в байтах
• для ECDSA, передайте объект со следующими ключами:
  • name — строка, должна быть установлена в ECDSA
  • hash — идентификатор алгоритма дайджеста для использования, может быть SHA-256, SHA-384, или SHA-512
• для HMAC, передайте строку, идентифицирующую алгоритм, или объект следующего вида { "name": "ALGORITHM" }

key

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

signature

это ArrayBuffer, TypedArray, или DataView, содержащий подпись для проверки

data

это ArrayBuffer, TypedArray, или DataView объект, содержащий данные, подпись которых должна быть проверена

CryptoKey

Объект CryptoKey представляет собой криптографический key, полученный одним из методов SubtleCrypto: сrypto.subtle.generateKey(), сrypto.subtle.deriveKey(), сrypto.subtle.importKey().

CryptoKey.algorithm

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

CryptoKey.extractable

булевое значение, true если ключ может быть экспортирован (с 0.8.0), только для чтения

CryptoKey.type

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

secret

Этот ключ — секретный ключ для использования с симметричным алгоритмом.

private

Этот ключ — частная часть несимметричного алгоритма CryptoKeyPair

public

Этот ключ — открытая часть несимметричного алгоритма CryptoKeyPair.

CryptoKey.usages

Массив строк, указывающий, для чего этот ключ может быть использован (с 0.8.0), только для чтения. Возможные значения массива:

encrypt

ключ для шифрования сообщений

decrypt

ключ для дешифрования сообщений

sign

ключ для подписи сообщений

verify

ключ для проверки подписей

deriveKey

ключ для вывода нового ключа

deriveBits

ключ для получения бит

CryptoKeyPair

Объект CryptoKeyPair — это объектный словарь API WebCrypto, представляющий пару несимметричных ключей.

CryptoKeyPair.privateKey

Объект CryptoKey, представляющий закрытый ключ.

CryptoKeyPair.publicKey

Объект CryptoKey, представляющий открытый ключ.

njs

Объект njs — это глобальный объект, представляющий текущую инстанцию виртуальной машины (с 0.2.0).

njs.version

Возвращает строку с текущей версией njs (например, “0.7.4”).

njs.version_number

Возвращает число с текущей версией njs. Например, “0.7.4” возвращается как 0x000704 (с 0.7.4).

njs.dump(value)

Возвращает строку представления значения в формате pretty-print.

njs.memoryStats

Объект, содержащий статистику использования памяти текущей инстанции виртуальной машины (с 0.7.8).

size

объем памяти в байтах, затребованный пулом памяти njs у операционной системы.

njs.on(event, callback)

Регистрирует обработчик для указанного события виртуальной машины (с 0.5.2). Событие может быть одной из следующих строк:

exit

вызывается перед уничтожением виртуальной машины. Обработчик вызывается без аргументов.

process

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

process.argv

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

process.env

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

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

process.pid

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

process.ppid

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

Строка

По умолчанию все строки в njs являются строками Юникод. Они соответствуют строкам ECMAScript, содержащим символы Юникод. До версии 0.8.0 поддерживались также байтовые строки.

Байтовые строки

С версии 0.8.0 поддержка байтовых строк и методов для них была удалена. При работе с последовательностями байтов следует использовать объект Buffer и свойства, такие как r.requestBuffer, r.rawVariables.

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

>> '£'.toUTF8().toString('hex')
'c2a3'  /* C2 A3 is the UTF-8 representation of 00A3 ('£') code point */

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

>> '£'.toBytes().toString('hex')
'a3'  /* a3 is a byte equal to 00A3 ('£') code point  */

String.bytesFrom(array | string, encoding)

Метод был устаревшим в 0.4.4 и был удалён в 0.8.0. Следует использовать метод Buffer.from:

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

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

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

String.prototype.fromBytes(start[, end])

свойство было устаревшим в 0.7.7 и было удалено в 0.8.0. До 0.7.7, возвращал новую строку Юникода из строки байтов, где каждый байт заменялся соответствующим кодом Юникода.

String.prototype.fromUTF8(start[, end])

свойство было устаревшим в 0.7.7 и было удалено в 0.8.0. Следует использовать метод TextDecoder. До 0.7.7, преобразовывал строку байтов, содержащую корректную строку UTF-8, в строку Юникода, в противном случае возвращалось null.

String.prototype.toBytes(start[, end])

свойство было устаревшим в 0.7.7 и было удалено в 0.8.0. До 0.7.7, сериализовывал строку Юникода в строку байтов, возвращал null если в строке был найден символ больше 255.

String.prototype.toString(encoding)

свойство было устаревшим в 0.7.7 и было удалено в 0.8.0. До 0.7.7, кодировал строку в hex, base64, или base64url:

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

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

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

String.prototype.toUTF8(start[, end])

свойство было устаревшим в 0.7.7 и было удалено в 0.8.0. Следует использовать метод TextEncoder. До 0.7.7, сериализовал строку Юникода в строку байтов с использованием кодировки UTF-8:

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

веб API

Декодер текста

TextDecoder производит поток кодовых точек из потока байтов (0.4.3).

TextDecoder([[encoding], options])

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

fatal

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

TextDecoder.prototype.encoding

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

TextDecoder.prototype.fatal

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

TextDecoder.prototype.ignoreBOM

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

TextDecoder.prototype.decode(buffer, [options])

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

stream

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

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

Кодировщик текста

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

TextEncoder()

Возвращает новый созданный TextEncoder объект, который сгенерирует поток байтов с кодировкой UTF-8.

TextEncoder.prototype.encode(string)

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

TextEncoder.prototype.encodeInto(string, uint8Array)

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

read

количество единиц кода UTF-16 из исходного string преобразованных в UTF-8

written

количество изменённых байтов в целевом Uint8Array

таймеры

clearTimeout(timeout)

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

setTimeout(function, milliseconds[, argument1, argumentN])

Вызывает function через указанное количество milliseconds. Одну или несколько необязательных arguments можно передать указанной функции. Возвращает объект timeout.

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

t = setTimeout(handler, 12);

// ...

clearTimeout(t);

глобальные функции

atob(encodedData)

Декодирует строку данных, закодированную с использованием кодировки Base64. Параметр encodedData — это двоичная строка, содержащая данные, закодированные в Base64. Возвращает строку, содержащую декодированные данные из encodedData.

Аналогичный метод btoa() может быть использован для кодирования и передачи данных, которые могут вызвать проблемы с общением, затем передать их и использовать метод atob() для декодирования данных снова. Например, вы можете закодировать, передать и декодировать управляющие символы, такие как ASCII значения 0 по 31.

const encodedData = btoa("text to encode"); // encode a string
const decodedData = atob(encodedData); // decode the string

btoa(stringToEncode)

Создаёт строку ASCII, закодированную в Base64, из двоичной строки. Параметр stringToEncode — это двоичная строка для кодирования. Возвращает строку ASCII, содержащую представление Base64 stringToEncode.

Метод может быть использован для кодирования данных, которые могут вызвать проблемы с общением, передать их, а затем использовать метод atob() для декодирования данных снова. Например, вы можете закодировать управляющие символы, такие как ASCII значения 0 по 31.

const encodedData = btoa("text to encode"); // encode a string
const decodedData = atob(encodedData); // decode the string

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

Буфер

Buffer.alloc(size[, fill[, encoding]]))

Выделяет новый буфер (Buffer) заданного size. Если fill не указан, буфер будет заполнен нулями. Если fill указан, выделенный буфер будет инициализирован вызовом buf.fill(fill). Если fill и encoding указаны, выделенный буфер будет инициализирован вызовом buf.fill(fill, encoding).

Параметр fill может быть string, Buffer, Uint8Array, или integer.

Buffer.allocUnsafe(size)

То же, что и Buffer.alloc(), с той разницей, что выделенная память для буфера не инициализируется, содержимое нового буфера неизвестно и может содержать конфиденциальные данные.

Buffer.byteLength(value[, encoding])

Возвращает длину в байтах заданного значения, закодированного с использованием encoding. Значение может быть string, Buffer, TypedArray, DataView, или ArrayBuffer. Если значение является string, параметр encoding указывает его кодировку, может быть utf8, hex, base64, base64url; по умолчанию используется utf8.

Buffer.compare(buffer1, buffer2)

Сравнивает buffer1 с buffer2 при сортировке массивов объектов Buffer. Возвращает 0, если buffer1 совпадает с buffer2, 1, если buffer2 должен предшествовать buffer1 при сортировке, или -1, если buffer2 должен следовать за buffer1 при сортировке.

Buffer.concat(list[, totalLength])

Возвращает новый буфер (Buffer), являющийся результатом конкатенации всех объектов Buffer в списке. Если список пуст или общая длина равна 0, возвращается новый буфер нулевой длины. Если totalLength не указан, он вычисляется из объектов Buffer в списке, складывая их длины. Если totalLength указан, он преобразуется в беззнаковое целое число. Если общая длина буферов в списке превышает totalLength, результат усекается до totalLength.

Buffer.from(array)

Выделяет новый буфер (Buffer) с использованием массива байтов в диапазоне 0 – 255. Элементы массива за пределами этого диапазона будут усечены.

Buffer.from(arrayBuffer, byteOffset[, length]])

Создает представление ArrayBuffer без копирования базовой памяти. Дополнительные аргументы byteOffset и length указывают диапазон памяти в arrayBuffer, который будет совместно использоваться буфером.

Buffer.from(buffer)

Копирует данные переданного буфера в новый экземпляр буфера (Buffer).

Buffer.from(object[, offsetOrEncoding[, length]])

Для объектов, чья функция valueOf() возвращает значение, не строго равное объекту, возвращает Buffer.from(object.valueOf(), offsetOrEncoding, length).

Buffer.from(string[, encoding])

Создает новый буфер (Buffer) со строкой string. Параметр encoding определяет кодировку символов, используемую при преобразовании строки в байты. Кодировка может быть utf8, hex, base64, base64url; по умолчанию используется utf8.

Buffer.isBuffer(object)

Логическое значение, возвращает true, если object является буфером (Buffer).

Buffer.isEncoding(encoding)

Логическое значение, возвращает true, если кодировка является именем поддерживаемой кодировки символов.

buffer[index]

Оператор индексации, который может использоваться для получения и установки октета в позиции index в buffer. Значения относятся к отдельным байтам, поэтому допустимый диапазон значений находится между 0 и 255 (десятичное).

buf.buffer

Базовый объект ArrayBuffer на основе которого создан этот объект Buffer.

buf.byteOffset

Целое число, указывающее byteOffset буферов, лежащих в основе объекта ArrayBuffer.

buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])

Сравнивает буфер с target и возвращает число, указывающее, предшествует ли буфер, следует ли он за или равен target в порядке сортировки. Сравнение основано на фактической последовательности байтов в каждом Buffer. targetStart — целое число, определяющее смещение в target для начала сравнения, по умолчанию 0. targetEnd — целое число, определяющее смещение в target для завершения сравнения, по умолчанию target.length. sourceStart — целое число, определяющее смещение в буфере для начала сравнения, по умолчанию 0. sourceEnd — целое число, определяющее смещение в буфере для завершения сравнения (не включая), по умолчанию buf.length.

buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]])

Копирует данные из области буфера в область в target, даже если целевая область памяти перекрывается с буфером. Параметр target — Buffer или Uint8Array для копирования.

targetStart — целое число, определяющее смещение в целевом объекте для начала записи, по умолчанию 0. sourceStart — целое число, определяющее смещение в буфере для начала копирования, по умолчанию 0. sourceEnd — целое число, определяющее смещение в буфере для остановки копирования (не включая), по умолчанию buf.length.

buf.equals(otherBuffer)

Логическое значение, возвращает true, если оба буфера (Buffer) и otherBuffer содержат точно такие же байты.

buf.fill(value[, offset[, end]][, encoding])

Заполняет буфер (Buffer) указанным value. Если offset и end не указаны, весь буфер будет заполнен. value приводится к типу uint32, если это не string, Buffer, или integer. Если полученное целое число больше 255, буфер будет заполнен value и 255.

buf.includes(value[, byteOffset][, encoding])

Эквивалентно buf.indexOf() !== -1, возвращает true, если value был найден в буфере.

buf.indexOf(value[, byteOffset][, encoding])

Возвращает целое число, являющееся индексом первого вхождения value в буфере, или -1, если буфер не содержит значение. value может быть string, со спецификацией encoding (по умолчанию utf8), Buffer, Unit8Array, или числом от 0 до 255.

buf.lastIndexOf(value[, byteOffset][, encoding])

То же, что и buf.indexOf(), за исключением того, что вместо первого вхождения ищется последнее вхождение value. value может быть строкой, буфером (Buffer) или целым числом от 1 до 255. Если value — пустая строка или пустой буфер, возвращается byteOffset.

buf.length

Возвращает количество байтов в буфере (Buffer).

buf.readIntBE(offset, byteLength)

Читает byteLength из buf в указанной offset и интерпретирует результат как большое-эндианское, дополнение до двух, знаковое значение, поддерживающее до 48 битов точности. Параметр byteLength — целое число от 1 до 6, определяющее количество байтов для чтения.

Также поддерживаются аналогичные методы: buf.readInt8([offset]), buf.readInt16BE([offset]), buf.readInt32BE([offset]).

buf.readIntLE(offset, byteLength)

Читает byteLength из buf в указанной offset и интерпретирует результат как мало-эндианское, дополнение до двух, знаковое значение, поддерживающее до 48 битов точности. Параметр byteLength — целое число от 1 до 6, определяющее количество байтов для чтения.

Также поддерживаются аналогичные методы: buf.readInt8([offset]), buf.readInt16LE([offset]), buf.readInt32LE([offset]).

buf.readUIntBE(offset, byteLength)

Читает byteLength из buf в указанной offset и интерпретирует результат как большое-эндианское целое число, поддерживающее до 48 битов точности. Параметр byteLength — целое число от 1 до 6, определяющее количество байтов для чтения.

Также поддерживаются аналогичные методы: buf.readUInt8([offset]), buf.readUInt16BE([offset]), buf.readUInt32BE([offset]).

buf.readUIntLE(offset, byteLength)

Читает byteLength из buf в указанной offset и интерпретирует результат как мало-эндианское целое число, поддерживающее до 48 битов точности. Параметр byteLength — целое число от 1 до 6, определяющее количество байтов для чтения.

Также поддерживаются аналогичные методы: buf.readUInt8([offset]), buf.readUInt16LE([offset]), buf.readUInt32LE([offset]).

buf.readDoubleBE([offset])

Читает 64-битное, большое-эндианское число с плавающей запятой из buf в указанной offset.

buf.readDoubleLE([offset])

Читает 64-битное, мало-эндианское число с плавающей запятой из buf в указанной offset.

buf.readFloatBE([offset])

Читает 32-битное, большое-эндианское число с плавающей запятой из buf в указанной offset.

buf.readFloatLE([offset])

Читает 32-битное, мало-эндианское число с плавающей запятой из buf в указанной offset.

buf.subarray([start[, end]])

Возвращает новый buf, который ссылается на ту же память, что и исходный, но смещен и обрезан с помощью start и end. Если end больше, чем buf.length, возвращается тот же результат, что и при конце, равном buf.length.

buf.slice([start[, end]])

Возвращает новый buf, который ссылается на ту же память, что и исходный, но смещен и обрезан значениями start и end. Метод не совместим с Uint8Array.prototype.slice(), который является суперклассом Buffer. Для копирования среза используйте Uint8Array.prototype.slice().

buf.swap16()

Интерпретирует buf как массив беззнаковых 16-битных чисел и меняет порядок байтов на месте. Вызывает ошибку, если buf.length не кратно 2.

buf.swap32()

Интерпретирует buf как массив беззнаковых 32-битных чисел и меняет порядок байтов на месте. Вызывает ошибку, если buf.length не кратно 4.

buf.swap64()

Интерпретирует buf как массив 64-битных чисел и меняет порядок байтов на месте. Вызывает ошибку, если buf.length не кратно 8.

buf.toJSON()

Возвращает JSON-представление buf. JSON.stringify() неявно вызывает эту функцию при строковом представлении экземпляра Buffer.

buf.toString([encoding[, start[, end]]])

Декодирует buf в строку в соответствии с указанным символом encoding, который может быть utf8, hex, base64, base64url. Параметры start и end могут быть переданы для декодирования только подмножества Buffer.

buf.write(string[, offset[, length]][, encoding])

Записывает string в buf по позиции offset в соответствии с символом encoding. Параметр length — количество байтов для записи. Если в Buffer не хватает места для размещения всей строки, будет записана только часть строки, но частично закодированные символы не будут записаны. encoding может быть utf8, hex, base64, base64url.

buf.writeIntBE(value, offset, byteLength)

Записывает byteLength байта value в buf по указанной offset как big-endian. Поддерживает точность до 48 бит. Параметр byteLength — целое число от 1 до 6, определяющее количество байтов для чтения.

Также поддерживаются следующие аналогичные методы: buf.writeInt8, buf.writeInt16BE, buf.writeInt32BE.

buf.writeIntLE(value, offset, byteLength)

Записывает byteLength байта value в buf по указанной offset как little-endian. Поддерживает точность до 48 бит. Параметр byteLength — целое число от 1 до 6, определяющее количество байтов для чтения.

Также поддерживаются следующие аналогичные методы: buf.writeInt8, buf.writeInt16LE, buf.writeInt32LE.

buf.writeUIntBE(value, offset, byteLength)

Записывает byteLength байта value в buf по указанной offset как big-endian. Поддерживает точность до 48 бит. Параметр byteLength — целое число от 1 до 6, определяющее количество байтов для чтения.

Также поддерживаются следующие аналогичные методы: buf.writeUInt8, buf.writeUInt16BE, buf.writeUInt32BE.

buf.writeUIntLE(value, offset, byteLength)

Записывает byteLength байта value в buf по указанной offset как little-endian. Поддерживает точность до 48 бит. Параметр byteLength — целое число от 1 до 6, определяющее количество байтов для чтения.

Также поддерживаются следующие аналогичные методы: buf.writeUInt8, buf.writeUInt16LE, buf.writeUInt32LE.

buf.writeDoubleBE(value, [offset])

Записывает value в buf по указанной offset как big-endian.

buf.writeDoubleLE(value, [offset])

Записывает value в buf по указанной offset как little-endian.

buf.writeFloatBE(value, [offset])

Записывает value в buf по указанной offset как big-endian.

buf.writeFloatLE(value, [offset])

Записывает value в buf по указанной offset как little-endian.

Криптография

С версии 0.7.0, расширенный API криптографии доступен как глобальный объект crypto.

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

crypto.createHash(algorithm)

Создаёт и возвращает объект Hash, который можно использовать для генерации хэш-дайджестов с использованием данного algorithm. Алгоритм может быть md5, sha1, и sha256.

crypto.createHmac(algorithm, secret key)

Создаёт и возвращает объект HMAC, использующий заданный algorithm и secret key. Алгоритм может быть md5, sha1, и sha256.

Хэш

hash.update(data)

Обновляет содержимое хэша с использованием данного data.

hash.digest([encoding])

Вычисляет дайджест всех данных, переданных с помощью hash.update(). Кодировка может быть hex, base64, и base64url. Если кодировка не указана, возвращается объект Buffer (0.4.4).

До версии (0.4.4) возвращалась строка байтов вместо объекта Buffer.

hash.copy()

Создаёт копию текущего состояния хэша (с версии 0.7.12).

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

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

HMAC

hmac.update(data)

Обновляет содержимое HMAC с использованием данного data.

hmac.digest([encoding])

Вычисляет HMAC-дайджест всех переданных данных с использованием hmac.update(). Кодировка может быть hex, base64, и base64url. Если кодировка не указана, возвращается объект Buffer (0.4.4).

До версии 0.4.4, возвращалась строка байтов вместо объекта Buffer.

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

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

Система файлов

Модуль системы файлов предоставляет операции с файлами.

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

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

accessSync(path[, mode])

Синхронно проверяет разрешения на файл или директорию, указанные в path (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(filename, data[, options])

Синхронно добавляет указанный data в конец файла с предоставленным filename. data ожидается, что это строка или объект Buffer (0.4.4). Если файла не существует, он будет создан. Параметр options ожидается, что это объект со следующими ключами:

mode

параметр режима, по умолчанию 0o666

flag

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

closeSync(fd)

Закрывает дескриптор файла fd, представленный целым числом, используемым методом. Возвращает undefined.

existsSync(path)

Булево значение, возвращает true если указанный path существует. (0.8.2)

fstatSync(fd)

Возвращает объект fs.Stats для дескриптора файла (0.7.7). Параметр fd — целое число, представляющее дескриптор файла, используемый методом.

lstatSync(path[, options])

Синхронно возвращает объект fs.Stats для символической ссылки, на которую указывает path (0.7.1). Параметр options ожидается, что это объект со следующими ключами:

throwIfNoEntry

булево значение, указывающее, будет ли выбрасываться исключение, если запись в файловой системе отсутствует, вместо возвращения undefined, по умолчанию false.

mkdirSync(path[, options])

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

mode

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

openSync(path[, flags[, mode]])

Возвращает целое число, представляющее дескриптор файла path (0.7.7).

flags

флаг файловой системы флаг, по умолчанию r

mode

параметр режима, по умолчанию 0o666

promises.open(path[, flags[, mode]])

Возвращает объект FileHandle, представляющий открытый файл path (0.7.7).

flags

флаг файловой системы флаг, по умолчанию r

mode

параметр режима, по умолчанию 0o666

readdirSync(path[, options])

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

encoding

кодировка, по умолчанию utf8. Кодировка может быть utf8 и buffer (0.4.4).

withFileTypes

если установлено значение true, массив файлов будет содержать объекты fs.Dirent, по умолчанию false.

readFileSync(filename[, options])

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

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

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

encoding

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

flag

флаг файловой системы флаг, по умолчанию 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

readSync(fd, buffer, offset[, length[, position]])

Читает содержимое пути к файлу с помощью дескриптора файла fd, возвращает количество прочитанных байтов (0.7.7).

buffer

значение buffer может быть Buffer, TypedArray, или DataView

offset

является integer , представляющим позицию в буфере для записи данных

length

является integer , представляющим количество байтов для чтения

position

определяет позицию начала чтения в файле, может быть integer или null, по умолчанию null. Если position равно null, данные будут считаны с текущей позиции файла, и позиция файла будет обновлена. Если позиция является integer, позиция файла останется неизменной

realpathSync(path[, options])

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

renameSync(oldPath, newPath)

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

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

rmdirSync(path)

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

statSync(path,[ options])

Синхронно возвращает объект fs.Stats для указанного path (0.7.1). path может быть string или buffer. Параметр options ожидается, что это объект со следующими ключами:

throwIfNoEntry

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

symlinkSync(target, path)

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

unlinkSync(path)

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

writeFileSync(filename, data[, options])

Синхронно записывает data в файл с предоставленным filename. data ожидается, что это строка или объект Buffer (0.4.4). Если файл не существует, он будет создан; если существует, он будет перезаписан. Параметр options ожидается, что это объект со следующими ключами:

mode

параметр режима, по умолчанию 0o666

flag

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

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

writeSync(fd, buffer, offset[, length[, position]])

Записывает буфер в файл с помощью дескриптора файла, возвращает количество записанных байтов (0.7.7).

fd

целое число, представляющее дескриптор файла

buffer

значение buffer может быть Buffer, TypedArray, или DataView

offset

это объект, определяющий часть буфера для записи, по умолчанию 0

length

это целое число, определяющее количество байтов для записи, по умолчанию это длина буфера Buffer.byteLength

position

указывает смещение от начала файла, где эти данные должны быть записаны, может быть integer или null, по умолчанию null. См. также pwrite(2).

writeSync(fd, string[, position[, encoding]])

Записывает string в файл, используя дескриптор файла fd, возвращает количество записанных байтов (0.7.7).

fd

это integer, представляющий дескриптор файла

position

относится к смещению от начала файла, где должна быть записана эта информация; может быть integer или null, по умолчанию равно null. См. также pwrite(2)

encoding

это string, по умолчанию равно utf8

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.

fs.FileHandle

Объект FileHandle — это объект-оболочка для числового дескриптора файла (0.7.7). Экземпляры объекта FileHandle создаются методом fs.promises.open(). Если объект FileHandle не закрыт с помощью метода filehandle.close(), он будет пытаться автоматически закрыть дескриптор файла, помогая предотвратить утечки памяти. Пожалуйста, не полагайтесь на это поведение, так как оно может быть ненадежным. Вместо этого всегда явно закрывайте объект FileHandle.

filehandle.close()

Закрывает дескриптор файла, ожидая завершения любых ожидающих операций с ним. Возвращает promise, выполняется с undefined при успехе.

filehandle.fd

Числовой дескриптор файла, управляемый объектом FileHandle.

filehandle.read(buffer, offset[, length[, position]])

Читает данные из файла и сохраняет их в заданном буфере.

buffer

буфер, который будет заполнен прочитанными данными из файла, значение может быть Buffer, TypedArray, или DataView

offset

это integer , представляющее позицию в буфере, с которой начинается заполнение

length

это integer , представляющее количество байтов для чтения

position

позиция начала чтения данных из файла, значение может быть integer, null. Если null, данные будут считаны с текущей позиции файла, и позиция будет обновлена. Если position это integer, текущая позиция файла останется неизменной.

Возвращает Promise, который выполняется при успехе с объектом, имеющим две свойства:

bytesRead

это integer , представляющее количество прочитанных байтов

buffer

ссылка на переданный аргумент в буфере, может быть Buffer, TypedArray, или DataView

filehandle.stat()

Возвращает объект fs.Stats для файла, возвращает promise.

filehandle.write(buffer, offset[, length[, position]])

Записывает буфер в файл.

buffer

значение buffer может быть Buffer, TypedArray, или DataView

offset

это integer , представляющее начальную позицию в буфере, где начинаются данные для записи

length

это integer , представляющее количество байтов из буфера для записи, по умолчанию равно смещению Buffer.byteLength

position

смещение от начала файла, куда должны быть записаны данные из буфера, может быть integer или null, по умолчанию равно null. Если position не является number, данные будут записаны в текущей позиции. Для получения подробностей смотрите документацию POSIX pwrite(2).

Возвращает Promise, который разрешается с объектом, содержащим два свойства:

bytesWritten

это integer , представляющее количество записанных байтов

buffer

ссылка на записанный буфер, может быть Buffer, TypedArray, или DataView

Небезопасно использовать filehandle.write() несколько раз для одного и того же файла без ожидания разрешения или отклонения обещания.

filehandle.write(string[, position[, encoding]])

Записывает string в файл.

position

смещение от начала файла, куда должны быть записаны данные из буфера, может быть integer или null, по умолчанию равно null. Если position не является number, данные будут записаны в текущей позиции. Для получения подробностей смотрите документацию POSIX pwrite(2).

encoding

ожидаемая кодировка строки, по умолчанию utf8

Возвращает Promise, который разрешается с объектом, содержащим два свойства:

bytesWritten

это integer , представляющее количество записанных байтов

buffer

ссылка на записанный буфер, может быть Buffer, TypedArray, или DataView

Небезопасно использовать filehandle.write() несколько раз для одного и того же файла без ожидания разрешения или отклонения обещания.

fs.Stats

Объект fs.Stats предоставляет информацию о файле. Объект возвращается из fs.statSync() и fs.lstatSync().

• stats.isBlockDevice() — возвращает true , если объект fs.Stats описывает блок-устройство.
• stats.isDirectory() — возвращает true , если объект fs.Stats описывает каталог файловой системы.
• stats.isFIFO() — возвращает true , если объект fs.Stats описывает FIFO-пайп.
• stats.isFile() — возвращает true , если объект fs.Stats описывает обычный файл.
• stats.isSocket() — возвращает true , если объект fs.Stats описывает сокет.
• stats.isSymbolicLink() — возвращает true , если объект fs.Stats описывает символическую ссылку.
• stats.dev — числовой идентификатор устройства, содержащего файл.
• stats.ino — специфичное для файловой системы число Inode для файла.
• stats.mode — битовое поле, описывающее тип и режим файла.
• stats.nlink — количество жёстких ссылок на файл.
• stats.uid — числовой идентификатор пользователя, владеющего файлом (POSIX).
• stats.gid — числовой идентификатор группы, владеющей файлом (POSIX).
• stats.rdev — числовой идентификатор устройства, если файл представляет собой устройство.
• stats.size — размер файла в байтах.
• stats.blksize — размер блока файловой системы для операций ввода/вывода.
• stats.blocks — количество выделенных блоков для этого файла.
• stats.atimeMs — метка времени последнего доступа к файлу, выраженная в миллисекундах с момента эпохи POSIX.
• stats.mtimeMs — метка времени последнего изменения файла, выраженная в миллисекундах с момента эпохи POSIX.
• stats.ctimeMs — метка времени последнего изменения файла, выраженная в миллисекундах с момента эпохи POSIX.
• stats.birthtimeMs — метка времени создания файла, выраженная в миллисекундах с момента эпохи POSIX.
• stats.atime — метка времени последнего доступа к файлу.
• stats.mtime — метка времени последнего изменения файла.
• stats.ctime — метка времени последнего изменения файла.
• stats.birthtime — метка времени создания файла.

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

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

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

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

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

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

Строка запроса

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

querystring.decode()

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

querystring.encode()

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

querystring.escape(string)

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

querystring.parse(string[, separator[, equal[, options]]])

Разбирает строку запроса URL и возвращает объект.

Параметр separator — подстрока для разграничения пар ключ-значение в строке запроса, по умолчанию это «&».

Параметр equal — подстрока для разграничения ключей и значений в строке запроса, по умолчанию это «=».

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

decodeURIComponent function

Функция для декодирования символов, закодированных в процентах в строке запроса, по умолчанию это querystring.unescape()

maxKeys number

максимальное количество ключей для разбора, по умолчанию это 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]]])

Сериализует объект и возвращает строку запроса URL.

Параметр separator — подстрока для разграничения пар ключ-значение в строке запроса, по умолчанию это «&».

Параметр equal — подстрока для разграничения ключей и значений в строке запроса, по умолчанию это «=».

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

encodeURIComponent function

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

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

Например, для следующей команды

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

строка запроса будет:

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

querystring.unescape(string)

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

XML

Модуль XML позволяет работать с XML-документами (с 0.7.10). Объект модуля XML возвращается require('xml').

Пример:

const xml = require("xml");
let data = `<note><to b="bar" a= "foo" >Tove</to><from>Jani</from></note>`;
let doc = xml.parse(data);

console.log(doc.note.to.$text) /* 'Tove' */
console.log(doc.note.to.$attr$b) /* 'bar' */
console.log(doc.note.$tags[1].$text) /* 'Jani' */

let dec = new TextDecoder();
let c14n = dec.decode(xml.exclusiveC14n(doc.note));
console.log(c14n) /* '<note><to a="foo" b="bar">Tove</to><from>Jani</from></note>' */

c14n = dec.decode(xml.exclusiveC14n(doc.note.to));
console.log(c14n) /* '<to a="foo" b="bar">Tove</to>' */

c14n = dec.decode(xml.exclusiveC14n(doc.note, doc.note.to /* excluding 'to' */));
console.log(c14n) /* '<note><from>Jani</from></note>' */

parse(string | Buffer)

Разбирает строку или буфер для XML-документа, возвращает объект-обёртку XMLDoc, представляющий проанализированный XML-документ.

c14n(root_node[, excluding_node])

Канонизирует root_node и его потомков в соответствии со спецификацией Canonical XML Version 1.1. Объект root_node может быть объектом-обёрткой XMLNode или XMLDoc вокруг XML-структуры. Возвращает буферный объект, содержащий канонизированный вывод.

excluding_node

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

exclusiveC14n(root_node[, excluding_node[, withComments [,prefix_list]]])

Канонизирует root_node и его потомков в соответствии со спецификацией Exclusive XML Canonicalization Version 1.0.

root_node

это объект-обёртка XMLNode или XMLDoc вокруг XML-структуры

excluding_node

позволяет опустить из вывода часть документа, соответствующую узлу и его потомкам

withComments

булево значение, по умолчанию false. Если true, канонизация соответствует Exclusive XML Canonicalization Version 1.0. Возвращает буферный объект, содержащий канонизированный вывод.

prefix_list

необязательная строка с именами пространств имён, разделёнными пробелами, которые также должны быть включены в вывод

serialize()

То же, что и xml.c14n() (с версии 0.7.11).

serializeToString()

То же, что и xml.c14n(), за исключением того, что результат возвращается как string (с версии 0.7.11).

XMLDoc

Объект-обёртка XMLDoc вокруг XML-структуры, корневой узел документа.

doc.$root

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

doc.abc

первый корневой тег с именем abc как объект-обёртка XMLNode

XMLNode

Объект-обёртка XMLNode вокруг узла XML-тега.

node.abc

то же, что и node.$tag$abc

node.$attr$abc

значение атрибута узла abc, доступно для записи с версии 0.7.11

node.$attr$abc=xyz

то же, что и node.setAttribute('abc', xyz) (с версии 0.7.11)

node.$attrs

объект-обёртка XMLAttr для всех атрибутов узла

node.$name

имя узла

node.$ns

пространство имён узла

node.$parent

родительский узел текущего узла

node.$tag$abc

первый дочерний тег узла с именем abc, доступен для записи с версии 0.7.11

node.$tags

массив всех дочерних тегов

node.$tags = [node1, node2, ...]

то же, что и node.removeChildren(); node.addChild(node1); node.addChild(node2) (с версии 0.7.11).

node.$tags$abc

все дочерние теги с именем abc узла, доступны для записи с версии 0.7.11

node.$text

содержимое узла, доступно для записи с версии 0.7.11

node.$text = 'abc'

то же, что и node.setText('abc') (с версии 0.7.11)

node.addChild(nd)

добавляет XMLNode в качестве дочернего узла к узлу (с версии 0.7.11). nd копируется рекурсивно перед добавлением в узел

node.removeAllAttributes()

удаляет все атрибуты узла (с версии 0.7.11)

node.removeAttribute(attr_name)

удаляет атрибут с именем attr_name (с версии 0.7.11)

node.removeChildren(tag_name)

удаляет все дочерние теги с именем tag_name (с версии 0.7.11). Если tag_name отсутствует, удаляются все дочерние теги

node.removeText()

удаляет текстовое значение узла (0.7.11)

node.setAttribute(attr_name, value)

задаёт значение для атрибута attr_name (с версии 0.7.11). Если значение null, атрибут с именем attr_name удаляется

node.setText(value)

устанавливает текстовое значение для узла (с версии 0.7.11). Если значение null, текст узла удаляется.

XMLAttr

Объект-обёртка XMLAttrs вокруг атрибутов XML-узла.

attr.abc

значение атрибута abc

zlib

Модуль zlib предоставляет функциональность сжатия, использующую алгоритмы «deflate» и «inflate» (с версии 0.7.12). Объект модуля zlib возвращается require('zlib').

deflateRawSync(string | Buffer[, options])

Сжимает данные с помощью алгоритма «deflate», предоставленные как строка или буфер, и не добавляет заголовок zlib. Значение буфера может быть Buffer, TypedArray, или DataView. Options - это необязательный объект, содержащий zlib_options. Возвращает экземпляр Buffer, содержащий сжатые данные.

deflateSync(string | Buffer[, options])

Сжимает данные с помощью алгоритма «deflate», предоставленные как строка или буфер. Значение буфера может быть Buffer, TypedArray, или DataView. Options - это необязательный объект, содержащий zlib_options. Возвращает экземпляр Buffer, содержащий сжатые данные.

inflateRawSync(string | Buffer)

Распаковывает поток с помощью алгоритма «deflate». Возвращает экземпляр Buffer, содержащий распакованные данные.

inflateSync(string | Buffer)

Распаковывает поток с помощью алгоритма «deflate». Возвращает экземпляр Buffer, содержащий распакованные данные.

zlib options

• chunkSize — целое число, по умолчанию 1024
• dictionary — Buffer, TypedArray, или DataView. По умолчанию пустая
• level — целое число, только для сжатия, см. zlib_compression_levels
• memLevel — целое число от 1 до 9, только для сжатия
• strategy — целое число, только для сжатия, см. zlib_compression_strategy
• windowBits — целое число, от -15 до -9 для сырых данных, от 9 до 15 для обычного потока

zlib уровни сжатия

zlib стратегия сжатия