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

В подключенных соединениях включена функция 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 <boolean> Сохранять сокеты даже при отсутствии активных запросов, чтобы они могли использоваться для будущих запросов без необходимости повторного установления TCP-соединения. По умолчанию = false
  • keepAliveMsecs <Целое> При использовании параметра keepAlive, задаёт начальную задержку для пакетов TCP Keep-Alive. Игнорируется, когда параметр keepAlive имеет значение false или undefined. По умолчанию = 1000.
  • maxSockets <число> Максимальное количество сокетов, разрешенных на один хост. По умолчанию = Infinity.
  • maxFreeSockets <число> Максимальное количество сокетов, которые следует оставить открытыми в свободном состоянии. Актуально только если keepAlive установлено в значение true. По умолчанию = 256.

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

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

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

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

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

agent.keepSocketAlive(socket)

• socket <net.Socket>

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

socket.unref();
socket.setKeepAlive(agent.keepAliveMsecs);

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

agent.reuseSocket(socket, request)

• socket <net.Socket>
• request <http.ClientRequest>

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

socket.ref();

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

agent.destroy()

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

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

agent.freeSockets

• <Объект>

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

agent.getName(options)

• options <Объект> Набор параметров, предоставляющих информацию для генерации имени
  • host <строка> Имя домена или IP-адрес сервера, к которому должен быть отправлен запрос
  • port <число> Порт удалённого сервера
  • localAddress <строка> Локальный интерфейс для привязки сетевых подключений при отправке запроса
• Возвращает: <Строка>

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

agent.maxFreeSockets

• <Число>

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

agent.maxSockets

• <Число>

По умолчанию установлено в Бесконечность. Определяет, сколько одновременных сокетов агент может держать открытыми на одну область происхождения. Область происхождения — это комбинация 'хост:порт' или 'хост:порт:локальныйАдрес'.

agent.requests

• <Объект>

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

agent.sockets

• <Объект>

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

Класс: http.ClientRequest

Этот объект создаётся внутри и возвращается из http.request(). Он представляет собой запрос в процессе, заголовок которого уже был помещён в очередь. Заголовок всё ещё можно изменить с помощью API setHeader(name, value), getHeader(name), removeHeader(name). Фактический заголовок будет отправлен вместе с первым блоком данных или при закрытии соединения.

Чтобы получить ответ, добавьте обработчик события 'response' к объекту запроса. Событие 'response' будет испущено из объекта запроса, когда заголовки ответа будут получены. Событие 'response' выполняется с одним аргументом, который является экземпляром http.IncomingMessage.

Во время события 'response' можно добавить обработчики к объекту ответа; особенно для прослушивания события 'data'.

Если обработчик события 'response' не добавлен, то ответ будет полностью отброшен. Однако, если вы добавите обработчик события 'response', то обязательно обработайте данные из объекта ответа, либо вызвав response.read() при каждом событии 'readable', или добавив обработчик 'data', или вызвав метод .resume(). Пока данные не будут обработаны, событие 'end' не будет сгенерировано. Кроме того, пока данные не будут прочитаны, они будут занимать память, что в конечном итоге может привести к ошибке «недостаточно памяти».

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

Запрос реализует интерфейс потока Writable Stream. Это EventEmitter со следующими событиями:

Событие: 'abort'

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

Событие: 'connect'

• response <http.IncomingMessage>
• socket <net.Socket>
• head <Буфер>

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

Событие: 'response'

• response <http.IncomingMessage>

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

Событие: 'socket'

• socket <net.Socket>

Исполнится после назначения сокета этому запросу.

Событие: 'upgrade'

• response <http.IncomingMessage>
• socket <net.Socket>
• head <Буфер>

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

Пример клиента и сервера, демонстрирующий прослушивание события '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,
    hostname: '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

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

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

• data <строка> | <Буфер>
• encoding <строка>
• callback <Функция>

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

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

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

request.flushHeaders()

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

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

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

request.setNoDelay([noDelay])

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

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

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

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

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

request.setTimeout(timeout[, callback])

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

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

Возвращает request.

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

• chunk <строка> | <Буфер>
• encoding <строка>
• callback <Функция>

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

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

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

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

Класс: 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.ClientRequest>
• response <http.ServerResponse>

Изначается каждый раз при получении запроса с HTTP заголовком Expect, где значение не равно 100-continue. Если этому событию не присвоен обработчик, сервер автоматически ответит соответствующим 417 Expectation Failed.

Обратите внимание, что при возникновении и обработке этого события, событие 'request' не будет сгенерировано.

Событие: 'clientError'

• exception <Error>
• socket <net.Socket>

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

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

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

• callback <Function>

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

server.listen(handle[, callback])

• handle <Object>
• callback <Function>

Объект handle может быть настроен на сервер или сокет (любое, имеющее член _handle), или на объект {fd: <n>}.

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

Прослушивание дескриптора файла не поддерживается в Windows.

Функция асинхронная. callback будет добавлен как слушатель события 'listening'. См. также net.Server.listen().

Возвращает server.

Примечание: метод server.listen() может быть вызван несколько раз. Каждый последующий вызов перезапустит сервер с предоставленными параметрами.

server.listen(path[, callback])

• path <string>
• callback <Function>

Запустить сервер сокета UNIX, прослушивающий подключения по указанному path.

Функция асинхронная. callback будет добавлен как слушатель события 'listening'. См. также net.Server.listen(path).

Примечание: метод server.listen() может быть вызван несколько раз. Каждый последующий вызов перезапустит сервер с предоставленными параметрами.

server.listen([port][, hostname][, backlog][, callback])

• port <number>
• hostname <string>
• backlog <number>
• callback <Function>

Начать приём подключений на указанном port и hostname. Если hostname опущен, сервер будет принимать подключения на любом IPv6 адресе (::) при наличии IPv6, или на любом IPv4 адресе (0.0.0.0) в противном случае. Опустить аргумент порта или использовать значение порта 0, чтобы операционная система назначила случайный порт, который можно получить, используя server.address().port после того, как событие 'listening' было сгенерировано.

Для прослушивания сокета unix, укажите имя файла вместо порта и хоста.

backlog — максимальная длина очереди ожидающих подключений. Фактическая длина будет определяться вашей ОС через настройки sysctl, такие как tcp_max_syn_backlog и somaxconn в Linux. Значение по умолчанию этого параметра 511 (а не 512).

Функция асинхронная. callback будет добавлен как слушатель события 'listening'. См. также net.Server.listen(port).

Примечание: метод server.listen() может быть вызван несколько раз. Каждый последующий вызов перезапустит сервер с предоставленными параметрами.

server.listening

• <Boolean>

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

server.maxHeadersCount

• <Число>

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

server.setTimeout(msecs, callback)

• msecs <число>
• callback <Функция>

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

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

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

Возвращает server.

server.headersTimeout

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

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

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

server.timeout

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

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

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

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

server.keepAliveTimeout

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

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

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

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

Класс: http.ServerResponse

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

Ответ реализует, но не наследуется от, интерфейса потока Writable Stream. Это EventEmitter со следующими событиями:

Событие: 'close'

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

Событие: 'finish'

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

После этого события на объекте ответа больше не будут генерироваться события.

response.addTrailers(headers)

• headers <Объект>

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

Прицепы только будут отправлены, если для ответа используется кодировка chunked; если нет (например, если запрос был 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.end([data][, encoding][, callback])

• data <строка> | <Буфер>
• encoding <строка>
• callback <Функция>

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

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

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

response.finished

• <Булево>

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

response.getHeader(name)

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

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

Пример:

const contentType = response.getHeader('content-type');

response.headersSent

• <Булево>

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

response.removeHeader(name)

• name <строка>

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

Пример:

response.removeHeader('Content-Encoding');

response.sendDate

• <Булево>

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

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

response.setHeader(name, value)

• name <строка>
• value <строка>

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

Пример:

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.setTimeout(msecs, callback)

• msecs <число>
• callback <Функция>

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

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

Возвращает response.

response.statusCode

• <Число>

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

Пример:

response.statusCode = 404;

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

response.statusMessage

• <Строка>

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

Пример:

response.statusMessage = 'Not found';

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

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

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

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

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

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

chunk может быть строкой или буфером. Если chunk является строкой, второй параметр указывает, как ее закодировать в потоке байтов. По умолчанию кодировка encoding — 'utf8'. 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, например, 404. Последний аргумент, headers, — это заголовки ответа. Дополнительно можно указать удобочитаемое statusMessage в качестве второго аргумента.

Пример:

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

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

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

Когда заголовки были заданы с помощью 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');
});

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

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

Класс: http.IncomingMessage

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

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

Событие: 'aborted'

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

Событие: 'close'

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

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

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 <Функция>

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

Возвращает message.

message.statusCode

• <Число>

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

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

message.statusMessage

• <Строка>

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

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

message.socket

• <net.Socket>

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

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

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')
{
  href: '/status?name=ryan',
  search: '?name=ryan',
  query: 'name=ryan',
  pathname: '/status'
}

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

$ node
> require('url').parse('/status?name=ryan', true)
{
  href: '/status?name=ryan',
  search: '?name=ryan',
  query: {name: 'ryan'},
  pathname: '/status'
}

http.METHODS

• <Массив>

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

http.STATUS_CODES

• <Объект>

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

http.createClient([port][, host])

Создаёт новый HTTP-клиент. port и host указывают на сервер для подключения.

http.createServer([requestListener])

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

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

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

http.get(options[, callback])

• options <Объект>
• 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.statusCode;
  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.log(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.log(e.message);
    }
  });
}).on('error', (e) => {
  console.log(`Got error: ${e.message}`);
});

http.globalAgent

• <http.Агент>

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

http.maxHeaderSize

• <число>

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

http.request(options[, callback])

• options <Объект>
  • protocol <строка> Протокол для использования. По умолчанию 'http:'.
  • host <строка> Имя домена или IP-адрес сервера для отправки запроса. По умолчанию 'localhost'.
  • hostname <строка> Псевдоним для host. Для поддержки url.parse(), hostname предпочтительнее host.
  • family <число> Семейство IP-адресов для использования при разрешении host и hostname. Допустимые значения 4 или 6. Если не указано, будут использоваться как IPv4, так и IPv6.
  • port <число> Порт удалённого сервера. По умолчанию 80.
  • localAddress <строка> Локальный интерфейс для привязки сетевых соединений.
  • socketPath <строка> Unix доменная сокета (используйте host:port или socketPath).
  • method <строка> Строка, определяющая метод HTTP-запроса. По умолчанию 'GET'.
  • path <строка> Путь запроса. По умолчанию '/'. Должен включать строку запроса, если она есть. Например, '/index.html?page=12'. Исключение генерируется, если путь запроса содержит недопустимые символы. В настоящее время отбрасываются только пробелы, но это может измениться в будущем.
  • headers <Объект> Объект, содержащий заголовки запроса.
  • auth <строка> Базовая аутентификация, т.е. 'user:password' для вычисления заголовка Authorization.
  • agent <http.Agent> | <логическое значение> Управляет поведением Agent. Возможные значения:
    • undefined (по умолчанию): использовать http.globalAgent для данного хоста и порта.
    • Agent объект: явно использовать переданный Agent.
    • false: вызывает создание нового Agent с значениями по умолчанию.
  • createConnection <Функция> Функция, которая генерирует сокет/поток для использования в запросе, когда параметр agent не используется. Это можно использовать, чтобы избежать создания собственного класса Agent, просто переопределяя функцию по умолчанию createConnection. Подробнее см. agent.createConnection().
  • timeout <Целое число>: Число, определяющее таймаут сокета в миллисекундах. Это установит таймаут до подключения сокета.
• callback <Функция>
• Возвращает: <http.ClientRequest>

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

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

Необязательный параметр 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.log(`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 для вычисления базовой аутентификации.