Skip to main content

qualia_core_db/services/
poet_render_api.rs

1//! Host-injected rendering boundary for the POET loopback API.
2//!
3//! `qualia-core-db` owns routing and scene authoring but deliberately does not
4//! depend on `webizen-render`. Native hosts register an implementation at cold
5//! startup, avoiding a dependency cycle while keeping browser responses honest.
6
7use std::sync::{Arc, OnceLock};
8
9use axum::{
10    body::Bytes,
11    http::StatusCode,
12    response::{IntoResponse, Response},
13    Json,
14};
15use serde::{Deserialize, Serialize};
16
17use super::poet_api::POET_PAYLOAD_LIMIT_BYTES;
18
19#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
20pub struct PoetRenderRequest {
21    pub kind: String,
22    #[serde(default)]
23    pub width: Option<u32>,
24    #[serde(default)]
25    pub height: Option<u32>,
26}
27
28#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
29pub struct PoetRenderResponse {
30    pub ok: bool,
31    pub kind: String,
32    pub honesty: String,
33    pub width: u32,
34    pub height: u32,
35    pub node_count: usize,
36    pub edge_count: usize,
37    pub face_count: usize,
38    pub data_uri: Option<String>,
39    pub diagnostic: Option<String>,
40    pub contract: String,
41}
42
43pub trait PoetRenderProvider: Send + Sync + 'static {
44    /// Renders a preview.
45    fn render_preview(&self, request: &PoetRenderRequest) -> PoetRenderResponse;
46}
47
48static RENDER_PROVIDER: OnceLock<Arc<dyn PoetRenderProvider>> = OnceLock::new();
49
50/// Install the process-wide renderer during native host startup.
51pub fn register_poet_render_provider(
52    provider: Arc<dyn PoetRenderProvider>,
53) -> Result<(), &'static str> {
54    RENDER_PROVIDER
55        .set(provider)
56        .map_err(|_| "a POET render provider is already registered")
57}
58
59fn normalise_request(mut request: PoetRenderRequest) -> Result<PoetRenderRequest, &'static str> {
60    request.kind = request.kind.trim().to_string();
61    if request.kind.is_empty() || request.kind.len() > 64 {
62        return Err("render kind must contain between 1 and 64 bytes");
63    }
64    request.width = Some(request.width.unwrap_or(960).clamp(160, 1920));
65    request.height = Some(request.height.unwrap_or(480).clamp(120, 1080));
66    Ok(request)
67}
68
69fn unavailable(request: &PoetRenderRequest, diagnostic: impl Into<String>) -> PoetRenderResponse {
70    PoetRenderResponse {
71        ok: false,
72        kind: request.kind.clone(),
73        honesty: "unavailable".into(),
74        width: request.width.unwrap_or(960),
75        height: request.height.unwrap_or(480),
76        node_count: 0,
77        edge_count: 0,
78        face_count: 0,
79        data_uri: None,
80        diagnostic: Some(diagnostic.into()),
81        contract: "webizen_render::scene_contract::RenderScene".into(),
82    }
83}
84
85/// HTTP `render-preview` handler.
86pub async fn render_preview_handler(body: Bytes) -> Response {
87    if body.len() > POET_PAYLOAD_LIMIT_BYTES {
88        return (
89            StatusCode::PAYLOAD_TOO_LARGE,
90            Json(serde_json::json!({
91                "ok": false,
92                "diagnostic": "POET render requests are limited to 64 KiB"
93            })),
94        )
95            .into_response();
96    }
97
98    let request = match serde_json::from_slice::<PoetRenderRequest>(&body)
99        .map_err(|error| error.to_string())
100        .and_then(|request| normalise_request(request).map_err(str::to_string))
101    {
102        Ok(request) => request,
103        Err(diagnostic) => {
104            return (
105                StatusCode::BAD_REQUEST,
106                Json(serde_json::json!({ "ok": false, "diagnostic": diagnostic })),
107            )
108                .into_response();
109        }
110    };
111
112    let Some(provider) = RENDER_PROVIDER.get().cloned() else {
113        return (
114            StatusCode::SERVICE_UNAVAILABLE,
115            Json(unavailable(
116                &request,
117                "This daemon host has no registered webizen-render provider",
118            )),
119        )
120            .into_response();
121    };
122
123    let fallback = request.clone();
124    match tokio::task::spawn_blocking(move || provider.render_preview(&request)).await {
125        Ok(result) => Json(result).into_response(),
126        Err(error) => (
127            StatusCode::INTERNAL_SERVER_ERROR,
128            Json(unavailable(
129                &fallback,
130                format!("Renderer worker failed: {error}"),
131            )),
132        )
133            .into_response(),
134    }
135}
136
137#[cfg(test)]
138mod tests {
139    use super::*;
140
141    #[test]
142    fn request_dimensions_are_bounded() {
143        let request = normalise_request(PoetRenderRequest {
144            kind: " map ".into(),
145            width: Some(1),
146            height: Some(u32::MAX),
147        })
148        .unwrap();
149        assert_eq!(request.kind, "map");
150        assert_eq!(request.width, Some(160));
151        assert_eq!(request.height, Some(1080));
152    }
153
154    #[tokio::test]
155    async fn oversized_request_is_rejected_before_provider_lookup() {
156        let response =
157            render_preview_handler(Bytes::from(vec![b'x'; POET_PAYLOAD_LIMIT_BYTES + 1])).await;
158        assert_eq!(response.status(), StatusCode::PAYLOAD_TOO_LARGE);
159    }
160
161    #[tokio::test]
162    async fn missing_provider_is_reported_as_unavailable() {
163        let response = render_preview_handler(Bytes::from_static(
164            br#"{"kind":"map","width":320,"height":180}"#,
165        ))
166        .await;
167        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
168    }
169}