Skip to main content

qualia_core_db/services/
poet_library_api.rs

1//! Host-injected Semantic Library boundary for the standalone POET browser.
2//!
3//! The loopback router stays independent of `qualia-client-core`; native hosts
4//! inject the persistent HypermediaStore implementation during cold startup.
5
6use std::sync::{Arc, OnceLock};
7
8use axum::{
9    body::Bytes,
10    http::StatusCode,
11    response::{IntoResponse, Response},
12    Json,
13};
14use serde::{Deserialize, Serialize};
15
16pub const LIBRARY_REQUEST_LIMIT_BYTES: usize = 2 * 1024 * 1024;
17const LIBRARY_TEXT_LIMIT_BYTES: usize = 1024 * 1024;
18const MAX_FACET_VALUES: usize = 32;
19
20#[derive(Debug, Clone, Default, Serialize, Deserialize)]
21pub struct PoetLibraryQueryRequest {
22    #[serde(default)]
23    pub query: String,
24    #[serde(default)]
25    pub section: Option<String>,
26    #[serde(default)]
27    pub sort: Option<String>,
28    #[serde(default)]
29    pub topics: Vec<String>,
30    #[serde(default)]
31    pub purposes: Vec<String>,
32    #[serde(default)]
33    pub projects: Vec<String>,
34    #[serde(default)]
35    pub media_types: Vec<String>,
36    #[serde(default)]
37    pub categories: Vec<String>,
38}
39
40#[derive(Debug, Clone, Serialize, Deserialize)]
41pub struct PoetLibraryIngestRequest {
42    pub uri: String,
43    #[serde(default = "default_media_type")]
44    pub media_type: String,
45    pub text: String,
46    #[serde(default)]
47    pub section: Option<String>,
48    #[serde(default)]
49    pub sensitivity: Option<String>,
50    #[serde(default)]
51    pub projects: Vec<String>,
52    #[serde(default)]
53    pub purposes: Vec<String>,
54    #[serde(default)]
55    pub occurred_at: Option<i64>,
56    #[serde(default)]
57    pub place_label: Option<String>,
58    #[serde(default)]
59    pub lat: Option<f32>,
60    #[serde(default)]
61    pub lon: Option<f32>,
62}
63
64fn default_media_type() -> String {
65    "text/markdown".into()
66}
67
68pub trait PoetLibraryProvider: Send + Sync + 'static {
69    /// Library stats.
70    fn stats(&self) -> Result<serde_json::Value, String>;
71    /// Library query.
72    fn query(&self, request: &PoetLibraryQueryRequest) -> Result<serde_json::Value, String>;
73    /// Library ingest.
74    fn ingest(&self, request: &PoetLibraryIngestRequest) -> Result<serde_json::Value, String>;
75}
76
77static LIBRARY_PROVIDER: OnceLock<Arc<dyn PoetLibraryProvider>> = OnceLock::new();
78
79/// Registers `poet-library-provider`.
80pub fn register_poet_library_provider(
81    provider: Arc<dyn PoetLibraryProvider>,
82) -> Result<(), &'static str> {
83    LIBRARY_PROVIDER
84        .set(provider)
85        .map_err(|_| "a POET Semantic Library provider is already registered")
86}
87
88fn diagnostic(status: StatusCode, code: &'static str, message: impl Into<String>) -> Response {
89    (
90        status,
91        Json(serde_json::json!({
92            "ok": false,
93            "honesty": "unavailable",
94            "code": code,
95            "diagnostic": message.into()
96        })),
97    )
98        .into_response()
99}
100
101fn decode<T: serde::de::DeserializeOwned>(body: &Bytes) -> Result<T, Response> {
102    if body.len() > LIBRARY_REQUEST_LIMIT_BYTES {
103        return Err(diagnostic(
104            StatusCode::PAYLOAD_TOO_LARGE,
105            "payload_too_large",
106            "Semantic Library requests are limited to 2 MiB",
107        ));
108    }
109    serde_json::from_slice(body)
110        .map_err(|error| diagnostic(StatusCode::BAD_REQUEST, "invalid_json", error.to_string()))
111}
112
113fn validate_query(request: &mut PoetLibraryQueryRequest) -> Result<(), &'static str> {
114    request.query = request.query.trim().to_string();
115    if request.query.len() > 512 {
116        return Err("library query cannot exceed 512 bytes");
117    }
118    if let Some(section) = request.section.as_mut() {
119        *section = section.trim().to_ascii_lowercase();
120        if section.len() > 32 {
121            return Err("library section cannot exceed 32 bytes");
122        }
123    }
124    for values in [
125        &request.topics,
126        &request.purposes,
127        &request.projects,
128        &request.media_types,
129        &request.categories,
130    ] {
131        if values.len() > MAX_FACET_VALUES || values.iter().any(|value| value.len() > 128) {
132            return Err("each facet supports at most 32 values of at most 128 bytes");
133        }
134    }
135    Ok(())
136}
137
138fn validate_ingest(request: &mut PoetLibraryIngestRequest) -> Result<(), &'static str> {
139    request.uri = request.uri.trim().to_string();
140    request.media_type = request.media_type.trim().to_ascii_lowercase();
141    if request.uri.is_empty() || request.uri.len() > 2048 {
142        return Err("asset URI must contain between 1 and 2048 bytes");
143    }
144    if request.media_type.is_empty() || request.media_type.len() > 128 {
145        return Err("media type must contain between 1 and 128 bytes");
146    }
147    if request.text.trim().is_empty() || request.text.len() > LIBRARY_TEXT_LIMIT_BYTES {
148        return Err("document text must contain between 1 byte and 1 MiB");
149    }
150    if request.projects.len() > MAX_FACET_VALUES
151        || request.purposes.len() > MAX_FACET_VALUES
152        || request
153            .projects
154            .iter()
155            .chain(&request.purposes)
156            .any(|value| value.len() > 128)
157    {
158        return Err("ingest facets support at most 32 values of at most 128 bytes");
159    }
160    if let (Some(lat), Some(lon)) = (request.lat, request.lon) {
161        if !(-90.0..=90.0).contains(&lat) || !(-180.0..=180.0).contains(&lon) {
162            return Err("latitude or longitude is outside its valid range");
163        }
164    } else if request.lat.is_some() || request.lon.is_some() {
165        return Err("latitude and longitude must be supplied together");
166    }
167    Ok(())
168}
169
170fn provider() -> Result<Arc<dyn PoetLibraryProvider>, Response> {
171    LIBRARY_PROVIDER.get().cloned().ok_or_else(|| {
172        diagnostic(
173            StatusCode::SERVICE_UNAVAILABLE,
174            "provider_unavailable",
175            "This daemon host has no registered Semantic Library provider",
176        )
177    })
178}
179
180fn provider_result(result: Result<serde_json::Value, String>) -> Response {
181    match result {
182        Ok(data) => Json(serde_json::json!({
183            "ok": true,
184            "honesty": "live",
185            "data": data
186        }))
187        .into_response(),
188        Err(error) => diagnostic(
189            StatusCode::UNPROCESSABLE_ENTITY,
190            "library_operation_failed",
191            error,
192        ),
193    }
194}
195
196/// HTTP `stats` handler.
197pub async fn stats_handler() -> Response {
198    let provider = match provider() {
199        Ok(provider) => provider,
200        Err(response) => return response,
201    };
202    match tokio::task::spawn_blocking(move || provider.stats()).await {
203        Ok(result) => provider_result(result),
204        Err(error) => diagnostic(
205            StatusCode::INTERNAL_SERVER_ERROR,
206            "library_worker_failed",
207            error.to_string(),
208        ),
209    }
210}
211
212/// HTTP `query` handler.
213pub async fn query_handler(body: Bytes) -> Response {
214    let mut request: PoetLibraryQueryRequest = match decode(&body) {
215        Ok(request) => request,
216        Err(response) => return response,
217    };
218    if let Err(error) = validate_query(&mut request) {
219        return diagnostic(StatusCode::BAD_REQUEST, "invalid_query", error);
220    }
221    let provider = match provider() {
222        Ok(provider) => provider,
223        Err(response) => return response,
224    };
225    match tokio::task::spawn_blocking(move || provider.query(&request)).await {
226        Ok(result) => provider_result(result),
227        Err(error) => diagnostic(
228            StatusCode::INTERNAL_SERVER_ERROR,
229            "library_worker_failed",
230            error.to_string(),
231        ),
232    }
233}
234
235/// HTTP `ingest` handler.
236pub async fn ingest_handler(body: Bytes) -> Response {
237    let mut request: PoetLibraryIngestRequest = match decode(&body) {
238        Ok(request) => request,
239        Err(response) => return response,
240    };
241    if let Err(error) = validate_ingest(&mut request) {
242        return diagnostic(StatusCode::BAD_REQUEST, "invalid_ingest", error);
243    }
244    let provider = match provider() {
245        Ok(provider) => provider,
246        Err(response) => return response,
247    };
248    match tokio::task::spawn_blocking(move || provider.ingest(&request)).await {
249        Ok(result) => provider_result(result),
250        Err(error) => diagnostic(
251            StatusCode::INTERNAL_SERVER_ERROR,
252            "library_worker_failed",
253            error.to_string(),
254        ),
255    }
256}
257
258#[cfg(test)]
259mod tests {
260    use super::*;
261
262    #[test]
263    fn query_facet_count_is_bounded() {
264        let mut request = PoetLibraryQueryRequest {
265            topics: vec!["x".into(); MAX_FACET_VALUES + 1],
266            ..Default::default()
267        };
268        assert!(validate_query(&mut request).is_err());
269    }
270
271    #[test]
272    fn ingest_requires_paired_valid_coordinates() {
273        let mut request = PoetLibraryIngestRequest {
274            uri: "urn:test".into(),
275            media_type: "text/plain".into(),
276            text: "hello".into(),
277            section: None,
278            sensitivity: None,
279            projects: Vec::new(),
280            purposes: Vec::new(),
281            occurred_at: None,
282            place_label: None,
283            lat: Some(91.0),
284            lon: Some(0.0),
285        };
286        assert!(validate_ingest(&mut request).is_err());
287        request.lat = Some(45.0);
288        request.lon = None;
289        assert!(validate_ingest(&mut request).is_err());
290    }
291
292    #[tokio::test]
293    async fn missing_provider_is_explicit() {
294        assert_eq!(
295            stats_handler().await.status(),
296            StatusCode::SERVICE_UNAVAILABLE
297        );
298    }
299
300    #[tokio::test]
301    async fn oversized_request_is_rejected_before_provider_lookup() {
302        let response =
303            query_handler(Bytes::from(vec![b'x'; LIBRARY_REQUEST_LIMIT_BYTES + 1])).await;
304        assert_eq!(response.status(), StatusCode::PAYLOAD_TOO_LARGE);
305    }
306}