Request Lifecycle

export const trace: string[] = [];
export const mark = (stage: string): void => {
  trace.push(stage);
  console.log(`[lifecycle] ${stage}`);
};

import {
  ArgumentMetadata, ArgumentsHost, BadRequestException, CallHandler, CanActivate, Catch,
  ExceptionFilter, ExecutionContext, HttpException, HttpStatus, Injectable, NestInterceptor,
  NestMiddleware, PipeTransform, Type,
} from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';
import { Observable, tap } from 'rxjs';
import { mark } from './trace.js';

@Injectable()
export class ModuleMiddleware implements NestMiddleware {
  use(req: any, _res: any, next: () => void): void {
    mark(`middleware:module ${req.method} ${req.url}`);
    next();
  }
}

export function globalMiddleware(req: any, _res: any, next: () => void): void {
  mark('middleware:global (app.use)');
  next();
}

export function makeGuard(label: string): Type<CanActivate> {
  @Injectable()
  class LogGuard implements CanActivate {
    canActivate(context: ExecutionContext): boolean {
      mark(`guard:${label}`);
      const request = context.switchToHttp().getRequest();
      // 403 when the header "x-deny" names this guard
      return request.headers['x-deny'] !== label;
    }
  }
  return LogGuard;
}

export function makeInterceptor(label: string): Type<NestInterceptor> {
  @Injectable()
  class LogInterceptor implements NestInterceptor {
    intercept(_context: ExecutionContext, next: CallHandler): Observable<unknown> {
      mark(`interceptor:${label}:before`);
      return next.handle().pipe(
        tap({
          next: () => mark(`interceptor:${label}:after`),
          error: (e: Error) => mark(`interceptor:${label}:error(${e.constructor.name})`),
        }),
      );
    }
  }
  return LogInterceptor;
}

export class LogPipe implements PipeTransform {
  constructor(private readonly label: string) {}
  transform(value: unknown, metadata: ArgumentMetadata): unknown {
    mark(`pipe:${this.label}[${metadata.type}]`);
    return value;
  }
}

export class RejectPipe implements PipeTransform {
  transform(value: string): string {
    mark('pipe:reject');
    if (value === 'bad') throw new BadRequestException('rejected by pipe');
    return value;
  }
}

export class TeapotError extends HttpException {
  constructor() {
    super('I am a teapot', HttpStatus.I_AM_A_TEAPOT);
  }
}

export function makeFilter(label: string, exception?: Type<Error>): Type<ExceptionFilter> {
  @Catch(...(exception ? [exception] : []))
  class LogFilter implements ExceptionFilter {
    constructor(private readonly httpAdapterHost: HttpAdapterHost) {}

    catch(error: Error, host: ArgumentsHost): void {
      mark(`filter:${label}(${error.constructor.name})`);
      const status = error instanceof HttpException ? error.getStatus() : 500;
      // Platform-agnostic reply: works for Express, Fastify and for errors thrown in
      // Fastify middleware, where the response is still the raw Node.js ServerResponse.
      this.httpAdapterHost.httpAdapter.reply(
        host.switchToHttp().getResponse(),
        { handledBy: label, message: error.message },
        status,
      );
    }
  }
  return LogFilter;
}

import {
  BadRequestException, Body, Controller, ForbiddenException, Get, Param, Post, Query,
  UseFilters, UseGuards, UseInterceptors, UsePipes,
} from '@nestjs/common';
import { LifecycleService } from './lifecycle.service.js';
import { LogPipe, RejectPipe, TeapotError, makeFilter, makeGuard, makeInterceptor } from './components.js';
import { mark } from './trace.js';

const ControllerGuard = makeGuard('controller');
const RouteGuard = makeGuard('route');
const ControllerInterceptor = makeInterceptor('controller');
const RouteInterceptor = makeInterceptor('route');
const ControllerFilter = makeFilter('controller', BadRequestException);
const RouteFilter = makeFilter('route', TeapotError);

@UseGuards(ControllerGuard)
@UseInterceptors(ControllerInterceptor)
@UsePipes(new LogPipe('controller'))
@UseFilters(ControllerFilter)
@Controller('lifecycle')
export class LifecycleController {
  constructor(private readonly service: LifecycleService) {}

  @Post(':id')
  @UseGuards(RouteGuard)
  @UseInterceptors(RouteInterceptor)
  @UsePipes(new LogPipe('route'))
  @UseFilters(RouteFilter)
  handler(
    @Body(new LogPipe('param:body')) body: { shout?: boolean },
    @Param('id', new LogPipe('param:id')) id: string,
    @Query('q', new LogPipe('param:query')) _q: string,
  ) {
    mark('handler');
    if (id === 'teapot') throw new TeapotError();
    if (id === 'boom') throw new Error('unexpected');
    return this.service.find(id, body?.shout ?? false);
  }

  @Get('strict/:id')
  strict(@Param('id', new RejectPipe()) id: string) {
    mark('handler');
    return { id };
  }

  @Get('forbidden')
  forbidden() {
    mark('handler');
    throw new ForbiddenException();
  }
}

import { Injectable } from '@nestjs/common';
import { mark } from './trace.js';

@Injectable()
export class LifecycleService {
  find(id: string, shout: boolean): { id: string; shout: boolean } {
    mark('service');
    return { id, shout };
  }
}

import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_PIPE } from '@nestjs/core';
import { LifecycleController } from './lifecycle.controller.js';
import { LifecycleService } from './lifecycle.service.js';
import { LogPipe, ModuleMiddleware, makeFilter, makeGuard, makeInterceptor } from './components.js';

@Module({
  controllers: [LifecycleController],
  providers: [
    LifecycleService,
    // Globally bound through DI: these can inject providers (app.useGlobal* cannot).
    { provide: APP_GUARD, useClass: makeGuard('global') },
    { provide: APP_INTERCEPTOR, useClass: makeInterceptor('global') },
    { provide: APP_PIPE, useValue: new LogPipe('global') },
    { provide: APP_FILTER, useClass: makeFilter('global') },
  ],
})
export class LifecycleModule implements NestModule {
  configure(consumer: MiddlewareConsumer): void {
    consumer.apply(ModuleMiddleware).forRoutes(LifecycleController);
  }
}

import { INestApplication } from '@nestjs/common';
import { globalMiddleware } from './components.js';

// Global middleware bound with app.use() runs before any module-bound middleware.
export function setup(app: INestApplication): void {
  app.use(globalMiddleware);
}

// main-express.ts
//   const app = await NestFactory.create(LifecycleModule);
//   setup(app);
//   await app.listen(3000);

// main-fastify.ts
//   const app = await NestFactory.create<NestFastifyApplication>(LifecycleModule, new FastifyAdapter());
//   setup(app);
//   await app.listen(3000, '0.0.0.0');

curl -X POST 'http://localhost:3000/lifecycle/42?q=x' -H 'content-type: application/json' -d '{"shout":true}'

{ "id": "42", "shout": true }

function middlewareFor(name: string) {
  @Injectable()
  class M implements NestMiddleware {
    use(_req: unknown, _res: unknown, next: () => void): void {
      mark(`middleware:${name}`);
      next();
    }
  }
  return M;
}

@Module({})
export class DeepModule implements NestModule {
  configure(consumer: MiddlewareConsumer): void {
    consumer.apply(middlewareFor('DeepModule')).forRoutes('{*splat}');
  }
}

@Module({ imports: [DeepModule] })
export class FeatureModule implements NestModule {
  configure(consumer: MiddlewareConsumer): void {
    consumer.apply(middlewareFor('FeatureModule')).forRoutes('{*splat}');
  }
}

@Global()
@Module({})
export class CoreModule implements NestModule {
  configure(consumer: MiddlewareConsumer): void {
    consumer.apply(middlewareFor('CoreModule (@Global)')).forRoutes('{*splat}');
  }
}

@Module({
  imports: [CoreModule, FeatureModule],
  controllers: [PingController],
})
export class OrderingModule implements NestModule {
  configure(consumer: MiddlewareConsumer): void {
    consumer.apply(middlewareFor('RootModule')).forRoutes('{*splat}');
  }
}

middleware:CoreModule (@Global)
middleware:RootModule
middleware:FeatureModule
middleware:DeepModule

// 1. Through a module: constructor injection works.
@Module({
  providers: [{ provide: APP_GUARD, useClass: ApiKeyGuard }],
})
export class SecurityModule {}

// 2. Outside any module: ApiKeyGuard would have to be built by hand, without DI.
const app = await NestFactory.create(AppModule);
app.useGlobalGuards(new ApiKeyGuard(/* nothing can be injected here */));

import { HttpAdapterHost } from '@nestjs/core';

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  constructor(private readonly httpAdapterHost: HttpAdapterHost) {}

  catch(exception: unknown, host: ArgumentsHost): void {
    const { httpAdapter } = this.httpAdapterHost;
    const ctx = host.switchToHttp();
    const status = exception instanceof HttpException ? exception.getStatus() : 500;
    httpAdapter.reply(ctx.getResponse(), { statusCode: status }, status);
  }
}