NestJS Enterprise Backend APIs · Leçon

Délais d’expiration, nouvelles tentatives et cloisons avec des intercepteurs

Implémentez des intercepteurs de délai d’expiration et de nouvelle tentative fondés sur RxJS, ainsi que des cloisons de concurrence pour les appels sortants.

Délais d’expiration, nouvelles tentatives et cloisons avec des intercepteurs est une leçon NestJS Enterprise Backend APIs gratuite sur CoddyKit. Ceci est la leçon 1 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage NestJS Enterprise Backend APIs, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours NestJS Enterprise Backend APIs comprend 4 leçons au total.

Certaines parties de cette leçon n'ont pas encore été traduites et s'affichent en anglais.

Why Resilience Patterns Belong in Interceptors

Outbound calls to other services fail in three classic ways: they hang forever, they fail transiently, or they flood a slow dependency until it (and you) collapse. The three matching defenses are timeouts, retries, and bulkheads.

Timeout — cap how long any one call may run.
Retry — re-attempt a failed call a bounded number of times, ideally only for transient errors.
Bulkhead — cap how many calls run concurrently so one dependency can't exhaust your resources.

In NestJS these compose cleanly as NestInterceptors. An interceptor wraps the handler's RxJS stream, so we can layer timeout and retry operators on the response Observable without touching business logic.

The Interceptor Contract

A NestJS interceptor implements intercept(context, next) and returns an Observable. Calling next.handle() runs the route handler and gives you its result stream. Anything you pipe onto that stream — timeout, retry, catchError — applies to the response.

This is why resilience logic lives here: it is cross-cutting and stream-based.
Operators run in order, so placement of timeout vs retry changes behavior — we will exploit that.

import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    const started = Date.now();
    // next.handle() executes the route handler; we pipe onto its stream.
    return next.handle().pipe(
      tap(() => console.log(`took ${Date.now() - started}ms`)),
    );
  }
}

A Timeout Interceptor

The RxJS timeout operator emits a TimeoutError if the source does not emit within the given window. We catch that error and convert it into a proper HTTP response — 504 Gateway Timeout — instead of leaking an RxJS error class.

Always translate TimeoutError into a meaningful status; an unhandled one becomes a generic 500.
Re-throw anything that is not a timeout so other filters can handle it.

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

@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  constructor(private readonly ms = 5000) {}

  intercept(_ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    return next.handle().pipe(
      timeout(this.ms),
      catchError((err) =>
        err instanceof TimeoutError
          ? throwError(() => new RequestTimeoutException('Upstream call timed out'))
          : throwError(() => err),
      ),
    );
  }
}

Making the Timeout Configurable Per Route

A flat 5s timeout rarely fits every endpoint. Expose the value via metadata so each handler can override it. Read it with Reflector, falling back to a default.

Define a @Timeout(ms) decorator using SetMetadata.
The interceptor pulls the value off the handler with reflector.get.

This keeps the policy declarative: the route says how patient it is.

import { SetMetadata, applyDecorators } from '@nestjs/common';

export const TIMEOUT_MS = 'timeout_ms';
export const Timeout = (ms: number) => applyDecorators(SetMetadata(TIMEOUT_MS, ms));

// In the interceptor:
// const ms = this.reflector.get<number>(TIMEOUT_MS, ctx.getHandler()) ?? 5000;
// return next.handle().pipe(timeout(ms), /* catchError ... */);

Retrying Transient Failures

RxJS retry resubscribes to the source when it errors. Naive retry(3) hammers a struggling dependency. Use retry({ count, delay }) where delay is a function returning an Observable — this lets us add exponential backoff with jitter and filter which errors are retryable.

Retry only idempotent operations (GET, PUT, DELETE) — never blind-retry a POST that may have already succeeded.
Retry only transient errors: timeouts, 502/503/504, connection resets — not a 400 or 422.

import { Observable, throwError, timer } from 'rxjs';
import { retry } from 'rxjs/operators';

const RETRYABLE = new Set([502, 503, 504]);

function withRetry<T>(source: Observable<T>): Observable<T> {
  return source.pipe(
    retry({
      count: 3,
      delay: (err, attempt) => {
        const status = err?.response?.status;
        if (status && !RETRYABLE.has(status)) return throwError(() => err);
        const base = 100 * 2 ** (attempt - 1); // 100, 200, 400 ms
        const jitter = Math.random() * base;
        return timer(base + jitter);
      },
    }),
  );
}

Backoff Math, Standalone

Before wiring backoff into an interceptor, it helps to see the delays. Full jitter picks a random delay in [0, base] to spread retries and avoid the thundering herd where every client retries at the same instant.

This snippet just prints the schedule — pure TypeScript, no framework.

function backoffSchedule(maxAttempts: number, baseMs: number): number[] {
  const delays: number[] = [];
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const cap = baseMs * 2 ** (attempt - 1);
    const fullJitter = Math.floor(Math.random() * cap); // [0, cap)
    delays.push(fullJitter);
  }
  return delays;
}

const schedule = backoffSchedule(5, 100);
console.log('Caps:   ', [100, 200, 400, 800, 1600].join(', '));
console.log('Jittered:', schedule.join(', '));
console.log('Total wait:', schedule.reduce((a, b) => a + b, 0), 'ms');

Ordering: Timeout Inside, Retry Outside

Operator order is the subtle part. Put timeout before retry in the pipe so each attempt gets its own deadline; retry then resubscribes and re-arms the timeout for the next attempt.

timeout then retry — per-attempt deadline, N fresh tries. Usually what you want.
retry then timeout — one deadline spanning all attempts; a slow first try eats the whole budget.

Always bound the worst case: attempts × (timeout + maxBackoff) must stay under the caller's own deadline.

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

@Injectable()
export class ResilientInterceptor implements NestInterceptor {
  intercept(_ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    return next.handle().pipe(
      timeout(2000),               // per-attempt deadline
      retry({ count: 3, delay: (_e, n) => timer(100 * 2 ** (n - 1)) }),
      catchError((err) =>
        err instanceof TimeoutError
          ? throwError(() => new RequestTimeoutException())
          : throwError(() => err),
      ),
    );
  }
}

The Bulkhead: Capping Concurrency

Timeouts and retries protect a single request. A bulkhead protects the whole process: it limits how many in-flight calls a dependency may have, so a slow downstream can't pile up unbounded promises and exhaust threads, sockets, or memory.

Calls beyond the limit either queue (bounded) or are rejected fast (503).
Named after ship compartments: a flood in one section is sealed off from the rest.

A minimal bulkhead is a semaphore: a permit count plus a waiter queue.

export class Bulkhead {
  private active = 0;
  private readonly queue: Array<() => void> = [];

  constructor(private readonly maxConcurrent: number, private readonly maxQueue: number) {}

  async run<T>(task: () => Promise<T>): Promise<T> {
    if (this.active >= this.maxConcurrent) {
      if (this.queue.length >= this.maxQueue) throw new Error('BULKHEAD_FULL');
      await new Promise<void>((resolve) => this.queue.push(resolve));
    }
    this.active++;
    try {
      return await task();
    } finally {
      this.active--;
      this.queue.shift()?.();
    }
  }
}

A Runnable Bulkhead Simulation

Here is the bulkhead exercised end-to-end with simulated async work. Watch that no more than maxConcurrent tasks run at once, and overflow past the queue is rejected immediately — the fast-fail that keeps your service healthy.

class Bulkhead {
  private active = 0;
  private queue: Array<() => void> = [];
  constructor(private max: number, private maxQueue: number) {}
  async run<T>(task: () => Promise<T>): Promise<T> {
    if (this.active >= this.max) {
      if (this.queue.length >= this.maxQueue) throw new Error('BULKHEAD_FULL');
      await new Promise<void>((r) => this.queue.push(r));
    }
    this.active++;
    try { return await task(); }
    finally { this.active--; this.queue.shift()?.(); }
  }
}

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
const bh = new Bulkhead(2, 1);
let peak = 0, running = 0;

async function call(id: number) {
  try {
    await bh.run(async () => {
      running++; peak = Math.max(peak, running);
      await sleep(50);
      running--;
    });
    return `ok-${id}`;
  } catch (e) { return `rejected-${id}`; }
}

async function main() {
  const results = await Promise.all([1, 2, 3, 4, 5].map(call));
  console.log(results.join(', '));
  console.log('peak concurrency:', peak);
}
main();

Wiring the Bulkhead into an Interceptor

To apply a bulkhead per outbound dependency, hold a Bulkhead instance in a provider and run the handler stream through it. Use from(promise) to bridge the async run() back into RxJS, then layer timeout and retry on top.

One bulkhead instance per dependency, not per request — the limit is shared, so it must be a singleton provider.
Convert BULKHEAD_FULL into 503 Service Unavailable so callers can back off.

import { CallHandler, ExecutionContext, Injectable, NestInterceptor, ServiceUnavailableException } from '@nestjs/common';
import { Observable, defer, lastValueFrom } from 'rxjs';
import { catchError } from 'rxjs/operators';
import { Bulkhead } from './bulkhead';

@Injectable()
export class BulkheadInterceptor implements NestInterceptor {
  private readonly bulkhead = new Bulkhead(10, 20); // shared, singleton-scoped

  intercept(_ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    return defer(() => this.bulkhead.run(() => lastValueFrom(next.handle()))).pipe(
      catchError((err) => {
        if (err?.message === 'BULKHEAD_FULL') throw new ServiceUnavailableException('Capacity reached');
        throw err;
      }),
    );
  }
}

Composing All Three at the HttpModule Layer

In practice you rarely intercept inbound routes for outbound resilience — you wrap the HTTP client. With Nest's HttpService (Axios + RxJS) you pipe the same operators onto each outbound observable, and run it through the dependency's bulkhead.

Tune budgets per dependency: a fast cache gets a 200ms timeout; a report API gets 10s and zero retries.
Pair this with a circuit breaker so a dependency that keeps failing is shed before timeouts even fire.

import { Injectable } from '@nestjs/common';
import { HttpService } from '@nestjs/axios';
import { AxiosResponse } from 'axios';
import { Observable, defer, lastValueFrom, throwError, timer } from 'rxjs';
import { retry, timeout } from 'rxjs/operators';
import { Bulkhead } from './bulkhead';

@Injectable()
export class PricingClient {
  private readonly bulkhead = new Bulkhead(8, 16);
  constructor(private readonly http: HttpService) {}

  getPrice(sku: string): Observable<AxiosResponse> {
    return defer(() =>
      this.bulkhead.run(() =>
        lastValueFrom(
          this.http.get(`/pricing/${sku}`).pipe(
            timeout(800),
            retry({ count: 2, delay: (_e, n) => timer(100 * 2 ** (n - 1)) }),
          ),
        ),
      ),
    );
  }
}

Quick Check

You wrap an outbound call with both a 2s timeout and a 3-attempt retry inside one RxJS pipe. You want each attempt to have its own 2-second deadline. Which operator ordering achieves that?

Recap

You built the three core outbound-resilience patterns as composable NestJS interceptors:

Timeout — timeout(ms) + catchError to translate TimeoutError into 504/408; make it per-route via Reflector metadata.
Retry — retry({ count, delay }) with exponential backoff and full jitter, restricted to idempotent operations and transient status codes.
Bulkhead — a semaphore (active count + bounded queue) per dependency that fast-fails with 503 when capacity is reached, isolating one slow downstream.

Key decisions: place timeout before retry for per-attempt deadlines; keep bulkheads singleton-scoped per dependency; and always bound the worst case (attempts × (timeout + backoff)) below the caller's deadline. Combine these with a circuit breaker for full steady-state protection.

Questions Fréquemment Posées

La leçon « Délais d’expiration, nouvelles tentatives et cloisons avec des intercepteurs » est-elle gratuite ?

Oui — le texte complet de « Délais d’expiration, nouvelles tentatives et cloisons avec des intercepteurs » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours NestJS Enterprise Backend APIs, passe à CoddyKit PRO. Le cours NestJS Enterprise Backend APIs comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Délais d’expiration, nouvelles tentatives et cloisons avec des intercepteurs » ?

Implémentez des intercepteurs de délai d’expiration et de nouvelle tentative fondés sur RxJS, ainsi que des cloisons de concurrence pour les appels sortants. Tu pratiques NestJS Enterprise Backend APIs avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer NestJS Enterprise Backend APIs ?

Aucune expérience préalable n'est requise. NestJS Enterprise Backend APIs sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 1 sur 4.

Combien de temps prend la leçon « Délais d’expiration, nouvelles tentatives et cloisons avec des intercepteurs » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon NestJS Enterprise Backend APIs ?

Oui. Chaque leçon NestJS Enterprise Backend APIs inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

Délais d’expiration, nouvelles tentatives et cloisons avec des intercepteurs
Disjoncteurs face aux défaillances des services en aval
Traçage distribué avec OpenTelemetry
Définition des SLO et des budgets d’erreur

← Retour à NestJS Enterprise Backend APIs