//! Host-owned HTTP engine over the `smith::http` vocabulary (`SMH-SPEC-SPEC0001`, `SMH-SPEC-PLUG0001`). //! //! One executor serves provider traffic today and plugin net-scope //! effects later; every call is bounded, cancellable, and recordable. use serde_json::Value; use smith::error::{ProviderFault, Result, SmithError}; use smith::http::{ HttpBodyEnd, HttpBodyItem, HttpChunk, HttpExchange, HttpExecutor, HttpExecutorRef, HttpHead, HttpResponse, }; use smith::tool::CancelHandle; use std::io::Read; use std::sync::Arc; use std::sync::mpsc; use std::time::{Duration, Instant}; use ureq::unversioned::resolver::DefaultResolver; use ureq::unversioned::transport::{ Buffers, ConnectionDetails, Connector, DefaultConnector, NextTimeout, Transport, }; const LIFECYCLE_RESPONSE_HEADER_BYTES_MAX: usize = 4096; const CREDENTIAL_RESPONSE_BYTES_MAX: u64 = 128 * 1024; const CREDENTIAL_CANCEL_CHECK: Duration = Duration::from_millis(50); /// Credential effect outcome, independent of transport diagnostic strings. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum CredentialFault { Cancelled, Deadline, Network, ExchangeUncertain, Rejected, InvalidGrant, } /// Bounded, no-redirect client for host-owned credential mechanisms. pub(crate) struct CredentialHttp; impl CredentialHttp { fn agent(cancel: &CancelHandle, timeout: Duration) -> ureq::Agent { let config = ureq::Agent::config_builder() .max_redirects(0) .proxy(None) .http_status_as_error(false) .timeout_global(Some(timeout)) .timeout_connect(Some(timeout)) .timeout_recv_response(Some(timeout)) .build(); ureq::Agent::with_parts( config, DefaultConnector::default().chain(CancelTransport { cancel: cancel.clone(), }), DefaultResolver::default(), ) } pub(crate) fn get( url: &str, deadline: Instant, cancel: &CancelHandle, ) -> std::result::Result { let timeout = credential_timeout(deadline, cancel)?; let response = Self::agent(cancel, timeout) .get(url) .call() .map_err(|_| credential_error(cancel))?; Self::response(response, cancel) } pub(crate) fn post( url: &str, body: &str, deadline: Instant, cancel: &CancelHandle, ) -> std::result::Result { Self::post_body( url, body, "application/x-www-form-urlencoded", deadline, cancel, ) } pub(crate) fn post_json( url: &str, body: &Value, deadline: Instant, cancel: &CancelHandle, ) -> std::result::Result { let body = serde_json::to_string(body).map_err(|_| CredentialFault::Rejected)?; Self::post_body(url, &body, "application/json", deadline, cancel) } fn post_body( url: &str, body: &str, content_type: &str, deadline: Instant, cancel: &CancelHandle, ) -> std::result::Result { let timeout = credential_timeout(deadline, cancel)?; let request = Self::agent(cancel, timeout) .post(url) .header("content-type", content_type); let response = if content_type == "application/json" { request.header("accept", "application/json").send(body) } else { request.send(body) } .map_err(|_| CredentialFault::ExchangeUncertain)?; Self::response(response, cancel).map_err(|fault| match fault { CredentialFault::Rejected | CredentialFault::InvalidGrant => fault, _ => CredentialFault::ExchangeUncertain, }) } pub(crate) fn control( url: &str, body: Option<&Value>, access: &str, deadline: Instant, cancel: &CancelHandle, ) -> std::result::Result { let timeout = credential_timeout(deadline, cancel)?; let agent = Self::agent(cancel, timeout); let authorization = format!("Bearer {access}"); let response = match body { Some(body) => { let body = serde_json::to_string(body).map_err(|_| CredentialFault::Rejected)?; agent .post(url) .header("authorization", &authorization) .header("content-type", "application/json") .header("accept", "application/json") .send(&body) .map_err(|_| CredentialFault::ExchangeUncertain)? } None => agent .get(url) .header("authorization", &authorization) .header("accept", "application/json") .call() .map_err(|_| credential_error(cancel))?, }; Self::response(response, cancel) } pub(crate) fn revoke( url: &str, body: &str, deadline: Instant, cancel: &CancelHandle, ) -> std::result::Result<(), CredentialFault> { let timeout = credential_timeout(deadline, cancel)?; let response = Self::agent(cancel, timeout) .post(url) .header("content-type", "application/x-www-form-urlencoded") .send(body) .map_err(|_| CredentialFault::ExchangeUncertain)?; if response.status().as_u16() == 200 { Ok(()) } else { Err(CredentialFault::Rejected) } } fn response( response: ureq::http::Response, cancel: &CancelHandle, ) -> std::result::Result { let status = response.status().as_u16(); let mut bytes = Vec::new(); if cancel.is_cancelled() { return Err(CredentialFault::Cancelled); } #[expect( clippy::disallowed_methods, reason = "Take caps credential response bytes before reporting overflow" )] response .into_body() .into_reader() .take(CREDENTIAL_RESPONSE_BYTES_MAX + 1) .read_to_end(&mut bytes) .map_err(|_| credential_error(cancel))?; if bytes.len() as u64 > CREDENTIAL_RESPONSE_BYTES_MAX { return Err(CredentialFault::Network); } let value: Value = serde_json::from_slice(&bytes).map_err(|_| CredentialFault::Network)?; if status != 200 { return Err( if status == 400 && value["error"].as_str() == Some("invalid_grant") { CredentialFault::InvalidGrant } else { CredentialFault::Rejected }, ); } Ok(value) } } fn credential_timeout( deadline: Instant, cancel: &CancelHandle, ) -> std::result::Result { if cancel.is_cancelled() { return Err(CredentialFault::Cancelled); } let remaining = deadline.saturating_duration_since(Instant::now()); if remaining.is_zero() { return Err(CredentialFault::Deadline); } Ok(remaining.min(Duration::from_secs(15))) } fn credential_error(cancel: &CancelHandle) -> CredentialFault { if cancel.is_cancelled() { CredentialFault::Cancelled } else { CredentialFault::Network } } /// Adds cancellation checks to every credential transport wait. #[derive(Debug)] struct CancelTransport { cancel: CancelHandle, } impl Connector> for CancelTransport { type Out = CancelledTransport; fn connect( &self, _details: &ConnectionDetails, chained: Option>, ) -> std::result::Result, ureq::Error> { if self.cancel.is_cancelled() { return Err(std::io::Error::new( std::io::ErrorKind::Interrupted, "OAuth login cancelled", ) .into()); } Ok(chained.map(|inner| CancelledTransport { inner, cancel: self.cancel.clone(), })) } } #[derive(Debug)] struct CancelledTransport { inner: Box, cancel: CancelHandle, } impl CancelledTransport { fn check(&self, timeout: &NextTimeout) -> std::result::Result { if self.cancel.is_cancelled() { return Err(std::io::Error::new( std::io::ErrorKind::Interrupted, "OAuth login cancelled", ) .into()); } Ok(NextTimeout { after: timeout.after.min(CREDENTIAL_CANCEL_CHECK.into()), reason: timeout.reason, }) } } impl Transport for CancelledTransport { fn buffers(&mut self) -> &mut dyn Buffers { self.inner.buffers() } fn transmit_output( &mut self, amount: usize, timeout: NextTimeout, ) -> std::result::Result<(), ureq::Error> { self.inner.transmit_output(amount, self.check(&timeout)?) } fn await_input(&mut self, timeout: NextTimeout) -> std::result::Result { use ureq::unversioned::transport::time::Duration as TransportDuration; let budget = match timeout.after { TransportDuration::Exact(duration) => duration, TransportDuration::NotHappening => Duration::from_secs(15), }; let deadline = Instant::now() + budget; loop { let remaining = deadline.saturating_duration_since(Instant::now()); if remaining.is_zero() { return Err(ureq::Error::Timeout(timeout.reason)); } let slice = self.check(&NextTimeout { after: remaining.into(), reason: timeout.reason, })?; match self.inner.await_input(slice) { Err(ureq::Error::Timeout(_)) => {} Err(ureq::Error::Io(error)) if matches!( error.kind(), std::io::ErrorKind::TimedOut | std::io::ErrorKind::WouldBlock ) => {} result => return result, } } } fn is_open(&mut self) -> bool { self.inner.is_open() } fn is_tls(&self) -> bool { self.inner.is_tls() } } /// Largest accepted response body, in bytes. pub const BODY_BYTES_MAX: u64 = 64 * 1024 * 1024; /// Largest accepted single request body, in bytes. pub const REQUEST_BYTES_MAX: usize = 16 * 1024 * 1024; /// Timeout for the response head. pub const HEAD_TIMEOUT: Duration = Duration::from_secs(120); /// Deadline for one chunk gap. pub const CHUNK_TIMEOUT: Duration = Duration::from_secs(300); /// The HTTP engine: `ureq`, blocking, pure Rust, no async runtime /// (`SMH-SPEC-SPEC0001`, network transport). #[derive(Clone)] pub struct UreqHttpExecutor { agent: ureq::Agent, body_bytes_max: u64, } impl UreqHttpExecutor { /// A default executor with [`HEAD_TIMEOUT`] and [`CHUNK_TIMEOUT`]. #[must_use] pub fn new() -> Self { Self::with_timeouts(HEAD_TIMEOUT, CHUNK_TIMEOUT) } /// An executor bounding the connect and the response head wait each by /// `head`, and every single socket wait by `gap`. #[must_use] pub fn with_timeouts(head: Duration, gap: Duration) -> Self { let config = ureq::Agent::config_builder() .http_status_as_error(false) .timeout_connect(Some(head)) .timeout_recv_response(Some(head)) .build(); Self::from_config(config, gap) } /// Inline lifecycle transport: no redirects/proxies, absolute request deadline, /// bounded response headers/body and cancellable blocking socket waits. pub(crate) fn lifecycle(timeout: Duration, cancel: &CancelHandle, body_bytes_max: u64) -> Self { let config = ureq::Agent::config_builder() .max_redirects(0) .proxy(None) .http_status_as_error(false) .max_response_header_size(LIFECYCLE_RESPONSE_HEADER_BYTES_MAX) .timeout_global(Some(timeout)) .timeout_connect(Some(timeout)) .timeout_recv_response(Some(timeout)) .build(); let connector = DefaultConnector::default().chain(CancelTransport { cancel: cancel.clone(), }); Self { agent: ureq::Agent::with_parts(config, connector, DefaultResolver::default()), body_bytes_max, } } fn from_config(config: ureq::config::Config, gap: Duration) -> Self { let connector = DefaultConnector::default().chain(GapTimeout(gap)); Self { agent: ureq::Agent::with_parts(config, connector, DefaultResolver::default()), body_bytes_max: BODY_BYTES_MAX, } } } impl Default for UreqHttpExecutor { fn default() -> Self { Self::new() } } impl HttpExecutor for UreqHttpExecutor { fn execute(&self, exchange: HttpExchange, cancel: CancelHandle) -> Result { admit(&exchange, &cancel)?; let response = match exchange.method { smith::http::HttpMethod::Get => { let mut prepared = self.agent.get(&exchange.url); for header in &exchange.headers { prepared = prepared.header(&header.name, &header.value); } prepared .call() .map_err(|error| transient(error.to_string()))? } smith::http::HttpMethod::Post => { let mut prepared = self.agent.post(&exchange.url); for header in &exchange.headers { prepared = prepared.header(&header.name, &header.value); } prepared .send(&exchange.body[..]) .map_err(|error| transient(error.to_string()))? } }; let head = HttpHead { status: response.status().as_u16(), }; Ok(stream_body_bounded( head, response.into_body().into_reader(), cancel, self.body_bytes_max, )) } } /// Connector stage capping every socket wait at a gap duration, so a /// stalled body fails per gap instead of per whole-body budget. #[derive(Debug)] struct GapTimeout(Duration); impl Connector> for GapTimeout { type Out = GapTransport; fn connect( &self, _details: &ConnectionDetails, chained: Option>, ) -> std::result::Result, ureq::Error> { Ok(chained.map(|inner| GapTransport { inner, gap: self.0 })) } } #[derive(Debug)] struct GapTransport { inner: Box, gap: Duration, } impl GapTransport { fn cap(&self, timeout: &NextTimeout) -> NextTimeout { NextTimeout { after: timeout.after.min(self.gap.into()), reason: timeout.reason, } } } impl Transport for GapTransport { fn buffers(&mut self) -> &mut dyn Buffers { self.inner.buffers() } fn transmit_output( &mut self, amount: usize, timeout: NextTimeout, ) -> std::result::Result<(), ureq::Error> { let timeout = self.cap(&timeout); self.inner.transmit_output(amount, timeout) } fn await_input(&mut self, timeout: NextTimeout) -> std::result::Result { let timeout = self.cap(&timeout); self.inner.await_input(timeout) } fn is_open(&mut self) -> bool { self.inner.is_open() } fn is_tls(&self) -> bool { self.inner.is_tls() } } /// Subscription traffic never follows redirects or inherits proxy authority from the environment. pub(crate) fn subscription_executor() -> HttpExecutorRef { let config = ureq::Agent::config_builder() .max_redirects(0) .proxy(None) .http_status_as_error(false) .timeout_connect(Some(HEAD_TIMEOUT)) .timeout_recv_response(Some(HEAD_TIMEOUT)) .build(); Arc::new(UreqHttpExecutor::from_config(config, CHUNK_TIMEOUT)) } /// The shared default executor. #[must_use] pub fn default_executor() -> HttpExecutorRef { Arc::new(UreqHttpExecutor::new()) } fn admit(exchange: &HttpExchange, cancel: &CancelHandle) -> Result<()> { if exchange.body.len() > REQUEST_BYTES_MAX { return Err(transient( "http effect: request body exceeds the size bound".to_string(), )); } if cancel.is_cancelled() { return Err(SmithError::Cancelled); } Ok(()) } /// Body chunks in flight before the reader thread blocks on the consumer. const BODY_CHANNEL_CHUNKS: usize = 16; /// Pump `body` into ordered items on a reader thread. /// /// The body ends with [`HttpBodyEnd::Complete`] at end of body, /// [`HttpBodyEnd::Failed`] on a read error or gap timeout, /// [`HttpBodyEnd::Truncated`] past [`MAX_BODY_BYTES`], or /// [`HttpBodyEnd::Cancelled`] once `cancel` fires; no chunk read after /// cancellation is delivered. fn stream_body_bounded( head: HttpHead, mut body: impl Read + Send + 'static, cancel: CancelHandle, body_bytes_max: u64, ) -> HttpResponse { let (sender, receiver) = mpsc::sync_channel(BODY_CHANNEL_CHUNKS); let allocation = smith_alloc::AllocationGroup::current(); std::thread::spawn(move || { let _allocation = allocation.as_ref().map(smith_alloc::AllocationGroup::enter); let mut buffer = [0u8; 16 * 1024]; let mut total: u64 = 0; let end = loop { let read = match body.read(&mut buffer) { Ok(0) => break HttpBodyEnd::Complete, Err(error) => { break HttpBodyEnd::Failed { message: error.to_string(), }; } Ok(read) => read, }; if cancel.is_cancelled() { break HttpBodyEnd::Cancelled; } total = total.saturating_add(u64::try_from(read).unwrap_or(u64::MAX)); if total > body_bytes_max { break HttpBodyEnd::Truncated { limit: body_bytes_max, }; } let chunk = HttpChunk { bytes: buffer[..read].to_vec(), }; if sender.send(HttpBodyItem::Chunk(chunk)).is_err() { return; } }; // The receiver may abandon the body before its terminal item arrives. let _send_result: std::result::Result<(), std::sync::mpsc::SendError> = sender.send(HttpBodyItem::End(end)); }); HttpResponse { head, body: receiver, } } const fn transient(message: String) -> SmithError { SmithError::Provider { fault: ProviderFault::Transient { message }, } } #[cfg(test)] mod credential_tests { use super::*; use std::io::{Read, Write}; use std::net::TcpListener; fn cancelled_request(method: &str, response_head: &[u8]) { let listener = TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, 0)).unwrap(); let address = listener.local_addr().unwrap(); let response_head = response_head.to_vec(); let (accepted, accepted_wait) = std::sync::mpsc::sync_channel(1); let (release, released) = std::sync::mpsc::sync_channel(1); let server = std::thread::spawn(move || { let (mut stream, _) = listener.accept().unwrap(); let mut request = [0u8; 1024]; assert!(stream.read(&mut request).unwrap() > 0); if !response_head.is_empty() { stream.write_all(&response_head).unwrap(); } accepted.send(()).unwrap(); released.recv().unwrap(); }); let cancel = CancelHandle::new(); let canceller = cancel.clone(); let cancellation = std::thread::spawn(move || { accepted_wait.recv().unwrap(); canceller.cancel(); }); let deadline = Instant::now() + Duration::from_secs(15); let start = Instant::now(); let result = if method == "GET" { CredentialHttp::get(&format!("http://{address}/credential"), deadline, &cancel) } else { CredentialHttp::post( &format!("http://{address}/credential"), "code=fixture", deadline, &cancel, ) }; release.send(()).unwrap(); cancellation.join().unwrap(); server.join().unwrap(); assert_eq!( result.unwrap_err(), if method == "POST" { CredentialFault::ExchangeUncertain } else { CredentialFault::Cancelled } ); assert!( start.elapsed() < Duration::from_secs(1), "cancellation must not wait for credential transport timeout" ); } #[derive(Debug)] struct OneCheckInterval { buffers: ureq::unversioned::transport::LazyBuffers, cancel: Option, timed_out: bool, } impl Transport for OneCheckInterval { fn buffers(&mut self) -> &mut dyn Buffers { &mut self.buffers } fn transmit_output( &mut self, _: usize, _: NextTimeout, ) -> std::result::Result<(), ureq::Error> { Ok(()) } fn await_input(&mut self, _: NextTimeout) -> std::result::Result { if self.timed_out { Ok(true) } else { self.timed_out = true; if let Some(cancel) = self.cancel.take() { cancel.cancel(); } Err(std::io::Error::new( std::io::ErrorKind::TimedOut, "fixture cancellation-check interval", ) .into()) } } fn is_open(&mut self) -> bool { true } fn is_tls(&self) -> bool { false } } #[test] fn subscription_transport_does_not_follow_redirects_into_private_backend_paths() { let listener = TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, 0)).unwrap(); let address = listener.local_addr().unwrap(); let (finished, completion) = std::sync::mpsc::sync_channel(1); let server = std::thread::spawn(move || { let (mut stream, _) = listener.accept().unwrap(); stream .set_read_timeout(Some(Duration::from_secs(3))) .unwrap(); stream .set_write_timeout(Some(Duration::from_secs(3))) .unwrap(); let mut request = [0; 2048]; assert!(stream.read(&mut request).unwrap() > 0); stream.write_all(b"HTTP/1.1 302 Found\r\nLocation: /backend-api/private\r\nContent-Length: 0\r\nConnection: close\r\n\r\n").unwrap(); drop(stream); let (mut stream, _) = listener.accept().unwrap(); stream .set_read_timeout(Some(Duration::from_secs(3))) .unwrap(); stream .set_write_timeout(Some(Duration::from_secs(3))) .unwrap(); let bytes = stream.read(&mut request).unwrap(); let redirected = request[..bytes].starts_with(b"GET "); if redirected { stream .write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\nConnection: close\r\n\r\n") .unwrap(); } finished.send(redirected).unwrap(); }); let response = subscription_executor() .execute( HttpExchange { method: smith::http::HttpMethod::Get, url: format!("http://{address}/v1/models"), headers: Vec::new(), body: Vec::new(), }, CancelHandle::new(), ) .unwrap(); if response.head.status == 302 { let mut wake = std::net::TcpStream::connect_timeout(&address, Duration::from_secs(3)).unwrap(); wake.write_all(b"stop").unwrap(); } let redirected = completion.recv_timeout(Duration::from_secs(3)).unwrap(); server.join().unwrap(); assert_eq!( response.head.status, 302, "subscription endpoints must not redirect to another path" ); assert!(!redirected); } #[test] fn cancellation_check_interval_is_not_the_credential_request_deadline() { let mut transport = CancelledTransport { inner: Box::new(OneCheckInterval { buffers: ureq::unversioned::transport::LazyBuffers::new(1024, 1024), cancel: None, timed_out: false, }), cancel: CancelHandle::new(), }; assert!( transport .await_input(NextTimeout { after: Duration::from_secs(1).into(), reason: ureq::Timeout::Global }) .unwrap() ); } #[test] fn cancelling_during_discovery_wait_terminates_request() { cancelled_request("GET", b""); } #[test] fn cancelling_during_token_exchange_wait_marks_exchange_uncertain() { cancelled_request("POST", b""); } #[test] fn cancelling_during_jwks_body_read_terminates_request() { let cancel = CancelHandle::new(); let mut transport = CancelledTransport { inner: Box::new(OneCheckInterval { buffers: ureq::unversioned::transport::LazyBuffers::new(1024, 1024), cancel: Some(cancel.clone()), timed_out: false, }), cancel, }; let error = transport .await_input(NextTimeout { after: Duration::from_secs(1).into(), reason: ureq::Timeout::Global, }) .unwrap_err(); assert!( matches!(error, ureq::Error::Io(error) if error.kind() == std::io::ErrorKind::Interrupted) ); } } #[cfg(test)] mod lifecycle_tests { //! SMH-SPEC-PLUG0001: blocking imports honor boundary deadlines and root cancellation. use super::*; use std::{io::Write, net::TcpListener}; #[test] fn stalled_lifecycle_headers_and_body_interrupt_without_server_cooperation() { for headers in [false, true] { for cancelled in [false, true] { let listener = TcpListener::bind("127.0.0.1:0").unwrap(); let address = listener.local_addr().unwrap(); let (accepted, ready) = mpsc::sync_channel(1); let (release, released) = mpsc::sync_channel(1); let server = std::thread::spawn(move || { let (mut stream, _) = listener.accept().unwrap(); stream .set_read_timeout(Some(Duration::from_secs(3))) .unwrap(); let mut bytes = [0; 4096]; assert!(stream.read(&mut bytes).unwrap() > 0); if headers { stream.write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 1\r\nConnection: close\r\n\r\n").unwrap(); } accepted.send(()).unwrap(); released.recv_timeout(Duration::from_secs(5)).unwrap(); }); let cancel = CancelHandle::new(); let handle = cancel.clone(); let (finished, done) = mpsc::sync_channel(1); let client = std::thread::spawn(move || { let timeout = if cancelled { Duration::from_secs(5) } else { Duration::from_millis(200) }; let executor = UreqHttpExecutor::lifecycle(timeout, &handle, 256); let response = executor.execute( HttpExchange { method: smith::http::HttpMethod::Post, url: format!("http://{address}"), headers: vec![], body: vec![], }, handle, ); let interrupted = match response { Err(_) => true, Ok(response) => response.body.into_iter().any(|item| { matches!( item, HttpBodyItem::End( HttpBodyEnd::Cancelled | HttpBodyEnd::Failed { .. } ) ) }), }; finished.send(interrupted).unwrap(); }); ready.recv_timeout(Duration::from_secs(3)).unwrap(); if cancelled { cancel.cancel(); } let interrupted = done.recv_timeout(Duration::from_secs(2)); release.send(()).unwrap(); server.join().unwrap(); client.join().unwrap(); assert!(interrupted.expect("HTTP must interrupt before server release")); } } } }