HTTP

Для использования 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.
  • maxFreeSockets <число> Максимальное количество сокетов, которые будут оставлены в свободном состоянии. Актуально только если keepAlive установлено в true. По умолчанию: 256.
  • 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])[src]

• options <Объект> Параметры, содержащие детали подключения. См. net.createConnection() для формата параметров
• callback <Функция> Функция обратного вызова, которая получает созданный сокет
• Возвращает: <net.Сокет>

Создаёт сокет/поток для использования в HTTP-запросах.

По умолчанию, эта функция эквивалентна net.createConnection(). Однако, пользовательские агенты могут переопределить этот метод для большей гибкости.

Сокет/поток можно предоставить двумя способами: вернув сокет/поток из этой функции или передав сокет/поток в callback.

callback имеет сигнатуру (err, stream).

agent.keepSocketAlive(socket)[src]

• socket <net.Сокет>

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

socket.setKeepAlive(true, this.keepAliveMsecs);
socket.unref();
return true;

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

agent.reuseSocket(socket, request)[src]

• socket <net.Сокет>
• request <http.Клиентский запрос>

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

socket.ref();

Этот метод может быть переопределён конкретным подклассом Agent.

agent.destroy()[src]

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

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

agent.freeSockets

• <Объект>

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

agent.getName(options)[src]

• options <Object> Набор параметров, предоставляющих информацию для генерации имени.

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

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

agent.maxFreeSockets

• <number>

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

agent.maxSockets

• <number>

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

agent.requests

• <Object>

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

agent.sockets

• <Object>

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

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

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

Запрос наследуется от Stream и дополнительно реализует следующее:

Событие: 'abort'

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

Событие: 'connect'

• response <http.IncomingMessage>
• socket <net.Socket>
• head <Buffer>

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

Пара клиент-сервер, демонстрирующая, как прослушивать событие '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, cltSocket, head) => {
  // connect to an origin server
  const srvUrl = url.parse(`http://${req.url}`);
  const srvSocket = net.connect(srvUrl.port, srvUrl.hostname, () => {
    cltSocket.write('HTTP/1.1 200 Connection Established\r\n' +
                    'Proxy-agent: Node.js-Proxy\r\n' +
                    '\r\n');
    srvSocket.write(head);
    srvSocket.pipe(cltSocket);
    cltSocket.pipe(srvSocket);
  });
});

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

Выпускается, когда сервер отправляет ответ 1xx (кроме 101 Upgrade). Это событие запускается с обратным вызовом, содержащим код статуса.

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', (res) => {
  console.log(`Got information prior to main response: ${res.statusCode}`);
});

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

Событие: 'response'

• response <http.IncomingMessage>

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

Событие: 'socket'

• socket <net.Socket>

Выпускается после того, как сокет назначен этому запросу.

Событие: 'timeout'

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

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

Событие: 'upgrade'

• response <http.IncomingMessage>
• socket <net.Socket>
• head <Buffer>

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

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

const http = require('http');

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

Если запрос был прерван, это значение — время прерывания запроса в миллисекундах с 1 января 1970 года 00:00:00 по UTC.

request.connection

• <net.Socket>

См. 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.removeHeader(name)

• name <string>

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

request.removeHeader('Content-Type');

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

• <net.Socket>

Ссылка на базовый сокет. Обычно пользователи не захотят обращаться к этому свойству. В частности, сокет не будет испускать '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
});

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 <net.Socket>

Если соединение клиента испускает событие 'error', оно будет перенаправлено сюда. Обработчик этого события отвечает за закрытие/удаление базового сокета. Например, можно более корректно закрыть сокет с помощью пользовательского HTTP-ответа вместо резкого разрыва соединения.

По умолчанию сокет закрывается с HTTP-ответом '400 Bad Request', если это возможно, в противном случае сокет немедленно уничтожается.

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: исходный пакет текущего запроса.

Событие: 'close'

Издаётся, когда сервер закрывается.

Событие: 'connect'

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

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

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

Событие: 'connection'

• socket <net.Socket>

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

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

Событие: 'request'

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

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

Событие: 'upgrade'

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

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

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

server.close([callback])[src]

• callback <Функция>

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

server.listen()

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

server.listening

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

server.maxHeadersCount

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

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

server.headersTimeout

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

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

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

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

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

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

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

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

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

server.timeout

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

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

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

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

server.keepAliveTimeout

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

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

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

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

Класс: http.ServerResponse

Этот объект создаётся внутренне HTTP-сервером, а не пользователем. Он передаётся в качестве второго параметра событию 'request'.

Ответ наследуется от Stream и дополнительно реализует следующее:

Событие: 'close'

Указывает, что базовое соединение было прервано до вызова response.end() или до его обработки.

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

• <net.Сокет>

См. response.socket.

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

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

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

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

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

response.finished

• <булево>

Булево значение, указывающее, завершен ли ответ. Начинается как false. После выполнения response.end(), значение будет true.

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

• <булево>

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

response.removeHeader(name)

• name <строка>

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

response.removeHeader('Content-Encoding');

response.sendDate

• <булево>

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

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

response.setHeader(name, value)

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

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

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

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

response.socket

• <net.Сокет>

Ссылка на базовый сокет. Обычно пользователи не захотят обращаться к этому свойству. В частности, сокет не будет генерировать события '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);

response.statusCode

• <число>

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

response.statusCode = 404;

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

response.statusMessage

• <строка>

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

response.statusMessage = 'Not found';

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

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>

Отправляет заголовок ответа на запрос. Код состояния — это 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');
});

Обратите внимание, что длина содержимого указывается в байтах, а не в символах. Приведённый выше пример работает, потому что строка 'hello world' содержит только символы с одним байтом. Если тело содержит символы с большим кодированием, то Buffer.byteLength() следует использовать для определения количества байтов в заданной кодировке. Node.js не проверяет, равны ли длина содержимого и количество переданных байтов.

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

response.writeProcessing()

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

Класс: http.IncomingMessage

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

Он реализует интерфейс потока Readable Stream, а также следующие дополнительные события, методы и свойства.

Событие: 'aborted'

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

Событие: 'close'

Указывает, что базовое соединение было закрыто. Как и 'end', это событие происходит только один раз на ответ.

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 <Ошибка>

Вызывает 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, или 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

• <net.Socket>

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

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

message.statusCode

• <число>

Только для ответа, полученного от http.ClientRequest.

3-значный код состояния 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\r\n
Accept: text/plain\r\n
\r\n

Тогда request.url будет:

'/status?name=ryan'

Для разбора URL на части можно использовать require('url').parse(request.url):

$ node
> require('url').parse('/status?name=ryan')
Url {
  protocol: null,
  slashes: null,
  auth: null,
  host: null,
  port: null,
  hostname: null,
  hash: null,
  search: '?name=ryan',
  query: 'name=ryan',
  pathname: '/status',
  path: '/status?name=ryan',
  href: '/status?name=ryan' }

Для извлечения параметров из строки запроса можно использовать функцию require('querystring').parse, или true можно передать в качестве второго аргумента функции require('url').parse:

$ node
> require('url').parse('/status?name=ryan', true)
Url {
  protocol: null,
  slashes: null,
  auth: null,
  host: null,
  port: null,
  hostname: null,
  hash: null,
  search: '?name=ryan',
  query: { name: 'ryan' },
  pathname: '/status',
  path: '/status?name=ryan',
  href: '/status?name=ryan' }

http.METHODS

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

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

http.STATUS_CODES

• <Объект>

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

http.createServer([options][, requestlistener])[src]

• 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])[src]

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

• 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;
  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])[src]

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

• url <строка> | <URL>

• options <объект>

  • protocol <строка> Протокол для использования. По умолчанию: 'http:'.
  • host <строка> Имя домена или IP-адрес сервера, которому нужно отправить запрос. По умолчанию: 'localhost'.
  • hostname <строка> Псевдоним для host. Для поддержки url.parse(), будет использоваться hostname если оба host и hostname указаны.
  • family <число> Семейство IP-адресов для использования при разрешении host или hostname. Допустимые значения 4 или 6. При отсутствии значения будут использованы как IPv4, так и IPv6.
  • insecureHTTPParser <логическое значение> Использовать небезопасный HTTP-парсер, который принимает недопустимые HTTP-заголовки, когда true. Использование небезопасного парсера следует избегать. Подробнее см. --insecure-http-parser. По умолчанию: false
  • port <число> Порт удалённого сервера. По умолчанию: 80.
  • localAddress <строка> Локальный интерфейс для привязки сетевых соединений.
  • socketPath <строка> Unix Domain Socket (не может быть использован, если указан один из host или port, они указывают на TCP-сокет).
  • method <строка> Строка, определяющая метод HTTP-запроса. По умолчанию: 'GET'.
  • path <строка> Путь запроса. Должен включать строку запроса, если она есть. Например: '/index.html?page=12'. Исключение выбрасывается, если путь запроса содержит недопустимые символы. В настоящее время отклоняются только пробелы, но это может измениться в будущем. По умолчанию: '/'.
  • headers <объект> Объект, содержащий заголовки запроса.
  • auth <строка> Аутентификация Basic, т.е. 'user:password' для вычисления заголовка Authorization.

  • agent <http.Agent> | <логическое значение> Управляет поведением Agent. Возможные значения:

    • undefined (по умолчанию): использует http.globalAgent для данного хоста и порта.
    • Agent объект: явно использует переданный Agent.
    • false: создаёт новый Agent с значениями по умолчанию.
  • createConnection <функция> Функция, которая создаёт сокет/поток для использования в запросе, когда не используется параметр agent . Это может быть использовано для избежания создания пользовательского класса Agent только для переопределения функции по умолчанию createConnection. Подробнее см. agent.createConnection(). Любой поток Duplex является допустимым значением возврата.
  • timeout <число>: Число, определяющее таймаут сокета в миллисекундах. Это задаёт таймаут до подключения сокета.
  • setHost <логическое значение>: Указывает, добавлять ли автоматически заголовок Host. По умолчанию true.
• callback <функция>
• Возвращает: <http.ClientRequest>

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

url может быть строкой или объектом URL. Если url является строкой, она автоматически парсится с помощью url.parse(). Если это объект 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'. Для более подробной информации см. RFC2616, раздел 8.2.3.

• Отправка заголовка Authorization переопределит использование параметра auth для вычисления аутентификации Basic.

Пример использования 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'.