HTTP
- Class: http.Agent
- Class: http.ClientRequest
- Event: 'abort'
- Event: 'aborted'
- Event: 'connect'
- Event: 'continue'
- Event: 'response'
- Event: 'socket'
- Event: 'upgrade'
- request.abort()
- request.end([data][, encoding][, callback])
- request.flushHeaders()
- request.setNoDelay([noDelay])
- request.setSocketKeepAlive([enable][, initialDelay])
- request.setTimeout(timeout[, callback])
- request.write(chunk[, encoding][, callback])
- Class: http.Server
- Event: 'checkContinue'
- Event: 'checkExpectation'
- Event: 'clientError'
- Event: 'close'
- Event: 'connect'
- Event: 'connection'
- Event: 'request'
- Event: 'upgrade'
- server.close([callback])
- server.listen(handle[, callback])
- server.listen(path[, callback])
- server.listen([port][, hostname][, backlog][, callback])
- server.listening
- server.maxHeadersCount
- server.setTimeout(msecs, callback)
- server.timeout
- Class: http.ServerResponse
- Event: 'close'
- Event: 'finish'
- response.addTrailers(headers)
- response.end([data][, encoding][, callback])
- response.finished
- response.getHeader(name)
- response.headersSent
- response.removeHeader(name)
- response.sendDate
- response.setHeader(name, value)
- response.setTimeout(msecs, callback)
- response.statusCode
- response.statusMessage
- response.write(chunk[, encoding][, callback])
- response.writeContinue()
- response.writeHead(statusCode[, statusMessage][, headers])
- Class: http.IncomingMessage
- http.METHODS
- http.STATUS_CODES
- http.createServer([requestListener])
- http.get(options[, callback])
- http.globalAgent
- http.request(options[, callback])
Стабильность: 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, так как это происходит в событии requestsocket
<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.ClientReques
t. Сообщение статуса ответа 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
для вычисления базовой аутентификации.