HTTP

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

Исходный код: lib/http.js

Этот модуль, содержащий как клиент, так и сервер, можно импортировать с помощью require('node:http') (CommonJS) или import * as http from 'node:http' (ES-модуль).

HTTP-интерфейсы в Node.js разработаны для поддержки многих функций протокола, которые традиционно были сложны в использовании. В частности, больших сообщений, возможно, закодированных по частям. Интерфейс разработан таким образом, чтобы никогда не буферизировать целые запросы или ответы, поэтому пользователь может передавать данные потоком.

Заголовки HTTP-сообщений представлены объектом такого вида:

{
  "content-length": "123",
  "content-type": "text/plain",
  "connection": "keep-alive",
  "host": "example.com",
  "accept": "*/*"
}

Ключи приведены в нижнем регистре. Значения не изменяются.

Для поддержки всего спектра возможных HTTP-приложений, HTTP API Node.js является очень низкоуровневым. Он работает только с обработкой потоков и разбором сообщений. Он разбирает сообщение на заголовки и тело, но не разбирает сами заголовки или тело.

См. message.headers для получения подробной информации о том, как обрабатываются дублирующиеся заголовки.

Необработанные заголовки в том виде, в котором они были получены, сохраняются в свойстве rawHeaders, которое представляет собой массив [key, value, key2, value2, ...]. Например, для предыдущего объекта заголовка сообщения список rawHeaders может выглядеть следующим образом:

;[
  'ConTent-Length',
  '123456',
  'content-LENGTH',
  '123',
  'content-type',
  'text/plain',
  'CONNECTION',
  'keep-alive',
  'Host',
  'example.com',
  'accepT',
  '*/*',
]

Класс: http.Agent

Добавлен в: v0.3.4

Agent отвечает за управление сохранением и повторным использованием соединений для HTTP-клиентов. Он поддерживает очередь ожидающих запросов для заданного хоста и порта, повторно используя одно сокетное соединение для каждого, пока очередь не опустеет, после чего сокет либо уничтожается, либо помещается в пул, где он хранится для повторного использования для запросов к тому же хосту и порту. Будет ли он уничтожен или помещен в пул, зависит от параметра keepAlive.

Для соединений из пула включено TCP Keep-Alive, но серверы все еще могут закрывать неиспользуемые соединения, в этом случае они будут удалены из пула, и при отправке нового HTTP-запроса для этого хоста и порта будет установлено новое соединение. Серверы также могут запрещать отправку нескольких запросов по одному соединению, в этом случае соединение будет необходимо переустанавливать для каждого запроса, и его нельзя будет помещать в пул. Agent все равно будет отправлять запросы на этот сервер, но каждый из них будет происходить по новому соединению.

Когда соединение закрывается клиентом или сервером, оно удаляется из пула. Все неиспользуемые сокеты в пуле будут отменены, чтобы не поддерживать запущенный процесс Node.js, когда нет ожидающих запросов. (см. socket.unref()).

Рекомендуется destroy() экземпляр Agent, когда он больше не используется, поскольку неиспользуемые сокеты потребляют ресурсы ОС.

Сокеты удаляются из агента, когда сокет испускает событие 'close' или событие 'agentRemove'. Если нужно сохранить один HTTP-запрос открытым в течение длительного времени, не сохраняя его в агенте, можно сделать следующее:

http
  .get(options, res => {
    // Выполняем действия
  })
  .on('socket', socket => {
    socket.emit('agentRemove')
  })

Агент также может использоваться для отдельного запроса. Указав {agent: false} в качестве параметра функций http.get() или http.request(), для клиентского соединения будет использоваться одноразовый Agent с параметрами по умолчанию.

agent:false:

http.get(
  {
    hostname: 'localhost',
    port: 80,
    path: '/',
    agent: false, // Создаем новый агент только для этого запроса
  },
  res => {
    // Выполняем действия с ответом
  }
)

new Agent([options])

[История]

Версия	Изменения
v15.6.0, v14.17.0	Изменение планирования по умолчанию с 'fifo' на 'lifo'.
v14.5.0, v12.20.0	Добавлена опция scheduling для указания стратегии планирования свободного сокета.
v14.5.0, v12.19.0	Добавлена опция maxTotalSockets в конструктор агента.
v0.3.4	Добавлено в: v0.3.4

• options <Object> Набор настраиваемых параметров для агента. Может содержать следующие поля:
  • keepAlive <boolean> Поддерживать сокеты даже при отсутствии незавершенных запросов, чтобы их можно было использовать для будущих запросов без необходимости повторного установления TCP-соединения. Не следует путать со значением keep-alive заголовка Connection. Заголовок Connection: keep-alive всегда отправляется при использовании агента, за исключением случаев, когда заголовок Connection указан явно или когда параметры keepAlive и maxSockets установлены соответственно в false и Infinity, в этом случае будет использоваться Connection: close. По умолчанию: false.
  • keepAliveMsecs <number> При использовании опции keepAlive указывает начальную задержку для пакетов TCP Keep-Alive. Игнорируется, если опция keepAlive равна false или undefined. По умолчанию: 1000.
  • maxSockets <number> Максимальное количество сокетов, разрешенных для каждого хоста. Если один и тот же хост открывает несколько параллельных соединений, каждый запрос будет использовать новый сокет, пока не будет достигнуто значение maxSockets. Если хост пытается открыть больше соединений, чем maxSockets, дополнительные запросы попадут в очередь ожидающих запросов и перейдут в активное состояние соединения при завершении существующего соединения. Это гарантирует, что в любой момент времени будет не более maxSockets активных соединений с данного хоста. По умолчанию: Infinity.
  • maxTotalSockets <number> Максимальное количество сокетов, разрешенных для всех хостов в целом. Каждый запрос будет использовать новый сокет, пока не будет достигнут максимум. По умолчанию: Infinity.
  • maxFreeSockets <number> Максимальное количество сокетов на хост, которые следует оставлять открытыми в свободном состоянии. Актуально только если keepAlive установлено в true. По умолчанию: 256.
  • scheduling <string> Стратегия планирования, применяемая при выборе следующего свободного сокета для использования. Может быть 'fifo' или 'lifo'. Основное различие между двумя стратегиями планирования заключается в том, что 'lifo' выбирает наиболее недавно используемый сокет, а 'fifo' — наименее недавно используемый сокет. В случае низкой скорости запросов в секунду планирование 'lifo' снизит риск выбора сокета, который мог быть закрыт сервером из-за бездействия. В случае высокой скорости запросов в секунду планирование 'fifo' максимизирует количество открытых сокетов, а планирование 'lifo' будет поддерживать его как можно ниже. По умолчанию: 'lifo'.
  • timeout <number> Тайм-аут сокета в миллисекундах. Это установит тайм-аут при создании сокета.

options в socket.connect() также поддерживаются.

Для настройки любого из них необходимо создать экземпляр пользовательского http.Agent.

ESM

import { Agent, request } from 'node:http'
const keepAliveAgent = new Agent({ keepAlive: true })
options.agent = keepAliveAgent
request(options, onResponseCallback)

CJS

const http = require('node:http')
const keepAliveAgent = new http.Agent({ keepAlive: true })
options.agent = keepAliveAgent
http.request(options, onResponseCallback)

agent.createConnection(options[, callback])

Добавлен в: v0.11.4

• options <Object> Параметры, содержащие сведения о подключении. Проверьте net.createConnection() для получения формата параметров
• callback <Function> Функция обратного вызова, которая получает созданный сокет
• Возвращает: <stream.Duplex>

Создает сокет/поток для использования в HTTP-запросах.

По умолчанию эта функция аналогична net.createConnection(). Однако пользовательские агенты могут переопределить этот метод, если требуется большая гибкость.

Сокет/поток может быть предоставлен одним из двух способов: путем возврата сокета/потока из этой функции или путем передачи сокета/потока в callback.

Гарантируется, что этот метод вернет экземпляр класса <net.Socket>, подкласса <stream.Duplex>, если пользователь не укажет тип сокета, отличный от <net.Socket>.

callback имеет сигнатуру (err, stream).

agent.keepSocketAlive(socket)

Добавлен в: v8.1.0

• socket <stream.Duplex>

Вызывается, когда socket отсоединяется от запроса и может быть сохранен агентом Agent. Поведение по умолчанию:

socket.setKeepAlive(true, this.keepAliveMsecs)
socket.unref()
return true

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

Аргумент socket может быть экземпляром <net.Socket>, подклассом <stream.Duplex>.

agent.reuseSocket(socket, request)

Добавлен в: v8.1.0

• socket <stream.Duplex>
• request <http.ClientRequest>

Вызывается, когда socket подключается к request после сохранения из-за параметров keep-alive. Поведение по умолчанию:

socket.ref()

Этот метод может быть переопределен конкретным подклассом Agent.

Аргумент socket может быть экземпляром <net.Socket>, подклассом <stream.Duplex>.

agent.destroy()

Добавлено в: v0.11.4

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

Обычно это делать не нужно. Однако, если используется агент с включенным keepAlive, то лучше явно завершить работу агента, когда он больше не нужен. В противном случае сокеты могут оставаться открытыми довольно долгое время, прежде чем сервер их закроет.

agent.freeSockets

[История]

Версия	Изменения
v16.0.0	Свойство теперь имеет прототип null.
v0.11.4	Добавлено в: v0.11.4

• <Объект>

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

Сокеты в списке freeSockets будут автоматически уничтожены и удалены из массива по событию 'timeout'.

agent.getName([options])

[История]

Версия	Изменения
v17.7.0, v16.15.0	Параметр options теперь необязательный.
v0.11.4	Добавлено в: v0.11.4

• options <Объект> Набор параметров, предоставляющих информацию для генерации имени

  • host <строка> Доменное имя или IP-адрес сервера, к которому отправляется запрос
  • port <число> Порт удаленного сервера
  • localAddress <строка> Локальный интерфейс для привязки сетевых соединений при отправке запроса
  • family <целое число> Должно быть равно 4 или 6, если не равно undefined.

• Возвращает: <строка>

Получает уникальное имя для набора параметров запроса, чтобы определить, можно ли повторно использовать соединение. Для HTTP-агента это возвращает host:port:localAddress или host:port:localAddress:family. Для HTTPS-агента имя включает CA, сертификат, шифры и другие специфические для HTTPS/TLS параметры, определяющие возможность повторного использования сокета.

agent.maxFreeSockets

Добавлено в: v0.11.7

• <число>

По умолчанию установлено в 256. Для агентов с включенным keepAlive это устанавливает максимальное количество сокетов, которые будут оставлены открытыми в свободном состоянии.

agent.maxSockets

Добавлено в: v0.3.6

• <число>

По умолчанию установлено в Infinity. Определяет, сколько одновременных сокетов агент может иметь открытыми на один источник. Источник — это возвращаемое значение agent.getName().

agent.maxTotalSockets

Добавлено в: v14.5.0, v12.19.0

• <число>

По умолчанию установлено в Infinity. Определяет, сколько одновременных сокетов может быть открыто агентом. В отличие от maxSockets, этот параметр применяется ко всем источникам.

agent.requests

[История]

Версия	Изменения
v16.0.0	Свойство теперь имеет прототип null.
v0.5.9	Добавлено в: v0.5.9

• <Объект>

Объект, содержащий очереди запросов, которые еще не назначены сокетам. Не изменяйте.

agent.sockets

[История]

Версия	Изменения
v16.0.0	Свойство теперь имеет прототип null.
v0.3.6	Добавлено в: v0.3.6

• <Объект>

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

Класс: http.ClientRequest

Добавлено в: v0.1.17

• Расширяет: <http.OutgoingMessage>

Этот объект создается внутренне и возвращается из http.request(). Он представляет собой текущий запрос, заголовок которого уже помещен в очередь. Заголовок все еще можно изменять с помощью API setHeader(name, value), getHeader(name), removeHeader(name). Фактический заголовок будет отправлен вместе с первым фрагментом данных или при вызове request.end().

Чтобы получить ответ, добавьте прослушиватель для 'response' к объекту запроса. 'response' будет отправлено объектом запроса после получения заголовков ответа. Событие 'response' выполняется с одним аргументом, который является экземпляром http.IncomingMessage.

Во время события 'response' можно добавлять прослушиватели к объекту ответа; в частности, для прослушивания события 'data'.

Если обработчик 'response' не добавлен, то ответ будет полностью отброшен. Однако, если обработчик события 'response' добавлен, то данные из объекта ответа должны быть обработаны, либо путем вызова response.read() всякий раз, когда возникает событие 'readable', либо путем добавления обработчика 'data', либо путем вызова метода .resume(). Пока данные не обработаны, событие 'end' не сработает. Кроме того, пока данные не прочитаны, они будут потреблять память, что может привести к ошибке «нехватка памяти в процессе».

Для обратной совместимости res будет отправлять 'error' только в том случае, если зарегистрирован прослушиватель 'error'.

Установите заголовок Content-Length, чтобы ограничить размер тела ответа. Если response.strictContentLength установлен в true, несоответствие значения заголовка Content-Length приведет к выбросу ошибки Error, идентифицируемой как code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

Значение Content-Length должно быть в байтах, а не в символах. Используйте Buffer.byteLength() для определения длины тела в байтах.

Событие: 'abort'

Добавлено в: v1.4.1

Устарело с: v17.0.0, v16.12.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте событие 'close' вместо этого.

Генерируется, когда запрос был прерван клиентом. Это событие генерируется только при первом вызове abort().

Событие: 'close'

Добавлено в: v0.5.4

Указывает на завершение запроса или преждевременное завершение его базового соединения (до завершения ответа).

Событие: 'connect'

Добавлено в: v0.7.0

• response <http.IncomingMessage>
• socket <stream.Duplex>
• head <Buffer>

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

Гарантируется, что этому событию будет передан экземпляр класса <net.Socket>, подкласс <stream.Duplex>, если пользователь не укажет тип сокета, отличный от <net.Socket>.

Пара клиент-сервер, демонстрирующая прослушивание события 'connect':

ESM

import { createServer, request } from 'node:http'
import { connect } from 'node:net'
import { URL } from 'node:url'

// Создаем HTTP-прокси туннелирования
const proxy = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('okay')
})
proxy.on('connect', (req, clientSocket, head) => {
  // Подключаемся к исходному серверу
  const { port, hostname } = new URL(`http://${req.url}`)
  const serverSocket = connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' + 'Proxy-agent: Node.js-Proxy\r\n' + '\r\n')
    serverSocket.write(head)
    serverSocket.pipe(clientSocket)
    clientSocket.pipe(serverSocket)
  })
})

// Теперь, когда прокси работает
proxy.listen(1337, '127.0.0.1', () => {
  // Делаем запрос к прокси туннелирования
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  }

  const req = request(options)
  req.end()

  req.on('connect', (res, socket, head) => {
    console.log('got connected!')

    // Делаем запрос через HTTP-туннель
    socket.write('GET / HTTP/1.1\r\n' + 'Host: www.google.com:80\r\n' + 'Connection: close\r\n' + '\r\n')
    socket.on('data', chunk => {
      console.log(chunk.toString())
    })
    socket.on('end', () => {
      proxy.close()
    })
  })
})

CJS

const http = require('node:http')
const net = require('node:net')
const { URL } = require('node:url')

// Создаем HTTP-прокси туннелирования
const proxy = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('okay')
})
proxy.on('connect', (req, clientSocket, head) => {
  // Подключаемся к исходному серверу
  const { port, hostname } = new URL(`http://${req.url}`)
  const serverSocket = net.connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' + 'Proxy-agent: Node.js-Proxy\r\n' + '\r\n')
    serverSocket.write(head)
    serverSocket.pipe(clientSocket)
    clientSocket.pipe(serverSocket)
  })
})

// Теперь, когда прокси работает
proxy.listen(1337, '127.0.0.1', () => {
  // Делаем запрос к прокси туннелирования
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  }

  const req = http.request(options)
  req.end()

  req.on('connect', (res, socket, head) => {
    console.log('got connected!')

    // Делаем запрос через HTTP-туннель
    socket.write('GET / HTTP/1.1\r\n' + 'Host: www.google.com:80\r\n' + 'Connection: close\r\n' + '\r\n')
    socket.on('data', chunk => {
      console.log(chunk.toString())
    })
    socket.on('end', () => {
      proxy.close()
    })
  })
})

Событие: 'continue'

Добавлено в: v0.3.2

Генерируется, когда сервер отправляет HTTP-ответ «100 Continue», обычно потому, что запрос содержал «Expect: 100-continue». Это инструкция, что клиент должен отправить тело запроса.

Событие: 'finish'

Добавлено в: v0.3.6

Генерируется после отправки запроса. Точнее, это событие генерируется, когда последний сегмент заголовков и тела ответа был передан операционной системе для передачи по сети. Это не означает, что сервер уже что-то получил.

Событие: 'information'

Добавлено в: v10.0.0

• info <Object>
  • httpVersion <string>
  • httpVersionMajor <integer>
  • httpVersionMinor <integer>
  • statusCode <integer>
  • statusMessage <string>
  • headers <Object>
  • rawHeaders <string[]>

Генерируется, когда сервер отправляет промежуточный ответ 1xx (за исключением 101 Upgrade). Слушатели этого события получат объект, содержащий версию HTTP, код состояния, сообщение состояния, объект заголовков «ключ-значение» и массив с необработанными именами заголовков, за которыми следуют их соответствующие значения.

ESM

import { request } from 'node:http'

const options = {
  host: '127.0.0.1',
  port: 8080,
  path: '/length_request',
}

// Make a request
const req = request(options)
req.end()

req.on('information', info => {
  console.log(`Got information prior to main response: ${info.statusCode}`)
})

CJS

const http = require('node:http')

const options = {
  host: '127.0.0.1',
  port: 8080,
  path: '/length_request',
}

// Make a request
const req = http.request(options)
req.end()

req.on('information', info => {
  console.log(`Got information prior to main response: ${info.statusCode}`)
})

Статусы 101 Upgrade не вызывают это событие из-за их отклонения от традиционной цепочки запросов/ответов HTTP, таких как веб-сокеты, обновления TLS на месте или HTTP 2.0. Чтобы получать уведомления о сообщениях 101 Upgrade, вместо этого прослушивайте событие 'upgrade'.

Событие: 'response'

Добавлено в: v0.1.0

• response <http.IncomingMessage>

Генерируется при получении ответа на этот запрос. Это событие генерируется только один раз.

Событие: 'socket'

Добавлено в: v0.5.3

• socket <stream.Duplex>

Гарантируется, что этому событию будет передан экземпляр класса <net.Socket>, подкласса <stream.Duplex>, если пользователь не укажет тип сокета, отличный от <net.Socket>.

Событие: 'timeout'

Добавлено в: v0.7.8

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

См. также: request.setTimeout().

Событие: 'upgrade'

Добавлено в: v0.1.94

• response <http.IncomingMessage>
• socket <stream.Duplex>
• head <Buffer>

Генерируется каждый раз, когда сервер отвечает на запрос обновлением. Если это событие не прослушивается, а код состояния ответа равен 101 Switching Protocols, соединения клиентов, получающих заголовок обновления, будут закрыты.

Гарантируется, что этому событию будет передан экземпляр класса <net.Socket>, подкласса <stream.Duplex>, если пользователь не укажет тип сокета, отличный от <net.Socket>.

Пример клиент-серверной пары, демонстрирующий прослушивание события 'upgrade'.

ESM

import http from 'node:http'
import process from 'node:process'

// Создаем HTTP-сервер
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('okay')
})
server.on('upgrade', (req, socket, head) => {
  socket.write(
    'HTTP/1.1 101 Web Socket Protocol Handshake\r\n' + 'Upgrade: WebSocket\r\n' + 'Connection: Upgrade\r\n' + '\r\n'
  )

  socket.pipe(socket) // эхо-ответ
})

// Теперь, когда сервер запущен
server.listen(1337, '127.0.0.1', () => {
  // делаем запрос
  const options = {
    port: 1337,
    host: '127.0.0.1',
    headers: {
      Connection: 'Upgrade',
      Upgrade: 'websocket',
    },
  }

  const req = http.request(options)
  req.end()

  req.on('upgrade', (res, socket, upgradeHead) => {
    console.log('got upgraded!')
    socket.end()
    process.exit(0)
  })
})

CJS

const http = require('node:http')

// Создаем HTTP-сервер
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('okay')
})
server.on('upgrade', (req, socket, head) => {
  socket.write(
    'HTTP/1.1 101 Web Socket Protocol Handshake\r\n' + 'Upgrade: WebSocket\r\n' + 'Connection: Upgrade\r\n' + '\r\n'
  )

  socket.pipe(socket) // эхо-ответ
})

// Теперь, когда сервер запущен
server.listen(1337, '127.0.0.1', () => {
  // делаем запрос
  const options = {
    port: 1337,
    host: '127.0.0.1',
    headers: {
      Connection: 'Upgrade',
      Upgrade: 'websocket',
    },
  }

  const req = http.request(options)
  req.end()

  req.on('upgrade', (res, socket, upgradeHead) => {
    console.log('got upgraded!')
    socket.end()
    process.exit(0)
  })
})

request.abort()

Добавлено в: v0.3.8

Устарело с: v14.1.0, v13.14.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело: Используйте request.destroy() вместо этого.

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

request.aborted

[История]

Версия	Изменения
v17.0.0, v16.12.0	Устарело с: v17.0.0, v16.12.0
v11.0.0	Свойство aborted больше не является числовым значением временной метки.
v0.11.14	Добавлено в: v0.11.14

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Проверьте request.destroyed вместо этого.

• <boolean>

Свойство request.aborted будет равно true, если запрос был прерван.

request.connection

Добавлено в: v0.3.0

Устарело с: v13.0.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте request.socket.

• <stream.Duplex>

См. request.socket.

request.cork()

Добавлено в: v13.2.0, v12.16.0

См. writable.cork().

request.end([data[, encoding]][, callback])

[История]

Версия	Изменения
v15.0.0	Параметр data теперь может быть Uint8Array.
v10.0.0	Этот метод теперь возвращает ссылку на ClientRequest.
v0.1.90	Добавлено в: v0.1.90

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Возвращает: <this>

Завершает отправку запроса. Если какие-либо части тела не отправлены, они будут отправлены в поток. Если запрос фрагментирован, это отправит завершающий '0\r\n\r\n'.

Если указан data, это эквивалентно вызову request.write(data, encoding) с последующим request.end(callback).

Если указан callback, он будет вызван, когда поток запроса будет завершен.

request.destroy([error])

[История]

Версия	Изменения
v14.5.0	Функция возвращает this для согласованности с другими потоками Readable.
v0.3.0	Добавлено в: v0.3.0

• error <Error> Необязательно, ошибка для генерации события 'error'.
• Возвращает: <this>

Уничтожает запрос. При желании генерирует событие 'error' и событие 'close'. Вызов этой функции приведет к отбрасыванию оставшихся данных в ответе и уничтожению сокета.

См. writable.destroy() для получения более подробной информации.

request.destroyed

Добавлено в: v14.1.0, v13.14.0

• <boolean>

Имеет значение true после вызова request.destroy().

См. writable.destroyed для получения более подробной информации.

request.finished

Добавлено в: v0.0.1

Устарело с: v13.4.0, v12.16.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте request.writableEnded.

• <boolean>

Свойство request.finished будет равно true, если был вызван request.end(). request.end() будет автоматически вызван, если запрос был инициирован через http.get().

request.flushHeaders()

Добавлено в: v1.6.0

Сбрасывает заголовки запроса.

В целях повышения эффективности Node.js обычно буферизует заголовки запроса до тех пор, пока не будет вызван request.end() или не будет записан первый фрагмент данных запроса. Затем он пытается упаковать заголовки запроса и данные в один TCP-пакет.

Это обычно желательно (это экономит TCP-обмен), но не тогда, когда первые данные не отправляются до гораздо более позднего момента. request.flushHeaders() обходит оптимизацию и запускает запрос.

request.getHeader(name)

Добавлено в: v1.6.0

• name <string>
• Возвращает: <any>

Считывает заголовок из запроса. Регистр имени не имеет значения. Тип возвращаемого значения зависит от аргументов, переданных в request.setHeader().

request.setHeader('content-type', 'text/html')
request.setHeader('Content-Length', Buffer.byteLength(body))
request.setHeader('Cookie', ['type=ninja', 'language=javascript'])
const contentType = request.getHeader('Content-Type')
// 'contentType' равно 'text/html'
const contentLength = request.getHeader('Content-Length')
// 'contentLength' имеет тип number
const cookie = request.getHeader('Cookie')
// 'cookie' имеет тип string[]

request.getHeaderNames()

Добавлено в: v7.7.0

• Возвращает: <string[]>

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

request.setHeader('Foo', 'bar')
request.setHeader('Cookie', ['foo=bar', 'bar=baz'])

const headerNames = request.getHeaderNames()
// headerNames === ['foo', 'cookie']

request.getHeaders()

Добавлено в: v7.7.0

• Возвращает: <Object>

Возвращает неглубокую копию текущих исходящих заголовков. Поскольку используется неглубокая копия, значения массива могут быть изменены без дополнительных вызовов различных методов модуля http, связанных с заголовками. Ключи возвращаемого объекта — это имена заголовков, а значения — соответствующие значения заголовков. Все имена заголовков строчные.

Объект, возвращаемый методом request.getHeaders(), не наследуется прототипически от JavaScript Object. Это означает, что типичные методы Object, такие как obj.toString(), obj.hasOwnProperty() и другие, не определены и не будут работать.

request.setHeader('Foo', 'bar')
request.setHeader('Cookie', ['foo=bar', 'bar=baz'])

const headers = request.getHeaders()
// headers === { foo: 'bar', 'cookie': ['foo=bar', 'bar=baz'] }

request.getRawHeaderNames()

Добавлено в: v15.13.0, v14.17.0

• Возвращает: <string[]>

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

request.setHeader('Foo', 'bar')
request.setHeader('Set-Cookie', ['foo=bar', 'bar=baz'])

const headerNames = request.getRawHeaderNames()
// headerNames === ['Foo', 'Set-Cookie']

request.hasHeader(name)

Добавлено в: v7.7.0

• name <string>
• Возвращает: <boolean>

Возвращает true, если заголовок, идентифицированный по name, в данный момент установлен в исходящих заголовках. Сопоставление имен заголовков нечувствительно к регистру.

const hasContentType = request.hasHeader('content-type')

request.maxHeadersCount

• <number> По умолчанию: 2000

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

request.path

Добавлено в: v0.4.0

• <string> Путь запроса.

request.method

Добавлено в: v0.1.97

• <string> Метод запроса.

request.host

Добавлено в: v14.5.0, v12.19.0

• <string> Хост запроса.

request.protocol

Добавлено в: v14.5.0, v12.19.0

• <string> Протокол запроса.

request.removeHeader(name)

Добавлено в: v1.6.0

• name <string>

Удаляет заголовок, уже определенный в объекте заголовков.

request.removeHeader('Content-Type')

request.reusedSocket

Добавлено в: v13.0.0, v12.16.0

• <boolean> Используется ли для запроса повторно используемый сокет.

При отправке запроса через агент с включённым keep-alive, базовый сокет может быть повторно использован. Но если сервер закроет соединение в неподходящее время, клиент может столкнуться с ошибкой 'ECONNRESET'.

ESM

import http from 'node:http'

// Сервер имеет по умолчанию таймаут keep-alive 5 секунд
http
  .createServer((req, res) => {
    res.write('hello\n')
    res.end()
  })
  .listen(3000)

setInterval(() => {
  // Адаптация агента keep-alive
  http.get('http://localhost:3000', { agent }, res => {
    res.on('data', data => {
      // Ничего не делаем
    })
  })
}, 5000) // Отправка запроса с интервалом 5с, чтобы легко достичь таймаута простоя

CJS

const http = require('node:http')

// Сервер имеет по умолчанию таймаут keep-alive 5 секунд
http
  .createServer((req, res) => {
    res.write('hello\n')
    res.end()
  })
  .listen(3000)

setInterval(() => {
  // Адаптация агента keep-alive
  http.get('http://localhost:3000', { agent }, res => {
    res.on('data', data => {
      // Ничего не делаем
    })
  })
}, 5000) // Отправка запроса с интервалом 5с, чтобы легко достичь таймаута простоя

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

ESM

import http from 'node:http'
const agent = new http.Agent({ keepAlive: true })

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, res => {
      // ...
    })
    .on('error', err => {
      // Проверка необходимости повтора
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest()
      }
    })
}

retriableRequest()

CJS

const http = require('node:http')
const agent = new http.Agent({ keepAlive: true })

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, res => {
      // ...
    })
    .on('error', err => {
      // Проверка необходимости повтора
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest()
      }
    })
}

retriableRequest()

request.setHeader(name, value)

Добавлен в: v1.6.0

• name <string>
• value <any>

Устанавливает одно значение заголовка для объекта заголовков. Если этот заголовок уже существует в отправляемых заголовках, его значение будет заменено. Используйте здесь массив строк, чтобы отправить несколько заголовков с одинаковым именем. Нестроковые значения будут сохранены без изменений. Поэтому request.getHeader() может возвращать нестроковые значения. Однако нестроковые значения будут преобразованы в строки для передачи по сети.

request.setHeader('Content-Type', 'application/json')

или

request.setHeader('Cookie', ['type=ninja', 'language=javascript'])

Если значение является строкой, будет выброшено исключение, если оно содержит символы за пределами кодировки latin1.

Если вам нужно передать символы UTF-8 в значении, закодируйте значение, используя стандарт RFC 8187.

const filename = 'Rock 🎵.txt'
request.setHeader('Content-Disposition', `attachment; filename*=utf-8''${encodeURIComponent(filename)}`)

request.setNoDelay([noDelay])

Добавлен в: v0.5.9

• noDelay <boolean>

После того, как сокет назначен этому запросу и подключен, будет вызван socket.setNoDelay().

request.setSocketKeepAlive([enable][, initialDelay])

Добавлен в: v0.5.9

• enable <boolean>
• initialDelay <number>

После того, как сокет назначен этому запросу и подключен, будет вызван socket.setKeepAlive().

request.setTimeout(timeout[, callback])

[История]

Версия	Изменения
v9.0.0	Таймаут сокета устанавливается согласованно только при подключении сокета.
v0.5.9	Добавлено в: v0.5.9

• timeout <number> Миллисекунды до истечения времени ожидания запроса.
• callback <Function> Необязательная функция, вызываемая при истечении времени ожидания. То же самое, что и привязка к событию 'timeout'.
• Возвращает: <http.ClientRequest>

После того, как сокет назначен этому запросу и подключен, будет вызван socket.setTimeout().

request.socket

Добавлено в: v0.3.0

• <stream.Duplex>

Ссылка на базовый сокет. Как правило, пользователям не нужно обращаться к этому свойству. В частности, сокет не будет генерировать события 'readable' из-за того, как парсер протокола подключается к сокету.

ESM

import http from 'node:http'
const options = {
  host: 'www.google.com',
}
const req = http.get(options)
req.end()
req.once('response', res => {
  const ip = req.socket.localAddress
  const port = req.socket.localPort
  console.log(`Ваш IP-адрес: ${ip}, порт источника: ${port}.`)
  // Обработка объекта ответа
})

CJS

const http = require('node:http')
const options = {
  host: 'www.google.com',
}
const req = http.get(options)
req.end()
req.once('response', res => {
  const ip = req.socket.localAddress
  const port = req.socket.localPort
  console.log(`Ваш IP-адрес: ${ip}, порт источника: ${port}.`)
  // Обработка объекта ответа
})

Гарантируется, что это свойство является экземпляром класса <net.Socket>, подкласса <stream.Duplex>, если пользователь не указал тип сокета, отличный от <net.Socket>.

request.uncork()

Добавлено в: v13.2.0, v12.16.0

См. writable.uncork().

request.writableEnded

Добавлено в: v12.9.0

• <boolean>

Имеет значение true после вызова request.end(). Это свойство не указывает, были ли данные отправлены, для этого используйте request.writableFinished.

request.writableFinished

Добавлено в: v12.7.0

• <boolean>

Имеет значение true, если все данные были отправлены в базовую систему, непосредственно перед событием 'finish'.

request.write(chunk[, encoding][, callback])

[История]

Версия	Изменения
v15.0.0	Параметр chunk теперь может быть Uint8Array.
v0.1.29	Добавлено в: v0.1.29

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Возвращает: <boolean>

Отправляет часть тела. Этот метод может вызываться несколько раз. Если Content-Length не установлен, данные будут автоматически закодированы в кодировку HTTP Chunked, чтобы сервер знал, когда данные заканчиваются. Добавляется заголовок Transfer-Encoding: chunked. Для завершения отправки запроса необходимо вызвать request.end().

Аргумент encoding является необязательным и применяется только тогда, когда chunk является строкой. По умолчанию используется 'utf8'.

Аргумент callback является необязательным и будет вызван, когда этот фрагмент данных будет отправлен, но только если фрагмент не пуст.

Возвращает true, если все данные были успешно отправлены в буфер ядра. Возвращает false, если все или часть данных были помещены в очередь в памяти пользователя. 'drain' будет вызвано, когда буфер снова освободится.

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

Класс: http.Server

Добавлено в: v0.1.17

• Расширяет: <net.Server>

Событие: 'checkContinue'

Добавлено в: v0.3.0

• request <http.IncomingMessage>
• response <http.ServerResponse>

Генерируется каждый раз при получении запроса с HTTP Expect: 100-continue. Если для этого события не назначен обработчик, сервер автоматически ответит 100 Continue, если это уместно.

Обработка этого события включает вызов response.writeContinue(), если клиент должен продолжить отправку тела запроса, или генерацию соответствующего HTTP-ответа (например, 400 Bad Request), если клиент не должен продолжать отправку тела запроса.

Когда это событие генерируется и обрабатывается, событие 'request' не генерируется.

Событие: 'checkExpectation'

Добавлено в: v5.5.0

• request <http.IncomingMessage>
• response <http.ServerResponse>

Генерируется каждый раз при получении запроса с HTTP-заголовком Expect, значение которого не равно 100-continue. Если для этого события не назначен обработчик, сервер автоматически ответит 417 Expectation Failed, если это уместно.

Когда это событие генерируется и обрабатывается, событие 'request' не генерируется.

Событие: 'clientError'

[История]

Версия	Изменения
v12.0.0	Поведение по умолчанию вернёт 431 Request Header Fields Too Large, если произошла ошибка HPE_HEADER_OVERFLOW.
v9.4.0	rawPacket — это текущий буфер, который только что был разобран. Добавление этого буфера в объект ошибки события 'clientError' позволяет разработчикам регистрировать повреждённый пакет.
v6.0.0	Действие по умолчанию — вызов .destroy() для socket — больше не будет выполняться, если есть обработчики для 'clientError'.
v0.1.94	Добавлено в: v0.1.94

• exception <Error>
• socket <stream.Duplex>

Если подключение клиента генерирует событие 'error', оно будет перенаправлено сюда. Обработчик этого события отвечает за закрытие/уничтожение базового сокета. Например, можно более корректно закрыть сокет с помощью пользовательского HTTP-ответа, вместо резкого разрыва соединения. Сокет должен быть закрыт или уничтожен до завершения обработчика.

Гарантируется, что этому событию будет передан экземпляр класса <net.Socket>, подкласса <stream.Duplex>, если только пользователь не укажет тип сокета, отличный от <net.Socket>.

Поведение по умолчанию — попытка закрыть сокет с HTTP '400 Bad Request' или HTTP '431 Request Header Fields Too Large' в случае ошибки HPE_HEADER_OVERFLOW. Если сокет не записываем или заголовки текущего присоединённого http.ServerResponse были отправлены, он немедленно уничтожается.

socket — это объект net.Socket, из которого произошла ошибка.

ESM

import http from 'node:http'

const server = http.createServer((req, res) => {
  res.end()
})
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
})
server.listen(8000)

CJS

const http = require('node:http')

const server = http.createServer((req, res) => {
  res.end()
})
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
})
server.listen(8000)

Когда происходит событие 'clientError', объектов request или response нет, поэтому любой отправляемый HTTP-ответ, включая заголовки и полезную нагрузку, должен быть записан непосредственно в объект socket. Необходимо убедиться, что ответ представляет собой правильно отформатированное сообщение HTTP-ответа.

err — это экземпляр Error с двумя дополнительными полями:

• bytesParsed: количество байтов пакета запроса, которое Node.js, возможно, правильно разобрать;
• rawPacket: необработанный пакет текущего запроса.

В некоторых случаях клиент уже получил ответ и/или сокет уже был уничтожен, как в случае ошибок ECONNRESET. Прежде чем пытаться отправить данные в сокет, лучше проверить, записываем ли он.

server.on('clientError', (err, socket) => {
  if (err.code === 'ECONNRESET' || !socket.writable) {
    return
  }

  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
})

Событие: 'close'

Добавлено в: v0.1.4

Генерируется при закрытии сервера.

Событие: 'connect'

Добавлено в: v0.7.0

• request <http.IncomingMessage> Аргументы HTTP-запроса, как в событии 'request'
• socket <stream.Duplex> Сетевой сокет между сервером и клиентом
• head <Buffer> Первый пакет потока туннелирования (может быть пустым)

Генерируется каждый раз, когда клиент запрашивает метод HTTP CONNECT. Если это событие не прослушивается, то соединения клиентов, запрашивающих метод CONNECT, будут закрыты.

Гарантируется, что этому событию будет передан экземпляр класса <net.Socket>, подкласса <stream.Duplex>, если пользователь не укажет тип сокета, отличный от <net.Socket>.

После генерации этого события у сокета запроса не будет обработчика событий 'data', а значит, его нужно будет привязать для обработки данных, отправляемых на сервер по этому сокету.

Событие: 'connection'

Добавлено в: v0.1.0

• socket <stream.Duplex>

Это событие генерируется при установлении нового TCP-потока. socket обычно является объектом типа net.Socket. Как правило, пользователям не нужно обращаться к этому событию. В частности, сокет не будет генерировать события 'readable' из-за того, как парсер протокола подключается к сокету. К сокету также можно получить доступ по адресу request.socket.

Это событие также может быть явно сгенерировано пользователями для вставки соединений в HTTP-сервер. В этом случае может быть передан любой поток Duplex.

Если здесь вызывается socket.setTimeout(), время ожидания будет заменено на server.keepAliveTimeout, когда сокет обработал запрос (если server.keepAliveTimeout не равно нулю).

Гарантируется, что этому событию будет передан экземпляр класса <net.Socket>, подкласса <stream.Duplex>, если пользователь не укажет тип сокета, отличный от <net.Socket>.

Событие: 'dropRequest'

Добавлено в: v18.7.0, v16.17.0

• request <http.IncomingMessage> Аргументы HTTP-запроса, как в событии 'request'
• socket <stream.Duplex> Сетевой сокет между сервером и клиентом

Когда количество запросов на сокете достигает порога server.maxRequestsPerSocket, сервер отклоняет новые запросы и вместо этого генерирует событие 'dropRequest', затем отправляет клиенту код 503.

Событие: 'request'

Добавлено в: v0.1.0

• request <http.IncomingMessage>
• response <http.ServerResponse>

Генерируется каждый раз при поступлении запроса. На одно соединение может приходиться несколько запросов (в случае соединений HTTP Keep-Alive).

Событие: 'upgrade'

[История]

Версия	Изменения
v10.0.0	Отсутствие прослушивания этого события больше не приводит к уничтожению сокета, если клиент отправляет заголовок Upgrade.
v0.1.94	Добавлено в: v0.1.94

• request <http.IncomingMessage> Аргументы HTTP-запроса, как в событии 'request'
• socket <stream.Duplex> Сетевой сокет между сервером и клиентом
• head <Buffer> Первый пакет обновленного потока (может быть пустым)

Генерируется каждый раз, когда клиент запрашивает обновление HTTP. Прослушивание этого события не обязательно, и клиенты не могут настаивать на изменении протокола.

После генерации этого события у сокета запроса не будет обработчика событий 'data', а значит, его необходимо будет связать для обработки данных, отправленных на сервер по этому сокету.

Гарантируется, что для этого события будет передан экземпляр класса <net.Socket>, подкласса <stream.Duplex>, если только пользователь не укажет тип сокета, отличный от <net.Socket>.

server.close([callback])

[История]

Версия	Изменения
v19.0.0	Метод закрывает неактивные соединения перед возвратом.
v0.1.90	Добавлено в: v0.1.90

• callback <Function>

Останавливает сервер от принятия новых соединений и закрывает все соединения, подключенные к этому серверу, которые не отправляют запрос или не ожидают ответа. См. net.Server.close().

const http = require('node:http')

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Hello World!',
    })
  )
})

server.listen(8000)
// Закрыть сервер через 10 секунд
setTimeout(() => {
  server.close(() => {
    console.log('Сервер на порту 8000 успешно закрыт')
  })
}, 10000)

server.closeAllConnections()

Добавлено в: v18.2.0

Закрывает все установленные HTTP(S) соединения, подключенные к этому серверу, включая активные соединения, подключенные к этому серверу, которые отправляют запрос или ожидают ответа. Это не уничтожает сокеты, обновленные до другого протокола, такого как WebSocket или HTTP/2.

const http = require('node:http')

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Hello World!',
    })
  )
})

server.listen(8000)
// Закрыть сервер через 10 секунд
setTimeout(() => {
  server.close(() => {
    console.log('Сервер на порту 8000 успешно закрыт')
  })
  // Закрывает все соединения, обеспечивая успешное закрытие сервера
  server.closeAllConnections()
}, 10000)

server.closeIdleConnections()

Добавлено в: v18.2.0

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

const http = require('node:http')

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Hello World!',
    })
  )
})

server.listen(8000)
// Закрыть сервер через 10 секунд
setTimeout(() => {
  server.close(() => {
    console.log('Сервер на порту 8000 успешно закрыт')
  })
  // Закрывает неактивные соединения, такие как соединения keep-alive. Сервер закроется,
  // как только оставшиеся активные соединения будут завершены
  server.closeIdleConnections()
}, 10000)

server.headersTimeout

[История]

Версия	Изменения
v19.4.0, v18.14.0	Теперь по умолчанию устанавливается минимальное значение между 60000 (60 секунд) или requestTimeout.
v11.3.0, v10.14.0	Добавлено в: v11.3.0, v10.14.0

• <число> По умолчанию: Минимальное значение между server.requestTimeout или 60000.

Ограничивает время ожидания парсером получения полных HTTP-заголовков.

Если время ожидания истекает, сервер отвечает статусом 408, не перенаправляя запрос обработчику запросов, а затем закрывает соединение.

Должно быть установлено ненулевое значение (например, 120 секунд) для защиты от потенциальных атак типа «отказ в обслуживании», если сервер развернут без обратного прокси-сервера.

server.listen()

Запускает HTTP-сервер для прослушивания соединений. Этот метод идентичен server.listen() из net.Server.

server.listening

Добавлено в: v5.7.0

• <булево> Указывает, прослушивает ли сервер соединения.

server.maxHeadersCount

Добавлено в: v0.7.0

• <число> По умолчанию: 2000

Ограничивает максимальное количество входящих заголовков. Если установлено значение 0, ограничение применяться не будет.

server.requestTimeout

[История]

Версия	Изменения
v18.0.0	Время ожидания запроса по умолчанию изменено с неограниченного на 300 с (5 минут).
v14.11.0	Добавлено в: v14.11.0

• <число> По умолчанию: 300000

Устанавливает значение тайм-аута в миллисекундах для получения всего запроса от клиента.

Если время ожидания истекает, сервер отвечает статусом 408, не перенаправляя запрос обработчику запросов, а затем закрывает соединение.

Должно быть установлено ненулевое значение (например, 120 секунд) для защиты от потенциальных атак типа «отказ в обслуживании», если сервер развернут без обратного прокси-сервера.

server.setTimeout([msecs][, callback])

[История]

Версия	Изменения
v13.0.0	Значение тайм-аута по умолчанию изменено с 120 с на 0 (без тайм-аута).
v0.9.12	Добавлено в: v0.9.12

• msecs <число> По умолчанию: 0 (без тайм-аута)
• callback <Функция>
• Возвращает: <http.Server>

Устанавливает значение тайм-аута для сокетов и генерирует событие 'timeout' в объекте Server, передавая сокет в качестве аргумента, если происходит тайм-аут.

Если в объекте Server есть обработчик события 'timeout', то он будет вызван с тайм-аутным сокетом в качестве аргумента.

По умолчанию сервер не устанавливает тайм-аут для сокетов. Однако, если обработчик назначен событию 'timeout' сервера, тайм-ауты должны обрабатываться явно.

server.maxRequestsPerSocket

Добавлено в: v16.10.0

• <число> Запросов на сокет. По умолчанию: 0 (без ограничения)

Максимальное количество запросов, которые сокет может обработать перед закрытием соединения keep alive.

Значение 0 отключит ограничение.

Когда достигается лимит, значение заголовка Connection устанавливается в close, но само соединение фактически не закрывается; последующие запросы, отправленные после достижения лимита, получат ответ 503 Service Unavailable.

server.timeout

[История]

Версия	Изменения
v13.0.0	Значение тайм-аута по умолчанию изменено с 120 с на 0 (без тайм-аута).
v0.9.12	Добавлено в: v0.9.12

• <число> Тайм-аут в миллисекундах. По умолчанию: 0 (без тайм-аута)

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

Значение 0 отключит поведение тайм-аута для входящих подключений.

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

server.keepAliveTimeout

Добавлено в: v8.0.0

• <число> Время ожидания в миллисекундах. По умолчанию: 5000 (5 секунд).

Количество миллисекунд бездействия, которое сервер должен ожидать дополнительных входящих данных после завершения записи последнего ответа, прежде чем сокет будет закрыт. Если сервер получит новые данные до истечения времени ожидания keep-alive, он сбросит обычное время ожидания бездействия, то есть server.timeout.

Значение 0 отключит поведение времени ожидания keep-alive для входящих соединений. Значение 0 заставит HTTP-сервер вести себя аналогично версиям Node.js до 8.0.0, в которых не было времени ожидания keep-alive.

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

server[Symbol.asyncDispose]()

Добавлено в: v20.4.0

[Стабильно: 1 - Экспериментально]

Стабильно: 1 Стабильность: 1 - Экспериментально

Вызывает server.close() и возвращает promise, который выполняется после закрытия сервера.

Класс: http.ServerResponse

Добавлено в: v0.1.17

• Расширяет: <http.OutgoingMessage>

Этот объект создается внутренне HTTP-сервером, а не пользователем. Он передается как второй параметр событию 'request'.

Событие: 'close'

Добавлено в: v0.6.7

Указывает на то, что ответ завершен или его базовое соединение было преждевременно разорвано (до завершения ответа).

Событие: 'finish'

Добавлено в: v0.3.6

Генерируется, когда ответ отправлен. Точнее, это событие генерируется, когда последний сегмент заголовков и тела ответа передан операционной системе для передачи по сети. Это не означает, что клиент уже что-то получил.

response.addTrailers(headers)

Добавлено в: v0.3.0

• headers <Object>

Этот метод добавляет к ответу HTTP-заголовки-трайлеры (заголовок, но в конце сообщения).

Трайлеры будут отправляться только в случае использования чанкового кодирования для ответа; если это не так (например, если запрос был HTTP/1.0), они будут молча отброшены.

HTTP требует отправки заголовка Trailer для отправки трайлеров, со списком полей заголовков в его значении. Например:

response.writeHead(200, { 'Content-Type': 'text/plain', Trailer: 'Content-MD5' })
response.write(fileData)
response.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' })
response.end()

Попытка установить имя поля заголовка или значение, содержащее недопустимые символы, приведет к возникновению ошибки TypeError.

response.connection

Добавлено в: v0.3.0

Устарело с: v13.0.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте response.socket.

• <stream.Duplex>

См. response.socket.

response.cork()

Добавлено в: v13.2.0, v12.16.0

См. writable.cork().

response.end([data[, encoding]][, callback])

[История]

Версия	Изменения
v15.0.0	Параметр data теперь может быть Uint8Array.
v10.0.0	Этот метод теперь возвращает ссылку на ServerResponse.
v0.1.90	Добавлено в: v0.1.90

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Возвращает: <this>

Этот метод сигнализирует серверу о том, что все заголовки и тело ответа отправлены; сервер должен считать это сообщение полным. Метод response.end() ДОЛЖЕН вызываться для каждого ответа.

Если указан data, это аналогично вызову response.write(data, encoding) с последующим вызовом response.end(callback).

Если указан callback, он будет вызван по завершении потока ответа.

response.finished

Добавлен в: v0.0.2

Устарел с: v13.4.0, v12.16.0

[Стабильность: 0 - Устарел]

Стабильность: 0 Стабильность: 0 - Устарел. Используйте response.writableEnded.

• <boolean>

Свойство response.finished будет иметь значение true, если был вызван метод response.end().

response.flushHeaders()

Добавлен в: v1.6.0

Сбрасывает заголовки ответа. См. также: request.flushHeaders().

response.getHeader(name)

Добавлен в: v0.4.0

• name <string>
• Возвращает: <any>

Считывает заголовок, который уже был помещён в очередь, но не отправлен клиенту. Название нечувствительно к регистру. Тип возвращаемого значения зависит от аргументов, переданных в response.setHeader().

response.setHeader('Content-Type', 'text/html')
response.setHeader('Content-Length', Buffer.byteLength(body))
response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript'])
const contentType = response.getHeader('content-type')
// contentType равно 'text/html'
const contentLength = response.getHeader('Content-Length')
// contentLength имеет тип number
const setCookie = response.getHeader('set-cookie')
// setCookie имеет тип string[]

response.getHeaderNames()

Добавлен в: v7.7.0

• Возвращает: <string[]>

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

response.setHeader('Foo', 'bar')
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz'])

const headerNames = response.getHeaderNames()
// headerNames === ['foo', 'set-cookie']

response.getHeaders()

Добавлено в: v7.7.0

• Возвращает: <Object>

Возвращает неглубокую копию текущих исходящих заголовков. Поскольку используется неглубокая копия, значения массива могут быть изменены без дополнительных вызовов различных методов модуля http, связанных с заголовками. Ключи возвращаемого объекта — это имена заголовков, а значения — соответствующие значения заголовков. Все имена заголовков строчные.

Объект, возвращаемый методом response.getHeaders(), не наследуется прототипически от JavaScript Object. Это означает, что типичные методы Object, такие как obj.toString(), obj.hasOwnProperty() и другие, не определены и не будут работать.

response.setHeader('Foo', 'bar')
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz'])

const headers = response.getHeaders()
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }

response.hasHeader(name)

Добавлено в: v7.7.0

• name <string>
• Возвращает: <boolean>

Возвращает true, если заголовок, идентифицированный по name, в данный момент установлен в исходящих заголовках. Сопоставление имен заголовков нечувствительно к регистру.

const hasContentType = response.hasHeader('content-type')

response.headersSent

Добавлено в: v0.9.3

• <boolean>

Логическое значение (только для чтения). True, если заголовки были отправлены, false — в противном случае.

response.removeHeader(name)

Добавлено в: v0.4.0

• name <string>

Удаляет заголовок, который находится в очереди для неявной отправки.

response.removeHeader('Content-Encoding')

response.req

Добавлено в: v15.7.0

• <http.IncomingMessage>

Ссылка на исходный объект HTTP request.

response.sendDate

Добавлен в: v0.7.5

• <boolean>

Если значение true, заголовок Date будет автоматически генерироваться и отправляться в ответе, если он ещё не присутствует в заголовках. По умолчанию — true.

Это следует отключать только для тестирования; HTTP требует заголовок Date в ответах.

response.setHeader(name, value)

Добавлен в: v0.4.0

• name <string>
• value <any>
• Возвращает: <http.ServerResponse>

Возвращает объект ответа.

Устанавливает одно значение заголовка для неявных заголовков. Если этот заголовок уже существует в отправляемых заголовках, его значение будет заменено. Используйте массив строк здесь, чтобы отправить несколько заголовков с одним и тем же именем. Нестроковые значения будут храниться без изменений. Поэтому response.getHeader() может возвращать нестроковые значения. Однако нестроковые значения будут преобразованы в строки для передачи по сети. Вызывающему объекту возвращается тот же объект ответа, чтобы включить цепочку вызовов.

response.setHeader('Content-Type', 'text/html')

или

response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript'])

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

Когда заголовки были установлены с помощью response.setHeader(), они будут объединены с любыми заголовками, переданными в response.writeHead(), при этом заголовки, переданные в response.writeHead(), будут иметь приоритет.

// Возвращает content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html')
  res.setHeader('X-Foo', 'bar')
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('ok')
})

Если вызывается метод response.writeHead() и этот метод не был вызван, он напрямую запишет предоставленные значения заголовков в сетевой канал без внутреннего кэширования, и response.getHeader() для заголовка не даст ожидаемого результата. Если желательно поэтапное заполнение заголовков с потенциальным будущим извлечением и изменением, используйте response.setHeader() вместо response.writeHead().

response.setTimeout(msecs[, callback])

Добавлено в: v0.9.12

• msecs <number>
• callback <Function>
• Возвращает: <http.ServerResponse>

Устанавливает значение тайм-аута сокета в msecs. Если указан обратный вызов, то он добавляется как обработчик события 'timeout' для объекта ответа.

Если обработчик события 'timeout' не добавлен к запросу, ответу или серверу, то сокеты уничтожаются по истечении времени ожидания. Если обработчик назначен событиям 'timeout' запроса, ответа или сервера, то по истечении времени ожидания сокетами необходимо управлять явно.

response.socket

Добавлено в: v0.3.0

• <stream.Duplex>

Ссылка на базовый сокет. Обычно пользователям не нужно обращаться к этому свойству. В частности, сокет не будет генерировать события 'readable' из-за того, как парсер протокола подключается к сокету. После response.end() свойство устанавливается в значение null.

ESM

import http from 'node:http'
const server = http
  .createServer((req, res) => {
    const ip = res.socket.remoteAddress
    const port = res.socket.remotePort
    res.end(`Ваш IP-адрес: ${ip}, порт источника: ${port}.`)
  })
  .listen(3000)

CJS

const http = require('node:http')
const server = http
  .createServer((req, res) => {
    const ip = res.socket.remoteAddress
    const port = res.socket.remotePort
    res.end(`Ваш IP-адрес: ${ip}, порт источника: ${port}.`)
  })
  .listen(3000)

Гарантируется, что это свойство является экземпляром класса <net.Socket>, подкласса <stream.Duplex>, если пользователь не указал тип сокета, отличный от <net.Socket>.

response.statusCode

Добавлено в: v0.4.0

• <number> По умолчанию: 200

При использовании неявных заголовков (без явного вызова response.writeHead()) это свойство управляет кодом состояния, который будет отправлен клиенту при очистке заголовков.

response.statusCode = 404

После отправки заголовка ответа клиенту это свойство указывает отправленный код состояния.

response.statusMessage

Добавлено в: v0.11.8

• <строка>

При использовании неявных заголовков (без явного вызова response.writeHead()), это свойство управляет сообщением о состоянии, которое будет отправлено клиенту при очистке заголовков. Если оно оставлено как undefined, будет использовано стандартное сообщение для кода состояния.

response.statusMessage = 'Not found'

После отправки заголовка ответа клиенту это свойство указывает отправленное сообщение о состоянии.

response.strictContentLength

Добавлено в: v18.10.0, v16.18.0

• <логическое> По умолчанию: false

Если установлено в true, Node.js проверит, совпадают ли значение заголовка Content-Length и размер тела в байтах. Несовпадение значения заголовка Content-Length приведёт к выбросу ошибки Error, идентифицируемой по code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

response.uncork()

Добавлено в: v13.2.0, v12.16.0

См. writable.uncork().

response.writableEnded

Добавлено в: v12.9.0

• <логическое>

Имеет значение true после вызова response.end(). Это свойство не указывает, были ли данные очищены; для этого используйте response.writableFinished.

response.writableFinished

Добавлено в: v12.7.0

• <логическое>

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

response.write(chunk[, encoding][, callback])

[История]

Версия	Изменения
v15.0.0	Параметр chunk теперь может быть Uint8Array.
v0.1.29	Добавлено в: v0.1.29

• chunk <строка> | <Buffer> | <Uint8Array>
• encoding <строка> По умолчанию: 'utf8'
• callback <Функция>
• Возвращает: <логическое>

Если этот метод вызывается, а response.writeHead() не был вызван, он переключится в режим неявных заголовков и очистит неявные заголовки.

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

Если rejectNonStandardBodyWrites установлен в true в createServer, запись в тело запрещена, если метод запроса или статус ответа не поддерживают содержимое. Если предпринята попытка записи в тело для запроса HEAD или как часть ответа 204 или 304, синхронно выбрасывается ошибка Error с кодом ERR_HTTP_BODY_NOT_ALLOWED.

chunk может быть строкой или буфером. Если chunk — строка, второй параметр указывает, как кодировать её в байтовый поток. callback будет вызван после очистки этого фрагмента данных.

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

При первом вызове response.write() будет отправлена буферизованная информация о заголовке и первый фрагмент тела клиенту. При втором вызове response.write() Node.js предполагает, что данные будут передаваться потоком, и отправляет новые данные отдельно. То есть ответ буферизуется до первого фрагмента тела.

Возвращает true, если все данные были успешно очищены в буфер ядра. Возвращает false, если все или часть данных были помещены в очередь в пользовательской памяти. 'drain' будет отправлено, когда буфер снова освободится.

response.writeContinue()

Добавлено в: v0.3.0

Отправляет клиенту сообщение HTTP/1.1 100 Continue, указывающее, что тело запроса должно быть отправлено. См. событие 'checkContinue' в Server.

response.writeEarlyHints(hints[, callback])

[История]

Версия	Изменения
v18.11.0	Разрешено передавать подсказки в виде объекта.
v18.11.0	Добавлено в: v18.11.0

• hints <Объект>
• callback <Функция>

Отправляет клиенту сообщение HTTP/1.1 103 Early Hints с заголовком Link, указывающее, что пользовательский агент может предварительно загрузить/предварительно подключиться к связанным ресурсам. hints — это объект, содержащий значения заголовков, которые необходимо отправить с сообщением early hints. Необязательный аргумент callback будет вызван после того, как сообщение ответа будет записано.

Пример

const earlyHintsLink = '</styles.css>; rel=preload; as=style'
response.writeEarlyHints({
  link: earlyHintsLink,
})

const earlyHintsLinks = ['</styles.css>; rel=preload; as=style', '</scripts.js>; rel=preload; as=script']
response.writeEarlyHints({
  link: earlyHintsLinks,
  'x-trace-id': 'id for diagnostics',
})

const earlyHintsCallback = () => console.log('early hints message sent')
response.writeEarlyHints(
  {
    link: earlyHintsLinks,
  },
  earlyHintsCallback
)

response.writeHead(statusCode[, statusMessage][, headers])

[История]

Версия	Изменения
v14.14.0	Разрешено передавать заголовки в виде массива.
v11.10.0, v10.17.0	Возвращает this из writeHead(), чтобы разрешить связывание с end().
v5.11.0, v4.4.5	Возбуждается RangeError, если statusCode не является числом в диапазоне [100, 999].
v0.1.30	Добавлено в: v0.1.30

• statusCode <число>
• statusMessage <строка>
• headers <Объект> | <Массив>
• Возвращает: <http.ServerResponse>

Отправляет заголовок ответа на запрос. Код состояния — это 3-значный код состояния HTTP, например, 404. Последний аргумент, headers, — это заголовки ответа. Дополнительно можно указать понятное человеку сообщение statusMessage во втором аргументе.

headers может быть Array, где ключи и значения находятся в одном списке. Это не список кортежей. Таким образом, четные смещения — это значения ключей, а нечетные смещения — связанные с ними значения. Массив имеет тот же формат, что и request.rawHeaders.

Возвращает ссылку на ServerResponse, чтобы можно было связывать вызовы.

const body = 'hello world'
response
  .writeHead(200, {
    'Content-Length': Buffer.byteLength(body),
    'Content-Type': 'text/plain',
  })
  .end(body)

Этот метод должен вызываться только один раз для сообщения, и он должен быть вызван до вызова response.end().

Если response.write() или response.end() вызываются до вызова этого метода, неявные/изменяемые заголовки будут вычислены, и этот метод будет вызван.

Когда заголовки установлены с помощью response.setHeader(), они будут объединены с любыми заголовками, переданными в response.writeHead(), при этом заголовки, переданные в response.writeHead(), имеют приоритет.

Если этот метод вызывается, а response.setHeader() не вызывался, он напрямую запишет предоставленные значения заголовков в сетевой канал без внутреннего кэширования, и response.getHeader() для заголовка не будет давать ожидаемый результат. Если требуется поэтапное заполнение заголовков с потенциальным будущим извлечением и изменением, используйте вместо этого response.setHeader().

// Возвращает content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html')
  res.setHeader('X-Foo', 'bar')
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('ok')
})

Content-Length читается в байтах, а не в символах. Используйте Buffer.byteLength() для определения длины тела в байтах. Node.js проверит, равны ли Content-Length и длина переданного тела или нет.

Попытка установить имя или значение поля заголовка, содержащее недопустимые символы, приведет к возбуждению исключения [Error][].

response.writeProcessing()

Добавлено в: v10.0.0

Отправляет клиенту сообщение HTTP/1.1 102 Processing, указывая, что тело запроса должно быть отправлено.

Класс: http.IncomingMessage

[История]

Версия	Изменения
v15.5.0	Значение destroyed возвращает true после того, как входящие данные обработаны.
v13.1.0, v12.16.0	Значение readableHighWaterMark отражает значение сокета.
v0.1.17	Добавлено в: v0.1.17

• Расширяет: <stream.Readable>

Объект IncomingMessage создается http.Server или http.ClientRequest и передается в качестве первого аргумента событиям 'request' и 'response' соответственно. Он может использоваться для доступа к статусу ответа, заголовкам и данным.

В отличие от своего значения socket, которое является подклассом <stream.Duplex>, сам IncomingMessage расширяет <stream.Readable> и создается отдельно для анализа и излучения входящих HTTP-заголовков и полезной нагрузки, поскольку базовый сокет может многократно использоваться в случае keep-alive.

Событие: 'aborted'

Добавлено в: v0.3.8

Устарело с: v17.0.0, v16.12.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте событие 'close' вместо этого.

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

Событие: 'close'

[История]

Версия	Изменения
v16.0.0	Событие close теперь генерируется, когда запрос завершен, а не когда закрыт базовый сокет.
v0.4.2	Добавлено в: v0.4.2

Генерируется, когда запрос завершен.

message.aborted

Добавлено в: v10.1.0

Устарело с: v17.0.0, v16.12.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Проверьте message.destroyed из <stream.Readable>.

• <boolean>

Свойство message.aborted будет равно true, если запрос был прерван.

message.complete

Добавлено в: v0.3.0

• <boolean>

Свойство message.complete будет иметь значение true, если полное HTTP-сообщение было получено и успешно разобрано.

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

const req = http.request(
  {
    host: '127.0.0.1',
    port: 8080,
    method: 'POST',
  },
  res => {
    res.resume()
    res.on('end', () => {
      if (!res.complete) console.error('Соединение было прервано, пока сообщение еще отправлялось')
    })
  }
)

message.connection

Добавлено в: v0.1.90

Устарело с: v16.0.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте message.socket.

Псевдоним для message.socket.

message.destroy([error])

[История]

Версия	Изменения
v14.5.0, v12.19.0	Функция возвращает this для согласованности с другими потоками Readable.
v0.3.0	Добавлено в: v0.3.0

• error <Error>
• Возвращает: <this>

Вызывает destroy() на сокете, который получил IncomingMessage. Если указан error, событие 'error' генерируется на сокете, и error передается в качестве аргумента любым слушателям этого события.

message.headers

[История]

Версия	Изменения
v19.5.0, v18.14.0	Опция joinDuplicateHeaders в функциях http.request() и http.createServer() гарантирует, что дубликаты заголовков не отбрасываются, а объединяются с помощью разделителя запятой в соответствии с RFC 9110 Section 5.3.
v15.1.0	message.headers теперь вычисляется лениво с использованием свойства-аксессора в прототипе и больше не является перечисляемым.
v0.1.5	Добавлено в: v0.1.5

• <Object>

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

Пары «ключ-значение» имен и значений заголовков. Имена заголовков приведены к нижнему регистру.

// Выводит что-то вроде:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers)

Дубликаты в необработанных заголовках обрабатываются следующим образом, в зависимости от имени заголовка:

• Дубликаты age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer, retry-after, server или user-agent отбрасываются. Чтобы разрешить объединение дублирующих значений перечисленных выше заголовков, используйте опцию joinDuplicateHeaders в http.request() и http.createServer(). См. RFC 9110 Section 5.3 для получения дополнительной информации.
• set-cookie всегда является массивом. Дубликаты добавляются в массив.
• Для дубликатов заголовков cookie значения объединяются с помощью ; .
• Для всех остальных заголовков значения объединяются с помощью , .

message.headersDistinct

Добавлено в: v18.3.0, v16.17.0

• <Object>

Аналогично message.headers, но без логики объединения, и значения всегда являются массивами строк, даже для заголовков, полученных только один раз.

// Выводит что-то вроде:
//
// { 'user-agent': ['curl/7.22.0'],
//   host: ['127.0.0.1:8000'],
//   accept: ['*/*'] }
console.log(request.headersDistinct)

message.httpVersion

Добавлено в: v0.1.1

• <string>

В случае серверного запроса — версия HTTP, отправленная клиентом. В случае клиентского ответа — версия HTTP подключенного сервера. Вероятно, либо '1.1', либо '1.0'.

Также message.httpVersionMajor — это первое целое число, а message.httpVersionMinor — второе.

message.method

Добавлено в: v0.1.1

• <string>

Действительно только для запроса, полученного от http.Server.

Метод запроса в виде строки. Только для чтения. Примеры: 'GET', 'DELETE'.

message.rawHeaders

Добавлено в: v0.11.6

• <string[]>

Список необработанных заголовков запроса/ответа точно так, как они были получены.

Ключи и значения находятся в одном списке. Это не список кортежей. Таким образом, четные смещения — это значения ключей, а нечетные смещения — соответствующие значения.

Имена заголовков не приводятся к нижнему регистру, и дубликаты не объединяются.

// Выводит что-то вроде:
//
// [ 'user-agent',
//   'this is invalid because there can be only one',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders)

message.rawTrailers

Добавлено в: v0.11.6

• <string[]>

Необработанные ключи и значения прицепов запроса/ответа точно так, как они были получены. Заполняется только в событии 'end'.

message.setTimeout(msecs[, callback])

Добавлено в: v0.5.9

• msecs <number>
• callback <Function>
• Возвращает: <http.IncomingMessage>

Вызывает message.socket.setTimeout(msecs, callback).

message.socket

Добавлено в: v0.3.0

• <stream.Duplex>

Объект net.Socket, связанный с соединением.

При поддержке HTTPS используйте request.socket.getPeerCertificate() для получения сведений об аутентификации клиента.

Гарантируется, что это свойство является экземпляром класса <net.Socket>, подкласса <stream.Duplex>, если пользователь не указал тип сокета, отличный от <net.Socket>, или он не был внутренне обнулен.

message.statusCode

Добавлено в: v0.1.1

• <number>

Действительно только для ответа, полученного от http.ClientRequest.

Трехзначный код состояния HTTP-ответа. Например, 404.

message.statusMessage

Добавлено в: v0.11.10

• <string>

Действительно только для ответа, полученного от http.ClientRequest.

Сообщение состояния HTTP-ответа (описательная фраза). Например, OK или Internal Server Error.

message.trailers

Добавлено в: v0.3.0

• <Object>

Объект заголовков запроса/ответа. Заполняется только в событии 'end'.

message.trailersDistinct

Добавлено в: v18.3.0, v16.17.0

• <Object>

Аналогично message.trailers, но отсутствует логика объединения, и значения всегда являются массивами строк, даже для заголовков, полученных только один раз. Заполняется только в событии 'end'.

message.url

Добавлен в: v0.1.90

• <string>

Действителен только для запросов, полученных из http.Server.

Строка URL запроса. Содержит только URL, присутствующий в фактическом HTTP-запросе. Возьмем следующий запрос:

GET /status?name=ryan HTTP/1.1 Accept: text/plain

Для разбора URL на его части:

new URL(`http://${process.env.HOST ?? 'localhost'}${request.url}`)

Когда request.url равно '/status?name=ryan', а process.env.HOST не определено:

$ node
> new URL(`http://${process.env.HOST ?? 'localhost'}${request.url}`);
URL {
  href: 'http://localhost/status?name=ryan',
  origin: 'http://localhost',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'localhost',
  hostname: 'localhost',
  port: '',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
}

Убедитесь, что вы установили process.env.HOST в имя хоста сервера или рассмотрите возможность полного замены этой части. При использовании req.headers.host обеспечьте надлежащую проверку, так как клиенты могут указывать настраиваемый заголовок Host.

Класс: http.OutgoingMessage

Добавлен в: v0.1.17

• Расширяет: <Stream>

Этот класс служит родительским классом для http.ClientRequest и http.ServerResponse. Это абстрактное исходящее сообщение с точки зрения участников HTTP-транзакции.

Событие: 'drain'

Добавлен в: v0.3.6

Вызывается, когда буфер сообщения снова освобождается.

Событие: 'finish'

Добавлен в: v0.1.17

Вызывается при успешном завершении передачи.

Событие: 'prefinish'

Добавлен в: v0.11.6

Вызывается после вызова outgoingMessage.end(). Когда событие вызывается, все данные обработаны, но не обязательно полностью очищены.

outgoingMessage.addTrailers(headers)

Добавлен в: v0.3.0

• headers <Object>

Добавляет HTTP-трайлеры (заголовки, но в конце сообщения) к сообщению.

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

HTTP требует отправки заголовка Trailer для отправки трайлеров со списком имен полей заголовка в его значении, например:

message.writeHead(200, { 'Content-Type': 'text/plain', Trailer: 'Content-MD5' })
message.write(fileData)
message.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' })
message.end()

Попытка установить имя поля заголовка или значение, содержащее недопустимые символы, приведет к возникновению ошибки TypeError.

outgoingMessage.appendHeader(name, value)

Добавлен в: v18.3.0, v16.17.0

• name <string> Имя заголовка
• value <string> | <string[]> Значение заголовка
• Возвращает: <this>

Добавляет одно значение заголовка к объекту заголовка.

Если значение является массивом, это эквивалентно многократному вызову этого метода.

Если ранее не было значений для заголовка, это эквивалентно вызову outgoingMessage.setHeader(name, value).

В зависимости от значения options.uniqueHeaders при создании клиентского запроса или сервера, это приведет к многократной отправке заголовка или к однократной отправке со значениями, объединенными с помощью ; .

outgoingMessage.connection

Добавлен в: v0.3.0

Устарел с: v15.12.0, v14.17.1

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело: Используйте outgoingMessage.socket вместо этого.

Псевдоним outgoingMessage.socket.

outgoingMessage.cork()

Добавлено в: v13.2.0, v12.16.0

См. writable.cork().

outgoingMessage.destroy([error])

Добавлено в: v0.3.0

• error <Error> Необязательно, ошибка для генерации события error
• Возвращает: <this>

Уничтожает сообщение. После того, как сокет связан с сообщением и подключен, этот сокет также будет уничтожен.

outgoingMessage.end(chunk[, encoding][, callback])

[История]

Версия	Изменения
v15.0.0	Параметр chunk теперь может быть Uint8Array.
v0.11.6	Добавлен аргумент callback.
v0.1.90	Добавлено в: v0.1.90

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> Необязательно, По умолчанию: utf8
• callback <Function> Необязательно
• Возвращает: <this>

Завершает исходящее сообщение. Если какие-либо части тела не отправлены, они будут отправлены в базовую систему. Если сообщение разбито на части, оно отправит завершающий фрагмент 0\r\n\r\n и отправит трейлеры (если таковые имеются).

Если указан chunk, это эквивалентно вызову outgoingMessage.write(chunk, encoding), за которым следует outgoingMessage.end(callback).

Если предоставлен callback, он будет вызван по завершении сообщения (эквивалентно прослушивателю события 'finish').

outgoingMessage.flushHeaders()

Добавлено в: v1.6.0

Сбрасывает заголовки сообщения.

В целях повышения эффективности Node.js обычно буферизует заголовки сообщений до вызова outgoingMessage.end() или записи первого фрагмента данных сообщения. Затем он пытается упаковать заголовки и данные в один TCP-пакет.

Обычно это желательно (это экономит TCP-обмен), но не тогда, когда первые данные не отправляются до гораздо более позднего времени. outgoingMessage.flushHeaders() обходит оптимизацию и запускает сообщение.

outgoingMessage.getHeader(name)

Добавлено в: v0.4.0

• name <string> Имя заголовка
• Возвращает: <string> | <undefined>

Получает значение HTTP-заголовка с заданным именем. Если этот заголовок не установлен, возвращаемое значение будет undefined.

outgoingMessage.getHeaderNames()

Добавлено в: v7.7.0

• Возвращает: <string[]>

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

outgoingMessage.getHeaders()

Добавлено в: v7.7.0

• Возвращает: <Object>

Возвращает неглубокую копию текущих исходящих заголовков. Поскольку используется неглубокая копия, значения массива могут быть изменены без дополнительных вызовов различных методов HTTP-модуля, связанных с заголовками. Ключи возвращаемого объекта — это имена заголовков, а значения — соответствующие значения заголовков. Все имена заголовков строчные.

Объект, возвращаемый методом outgoingMessage.getHeaders(), не наследуется прототипически от JavaScript Object. Это означает, что типичные методы Object, такие как obj.toString(), obj.hasOwnProperty() и другие, не определены и работать не будут.

outgoingMessage.setHeader('Foo', 'bar')
outgoingMessage.setHeader('Set-Cookie', ['foo=bar', 'bar=baz'])

const headers = outgoingMessage.getHeaders()
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }

outgoingMessage.hasHeader(name)

Добавлено в: v7.7.0

• name <string>
• Возвращает: <boolean>

Возвращает true, если заголовок, идентифицированный по name, в данный момент установлен в исходящих заголовках. Имя заголовка нечувствительно к регистру.

const hasContentType = outgoingMessage.hasHeader('content-type')

outgoingMessage.headersSent

Добавлено в: v0.9.3

• <boolean>

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

outgoingMessage.pipe()

Добавлено в: v9.0.0

Переопределяет метод stream.pipe(), унаследованный от устаревшего класса Stream, который является родительским классом http.OutgoingMessage.

Вызов этого метода вызовет ошибку Error, поскольку outgoingMessage является потоком только для записи.

outgoingMessage.removeHeader(name)

Добавлено в: v0.4.0

• name <string> Имя заголовка

Удаляет заголовок, который находится в очереди для неявной отправки.

outgoingMessage.removeHeader('Content-Encoding')

outgoingMessage.setHeader(name, value)

Добавлено в: v0.4.0

• name <string> Имя заголовка
• value <any> Значение заголовка
• Возвращает: <this>

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

outgoingMessage.setHeaders(headers)

Добавлено в: v19.6.0, v18.15.0

• headers <Headers> | <Map>
• Возвращает: <this>

Устанавливает несколько значений заголовков для неявных заголовков. headers должен быть экземпляром Headers или Map, если заголовок уже существует в заголовках, которые будут отправлены, его значение будет заменено.

const headers = new Headers({ foo: 'bar' })
outgoingMessage.setHeaders(headers)

или

const headers = new Map([['foo', 'bar']])
outgoingMessage.setHeaders(headers)

Когда заголовки были установлены с помощью outgoingMessage.setHeaders(), они будут объединены с любыми заголовками, переданными в response.writeHead(), при этом заголовки, переданные в response.writeHead(), будут иметь приоритет.

// Возвращает content-type = text/plain
const server = http.createServer((req, res) => {
  const headers = new Headers({ 'Content-Type': 'text/html' })
  res.setHeaders(headers)
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('ok')
})

outgoingMessage.setTimeout(msesc[, callback])

Добавлено в: v0.9.12

• msesc <number>
• callback <Function> Необязательная функция, вызываемая при возникновении тайм-аута. Аналогично привязке к событию timeout.
• Возвращает: <this>

После того, как сокет связан с сообщением и подключен, socket.setTimeout() будет вызван с msecs в качестве первого параметра.

outgoingMessage.socket

Добавлено в: v0.3.0

• <stream.Duplex>

Ссылка на базовый сокет. Как правило, пользователям не потребуется доступ к этому свойству.

После вызова outgoingMessage.end() это свойство будет установлено в значение null.

outgoingMessage.uncork()

Добавлено в: v13.2.0, v12.16.0

См. writable.uncork()

outgoingMessage.writableCorked

Добавлено в: v13.2.0, v12.16.0

• <number>

Количество вызовов outgoingMessage.cork().

outgoingMessage.writableEnded

Добавлено в: v12.9.0

• <boolean>

Имеет значение true, если был вызван outgoingMessage.end(). Это свойство не указывает на то, были ли данные очищены. Для этой цели используйте message.writableFinished.

outgoingMessage.writableFinished

Добавлено в: v12.7.0

• <boolean>

Имеет значение true, если все данные были очищены в базовой системе.

outgoingMessage.writableHighWaterMark

Добавлено в: v12.9.0

• <number>

highWaterMark базового сокета, если назначен. В противном случае, уровень буфера по умолчанию, когда writable.write() начинает возвращать false (16384).

outgoingMessage.writableLength

Добавлено в: v12.9.0

• <number>

Количество буферизованных байтов.

outgoingMessage.writableObjectMode

Добавлено в: v12.9.0

• <boolean>

Всегда false.

outgoingMessage.write(chunk[, encoding][, callback])

[История]

Версия	Изменения
v15.0.0	Параметр chunk теперь может быть Uint8Array.
v0.11.6	Добавлен аргумент callback.
v0.1.29	Добавлено в: v0.1.29

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> По умолчанию: utf8
• callback <Function>
• Возвращает: <boolean>

Отправляет фрагмент тела. Этот метод можно вызывать несколько раз.

Аргумент encoding актуален только тогда, когда chunk является строкой. По умолчанию используется 'utf8'.

Аргумент callback является необязательным и будет вызван, когда этот фрагмент данных будет очищен.

Возвращает true, если все данные были успешно очищены в буфер ядра. Возвращает false, если все или часть данных были помещены в очередь в памяти пользователя. Событие 'drain' будет вызвано, когда буфер снова освободится.

http.METHODS

Добавлено в: v0.11.8

• <string[]>

Список HTTP-методов, поддерживаемых парсером.

http.STATUS_CODES

Добавлено в: v0.1.22

• <Object>

Коллекция всех стандартных кодов состояния HTTP-ответа и краткое описание каждого из них. Например, http.STATUS_CODES[404] === 'Not Found'.

http.createServer([options][, requestListener])

[История]

Версия	Изменения
v20.1.0, v18.17.0	Теперь поддерживается параметр highWaterMark.
v18.0.0	Теперь поддерживаются параметры requestTimeout, headersTimeout, keepAliveTimeout и connectionsCheckingInterval.
v18.0.0	Параметр noDelay теперь по умолчанию имеет значение true.
v17.7.0, v16.15.0	Теперь поддерживаются параметры noDelay, keepAlive и keepAliveInitialDelay.
v13.3.0	Теперь поддерживается параметр maxHeaderSize.
v13.8.0, v12.15.0, v10.19.0	Теперь поддерживается параметр insecureHTTPParser.
v9.6.0, v8.12.0	Теперь поддерживается аргумент options.
v0.1.13	Добавлено в: v0.1.13

• options <Object>

  • connectionsCheckingInterval: Задает интервал в миллисекундах для проверки таймаутов запроса и заголовков в неполных запросах. По умолчанию: 30000.
  • headersTimeout: Задает значение таймаута в миллисекундах для получения полных HTTP-заголовков от клиента. Дополнительные сведения см. в разделе server.headersTimeout. По умолчанию: 60000.
  • highWaterMark <number> Дополнительно переопределяет readableHighWaterMark и writableHighWaterMark всех socket. Это влияет на свойство highWaterMark как IncomingMessage, так и ServerResponse. По умолчанию: см. stream.getDefaultHighWaterMark().
  • insecureHTTPParser <boolean> Если установлено в true, будет использоваться HTTP-парсер с включенными флагами снисходительности. Использования небезопасного парсера следует избегать. Дополнительные сведения см. в разделе --insecure-http-parser. По умолчанию: false.
  • IncomingMessage <http.IncomingMessage> Указывает класс IncomingMessage, который будет использоваться. Полезно для расширения исходного IncomingMessage. По умолчанию: IncomingMessage.
  • joinDuplicateHeaders <boolean> Если установлено в true, этот параметр позволяет объединять значения строк полей нескольких заголовков в запросе с помощью запятой (, ) вместо отбрасывания дубликатов. Для получения дополнительной информации см. message.headers. По умолчанию: false.
  • keepAlive <boolean> Если установлено в true, это включает функцию поддержания соединения на сокете сразу после получения нового входящего соединения, аналогично тому, что делается в [socket.setKeepAlive([enable][, initialDelay])][socket.setKeepAlive(enable, initialDelay)]. По умолчанию: false.
  • keepAliveInitialDelay <number> Если установлено в положительное число, оно устанавливает начальную задержку перед отправкой первого зонда keepalive на неактивном сокете. По умолчанию: 0.
  • keepAliveTimeout: Количество миллисекунд бездействия, в течение которого сервер должен ожидать дополнительных входящих данных после завершения записи последнего ответа, прежде чем сокет будет уничтожен. Дополнительные сведения см. в разделе server.keepAliveTimeout. По умолчанию: 5000.
  • maxHeaderSize <number> Дополнительно переопределяет значение --max-http-header-size для запросов, полученных этим сервером, т. е. максимальную длину заголовков запроса в байтах. По умолчанию: 16384 (16 KiB).
  • noDelay <boolean> Если установлено в true, это отключает использование алгоритма Нагла сразу после получения нового входящего соединения. По умолчанию: true.
  • requestTimeout: Задает значение таймаута в миллисекундах для получения всего запроса от клиента. Дополнительные сведения см. в разделе server.requestTimeout. По умолчанию: 300000.
  • requireHostHeader <boolean> Если установлено в true, это заставляет сервер отвечать кодом состояния 400 (Неверный запрос) на любое сообщение запроса HTTP/1.1, в котором отсутствует заголовок Host (как предписано спецификацией). По умолчанию: true.
  • ServerResponse <http.ServerResponse> Указывает класс ServerResponse, который будет использоваться. Полезно для расширения исходного ServerResponse. По умолчанию: ServerResponse.
  • uniqueHeaders <Array> Список заголовков ответов, которые должны отправляться только один раз. Если значение заголовка является массивом, элементы будут объединены с помощью ; .
  • rejectNonStandardBodyWrites <boolean> Если установлено в true, возникает ошибка при записи в HTTP-ответ, у которого нет тела. По умолчанию: false.

• requestListener <Function>

• Возвращает: <http.Server>

Возвращает новый экземпляр http.Server.

requestListener — это функция, которая автоматически добавляется к событию 'request'.

ESM

import http from 'node:http'

// Создаем локальный сервер для приема данных
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Hello World!',
    })
  )
})

server.listen(8000)

CJS

const http = require('node:http')

// Создаем локальный сервер для приема данных
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Hello World!',
    })
  )
})

server.listen(8000)

ESM

import http from 'node:http'

// Создаем локальный сервер для приема данных
const server = http.createServer()

// Прослушиваем событие request
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Hello World!',
    })
  )
})

server.listen(8000)

CJS

const http = require('node:http')

// Создаем локальный сервер для приема данных
const server = http.createServer()

// Прослушиваем событие request
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Hello World!',
    })
  )
})

server.listen(8000)

http.get(options[, callback])

http.get(url[, options][, callback])

[История]

Версия	Изменения
v10.9.0	Теперь параметр url может передаваться вместе с отдельным объектом options.
v7.5.0	Параметр options может быть объектом WHATWG URL.
v0.3.6	Добавлено в: v0.3.6

• url <строка> | <URL>
• options <Объект> Принимает те же options, что и http.request(), при этом метод по умолчанию установлен как GET.
• callback <Функция>
• Возвращает: <http.ClientRequest>

Поскольку большинство запросов являются GET-запросами без тела, Node.js предоставляет этот удобный метод. Единственное отличие этого метода от http.request() заключается в том, что он по умолчанию устанавливает метод GET и автоматически вызывает req.end(). Обратный вызов должен обрабатывать потребление данных ответа по причинам, указанным в разделе http.ClientRequest.

Обратный вызов вызывается с единственным аргументом, который является экземпляром http.IncomingMessage.

Пример извлечения JSON:

http
  .get('http://localhost:8000/', res => {
    const { statusCode } = res
    const contentType = res.headers['content-type']

    let error
    // Любой код состояния 2xx сигнализирует об успешном ответе, но
    // здесь мы проверяем только 200.
    if (statusCode !== 200) {
      error = new Error('Request Failed.\n' + `Status Code: ${statusCode}`)
    } else if (!/^application\/json/.test(contentType)) {
      error = new Error('Invalid content-type.\n' + `Expected application/json but received ${contentType}`)
    }
    if (error) {
      console.error(error.message)
      // Потребляем данные ответа, чтобы освободить память
      res.resume()
      return
    }

    res.setEncoding('utf8')
    let rawData = ''
    res.on('data', chunk => {
      rawData += chunk
    })
    res.on('end', () => {
      try {
        const parsedData = JSON.parse(rawData)
        console.log(parsedData)
      } catch (e) {
        console.error(e.message)
      }
    })
  })
  .on('error', e => {
    console.error(`Got error: ${e.message}`)
  })

// Создаем локальный сервер для приема данных
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Hello World!',
    })
  )
})

server.listen(8000)

http.globalAgent

[История]

Версия	Изменения
v19.0.0	Агент теперь использует HTTP Keep-Alive и таймаут 5 секунд по умолчанию.
v0.5.9	Добавлено в: v0.5.9

• <http.Agent>

Глобальный экземпляр Agent, который используется в качестве значения по умолчанию для всех запросов HTTP-клиента. Отличается от конфигурации Agent по умолчанию тем, что у него включен keepAlive и таймаут timeout составляет 5 секунд.

http.maxHeaderSize

Добавлено в: v11.6.0, v10.15.0

• <number>

Свойство только для чтения, указывающее максимально допустимый размер HTTP-заголовков в байтах. По умолчанию 16 КиБ. Настраивается с помощью параметра командной строки --max-http-header-size.

Это может быть переопределено для серверов и клиентских запросов путем передачи параметра maxHeaderSize.

http.request(options[, callback])

http.request(url[, options][, callback])

[История]

Версия	Изменения
v16.7.0, v14.18.0	При использовании объекта URL разобранные имя пользователя и пароль теперь будут правильно декодированы URI.
v15.3.0, v14.17.0	Теперь можно прервать запрос с помощью AbortSignal.
v13.3.0	Теперь поддерживается параметр maxHeaderSize.
v13.8.0, v12.15.0, v10.19.0	Теперь поддерживается параметр insecureHTTPParser.
v10.9.0	Параметр url теперь можно передавать вместе с отдельным объектом options.
v7.5.0	Параметр options может быть объектом WHATWG URL.
v0.3.6	Добавлено в: v0.3.6

• url <string> | <URL>

• options <Object>

  • agent <http.Agent> | <boolean> Управляет поведением Agent. Возможные значения:

  • undefined (по умолчанию): использовать http.globalAgent для этого хоста и порта.

  • Объект Agent: явно использовать переданный Agent.

  • false: приводит к использованию нового Agent со значениями по умолчанию.

  • auth <string> Базовая аутентификация ('user:password') для вычисления заголовка Authorization.

  • createConnection <Function> Функция, которая создает сокет/поток для использования в запросе, когда параметр agent не используется. Это можно использовать, чтобы избежать создания пользовательского класса Agent только для переопределения функции createConnection по умолчанию. См. agent.createConnection() для получения более подробной информации. Любой поток Duplex является допустимым возвращаемым значением.

  • defaultPort <number> Порт по умолчанию для протокола. По умолчанию: agent.defaultPort, если используется Agent, иначе undefined.

  • family <number> Семейство IP-адресов, которое нужно использовать при разрешении host или hostname. Допустимые значения — 4 или 6. Если не указано, будут использоваться как IP v4, так и v6.

  • headers <Object> Объект, содержащий заголовки запроса.

  • hints <number> Необязательные dns.lookup() hints.

  • host <string> Доменное имя или IP-адрес сервера, которому нужно отправить запрос. По умолчанию: 'localhost'.

  • hostname <string> Псевдоним для host. Для поддержки url.parse(), hostname будет использоваться, если указаны как host, так и hostname.

  • insecureHTTPParser <boolean> Если установлено в true, будет использоваться HTTP-анализатор с включенными флагами снисхождения. Использования небезопасного анализатора следует избегать. См. --insecure-http-parser для получения дополнительной информации. По умолчанию: false

  • joinDuplicateHeaders <boolean> Объединяет значения строк полей нескольких заголовков в запросе с помощью , вместо отбрасывания дубликатов. См. message.headers для получения дополнительной информации. По умолчанию: false.

  • localAddress <string> Локальный интерфейс для привязки сетевых соединений.

  • localPort <number> Локальный порт для подключения.

  • lookup <Function> Пользовательская функция поиска. По умолчанию: dns.lookup().

  • maxHeaderSize <number> При необходимости переопределяет значение --max-http-header-size (максимальная длина ответов заголовков в байтах) для ответов, полученных от сервера. По умолчанию: 16384 (16 КиБ).

  • method <string> Строка, указывающая метод HTTP-запроса. По умолчанию: 'GET'.

  • path <string> Путь запроса. Должен включать строку запроса, если таковая имеется. Например, '/index.html?page=12'. Исключение генерируется, когда путь запроса содержит недопустимые символы. В настоящее время отклоняются только пробелы, но это может измениться в будущем. По умолчанию: '/'.

  • port <number> Порт удаленного сервера. По умолчанию: defaultPort, если установлен, иначе 80.

  • protocol <string> Протокол для использования. По умолчанию: 'http:'.

  • setDefaultHeaders <boolean>: Указывает, следует ли автоматически добавлять заголовки по умолчанию, такие как Connection, Content-Length, Transfer-Encoding и Host. Если установлено значение false, то все необходимые заголовки должны быть добавлены вручную. Значение по умолчанию — true.

  • setHost <boolean>: Указывает, следует ли автоматически добавлять заголовок Host. Если указано, это переопределяет setDefaultHeaders. Значение по умолчанию — true.

  • signal <AbortSignal>: AbortSignal, который может использоваться для прерывания текущего запроса.

  • socketPath <string> Unix-сокет домена. Не может использоваться, если указан один из параметров host или port, так как они указывают TCP-сокет.

  • timeout <number>: Число, указывающее таймаут сокета в миллисекундах. Это установит таймаут до подключения сокета.

  • uniqueHeaders <Array> Список заголовков запроса, которые должны быть отправлены только один раз. Если значение заголовка является массивом, элементы будут объединены с помощью ; .

• callback <Function>

• Возвращает: <http.ClientRequest>

Также поддерживаются параметры options в socket.connect().

Node.js поддерживает несколько соединений на сервер для отправки HTTP-запросов. Эта функция позволяет прозрачно отправлять запросы.

url может быть строкой или объектом URL. Если url — строка, она автоматически разбирается с помощью new URL(). Если это объект URL, он будет автоматически преобразован в обычный объект options.

Если указаны как url, так и options, объекты объединяются, причем свойства options имеют приоритет.

Необязательный параметр callback будет добавлен в качестве одноразового обработчика события 'response'.

http.request() возвращает экземпляр класса http.ClientRequest. Экземпляр ClientRequest является записываемым потоком. Если необходимо загрузить файл с помощью POST-запроса, запишите данные в объект ClientRequest.

ESM

import http from 'node:http'
import { Buffer } from 'node:buffer'

const postData = JSON.stringify({
  msg: 'Hello World!',
})

const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData),
  },
}

const req = http.request(options, res => {
  console.log(`STATUS: ${res.statusCode}`)
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`)
  res.setEncoding('utf8')
  res.on('data', chunk => {
    console.log(`BODY: ${chunk}`)
  })
  res.on('end', () => {
    console.log('No more data in response.')
  })
})

req.on('error', e => {
  console.error(`problem with request: ${e.message}`)
})

// Write data to request body
req.write(postData)
req.end()

CJS

const http = require('node:http')

const postData = JSON.stringify({
  msg: 'Hello World!',
})

const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData),
  },
}

const req = http.request(options, res => {
  console.log(`STATUS: ${res.statusCode}`)
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`)
  res.setEncoding('utf8')
  res.on('data', chunk => {
    console.log(`BODY: ${chunk}`)
  })
  res.on('end', () => {
    console.log('No more data in response.')
  })
})

req.on('error', e => {
  console.error(`problem with request: ${e.message}`)
})

// Write data to request body
req.write(postData)
req.end()

В примере был вызван req.end(). С http.request() всегда необходимо вызывать req.end(), чтобы сигнализировать о конце запроса — даже если данные не записываются в тело запроса.

Если во время запроса возникает какая-либо ошибка (будь то разрешение DNS, ошибки на уровне TCP или фактические ошибки анализа HTTP), событие 'error' генерируется в возвращенном объекте запроса. Как и во всех событиях 'error', если обработчики не зарегистрированы, ошибка будет выброшена.

Следует отметить несколько специальных заголовков.

• Отправка 'Connection: keep-alive' уведомит Node.js о том, что соединение с сервером должно сохраняться до следующего запроса.
• Отправка заголовка 'Content-Length' отключит кодировку по частям по умолчанию.
• Отправка заголовка 'Expect' немедленно отправит заголовки запроса. Обычно, при отправке 'Expect: 100-continue', следует установить как таймаут, так и обработчик события 'continue'. См. RFC 2616 Section 8.2.3 для получения дополнительной информации.
• Отправка заголовка Authorization переопределит использование параметра auth для вычисления базовой аутентификации.

Пример использования URL в качестве options:

const options = new URL('http://abc:')

const req = http.request(options, res => {
  // ...
})

В успешном запросе будут генерироваться следующие события в следующем порядке:

• 'socket'

• 'response'

  • 'data' любое количество раз, в объекте res ('data' вообще не будет генерироваться, если тело ответа пустое, например, в большинстве перенаправлений)
  • 'end' в объекте res

• 'close'

В случае ошибки соединения будут генерироваться следующие события:

• 'socket'
• 'error'
• 'close'

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

• 'socket'
• 'error' с ошибкой с сообщением 'Error: socket hang up' и кодом 'ECONNRESET'
• 'close'

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

• 'socket'

• 'response'

  • 'data' любое количество раз, в объекте res

• (соединение закрыто здесь)

• 'aborted' в объекте res

• 'close'

• 'error' в объекте res с ошибкой с сообщением 'Error: aborted' и кодом 'ECONNRESET'

• 'close' в объекте res

Если вызывается req.destroy() до присвоения сокета, будут генерироваться следующие события в следующем порядке:

• (req.destroy() вызывается здесь)
• 'error' с ошибкой с сообщением 'Error: socket hang up' и кодом 'ECONNRESET' или ошибкой, с которой был вызван req.destroy()
• 'close'

Если вызывается req.destroy() до успешного установления соединения, будут генерироваться следующие события в следующем порядке:

• 'socket'
• (req.destroy() вызывается здесь)
• 'error' с ошибкой с сообщением 'Error: socket hang up' и кодом 'ECONNRESET' или ошибкой, с которой был вызван req.destroy()
• 'close'

Если вызывается req.destroy() после получения ответа, будут генерироваться следующие события в следующем порядке:

• 'socket'

• 'response'

  • 'data' любое количество раз, в объекте res

• (req.destroy() вызывается здесь)

• 'aborted' в объекте res

• 'close'

• 'error' в объекте res с ошибкой с сообщением 'Error: aborted' и кодом 'ECONNRESET' или ошибкой, с которой был вызван req.destroy()

• 'close' в объекте res

Если вызывается req.abort() до присвоения сокета, будут генерироваться следующие события в следующем порядке:

• (req.abort() вызывается здесь)
• 'abort'
• 'close'

Если вызывается req.abort() до успешного установления соединения, будут генерироваться следующие события в следующем порядке:

• 'socket'
• (req.abort() вызывается здесь)
• 'abort'
• 'error' с ошибкой с сообщением 'Error: socket hang up' и кодом 'ECONNRESET'
• 'close'

Если вызывается req.abort() после получения ответа, будут генерироваться следующие события в следующем порядке:

• 'socket'

• 'response'

  • 'data' любое количество раз, в объекте res

• (req.abort() вызывается здесь)

• 'abort'

• 'aborted' в объекте res

• 'error' в объекте res с сообщением об ошибке 'Error: aborted' и кодом 'ECONNRESET'.

• 'close'

• 'close' в объекте res

Установка параметра timeout или использование функции setTimeout() не прервет запрос и не сделает ничего, кроме добавления события 'timeout'.

Передача AbortSignal и последующий вызов abort() в соответствующем AbortController будет вести себя так же, как вызов .destroy() для запроса. В частности, событие 'error' будет генерироваться с ошибкой с сообщением 'AbortError: The operation was aborted', кодом 'ABORT_ERR' и cause, если таковой был предоставлен.

http.validateHeaderName(name[, label])

[История]

Версия	Изменения
v19.5.0, v18.14.0	Добавлен параметр label.
v14.3.0	Добавлено в: v14.3.0

• name <строка>
• label <строка> Метка для сообщения об ошибке. По умолчанию: 'Header name'.

Выполняет проверку переданного name низкого уровня, которая выполняется при вызове res.setHeader(name, value).

Передача недопустимого значения в качестве name приведёт к выбросу исключения TypeError, идентифицированного как code: 'ERR_INVALID_HTTP_TOKEN'.

Нет необходимости использовать этот метод перед передачей заголовков в HTTP-запрос или ответ. Модуль HTTP автоматически проверит такие заголовки.

Пример:

ESM

import { validateHeaderName } from 'node:http'

try {
  validateHeaderName('')
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code) // --> 'ERR_INVALID_HTTP_TOKEN'
  console.error(err.message) // --> 'Header name must be a valid HTTP token [""]'
}

CJS

const { validateHeaderName } = require('node:http')

try {
  validateHeaderName('')
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code) // --> 'ERR_INVALID_HTTP_TOKEN'
  console.error(err.message) // --> 'Header name must be a valid HTTP token [""]'
}

http.validateHeaderValue(name, value)

Добавлено в: v14.3.0

• name <строка>
• value <любое>

Выполняет проверку переданного value низкого уровня, которая выполняется при вызове res.setHeader(name, value).

Передача недопустимого значения в качестве value приведёт к выбросу исключения TypeError.

• Ошибка неопределённого значения идентифицируется как code: 'ERR_HTTP_INVALID_HEADER_VALUE'.
• Ошибка недопустимого символа значения идентифицируется как code: 'ERR_INVALID_CHAR'.

Нет необходимости использовать этот метод перед передачей заголовков в HTTP-запрос или ответ. Модуль HTTP автоматически проверит такие заголовки.

Примеры:

ESM

import { validateHeaderValue } from 'node:http'

try {
  validateHeaderValue('x-my-header', undefined)
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code === 'ERR_HTTP_INVALID_HEADER_VALUE') // --> true
  console.error(err.message) // --> 'Invalid value "undefined" for header "x-my-header"'
}

try {
  validateHeaderValue('x-my-header', 'oʊmɪɡə')
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code === 'ERR_INVALID_CHAR') // --> true
  console.error(err.message) // --> 'Invalid character in header content ["x-my-header"]'
}

CJS

const { validateHeaderValue } = require('node:http')

try {
  validateHeaderValue('x-my-header', undefined)
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code === 'ERR_HTTP_INVALID_HEADER_VALUE') // --> true
  console.error(err.message) // --> 'Invalid value "undefined" for header "x-my-header"'
}

try {
  validateHeaderValue('x-my-header', 'oʊmɪɡə')
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code === 'ERR_INVALID_CHAR') // --> true
  console.error(err.message) // --> 'Invalid character in header content ["x-my-header"]'
}

http.setMaxIdleHTTPParsers(max)

Добавлено в: v18.8.0, v16.18.0

• max <число> По умолчанию: 1000.

Устанавливает максимальное количество неиспользуемых HTTP-парсеров.

WebSocket

Добавлено в: v22.5.0

Совместимая с браузером реализация WebSocket.