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

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

new Agent([options])

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

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

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

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

const http = require('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;

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

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

agent.reuseSocket(socket, request)

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

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

socket.ref();

Этот метод может быть переопределён подклассом 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

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

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

В отличие от объекта request, если ответ закрывается преждевременно, объект response не испускает событие 'error', а вместо этого испускает событие 'aborted'.

Node.js не проверяет, равны ли длина Content-Length и длина переданного тела.

Событие: 'abort'

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

Событие: 'connect'

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

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

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

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

const http = require('http');
const net = require('net');
const { URL } = require('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' в запросе. Это инструкция, что клиент должен отправить тело запроса.

Событие: 'information'

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

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

const http = require('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'.

const http = require('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.end([data[, encoding]][, callback])

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

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

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

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

request.destroy([error])

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

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

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

request.destroyed

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

Является true после того, как был вызван request.destroy().

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

request.finished

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

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

request.flushHeaders()

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

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

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

request.getHeader(name)

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

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

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

request.getRawHeaderNames()

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

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

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

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

request.maxHeadersCount

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

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

request.path

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

request.method

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

request.host

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

request.protocol

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

request.removeHeader(name)

• name <строка>

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

request.removeHeader('Content-Type');

request.reusedSocket

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

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

const http = require('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('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');

или

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

request.setNoDelay([noDelay])

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

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

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

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

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

request.setTimeout(timeout[, callback])

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

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

request.socket

• <stream.Duplex>

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

const http = require('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.writableEnded

• <boolean>

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

request.writableFinished

• <boolean>

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

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

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

Отправляет фрагмент тела. Повторный вызов этого метода позволяет отправлять тело запроса на сервер. В этом случае рекомендуется использовать строку заголовка ['Transfer-Encoding', 'chunked'] при создании запроса.

Аргумент 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. Если сокет не является записью или уже записал данные, он немедленно уничтожается.

socket — это объект net.Socket, из которого произошла ошибка.

const http = require('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');
});

Событие: '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>.

Событие: 'request'

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

Вызывается каждый раз, когда есть запрос. Может быть несколько запросов на одно соединение (в случае HTTP Keep-Alive соединений).

Событие: 'upgrade'

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

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

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

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

server.close([callback])

• callback <Function>

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

server.headersTimeout

• <number> По умолчанию: 60000

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

В случае бездействия применяются правила, определенные в server.timeout. Однако, этот таймаут, основанный на бездействии, всё ещё позволит поддерживать открытое соединение, если заголовки отправляются очень медленно (по умолчанию, до одного байта каждые 2 минуты). Чтобы предотвратить это, всякий раз, когда приходят данные заголовков, производится дополнительная проверка, что не прошло более server.headersTimeout миллисекунд с момента установления соединения. Если проверка завершается неудачно, событие 'timeout' генерируется на объекте сервера, и (по умолчанию) сокет уничтожается. См. server.timeout для получения более подробной информации о том, как можно настроить поведение таймаута.

server.listen()

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

server.listening

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

server.maxHeadersCount

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

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

server.requestTimeout

• <number> По умолчанию: 0

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

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

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

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

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

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

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

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

server.timeout

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

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

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

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

server.keepAliveTimeout

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

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

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

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

Класс: http.ServerResponse

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

Этот объект создается внутри сервера 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();

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

response.connection

• <stream.Duplex>

См. response.socket.

response.cork()

См. writable.cork().

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

• data <строка> | <Буфер>
• 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[]

response.getHeaderNames()

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

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

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

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

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

response.hasHeader(name)

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

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

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

response.headersSent

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

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

response.removeHeader(name)

• name <строка>

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

response.removeHeader('Content-Encoding');

response.sendDate

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

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

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

response.setHeader(name, value)

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

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

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

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

или

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

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

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

response.setTimeout(msecs[, callback])

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

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

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

response.socket

• <stream.Duplex>

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

const http = require('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;

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

response.statusMessage

• <строка>

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

response.statusMessage = 'Not found';

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

response.uncork()

См. writable.uncork().

response.writableEnded

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

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

response.writableFinished

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

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

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

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

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

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

В модуле http, тело ответа опускается, когда запрос является HEAD-запросом. Аналогично, ответы 204 и 304 не должны содержать тело сообщения.

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

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

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

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

response.writeContinue()

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

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

• statusCode <число>
• statusMessage <строка>
• 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);

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

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

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

response.writeProcessing()

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

Класс: http.IncomingMessage

• Расширяет: <stream.Readable>

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

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

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

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

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

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

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

• <string>

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

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

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

Для разбора URL на его части:

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

Когда request.url равно '/status?name=ryan' и request.headers.host равно 'localhost:3000':

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

http.METHODS

• <string[]>

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

http.STATUS_CODES

• <Object>

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

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

• options <Object>

  • IncomingMessage <http.IncomingMessage> Указывает класс IncomingMessage для использования. Полезно для расширения исходного класса IncomingMessage. По умолчанию: IncomingMessage.
  • ServerResponse <http.ServerResponse> Указывает класс ServerResponse для использования. Полезно для расширения исходного класса ServerResponse. По умолчанию: ServerResponse.
  • insecureHTTPParser <boolean> Использовать небезопасный HTTP-парсер, который принимает недопустимые HTTP-заголовки, когда true. Использование небезопасного парсера следует избегать. См. --insecure-http-parser для получения дополнительной информации. По умолчанию: false
  • maxHeaderSize <number> Необязательно переопределяет значение --max-http-header-size для запросов, полученных этим сервером, т. е. максимальную длину заголовков запроса в байтах. По умолчанию: 16384 (16 КБ).

• requestListener <Function>

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

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

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

http.get(options[, callback])

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

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

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

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

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

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

  let error;
  // Any 2xx status code signals a successful response but
  // here we're only checking for 200.
  if (statusCode !== 200) {
    error = new Error('Request Failed.\n' +
                      `Status Code: ${statusCode}`);
  } else if (!/^application\/json/.test(contentType)) {
    error = new Error('Invalid content-type.\n' +
                      `Expected application/json but received ${contentType}`);
  }
  if (error) {
    console.error(error.message);
    // Consume response data to free up memory
    res.resume();
    return;
  }

  res.setEncoding('utf8');
  let rawData = '';
  res.on('data', (chunk) => { rawData += chunk; });
  res.on('end', () => {
    try {
      const parsedData = JSON.parse(rawData);
      console.log(parsedData);
    } catch (e) {
      console.error(e.message);
    }
  });
}).on('error', (e) => {
  console.error(`Got error: ${e.message}`);
});

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

server.listen(8000);

http.globalAgent

• <http.Agent>

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

http.maxHeaderSize

• <number>

Только для чтения свойство, определяющее максимальный разрешенный размер заголовков HTTP в байтах. По умолчанию 8 КБ. Настраивается с помощью опции командной строки --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
  • 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.
  • socketPath <строка> Unix-доменный сокет (не может быть использован, если задан один из host или port, они указывают на TCP-сокет).
  • timeout <число>: Число, определяющее таймаут сокета в миллисекундах. Это задаст таймаут до подключения сокета.
  • signal <AbortSignal>: AbortSignal, который может быть использован для прерывания текущего запроса.
• callback <Функция>
• Возвращает: <http.ClientRequest>

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

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

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

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

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

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

const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    '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) => {
  // ...
});

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

• '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'
• 'close' на объекте res

Если req.destroy() вызван до назначения сокета, следующие события будут выпущены в следующем порядке:

• (req.destroy() вызван здесь)
• 'error' с ошибкой с сообщением 'Error: socket hang up' и кодом 'ECONNRESET'
• 'close'

Если req.destroy() вызван до успешного соединения, следующие события будут выпущены в следующем порядке:

• 'socket'
• (req.destroy() вызван здесь)
• 'error' с ошибкой с сообщением 'Error: socket hang up' и кодом 'ECONNRESET'
• 'close'

Если req.destroy() вызван после получения ответа, следующие события будут выпущены в следующем порядке:

• 'socket'
• 'response'
  • 'data' любое количество раз, на объекте res
• (req.destroy() вызван здесь)
• 'aborted' на объекте res
• 'close'
• 'close' на объекте res

Если req.abort() вызван до назначения сокета, следующие события будут выпущены в следующем порядке:

• (req.abort() вызван здесь)
• 'abort'
• 'close'

Если req.abort() вызван до успешного соединения, следующие события будут выпущены в следующем порядке:

• 'socket'
• (req.abort() вызван здесь)
• 'abort'
• 'error' с ошибкой с сообщением 'Error: socket hang up' и кодом 'ECONNRESET'
• 'close'

Если req.abort() вызван после получения ответа, следующие события будут выпущены в следующем порядке:

• 'socket'
• 'response'
  • 'data' любое количество раз, на объекте res
• (req.abort() вызван здесь)
• 'abort'
• 'aborted' на объекте res
• 'close'
• 'close' на объекте res

Указание опции timeout или использование функции setTimeout() не прерывает запрос и не делает ничего, кроме добавления события 'timeout'.

Передача AbortSignal и затем вызов abort на соответствующем AbortController будет работать так же, как вызов .destroy() на самом запросе.

http.validateHeaderName(name)

• name <строка>

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

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

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

Пример:

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

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

http.validateHeaderValue(name, value)

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

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

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

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

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

Примеры:

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

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

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