//! The HTTP transport seam: every outgoing request the API clients make goes //! through [`HttpTransport`], so unit tests can swap in //! [`crate::testing::FakeTransport`] and run with the network unplugged. [`ReqwestTransport`] is the real implementation, exercised only //! by the live integration suite (`crates/core/tests/live_api.rs`). use std::path::PathBuf; use std::time::Duration; use async_trait::async_trait; use serde::de::DeserializeOwned; use thiserror::Error; /// HTTP method a [`HttpRequest`] is sent with. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Method { Get, Post, Delete, } /// One field of a `multipart/form-data` body. #[derive(Debug, Clone, PartialEq)] pub enum Part { Text { name: String, value: String, }, /// Streamed from disk by [`ReqwestTransport`]; never read fully into /// memory (recordings can be tens of megabytes). File { name: String, file_name: String, path: PathBuf, mime: String, }, } /// Body of a [`HttpRequest`]. #[derive(Debug, Clone, PartialEq)] pub enum HttpBody { Empty, Json(serde_json::Value), Multipart(Vec), } /// A request to send through a [`HttpTransport`]. #[derive(Debug, Clone, PartialEq)] pub struct HttpRequest { pub method: Method, pub url: String, pub headers: Vec<(String, String)>, pub body: HttpBody, /// `false` returns a redirect (3xx) as the response instead of /// following it. pub follow_redirects: bool, } impl HttpRequest { /// The value of the first header matching `name`, case-insensitively. pub fn header(&self, name: &str) -> Option<&str> { self.headers .iter() .find(|(k, _)| k.eq_ignore_ascii_case(name)) .map(|(_, v)| v.as_str()) } } /// A response as returned by a [`HttpTransport`]. Non-2xx statuses are not an /// error at this layer: callers inspect `status` themselves. #[derive(Debug, Clone, PartialEq)] pub struct HttpResponse { pub status: u16, pub body: Vec, } impl HttpResponse { /// Decodes the body as JSON. pub fn json(&self) -> Result { serde_json::from_slice(&self.body) } } /// Transport-level failure: a request that could not be sent or whose /// response could not be read at all. A non-2xx status is *not* one of /// these; it comes back as an ordinary [`HttpResponse`]. #[derive(Debug, Error)] pub enum TransportError { #[error("E/A-Fehler: {0}")] Io(String), #[error("Netzwerkfehler: {0}")] Network(String), #[error("Zeitüberschreitung")] Timeout, } /// Seam between the API clients and the network. Implemented by /// [`ReqwestTransport`] for real traffic and by /// [`crate::testing::FakeTransport`] for unit tests. #[async_trait] pub trait HttpTransport: Send + Sync { async fn send(&self, req: HttpRequest) -> Result; } /// Live `HttpTransport` backed by `reqwest` (rustls). Shares its /// `reqwest::Client`s (connection pooling) with a 10 minute request timeout /// and a 30 second connect timeout, matching the DeepScript client's /// worst-case wait. reqwest sets the redirect policy per client, so there /// is one that follows redirects and one that does not. pub struct ReqwestTransport { client: reqwest::Client, no_redirect_client: reqwest::Client, } impl ReqwestTransport { pub fn new() -> Self { let build = |redirects| { reqwest::Client::builder() .timeout(Duration::from_secs(10 * 60)) .connect_timeout(Duration::from_secs(30)) .redirect(redirects) .build() .expect("failed to build reqwest client") }; ReqwestTransport { client: build(reqwest::redirect::Policy::default()), no_redirect_client: build(reqwest::redirect::Policy::none()), } } } impl Default for ReqwestTransport { fn default() -> Self { Self::new() } } #[async_trait] impl HttpTransport for ReqwestTransport { async fn send(&self, req: HttpRequest) -> Result { let client = if req.follow_redirects { &self.client } else { &self.no_redirect_client }; let mut builder = match req.method { Method::Get => client.get(&req.url), Method::Post => client.post(&req.url), Method::Delete => client.delete(&req.url), }; for (name, value) in &req.headers { builder = builder.header(name, value); } builder = match &req.body { HttpBody::Empty => builder, HttpBody::Json(value) => builder.json(value), HttpBody::Multipart(parts) => { let form = build_multipart(parts).await?; builder.multipart(form) } }; let response = builder.send().await.map_err(map_reqwest_error)?; let status = response.status().as_u16(); let body = response.bytes().await.map_err(map_reqwest_error)?.to_vec(); Ok(HttpResponse { status, body }) } } /// Builds a `reqwest` multipart form, streaming any [`Part::File`] from disk /// rather than reading it into memory. async fn build_multipart(parts: &[Part]) -> Result { let mut form = reqwest::multipart::Form::new(); for part in parts { form = match part { Part::Text { name, value } => form.text(name.clone(), value.clone()), Part::File { name, file_name, path, mime, } => { let file = tokio::fs::File::open(path) .await .map_err(|e| TransportError::Io(format!("{}: {e}", path.display())))?; let len = file.metadata().await.ok().map(|m| m.len()); let body = reqwest::Body::from(file); let mut field = match len { Some(len) => reqwest::multipart::Part::stream_with_length(body, len), None => reqwest::multipart::Part::stream(body), }; field = field.file_name(file_name.clone()); field = field .mime_str(mime) .map_err(|e| TransportError::Io(format!("ungültiger MIME-Typ {mime}: {e}")))?; form.part(name.clone(), field) } }; } Ok(form) } fn map_reqwest_error(e: reqwest::Error) -> TransportError { if e.is_timeout() { TransportError::Timeout } else { TransportError::Network(e.to_string()) } } #[cfg(test)] mod tests { use super::*; use crate::testing::FakeTransport; fn get(url: &str) -> HttpRequest { HttpRequest { method: Method::Get, url: url.to_string(), headers: vec![], body: HttpBody::Empty, follow_redirects: true, } } #[tokio::test] async fn fake_transport_returns_scripted_responses_in_order() { let transport = FakeTransport::new(); transport.expect(Method::Get, "https://api.example.com/a", 200, "first"); transport.expect(Method::Post, "https://api.example.com/b?x=1", 201, "second"); let first = transport .send(get("https://api.example.com/a")) .await .unwrap(); assert_eq!(first.status, 200); assert_eq!(first.body, b"first"); let second = transport .send(HttpRequest { method: Method::Post, url: "https://api.example.com/b?x=1".to_string(), headers: vec![("x-test".to_string(), "1".to_string())], body: HttpBody::Empty, follow_redirects: true, }) .await .unwrap(); assert_eq!(second.status, 201); assert_eq!(second.body, b"second"); let requests = transport.requests(); assert_eq!(requests.len(), 2); assert_eq!(requests[0].url, "https://api.example.com/a"); assert_eq!(requests[1].url, "https://api.example.com/b?x=1"); assert_eq!(requests[1].header("x-test"), Some("1")); transport.assert_done(); } #[tokio::test] #[should_panic(expected = "FakeTransport")] async fn fake_transport_panics_on_unexpected_url() { let transport = FakeTransport::new(); transport.expect(Method::Get, "https://api.example.com/a", 200, "body"); let _ = transport.send(get("https://api.example.com/wrong")).await; } #[test] #[should_panic(expected = "FakeTransport")] fn fake_transport_assert_done_detects_missing_calls() { let transport = FakeTransport::new(); transport.expect(Method::Get, "https://api.example.com/a", 200, "body"); transport.assert_done(); } #[test] fn http_request_header_lookup_is_case_insensitive() { let req = HttpRequest { method: Method::Get, url: "https://api.example.com".to_string(), headers: vec![("Authorization".to_string(), "Bearer xyz".to_string())], body: HttpBody::Empty, follow_redirects: true, }; assert_eq!(req.header("authorization"), Some("Bearer xyz")); assert_eq!(req.header("missing"), None); } #[test] fn http_response_json_decodes_body() { let resp = HttpResponse { status: 200, body: br#"{"ok":true}"#.to_vec(), }; let value: serde_json::Value = resp.json().unwrap(); assert_eq!(value["ok"], serde_json::json!(true)); } }