Skip to content
1        10        20        30        40        50        60        70        80        901//! HTTP surface.2//!3//! The endpoints mirror the Python API, plus the extras a local service wants:4//!5//! | Method | Path | Python equivalent |6//! | --- | --- | --- |7//! | `GET` | `/` | — (playground page, key embedded) |8//! | `POST` | `/v1/classify_text` | `model.classify_text(text, tasks, ...)` |9//! | `POST` | `/v1/batch_classify_text` | `model.batch_classify_text(texts, tasks, ...)` |10//! | `POST` | `/v1/extract` | `model.extract_json(text, structures, ...)` |11//! | `GET` | `/health` | — |12//!13//! The `/v1` POST routes check `X-Api-Key` (or `Authorization: Bearer <key>`)14//! against `API_KEY` when that variable is set; `GET /` and `GET /health` stay15//! public. Without `API_KEY` everything is open, which is the default local16//! mode.1718use actix_web::{19    App, FromRequest, HttpRequest, HttpResponse, HttpServer, Responder, dev::Payload,20    http::StatusCode, http::header, web,21};2223use crate::config::Config;24use crate::decisions::{25    AppState, BatchClassifyRequest, ClassifyRequest, ErrorResponse, ExtractRequest,26};2728mod playground;2930/// Port the playground page calls itself on when none is handed in.31///32/// [`run`] passes the configured port; the default keeps [`configure`] usable33/// from tests that only exercise auth or shapes.34const DEFAULT_PLAYGROUND_PORT: u16 = 8080;3536/// The API key the `/v1` routes demand, from `API_KEY`.37struct ApiKey(Option<String>);3839/// The playground page, rendered once at startup and served from memory.40struct Playground {41    html: std::sync::Arc<String>,42}4344async fn health(state: web::Data<AppState>) -> impl Responder {45    let _ = state;46    HttpResponse::Ok().json(serde_json::json!({47        "status": "ok",48        "local": true,49        "engine": "GLiNER2.5-Decide"50    }))51}5253async fn playground(page: web::Data<Playground>) -> impl Responder {54    let html = page.html.clone();55    HttpResponse::Ok()56        .content_type("text/html; charset=utf-8")57        .body(html.as_str().to_owned())58}5960/// Proof that a request carried the configured API key.61///62/// An extractor ordered before the JSON body: when `API_KEY` is set and neither63/// header matches, extraction fails with `401` before the payload is read.64/// `X-Api-Key` is the header the playground sets; `Authorization: Bearer` is65/// accepted for clients that speak the standard header.66struct Authorized;6768impl FromRequest for Authorized {69    type Error = actix_web::Error;70    type Future = std::future::Ready<Result<Self, Self::Error>>;7172    fn from_request(request: &HttpRequest, _payload: &mut Payload) -> Self::Future {73        let expected = request74            .app_data::<web::Data<ApiKey>>()75            .and_then(|key| key.0.as_deref());76        let result = match expected {77            // No key configured: the endpoint is open.78            None => Ok(Self),79            Some(expected) => sent_key(request)80                .filter(|key| constant_time_eq(key, expected))81                .map_or_else(|| Err(unauthorized()), |_| Ok(Self)),82        };83        std::future::ready(result)84    }85}8687/// Header name for `X-Api-Key`, the one the playground sets.88///89/// `actix-http` re-exports only the standard names, so this one is parsed from90/// its wire form; the parse cannot fail for a valid lowercase name.91fn x_api_key() -> header::HeaderName {92    static NAME: std::sync::OnceLock<header::HeaderName> = std::sync::OnceLock::new();93    NAME.get_or_init(|| {94        header::HeaderName::from_lowercase(b"x-api-key").expect("x-api-key is a valid header name")95    })96    .clone()97}9899/// The key a request presents, from either accepted header.100fn sent_key(request: &HttpRequest) -> Option<&str> {101    let text_of = |name: &header::HeaderName| {102        request103            .headers()104            .get(name)105            .and_then(|value| value.to_str().ok())106            .map(str::trim)107    };108    text_of(&x_api_key())109        .or_else(|| {110            text_of(&header::AUTHORIZATION)111                .and_then(|value| value.strip_prefix("Bearer "))112                .map(str::trim)113        })114        .filter(|key| !key.is_empty())115}116117/// The `401` an unmatched key gets, shaped like every other error answer.118fn unauthorized() -> actix_web::Error {119    actix_web::error::InternalError::from_response(120        "unauthorized",121        HttpResponse::Unauthorized().json(ErrorResponse {122            error: "missing or invalid API key".to_owned(),123        }),124    )125    .into()126}127128/// Compare two strings without short-circuiting on the first mismatch byte.129fn constant_time_eq(left: &str, right: &str) -> bool {130    if left.len() != right.len() {131        return false;132    }133    let mut diff = 0u8;134    for (a, b) in left.bytes().zip(right.bytes()) {135        diff |= a ^ b;136    }137    diff == 0138}139140async fn classify(141    state: web::Data<AppState>,142    _api_key: Authorized,143    payload: web::Json<ClassifyRequest>,144) -> HttpResponse {145    let request = payload.into_inner();146    let result = web::block(move || {147        crate::decisions::classify(148            &state,149            &request.text,150            &request.tasks,151            request.include_confidence,152            request.max_len,153        )154    })155    .await;156157    respond(result)158}159160async fn batch_classify(161    state: web::Data<AppState>,162    _api_key: Authorized,163    payload: web::Json<BatchClassifyRequest>,164) -> HttpResponse {165    let request = payload.into_inner();166    let result = web::block(move || {167        crate::decisions::batch_classify(168            &state,169            &request.texts,170            &request.tasks,171            request.include_confidence,172            request.max_len,173        )174    })175    .await;176177    respond(result)178}179180async fn extract(181    state: web::Data<AppState>,182    _api_key: Authorized,183    payload: web::Json<ExtractRequest>,184) -> HttpResponse {185    let request = payload.into_inner();186    let result =187        web::block(move || crate::decisions::extract(&state, &request.text, &request)).await;188189    respond(result)190}191192fn respond<T: serde::Serialize>(193    result: Result<Result<T, String>, actix_web::error::BlockingError>,194) -> HttpResponse {195    match result {196        Ok(Ok(value)) => HttpResponse::Ok().json(value),197        Ok(Err(error)) => {198            log::warn!("request rejected: {error}");199            HttpResponse::BadRequest().json(ErrorResponse { error })200        }201        Err(error) => {202            log::error!("inference task failed: {error}");203            HttpResponse::build(StatusCode::INTERNAL_SERVER_ERROR).json(ErrorResponse {204                error: "inference failed".to_owned(),205            })206        }207    }208}209210/// Register every route, so integration tests can build the same app without a211/// socket.212///213/// `api_key` turns the `/v1` POST routes into `X-Api-Key` (or `Authorization:214/// Bearer`) authenticated endpoints; `None` leaves them open, which is how a215/// keyless local run behaves. The `/` playground carries the key itself, so it216/// stays public either way.217pub fn configure(config: &mut web::ServiceConfig, api_key: Option<&str>) {218    configure_with(config, api_key, DEFAULT_PLAYGROUND_PORT);219}220221/// The same, with the port the playground page should call itself on.222fn configure_with(config: &mut web::ServiceConfig, api_key: Option<&str>, port: u16) {223    config224        .app_data(web::Data::new(ApiKey(api_key.map(str::to_owned))))225        .app_data(web::Data::new(Playground {226            html: std::sync::Arc::new(playground::page(227                api_key.unwrap_or(""),228                &format!("http://127.0.0.1:{port}"),229            )),230        }))231        .route("/", web::get().to(playground))232        .route("/health", web::get().to(health))233        .route("/v1/classify_text", web::post().to(classify))234        .route("/v1/batch_classify_text", web::post().to(batch_classify))235        .route("/v1/extract", web::post().to(extract));236}237238/// Bind `PORT` and serve until the process is asked to stop.239///240/// # Errors241/// Returns the io error from binding or from the server loop.242pub async fn run(config: &Config, engine: crate::engine::Engine) -> std::io::Result<()> {243    let state = web::Data::new(AppState {244        engine: std::sync::Arc::new(engine),245        gate: std::sync::Mutex::new(()),246    });247    let address = format!("0.0.0.0:{}", config.port);248    log::info!(249        "serving {} (storage {})",250        config.model_label(),251        config.storage_dir.display()252    );253    log::info!(254        "playground at http://127.0.0.1:{} ({})",255        config.port,256        if config.api_key.is_some() {257            "API key required on /v1"258        } else {259            "no API_KEY set, /v1 is open"260        }261    );262263    let port = config.port;264    let api_key = config.api_key.clone();265    HttpServer::new(move || {266        App::new()267            .app_data(state.clone())268            .configure(|app| configure_with(app, api_key.as_deref(), port))269    })270    .bind(&address)?271    .run()272    .await273}274275#[cfg(test)]276mod tests {277    use std::sync::{Arc, OnceLock};278279    use actix_web::{http::StatusCode, web};280281    use super::{configure_with, constant_time_eq};282    use crate::decisions::AppState;283    use crate::engine::Engine;284285    /// The engine is only dereferenced after the JSON extractor succeeds, and286    /// every test here sends malformed JSON or a `GET`, so a state built287    /// without a checkpoint is enough — the model is never touched.288    fn state() -> web::Data<AppState> {289        web::Data::new(AppState {290            engine: engine(),291            gate: std::sync::Mutex::new(()),292        })293    }294295    /// An engine without a checkpoint, for tests that never reach inference.296    static ENGINE: OnceLock<Arc<Engine>> = OnceLock::new();297298    fn engine() -> Arc<Engine> {299        ENGINE.get_or_init(|| Arc::new(Engine::for_tests())).clone()300    }301302    /// Build the test app. `init_service` returns an unnameable service type,303    /// so the build expands inline through a macro.304    macro_rules! app {305        ($key:expr) => {{306            actix_web::test::init_service(307                actix_web::App::new()308                    .app_data(state())309                    .configure(|config| configure_with(config, $key, 8123)),310            )311            .await312        }};313    }314315    #[test]316    fn key_comparison_is_length_safe() {317        assert!(constant_time_eq("abc", "abc"));318        assert!(!constant_time_eq("abc", "abd"));319        assert!(!constant_time_eq("abc", "abcd"));320        assert!(!constant_time_eq("", "abc"));321    }322323    #[actix_web::test]324    async fn wrong_key_is_401() {325        let app = app!(Some("secret"));326        let request = actix_web::test::TestRequest::post()327            .uri("/v1/classify_text")328            .insert_header(("content-type", "application/json"))329            .insert_header(("X-Api-Key", "wrong"))330            .set_payload("not json")331            .to_request();332        let response = actix_web::test::call_service(&app, request).await;333        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);334    }335336    #[actix_web::test]337    async fn no_key_is_401_when_one_is_configured() {338        let app = app!(Some("secret"));339        let request = actix_web::test::TestRequest::post()340            .uri("/v1/classify_text")341            .insert_header(("content-type", "application/json"))342            .set_payload("not json")343            .to_request();344        let response = actix_web::test::call_service(&app, request).await;345        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);346    }347348    #[actix_web::test]349    async fn right_key_gets_past_auth() {350        let app = app!(Some("secret"));351        // Auth lets it through; the JSON extractor then answers 400.352        let request = actix_web::test::TestRequest::post()353            .uri("/v1/classify_text")354            .insert_header(("content-type", "application/json"))355            .insert_header(("X-Api-Key", "secret"))356            .set_payload("not json")357            .to_request();358        let response = actix_web::test::call_service(&app, request).await;359        assert_eq!(response.status(), StatusCode::BAD_REQUEST);360    }361362    #[actix_web::test]363    async fn v1_is_open_without_a_configured_key() {364        let app = app!(None);365        let request = actix_web::test::TestRequest::post()366            .uri("/v1/classify_text")367            .insert_header(("content-type", "application/json"))368            .set_payload("not json")369            .to_request();370        let response = actix_web::test::call_service(&app, request).await;371        assert_eq!(response.status(), StatusCode::BAD_REQUEST);372    }373374    #[actix_web::test]375    async fn playground_and_health_are_public() {376        let app = app!(Some("secret"));377        for uri in ["/", "/health"] {378            let request = actix_web::test::TestRequest::get().uri(uri).to_request();379            let response = actix_web::test::call_service(&app, request).await;380            assert!(response.status().is_success(), "{uri}");381        }382    }383384    #[actix_web::test]385    async fn playground_embeds_the_real_key_and_origin() {386        let app = app!(Some("s3cret"));387        let request = actix_web::test::TestRequest::get().uri("/").to_request();388        let response = actix_web::test::call_service(&app, request).await;389        let body = actix_web::test::read_body(response).await;390        let html = String::from_utf8(body.to_vec()).expect("utf-8");391        assert!(html.contains(r#""s3cret""#), "key missing: {html}");392        assert!(html.contains("http://127.0.0.1:8123"), "origin: {html}");393        assert!(html.contains("/v1/classify_text"), "endpoint: {html}");394    }395}