Skip to main content

cripsy_binary_api/broker/
historico.rs

1//! Descarga paginada de histórico: más allá del tope de 1000 velas por request.
2//!
3//! LÍMITES VERIFICADOS CONTRA EL BRÓKER (2026-10-30, EURUSD-op)
4//!   · `count` máximo: 1000. Pedir 2000 o 5000 devuelve 1000 igual.
5//!   · `from`+`to` devuelve 0 velas: el rango no se puede saltar, solo se
6//!     pagina hacia atrás con `to`/`to_id`. El canal antiguo `get-candles` v1.0 con
7//!     `from`/`to` no devuelve datos ni error.
8//!   · Retención por tamaño: 1 s y 5 s ≈ 7 días · 1 m 45–90 días ·
9//!     5 m 270–330 días · ≥15 m > 2 años.
10//!   · La semana completa de 1 s son ~605 páginas por activo.
11//!
12//! SEMÁNTICA DE `to` (medida en vivo 2026-10-30): es inclusivo sobre el
13//! **inicio** de la vela. Pedir `to=T` devuelve la vela que empieza en `T`
14//! (aunque siga en curso) y las anteriores. Por eso [`ultimo_cierre`] resta
15//! un paso: entrega el inicio de la última vela cerrada.
16//!
17//! Enfoque: retroceder `to` un paso por debajo del `from` más viejo de cada
18//! página, fusionar y deduplicar por `from`. Se detiene al alcanzar `desde`,
19//! al recibir una página vacía (retención del bróker) o al llegar a
20//! [`PAGINAS_MAXIMAS`].
21
22use crate::broker::error::BrokerError;
23use crate::broker::trait_::Broker;
24use crate::domain::{Candle, CandleRequest};
25
26/// Tope real de velas por request en IQ Option (verificado en vivo).
27pub const VELAS_POR_PAGINA: usize = 1000;
28
29/// Freno de seguridad para una ventana mal pedida (p. ej. `desde` en el año 1970).
30pub const PAGINAS_MAXIMAS: usize = 5_000;
31
32/// Resultado de una descarga de ventana.
33#[derive(Debug, Clone, PartialEq)]
34pub struct Ventana {
35    /// Velas ordenadas de vieja a nueva, sin duplicados por `from`.
36    pub velas: Vec<Candle>,
37    /// Requests efectivamente enviados.
38    pub paginas: usize,
39    /// Se alcanzó `desde` (no se agotó la retención antes).
40    pub completa: bool,
41    /// Se detuvo por [`PAGINAS_MAXIMAS`] en vez de por datos.
42    pub truncada: bool,
43    /// Huecos según `intervalo` entre la primera y la última vela. Incluye
44    /// cierres de mercado (fines de semana): no distingue unos de otros.
45    pub faltantes: usize,
46}
47
48/// Inicio de la última vela **cerrada** para `intervalo`, que es el `to`
49/// seguro: el bróker incluye la vela que empieza exactamente en `to`.
50pub fn ultimo_cierre(ahora: i64, intervalo: u64) -> i64 {
51    let paso = intervalo.max(1) as i64;
52    (ahora / paso) * paso - paso
53}
54
55/// Páginas que harían falta para cubrir `desde..hasta` con [`VELAS_POR_PAGINA`].
56pub fn paginas_estimadas(intervalo: u64, desde: i64, hasta: i64) -> usize {
57    if hasta <= desde {
58        return 0;
59    }
60    let paso = intervalo.max(1) as i64;
61    let velas = ((hasta - desde) as f64 / paso as f64).ceil().max(0.0) as usize;
62    velas.div_ceil(VELAS_POR_PAGINA)
63}
64
65/// Descarga `desde..hasta` paginando hacia atrás.
66///
67/// `hasta` debe ser el cierre de una vela cerrada; usar [`ultimo_cierre`].
68pub async fn descargar(
69    broker: &dyn Broker,
70    simbolo: &str,
71    intervalo: u64,
72    desde: i64,
73    hasta: i64,
74) -> Result<Ventana, BrokerError> {
75    if intervalo == 0 {
76        return Err(BrokerError::Internal("intervalo de vela 0".into()));
77    }
78    if hasta <= desde {
79        return Ok(Ventana {
80            velas: Vec::new(),
81            paginas: 0,
82            completa: true,
83            truncada: false,
84            faltantes: 0,
85        });
86    }
87
88    let mut velas: Vec<Candle> = Vec::new();
89    let mut paginas = 0usize;
90    let mut to = hasta;
91    let mut truncada = false;
92
93    loop {
94        if paginas >= PAGINAS_MAXIMAS {
95            truncada = true;
96            break;
97        }
98        if to < desde {
99            break;
100        }
101        let request = CandleRequest {
102            symbol: simbolo.to_string(),
103            interval: intervalo,
104            count: VELAS_POR_PAGINA,
105            end_time: Some(to),
106        };
107        let pagina = broker.get_candles(request).await?;
108        paginas += 1;
109        if pagina.is_empty() {
110            // Retención del bróker: no hay nada más viejo.
111            break;
112        }
113
114        let antes = velas.len();
115        velas.extend(pagina.into_iter().filter(|v| v.from >= desde));
116        velas.sort_by_key(|v| v.from);
117        velas.dedup_by_key(|v| v.from);
118
119        let Some(mas_vieja) = velas.first().map(|v| v.from) else {
120            break;
121        };
122        if mas_vieja <= desde {
123            break;
124        }
125        if velas.len() == antes {
126            // La página no aportó nada nuevo: evita el bucle infinito.
127            break;
128        }
129        // `to` es inclusivo sobre el inicio: bajar un paso evita repetir la
130        // vela más vieja ya descargada.
131        to = mas_vieja - intervalo as i64;
132    }
133
134    let completa = velas.first().map(|v| v.from <= desde).unwrap_or(true);
135    let faltantes = faltantes(&velas, intervalo);
136    Ok(Ventana {
137        velas,
138        paginas,
139        completa,
140        truncada,
141        faltantes,
142    })
143}
144
145/// Huecos entre la primera y la última vela, medidos en velas de `intervalo`.
146pub fn faltantes(velas: &[Candle], intervalo: u64) -> usize {
147    let (Some(primera), Some(ultima)) = (velas.first(), velas.last()) else {
148        return 0;
149    };
150    let paso = intervalo.max(1) as i64;
151    let esperadas = ((ultima.to - primera.from) / paso).max(0) as usize;
152    esperadas.saturating_sub(velas.len())
153}
154
155#[cfg(test)]
156mod tests {
157    use super::*;
158
159    fn vela(from: i64, precio: f64) -> Candle {
160        Candle {
161            from,
162            to: from + 1,
163            open: precio,
164            close: precio,
165            high: precio,
166            low: precio,
167            volume: Some(1.0),
168        }
169    }
170
171    #[test]
172    fn ultimo_cierre_excluye_la_vela_en_curso() {
173        assert_eq!(ultimo_cierre(1_000, 60), 900);
174        assert_eq!(ultimo_cierre(1_000, 1), 999);
175        assert_eq!(ultimo_cierre(120, 60), 60);
176    }
177
178    #[test]
179    fn paginas_estimadas_cubre_la_semana() {
180        assert_eq!(paginas_estimadas(1, 0, 7 * 86_400), 605);
181        assert_eq!(paginas_estimadas(1, 0, 7_200), 8);
182        assert_eq!(paginas_estimadas(60, 0, 3_600), 1);
183        assert_eq!(paginas_estimadas(1, 100, 100), 0);
184        assert_eq!(paginas_estimadas(1, 200, 100), 0);
185    }
186
187    #[test]
188    fn faltantes_detecta_un_hueco() {
189        let velas = vec![vela(0, 1.0), vela(1, 1.1), vela(4, 1.2)];
190        assert_eq!(faltantes(&velas, 1), 2);
191        assert_eq!(faltantes(&velas[..2], 1), 0);
192        assert_eq!(faltantes(&[], 1), 0);
193    }
194}