Класс: 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');
}); copy

Агент также может быть использован для отдельного запроса. Предоставление {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
}); copy

new Agent([options])

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

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

По умолчанию http.globalAgent, который используется http.request(), имеет все эти значения, установленные по умолчанию.

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

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

agent.createConnection(options[, callback])

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

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

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

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

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

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

agent.keepSocketAlive(socket)

• socket <stream.Duplex>

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

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

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

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

agent.reuseSocket(socket, request)

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

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

socket.ref(); copy

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

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

agent.destroy()

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

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

agent.freeSockets

• <Объект>

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

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

agent.getName([options])

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

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

agent.maxFreeSockets

• <число>

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

agent.maxSockets

• <число>

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

agent.maxTotalSockets

• <число>

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

agent.requests

• <Объект>

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

agent.sockets

• <Объект>

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

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

Для обеспечения обратной совместимости, 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':

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

Событие: 'continue'

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

Событие: 'finish'

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

Событие: 'information'

• info <Объект>
  • httpVersion <строка>
  • httpVersionMajor <целое число>
  • httpVersionMinor <целое число>
  • statusCode <целое число>
  • statusMessage <строка>
  • headers <Объект>
  • rawHeaders <массив строк>

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

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

Статусы 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>
• socket <stream.Duplex>
• head <Buffer>

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

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

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

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, socket, head) => {
  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
               'Upgrade: WebSocket\r\n' +
               'Connection: Upgrade\r\n' +
               '\r\n');

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

request.abort()

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

request.aborted

• <булево значение>

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

request.connection

• <stream.Duplex>

См. request.socket.

request.cork()

См. writable.cork().

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

• data <строка> | <Buffer> | <Uint8Array>
• encoding <строка>
• callback <Функция>
• Возвращает: <this>

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

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

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

request.destroy([error])

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

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

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

request.destroyed

• <булево>

Будет true после вызова request.destroy().

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

request.finished

• <булево>

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

request.flushHeaders()

Очищает заголовки запроса.

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

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

request.getHeader(name)

• name <строка>
• Возвращает: <любой>

Считывает заголовок запроса. Название нечувствительно к регистру. Тип возвращаемого значения зависит от аргументов, переданных в 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[] copy

request.getHeaderNames()

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

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

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

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

request.getHeaders()

• Возвращает: <Объект>

Возвращает поверхностную копию текущих исходящих заголовков. Поскольку используется поверхностная копия, значения массивов могут быть изменены без дополнительных вызовов различных методов модуля 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'] } copy

request.getRawHeaderNames()

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

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

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

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

request.hasHeader(name)

• name <строка>
• Возвращает: <булево>

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

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

request.maxHeadersCount

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

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

request.path

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

request.method

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

request.host

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

request.protocol

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

request.removeHeader(name)

• name <строка>

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

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

request.reusedSocket

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

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

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

// 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 copy

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

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

request.setHeader(name, value)

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

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

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

или

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

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

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

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

request.setNoDelay([noDelay])

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

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

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

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

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

request.setTimeout(timeout[, callback])

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

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

request.socket

• <stream.Duplex>

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

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

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

request.uncork()

См. writable.uncork().

request.writableEnded

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

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

request.writableFinished

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

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

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

• chunk <строка> | <Буфер> | <Uint8Array>
• encoding <строка>
• callback <Функция>
• Возвращает: <логическое>

Отправляет фрагмент тела. Этот метод можно вызывать несколько раз. Если Content-Length не задан, данные будут автоматически закодированы в кодировке HTTP Chunked, чтобы сервер знал, когда данные заканчиваются. Заголовок 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, из которого произошла ошибка.

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

При возникновении события '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');
}); copy

Событие: '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'
• socket <stream.Duplex> Сеть сокет между сервером и клиентом
• head <Buffer> Первый пакет обновлённого потока (может быть пустым)

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

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

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

server.close([callback])

• callback <Function>

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

server.closeAllConnections()

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

server.closeIdleConnections()

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

server.headersTimeout

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

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

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

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

server.listen()

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

server.listening

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

server.maxHeadersCount

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

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

server.requestTimeout

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

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

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

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

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

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

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

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

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

server.maxRequestsPerSocket

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

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

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

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

server.timeout

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

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

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

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

server.keepAliveTimeout

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

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

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

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

Класс: http.ServerResponse

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

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

Событие: 'close'

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

Событие: 'finish'

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

response.addTrailers(headers)

• headers <Объект>

Этот метод добавляет 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(); copy

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

response.connection

• <stream.Duplex>

См. response.socket.

response.cork()

См. writable.cork().

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

• data <строка> | <Буфер> | <Uint8Array>
• encoding <строка>
• callback <Функция>
• Возвращает: <this>

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

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

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

response.finished

• <булево значение>

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

response.flushHeaders()

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

response.getHeader(name)

• name <строка>
• Возвращает: <любое значение>

Читает заголовок, который уже был помещён в очередь, но ещё не отправлен клиенту. Имя регистронезависимо. Тип возвращаемого значения зависит от аргументов, предоставленных 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[] copy

response.getHeaderNames()

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

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

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

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

response.getHeaders()

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

Возвращает поверхностную копию текущих исходящих заголовков. Поскольку используется поверхностная копия, значения массивов могут быть изменены без дополнительных вызовов различных методов модуля 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'] } copy

response.hasHeader(name)

• name <строка>
• Возвращает: <булево значение>

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

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

response.headersSent

• <булево значение>

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

response.removeHeader(name)

• name <строка>

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

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

response.req

• <http.IncomingMessage>

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

response.sendDate

• <булево значение>

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

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

response.setHeader(name, value)

• name <строка>
• value <любое значение>
• Возвращает: <http.ServerResponse>

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

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

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

или

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

Попытка установить имя или значение поля заголовка, содержащего недопустимые символы, приведёт к выбросу исключения 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');
}); copy

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

response.setTimeout(msecs[, callback])

• msecs <число>
• callback <Функция>
• Возвращает: <http.ServerResponse>

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

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

response.socket

• <stream.Duplex>

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

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

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

response.statusCode

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

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

response.statusCode = 404; copy

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

response.statusMessage

• <строка>

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

response.statusMessage = 'Not found'; copy

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

response.strictContentLength

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

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

response.uncork()

См. writable.uncork().

response.writableEnded

• <логическое значение>

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

response.writableFinished

• <логическое значение>

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

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

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

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

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

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

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

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

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

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

response.writeContinue()

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

response.writeEarlyHints(hints[, callback])

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

Отправляет клиенту сообщение 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); copy

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

Этот метод можно вызвать только один раз для сообщения, и его нужно вызвать до того, как будет вызван 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');
}); copy

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

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

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-заголовков и полезной нагрузки, так как базовый сокет может быть повторно использован несколько раз в случае keep-alive.

Событие: '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');
  });
}); copy

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

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

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

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

message.rawTrailers

• <string[]>

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

message.setTimeout(msecs[, callback])

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

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

message.socket

• <stream.Duplex>

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

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

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

message.statusCode

• <number>

Только для ответа, полученного от http.ClientRequest.

Код состояния HTTP из 3 цифр. Например: 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 copy

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

new URL(request.url, `http://${request.headers.host}`); copy

Когда request.url является '/status?name=ryan' и request.headers.host является 'localhost:3000':

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

Класс: http.OutgoingMessage

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

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

Событие: 'drain'

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

Событие: 'finish'

Срабатывает, когда передача успешно завершена.

Событие: 'prefinish'

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

outgoingMessage.addTrailers(headers)

• headers <Объект>

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

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

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

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

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

outgoingMessage.appendHeader(name, value)

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

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

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

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

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

outgoingMessage.connection

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

outgoingMessage.cork()

См. writable.cork().

outgoingMessage.destroy([error])

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

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

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

• chunk <строка> | <Буфер> | <Uint8Array>
• encoding <строка> Необязательно, Значение по умолчанию: utf8
• callback <Функция> Необязательно
• Возвращает: <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 <строка> Название заголовка
• Возвращает <строку> | <undefined>

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

outgoingMessage.getHeaderNames()

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

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

outgoingMessage.getHeaders()

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

Возвращает поверхностную копию текущих исходящих заголовков. Поскольку используется поверхностная копия, значения массивов могут быть изменены без дополнительных вызовов различных методов модуля 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'] } copy

outgoingMessage.hasHeader(name)

• name <строка>
• Возвращает <логическое значение>

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

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

outgoingMessage.headersSent

• <логическое значение>

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

outgoingMessage.pipe()

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

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

outgoingMessage.removeHeader(name)

• name <строка> Имя заголовка

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

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

outgoingMessage.setHeader(name, value)

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

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

outgoingMessage.setHeaders(headers)

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

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

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

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

или

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

Когда заголовки были установлены с помощью 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');
}); copy

outgoingMessage.setTimeout(msesc[, callback])

• msesc <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>

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

outgoingMessage.writableFinished

• <boolean>

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

outgoingMessage.writableHighWaterMark

• <number>

Уровень буфера базового сокета, если он задан. Иначе — стандартный уровень буфера, когда 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 <Объект>

  • connectionsCheckingInterval: Устанавливает значение интервала в миллисекундах для проверки таймаута запроса и заголовков в неполных запросах. По умолчанию: 30000.
  • headersTimeout: Устанавливает значение таймаута в миллисекундах для получения полных HTTP-заголовков от клиента. Подробнее см. server.headersTimeout. По умолчанию: 60000.
  • highWaterMark <число> Дополнительно переопределяет все значения socket и writableHighWaterMark. Это влияет на свойство highWaterMark как для IncomingMessage, так и для ServerResponse объектов. По умолчанию: См. stream.getDefaultHighWaterMark().
  • insecureHTTPParser <логическое значение> Использует небезопасный HTTP-парсер, который принимает недопустимые HTTP-заголовки, когда true. Не рекомендуется использовать небезопасный парсер. Подробнее см. --insecure-http-parser. По умолчанию: false.
  • IncomingMessage <http.IncomingMessage> Указывает класс IncomingMessage, который будет использоваться. Полезно для расширения исходного класса IncomingMessage. По умолчанию: IncomingMessage.
  • joinDuplicateHeaders <логическое значение> Объединяет значения строк полей нескольких заголовков в запросе с , , вместо удаления дубликатов. Подробнее см. message.headers. По умолчанию: false.
  • keepAlive <логическое значение> Если установлено значение true, включает функцию keep-alive на сокете сразу после получения нового входящего подключения, аналогично тому, что выполняется в [socket.setKeepAlive([enable][, initialDelay])][socket.setKeepAlive(enable, initialDelay)]. По умолчанию: false.
  • keepAliveInitialDelay <число> Если установлено положительное значение, устанавливает начальную задержку перед отправкой первого запроса keepalive на незанятый сокет. По умолчанию: 0.
  • requestTimeout: Устанавливает значение таймаута в миллисекундах для получения всего запроса от клиента. Подробнее см. server.requestTimeout. По умолчанию: 300000.
  • ServerResponse <http.ServerResponse> Указывает класс ServerResponse, который будет использоваться. Полезно для расширения исходного класса ServerResponse. По умолчанию: ServerResponse.
  • uniqueHeaders <Массив> Список заголовков ответа, которые должны быть отправлены только один раз. Если значение заголовка является массивом, элементы будут объединены с помощью ; .

• requestListener <Функция>

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

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

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

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

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

http.get(options[, callback])

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

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

http.globalAgent

• <http.Agent>

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

http.maxHeaderSize

• <число>

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

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

http.request(options[, callback])

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

• url <строка> | <URL>
• options <Объект>
  • agent <http.Agent> | <логическое значение> Управляет поведением Agent. Возможные значения:
    • undefined (по умолчанию): использовать http.globalAgent для этого хоста и порта.
    • Agent объект: явно использовать переданный Agent.
    • false: вызывает использование нового Agent с значениями по умолчанию.
  • auth <строка> Базовая аутентификация ('user:password') для вычисления заголовка Authorization.
  • createConnection <Функция> Функция, создающая сокет/поток для использования в запросе, когда опция agent не используется. Это можно использовать для избежания создания настраиваемого класса Agent только для переопределения функции по умолчанию createConnection. Подробнее см. agent.createConnection(). Любой поток Duplex является допустимым возвращаемым значением.
  • defaultPort <число> Порт по умолчанию для протокола. По умолчанию: agent.defaultPort если используется Agent, в противном случае undefined.
  • family <число> Семейство IP-адресов для использования при разрешении host или hostname . Допустимые значения: 4 или 6. При отсутствии указания будут использоваться как IP v4, так и v6.
  • headers <Объект> Объект, содержащий заголовки запроса.
  • hints <число> Необязательные dns.lookup() подсказки.
  • host <строка> Имя домена или IP-адрес сервера, которому необходимо отправить запрос. По умолчанию: 'localhost'.
  • hostname <строка> Псевдоним для host. Для поддержки url.parse(), будет использоваться hostname если оба host и hostname указаны.
  • insecureHTTPParser <логическое значение> Использовать небезопасный HTTP-парсер, который принимает недопустимые HTTP-заголовки, когда true. Использование небезопасного парсера следует избегать. Подробнее см. --insecure-http-parser. По умолчанию: false
  • joinDuplicateHeaders <логическое значение> Объединяет значения строк поля нескольких заголовков в запросе с помощью , вместо удаления дубликатов. Подробнее см. message.headers. По умолчанию: false.
  • localAddress <строка> Локальный интерфейс для привязки сетевых соединений.
  • localPort <число> Локальный порт для подключения.
  • lookup <Функция> Пользовательская функция поиска. По умолчанию: dns.lookup().
  • maxHeaderSize <число> Необязательно переопределяет значение --max-http-header-size (максимальная длина заголовков ответа в байтах) для ответов, полученных от сервера. По умолчанию: 16384 (16 КБ).
  • method <строка> Строка, определяющая метод HTTP-запроса. По умолчанию: 'GET'.
  • path <строка> Путь запроса. Должен включать строку запроса, если она есть. Например, '/index.html?page=12'. Исключение возникает, когда путь запроса содержит недопустимые символы. В настоящее время отбрасываются только пробелы, но это может измениться в будущем. По умолчанию: '/'.
  • port <число> Порт удаленного сервера. По умолчанию: defaultPort если задан, в противном случае 80.
  • protocol <строка> Протокол для использования. По умолчанию: 'http:'.
  • setHost <логическое значение>: Указывает, добавлять ли автоматически заголовок Host. По умолчанию true.
  • signal <AbortSignal>: Объект AbortSignal, который может быть использован для прерывания текущего запроса.
  • socketPath <строка> Unix-доменный сокет. Не может быть использован, если указан один из host или port, так как они указывают на TCP-сокет.
  • timeout <число>: Число, задающее тайм-аут сокета в миллисекундах. Это установит тайм-аут до подключения сокета.
  • uniqueHeaders <Массив> Список заголовков запроса, которые должны быть отправлены только один раз. Если значение заголовка является массивом, элементы будут объединены с использованием ; .
• callback <Функция>
• Возвращает: <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.

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

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

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

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

• Отправка заголовка 'Connection: keep-alive' уведомит Node.js о том, что соединение с сервером должно сохраняться до следующего запроса.

• Отправка заголовка 'Content-Length' отключит по умолчанию кодировку чанков.

• Отправка заголовка 'Expect' немедленно отправит заголовки запроса. Обычно при отправке 'Expect: 100-continue' следует установить таймаут и обработчик события 'continue'. Дополнительную информацию см. в RFC 2616, раздел 8.2.3.

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

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

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

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

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

• '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
• 'error' на объекте res с ошибкой с сообщением 'Error: aborted' и кодом 'ECONNRESET'
• 'close'
• '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
• 'error' на объекте res с ошибкой с сообщением 'Error: aborted' и кодом 'ECONNRESET', или ошибкой, с которой был вызван req.destroy()
• 'close'
• '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 <строка>
• label <строка> Метка для сообщения об ошибке. По умолчанию: 'Header name'.

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

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

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

Пример:

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

http.validateHeaderValue(name, value)

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

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

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

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

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

Примеры:

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

http.setMaxIdleHTTPParsers(max)

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

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