Skip to main content

radio_cli/podcast/
directory.rs

1//! Public, regional podcast charts with lazy RSS resolution on selection.
2use super::{error, feed};
3use crate::{config::Config, store::Store};
4use anyhow::Result;
5use rand::seq::SliceRandom;
6use serde_json::{Value, json};
7use std::{
8    collections::{HashMap, HashSet},
9    sync::{
10        Arc, Mutex, OnceLock,
11        atomic::{AtomicBool, Ordering},
12    },
13    time::{Duration, Instant},
14};
15
16// Apple Podcasts' top-level category IDs. Keep slugs stable for CLI scripts.
17pub const CATEGORIES: &[(&str, &str, &str, &str)] = &[
18    ("1301", "arts", "Arts", "艺术"),
19    ("1321", "business", "Business", "商务"),
20    ("1303", "comedy", "Comedy", "喜剧"),
21    ("1304", "education", "Education", "教育"),
22    ("1483", "fiction", "Fiction", "小说"),
23    ("1511", "government", "Government", "政府"),
24    ("1512", "health-fitness", "Health & Fitness", "健康与健身"),
25    ("1487", "history", "History", "历史"),
26    ("1305", "kids-family", "Kids & Family", "儿童与家庭"),
27    ("1502", "leisure", "Leisure", "休闲"),
28    ("1310", "music", "Music", "音乐"),
29    ("1489", "news", "News", "新闻"),
30    (
31        "1314",
32        "religion-spirituality",
33        "Religion & Spirituality",
34        "宗教与心灵",
35    ),
36    ("1533", "science", "Science", "科学"),
37    ("1324", "society-culture", "Society & Culture", "社会与文化"),
38    ("1545", "sports", "Sports", "体育"),
39    ("1318", "technology", "Technology", "科技"),
40    ("1488", "true-crime", "True Crime", "犯罪纪实"),
41    ("1309", "tv-film", "TV & Film", "电视与电影"),
42];
43
44pub fn category_id(value: &str) -> std::result::Result<String, String> {
45    CATEGORIES
46        .iter()
47        .find(|(id, slug, _, _)| *id == value || *slug == value)
48        .map(|(id, _, _, _)| (*id).into())
49        .ok_or_else(|| crate::t!("podcast_invalid_category").into())
50}
51
52pub fn country(config: &Config, value: &str) -> Result<String> {
53    let value = if value.is_empty() {
54        config.settings.podcasts.country.as_deref().unwrap_or(
55            if crate::messages::locale() == crate::messages::Locale::ZhCn {
56                "CN"
57            } else {
58                "US"
59            },
60        )
61    } else {
62        value
63    };
64    if value.len() != 2 || !value.bytes().all(|c| c.is_ascii_alphabetic()) {
65        return Err(error(crate::t!("podcast_invalid_country")));
66    }
67    Ok(value.to_ascii_uppercase())
68}
69
70pub fn categories(country: &str) -> Value {
71    let zh = crate::messages::locale() == crate::messages::Locale::ZhCn;
72    let rows: Vec<_> = CATEGORIES
73        .iter()
74        .map(|(id, slug, en, cn)| {
75            json!({
76                "id": id, "slug": slug, "title": if zh {cn} else {en},
77                "kind": "category", "meta": slug,
78                "command": format!("podcast charts --country {country} --category {slug}"),
79            })
80        })
81        .collect();
82    json!({"items": rows, "total": rows.len(), "feed_title": format!("{} · {country}", crate::t!("podcast_categories"))})
83}
84
85pub fn home(country: &str) -> Value {
86    let rows = vec![
87        json!({"title": crate::t!("podcast_charts"), "command": format!("podcast charts --country {country}")}),
88        json!({"title": crate::t!("podcast_categories"), "command": format!("podcast categories --country {country}")}),
89        json!({"title": crate::t!("podcast_surprise"), "description": crate::t!("podcast_random_scope"), "command": format!("podcast charts --country {country} --random")}),
90        json!({"title": crate::t!("podcast_search_prompt"), "command": format!("podcast search --country {country} "), "input": true}),
91        json!({"title": crate::t!("podcast_region"), "command": "podcast browse --country ", "input": true}),
92        json!({"title": crate::t!("podcast_subscriptions"), "command": "podcast list"}),
93    ];
94    let rows: Vec<_> = rows
95        .into_iter()
96        .map(|mut v| {
97            v["kind"] = json!("directory");
98            v
99        })
100        .collect();
101    json!({"items": rows, "total": rows.len(), "feed_title": format!("{} · {country}", crate::t!("podcast_browse"))})
102}
103
104fn parse_chart(value: &Value, country: &str) -> Result<Vec<Value>> {
105    let feed = value
106        .get("feed")
107        .and_then(Value::as_object)
108        .ok_or_else(|| error(crate::t!("podcast_invalid_feed")))?;
109    // Apple omits entry when a storefront/category has no chart.
110    let empty = vec![];
111    let entries = match feed.get("entry") {
112        None => &empty,
113        Some(Value::Array(rows)) => rows,
114        _ => return Err(error(crate::t!("podcast_invalid_feed"))),
115    };
116    let mut seen = HashSet::new();
117    let rows = entries.iter().take(100).enumerate().filter_map(|(rank, entry)| {
118        let id = entry["id"]["attributes"]["im:id"].as_str()?;
119        if id.is_empty() || !id.bytes().all(|c| c.is_ascii_digit()) || !seen.insert(id.to_owned()) {
120            return None;
121        }
122        let title = entry["im:name"]["label"].as_str().filter(|s| !s.is_empty())?;
123        Some(json!({
124            "collectionId": id, "collectionName": title,
125            "artistName": entry["im:artist"]["label"].as_str().unwrap_or(""),
126            "collectionViewUrl": format!("https://podcasts.apple.com/{}/podcast/id{id}", country.to_ascii_lowercase()),
127            "description": entry["summary"]["label"].as_str().unwrap_or(""),
128            "primaryGenreName": entry["category"]["attributes"]["label"].as_str().unwrap_or(""),
129            "chartRank": rank + 1,
130        }))
131    }).collect::<Vec<_>>();
132    if !entries.is_empty() && rows.is_empty() {
133        return Err(error(crate::t!("podcast_invalid_feed")));
134    }
135    Ok(rows)
136}
137
138#[derive(Default)]
139struct Cache {
140    pages: HashMap<String, (Instant, Vec<Value>)>,
141    retry_at: Option<Instant>,
142}
143static CACHE: OnceLock<Mutex<Cache>> = OnceLock::new();
144
145fn fetch_chart(
146    config: &Config,
147    url: &str,
148    country: &str,
149    stop: &Arc<AtomicBool>,
150) -> Result<Vec<Value>> {
151    if stop.load(Ordering::Relaxed) {
152        return Err(crate::error::DomainError::new(crate::error::ErrorCode::Cancelled).into());
153    }
154    let cache = CACHE.get_or_init(Mutex::default);
155    {
156        let cache = cache.lock().unwrap();
157        if let Some((at, rows)) = cache.pages.get(url)
158            && at.elapsed() < Duration::from_secs(600)
159        {
160            return Ok(rows.clone());
161        }
162        if cache.retry_at.is_some_and(|at| at > Instant::now()) {
163            return Err(error(crate::t!("podcast_rate_limited")));
164        }
165    }
166    let response = feed::client(config)?
167        .get(url)
168        .send()
169        .map_err(feed::network_error)?;
170    if response.status() == 429 {
171        let seconds = response
172            .headers()
173            .get("retry-after")
174            .and_then(|v| v.to_str().ok())
175            .and_then(|s| s.parse::<u64>().ok())
176            .unwrap_or(60)
177            .clamp(1, 3600);
178        cache.lock().unwrap().retry_at = Some(Instant::now() + Duration::from_secs(seconds));
179        return Err(error(crate::t!("podcast_rate_limited")));
180    }
181    let (_, data) = feed::body(response, stop)?;
182    let value =
183        serde_json::from_slice(&data).map_err(|_| error(crate::t!("podcast_invalid_feed")))?;
184    let rows = parse_chart(&value, country)?;
185    let mut cache = cache.lock().unwrap();
186    if cache.pages.len() >= 32 {
187        cache.pages.clear();
188    }
189    cache
190        .pages
191        .insert(url.into(), (Instant::now(), rows.clone()));
192    Ok(rows)
193}
194
195pub fn annotate_subscriptions(store: &Store, rows: &mut [Value]) -> Result<()> {
196    for row in rows {
197        let url = row["feedUrl"]
198            .as_str()
199            .or_else(|| row["collectionViewUrl"].as_str());
200        if let Some(feed) = url
201            .map(|url| store.podcast_by_url(url))
202            .transpose()?
203            .flatten()
204            && feed.subscribed
205        {
206            row["local_feed_id"] = json!(feed.id);
207        }
208    }
209    Ok(())
210}
211
212pub fn charts(
213    config: &Config,
214    store: &Store,
215    country: &str,
216    category: Option<&str>,
217    limit: u16,
218    random: bool,
219    stop: &Arc<AtomicBool>,
220) -> Result<Value> {
221    let genre = category
222        .map(category_id)
223        .transpose()
224        .map_err(|e| error(&e))?;
225    let url = format!(
226        "https://itunes.apple.com/{}/rss/toppodcasts/limit=100{}/json",
227        country.to_ascii_lowercase(),
228        genre
229            .as_ref()
230            .map(|id| format!("/genre={id}"))
231            .unwrap_or_default()
232    );
233    let mut rows = fetch_chart(config, &url, country, stop)?;
234    if random {
235        rows.shuffle(&mut rand::rng());
236    }
237    rows.truncate(usize::from(limit));
238    annotate_subscriptions(store, &mut rows)?;
239    if random {
240        for row in &mut rows {
241            row["description"] = json!(format!(
242                "{}\n\n{}",
243                crate::t!("podcast_random_scope"),
244                row["description"].as_str().unwrap_or("")
245            ));
246        }
247    }
248    let label = if random {
249        crate::t!("podcast_surprise")
250    } else {
251        crate::t!("podcast_charts")
252    };
253    let category_label = genre
254        .as_ref()
255        .and_then(|id| CATEGORIES.iter().find(|(key, _, _, _)| key == id))
256        .map(|(_, _, en, cn)| {
257            if crate::messages::locale() == crate::messages::Locale::ZhCn {
258                *cn
259            } else {
260                *en
261            }
262        });
263    Ok(
264        json!({"items": rows, "total": rows.len(), "country": country,
265        "category": genre, "random": random, "source": "Apple Podcasts",
266        "feed_title": format!("{label} · {country}{} · Apple Podcasts", category_label.map(|name| format!(" · {name}")).unwrap_or_default())}),
267    )
268}
269
270#[cfg(test)]
271mod tests {
272    use super::*;
273    #[test]
274    fn random_candidates_keep_rank_identity_and_leave_the_chart_unchanged() {
275        let dir = tempfile::tempdir().unwrap();
276        let config = crate::test_support::config(dir.path());
277        let store = Store::open(&config.data_dir.join("radio.db")).unwrap();
278        let url = "https://itunes.apple.com/zz/rss/toppodcasts/limit=100/genre=1318/json";
279        let rows = (1..=100).map(|n| json!({"collectionId":n.to_string(),"collectionName":format!("Show {n}"),"chartRank":n})).collect();
280        CACHE
281            .get_or_init(Mutex::default)
282            .lock()
283            .unwrap()
284            .pages
285            .insert(url.into(), (Instant::now(), rows));
286        let stop = Arc::new(AtomicBool::new(false));
287        let random = charts(&config, &store, "ZZ", Some("technology"), 10, true, &stop).unwrap();
288        let rows = random["items"].as_array().unwrap();
289        assert_eq!(rows.len(), 10);
290        let ids = rows
291            .iter()
292            .map(|row| row["collectionId"].as_str().unwrap())
293            .collect::<HashSet<_>>();
294        assert_eq!(ids.len(), 10);
295        for row in rows {
296            assert_eq!(
297                row["collectionId"].as_str().unwrap(),
298                row["chartRank"].to_string()
299            );
300            assert!((1..=100).contains(&row["chartRank"].as_u64().unwrap()));
301        }
302        let chart = charts(&config, &store, "ZZ", Some("1318"), 10, false, &stop).unwrap();
303        assert_eq!(chart["items"][0]["chartRank"], 1);
304        assert_eq!(chart["items"][9]["chartRank"], 10);
305        CACHE.get().unwrap().lock().unwrap().pages.remove(url);
306    }
307    #[test]
308    fn chart_cache_errors_cancellation_and_cooldown_are_bounded() {
309        use std::{
310            io::{Read, Write},
311            net::TcpListener,
312            thread,
313        };
314        let dir = tempfile::tempdir().unwrap();
315        let config = crate::test_support::config(dir.path());
316        let stop = Arc::new(AtomicBool::new(false));
317        let serve = |status: &str, body: &str| {
318            let listener = TcpListener::bind("127.0.0.1:0").unwrap();
319            let url = format!("http://{}", listener.local_addr().unwrap());
320            let reply = format!(
321                "HTTP/1.1 {status}\r\nContent-Length: {}\r\nConnection: close\r\nRetry-After: 60\r\n\r\n{body}",
322                body.len()
323            );
324            let task = thread::spawn(move || {
325                let (mut stream, _) = listener.accept().unwrap();
326                stream
327                    .set_read_timeout(Some(Duration::from_secs(2)))
328                    .unwrap();
329                let mut buf = [0; 4096];
330                let n = stream.read(&mut buf).unwrap();
331                assert!(n > 0);
332                stream.write_all(reply.as_bytes()).unwrap();
333            });
334            (url, task)
335        };
336        let (url, task) = serve(
337            "200 OK",
338            r#"{"feed":{"entry":[{"id":{"attributes":{"im:id":"123"}},"im:name":{"label":"Example"}}]}}"#,
339        );
340        let rows = fetch_chart(&config, &url, "US", &stop).unwrap();
341        task.join().unwrap();
342        assert_eq!(fetch_chart(&config, &url, "US", &stop).unwrap(), rows);
343        stop.store(true, Ordering::Relaxed);
344        assert!(fetch_chart(&config, &url, "US", &stop).is_err());
345        stop.store(false, Ordering::Relaxed);
346        let (bad, task) = serve("200 OK", "not json");
347        assert!(fetch_chart(&config, &bad, "US", &stop).is_err());
348        task.join().unwrap();
349        assert!(
350            !CACHE
351                .get()
352                .unwrap()
353                .lock()
354                .unwrap()
355                .pages
356                .contains_key(&bad)
357        );
358        let (limited, task) = serve("429 Too Many Requests", "");
359        assert!(fetch_chart(&config, &limited, "US", &stop).is_err());
360        task.join().unwrap();
361        let err = fetch_chart(&config, "http://127.0.0.1:1/uncontacted", "US", &stop).unwrap_err();
362        assert!(err.to_string().contains(crate::t!("podcast_rate_limited")));
363        CACHE.get().unwrap().lock().unwrap().retry_at = None;
364    }
365    #[test]
366    fn charts_preserve_rank_and_resolve_only_when_selected() {
367        let value = json!({"feed":{"entry":[
368            {"id":{"attributes":{"im:id":"123"}},"im:name":{"label":"科技"},"im:artist":{"label":"作者"}},
369            {"id":{"attributes":{"im:id":"123"}},"im:name":{"label":"Duplicate"}},
370            {"id":{"attributes":{"im:id":"456"}},"im:name":{"label":"Second"}},
371            {"id":{"attributes":{"im:id":"../bad"}},"im:name":{"label":"Invalid"}}
372        ]}});
373        let rows = parse_chart(&value, "CN").unwrap();
374        assert_eq!(rows.len(), 2);
375        assert_eq!(rows[1]["chartRank"], 3);
376        assert_eq!(
377            rows[0]["collectionViewUrl"],
378            "https://podcasts.apple.com/cn/podcast/id123"
379        );
380        assert!(rows[0].get("feedUrl").is_none());
381        assert!(parse_chart(&json!({"feed":{}}), "US").unwrap().is_empty());
382        assert!(parse_chart(&json!({"error":"not a chart"}), "US").is_err());
383        assert!(parse_chart(&json!({"feed":{"entry":{}}}), "US").is_err());
384    }
385    #[test]
386    fn directory_options_are_validated_before_networking() {
387        let dir = tempfile::tempdir().unwrap();
388        let config = crate::test_support::config(dir.path());
389        assert_eq!(country(&config, "cn").unwrap(), "CN");
390        assert!(country(&config, "../cn").is_err());
391        assert_eq!(category_id("technology").unwrap(), "1318");
392        assert_eq!(category_id("1318").unwrap(), "1318");
393        assert!(category_id("not-a-category").is_err());
394        let cancelled = Arc::new(AtomicBool::new(true));
395        assert!(fetch_chart(&config, "https://example.invalid", "CN", &cancelled).is_err());
396    }
397}