Таймауты, ретраи и graceful shutdown
Отказ зависимости, перезапуск пода и всплеск трафика — не исключения, а штатные условия работы сервиса. Надёжность складывается из скучных решений: у каждого ожидания есть предел, повтор разрешён не всегда, а остановка процесса не обрывает работу на середине. Ниже — как собрать эти решения в Node-сервисе так, чтобы сбой одного вызова не превращался в отказ всего API.
Содержание
- Ошибки: операционные и программерские
- Таймауты на всех уровнях
- Дедлайн: бюджет на всю операцию
- Ретраи: что и когда повторять
- Backoff, jitter и бюджет попыток
- Circuit breaker
- Bulkhead: изоляция ресурсов
- Порядок в цепочке вызовов
- Деградация вместо отказа
- Graceful shutdown: сигнал и дренаж
- Порядок остановки и дедлайн
- Практика: TaskFlow
- Частые ошибки
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Ошибки: операционные и программерские
Надёжность начинается не с библиотеки ретраев, а с ответа на вопрос: что именно сломалось. Одна и та же обработка для всех исключений гарантирует, что часть проблем будет замаскирована, а часть — усилена.
Операционные ошибки — ожидаемые состояния среды. Зависимость не ответила вовремя, база вернула 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.headersTimeout | 10–30 с |
| Приём запроса целиком | server.requestTimeout | 30–60 с |
| Простой keep-alive | server.keepAliveTimeout | 5–65 с, больше прокси |
| Ожидание соединения с БД | connectionTimeoutMillis | 2–5 с |
| Запрос к БД | statement_timeout, query_timeout | 1–5 с |
| Внешний HTTP | connectTimeout/headersTimeout/bodyTimeout | 1–3 / 5–10 / 10–30 с |
| Команда Redis | commandTimeout, connectTimeout | 100–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 jitter | random(0, base × 2^n) | максимально разносит попытки |
| Equal jitter | base/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 полезным:
- Лимит согласован с зависимостью. Если API разрешает 20 RPS, а лимит 8 одновременных вызовов по 3 секунды, реальная пропускная способность — около 2,6 RPS. Лимит считают от целевой нагрузки, а не «на глаз».
- Переполнение — это
503сRetry-After, а не ожидание. Быстрый отказ дешевле для всех: клиент может повторить позже, а сервис не копит бесполезную работу. - Приоритеты важнее симметрии. Под нагрузкой сначала отключают фоновые задачи, экспорт и пересчёты, оставляя критичный путь. Это тоже 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 | да |
SIGINT | Ctrl+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 логов, иначе последние — самые важные — записи потеряются.
Порядок остановки и дедлайн
Последовательность остановки — это не список «что закрыть», а бюджет времени, который должен сойтись с настройками оркестратора.
| Шаг | Что делаем | Что будет, если пропустить |
|---|---|---|
| 1 | draining = true, readiness → 503 | трафик придёт в закрывающийся процесс |
| 2 | Пауза на распространение (3–10 с) | балансировщик продолжит слать запросы |
| 3 | server.close() + closeIdleConnections() | keep-alive держит процесс до таймаута |
| 4 | Ожидание активных запросов с дедлайном | зависший обработчик блокирует деплой |
| 5 | closeAllConnections() по истечении | процесс не завершится в grace period |
| 6 | Остановка воркеров и консьюмеров | задача оборвётся посреди эффекта |
| 7 | pool.end(), redis.quit() | соединения и транзакции повиснут |
| 8 | flush логов и трейсов, 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 и лимиты памяти добавляют свои правила.
Полезные ссылки
- Node.js:
server.close()— остановка сервера и ожидание соединений - Node.js:
closeIdleConnections()— закрытие простаивающих keep-alive-соединений - Node.js:
closeAllConnections()— принудительное закрытие всех соединений - AbortSignal —
timeout,any,reasonи отмена операций - undici: Agent — таймауты, пул соединений и keep-alive
- p-retry — повтор с backoff и собственным фильтром ошибок
- opossum — circuit breaker для Node
- cockatiel — retry, breaker, bulkhead и timeout в одной политике
- Retries и exponential backoff — теория задержек, jitter и
Retry-After - Google SRE: Addressing Cascading Failures — как перегрузка превращается в каскадный отказ
- AWS: Timeouts, retries and backoff with jitter — практика таймаутов и повторов
- Kubernetes: Pod lifecycle —
terminationGracePeriodSecondsиpreStop