HTTP

Стабильность: 2 – Стабильная

АПИ является удовлетворительным. Совместимость с NPM имеет высший приоритет и не будет нарушена кроме случаев явной необходимости.

Чтобы использовать сервер и клиент HTTP его необходимо подключить с помощью require('http').

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

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

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

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

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

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

Прочитайте message.headers для детальной информации о том как обрабатываются дублированные заголовки.

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

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

Class: http.Agent

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

HTTP Agent также устанавливает по умолчанию запросы клиентов по использованию Connection: Keep-Alive. Если нет ожидающих HTTP запросов, ожидающих на сокете, то сокет будет закрыт.

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

Если вы cделаете выбор в пользу использования HTTP KeepAlive, то вы сможете создать объект агента с этим флагом, установленным на true. (Читайте constructor options.) Затем агент будет хранить неиспользуемые сокеты в пуле для последующего использования.

Они будут помечены напрямую таким образом, чтобы не держать процесс 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 - <Boolean> Держите сокеты в пуле, чтобы они могли быть использованы другими запросами в будущем. По умолчанию false
    • keepAliveMsecs - <Число> При использовании HTTP Keep Alive, поддерживается частота посылания TCP KeepAlive пакетов через сокеты. По умолчанию = 1000. Релевантно если keepAlive установлено на true.
    • 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.createConnection(options[, callback])

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

Производит сокет / поток, который будет использоваться для HTTP-запросов.

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

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

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

agent.destroy()

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

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

agent.freeSockets

  • <Объект>

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

agent.getName(options)

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

agent.maxFreeSockets

  • <Число>

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

agent.maxSockets

  • <Число>

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

agent.requests

  • <Объект>

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

agent.sockets

  • <Объект>

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

Class: 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' (конец) не запустится. Кроме того, пока данные не будут считаны он будет потреблять память, которая в конечном итоге может привести к ошибке 'process out of memory' «у данного процесса закончилась память".

Примечание: Node.js не проверяет, являются ли длина содержания и длина тела которое было передано, одинаковыми или нет. (Тело - набор операторов внутри некоторой структуры. Например, тело операции)

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

Event: 'abort'

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

Event: 'aborted'

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

Event: '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
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();
    });
  });
});

Event: 'continue'

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

Event: 'response'

  • response - <http.IncomingMessage>

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

Event: 'socket'

  • socket - <net.Socket>

Генерируется после того, как назначается сокет на этот запрос.

Event: 'upgrade'

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

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

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

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

later.request.flushHeaders() позволяет обойти оптимизацию и запустить запрос.

request.setNoDelay([noDelay])

  • noDelay - <Boolean>

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

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

  • enable - <Boolean>
  • initialDelay - <Число>

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

request.setTimeout(timeout[, callback])

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

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

Возвращает request (запрос).

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

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

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

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

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

Аргумент callback (обратного вызова ) не является обязательным и будет вызываться, когда эта порция данных сбрасывается. Возвращает request (запрос).

Class: http.Server

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

Event: 'checkContinue'

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

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

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

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

Event: 'checkExpectation'

  • request - <http.ClientRequest>
  • response - <http.ServerResponse>

Создается каждый раз, когда запрос с HTTP Expect заголовком принимается, где значение не 100-continue (сервер удовлетворён начальными сведениями о запросе, клиент может продолжать пересылать заголовки.).

Если это событие не обрабатывается, то сервер автоматически отвечает соответствующим 417 Expectation Failed ( по каким-то причинам сервер не может удовлетворить значению поля ).

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

Event: 'clientError'

  • request - <http.ClientRequest>
  • response - <http.ServerResponse>

Если соединение с клиентом генерирует событие '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.

Event: 'close'

Генерируется при завершении работы сервера.

Event: 'connect'

  • request - <http.IncomingMessage> Request это аргументы для запроса HTTP, так как это происходит в случае запроса
  • socket - <net.Socket> Socket это сетевой сокет между сервером и клиентом.
  • head - <Buffer> Head это экземпляр Buffer, первый пакет из потока туннелирования, он может быть пустым

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

Event: 'connection'

  • socket - <net.Socket>

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

Event: 'request'

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

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

Event: 'upgrade'

  • request - <http.IncomingMessage> request это аргументы для запроса HTTP, так как это происходит в событии request
  • socket <net.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() может вызываться несколько раз. Каждый последующий вызов будет повторно открыть сервер, используя предоставленные опции.

server.listen(path[, callback])

  • path - <Строка>
  • callback - <Функция>

Запускает обработку соединений на данном path (пути) сокет сервера UNIX

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

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

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

  • port - <Число>
  • hostname - <Строка>
  • backlog - <Число>
  • callback - <Функция>

Начинает принимать соединения на указанном 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 будет добавлен в качестве обработчика для «прослушивания» события. Смотрите также net.Server.listen(port).

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

server.listening

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

server.maxHeadersCount

  • <Число>

Ограничивает подсчет максимального количества входящих заголовков, равняется 1000 по умолчанию. Если установлено значение 0 – то будет применяться правило no limit (без ограничений) .

server.setTimeout(msecs, callback)

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

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

Если есть событие 'timeout', на объекте сервера, то оно будет вызвано с помощью сокета timed-out в качестве аргумента.

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

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

server.timeout

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

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

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

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

Class: http.ServerResponse

Этот объект создаётся изнутри с помощью сервера HTTP - не пользователем. Он передается в качестве второго параметра события 'request'. Ответ реализует, но не наследует интерфейс Writable Stream. Это EventEmitter (генератор событий) со следующими событиями:

Event: 'close'

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

Event: 'finish'

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

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

response.addTrailers(headers)

  • headers - <Object>

(прим. - Trailer относится к дополнительным данным, помещенным в конце блока данных, которые будут сохранены или переданы, которые могут содержать информацию для обработки блока данных, или просто отмечать его конец.)

Этот метод добавляет

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

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

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

Метод, response.end() ДОЛЖЕН быть вызван при каждом ответе. Если data определены, то это эквивалентно вызову response.write(data, encoding) с последующим response.end(callback).

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

response.finished

  • <Boolean>

(прим. - Boolean -Бинарная переменная, имеющая два возможных значения истина/ложь – true/false)

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

response.getHeader(name)

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

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

Пример:

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

response.headersSent

  • <Boolean>

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

response.removeHeader(name)

  • name - <Строка>

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

Пример:

response.removeHeader('Content-Encoding');

response.sendDate

  • <Boolean>

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

Это должно быть отключено только для тестирования; 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 - <Функция>

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

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

Если назначить обработчик на запрос, ответ, или событий сервера 'timeout', то тогда это ваша задача обработать просроченные сокеты

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

response.statusCode

  • <Number>

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

Пример:

response.statusCode = 404;

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

response.statusMessage

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

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

Пример:

response.statusMessage = 'Not found';

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

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

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

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

chunk может быть строкой или буфером. Если chunk является строкой, то второй параметр указывает, как кодировать его в поток байтов. По умолчанию encoding (кодировка) это 'utf8'. callback будет вызван тогда, когда этот фрагмент данных будет сброшен.

Примечание: Это необработанное тело HTTP и не имеет ничего общего с multi-part кодировками тела заголовка более высокого уровня, которые могут быть использованы. В первый раз когда вызывается 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 - <Объект>

Посылает заголовок ответа на запрос. Код состояния представляет собой 3-значный код состояния 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.writeHead(statusCode[, statusMessage][, headers]), то будут вычислены неявные / переменные заголовки и вызовут для вас эту функцию.

Когда заголовки были установлены с помощью 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.

Class: http.IncomingMessage

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

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

Event: 'aborted'

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

Event: 'close'

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

message.destroy([error])

  • error - <Error>

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

message.headers

  • <Объект>

Заголовки объекта запроса / ответа (request/response).

KVP (Key-value pairs) заголовков и значений. (прим.- Ключ-значение пары (КВП) представляет собой набор из двух связанных между собой элементов данных: ключ, который является уникальным идентификатором для некоторого элемента данных, а также значение.) Имена заголовков в нижнем регистре.

Пример:


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

  • <Массив>

Список необработанных заголовков request / response именно в том виде как они были получены. Обратите внимание, что ключи и значения находятся в одном списке. Это не список кортежей (tuples). Таким образом, даже четные смещения являются ключевыми значениями, а нечетные смещения являются сопутствующими.

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

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

  • <Массив>

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

message.setTimeout(msecs, callback)

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

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

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

message.socket

  • <net.Socket>

Объект net.Socket, связанный с соединением. При поддержке HTTPS, используйте request.socket.getPeerCertificate(), чтобы получить детальную информации об аутентификации клиента.

message.statusCode

  • <Число>

Действительно только для ответа, полученного от http.ClientRequest. Трехзначный ответ HTTP кода состояния. Например, 404.

message.statusMessage

  • <Строка>

Действительно только для ответа, полученного от http.ClientRequest. Сообщение статуса ответа HTTP (reason phrase). (прим. Reason-Phrase - короткое текстовое описание Status-Code. Status-Code это код результата попытки понять и выполнить запрос. Status-Code предназначен для программ, Reason-Phrase - для человека.) Например, OK или Internal Server Error.

message.trailers

  • <Объект>

Необработанные request / response трейлеры объекта. Находится только событии '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.createServer([requestListener])

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

Возвращает новый экземпляр http.Server. RequestListener это функция, которая автоматически добавляется к событию 'request'.

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

Стабильность: 0 – устарело или набрало много негативных отзывов

Используйте вместо этого http.request().

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

http.get(options[, callback])

  • options - <Объект>
  • callback - <Функция>
  • Возвращает: <http.ClientRequest>

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

Учтите, что данные из response (ответа) должны быть использованы в callback по причине заявленной в http.ClientRequest

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

Пример:

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 {
      let 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 запросов клиента.

http.request(options[, callback])

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

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

  • Опции: - <Объект>
    • protocol - <Строка> Протокол к использованию. По умолчанию "http:".
    • host - <Строка> Доменное имя или IP-адрес сервера предназначенные для того чтобы выдать запрос. По умолчанию 'localhost'
    • hostname - <Строка> псевдоним для хоста. Для поддержки 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' , чтобы вычислить заголовок авторизации.
    • agent - <http.Agent > | <Boolean> Управляет поведением Agent . Когда используется агент, то запрос по умолчанию будет Connection: Keep-Alive.
      Возможные значения:
      • undefined (по умолчанию): используйте http.globalAgent для этого хоста и порта.
      • Объект Agent: напрямую использует переданное в Agent.
      • false: отказывается от организации связного пула с агентом, ставит по умолчанию запрос на Connection: close.
    • createConnection - <Функция>, которая создает сокет / поток, используемый для запроса, когда опция agent не используется. Может быть использовано, чтобы не допустить создание пользовательского класса Agent чтобы просто переопределить функцию по умолчанию CreateConnection. См. agent.createConnection() для получения более подробной информации.
    • timeout - <Integer> Число, указывающее таймаут сокета в миллисекундах. Это позволит установить таймаут до того, как сокет будет подключен.
  • callback - <Функция>
  • Возвращает - <http.ClientRequest>

Необязательный параметр обратного вызова будет добавлен в качестве обработчика на один раз для события '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' См. раздел 8.2.3 RFC2616 для получения дополнительной информации.
  • Отправка заголовка авторизации будет переопределять использование опции auth для вычисления базовой аутентификации.