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

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

См. response.socket.

response.cork()

См. writable.cork().

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

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

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

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

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

response.finished

• <булево>

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

response.flushHeaders()

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

response.getHeader(name)

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

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

response.setHeader('Content-Type', 'text/html');
response.setHeader('Content-Length', Buffer.byteLength(body));
response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);
const contentType = response.getHeader('content-type');
// contentType is 'text/html'
const contentLength = response.getHeader('Content-Length');
// contentLength is of type number
const setCookie = response.getHeader('set-cookie');
// setCookie is of type string[] copy

response.getHeaderNames()

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

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

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

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

response.getHeaders()

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

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

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

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

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

response.hasHeader(name)

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

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

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

response.headersSent

• <булево>

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

response.removeHeader(name)

• name <строка>

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

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

response.req

• <http.ВходноеСообщение>

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

response.sendDate

• <булево>

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

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

response.setHeader(name, value)

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

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

Устанавливает значение одного заголовка для неявных заголовков. Если этот заголовок уже существует в заголовках, которые будут отправлены, его значение будет заменено. Используйте массив строк для отправки нескольких заголовков с одинаковым именем. Значения, отличные от строк, будут сохранены без изменений. Поэтому 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 <Объект> | <Массив>
• Возвращает: <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 <Ошибка>
• Возвращает: <this>

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

message.headers

• <Объект>

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

Ключевые пары имён и значений заголовков. Имена заголовков в нижнем регистре.

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

• <Объект>

Аналогично 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

• <строка>

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

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

message.method

• <строка>

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

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

message.rawHeaders

• <строка[]>

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

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

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

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

• <строка[]>

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

message.setTimeout(msecs[, callback])

• msecs <число>
• callback <Функция>
• Возвращает: <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 <строка> | <массив строк> Значение заголовка
• Возвращает: <текущий объект>

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

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

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

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

outgoingMessage.connection

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

outgoingMessage.cork()

См. writable.cork().

outgoingMessage.destroy([error])

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

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

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

• chunk <строка> | <Буфер> | <Uint8 массив>
• encoding <строка> Необязательно, Значение по умолчанию: utf8
• callback <Функция> Необязательно
• Возвращает: <текущий объект>

Завершает исходящее сообщение. Если какие-либо части тела не отправлены, они будут отправлены в подлежащую системе. Если сообщение фрагментировано, будет отправлен завершающий фрагмент 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. Это свойство не указывает, была ли данные сброшены. Для этой цели используйте message.writableFinished.

outgoingMessage.writableFinished

• <boolean>

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

outgoingMessage.writableHighWaterMark

• <number>

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

outgoingMessage.writableLength

• <number>

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

outgoingMessage.writableObjectMode

• <boolean>

Всегда false.

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

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

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

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

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

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

http.METHODS

• <string[]>

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

http.STATUS_CODES

• <Object>

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

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

• options <Объект>

  • connectionsCheckingInterval: Устанавливает значение интервала в миллисекундах для проверки таймаута запроса и заголовков в неполных запросах. По умолчанию: 30000.
  • headersTimeout: Устанавливает значение таймаута в миллисекундах для получения полных HTTP-заголовков от клиента. Дополнительная информация в server.headersTimeout. По умолчанию: 60000.
  • highWaterMark <число> Дополнительно переопределяет все значения socket readableHighWaterMark и writableHighWaterMark. Это влияет на свойство highWaterMark как для IncomingMessage, так и для ServerResponse. По умолчанию: см. stream.getDefaultHighWaterMark().
  • insecureHTTPParser <логическое значение> Использовать небезопасный HTTP-парсер, который принимает недопустимые HTTP-заголовки, когда true. Не рекомендуется использовать небезопасный парсер. Дополнительная информация в --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 <число> Если установлено в положительное число, устанавливает начальную задержку перед отправкой первого запроса keepalive на неактивный сокет. По умолчанию: 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 <логическое_значение> Использовать небезопасный HTTP-парсер, который принимает недопустимые HTTP-заголовки, когда true. Использование небезопасного парсера следует избегать. См. --insecure-http-parser для получения дополнительной информации. По умолчанию: false
  • joinDuplicateHeaders <логическое_значение> Объединяет значения строк поля нескольких заголовков в запросе с помощью , вместо удаления дубликатов. См. message.headers для получения дополнительной информации. По умолчанию: false.
  • localAddress <строка> Локальный интерфейс для привязки к сетевым подключениям.
  • localPort <число> Локальный порт для подключения.
  • lookup <Функция> Пользовательская функция поиска. По умолчанию: dns.lookup().
  • maxHeaderSize <число> Необязательно переопределяет значение --max-http-header-size (максимальная длина заголовков ответа в байтах) для ответов, полученных от сервера. По умолчанию: 16384 (16 КБ).
  • method <строка> Строка, определяющая метод HTTP-запроса. По умолчанию: 'GET'.
  • path <строка> Путь запроса. Должен включать строку запроса, если она есть. Например: '/index.html?page=12'. Исключение выбрасывается, когда путь запроса содержит недопустимые символы. В настоящее время отклоняются только пробелы, но в будущем это может измениться. По умолчанию: '/'.
  • port <число> Порт удаленного сервера. По умолчанию: defaultPort если установлен, иначе 80.
  • protocol <строка> Протокол для использования. По умолчанию: 'http:'.
  • setHost <логическое_значение>: Указывает, добавлять ли автоматически заголовок Host. По умолчанию true.
  • signal <AbortSignal>: Объект AbortSignal, который может быть использован для прерывания текущего запроса.
  • socketPath <строка> Unix-сокет. Не может использоваться, если указан один из host или port, так как они указывают на TCP-сокет.
  • timeout <число>: Число, определяющее таймаут сокета в миллисекундах. Это установит таймаут до подключения сокета.
  • uniqueHeaders <Массив> Список заголовков запроса, которые должны быть отправлены только один раз. Если значение заголовка является массивом, элементы будут объединены с помощью ; .
• callback <Функция>
• Возвращает: <http.ClientRequest>

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

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

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

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

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

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

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.

• Ошибка значения undefined идентифицируется по 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.