new Agent([options])

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

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

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

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

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

agent.createConnection(options[, callback])

• options <Object> Параметры с данными о соединении. Формат параметров см. в разделе net.createConnection()
• callback <Function> Функция обратного вызова, получающая созданный сокет
• Возвращает: <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

• Тип: <Object>

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

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

agent.getName([options])

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

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

agent.maxFreeSockets

• Тип: <number>

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

agent.maxSockets

• Тип: <number>

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

agent.maxTotalSockets

• Тип: <number>

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

agent.requests

• Тип: <Object>

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

agent.sockets

• Тип: <Object>

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

Событие: 'abort'

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

Событие: 'close'

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

Событие: 'connect'

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

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

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

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

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

// Create an HTTP tunneling proxy
const proxy = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // Connect to an origin server
  const { port, hostname } = new URL(`http://${req.url}`);
  const serverSocket = connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' +
                    'Proxy-agent: Node.js-Proxy\r\n' +
                    '\r\n');
    serverSocket.write(head);
    serverSocket.pipe(clientSocket);
    clientSocket.pipe(serverSocket);
  });
});

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

  // Make a request to a tunneling proxy
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  };

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

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

    // Make a request over an HTTP tunnel
    socket.write('GET / HTTP/1.1\r\n' +
                 'Host: www.google.com:80\r\n' +
                 'Connection: close\r\n' +
                 '\r\n');
    socket.on('data', (chunk) => {
      console.log(chunk.toString());
    });
    socket.on('end', () => {
      proxy.close();
    });
  });
});

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

// Create an HTTP tunneling proxy
const proxy = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // Connect to an origin server
  const { port, hostname } = new URL(`http://${req.url}`);
  const serverSocket = net.connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' +
                    'Proxy-agent: Node.js-Proxy\r\n' +
                    '\r\n');
    serverSocket.write(head);
    serverSocket.pipe(clientSocket);
    clientSocket.pipe(serverSocket);
  });
});

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

  // Make a request to a tunneling proxy
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  };

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

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

    // Make a request over an HTTP tunnel
    socket.write('GET / HTTP/1.1\r\n' +
                 'Host: www.google.com:80\r\n' +
                 'Connection: close\r\n' +
                 '\r\n');
    socket.on('data', (chunk) => {
      console.log(chunk.toString());
    });
    socket.on('end', () => {
      proxy.close();
    });
  });
});

Событие: 'continue'

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

Событие: 'finish'

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

Событие: 'information'

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

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

import { request } from 'node:http';

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

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

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

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

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

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

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

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

Событие: 'response'

• response <http.IncomingMessage>

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

Событие: 'socket'

• socket <stream.Duplex>

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

Событие: 'timeout'

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

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

Событие: 'upgrade'

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

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

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

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

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

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

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.finished

• Тип: <boolean>

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

request.flushHeaders()

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

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

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

request.getHeader(name)

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

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

request.setHeader('content-type', 'text/html');
request.setHeader('Content-Length', Buffer.byteLength(body));
request.setHeader('Cookie', ['type=ninja', 'language=javascript']);
const contentType = request.getHeader('Content-Type');
// 'contentType' is 'text/html'
const contentLength = request.getHeader('Content-Length');
// 'contentLength' is of type number
const cookie = request.getHeader('Cookie');
// 'cookie' is of type string[] 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».

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

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

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

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

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

retriableRequest();

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

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

retriableRequest();

request.setHeader(name, value)

• name <string>
• value <any>

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

request.setHeader('Content-Type', 'application/json'); 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 <boolean>

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

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

• enable <boolean>
• initialDelay <number>

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

request.setTimeout(timeout[, callback])

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

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

request.socket

• Тип: <stream.Duplex>

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

import http from 'node:http';
const options = {
  host: 'www.google.com',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`Your IP address is ${ip} and your source port is ${port}.`);
  // Consume response object
});

const http = require('node:http');
const options = {
  host: 'www.google.com',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`Your IP address is ${ip} and your source port is ${port}.`);
  // Consume response object
});

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

request.uncork()

См. writable.uncork().

request.writableEnded

• Тип: <boolean>

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

request.writableFinished

• Тип: <boolean>

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

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

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

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

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

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

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

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

Событие: '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» или, в случае ошибки HPE_HEADER_OVERFLOW, HTTP-ответ «431 Request Header Fields Too Large». Если сокет недоступен для записи или заголовки текущего присоединенного http.ServerResponse уже отправлены, сокет немедленно уничтожается.

socket — это объект net.Socket, в котором возникла ошибка.

import http from 'node:http';

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

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

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

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

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

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

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

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

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

Событие: 'close'

Создается при закрытии сервера.

Событие: 'connect'

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

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

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

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

Событие: 'connection'

• socket <stream.Duplex>

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

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

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

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

Событие: 'dropRequest'

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

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

Событие: 'request'

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

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

Событие: 'upgrade'

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

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

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

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

server.close([callback])

• callback <Function>

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

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

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

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

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

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

server.listen(8000);
// Close the server after 10 seconds
setTimeout(() => {
  server.close(() => {
    console.log('server on port 8000 closed successfully');
  });
  // Closes all connections, ensuring the server closes successfully
  server.closeAllConnections();
}, 10000); copy

server.closeIdleConnections()

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

Начиная с Node.js 19.0.0, для закрытия неактивных подключений keep-alive больше не нужно вызывать этот метод вместе с server.close. Однако его вызов не причинит вреда и может быть полезен для обеспечения обратной совместимости библиотек и приложений, которым необходимо поддерживать версии старше 19.0.0. При использовании этого метода вместе с server.close рекомендуется вызывать его после server.close, чтобы избежать состояния гонки, при котором между вызовами этого метода и server.close создаются новые подключения.

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

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

server.listen(8000);
// Close the server after 10 seconds
setTimeout(() => {
  server.close(() => {
    console.log('server on port 8000 closed successfully');
  });
  // Closes idle connections, such as keep-alive connections. Server will close
  // once remaining active connections are terminated
  server.closeIdleConnections();
}, 10000); copy

server.headersTimeout

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

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

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

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

server.listen()

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

server.listening

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

server.maxHeadersCount

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

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

server.requestTimeout

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

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

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

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

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

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

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

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

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

server.maxRequestsPerSocket

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

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

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

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

server.timeout

• Тип: <number> Время ожидания в миллисекундах. По умолчанию: 0 (без ограничения времени ожидания)

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

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

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

server.keepAliveTimeout

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

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

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

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

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

server.keepAliveTimeoutBuffer

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

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

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

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

server[Symbol.asyncDispose]()

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

Событие: 'close'

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

Событие: 'finish'

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

response.addTrailers(headers)

• headers <Object>

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

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

Для отправки завершающих заголовков HTTP требует передать заголовок Trailer со списком имён полей заголовков в его значении. Например:

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

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

response.connection

• Тип: <stream.Duplex>

См. response.socket.

response.cork()

См. writable.cork().

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

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

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

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

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

response.finished

• Тип: <boolean>

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

response.flushHeaders()

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

response.getHeader(name)

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

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

response.setHeader('Content-Type', 'text/html');
response.setHeader('Content-Length', Buffer.byteLength(body));
response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);
const contentType = response.getHeader('content-type');
// contentType 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()

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

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

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

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

response.getHeaders()

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

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

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

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

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

response.hasHeader(name)

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

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

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

response.headersSent

• Тип: <boolean>

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

response.removeHeader(name)

• name <string>

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

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

response.req

• Тип: <http.IncomingMessage>

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

response.sendDate

• Тип: <boolean>

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

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

response.setHeader(name, value)

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

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

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

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

или

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

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

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

// Returns content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
}); copy

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

response.setTimeout(msecs[, callback])

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

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

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

response.socket

• Тип: <stream.Duplex>

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

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

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

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

response.statusCode

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

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

response.statusCode = 404; copy

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

response.statusMessage

• Тип: <string>

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

response.statusMessage = 'Not found'; copy

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

response.strictContentLength

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

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

response.uncork()

См. writable.uncork().

response.writableEnded

• Тип: <boolean>

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

response.writableFinished

• Тип: <boolean>

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

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

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

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

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

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

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

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

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

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

response.writeContinue()

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

response.writeEarlyHints(hints[, callback])

• hints <Object>
• callback <Function>

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

Пример

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

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

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

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

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

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

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

Возвращает ссылку на ServerResponse, что позволяет объединять вызовы в цепочку.

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

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

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

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

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

// Returns content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
}); copy

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

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

response.writeProcessing()

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

Событие: 'aborted'

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

Событие: 'close'

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

message.aborted

• Тип: <boolean>

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

message.complete

• Тип: <boolean>

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

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

const req = http.request({
  host: '127.0.0.1',
  port: 8080,
  method: 'POST',
}, (res) => {
  res.resume();
  res.on('end', () => {
    if (!res.complete)
      console.error(
        'The connection was terminated while the message was still being sent');
  });
}); copy

message.connection

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

message.destroy([error])

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

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

message.headers

• Тип: <Object>

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

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

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

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

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

message.headersDistinct

• Тип: <Object>

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

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

message.httpVersion

• Тип: <string>

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

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

message.method

• Тип: <string>

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

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

message.rawHeaders

• Тип: <string[]>

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

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

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

// Prints something like:
//
// [ 'user-agent',
//   'this is invalid because there can be only one',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders); copy

message.rawTrailers

• Тип: <string[]>

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

message.setTimeout(msecs[, callback])

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

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

message.socket

• Тип: <stream.Duplex>

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

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

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

message.statusCode

• Тип: <number>

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

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

message.statusMessage

• Тип: <string>

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

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

message.trailers

• Тип: <Object>

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

message.trailersDistinct

• Тип: <Object>

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

message.url

• Тип: <string>

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

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

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

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

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

Если request.url имеет значение '/status?name=ryan', а process.env.HOST не задано:

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

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

Событие: 'drain'

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

Событие: 'finish'

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

Событие: 'prefinish'

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

outgoingMessage.addTrailers(headers)

• headers <Object>

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

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

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

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

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

outgoingMessage.appendHeader(name, value)

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

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

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

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

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

outgoingMessage.connection

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

outgoingMessage.cork()

См. writable.cork().

outgoingMessage.destroy([error])

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

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

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

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

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

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

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

outgoingMessage.flushHeaders()

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

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

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

outgoingMessage.getHeader(name)

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

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

outgoingMessage.getHeaderNames()

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

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

outgoingMessage.getHeaders()

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

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

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

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

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

outgoingMessage.hasHeader(name)

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

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

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

outgoingMessage.headersSent

• Тип: <boolean>

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

outgoingMessage.pipe()

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

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

outgoingMessage.removeHeader(name)

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

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

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

outgoingMessage.setHeader(name, value)

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

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

outgoingMessage.setHeaders(headers)

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

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

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

или

const headers = new Map([['foo', 'bar']]);
outgoingMessage.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(msecs[, callback])

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

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

outgoingMessage.socket

• Тип: <stream.Duplex>

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

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

outgoingMessage.uncork()

См. writable.uncork()

outgoingMessage.writableCorked

• Тип: <number>

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

outgoingMessage.writableEnded

• Тип: <boolean>

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

outgoingMessage.writableFinished

• Тип: <boolean>

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

outgoingMessage.writableHighWaterMark

• Тип: <number>

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

outgoingMessage.writableLength

• Тип: <number>

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

outgoingMessage.writableObjectMode

• Тип: <boolean>

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

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

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

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

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

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

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