Перейти к содержанию

HTTP

v18.x.x

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

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

Для использования HTTP-сервера и клиента необходимо require('node:http').

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

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

1
2
3
4
5
6
7
{
    'content-length': '123',
    'content-type': 'text/plain',
    'connection': 'keep-alive',
    'host': 'example.com',
    'accept': '*/*'
}

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

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

Смотрите message.headers для подробностей о том, как обрабатываются дублирующиеся заголовки.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[
    'ConTent-Length',
    '123456',
    'content-LENGTH',
    '123',
    'content-type',
    'text/plain',
    'CONNECTION',
    'keep-alive',
    'Host',
    'example.com',
    'accepT',
    '*/*',
];

Класс http.Agent

Агент отвечает за управление сохранением и повторным использованием соединений для HTTP-клиентов. Он поддерживает очередь ожидающих запросов для данного хоста и порта, повторно используя одно сокетное соединение для каждого до тех пор, пока очередь не опустеет, после чего сокет либо уничтожается, либо помещается в пул, где он хранится для повторного использования для запросов к тому же хосту и порту. Будет ли он уничтожен или помещен в пул, зависит от keepAlive опция.

Для пула соединений включена функция TCP Keep-Alive, но серверы могут закрывать простаивающие соединения, в этом случае они будут удалены из пула, а новое соединение будет создано при новом HTTP-запросе на этот хост и порт. Серверы также могут отказаться разрешать несколько запросов через одно и то же соединение, в этом случае соединение будет создаваться заново для каждого запроса и не может быть объединено в пул. Агент будет по-прежнему выполнять запросы к этому серверу, но каждый запрос будет выполняться через новое соединение.

Когда соединение закрывается клиентом или сервером, оно удаляется из пула. Любые неиспользуемые сокеты в пуле будут удалены, чтобы не заставлять процесс Node.js работать, когда нет незавершенных запросов. (см. socket.unref()).

Хорошей практикой является destroy() экземпляра Agent, когда он больше не используется, поскольку неиспользуемые сокеты потребляют ресурсы ОС.

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

1
2
3
4
5
http.get(options, (res) => {
    // Делаем что-нибудь
}).on('socket', (socket) => {
    socket.emit('agentRemove');
});

Агент также может быть использован для отдельного запроса. Если указать {agent: false} в качестве опции для функций http.get() или http.request(), то для клиентского соединения будет использоваться одноразовый Agent с параметрами по умолчанию.

agent:false:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
http.get(
    {
        hostname: 'localhost',
        port: 80,
        path: '/',
        agent: false, // Создаем нового агента только для этого запроса
    },
    (res) => {
        // Делаем что-нибудь с ответом
    }
);

new Agent

1
new Agent([options]);
  • options <Object> Набор конфигурируемых опций для установки на агента. Может иметь следующие поля:
    • keepAlive <boolean> Сохранять сокеты даже при отсутствии невыполненных запросов, чтобы их можно было использовать для будущих запросов без необходимости восстанавливать TCP-соединение. Не путать со значением keep-alive заголовка Connection. Заголовок Connection: keep-alive всегда отправляется при использовании агента, за исключением случаев, когда заголовок Connection указан явно или когда опции keepAlive и maxSockets соответственно установлены в false и Infinity, в этом случае будет использоваться Connection: close. По умолчанию: false.
    • keepAliveMsecs <number> При использовании опции keepAlive указывает начальную задержку для пакетов TCP Keep-Alive. Игнорируется, если опция keepAlive имеет значение false или undefined. По умолчанию: 1000.
    • maxSockets <number> Максимальное количество сокетов, разрешенное для одного хоста. Если один и тот же хост открывает несколько одновременных соединений, каждый запрос будет использовать новый сокет, пока не будет достигнуто значение maxSockets. Если хост пытается открыть больше соединений, чем maxSockets, дополнительные запросы попадают в очередь ожидающих запросов и переходят в состояние активного соединения, когда существующее соединение завершается. Это гарантирует, что в любой момент времени с данного хоста будет не более maxSockets активных соединений. По умолчанию: бесконечность.
    • maxTotalSockets <number> Максимальное количество сокетов, разрешенное для всех хостов в целом. Каждый запрос будет использовать новый сокет, пока не будет достигнуто максимальное значение. По умолчанию: Infinity.
    • maxFreeSockets <number> Максимальное количество сокетов на хосте, которое можно оставить открытым в свободном состоянии. Имеет значение, только если keepAlive установлено в true. По умолчанию: 256.
    • scheduling <string> Стратегия планирования, которую следует применять при выборе следующего свободного сокета для использования. Это может быть 'fifo' или 'lifo'. Основное различие между этими двумя стратегиями планирования заключается в том, что 'lifo' выбирает последний использованный сокет, а 'fifo' выбирает наименее использованный сокет. В случае низкой скорости запросов в секунду, планирование 'lifo' снижает риск выбора сокета, который мог быть закрыт сервером из-за неактивности. В случае высокой скорости запросов в секунду, планирование 'fifo' будет максимизировать количество открытых сокетов, в то время как планирование 'lifo' будет поддерживать его на минимально возможном уровне. По умолчанию: 'lifo'.
    • timeout <number> Таймаут сокета в миллисекундах. Таймаут устанавливается при создании сокета.

Также поддерживаются опции в socket.connect().

В стандартном http.globalAgent, который используется http.request(), все эти значения установлены по умолчанию.

Для настройки любого из них необходимо создать пользовательский экземпляр http.Agent.

1
2
3
4
const http = require('node:http');
const keepAliveAgent = new http.Agent({ keepAlive: true });
options.agent = keepAliveAgent;
http.request(options, onResponseCallback);

agent.createConnection

1
agent.createConnection(options[, callback])
  • options <Object> Опции, содержащие детали соединения. Формат опций смотрите в net.createConnection()
  • callback <Function> Функция обратного вызова, которая получает созданный сокет
  • Возвращает: {stream.Duplex}

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

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

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

Этот метод гарантированно возвращает экземпляр класса <net.Socket>, подкласса {stream.Duplex}, если пользователь не укажет тип сокета, отличный от <net.Socket>.

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

agent.keepSocketAlive

1
agent.keepSocketAlive(socket);
  • socket {stream.Duplex}

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

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

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

Аргумент socket может быть экземпляром <net.Socket>, подкласса {stream.Duplex}.

agent.reuseSocket

1
agent.reuseSocket(socket, request);
  • socket {stream.Duplex}
  • request {http.ClientRequest}

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

1
socket.ref();

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

Аргумент socket может быть экземпляром <net.Socket>, подкласса {stream.Duplex}.

agent.destroy

1
agent.destroy();

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

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

agent.freeSockets

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

Сокеты в списке freeSockets будут автоматически уничтожены и удалены из массива по таймауту.

agent.getName

1
agent.getName([options]);
  • options <Object> Набор опций, предоставляющих информацию для генерации имени
    • host <string> Доменное имя или IP-адрес сервера, на который будет отправлен запрос
    • port <number> Порт удаленного сервера
    • localAddress <string> Локальный интерфейс для привязки сетевых соединений при выдаче запроса
    • family <integer> Должно быть 4 или 6, если это не равно undefined.
  • Возвращает: <string>

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

agent.maxFreeSockets

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

agent.maxSockets

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

agent.maxTotalSockets

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

agent.requests

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

agent.sockets

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

Класс http.ClientRequest

  • Расширяет: {http.OutgoingMessage}

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

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

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

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

Для обратной совместимости, res будет выдавать 'error' только если зарегистрирован слушатель 'error'.

Установите заголовок Content-Length, чтобы ограничить размер тела ответа. Если response.strictContentLength установлен в true, несоответствие значения заголовка Content-Length приведет к возникновению ошибки, определяемой code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH.

Значение Content-Length должно быть в байтах, а не в символах. Используйте Buffer.byteLength() для определения длины тела в байтах.

Событие abort

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

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

Вместо этого слушайте событие 'close'.

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

Событие close

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

Событие connect

  • ответ {http.IncomingMessage}
  • сокет {stream.Duplex}
  • head <Buffer>

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

Это событие гарантированно передается экземпляру класса <net.Socket>, подкласса {stream.Duplex}, если только пользователь не укажет тип сокета, отличный от <net.Socket>.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
const http = require('node:http');
const net = require('node:net');
const { URL } = require('node:url');

// Create an HTTP tunneling proxy
const proxy = http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
    // Connect to an origin server
    const { port, hostname } = new URL(`http://${req.url}`);
    const serverSocket = net.connect(
        port || 80,
        hostname,
        () => {
            clientSocket.write(
                'HTTP/1.1 200 Connection Established\r\n' +
                    'Proxy-agent: Node.js-Proxy\r\n' +
                    '\r\n'
            );
            serverSocket.write(head);
            serverSocket.pipe(clientSocket);
            clientSocket.pipe(serverSocket);
        }
    );
});

// Now that proxy is running
proxy.listen(1337, '127.0.0.1', () => {
    // Make a request to a tunneling proxy
    const options = {
        port: 1337,
        host: '127.0.0.1',
        method: 'CONNECT',
        path: 'www.google.com:80',
    };

    const req = http.request(options);
    req.end();

    req.on('connect', (res, socket, head) => {
        console.log('got connected!');

        // Make a request over an HTTP tunnel
        socket.write(
            'GET / HTTP/1.1\r\n' +
                'Host: www.google.com:80\r\n' +
                'Connection: close\r\n' +
                '\r\n'
        );
        socket.on('data', (chunk) => {
            console.log(chunk.toString());
        });
        socket.on('end', () => {
            proxy.close();
        });
    });
});

Событие continue

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

Событие finish

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

Событие information

Выдается, когда сервер посылает промежуточный ответ 1xx (исключая 101 Upgrade). Слушатели этого события получат объект, содержащий версию HTTP, код статуса, сообщение о статусе, объект заголовков с ключевыми значениями и массив с именами необработанных заголовков, за которыми следуют их соответствующие значения.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
const http = require('node:http');

const options = {
    host: '127.0.0.1',
    port: 8080,
    path: '/length_request',
};

// Make a request
const req = http.request(options);
req.end();

req.on('information', (info) => {
    console.log(
        `Got information prior to main response: ${info.statusCode}`
    );
});

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

Событие response

  • response {http.IncomingMessage}

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

Событие socket

  • socket {stream.Duplex}

Это событие гарантированно передается экземпляру класса <net.Socket>, подкласса {stream.Duplex}, если пользователь не укажет тип сокета, отличный от <net.Socket>.

Событие timeout

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

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

Событие upgrade

  • ответ {http.IncomingMessage}
  • сокет {stream.Duplex}
  • head <Buffer>

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

Это событие гарантированно передается экземпляру класса <net.Socket>, подкласса {stream.Duplex}, если только пользователь не укажет тип сокета, отличный от <net.Socket>.

Пара клиент-сервер демонстрирует, как прослушивать событие update.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
const http = require('node:http');

// Create an HTTP server
const server = http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('okay');
});
server.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
server.listen(1337, '127.0.0.1', () => {
    // make a request
    const options = {
        port: 1337,
        host: '127.0.0.1',
        headers: {
            Connection: 'Upgrade',
            Upgrade: 'websocket',
        },
    };

    const req = http.request(options);
    req.end();

    req.on('upgrade', (res, socket, upgradeHead) => {
        console.log('got upgraded!');
        socket.end();
        process.exit(0);
    });
});

request.abort

1
request.abort();

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

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

Вместо этого используйте request.destroy().

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

request.aborted

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

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

Вместо этого проверьте request.destroyed.

Свойство request.aborted будет true, если запрос был прерван.

request.connection

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

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

Используйте request.socket.

  • {stream.Duplex}

См. request.socket.

request.cork

1
request.cork();

См. writable.cork().

request.end

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

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

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

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

request.destroy

1
request.destroy([error]);
  • error <Error> Необязательно, ошибка, которую нужно выдать с событием 'error'.
  • Возвращает: <this>

Уничтожить запрос. Опционально выдает событие 'error' и выдает событие 'close'. Вызов этой функции приведет к тому, что оставшиеся данные в ответе будут сброшены, а сокет будет уничтожен.

Подробности см. в writable.destroy().

request.destroyed

Является true после вызова request.destroy().

Более подробную информацию смотрите в writable.destroyed.

request.finished

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

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

Используйте request.writableEnded.

Свойство request.finished будет true, если был вызван request.end(). Свойство request.end() будет вызвано автоматически, если запрос был инициирован через http.get().

request.flushHeaders

1
request.flushHeaders();

Смывает заголовки запроса.

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

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

request.getHeader

1
request.getHeader(name);

Считывает заголовок запроса. Имя не чувствительно к регистру. Тип возвращаемого значения зависит от аргументов, переданных в request.setHeader().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
request.setHeader('content-type', 'text/html');
request.setHeader(
    'Content-Length',
    Buffer.byteLength(body)
);
request.setHeader('Cookie', [
    'type=ninja',
    'language=javascript',
]);
const contentType = request.getHeader('Content-Type');
// 'contentType' - 'text/html'
const contentLength = request.getHeader('Content-Length');
// 'contentLength' имеет тип число
const cookie = request.getHeader('Cookie');
// 'cookie' имеет тип string[]

request.getHeaderNames

1
request.getHeaderNames();

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

1
2
3
4
5
request.setHeader('Foo', 'bar');
request.setHeader('Cookie', ['foo=bar', 'bar=baz']);

const headerNames = request.getHeaderNames();
// headerNames === ['foo', 'cookie']

request.getHeaders

1
request.getHeaders();

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

Объект, возвращаемый методом request.getHeaders(), не прототипически наследует от JavaScript Object. Это означает, что типичные методы Object, такие как obj.toString(), obj.hasOwnProperty() и другие, не определены и не будут работать.

1
2
3
4
5
request.setHeader('Foo', 'bar');
request.setHeader('Cookie', ['foo=bar', 'bar=baz']);

const headers = request.getHeaders();
// headers === { foo: 'bar', 'cookie': ['foo=bar', 'bar=baz'] }

request.getRawHeaderNames

1
request.getRawHeaderNames();

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

1
2
3
4
5
request.setHeader('Foo', 'bar');
request.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headerNames = request.getRawHeaderNames();
// headerNames === ['Foo', 'Set-Cookie']

request.hasHeader

1
request.hasHeader(name);

Возвращает true, если заголовок, обозначенный name, в настоящее время установлен в исходящих заголовках. Соответствие имени заголовка не чувствительно к регистру.

1
const hasContentType = request.hasHeader('content-type');

request.maxHeadersCount

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

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

request.path

request.method

request.host

request.protocol

  • <string> Протокол запроса.

request.removeHeader

1
request.removeHeader(name);

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

1
request.removeHeader('Content-Type');

request.reusedSocket

  • <boolean> Отправляется ли запрос через повторно используемый сокет.

При отправке запроса через агент с поддержкой keep-alive, базовый сокет может быть использован повторно. Но если сервер закроет соединение в неудачное время, клиент может столкнуться с ошибкой 'ECONNRESET'.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
const http = require('node:http');

// По умолчанию сервер имеет таймаут ожидания 5 секунд
http.createServer((req, res) => {
    res.write('hello\n');
    res.end();
}).listen(3000);

setInterval(() => {
    // Адаптация агента keep-alive
    http.get('http://localhost:3000', { agent }, (res) => {
        res.on('data', (data) => {
            // Ничего не делать
        });
    });
}, 5000); // Отправка запроса с интервалом в 5 секунд, так что легко нарваться на таймаут простоя.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
const http = require('node:http');
const agent = new http.Agent({ keepAlive: true });

function retriableRequest() {
    const req = http
        .get('http://localhost:3000', { agent }, (res) => {
            // ...
        })
        .on('error', (err) => {
            // Проверяем, нужна ли повторная попытка
            if (
                req.reusedSocket &&
                err.code === 'ECONNRESET'
            ) {
                retriableRequest();
            }
        });
}

retriableRequest();

request.setHeader

1
request.setHeader(name, value);

Устанавливает значение одного заголовка для объекта headers. Если этот заголовок уже существует в отправляемых заголовках, его значение будет заменено. Для отправки нескольких заголовков с одинаковым именем используйте массив строк. Значения, не являющиеся строками, будут сохранены без изменений. Поэтому request.getHeader() может возвращать нестроковые значения. Однако нестроковые значения будут преобразованы в строки для передачи по сети.

1
request.setHeader('Content-Type', 'application/json');

или

1
2
3
4
request.setHeader('Cookie', [
    'type=ninja',
    'language=javascript',
]);

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

Если вам нужно передать в значении символы UTF-8, пожалуйста, кодируйте значение, используя стандарт RFC 8187.

1
2
3
4
5
6
7
const filename = 'Rock 🎵.txt';
request.setHeader(
    'Content-Disposition',
    `attachment; filename*=utf-8''${encodeURIComponent(
        filename
    )}`
);

request.setNoDelay

1
request.setNoDelay([noDelay]);

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

request.setSocketKeepAlive

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

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

request.setTimeout

1
request.setTimeout(timeout[, callback])
  • timeout <number> Миллисекунды до завершения запроса.
  • callback <Function> Необязательная функция, которая будет вызвана, когда произойдет таймаут. Аналогично привязке к событию timeout.
  • Возвращает: {http.ClientRequest}

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

request.socket

  • {stream.Duplex}

Ссылка на базовый сокет. Обычно пользователи не хотят обращаться к этому свойству. В частности, сокет не будет испускать события `'readable'' из-за того, как парсер протокола присоединяется к сокету.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
const http = require('node:http');
const options = {
    host: 'www.google.com',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
    const ip = req.socket.localAddress;
    const port = req.socket.localPort;
    console.log(
        `Ваш IP-адрес - ${ip}, а порт источника - ${port}.`
    );
    // Потребляем объект ответа
});

Это свойство гарантированно является экземпляром класса <net.Socket>, подкласса {stream.Duplex}, если пользователь не указал тип сокета, отличный от <net.Socket>.

request.uncork

1
request.uncork();

См. writable.uncork().

request.writableEnded

Является true после вызова request.end(). Это свойство не указывает, были ли данные выгружены, для этого используйте request.writableFinished.

request.writableFinished

Является true, если все данные были выгружены в базовую систему, непосредственно перед тем, как будет выпущено событие 'finish'.

request.write

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

Отправляет фрагмент тела. Этот метод может быть вызван несколько раз. Если не задана Content-Length, данные будут автоматически закодированы в кодировке передачи HTTP Chunked, чтобы сервер знал, когда данные заканчиваются. Добавляется заголовок Transfer-Encoding: chunked. Вызов request.end() необходим для завершения отправки запроса.

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

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

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

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

http.Server

  • Расширяет: {net.Server}

Событие: checkContinue

  • запрос {http.IncomingMessage}
  • ответ {http.ServerResponse}

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

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

Когда это событие испущено и обработано, событие 'request' не будет испущено.

Событие: checkExpectation

  • запрос {http.IncomingMessage}
  • ответ {http.ServerResponse}

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

Когда это событие испущено и обработано, событие 'request' не будет испущено.

Событие: clientError

  • exception <Error>
  • socket {stream.Duplex}

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

Это событие гарантированно передается экземпляру класса <net.Socket>, подкласса {stream.Duplex}, если пользователь не укажет тип сокета, отличный от <net.Socket>.

Поведение по умолчанию заключается в попытке закрыть сокет с HTTP '400 Bad Request', или HTTP '431 Request Header Fields Too Large' в случае ошибки HPE_HEADER_OVERFLOW. Если сокет не доступен для записи или были отправлены заголовки текущего присоединенного http.ServerResponse, он немедленно уничтожается.

socket - это объект net.Socket, с которого произошла ошибка.

1
2
3
4
5
6
7
8
9
const http = require('node:http');

const server = http.createServer((req, res) => {
    res.end();
});
server.on('clientError', (err, socket) => {
    socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});
server.listen(8000);

Когда происходит событие clientError, не существует ни объекта request, ни объекта response, поэтому любой отправленный HTTP-ответ, включая заголовки ответа и полезную нагрузку, должен быть записан непосредственно в объект socket. Необходимо следить за тем, чтобы ответ был правильно отформатированным сообщением HTTP-ответа.

err - это экземпляр Error с двумя дополнительными колонками:

  • bytesParsed: количество байт пакета запроса, который Node.js, возможно, разобрал правильно;
  • rawPacket: необработанный пакет текущего запроса.

В некоторых случаях клиент уже получил ответ и/или сокет уже был уничтожен, как в случае ошибок ECONNRESET. Прежде чем пытаться отправить данные в сокет, лучше проверить, что он все еще доступен для записи.

1
2
3
4
5
6
7
server.on('clientError', (err, socket) => {
    if (err.code === 'ECONNRESET' || !socket.writable) {
        return;
    }

    socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});

Событие: close

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

Событие: connect

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

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

Это событие гарантированно передается экземпляру класса <net.Socket>, подкласса {stream.Duplex}, если пользователь не укажет тип сокета, отличный от <net.Socket>.

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

Событие: connection

  • socket {stream.Duplex}

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

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

Если здесь вызывается socket.setTimeout(), то таймаут будет заменен на server.keepAliveTimeout, когда сокет обслужит запрос (если server.keepAliveTimeout ненулевой).

Это событие гарантированно передается экземпляру класса <net.Socket>, подкласса {stream.Duplex}, если пользователь не укажет тип сокета, отличный от <net.Socket>.

Событие: dropRequest

  • request {http.IncomingMessage} Аргументы для HTTP-запроса, как в событии 'request'
  • socket {stream.Duplex} Сетевой сокет между сервером и клиентом

Когда количество запросов на сокете достигнет порога server.maxRequestsPerSocket, сервер отменит новые запросы и вместо них выдаст событие 'dropRequest', а затем отправит 503 клиенту.

Событие: request

  • запрос {http.IncomingMessage}
  • ответ {http.ServerResponse}

Выдается каждый раз, когда поступает запрос. На одно соединение может приходиться несколько запросов (в случае соединений HTTP Keep-Alive).

Событие: upgrade

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

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

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

Это событие гарантированно передается экземпляру класса <net.Socket>, подкласса {stream.Duplex}, если пользователь не укажет тип сокета, отличный от <net.Socket>.

server.close

1
server.close([callback]);

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

server.closeAllConnections

1
server.closeAllConnections();

Закрывает все соединения, подключенные к этому серверу.

server.closeIdleConnections

1
server.closeIdleConnections();

Закрывает все соединения, подключенные к этому серверу, которые не посылают запрос и не ожидают ответа.

server.headersTimeout

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

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

Это значение должно быть ненулевым (например, 120 секунд) для защиты от потенциальных атак Denial-of-Service в случае, если сервер развернут без обратного прокси.

server.listen

1
server.listen();

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

server.listening

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

server.maxHeadersCount

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

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

server.requestTimeout

  • <number> По умолчанию: 300000.

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

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

Это значение должно быть ненулевым (например, 120 секунд) для защиты от потенциальных атак Denial-of-Service в случае, если сервер развернут без обратного прокси.

server.setTimeout

1
server.setTimeout([msecs][, callback])
  • msecs <number> По умолчанию: 0 (без таймаута)
  • callback <Function>
  • Возвращает: {http.Server}

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

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

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

server.maxRequestsPerSocket

  • <number> Запросы на сокет. По умолчанию: 0 (без ограничений).

Максимальное количество запросов, которое может обработать сокет перед закрытием соединения keep alive.

Значение 0 отключает ограничение.

При достижении лимита значение заголовка Connection будет установлено на close, но фактически соединение закрыто не будет, последующие запросы, отправленные после достижения лимита, получат в ответ 503 Service Unavailable.

server.timeout

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

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

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

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

server.keepAliveTimeout

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

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

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

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

http.ServerResponse

  • Расширяет: {http.OutgoingMessage}

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

Событие: close

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

Событие: finish

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

response.addTrailers

1
response.addTrailers(headers);

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

Заголовки будут только если для ответа используется кодировка chunked; если это не так (например, если запрос был HTTP/1.0), они будут молча отброшены.

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

1
2
3
4
5
6
7
8
9
response.writeHead(200, {
    'Content-Type': 'text/plain',
    Trailer: 'Content-MD5',
});
response.write(fileData);
response.addTrailers({
    'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667',
});
response.end();

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

response.connection

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

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

Используйте response.socket.

  • {stream.Duplex}

См. response.socket.

response.cork

1
response.cork();

См. writable.cork().

response.end

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

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

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

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

response.finished

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

Утратил актуальность. Используйте response.writableEnded.

Свойство response.finished будет true, если был вызван response.end().

response.flushHeaders

1
response.flushHeaders();

Промывает заголовки ответа. См. также: request.flushHeaders().

response.getHeader

1
response.getHeader(name);

Считывает заголовок, который уже был поставлен в очередь, но не отправлен клиенту. Имя не чувствительно к регистру. Тип возвращаемого значения зависит от аргументов, переданных в response.setHeader().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
response.setHeader('Content-Type', 'text/html');
response.setHeader(
    'Content-Length',
    Buffer.byteLength(body)
);
response.setHeader('Set-Cookie', [
    'type=ninja',
    'language=javascript',
]);
const contentType = response.getHeader('content-type');
// contentType - 'text/html'
const contentLength = response.getHeader('Content-Length');
// contentLength имеет тип число
const setCookie = response.getHeader('set-cookie');
// setCookie имеет тип string[]

response.getHeaderNames

1
response.getHeaderNames();

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

1
2
3
4
5
response.setHeader('Foo', 'bar');
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headerNames = response.getHeaderNames();
// headerNames === ['foo', 'set-cookie']

response.getHeaders

1
response.getHeaders();

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

Объект, возвращаемый методом response.getHeaders(), не прототипически наследует от JavaScript Object. Это означает, что типичные методы Object, такие как obj.toString(), obj.hasOwnProperty() и другие, не определены и не будут работать.

1
2
3
4
5
response.setHeader('Foo', 'bar');
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headers = response.getHeaders();
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }

response.hasHeader

1
response.hasHeader(name);

Возвращает true, если заголовок, обозначенный name, в настоящее время установлен в исходящих заголовках. Соответствие имени заголовка не чувствительно к регистру.

1
const hasContentType = response.hasHeader('content-type');

response.headersSent

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

response.removeHeader

1
response.removeHeader(name);

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

1
response.removeHeader('Content-Encoding');

response.req

  • {http.IncomingMessage}

Ссылка на исходный объект HTTP request.

response.sendDate

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

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

response.setHeader

1
response.setHeader(name, value);
  • name <string>
  • value <any>
  • Возвращает: {http.ServerResponse}

Возвращает объект ответа.

Устанавливает одно значение заголовка для неявных заголовков. Если этот заголовок уже существует в отправляемых заголовках, его значение будет заменено. Для отправки нескольких заголовков с одинаковым именем используйте массив строк. Значения, не являющиеся строками, будут сохранены без изменений. Поэтому response.getHeader() может возвращать нестроковые значения. Однако нестроковые значения будут преобразованы в строки для передачи по сети. Один и тот же объект ответа возвращается вызывающей стороне, чтобы обеспечить возможность цепочки вызовов.

1
response.setHeader('Content-Type', 'text/html');

или

1
2
3
4
response.setHeader('Set-Cookie', [
    'type=ninja',
    'language=javascript',
]);

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

Когда заголовки были установлены с помощью response.setHeader(), они будут объединены с любыми заголовками, переданными в response.writeHead(), причем заголовки, переданные в response.writeHead(), будут иметь приоритет.

1
2
3
4
5
6
7
// Возвращает content-type = text/plain
const server = http.createServer((req, res) => {
    res.setHeader('Content-Type', 'text/html');
    res.setHeader('X-Foo', 'bar');
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('ok');
});

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

response.setTimeout

1
response.setTimeout(msecs[, callback])

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

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

response.socket

  • {stream.Duplex}

Ссылка на базовый сокет. Обычно пользователи не хотят обращаться к этому свойству. В частности, сокет не будет выдавать события 'readable' из-за того, как парсер протокола подключается к сокету. После response.end() свойство обнуляется.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const http = require('node:http');
const server = http
    .createServer((req, res) => {
        const ip = res.socket.remoteAddress;
        const port = res.socket.remotePort;
        res.end(
            `Ваш IP адрес ${ip} и ваш порт источника ${port}.`
        );
    })
    .listen(3000);

Это свойство гарантированно является экземпляром класса <net.Socket>, подкласса {stream.Duplex}, если пользователь не указал тип сокета, отличный от <net.Socket>.

response.statusCode

  • <number> По умолчанию: 200.

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

1
response.statusCode = 404;

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

response.statusMessage

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

1
response.statusMessage = 'Not found';

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

response.strictContentLength

Если установлено значение true, Node.js будет проверять, равны ли значение заголовка Content-Length и размер тела в байтах. Несоответствие значения заголовка Content-Length приведет к возникновению ошибки, определяемой кодом: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

response.uncork

1
response.uncork();

См. writable.uncork().

response.writableEnded

Является true после вызова response.end(). Это свойство не указывает, были ли данные удалены, для этого используйте response.writableFinished.

response.writableFinished

Является true, если все данные были выгружены в базовую систему, непосредственно перед тем, как будет выпущено событие 'finish'.

response.write

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

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

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

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

chunk может быть строкой или буфером. Если chunk является строкой, второй параметр указывает, как кодировать его в поток байтов. Функция callback будет вызвана, когда этот кусок данных будет сброшен.

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

При первом вызове response.write() клиенту будет отправлена буферизованная информация заголовка и первый фрагмент тела. При втором вызове response.write() Node.js предполагает, что данные будут передаваться потоком, и отправляет новые данные отдельно. То есть, ответ буферизируется до первого куска тела.

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

response.writeContinue

1
response.writeContinue();

Отправляет клиенту сообщение HTTP/1.1 100 Continue, указывающее на то, что тело запроса должно быть отправлено. См. событие 'checkContinue' на Server.

response.writeEarlyHints

1
response.writeEarlyHints(hints[, callback])

Отправляет сообщение HTTP/1.1 103 Early Hints клиенту с заголовком Link, указывая, что пользовательский агент может предварительно загрузить/подключить связанные ресурсы. hints - это объект, содержащий значения заголовков, которые должны быть отправлены с сообщением ранних подсказок. Необязательный аргумент callback будет вызван, когда сообщение ответа будет записано.

Пример

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const earlyHintsLink =
    '</styles.css>; rel=preload; as=style';
response.writeEarlyHints({
    link: earlyHintsLink,
});

const earlyHintsLinks = [
    '</styles.css>; rel=preload; as=style',
    '</scripts.js>; rel=preload; as=script',
];
response.writeEarlyHints({
    link: earlyHintsLinks,
    'x-trace-id': 'id для диагностики',
});

const earlyHintsCallback = () =>
    console.log('early hints message sent');
response.writeEarlyHints(
    {
        link: earlyHintsLinks,
    },
    earlyHintsCallback
);

response.writeHead

1
response.writeHead(statusCode[, statusMessage][, headers])

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

headers может быть массивом, где ключи и значения находятся в одном списке. Это не список кортежей. Таким образом, четные смещения являются значениями ключей, а нечетные смещения - связанными с ними значениями. Массив имеет тот же формат, что и request.rawHeaders.

Возвращает ссылку на ServerResponse, так что вызовы могут быть объединены в цепочку.

1
2
3
4
5
6
7
const body = 'hello world';
response
    .writeHead(200, {
        'Content-Length': Buffer.byteLength(body),
        'Content-Type': 'text/plain',
    })
    .end(body);

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

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

Если заголовки были установлены с помощью response.setHeader(), они будут объединены с любыми заголовками, переданными в response.writeHead(), причем заголовки, переданные в response.writeHead(), будут иметь приоритет.

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

1
2
3
4
5
6
7
// Возвращает 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 считывается в байтах, а не в символах. Используйте Buffer.byteLength() для определения длины тела в байтах. Node.js будет проверять, равны ли Content-Length и длина переданного тела или нет.

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

response.writeProcessing

1
response.writeProcessing();

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

http.IncomingMessage

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

В отличие от своего значения socket, которое является подклассом {stream.Duplex}, само IncomingMessage расширяет <stream.Readable> и создается отдельно для разбора и выдачи входящих HTTP-заголовков и полезной нагрузки, поскольку базовый сокет может быть использован многократно в случае keep-alive.

Событие: aborted

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

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

Вместо этого слушайте событие 'close'.

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

Событие: close

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

message.aborted

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

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

Проверьте message.destroyed из {stream.Readable}.

Свойство message.aborted будет true, если запрос был прерван.

message.complete

Свойство message.complete будет иметь значение true, если было получено и успешно разобрано полное HTTP-сообщение.

Это свойство особенно полезно как средство определения того, полностью ли клиент или сервер передал сообщение до того, как соединение было разорвано:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
const req = http.request(
    {
        host: '127.0.0.1',
        port: 8080,
        method: 'POST',
    },
    (res) => {
        res.resume();
        res.on('end', () => {
            if (!res.complete)
                console.error(
                    'The connection was terminated while the message was still being sent'
                );
        });
    }
);

message.connection

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

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

Используйте message.socket.

Псевдоним для message.socket.

message.destroy

1
message.destroy([error]);

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

message.headers

Объект заголовков запроса/ответа.

Пары ключ-значение имен и значений заголовков. Имена заголовков приводятся в нижнем регистре.

1
2
3
4
5
6
// Выводит что-то вроде:
//
// { { '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, server или user-agent отбрасываются. Чтобы разрешить объединение дубликатов перечисленных выше заголовков, используйте опцию joinDuplicateHeaders в http.request() и http.createServer(). См. RFC 9110 Раздел 5.3 для получения дополнительной информации.
  • set-cookie - это всегда массив. Дубликаты добавляются в массив.
  • Для дублирующихся заголовков cookie значения объединяются с помощью ;.
  • Для всех остальных заголовков значения объединяются с помощью ,.

message.headersDistinct

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

1
2
3
4
5
6
// Выводит что-то вроде:
//
// { 'user-agent': ['curl/7.22.0'],
// host: ['127.0.0.1:8000'],
// accept: ['*/*'] }
console.log(request.headersDistinct);

message.httpVersion

В случае запроса сервера, версия HTTP, отправленная клиентом. В случае ответа клиента, версия HTTP подключенного сервера. Возможно, либо '1.1', либо '1.0'.

Также message.httpVersionMajor является первым целым числом, а message.httpVersionMinor - вторым.

message.method

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

Метод запроса в виде строки. Только для чтения. Примеры: 'GET', 'DELETE'.

message.rawHeaders

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

Ключи и значения находятся в одном списке. Это не список кортежей. Таким образом, четные смещения - это значения ключей, а нечетные смещения - связанные с ними значения.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// Выводит что-то вроде:
//
// [ '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

Необработанные ключи и значения трейлеров запроса/ответа точно в том виде, в котором они были получены. Заполняются только при событии конец.

message.setTimeout

1
message.setTimeout(msecs[, callback])

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

message.socket

  • {stream.Duplex}

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

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

Это свойство гарантированно является экземпляром класса <net.Socket>, подкласса {stream.Duplex}, если пользователь не указал тип сокета, отличный от <net.Socket>, или не обнулен внутренне.

message.statusCode

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

Трехзначный код состояния ответа HTTP. НАПРИМЕР, 404.

message.statusMessage

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

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

message.trailers

Объект трейлеров запроса/ответа. Заполняется только при событии end.

message.trailersDistinct

Аналогичен message.trailers, но здесь нет логики объединения и значения всегда являются массивами строк, даже для заголовков, полученных только один раз. Заполняется только при событии end.

message.url

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

Строка URL запроса. Она содержит только тот URL, который присутствует в фактическом HTTP-запросе. Возьмем следующий запрос:

1
2
GET /status?name=ryan HTTP/1.1
Accept: text/plain

Разберем URL на части:

1
new URL(request.url, `http://${request.headers.host}`);

Когда request.url будет '/status?name=ryan' и request.headers.host будет 'localhost:3000':

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
$ node
> new URL(request.url, `http://${request.headers.host}`)
URL {
  href: 'http://localhost:3000/status?name=ryan',
  origin: 'http://localhost:3000',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'localhost:3000',
  hostname: 'localhost',
  port: '3000',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
}

http.OutgoingMessage

Этот класс служит в качестве родительского класса для http.ClientRequest и http.ServerResponse. Это абстрактное исходящее сообщение с точки зрения участников HTTP-транзакции.

Событие: drain

Выдается, когда буфер сообщения снова свободен.

Событие: finish

Выдается при успешном завершении передачи.

Событие: prefinish

Вызывается после вызова функции outgoingMessage.end(). Когда это событие происходит, все данные были обработаны, но не обязательно полностью смыты.

outgoingMessage.addTrailers

1
outgoingMessage.addTrailers(headers);

Добавляет HTTP трейлеры (заголовки, но в конце сообщения) к сообщению.

Трейлеры будут только если сообщение закодировано в виде чанков. В противном случае трейлеры будут молча отброшены.

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

1
2
3
4
5
6
7
8
9
message.writeHead(200, {
    'Content-Type': 'text/plain',
    Trailer: 'Content-MD5',
});
message.write(fileData);
message.addTrailers({
    'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667',
});
message.end();

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

outgoingMessage.appendHeader

1
outgoingMessage.appendHeader(name, value);

Добавляет одно значение заголовка для объекта заголовка.

Если значение является массивом, это эквивалентно вызову этого метода несколько раз.

Если предыдущего значения для заголовка не было, это эквивалентно вызову outgoingMessage.setHeader(name, value).

В зависимости от значения параметра options.uniqueHeaders при создании клиентского запроса или сервера, заголовок будет отправлен несколько раз или один раз со значениями, объединенными с помощью ;.

outgoingMessage.connection

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

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

Используйте outgoingMessage.socket вместо этого.

Псевдоним outgoingMessage.socket.

outgoingMessage.cork

1
outgoingMessage.cork();

См. writable.cork().

outgoingMessage.destroy

1
outgoingMessage.destroy([error]);
  • error <Error> Необязательно, ошибка, которую нужно выдать с событием error.
  • Возвращает: <this>

Уничтожает сообщение. Если сокет связан с сообщением и подключен, этот сокет также будет уничтожен.

outgoingMessage.end

1
outgoingMessage.end(chunk[, encoding][, callback])

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

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

Если указан callback, он будет вызван, когда сообщение будет завершено (эквивалентно слушателю события 'finish').

outgoingMessage.flushHeaders

1
outgoingMessage.flushHeaders();

Смывает заголовки сообщений.

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

Обычно это желательно (это экономит время прохождения TCP), но не тогда, когда первые данные не будут отправлены, возможно, намного позже. Функция outgoingMessage.flushHeaders() обходит оптимизацию и запускает сообщение.

outgoingMessage.getHeader

1
outgoingMessage.getHeader(name);

Получает значение HTTP-заголовка с заданным именем. Если этот заголовок не установлен, возвращаемое значение будет undefined.

outgoingMessage.getHeaderNames

1
outgoingMessage.getHeaderNames();

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

outgoingMessage.getHeaders

1
outgoingMessage.getHeaders();

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

Объект, возвращаемый методом outgoingMessage.getHeaders(), прототипически не наследует от JavaScript Object. Это означает, что типичные методы Object, такие как obj.toString(), obj.hasOwnProperty() и другие, не определены и не будут работать.

1
2
3
4
5
6
7
8
outgoingMessage.setHeader('Foo', 'bar');
outgoingMessage.setHeader('Set-Cookie', [
    'foo=bar',
    'bar=baz',
]);

const headers = outgoingMessage.getHeaders();
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }

outgoingMessage.hasHeader

1
outgoingMessage.hasHeader(name);

Возвращает true, если заголовок, обозначенный name, в настоящее время установлен в исходящих заголовках. Имя заголовка не чувствительно к регистру.

1
2
3
const hasContentType = outgoingMessage.hasHeader(
    'content-type'
);

outgoingMessage.headersSent

Только для чтения. true, если заголовки были отправлены, иначе false.

outgoingMessage.pipe

1
outgoingMessage.pipe();

Переопределяет метод stream.pipe(), унаследованный от унаследованного класса Stream, который является родительским классом http.OutgoingMessage.

Вызов этого метода вызовет ошибку, поскольку outgoingMessage является потоком только для записи.

outgoingMessage.removeHeader

1
outgoingMessage.removeHeader(name);
  • name <string> Имя заголовка

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

1
outgoingMessage.removeHeader('Content-Encoding');

outgoingMessage.setHeader

1
outgoingMessage.setHeader(name, value);
  • name <string> Имя заголовка
  • value <any> Значение заголовка
  • Возвращает: <this>

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

outgoingMessage.setHeaders

1
outgoingMessage.setHeaders(headers);
  • headers {Headers} | {Map}
  • Возвращает: {http.ServerResponse}

Возвращает объект ответа.

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

1
2
const headers = new Headers({ foo: 'bar' });
response.setHeaders(headers);

или

1
2
const headers = new Map([['foo', 'bar']]);
res.setHeaders(headers);

Когда заголовки были установлены с помощью outgoingMessage.setHeaders(), они будут объединены с любыми заголовками, переданными в response.writeHead(), причем заголовки, переданные в response.writeHead(), будут иметь приоритет.

1
2
3
4
5
6
7
8
9
// Возвращает content-type = text/plain
const server = http.createServer((req, res) => {
    const headers = new Headers({
        'Content-Type': 'text/html',
    });
    res.setHeaders(headers);
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('ok');
});

outgoingMessage.setTimeout

1
outgoingMessage.setTimeout(msesc[, callback])
  • msesc <number>
  • callback <Function> Необязательная функция, которая будет вызываться при возникновении тайм-аута. Аналогично привязке к событию timeout.
  • Возвращает: <this>

Когда сокет связан с сообщением и подключен, будет вызвана функция socket.setTimeout() с msecs в качестве первого параметра.

outgoingMessage.socket

  • {stream.Duplex}

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

После вызова outgoingMessage.end() это свойство будет обнулено.

outgoingMessage.uncork

1
outgoingMessage.uncork();

См. writable.uncork()

outgoingMessage.writableCorked

Количество раз, когда outgoingMessage.cork() был вызван.

outgoingMessage.writableEnded

Является true, если была вызвана функция outgoingMessage.end(). Это свойство не указывает, были ли данные удалены. Для этого используйте message.writableFinished.

outgoingMessage.writableFinished

Является true, если все данные были переданы в базовую систему.

outgoingMessage.writableHighWaterMark

highWaterMark базового сокета, если он назначен. Иначе, уровень буфера по умолчанию, когда writable.write() начинает возвращать false (16384).

outgoingMessage.writableLength

Количество буферизованных байтов.

outgoingMessage.writableObjectMode

Всегда false.

outgoingMessage.write

1
outgoingMessage.write(chunk[, encoding][, callback])

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

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

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

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

http.METHODS

Список методов HTTP, которые поддерживаются парсером.

http.STATUS_CODES

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

http.createServer

1
http.createServer([options][, requestListener])

  • options <Object>

    • connectionsCheckingInterval: Устанавливает значение интервала в миллисекундах для проверки таймаута запроса и заголовков в неполных запросах. По умолчанию: 30000.
    • headersTimeout: Устанавливает значение таймаута в миллисекундах для получения полных заголовков HTTP от клиента. Дополнительную информацию смотрите в server.headersTimeout. По умолчанию: 60000.
    • insecureHTTPParser <boolean> Использовать небезопасный парсер HTTP, который принимает недействительные заголовки HTTP, если true. Следует избегать использования небезопасного парсера. Дополнительную информацию смотрите в --insecure-http-parser. По умолчанию: false.
    • IncomingMessage {http.IncomingMessage} Определяет класс IncomingMessage, который будет использоваться. Полезно для расширения оригинального IncomingMessage. По умолчанию: IncomingMessage.
    • keepAlive <boolean> Если установлено значение true, это включает функцию keep-alive на сокете сразу после получения нового входящего соединения, аналогично тому, как это делается в [socket.setKeepAlive([enable][, initialDelay])][socket.setKeepAlive(enable, initialDelay)]. По умолчанию: false.
    • keepAliveInitialDelay <number> Если задано положительное число, оно устанавливает начальную задержку перед отправкой первого зонда keepalive на неработающем сокете. По умолчанию: 0.
    • keepAliveTimeout: Количество миллисекунд бездействия, в течение которых сервер должен ожидать поступления дополнительных данных, после того как он закончил писать последний ответ, прежде чем сокет будет уничтожен. Дополнительную информацию смотрите в server.keepAliveTimeout. По умолчанию: 5000.
    • maxHeaderSize <number> Опционально переопределяет значение параметра --max-http-header-size для запросов, полученных этим сервером, т.е. максимальную длину заголовков запроса в байтах. По умолчанию: 16384 (16 KiB).
    • noDelay <boolean> Если установлено значение true, то отключает использование алгоритма Нагла сразу после получения нового входящего соединения. По умолчанию: true.
    • requestTimeout: Устанавливает значение таймаута в миллисекундах для получения всего запроса от клиента. Дополнительную информацию смотрите в server.requestTimeout. По умолчанию: 300000.
    • requireHostHeader <boolean> Заставляет сервер отвечать кодом состояния 400 (Bad Request) на любой запрос HTTP/1.1, в котором отсутствует заголовок Host (как предписано спецификацией). По умолчанию: true.
    • joinDuplicateHeaders <boolean> Объединяет значения строк полей нескольких заголовков в запросе с помощью , вместо того, чтобы отбрасывать дубликаты. Более подробную информацию смотрите в message.headers. По умолчанию: false.
    • ServerResponse {http.ServerResponse} Определяет класс ServerResponse, который будет использоваться. Полезен для расширения оригинального ServerResponse. По умолчанию: ServerResponse.
    • uniqueHeaders <Array> Список заголовков ответа, которые должны быть отправлены только один раз. Если значение заголовка представляет собой массив, элементы будут объединены с помощью ;.

  • requestListener <Function>

  • Возвращает: {http.Server}

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
const http = require('node:http');

// Создаем локальный сервер для получения данных
const server = http.createServer((req, res) => {
    res.writeHead(200, {
        'Content-Type': 'application/json',
    });
    res.end(
        JSON.stringify({
            data: 'Hello World!',
        })
    );
});

server.listen(8000);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
const http = require('node:http');

// Создаем локальный сервер для получения данных
const server = http.createServer();

// Прослушиваем событие запроса
server.on('request', (request, res) => {
    res.writeHead(200, {
        'Content-Type': 'application/json',
    });
    res.end(
        JSON.stringify({
            data: 'Hello World!',
        })
    );
});

server.listen(8000);

http.get

1
http.get(options[, callback])

1
http.get(url[, options][, callback])
  • url <string> | <URL>
  • options <Object> Принимает те же options, что и http.request(), с method, всегда установленным на GET. Свойства, унаследованные от прототипа, игнорируются.
  • callback <Function>
  • Возвращает: {http.ClientRequest}

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

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

Пример получения JSON:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
http.get('http://localhost:8000/', (res) => {
    const { statusCode } = res;
    const contentType = res.headers['content-type'];

    let error;
    // Any 2xx status code signals a successful response but
    // here we're only checking for 200.
    if (statusCode !== 200) {
        error = new Error(
            'Request Failed.\n' +
                `Status Code: ${statusCode}`
        );
    } else if (!/^application\/json/.test(contentType)) {
        error = new Error(
            'Invalid content-type.\n' +
                `Expected application/json but received ${contentType}`
        );
    }
    if (error) {
        console.error(error.message);
        // Consume response data to free up memory
        res.resume();
        return;
    }

    res.setEncoding('utf8');
    let rawData = '';
    res.on('data', (chunk) => {
        rawData += chunk;
    });
    res.on('end', () => {
        try {
            const parsedData = JSON.parse(rawData);
            console.log(parsedData);
        } catch (e) {
            console.error(e.message);
        }
    });
}).on('error', (e) => {
    console.error(`Got error: ${e.message}`);
});

// Create a local server to receive data from
const server = http.createServer((req, res) => {
    res.writeHead(200, {
        'Content-Type': 'application/json',
    });
    res.end(
        JSON.stringify({
            data: 'Hello World!',
        })
    );
});

server.listen(8000);

http.globalAgent

  • {http.Agent}

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

http.maxHeaderSize

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

Его можно переопределить для серверов и клиентских запросов, передав параметр maxHeaderSize.

http.request

1
http.request(options[, callback])

http.request

1
http.request(url[, options][, callback])
  • url <string> | <URL>
  • options <Object>
    • agent {http.Agent} | <boolean> Управляет поведением Agent. Возможные значения:
      • undefined (по умолчанию): использовать http.globalAgent для данного хоста и порта.
      • Agent объект: явно использовать переданный Agent.
      • false: заставляет использовать новый Agent со значениями по умолчанию.
    • auth <string> Базовая аутентификация ('user:password') для вычисления заголовка Authorization.
    • createConnection <Function> Функция, создающая сокет/поток для использования в запросе, когда опция agent не используется. Это можно использовать, чтобы не создавать собственный класс Agent только для переопределения функции по умолчанию createConnection. Подробнее см. в agent.createConnection(). Любой поток Duplex является допустимым возвращаемым значением.
    • defaultPort <number> Порт по умолчанию для протокола. По умолчанию: agent.defaultPort, если используется Agent, иначе undefined.
    • family <number> Семейство IP-адресов для использования при разрешении host или hostname. Допустимыми значениями являются 4 или 6. Если значение не указано, будут использоваться IP v4 и v6.
    • headers <Object> Объект, содержащий заголовки запроса.
    • hints <number> Необязательные dns.lookup() hints.
    • host <string> Доменное имя или IP-адрес сервера, на который будет отправлен запрос. По умолчанию: 'localhost'.
    • hostname <string> Псевдоним для host. Для поддержки url.parse(), hostname будет использоваться, если указаны и host и hostname.
    • insecureHTTPParser <boolean> Использовать небезопасный парсер HTTP, который принимает недействительные заголовки HTTP, если true. Следует избегать использования небезопасного парсера. Дополнительную информацию смотрите в --insecure-http-parser. По умолчанию: false.
    • localAddress <string> Локальный интерфейс для привязки сетевых соединений.
    • localPort <number> Локальный порт для подключения.
    • lookup <Function> Пользовательская функция поиска. По умолчанию: dns.lookup().
    • maxHeaderSize <number> Опционально переопределяет значение параметра --max-http-header-size (максимальная длина заголовков ответа в байтах) для ответов, полученных от сервера. По умолчанию: 16384 (16 KiB).
    • method <string> Строка, определяющая метод запроса HTTP. По умолчанию: GET.
    • path <string> Путь запроса. Должен включать строку запроса, если таковая имеется. Например, '/index.html?page=12'. Исключение возникает, если путь запроса содержит недопустимые символы. В настоящее время отклоняются только пробелы, но в будущем это может измениться. По умолчанию: '/'.
    • port <number> Порт удаленного сервера. По умолчанию: defaultPort, если установлен, иначе 80.
    • protocol <string> Используемый протокол. По умолчанию: 'http:'.
    • setHost <boolean>: Определяет, следует ли автоматически добавлять заголовок Host. По умолчанию true.
    • signal <AbortSignal>: Сигнал прерывания, который может быть использован для прерывания текущего запроса.
    • socketPath <string>. Сокет домена Unix. Не может быть использован, если указано одно из host или port, так как они определяют TCP-сокет.
    • timeout <number>: Число, определяющее таймаут сокета в миллисекундах. Это задает таймаут до подключения сокета.
    • uniqueHeaders <Array>. Список заголовков запроса, которые должны быть отправлены только один раз. Если значение заголовка представляет собой массив, элементы будут объединены с помощью ;.
    • joinDuplicateHeaders <boolean> Объединяет значения строк полей нескольких заголовков в запросе с помощью , вместо того, чтобы отбрасывать дубликаты. Более подробную информацию смотрите в message.headers. По умолчанию: false.
  • callback <Function>
  • Возвращает: {http.ClientRequest}

Также поддерживаются опции в socket.connect().

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

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
const http = require('node:http');

const postData = JSON.stringify({
    msg: 'Hello World!',
});

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

const req = http.request(options, (res) => {
    console.log(`STATUS: ${res.statusCode}`);
    console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
    res.setEncoding('utf8');
    res.on('data', (chunk) => {
        console.log(`BODY: ${chunk}`);
    });
    res.on('end', () => {
        console.log('No more data in response.');
    });
});

req.on('error', (e) => {
    console.error(`problem with request: ${e.message}`);
});

// Write data to request body
req.write(postData);
req.end();

В примере был вызван req.end(). При использовании http.request() необходимо всегда вызывать req.end() для обозначения окончания запроса - даже если в тело запроса не записываются данные.

Если во время запроса встречается какая-либо ошибка (будь то разрешение DNS, ошибки на уровне TCP или фактические ошибки разбора HTTP), на возвращаемом объекте запроса выдается событие 'error'. Как и в случае со всеми событиями 'error', если не зарегистрированы слушатели, ошибка будет сброшена.

Есть несколько специальных заголовков, на которые следует обратить внимание.

  • Отправка 'Connection: keep-alive' уведомляет Node.js о том, что соединение с сервером должно сохраняться до следующего запроса.

  • Отправка заголовка 'Content-Length' отключит кодировку по умолчанию.

  • Отправка заголовка 'Expect' немедленно отправит заголовки запроса. Обычно при отправке 'Expect: 100-continue' следует установить таймаут и слушателя для события 'continue'. См. RFC 2616 Раздел 8.2.3 для получения дополнительной информации.

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

Пример с использованием URL в качестве options:

1
2
3
4
5
const options = new URL('http://abc:[email protected]');

const req = http.request(options, (res) => {
    // ...
});

При успешном запросе будут выданы следующие события в следующем порядке:

  • socket
  • response
    • 'data' любое количество раз, на объекте res ('data' не будет выдаваться вообще, если тело ответа пустое, например, при большинстве перенаправлений)
    • 'end' на объекте res.
  • close.

В случае ошибки соединения будут выданы следующие события:

  • socket
  • error
  • close

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

  • socket
  • error с ошибкой с сообщением 'Error: socket hang up' и кодом 'ECONNRESET'
  • close

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

  • socket
  • response
    • data любое количество раз, на объекте res.
  • (здесь соединение закрыто)
  • aborted на объекте res
  • error на объекте res с ошибкой с сообщением Ошибка: прервано и кодом ECONNRESET.
  • close
  • close объекта res

Если req.destroy() вызывается до назначения сокета, то следующие события будут выдаваться в следующем порядке:

  • (req.destroy() вызывается здесь)
  • 'error' с ошибкой с сообщением 'Error: socket hang up' и кодом 'ECONNRESET'.
  • close.

Если req.destroy() вызывается до успешного соединения, то следующие события будут выдаваться в следующем порядке:

  • 'socket'
  • (req.destroy() вызывается здесь)
  • 'error' с ошибкой с сообщением 'Error: socket hang up' и кодом 'ECONNRESET'
  • close.

Если req.destroy() вызывается после получения ответа, то следующие события будут выдаваться в следующем порядке:

  • 'socket'
  • response
    • data любое количество раз, на объекте res.
  • (req.destroy() вызывается здесь)
  • aborted на объекте res
  • 'error' на объекте res с ошибкой с сообщением 'Error: aborted' и кодом 'ECONNRESET'.
  • close
  • close объекта `res``

Если req.abort() вызывается до назначения сокета, то следующие события будут выдаваться в следующем порядке:

  • (req.abort() вызывается здесь)
  • abort
  • close.

Если req.abort() вызывается до успешного соединения, то следующие события будут выдаваться в следующем порядке:

  • 'socket'
  • (req.abort() вызывается здесь)
  • 'abort'
  • 'error' с ошибкой с сообщением 'Error: socket hang up' и кодом 'ECONNRESET'
  • close.

Если req.abort() вызывается после получения ответа, то следующие события будут выдаваться в следующем порядке:

  • 'socket'
  • response
    • data любое количество раз, на объекте res.
  • (req.abort() вызывается здесь)
  • 'abort'
  • aborted на объекте res
  • error на объекте res с ошибкой с сообщением 'Error: aborted' и кодом 'ECONNRESET'.
  • close
  • close на объекте res

Установка опции timeout или использование функции setTimeout() не прервет запрос и не сделает ничего, кроме добавления события 'timeout'.

Передача AbortSignal и последующий вызов abort на соответствующем AbortController будет вести себя так же, как вызов .destroy() на самом запросе.

http.validateHeaderName

1
http.validateHeaderName(name[, label])
  • name <string>
  • label <string> Метка для сообщения об ошибке. По умолчанию: Имя заголовка.

Выполняет низкоуровневые проверки предоставленного name, которые выполняются при вызове res.setHeader(name, value).

Передача недопустимого значения в качестве name приведет к возникновению TypeError, идентифицируемой code: 'ERR_INVALID_HTTP_TOKEN'.

Нет необходимости использовать этот метод перед передачей заголовков в HTTP-запрос или ответ. Модуль HTTP автоматически проверит такие заголовки. Примеры:

Пример:

1
2
3
4
5
6
7
8
9
const { validateHeaderName } = require('node:http');

try {
    validateHeaderName('');
} catch (err) {
    console.error(err instanceof TypeError); // --> true
    console.error(err.code); // --> 'ERR_INVALID_HTTP_TOKEN'
    console.error(err.message); // --> 'Имя заголовка должно быть действительным HTTP-токеном [""]'
}

http.validateHeaderValue

1
http.validateHeaderValue(name, value);

Выполняет низкоуровневые проверки предоставленного значения, которые выполняются при вызове res.setHeader(name, value).

Передача недопустимого значения в качестве value приведет к возникновению TypeError.

  • Ошибка неопределенного значения идентифицируется code: 'ERR_HTTP_INVALID_HEADER_VALUE'.
  • Ошибка недопустимого символа значения идентифицируется кодом: 'ERR_INVALID_CHAR'.

Нет необходимости использовать этот метод перед передачей заголовков в HTTP-запрос или ответ. Модуль HTTP автоматически проверит такие заголовки.

Примеры:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
const { validateHeaderValue } = require('node:http');

try {
    validateHeaderValue('x-my-header', undefined);
} catch (err) {
    console.error(err instanceof TypeError); // --> true
    console.error(
        err.code === 'ERR_HTTP_INVALID_HEADER_VALUE'
    ); // --> true
    console.error(err.message); // --> 'Недопустимое значение "undefined" для заголовка "x-my-header"'
}

try {
    validateHeaderValue('x-my-header', 'oʊmɪɡə');
} catch (err) {
    console.error(err instanceof TypeError); // --> true
    console.error(err.code === 'ERR_INVALID_CHAR'); // --> true
    console.error(err.message); // --> 'Недопустимый символ в содержимом заголовка ["x-my-header"]'
}

http.setMaxIdleHTTPParsers

1
http.setMaxIdleHTTPParsers(max);
  • max <number> По умолчанию: 1000.

Устанавливает максимальное количество неработающих парсеров HTTP.

Комментарии