Interceptors

Interceptors

Interceptor는 NestInterceptor interface를 구현하고 @Injectable() decorator가 주석으로 달린 class이다.

Interceptor는 들어오는 요청(reqeust)와 나가는 응답(response)을 가로채고, 이들 사이에서 추가적인 로직을 실행할 수 있도록 하는 강력한 기능을 제공한다. 인터셉터는 다음과 같은 여러 용도로 사용될 수 있다.
    - 로깅(Logging): 요청 및 응답 정보를 기록
    - 변환(Transformation): 응답 데이터를 특정 형식으로 변환
    - 캐싱(Caching): 반복적인 요청에 대해 캐시된 응답을 제공한다.
    - 에러 처리(Error Handling): 특정한 에러를 처리하거나 에러 메시지를 변환한다.
    - 타이밍(Timing): 요청 처리 시간을 측정한다.

 

1. Middleware: 모든 미들웨어가 순차적으로 실행된다.
2. Guard: 요청을 처리할 수 있는지 확인하는 모든 가드가 실행된다.
3. Interceptor(전처리): 요청 전처리를 수행하는 모든 인터셉터가 실행된다
4. Pipe: 입력 데이터의 변환 및 유효성 검사를 수행하는 모든 파이프가 실행된다.
5. Controller Handler: 컨트롤러의 핸들러 메서드가 실행된다.
6. Pipe(응답 데이터 변환): 컨트롤러 핸들러가 반환한 데이터를 변환하는 파이프가 있을 경우 실행된다.
7. Interceptor(후처리): 요청 후처리를 수행하는 모든 인터셉터가 실행된다. 

 

 

interceptor는 AOP(Aspect Oriented Programming) 기술에 의해 고무된 유용한 기능들의 집합이다.

AOP: OOP와 같은 방식으로 소프트웨어 모듈화를 목표로 하는 프로그래밍 패러다임이다. 주로 관심사의 분리(Separation of Concerns)를     통해 코드의 재사용성과 유지보수성을 높이는 데 중점을 둔다.

• method 실행의 전, 후 로직을 묶는다.
• function으로 부터 반환된 result를 바꿈
• function으로 부터 던져진 exception을 바꿈
• basic fucntion들의 기능 추가
• 특정 조건에 따라 function을 override 하는 것

 

Basics

 

각 interceptor는 intercept() method를 구현한다. 이는 두 개의 argument를 받는다. (ExecutionContext, CallHandler) ExecutionContext의 instance이다.(Guards에서의 object과 동일하다.) ExecutionContext는 ArgumentsHost를 상속받는다. 이전의 exception filter chapter에서 ArgumentHost를 살펴보았다. 이것은 original handler에 전달된 arguments들의 wrapper이며, application의 type에 따라 다양한 arguments array를 포함하고 있음을 보았다. 자세한 사항은 exception filters 살펴봐라.

ArgumentHost: 원래 handler에 전달된 argument를 래핑하는 객체로, 어플리케이션의 타입에 따라 다양한 인수 배열을 포함한다.
        이를 통해, request handler에 전달된 모든 인수를 쉽게 접근할 수 있다.
    1. getArgs() : 원래의 핸들러에 전달된 모드 인수 배열을 반환
    2. getArgByIndex(index:number): 특정 인덱스의 인수를 반환
    3. switchToHttp(): Http 컨텍스트로 전환하여 HTTP 요청 및 응답 객체에 접근할 수 있다.
    4. swtichToWs(): WebSocket 컨텍스트로 전환하여 WebSocket 요청 및 응답 객체에 접근할 수 있다.
ExecutionContext: 'ArgumentsHost'를 확장한 인터페이스로, 주로 가드와 인터셉터에서 사용된다.  
    1. getClass(): 현재 처리 중인 클래스(controller)를 반환한다.
    2. getHandler(): 현재 처리 중인 핸들러(method)를 반환한다.
    3. getType(): 현재 실행 컨텍스트의 유형을 반환한다.(HTTP, RPC, WebSocket)


ArgumentHost와 ExecutionContext의 주요 정보
1. HTTP 컨텍스트(Express 사용 시)
    - Request: Express의 요청 객체로, 요청된 URL, 헤더, 본문, 쿼리 파라미터 등을 포함한다.
    - Response: Express의 응답 객체로, 응답을 작성하고 반환하는데 사용된다.
    - Next: (옵션) 미들웨어 체인의 다음 함수로, 일반적으로 사용은 안됨
2. 메서드 및 클래스 정보
    - Handler: 현재 실행 중인 핸들러 메서드
    - Class: 현재 실행 중인 클래스(컨트롤러)

 

Execution context

 

ArgumentsHost, ExecutionContext를 extending함으로써 현재 execution process에 대해 추가정보를 제공하는 새로운 helper method들을 추가할 수 있다. 이러한 정보들은 controller, method, execution context를 걸쳐 좀더 generic interceptor를 build하는데 도움된다. ExecutionContext

Call handler

NestJs에서의 interceptor는 request를 가로채어 특정 로직을 실행할 수 있다. 인터셉터의 intercept() method는 두 개의 인자를 받는다. ExecutionContext와 CallHandler. CallHandler의 'handle()' method는 rotue handler method를 호출하는 데 사용된다. 만약 handle() method를 호출하지 않으면, request가 route handler로 전달되지 않고, 해당 route handler method는 실행되지 않는다.

 

이러한 접근은 intercept() method는 효과적으로 request/response streamdmf 감싼다. 결과대로, 마지막 route handler의 실행 전/후 둘다 custom logic를 실행할 것 이다. intercept() method가 handle() 이 호출되기 전에 실행된다. 하지만 후에 어떻게 영향을 주는가? handle() method가 Observable를 return 하기 때문에, 우리는 강력한 RxJS operator를 사용하여 response를 조작할 수 있다. Aspect Oriented Programming 기술을 사용하면, route handler의 호출(즉, handle() 호출)은 Pointcut이라고 하며 이 지점에서 추가 로직이 삽입 된다.

 

RxJS: 이벤트나 비동기, 시간을 마치 Array 처럼 다룰 수 있게 만들어 주는 라이브러리

 

예를 들어, POST /cats request가 들어온다고 가정하자. request는 CatsController안에 정의된 create() handler method로 향할 것이다. interceptor가 handle() method를 호출하지 않으면, 그 경로상의 어느 곳에서든 create() method가 실행되지 않을 것 이다. 한번 handle()이 호출되면(이는 Observable을 반환할 것 이다.) create() handler가 트리거된다. 그리고 Observable를 통해 응답 스트림이 수신되면, 그 스트림에 추가 작업을 수행하고 최종 결과를 호출자에게 반환할 수 있다.

Aspect interception

NestJs에서 인터셉터를 사용하여 사용자 상호작용을 logging 할 수 있다. 예를 들어, 사용자의 호출을 저장하거나, 비동기적으로 이벤트를 디스패치하거나, 타임스탬프를 계산할 수 있다. 아래는 간단한 LoggingInterceptor이다.

 

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

// pipe
// RxJS의 주요 연산자 중 하나로, Observable의 데이터를 처리하기 위해 다양한 연산자를 연결
// 할 수 있는 메서드이다. pipe를 사용하면 데이터를 변환하거나, 필터링하거나, 부수 효과를 추가하는 
// 등의 작업을 체인 방식으로 적용할 수 있다.

// tap
// RxJS의 연산자 중 하나로, Observable 데이터 스트림을 변경하지 않고, 부수 효과(side effect)를 추가
// 할 수 있게 해준다. 주로 디버깅, 로깅, 데이터 수집 등의 목적으로 사용된다. 
// tap 연산자는 스트림에 있는 각 데이터 항목에 대해 지정된 함수를 호출한다.

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    // route handler 전
    console.log('Before...');

    const now = Date.now();
    // next: CallHandler 인터페이스를 구현한 객체로, 실제 컨트롤러의 핸들러 메서드를 호출하는 handle method를 제공한다.
    // next.handle(): 핸들러 메서드를 호출하고, Observable을 반환한다.
    return next
      .handle()
    // route handler 후
      .pipe(
        tap(() => console.log(`After... ${Date.now() - now}ms`)),
      );
  }
}

 

<팁!>

NestInterceptor<T,R> 는 generic interface이다.
T는 Observable<T>의 타입을 나타낸다. 요청 핸들러가 반환하는 데이터 스트림의 타입을 나타낸다. 즉, 라우트 핸들러 메서드가 반환하는 데이터 타입 이다.
R는 Observable<R>에 의해 감싸진 값의 타입을 말한다. 인터셉터가 반환하는 최종 데이터 타입이다. 인터셉터가 응답 데이터를 어떻게 변형할지를 정의한다.

 

<주의사항!>
interceptor는 controller, provider, guard와 동일하게 constructor를 통해 dependency를 inject한다.

 

handle() 은 RxJS Observable를 반환하기 때문에, 우리는 다양한 RxJS 연산자를 사용하여 stream을 조작할 수 있다.
이를 통해, response data에 추가적인 로직을 적용하거나, 데이터를 변환하고, 부수 효과를 추가할 수 있다. 위의 예에서 tab() 연산자를 사용했다. 이는 Observable 스트림이 정상적으로 완료되거나 예외가 발생할 때 익명 로깅 함수를 호출한다. 그러나 response cycle에는 영향을 미치지 않는다. 이는 주로 디버깅, 로깅, 또는 부수효과를 추가하는 용도로 사용된다.

Binding interceptor

interceptor를 설정하기 위해서는 @nestjs/common에서 @UseInterceptors() decorator를 사용한다. pipe, guards와 마찬가지로interceptor는 또한 controller, method, global scope로 설정할 수 있다.

@UseInterceptors(LoggingInterceptor)
export class CatsController {}

 

위의 구조로, CatsController안에 정의된 모든 route handler들은 LogginInterceptor를 사용할 수 있다. 만일 GET /cats endpoint가 호출된다면, 다음과 같은 output을 얻을 수 있다.

Before...
After... 1ms

 

instance가 아닌 LogginInterceptor class 를 전달했다. 이는 instantiation과 dependeny injection 책임을 framework에게 넘겨준다. pipe, guard, exception filter과 동일하게, 또한 instance를 넘겨줄 수 있다.

@UseInterceptors(new LoggingInterceptor())
export class CatsController {}

 

앞서 언급한 대로 위의 구조는 controller에 선언된 모든 handler에 interceptor를 붙인다. 만일 interceptor의 범위를 single method로 좁히고 싶다면, 간단히 method level로 적용하면 된다.

 

만일 global interceptor를 설정하고 싶다면, useGlobalInterceptors() method를 사용한다.

const app = await NestFactory.create(AppModule);
app.useGlobalInterceptors(new LoggingInterceptor());

 

global interceptor는 모든 controller, route handler를 걸친 application에 사용된다. dependency injection면에서, 위의 예 처럼, useGlobalInterceptors()를 사용하여 module 바깥에서 등록된 global interceptor는 dependency를 inject할 수 없다. 왜냐하면 module의 외부에서 inject가 이루어 졌기 때문이다. 이러한 문제를 해결하기 위해서는 다음과 같은 구조로 interceptor를 module 에서 바로 설정하면 된다.

 

import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: LoggingInterceptor,
    },
  ],
})
export class AppModule {}

 

<팁!>
이 접근 방식을 사용하여 interceptor에 대한 dependency inject를 수행할 때, 이 구성이 사용되는 모듈에 관계없이 interceptor는 실제로 전역적임을 유의해야 한다. 이는 intercepter(위의 경우 LogginInterceptor)가 정의된 모듈을 선택해야 한다. 또한 'useClass'는 custome provider 등록을 처리하는 유일한 방법이 아니다. 자세히

Response mapping

handle() method는 Observable를 반환한다. stream에는 route handler에서 반환된 value를 포함한다. 그리고 즉, 이는 RxJS의 map() operator를 통해 쉽게 변경할 수 있다. map() 연산자는 Observable의 각 값을 변환하여 새로운 값으로 반환한다. 이를 통해 응답 데이터를 변형하거나 추가적인 로직을 적용할 수 있다.

 

<주의사항!>
response mapping feature은 라이브러리별 response strategy(즉, '@Res() obejct를 직접 사용하는 것')와 함께 작동하지 않는다.

 

TransformInterceptor를 만들자. 이는 process를 보여주기 위해 각 response를 간단하게 변형한 것 이다. 이는 response object를 새롭게 만들어진 object의 data 속성에 할당하기 위해 RxJS의 map() 연산자를 사용할 것 이다. 이렇게 만들어진 object는 client에게 반환될 것 이다.

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

// 응답 데이터의 구조를 정의
export interface Response<T> {
  data: T;
}

@Injectable()
//<T, Response<T>>
//    T: 인터셉터가 처리할 입력 데이터의 타입을 나타냄
//    Response<T>: 인터셉터가 반환할 출력 데이터의 타입을 나타냄
export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
  // context: 현재 실행 컨텍스트를 나타냄, 요청 및 응답 객체에 접근할 수 있다.
  // next: CallHandler 인터페이스를 구현한 객체로, 실제 컨트롤러의 핸들러 메서드를 호출하는 handle 메서드를 제공
  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
    return next.handle().pipe(map(data => ({ data })));
  }
}

// 사용
import { Controller, Get, UseInterceptors } from '@nestjs/common';
import { TransformInterceptor } from './transform.interceptor';

@Controller('cats')
@UseInterceptors(TransformInterceptor)
export class CatsController {
  @Get()
  findAll() {
    return [{ name: 'Tom' }, { name: 'Jerry' }];
  }
}

 

Nest 인터셉터는 동기와 비동기 모두에서 작동한다. 필요에 따라 메서드를 간단히 async로 변경할 수 있다.

 

위의 구조에서 만일 GET /cats endpoints로 호출했을 때, response는 다음과 같은 결과를 도출할 것 이다.

{
  "data": []
}

 

인터셉터는 어플리케이션 전체에서 발생하는 요구 사항에 대한 재사용 가능한 솔루션을 만드는데 큰 가치를 제공한다.

예를 들어, null값을 빈 문자열("")로 변환해야 한다고 가정해보자. 한 줄의 코드로 이를 수행할 수 있으며, 인터셉터를 전역적으로 바인딩하여 등록된 각 핸들러에서 자동으로 사용되도록 할 수 있다.

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

@Injectable()
export class ExcludeNullInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next
      .handle()
      .pipe(map(value => value === null ? '' : value ));
  }
}

Exception mapping

다른 RxJS의 catchError() 연산자는 thrown exception을 override할 수 있다.

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

@Injectable()
export class ErrorsInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next
      .handle()
      .pipe(
          // 핸들러 메서드에서 발생한 에러를 가로채고, 이를 BadGatewayException으로 변환
        catchError(err => throwError(() => new BadGatewayException())),
      );
  }
}

Stream overriding

 

때때로 완전히 handler의 호출을 막고, 대신에 다른 값을 반환하기를 원하는 이유가 몇 있다. 명백한 예는 response time을 항샹시키기 위해 cache를 구현하는 것 이다. 간단한 simple cache interceptor를 보자. 이는 cache로 부터 interceptor의 response를 반환한다. cache interceptor를 사용하면 response time을 개선하기 위해 cached data를 반환할 수 있다. cache interceptor는 request에 대한 response를 cache하고, 동일한 request가 들어올 때 cached된 데이터를 반환하여 서버의 부담을 줄일 수 있다. 현실적인 예로, 우리는 TTL, cache invalidation, cache size...와 같은 다른 요소들을 고려해야 하지만, 이는 이 논의의 범위를 벗어난다. 여기서 main concept에 를 보여주는 간단한 예시가 있다.

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

@Injectable()
export class CacheInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const isCached = true;
    if (isCached) {
      return of([]);
    }
    return next.handle();
  }
}

위에서 CacheInterceptor는 하드코딩된 isCached 변수와 하드코딩된 [ ]을 가진다. 여기서 핵심 포인트는 RxJS의 of() 연산자로 인해 생성된 new stream을 반환하는 것 이다. 그러므로, route handler는 호출되지 않는다. 누군가 CacheInterceptor를 사용하는 endpoint를 호출하면, response(하드코딩된 빈 배열)이 즉시 반환된다. 일반적인 해결책으로는, Reflector를 사용하여 새로운 custom decorator을 만드는 것 이다. reflector

More operators

RxJS operator를 사용하여 stream을 조작하는 것은 많은 가능성을 제공해 준다. 흔한 use case를 생각해보자. 만일 route requests에서 timeouts를 handle하고 싶다고 하자. 만일 특정 시간이 지난 후에도, endpoint가 아무것도 반환하지 않으면 error response로 종료하고 싶을 수 있다. 다음 코드는 이러한 기능을 구현하는 방법을 보여준다.

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<any> {
    return next.handle().pipe(
      // 요청이 5초 내에 완료되지 않으면 TimeoutError를 발생
      timeout(5000),
      catchError(err => {
        if (err instanceof TimeoutError) {
          return throwError(() => new RequestTimeoutException());
        }
        return throwError(() => err);
      }),
    );
  };
};

5초 후에, request processing은 취소될 것 이다. RequestTimeoutException이 던져지기 전에 custom logic또한 추가할 수 있다.