Skip to main content

popo_cli/
feed.rs

1use crate::error::{PopoError, Result};
2use crate::models::{FeedIndex, VolcanoReport, SCHEMA_VERSION};
3use chrono::NaiveDate;
4use serde::de::DeserializeOwned;
5
6/// Where the published JSON lives by default.
7///
8/// The CLI deliberately does not talk to CENAPRED. That site sits behind a bot
9/// manager which serves an HTTP 200 challenge page to every non-browser client,
10/// so per-user scraping cannot work. Ingestion happens once, centrally, and
11/// this feed is the result. See `docs/feed-schema.md`.
12pub const DEFAULT_FEED_BASE: &str =
13    "https://raw.githubusercontent.com/KyleEdwardDonaldson/PopoCLI/main/data";
14
15/// Environment variable used to point the CLI at a different feed: a fork, a
16/// local mirror, or a directory on disk.
17pub const FEED_BASE_ENV: &str = "POPO_FEED_BASE";
18
19pub struct Feed {
20    client: reqwest::blocking::Client,
21    base: String,
22}
23
24impl Feed {
25    /// Build a client against the default feed, or whatever `POPO_FEED_BASE`
26    /// points at.
27    pub fn new() -> Self {
28        let base = std::env::var(FEED_BASE_ENV).unwrap_or_else(|_| DEFAULT_FEED_BASE.to_string());
29        Self::with_base(base)
30    }
31
32    /// Build a client against a specific feed. The base may be an HTTP(S) URL
33    /// or a filesystem path holding the same layout.
34    pub fn with_base(base: impl Into<String>) -> Self {
35        let client = reqwest::blocking::Client::builder()
36            .user_agent(concat!("popo-cli/", env!("CARGO_PKG_VERSION")))
37            .timeout(std::time::Duration::from_secs(30))
38            .build()
39            .expect("failed to build HTTP client");
40
41        Self {
42            client,
43            base: base.into().trim_end_matches(['/', '\\']).to_string(),
44        }
45    }
46
47    pub fn base(&self) -> &str {
48        &self.base
49    }
50
51    /// The most recently published report.
52    pub fn latest(&self) -> Result<VolcanoReport> {
53        let report: VolcanoReport = self.fetch("latest.json", None)?;
54        check_schema(report.schema_version)?;
55        Ok(report)
56    }
57
58    /// The report for a specific day.
59    pub fn get(&self, date: NaiveDate) -> Result<VolcanoReport> {
60        let path = format!("reports/{}/{}.json", date.format("%Y"), date);
61        let report: VolcanoReport = self.fetch(&path, Some(date))?;
62        check_schema(report.schema_version)?;
63        Ok(report)
64    }
65
66    /// Everything the feed currently carries.
67    pub fn index(&self) -> Result<FeedIndex> {
68        let index: FeedIndex = self.fetch("index.json", None)?;
69        check_schema(index.schema_version)?;
70        Ok(index)
71    }
72
73    fn fetch<T: DeserializeOwned>(&self, path: &str, date: Option<NaiveDate>) -> Result<T> {
74        let body = if self.is_remote() {
75            self.fetch_http(path, date)?
76        } else {
77            self.read_local(path, date)?
78        };
79
80        serde_json::from_str(&body).map_err(|e| {
81            PopoError::Parse(format!("feed returned malformed JSON for {}: {}", path, e))
82        })
83    }
84
85    fn is_remote(&self) -> bool {
86        self.base.starts_with("http://") || self.base.starts_with("https://")
87    }
88
89    fn fetch_http(&self, path: &str, date: Option<NaiveDate>) -> Result<String> {
90        let url = format!("{}/{}", self.base, path);
91        let response = self.client.get(&url).send()?;
92        let status = response.status();
93
94        if status == reqwest::StatusCode::NOT_FOUND {
95            return Err(match date {
96                Some(date) => PopoError::NotFound(date),
97                None => PopoError::Feed(format!(
98                    "{} is missing from the feed. The feed may not be published yet.",
99                    path
100                )),
101            });
102        }
103
104        if !status.is_success() {
105            return Err(PopoError::Feed(format!(
106                "feed request to {} failed with HTTP {}",
107                url, status
108            )));
109        }
110
111        Ok(response.text()?)
112    }
113
114    fn read_local(&self, path: &str, date: Option<NaiveDate>) -> Result<String> {
115        let full = std::path::Path::new(&self.base).join(path);
116        match std::fs::read_to_string(&full) {
117            Ok(body) => Ok(body),
118            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Err(match date {
119                Some(date) => PopoError::NotFound(date),
120                None => PopoError::LocalFeed {
121                    path: full.display().to_string(),
122                    source: e,
123                },
124            }),
125            Err(e) => Err(PopoError::LocalFeed {
126                path: full.display().to_string(),
127                source: e,
128            }),
129        }
130    }
131}
132
133impl Default for Feed {
134    fn default() -> Self {
135        Self::new()
136    }
137}
138
139fn check_schema(found: u32) -> Result<()> {
140    if found > SCHEMA_VERSION {
141        return Err(PopoError::UnsupportedSchema {
142            found,
143            supported: SCHEMA_VERSION,
144        });
145    }
146    Ok(())
147}
148
149#[cfg(test)]
150mod tests {
151    use super::*;
152    use std::fs;
153
154    fn write_fixture(dir: &std::path::Path) {
155        fs::create_dir_all(dir.join("reports/2026")).unwrap();
156        let report = r#"{
157            "schema_version": 1,
158            "date": "2026-08-04",
159            "exhalations": 160,
160            "volcanotectonic_events": 0,
161            "tremor_minutes_total": 0,
162            "explosions": 0,
163            "alert_level": "YELLOW",
164            "alert_phase": "AMARILLO FASE 2",
165            "wind_direction": "W",
166            "summary_spanish": "Se detectaron 160 exhalaciones.",
167            "ashfall_reports": [],
168            "image_urls": [],
169            "video_urls": [],
170            "source_url": "https://www.cenapred.unam.mx/",
171            "ingested_at": "2026-08-05T17:04:00Z"
172        }"#;
173        fs::write(dir.join("latest.json"), report).unwrap();
174        fs::write(dir.join("reports/2026/2026-08-04.json"), report).unwrap();
175    }
176
177    fn temp_dir(name: &str) -> std::path::PathBuf {
178        let dir = std::env::temp_dir().join(format!("popo-feed-test-{}", name));
179        let _ = fs::remove_dir_all(&dir);
180        fs::create_dir_all(&dir).unwrap();
181        dir
182    }
183
184    #[test]
185    fn reads_latest_from_local_feed() {
186        let dir = temp_dir("latest");
187        write_fixture(&dir);
188
189        let feed = Feed::with_base(dir.to_str().unwrap());
190        let report = feed.latest().unwrap();
191
192        assert_eq!(report.exhalations, Some(160));
193        assert_eq!(report.date, NaiveDate::from_ymd_opt(2026, 8, 4).unwrap());
194    }
195
196    #[test]
197    fn reads_specific_date_from_local_feed() {
198        let dir = temp_dir("bydate");
199        write_fixture(&dir);
200
201        let feed = Feed::with_base(dir.to_str().unwrap());
202        let date = NaiveDate::from_ymd_opt(2026, 8, 4).unwrap();
203        assert_eq!(feed.get(date).unwrap().date, date);
204    }
205
206    #[test]
207    fn missing_date_reports_not_found() {
208        let dir = temp_dir("missing");
209        write_fixture(&dir);
210
211        let feed = Feed::with_base(dir.to_str().unwrap());
212        let absent = NaiveDate::from_ymd_opt(1998, 1, 1).unwrap();
213
214        match feed.get(absent) {
215            Err(PopoError::NotFound(d)) => assert_eq!(d, absent),
216            other => panic!("expected NotFound, got {:?}", other.map(|r| r.date)),
217        }
218    }
219
220    /// A feed published by a newer ingester must not be silently misread.
221    #[test]
222    fn rejects_newer_schema_version() {
223        let dir = temp_dir("schema");
224        fs::create_dir_all(&dir).unwrap();
225        fs::write(
226            dir.join("latest.json"),
227            r#"{
228                "schema_version": 99,
229                "date": "2026-08-04",
230                "alert_level": "YELLOW",
231                "alert_phase": "AMARILLO FASE 2",
232                "ingested_at": "2026-08-05T17:04:00Z"
233            }"#,
234        )
235        .unwrap();
236
237        let feed = Feed::with_base(dir.to_str().unwrap());
238        match feed.latest() {
239            Err(PopoError::UnsupportedSchema { found, supported }) => {
240                assert_eq!(found, 99);
241                assert_eq!(supported, SCHEMA_VERSION);
242            }
243            other => panic!(
244                "expected UnsupportedSchema, got {:?}",
245                other.map(|r| r.date)
246            ),
247        }
248    }
249
250    #[test]
251    fn malformed_json_is_a_parse_error() {
252        let dir = temp_dir("malformed");
253        fs::write(dir.join("latest.json"), "not json at all").unwrap();
254
255        let feed = Feed::with_base(dir.to_str().unwrap());
256        assert!(matches!(feed.latest(), Err(PopoError::Parse(_))));
257    }
258
259    #[test]
260    fn base_url_trailing_slash_is_normalized() {
261        assert_eq!(
262            Feed::with_base("https://example.com/data/").base(),
263            "https://example.com/data"
264        );
265    }
266}