Хуки жизненного цикла и graceful shutdown

Старт: снизу вверх, дочерние модули раньше родителей

Задаёшься вопросом «можно ли запустить поллер в onModuleInit?» или «почему соединение соседнего модуля выглядело неготовым?» — ответ определяется порядком старта. Пойми его — и запуск детерминирован; ошибись — и стреляешь в полу-инициализированный граф.

Nest стартует в два прохода. Сначала он конструирует весь DI-граф — каждый провайдер, про который тебе рассказал L02. Потом он обходит модули и зовёт init-хуки. Здесь важны два хука, и порядок между ними — то, что путают чаще всего.

onModuleInit() срабатывает на каждый модуль, как только собственные провайдеры этого модуля зарезолвлены, — и дочерние (импортируемые) модули срабатывают раньше своих родителей. Так что импортированный тобой DatabaseModule отработает свой onModuleInit раньше, чем UsersModule, который его импортирует. onApplicationBootstrap() срабатывает один раз, после того как каждый модуль в приложении закончил инициализацию.

import { Injectable, OnModuleInit, OnApplicationBootstrap } from '@nestjs/common';

@Injectable()
export class IndexerService implements OnModuleInit, OnApplicationBootstrap {
  // runs when THIS module's providers are ready — children before parents.
  // Хуки могут быть async; Nest их ожидает перед продолжением.
  async onModuleInit() {
    await this.warmLocalCache(); // нужны только зависимости ЭТОГО модуля
  }

  // срабатывает, когда ВЕСЬ граф приложения жив — безопасно обращаться к другим модулям.
  async onApplicationBootstrap() {
    this.startPoller(); // зависит от инициализации соседнего модуля
  }
}

Различие не косметическое. В onModuleInit модуля A гарантированно готовы только сам A и модули, которые A импортирует. Соседний модуль B, к которому ты тянешься поперёк, — скажем, шина сообщений, в которую ты публикуешь, — может ещё не отработать свой onModuleInit. Запусти поллер там — и он может стрельнуть в полу-инициализированный граф.

Остановка: обратный порядок и ВЫКЛ по умолчанию

Остановка прогоняет жизненный цикл задом наперёд. Порядок такой: onModuleDestroy() → beforeApplicationShutdown(signal?) → onApplicationShutdown(signal?), а модули разрушаются в обратном порядке к старту: зависящие раньше зависимостей. Этот порядок намеренный — модуль успевает прибраться до того, как исчезнут модули, от которых он зависит, так что твой UsersModule может сбросить буферы прежде, чем DatabaseModule, на котором он стоит, закроет свой пул. Последние два хука получают строку сигнала ('SIGTERM', 'SIGINT'), так что ты можешь ветвиться по причине остановки.

import { Injectable, OnModuleDestroy } from '@nestjs/common';
import { Pool } from 'pg';

@Injectable()
export class Database implements OnModuleDestroy {
  private pool = new Pool(/* ... */);

  // Nest ЖДЁТ это при остановке — дренируй в-полёте, потом закрой чисто.
  async onModuleDestroy() {
    await this.pool.end(); // ждёт активные запросы, затем освобождает сокеты
    // для брокера: await this.consumer.disconnect() — коммит оффсетов, отписка
  }
}

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

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // WITHOUT this line, SIGTERM exits the process immediately and NO
  // onModuleDestroy / onApplicationShutdown ever runs — pools severed,
  // requests dropped, broker offsets uncommitted.
  app.enableShutdownHooks();

  await app.listen(3000);
}
bootstrap();

Забудь эту строку — и SIGTERM в части твоей чистки ведёт себя как kill -9: цикл событий так и не получает шанса выполнить твой pool.end(), консьюмер не отключается, а Kubernetes радостно рапортует об успешном раскате, пока старые поды текут недоделанной работой.

Два режима отказа: нет дренажа и дренаж, который не кончается

Первый режим отказа — это инцидент выше: нет enableShutdownHooks(), так что SIGTERM обрубает всё. Фикс — та самая одна строка плюс настоящая чистка в onModuleDestroy — await pool.end(), await consumer.disconnect(), — чтобы пулы дренировались, а брокер закоммитил до того, как процесс уйдёт.

Но есть симметричный второй режим отказа, и сеньоры попадают в него после того, как включили хуки: shutdown-хук, который зависает. Если onModuleDestroy ждёт промис, который никогда не резолвится, или ты написал 60-секундный дренаж, Kubernetes не ждёт вечно. Он ждёт terminationGracePeriodSeconds — по умолчанию 30 секунд, — затем посылает SIGKILL и всё равно обрубает твою чистку. Хук, который блокируется дольше grace-периода, не безопаснее, чем отсутствие хука; он просто падает позже и запутаннее. Так что дренаж обязан укладываться с запасом под 30 секунд: вменяемый бюджет — 5–15 секунд. И дренажа запросов самого по себе мало — нужно ещё, чтобы балансировщик перестал слать новые, прежде чем ты перестанешь принимать. Переключи readiness-пробу в unready на SIGTERM и добавь preStop sleep около 5 секунд, чтобы дерегистрация эндпоинта успела распространиться через kube-proxy до того, как приложение реально ляжет. Иначе ты идеально сдренируешь старые запросы и потом уронишь новые, которые пришли в это окно.