Idempotencia no es un lujo

export async function crearPago(req: Request) {
  const clave = req.headers.get("Idempotency-Key");
  if (!clave) return error(400, "falta Idempotency-Key");
 
  const previo = await db.idempotencia.buscar(clave);
  if (previo) return respuesta(previo.status, previo.body);
 
  const pago = await procesar(req.body);
 
  await db.idempotencia.guardar(clave, pago);
  return respuesta(201, pago);
}

CREATE TABLE claves_idempotencia (
    clave           text        PRIMARY KEY,
    huella_pedido   text        NOT NULL,
    estado          text        NOT NULL,  -- 'en_curso' | 'terminado'
    codigo_http     smallint,
    cuerpo          jsonb,
    recurso_id      text,
    -- Dos relojes distintos, y conviene no confundirlos:
    creada_en       timestamptz NOT NULL DEFAULT now(),  -- cuándo empezó este intento
    vence_en        timestamptz NOT NULL                 -- hasta cuándo repetimos la respuesta
);
 
CREATE INDEX ON claves_idempotencia (vence_en);

export async function crearPago(req: Request) {
  const clave = exigirClave(req);
  const huella = huellaDe(req.body);
 
  const reserva = await db.query(
    `INSERT INTO claves_idempotencia (clave, huella_pedido, estado, vence_en)
     VALUES ($1, $2, 'en_curso', now() + interval '24 hours')
     ON CONFLICT (clave) DO NOTHING
     RETURNING clave`,
    [clave, huella],
  );
 
  if (reserva.rowCount === 0) {
    return await resolverConflicto(clave, huella);
  }
 
  // Somos los únicos con la reserva: acá adentro estamos solos.
  const pago = await procesar(req.body);
 
  await db.query(
    `UPDATE claves_idempotencia
        SET estado = 'terminado', codigo_http = 201,
            cuerpo = $2, recurso_id = $3
      WHERE clave = $1`,
    [clave, JSON.stringify(pago), pago.id],
  );
 
  return respuesta(201, pago);
}

async function resolverConflicto(clave: string, huella: string) {
  const fila = await db.idempotencia.buscar(clave);
 
  if (fila.huella_pedido !== huella) {
    // 422 y no 409: el pedido es sintácticamente válido pero
    // semánticamente incompatible con lo que esa clave ya representa.
    return error(422, "Idempotency-Key reutilizada con otro cuerpo");
  }
 
  if (fila.estado === "en_curso") {
    // El original sigue corriendo. No adivinamos el resultado:
    // pedimos que vuelva a preguntar.
    // OJO: esta rama todavía está incompleta. Ver "Agujero 3".
    return error(409, "pedido en curso", { "Retry-After": "1" });
  }
 
  return respuesta(fila.codigo_http, fila.cuerpo);
}

// Cuánto puede tardar, en el peor caso real, una operación contra el
// adquirente. Es el reloj que decide si una reserva sigue viva o quedó zombi,
// y no tiene nada que ver con `vence_en`, que es cuánto tiempo seguimos
// repitiendo una respuesta ya terminada.
const TIMEOUT_OPERACION_MS = 60_000;
 
async function resolverConflicto(clave: string, huella: string) {
  const fila = await db.idempotencia.buscar(clave);
 
  if (fila.huella_pedido !== huella) {
    return error(422, "Idempotency-Key reutilizada con otro cuerpo");
  }
 
  if (fila.estado === "terminado") {
    return respuesta(fila.codigo_http, fila.cuerpo);
  }
 
  // `en_curso`. La pregunta ya no es "¿existe la reserva?" sino
  // "¿queda alguien del otro lado sosteniéndola?".
  const vencida =
    Date.now() - fila.creada_en.getTime() > TIMEOUT_OPERACION_MS;
 
  if (!vencida) {
    return error(409, "pedido en curso", { "Retry-After": "1" });
  }
 
  // Vencida: el dueño se murió o se colgó. Antes de tocar nada le
  // preguntamos al adquirente si el cobro llegó a existir. El id es
  // determinístico, así que se puede preguntar sin haber guardado nada.
  const enAdquirente = await adquirente.buscarPago(idDeterministico(clave));
 
  if (enAdquirente?.estado === "aprobado") {
    // El cobro se hizo. Se cierra la reserva con ese resultado y no se
    // reprocesa: reprocesar acá es exactamente el cobro duplicado que
    // toda esta nota trata de evitar.
    const pago = await cerrarReserva(clave, enAdquirente);
    return respuesta(201, pago);
  }
 
  if (enAdquirente?.estado === "pendiente") {
    // Existe pero no se resolvió. No es nuestro para reclamar: lo
    // va a cerrar el webhook.
    return error(409, "pedido en curso", { "Retry-After": "5" });
  }
 
  // No existe del lado del adquirente: recién acá la reserva es reclamable.
  // El UPDATE condicionado es lo que evita que dos reintentos simultáneos
  // la reclamen los dos — la misma idea que el ON CONFLICT de más arriba.
  const reclamo = await db.query(
    `UPDATE claves_idempotencia
        SET creada_en = now()
      WHERE clave = $1
        AND estado = 'en_curso'
        AND creada_en < now() - make_interval(secs => $2)
      RETURNING clave`,
    [clave, TIMEOUT_OPERACION_MS / 1000],
  );
 
  if (reclamo.rowCount === 0) {
    // Otro reintento la reclamó en el medio. Su intento gana.
    return error(409, "pedido en curso", { "Retry-After": "1" });
  }
 
  return await procesarYCerrar(clave);
}