context7_cli/

api.rs

/// HTTP client, retry logic, and Context7 API calls.
///
/// This module owns the full lifecycle of API interaction:
/// request building, status handling, and key-rotation retry.
use anyhow::{bail, Context, Result};
use rand::seq::SliceRandom;
use reqwest::StatusCode;
use serde::{Deserialize, Serialize};
use tokio::time::{sleep, Duration};
use tracing::{error, info, warn};

use crate::errors::ErroContext7;

// ─── CONSTANTE ───────────────────────────────────────────────────────────────

const BASE_URL: &str = "https://context7.com/api";

// ─── MODELOS DE RESPOSTA DA API ───────────────────────────────────────────────

/// Represents a single library entry returned by the search endpoint.
#[derive(Debug, Deserialize, Serialize)]
pub struct LibrarySearchResult {
    /// Unique library identifier (e.g. `/facebook/react`).
    pub id: String,
    /// Human-readable library title.
    pub title: String,
    /// Optional short description of the library.
    pub description: Option<String>,
    /// Relevance/trust score returned by the API, if available.
    pub trust_score: Option<f64>,
}

/// Represents a single documentation excerpt returned by the docs endpoint.
#[derive(Debug, Deserialize, Serialize)]
pub struct DocumentationSnippet {
    /// Markdown or plain-text content of the snippet.
    pub content: String,
    /// Content type hint (e.g. `"text"`, `"code"`), if provided.
    #[serde(rename = "type")]
    pub tipo: Option<String>,
    /// Source URLs associated with this snippet, if provided.
    pub source_urls: Option<Vec<String>>,
}

/// Top-level response from the library search endpoint (`GET /api/v1/search`).
#[derive(Debug, Deserialize)]
pub struct RespostaListaBibliotecas {
    /// List of matching libraries.
    pub results: Vec<LibrarySearchResult>,
}

/// Top-level response from the documentation endpoint (`GET /api/v1/{library_id}`).
#[derive(Debug, Deserialize, Serialize)]
pub struct RespostaDocumentacao {
    /// Library identifier echoed back by the API, if present.
    #[allow(dead_code)]
    pub id: Option<String>,
    /// Structured documentation snippets (JSON mode).
    pub snippets: Option<Vec<DocumentationSnippet>>,
    /// Raw text content (plain-text mode).
    pub content: Option<String>,
}

// ─── CLIENTE HTTP ─────────────────────────────────────────────────────────────

/// Creates a reusable HTTP client with rustls-TLS, 30 s timeout, and HTTP/2.
///
/// The client should be created once per invocation and shared via `Arc`.
pub fn criar_cliente_http() -> Result<reqwest::Client> {
    let cliente = reqwest::Client::builder()
        .use_rustls_tls()
        .timeout(Duration::from_secs(30))
        .user_agent("context7-cli/0.2.0")
        .pool_max_idle_per_host(4)
        .build()
        .context("Falha ao criar cliente HTTP")?;

    Ok(cliente)
}

// ─── RETRY COM ROTAÇÃO DE CHAVES ──────────────────────────────────────────────

/// Executes an API call with retry and key rotation.
///
/// Shuffles a local copy of the provided keys (random draw without replacement)
/// and retries up to `min(3, keys.len())` times with exponential backoff:
/// 500 ms → 1 s → 2 s.
///
/// The closure receives an owned `String` (clone of the key) to satisfy the
/// `async move` ownership requirement inside the future.
pub async fn executar_com_retry<F, Fut, T>(chaves: &[String], operacao: F) -> Result<T>
where
    F: Fn(String) -> Fut,
    Fut: std::future::Future<Output = Result<T, ErroContext7>>,
{
    let max_tentativas = 3usize.min(chaves.len());

    // Shuffles a local copy — avoids modifying the caller's vec
    let mut chaves_embaralhadas = chaves.to_vec();
    let mut rng = rand::thread_rng();
    chaves_embaralhadas.shuffle(&mut rng);

    let atrasos_ms = [500u64, 1000, 2000];
    let mut chaves_falhas_auth = 0usize;

    for (tentativa, chave) in chaves_embaralhadas
        .into_iter()
        .take(max_tentativas)
        .enumerate()
    {
        info!("Tentativa {}/{}", tentativa + 1, max_tentativas);

        match operacao(chave).await {
            Ok(resultado) => return Ok(resultado),

            Err(ErroContext7::ApiRetornou400 { mensagem }) => {
                // 400 is not transient — abort immediately
                bail!(ErroContext7::ApiRetornou400 { mensagem });
            }

            Err(ErroContext7::SemChavesApi) => {
                chaves_falhas_auth += 1;
                warn!("Chave de API inválida (401/403), tentando próxima...");
            }

            Err(e) => {
                warn!("Falha na tentativa {}: {}", tentativa + 1, e);

                // Backoff before next attempt (not on the last one)
                if tentativa + 1 < max_tentativas && tentativa < atrasos_ms.len() {
                    let atraso = Duration::from_millis(atrasos_ms[tentativa]);
                    info!(
                        "Aguardando {}ms antes de tentar novamente...",
                        atraso.as_millis()
                    );
                    sleep(atraso).await;
                }
            }
        }
    }

    if chaves_falhas_auth >= max_tentativas {
        bail!(ErroContext7::SemChavesApi);
    }

    bail!(ErroContext7::RetryEsgotado {
        tentativas: max_tentativas as u32,
    });
}

// ─── CHAMADAS À API ───────────────────────────────────────────────────────────

/// Searches for libraries matching `nome` with optional relevance `query_contexto`.
///
/// Returns `Err(ErroContext7)` on HTTP errors to enable retry in `executar_com_retry`.
pub async fn buscar_biblioteca(
    cliente: &reqwest::Client,
    chave: &str,
    nome: &str,
    query_contexto: &str,
) -> Result<RespostaListaBibliotecas, ErroContext7> {
    let url = format!("{}/v1/search", BASE_URL);

    let resposta = cliente
        .get(&url)
        .bearer_auth(chave)
        .query(&[("libraryName", nome), ("query", query_contexto)])
        .send()
        .await
        .map_err(|e| {
            error!("Erro de rede ao buscar biblioteca: {}", e);
            ErroContext7::RespostaInvalida { status: 0 }
        })?;

    tratar_status_resposta(resposta).await
}

/// Fetches documentation for `library_id` with an optional `query` filter.
///
/// `texto_plano = true` requests the `txt` content type instead of JSON.
/// Returns `Err(ErroContext7)` on HTTP errors to enable retry in `executar_com_retry`.
pub async fn buscar_documentacao(
    cliente: &reqwest::Client,
    chave: &str,
    library_id: &str,
    query: Option<&str>,
    texto_plano: bool,
) -> Result<RespostaDocumentacao, ErroContext7> {
    // Normalise library_id: strip leading slash if present
    let id_normalizado = library_id.trim_start_matches('/');
    let url = format!("{}/v1/{}", BASE_URL, id_normalizado);

    let tipo = if texto_plano { "txt" } else { "json" };

    let mut construtor = cliente
        .get(&url)
        .bearer_auth(chave)
        .query(&[("type", tipo)]);

    if let Some(q) = query {
        construtor = construtor.query(&[("query", q)]);
    }

    let resposta = construtor.send().await.map_err(|e| {
        error!("Erro de rede ao buscar documentação: {}", e);
        ErroContext7::RespostaInvalida { status: 0 }
    })?;

    tratar_status_resposta(resposta).await
}

/// Maps HTTP status codes to typed `ErroContext7` variants or deserialises success bodies.
async fn tratar_status_resposta<T: for<'de> Deserialize<'de>>(
    resposta: reqwest::Response,
) -> Result<T, ErroContext7> {
    let status = resposta.status();

    match status {
        s if s.is_success() => resposta.json::<T>().await.map_err(|e| {
            error!("Falha ao desserializar resposta JSON: {}", e);
            ErroContext7::RespostaInvalida {
                status: status.as_u16(),
            }
        }),

        StatusCode::BAD_REQUEST => {
            let mensagem = resposta
                .text()
                .await
                .unwrap_or_else(|_| "Sem detalhes".to_string());
            Err(ErroContext7::ApiRetornou400 { mensagem })
        }

        StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN => Err(ErroContext7::SemChavesApi),

        StatusCode::TOO_MANY_REQUESTS => {
            warn!("Rate limit atingido (429), aguardando retry...");
            Err(ErroContext7::RespostaInvalida {
                status: status.as_u16(),
            })
        }

        s if s.is_server_error() => {
            warn!(
                "Erro do servidor ({}), tentando novamente...",
                status.as_u16()
            );
            Err(ErroContext7::RespostaInvalida {
                status: status.as_u16(),
            })
        }

        _ => Err(ErroContext7::RespostaInvalida {
            status: status.as_u16(),
        }),
    }
}

// ─── TESTES ───────────────────────────────────────────────────────────────────

#[cfg(test)]
mod testes {
    use super::*;

    // ── Desserialização de structs ────────────────────────────────────────────

    #[test]
    fn testa_deserializacao_library_search_result() {
        let json = r#"{
            "id": "/facebook/react",
            "title": "React",
            "description": "A JavaScript library for building user interfaces",
            "trust_score": 95.0
        }"#;

        let resultado: LibrarySearchResult =
            serde_json::from_str(json).expect("Deve deserializar LibrarySearchResult");

        assert_eq!(resultado.id, "/facebook/react");
        assert_eq!(resultado.title, "React");
        assert_eq!(
            resultado.description.as_deref(),
            Some("A JavaScript library for building user interfaces")
        );
        assert!((resultado.trust_score.unwrap() - 95.0).abs() < f64::EPSILON);
    }

    #[test]
    fn testa_deserializacao_library_search_result_tolerante_campos_faltando() {
        let json = r#"{
            "id": "/minimal/lib",
            "title": "MinimalLib"
        }"#;

        let resultado: LibrarySearchResult =
            serde_json::from_str(json).expect("Deve deserializar mesmo com campos ausentes");

        assert_eq!(resultado.id, "/minimal/lib");
        assert_eq!(resultado.title, "MinimalLib");
        assert!(resultado.description.is_none(), "description deve ser None");
        assert!(resultado.trust_score.is_none(), "trust_score deve ser None");
    }

    #[test]
    fn testa_deserializacao_documentation_snippet() {
        let json = r#"{
            "content": "The Effect Hook lets you perform side effects in function components.",
            "type": "text",
            "source_urls": ["https://react.dev/reference/react/useEffect"]
        }"#;

        let trecho: DocumentationSnippet =
            serde_json::from_str(json).expect("Deve deserializar DocumentationSnippet");

        assert!(trecho.content.contains("side effects"));
        assert_eq!(trecho.tipo.as_deref(), Some("text"));
        let urls = trecho.source_urls.as_ref().expect("Deve ter source_urls");
        assert_eq!(urls[0], "https://react.dev/reference/react/useEffect");
    }

    #[test]
    fn testa_deserializacao_documentation_snippet_sem_campos_opcionais() {
        let json = r#"{
            "content": "Conteúdo mínimo do trecho."
        }"#;

        let trecho: DocumentationSnippet =
            serde_json::from_str(json).expect("Deve deserializar sem campos opcionais");

        assert_eq!(trecho.content, "Conteúdo mínimo do trecho.");
        assert!(trecho.tipo.is_none());
        assert!(trecho.source_urls.is_none());
    }

    // ── Mock HTTP ─────────────────────────────────────────────────────────────

    #[tokio::test]
    async fn testa_buscar_biblioteca_com_mock_servidor_retorna_200() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let servidor_mock = MockServer::start().await;

        let resposta_json = serde_json::json!({
            "results": [
                {
                    "id": "/axum-rs/axum",
                    "title": "axum",
                    "description": "Framework web para Rust",
                    "trust_score": 90.0
                }
            ]
        });

        Mock::given(method("GET"))
            .and(path("/api/v1/search"))
            .respond_with(ResponseTemplate::new(200).set_body_json(&resposta_json))
            .mount(&servidor_mock)
            .await;

        let cliente = reqwest::Client::new();
        let url = format!("{}/api/v1/search", servidor_mock.uri());

        let resposta = cliente
            .get(&url)
            .bearer_auth("ctx7sk-teste-mock")
            .query(&[("libraryName", "axum"), ("query", "axum")])
            .send()
            .await
            .expect("Deve conectar ao mock server");

        assert!(resposta.status().is_success(), "Status deve ser 200");

        let dados: RespostaListaBibliotecas = resposta
            .json()
            .await
            .expect("Deve deserializar resposta do mock");

        assert_eq!(dados.results.len(), 1);
        assert_eq!(dados.results[0].id, "/axum-rs/axum");
        assert_eq!(dados.results[0].title, "axum");
    }

    #[tokio::test]
    async fn testa_buscar_documentacao_com_mock_servidor_retorna_200() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let servidor_mock = MockServer::start().await;

        let resposta_json = serde_json::json!({
            "id": "/axum-rs/axum",
            "snippets": [
                {
                    "content": "O Router do Axum permite definir rotas HTTP de forma declarativa.",
                    "type": "text",
                    "source_urls": ["https://docs.rs/axum/latest/axum/struct.Router.html"]
                }
            ]
        });

        Mock::given(method("GET"))
            .and(path("/api/v1/axum-rs/axum"))
            .respond_with(ResponseTemplate::new(200).set_body_json(&resposta_json))
            .mount(&servidor_mock)
            .await;

        let cliente = reqwest::Client::new();
        let url = format!("{}/api/v1/axum-rs/axum", servidor_mock.uri());

        let resposta = cliente
            .get(&url)
            .bearer_auth("ctx7sk-teste-docs-mock")
            .query(&[("type", "json"), ("query", "como criar router")])
            .send()
            .await
            .expect("Deve conectar ao mock server");

        assert!(resposta.status().is_success());

        let dados: RespostaDocumentacao = resposta
            .json()
            .await
            .expect("Deve deserializar resposta do mock");

        let trechos = dados.snippets.as_ref().expect("Deve ter snippets");
        assert_eq!(trechos.len(), 1);
        assert!(trechos[0].content.contains("Router do Axum"));
    }

    // ── Shuffle de chaves ─────────────────────────────────────────────────────

    #[test]
    fn testa_shuffle_chaves_preserva_todos_os_elementos() {
        let chaves_originais: Vec<String> =
            (0..10).map(|i| format!("ctx7sk-chave-{:02}", i)).collect();

        let mut chaves_copia = chaves_originais.clone();
        let mut rng = rand::thread_rng();
        chaves_copia.shuffle(&mut rng);

        assert_eq!(
            chaves_copia.len(),
            chaves_originais.len(),
            "Shuffle deve preservar todos os elementos"
        );

        let mut ordenadas_original = chaves_originais.clone();
        let mut ordenadas_copia = chaves_copia.clone();
        ordenadas_original.sort();
        ordenadas_copia.sort();
        assert_eq!(
            ordenadas_original, ordenadas_copia,
            "Shuffle deve conter os mesmos elementos, apenas em ordem diferente"
        );
    }
}