HTTP

Исходный код: lib/http.js

Для использования HTTP-сервера и клиента необходимо require('http').

HTTP-интерфейсы в Node.js разработаны для поддержки многих функций протокола, которые традиционно были сложными в использовании. В частности, больших, возможно, с кодировкой кусками, сообщений. Интерфейс тщательно избегает буферизации полных запросов или ответов, поэтому пользователь может передавать данные потоком.

Заголовки сообщений HTTP представлены объектом такого типа:

{ 'content-length': '123',
  'content-type': 'text/plain',
  'connection': 'keep-alive',
  'host': 'mysite.com',
  'accept': '*/*' }

Ключи приведены в нижнем регистре. Значения не изменяются.

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

См. message.headers для получения подробностей о том, как обрабатываются дублирующиеся заголовки.

Необработанные заголовки, полученные с сервера, хранятся в свойстве rawHeaders, которое является массивом [key, value, key2, value2, ...]. Например, предыдущий объект заголовка сообщения может иметь список rawHeaders следующего вида:

[ 'ConTent-Length', '123456',
  'content-LENGTH', '123',
  'content-type', 'text/plain',
  'CONNECTION', 'keep-alive',
  'Host', 'mysite.com',
  'accepT', '*/*' ]

Класс: 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 <число> Максимальное количество сокетов, разрешенных на хост. Каждый запрос будет использовать новый сокет, пока не будет достигнуто максимум. По умолчанию: Infinity.
  • maxTotalSockets <число> Максимальное количество сокетов, разрешенное для всех хостов в сумме. Каждый запрос будет использовать новый сокет, пока не будет достигнуто максимум. По умолчанию: Infinity.
  • maxFreeSockets <число> Максимальное количество сокетов, которые должны оставаться открытыми в свободном состоянии. Актуально только если keepAlive установлено в true. По умолчанию: 256.
  • scheduling <строка> Стратегия планирования, применяемая при выборе следующего свободного сокета для использования. Может быть 'fifo' или 'lifo'. Основное отличие между двумя стратегиями планирования состоит в том, что 'lifo' выбирает сокет, который использовался в последний раз, а 'fifo' выбирает сокет, который использовался в наименьший раз. В случае низкой скорости запросов в секунду стратегия 'lifo' снижает риск выбора сокета, который мог быть закрыт сервером из-за бездействия. В случае высокой скорости запросов в секунду стратегия 'fifo' максимизирует количество открытых сокетов, а стратегия 'lifo' минимизирует его. По умолчанию: 'fifo'.
  • 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

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

Этот объект создаётся внутри и возвращается из 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 <Буфер>

Используется каждый раз, когда сервер отвечает на запрос с помощью метода 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 <Объект>
  • httpVersion <строка>
  • httpVersionMajor <целое число>
  • httpVersionMinor <целое число>
  • statusCode <целое число>
  • statusMessage <строка>
  • headers <Объект>
  • rawHeaders <массив строк>

Используется, когда сервер отправляет промежуточный ответ 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 <string> | <Buffer>
• encoding <string>
• callback <Function>
• Возвращает: <this>

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

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

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

request.finished

• <boolean>

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

request.flushHeaders()

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

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

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

request.getHeader(name)

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

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

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

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

request.reusedSocket

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

При отправке запроса через агент с поддержкой 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 <string>
• value <any>

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

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

или

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

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' события, из-за того, как анализатор протокола прикрепляется к сокету. К socket также можно получить доступ через request.connection.

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

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

Значение 0 отключит проверку таймаута HTTP-заголовков.

server.listen()

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

server.listening

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

server.maxHeadersCount

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

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

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

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

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

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

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

Для изменения значения таймаута по умолчанию используйте флаг --http-server-default-timeout.

server.timeout

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

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

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

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

Для изменения значения таймаута по умолчанию используйте флаг --http-server-default-timeout.

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

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

response.connection

• <stream.Duplex>

См. response.socket.

response.cork()

См. writable.cork().

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

• data <string> | <Buffer>
• 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[]

response.getHeaderNames()

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

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

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

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

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

response.hasHeader(name)

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

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

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

response.headersSent

• <boolean>

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

response.removeHeader(name)

• name <string>

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

response.removeHeader('Content-Encoding');

response.sendDate

• <boolean>

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

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

response.setHeader(name, value)

• name <string>
• value <any>

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

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

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

response.socket

• <stream.Duplex>

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

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

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

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

response.statusCode = 404;

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

response.statusMessage

• <string>

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

response.statusMessage = 'Not found';

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

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>
• encoding <string> Значение по умолчанию: 'utf8'
• callback <Функция>
• Возвращает: <boolean>

Если этот метод вызывается, и 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>

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

Возвращает ссылку на 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

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

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

message.complete

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

Свойство 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 <Ошибка>
• Возвращает: <this>

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

message.headers

• <Объект>

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

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

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

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

• Дубликаты 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

• <строка>

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

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

message.method

• <строка>

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

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

message.rawHeaders

• <массив строк>

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

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

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

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

message.rawTrailers

• <массив строк>

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

message.setTimeout(msecs[, callback])

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

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

message.socket

• <stream.Duplex>

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

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

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

message.statusCode

• <число>

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

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

message.statusMessage

• <строка>

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

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

message.trailers

• <Объект>

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

message.url

• <строка>

Действителен только для запроса, полученного от 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

• <массив строк>

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

http.STATUS_CODES

• <Объект>

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

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

• options <Объект>

  • IncomingMessage <http.IncomingMessage> Указывает класс IncomingMessage для использования. Полезно для расширения исходного IncomingMessage. По умолчанию: IncomingMessage.
  • ServerResponse <http.ServerResponse> Указывает класс ServerResponse для использования. Полезно для расширения исходного ServerResponse. По умолчанию: ServerResponse.
  • insecureHTTPParser <логическое значение> Использовать небезопасный HTTP-парсер, который принимает недопустимые HTTP-заголовки, когда true. Необходимо избегать использования небезопасного парсера. См. --insecure-http-parser для получения дополнительной информации. По умолчанию: false

• requestListener <Функция>

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

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

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

http.get(options[, callback])

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

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

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

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

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

http.get('http://nodejs.org/dist/index.json', (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}`);
});

http.globalAgent

• <http.Agent>

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

http.maxHeaderSize

• <число>

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

http.request(options[, callback])

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

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

• Отправка заголовка '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'

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

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