10. El ciclo de petición: middleware, guards, interceptores, pipes y filtros

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

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

  // Registro global sin inyección de dependencias: Nest no crea estas
  // instancias, las creas tú. Válido para piezas SIN dependencias.
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));

  // Se pueden pasar varios; se ejecutan en el orden en que aparecen.
  // app.useGlobalInterceptors(new RequestIdInterceptor(), new TimeoutInterceptor());

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

import { Module } from '@nestjs/common';
import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_PIPE } from '@nestjs/core';

@Module({
  imports: [ConfigModule.forRoot(), MikroOrmModule.forRoot(), TasksModule],
  providers: [
    // ── Guards ──────────────────────────────────────────────────────────
    // JwtAuthGuard puede inyectar JwtService, ConfigService y el EM.
    { provide: APP_GUARD, useClass: JwtAuthGuard },
    { provide: APP_GUARD, useClass: RolesGuard },   // se ejecuta DESPUÉS

    // ── Interceptores ───────────────────────────────────────────────────
    { provide: APP_INTERCEPTOR, useClass: RequestLoggingInterceptor },
    { provide: APP_INTERCEPTOR, useClass: TransformResponseInterceptor },

    // ── Pipe de validación con opciones y con inyección disponible ──────
    {
      provide: APP_PIPE,
      useFactory: (config: ConfigService) => new ValidationPipe({
        whitelist: true,
        forbidNonWhitelisted: true,
        transform: true,
        // En producción no revelamos qué campos esperábamos.
        disableErrorMessages: config.get('NODE_ENV') === 'production',
      }),
      inject: [ConfigService],
    },

    // ── Filtros: el orden de declaración importa, ver más abajo ─────────
    { provide: APP_FILTER, useClass: ProblemDetailsFilter },
    { provide: APP_FILTER, useClass: MikroOrmExceptionFilter },
  ],
})
export class AppModule {}

@UseGuards(RolesGuard)                    // ámbito: toda la clase
@UseInterceptors(ClassSerializerInterceptor)
@UseFilters(TasksExceptionFilter)
@Controller('projects/:projectId/tasks')
export class TasksController {
  @Get()
  @Roles('MIEMBRO')                       // metadato leído por RolesGuard
  listar(@Query() filtros: ListarTareasDto) { /* … */ }

  @Patch(':id')
  @Roles('EDITOR')
  @UseGuards(TaskOwnerGuard)               // ámbito: solo este método
  @UsePipes(new ValidationPipe({ groups: ['actualizar'] }))
  actualizar(
    @Param('id', ParseUUIDPipe) id: string,        // ámbito: un parámetro
    @Body() dto: ActualizarTareaDto,
  ) { /* … */ }
}

// Se puede pasar la CLASE (Nest la instancia y la inyecta: preferible)
//   @UseGuards(TaskOwnerGuard)
// o una INSTANCIA (útil solo para configurar opciones, sin inyección)
//   @UsePipes(new ValidationPipe({ transform: true }))

import { MiddlewareConsumer, Module, NestModule, RequestMethod } from '@nestjs/common';

@Module({ imports: [TasksModule, AuthModule, WebhooksModule] })
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer): void {
    // ── 1 · Varios middleware en un solo apply: se ejecutan EN ESTE ORDEN
    consumer
      .apply(RequestIdMiddleware, LoggerMiddleware, MikroOrmContextMiddleware)
      // exclude SIEMPRE antes de forRoutes; si lo pones después, se ignora
      .exclude(
        { path: 'health', method: RequestMethod.GET },
        { path: 'metrics', method: RequestMethod.GET },
      )
      .forRoutes('*');   // todas las rutas

    // ── 2 · Otro apply: se ejecuta después del bloque anterior
    consumer
      .apply(RawBodyMiddleware)
      .forRoutes({ path: 'webhooks/stripe', method: RequestMethod.POST });

    // ── 3 · forRoutes acepta tres formas de referirse a las rutas:
    consumer
      .apply(SlowDownMiddleware)
      .forRoutes(
        'auth/login',                                      // cadena
        { path: 'auth/reset', method: RequestMethod.POST }, // objeto con método
        AuthController,                                     // clase controlador
      );
  }
}

import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';

export interface AlcanceDePeticion {
  requestId: string;
  usuarioId?: string;
  inicio: bigint;
}
export const almacen = new AsyncLocalStorage<AlcanceDePeticion>();
export const contextoActual = () => almacen.getStore();

@Injectable()
export class RequestIdMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction): void {
    const entrante = req.header('x-request-id');
    // NUNCA aceptes el valor del cliente tal cual: iría a los logs y a la
    // respuesta. Un valor con saltos de línea permite falsificar entradas
    // de log (log forging); uno de 10 MB llena el disco.
    const valido = typeof entrante === 'string' && /^[\w-]{8,64}$/.test(entrante);
    const requestId = valido ? entrante : randomUUID();

    res.setHeader('x-request-id', requestId);
    // La clave está aquí: run() envuelve TODA la continuación asíncrona,
    // así que el store sigue disponible dentro de guards, servicios,
    // callbacks de MikroORM y filtros de excepción.
    almacen.run({ requestId, inicio: process.hrtime.bigint() }, () => next());
  }
}

import { MikroORM, RequestContext } from '@mikro-orm/core';

@Injectable()
export class MikroOrmContextMiddleware implements NestMiddleware {
  constructor(private readonly orm: MikroORM) {}

  use(_req: Request, _res: Response, next: NextFunction): void {
    // Crea un fork del EntityManager y lo asocia al contexto asíncrono
    // de esta petición. Todo lo que ocurra dentro de next() usará ese fork.
    RequestContext.create(this.orm.em, next);
  }
}

// IMPORTANTE: MikroOrmModule.forRoot() ya registra este middleware por ti
// (opción registerRequestContext, activada por defecto). Solo lo escribirías
// a mano si necesitas controlar su posición respecto a otros middleware.
//
// Fuera del ciclo HTTP no hay petición y por tanto no hay contexto: en tareas
// programadas, consumidores de cola o comandos de CLI hay que abrirlo
// explícitamente con el decorador @CreateRequestContext() (MikroORM 6;
// se llamaba @UseRequestContext() en la versión 5). Si lo olvidas, verás
// "Using global EntityManager instance methods for context specific actions
// is disallowed", que es exactamente la protección funcionando.

import helmet from 'helmet';
import compression from 'compression';
import { json, urlencoded } from 'express';

const app = await NestFactory.create(AppModule);

app.use(helmet());          // ~15 cabeceras de seguridad, coste despreciable
app.use(compression());     // gzip/brotli sobre respuestas grandes

// Límites de tamaño del cuerpo: el valor por defecto de Express es 100 kb.
// Subirlo "por si acaso" convierte cada endpoint en un vector de DoS.
app.use(json({ limit: '1mb' }));
app.use(urlencoded({ extended: true, limit: '1mb' }));

app.enableCors({ origin: ['https://app.ejemplo.com'], credentials: true });

// 1 · Nest guarda el buffer original si se lo pides al crear la app.
const app = await NestFactory.create(AppModule, { rawBody: true });

// 2 · En el manejador se recupera con el tipo RawBodyRequest.
import { RawBodyRequest, Controller, Post, Req, Headers } from '@nestjs/common';

@Controller('webhooks')
export class WebhooksController {
  @Post('stripe')
  recibir(
    @Req() req: RawBodyRequest<Request>,
    @Headers('stripe-signature') firma: string,
  ) {
    const crudo = req.rawBody;            // Buffer intacto, byte a byte
    if (!crudo) throw new BadRequestException('Falta el cuerpo');
    // La verificación de firma se hace SOBRE EL BUFFER, nunca sobre el JSON
    // reserializado, y con comparación en tiempo constante.
    const evento = this.stripe.webhooks.constructEvent(crudo, firma, this.secreto);
    return this.procesar(evento);
  }
}
// Alternativa para casos raros: crear la app con bodyParser: false y montar
// express.raw({ type: 'application/json' }) solo en la ruta del webhook.

export interface CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean>;
}

// ExecutionContext extiende ArgumentsHost y añade lo que hace posible la
// autorización declarativa:
interface ExecutionContext extends ArgumentsHost {
  getClass<T>(): Type<T>;          // el controlador: TasksController
  getHandler(): Function;          // el método: actualizar()
  // heredado de ArgumentsHost:
  getType<T extends string>(): T;  // 'http' | 'rpc' | 'ws' | 'graphql'
  switchToHttp(): HttpArgumentsHost;
  switchToRpc(): RpcArgumentsHost;
  switchToWs(): WsArgumentsHost;
  getArgs<T extends any[]>(): T;   // los argumentos crudos del handler
}

// ── FORMA CLÁSICA: SetMetadata con una clave de tipo cadena ─────────────
export const ROLES_KEY = 'roles';
export const Roles = (...roles: Rol[]) => SetMetadata(ROLES_KEY, roles);
// Lectura: hay que repetir la clave y anotar el genérico a mano. Si te
// equivocas en la cadena, el guard lee undefined y no falla: solo deja
// de aplicar la regla, que es el peor tipo de error posible.
const roles = this.reflector.getAllAndOverride<Rol[]>(ROLES_KEY, [
  ctx.getHandler(), ctx.getClass(),
]);

// ── FORMA MODERNA: Reflector.createDecorator (Nest 10 y posteriores) ────
export const Roles = Reflector.createDecorator<Rol[]>();
// Uso idéntico en el controlador:  @Roles(['ADMIN'])
// Lectura con tipado automático y sin claves de texto:
const roles = this.reflector.getAllAndOverride(Roles, [
  ctx.getHandler(), ctx.getClass(),
]);   // roles: Rol[] | undefined, inferido

// Matiz de firma: createDecorator<T>() genera un decorador que recibe UN
// argumento de tipo T. Para @Roles('ADMIN', 'EDITOR') con parámetros
// variádicos sigue haciendo falta SetMetadata, o se declara como array.
// Con transform se puede normalizar el valor en el momento de decorar:
export const Roles = Reflector.createDecorator<string[], Rol[]>({
  transform: (valor) => valor.map((r) => r.toUpperCase() as Rol),
});

// ── Comparación de estrategias de combinación ───────────────────────────
// @Permisos(['tarea:leer'])  en la CLASE
// @Permisos(['tarea:editar']) en el MÉTODO
// getAllAndOverride → ['tarea:editar']                  (el método manda)
// getAllAndMerge    → ['tarea:editar', 'tarea:leer']    (se acumulan)
// Elegir mal aquí es un fallo de seguridad silencioso: con merge, un
// método NO PUEDE restringir lo que abrió el controlador.

import { timingSafeEqual } from 'node:crypto';

@Injectable()
export class ApiKeyGuard implements CanActivate {
  private readonly claves: Buffer[];

  constructor(config: ConfigService) {
    // Se leen UNA vez al construir el guard, no en cada petición.
    this.claves = config
      .getOrThrow<string>('API_KEYS')
      .split(',')
      .map((k) => Buffer.from(k.trim(), 'utf8'));
  }

  canActivate(ctx: ExecutionContext): boolean {
    const req = ctx.switchToHttp().getRequest<Request>();
    const recibida = req.header('x-api-key');
    if (!recibida) throw new UnauthorizedException('Falta la cabecera x-api-key');

    const buf = Buffer.from(recibida, 'utf8');
    const valida = this.claves.some(
      // timingSafeEqual exige longitudes iguales o lanza; comprobarlas
      // antes filtra la longitud, que es información despreciable.
      (k) => k.length === buf.length && timingSafeEqual(k, buf),
    );
    if (!valida) throw new UnauthorizedException('Clave de API no válida');
    return true;
  }
}

providers: [
  // 1 · Barato: solo criptografía en memoria, sin base de datos.
  { provide: APP_GUARD, useClass: JwtAuthGuard },
  // 2 · Barato: lee metadatos y compara arrays en memoria.
  { provide: APP_GUARD, useClass: RolesGuard },
  // 3 · Caro: consulta la base de datos. Solo se llega aquí si 1 y 2 han
  //     pasado, así que un atacante sin token NUNCA provoca la consulta.
  { provide: APP_GUARD, useClass: PermisosGuard },
]
// Los guards se evalúan en secuencia y el primero que deniega corta la
// cadena. Ordenar de barato a caro no es micro-optimización: es la
// diferencia entre absorber una avalancha de peticiones sin token y
// tumbar la base de datos con ella.

@Injectable()
export class TaskOwnerGuard implements CanActivate {
  constructor(private readonly em: EntityManager) {}

  async canActivate(ctx: ExecutionContext): Promise<boolean> {
    const req = ctx.switchToHttp().getRequest<Request>();
    if (!req.user) throw new UnauthorizedException();

    const { projectId, id } = req.params;

    // La pertenencia va EN el where. Si escribiéramos findOne(Task, { id })
    // y luego comprobásemos task.project.id === projectId, tendríamos que
    // acordarnos de hacerlo en cada endpoint. Aquí es imposible olvidarlo.
    const tarea = await this.em.findOne(
      Task,
      { id, project: { id: projectId, members: { user: req.user.id } } },
      { populate: ['project'] },
    );

    // 404 y no 403 de forma deliberada: un 403 confirmaría que la tarea
    // existe, lo que ya es una fuga de información en recursos privados.
    if (!tarea) throw new NotFoundException('Tarea no encontrada');

    // Se guarda en la petición para que el manejador no repita la consulta.
    // Esto es una optimización REAL: ahorra un viaje a la base de datos por
    // petición. El coste es acoplamiento: el servicio recibe la entidad ya
    // cargada y hay que documentarlo (ver 10.10).
    req.recurso = tarea;
    return true;
  }
}

export interface NestInterceptor<T = any, R = any> {
  intercept(
    context: ExecutionContext,
    next: CallHandler<T>,
  ): Observable<R> | Promise<Observable>;
}
export interface CallHandler<T = any> {
  handle(): Observable<T>;   // ejecuta el resto de la cadena y el manejador
}

// handle() es EJECUCIÓN DIFERIDA. Nada ocurre hasta que alguien se
// suscribe al observable devuelto; Nest se suscribe al final. Por eso:
//   · el código ANTES de next.handle() corre antes del manejador
//   · los operadores encadenados a handle() corren DESPUÉS
//   · si no devuelves el observable, o no llamas a handle(), el manejador
//     NO se ejecuta nunca y la petición se queda colgada

export interface RespuestaApi<T> {
  data: T;
  meta: { requestId?: string; timestamp: string; duracionMs?: number };
}

@Injectable()
export class TransformResponseInterceptor<T>
  implements NestInterceptor<T, RespuestaApi<T> | T>
{
  intercept(ctx: ExecutionContext, next: CallHandler<T>) {
    // Solo HTTP: en WebSockets o RPC el envoltorio no tiene sentido.
    if (ctx.getType() !== 'http') return next.handle();

    const res = ctx.switchToHttp().getResponse<Response>();
    const inicio = process.hrtime.bigint();

    return next.handle().pipe(
      map((data) => {
        // Casos que NO se deben envolver, y son más de los que parece:
        // descargas de fichero, respuestas ya envueltas y cuerpos vacíos.
        if (data instanceof StreamableFile) return data;
        if (res.statusCode === 204 || data === undefined) return data;

        return {
          data,
          meta: {
            requestId: contextoActual()?.requestId,
            timestamp: new Date().toISOString(),
            duracionMs: Number(process.hrtime.bigint() - inicio) / 1e6,
          },
        };
      }),
    );
  }
}
// Decisión de diseño: los ERRORES no pasan por aquí (el flujo termina en
// error, no en valor). Su formato lo define el filtro de excepción, y hay
// que cuidar que ambos sean coherentes entre sí. Ver 10.8.

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  private readonly logger = new Logger(LoggingInterceptor.name);

  intercept(ctx: ExecutionContext, next: CallHandler) {
    const req = ctx.switchToHttp().getRequest<Request>();
    const inicio = process.hrtime.bigint();
    const ms = () => Number(process.hrtime.bigint() - inicio) / 1e6;

    // Aquí SÍ tenemos el manejador: se puede registrar el caso de uso
    // real, no solo la ruta. Es oro puro para depurar en producción.
    const etiqueta = `${ctx.getClass().name}.${ctx.getHandler().name}`;

    return next.handle().pipe(
      tap({
        next: () => this.logger.log({
          msg: 'ok', etiqueta, metodo: req.method, ruta: req.url,
          ms: +ms().toFixed(1), requestId: contextoActual()?.requestId,
        }),
        error: (e) => this.logger.warn({
          msg: 'error', etiqueta, ms: +ms().toFixed(1),
          error: e?.constructor?.name, requestId: contextoActual()?.requestId,
        }),
      }),
      // Se ejecuta también si el cliente aborta la petición, caso que
      // tap({next}) y tap({error}) no cubren.
      finalize(() => this.metricas.observarDuracion(etiqueta, ms())),
    );
  }
}

export const TiempoLimite = Reflector.createDecorator<number>();

@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  constructor(private readonly reflector: Reflector) {}

  intercept(ctx: ExecutionContext, next: CallHandler) {
    // El umbral es configurable por endpoint: un informe pesado necesita
    // más margen que un GET por identificador.
    const ms = this.reflector.get(TiempoLimite, ctx.getHandler()) ?? 5_000;

    return next.handle().pipe(
      timeout(ms),
      catchError((e) =>
        e instanceof TimeoutError
          ? throwError(() => new RequestTimeoutException(
              `La operación superó ${ms} ms`))
          : throwError(() => e),   // cualquier otro error se deja pasar
      ),
    );
  }
}
// LÍMITE IMPORTANTE: timeout() deja de esperar la respuesta, pero NO
// cancela el trabajo que ya está en marcha. La consulta SQL sigue
// ejecutándose en el servidor de base de datos y el INSERT puede
// completarse igualmente. Para cancelar de verdad hace falta un
// AbortSignal propagado hasta el driver, o un statement_timeout en
// PostgreSQL. Un timeout de interceptor protege al CLIENTE, no al backend.

@Injectable()
export class UserScopedCacheInterceptor implements NestInterceptor {
  constructor(
    @Inject(CACHE_MANAGER) private readonly cache: Cache,
    private readonly reflector: Reflector,
  ) {}

  async intercept(ctx: ExecutionContext, next: CallHandler) {
    const ttl = this.reflector.get(CacheTtl, ctx.getHandler());
    const req = ctx.switchToHttp().getRequest<Request>();
    if (!ttl || req.method !== 'GET') return next.handle();

    // La clave INCLUYE al usuario. Olvidarlo es el bug de caché clásico:
    // el primer usuario que pide /me deja su respuesta para los demás.
    const clave = `resp:${req.user?.id ?? 'anon'}:${req.originalUrl}`;

    const guardada = await this.cache.get(clave);
    // of() devuelve un valor SIN llamar a next.handle(): el manejador y
    // el servicio no se ejecutan en absoluto. Ahí está todo el ahorro.
    if (guardada !== undefined) return of(guardada);

    return next.handle().pipe(tap((valor) => this.cache.set(clave, valor, ttl)));
  }
}

// Registro global (recomendado): en AppModule
{ provide: APP_INTERCEPTOR, useClass: ClassSerializerInterceptor }

export class Usuario {
  id!: string;
  email!: string;
  @Exclude() passwordHash!: string;              // nunca se serializa
  @Expose() get nombreCompleto(): string {       // campo calculado
    return `${this.nombre} ${this.apellidos}`;
  }
  @Transform(({ value }) => value?.toISOString()) creadoEn!: Date;
}

// Opciones por endpoint:
@SerializeOptions({ groups: ['admin'], excludeExtraneousValues: true })
@Get(':id') ver(@Param('id') id: string): Promise<Usuario> { … }

// ── TRES TRAMPAS DOCUMENTADAS ──────────────────────────────────────────
// 1 · Solo funciona si devuelves una INSTANCIA de la clase. Si el servicio
//     hace un `select` con QueryBuilder y devuelve objetos planos, los
//     decoradores no se aplican y @Exclude() no protege nada.
// 2 · Si devuelves una entidad de MikroORM, la serialización puede tocar
//     relaciones no cargadas y provocar consultas inesperadas (N+1) o
//     errores de proxy no inicializado. Devuelve DTOs de salida.
// 3 · Con @Res() sin passthrough no se ejecuta: te has salido del ciclo.

@Injectable()
export class TransactionInterceptor implements NestInterceptor {
  private static readonly MUTACIONES = ['POST', 'PATCH', 'PUT', 'DELETE'];
  constructor(private readonly em: EntityManager) {}

  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    const req = ctx.switchToHttp().getRequest<Request>();
    if (!TransactionInterceptor.MUTACIONES.includes(req.method)) {
      return next.handle();
    }

    return from(
      // em.transactional() crea un fork y lo propaga por el contexto
      // asíncrono (TransactionContext). Los servicios que inyectan
      // EntityManager participan en ESTA transacción sin recibirla como
      // parámetro: no hay que ensuciar las firmas del dominio.
      this.em.transactional(async () => {
        // firstValueFrom convierte el observable en promesa. Si el
        // manejador lanza, la promesa rechaza y MikroORM hace ROLLBACK.
        return firstValueFrom(next.handle());
      }),
    );
  }
}
// ── LO QUE HAY QUE SABER ANTES DE USARLO ───────────────────────────────
// · La transacción se COMMITEA antes de que corran los interceptores
//   más externos. Un error en la serialización posterior NO hará rollback:
//   el cliente verá un 500 con los datos ya guardados.
// · firstValueFrom rompe el streaming: solo sirve para respuestas con un
//   único valor. No lo apliques a endpoints que devuelvan StreamableFile.
// · Mantiene una conexión del pool ocupada durante TODA la petición,
//   incluida cualquier llamada HTTP externa que haga el servicio. Una
//   transacción abierta esperando a una pasarela de pago es un desastre
//   de concurrencia y una fuente segura de deadlocks.
// · ALTERNATIVA PREFERIBLE en dominios complejos: abrir la transacción en
//   el caso de uso con em.transactional(), donde sí se sabe qué operaciones
//   forman una unidad atómica. El límite transaccional es una decisión de
//   negocio, no de transporte.

export interface PipeTransform<T = any, R = any> {
  transform(value: T, metadata: ArgumentMetadata): R;   // puede ser async
}
export interface ArgumentMetadata {
  type: 'body' | 'query' | 'param' | 'custom';  // de qué decorador viene
  metatype?: Type<unknown>;   // el tipo declarado en TypeScript, si existe
  data?: string;              // el argumento del decorador: @Param('id') → 'id'
}

// ── PIPE DE TRANSFORMACIÓN: cambia el valor, no juzga ──────────────────
@Injectable()
export class TrimPipe implements PipeTransform<unknown, unknown> {
  transform(valor: unknown, { type }: ArgumentMetadata): unknown {
    if (type !== 'body' || valor === null || typeof valor !== 'object') return valor;
    // Recortar espacios en la entrada evita el clásico "  ana@ejemplo.com "
    // que crea usuarios duplicados y no encuentra al iniciar sesión.
    return Object.fromEntries(
      Object.entries(valor).map(([k, v]) => [k, typeof v === 'string' ? v.trim() : v]),
    );
  }
}

// ── PIPE DE VALIDACIÓN: no cambia el valor, decide si es aceptable ─────
@Injectable()
export class ParseObjectIdPipe implements PipeTransform<string, string> {
  transform(valor: string, metadata: ArgumentMetadata): string {
    if (!/^[0-9a-f]{24}$/i.test(valor)) {
      // El mensaje incluye QUÉ parámetro falla usando metadata.data: es la
      // diferencia entre un error accionable y un "Bad Request" inútil.
      throw new BadRequestException(
        `El parámetro '${metadata.data}' no es un ObjectId válido`);
    }
    return valor;
  }
}
// Un pipe puede hacer las dos cosas (ValidationPipe transforma Y valida),
// pero conviene saber cuál es su intención principal: los de validación
// deben devolver el valor intacto para no sorprender a quien los combine.

@Get()
listar(
  // El orden ES la cadena: primero rellena el hueco, luego convierte.
  @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
  @Query('limit', new DefaultValuePipe(20), ParseIntPipe) limit: number,
  // Sin optional:true, ausencia de parámetro provoca 400 en lugar de undefined.
  @Query('tags', new ParseArrayPipe({ items: String, separator: ',', optional: true }))
  tags?: string[],
  @Query('estado', new ParseEnumPipe(EstadoTarea, { optional: true }))
  estado?: EstadoTarea,
) { /* … */ }

@Get(':id')
// Validar el formato ANTES de consultar evita que un 'DROP TABLE' llegue al
// driver y, sobre todo, convierte un 500 por tipo inválido en un 400 limpio.
ver(@Param('id', new ParseUUIDPipe({ version: '4' })) id: string) { /* … */ }

@Post(':id/adjunto')
@UseInterceptors(FileInterceptor('fichero'))
subir(
  @UploadedFile(new ParseFilePipe({
    validators: [
      new MaxFileSizeValidator({ maxSize: 5 * 1024 * 1024 }),
      new FileTypeValidator({ fileType: 'application/pdf' }),
    ],
    fileIsRequired: true,
  })) fichero: Express.Multer.File,
) { /* … */ }
// FileTypeValidator comprueba el MIME que DECLARA el cliente: es una
// comodidad, no una medida de seguridad. Verifica la firma real del fichero
// en el servicio si el contenido importa.

class DireccionDto {
  @IsString() @Length(1, 200) calle!: string;
  @Matches(/^\d{5}$/, { message: 'El código postal debe tener 5 dígitos' })
  codigoPostal!: string;
}

export class CrearFacturaDto {
  @IsEnum(TipoCliente) tipo!: TipoCliente;

  // Condicional: el NIF solo se exige (y solo se valida) para empresas.
  @ValidateIf((o: CrearFacturaDto) => o.tipo === TipoCliente.EMPRESA)
  @IsString() @Matches(/^[A-Z]\d{8}$/) nif?: string;

  // Objeto anidado: hacen falta LAS DOS anotaciones.
  // · @Type indica a class-transformer qué clase instanciar.
  // · @ValidateNested le dice a class-validator que entre dentro.
  // Sin @Type, el hijo sigue siendo un objeto plano; class-validator no
  // encuentra metadatos y (con forbidUnknownValues activo) lanza un error
  // confuso del tipo "an unknown value was passed to the validate function".
  @ValidateNested() @Type(() => DireccionDto) direccion!: DireccionDto;

  // Array de objetos anidados: each: true en el ValidateNested.
  @IsArray() @ArrayNotEmpty() @ArrayMaxSize(100)
  @ValidateNested({ each: true }) @Type(() => LineaDto) lineas!: LineaDto[];

  // Array de primitivos: each: true en el decorador del tipo.
  @IsOptional() @IsUUID('4', { each: true }) etiquetas?: string[];
}

// 1 · La restricción es un provider de Nest, así que puede inyectar el EM.
@ValidatorConstraint({ name: 'EsUnico', async: true })
@Injectable()
export class EsUnicoConstraint implements ValidatorConstraintInterface {
  constructor(private readonly em: EntityManager) {}

  async validate(valor: unknown, args: ValidationArguments): Promise<boolean> {
    const [entidad, campo] = args.constraints as [EntityName<object>, string];
    if (valor === undefined || valor === null) return true;   // eso lo dice @IsOptional
    const existentes = await this.em.count(entidad, { [campo]: valor });
    return existentes === 0;
  }
  defaultMessage(args: ValidationArguments): string {
    return `Ya existe un registro con ${args.property} = ${args.value}`;
  }
}

export function EsUnico(entidad: EntityName<object>, campo: string, opts?: ValidationOptions) {
  return (objeto: object, propiedad: string) => registerDecorator({
    target: objeto.constructor, propertyName: propiedad,
    constraints: [entidad, campo], validator: EsUnicoConstraint,
    async: true, options: opts,
  });
}

// 2 · Sin esta línea en main.ts, class-validator instancia la restricción
//     con new y el EntityManager llega undefined. Es EL requisito olvidado.
useContainer(app.select(AppModule), { fallbackOnErrors: true });

// 3 · Uso:  @IsEmail() @EsUnico(Usuario, 'email') email!: string;
//
// ADVERTENCIA DE CONCURRENCIA: esto es una comprobación TOCTOU. Entre la
// validación y el INSERT hay una ventana en la que otra petición puede
// insertar el mismo valor. La validación mejora el mensaje de error; la
// GARANTÍA la da el índice único en la base de datos, y su violación se
// traduce a 409 en el filtro de excepción (ver 10.8.4). Hacen falta las dos.
// Coste añadido: una consulta por campo y por petición, también cuando el
// resto del DTO es inválido. Con muchos validadores asíncronos, considera
// mover la comprobación al caso de uso.

import { Expose, Transform, Type, plainToInstance } from 'class-transformer';

export class PaginacionDto {
  // @Type es la conversión declarativa correcta: solo este campo, solo a número.
  @IsOptional() @Type(() => Number) @IsInt() @Min(1) page: number = 1;

  @IsOptional() @Type(() => Number) @IsInt() @Min(1) @Max(100) limit: number = 20;

  // @Transform permite lógica arbitraria: normalizar, partir, sanear.
  @IsOptional() @IsIn(['ASC', 'DESC'])
  @Transform(({ value }) => String(value ?? 'DESC').toUpperCase())
  orden: 'ASC' | 'DESC' = 'DESC';

  // 'a,b,c' → ['a','b','c'] y también acepta ?tag=a&tag=b (array real).
  @IsOptional() @IsString({ each: true })
  @Transform(({ value }) => Array.isArray(value) ? value : String(value).split(','))
  tags?: string[];

  // Getters que el servicio y el repositorio consumen directamente. Solo
  // existen si ValidationPipe se configuró con transform: true.
  @Exclude() get offset(): number { return (this.page - 1) * this.limit; }
}

// Uso en el controlador: @Get() listar(@Query() q: PaginacionDto) { … }
// Y la reutilización por composición, no por herencia múltiple:
export class ListarTareasDto extends IntersectionType(PaginacionDto, FiltroTareasDto) {}

// plainToInstance es lo que ValidationPipe usa por debajo. Conviene conocerlo
// para los casos en que el dato NO entra por HTTP (una cola, un fichero CSV):
const dto = plainToInstance(PaginacionDto, mensaje.payload, {
  excludeExtraneousValues: false,   // true exige @Expose() en cada campo
});
await validateOrReject(dto);        // misma validación, fuera del ciclo HTTP

import { z, ZodSchema } from 'zod';

export class ZodValidationPipe implements PipeTransform {
  constructor(private readonly esquema: ZodSchema) {}

  transform(valor: unknown) {
    const r = this.esquema.safeParse(valor);
    if (!r.success) {
      throw new UnprocessableEntityException({
        title: 'Datos de entrada no válidos',
        // El árbol de errores de Zod ya viene con rutas y mensajes.
        errors: r.error.issues.map((i) => ({ campo: i.path.join('.'), mensaje: i.message })),
      });
    }
    return r.data;   // devuelve el valor YA convertido y tipado
  }
}

export const crearTareaSchema = z.object({
  titulo: z.string().trim().min(3).max(120),
  // La conversión es parte del esquema, no un decorador aparte.
  horas: z.coerce.number().int().min(0).max(999).optional(),
  etiquetas: z.array(z.string().uuid()).max(10).default([]),
  // Reglas entre campos, que con class-validator exigen un validador propio:
}).refine((d) => !d.fin || !d.inicio || d.fin > d.inicio, {
  message: 'La fecha de fin debe ser posterior al inicio', path: ['fin'],
});

// El tipo se DERIVA del esquema: imposible que se desincronicen.
export type CrearTareaDto = z.infer<typeof crearTareaSchema>;

// Uso: @Post() crear(@Body(new ZodValidationPipe(crearTareaSchema)) dto: CrearTareaDto)

// Firma: (response: string | object, status: number, options?: HttpExceptionOptions)
throw new HttpException('Servicio en mantenimiento', HttpStatus.SERVICE_UNAVAILABLE);

// Cuerpo estructurado en lugar de una simple cadena:
throw new BadRequestException({ code: 'TAREA_CERRADA', detalle: 'No admite cambios' });

// Nest 9 y posteriores admiten cause y description, muy útiles para no
// perder el error original al traducirlo:
throw new InternalServerErrorException('Fallo al contactar con el ERP', {
  cause: errorOriginal,          // se conserva para el log, NO se serializa
  description: 'ERP timeout',
});

// Dentro de un filtro:
exception.getStatus();     // number
exception.getResponse();   // string | object, tal cual se construyó
exception.cause;           // el error original, si se pasó

import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus, Logger } from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';

// @Catch() sin argumentos captura absolutamente todo, incluidos los errores
// que no heredan de Error. Es lo que se quiere en el filtro global.
@Catch()
export class ProblemDetailsFilter implements ExceptionFilter {
  private readonly logger = new Logger('Excepciones');
  constructor(
    // HttpAdapterHost hace el filtro independiente de Express o Fastify:
    // no usamos res.status().json(), sino la API del adaptador.
    private readonly adapterHost: HttpAdapterHost,
    private readonly config: ConfigService,
  ) {}

  catch(exception: unknown, host: ArgumentsHost): void {
    // Un filtro global también recibe errores de contextos no HTTP.
    if (host.getType() !== 'http') throw exception;

    const { httpAdapter } = this.adapterHost;
    const ctx = host.switchToHttp();
    const req = ctx.getRequest<Request>();
    const produccion = this.config.get('NODE_ENV') === 'production';
    const requestId = contextoActual()?.requestId;

    const { status, cuerpo } = this.normalizar(exception, produccion);

    // Registro: los 5xx con traza completa, los 4xx en nivel bajo. Un 404
    // no es un incidente; un 500 sí, y sin traza no se puede diagnosticar.
    if (status >= 500) {
      this.logger.error(
        { requestId, ruta: req.url, metodo: req.method, ...cuerpo },
        exception instanceof Error ? exception.stack : String(exception),
      );
    } else {
      this.logger.debug({ requestId, ruta: req.url, status, code: cuerpo.code });
    }

    httpAdapter.setHeader?.(ctx.getResponse(), 'Content-Type', 'application/problem+json');
    httpAdapter.reply(
      ctx.getResponse(),
      { ...cuerpo, status, instance: req.url, requestId, timestamp: new Date().toISOString() },
      status,
    );
  }

  private normalizar(e: unknown, produccion: boolean) {
    if (e instanceof HttpException) {
      const r = e.getResponse();
      const base = typeof r === 'string' ? { title: r } : (r as Record<string, unknown>);
      return { status: e.getStatus(), cuerpo: { type: 'about:blank', ...base } };
    }
    if (e instanceof ErrorDeDominio) {
      return {
        status: MAPA_DOMINIO[e.codigo] ?? 422,
        cuerpo: { type: `https://api.ejemplo.com/errores/${e.codigo.toLowerCase()}`,
                  title: e.message, code: e.codigo },
      };
    }
    // Cualquier otra cosa es un fallo nuestro: mensaje genérico. NUNCA
    // e.message, que puede contener SQL, rutas del servidor o secretos.
    return {
      status: HttpStatus.INTERNAL_SERVER_ERROR,
      cuerpo: {
        type: 'https://api.ejemplo.com/errores/interno',
        title: 'Error interno del servidor',
        // El detalle solo en desarrollo, y jamás la traza al cliente.
        ...(produccion ? {} : { detail: e instanceof Error ? e.message : String(e) }),
      },
    };
  }
}
// Registro con inyección: { provide: APP_FILTER, useClass: ProblemDetailsFilter }
// Si prefieres reutilizar el comportamiento por defecto de Nest para lo que
// no sepas tratar, extiende BaseExceptionFilter y llama a super.catch().

import { NotFoundError, UniqueConstraintViolationException,
  ForeignKeyConstraintViolationException, NotNullConstraintViolationException,
  OptimisticLockError } from '@mikro-orm/core';

// @Catch con varias clases: solo captura estas, el resto va al filtro global.
@Catch(NotFoundError, UniqueConstraintViolationException,
       ForeignKeyConstraintViolationException, NotNullConstraintViolationException,
       OptimisticLockError)
export class MikroOrmExceptionFilter implements ExceptionFilter {
  catch(e: Error, host: ArgumentsHost): never {
    // Este filtro no responde: TRADUCE y relanza para que el filtro global
    // aplique el formato Problem Details. Un solo formato en toda la API.
    if (e instanceof NotFoundError) {
      throw new NotFoundException('Recurso no encontrado');
    }
    if (e instanceof UniqueConstraintViolationException) {
      // El detalle del driver contiene el nombre del índice y a veces el
      // valor: útil en el log, inaceptable en la respuesta.
      throw new ConflictException({
        code: 'DUPLICADO', title: 'Ya existe un registro con esos datos',
        campo: this.campoDelIndice(e),
      });
    }
    if (e instanceof ForeignKeyConstraintViolationException) {
      throw new ConflictException({ code: 'REFERENCIA_EN_USO',
        title: 'La operación viola una relación existente' });
    }
    if (e instanceof NotNullConstraintViolationException) {
      throw new UnprocessableEntityException({ code: 'CAMPO_OBLIGATORIO',
        title: 'Falta un campo obligatorio' });
    }
    throw new ConflictException({ code: 'CONFLICTO_DE_VERSION',
      title: 'El recurso ha cambiado; recárgalo e inténtalo de nuevo' });
  }
  private campoDelIndice(e: Error): string | undefined {
    return /\(([^)]+)\)/.exec((e as any).sqlMessage ?? e.message)?.[1];
  }
}
// Registro: { provide: APP_FILTER, useClass: MikroOrmExceptionFilter }
// junto con ProblemDetailsFilter. Los @Catch() son DISJUNTOS, así que no
// hay ambigüedad sobre quién atiende cada error.

@Controller('projects/:projectId/tasks')
// Ámbito de clase: se aplica a todos los métodos del controlador.
@UseInterceptors(ClassSerializerInterceptor)
export class TasksController {
  constructor(private readonly tareas: TasksService) {}

  @Patch(':id')
  // ── Metadatos: los leen los guards vía Reflector, no se ejecutan ──────
  @Roles(['EDITOR', 'ADMIN'])
  @TiempoLimite(3_000)
  // ── Guards de método: se ejecutan DESPUÉS de los globales ─────────────
  @UseGuards(TaskOwnerGuard)
  // ── Interceptor de método: el más interno de los tres ─────────────────
  @UseInterceptors(TransactionInterceptor)
  @HttpCode(HttpStatus.OK)
  async actualizar(
    // Pipes de parámetro: el último eslabón antes del manejador.
    @Param('projectId', ParseUUIDPipe) projectId: string,
    @Param('id', ParseUUIDPipe) id: string,
    // ValidationPipe global: whitelist elimina 'borrado', transform
    // convierte '3' a 3 y devuelve una instancia real del DTO.
    @Body() dto: ActualizarTareaDto,
    // Decorador propio: extrae req.user, que puso JwtAuthGuard en t2.
    @CurrentUser() usuario: UsuarioAutenticado,
    // Decorador propio: extrae req.recurso, que puso TaskOwnerGuard en t4.
    // Así el servicio no repite la consulta de propiedad.
    @Recurso() tarea: Task,
  ): Promise<TareaRespuestaDto> {
    // El controlador NO tiene lógica: valida nada, autoriza nada, consulta
    // nada. Traduce y delega. Si crece, la lógica está mal colocada.
    const actualizada = await this.tareas.actualizar(tarea, dto, usuario);
    return TareaRespuestaDto.desde(actualizada);
  }
}

// ── El decorador de parámetro, por completitud ──────────────────────────
export const Recurso = createParamDecorator((_d: unknown, ctx: ExecutionContext) => {
  const req = ctx.switchToHttp().getRequest<Request>();
  if (!req.recurso) {
    // Falla ruidosamente en desarrollo: si falta el guard, el decorador
    // devolvería undefined y el servicio recibiría basura silenciosamente.
    throw new InternalServerErrorException('Falta @UseGuards(TaskOwnerGuard)');
  }
  return req.recurso;
});

@Injectable()
export class TasksService {
  constructor(private readonly em: EntityManager) {}

  async actualizar(tarea: Task, dto: ActualizarTareaDto, usuario: UsuarioAutenticado) {
    // Reglas de negocio con errores de DOMINIO, sin saber que existe HTTP.
    if (tarea.estado === EstadoTarea.CERRADA) {
      throw new TransicionInvalida('Una tarea cerrada no admite cambios',
        { id: tarea.id, estado: tarea.estado });
    }
    if (dto.estado === EstadoTarea.HECHA && !tarea.responsable) {
      throw new ReglaDeNegocio('No se puede completar una tarea sin responsable');
    }
    // Asignación EXPLÍCITA: el DTO ya está saneado, pero la lista de campos
    // asignables es una decisión del dominio, no del transporte.
    this.em.assign(tarea, {
      estado: dto.estado ?? tarea.estado,
      horas: dto.horas ?? tarea.horas,
      actualizadoPor: usuario.id,
    });
    // Sin flush explícito si el TransactionInterceptor envuelve la petición:
    // el commit hace flush. Con flush aquí también funciona y es más
    // explícito; elige una convención y respétala en todo el proyecto.
    await this.em.flush();
    return tarea;
  }
}