Health-проверки и сквозные interceptors

Terminus: один эндпоинт, много индикаторов

@nestjs/terminus — это health-check тулкит Nest. Ты инжектишь HealthCheckService и вызываешь check([...]) с массивом функций-индикаторов; check здоров, только если каждый индикатор отдаёт up. Terminus поставляет индикаторы под частые зависимости — TypeOrmHealthIndicator (гоняет SELECT 1 через pingCheck), HttpHealthIndicator.pingCheck(name, url), MemoryHealthIndicator.checkHeap(key, bytes), плюс варианты под Mongoose/Prisma/Redis/Disk — а кастомные ты пишешь через HealthIndicatorService. Декоратор @HealthCheck() навешивает Swagger/форму ответа.

import { Controller, Get } from '@nestjs/common';
import {
  HealthCheckService, HealthCheck,
  TypeOrmHealthIndicator, MemoryHealthIndicator,
} from '@nestjs/terminus';

@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private db: TypeOrmHealthIndicator,
    private memory: MemoryHealthIndicator,
  ) {}

  // LIVENESS: "процесс жив и не заклинил?" — БЕЗ downstream-зависимостей.
  @Get('live')
  @HealthCheck()
  liveness() {
    return this.health.check([
      () => this.memory.checkHeap('memory_heap', 512 * 1024 * 1024),
    ]);
  }

  // READINESS: "могу ли я обслуживать трафик прямо сейчас?" — зависимости тут МОЖНО.
  @Get('ready')
  @HealthCheck()
  readiness() {
    return this.health.check([
      () => this.db.pingCheck('database'),
    ]);
  }
}

Кастомный индикатор живёт по тому же контракту — HealthIndicatorService.check(key) даёт индикатор, который ты помечаешь up() или down({ ...detail }):

import { Injectable } from '@nestjs/common';
import { HealthIndicatorService } from '@nestjs/terminus';

@Injectable()
export class QueueHealthIndicator {
  constructor(private readonly hi: HealthIndicatorService) {}

  async isHealthy(key: string) {
    const indicator = this.hi.check(key);
    const depth = await this.queue.depth();
    return depth < 10_000 ? indicator.up({ depth }) : indicator.down({ depth });
  }
}

Liveness vs readiness: различие, предотвращающее аварии

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

• Liveness отвечает на «процесс жив и не заклинил?» Проваленная liveness-проба заставляет kubelet перезапустить под. Поэтому liveness никогда не должен зависеть от downstream-сервиса. Если твоя база, кэш или очередь на миг недоступны — это не повод убивать процесс: рестарт не починит внешний сбой, он лишь усилит его в crash loop. Держи liveness на уровне «event loop отвечает и процесс не в дедлоке».
• Readiness отвечает на «могу ли я обслуживать трафик прямо сейчас?» Проваленная readiness-проба убирает под из endpoints Service / load balancer, но оставляет процесс работать. Так что readiness может и должен проверять критические зависимости, нужные, чтобы реально обслужить запрос. Когда база возвращается, readiness снова проходит и под ставят обратно в ротацию — без рестарта, без потери процесса, без шторма.

Соответствующие пробы Kubernetes указывают на два раздельных эндпоинта:

livenessProbe:
  httpGet: { path: /health/live, port: 3000 }
  periodSeconds: 10
  failureThreshold: 3
readinessProbe:
  httpGet: { path: /health/ready, port: 3000 }
  periodSeconds: 5
  failureThreshold: 2

Readiness как рычаг graceful shutdown

Тот же readiness-эндпоинт — это твой рычаг слива на шатдауне. На SIGTERM ты хочешь, чтобы load balancer перестал слать новый трафик до того, как ты начнёшь рушить процесс, — иначе in-flight запросы обрежутся. Так что верный порядок шатдауна такой: переключить readiness в down первым, дождаться, пока LB заметит и сольёт, затем закрыть сервер и соединения. Shutdown hooks Nest дают тебе этот шов:

@Injectable()
export class ReadinessState {
  private ready = true;
  isReady() { return this.ready; }
  setDraining() { this.ready = false; } // readiness-индикатор читает это
}

// В readiness-проверке гейти на этом состоянии, чтобы SIGTERM переключил её в 503 первой.
async beforeApplicationShutdown() {
  this.readinessState.setDraining();      // провалить readiness -> LB сливает нас
  await sleep(this.drainGraceMs);         // дай k8s несколько интервалов пробы
}

Именно этот порядок — readiness down, слив, затем закрытие — заставляет rolling deploy не потерять ни одного запроса. (Хук beforeApplicationShutdown срабатывает только если был вызван app.enableShutdownHooks(); app-level обвязка шатдауна живёт в уроке про graceful shutdown. Здесь суть — какой сигнал переключает readiness и почему он должен предшествовать teardown.)

Сквозные interceptors для устойчивости и наблюдаемости

Когда health-пробы расставлены верно, остаётся целый класс задач уровня запроса — что делать, если хендлер завис навсегда? кто измеряет задержку каждого запроса? — которые не принадлежат ни одному конкретному хендлеру. Если ты добавляешь один и тот же try/catch или таймер в десяток маршрутов — это сигнал: пора взять interceptor. Interceptors оборачивают next.handle() (RxJS Observable) с обеих сторон, что делает их верным домом для сквозного слоя, обрамляющего каждый запрос: таймаут, чтобы заклинивший downstream не держал запрос открытым вечно, метрики, чтобы видеть латентность и статус, и кэширование для горячих GET’ов. Канонический TimeoutInterceptor гоняет хендлер наперегонки с RxJS timeout() и конвертирует получившийся TimeoutError в нормальный RequestTimeoutException (408):

import {
  Injectable, NestInterceptor, ExecutionContext,
  CallHandler, RequestTimeoutException,
} from '@nestjs/common';
import { Observable, throwError, TimeoutError } from 'rxjs';
import { catchError, timeout } from 'rxjs/operators';

@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
    return next.handle().pipe(
      timeout(5000),
      catchError((err) =>
        err instanceof TimeoutError
          ? throwError(() => new RequestTimeoutException())
          : throwError(() => err),
      ),
    );
  }
}

Interceptor метрик пишет длительность и исход в гистограмму prom-client, тапая и успешный, и ошибочный путь:

@Injectable()
export class MetricsInterceptor implements NestInterceptor {
  constructor(private readonly httpDuration: Histogram) {}
  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    const route = ctx.switchToHttp().getRequest().route?.path ?? 'unknown';
    const stop = this.httpDuration.startTimer({ route });
    return next.handle().pipe(
      tap(() => stop({ status: 'ok' })),
      catchError((err) => { stop({ status: 'error' }); return throwError(() => err); }),
    );
  }
}

Тонкость, которую сеньор обязан держать: глобальные interceptors композируются, а исходящий путь разматывается в обратном порядке. На входе они идут global → controller → route; стрим ответа разматывается route → controller → global, как возвраты вложенных функций. Так что порядок важен. Если хочешь, чтобы метрики писали реальную отданную латентность, включая таймаут, interceptor метрик должен оборачивать снаружи timeout-interceptor — иначе он остановит таймер до того, как сработает таймаут, и недосчитает хвостовую латентность.