Класс: http.Agent

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

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

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

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

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

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

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

agent:false:

http.get({
  hostname: 'localhost',
  port: 80,
  path: '/',
  agent: false  // Create a new agent just for this one request
}, (res) => {
  // Do stuff with response
});

new Agent([options])

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

Параметры socket.connect() также поддерживаются.

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

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

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

agent.createConnection(options[, callback])

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

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

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

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

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

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

agent.keepSocketAlive(socket)

• socket <stream.Duplex>

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

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

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

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

agent.reuseSocket(socket, request)

• socket <stream.Duplex>
• request <http.ClientRequest>

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

socket.ref();

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

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

agent.destroy()

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

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

agent.freeSockets

• <Объект>

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

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

agent.getName(options)

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

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

agent.maxFreeSockets

• <число>

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

agent.maxSockets

• <число>

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

agent.maxTotalSockets

• <число>

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

agent.requests

• <Объект>

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

agent.sockets

• <Объект>

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

Класс: http.ClientRequest

• Расширяет: <Stream>

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

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

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

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

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

Node.js не проверяет, равны ли длина заголовка Content-Length и длина переданного тела.

Событие: 'abort'

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

Событие: 'connect'

• response <http.IncomingMessage>
• socket <stream.Duplex>
• head <Buffer>

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

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

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

const http = require('http');
const net = require('net');
const { URL } = require('url');

// Create an HTTP tunneling proxy
const proxy = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, 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'. Это инструкция, что клиент должен отправить тело запроса.

Событие: 'information'

• info <Объект>
  • httpVersion <строка>
  • httpVersionMajor <целое число>
  • httpVersionMinor <целое число>
  • statusCode <целое число>
  • statusMessage <строка>
  • headers <Объект>
  • rawHeaders <массив строк>

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

const http = require('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, прослушивайте событие 'upgrade' вместо этого.

Событие: 'response'

• response <http.IncomingMessage>

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

Событие: 'socket'

• socket <stream.Duplex>

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

Событие: 'timeout'

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

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

Событие: 'upgrade'

• response <http.IncomingMessage>
• socket <stream.Duplex>
• head <Buffer>

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

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

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

const http = require('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()

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

request.aborted

• <логическое значение>

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

request.connection

• <stream.Duplex>

См. request.socket.

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

• data <строка> | <Buffer>
• encoding <строка>
• callback <Функция>
• Возвращает: <this>

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

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

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

request.destroy([error])

• error <Ошибка> Необязательно, ошибка, которую нужно сгенерировать с событием 'error'.
• Возвращает: <this>

Уничтожить запрос. Необязательно сгенерировать событие 'error', и сгенерировать событие 'close'. Вызов этого приведет к удалению оставшихся данных в ответе и уничтожению сокета.

См. writable.destroy() для получения дополнительной информации.

request.destroyed

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

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

См. writable.destroyed для получения дополнительной информации.

request.finished

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

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

request.flushHeaders()

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

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

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

request.getHeader(name)

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

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

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' is 'text/html'
const contentLength = request.getHeader('Content-Length');
// 'contentLength' is of type number
const cookie = request.getHeader('Cookie');
// 'cookie' is of type string[]

request.getRawHeaderNames()

• Возвращает: <массив строк>

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

request.setHeader('Foo', 'bar');
request.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

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

request.maxHeadersCount

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

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

request.path

• <строка> Путь запроса.

request.method

• <строка> Метод запроса.

request.host

• <строка> Хост запроса.

request.protocol

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

request.removeHeader(name)

• name <строка>

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

request.removeHeader('Content-Type');

request.reusedSocket

• <логическое> Используется ли повторно сокет для запроса.

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

const http = require('http');

// Server has a 5 seconds keep-alive timeout by default
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // Adapting a keep-alive agent
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // Do nothing
    });
  });
}, 5000); // Sending request on 5s interval so it's easy to hit idle timeout

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

const http = require('http');
const agent = new http.Agent({ keepAlive: true });

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, (res) => {
      // ...
    })
    .on('error', (err) => {
      // Check if retry is needed
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();

request.setHeader(name, value)

• name <строка>
• value <любое>

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

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

или

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

request.setNoDelay([noDelay])

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

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

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

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

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

request.setTimeout(timeout[, callback])

• timeout <число> Миллисекунды до истечения таймаута запроса.
• callback <Функция> Необязательная функция, которая вызывается при истечении таймаута. Аналогично привязке к событию 'timeout'.
• Возвращает: <http.ClientRequest>

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

request.socket

• <stream.Duplex>

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

const http = require('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(`Your IP address is ${ip} and your source port is ${port}.`);
  // Consume response object
});

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

request.writableEnded

• <boolean>

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

request.writableFinished

• <boolean>

Является true , если все данные были сброшены в системный буфер непосредственно перед вызовом события 'finish'.

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

• chunk <string> | <Buffer>
• encoding <string>
• callback <Function>
• Возвращает: <boolean>

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

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

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

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

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

Класс: http.Server

• Расширяет: <net.Server>

Событие: 'checkContinue'

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

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

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

При вызове и обработке этого события событие 'request' не будет вызвано.

Событие: 'checkExpectation'

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

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

При вызове и обработке этого события событие 'request' не будет вызвано.

Событие: 'clientError'

• exception <Ошибка>
• 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. Если сокет недоступен для записи или уже передал данные, он немедленно уничтожается.

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

const http = require('http');

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

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

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

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

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

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

Событие: 'request'

• request <http.IncomingMessage>
• response <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([callback])

• callback <Функция>

Прекращает приём новых соединений сервером. См. net.Server.close().

server.headersTimeout

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

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

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

server.listen()

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

server.listening

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

server.maxHeadersCount

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

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

server.requestTimeout

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

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

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

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

server.setTimeout([msecs][, callback])

• msecs <number> По умолчанию: 0 (нет таймаута)
• callback <Функция>
• Возвращает: <http.Сервер>

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

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

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

server.maxRequestsPerSocket

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

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

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

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

server.timeout

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

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

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

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

server.keepAliveTimeout

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

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

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

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

Класс: http.ServerResponse

• Расширяет: <Stream>

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

Событие: 'close'

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

Событие: 'finish'

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

response.addTrailers(headers)

• headers <Объект>

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

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

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

response.writeHead(200, { 'Content-Type': 'text/plain',
                          'Trailer': 'Content-MD5' });
response.write(fileData);
response.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' });
response.end();

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

response.connection

• <stream.Duplex>

См. response.socket.

response.cork()

См. writable.cork().

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

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

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

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

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

response.finished

• <логическое значение>

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

response.flushHeaders()

Очищает заголовки ответа. См. также: request.flushHeaders().

response.getHeader(name)

• name <строка>
• Возвращает: <любой тип>

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

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 is 'text/html'
const contentLength = response.getHeader('Content-Length');
// contentLength is of type number
const setCookie = response.getHeader('set-cookie');
// setCookie is of type string[]

response.getHeaderNames()

• Возвращает: <массив строк>

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

response.setHeader('Foo', 'bar');
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

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

response.getHeaders()

• Возвращает: <объект>

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

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

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(name)

• name <строка>
• Возвращает: <логическое значение>

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

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

response.headersSent

• <логическое значение>

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

response.removeHeader(name)

• name <строка>

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

response.removeHeader('Content-Encoding');

response.req

• <http.IncomingMessage>

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

response.sendDate

• <логическое значение>

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

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

response.setHeader(name, value)

• name <строка>
• value <любой тип>
• Возвращает: <http.ServerResponse>

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

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

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

или

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

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

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

// Returns content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
});

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

response.setTimeout(msecs[, callback])

• msecs <число>
• callback <Функция>
• Возвращает: <http.ServerResponse>

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

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

response.socket

• <stream.Duplex>

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

const http = require('http');
const server = http.createServer((req, res) => {
  const ip = res.socket.remoteAddress;
  const port = res.socket.remotePort;
  res.end(`Your IP address is ${ip} and your source port is ${port}.`);
}).listen(3000);

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

response.statusCode

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

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

response.statusCode = 404;

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

response.statusMessage

• <строка>

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

response.statusMessage = 'Not found';

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

response.uncork()

См. writable.uncork().

response.writableEnded

• <логическое значение>

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

response.writableFinished

• <логическое значение>

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

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

• chunk <строка> | <Buffer>
• encoding <строка> По умолчанию: 'utf8'
• callback <Функция>
• Возвращает: <логическое значение>

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

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

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

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

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

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

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

response.writeContinue()

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

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

• statusCode <число>
• statusMessage <строка>
• headers <Объект> | <Массив>
• Возвращает: <http.ServerResponse>

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

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

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

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() вместо этого.

// Returns content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
});

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

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

response.writeProcessing()

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

Класс: http.IncomingMessage

• Расширяет: <stream.Readable>

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

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

Событие: 'aborted'

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

Событие: 'close'

Указывает, что основное соединение было закрыто.

message.aborted

• <boolean>

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

message.complete

• <boolean>

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

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

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

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

message.destroy([error])

• error <Error>
• Возвращает: <this>

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

message.headers

• <Object>

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

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

// Prints something like:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers);

Дубликаты в исходных заголовках обрабатываются следующим образом, в зависимости от имени заголовка:

• Дубликаты age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer, retry-after, server, или user-agent отбрасываются.
• set-cookie всегда является массивом. Дубликаты добавляются в массив.
• Для дублирующих заголовков cookie значения объединяются с помощью '; '.
• Для всех остальных заголовков значения объединяются с помощью ', '.

message.httpVersion

• <строка>

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

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

message.method

• <строка>

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

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

message.rawHeaders

• <строковый массив>

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

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

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

// Prints something like:
//
// [ 'user-agent',
//   'this is invalid because there can be only one',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders);

message.rawTrailers

• <строковый массив>

Исходные ключи и значения трейлеров запроса/ответа точно так, как они были получены. Заполняется только при событии 'end'.

message.setTimeout(msecs[, callback])

• msecs <число>
• callback <Функция>
• Возвращает: <http.IncomingMessage>

Вызывает 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.url

• <строка>

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

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

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

Для разбора URL на составляющие:

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

Когда request.url равно '/status?name=ryan' и request.headers.host равно 'localhost:3000':

$ 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(headers)

• headers <Объект>

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

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

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

message.writeHead(200, { 'Content-Type': 'text/plain',
                         'Trailer': 'Content-MD5' });
message.write(fileData);
message.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' });
message.end();

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

outgoingMessage.connection

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

outgoingMessage.cork()

См. writable.cork().

outgoingMessage.destroy([error])

• error <Ошибка> Необязательно, ошибка, которую необходимо вывести вместе с событием error
• Возвращает: <this>

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

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

• chunk <строка> | <Буфер>
• encoding <строка> Необязательно, По умолчанию: utf8
• callback <Функция> Необязательно
• Возвращает: <this>

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

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

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

outgoingMessage.flushHeaders()

Принудительно отправляет заголовки сообщения.

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

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

outgoingMessage.getHeader(name)

• name <строка> Название заголовка
• Возвращает <строка> | <неопределено>

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

outgoingMessage.getHeaderNames()

• Возвращает <массив строк>

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

outgoingMessage.getHeaders()

• Возвращает: <Объект>

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

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

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(name)

• name <строка>
• Возвращает <логическое значение>

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

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

outgoingMessage.headersSent

• <логическое значение>

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

outgoingMessage.pipe()

Переопределяет метод pipe устаревшего Stream, который является родительским классом для http.outgoingMessage

Так как OutgoingMessage должен быть потоком только для записи, вызов этой функции приведет к выбросу Error. Таким образом, метод pipe, унаследованный от Stream, отключен.

Пользователю не следует вызывать эту функцию напрямую.

outgoingMessage.removeHeader()

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

outgoingMessage.removeHeader('Content-Encoding');

outgoingMessage.setHeader(name, value)

• name <строка> Имя заголовка
• value <строка> Значение заголовка
• Возвращает: <this>

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

outgoingMessage.setTimeout(msesc[, callback])

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

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

outgoingMessage.socket

• <stream.Duplex>

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

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

outgoingMessage.uncork()

См. writable.uncork()

outgoingMessage.writableCorked

• <number>

Это outgoingMessage.writableCorked вернёт время, сколько раз outgoingMessage.cork() было вызвано.

outgoingMessage.writableEnded

• <boolean>

Только для чтения, true если outgoingMessage.end() было вызвано. Обратите внимание, что это свойство не отражает, был ли данные сброшены. Для этой цели используйте message.writableFinished.

outgoingMessage.writableFinished

• <boolean>

Только для чтения. true если все данные были сброшены в базовую систему.

outgoingMessage.writableHighWaterMark

• <number>

Это outgoingMessage.writableHighWaterMark будет highWaterMark базового сокета, если сокет существует. В противном случае, это будет значение по умолчанию highWaterMark.

highWaterMark — максимальный объём данных, который может быть потенциально буферизован сокетом.

outgoingMessage.writableLength

• <number>

Только для чтения. Это outgoingMessage.writableLength содержит количество байтов (или объектов) в буфере, готовых к отправке.

outgoingMessage.writableObjectMode

• <boolean>

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

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

• chunk <string> | <Buffer>
• encoding <string> По умолчанию: utf8
• callback <Function>
• Возвращает <boolean>

Если этот метод вызван, а заголовок не отправлен, он вызовет this._implicitHeader для сброса неявного заголовка. Если сообщение не должно иметь тела (указано this._hasBody), вызов игнорируется и chunk не будет отправлен. Это может быть полезно при обработке конкретного сообщения, которое не должно включать тело. Например, ответ на запрос HEAD, 204 и 304 ответы.

chunk может быть строкой или буфером. Когда chunk является строкой, параметр encoding указывает, как закодировать chunk в поток байтов. callback будет вызвано, когда chunk сбрасывается.

Если сообщение передаётся в кодировке с чанками (указано this.chunkedEncoding), chunk будет сброшен как один чанк среди потока чанков. В противном случае он будет сброшен как тело сообщения.

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

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

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

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

http.METHODS

• <string[]>

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

http.STATUS_CODES

• <Object>

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

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

• options <Object>

  • IncomingMessage <http.IncomingMessage> Указывает класс IncomingMessage для использования. Полезно для расширения исходного IncomingMessage. По умолчанию: IncomingMessage.
  • ServerResponse <http.ServerResponse> Указывает класс ServerResponse для использования. Полезно для расширения исходного ServerResponse. По умолчанию: ServerResponse.
  • insecureHTTPParser <boolean> Используйте небезопасный HTTP-парсер, который принимает недопустимые HTTP-заголовки, когда true. Использование небезопасного парсера следует избегать. См. --insecure-http-parser для получения дополнительной информации. По умолчанию: false
  • maxHeaderSize <number> Дополнительно переопределяет значение --max-http-header-size для запросов, полученных этим сервером, т. е. максимальную длину заголовков запроса в байтах. По умолчанию: 16384 (16 КБ).

• requestListener <Function>

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

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

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

const http = require('http');

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

const http = require('http');

// Create a local server to receive data from
const server = http.createServer();

// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!'
  }));
});

server.listen(8000);

http.get(options[, callback])

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.

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

Пример получения данных JSON:

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

• <number>

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

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

http.request(options[, callback])

http.request(url[, options][, callback])

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

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

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

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

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

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

const http = require('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:

const options = new URL('http://abc:xyz@example.com');

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 с ошибкой с сообщением 'Error: aborted' и кодом '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(name)

• name <строка>

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

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

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

Пример:

const { validateHeaderName } = require('http');

try {
  validateHeaderName('');
} catch (err) {
  err instanceof TypeError; // --> true
  err.code; // --> 'ERR_INVALID_HTTP_TOKEN'
  err.message; // --> 'Header name must be a valid HTTP token [""]'
}

http.validateHeaderValue(name, value)

• name <строка>
• value <любое>

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

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

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

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

Примеры:

const { validateHeaderValue } = require('http');

try {
  validateHeaderValue('x-my-header', undefined);
} catch (err) {
  err instanceof TypeError; // --> true
  err.code === 'ERR_HTTP_INVALID_HEADER_VALUE'; // --> true
  err.message; // --> 'Invalid value "undefined" for header "x-my-header"'
}

try {
  validateHeaderValue('x-my-header', 'oʊmɪɡə');
} catch (err) {
  err instanceof TypeError; // --> true
  err.code === 'ERR_INVALID_CHAR'; // --> true
  err.message; // --> 'Invalid character in header content ["x-my-header"]'
}