Навигация

Таймауты, ретраи и graceful shutdown

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

Содержание

  1. Ошибки: операционные и программерские
  2. Таймауты на всех уровнях
  3. Дедлайн: бюджет на всю операцию
  4. Ретраи: что и когда повторять
  5. Backoff, jitter и бюджет попыток
  6. Circuit breaker
  7. Bulkhead: изоляция ресурсов
  8. Порядок в цепочке вызовов
  9. Деградация вместо отказа
  10. Graceful shutdown: сигнал и дренаж
  11. Порядок остановки и дедлайн
  12. Практика: TaskFlow
  13. Частые ошибки
  14. Ключевые тезисы для интервью
  15. Заключение
  16. Полезные ссылки

Ошибки: операционные и программерские

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

Операционные ошибки — ожидаемые состояния среды. Зависимость не ответила вовремя, база вернула deadlock detected, внешний API ответил 429, диск закончился. Это не баг кода, и сервис знает, что с этим делать: повторить, подождать, вернуть 503, отдать устаревшие данные.

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

Тип ошибкиПримерыЧто делать
Операционная временнаяETIMEDOUT, ECONNRESET, 503, 429, 40P01ретрай, breaker, деградация
Операционная постоянная401, 403, 404, 422, ошибка схемывернуть ошибку клиенту, не повторять
ПрограммерскаяTypeError, ReferenceError, нарушенный инвариантлог с контекстом, остановка процесса
НеизвестнаяuncaughtException, unhandledRejectionсчитать программерской, пока не доказано обратное

Граница проходит не по типу исключения, а по вопросу «может ли повтор дать другой результат». Ошибка валидации от внешнего API — операционная, но постоянная: повтор вернёт тот же 422. Обрыв соединения — операционная и временная. А JSON.parse упавший на ответе внешнего сервиса, — это нарушение контракта: формально операционная ошибка, но лечится она не ретраем, а алертом и разбором.

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

// src/errors.js
export class AppError extends Error {
  constructor(message, { status = 500, code = 'internal', retryable = false, cause } = {}) {
    super(message, { cause });
    this.name = 'AppError';
    this.status = status;
    this.code = code;
    this.retryable = retryable;
  }
}

export function isRetryable(err) {
  if (err.retryable === true) return true;
  if (err.name === 'AbortError') return false;       // отмена клиентом
  if (err.name === 'TimeoutError') return true;      // истёк таймаут попытки
  return ['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EAI_AGAIN'].includes(err.code)
    || ['ECONNRESET', 'UND_ERR_HEADERS_TIMEOUT'].includes(err.cause?.code);
}

Классифицировать нужно там, где ошибка впервые понятна: на границе HTTP-клиента, в адаптере базы, в middleware. Глубже по стеку обычно остаётся только throw. Почему uncaughtException не даёт права продолжать работу — разобрано в статье «Асинхронность в Node.js»: обработчик логирует контекст и запускает остановку, а рестарт делает оркестратор.


Таймауты на всех уровнях

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

Таймаутов не бывает «достаточно одного». Зависнуть можно на каждом этапе, и на каждом этапе ограничение своё:

Что ограничиваемГде настраиваетсяТипичное значение
Приём заголовковserver.headersTimeout10–30 с
Приём запроса целикомserver.requestTimeout30–60 с
Простой keep-aliveserver.keepAliveTimeout5–65 с, больше прокси
Ожидание соединения с БДconnectionTimeoutMillis2–5 с
Запрос к БДstatement_timeout, query_timeout1–5 с
Внешний HTTPconnectTimeout/headersTimeout/bodyTimeout1–3 / 5–10 / 10–30 с
Команда RediscommandTimeout, connectTimeout100–500 мс
Задача в очередитаймаут обработчика, lockDurationпо операции

Разделение важно и по смыслу. headersTimeout защищает от slowloris: клиент, присылающий заголовки по байту в минуту, иначе держал бы сокет бесконечно. requestTimeout ограничивает получение запроса целиком, но не прерывает обработчик: если код после чтения тела ушёл в бесконечный цикл, сервер об этом не узнает.

Собственного таймаута на выполнение обработчика в Node нет — его либо даёт reverse proxy, либо добавляют в приложение:

// src/middleware/handler-timeout.js
export function handlerTimeout(ms) {
  return (req, res, next) => {
    const controller = new AbortController();
    req.signal = controller.signal;

    const timer = setTimeout(() => {
      controller.abort(new Error('handler timeout'));
      if (!res.headersSent) {
        res.status(503).json({ error: 'request timeout' });
      }
    }, ms);

    timer.unref();
    res.on('close', () => {
      clearTimeout(timer);
      controller.abort(); // клиент ушёл — работа больше не нужна
    });

    next();
  };
}

Таймаут и отмена — не одно и то же. Событие timeout у http.request само по себе ничего не прерывает: без req.destroy() запрос продолжит висеть. Таймаут клиента pg отклоняет промис, но запрос на сервере базы может продолжать выполняться, а соединение останется в неопределённом состоянии — поэтому для базы предпочтителен серверный statement_timeout, который останавливает саму работу. Подробности по HTTP-клиентам — в статье «HTTP-клиенты в Node.js».


Дедлайн: бюджет на всю операцию

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

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

// src/lib/deadline.js
import { AsyncLocalStorage } from 'node:async_hooks';

const storage = new AsyncLocalStorage();
const DEFAULT_BUDGET_MS = 8_000;
const MAX_BUDGET_MS = 30_000;

export function deadlineMiddleware(req, res, next) {
  const requested = Number(req.headers['x-request-deadline-ms']);
  const budget = Number.isFinite(requested) && requested > 0
    ? Math.min(requested, MAX_BUDGET_MS) // клиент может только сократить бюджет
    : DEFAULT_BUDGET_MS;

  res.setHeader('x-request-deadline-ms', String(budget));
  storage.run({ deadlineAt: performance.now() + budget }, next);
}

export function remainingMs() {
  const store = storage.getStore();
  return store ? Math.max(0, store.deadlineAt - performance.now()) : Infinity;
}

export function currentDeadline() {
  return storage.getStore()?.deadlineAt ?? Infinity;
}

export function budgetSignal(parent) {
  const remaining = remainingMs();
  if (remaining <= 0) {
    throw Object.assign(new Error('deadline exceeded'), { code: 'DEADLINE_EXCEEDED' });
  }

  const timeout = AbortSignal.timeout(Math.max(1, Math.floor(remaining)));
  return parent ? AbortSignal.any([parent, timeout]) : timeout;
}

Несколько решений в этом коде стоит проговорить отдельно.

Наружу передаётся остаток, а не абсолютное время. Часы на разных машинах идут по-разному, и Date.now() + 5000 на другой стороне может означать что угодно. Остаток в миллисекундах не зависит от синхронизации часов. Для измерения внутри процесса берут performance.now() — монотонные часы, которые не прыгают при смене системного времени.

Заголовку клиента доверяют только в сторону уменьшения. x-request-deadline-ms: 999999 иначе стал бы способом занять все соединения сервиса на полчаса. Верхняя граница — константа конфигурации.

Дедлайн живёт в AsyncLocalStorage. Пробрасывать его параметром через десять функций нереально, а контекст запроса доступен в любой точке цепочки через await и колбэки. Как это связано с request-id и логированием — в статье «Логирование и наблюдаемость».

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

Дедлайн полезно отдавать наружу — в заголовке ответа и в логах. Тогда инцидент вида «клиент получает таймауты, а сервис отвечает за 200 мс» разбирается за минуты: видно, какой бюджет пришёл на входе.

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


Ретраи: что и когда повторять

Ретрай — самое злоупотребляемое средство надёжности. Он помогает только при совпадении трёх условий: ошибка временная, операция идемпотентная, и на повтор есть бюджет. Если хотя бы одно не выполняется, повтор делает хуже.

Подробный разбор идемпотентности и кодов ошибок — в статье «HTTP-клиенты в Node.js»; здесь важны правила уровня сервиса.

Повторять можно временные сбои: сетевые ошибки до получения ответа, 408, 425, 429, 502, 503, 504, ошибки блокировок и deadlock в базе. Не повторяют 400, 401, 403, 404, 409, 422, ошибки TLS, нарушение схемы и всё, что не изменится от второй попытки.

Повторять нужно на одном слое. Классическая ошибка — ретраи в клиенте, в gateway и в вызывающем сервисе одновременно. Три уровня по три попытки дают двадцать семь запросов к зависимости, которая уже лежит: вместо защиты получается самонанесённый DDoS. Ретрай ставят на одном слое — обычно в клиенте зависимости, — а выше по стеку ограничиваются дедлайном и breaker.

Ретрай не ставится после начала ответа. Если тело уже пошло клиенту, повтор невозможно «приклеить» к середине — получится дубль или битый ответ. Поэтому потоковые ответы не повторяют.

Общий бюджет попыток. Даже корректный ретрай на каждом слое складывается в лишнюю нагрузку. Практика крупных систем — retry budget: доля дополнительных запросов к зависимости, обычно 10–20% от основного трафика. Когда бюджет исчерпан, новые повторы не начинаются, даже если ошибка временная.

// src/lib/retry.js
import { setTimeout as sleep } from 'node:timers/promises';

export async function withRetry(fn, {
  attempts = 3,
  baseMs = 200,
  capMs = 2_000,
  deadlineAt = Infinity,
  isRetryable = () => false,
} = {}) {
  let lastError;

  for (let attempt = 0; attempt < attempts; attempt++) {
    if (performance.now() >= deadlineAt) break;

    try {
      return await fn(attempt); // каждая попытка создаёт новый запрос
    } catch (err) {
      lastError = err;
      if (!isRetryable(err)) throw err;

      const ceiling = Math.min(capMs, baseMs * 2 ** attempt);
      const delay = Math.random() * ceiling; // full jitter

      if (performance.now() + delay >= deadlineAt) break;
      await sleep(delay);
    }
  }

  throw lastError ?? Object.assign(new Error('deadline exceeded'), {
    code: 'DEADLINE_EXCEEDED',
  });
}

Две детали, без которых цикл бесполезен. fn — фабрика запроса, а не готовый промис: стрим-тело и FormData одноразовы, а сигнал с таймаутом продолжает тикать. И deadlineAt проверяется до сна, а не после: иначе последняя задержка съест остаток бюджета и попытка начнётся уже после того, как клиент ушёл.

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


Backoff, jitter и бюджет попыток

Мгновенный повтор после сбоя почти всегда бессмысленен. Зависимость не успела освободиться, соединение не восстановилось, балансировщик ещё не переключил трафик. Но главная проблема не в отдельном запросе, а в синхронности: после падения внешнего API тысячи клиентов повторяют одновременно и с одинаковой задержкой.

Арифметика простая. Зависимость держала 1 000 RPS и упала на две секунды. Если каждый клиент делает три попытки без задержки, к ней приходит 3 000 запросов в момент, когда она ещё не готова, — и она падает снова. Повтор без задержки превращает временный сбой в устойчивую перегрузку.

Экспоненциальная задержка разносит попытки во времени: base × 2^attempt, с верхней границей, чтобы десятая попытка не ждала полчаса. Jitter разводит клиентов между собой, чтобы они не синхронизировались на одинаковых интервалах.

СтратегияФормулаПоведение
Без задержки0синхронный шторм повторов
Фиксированнаяbaseпопытки не нарастают, клиенты синхронны
Экспоненциальнаяbase × 2^nнарастает, но все клиенты ждут одинаково
Full jitterrandom(0, base × 2^n)максимально разносит попытки
Equal jitterbase/2 + random(0, base/2)компромисс: есть минимальная пауза

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

Отдельно про Retry-After: если сервер явно сказал, сколько ждать, это указание сильнее любой формулы. Значение приходит либо в секундах, либо датой, и его нужно разбирать до сна, а не игнорировать.

function retryAfterMs(headers, fallbackMs) {
  const raw = headers.get('retry-after');
  if (!raw) return fallbackMs;

  const seconds = Number(raw);
  if (Number.isFinite(seconds)) return Math.min(seconds * 1_000, 60_000);

  const date = Date.parse(raw);
  return Number.isNaN(date) ? fallbackMs : Math.min(Math.max(0, date - Date.now()), 60_000);
}

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


Circuit breaker

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

Circuit breaker добавляет третье состояние между «работает» и «упал»:

СостояниеЧто происходитПереход
closedзапросы идут, failures считаютсяв open при пороге ошибок
openзапросы не отправляются, ошибка сразув half-open по истечении cooldown
half-openограниченное число пробных запросовв closed при успехе, в open при ошибке

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

// src/lib/breaker.js
export function createBreaker({ name, threshold = 5, cooldownMs = 10_000, logger }) {
  let state = 'closed';
  let failures = 0;
  let openedAt = 0;
  let probing = false;

  function allow() {
    if (state === 'closed') return true;

    if (state === 'open' && performance.now() - openedAt >= cooldownMs) {
      state = 'half-open';
      probing = false;
    }

    if (state === 'half-open' && !probing) {
      probing = true; // ровно одна пробная попытка
      return true;
    }

    return false;
  }

  return {
    get state() {
      return state;
    },

    async exec(fn) {
      if (!allow()) {
        throw Object.assign(new Error(`${name}: circuit is open`), {
          code: 'CIRCUIT_OPEN',
          retryable: false,
        });
      }

      try {
        const result = await fn();
        failures = 0;
        state = 'closed';
        return result;
      } catch (err) {
        failures++;
        if (state === 'half-open' || failures >= threshold) {
          state = 'open';
          openedAt = performance.now();
          logger.warn({ breaker: name, failures }, 'circuit opened');
        }
        throw err;
      } finally {
        probing = false;
      }
    },
  };
}

Что важно в настройке, помимо самого кода:

  • Считать нужно и таймауты, и 5xx, и сетевые ошибки. Если 4xx тоже попадает в счётчик, breaker откроется из-за невалидных запросов клиентов, а не из-за проблем зависимости.
  • Breaker на зависимость, а не на приложение. Один общий breaker закроет доступ ко всем внешним сервисам из-за одного лежащего.
  • Cooldown соразмерен восстановлению. Для быстрого сервиса это секунды, для тяжёлой базы — десятки секунд.
  • Пробных запросов должно быть мало. Пять параллельных проб в half-open — это тот же шторм, только меньше.
  • Состояние локально для инстанса. Каждый под учится сам; общую картину дают метрики circuit_state, а не синхронизация состояния между процессами.

Готовые реализации — opossum и cockatiel; своя полезна, когда нужно встроить breaker в существующий клиент и добавить специфичные правила. Но у breaker есть цена: пока он открыт, запросы не выполняются, поэтому для критичных операций нужен осмысленный fallback, а не просто 500.


Bulkhead: изоляция ресурсов

Если один медленный внешний API забирает все соединения процесса, падает не этот API, а весь сервис: листинг задач перестаёт отвечать, потому что все сокеты заняты ожиданием платёжного шлюза. Bulkhead (переборка) — это разделение ресурсов так, чтобы отказ одного потребителя не затапливал остальные.

Ресурсы, которые нужно делить:

РесурсКак изолировать
Соединения к внешнему APIотдельный undici.Agent на зависимость
Соединения к базеотдельные пулы для критичных и аналитических запросов
Одновременные вызовысемафор с лимитом и ограниченной очередью
Слоты воркеровconcurrency на очередь, пул воркеров на CPU-задачи
Пропускная способностьприоритеты и отказ от фоновой работы под нагрузкой

Лимит без границы очереди — не защита, а накопитель. Запросы сверх лимита встают в очередь, ждут своей очереди дольше дедлайна и приходят к зависимости уже бесполезными, занимая память. Поэтому у bulkhead две границы: сколько выполняется одновременно и сколько ждёт.

// src/lib/bulkhead.js
export function createBulkhead({ limit, maxQueue }) {
  let active = 0;
  const waiting = [];

  return async function acquire() {
    if (active < limit) {
      active++;
      return release;
    }

    if (waiting.length >= maxQueue) {
      throw Object.assign(new Error('bulkhead is full'), {
        status: 503,
        code: 'OVERLOADED',
        retryAfter: 1,
      });
    }

    await new Promise((resolve) => waiting.push(resolve));
    return release; // слот передан ожидающему, active не меняется
  };

  function release() {
    const next = waiting.shift();
    if (next) next();
    else active--;
  }
}

Использование выглядит так:

const billingSlots = createBulkhead({ limit: 8, maxQueue: 32 });

async function createCharge(order, { signal }) {
  const release = await billingSlots.acquire();
  try {
    return await sendCharge(order, { signal });
  } finally {
    release(); // слот освобождается и при ошибке
  }
}

Три правила, которые делают bulkhead полезным:

  1. Лимит согласован с зависимостью. Если API разрешает 20 RPS, а лимит 8 одновременных вызовов по 3 секунды, реальная пропускная способность — около 2,6 RPS. Лимит считают от целевой нагрузки, а не «на глаз».
  2. Переполнение — это 503 с Retry-After, а не ожидание. Быстрый отказ дешевле для всех: клиент может повторить позже, а сервис не копит бесполезную работу.
  3. Приоритеты важнее симметрии. Под нагрузкой сначала отключают фоновые задачи, экспорт и пересчёты, оставляя критичный путь. Это тоже bulkhead — только по типам работы, а не по зависимостям.

Отдельный приём — load shedding по глубине очереди: если очередь на запрос уже длиннее, чем бюджет времени позволяет её разобрать, новые запросы отклоняются сразу. Это защищает от каскада, когда каждый новый запрос только увеличивает задержку для всех.


Порядок в цепочке вызовов

По отдельности таймаут, breaker, bulkhead и ретрай выглядят простыми. Сложность начинается при сборке: неправильный порядок сводит их эффект к нулю или делает хуже, чем без них.

Рабочая композиция — снаружи внутрь:

дедлайн запроса
└── ретрай         только безопасные ошибки, пока есть бюджет
    └── breaker    мгновенный отказ, если зависимость лежит
        └── bulkhead   лимит одновременных вызовов и очереди
            └── таймаут попытки   остаток дедлайна
                └── вызов

Почему именно так:

  • Ретрай снаружи. Он повторяет всю защищённую операцию, включая решение breaker. Если поставить его внутрь, повтор пойдёт мимо проверки состояния.
  • Breaker перед bulkhead. Открытый breaker отвечает мгновенно и не занимает слот, который нужен другим запросам. Если поменять местами, каждый отказ сначала выстраивается в очередь за слотом.
  • Bulkhead перед таймаутом. Лимит применяется к вызову целиком, включая ожидание соединения.
  • Таймаут внутри. Каждая попытка получает собственный ограниченный срок, посчитанный от общего дедлайна, а не фиксированные «пять секунд», которые могут превысить весь бюджет.
// src/clients/billing.js
import { budgetSignal, currentDeadline } from '../lib/deadline.js';
import { createBulkhead } from '../lib/bulkhead.js';
import { createBreaker } from '../lib/breaker.js';
import { withRetry } from '../lib/retry.js';
import { isRetryable } from '../errors.js';

const slots = createBulkhead({ limit: 8, maxQueue: 32 });
const breaker = createBreaker({ name: 'billing', threshold: 5, cooldownMs: 10_000, logger });

export async function createCharge(order, { signal } = {}) {
  return withRetry(
    () => breaker.exec(async () => {
      const release = await slots.acquire();
      try {
        return await sendCharge(order, { signal: budgetSignal(signal) });
      } finally {
        release();
      }
    }),
    { attempts: 3, isRetryable, deadlineAt: currentDeadline() },
  );
}

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

Композиция — не догма. Для операций чтения иногда ставят breaker внутрь bulkhead, чтобы ограничить число одновременных проб; для фоновых задач ретрай вообще живёт в очереди, а не в коде вызова. Общее правило одно: решения о повторе и отказе должны быть в одном месте, а не размазаны по обработчикам.


Деградация вместо отказа

Не каждая зависимость должна ронять запрос. Разница между «сервис не работает» и «сервис работает хуже» — это и есть деградация, и её выбирают осознанно, а не по факту падения.

ЗависимостьПоведение при отказеМодель
Кешчитаем из базы, пусть медленнееfail-open
Рекомендации, персональные блокипустой блок или общий списокfail-open
Аналитика, аудит в реальном временипишем в очередь/лог, досылаем позжеfail-open с отложенным эффектом
Rate limitпри недоступности Redis — решаем по рискузависит от эндпоинта
Платёжный шлюз503 и понятная ошибка клиентуfail-closed
Аутентификация и проверка правотказ в доступеfail-closed

Fail-open допустим там, где отсутствие данных хуже, чем неполные данные: пустой блок рекомендаций не ломает страницу, а устаревший кеш лучше, чем пятисекундное ожидание. Fail-closed обязателен там, где цена пропуска выше цены отказа: платежи, доступ к чужим данным, проверка подписи.

Три требования к любому fallback:

  • Он явный. Ветка деградации — отдельный код с понятным поведением, а не catch {}, который возвращает null.
  • Он наблюдаем. Каждый переход в деградацию увеличивает счётчик dependency_fallback_total{dependency,reason} и пишет warn. Иначе сервис месяцами отдаёт устаревшие данные, и никто об этом не знает.
  • Он не врёт. Нельзя вернуть 200 на неудавшийся платёж или показать «сохранено», когда запись не сохранилась. Деградация — это честное «данных нет» или «попробуйте позже», а не имитация успеха.

У кеша деградация имеет отдельный нюанс: при отказе Redis не стоит идти в базу всем сразу — это thundering herd, который добьёт базу. Здесь помогают single-flight, короткий таймаут на кеш и ограничение параллелизма на перезагрузку ключа, разобранные в статье «Redis и фоновые задачи».

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


Graceful shutdown: сигнал и дренаж

Процесс останавливается не только когда падает. Деплой, автомасштабирование, переезд на другой узел — всё это SIGTERM, после которого у процесса есть ограниченное время. Если в этот момент просто выйти, клиенты получат оборванные соединения, транзакции останутся незавершёнными, а задачи воркера — наполовину выполненными.

Что происходит по сигналам:

СигналКто отправляетМожно перехватить
SIGTERMоркестратор, systemd, docker stopда
SIGINTCtrl+C в терминаледа
SIGKILLоркестратор после grace period или OOM-killerнет

SIGKILL — это не «ещё один сигнал», а принудительное завершение: никакой код не выполнится. Отсюда правило: всё, что должно случиться при остановке, должно уложиться в grace period, который задаёт оркестратор.

Дренаж — первый и самый пропускаемый шаг. Недостаточно перестать принимать соединения: балансировщик ещё какое-то время считает инстанс живым и продолжает слать трафик. Поэтому сначала readiness-проверка начинает отдавать 503 («Логирование и наблюдаемость»), затем выдерживается пауза на распространение состояния, и только потом закрывается сервер.

// src/lifecycle.js
import { setTimeout as sleep } from 'node:timers/promises';

const DRAIN_MS = 5_000;       // балансировщику нужно время убрать инстанс
const HARD_LIMIT_MS = 20_000; // меньше terminationGracePeriodSeconds

export function installShutdown({ server, app, pool, redis, worker, logger }) {
  let started = false;

  async function stop(signal) {
    if (started) {
      logger.warn({ signal }, 'second signal, exiting now');
      process.exit(1);
    }
    started = true;
    logger.info({ signal }, 'shutdown started');

    app.locals.draining = true; // readiness начнёт отдавать 503
    await sleep(DRAIN_MS);      // даём балансировщику исключить инстанс

    const closed = new Promise((resolve) => server.close(resolve));
    server.closeIdleConnections(); // простаивающий keep-alive не держит процесс

    let hardTimer;
    const forced = new Promise((resolve) => {
      hardTimer = setTimeout(() => {
        logger.warn('forcing connections closed');
        server.closeAllConnections();
        resolve();
      }, HARD_LIMIT_MS);
      hardTimer.unref(); // не держит процесс, если всё закрылось раньше
    });

    await Promise.race([closed, forced]);
    clearTimeout(hardTimer);

    await worker.close();  // новые задачи не берём, активные доигрываем
    await pool.end();      // транзакции и соединения закрываются штатно
    await redis.quit();
    await logger.flush?.();

    logger.info('shutdown complete');
    process.exit(0);
  }

  process.on('SIGTERM', () => void stop('SIGTERM'));
  process.on('SIGINT', () => void stop('SIGINT'));
}

Разберём ключевые места.

server.close() перестаёт принимать новые соединения, но не закрывает существующие. Keep-alive-сокеты живут до keepAliveTimeout, а он может быть 65 секунд — процесс будет висеть, хотя работы уже нет. closeIdleConnections() закрывает простаивающие сразу, closeAllConnections() — все, включая активные.

Ожидание ограничено. server.close() ждёт текущие запросы сколько угодно; зависший обработчик не должен держать деплой. Через HARD_LIMIT_MS соединения обрываются принудительно, и это лучше, чем SIGKILL от оркестратора без логов и без закрытия пулов.

Второй сигнал — немедленный выход. Деплой, который «висит», раздражает больше, чем оборванный запрос. Повторный SIGTERM означает «не церемонься».

Порядок важен. Воркер закрывается до пулов: активная задача ещё может сходить в базу. Redis закрывается после сервера и воркера. process.exit() вызывается последним, после flush логов, иначе последние — самые важные — записи потеряются.


Порядок остановки и дедлайн

Последовательность остановки — это не список «что закрыть», а бюджет времени, который должен сойтись с настройками оркестратора.

ШагЧто делаемЧто будет, если пропустить
1draining = true, readiness → 503трафик придёт в закрывающийся процесс
2Пауза на распространение (3–10 с)балансировщик продолжит слать запросы
3server.close() + closeIdleConnections()keep-alive держит процесс до таймаута
4Ожидание активных запросов с дедлайномзависший обработчик блокирует деплой
5closeAllConnections() по истечениипроцесс не завершится в grace period
6Остановка воркеров и консьюмеровзадача оборвётся посреди эффекта
7pool.end(), redis.quit()соединения и транзакции повиснут
8flush логов и трейсов, process.exit(0)потеряются последние записи

Бюджет считают сверху вниз. Если terminationGracePeriodSeconds равен 30 секундам, то дренаж 5 секунд, ожидание запросов 20 секунд и запас 5 секунд на закрытие ресурсов — сходится. Если поставить таймаут ожидания 30 секунд, оркестратор пришлёт SIGKILL раньше, чем код дойдёт до pool.end().

Минимальный набор полей в манифесте пода:

spec:
  terminationGracePeriodSeconds: 30
  containers:
    - name: taskflow-api
      lifecycle:
        preStop:
          exec:
            command: ["sleep", "5"] # пауза до SIGTERM, пока трафик уходит

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

Важная деталь для контейнеров: если Node запущен как PID 1 и не обрабатывает SIGTERM, действует особое правило ядра — сигнал по умолчанию игнорируется. Поэтому нужен init-процесс (tini, --init) или exec в entrypoint. Об этом — в статье «Docker и деплой Node.js».

Проверять остановку нужно тестом, а не руками: поднять сервер, отправить запрос, который отвечает через секунду, послать SIGTERM и убедиться, что клиент получил 200, а процесс завершился с кодом 0. Такой тест ловит и забытый closeIdleConnections, и порядок закрытия пулов. Основа — в статье «Тестирование Node-приложений».


Практика: TaskFlow

Добавим надёжность в TaskFlow из статей «Express и middleware», «HTTP-клиенты в Node.js» и «Redis и фоновые задачи».

1. Дедлайн на входе. Подключаем deadlineMiddleware глобально, с бюджетом 8 секунд по умолчанию и потолком 30. В лог каждого запроса пишем remainingMs на входе и на выходе — разница показывает, сколько бюджета съел сервис.

2. Матрица таймаутов в конфиге. Все значения — в схеме конфига, а не в коде:

// src/config.js
export const timeouts = {
  handlerMs: 10_000,
  dbConnectMs: 3_000,
  dbStatementMs: 4_000,
  billingConnectMs: 2_000,
  billingHeadersMs: 5_000,
  redisCommandMs: 300,
};

3. Клиент платежей по цепочке. createCharge из раздела про композицию: ретрай на 3 попытки с full jitter, breaker на 5 ошибок с cooldown 10 секунд, bulkhead на 8 слотов и очередь 32, таймаут попытки — остаток дедлайна. Ключ идемпотентности — order.id, одинаковый для всех попыток.

4. Деградация рекомендаций. Блок «похожие задачи» при отказе сервиса рекомендаций отдаёт пустой массив за 300 мс и увеличивает dependency_fallback_total. Страница продолжает работать, метрика показывает рост.

5. База под защитой. statement_timeout в пуле, отдельный пул для отчётов с лимитом 2 соединения, чтобы выгрузка не заняла все слоты. Ошибки 40P01 и 40001 помечаются как retryable, остальные — нет. Подробнее — в статье «Доступ к базам данных».

6. Остановка. installShutdown из раздела выше: SIGTERM → draining → 5 секунд паузы → server.close() → дренаж до 20 секунд → worker.close() → pool.end() → redis.quit() → flush → выход.

7. Проверка. Три сценария в CI:

  • SIGTERM под нагрузкой: ни один начатый запрос не оборван, процесс выходит за отведённое время.
  • Платежный шлюз отвечает ошибкой: breaker открывается, p99 эндпоинта падает, в логах CIRCUIT_OPEN, клиент получает 503 с Retry-After.
  • База недоступна: запросы получают 503 за время, близкое к dbConnectMs, а не висят до клиентского таймаута.

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

Что добавляют в проде: общий retry budget на зависимость, дашборд состояний breaker, алерты на рост dependency_fallback_total и на превышение дедлайна, регулярные учения с отключением зависимости на стенде.


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

  • Ретрай всего подряд. Повтор 400, 401 и ошибок валидации — бесполезные запросы и ложные алерты.
  • Ретрай неидемпотентной операции без ключа. Таймаут после успешного выполнения создаёт дубль.
  • Ретраи на нескольких слоях одновременно. Три уровня по три попытки дают двадцать семь запросов к лежащей зависимости.
  • Повтор без задержки. Синхронные попытки превращают временный сбой в устойчивую перегрузку.
  • Backoff без jitter. Клиенты синхронизируются и приходят к зависимости залпом.
  • Backoff без верхней границы и дедлайна. Задача повторяется дольше, чем живёт входящий запрос.
  • Таймаут на вызов вместо дедлайна на операцию. Сумма таймаутов превышает терпение клиента.
  • Сигнал создан заранее. AbortSignal.timeout тикает с момента создания; повтор получает уже сработавший сигнал.
  • Таймаут без отмены. http.request после события timeout продолжает висеть без destroy().
  • Только клиентский таймаут для базы. Запрос на сервере продолжает работать, а соединение остаётся в неизвестном состоянии.
  • Breaker, который считает 4xx. Он открывается из-за клиентских ошибок, а не из-за проблем зависимости.
  • Один breaker на все зависимости. Отказ одного сервиса закрывает доступ ко всем остальным.
  • Bulkhead без границы очереди. Лимит превращается в накопитель запросов с истёкшим дедлайном.
  • Fallback-заглушка без метрики. Сервис месяцами отдаёт пустые данные, и никто не замечает.
  • 200 на неудавшийся платёж. Деградация превращается в потерю денег и доверия.
  • Остановка без дренажа. Балансировщик шлёт трафик в процесс, который уже закрывает сокеты.
  • server.close() без closeIdleConnections(). Процесс висит до keepAliveTimeout.
  • process.exit() до закрытия пулов. Транзакции и задачи обрываются на середине.
  • Grace period меньше времени остановки. Оркестратор присылает SIGKILL раньше, чем код дошёл до pool.end().

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

  • Надёжность начинается с классификации ошибок: операционную обрабатывают ретраем или деградацией, программерскую логируют и завершают процесс, потому что состояние после неё неизвестно.
  • Таймаут ограничивает один вызов, дедлайн — всю операцию; бюджет передаётся вниз остатком, проверяется перед каждой попыткой, а каждая попытка получает собственный сигнал от остатка.
  • Ретрай допустим только для временных сбоев идемпотентных операций, на одном слое, с экспоненциальной задержкой, jitter и общим бюджетом — иначе он усиливает сбой.
  • Circuit breaker нужен потому, что таймаут продолжает отправлять запросы и занимать ресурсы; breaker отсекает поток к лежащей зависимости и даёт ей восстановиться, отвечая за микросекунды.
  • Bulkhead ограничивает одновременные вызовы и длину очереди на зависимость; без границы очереди лимит превращается в накопитель запросов с истёкшим дедлайном.
  • Деградация выбирается по цене ошибки: кеш и рекомендации работают fail-open, платежи и проверка прав — fail-closed, а любой fallback виден в метриках и не имитирует успех.
  • Graceful shutdown — это последовательность draining → пауза на балансировщик → server.close() → дренаж соединений → воркеры → пулы → выход, ограниченная дедлайном меньше terminationGracePeriodSeconds.

Заключение

Надёжность Node-сервиса — не набор библиотек, а несколько явных решений, принятых один раз и в одном месте. У каждого ожидания есть предел: таймаут на вызов и дедлайн на операцию, который передаётся вниз остатком бюджета. Повтор разрешён только там, где он безопасен, и ограничен задержкой, jitter и общим бюджетом. Лежащая зависимость должна получать паузу, а не весь поток запросов, поэтому рядом с таймаутом стоят breaker и bulkhead.

Деградация — это осознанный выбор, а не побочный эффект catch: где-то пустой блок рекомендаций лучше ошибки, а где-то пропуск платежа недопустим. Остановка процесса — такая же часть жизненного цикла, как обработка запроса: дренаж, закрытие соединений, воркеров и пулов укладываются в дедлайн оркестратора.

Проверить всё это можно только сценариями: SIGTERM под нагрузкой, отключённая зависимость, зависший внешний API. Дальше логично перейти к деплою — там эти же механизмы проверяются в контейнере, где сигналы, PID 1 и лимиты памяти добавляют свои правила.

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