Skip to main content

hyprstream_decision_stub/
facade.rs

1//! The jev-1 JSON/HTTPS facade: `POST /v1/systemone` + `GET /v1/models`.
2//!
3//! This is the portability surface the stock TypeSafe SDKs run against via
4//! `TYPESAFE_BASE_URL` (S6a §4). Behavior contract:
5//!
6//! - **Auth**: `Authorization: Bearer <anything>` is required (the SDKs refuse to run
7//!   keyless); any non-empty token is accepted. Missing/malformed → 401 with the
8//!   FastAPI-style `{"detail": …}` body (A10).
9//! - **Validation**: 422 with the FastAPI detail list shape for every request violation
10//!   ([`wire::parse_request`]).
11//! - **Alias resolution**: any requested model string resolves to
12//!   [`STUB_MODEL_VERSION`](crate::mock::STUB_MODEL_VERSION), echoed as `response.model`
13//!   (the "may differ from the alias supplied" rule is part of the contract).
14//! - **Usage**: `input_tokens = ceil(serialized_bytes / 4)` over the P0.1a canonical
15//!   serialization — a documented stub approximation (A11: the upstream tokenizer is
16//!   unspecified); `output_tokens` = total answered cardinality.
17//! - The SDKs' observability headers (`X-TypeSafe-*`) are accepted and ignored.
18
19use axum::body::Bytes;
20use axum::extract::State;
21use axum::http::{HeaderMap, StatusCode};
22use axum::response::{IntoResponse, Response};
23use axum::routing::{get, post};
24use axum::Router;
25use hyprstream_decision::serialize;
26use serde_json::{Map, Value};
27
28use crate::mock::{MockDecisionModel, STUB_MODEL_ALIAS, STUB_MODEL_VERSION};
29use crate::render;
30use crate::wire::{self, WireError};
31
32/// The facade routes, ready to layer onto any axum server.
33pub fn router() -> Router {
34    Router::new()
35        .route("/v1/systemone", post(post_system_one))
36        .route("/v1/models", get(get_models))
37        .with_state(MockDecisionModel)
38}
39
40fn error_response(error: WireError) -> Response {
41    (
42        StatusCode::from_u16(error.status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR),
43        [("content-type", "application/json")],
44        error.body,
45    )
46        .into_response()
47}
48
49fn check_auth(headers: &HeaderMap) -> Result<(), WireError> {
50    let valid = headers
51        .get("authorization")
52        .and_then(|value| value.to_str().ok())
53        .and_then(|value| value.strip_prefix("Bearer "))
54        .is_some_and(|token| !token.trim().is_empty());
55    if valid {
56        Ok(())
57    } else {
58        Err(WireError::simple(
59            401,
60            "missing or malformed Authorization header; expected `Bearer <token>`",
61        ))
62    }
63}
64
65async fn post_system_one(
66    State(mock): State<MockDecisionModel>,
67    headers: HeaderMap,
68    body: Bytes,
69) -> Response {
70    if let Err(error) = check_auth(&headers) {
71        return error_response(error);
72    }
73    let request = match wire::parse_request(&body) {
74        Ok(request) => request,
75        Err(error) => return error_response(error),
76    };
77
78    let state_text = request.state.canonical_text();
79    let row = mock.answer_row(&request.set, &state_text, 0);
80    let output_tokens: usize = row
81        .answers
82        .values()
83        .filter_map(|answer| answer.value.as_ref())
84        .map(|value| value.probabilities().len())
85        .sum();
86
87    let mut usage = Map::new();
88    let mut push_int = |key: &str, value: usize| {
89        usage.insert(
90            key.to_owned(),
91            Value::Number(serde_json::Number::from(value as u64)),
92        );
93    };
94    push_int(
95        "input_tokens",
96        serialize::serialized_bytes(&request.set).div_ceil(4),
97    );
98    push_int("output_tokens", output_tokens);
99
100    let mut response = Map::new();
101    response.insert(
102        "model".to_owned(),
103        Value::String(STUB_MODEL_VERSION.to_owned()),
104    );
105    response.insert(
106        "answers".to_owned(),
107        render::render_answers(&request.set, &row),
108    );
109    response.insert("usage".to_owned(), Value::Object(usage));
110
111    let body = serde_json::to_string(&Value::Object(response))
112        .unwrap_or_else(|_| r#"{"detail":"serialization failed"}"#.to_owned());
113    (StatusCode::OK, [("content-type", "application/json")], body).into_response()
114}
115
116async fn get_models() -> Response {
117    let body = serde_json::json!({
118        "models": [
119            {
120                "name": STUB_MODEL_ALIAS,
121                "description": "Alias for the deterministic System One stub (resolves to jev-stub-1.0.0).",
122                "release_date": "2026-09-18",
123            },
124            {
125                "name": STUB_MODEL_VERSION,
126                "description": "Deterministic mock decision model (System One P0.7); hash-drawn distributions, schema-valid jev-1 answers.",
127                "release_date": "2026-09-18",
128            }
129        ]
130    });
131    (
132        StatusCode::OK,
133        [("content-type", "application/json")],
134        body.to_string(),
135    )
136        .into_response()
137}
138
139/// Bind the facade on `listener` and serve it in the background. Returns the bound
140/// address (use `:0` for an ephemeral port) and a handle that stops the server on abort.
141pub async fn serve(
142    listener: std::net::TcpListener,
143) -> std::io::Result<(std::net::SocketAddr, tokio::task::JoinHandle<()>)> {
144    listener.set_nonblocking(true)?;
145    let address = listener.local_addr()?;
146    let handle = tokio::spawn(async move {
147        let listener = tokio::net::TcpListener::from_std(listener)
148            .unwrap_or_else(|error| panic!("tokio listener: {error}"));
149        axum::serve(listener, router())
150            .await
151            .unwrap_or_else(|error| panic!("facade server: {error}"));
152    });
153    Ok((address, handle))
154}
155
156#[cfg(test)]
157mod tests {
158    use super::*;
159
160    #[tokio::test]
161    async fn end_to_end_round_trip() {
162        let listener = std::net::TcpListener::bind("127.0.0.1:0")
163            .unwrap_or_else(|error| panic!("bind: {error}"));
164        let (address, server) = serve(listener)
165            .await
166            .unwrap_or_else(|error| panic!("serve: {error}"));
167        let client = reqwest::Client::new();
168        let response = client
169            .post(format!("http://{address}/v1/systemone"))
170            .header("authorization", "Bearer test")
171            .header("content-type", "application/json")
172            .body(
173                r#"{"state": "The box was crushed.", "model": "jev-latest", "questions": {"tone": {"type": "choice", "criteria": {"angry": null, "calm": null}}}}"#,
174            )
175            .send()
176            .await
177            .unwrap_or_else(|error| panic!("request: {error}"));
178        assert_eq!(response.status(), 200);
179        let body: Value = response
180            .json()
181            .await
182            .unwrap_or_else(|error| panic!("json: {error}"));
183        assert_eq!(
184            body["model"], STUB_MODEL_VERSION,
185            "alias resolves to the versioned id"
186        );
187        assert_eq!(body["answers"]["tone"]["type"], "choice");
188        server.abort();
189    }
190
191    #[tokio::test]
192    async fn missing_auth_is_401() {
193        let listener = std::net::TcpListener::bind("127.0.0.1:0")
194            .unwrap_or_else(|error| panic!("bind: {error}"));
195        let (address, server) = serve(listener)
196            .await
197            .unwrap_or_else(|error| panic!("serve: {error}"));
198        let response = reqwest::Client::new()
199            .post(format!("http://{address}/v1/systemone"))
200            .header("content-type", "application/json")
201            .body("{}")
202            .send()
203            .await
204            .unwrap_or_else(|error| panic!("request: {error}"));
205        assert_eq!(response.status(), 401);
206        let body: Value = response
207            .json()
208            .await
209            .unwrap_or_else(|error| panic!("json: {error}"));
210        assert!(
211            body["detail"].is_string(),
212            "FastAPI simple detail shape: {body}"
213        );
214        server.abort();
215    }
216
217    #[tokio::test]
218    async fn invalid_question_is_422_fastapi_shape() {
219        let listener = std::net::TcpListener::bind("127.0.0.1:0")
220            .unwrap_or_else(|error| panic!("bind: {error}"));
221        let (address, server) = serve(listener)
222            .await
223            .unwrap_or_else(|error| panic!("serve: {error}"));
224        let response = reqwest::Client::new()
225            .post(format!("http://{address}/v1/systemone"))
226            .header("authorization", "Bearer test")
227            .header("content-type", "application/json")
228            .body(r#"{"state": "x", "model": "m", "questions": {"q": {"type": "choice"}}}"#)
229            .send()
230            .await
231            .unwrap_or_else(|error| panic!("request: {error}"));
232        assert_eq!(response.status(), 422);
233        let body: Value = response
234            .json()
235            .await
236            .unwrap_or_else(|error| panic!("json: {error}"));
237        let detail = body["detail"]
238            .as_array()
239            .unwrap_or_else(|| panic!("detail list"));
240        assert!(!detail.is_empty());
241        assert!(
242            detail[0]["loc"].is_array()
243                && detail[0]["msg"].is_string()
244                && detail[0]["type"].is_string()
245        );
246        server.abort();
247    }
248}