Middleware de Idempotencia Estricta en Node.js y Express para Transacciones Críticas

JAVASCRIPT / NODE.JS 31 de julio de 2026 90 lecturas
Implementa un middleware de idempotencia estricta para Express que previene duplicación de transacciones y race conditions mediante bloqueos PENDING y caching de respuestas.

Durante mi trayectoria diseñando e implementando arquitecturas de backend resilientes para plataformas fintech y motores de procesamiento de pagos distribuidos, he constatado que la falacia de la confiabilidad de la red es uno de los riesgos arquitectónicos más graves en el desarrollo web. En un entorno distribuido, las redes IP son intrínsecamente asíncronas e impredecibles. Pérdidas temporales de paquetes, latencias variables, reconexiones automáticas de clientes móviles y conmutaciones por error en balanceadores de carga provocan inevitablemente peticiones HTTP duplicadas. Cuando un cliente no recibe una respuesta a tiempo, la norma por defecto de la capa de transporte o del SDK del cliente es reintentar la solicitud. Si el endpoint de destino ejecuta una mutación de estado no idempotente —como el cobro a una tarjeta de crédito, la deducción de saldo en un monedero digital o la emisión de un boleto aéreo—, la reejecución de la lógica de negocio puede acarrear repercusiones financieras nefastas y generar inconsistencias contables extremadamente complejas de auditar.

Para solucionar de raíz este problema sin comprometer el rendimiento global de la API, he diseñado e implementado este middleware de idempotencia estricta para Express en Node.js. El principio básico de la idempotencia en las API RESTful dicta que múltiples solicitudes idénticas deben tener exactamente el mismo efecto en el estado del servidor que una sola solicitud. Para lograr esto en operaciones mutables de alto riesgo (habitualmente asociadas a métodos HTTP POST o PATCH), implementamos un patrón donde cada transacción se identifica unívocamente mediante una cabecera HTTP estándar: Idempotency-Key. El middleware intercepta la petición entrante, verifica el historial de ejecución y determina de forma determinista si debe procesar la lógica de negocio o devolver una respuesta previamente memorizada.

La Arquitectura del Estado y la Prevención de Race Conditions

La implementación más ingenua del patrón de idempotencia suele limitarse a consultar un almacenamiento en caché para verificar si existe una respuesta registrada para la clave proporcionada. Si la respuesta existe, se devuelve; si no, se procesa la petición y se guarda el resultado final. Sin embargo, esta aproximación ignora por completo la concurrencia. En escenarios reales de alta volatilidad, dos o más peticiones con la misma clave de idempotencia pueden impactar a la API en un intervalo de microsegundos —por ejemplo, cuando un script automatizado realiza reintentos agresivos sin esperar el tiempo de espera adecuado o cuando el usuario presiona dos veces seguidas el botón de pago en la interfaz móvil.

Si ambas peticiones superan la verificación inicial antes de que la primera haya concluido su escritura en la base de datos o en el almacén de caché, ambas peticiones procederán a ejecutar la lógica de negocio en paralelo. Este fenómeno, conocido como condición de carrera (race condition), destruye la garantía de idempotencia. Para contrarrestar esta vulnerabilidad, mi arquitectura introduce una máquina de estados de dos fases basada en un bloqueo inmediato en estado PENDING. Tan pronto como la primera petición llega al middleware, la clave se registra atómicamente con el estado PENDING antes de ceder el control al siguiente middleware mediante next(). Si entra una segunda petición simultánea portando la misma clave mientras el estado siga en PENDING, el middleware interrumpe inmediatamente el ciclo de vida respondiendo con un código de estado HTTP 409 Conflict. Esto notifica formalmente al cliente que una transacción idéntica ya está siendo procesada, evitando la ejecución redundante de rutinas pesadas de base de datos o llamadas a pasarelas externas de pago.

Intercepción Transparente del Ciclo de Vida en Express

Uno de mis principales objetivos al diseñar este middleware fue evitar la contaminación del código de dominio. Los controladores de la aplicación no deben preocuparse por la persistencia ni por el formato de las respuestas memorizadas; simplemente deben continuar invocando las rutinas estándar de Express como res.json() o res.send(). Para lograr esta desacoplación total, utilicé una variante limpia del patrón Monkey Patching sobre los métodos de salida del objeto Response (res) dentro del contexto de la solicitud actual.

Al envolver el método res.send, capturamos el objeto del cuerpo de la respuesta y el código de estado HTTP resultante. Si la operación se completa con éxito (códigos HTTP de la serie 2xx), el estado de la clave en el almacén evoluciona de PENDING a COMPLETED, adjuntando la carga útil, los encabezados clave de la respuesta y el código de estado. Durante peticiones subsecuentes con la misma clave, el middleware interceptará la llamada en las primeras líneas de ejecución y retornará la respuesta memorizada directamente desde la memoria o memoria intermedia, agregando el encabezado X-Cache-Lookup: HIT-IDEMPOTENT para facilitar la observabilidad y trazabilidad desde herramientas de monitoreo o proxies inversos.

Gestión de Excepciones, Desconexiones Prematuras y Limpieza de Memoria

El diseño de software resiliente exige considerar detenidamente los escenarios de fallo. ¿Qué sucede si la lógica de negocio falla con un error 500 o una validación de datos 400? ¿O si el cliente aborta repentinamente la conexión TCP en medio de la ejecución? Un middleware estricto no debe bloquear indefinidamente una clave de idempotencia si la transacción falló por un problema transitorio o un error de entrada que el usuario puede corregir. Por lo tanto, si el controlador responde con un código de error de la serie 4xx o 5xx, el middleware elimina la clave del estado PENDING, permitiendo que el cliente corrija los datos enviados o reintente la solicitud legítimamente.

Asimismo, el middleware escucha activamente el evento close del objeto req. Si el cliente cierra la conexión HTTP antes de que la respuesta sea enviada por completo, se remueve el estado PENDING para evitar bloqueos fantasma. Finalmente, para prevenir fugas de memoria (memory leaks) ocasionadas por el crecimiento indefinido del almacenamiento interno, se implementa un mecanismo de barrido basado en expiración por TTL (Time-To-Live). En entornos distribuidos y multinodo, esta abstracción puede ser reemplazada por una tienda distribuida como Redis, aprovechando la atomicidad de comandos como SET key value NX PX ttl.

/**
 * Express Strict Idempotency Middleware
 * Previene transacciones duplicadas y race conditions mediante máquina de estados (PENDING / COMPLETED)
 */

class InMemoryStore {
  constructor(defaultTtlMs = 86400000) {
    this.store = new Map();
    this.defaultTtlMs = defaultTtlMs;
  }

  async get(key) {
    const record = this.store.get(key);
    if (!record) return null;
    if (Date.now() > record.expiresAt) {
      this.store.delete(key);
      return null;
    }
    return record.value;
  }

  async setPending(key) {
    if (this.store.has(key)) {
      const record = await this.get(key);
      if (record) return false;
    }
    this.store.set(key, {
      value: { status: 'PENDING' },
      expiresAt: Date.now() + 60000 // Bloqueo temporal de 60s para estado PENDING
    });
    return true;
  }

  async setCompleted(key, responseData, ttlMs = this.defaultTtlMs) {
    this.store.set(key, {
      value: { status: 'COMPLETED', ...responseData },
      expiresAt: Date.now() + ttlMs
    });
  }

  async delete(key) {
    this.store.delete(key);
  }
}

class IdempotencyManager {
  constructor(options = {}) {
    this.ttlMs = (options.ttlInHours || 24) * 60 * 60 * 1000;
    this.headerName = options.headerName || 'idempotency-key';
    this.store = options.store || new InMemoryStore(this.ttlMs);
  }

  middleware() {
    return async (req, res, next) => {
      // Ignorar métodos seguros/idempotentes por especificación HTTP (RFC 9110)
      if (['GET', 'HEAD', 'OPTIONS'].includes(req.method)) {
        return next();
      }

      const idempotencyKey = req.headers[this.headerName];

      if (!idempotencyKey) {
        return res.status(400).json({
          success: false,
          error: `La cabecera "${this.headerName}" es requerida para procesar esta operación.`
        });
      }

      try {
        const cachedState = await this.store.get(idempotencyKey);

        // Escenario 1: Cache Hit - Respuesta completada previa
        if (cachedState && cachedState.status === 'COMPLETED') {
          res.setHeader('X-Cache-Lookup', 'HIT-IDEMPOTENT');
          return res.status(cachedState.statusCode).send(cachedState.body);
        }

        // Escenario 2: Race Condition - Operación en progreso
        if (cachedState && cachedState.status === 'PENDING') {
          return res.status(409).json({
            success: false,
            error: 'Una transacción concurrente con esta Idempotency-Key está en progreso.'
          });
        }

        // Escenario 3: Primera ejecución -> Adquirir bloqueo PENDING
        const lockAcquired = await this.store.setPending(idempotencyKey);
        if (!lockAcquired) {
          return res.status(409).json({
            success: false,
            error: 'Conflicto de concurrencia al registrar la Idempotency-Key.'
          });
        }

        // Manejo de desconexión prematura del cliente
        const handleClientAbort = () => {
          this.store.get(idempotencyKey).then((state) => {
            if (state && state.status === 'PENDING') {
              this.store.delete(idempotencyKey);
            }
          }).catch(() => {});
        };

        req.once('close', handleClientAbort);

        // Intercepción del método res.send para capturar todo tipo de respuestas
        const originalSend = res.send.bind(res);

        res.send = (body) => {
          req.removeListener('close', handleClientAbort);

          if (res.statusCode >= 200 && res.statusCode < 300) {
            let parsedBody = body;
            try {
              parsedBody = typeof body === 'string' ? JSON.parse(body) : body;
            } catch (_) {
              parsedBody = body;
            }

            this.store.setCompleted(idempotencyKey, {
              statusCode: res.statusCode,
              body: parsedBody
            }, this.ttlMs).catch((err) => {
              console.error('Error al guardar registro de idempotencia:', err);
            });
          } else {
            // Si la operación falla (4xx o 5xx), liberamos la clave para permitir reintentos corregidos
            this.store.delete(idempotencyKey).catch(() => {});
          }

          return originalSend(body);
        };

        next();
      } catch (error) {
        console.error('Error en el middleware de idempotencia:', error);
        next(error);
      }
    };
  }
}

module.exports = IdempotencyManager;
¿Qué te pareció?
🔥 Brillante 1
💡 Me sirvió 0
🚀 A otro nivel 0

Sugerencias para ti

Snippet

Cómo Crear una Tarjeta Glassmorphism con Efecto Neón Avanzado en CSS3

👁️ 199 vistas
Snippet

Construcción de APIs REST Escalables con Express, Node.js y PostgreSQL: Patrones Avanzados de Conexiones y Seguridad

👁️ 168 vistas
Snippet

Construcción de un Orquestador de Colas Asíncronas en Node.js con Control de Concurrencia y Full Jitter Backoff

👁️ 100 vistas

¿Te resultó útil este snippet? Explora más código y soluciones en AndresSY.dev.

Volver a Snippets