1use 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 fn stats(&self) -> Result<serde_json::Value, String>;
71 fn query(&self, request: &PoetLibraryQueryRequest) -> Result<serde_json::Value, String>;
73 fn ingest(&self, request: &PoetLibraryIngestRequest) -> Result<serde_json::Value, String>;
75}
76
77static LIBRARY_PROVIDER: OnceLock<Arc<dyn PoetLibraryProvider>> = OnceLock::new();
78
79pub 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
196pub 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
212pub 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
235pub 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}