# Справочник API NJS Модуль [NJS](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) предоставляет объекты, методы и свойства для расширения функциональности Angie. Данный справочник содержит только специфичные для NJS свойства, методы и модули, не соответствующие ECMAScript. Определения свойств и методов NJS, соответствующих ECMAScript, можно найти в [спецификации ECMAScript](http://www.ecma-international.org/ecma-262/). ## Объекты Angie ### HTTP-запрос - `r.args{}` - `r.done()` - `r.error()` - `r.finish()` - `r.headersIn{}` - `r.headersOut{}` - `r.httpVersion` - `r.internal` - `r.internalRedirect()` - `r.log()` - `r.method` - `r.parent` - `r.remoteAddress` - `r.requestBody` - `r.requestBuffer` - `r.requestText` - `r.rawHeadersIn[]` - `r.rawHeadersOut[]` - `r.responseBody` - `r.responseBuffer` - `r.responseText` - `r.return()` - `r.send()` - `r.sendBuffer()` - `r.sendHeader()` - `r.setReturnValue()` - `r.status` - `r.subrequest()` - `r.uri` - `r.rawVariables{}` - `r.variables{}` - `r.warn()` Объект HTTP-запроса доступен только в модуле [HTTP JS](https://angie.software//angie/docs/installation/external-modules/http_js.md#http-js). До версии 0.8.5 все строковые свойства объекта были байтовыми строками. `r.args{}` > Объект аргументов запроса, только для чтения. > Строка запроса возвращается в виде объекта. Начиная с версии 0.7.6 дублирующиеся ключи возвращаются в виде массива, ключи чувствительны к регистру, как ключи, так и значения декодируются из процентной кодировки. > Например, строка запроса > ```text > a=1&b=%32&A=3&b=4&B=two%20words > ``` > преобразуется в `r.args` следующим образом: > ```javascript > {a: "1", b: ["2", "4"], A: "3", B: "two words"} > ``` > Более сложные сценарии разбора можно реализовать с помощью модуля [Query String](#njs-querystring) и переменной `$args`, например: > ```javascript > import qs from 'querystring'; > function args(r) { > return qs.parse(r.variables.args); > } > ``` > Объект аргументов вычисляется при первом обращении к `r.args`. Если требуется только один аргумент, например `foo`, можно использовать переменные Angie: > ```javascript > r.variables.arg_foo > ``` > В этом случае объект переменных Angie возвращает первое значение для заданного ключа, без учета регистра и без декодирования процентной кодировки. > Для преобразования `r.args` обратно в строку можно использовать метод `stringify` модуля Query String. `r.done()` : После вызова этой функции следующие фрагменты данных будут передаваться клиенту без вызова `js_body_filter` (0.5.2). Может вызываться только из функции `js_body_filter`. `r.error(string)` : Записывает `string` в журнал ошибок на уровне логирования `error`.
#### NOTE Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 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) могут быть установлены с помощью синтаксиса:
```javascript r.headersOut['Foo'] = ['a', 'b'] ```
где результат будет:
```text 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` для внутренних location. `r.internalRedirect(uri)` : Выполняет внутреннее перенаправление на указанный `uri`. Если URI начинается с префикса `@`, он считается именованным location. В новом location вся обработка запроса повторяется, начиная с фазы `NGX_HTTP_SERVER_REWRITE_PHASE` для обычных location и с `NGX_HTTP_REWRITE_PHASE` для именованных location. В результате перенаправление на именованный location не проверяет ограничение `client_max_body_size`. Перенаправленные запросы становятся внутренними и могут обращаться к внутренним location. Фактическое перенаправление происходит после завершения выполнения обработчика.
#### NOTE После перенаправления в целевом location запускается новая виртуальная машина NJS, а виртуальная машина в исходном location останавливается. Значения переменных Angie сохраняются и могут использоваться для передачи информации в целевой location. Начиная с версии 0.5.3 может использоваться переменная, объявленная с помощью директивы `js_var` для HTTP или Stream.
#### NOTE Начиная с версии 0.7.4 метод принимает экранированные URI. `r.log(string)` : Записывает `string` в журнал ошибок на уровне логирования `info`.
#### NOTE Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 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).
Например, при следующих заголовках запроса:
```text Host: localhost Foo: bar foo: bar2 ```
вывод `r.rawHeadersIn` будет:
```javascript [ ['Host', 'localhost'], ['Foo', 'bar'], ['foo', 'bar2'] ] ```
Все заголовки `foo` можно собрать с помощью синтаксиса:
```javascript r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1]) ```
результат будет:
```javascript ['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` клиенту. Ответ может быть строкой или буфером Buffer (0.5.0).
В качестве второго аргумента можно указать либо URL перенаправления (для кодов 301, 302, 303, 307 и 308), либо текст тела ответа (для других кодов). `r.send(string | Buffer)` : Отправляет часть тела ответа клиенту. Отправляемые данные могут быть строкой или буфером Buffer (0.5.0). `r.sendBuffer(data[, options])` : Добавляет данные в цепочку фрагментов данных, которые будут переданы следующему фильтру тела (0.5.2). Фактическая передача происходит позже, когда все фрагменты данных текущей цепочки обработаны.
Данные могут быть строкой или буфером Buffer. `options` — это объект, используемый для переопределения флагов буфера Angie, полученных из буфера входящего фрагмента данных. Флаги могут быть переопределены следующими флагами:
`last` : Логическое значение, `true`, если буфер является последним буфером.
`flush` : Логическое значение, `true`, если буфер должен иметь флаг `flush`.
Метод может вызываться только из функции `js_body_filter`. `r.sendHeader()` : Отправляет HTTP-заголовки клиенту. `r.setReturnValue(value)` : Устанавливает возвращаемое значение обработчика `js_set` (0.7.0). В отличие от обычного оператора return, этот метод следует использовать, когда обработчик является асинхронной функцией JS. Например:
```javascript 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`.
Подзапрос разделяет свои входящие заголовки с клиентским запросом. Для отправки заголовков, отличных от исходных, прокси-серверу можно использовать директиву `proxy_set_header`. Для отправки совершенно нового набора заголовков прокси-серверу можно использовать директиву `proxy_pass_request_headers`.
Если `options` является строкой, она содержит строку аргументов подзапроса. В противном случае ожидается, что `options` будет объектом со следующими ключами:
`args` : Строка аргументов, по умолчанию используется пустая строка.
`body` : Тело запроса, по умолчанию используется тело запроса родительского объекта запроса.
`method` : HTTP-метод, по умолчанию используется метод `GET`.
`detached` : Логический флаг (0.3.9); если `true`, созданный подзапрос является отдельным подзапросом. Ответы на отдельные подзапросы игнорируются. В отличие от обычных подзапросов, отдельный подзапрос может быть создан внутри обработчика переменной. Флаг `detached` и аргумент callback взаимоисключающи.
Обратный вызов завершения `callback` получает объект ответа подзапроса с методами и свойствами, идентичными родительскому объекту запроса.
Начиная с версии 0.3.8, если `callback` не предоставлен, возвращается объект `Promise`, который разрешается в объект ответа подзапроса.
Например, для просмотра всех заголовков ответа в подзапросе:
```javascript 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{}` : Переменные Angie в виде буферов, для записи (начиная с версии 0.5.0). `r.variables{}` : Объект переменных Angie, для записи (начиная с версии 0.2.8).
Например, для получения переменной `$foo` можно использовать один из следующих синтаксисов:
```javascript r.variables['foo'] r.variables.foo ```
Начиная с версии 0.8.6 к захватам регулярных выражений можно обращаться с помощью следующего синтаксиса:
```javascript r.variables['1'] r.variables[1] ```
Angie обрабатывает переменные, на которые есть ссылки в `angie.conf`, и переменные, на которые нет ссылок, по-разному. Когда на переменную есть ссылка, она может кэшироваться, но когда на нее нет ссылки, она всегда не кэшируется. Например, когда к переменной `$request_id` обращаются только из NJS, она имеет новое значение каждый раз при вычислении. Но когда на `$request_id` есть ссылка, например:
```nginx proxy_set_header X-Request-Id $request_id; ```
`r.variables.request_id` возвращает одно и то же значение каждый раз.
Переменная доступна для записи, если:
- она была создана с помощью директивы `js_var` для HTTP или Stream (начиная с версии 0.5.3) - на нее есть ссылка в файле конфигурации Angie
Тем не менее, некоторым встроенным переменным все еще нельзя присвоить значение (например, `$http_`). `r.warn(string)` : Записывает `string` в журнал ошибок на уровне логирования `warning`.
#### NOTE Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки. ### Stream-сессия - `s.allow()` - `s.decline()` - `s.deny()` - `s.done()` - `s.error()` - `s.log()` - `s.off()` - `s.on()` - `s.remoteAddress` - `s.rawVariables{}` - `s.send()` - `s.sendDownstream()` - `s.sendUpstream()` - `s.status` - `s.setReturnValue()` - `s.variables{}` - `s.warn()` Объект stream-сессии доступен только в модуле [Stream JS](https://angie.software//angie/docs/installation/external-modules/stream_js.md#stream-js). До версии 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`.
#### NOTE Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки. `s.log(string)` : Записывает отправленную `string` в журнал ошибок на уровне логирования `info`.
#### NOTE Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки. `s.off(eventName)` : Отменяет регистрацию обратного вызова, установленного методом `s.on()` (0.2.4). `s.on(event, callback)` : Регистрирует `callback` для указанного `event` (0.2.4).
`event` может быть одной из следующих строк:
`upload` : Новые данные (строка) от клиента.
`download` : Новые данные (строка) клиенту.
`upstream` : Новые данные (буфер) от клиента (начиная с версии 0.5.0).
`downstream` : Новые данные (буфер) клиенту (начиная с версии 0.5.0).
Обратный вызов завершения имеет следующий прототип: `callback(data, flags)`, где `data` — строка или буфер Buffer (в зависимости от типа события); `flags` — объект со следующими свойствами:
`last` : Логическое значение, `true`, если data является последним буфером. `s.remoteAddress` : Адрес клиента, только для чтения. `s.rawVariables` : Переменные Angie в виде буферов, для записи (начиная с версии 0.5.0). `s.send(data[, options])` : Добавляет данные в цепочку фрагментов данных, которые будут переданы в прямом направлении: в обратном вызове download клиенту; в upload восходящему серверу (0.2.4). Фактическая передача происходит позже, когда все фрагменты данных текущей цепочки обработаны.
Данные могут быть строкой или буфером Buffer (0.5.0). `options` — это объект, используемый для переопределения флагов буфера Angie, полученных из буфера входящего фрагмента данных. Флаги могут быть переопределены следующими флагами:
`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. Например:
```javascript async function js_set(r) { const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host); r.setReturnValue(digest); } ``` `s.variables{}` : Объект переменных Angie, для записи (начиная с версии 0.2.8). Переменная может быть доступна для записи только в том случае, если на нее есть ссылка в файле конфигурации Angie. Тем не менее, некоторым встроенным переменным все еще нельзя присвоить значение. `s.warn(string)` : Записывает отправленную `string` в журнал ошибок на уровне логирования `warning`.
#### NOTE Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки. ### Периодическая сессия - `PeriodicSession.rawVariables{}` - `PeriodicSession.variables{}` Объект `Periodic Session` предоставляется в качестве первого аргумента обработчика `js_periodic` для HTTP и Stream (начиная с версии 0.8.1). `PeriodicSession.rawVariables{}` : Переменные Angie в виде буферов, для записи. `PeriodicSession.variables{}` : Объект переменных Angie, для записи. ### Заголовки - `Headers()` - `Headers.append()` - `Headers.delete()` - `Headers.get()` - `Headers.getAll()` - `Headers.forEach()` - `Headers.has()` - `Headers.set()` Интерфейс `Headers` из API Fetch доступен начиная с версии 0.5.1. Новый объект `Headers` можно создать с помощью конструктора `Headers()` (начиная с версии 0.7.10): `Headers([init])` : `init` : Объект, содержащий HTTP-заголовки для предварительного заполнения объекта `Headers`, может быть строкой, массивом пар имя-значение или существующим объектом `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()` - `Request.arrayBuffer()` - `Request.bodyUsed` - `Request.cache` - `Request.credentials` - `Request.headers` - `Request.json()` - `Request.method` - `Request.mode` - `Request.text()` - `Request.url` Интерфейс `Request` из API Fetch доступен начиная с версии 0.7.10. Новый объект `Request` можно создать с помощью конструктора `Request()`: `Request[resource[, options]])` : Создает объект `Request` для получения данных, который может быть позже передан в `ngx.fetch()`. Аргумент `resource` может быть URL-адресом или существующим объектом `Request`. Аргумент `options` является опциональным и ожидается быть объектом со следующими ключами:
`body` : Тело запроса, по умолчанию пусто.
`headers` : Объект заголовков ответа — объект, содержащий HTTP-заголовки для предварительного заполнения объекта `Headers`, может быть строкой, массивом пар имя-значение или существующим объектом `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()` - `Response.arrayBuffer()` - `Response.bodyUsed` - `Response.headers` - `Response.json()` - `Response.ok` - `Response.redirected` - `Response.status` - `Response.statusText` - `Response.text()` - `Response.type` - `Response.url` Интерфейс `Response` доступен начиная с версии 0.5.1. Новый объект `Response` можно создать с помощью конструктора `Response()` (начиная с версии 0.7.10): `Response[body[, options]])` : Создает объект `Response`. Аргумент `body` является опциональным, может быть строкой или буфером, по умолчанию `null`. Аргумент `options` является опциональным и ожидается быть объектом со следующими ключами:
`headers` : Объект заголовков ответа — объект, содержащий HTTP-заголовки для предварительного заполнения объекта `Headers`, может быть строкой, массивом пар имя-значение или существующим объектом `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.build` - `ngx.conf_file_path` - `ngx.conf_prefix` - `ngx.error_log_path` - `ngx.fetch()` - `ngx.log()` - `ngx.prefix` - `ngx.version` - `ngx.version_number` - `ngx.worker_id` Глобальный объект `ngx` доступен начиная с версии 0.5.0. `ngx.build` : Строка, содержащая опциональное имя сборки Angie, соответствует аргументу `--build=name` скрипта configure, по умолчанию `""` (0.8.0). `ngx.conf_file_path` : Строка, содержащая путь к файлу текущей конфигурации Angie (0.8.0). `ngx.conf_prefix` : Строка, содержащая путь к префиксу конфигурации Angie — каталог, в котором Angie ищет конфигурацию (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://`, директива `js_fetch_trusted_certificate` должна быть настроена для аутентификации HTTPS-сервера `resource`.
Параметр `options` ожидается быть объектом со следующими ключами:
`body` : Тело запроса, по умолчанию пусто.
`buffer_size` : Размер буфера для чтения ответа, по умолчанию `4096`.
`headers` : Объект заголовков запроса.
`max_response_body_size` : Максимальный размер тела ответа в байтах, по умолчанию `32768`.
`method` : HTTP-метод, по умолчанию используется метод `GET`.
`verify` : Включает или отключает проверку сертификата HTTPS-сервера, по умолчанию `true` (0.7.0).
Пример:
```javascript let reply = await ngx.fetch('http://example.com/'); let body = await reply.text();
r.return(200, body); ``` `ngx.log(level, message)` : Записывает сообщение в журнал ошибок с указанным уровнем логирования. Параметр `level` задает один из уровней логирования; параметр `message` может быть строкой или буфером. Можно задать следующие уровни логирования: `ngx.INFO`, `ngx.WARN` и `ngx.ERR`.
#### NOTE Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки. `ngx.prefix` : Строка, содержащая путь к префиксу Angie — каталогу, который содержит файлы сервера (0.8.0). `ngx.version` : Строка, содержащая версию Angie, например: `1.25.0` (0.8.0). `ngx.version_number` : Число, содержащее номер версии Angie, например: `1025000` (0.8.0). `ngx.worker_id` : Число, соответствующее внутреннему идентификатору рабочего процесса Angie, значение между `0` и значением, указанным в директиве `worker_processes` (0.8.0). ### ngx.shared Глобальный объект `ngx.shared` доступен начиная с версии 0.8.0. #### SharedDict - `ngx.shared.SharedDict.add()` - `ngx.shared.SharedDict.capacity` - `ngx.shared.SharedDict.clear()` - `ngx.shared.SharedDict.delete()` - `ngx.shared.SharedDict.freeSpace()` - `ngx.shared.SharedDict.get()` - `ngx.shared.SharedDict.has()` - `ngx.shared.SharedDict.incr()` - `ngx.shared.SharedDict.items()` - `ngx.shared.SharedDict.keys()` - `ngx.shared.SharedDict.name` - `ngx.shared.SharedDict.pop()` - `ngx.shared.SharedDict.replace()` - `ngx.shared.SharedDict.set()` - `ngx.shared.SharedDict.size()` - `ngx.shared.SharedDict.type` Объект общей памяти доступен начиная с версии 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`, если этот словарь не ожидает чисел.
#### NOTE Этот метод можно использовать только если тип словаря был объявлен с параметром `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 - `console.error()` - `console.info()` - `console.log()` - `console.time()` - `console.timeEnd()` - `console.warn()` Объект `console` доступен в Angie начиная с версии 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 - `crypto.getRandomValues()` - `crypto.subtle.encrypt()` - `crypto.subtle.decrypt()` - `crypto.subtle.deriveBits()` - `crypto.subtle.deriveKey()` - `crypto.subtle.digest()` - `crypto.subtle.exportKey()` - `crypto.subtle.generateKey()` - `crypto.subtle.importKey()` - `crypto.subtle.sign()` - `crypto.subtle.verify()` Объект `crypto` — это глобальный объект, который позволяет использовать криптографические функции (начиная с версии 0.7.0). `crypto.getRandomValues(typedArray)` : Получает криптографически надежные случайные значения. Возвращает тот же массив, переданный как `typedArray`, но с его содержимым, замененным на новые сгенерированные случайные числа. Возможные значения:
`typedArray` : Может быть `Int8Array`, `Int16Array`, `Uint16Array`, `Int32Array` или `Uint32Array`. `crypto.subtle.encrypt(algorithm, key, data)` : Шифрует `data` с использованием предоставленного `algorithm` и `key`. Возвращает `Promise`, который выполняется `ArrayBuffer`, содержащим зашифрованный текст. Возможные значения:
`algorithm` : Объект, который определяет используемый алгоритм и любые дополнительные параметры, если требуется:
- Для `RSA-OAEP` передайте объект со следующими ключами:
`name` : Строка, должна быть установлена на `RSA-OAEP`: ```javascript crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data) ``` - Для `AES-CTR` передайте объект со следующими ключами:
`name` : Строка, должна быть установлена на `AES-CTR`.
`counter` : `ArrayBuffer`, `TypedArray` или `DataView` — начальное значение блока счетчика, должно быть длиной 16 байт (размер блока AES). Крайние биты длины этого блока используются для счетчика, остальные используются для nonce. Например, если length установлена на 64, то первая половина counter — это 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`, которая содержит данные для шифрования (также известные как открытый текст). `crypto.subtle.decrypt(algorithm, key, data)` : Расшифровывает зашифрованные данные. Возвращает `Promise` с расшифрованными данными. Возможные значения:
`algorithm` : Объект, который определяет используемый алгоритм и любые дополнительные параметры, если требуется. Значения, указанные для дополнительных параметров, должны совпадать со значениями, переданными в соответствующий вызов `encrypt()`.
- Для `RSA-OAEP` передайте объект со следующими ключами:
`name` : Строка, должна быть установлена на `RSA-OAEP`: ```javascript crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data) ``` - Для `AES-CTR` передайте объект со следующими ключами:
`name` : Строка, должна быть установлена на `AES-CTR`.
`counter` : `ArrayBuffer`, `TypedArray` или `DataView` — начальное значение блока счетчика, должно быть длиной 16 байт (размер блока AES). Крайние биты длины этого блока используются для счетчика, остальные используются для nonce. Например, если length установлена на 64, то первая половина counter — это 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`, которая содержит данные для расшифровки (также известные как зашифрованный текст). `crypto.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()`. - Для `ECDH` передайте объект со следующими ключами (начиная с версии 0.9.1):
`name` : Строка, должна быть установлена на `ECDH`.
`public` : `CryptoKey`, который представляет открытый ключ другой стороны. Ключ должен быть сгенерирован с использованием той же кривой, что и базовый ключ.
`baseKey` : `CryptoKey`, который представляет входные данные для алгоритма производства — исходный материал ключа для функции производства: например, для `PBKDF2` это может быть пароль, импортированный как `CryptoKey` с использованием `crypto.subtle.importKey()`.
`length` : Число, представляющее количество битов, которые нужно производить. Для совместимости с браузером число должно быть кратно `8`. `crypto.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()`. - Для `ECDH` передайте объект со следующими ключами (начиная с версии 0.9.1):
`name` : Строка, должна быть установлена на `ECDH`.
`publicKey` : `CryptoKey`, который представляет открытый ключ другой стороны. Ключ должен быть сгенерирован с использованием той же кривой, что и базовый ключ.
`baseKey` : `CryptoKey`, который представляет входные данные для алгоритма производства — исходный материал ключа для функции производства: например, для `PBKDF2` это может быть пароль, импортированный как `CryptoKey` с использованием `crypto.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` : Ключ для разворачивания ключа. `crypto.subtle.digest(algorithm, data)` : Генерирует дайджест указанных данных. Принимает как аргументы идентификатор алгоритма дайджеста для использования и данные для дайджеста. Возвращает `Promise`, который будет выполнен дайджестом. Возможные значения:
`algorithm` : Строка, которая определяет функцию хеша для использования: `SHA-1` (не для криптографических приложений), `SHA-256`, `SHA-384` или `SHA-512`.
`data` : `ArrayBuffer`, `TypedArray` или `DataView`, которая содержит данные для дайджеста. `crypto.subtle.exportKey(format, key)` : Экспортирует ключ: принимает ключ как объект `CryptoKey` и возвращает ключ во внешнем, переносимом формате (начиная с версии 0.7.10). Если `format` был `jwk`, то `Promise` выполняется объектом JSON, содержащим ключ. В противном случае обещание выполняется `ArrayBuffer`, содержащим ключ. Возможные значения:
`format` : Строка, которая описывает формат данных, в котором должен быть экспортирован ключ, может быть следующей:
`raw` : Формат данных raw.
`pkcs8` : Формат [PKCS #8](https://datatracker.ietf.org/doc/html/rfc5208).
`spki` : Формат [SubjectPublicKeyInfo](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1).
`jwk` : Формат [JSON Web Key](https://datatracker.ietf.org/doc/html/rfc7517) (JWK) (начиная с версии 0.7.10).
`key` : `CryptoKey`, которая содержит ключ, который должен быть экспортирован. `crypto.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` — это имя алгоритма. - Для `ECDH` передайте объект со следующими ключами (начиная с версии 0.9.1):
`name` : Строка, должна быть установлена на `ECDH`.
`namedCurve` : Строка, которая представляет имя эллиптической кривой для использования, может быть `P-256`, `P-384` или `P-521`.
`extractable` : Логическое значение, которое указывает, возможен ли экспорт ключа.
`usage` : `array`, который указывает возможные действия с ключом:
`encrypt` : Ключ для шифрования сообщений.
`decrypt` : Ключ для расшифровки сообщений.
`sign` : Ключ для подписания сообщений.
`verify` : Ключ для проверки подписей.
`deriveKey` : Ключ для производства нового ключа.
`deriveBits` : Ключ для производства битов.
`wrapKey` : Ключ для обертывания ключа.
`unwrapKey` : Ключ для разворачивания ключа. `crypto.subtle.importKey(format, keyData, algorithm, extractable, keyUsages)` : Импортирует ключ: принимает ключ во внешнем, переносимом формате и дает объект `CryptoKey`. Возвращает `Promise`, который выполняется импортированным ключом как объект `CryptoKey`. Возможные значения:
`format` : Строка, которая описывает формат данных ключа для импорта, может быть следующей:
`raw` : Формат данных raw.
`pkcs8` : Формат [PKCS #8](https://datatracker.ietf.org/doc/html/rfc5208).
`spki` : Формат [SubjectPublicKeyInfo](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1).
`jwk` : Формат [JSON Web Key](https://datatracker.ietf.org/doc/html/rfc7517) (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`. - Для `ECDH` передайте объект со следующими ключами (начиная с версии 0.9.1):
`name` : Строка, должна быть установлена на `ECDH`.
`namedCurve` : Строка, которая представляет имя эллиптической кривой для использования, может быть `P-256`, `P-384` или `P-521`.
`extractable` : Логическое значение, которое указывает, возможен ли экспорт ключа.
`keyUsages` : `array`, который указывает возможные действия с ключом:
`encrypt` : Ключ для шифрования сообщений.
`decrypt` : Ключ для расшифровки сообщений.
`sign` : Ключ для подписания сообщений.
`verify` : Ключ для проверки подписей.
`deriveKey` : Ключ для производства нового ключа.
`deriveBits` : Ключ для производства битов.
`wrapKey` : Ключ для обертывания ключа.
`unwrapKey` : Ключ для разворачивания ключа. `crypto.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`, который содержит данные для подписания. `crypto.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.algorithm` - `CryptoKey.extractable` - `CryptoKey.type` - `CryptoKey.usages` Объект `CryptoKey` представляет криптографический `key`, полученный из одного из методов `SubtleCrypto`: `crypto.subtle.generateKey()`, `crypto.subtle.deriveKey()`, `crypto.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.privateKey` - `CryptoKeyPair.publicKey` `CryptoKeyPair` — это объект словаря WebCrypto API, который представляет асимметричную пару ключей. `CryptoKeyPair.privateKey` : Объект `CryptoKey`, который представляет закрытый ключ. `CryptoKeyPair.publicKey` : Объект `CryptoKey`, который представляет открытый ключ. ### njs - `njs.version` - `njs.version_number` - `njs.dump()` - `njs.memoryStats` - `njs.on()` Объект `njs` — это глобальный объект, представляющий текущий экземпляр VM (с версии 0.2.0). `njs.version` : Возвращает строку с текущей версией NJS (например, "0.7.4"). `njs.version_number` : Возвращает число с текущей версией NJS. Например, "0.7.4" возвращается как `0x000704` (с версии 0.7.4). `njs.dump(value)` : Возвращает красиво отформатированное строковое представление значения. `njs.memoryStats` : Объект, содержащий статистику использования памяти для текущего экземпляра VM (с версии 0.7.8).
`size` : Объем памяти в байтах, занятый пулом памяти NJS от операционной системы. `njs.on(event, callback)` : Регистрирует обработчик для указанного события VM (с версии 0.5.2). Событие может быть одной из следующих строк:
`exit` : Вызывается перед уничтожением VM. Обработчик вызывается без аргументов. ### process - `process.argv` - `process.env` - `process.kill()` - `process.pid` - `process.ppid` Объект `process` — это глобальный объект, предоставляющий информацию о текущем процессе (0.3.3). `process.argv` : Возвращает массив, содержащий аргументы командной строки, переданные при запуске текущего процесса. `process.env` : Возвращает объект, содержащий переменные окружения пользователя.
#### NOTE По умолчанию Angie удаляет все переменные окружения, унаследованные от родительского процесса, за исключением переменной TZ. Используйте директиву `env` для сохранения некоторых унаследованных переменных. `process.kill(pid, number | string)` : Отправляет сигнал процессу, идентифицируемому `pid`. Имена сигналов — это числа или строки, такие как `SIGINT` или `SIGHUP`. Дополнительную информацию см. в [kill(2)](https://man7.org/linux/man-pages/man2/kill.2.html). `process.pid` : Возвращает PID текущего процесса. `process.ppid` : Возвращает PID родительского процесса текущего процесса. ### String По умолчанию все строки в NJS — это Unicode-строки. Они соответствуют строкам ECMAScript, содержащим символы Unicode. До версии 0.8.0 также поддерживались байтовые строки. #### Byte Strings (Removed) #### NOTE Начиная с версии 0.8.0, поддержка байтовых строк и методов байтовых строк была удалена. При работе с последовательностями байтов следует использовать объект [Buffer](#njs-buffer) и свойства Buffer, такие как `r.requestBuffer`, `r.rawVariables`. Байтовые строки содержали последовательность байтов и использовались для сериализации Unicode строк во внешние данные и десериализации из внешних источников. Например, метод `toUTF8()` сериализовал Unicode строку в байтовую строку с использованием кодировки UTF-8. Метод `toBytes()` сериализовал Unicode строку с кодовыми точками до 255 в байтовую строку; в противном случае возвращалось `null`. Следующие методы были объявлены устаревшими и удалены в версии 0.8.0: - `String.bytesFrom()` (удалено в 0.8.0, используйте `Buffer.from()`) - `String.prototype.fromBytes()` (удалено в 0.8.0) - `String.prototype.fromUTF8()` (удалено в 0.8.0, используйте `TextDecoder`) - `String.prototype.toBytes()` (удалено в 0.8.0) - `String.prototype.toString()` с кодировкой (удалено в 0.8.0) - `String.prototype.toUTF8()` (удалено в 0.8.0, используйте `TextEncoder`) ## Web API ### TextDecoder - `TextDecoder()` - `TextDecoder.prototype.encoding` - `TextDecoder.prototype.fatal` - `TextDecoder.prototype.ignoreBOM` - `TextDecoder.prototype.decode()` `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`.
Пример:
```none >> (new TextDecoder()).decode(new Uint8Array([206,177,206,178])) \alpha\beta ``` ### TextEncoder - `TextEncoder()` - `TextEncoder.prototype.encode()` - `TextEncoder.prototype.encodeInto()` Объект `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()` - `setTimeout()` `clearTimeout(timeout)` : Отменяет объект `timeout`, созданный `setTimeout()`. `setTimeout(function, milliseconds[, argument1, argumentN])` : Вызывает `function` после указанного количества `milliseconds`. Можно передать один или несколько опциональных `arguments` в указанную функцию. Возвращает объект `timeout`.
Пример:
```javascript function handler(v) { // ... }
t = setTimeout(handler, 12);
// ...
clearTimeout(t); ``` ### Глобальные функции - `atob()` - `btoa()` `atob(encodedData)` : Декодирует строку данных, которая была закодирована с использованием кодировки `Base64`. Параметр `encodedData` — это двоичная строка, содержащая данные в кодировке Base64. Возвращает строку, содержащую декодированные данные из `encodedData`.
Подобный метод `btoa()` может использоваться для кодирования и передачи данных, которые иначе могут вызвать проблемы связи, а затем их передачи и использования метода `atob()` для повторного декодирования данных. Например, можно кодировать, передавать и декодировать управляющие символы, такие как значения ASCII от `0` до `31`.
Пример:
```javascript const encodedData = btoa("text to encode"); // encode a string const decodedData = atob(encodedData); // decode the string ``` `btoa(stringToEncode)` : Создает строку ASCII в кодировке Base64 из двоичной строки. Параметр `stringToEncode` — это двоичная строка для кодирования. Возвращает строку ASCII, содержащую представление `stringToEncode` в Base64.
Метод может использоваться для кодирования данных, которые иначе могут вызвать проблемы связи, их передачи и затем использования метода `atob()` для повторного декодирования данных. Например, можно кодировать управляющие символы, такие как значения ASCII от `0` до `31`.
Пример:
```javascript const encodedData = btoa("text to encode"); // encode a string const decodedData = atob(encodedData); // decode the string ``` ## Встроенные модули ### Buffer Объект `Buffer` — это совместимый с Node.js способ работы с двоичными данными. Из-за большого размера файла этот раздел ограничен полным списком методов Buffer. - `Buffer.alloc()` - `Buffer.allocUnsafe()` - `Buffer.byteLength()` - `Buffer.compare()` - `Buffer.concat()` - `Buffer.from(array)` - `Buffer.from(arrayBuffer)` - `Buffer.from(buffer)` - `Buffer.from(object)` - `Buffer.from(string)` - `Buffer.isBuffer()` - `Buffer.isEncoding()` - `buffer[]` - `buf.buffer` - `buf.byteOffset` - `buf.compare()` - `buf.copy()` - `buf.equals()` - `buf.fill()` - `buf.includes()` - `buf.indexOf()` - `buf.lastIndexOf()` - `buf.length` - `buf.readIntBE()` - `buf.readIntLE()` - `buf.readUIntBE()` - `buf.readUIntLE()` - `buf.readDoubleBE()` - `buf.readDoubleLE()` - `buf.readFloatBE()` - `buf.readFloatLE()` - `buf.subarray()` - `buf.slice()` - `buf.swap16()` - `buf.swap32()` - `buf.swap64()` - `buf.toJSON()` - `buf.toString()` - `buf.write()` - `buf.writeIntBE()` - `buf.writeIntLE()` - `buf.writeUIntBE()` - `buf.writeUIntLE()` - `buf.writeDoubleBE()` - `buf.writeDoubleLE()` - `buf.writeFloatBE()` - `buf.writeFloatLE()` Подробную документацию по методам Buffer см. в [документации Node.js по Buffer](https://nodejs.org/api/buffer.html). ### Crypto Модуль Crypto предоставляет поддержку криптографической функциональности. Объект модуля Crypto импортируется с использованием `import crypto from 'crypto'`. #### NOTE Начиная с версии 0.7.0, расширенный API криптографии доступен как глобальный объект [crypto](#njs-builtin-crypto). - `crypto.createHash()` - `crypto.createHmac()` `crypto.createHash(algorithm)` : Создает и возвращает объект Hash, который может использоваться для генерации дайджестов хешей с использованием заданного `algorithm`. Алгоритм может быть `md5`, `sha1` и `sha256`. `crypto.createHmac(algorithm, secret key)` : Создает и возвращает объект HMAC, который использует заданный `algorithm` и `secret key`. Алгоритм может быть `md5`, `sha1` и `sha256`. #### Hash - `hash.update()` - `hash.digest()` `hash.update(data)` : Обновляет содержимое хеша с заданными `data`. `hash.digest([encoding])` : Вычисляет дайджест всех данных, переданных с использованием `hash.update()`. Кодировка может быть `hex`, `base64` и `base64url`. Если кодировка не предоставлена, возвращается объект Buffer (0.4.4).
#### NOTE До версии 0.4.4 вместо объекта Buffer возвращалась байтовая строка. `hash.copy()` : Создает копию текущего состояния хеша (с версии 0.7.12). Пример: ```javascript import crypto from 'crypto'; crypto.createHash('sha1').update('A').update('B').digest('base64url'); /* BtlFlCqiamG-GMPiK_GbvKjdK10 */ ``` #### HMAC - `hmac.update()` - `hmac.digest()` `hmac.update(data)` : Обновляет содержимое HMAC с заданными `data`. `hmac.digest([encoding])` : Вычисляет дайджест HMAC всех данных, переданных с использованием `hmac.update()`. Кодировка может быть `hex`, `base64` и `base64url`. Если кодировка не предоставлена, возвращается объект Buffer (0.4.4).
#### NOTE До версии 0.4.4 вместо объекта Buffer возвращалась байтовая строка. ### fs Модуль `fs` предоставляет операции с файловой системой. Объект модуля импортируется с использованием `import fs from 'fs'`. - `fs.accessSync()` - `fs.appendFileSync()` - `fs.mkdirSync()` - `fs.readdirSync()` - `fs.readFileSync()` - `fs.realpathSync()` - `fs.renameSync()` - `fs.rmdirSync()` - `fs.symlinkSync()` - `fs.unlinkSync()` - `fs.writeFileSync()` - `fs.promises.readFile()` - `fs.promises.appendFile()` - `fs.promises.writeFile()` - `fs.promises.readdir()` - `fs.promises.mkdir()` - `fs.promises.rmdir()` - `fs.promises.rename()` - `fs.promises.unlink()` - `fs.promises.symlink()` - `fs.promises.access()` - `fs.promises.realpath()` За более подробной документацией по методам fs обратитесь к [документации Node.js по fs](https://nodejs.org/api/fs.html). ### Query String Модуль Query String предоставляет методы для парсинга и форматирования строк запроса URL. Объект модуля импортируется с использованием `import qs from 'querystring'`. - `querystring.decode()` - `querystring.encode()` - `querystring.escape()` - `querystring.parse()` - `querystring.stringify()` - `querystring.unescape()` `querystring.decode()` : Псевдоним для `querystring.parse()`. `querystring.encode()` : Псевдоним для `querystring.stringify()`. `querystring.escape(string)` : Выполняет процентное кодирование URL `string` оптимизированным для требований строк запроса URL образом. Метод используется `querystring.stringify()` и не должен использоваться напрямую. `querystring.parse(string[, separator[, equal[, options]]])` : Парсит `string` как строку запроса URL и возвращает объект. Опциональный параметр `separator` (по умолчанию: `&`) указывает подстроку для разделения пар ключ-значение. Опциональный параметр `equal` (по умолчанию: `=`) указывает подстроку для разделения ключей и значений. Опциональный параметр `options` — это объект, который может содержать следующее свойство:
`decodeURIComponent` : Функция, используемая при декодировании процентно-кодированных символов в строке запроса, по умолчанию: `querystring.unescape()`.
`maxKeys` : Максимальное количество ключей для парсинга, по умолчанию: `1000`. Значение `0` удаляет ограничения на подсчет ключей.
Пример:
```javascript >> qs.parse('foo=bar&abc=xyz&abc=123') { foo: 'bar', abc: ['xyz', '123'] } ``` `querystring.stringify(object[, separator[, equal[, options]]])` : Создает строку запроса URL из `object` путем итерации по его собственным свойствам. Опциональный параметр `separator` (по умолчанию: `&`) указывает подстроку для разделения пар ключ-значение. Опциональный параметр `equal` (по умолчанию: `=`) указывает подстроку для разделения ключей и значений. Опциональный параметр `options` — это объект, который может содержать следующее свойство:
`encodeURIComponent` : Функция, используемая при преобразовании небезопасных для URL символов в процентное кодирование в строке запроса, по умолчанию: `querystring.escape()`.
Пример:
```javascript >> qs.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' }) 'foo=bar&baz=qux&baz=quux&corge=' ``` `querystring.unescape(string)` : Выполняет декодирование процентно-кодированных символов URL в `string`. Метод используется `querystring.parse()` и не должен использоваться напрямую. ### XML - `xml.parse()` - `xml.c14n()` - `xml.exclusiveC14n()` - `xml.serialize()` - `xml.serializeToString()` - `XMLDoc` - `XMLNode` - `XMLAttr` Модуль XML позволяет работать с XML документами (с версии 0.7.10). Объект модуля XML импортируется с использованием `import xml from 'xml'`. Пример: ```javascript import xml from 'xml'; let data = `ToveJani`; 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) /* 'ToveJani' */ c14n = dec.decode(xml.exclusiveC14n(doc.note.to)); console.log(c14n) /* 'Tove' */ c14n = dec.decode(xml.exclusiveC14n(doc.note, doc.note.to /* excluding 'to' */)); console.log(c14n) /* 'Jani' */ ``` `parse(string | Buffer)` : Парсит строку или Buffer для XML документа; возвращает объект-обертку `XMLDoc`, представляющий проанализированный XML документ. `c14n(root_node[, excluding_node])` : Канонизирует `root_node` и его потомков согласно [Canonical XML Version 1.1](https://www.w3.org/TR/xml-c14n). `root_node` может быть объектом-оберткой `XMLNode` или `XMLDoc` вокруг XML структуры. Возвращает объект Buffer, содержащий канонизированный вывод.
`excluding_node` : Позволяет исключить из вывода часть документа. `exclusiveC14n(root_node[, excluding_node[, withComments[,prefix_list]]])` : Канонизирует `root_node` и его потомков согласно [Exclusive XML Canonicalization Version 1.0](https://www.w3.org/TR/xml-exc-c14n/).
`root_node` : Является объектом-оберткой `XMLNode` или `XMLDoc` вокруг XML структуры.
`excluding_node` : Позволяет исключить из вывода часть документа, соответствующую узлу и его потомкам.
`withComments` : Логическое значение, по умолчанию `false`. Если `true`, канонизация соответствует [Exclusive XML Canonicalization Version 1.0](http://www.w3.org/2001/10/xml-exc-c14n#WithComments). Возвращает объект Buffer, содержащий канонизированный вывод.
`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` (0.5.2) предоставляет функциональность сжатия и распаковки с использованием zlib. Объект модуля импортируется с использованием `import zlib from 'zlib'`. - `zlib.constants` - `zlib.deflateRawSync()` - `zlib.deflateSync()` - `zlib.inflateRawSync()` - `zlib.inflateSync()` `zlib.constants` : Возвращает словарь констант zlib. `zlib.deflateRawSync(data[, options])` : Сжимает `data` с использованием алгоритма Deflate без заголовка zlib. `zlib.deflateSync(data[, options])` : Сжимает `data` с использованием алгоритма Deflate. `zlib.inflateRawSync(data[, options])` : Распаковывает `data` с использованием алгоритма Deflate без заголовка zlib. `zlib.inflateSync(data[, options])` : Распаковывает `data` с использованием алгоритма Deflate. Параметр `options` — это объект, который может содержать следующие свойства: `level` : Уровень сжатия (по умолчанию: `zlib.constants.Z_DEFAULT_COMPRESSION`). `memLevel` : Указывает, сколько памяти должно быть выделено для состояния сжатия (по умолчанию: `zlib.constants.Z_DEFAULT_MEMLEVEL`). `strategy` : Настраивает алгоритм сжатия (по умолчанию: `zlib.constants.Z_DEFAULT_STRATEGY`). `windowBits` : Устанавливает размер окна (по умолчанию: `zlib.constants.Z_DEFAULT_WINDOWBITS`). `dictionary` : Buffer, содержащий предопределенный словарь сжатия. `info` : Логическое значение, если `true`, возвращает объект с буфером и движком. `chunkSize` : Размер блока для сжатия (по умолчанию: `zlib.constants.Z_DEFAULT_CHUNK`). Пример: ```javascript import zlib from 'zlib'; const deflated = zlib.deflateSync('Hello World!'); const inflated = zlib.inflateSync(deflated); console.log(inflated.toString()); // 'Hello World!' ```