HTTPS¶
Стабильность: 2 – Стабильная
АПИ является удовлетворительным. Совместимость с NPM имеет высший приоритет и не будет нарушена кроме случаев явной необходимости.
HTTPS - это протокол HTTP через TLS/SSL. В Node.js он реализован в виде отдельного модуля.
Определение отсутствия поддержки криптографии¶
Возможно, что Node.js собран без поддержки модуля node:crypto
. В таких случаях попытка импорта
из https
или вызов require('node:https')
приведет к ошибке.
При использовании CommonJS возникшую ошибку можно перехватить с помощью try/catch
:
1 2 3 4 5 6 |
|
При использовании лексического ключевого слова ESM import
ошибка может быть поймана только в том случае, если обработчик process.on('uncaughtException')
зарегистрирован до любой попытки загрузить модуль (например, с помощью модуля предварительной загрузки).
При использовании ESM, если есть вероятность, что код может быть запущен на сборке Node.js, в которой не включена поддержка криптографии, используйте функцию import()
вместо лексического ключевого слова import
:
1 2 3 4 5 6 |
|
Класс: https.Agent
¶
Объект Agent
для HTTPS, аналогичный http.Agent
. Дополнительную информацию смотрите в https.request()
.
new Agent([options])
¶
-
options
<Object>
Набор конфигурируемых опций для установки на агента. Может иметь те же поля, что и дляhttp.Agent(options)
, и-
maxCachedSessions
<number>
максимальное количество TLS кэшированных сессий. Используйте0
, чтобы отключить кэширование сессий TLS. По умолчанию:100
. -
servername
<string>
значение расширения Server Name Indication extension для отправки на сервер. Используйте пустую строку''
, чтобы отключить отправку расширения. По умолчанию: имя хоста целевого сервера, если только целевой сервер не указан с помощью IP-адреса, в этом случае по умолчанию используется''
(без расширения).Информацию о повторном использовании сеанса TLS см. в
Session Resumption
.
-
Событие: keylog
¶
line
<Buffer>
Строка текста ASCII, в формате NSSSSLKEYLOGFILE
.tlsSocket
{tls.TLSSocket} Экземплярtls.TLSSocket
, на котором оно было сгенерировано.
Событие keylog
испускается, когда ключевой материал генерируется или принимается соединением, управляемым этим агентом (обычно до завершения рукопожатия, но не обязательно). Этот ключевой материал может быть сохранен для отладки, поскольку он позволяет расшифровать захваченный трафик TLS. Он может выдаваться несколько раз для каждого сокета.
Типичный случай использования - добавление полученных строк в общий текстовый файл, который впоследствии используется программами (например, Wireshark) для расшифровки трафика:
1 2 3 4 5 6 |
|
Класс: https.Server
¶
- Расширяет: {tls.Server}
Дополнительную информацию смотрите в http.Server
.
server.close([callback])
¶
callback
<Function>
- Возвращает: {https.Server}
См. server.close()
в модуле node:http
.
server.closeAllConnections()
¶
Смотрите server.closeAllConnections()
в модуле node:http
.
server.closeIdleConnections()
¶
Смотрите server.closeIdleConnections()
в модуле node:http
.
server.headersTimeout
¶
<number>
По умолчанию:60000
.
Смотрите server.headersTimeout
в модуле node:http
.
server.listen()
¶
Запускает HTTPS-сервер, прослушивающий зашифрованные соединения. Этот метод идентичен server.listen()
из net.Server
.
server.maxHeadersCount
¶
<number>
По умолчанию:2000
.
Смотрите server.maxHeadersCount
в модуле node:http
.
server.requestTimeout
¶
<number>
По умолчанию:300000
.
Смотрите server.requestTimeout
в модуле node:http
.
server.setTimeout([msecs][, callback])
¶
msecs
<number>
По умолчанию:120000
(2 минуты)callback
<Function>
- Возвращает: {https.Server}
См. server.setTimeout()
в модуле node:http
.
server.timeout
¶
<number>
По умолчанию: 0 (без таймаута).
Смотрите server.timeout
в модуле node:http
.
server.keepAliveTimeout
¶
<number>
По умолчанию:5000
(5 секунд)
Смотрите server.keepAliveTimeout
в модуле node:http
.
https.createServer([options][, requestListener])
¶
options
<Object>
Принимаетопции
изtls.createServer()
,tls.createSecureContext()
иhttp.createServer()
.requestListener
<Function>
Слушатель, который будет добавлен к событию'request'
.- Возвращает: {https.Server}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
Или
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
https.get(options[, callback])
¶
https.get(url[, options][, callback])
¶
url
{строка | URL}options
{Object | string | URL} Принимает те жеопции
, что иhttps.request()
, сметодом
, всегда установленным наGET
.callback
<Function>
Подобно http.get()
, но для HTTPS.
options
может быть объектом, строкой или объектом URL
. Если options
является строкой, она автоматически разбирается с помощью new URL()
. Если это объект URL
, он будет автоматически преобразован в обычный объект options
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
https.globalAgent
¶
Глобальный экземпляр https.Agent
для всех запросов HTTPS клиентов.
https.request(options[, callback])
¶
url
{строка | URL}options
{Object | string | URL} Принимает всеопции
изhttp.request()
, с некоторыми различиями в значениях по умолчанию:protocol
Default:'https:'
.port
По умолчанию:443
agent
По умолчанию:https.globalAgent
callback
<Function>
- Возвращает: {http.ClientRequest}
Делает запрос на защищенный веб-сервер.
Также принимаются следующие дополнительные опции
из tls.connect()
: ca
, cert
, ciphers
, clientCertEngine
, crl
, dhparam
, ecdhCurve
, honorCipherOrder
, key
, passphrase
, pfx
, rejectUnauthorized
, ecureOptions
, ecureProtocol
, servername
, essionIdContext
, highWaterMark
.
options
может быть объектом, строкой или объектом URL
. Если options
- строка, она автоматически разбирается с помощью new URL()
. Если это объект URL
, то он будет автоматически преобразован в обычный объект options
.
https.request()
возвращает экземпляр класса http.ClientRequest
. Экземпляр ClientRequest
представляет собой поток, доступный для записи. Если нужно загрузить файл с помощью POST-запроса, то пишите в объект ClientRequest
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
|
Пример использования опций из tls.connect()
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
В качестве альтернативы откажитесь от пула соединений, не используя Agent
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
Пример с использованием URL
в качестве options
:
1 2 3 4 5 |
|
Пример привязки к отпечатку пальца сертификата или открытому ключу (аналогично pin-sha256
):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 |
|
Выходные данные, например:
1 2 3 4 5 6 7 8 9 10 11 12 |
|