Класс: 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.Agent.

MJS модули

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

CJS модули

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

agent.createConnection(options[, callback])

• 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'.

Модули MJS

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

Модули CJS

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 <Объект>
  • httpVersion <строка>
  • httpVersionMajor <целое число>
  • httpVersionMinor <целое число>
  • statusCode <целое число>
  • statusMessage <строка>
  • headers <Объект>
  • rawHeaders <массив строк>

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

Модули MJS

import { request } from 'node:http';

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

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

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

Модули CJS

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

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

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

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

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

Событие: 'response'

• 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'.

Модули MJS

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

Модули CJS

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

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'. Вызов этого приведет к удалению оставшихся данных в ответе и уничтожению сокета.

См. 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() или не будет записан первый фрагмент данных запроса. Затем он пытается упаковать заголовки запроса и данные в один 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[] copy

request.getHeaderNames()

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

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

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

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

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

request.getRawHeaderNames()

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

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

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 <string>
• Возвращает: <boolean>

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

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

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

request.reusedSocket

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

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

MJS-модули

import http from '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

CJS-модули

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

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

Модули MJS

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

Модули CJS

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

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, (res) => {
      // ...
    })
    .on('error', (err) => {
      // Check if retry is needed
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();

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' из-за способа подключения анализатора протокола к сокету.

Модули MJS

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

Модули CJS

const http = require('node:http');
const options = {
  host: 'www.google.com',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`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

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

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

request.writableFinished

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

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

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

• chunk <строка> | <Буфер> | <Uint8 массив>
• 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, из которого произошла ошибка.

Модули MJS

import http from 'node:http';

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

Модули CJS

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

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

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

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

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

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

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

  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
}); 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 <Функция>

Прекращает прием новых соединений сервером и закрывает все соединения, подключенные к этому серверу, которые не отправляют запрос или не ожидают ответа. См. 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); copy

server.closeAllConnections()

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

Это жёсткий способ закрытия всех соединений и следует применять с осторожностью. При использовании вместе с 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); copy

server.closeIdleConnections()

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

Начиная с Node.js 19.0.0, нет необходимости вызывать этот метод в сочетании с server.close, чтобы освободить keep-alive соединения. Его использование не принесёт вреда, и оно может быть полезно для обеспечения обратной совместимости для библиотек и приложений, которым необходимо поддерживать версии, более старые, чем 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); copy

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.

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

server[Symbol.asyncDispose]()

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

Класс: 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

• <boolean>

Свойство 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 <строка>
• Возвращает: <boolean>

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

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

response.headersSent

• <boolean>

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

response.removeHeader(name)

• name <строка>

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

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

response.req

• <http.IncomingMessage>

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

response.sendDate

• <boolean>

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

Это следует отключать только для тестирования; 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(), свойство обнуляется.

MJS модули

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

CJS модули

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

• <число> По умолчанию: 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

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

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

response.writableFinished

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

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

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

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

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

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

Запись в тело запрещена, если метод запроса или код состояния ответа не поддерживают контент. При попытке записать в тело для запроса 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 <Объект>
• callback <Функция>

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

Пример

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

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

const earlyHintsCallback = () => console.log('early hints message sent');
response.writeEarlyHints({
  'link': earlyHintsLinks,
}, earlyHintsCallback); 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 ответа. Например: 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(`http://${process.env.HOST ?? 'localhost'}${request.url}`); copy

Когда 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: ''
} copy

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

Класс: http.OutgoingMessage

• Расширяет: <Поток>

Этот класс служит родительским классом для 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 <строка> | <Буфер> | <Uint8 массив>
• 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 <строка> Название заголовка
• Возвращает: <строка> | <неопределено>

Получает значение 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>

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

outgoingMessage.writableFinished

• <boolean>

Является true, если все данные были сброшены в базу данных.

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

• requestListener <Функция>

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

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

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

Модули MJS

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

Модули CJS

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

Модули MJS

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

Модули CJS

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 <строка> | <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-клиентских запросов. Отличается от конфигурации Agent по умолчанию тем, что keepAlive включен, а таймаут timeout составляет 5 секунд.

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 <логическое> Если установлено в true, он будет использовать HTTP-парсер с включёнными флагами лояльности. Необходимо избегать использования небезопасного парсера. См. --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.

MJS-модули

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

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

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

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

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

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

CJS-модули

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

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

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

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

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

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

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

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

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

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

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

• Отправка заголовка 'Expect' немедленно отправит заголовки запроса. Обычно, при отправке 'Expect: 100-continue', необходимо установить таймаут и обработчик события 'continue'. Дополнительную информацию см. в RFC 2616, раздел 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
• '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 <строка>
• label <строка> Метка для сообщения об ошибке. По умолчанию: 'Header name'.

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

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

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

Пример:

MJS модули

import { validateHeaderName } from 'node:http';

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

CJS модули

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

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

http.validateHeaderValue(name, value)

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

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

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

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

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

Примеры:

MJS модули

import { validateHeaderValue } from 'node:http';

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

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

CJS модули

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

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

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

http.setMaxIdleHTTPParsers(max)

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

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