Spec-Zone.ru › Deno 2

http

Чтобы использовать HTTP-сервер и клиент, необходимо импортировать модуль node:http.

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

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

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

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

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

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

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

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

Использование в Deno

import * as mod from "node:http";

класс Agent

наследует EventEmitter

Использование в Deno

import { Agent } from "node:http";

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

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

Когда клиент или сервер закрывает соединение, оно удаляется из пула. Сокеты в пуле, которые не используются, будут переведены в режим unref, чтобы процесс 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
});

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

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

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

Конструкторы

Agent(opts?: AgentOptions)
новый

Свойства

freeSockets: ReadOnlyDict<Socket[]>
только для чтения

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

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

maxFreeSockets: number

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

maxSockets: number

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

maxTotalSockets: number

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

requests: ReadOnlyDict<IncomingMessage[]>
только для чтения

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

sockets: ReadOnlyDict<Socket[]>
только для чтения

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

Методы

destroy(): void

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

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

класс ClientRequest

наследует OutgoingMessage

Использование в Deno

import { ClientRequest } from "node:http";
Совместимость с Deno

Параметр конструктора createConnection не поддерживается.

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

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

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

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

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

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

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

Конструкторы

ClientRequest(
url:
string
| URL
| ClientRequestArgs
,
cb?: (res: IncomingMessage) => void,
)
новый

Свойства

aborted: boolean
устарело

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

host: string

Хост запроса.

maxHeadersCount: number

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

method: string

Метод запроса.

path: string

Путь запроса.

protocol: string

Протокол запроса.

reusedSocket: boolean

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

import http from 'node: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

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

import http from 'node: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 &#x26;&#x26; err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();

Методы

abort(): void
устарело

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

addListener(
event: "abort",
listener: () => void,
): this
устарело
addListener(
event: "connect",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
addListener(
event: "continue",
listener: () => void,
): this
addListener(
event: "information",
listener: (info: InformationEvent) => void,
): this
addListener(
event: "response",
listener: (response: IncomingMessage) => void,
): this
addListener(
event: "socket",
listener: (socket: Socket) => void,
): this
addListener(
event: "timeout",
listener: () => void,
): this
addListener(
event: "upgrade",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
addListener(
event: "close",
listener: () => void,
): this
addListener(
event: "drain",
listener: () => void,
): this
addListener(
event: "error",
listener: (err: Error) => void,
): this
addListener(
event: "finish",
listener: () => void,
): this
addListener(
event: "pipe",
listener: (src: stream.Readable) => void,
): this
addListener(
event: "unpipe",
listener: (src: stream.Readable) => void,
): this
addListener(
event: string | symbol,
listener: (...args: any[]) => void,
): this
getRawHeaderNames(): string[]

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

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

const headerNames = request.getRawHeaderNames();
// headerNames === ['Foo', 'Set-Cookie']
on(
event: "abort",
listener: () => void,
): this
устарело
on(
event: "connect",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
on(
event: "continue",
listener: () => void,
): this
on(
event: "information",
listener: (info: InformationEvent) => void,
): this
on(
event: "response",
listener: (response: IncomingMessage) => void,
): this
on(
event: "socket",
listener: (socket: Socket) => void,
): this
on(
event: "timeout",
listener: () => void,
): this
on(
event: "upgrade",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
on(
event: "close",
listener: () => void,
): this
on(
event: "drain",
listener: () => void,
): this
on(
event: "error",
listener: (err: Error) => void,
): this
on(
event: "finish",
listener: () => void,
): this
on(
event: "pipe",
listener: (src: stream.Readable) => void,
): this
on(
event: "unpipe",
listener: (src: stream.Readable) => void,
): this
on(
event: string | symbol,
listener: (...args: any[]) => void,
): this
onSocket(socket: Socket): void
once(
event: "abort",
listener: () => void,
): this
устарело
once(
event: "connect",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
once(
event: "continue",
listener: () => void,
): this
once(
event: "information",
listener: (info: InformationEvent) => void,
): this
once(
event: "response",
listener: (response: IncomingMessage) => void,
): this
once(
event: "socket",
listener: (socket: Socket) => void,
): this
once(
event: "timeout",
listener: () => void,
): this
once(
event: "upgrade",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
once(
event: "close",
listener: () => void,
): this
once(
event: "drain",
listener: () => void,
): this
once(
event: "error",
listener: (err: Error) => void,
): this
once(
event: "finish",
listener: () => void,
): this
once(
event: "pipe",
listener: (src: stream.Readable) => void,
): this
once(
event: "unpipe",
listener: (src: stream.Readable) => void,
): this
once(
event: string | symbol,
listener: (...args: any[]) => void,
): this
prependListener(
event: "abort",
listener: () => void,
): this
устарело
prependListener(
event: "connect",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
prependListener(
event: "continue",
listener: () => void,
): this
prependListener(
event: "information",
listener: (info: InformationEvent) => void,
): this
prependListener(
event: "response",
listener: (response: IncomingMessage) => void,
): this
prependListener(
event: "socket",
listener: (socket: Socket) => void,
): this
prependListener(
event: "timeout",
listener: () => void,
): this
prependListener(
event: "upgrade",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
prependListener(
event: "close",
listener: () => void,
): this
prependListener(
event: "drain",
listener: () => void,
): this
prependListener(
event: "error",
listener: (err: Error) => void,
): this
prependListener(
event: "finish",
listener: () => void,
): this
prependListener(
event: "pipe",
listener: (src: stream.Readable) => void,
): this
prependListener(
event: "unpipe",
listener: (src: stream.Readable) => void,
): this
prependListener(
event: string | symbol,
listener: (...args: any[]) => void,
): this
prependOnceListener(
event: "abort",
listener: () => void,
): this
устарело
prependOnceListener(
event: "connect",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
prependOnceListener(
event: "continue",
listener: () => void,
): this
prependOnceListener(
event: "information",
listener: (info: InformationEvent) => void,
): this
prependOnceListener(
event: "response",
listener: (response: IncomingMessage) => void,
): this
prependOnceListener(
event: "socket",
listener: (socket: Socket) => void,
): this
prependOnceListener(
event: "timeout",
listener: () => void,
): this
prependOnceListener(
event: "upgrade",
listener: (
response: IncomingMessage,
socket: Socket,
head: Buffer,
) => void,
): this
prependOnceListener(
event: "close",
listener: () => void,
): this
prependOnceListener(
event: "drain",
listener: () => void,
): this
prependOnceListener(
event: "error",
listener: (err: Error) => void,
): this
prependOnceListener(
event: "finish",
listener: () => void,
): this
prependOnceListener(
event: "pipe",
listener: (src: stream.Readable) => void,
): this
prependOnceListener(
event: "unpipe",
listener: (src: stream.Readable) => void,
): this
prependOnceListener(
event: string | symbol,
listener: (...args: any[]) => void,
): this
setNoDelay(noDelay?: boolean): void

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

setSocketKeepAlive(
enable?: boolean,
initialDelay?: number,
): void

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

setTimeout(
timeout: number,
callback?: () => void,
): this

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

класс IncomingMessage

наследует stream.Readable

Использование в Deno

import { IncomingMessage } from "node:http";

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

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

Конструкторы

IncomingMessage(socket: Socket)
новый

Свойства

aborted: boolean
устарело

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

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');
  });
});
connection: Socket
устарело

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

headers: IncomingHttpHeaders

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

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

// 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 отбрасываются. Чтобы разрешить объединение повторяющихся значений перечисленных выше заголовков, используйте параметр joinDuplicateHeaders в request и createServer. Дополнительные сведения см. в разделе 5.3 RFC 9110.
  • set-cookie всегда является массивом. Дубликаты добавляются в массив.
  • Для повторяющихся заголовков cookie значения объединяются с помощью ; .
  • Для всех остальных заголовков значения объединяются с помощью , .
headersDistinct: Dict<string[]>

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

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

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

Кроме того, message.httpVersionMajor — это первое целое число, а message.httpVersionMinor — второе.

httpVersionMajor: number
httpVersionMinor: number
method: string | undefined
необязательное

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

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

rawHeaders: string[]

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

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

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

// 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);
rawTrailers: string[]

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

socket: Socket

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

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

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

statusCode: number | undefined
необязательное

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

Трехзначный код состояния HTTP-ответа. Например, 404.

statusMessage: string | undefined
необязательное

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

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

trailers: Dict<string>

Объект завершающих заголовков запроса/ответа. Заполняется только при событии 'end'.

trailersDistinct: Dict<string[]>

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

url: string | undefined
необязательное

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

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

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

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

new URL(`http://${process.env.HOST ?? 'localhost'}${request.url}`);

Если request.url имеет значение '/status?name=ryan', а process.env.HOST не задано:

$ node
> new URL(`http://${process.env.HOST ?? 'localhost'}${request.url}`);
URL {
  href: 'http://localhost/status?name=ryan',
  origin: 'http://localhost',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'localhost',
  hostname: 'localhost',
  port: '',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
}

Обязательно задайте process.env.HOST как имя хоста сервера или полностью замените эту часть. При использовании req.headers.host убедитесь, что выполняется надлежащая проверка, поскольку клиенты могут указать собственный заголовок Host.

Методы

destroy(error?: Error): this

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

setTimeout(
msecs: number,
callback?: () => void,
): this

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

класс OutgoingMessage

наследует stream.Writable

Использование в Deno

import { OutgoingMessage } from "node:http";

Этот класс является родительским для ClientRequest и ServerResponse. С точки зрения участников HTTP-транзакции он представляет собой абстрактное исходящее сообщение.

Конструкторы

OutgoingMessage()
новый

Параметры типа

Request extends IncomingMessage = IncomingMessage

Свойства

chunkedEncoding: boolean
connection: Socket | null
устарело
только для чтения

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

finished: boolean
устарело
headersSent: boolean
только для чтения

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

req: Request
только для чтения
sendDate: boolean
shouldKeepAlive: boolean
socket: Socket | null
только для чтения

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

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

useChunkedEncodingByDefault: boolean

Методы

addTrailers(headers: OutgoingHttpHeaders | ReadonlyArray<[string, string]>): void

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

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

Для отправки завершающих заголовков HTTP требует наличия заголовка Trailer со списком имен полей заголовков в его значении, например:

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

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

appendHeader(
name: string,
value: string | readonly string[],
): this

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

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

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

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

flushHeaders(): void

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

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

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

getHeader(name: string):
number
| string
| string[]
| undefined

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

getHeaderNames(): string[]

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

getHeaders(): OutgoingHttpHeaders

Возвращает поверхностную копию текущих исходящих заголовков. Поскольку используется поверхностная копия, значения массивов можно изменять без дополнительных вызовов методов модуля 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'] }
hasHeader(name: string): boolean

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

const hasContentType = outgoingMessage.hasHeader('content-type');
removeHeader(name: string): void

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

outgoingMessage.removeHeader('Content-Encoding');
setHeader(
name: string,
value:
number
| string
| readonly string[]
,
): this

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

setHeaders(headers: Headers | Map<string,
number
| string
| readonly string[]
>): this

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

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

или

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

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

// Returns 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');
});
setTimeout(
msecs: number,
callback?: () => void,
): this

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

класс Server

наследует NetServer

Использование в Deno

import { Server } from "node:http";

Конструкторы

Server(requestListener?: RequestListener<Request, Response>)
new
Server(
options: ServerOptions<Request, Response>,
requestListener?: RequestListener<Request, Response>,
)
new

Параметры типа

Request extends IncomingMessage = IncomingMessage
Response extends ServerResponse = ServerResponse

Свойства

headersTimeout: number

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

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

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

keepAliveTimeout: number

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

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

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

maxHeadersCount: number | null

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

maxRequestsPerSocket: number | null

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

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

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

requestTimeout: number

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

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

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

timeout: number

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

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

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

Методы

addListener(
event: string,
listener: (...args: any[]) => void,
): this
addListener(
event: "close",
listener: () => void,
): this
addListener(
event: "connection",
listener: (socket: Socket) => void,
): this
addListener(
event: "error",
listener: (err: Error) => void,
): this
addListener(
event: "listening",
listener: () => void,
): this
addListener(
event: "checkContinue",
listener: RequestListener<Request, Response>,
): this
addListener(
event: "checkExpectation",
listener: RequestListener<Request, Response>,
): this
addListener(
event: "clientError",
listener: (
err: Error,
socket: stream.Duplex,
) => void,
): this
addListener(
event: "connect",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
) => void,
): this
addListener(
event: "dropRequest",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
) => void,
): this
addListener(
event: "request",
listener: RequestListener<Request, Response>,
): this
addListener(
event: "upgrade",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
) => void,
): this
closeAllConnections(): void

Закрывает все соединения с этим сервером.

closeIdleConnections(): void

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

emit(
event: string,
...args: any[],
): boolean
emit(event: "close"): boolean
emit(
event: "connection",
socket: Socket,
): boolean
emit(
event: "error",
err: Error,
): boolean
emit(event: "listening"): boolean
emit(
event: "checkContinue",
req: InstanceType<Request>,
res: InstanceType<Response> & { req: InstanceType<Request>; },
): boolean
emit(
event: "checkExpectation",
req: InstanceType<Request>,
res: InstanceType<Response> & { req: InstanceType<Request>; },
): boolean
emit(
event: "clientError",
err: Error,
socket: stream.Duplex,
): boolean
emit(
event: "connect",
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
): boolean
emit(
event: "dropRequest",
req: InstanceType<Request>,
socket: stream.Duplex,
): boolean
emit(
event: "request",
req: InstanceType<Request>,
res: InstanceType<Response> & { req: InstanceType<Request>; },
): boolean
emit(
event: "upgrade",
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
): boolean
on(
event: string,
listener: (...args: any[]) => void,
): this
on(
event: "close",
listener: () => void,
): this
on(
event: "connection",
listener: (socket: Socket) => void,
): this
on(
event: "error",
listener: (err: Error) => void,
): this
on(
event: "listening",
listener: () => void,
): this
on(
event: "checkContinue",
listener: RequestListener<Request, Response>,
): this
on(
event: "checkExpectation",
listener: RequestListener<Request, Response>,
): this
on(
event: "clientError",
listener: (
err: Error,
socket: stream.Duplex,
) => void,
): this
on(
event: "connect",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
) => void,
): this
on(
event: "dropRequest",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
) => void,
): this
on(
event: "request",
listener: RequestListener<Request, Response>,
): this
on(
event: "upgrade",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
) => void,
): this
once(
event: string,
listener: (...args: any[]) => void,
): this
once(
event: "close",
listener: () => void,
): this
once(
event: "connection",
listener: (socket: Socket) => void,
): this
once(
event: "error",
listener: (err: Error) => void,
): this
once(
event: "listening",
listener: () => void,
): this
once(
event: "checkContinue",
listener: RequestListener<Request, Response>,
): this
once(
event: "checkExpectation",
listener: RequestListener<Request, Response>,
): this
once(
event: "clientError",
listener: (
err: Error,
socket: stream.Duplex,
) => void,
): this
once(
event: "connect",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
) => void,
): this
once(
event: "dropRequest",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
) => void,
): this
once(
event: "request",
listener: RequestListener<Request, Response>,
): this
once(
event: "upgrade",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
) => void,
): this
prependListener(
event: string,
listener: (...args: any[]) => void,
): this
prependListener(
event: "close",
listener: () => void,
): this
prependListener(
event: "connection",
listener: (socket: Socket) => void,
): this
prependListener(
event: "error",
listener: (err: Error) => void,
): this
prependListener(
event: "listening",
listener: () => void,
): this
prependListener(
event: "checkContinue",
listener: RequestListener<Request, Response>,
): this
prependListener(
event: "checkExpectation",
listener: RequestListener<Request, Response>,
): this
prependListener(
event: "clientError",
listener: (
err: Error,
socket: stream.Duplex,
) => void,
): this
prependListener(
event: "connect",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
) => void,
): this
prependListener(
event: "dropRequest",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
) => void,
): this
prependListener(
event: "request",
listener: RequestListener<Request, Response>,
): this
prependListener(
event: "upgrade",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
) => void,
): this
prependOnceListener(
event: string,
listener: (...args: any[]) => void,
): this
prependOnceListener(
event: "close",
listener: () => void,
): this
prependOnceListener(
event: "connection",
listener: (socket: Socket) => void,
): this
prependOnceListener(
event: "error",
listener: (err: Error) => void,
): this
prependOnceListener(
event: "listening",
listener: () => void,
): this
prependOnceListener(
event: "checkContinue",
listener: RequestListener<Request, Response>,
): this
prependOnceListener(
event: "checkExpectation",
listener: RequestListener<Request, Response>,
): this
prependOnceListener(
event: "clientError",
listener: (
err: Error,
socket: stream.Duplex,
) => void,
): this
prependOnceListener(
event: "connect",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
) => void,
): this
prependOnceListener(
event: "dropRequest",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
) => void,
): this
prependOnceListener(
event: "request",
listener: RequestListener<Request, Response>,
): this
prependOnceListener(
event: "upgrade",
listener: (
req: InstanceType<Request>,
socket: stream.Duplex,
head: Buffer,
) => void,
): this
setTimeout(
msecs?: number,
callback?: (socket: Socket) => void,
): this

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

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

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

setTimeout(callback: (socket: Socket) => void): this

класс ServerResponse

наследует OutgoingMessage<Request>

Использование в Deno

import { ServerResponse } from "node:http";

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

Конструкторы

ServerResponse(req: Request)
new

Параметры типа

Request extends IncomingMessage = IncomingMessage

Свойства

statusCode: number

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

response.statusCode = 404;

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

statusMessage: string

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

response.statusMessage = 'Not found';

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

strictContentLength: boolean

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

Методы

assignSocket(socket: Socket): void
detachSocket(socket: Socket): void
writeContinue(callback?: () => void): void

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

writeEarlyHints(
hints: Record<string, string | string[]>,
callback?: () => void,
): void

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

Пример

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 for diagnostics',
});

const earlyHintsCallback = () => console.log('early hints message sent');
response.writeEarlyHints({
  'link': earlyHintsLinks,
}, earlyHintsCallback);
writeHead(
statusCode: number,
statusMessage?: string,
headers?: OutgoingHttpHeaders | OutgoingHttpHeader[],
): this

Отправляет заголовок ответа на запрос. Код состояния — это трёхзначный код состояния 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 и длина переданного тела.

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

writeHead(
statusCode: number,
headers?: OutgoingHttpHeaders | OutgoingHttpHeader[],
): this
writeProcessing(): void

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

функция createServer

Использование в Deno

import { createServer } from "node:http";

Перегрузка 1

createServer<
Request extends IncomingMessage = IncomingMessage,
Response extends ServerResponse = ServerResponse,
>(requestListener?: RequestListener<Request, Response>): Server<Request, Response>

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

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

import http from 'node: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);

import http from 'node: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);

Параметры типа

Request extends IncomingMessage = IncomingMessage
Response extends ServerResponse = ServerResponse

Параметры

requestListener: RequestListener<Request, Response>
необязательный

Тип возвращаемого значения

Server<Request, Response>

Перегрузка 2

createServer<
Request extends IncomingMessage = IncomingMessage,
Response extends ServerResponse = ServerResponse,
>(
options: ServerOptions<Request, Response>,
requestListener?: RequestListener<Request, Response>,
): Server<Request, Response>

Параметры типа

Request extends IncomingMessage = IncomingMessage
Response extends ServerResponse = ServerResponse

Параметры

options: ServerOptions<Request, Response>
requestListener: RequestListener<Request, Response>
необязательный

Тип возвращаемого значения

Server<Request, Response>

функция get

Использование в Deno

import { get } from "node:http";

Перегрузка 1

get(
options:
RequestOptions
| string
| URL
,
callback?: (res: IncomingMessage) => void,
): ClientRequest
Совместимость с Deno

Параметр конструктора createConnection не поддерживается.

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

Функция callback вызывается с одним аргументом — экземпляром 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);

Параметры

options:
RequestOptions
| string
| URL

Принимает те же options, что и request; по умолчанию в качестве метода устанавливается GET.

callback: (res: IncomingMessage) => void
необязательный

Возвращаемый тип

ClientRequest

Перегрузка 2

get(
url: string | URL,
options: RequestOptions,
callback?: (res: IncomingMessage) => void,
): ClientRequest
Совместимость с Deno

Параметр конструктора createConnection не поддерживается.

Параметры

url: string | URL
options: RequestOptions
callback: (res: IncomingMessage) => void
необязательный

Возвращаемый тип

ClientRequest

функция request

Использование в Deno

import { request } from "node:http";

Перегрузка 1

request(
options:
RequestOptions
| string
| URL
,
callback?: (res: IncomingMessage) => void,
): ClientRequest
Совместимость с Deno

Параметр конструктора createConnection не поддерживается.

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

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

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

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

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

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

import http from 'node:http';
import { Buffer } from 'node:buffer';

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'. Дополнительные сведения см. в разделе 8.2.3 RFC 2616.
  • Отправка заголовка 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
  • 'close'
  • 'error' на объекте res с ошибкой, сообщение которой — 'Error: aborted', а код — 'ECONNRESET'
  • 'close' на объекте res

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

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

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

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

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

  • 'socket'
  • 'response'
    • 'data' любое количество раз на объекте res
  • (здесь вызывается req.destroy())
  • 'aborted' на объекте res
  • 'close'
  • 'error' на объекте res с ошибкой, сообщение которой — 'Error: aborted', а код — 'ECONNRESET', либо с ошибкой, с которой был вызван req.destroy()
  • '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() для запроса. В частности, событие 'error' будет сгенерировано с ошибкой, сообщение которой — 'AbortError: The operation was aborted', код — 'ABORT_ERR', а также с cause, если оно было указано.

Параметры

options:
RequestOptions
| string
| URL
callback: (res: IncomingMessage) => void
необязательный

Возвращаемый тип

ClientRequest

Перегрузка 2

request(
url: string | URL,
options: RequestOptions,
callback?: (res: IncomingMessage) => void,
): ClientRequest
Совместимость с Deno

Параметр конструктора createConnection не поддерживается.

Параметры

url: string | URL
options: RequestOptions
callback: (res: IncomingMessage) => void
необязательный

Возвращаемый тип

ClientRequest

функция setMaxIdleHTTPParsers

Использование в Deno

import { setMaxIdleHTTPParsers } from "node:http";
setMaxIdleHTTPParsers(max: number): void

Устанавливает максимальное количество неактивных HTTP-парсеров.

Параметры

max: number = 1000
необязательный

Возвращаемый тип

void

функция validateHeaderName

Использование в Deno

import { validateHeaderName } from "node:http";
validateHeaderName(name: string): void

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

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

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

Пример:

import { validateHeaderName } from 'node:http';

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

Параметры

name: string

Возвращаемый тип

void

функция validateHeaderValue

Использование в Deno

import { validateHeaderValue } from "node:http";
validateHeaderValue(
name: string,
value: string,
): void

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

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

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

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

Примеры:

import { validateHeaderValue } from '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); // --> 'Invalid value "undefined" for header "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); // --> 'Invalid character in header content ["x-my-header"]'
}

Параметры

name: string

Имя заголовка

value: string

Значение заголовка

Возвращаемый тип

void

интерфейс AgentOptions

расширяет Partial<TcpSocketConnectOpts>

Использование в Deno

import { type AgentOptions } from "node:http";

Свойства

keepAlive: boolean | undefined
необязательный

Сохраняет сокеты в пуле для использования другими запросами в будущем. Значение по умолчанию = false

keepAliveMsecs: number | undefined
необязательный

При использовании HTTP KeepAlive задаёт частоту отправки пакетов TCP KeepAlive через поддерживаемые открытыми сокеты. Значение по умолчанию = 1000. Актуально только при значении keepAlive true.

maxSockets: number | undefined
необязательный

Максимальное количество сокетов для одного хоста. Значение по умолчанию для Node 0.10 — 5, для Node 0.12 — Infinity

maxTotalSockets: number | undefined
необязательный

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

maxFreeSockets: number | undefined
необязательный

Максимальное количество сокетов, которые могут оставаться открытыми в свободном состоянии. Актуально только при значении keepAlive true. Значение по умолчанию = 256.

timeout: number | undefined
необязательный

Тайм-аут сокета в миллисекундах. Тайм-аут устанавливается после подключения сокета.

scheduling:
"fifo"
| "lifo"
| undefined
необязательный

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

интерфейс ClientRequestArgs

Использование в Deno

import { type ClientRequestArgs } from "node:http";
Совместимость с Deno

Параметр createConnection не поддерживается.

Свойства

_defaultAgent: Agent | undefined
необязательное
agent:
Agent
| boolean
| undefined
необязательное
auth:
string
| null
| undefined
необязательное
createConnection: ((
options: ClientRequestArgs,
oncreate: (
err: Error | null,
socket: stream.Duplex,
) => void,
) =>
stream.Duplex
| null
| undefined
) | undefined
необязательное
defaultPort:
number
| string
| undefined
необязательное
family: number | undefined
необязательное
headers: OutgoingHttpHeaders | undefined
необязательное
hints: LookupOptions["hints"]
необязательное
host:
string
| null
| undefined
необязательное
hostname:
string
| null
| undefined
необязательное
insecureHTTPParser: boolean | undefined
необязательное
localAddress: string | undefined
необязательное
localPort: number | undefined
необязательное
lookup: LookupFunction | undefined
необязательное
maxHeaderSize: number | undefined
необязательное
method: string | undefined
необязательное
path:
string
| null
| undefined
необязательное
port:
number
| string
| null
| undefined
необязательное
protocol:
string
| null
| undefined
необязательное
setDefaultHeaders: boolean | undefined
необязательное
setHost: boolean | undefined
необязательное
signal: AbortSignal | undefined
необязательное
socketPath: string | undefined
необязательное
timeout: number | undefined
необязательное

Время ожидания в миллисекундах.

uniqueHeaders: Array<string | string[]> | undefined
необязательное
joinDuplicateHeaders: boolean
необязательное

интерфейс IncomingHttpHeaders

extends [NodeJS.Dict]<string | string[]>

Использование в Deno

import { type IncomingHttpHeaders } from "node:http";

Свойства

accept: string | undefined
необязательное
accept-language: string | undefined
необязательное
accept-patch: string | undefined
необязательное
accept-ranges: string | undefined
необязательное
access-control-allow-credentials: string | undefined
необязательное
access-control-allow-headers: string | undefined
необязательное
access-control-allow-methods: string | undefined
необязательное
access-control-allow-origin: string | undefined
необязательное
access-control-expose-headers: string | undefined
необязательное
access-control-max-age: string | undefined
необязательное
access-control-request-headers: string | undefined
необязательное
access-control-request-method: string | undefined
необязательное
age: string | undefined
необязательное
allow: string | undefined
необязательное
alt-svc: string | undefined
необязательное
authorization: string | undefined
необязательное
cache-control: string | undefined
необязательное
connection: string | undefined
необязательное
content-disposition: string | undefined
необязательное
content-encoding: string | undefined
необязательное
content-language: string | undefined
необязательное
content-length: string | undefined
необязательное
content-location: string | undefined
необязательное
content-range: string | undefined
необязательное
content-type: string | undefined
необязательное
cookie: string | undefined
необязательное
date: string | undefined
необязательное
etag: string | undefined
необязательное
expect: string | undefined
необязательное
expires: string | undefined
необязательное
forwarded: string | undefined
необязательное
from: string | undefined
необязательное
host: string | undefined
необязательное
if-match: string | undefined
необязательное
if-modified-since: string | undefined
необязательное
if-none-match: string | undefined
необязательное
if-unmodified-since: string | undefined
необязательное
last-modified: string | undefined
необязательное
location: string | undefined
необязательное
origin: string | undefined
необязательное
pragma: string | undefined
необязательное
proxy-authenticate: string | undefined
необязательное
proxy-authorization: string | undefined
необязательное
public-key-pins: string | undefined
необязательное
range: string | undefined
необязательное
referer: string | undefined
необязательное
retry-after: string | undefined
необязательное
sec-websocket-accept: string | undefined
необязательное
sec-websocket-extensions: string | undefined
необязательное
sec-websocket-key: string | undefined
необязательное
sec-websocket-protocol: string | undefined
необязательное
sec-websocket-version: string | undefined
необязательное
set-cookie: string[] | undefined
необязательное
strict-transport-security: string | undefined
необязательное
tk: string | undefined
необязательное
trailer: string | undefined
необязательное
transfer-encoding: string | undefined
необязательное
upgrade: string | undefined
необязательное
user-agent: string | undefined
необязательное
vary: string | undefined
необязательное
via: string | undefined
необязательное
warning: string | undefined
необязательное
www-authenticate: string | undefined
необязательное

интерфейс InformationEvent

Использование в Deno

import { type InformationEvent } from "node:http";

Свойства

statusCode: number
statusMessage: string
httpVersion: string
httpVersionMajor: number
httpVersionMinor: number
headers: IncomingHttpHeaders
rawHeaders: string[]

интерфейс OutgoingHttpHeaders

наследует [NodeJS.Dict]<OutgoingHttpHeader>

Использование в Deno

import { type OutgoingHttpHeaders } from "node:http";

Свойства

accept:
string
| string[]
| undefined
необязательное
accept-charset:
string
| string[]
| undefined
необязательное
accept-encoding:
string
| string[]
| undefined
необязательное
accept-language:
string
| string[]
| undefined
необязательное
accept-ranges: string | undefined
необязательное
access-control-allow-credentials: string | undefined
необязательное
access-control-allow-headers: string | undefined
необязательное
access-control-allow-methods: string | undefined
необязательное
access-control-allow-origin: string | undefined
необязательное
access-control-expose-headers: string | undefined
необязательное
access-control-max-age: string | undefined
необязательное
access-control-request-headers: string | undefined
необязательное
access-control-request-method: string | undefined
необязательное
age: string | undefined
необязательное
allow: string | undefined
необязательное
authorization: string | undefined
необязательное
cache-control: string | undefined
необязательное
cdn-cache-control: string | undefined
необязательное
connection:
string
| string[]
| undefined
необязательное
content-disposition: string | undefined
необязательное
content-encoding: string | undefined
необязательное
content-language: string | undefined
необязательное
content-length:
string
| number
| undefined
необязательное
content-location: string | undefined
необязательное
content-range: string | undefined
необязательное
content-security-policy: string | undefined
необязательное
content-security-policy-report-only: string | undefined
необязательное
content-type: string | undefined
необязательное
cookie:
string
| string[]
| undefined
необязательное
dav:
string
| string[]
| undefined
необязательное
dnt: string | undefined
необязательное
date: string | undefined
необязательное
etag: string | undefined
необязательное
expect: string | undefined
необязательное
expires: string | undefined
необязательное
forwarded: string | undefined
необязательное
from: string | undefined
необязательное
host: string | undefined
необязательное
if-match: string | undefined
необязательное
if-modified-since: string | undefined
необязательное
if-none-match: string | undefined
необязательное
if-range: string | undefined
необязательное
if-unmodified-since: string | undefined
необязательное
last-modified: string | undefined
необязательное
link:
string
| string[]
| undefined
необязательное
location: string | undefined
необязательное
max-forwards: string | undefined
необязательное
origin: string | undefined
необязательное
pragma:
string
| string[]
| undefined
необязательное
proxy-authenticate:
string
| string[]
| undefined
необязательное
proxy-authorization: string | undefined
необязательное
public-key-pins: string | undefined
необязательное
public-key-pins-report-only: string | undefined
необязательное
range: string | undefined
необязательное
referer: string | undefined
необязательное
referrer-policy: string | undefined
необязательное
refresh: string | undefined необязательное
retry-after: string | undefined
необязательное
sec-websocket-accept: string | undefined
необязательное
sec-websocket-extensions:
string
| string[]
| undefined
необязательное
sec-websocket-key: string | undefined
необязательное
sec-websocket-protocol:
string
| string[]
| undefined
необязательное
sec-websocket-version: string | undefined
необязательное
server: string | undefined
необязательное
set-cookie:
string
| string[]
| undefined
необязательное
strict-transport-security: string | undefined
необязательное
te: string | undefined
необязательное
trailer: string | undefined
необязательное
transfer-encoding: string | undefined
необязательное
user-agent: string | undefined
необязательное
upgrade: string | undefined
необязательное
upgrade-insecure-requests: string | undefined
необязательное
vary: string | undefined
необязательное
via:
string
| string[]
| undefined
необязательное
warning: string | undefined
необязательное
www-authenticate:
string
| string[]
| undefined
необязательное
x-content-type-options: string | undefined
необязательное
x-dns-prefetch-control: string | undefined
необязательное
x-frame-options: string | undefined
необязательное
x-xss-protection: string | undefined
необязательное

интерфейс RequestOptions

наследует ClientRequestArgs

Использование в Deno

import { type RequestOptions } from "node:http";
Совместимость с Deno

Параметр createConnection не поддерживается.

интерфейс ServerOptions

Использование в Deno

import { type ServerOptions } from "node:http";

Параметры типа

Request extends IncomingMessage = IncomingMessage
Response extends ServerResponse = ServerResponse

Свойства

IncomingMessage: Request | undefined
необязательное

Указывает класс IncomingMessage, который следует использовать. Полезно для расширения исходного IncomingMessage.

ServerResponse: Response | undefined
необязательное

Указывает класс ServerResponse, который следует использовать. Полезно для расширения исходного ServerResponse.

requestTimeout: number | undefined
необязательное

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

joinDuplicateHeaders: boolean
необязательное

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

keepAliveTimeout: number | undefined
необязательное

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

connectionsCheckingInterval: number | undefined
необязательное

Задает интервал в миллисекундах для проверки времени ожидания запроса и заголовков в незавершенных запросах.

highWaterMark: number | undefined
необязательное

Необязательно переопределяет sockets' readableHighWaterMark и writableHighWaterMark. Это влияет на свойство highWaterMark как у IncomingMessage, так и у ServerResponse. Значение по умолчанию: @see stream.getDefaultHighWaterMark().

insecureHTTPParser: boolean | undefined
необязательное

Использует небезопасный HTTP-парсер, который принимает некорректные HTTP-заголовки, когда true. Следует избегать использования небезопасного парсера. Дополнительные сведения см. в описании --insecure-http-parser.

maxHeaderSize: number | undefined
необязательное

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

noDelay: boolean | undefined
необязательное

Если установлено значение true, отключает алгоритм Нейгла сразу после установки нового входящего соединения.

keepAlive: boolean | undefined
необязательное

Если установлено значение true, включает функцию keep-alive для сокета сразу после установки нового входящего соединения, аналогично тому, как это выполняется в socket.setKeepAlive([enable][, initialDelay]).

keepAliveInitialDelay: number | undefined
необязательное

Если задано положительное число, устанавливает начальную задержку перед отправкой первого keepalive-зонда по простаивающему сокету.

uniqueHeaders: Array<string | string[]> | undefined
необязательное

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

псевдоним типа OutgoingHttpHeader

Использование в Deno

import { type OutgoingHttpHeader } from "node:http";

Определение

number
| string
| string[]

псевдоним типа RequestListener

Использование в Deno

import { type RequestListener } from "node:http";

Параметры типа

Request extends IncomingMessage = IncomingMessage
Response extends ServerResponse = ServerResponse

Определение

(
req: InstanceType<Request>,
res: InstanceType<Response> & { req: InstanceType<Request>; },
) => void

переменная CloseEvent

Использование в Deno

import { CloseEvent } from "node:http";

Тип

import("undici-types").CloseEvent

переменная globalAgent

Использование в Deno

import { globalAgent } from "node:http";

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

Тип

Agent

переменная maxHeaderSize

Использование в Deno

import { maxHeaderSize } from "node:http";

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

Тип

number

переменная MessageEvent

Использование в Deno

import { MessageEvent } from "node:http";

Тип

import("undici-types").MessageEvent

переменная METHODS

Использование в Deno

import { METHODS } from "node:http";

Тип

string[]

переменная STATUS_CODES

Использование в Deno

import { STATUS_CODES } from "node:http";

Сигнатуры индекса

[errorCode: number]: string | undefined
[errorCode: string]: string | undefined

переменная WebSocket

Использование в Deno

import { WebSocket } from "node:http";

Реализация WebSocket, совместимая с браузерами.

Тип

import("undici-types").WebSocket

© 2018–2025 the Deno authors
Licensed under the MIT License.
https://docs.deno.com/api/node/http

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API