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

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

HTTP Agent также по умолчанию настраивает клиентские запросы для использования Connection:keep-alive. Если нет ожидающих HTTP-запросов, ждущих освобождения сокета, сокет закрывается. Это означает, что пул Node.js имеет преимущество keep-alive при высокой нагрузке, но при этом разработчикам не нужно вручную закрывать HTTP-клиенты с помощью KeepAlive.

Если вы выбираете использование HTTP KeepAlive, вы можете создать объект Agent с этим флагом, установленным в true. (См. опции конструктора.) Затем Agent будет хранить неиспользуемые сокеты в пуле для дальнейшего использования. Они будут явно помечены, чтобы не удерживать процесс Node.js. Однако по-прежнему рекомендуется явно destroy() агенты KeepAlive, когда они больше не используются, чтобы сокеты были закрыты.

Сокеты удаляются из пула агента, когда сокет генерирует событие 'close' или специальное событие 'agentRemove'. Это означает, что если вы хотите оставить один HTTP-запрос открытым в течение длительного времени и не хотите, чтобы он оставался в пуле, вы можете сделать что-то вроде:

http.get(options, (res) => {
  // Do stuff
}).on('socket', (socket) => {
  socket.emit('agentRemove');
});

В качестве альтернативы вы можете полностью отказаться от пула, используя 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-соединения. Значение по умолчанию = 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');
var keepAliveAgent = new http.Agent({ keepAlive: true });
options.agent = keepAliveAgent;
http.request(options, onResponseCallback);

agent.destroy()

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

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

agent.freeSockets

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

agent.getName(options)

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

Параметры:

• host: Имя домена или IP-адрес сервера, которому необходимо отправить запрос.
• port: Порт удаленного сервера.
• localAddress: Локальный интерфейс для привязки сетевых подключений при отправке запроса.

agent.maxFreeSockets

По умолчанию установлено в 256. Для агентов, поддерживающих HTTP KeepAlive, это устанавливает максимальное количество сокетов, которые будут оставлены открытыми в свободном состоянии.

agent.maxSockets

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

agent.requests

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

agent.sockets

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

Класс: http.ClientRequest

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

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

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

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

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

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

Событие: 'abort'

function () { }

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

Событие: 'aborted'

function () { }

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

Событие: 'connect'

function (response, socket, head) { }

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

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

const http = require('http');
const net = require('net');
const url = require('url');

// Create an HTTP tunneling proxy
var 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
  var srvUrl = url.parse(`http://${req.url}`);
  var 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
  var options = {
    port: 1337,
    hostname: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80'
  };

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

function () { }

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

Событие: 'response'

function (response) { }

Издаётся, когда получен ответ на этот запрос. Это событие генерируется только один раз. Аргумент response будет экземпляром http.IncomingMessage.

Событие: 'socket'

function (socket) { }

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

Событие: 'upgrade'

function (response, socket, head) { }

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

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

const http = require('http');

// Create an HTTP server
var 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
  var options = {
    port: 1337,
    hostname: '127.0.0.1',
    headers: {
      'Connection': 'Upgrade',
      'Upgrade': 'websocket'
    }
  };

  var 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])

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

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

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

request.flushHeaders()

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

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

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

request.setNoDelay([noDelay])

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

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

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

request.setTimeout(timeout[, callback])

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

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

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

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

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

Аргумент chunk должен быть Buffer или строкой.

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

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

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

Класс: http.Server

Этот класс наследуется от net.Server и имеет следующие дополнительные события:

Событие: 'checkContinue'

function (request, response) { }

Вызывается каждый раз, когда поступает запрос с http Expect: 100-continue. Если это событие не обрабатывается, сервер автоматически отвечает с 100 Continue, как соответствующим образом.

Обработка этого события подразумевает вызов response.writeContinue(), если клиент должен продолжить отправку тела запроса, или генерацию соответствующего HTTP-ответа (например, 400 Bad Request), если клиент не должен продолжать отправку тела запроса.

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

Событие: 'clientError'

function (exception, socket) { }

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

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

Событие: 'close'

function () { }

Вызывается при закрытии сервера.

Событие: 'connect'

function (request, socket, head) { }

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

• request — аргументы для http запроса, как и в событии request.
• socket — сетевой сокет между сервером и клиентом.
• head — экземпляр Buffer, первый пакет туннельного потока, может быть пустым.

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

Событие: 'connection'

function (socket) { }

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

Событие: 'request'

function (request, response) { }

Вызывается каждый раз, когда поступает запрос. Обратите внимание, что может быть несколько запросов на одно соединение (в случае соединений keep-alive). request — экземпляр http.IncomingMessage, а response — экземпляр http.ServerResponse.

Событие: 'upgrade'

function (request, socket, head) { }

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

• request — аргументы для http запроса, как и в событии request.
• socket — сетевой сокет между сервером и клиентом.
• head — экземпляр Buffer, первый пакет обновленного потока, может быть пустым.

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

server.close([callback])

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

server.listen(handle[, callback])

• handle <Объект>
• callback <Функция>

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

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

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

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

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

server.listen(path[, callback])

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

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

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

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

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

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

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

server.maxHeadersCount

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

server.setTimeout(msecs, callback)

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

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

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

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

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

server.timeout

• <Число> Значение по умолчанию = 120000 (2 минуты)

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

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

Установите в 0, чтобы отключить любое автоматическое поведение таймаута при входящих подключениях.

Класс: http.ServerResponse

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

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

Событие: 'close'

function () { }

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

Событие: 'finish'

function () { }

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

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

response.addTrailers(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.end([data][, encoding][, callback])

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

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

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

response.finished

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

response.getHeader(name)

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

Пример:

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

response.headersSent

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

response.removeHeader(name)

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

Пример:

response.removeHeader('Content-Encoding');

response.sendDate

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

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

response.setHeader(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])

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

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

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

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

Пример:

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

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

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

Класс: http.IncomingMessage

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

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

Событие: 'aborted'

function () { }

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

Событие: 'close'

function () { }

Указывает, что базовое соединение было закрыто. Как и '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, связанный с подключением.

При поддержке 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.Server.

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

http.get(options[, callback])

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

Пример:

http.get('http://www.google.com/index.html', (res) => {
  console.log(`Got response: ${res.statusCode}`);
  // consume response body
  res.resume();
}).on('error', (e) => {
  console.log(`Got error: ${e.message}`);
});

http.globalAgent

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

http.request(options[, callback])

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

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

Параметры:

• protocol: Протокол для использования. По умолчанию 'http:'.
• host: Имя домена или IP-адрес сервера, к которому необходимо отправить запрос. По умолчанию 'localhost'.
• hostname: Псевдоним для host. Для поддержки url.parse() hostname предпочтительнее host.
• family: Семейство IP-адресов для использования при разрешении host и hostname. Допустимые значения 4 или 6. При отсутствии указания будут использованы как IP v4, так и v6.
• port: Порт удаленного сервера. По умолчанию 80.
• localAddress: Локальный интерфейс для привязки сетевых соединений.
• socketPath: Unix доменная сокета (используйте один из host:port или socketPath).
• method: Строка, определяющая метод HTTP-запроса. По умолчанию 'GET'.
• path: Путь запроса. По умолчанию '/'. Должен включать строку запроса, если она есть. Например, '/index.html?page=12'. При наличии недопустимых символов в пути запроса генерируется исключение. В настоящее время отклоняются только пробелы, но это может измениться в будущем.
• headers: Объект, содержащий заголовки запроса.
• auth: Базовая аутентификация, т.е. 'user:password' для вычисления заголовка Authorization.
• agent: Управление поведением Agent. При использовании Agent запрос по умолчанию Connection: keep-alive. Возможные значения:
  • undefined (по умолчанию): использовать http.globalAgent для данного хоста и порта.
  • Agent объект: явно использовать переданный Agent.
  • false: Отключение кэширования соединений с помощью Agent, запрос по умолчанию Connection: close.

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

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

Пример:

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

var options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(postData)
  }
};

var 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 для вычисления базовой аутентификации.