Навигация

HTTP-клиенты в Node.js

Сервис редко работает в одиночку: он ходит в базу, платёжный шлюз, сервис уведомлений и чужие API. Каждый такой вызов — это соединение, дедлайн, возможный повтор и обработка ошибки, и именно на них приходится заметная часть p99 и инцидентов. Разберём, как устроены HTTP-клиенты Node.js, чем fetch отличается от http.request и какие настройки превращают исходящий запрос из «просто await» в предсказуемую операцию.

Содержание

  1. Почему исходящий запрос — часть архитектуры
  2. Три уровня API: fetch, undici и http.request
  3. Ответ не равен ошибке
  4. Соединения и keep-alive
  5. Пул соединений и лимиты
  6. Таймауты на каждом уровне
  7. Отмена запроса
  8. Стриминг ответа и размер тела
  9. Ретраи и идемпотентность
  10. Клиент как модуль: конфигурация и наблюдаемость
  11. Отличия от браузерного fetch
  12. Частые ошибки
  13. Эксперименты
  14. Ключевые тезисы для интервью
  15. Заключение
  16. Полезные ссылки

Почему исходящий запрос — часть архитектуры

Исходящий запрос выглядит как одна строка await fetch(url), но за ней стоят четыре независимых решения:

  • соединение — новое или переиспользованное, сколько их всего и кому они принадлежат;
  • время — сколько ждать установки соединения, заголовков и тела по отдельности и сколько на всё вместе;
  • повтор — какие сбои считать временными и безопасно ли выполнить запрос ещё раз;
  • данные — читать ответ целиком в память или потоком, и какого размера ответ допустим.

Пропущенное решение не исчезает, а превращается в поведение по умолчанию. Клиент без таймаута ждёт бесконечно и держит соединение из пула. Клиент без проверки статуса принимает страницу ошибки прокси за JSON. Клиент с ретраями на всё подряд усиливает сбой внешнего сервиса. Поэтому HTTP-клиент в сервисе — такой же конфигурируемый модуль, как пул базы данных, а не набор вызовов в бизнес-логике.


Три уровня API: fetch, undici и http.request

В Node есть три уровня абстракции, и выбирать между ними стоит осознанно.

УровеньAPIЧто даётЧего не делает
Высокийfetch (undici)web-стандарт, редиректы, распаковка, web streamsне проверяет статус, не хранит куки, не даёт прямого доступа к сокету
Среднийundici.requestNode-стрим, таймауты клиента, меньше слоёвне следует редиректам, не парсит тело
Низкийnode:http, node:httpsагент, сокет, заголовки, полный контрольвсё вручную: редиректы, gzip, JSON

Глобальный fetch появился в Node 18 и внутри работает на undici — HTTP/1.1-клиенте, который Node использует и для собственных нужд. Снаружи это знакомый web API:

const res = await fetch('https://api.example.com/users/42', { signal });

if (!res.ok) throw new Error(`HTTP ${res.status}`);

const user = await res.json();

Средний уровень — undici.request: те же соединения и агенты, но ответ приходит Node-стримом, а редиректы и разбор тела остаются на вызывающем.

import { request } from 'undici';

const { statusCode, headers, body } = await request(
  'https://api.example.com/report.csv',
  { method: 'GET' },
);

for await (const chunk of body) {
  // чанк приходит по мере чтения, без буферизации всего файла
}

Низкий уровень — node:https. Здесь нет ни распаковки, ни следования редиректам, ни JSON-хелперов, но есть прямой доступ к агенту и сокету:

import { request } from 'node:https';

const req = request('https://api.example.com/users/42', (res) => {
  res.setEncoding('utf8');
  res.on('data', (chunk) => { /* ... */ });
  res.on('end', () => { /* ... */ });
});

req.on('timeout', () => req.destroy(new Error('ETIMEDOUT')));
req.end();

Практическое правило: fetch — по умолчанию, http.request — когда нужен контроль, которого fetch не даёт. Например, для прокси с mTLS, нестандартного агента, чтения трейлеров или очень горячего пути, где лишние слои абстракции мешают. Для обычного вызова внешнего API возможностей fetch и настроенного диспетчера достаточно.

Отдельно стоит помнить, что fetch в Node — это HTTP/1.1. Мультиплексирования HTTP/2 у него нет: для h2 нужен node:http2 или специализированный клиент. Для большинства сервисов это не проблема, но при разговоре с h2-only шлюзом выбор уже другой.


Ответ не равен ошибке

Главная ловушка fetch — он не бросает исключение на HTTP-ошибку. Ответ 500 — такой же успешно полученный Response, как и 200; отличается только res.ok и res.status.

const res = await fetch(url, { signal });

if (!res.ok) {
  const text = await res.text(); // тело ошибки может быть HTML от прокси
  throw new HttpError(res.status, text.slice(0, 500));
}

const data = await res.json();

Отсюда два следствия. Во-первых, проверка статуса должна быть в одном месте — в модуле клиента, а не в каждом обработчике. Во-вторых, тело ошибки нужно читать защищённо: внешний сервис может вернуть HTML, пустую строку или гигантский stack trace, и res.json() на нём упадёт с SyntaxError, замаскировав исходную проблему.

Что вообще может пойти не так:

СитуацияКак выглядитЧто делать
DNS, TCP, TLS, обрывTypeError: fetch failed, причина в err.causeретрай по коду или алерт
Таймаут или отменаTimeoutError / AbortErrorразличать уход клиента и дедлайн
HTTP 4xxres.ok === false, статус конкретныйбизнес-ошибка, обычно без ретрая
HTTP 5xxres.ok === falseретрай только для идемпотентных вызовов
Невалидный JSONSyntaxError при res.json()ошибка контракта, алерт

У fetch есть и полезные умолчания: редиректы он проходит сам (до 20), content-encoding распаковывает, accept-encoding добавляет. redirect: 'manual' в Node возвращает настоящий 3xx с заголовком location, а не «непрозрачный» ответ, как в браузере.

Ещё одна деталь: у ответов 204, 304 и HEAD тела нет. res.body === null, а res.json() на таком ответе бросит исключение — проверяйте статус и метод до разбора.


Соединения и keep-alive

Новое HTTPS-соединение — это DNS-запрос, TCP-рукопожатие и TLS-рукопожатие. На локальной сети это единицы миллисекунд, до удалённого дата-центра — десятки, а при плохом DNS или проблемах с TLS — сотни. Keep-alive позволяет отправить следующий запрос по уже открытому соединению и заплатить за рукопожатие один раз.

Работает это на двух сторонах:

  • клиент помечает соединение как переиспользуемое (в HTTP/1.1 это Connection: keep-alive, умолчание) и держит его в пуле;
  • сервер не закрывает соединение сразу после ответа, а ждёт следующий запрос в пределах keepAliveTimeout.

В Node 19+ глобальный агент http уже включает keep-alive, а fetch/undici держит пул соединений на каждый origin сам. Но у этой схемы есть классическая ловушка — гонка таймаутов. Если сервер или балансировщик закрывает idle-соединение через 60 секунд, а клиент считает его живым пять минут, очередной запрос уйдёт в уже закрытый сокет и упадёт с ECONNRESET. Поэтому клиентский idle-таймаут должен быть меньше серверного:

import { Agent } from 'undici';

const agent = new Agent({
  keepAliveTimeout: 30_000, // меньше idle-таймаута сервера и балансировщика
});

На серверной стороне обратное правило: если вы поднимаете server.keepAliveTimeout, поднимите и headersTimeout, иначе Node закроет соединение раньше, чем клиент дошлёт заголовки.

server.keepAliveTimeout = 65_000;  // больше, чем idle-таймаут nginx
server.headersTimeout = 66_000;    // должен быть больше keepAliveTimeout

ECONNRESET на переиспользованном соединении не всегда означает, что запрос дошёл до сервиса: он мог умереть на этапе отправки. Для идемпотентных методов такой сбой безопасно повторить, для POST — только с ключом идемпотентности.

Ещё один скрытый расход: DNS. Node не кеширует результаты dns.lookup, а каждое новое соединение снова обращается к резолверу через пул libuv. Пока соединения переиспользуются, это незаметно; при высокой частоте новых соединений DNS становится узким местом и конкурирует за те же четыре потока пула, что и файловые операции.


Пул соединений и лимиты

Пул решает две задачи: не открывать бесконечно много сокетов и переиспользовать уже открытые. Размер пула — это лимит одновременных запросов к конкретному origin, а не лимит нагрузки вообще.

Для fetch пул задаётся через undici.Agent:

import { Agent } from 'undici';

const agent = new Agent({
  connections: 16,          // одновременных соединений на origin
  connectTimeout: 3_000,    // установка соединения
  headersTimeout: 10_000,   // ожидание заголовков ответа
  bodyTimeout: 30_000,      // пауза между чанками тела
  keepAliveTimeout: 30_000, // сколько держать idle-соединение
});

undici — обычная зависимость (npm i undici), хотя внутри Node уже есть его копия. Агент передают либо явно в запрос, либо глобально:

// точечно: только для этого клиента
const res = await fetch(url, { dispatcher: agent, signal });

// глобально: для всех fetch в процессе
import { setGlobalDispatcher } from 'undici';
setGlobalDispatcher(agent);

Опция dispatcher — расширение undici, которого нет в браузерном fetch. Глобальная установка действует на весь процесс, включая сторонние библиотеки, поэтому в сервисе с разными внешними API чаще настраивают отдельный агент на каждого зависимого сервиса.

Для node:http аналог — http.Agent:

import { Agent } from 'node:http';

const agent = new Agent({
  keepAlive: true,
  maxSockets: 16,      // соединений на origin
  maxFreeSockets: 8,   // сколько idle держать
  timeout: 30_000,     // socket timeout
});

Три правила, которые спасают от неожиданностей:

  1. Лимит пула — не rate limit. Запросы сверх лимита не отбрасываются, а стоят в очереди внутри агента. При неограниченной очереди они копятся в памяти и приходят с уже истёкшим дедлайном.
  2. Пулы не общие между origin. Десять соединений к платежному шлюзу не мешают десяти к базе, но и не помогают: у каждого хоста свой пул.
  3. Лимит должен быть согласован с внешним сервисом. Если API разрешает 20 rps, а пул держит 16 соединений, ограничение всё равно задаёт дедлайн, а не агент.

Для HTTP/2 пул соединений выглядит иначе: одно соединение мультиплексирует много запросов, поэтому connections — это уже не число одновременных запросов. Встроенный fetch h2 не умеет, и это ещё один аргумент не считать его универсальным клиентом для любых протоколов.


Таймауты на каждом уровне

Бесконечное ожидание — не «надёжность», а способ исчерпать пул и память. Но одного общего таймаута мало: зависнуть можно на разных этапах, и диагностировать их нужно отдельно.

Что ограничиваемfetchundici.Agenthttp.request
Установка соединенияsignalconnectTimeouttimeout (после назначения сокета)
Ожидание заголовковsignalheadersTimeoutsocket timeout
Тело ответаsignalbodyTimeoutsocket timeout
Общий дедлайнAbortSignal.timeout(ms)сигналсигнал или ручной таймер

У fetch собственной опции timeout нет — таймаут делают сигналом:

const res = await fetch(url, {
  signal: AbortSignal.timeout(5_000),
});

Важная деталь: таймер AbortSignal.timeout стартует в момент создания сигнала. Если создать его в конфиге или на старте функции, а запрос начать позже, дедлайн съестся подготовкой. Если сигнал создан один раз на несколько попыток, вторая попытка получит уже сработавший сигнал. Поэтому сигнал создают прямо перед конкретной попыткой.

Второй нюанс — что именно обрывает сигнал. AbortSignal.timeout отменяет и установку соединения, и чтение тела: тело большого ответа тоже перестанет читаться. headersTimeout в undici ограничивает только ожидание заголовков, а bodyTimeout — паузу между чанками, а не общую длительность передачи.

Для http.request таймаут — это таймаут неактивности сокета, а не общий дедлайн:

const req = request(url, { timeout: 5_000 }, (res) => { /* ... */ });

req.on('timeout', () => {
  req.destroy(new Error('ETIMEDOUT')); // без destroy запрос продолжит висеть
});

Событие timeout само по себе ничего не прерывает: если его не обработать, запрос может висеть дальше. И помните, что таймаут на попытку — не то же самое, что дедлайн на всю операцию: три попытки по пять секунд плюс backoff легко выходят за дедлайн клиента.

Дедлайн принято пробрасывать сверху вниз. Если входящий запрос имеет бюджет 8 секунд, внешние вызовы должны получать не «свои» 30 секунд, а остаток бюджета:

const deadlineAt = performance.now() + 8_000;

async function callWithBudget(url) {
  const remaining = deadlineAt - performance.now();
  if (remaining <= 0) throw new Error('deadline exceeded');

  return fetch(url, { signal: AbortSignal.timeout(remaining) });
}

Отмена запроса

Отмена нужна в трёх случаях: клиент ушёл, работа потеряла смысл из-за ошибки соседней операции, истёк общий дедлайн. Во всех случаях используется один механизм — AbortController и его AbortSignal.

const controller = new AbortController();

res.on('close', () => {
  if (!res.writableEnded) controller.abort(); // клиент ушёл, ответ ещё не отправлен
});

const signal = AbortSignal.any([
  controller.signal,
  AbortSignal.timeout(5_000),
]);

try {
  const upstream = await fetch(url, { signal });
  res.json(await upstream.json());
} catch (err) {
  if (err.name === 'AbortError') return; // отмена клиентом — не ошибка сервиса
  throw err;                             // TimeoutError и сетевые сбои — инцидент
}

AbortSignal.any объединяет несколько сигналов: срабатывает первый. Это стандартный способ совместить «клиент ушёл» и «дедлайн истёк», не заводя два вложенных try/catch.

Проверять только err.name === 'AbortError' недостаточно. Если отменить контроллер с причиной (controller.abort(new Error('client disconnected'))), fetch отклонится этой причиной, а не AbortError. Надёжнее смотреть на signal.aborted и signal.reason:

catch (err) {
  if (signal.aborted) {
    // это отмена, а не сбой внешнего сервиса
  }
}

http.request тоже принимает signal в опциях и обрывает запрос при отмене; без сигнала для этого используют req.destroy(). Сигнал удобнее тем, что связывает HTTP-вызов с остальной цепочкой отмены, но в обоих случаях соединение рвётся, а не возвращается в пул.

Отмена не откатывает уже сделанное: если запрос дошёл до внешнего сервиса и тот успел списать деньги, отмена лишь прекратит ожидание ответа. Поэтому операции с побочными эффектами должны быть идемпотентными независимо от отмены.


Стриминг ответа и размер тела

res.json() и res.arrayBuffer() читают ответ целиком в память. Для небольшого JSON это нормально; для выгрузки, архива или файла на сотни мегабайт — прямой путь к OOM. Арифметика простая: 100 МБ ответа × 50 одновременных запросов = 5 ГБ, которые никто не планировал.

fetch возвращает res.body как web ReadableStream. В Node его можно перебирать for await или превратить в Node-стрим:

import { createWriteStream } from 'node:fs';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

const res = await fetch(fileUrl, { signal });
if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);

await pipeline(
  Readable.fromWeb(res.body),
  createWriteStream('report.zip'),
);

pipeline обеспечивает backpressure: если диск пишет медленнее сети, чтение ответа притормозится, и память не вырастет. Подробнее об этом — в статье «Стримы и backpressure».

Для ответов, которые должны помещаться в память, лимит ставят вручную: content-length можно подделать или не указывать вовсе (chunked), поэтому считать байты нужно по факту:

async function readLimited(res, maxBytes) {
  let total = 0;
  const chunks = [];

  for await (const chunk of res.body) {
    total += chunk.byteLength;
    if (total > maxBytes) {
      await res.body.cancel(); // не дочитываем и освобождаем соединение
      throw new Error('response too large');
    }
    chunks.push(chunk);
  }

  return Buffer.concat(chunks);
}

Отдельная ловушка — не дочитать тело. Если вернуть управление, не вызвав res.json(), res.text() или res.body.cancel(), соединение останется занятым и не вернётся в пул. При потоке таких запросов процесс упирается в сокеты, хотя внешний сервис давно ответил.

Тело запроса тоже можно стримить, но у fetch для этого нужен флаг duplex:

import { createReadStream } from 'node:fs';
import { Readable } from 'node:stream';

await fetch(uploadUrl, {
  method: 'PUT',
  body: Readable.toWeb(createReadStream('backup.tar.gz')),
  duplex: 'half', // требование undici для потокового тела
});

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


Ретраи и идемпотентность

Повторять запрос можно не потому, что он упал, а потому, что повтор безопасен. Ключевое свойство — идемпотентность: повтор не создаёт дополнительного эффекта.

МетодИдемпотентенКомментарий
GET, HEAD, OPTIONS, TRACEдачитают, не меняют состояние
PUT, DELETEдаповтор приводит к тому же состоянию
POSTнетсоздаёт новую сущность при каждом вызове
PATCHобычно нетзависит от операции, по умолчанию не повторяют

Ретраить имеет смысл только временные сбои:

  • сетевые ошибки до получения ответа: ECONNRESET, ECONNREFUSED, ETIMEDOUT, EAI_AGAIN, UND_ERR_CONNECT_TIMEOUT, UND_ERR_HEADERS_TIMEOUT;
  • статусы 408, 425, 429, 502, 503, 504;
  • Retry-After в ответе — прямое указание, сколько ждать.

Не ретраят 400, 401, 403, 404, 409, 422, ошибки TLS и неверный сертификат: повтор не исправит ни валидацию, ни права, ни конфигурацию. 500 — спорный случай: он может быть транзиентным, но может и повторяться на каждом вызове, поэтому по умолчанию его не ретраят без явного решения.

Простейший цикл с экспоненциальной задержкой и jitter:

import { setTimeout as sleep } from 'node:timers/promises';

const RETRYABLE_CODES = new Set([
  'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EAI_AGAIN',
  'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT',
]);

const RETRYABLE_STATUS = new Set([408, 425, 429, 502, 503, 504]);

function isRetryable(err) {
  if (err.name === 'TimeoutError') return true;
  if (err.name === 'AbortError') return false;
  if (RETRYABLE_STATUS.has(err.status)) return true;

  const code = err.code ?? err.cause?.code;
  return RETRYABLE_CODES.has(code);
}

async function withRetry(makeRequest, { attempts = 3, base = 200, cap = 2_000 } = {}) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await makeRequest();
    } catch (err) {
      if (attempt >= attempts - 1 || !isRetryable(err)) throw err;

      const ceiling = Math.min(cap, base * 2 ** attempt);
      await sleep(Math.random() * ceiling); // full jitter
    }
  }
}

Два условия, без которых эта схема не работает: 5xx на границе клиента нужно превратить в HttpError со статусом, иначе isRetryable увидит только успешный Response; а TimeoutError ретраят, только если это таймаут попытки, а не исчерпанный общий дедлайн.

makeRequest — именно фабрика, а не готовый промис: каждая попытка должна создать новый запрос. Стрим-тело и FormData одноразовы, а AbortSignal.timeout продолжает тикать и может прервать уже следующую попытку.

Для POST (и любого неидемпотентного вызова) нужен ключ идемпотентности — стабильный идентификатор операции, который сервер проверяет и не выполняет работу дважды:

import { randomUUID } from 'node:crypto';

const idempotencyKey = randomUUID(); // один на всю операцию, не на попытку

const res = await fetch(url, {
  method: 'POST',
  headers: { 'idempotency-key': idempotencyKey },
  body: JSON.stringify(payload),
});

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

Ещё две детали, без которых ретраи делают хуже:

  • Перед повтором закройте тело неудачного ответа. res.body.cancel() или res.text() — иначе соединение останется занятым.
  • Ограничьте общий бюджет. Три попытки с backoff и таймаутом по пять секунд могут идти дольше, чем весь входящий запрос. Дедлайн считается на операцию, а не на попытку, и проверяется перед каждой из них.

Теория backoff, jitter и Retry-After подробно разобрана в статье «Ретраи и exponential backoff». Отдельный уровень — circuit breaker и bulkhead: они останавливают поток запросов к уже лежащему сервису, чтобы ретраи не превратились в самонанесённый DDoS. Этот механизм разбирается в статье «Таймауты, ретраи и graceful shutdown».


Клиент как модуль: конфигурация и наблюдаемость

Если fetch вызывают из десяти файлов с разными заголовками и таймаутами, поведение сервиса становится непредсказуемым. Внешний API заслуживает отдельного модуля: один агент, один базовый URL, одна политика ошибок и ретраев.

// clients/billing.js
import { Agent } from 'undici';

const agent = new Agent({
  connections: 10,
  connectTimeout: 2_000,
  headersTimeout: 5_000,
  bodyTimeout: 10_000,
  keepAliveTimeout: 30_000,
});

const BASE_URL = process.env.BILLING_URL;

export async function createCharge(order, { signal } = {}) {
  const res = await fetch(`${BASE_URL}/charges`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'idempotency-key': order.id,
    },
    body: JSON.stringify({ amount: order.amount }),
    dispatcher: agent,
    signal: AbortSignal.any(
      [signal, AbortSignal.timeout(5_000)].filter(Boolean),
    ),
  });

  if (!res.ok) throw new HttpError(res.status, await res.text());
  return res.json();
}

Такой модуль — естественное место для метрик и логов. Что стоит фиксировать на каждом исходящем вызове:

  • метод, host и путь — без query-параметров, в которых могут быть токены;
  • статус, длительность и номер попытки — по ним видно деградацию зависимости;
  • код ошибки из err.cause — fetch failed без причины бесполезен для диагностики;
  • request-id и traceparent — их нужно явно положить в исходящие заголовки: AsyncLocalStorage хранит контекст внутри процесса, но сам HTTP-заголовки не добавляет;
  • число занятых соединений и размер очереди — если in-flight растёт, а статусы ещё 200, значит зависимость тормозит.

Чего логировать не стоит: заголовки authorization и cookie, тела запросов и ответов, полные URL с секретами. Успешные вызовы можно сэмплировать, ошибки — логировать всегда.

Отдельное решение — не менять глобальный fetch. Патчи глобального диспетчера влияют на все библиотеки в процессе, включая те, о существовании которых вы забыли. Явный dispatcher в клиенте внешнего сервиса делает настройку локальной и предсказуемой.


Отличия от браузерного fetch

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

АспектБраузерNode.js
CORSпроверяется браузеромне существует: сервер вызывает любой origin
Кукиcookie-jar, credentialsне хранятся, передаются вручную заголовком
Проксисистемный или браузерныйпо умолчанию HTTP_PROXY не читается
Редиректыавтоматически, manual — opaqueавтоматически, manual — реальный 3xx
Тело ответаweb stream без Node-хелперовweb stream + for await и Readable.fromWeb
Соединениябраузер управляет пуломundici.Agent или http.Agent
HTTP/2обычно поддержанвстроенный fetch — только HTTP/1.1
keepaliveдогрузка после закрытия вкладкине управляет переиспользованием соединения

Отсюда типичные ошибки при переносе кода: ожидание, что Node-клиент «сам» добавит куки, что HTTP_PROXY подхватится из окружения, что res.body можно без преобразования отдать в Node-pipeline (нужен Readable.fromWeb), что keepalive: true включает keep-alive. И обратная: в браузере нельзя отключить проверку TLS-сертификата или подменить агент, а в Node можно — и это почти всегда плохая идея, даже если очень хочется обойти стенд.


Частые ошибки

  • Нет таймаута. Запрос висит, соединение занято, пул исчерпан, входящий клиент давно ушёл.
  • Нет проверки res.ok. Тело ошибки парсится как успешный ответ, а баг всплывает на уровне бизнес-логики.
  • res.json() без чтения текста ошибки. HTML от прокси превращается в SyntaxError, исходный статус теряется.
  • Ретрай всего подряд. POST дублируется, 401 повторяется три раза, сбой внешнего сервиса усиливается.
  • Ретрай с телом-стримом. Повтор использует уже исчерпанный поток и падает или отправляет пустое тело.
  • Ключ идемпотентности внутри попытки. Каждый повтор становится новой операцией.
  • Незакрытое тело ответа. Соединение не возвращается в пул; при потоке запросов кончаются сокеты.
  • arrayBuffer() для большого файла. Память растёт линейно от размера ответа и числа параллельных вызовов.
  • Безлимитный пул. Сотни соединений к чужому API вместо очереди и лимита.
  • Логирование err.message без err.cause. В логе остаётся fetch failed и ничего больше.
  • Глобальный патч диспетчера. Настройка для одного сервиса меняет поведение всех fetch в процессе.

Эксперименты

Три коротких запуска, которые показывают разницу между «код работает» и «код ведёт себя предсказуемо».

1. Ответ 500 — не исключение

const res = await fetch('http://localhost:3000/users');
console.log(res.status, res.ok); // 500 false
console.log(typeof res.json);    // function — тело ещё можно разобрать

// никакого throw не было: статус проверяют вручную

Если заменить сервер на res.statusCode = 200, тот же код вернёт 200 true. Разницы в обработке ошибок нет — и это главная причина, по которой проверка статуса должна быть в клиенте.

2. Keep-alive переиспользует соединение

import { createServer, Agent, request } from 'node:http';

let connections = 0;

const server = createServer((req, res) => res.end('ok'));
server.on('connection', () => connections++);

server.listen(0, async () => {
  const url = `http://127.0.0.1:${server.address().port}`;
  const agent = new Agent({ keepAlive: true, maxSockets: 1 });

  for (let i = 0; i < 3; i++) {
    await new Promise((resolve, reject) => {
      const req = request(url, { agent }, (res) => {
        res.resume();
        res.on('end', resolve);
      });
      req.on('error', reject);
      req.end();
    });
  }

  console.log(connections); // 1 — три запроса, одно TCP-соединение
  agent.destroy();
  server.close();
});

Замените agent на { agent: false } — счётчик покажет три соединения. Разница в стоимости — три DNS/TCP/TLS-рукопожатия вместо одного.

3. Таймаут обрывает ожидание

const started = performance.now();

try {
  await fetch('http://localhost:3000/slow', {
    signal: AbortSignal.timeout(100),
  });
} catch (err) {
  console.log(err.name, Math.round(performance.now() - started));
  // TimeoutError ~100
}

Если маршрут /slow отвечает через 300 мс, без сигнала запрос вернётся примерно через 300 мс, а с сигналом — через 100. Обратите внимание: таймер стартовал при создании сигнала, поэтому создавать его нужно непосредственно перед вызовом.


Ключевые тезисы для интервью

  • fetch отклоняется только при сетевом сбое и отмене; 4xx/5xx — это успешно полученный ответ, поэтому проверка res.ok — обязательная часть клиента, а не деталь обработчика.
  • Настоящая причина TypeError: fetch failed лежит в err.cause (ECONNREFUSED, ENOTFOUND, UND_ERR_*), и логировать нужно её, а не общее сообщение.
  • Keep-alive переиспользует TCP/TLS-соединение, а пул ограничивает число одновременных соединений на origin; очередь сверх лимита ждёт в памяти, поэтому пул сочетают с дедлайном, а клиентский idle-таймаут держат меньше серверного.
  • У запроса четыре независимых времени: установка соединения, заголовки, тело и общий дедлайн; fetch умеет только сигнал, undici.Agent и http.request дают раздельные таймауты, а AbortSignal.timeout стартует в момент создания.
  • Ретрай допустим только для идемпотентных операций и временных сбоев, с backoff и jitter; тело-стрим нельзя переиспользовать, а ключ идемпотентности должен быть стабильным для всех попыток.
  • Ответ читают потоком с backpressure и лимитом байт; не дочитанное тело держит соединение и не возвращается в пул.
  • Серверный fetch — не браузерный: нет CORS и cookie-jar, не читается HTTP_PROXY, manual-редирект возвращает реальный 3xx, а HTTP/2 встроенный клиент не поддерживает.

Заключение

HTTP-клиент в Node — это не выбор библиотеки, а набор решений о соединениях, времени, повторах и данных. fetch закрывает большинство задач, пока ему заданы пул, таймауты и проверка статуса; http.request нужен там, где требуется контроль над сокетом и потоком. Предсказуемость дают три вещи: дедлайн, проброшенный через всю цепочку вызовов, повтор только безопасных операций и чтение ответа с ограничением размера. Всё это стоит держать в одном модуле на каждый внешний сервис — тогда деградация зависимости видна в логах и метриках, а не выясняется по жалобам пользователей.

Полезные ссылки