HTTP

Этот модуль, содержащий клиентскую и серверную части, можно импортировать через 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": "*/*" }
jsoncopy

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

Чтобы поддерживать весь спектр возможных 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", "*/*" ]
jsoncopy

Класс: http.Agent

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

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

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

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

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

http.get(options, (res) => {
  // Do stuff
}).on('socket', (socket) => {
  socket.emit('agentRemove');
});
jscopy

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

agent:false:

http.get({
  hostname: 'localhost',
  port: 80,
  path: '/',
  agent: false,  // Create a new agent just for this one request
}, (res) => {
  // Do stuff with response
});
jscopy

new Agent([options])

• 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.
  • agentKeepAliveTimeoutBuffer <number> Количество миллисекунд, вычитаемое из подсказки keep-alive: timeout=..., предоставленной сервером, при определении времени истечения срока действия сокета. Этот запас помогает агенту закрыть сокет немного раньше сервера и уменьшает вероятность отправки запроса через сокет, который сервер собирается закрыть. По умолчанию: 1000.
  • maxSockets <number> Максимальное количество сокетов для одного хоста. Если для одного хоста открыто несколько одновременных соединений, каждый запрос будет использовать новый сокет, пока не будет достигнуто значение maxSockets. Если хост попытается открыть больше соединений, чем допускает maxSockets, дополнительные запросы попадут в очередь ожидания и перейдут в состояние активного соединения, когда завершится одно из существующих соединений. Это гарантирует, что для заданного хоста в любой момент времени будет не более maxSockets активных соединений. По умолчанию: Infinity.
  • maxTotalSockets <number> Максимальное общее количество сокетов для всех хостов. Каждый запрос будет использовать новый сокет, пока не будет достигнуто максимальное значение. По умолчанию: Infinity.
  • maxFreeSockets <number> Максимальное количество сокетов на хост, которые можно оставить открытыми в свободном состоянии. Учитывается только при значении true параметра keepAlive. По умолчанию: 256.
  • scheduling <string> Стратегия планирования при выборе следующего свободного сокета. Возможны значения 'fifo' и 'lifo'. Основное различие между стратегиями заключается в том, что 'lifo' выбирает сокет, использовавшийся последним, а 'fifo' — сокет, использовавшийся раньше всех. При низкой частоте запросов 'lifo' планирование снижает риск выбора сокета, который сервер мог закрыть из-за бездействия. При высокой частоте запросов 'fifo' планирование максимизирует число открытых сокетов, а 'lifo' планирование поддерживает его как можно ниже. По умолчанию: 'lifo'.
  • timeout <number> Тайм-аут сокета в миллисекундах. Задаёт тайм-аут при создании сокета.
  • proxyEnv <Object> | <undefined> Переменные среды для настройки прокси. Подробности см. в разделе Встроенная поддержка прокси. По умолчанию: undefined
    • HTTP_PROXY <string> | <undefined> URL прокси-сервера, который следует использовать для HTTP-запросов. Если значение не задано, для HTTP-запросов прокси не используется.
    • HTTPS_PROXY <string> | <undefined> URL прокси-сервера, который следует использовать для HTTPS-запросов. Если значение не задано, для HTTPS-запросов прокси не используется.
    • NO_PROXY <string> | <undefined> Шаблоны, задающие конечные точки, для которых не следует использовать прокси.
    • http_proxy <string> | <undefined> То же, что и HTTP_PROXY. Если заданы оба параметра, приоритет имеет http_proxy.
    • https_proxy <string> | <undefined> То же, что и HTTPS_PROXY. Если заданы оба параметра, приоритет имеет https_proxy.
    • no_proxy <string> | <undefined> То же, что и NO_PROXY. Если заданы оба параметра, приоритет имеет no_proxy.
  • defaultPort <number> Порт по умолчанию, используемый, если в запросах порт не указан. По умолчанию: 80.
  • protocol <string> Протокол, используемый агентом. По умолчанию: 'http:'.

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

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

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

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

agent.createConnection(options[, callback])

• options <Object> Параметры с информацией о соединении. Формат параметров см. в разделе net.createConnection(). Для пользовательских агентов этот объект передаётся пользовательской функции createConnection.
• callback <Function> (Необязательный параметр, в основном для пользовательских агентов) Функция, вызываемая пользовательской реализацией createConnection при создании сокета, особенно для асинхронных операций.
  • err <Error> | <null> Объект ошибки, если при создании сокета произошёл сбой.
  • socket <stream.Duplex> Созданный сокет.
• Возвращает: <stream.Duplex> Созданный сокет. Возвращается реализацией по умолчанию или пользовательской синхронной реализацией createConnection. Если пользовательская реализация createConnection использует callback для асинхронной операции, это возвращаемое значение может не быть основным способом получения сокета.

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

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

Однако пользовательские агенты могут переопределить этот метод для большей гибкости, например для асинхронного создания сокетов. При переопределении createConnection:

1. Синхронное создание сокета: переопределённый метод может напрямую возвращать сокет/поток.
2. Асинхронное создание сокета: переопределённый метод может принимать callback и передавать ему созданный сокет/поток (например, callback(null, newSocket)). Если при создании сокета происходит ошибка, её следует передать в качестве первого аргумента в callback (например, callback(err)).

Агент вызовет переданную функцию createConnection с options и этим внутренним callback. Переданная агентом функция callback имеет сигнатуру (err, stream).

agent.keepSocketAlive(socket)

• socket <stream.Duplex>

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

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

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

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

agent.reuseSocket(socket, request)

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

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

socket.ref();
jscopy

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

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

agent.destroy()

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

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

agent.freeSockets

• Тип: <Object>

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

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

agent.getName([options])

• options <Object> Набор параметров, содержащих сведения для формирования имени
  • host <string> Доменное имя или IP-адрес сервера, которому будет отправлен запрос
  • port <number> Порт удалённого сервера
  • localAddress <string> Локальный интерфейс для привязки сетевых соединений при отправке запроса
  • family <integer> Должен быть равен 4 или 6, если это значение не равно undefined.
• Возвращает: <string>

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

agent.maxFreeSockets

• Тип: <number>

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

agent.maxSockets

• Тип: <number>

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

agent.maxTotalSockets

• Тип: <number>

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

agent.requests

• Тип: <Object>

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

agent.sockets

• Тип: <Object>

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

Класс: http.ClientRequest

• Наследует: <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' не сработает. Кроме того, до чтения данные занимают память, что со временем может привести к ошибке «process out of memory».

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

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

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

Событие: 'abort'

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

Событие: 'close'

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

Событие: 'connect'

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

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

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

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

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

// Create an HTTP tunneling proxy
const proxy = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // Connect to an origin server
  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);
  });
});

// Now that proxy is running
proxy.listen(1337, '127.0.0.1', () => {

  // Make a request to a tunneling proxy
  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!');

    // Make a request over an HTTP tunnel
    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();
    });
  });
});

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

// Create an HTTP tunneling proxy
const proxy = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // Connect to an origin server
  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);
  });
});

// Now that proxy is running
proxy.listen(1337, '127.0.0.1', () => {

  // Make a request to a tunneling proxy
  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!');

    // Make a request over an HTTP tunnel
    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'

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

Событие: 'finish'

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

Событие: 'information'

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

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

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}`);
});

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'

• response <http.IncomingMessage>

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

Событие: 'socket'

• socket <stream.Duplex>

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

Событие: 'timeout'

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

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

Событие: 'upgrade'

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

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

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

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

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

// Create an HTTP server
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
server.on('upgrade', (req, stream, head) => {
  stream.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
               'Upgrade: WebSocket\r\n' +
               'Connection: Upgrade\r\n' +
               '\r\n');

  stream.pipe(stream); // echo back
});

// Now that server is running
server.listen(1337, '127.0.0.1', () => {

  // make a request
  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, stream, upgradeHead) => {
    console.log('got upgraded!');
    stream.end();
    process.exit(0);
  });
});

const http = require('node:http');

// Create an HTTP server
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
server.on('upgrade', (req, stream, head) => {
  stream.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
               'Upgrade: WebSocket\r\n' +
               'Connection: Upgrade\r\n' +
               '\r\n');

  stream.pipe(stream); // echo back
});

// Now that server is running
server.listen(1337, '127.0.0.1', () => {

  // make a request
  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, stream, upgradeHead) => {
    console.log('got upgraded!');
    stream.end();
    process.exit(0);
  });
});

request.abort()

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

request.aborted

• Тип: <boolean>

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

request.connection

• Тип: <stream.Duplex>

См. request.socket.

request.cork()

См. writable.cork().

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

• 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])

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

Уничтожает запрос. При необходимости генерирует событие 'error' и генерирует событие 'close'. Вызов этого метода приведёт к отбрасыванию оставшихся данных ответа и уничтожению сокета, если он используется; в противном случае сокет по возможности будет возвращён в соответствующий пул Agent.

Дополнительные сведения см. в разделе writable.destroy().

request.destroyed

• Тип: <boolean>

Равно true после вызова request.destroy().

Дополнительные сведения см. в разделе writable.destroyed.

request.finished

• Тип: <boolean>

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

request.flushHeaders()

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

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

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

request.getHeader(name)

• 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' is 'text/html'
const contentLength = request.getHeader('Content-Length');
// 'contentLength' is of type number
const cookie = request.getHeader('Cookie');
// 'cookie' is of type string[]
jscopy

request.getHeaderNames()

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

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

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

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

request.getHeaders()

• Возвращает: <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'] }
jscopy

request.getRawHeaderNames()

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

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

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

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

request.hasHeader(name)

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

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

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

request.maxHeadersCount

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

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

request.path

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

request.method

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

request.host

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

request.protocol

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

request.removeHeader(name)

• name <string>

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

request.removeHeader('Content-Type');
jscopy

request.reusedSocket

• Тип: <boolean> Указывает, был ли запрос отправлен через повторно используемый сокет.

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

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

// Server has a 5 seconds keep-alive timeout by default
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // Adapting a keep-alive agent
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // Do nothing
    });
  });
}, 5000); // Sending request on 5s interval so it's easy to hit idle timeout

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

// Server has a 5 seconds keep-alive timeout by default
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // Adapting a keep-alive agent
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // Do nothing
    });
  });
}, 5000); // Sending request on 5s interval so it's easy to hit idle timeout

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

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) => {
      // Check if retry is needed
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();

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) => {
      // Check if retry is needed
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();

request.setHeader(name, value)

• name <string>
• value <any>

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

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

или

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

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

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

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

request.setNoDelay([noDelay])

• noDelay <boolean>

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

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

• enable <boolean>
• initialDelay <number>

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

request.setTimeout(timeout[, callback])

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

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

request.socket

• Тип: <stream.Duplex>

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

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(`Your IP address is ${ip} and your source port is ${port}.`);
  // Consume response object
});

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(`Your IP address is ${ip} and your source port is ${port}.`);
  // Consume response object
});

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

request.uncork()

См. writable.uncork().

request.writableEnded

• Тип: <boolean>

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

request.writableFinished

• Тип: <boolean>

Равно true, если все данные сброшены в базовую систему; это происходит непосредственно перед генерацией события 'finish'.

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

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

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

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

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

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

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

Класс: http.Server

• Наследует: <net.Server>

Событие: 'checkContinue'

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

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

Для обработки этого события необходимо вызвать response.writeContinue(), если клиенту следует продолжить отправку тела запроса, или сформировать подходящий ответ HTTP (например, 400 Bad Request), если клиенту не следует продолжать отправку тела запроса.

Если это событие вызвано и обработано, событие 'request' вызвано не будет.

Событие: 'checkExpectation'

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

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

Если это событие вызвано и обработано, событие 'request' вызвано не будет.

Событие: 'clientError'

• 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, в котором возникла ошибка.

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);

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');
});
jscopy

Событие: 'close'

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

Событие: 'connect'

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

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

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

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

Событие: 'connection'

• socket <stream.Duplex>

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

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

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

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

Событие: 'dropRequest'

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

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

Событие: 'request'

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

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

Событие: 'upgrade'

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

Генерируется каждый раз, когда принимается запрос клиента на обновление HTTP. По умолчанию все запросы на обновление HTTP игнорируются (то есть генерируются только обычные события 'request', сохраняя стандартный поток запросов и ответов HTTP), если только не добавить обработчик этого события; в этом случае принимаются все такие запросы (то есть вместо него генерируется событие 'upgrade', а дальнейшее взаимодействие должно выполняться напрямую через необработанный поток). Более точное управление доступно с помощью параметра сервера shouldUpgradeCallback.

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

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

В редких случаях, когда входящий запрос содержит тело, оно будет разобрано обычным образом отдельно от потока обновления, а данные необработанного потока начнут поступать только после завершения разбора тела. Чтобы чтение из потока не блокировалось ожиданием чтения тела запроса, любое чтение из потока автоматически запустит передачу тела запроса. Если нужно прочитать тело запроса, сделайте это (то есть назначьте обработчики 'data') до начала чтения из обновленного потока.

Аргумент stream обычно представляет собой экземпляр <net.Socket>, используемый запросом, но в некоторых случаях (например, при наличии тела запроса) это может быть дуплексный поток. При необходимости получить доступ к исходному соединению, лежащему в основе запроса, можно через request.socket. Гарантируется, что это будет экземпляр <net.Socket>, если только пользователь не указал другой тип сокета.

server.close([callback])

• 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);
// Close the server after 10 seconds
setTimeout(() => {
  server.close(() => {
    console.log('server on port 8000 closed successfully');
  });
}, 10000);
jscopy

server.closeAllConnections()

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

Это принудительный способ закрыть все соединения, поэтому использовать его следует с осторожностью. При совместном использовании с server.close рекомендуется вызывать этот метод после server.close, чтобы избежать состояний гонки, при которых новые подключения создаются между вызовами этого метода и 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);
// Close the server after 10 seconds
setTimeout(() => {
  server.close(() => {
    console.log('server on port 8000 closed successfully');
  });
  // Closes all connections, ensuring the server closes successfully
  server.closeAllConnections();
}, 10000);
jscopy

server.closeIdleConnections()

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

Начиная с Node.js 19.0.0, для закрытия неактивных соединений keep-alive нет необходимости вызывать этот метод вместе с server.close. Его использование не причинит вреда и может быть полезно для обеспечения обратной совместимости библиотек и приложений, которым необходимо поддерживать версии ниже 19.0.0. При совместном использовании с server.close рекомендуется вызывать этот метод после server.close, чтобы избежать состояний гонки, при которых новые подключения создаются между вызовами этого метода и 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);
// Close the server after 10 seconds
setTimeout(() => {
  server.close(() => {
    console.log('server on port 8000 closed successfully');
  });
  // Closes idle connections, such as keep-alive connections. Server will close
  // once remaining active connections are terminated
  server.closeIdleConnections();
}, 10000);
jscopy

server.headersTimeout

• Тип: <number> По умолчанию: минимум из server.requestTimeout и 60000.

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

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

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

server.listen()

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

server.listening

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

server.maxHeadersCount

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

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

server.requestTimeout

• Тип: <number> По умолчанию: 300000

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

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

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

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

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

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

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

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

server.maxRequestsPerSocket

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

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

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

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

server.timeout

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

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

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

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

server.keepAliveTimeout

• Тип: <number> Тайм-аут в миллисекундах. По умолчанию: 5000 (5 секунд).

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

Это значение тайм-аута объединяется с параметром server.keepAliveTimeoutBuffer для определения фактического тайм-аута сокета, который рассчитывается так: socketTimeout = keepAliveTimeout + keepAliveTimeoutBuffer. Если сервер получает новые данные до истечения тайм-аута keep-alive, обычный тайм-аут бездействия, то есть server.timeout, сбрасывается.

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

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

server.keepAliveTimeoutBuffer

• Тип: <number> Тайм-аут в миллисекундах. По умолчанию: 1000 (1 секунда).

Дополнительный временной интервал, добавляемый к значению server.keepAliveTimeout для увеличения внутреннего тайм-аута сокета.

Этот интервал помогает уменьшить количество ошибок сброса соединения (ECONNRESET), немного увеличивая тайм-аут сокета сверх объявленного тайм-аута keep-alive.

Этот параметр применяется только к новым входящим подключениям.

server[Symbol.asyncDispose]()

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

Класс: http.ServerResponse

• Наследует: <http.OutgoingMessage>

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

Событие: 'close'

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

Событие: 'finish'

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

response.addTrailers(headers)

• 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();
jscopy

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

response.connection

• Тип: <stream.Duplex>

См. response.socket.

response.cork()

См. writable.cork().

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

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

Этот метод сообщает серверу, что все заголовки и тело ответа отправлены и сервер должен считать сообщение завершенным. Метод response.end() необходимо вызывать для каждого ответа.

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

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

response.finished

• Тип: <boolean>

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

response.flushHeaders()

Отправляет заголовки ответа. См. также: request.flushHeaders().

response.getHeader(name)

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

Возвращает заголовок, который уже добавлен в очередь, но еще не отправлен клиенту. Регистр имени не учитывается. Тип возвращаемого значения зависит от аргументов, переданных в 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 is 'text/html'
const contentLength = response.getHeader('Content-Length');
// contentLength is of type number
const setCookie = response.getHeader('set-cookie');
// setCookie is of type string[]
jscopy

response.getHeaderNames()

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

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

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

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

response.getHeaders()

• Возвращает: <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'] }
jscopy

response.hasHeader(name)

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

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

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

response.headersSent

• Тип: <boolean>

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

response.removeHeader(name)

• name <string>

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

response.removeHeader('Content-Encoding');
jscopy

response.req

• Тип: <http.IncomingMessage>

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

response.sendDate

• Тип: <boolean>

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

Отключать эту функцию следует только при тестировании; заголовок Date обязателен в большинстве HTTP-ответов (подробности см. в разделе 6.6.1 RFC 9110).

response.setHeader(name, value)

• name <string>
• value <number> | <string> | <string[]>
• Возвращает: <http.ServerResponse>

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

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

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

или

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

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

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

// Returns 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');
});
jscopy

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

response.setTimeout(msecs[, callback])

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

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

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

response.socket

• Тип: <stream.Duplex>

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

import http from 'node:http';
const server = http.createServer((req, res) => {
  const ip = res.socket.remoteAddress;
  const port = res.socket.remotePort;
  res.end(`Your IP address is ${ip} and your source port is ${port}.`);
}).listen(3000);

const http = require('node:http');
const server = http.createServer((req, res) => {
  const ip = res.socket.remoteAddress;
  const port = res.socket.remotePort;
  res.end(`Your IP address is ${ip} and your source port is ${port}.`);
}).listen(3000);

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

response.statusCode

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

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

response.statusCode = 404;
jscopy

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

response.statusMessage

• Тип: <string>

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

response.statusMessage = 'Not found';
jscopy

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

response.strictContentLength

• Тип: <boolean> По умолчанию: false

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

response.uncork()

См. writable.uncork().

response.writableEnded

• Тип: <boolean>

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

response.writableFinished

• Тип: <boolean>

Равно true, если все данные переданы в базовую систему непосредственно перед генерацией события 'finish'.

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

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

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

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

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

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

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

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

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

response.writeContinue()

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

response.writeEarlyHints(hints[, callback])

• hints <Object>
• callback <Function>

Отправляет клиенту сообщение HTTP/1.1 103 Early Hints с заголовком Link, указывая, что пользовательский агент может предварительно загрузить или установить соединение с указанными ресурсами. 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);
jscopy

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

• statusCode <number>
• statusMessage <string>
• headers <Object> | <Array>
• Возвращает: <http.ServerResponse>

Отправляет заголовок ответа на запрос. Код состояния — это трехзначный код состояния 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);
jscopy

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

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

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

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

// Returns 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');
});
jscopy

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

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

response.writeInformation(statusCode[, headers][, callback])

• statusCode <number> Информационный код состояния HTTP 1xx в диапазоне от 100 до 199 включительно, за исключением 101 (Switching Protocols), доступного только через событие 'upgrade'.
• headers <Object> | <Array> Необязательный набор заголовков, отправляемых с информационным ответом. Поддерживаются те же форматы, что и в response.writeHead().
• callback <Function> Необязательный аргумент, вызываемый после записи сообщения в сокет.

Отправляет клиенту произвольный информационный ответ HTTP/1.1 1xx. Это универсальный аналог методов response.writeContinue(), response.writeProcessing() и response.writeEarlyHints(); его можно вызывать несколько раз до окончательного ответа. После отправки заголовков окончательного ответа (через response.writeHead() или неявный заголовок) вызов этого метода приводит к выбросу ERR_HTTP_HEADERS_SENT.

Клиенты получают эти ответы через событие 'information' объекта http.ClientRequest.

response.writeInformation(110, { 'X-Progress': '50%' });
jscopy

response.writeProcessing()

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

Класс: http.IncomingMessage

• Наследует: <stream.Readable>

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

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

Событие: 'aborted'

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

Событие: 'close'

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

message.aborted

• Тип: <boolean>

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

message.complete

• Тип: <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(
        'The connection was terminated while the message was still being sent');
  });
});
jscopy

message.connection

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

message.destroy([error])

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

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

message.headers

• Тип: <Object>

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

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

// Prints something like:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers);
jscopy

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

• Дубликаты 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(). Дополнительные сведения см. в разделе 5.3 RFC 9110.
• set-cookie всегда является массивом. Дубликаты добавляются в массив.
• Значения дублирующихся заголовков cookie объединяются с помощью ; .
• Значения всех остальных заголовков объединяются с помощью , .

message.headersDistinct

• Тип: <Object>

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

// Prints something like:
//
// { 'user-agent': ['curl/7.22.0'],
//   host: ['127.0.0.1:8000'],
//   accept: ['*/*'] }
console.log(request.headersDistinct);
jscopy

message.httpVersion

• Тип: <string>

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

Кроме того, message.httpVersionMajor — это первое целое число, а message.httpVersionMinor — второе.

message.method

• Тип: <string>

Применимо только к запросам, полученным от http.Server.

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

message.rawHeaders

• Тип: <string[]>

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

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

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

// Prints something like:
//
// [ '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);
jscopy

message.rawTrailers

• Тип: <string[]>

Исходные ключи и значения трейлеров запроса/ответа в точности в том виде, в котором они были получены. Заполняется только во время события 'end'.

message.setTimeout(msecs[, callback])

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

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

message.signal

• Тип: <AbortSignal>

<AbortSignal>, который прерывается при закрытии базового сокета или уничтожении запроса. Сигнал создаётся лениво при первом обращении — для запросов, в которых это свойство никогда не используется, объект <AbortController> не создаётся.

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

import http from 'node:http';

http.createServer(async (req, res) => {
  try {
    const data = await fetch('https://example.com/api', { signal: req.signal });
    res.end(JSON.stringify(await data.json()));
  } catch (err) {
    if (err.name === 'AbortError') return;
    res.statusCode = 500;
    res.end('Internal Server Error');
  }
}).listen(3000);

const http = require('node:http');

http.createServer(async (req, res) => {
  try {
    const data = await fetch('https://example.com/api', { signal: req.signal });
    res.end(JSON.stringify(await data.json()));
  } catch (err) {
    if (err.name === 'AbortError') return;
    res.statusCode = 500;
    res.end('Internal Server Error');
  }
}).listen(3000);

message.socket

• Тип: <stream.Duplex>

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

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

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

message.statusCode

• Тип: <number>

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

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

message.statusMessage

• Тип: <string>

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

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

message.trailers

• Тип: <Object>

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

message.trailersDistinct

• Тип: <Object>

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

message.url

• Тип: <string>

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

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

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

Чтобы разобрать URL на составляющие:

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

Если 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: ''
}
consolecopy

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

Класс: http.OutgoingMessage

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

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

Событие: 'drain'

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

Событие: 'finish'

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

Событие: 'prefinish'

Генерируется после вызова outgoingMessage.end(). На момент генерации события все данные обработаны, но не обязательно полностью сброшены.

outgoingMessage.addTrailers(headers)

• 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();
jscopy

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

outgoingMessage.appendHeader(name, value)

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

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

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

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

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

outgoingMessage.connection

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

outgoingMessage.cork()

См. writable.cork().

outgoingMessage.destroy([error])

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

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

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

• 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()

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

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

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

outgoingMessage.getHeader(name)

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

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

outgoingMessage.getHeaderNames()

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

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

outgoingMessage.getHeaders()

• Возвращает: <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'] }
jscopy

outgoingMessage.hasHeader(name)

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

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

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

outgoingMessage.headersSent

• Тип: <boolean>

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

outgoingMessage.pipe()

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

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

outgoingMessage.removeHeader(name)

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

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

outgoingMessage.removeHeader('Content-Encoding');
jscopy

outgoingMessage.setHeader(name, value)

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

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

outgoingMessage.setHeaders(headers)

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

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

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

или

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

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

// Returns 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');
});
jscopy

outgoingMessage.setTimeout(msecs[, callback])

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

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

outgoingMessage.socket

• Тип: <stream.Duplex>

Ссылка на базовый сокет. Обычно пользователям не требуется обращаться к этому свойству.

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

outgoingMessage.uncork()

См. writable.uncork()

outgoingMessage.writableCorked

• Тип: <number>

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

outgoingMessage.writableEnded

• Тип: <boolean>

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

outgoingMessage.writableFinished

• Тип: <boolean>

Равно true, если все данные сброшены в базовую систему.

outgoingMessage.writableHighWaterMark

• Тип: <number>

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

outgoingMessage.writableLength

• Тип: <number>

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

outgoingMessage.writableObjectMode

• Тип: <boolean>

Всегда равно false.

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

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

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

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

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

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

http.METHODS

• Тип: <string[]>

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

http.STATUS_CODES

• Тип: <Object>

Список всех стандартных кодов состояния HTTP-ответа и их кратких описаний. Например, http.STATUS_CODES[404] === 'Not Found'.

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

• options <Object>

  • connectionsCheckingInterval: Задает интервал в миллисекундах для проверки времени ожидания запроса и заголовков в незавершенных запросах. По умолчанию: 30000.
  • headersTimeout: Задает время ожидания в миллисекундах для получения полных HTTP-заголовков от клиента. Дополнительные сведения см. в разделе server.headersTimeout. По умолчанию: 60000.
  • highWaterMark <number> При необходимости переопределяет параметры socket и readableHighWaterMark всех writableHighWaterMark. Это влияет на свойство highWaterMark объектов IncomingMessage и ServerResponse. По умолчанию: см. stream.getDefaultHighWaterMark().
  • httpValidation <string> Управляет строгостью проверки значений HTTP-заголовков входящих запросов. Допустимые значения:
    • 'strict': наиболее строгая проверка; отклоняются все не-ASCII-символы и управляющие символы в значениях заголовков.
    • 'relaxed': допускает ограниченный набор символов не из ASCII в значениях заголовков, что соответствует спецификации Fetch.
    • 'insecure': отключает проверку значений заголовков (эквивалентно insecureHTTPParser: true). Нельзя использовать вместе с insecureHTTPParser. По умолчанию: 'strict'.
  • insecureHTTPParser <boolean> Если задано значение true, используется HTTP-парсер с включенными флагами снисходительного режима. Не рекомендуется использовать небезопасный парсер. Дополнительные сведения см. в разделе --insecure-http-parser. По умолчанию: false.
  • IncomingMessage <http.IncomingMessage> Задает используемый класс IncomingMessage. Полезен для расширения исходного IncomingMessage. По умолчанию: IncomingMessage.
  • joinDuplicateHeaders <boolean> Если задано значение true, этот параметр позволяет объединять значения строк нескольких заголовков запроса через запятую (, ), а не отбрасывать дубликаты. Дополнительные сведения см. в разделе message.headers. По умолчанию: false.
  • keepAlive <boolean> Если задано значение true, сразу после установления нового входящего соединения на сокете включается функция keep-alive, как и в [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 КиБ).
  • noDelay <boolean> Если задано значение true, сразу после установления нового входящего соединения отключается алгоритм Нейгла. По умолчанию: true.
  • requestTimeout: Задает время ожидания в миллисекундах для получения полного запроса от клиента. Дополнительные сведения см. в разделе server.requestTimeout. По умолчанию: 300000.
  • requireHostHeader <boolean> Если задано значение true, сервер принудительно отвечает кодом состояния 400 (Bad Request) на любой запрос HTTP/1.1 без заголовка Host (как того требует спецификация). По умолчанию: true.
  • ServerResponse <http.ServerResponse> Задает используемый класс ServerResponse. Полезен для расширения исходного ServerResponse. По умолчанию: ServerResponse.
  • shouldUpgradeCallback(request) <Function> Функция обратного вызова, которая получает входящий запрос и возвращает логическое значение, определяющее, какие попытки обновления соединения следует принять. Принимаемые запросы на обновление вызывают событие 'upgrade' (или их сокеты уничтожаются, если обработчик не зарегистрирован), а отклоненные запросы вызывают событие 'request', как и любые запросы без обновления соединения. По умолчанию для этого параметра задано значение () => server.listenerCount('upgrade') > 0.
  • uniqueHeaders <Array> Список заголовков ответа, которые следует отправлять только один раз. Если значение заголовка является массивом, его элементы будут объединены с помощью ; .
  • rejectNonStandardBodyWrites <boolean> Если задано значение true, при записи в HTTP-ответ без тела возникает ошибка. По умолчанию: false.
  • optimizeEmptyRequests <boolean> Если задано значение true, запросы без заголовков Content-Length или Transfer-Encoding (указывающих на отсутствие тела) инициализируются уже завершенным потоком тела, поэтому они никогда не будут генерировать события потока (например, 'data' или 'end'). Чтобы определить такой случай, можно использовать req.readableEnded. По умолчанию: false.

• requestListener <Function>

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

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

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

import http from 'node:http';

// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);

const http = require('node:http');

// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);

import http from 'node:http';

// Create a local server to receive data from
const server = http.createServer();

// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);

const http = require('node:http');

// Create a local server to receive data from
const server = http.createServer();

// Listen to the request event
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])

• url <string> | <URL>
• options <Object> Принимает те же options, что и http.request(); по умолчанию используется метод GET.
• callback <Function>
• Возвращает: <http.ClientRequest>

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

callback вызывается с одним аргументом — экземпляром http.IncomingMessage.

Пример получения JSON:

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

  let error;
  // Any 2xx status code signals a successful response but
  // here we're only checking for 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);
    // Consume response data to free up memory
    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}`);
});

// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);
jscopy

http.globalAgent

• Тип: <http.Agent>

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

http.maxHeaderSize

• Тип: <number>

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

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

http.request(options[, callback])

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

• url <string> | <URL>
• options <Object>
  • agent <http.Agent> | <boolean> Управляет поведением Agent. Возможные значения:
    • undefined (по умолчанию): использовать http.globalAgent для этого узла и порта.
    • Agent object: явно использовать переданный 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. Если значение не указано, используются IPv4 и IPv6.
  • headers <Object> | <Array> Объект или массив строк, содержащий заголовки запроса. Массив имеет тот же формат, что и message.rawHeaders.
  • hints <number> Необязательные dns.lookup() подсказки.
  • host <string> Доменное имя или IP-адрес сервера, которому отправляется запрос. По умолчанию: 'localhost'.
  • hostname <string> Псевдоним для host. Для поддержки url.parse(), если указаны и host, и hostname, будет использоваться hostname.
  • httpValidation <string> Определяет строгость проверки значений HTTP-заголовков исходящих запросов. Допустимые значения:
    • 'strict': самая строгая проверка; отклоняет любые символы, отличные от ASCII, а также управляющие символы в значениях заголовков.
    • 'relaxed': допускает ограниченный набор символов, отличных от ASCII, в значениях заголовков в соответствии со спецификацией Fetch.
    • 'insecure': отключает проверку значений всех заголовков (эквивалентно insecureHTTPParser: true). Нельзя использовать вместе с insecureHTTPParser. По умолчанию: 'strict'.
  • 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.

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();

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'. Дополнительные сведения см. в разделе 8.2.3 RFC 2616.

• Отправка заголовка Authorization переопределяет использование параметра auth для формирования базовой аутентификации.

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

const options = new URL('http://abc:xyz@example.com');

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

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

• '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])

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

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

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

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

Пример:

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 [""]'
}

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)

• name <string>
• value <any>

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

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

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

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

Примеры:

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"]'
}

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)

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

Задает максимальное количество простаивающих HTTP-анализаторов.

http.setGlobalProxyFromEnv([proxyEnv])

• proxyEnv <Object> Объект с конфигурацией прокси. Принимает те же параметры, что и параметр proxyEnv, принимаемый Agent. По умолчанию: process.env.
• Возвращает: <Function> Функция, восстанавливающая исходные настройки агента и диспетчера, существовавшие до вызова http.setGlobalProxyFromEnv().

Динамически сбрасывает глобальные настройки, чтобы включить встроенную поддержку прокси для fetch() и http.request()/https.request() во время выполнения, вместо использования флага --use-env-proxy или переменной окружения NODE_USE_ENV_PROXY. Также может использоваться для переопределения настроек, заданных переменными окружения.

Поскольку эта функция сбрасывает глобальные настройки, после ее вызова будут переопределены все ранее настроенные http.globalAgent, https.globalAgent и глобальный диспетчер undici. Рекомендуется вызывать ее до отправки запросов и не вызывать во время выполнения запросов.

Подробнее о форматах URL прокси и синтаксисе NO_PROXY см. в разделе Встроенная поддержка прокси.

Класс: WebSocket

Реализация <WebSocket>, совместимая с браузерами.

Встроенная поддержка прокси

Когда Node.js создает глобальный агент, если для переменной окружения NODE_USE_ENV_PROXY задано значение 1 или включен параметр --use-env-proxy, глобальный агент будет создан с proxyEnv: process.env, что позволит использовать прокси на основе переменных окружения.

Чтобы динамически и глобально включить поддержку прокси, используйте http.setGlobalProxyFromEnv().

Пользовательские агенты также можно создать с поддержкой прокси, передав параметр proxyEnv при создании агента. Значением может быть process.env, если требуется унаследовать конфигурацию из переменных окружения, или объект с отдельными настройками, переопределяющими настройки окружения.

Для настройки поддержки прокси проверяются следующие свойства объекта proxyEnv.

• HTTP_PROXY или http_proxy: URL прокси-сервера для HTTP-запросов. Если заданы оба значения, приоритет имеет http_proxy.
• HTTPS_PROXY или https_proxy: URL прокси-сервера для HTTPS-запросов. Если заданы оба значения, приоритет имеет https_proxy.
• NO_PROXY или no_proxy: разделенный запятыми список узлов, для которых прокси использовать не нужно. Если заданы оба значения, приоритет имеет no_proxy.

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

Формат URL прокси

В URL прокси можно использовать протокол HTTP или HTTPS:

• Прокси HTTP: http://proxy.example.com:8080
• Прокси HTTPS: https://proxy.example.com:8080
• Прокси с аутентификацией: http://username:password@proxy.example.com:8080

Формат NO_PROXY

Переменная окружения NO_PROXY поддерживает несколько форматов:

• * — обходить прокси для всех узлов
• example.com — точное совпадение имени узла
• .example.com — совпадение по суффиксу домена (соответствует sub.example.com)
• *.example.com — совпадение по шаблону домена
• 192.168.1.100 — точное совпадение IP-адреса
• 192.168.1.1-192.168.1.100 — диапазон IP-адресов
• example.com:8080 — имя узла с определенным портом

Несколько записей следует разделять запятыми.

Пример

Чтобы запустить процесс Node.js с поддержкой прокси для всех запросов, отправляемых через глобальный агент по умолчанию, используйте переменную окружения NODE_USE_ENV_PROXY:

NODE_USE_ENV_PROXY=1 HTTP_PROXY=http://proxy.example.com:8080 NO_PROXY=localhost,127.0.0.1 node client.js
consolecopy

Или флаг --use-env-proxy.

HTTP_PROXY=http://proxy.example.com:8080 NO_PROXY=localhost,127.0.0.1 node --use-env-proxy client.js
consolecopy

Чтобы динамически и глобально включить поддержку прокси с помощью process.env (параметр по умолчанию для http.setGlobalProxyFromEnv()):

const http = require('node:http');

// Reads proxy-related environment variables from process.env
const restore = http.setGlobalProxyFromEnv();

// Subsequent requests will use the configured proxies from environment variables
http.get('http://www.example.com', (res) => {
  // This request will be proxied if HTTP_PROXY or http_proxy is set
});

fetch('https://www.example.com', (res) => {
  // This request will be proxied if HTTPS_PROXY or https_proxy is set
});

// To restore the original global agent and dispatcher settings, call the returned function.
// restore();

import http from 'node:http';

// Reads proxy-related environment variables from process.env
http.setGlobalProxyFromEnv();

// Subsequent requests will use the configured proxies from environment variables
http.get('http://www.example.com', (res) => {
  // This request will be proxied if HTTP_PROXY or http_proxy is set
});

fetch('https://www.example.com', (res) => {
  // This request will be proxied if HTTPS_PROXY or https_proxy is set
});

// To restore the original global agent and dispatcher settings, call the returned function.
// restore();

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

const http = require('node:http');

const restore = http.setGlobalProxyFromEnv({
  http_proxy: 'http://proxy.example.com:8080',
  https_proxy: 'https://proxy.example.com:8443',
  no_proxy: 'localhost,127.0.0.1,.internal.example.com',
});

// Subsequent requests will use the configured proxies
http.get('http://www.example.com', (res) => {
  // This request will be proxied through proxy.example.com:8080
});

fetch('https://www.example.com', (res) => {
  // This request will be proxied through proxy.example.com:8443
});

import http from 'node:http';

http.setGlobalProxyFromEnv({
  http_proxy: 'http://proxy.example.com:8080',
  https_proxy: 'https://proxy.example.com:8443',
  no_proxy: 'localhost,127.0.0.1,.internal.example.com',
});

// Subsequent requests will use the configured proxies
http.get('http://www.example.com', (res) => {
  // This request will be proxied through proxy.example.com:8080
});

fetch('https://www.example.com', (res) => {
  // This request will be proxied through proxy.example.com:8443
});

Чтобы создать пользовательский агент со встроенной поддержкой прокси:

const http = require('node:http');

// Creating a custom agent with custom proxy support.
const agent = new http.Agent({ proxyEnv: { HTTP_PROXY: 'http://proxy.example.com:8080' } });

http.request({
  hostname: 'www.example.com',
  port: 80,
  path: '/',
  agent,
}, (res) => {
  // This request will be proxied through proxy.example.com:8080 using the HTTP protocol.
  console.log(`STATUS: ${res.statusCode}`);
});
cjscopy

Также можно использовать следующий вариант:

const http = require('node:http');
// Use lower-cased option name.
const agent1 = new http.Agent({ proxyEnv: { http_proxy: 'http://proxy.example.com:8080' } });
// Use values inherited from the environment variables, if the process is started with
// HTTP_PROXY=http://proxy.example.com:8080 this will use the proxy server specified
// in process.env.HTTP_PROXY.
const agent2 = new http.Agent({ proxyEnv: process.env });
cjscopy