Skip to main content

qualia_core_db/domains/geospatial/adapters/
gbif_adapter.rs

1use crate::domains::geospatial::adapters::AdapterHttpRequest;
2use crate::net::disclosure::NetworkDisclosureRegistry;
3
4/// Adapter for GBIF occurrence API bbox queries.
5pub struct GbifAdapter {
6    pub id: &'static str,
7    pub occurrence_endpoint: String,
8}
9
10impl GbifAdapter {
11    /// Creates a GBIF adapter for `occurrence_endpoint`.
12    pub fn new(id: &'static str, occurrence_endpoint: &str) -> Self {
13        Self {
14            id,
15            occurrence_endpoint: occurrence_endpoint.to_string(),
16        }
17    }
18}
19
20impl GbifAdapter {
21    /// Stable adapter identifier.
22    pub fn adapter_id(&self) -> &'static str {
23        self.id
24    }
25
26    /// Builds a GBIF occurrence fetch request for a region.
27    pub fn build_fetch_request(
28        &self,
29        bbox: (f64, f64, f64, f64),
30        time_range: (u64, u64),
31        registry: &NetworkDisclosureRegistry,
32    ) -> Result<AdapterHttpRequest, String> {
33        if !registry.check_egress_consent(self.adapter_id(), &self.occurrence_endpoint) {
34            return Err(format!(
35                "Consent denied or unregistered for endpoint {} by adapter {}",
36                self.occurrence_endpoint,
37                self.adapter_id()
38            ));
39        }
40
41        let gbif_query = format!(
42            "{}?decimalLatitude={},{}&decimalLongitude={},{}&year={},{}",
43            self.occurrence_endpoint, bbox.1, bbox.3, bbox.0, bbox.2, time_range.0, time_range.1
44        );
45
46        Ok(AdapterHttpRequest::get(gbif_query, "GBIF"))
47    }
48
49    /// Parse a GBIF occurrence-search JSON response body into provenance `NQuin`s.
50    ///
51    /// The `results` array (each element an occurrence record) is mapped to a set of
52    /// Dublin Core / WGS84 provenance quins per record, using `generate_60bit_token`
53    /// for IRI/literal hashing so the emitted data is queryable by the SPARQL layer
54    /// (which hashes IRIs the same way). If `results` is absent an empty `Vec` is
55    /// returned. Only invalid JSON yields an `Err`.
56    pub fn parse_features(&self, body: &str) -> Result<Vec<crate::NQuin>, String> {
57        use crate::lexicon::generate_60bit_token;
58
59        // Predicate / type-object hashes (constant per call).
60        let title = generate_60bit_token(b"http://purl.org/dc/terms/title");
61        let ty = generate_60bit_token(b"http://www.w3.org/1999/02/22-rdf-syntax-ns#type");
62        let license = generate_60bit_token(b"http://purl.org/dc/terms/license");
63        let created = generate_60bit_token(b"http://purl.org/dc/terms/created");
64        let source = generate_60bit_token(b"http://purl.org/dc/terms/source");
65        let lat_p = generate_60bit_token(b"http://www.w3.org/2003/01/geo/wgs84_pos#lat");
66        let long_p = generate_60bit_token(b"http://www.w3.org/2003/01/geo/wgs84_pos#long");
67        let kind = generate_60bit_token(b"https://www.gbif.org/occurrence");
68
69        fn quin(s: u64, p: u64, o: u64) -> crate::NQuin {
70            crate::NQuin {
71                subject: s,
72                predicate: p,
73                object: o,
74                context: 0,
75                metadata: 0,
76                parity: s ^ p ^ o,
77            }
78        }
79
80        let json: serde_json::Value = serde_json::from_str(body).map_err(|e| e.to_string())?;
81
82        let mut quins = Vec::new();
83        let results = match json.get("results").and_then(|r| r.as_array()) {
84            Some(arr) => arr,
85            None => return Ok(quins),
86        };
87
88        for rec in results {
89            // `key` identifies the occurrence; skip records without one.
90            let key = match rec.get("key").and_then(|k| k.as_u64()) {
91                Some(k) => k,
92                None => continue,
93            };
94            let occ_iri = format!("https://www.gbif.org/occurrence/{key}");
95            let subject = generate_60bit_token(occ_iri.as_bytes());
96
97            // rdf:type -> gbif occurrence (always).
98            quins.push(quin(subject, ty, kind));
99
100            if let Some(name) = rec.get("scientificName").and_then(|v| v.as_str()) {
101                quins.push(quin(subject, title, generate_60bit_token(name.as_bytes())));
102            }
103            if let Some(lic) = rec.get("license").and_then(|v| v.as_str()) {
104                quins.push(quin(subject, license, generate_60bit_token(lic.as_bytes())));
105            }
106            if let Some(date) = rec.get("eventDate").and_then(|v| v.as_str()) {
107                quins.push(quin(
108                    subject,
109                    created,
110                    generate_60bit_token(date.as_bytes()),
111                ));
112            }
113
114            // dc:source -> occurrence IRI (always).
115            quins.push(quin(
116                subject,
117                source,
118                generate_60bit_token(occ_iri.as_bytes()),
119            ));
120
121            if let Some(lat) = rec.get("decimalLatitude").and_then(|v| v.as_f64()) {
122                quins.push(quin(subject, lat_p, lat.to_bits()));
123            }
124            if let Some(lon) = rec.get("decimalLongitude").and_then(|v| v.as_f64()) {
125                quins.push(quin(subject, long_p, lon.to_bits()));
126            }
127        }
128
129        Ok(quins)
130    }
131
132    /// Fetches occurrence records covering the region.
133    pub fn fetch_region(
134        &self,
135        bbox: (f64, f64, f64, f64),
136        time_range: (u64, u64),
137        registry: &NetworkDisclosureRegistry,
138    ) -> Result<(), String> {
139        let request = self.build_fetch_request(bbox, time_range, registry)?;
140        super::execute_http_request_status(&request)?;
141        // Parsing JSON and emitting 4D semantic points is deferred.
142        Ok(())
143    }
144}
145
146#[cfg(test)]
147mod tests {
148    use super::*;
149
150    #[test]
151    fn test_gbif_adapter_egress() {
152        let adapter = GbifAdapter::new("gbif_adapter", "https://api.gbif.org/v1/occurrence/search");
153        let registry = NetworkDisclosureRegistry::new();
154
155        // Without egress registration, the request must fail (disclosure gate).
156        let res1 = adapter.fetch_region((10.0, 45.0, 11.0, 46.0), (2020, 2024), &registry);
157        assert!(res1.is_err());
158
159        let mut registry = registry;
160        registry.register_egress(
161            adapter.adapter_id(),
162            "https://api.gbif.org/v1/occurrence/search",
163            "Fetch species occurrence records in bbox",
164            "User enables biodiversity layer",
165        );
166
167        // With egress registered, the disclosure gate passes. The actual HTTP
168        // call may fail due to network unavailability — that's not a logic bug.
169        // We only assert that the egress gate itself passed (i.e., the error
170        // is not a disclosure-gate error).
171        let res2 = adapter.fetch_region((10.0, 45.0, 11.0, 46.0), (2020, 2024), &registry);
172        match res2 {
173            Ok(()) => {}
174            Err(e) if e.contains("disclosure") || e.contains("egress") => {
175                panic!("egress gate should have passed after registration: {e}");
176            }
177            Err(e) => {
178                // Network error — skip gracefully.
179                eprintln!("gbif egress test skipped (network): {e}");
180            }
181        }
182    }
183
184    #[test]
185    fn test_gbif_parse_features() {
186        use crate::lexicon::generate_60bit_token;
187
188        let adapter = GbifAdapter::new("gbif_adapter", "https://api.gbif.org/v1/occurrence/search");
189
190        // Realistic 2-occurrence fixture.
191        // Record 1: full record -> type, title, license, created, source, lat, long = 7 quins.
192        // Record 2: minimal (no license/eventDate/coords) -> type, title, source = 3 quins.
193        let body = r#"{
194            "offset": 0,
195            "limit": 20,
196            "endOfRecords": false,
197            "count": 1234,
198            "results": [
199                {
200                    "key": 123456,
201                    "scientificName": "Panthera leo",
202                    "decimalLatitude": -1.2,
203                    "decimalLongitude": 36.8,
204                    "eventDate": "2019-05-01T00:00:00",
205                    "datasetKey": "abc-def",
206                    "license": "http://creativecommons.org/licenses/by/4.0/legalcode"
207                },
208                {
209                    "key": 654321,
210                    "scientificName": "Loxodonta africana"
211                }
212            ]
213        }"#;
214
215        let quins = adapter.parse_features(body).expect("valid JSON parses");
216        // 7 from record 1 + 3 from record 2 = 10.
217        assert_eq!(quins.len(), 10, "expected 10 quins, got {}", quins.len());
218
219        // Recompute expected hashes the same way the parser does.
220        let title = generate_60bit_token(b"http://purl.org/dc/terms/title");
221        let subj1 = generate_60bit_token(b"https://www.gbif.org/occurrence/123456");
222        let title_obj1 = generate_60bit_token(b"Panthera leo");
223
224        assert!(
225            quins
226                .iter()
227                .any(|q| q.subject == subj1 && q.predicate == title && q.object == title_obj1),
228            "expected TITLE quin for Panthera leo not found"
229        );
230
231        // Absent-results object -> empty Vec, not an error.
232        let empty = adapter
233            .parse_features(r#"{"offset":0,"count":0}"#)
234            .expect("no results field is not an error");
235        assert!(empty.is_empty());
236
237        // Invalid JSON -> Err.
238        assert!(adapter.parse_features("{not json").is_err());
239    }
240}