goat_cli/utils/
field_registry.rs

1//!
2//! Runtime field registry, from the live GoaT `resultFields` endpoint.
3//!
4//! This lets the expression engine (`-e`) and variables (`-v`) accept fields
5//! that were added to GoaT after the last time the static variable-data file
6//! was regenerated, without requiring a binary rebuild.
7//!
8//! The registry is only loaded when an expression or variable list names a
9//! field the static data does not know (see [`prepare`](crate::utils::field_registry::prepare)), and the field
10//! names are cached on disk for a day, so most runs make no request for it.
11//!
12//! # Fallback behaviour
13//!
14//! If the HTTP request fails (network error, API down) the registry is
15//! silently left empty and all field lookups return `false`.  The static
16//! `GOAT_TAXON_VARIABLE_DATA` / `GOAT_ASSEMBLY_VARIABLE_DATA` maps are
17//! still used for detailed type-checking; the dynamic registry only widens
18//! the set of *accepted* field names.
19
20use std::collections::HashSet;
21use std::path::{Path, PathBuf};
22use std::sync::OnceLock;
23use std::time::{Duration, SystemTime};
24
25use serde_json::Value;
26
27use crate::client::GoatClient;
28use crate::utils::expression::{canonical_field, CLIexpression};
29use crate::utils::utils::parse_comma_separated;
30use crate::utils::variable_data::{GOAT_ASSEMBLY_VARIABLE_DATA, GOAT_TAXON_VARIABLE_DATA};
31use crate::{IndexType, GOAT_URL, TAXONOMY};
32
33/// How long the on-disk cache of field names is used before refetching.
34const CACHE_TTL: Duration = Duration::from_secs(24 * 60 * 60);
35
36static TAXON_FIELDS: OnceLock<HashSet<String>> = OnceLock::new();
37static ASSEMBLY_FIELDS: OnceLock<HashSet<String>> = OnceLock::new();
38
39fn cell_for(index_type: IndexType) -> &'static OnceLock<HashSet<String>> {
40    match index_type {
41        IndexType::Taxon => &TAXON_FIELDS,
42        IndexType::Assembly => &ASSEMBLY_FIELDS,
43    }
44}
45
46/// Where the field names for `index_type` are cached: under
47/// `$XDG_CACHE_HOME`, `~/.cache` or `%LOCALAPPDATA%`, in `goat-cli/`.
48fn cache_path(index_type: IndexType) -> Option<PathBuf> {
49    let base = std::env::var_os("XDG_CACHE_HOME")
50        .map(PathBuf::from)
51        .or_else(|| std::env::var_os("HOME").map(|home| PathBuf::from(home).join(".cache")))
52        .or_else(|| std::env::var_os("LOCALAPPDATA").map(PathBuf::from))?;
53    Some(base.join("goat-cli").join(format!("{}_fields.json", index_type)))
54}
55
56/// Read cached field names, if the cache exists and is fresh.
57fn read_cache(path: &Path) -> Option<HashSet<String>> {
58    let age = SystemTime::now()
59        .duration_since(std::fs::metadata(path).ok()?.modified().ok()?)
60        .ok()?;
61    if age > CACHE_TTL {
62        return None;
63    }
64    serde_json::from_str(&std::fs::read_to_string(path).ok()?).ok()
65}
66
67/// Cache field names. Best effort: failing to cache is not an error.
68fn write_cache(path: &Path, fields: &HashSet<String>) {
69    let write = || -> std::io::Result<()> {
70        std::fs::create_dir_all(path.parent().unwrap_or(Path::new(".")))?;
71        // write then rename, so a concurrent run never reads a partial file
72        let tmp = path.with_extension(format!("{}.tmp", std::process::id()));
73        std::fs::write(&tmp, serde_json::to_string(fields)?)?;
74        std::fs::rename(&tmp, path)
75    };
76    let _ = write();
77}
78
79/// Fetch all field names from the GoaT `resultFields` endpoint.
80///
81/// Returns `None` on any error, so that a failure is not cached.
82async fn fetch_fields(index_type: IndexType) -> Option<HashSet<String>> {
83    let url = format!(
84        "{}resultFields?result={}&taxonomy={}",
85        *GOAT_URL,
86        index_type,
87        *TAXONOMY
88    );
89    let v: Value = GoatClient::new().get_json(&url).await.ok()?;
90    v["fields"]
91        .as_object()
92        .map(|obj| obj.keys().cloned().collect())
93}
94
95/// Initialise the dynamic field registry for `index_type`, from the disk
96/// cache if it is fresh, otherwise from the API.
97///
98/// Safe to call multiple times — the work is done at most once.
99/// Errors are swallowed; the registry will simply be empty.
100pub async fn init(index_type: IndexType) {
101    let cell = cell_for(index_type);
102    if cell.get().is_some() {
103        return;
104    }
105    let path = cache_path(index_type);
106    let fields = match path.as_deref().and_then(read_cache) {
107        Some(fields) => fields,
108        None => match fetch_fields(index_type).await {
109            Some(fields) => {
110                if let Some(path) = &path {
111                    write_cache(path, &fields);
112                }
113                fields
114            }
115            None => HashSet::new(),
116        },
117    };
118    // Ignore the error — it just means another task beat us to it.
119    let _ = cell.set(fields);
120}
121
122/// Load the registry for `index_type` if any of `expressions` (e.g. `-e`, or
123/// `arc -x/-y`) or `variables` (`-v`) name a field that the static data does
124/// not know.
125///
126/// Call this before the arguments are parsed, so that parsing can accept
127/// fields added to GoaT since this binary was built.
128pub async fn prepare(expressions: &[&str], variables: Option<&str>, index_type: IndexType) {
129    let data = match index_type {
130        IndexType::Taxon => &*GOAT_TAXON_VARIABLE_DATA,
131        IndexType::Assembly => &*GOAT_ASSEMBLY_VARIABLE_DATA,
132    };
133    let unknown_in_expression = expressions
134        .iter()
135        .any(|e| CLIexpression::new(e).has_unknown_field(data));
136    let unknown_in_variables = variables.map_or(false, |v| {
137        parse_comma_separated(v)
138            .iter()
139            .any(|field| canonical_field(field, data).is_none())
140    });
141    if unknown_in_expression || unknown_in_variables {
142        init(index_type).await;
143    }
144}
145
146/// Returns a clone of all field names in the registry for `index_type`.
147///
148/// Returns an empty set if the registry has not been initialised yet.
149pub fn get_all_fields(index_type: IndexType) -> HashSet<String> {
150    cell_for(index_type)
151        .get()
152        .cloned()
153        .unwrap_or_default()
154}
155
156/// Returns `true` if `field` appears in the live GoaT field list for
157/// `index_type`.
158///
159/// Returns `false` both when the field is unknown **and** when the registry
160/// has not been initialised yet (i.e. [`init`] was not awaited before the
161/// expression was validated).
162pub fn is_dynamic_field(field: &str, index_type: IndexType) -> bool {
163    cell_for(index_type)
164        .get()
165        .map(|fields| fields.contains(field))
166        .unwrap_or(false)
167}
168
169/// Like [`is_dynamic_field`], for either index.
170pub fn is_dynamic_field_any(field: &str) -> bool {
171    is_dynamic_field(field, IndexType::Taxon) || is_dynamic_field(field, IndexType::Assembly)
172}
173
174#[cfg(test)]
175mod tests {
176    use super::*;
177
178    #[test]
179    fn test_cache_round_trip() {
180        let path = std::env::temp_dir()
181            .join(format!("goat_cli_registry_{}", std::process::id()))
182            .join("taxon_fields.json");
183        let fields: HashSet<String> = ["genome_size", "brand_new_field"]
184            .iter()
185            .map(|s| s.to_string())
186            .collect();
187        write_cache(&path, &fields);
188        assert_eq!(read_cache(&path), Some(fields));
189        std::fs::remove_dir_all(path.parent().unwrap()).unwrap();
190    }
191
192    #[test]
193    fn test_missing_cache_is_none() {
194        assert_eq!(read_cache(Path::new("/nonexistent/goat-cli/taxon_fields.json")), None);
195    }
196
197    #[test]
198    fn test_has_unknown_field() {
199        let data = &*GOAT_TAXON_VARIABLE_DATA;
200        assert!(!CLIexpression::new("genome_size > 1 OR max(c_value) < 2").has_unknown_field(data));
201        assert!(!CLIexpression::new("ebp_metric_date >= 2023").has_unknown_field(data));
202        assert!(CLIexpression::new("genome_size > 1 AND brand_new_field = x").has_unknown_field(data));
203    }
204}