Skip to main content

cripsy_binary_api/
compliance.rs

1//! Cumplimiento de consumo: garantía, descargo y advertencias de uso.
2//!
3//! Una librería no puede detectar quién la consume, pero sí puede **avisar**
4//! cuando el uso se aparta del flujo documentado y dejar explícito el contrato
5//! (garantía para el flujo documentado, ausencia de responsabilidad para el
6//! resto). Ver la sección «Garantía y descargo» de `README.md`.
7
8use crate::broker::config::{AccountSelection, IqOptionConfig, TransportConfig};
9
10/// Versión de la API (del propio crate).
11pub const API_VERSION: &str = env!("CARGO_PKG_VERSION");
12
13/// Dónde está la documentación de usuario.
14pub const DOCS_INDEX: &str = "docs/site/es/index.html";
15
16/// Garantía y descargo, en texto listo para mostrar al consumidor.
17pub const GARANTIA: &str = "cripsy_binary_API garantiza el comportamiento \
18documentado (docs/) cuando se sigue el flujo documentado: \
19dependencia como librería, trait Broker canónico, canales documentados y compuerta \
20verde. Cualquier otro uso queda fuera de la garantía y sus consecuencias no son \
21responsabilidad de este equipo.";
22
23/// Informe de cumplimiento para un consumo concreto.
24#[derive(Debug, Clone, PartialEq)]
25pub struct ComplianceReport {
26    /// Versión de la librería que se está usando.
27    pub api_version: &'static str,
28    /// Features activas de compilación.
29    pub features: Vec<&'static str>,
30    /// Advertencias de uso apartado del flujo documentado (vacío = conforme).
31    pub advertencias: Vec<String>,
32}
33
34impl ComplianceReport {
35    /// ¿El consumo analizado no tiene advertencias?
36    pub fn conforme(&self) -> bool {
37        self.advertencias.is_empty()
38    }
39}
40
41/// Features activas detectadas en tiempo de compilación.
42pub fn features_activas() -> Vec<&'static str> {
43    let mut f = Vec::new();
44    if cfg!(feature = "async") {
45        f.push("async");
46    }
47    if cfg!(feature = "blocking") {
48        f.push("blocking");
49    }
50    f
51}
52
53/// Revisa una configuración y devuelve el informe de cumplimiento.
54///
55/// No bloquea nada: solo advierte. Las advertencias cubren los casos que la
56/// experiencia contra el bróker real demostrado como problemáticos.
57pub fn revisar_config(cfg: &IqOptionConfig) -> ComplianceReport {
58    let mut advertencias = Vec::new();
59
60    if cfg.timeout_secs == 0 {
61        advertencias.push(
62            "timeout_secs = 0: toda espera de respuesta quedará sin plazo; \
63             usa un valor > 0 (el bróker puede no responder)"
64                .into(),
65        );
66    }
67    if !cfg.transport.verify_tls {
68        advertencias.push(
69            "verify_tls = false: la conexión acepta certificados inválidos; \
70             solo para pruebas documentadas, nunca en producción"
71                .into(),
72        );
73    }
74    if cfg.transport.request_timeout_secs > cfg.timeout_secs {
75        advertencias.push(
76            "request_timeout_secs > timeout_secs: el transporte esperaría más \
77             que el plazo de la solicitud"
78                .into(),
79        );
80    }
81    if cfg.account == AccountSelection::Real {
82        advertencias.push(
83            "cuenta Real seleccionada al conectar: para pruebas usa \
84             AccountSelection::Practice (demo); las operaciones reales requieren \
85             autorización explícita"
86                .into(),
87        );
88    }
89    if cfg.email.is_empty() || cfg.password.is_empty() {
90        advertencias.push(
91            "credenciales vacías: el login fallará; cárgalas desde .env \
92             (variables de entorno), nunca en el código"
93                .into(),
94        );
95    }
96    for host in [&cfg.auth_host, &cfg.api_host, &cfg.ws_host] {
97        if host.is_empty() {
98            advertencias.push("host vacío en la configuración".into());
99        }
100    }
101
102    ComplianceReport {
103        api_version: API_VERSION,
104        features: features_activas(),
105        advertencias,
106    }
107}
108
109/// Revisa una configuración de transporte suelta (sin datos de cuenta).
110pub fn revisar_transporte(cfg: &TransportConfig) -> ComplianceReport {
111    let mut advertencias = Vec::new();
112    if !cfg.verify_tls {
113        advertencias.push("verify_tls = false: solo para pruebas documentadas".into());
114    }
115    if cfg.max_retries > 20 {
116        advertencias.push(
117            "max_retries muy alto: con backoff máximo, una reconexión puede \
118             tardar minutos; valores razonables: 3-10"
119                .into(),
120        );
121    }
122    ComplianceReport {
123        api_version: API_VERSION,
124        features: features_activas(),
125        advertencias,
126    }
127}
128
129/// Mensaje listo para mostrar al consumidor (garantía + descargo).
130pub fn mensaje_consumidor() -> String {
131    format!(
132        "cripsy_binary_API {API_VERSION}\n\
133         Documentación: {DOCS_INDEX}\n\
134         Reglas de uso: README.md\n\
135         {GARANTIA}"
136    )
137}
138
139#[cfg(test)]
140mod tests {
141    use super::*;
142
143    #[test]
144    fn config_conforme_sin_advertencias() {
145        let cfg = IqOptionConfig {
146            email: "u@ejemplo.com".into(),
147            password: "secreto".into(),
148            account: AccountSelection::Practice,
149            ..IqOptionConfig::default()
150        };
151        let reporte = revisar_config(&cfg);
152        assert!(
153            reporte.conforme(),
154            "no debía haber advertencias: {:?}",
155            reporte.advertencias
156        );
157        assert_eq!(reporte.api_version, API_VERSION);
158    }
159
160    #[test]
161    fn config_real_y_sin_tls_advierte() {
162        let transporte = TransportConfig {
163            verify_tls: false,
164            ..TransportConfig::default()
165        };
166        let cfg = IqOptionConfig {
167            email: "u@ejemplo.com".into(),
168            password: "secreto".into(),
169            account: AccountSelection::Real,
170            transport: transporte,
171            ..IqOptionConfig::default()
172        };
173        let reporte = revisar_config(&cfg);
174        assert!(!reporte.conforme());
175        assert!(reporte
176            .advertencias
177            .iter()
178            .any(|a| a.contains("verify_tls")));
179        assert!(reporte.advertencias.iter().any(|a| a.contains("Real")));
180    }
181
182    #[test]
183    fn credenciales_vacias_advierten() {
184        let cfg = IqOptionConfig {
185            email: String::new(),
186            password: String::new(),
187            ..IqOptionConfig::default()
188        };
189        let reporte = revisar_config(&cfg);
190        assert!(!reporte.conforme());
191        assert!(reporte
192            .advertencias
193            .iter()
194            .any(|a| a.contains("credenciales vacías")));
195    }
196
197    #[test]
198    fn mensaje_incluye_garantia() {
199        let m = mensaje_consumidor();
200        assert!(m.contains("garantiza"));
201        assert!(m.contains("README.md"));
202        assert!(m.contains(API_VERSION));
203    }
204}
205
206#[cfg(test)]
207mod tests_ejemplo_documentado {
208    use crate::broker::IqOptionConfig;
209    // Réplica del ejemplo del README («Garantía y descargo»): el mismo código
210    // que copiaría un consumidor externo (con el nombre del crate).
211    #[test]
212    fn ejemplo_de_consumidores_compila() {
213        // Un consumidor externo escribe `cripsy_binary_api::`; dentro del crate
214        // el equivalente es `crate::` (mismos ítems, mismo contrato).
215        use crate::{mensaje_consumidor, revisar_config};
216        let _texto = mensaje_consumidor();
217        let cfg = IqOptionConfig::default();
218        let reporte = revisar_config(&cfg);
219        for aviso in &reporte.advertencias {
220            let _ = aviso;
221        }
222        assert!(!reporte.conforme());
223        assert!(!reporte.api_version.is_empty());
224    }
225}