Skip to main content

autoeq_measurements/read/read_api/
fetch.rs

1use super::backend::{
2    FsMeasurementCache, MeasurementBackend, MeasurementCache, ReqwestMeasurementBackend,
3};
4#[cfg(test)]
5use super::backend::{InMemoryMeasurementCache, MockMeasurementBackend};
6use super::extract::extract_contour_data;
7use super::extract::extract_curve_by_name;
8use super::extract::extract_directivity_curves;
9use super::parse::parse_headphone_csv;
10use super::types::ContourPlotData;
11use crate::read::directory::{
12    cache_root, data_dir_for_cache_root, headphone_cache_dir_for_cache_root, measurement_filename,
13};
14use crate::read::plot::{normalize_plotly_json_from_str, normalize_plotly_value_with_suggestions};
15use crate::{DirectivityData, MeasurementRecord};
16use serde_json::Value;
17use std::error::Error;
18use std::path::Path;
19use urlencoding;
20
21/// Fetch a frequency response curve from the spinorama API
22///
23/// # Arguments
24/// * `speaker` - Speaker name
25/// * `version` - Measurement version
26/// * `measurement` - Measurement type (e.g., "CEA2034")
27/// * `curve_name` - Name of the specific curve to extract
28///
29/// # Returns
30/// * Result containing a Curve struct or an error
31pub async fn read_spinorama(
32    speaker: &str,
33    version: &str,
34    measurement: &str,
35    curve_name: &str,
36) -> Result<crate::Curve, Box<dyn Error>> {
37    fetch_curve_from_api(speaker, version, measurement, curve_name).await
38}
39
40/// Fetch a frequency response curve using an explicit cache root.
41pub async fn read_spinorama_at_cache_root(
42    speaker: &str,
43    version: &str,
44    measurement: &str,
45    curve_name: &str,
46    cache_root: &Path,
47) -> Result<crate::Curve, Box<dyn Error>> {
48    fetch_curve_from_api_at_cache_root(speaker, version, measurement, curve_name, cache_root).await
49}
50
51/// Fetch a frequency response curve from the spinorama API
52///
53/// # Arguments
54/// * `speaker` - Speaker name
55/// * `version` - Measurement version
56/// * `measurement` - Measurement type (e.g., "CEA2034")
57/// * `curve_name` - Name of the specific curve to extract
58///
59/// # Returns
60/// * Result containing a Curve struct or an error
61pub async fn fetch_curve_from_api(
62    speaker: &str,
63    version: &str,
64    measurement: &str,
65    curve_name: &str,
66) -> Result<crate::Curve, Box<dyn Error>> {
67    // Fetch the full measurement once, then extract the requested curve
68    let plot_data = fetch_measurement_plot_data(speaker, version, measurement).await?;
69    extract_curve_by_name(&plot_data, measurement, curve_name)
70}
71
72/// Fetch a frequency response curve using an explicit cache root.
73pub async fn fetch_curve_from_api_at_cache_root(
74    speaker: &str,
75    version: &str,
76    measurement: &str,
77    curve_name: &str,
78    cache_root: &Path,
79) -> Result<crate::Curve, Box<dyn Error>> {
80    let plot_data =
81        fetch_measurement_plot_data_at_cache_root(speaker, version, measurement, cache_root)
82            .await?;
83    extract_curve_by_name(&plot_data, measurement, curve_name)
84}
85
86/// Fetch a curve together with an API-origin provenance record.
87pub async fn fetch_record_from_api(
88    speaker: &str,
89    version: &str,
90    measurement: &str,
91    curve_name: &str,
92) -> Result<MeasurementRecord, Box<dyn Error>> {
93    let curve = fetch_curve_from_api(speaker, version, measurement, curve_name).await?;
94    let uri = format!(
95        "https://api.spinorama.org/v1/speaker/{}/version/{}/measurements/{}?measurement_format=json#{}",
96        urlencoding::encode(speaker),
97        urlencoding::encode(version),
98        urlencoding::encode(measurement),
99        urlencoding::encode(curve_name),
100    );
101    MeasurementRecord::from_api(curve, uri).map_err(|error| error.into())
102}
103
104/// Fetch and parse the full Plotly JSON object for a given measurement (single HTTP GET)
105///
106/// # Arguments
107/// * `speaker` - Speaker name
108/// * `version` - Measurement version
109/// * `measurement` - Measurement type (e.g., "CEA2034")
110///
111/// # Returns
112/// * Result containing the Plotly JSON data or an error
113pub async fn fetch_measurement_plot_data(
114    speaker: &str,
115    version: &str,
116    measurement: &str,
117) -> Result<Value, Box<dyn Error>> {
118    let root = cache_root();
119    fetch_measurement_plot_data_at_cache_root(speaker, version, measurement, &root).await
120}
121
122/// Fetch and parse Plotly JSON using an explicit cache root.
123pub async fn fetch_measurement_plot_data_at_cache_root(
124    speaker: &str,
125    version: &str,
126    measurement: &str,
127    cache_root: &Path,
128) -> Result<Value, Box<dyn Error>> {
129    fetch_measurement_plot_data_with_backend_at_cache_root(
130        speaker,
131        version,
132        measurement,
133        cache_root,
134        &ReqwestMeasurementBackend::new(),
135        &FsMeasurementCache::new(),
136    )
137    .await
138}
139
140/// Fetch and parse Plotly JSON using the supplied backend and cache.
141///
142/// This is the seam that makes network-dependent code testable: tests can pass
143/// an in-memory cache and a [`MockMeasurementBackend`] to run offline.
144pub async fn fetch_measurement_plot_data_with_backend(
145    speaker: &str,
146    version: &str,
147    measurement: &str,
148    backend: &dyn MeasurementBackend,
149    cache: &dyn MeasurementCache,
150) -> Result<Value, Box<dyn Error>> {
151    let root = cache_root();
152    fetch_measurement_plot_data_with_backend_at_cache_root(
153        speaker,
154        version,
155        measurement,
156        &root,
157        backend,
158        cache,
159    )
160    .await
161}
162
163/// Fetch and parse Plotly JSON using supplied adapters and an explicit root.
164pub async fn fetch_measurement_plot_data_with_backend_at_cache_root(
165    speaker: &str,
166    version: &str,
167    measurement: &str,
168    cache_root: &Path,
169    backend: &dyn MeasurementBackend,
170    cache: &dyn MeasurementCache,
171) -> Result<Value, Box<dyn Error>> {
172    // 1) Try local cache first: data_cached/speakers/org.spinorama/{speaker}/{measurement}.json
173    // We keep filename identical to measurement name when possible (with path separators replaced).
174    let cache_dir = data_dir_for_cache_root(cache_root, speaker);
175    let cache_file = cache_dir.join(measurement_filename(measurement));
176
177    if let Ok(Some(content)) = cache.read_to_string(&cache_file).await {
178        if let Ok(plot_data) = normalize_plotly_json_from_str(&content) {
179            return Ok(plot_data);
180        } else {
181            log::debug!(
182                "⚠️  Cache file exists but could not be parsed as Plotly JSON: {:?}",
183                cache_file
184            );
185        }
186    }
187
188    // URL-encode the parameters
189    let encoded_speaker = urlencoding::encode(speaker);
190    let encoded_version = urlencoding::encode(version);
191    let encoded_measurement = urlencoding::encode(measurement);
192
193    let url = format!(
194        "https://api.spinorama.org/v1/speaker/{}/version/{}/measurements/{}?measurement_format=json",
195        encoded_speaker, encoded_version, encoded_measurement
196    );
197
198    let body = backend.get_text(&url).await?;
199    let api_response: Value = serde_json::from_str(&body)?;
200
201    // Normalize from API response (array-of-string JSON) to Plotly JSON object
202    let plot_data = normalize_plotly_value_with_suggestions(&api_response).await?;
203
204    // 2) Save normalized Plotly JSON to cache for future use
205    if let Err(e) = cache.create_dir_all(&cache_dir).await {
206        log::debug!("⚠️  Failed to create cache dir {:?}: {}", cache_dir, e);
207    } else {
208        match serde_json::to_string(&plot_data) {
209            Ok(serialized) => {
210                if let Err(e) = cache.write(&cache_file, &serialized).await {
211                    log::debug!("⚠️  Failed to write cache file {:?}: {}", cache_file, e);
212                }
213            }
214            Err(e) => log::debug!("⚠️  Failed to serialize plot data for cache: {}", e),
215        }
216    }
217
218    Ok(plot_data)
219}
220
221/// Fetch directivity data (SPL Horizontal and SPL Vertical) from the spinorama API
222///
223/// # Arguments
224/// * `speaker` - Speaker name
225/// * `version` - Measurement version
226///
227/// # Returns
228/// * Result containing DirectivityData or an error
229///
230/// # Details
231/// Fetches both "SPL Horizontal" and "SPL Vertical" measurements, extracting
232/// all angle traces (typically -60° to +60° in 10° increments).
233pub async fn fetch_directivity_data(
234    speaker: &str,
235    version: &str,
236) -> Result<DirectivityData, Box<dyn Error>> {
237    let root = cache_root();
238    fetch_directivity_data_at_cache_root(speaker, version, &root).await
239}
240
241/// Fetch directivity data using an explicit cache root.
242pub async fn fetch_directivity_data_at_cache_root(
243    speaker: &str,
244    version: &str,
245    cache_root: &Path,
246) -> Result<DirectivityData, Box<dyn Error>> {
247    // Fetch horizontal data
248    let horizontal_data =
249        fetch_measurement_plot_data_at_cache_root(speaker, version, "SPL Horizontal", cache_root)
250            .await?;
251    let horizontal = extract_directivity_curves(&horizontal_data)?;
252
253    if horizontal.is_empty() {
254        return Err("No horizontal directivity curves found".into());
255    }
256
257    // Fetch vertical data
258    let vertical_data =
259        fetch_measurement_plot_data_at_cache_root(speaker, version, "SPL Vertical", cache_root)
260            .await?;
261    let vertical = extract_directivity_curves(&vertical_data)?;
262
263    if vertical.is_empty() {
264        return Err("No vertical directivity curves found".into());
265    }
266
267    Ok(DirectivityData {
268        horizontal,
269        vertical,
270    })
271}
272
273/// Fetch contour plot data (SPL Horizontal Contour or SPL Vertical Contour) from the spinorama API
274///
275/// # Arguments
276/// * `speaker` - Speaker name
277/// * `version` - Measurement version
278/// * `plane` - Either "horizontal" or "vertical"
279///
280/// # Returns
281/// * Result containing ContourPlotData or an error
282///
283/// # Details
284/// Fetches "SPL Horizontal Contour" or "SPL Vertical Contour" measurements, which are
285/// pre-computed heatmaps with full angle range (typically -180° to +180°).
286pub async fn fetch_contour_data(
287    speaker: &str,
288    version: &str,
289    plane: &str,
290) -> Result<ContourPlotData, Box<dyn Error>> {
291    let root = cache_root();
292    fetch_contour_data_at_cache_root(speaker, version, plane, &root).await
293}
294
295/// Fetch contour data using an explicit cache root.
296pub async fn fetch_contour_data_at_cache_root(
297    speaker: &str,
298    version: &str,
299    plane: &str,
300    cache_root: &Path,
301) -> Result<ContourPlotData, Box<dyn Error>> {
302    let measurement = match plane.to_lowercase().as_str() {
303        "horizontal" | "h" => "SPL Horizontal Contour",
304        "vertical" | "v" => "SPL Vertical Contour",
305        _ => {
306            return Err(format!("Invalid plane: {}. Use 'horizontal' or 'vertical'", plane).into());
307        }
308    };
309
310    let plot_data =
311        fetch_measurement_plot_data_at_cache_root(speaker, version, measurement, cache_root)
312            .await?;
313    extract_contour_data(&plot_data)
314}
315
316/// Fetch a headphone's frequency response from the spinorama API.
317///
318/// Uses `GET /v1/headphone/{name}/frequency_response`.
319/// The API returns CSV data (4-column: L_freq, L_spl, R_freq, R_spl with header rows).
320/// Caches the raw CSV and also writes a simplified 2-column CSV for the optimization pipeline.
321pub async fn fetch_headphone_frequency_response(
322    headphone: &str,
323) -> Result<(String, crate::Curve), Box<dyn Error>> {
324    let root = cache_root();
325    fetch_headphone_frequency_response_at_cache_root(headphone, &root).await
326}
327
328/// Fetch a headphone response using an explicit cache root.
329pub async fn fetch_headphone_frequency_response_at_cache_root(
330    headphone: &str,
331    cache_root: &Path,
332) -> Result<(String, crate::Curve), Box<dyn Error>> {
333    fetch_headphone_frequency_response_with_backend_at_cache_root(
334        headphone,
335        cache_root,
336        &ReqwestMeasurementBackend::new(),
337        &FsMeasurementCache::new(),
338    )
339    .await
340}
341
342/// Fetch a headphone response using the supplied backend and cache.
343pub async fn fetch_headphone_frequency_response_with_backend(
344    headphone: &str,
345    backend: &dyn MeasurementBackend,
346    cache: &dyn MeasurementCache,
347) -> Result<(String, crate::Curve), Box<dyn Error>> {
348    let root = cache_root();
349    fetch_headphone_frequency_response_with_backend_at_cache_root(headphone, &root, backend, cache)
350        .await
351}
352
353/// Fetch a headphone response using supplied adapters and an explicit root.
354pub async fn fetch_headphone_frequency_response_with_backend_at_cache_root(
355    headphone: &str,
356    cache_root: &Path,
357    backend: &dyn MeasurementBackend,
358    cache: &dyn MeasurementCache,
359) -> Result<(String, crate::Curve), Box<dyn Error>> {
360    let cache_dir = headphone_cache_dir_for_cache_root(cache_root, headphone);
361    let raw_cache = cache_dir.join("frequency_response_raw.csv");
362    let csv_path = cache_dir.join("measurement.csv");
363
364    // Try local cache first
365    let csv_text = if let Ok(Some(content)) = cache.read_to_string(&raw_cache).await {
366        content
367    } else {
368        fetch_headphone_csv_from_backend(headphone, &cache_dir, &raw_cache, backend, cache).await?
369    };
370
371    // Parse the CSV (handles 2-col and 4-col with multiple header rows)
372    let curve = parse_headphone_csv(&csv_text)?;
373
374    // Write simplified 2-column CSV for the optimization pipeline
375    cache.create_dir_all(&cache_dir).await?;
376    let mut out = String::from("frequency,spl\n");
377    for (f, s) in curve.freq.iter().zip(curve.spl.iter()) {
378        out.push_str(&format!("{},{}\n", f, s));
379    }
380    cache.write(&csv_path, &out).await?;
381
382    Ok((csv_path.to_string_lossy().to_string(), curve))
383}
384
385async fn fetch_headphone_csv_from_backend(
386    headphone: &str,
387    cache_dir: &std::path::Path,
388    raw_cache: &std::path::Path,
389    backend: &dyn MeasurementBackend,
390    cache: &dyn MeasurementCache,
391) -> Result<String, Box<dyn Error>> {
392    let encoded = urlencoding::encode(headphone);
393    let url = format!(
394        "https://api.spinorama.org/v1/headphone/{}/frequency_response",
395        encoded
396    );
397
398    let body = backend.get_text(&url).await?;
399
400    // Check for JSON error response (the API returns JSON errors even though
401    // successful responses are CSV)
402    if body.trim_start().starts_with('{')
403        && let Ok(json) = serde_json::from_str::<Value>(&body)
404        && let Some(error_msg) = json.get("error").and_then(|e| e.as_str())
405    {
406        return Err(error_msg.to_string().into());
407    }
408
409    // Cache the raw CSV
410    if let Err(e) = cache.create_dir_all(cache_dir).await {
411        log::debug!("Failed to create headphone cache dir: {}", e);
412    } else if let Err(e) = cache.write(raw_cache, &body).await {
413        log::debug!("Failed to write headphone cache: {}", e);
414    }
415
416    Ok(body)
417}
418
419#[cfg(test)]
420mod tests {
421    use super::*;
422    use crate::read::{
423        data_dir_for_cache_root, headphone_cache_dir_for_cache_root, measurement_filename,
424    };
425    use serde_json::json;
426    use tempfile::TempDir;
427
428    fn plotly_object() -> Value {
429        json!({
430            "data": [
431                {"name": "On Axis", "x": [100.0, 1000.0], "y": [80.0, 81.0]},
432                {"name": "Listening Window", "x": [100.0, 1000.0], "y": [82.0, 83.0]},
433                {"name": "Early Reflections", "x": [100.0, 1000.0], "y": [81.0, 82.0]},
434                {"name": "Sound Power", "x": [100.0, 1000.0], "y": [80.5, 81.5]},
435                {"name": "Early Reflections DI", "x": [100.0, 1000.0], "y": [1.0, 1.0]},
436                {"name": "Sound Power DI", "x": [100.0, 1000.0], "y": [0.5, 0.5]},
437            ]
438        })
439    }
440
441    fn setup_cache() -> TempDir {
442        TempDir::new().unwrap()
443    }
444
445    #[test]
446    fn explicit_cache_roots_are_isolated() {
447        let first = setup_cache();
448        let second = setup_cache();
449        let speaker = "isolated-speaker";
450        assert_ne!(
451            data_dir_for_cache_root(first.path(), speaker),
452            data_dir_for_cache_root(second.path(), speaker)
453        );
454    }
455
456    #[tokio::test]
457    async fn fetch_measurement_plot_data_uses_local_cache() {
458        let tmp = setup_cache();
459        let speaker = "cache-speaker";
460        let measurement = "CEA2034";
461        let cache_file =
462            data_dir_for_cache_root(tmp.path(), speaker).join(measurement_filename(measurement));
463        tokio::fs::create_dir_all(cache_file.parent().unwrap())
464            .await
465            .unwrap();
466        tokio::fs::write(
467            &cache_file,
468            serde_json::to_string(&plotly_object()).unwrap(),
469        )
470        .await
471        .unwrap();
472
473        let plot =
474            fetch_measurement_plot_data_at_cache_root(speaker, "asr", measurement, tmp.path())
475                .await
476                .unwrap();
477        assert!(plot.get("data").is_some());
478    }
479
480    #[tokio::test]
481    async fn fetch_curve_from_api_uses_cache() {
482        let tmp = setup_cache();
483        let speaker = "curve-speaker";
484        let cache_file =
485            data_dir_for_cache_root(tmp.path(), speaker).join(measurement_filename("CEA2034"));
486        tokio::fs::create_dir_all(cache_file.parent().unwrap())
487            .await
488            .unwrap();
489        tokio::fs::write(
490            &cache_file,
491            serde_json::to_string(&plotly_object()).unwrap(),
492        )
493        .await
494        .unwrap();
495
496        let curve =
497            fetch_curve_from_api_at_cache_root(speaker, "asr", "CEA2034", "On Axis", tmp.path())
498                .await
499                .unwrap();
500        assert_eq!(curve.freq.len(), 2);
501    }
502
503    #[tokio::test]
504    async fn fetch_directivity_data_uses_cache() {
505        let tmp = setup_cache();
506        let speaker = "dir-speaker";
507        for measurement in ["SPL Horizontal", "SPL Vertical"] {
508            let cache_file = data_dir_for_cache_root(tmp.path(), speaker)
509                .join(measurement_filename(measurement));
510            tokio::fs::create_dir_all(cache_file.parent().unwrap())
511                .await
512                .unwrap();
513            let plot = json!({
514                "data": [
515                    {"name": "-10°", "x": {"dtype": "f8", "bdata": ""}, "y": {"dtype": "f8", "bdata": ""}},
516                ]
517            });
518            tokio::fs::write(&cache_file, serde_json::to_string(&plot).unwrap())
519                .await
520                .unwrap();
521        }
522
523        let result = fetch_directivity_data_at_cache_root(speaker, "asr", tmp.path()).await;
524        // Empty base64 decodes to no curves, so this returns an error about missing curves.
525        assert!(result.is_err());
526    }
527
528    #[tokio::test]
529    async fn fetch_contour_data_uses_cache() {
530        let tmp = setup_cache();
531        let speaker = "contour-speaker";
532        let cache_file = data_dir_for_cache_root(tmp.path(), speaker)
533            .join(measurement_filename("SPL Horizontal Contour"));
534        tokio::fs::create_dir_all(cache_file.parent().unwrap())
535            .await
536            .unwrap();
537        let plot = json!({
538            "data": [{
539                "x": [100.0, 1000.0],
540                "y": [-10.0, 0.0, 10.0],
541                "z": [[80.0, 81.0], [82.0, 83.0], [84.0, 85.0]],
542            }]
543        });
544        tokio::fs::write(&cache_file, serde_json::to_string(&plot).unwrap())
545            .await
546            .unwrap();
547
548        let contour = fetch_contour_data_at_cache_root(speaker, "asr", "horizontal", tmp.path())
549            .await
550            .unwrap();
551        assert_eq!(contour.freq_count, 2);
552        assert_eq!(contour.angle_count, 3);
553    }
554
555    #[tokio::test]
556    async fn fetch_headphone_frequency_response_uses_cache() {
557        let tmp = setup_cache();
558        let headphone = "test-headphone";
559        let cache_dir = headphone_cache_dir_for_cache_root(tmp.path(), headphone);
560        tokio::fs::create_dir_all(&cache_dir).await.unwrap();
561        let csv = "20,100,20,104\n100,90,100,92\n";
562        tokio::fs::write(cache_dir.join("frequency_response_raw.csv"), csv)
563            .await
564            .unwrap();
565
566        let (path, curve) = fetch_headphone_frequency_response_at_cache_root(headphone, tmp.path())
567            .await
568            .unwrap();
569        assert!(path.contains("measurement.csv"));
570        assert_eq!(curve.freq.len(), 2);
571        assert!((curve.spl[0] - 102.0).abs() < 1e-9);
572    }
573
574    #[tokio::test]
575    async fn fetch_measurement_plot_data_with_backend_uses_cache_and_backend() {
576        let cache_root = std::path::Path::new("isolated-memory-cache");
577        let cache = InMemoryMeasurementCache::new();
578        let speaker = "mock-speaker";
579        let measurement = "CEA2034";
580        let cache_file =
581            data_dir_for_cache_root(cache_root, speaker).join(measurement_filename(measurement));
582
583        // First call: cache miss -> backend is queried.
584        // The backend returns the API array-of-string format.
585        let backend = MockMeasurementBackend::new(
586            serde_json::to_string(&json!([serde_json::to_string(&plotly_object()).unwrap()]))
587                .unwrap(),
588        );
589        let plot = fetch_measurement_plot_data_with_backend_at_cache_root(
590            speaker,
591            "asr",
592            measurement,
593            cache_root,
594            &backend,
595            &cache,
596        )
597        .await
598        .unwrap();
599        assert!(plot.get("data").is_some());
600        assert!(
601            cache.get(&cache_file).is_some(),
602            "plot data should be cached"
603        );
604
605        // Second call: cache hit -> backend is not queried (empty response would fail).
606        let silent_backend = MockMeasurementBackend::new("not-json");
607        let plot2 = fetch_measurement_plot_data_with_backend_at_cache_root(
608            speaker,
609            "asr",
610            measurement,
611            cache_root,
612            &silent_backend,
613            &cache,
614        )
615        .await
616        .unwrap();
617        assert!(plot2.get("data").is_some());
618    }
619}