//! Descriptions of one HTTP exchange, without performing it. //! //! The crate builds an [`HttpRequest`]; the program performs it however it can (a native HTTP client, the //! browser's Fetch API, a test double) and describes what came back in an [`HttpResponse`]. The //! [`HttpExchange`] trait is the shape of that service when the crate's asynchronous helpers are used. //! //! What the program performing a request must do: //! //! * send the method, address, header fields and body exactly as given; //! * follow no redirect itself (or, if it must, check each target with //! [`Address::check_link`](crate::Address::check_link) and drop the credentials when the origin changes); //! * read [`HttpRequest::max_response_bytes`] *before* reading the body (it is the kind's limit, or the lower //! one the caller set with [`HttpRequest::with_response_limit`]), refuse at once a `Content-Length` above it, //! and stop reading as soon as the body passes it, reporting [`TransportError::BodyTooLarge`]. The crate //! refuses a longer body anyway, but only after it has been read; //! * copy into the response the header fields named in [`HttpResponse::FIELDS_READ`]. use std::fmt; use std::future::Future; use crate::address::Address; use crate::credentials::Secret; /// The most a session object may weigh, in octets. pub const SESSION_RESPONSE_LIMIT: usize = 4 * 1024 * 1024; /// The most an API response may weigh, in octets. pub const API_RESPONSE_LIMIT: usize = 32 * 1024 * 1024; /// The most a downloaded blob may weigh, in octets. pub const DOWNLOAD_RESPONSE_LIMIT: usize = 256 * 1024 * 1024; /// The most of an error response's body that is read for a problem details object, in octets. pub const PROBLEM_BODY_LIMIT: usize = 64 * 1024; /// The longest header field value the response keeps; longer ones are dropped. pub const MAX_FIELD_VALUE_LEN: usize = 8 * 1024; /// The request method. #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] pub enum Method { /// `GET` Get, /// `POST` Post, } impl Method { /// The method's name. pub fn as_str(self) -> &'static str { match self { Self::Get => "GET", Self::Post => "POST", } } } /// What a request is for; it decides the response size limit and what a successful answer must look like. #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] pub enum RequestKind { /// Fetching the session object (RFC 8620 §2). Session, /// An API request (RFC 8620 §3.1). Api, /// Downloading a blob (RFC 8620 §6.2). Download, } impl RequestKind { /// The largest response body accepted for this kind of request, in octets. pub fn max_response_bytes(self) -> usize { match self { Self::Session => SESSION_RESPONSE_LIMIT, Self::Api => API_RESPONSE_LIMIT, Self::Download => DOWNLOAD_RESPONSE_LIMIT, } } /// Whether a successful answer must be `application/json`. pub fn expects_json(self) -> bool { matches!(self, Self::Session | Self::Api) } } #[derive(Clone)] enum FieldValue { Plain(String), Secret(Secret), } impl FieldValue { fn as_str(&self) -> &str { match self { Self::Plain(text) => text, Self::Secret(secret) => secret.expose(), } } } /// A request for the program to perform. #[derive(Clone)] pub struct HttpRequest { method: Method, address: Address, fields: Vec<(&'static str, FieldValue)>, body: Vec, kind: RequestKind, max_response: usize, } impl HttpRequest { pub(crate) fn new(method: Method, address: Address, kind: RequestKind, authorization: &Secret) -> Self { let mut fields = vec![("Authorization", FieldValue::Secret(authorization.clone()))]; if kind.expects_json() { fields.push(("Accept", FieldValue::Plain("application/json".to_owned()))); } Self { method, address, fields, body: Vec::new(), kind, max_response: kind.max_response_bytes() } } /// Lowers the largest response body accepted for this request to `bytes`. A value above the kind's /// limit ([`RequestKind::max_response_bytes`]) is reduced to it: the limit can only go down. pub fn with_response_limit(mut self, bytes: usize) -> Self { self.max_response = bytes.min(self.kind.max_response_bytes()); self } pub(crate) fn with_json_body(mut self, body: Vec) -> Self { self.fields.push(("Content-Type", FieldValue::Plain("application/json".to_owned()))); self.body = body; self } /// The method. pub fn method(&self) -> Method { self.method } /// The target address. pub fn address(&self) -> &Address { &self.address } /// The full target address as text, for the request line. pub fn url(&self) -> &str { self.address.as_str() } /// The header fields to send, `Authorization` included. pub fn fields(&self) -> impl Iterator { self.fields.iter().map(|(name, value)| (*name, value.as_str())) } /// The body (empty for `GET`). pub fn body(&self) -> &[u8] { &self.body } /// What the request is for. pub fn kind(&self) -> RequestKind { self.kind } /// The most body octets to read from the response: the kind's limit, or the lower one set with /// [`HttpRequest::with_response_limit`]. The program reads it before the body, to stop early. pub fn max_response_bytes(&self) -> usize { self.max_response } } impl fmt::Debug for HttpRequest { /// Method, origin, field names (the `Authorization` value hidden) and body length: no path, no query, no /// secret, no content. fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let fields: Vec = self .fields .iter() .map(|(name, value)| match value { FieldValue::Plain(text) => format!("{name}: {text}"), FieldValue::Secret(_) => format!("{name}: "), }) .collect(); f.debug_struct("HttpRequest") .field("method", &self.method) .field("origin", &self.address.origin()) .field("kind", &self.kind) .field("fields", &fields) .field("body_len", &self.body.len()) .field("max_response_bytes", &self.max_response) .finish() } } /// What came back, as the program describes it. #[derive(Clone, Default, PartialEq, Eq)] pub struct HttpResponse { status: u16, content_type: Option, retry_after: Option, location: Option, body: Vec, } impl HttpResponse { /// The header fields the crate reads; others may be left out. pub const FIELDS_READ: [&'static str; 3] = ["Content-Type", "Retry-After", "Location"]; /// A response with a status code and a body. pub fn new(status: u16, body: Vec) -> Self { Self { status, body, ..Self::default() } } /// Adds a header field; names are matched without regard to case (RFC 9110 §5.1) and only those of /// [`HttpResponse::FIELDS_READ`] are kept. A value longer than [`MAX_FIELD_VALUE_LEN`] is dropped. /// When a field comes twice, the first value is kept. pub fn with_field(mut self, name: &str, value: &str) -> Self { self.set_field(name, value); self } /// Like [`HttpResponse::with_field`], in place. pub fn set_field(&mut self, name: &str, value: &str) { if value.len() > MAX_FIELD_VALUE_LEN { return; } let slot = if name.eq_ignore_ascii_case("content-type") { &mut self.content_type } else if name.eq_ignore_ascii_case("retry-after") { &mut self.retry_after } else if name.eq_ignore_ascii_case("location") { &mut self.location } else { return; }; if slot.is_none() { *slot = Some(value.trim_matches([' ', '\t']).to_owned()); } } /// The status code. pub fn status(&self) -> u16 { self.status } /// The `Content-Type` field value. pub fn content_type(&self) -> Option<&str> { self.content_type.as_deref() } /// The `Retry-After` field value. pub fn retry_after(&self) -> Option<&str> { self.retry_after.as_deref() } /// The `Location` field value. pub fn location(&self) -> Option<&str> { self.location.as_deref() } /// The body. pub fn body(&self) -> &[u8] { &self.body } /// The body, taken out of the response. pub fn into_body(self) -> Vec { self.body } } impl fmt::Debug for HttpResponse { /// Status, content type and body length: the body may hold someone's mail. fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let short = |value: &Option| value.as_deref().map(|text| text.chars().take(64).collect::()); f.debug_struct("HttpResponse") .field("status", &self.status) .field("content_type", &short(&self.content_type)) .field("retry_after", &short(&self.retry_after)) .field("has_location", &self.location.is_some()) .field("body_len", &self.body.len()) .finish() } } /// Why the program could not complete an exchange; no free text, so nothing private can travel in it. #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] #[non_exhaustive] pub enum TransportError { /// The server is overloaded at the connection level (connections refused under load, an HTTP/2 /// `REFUSED_STREAM`, a `GOAWAY` before the request was processed, …). Classified as busy. Overloaded, /// No answer in the time the program allows. TimedOut, /// The host could not be reached (name resolution, connection). Unreachable, /// TLS failed, a certificate among the causes. Tls, /// The body was longer than [`HttpRequest::max_response_bytes`]. BodyTooLarge, /// The server redirected and the program, as asked, did not follow. RedirectRefused, /// The exchange was cancelled. Aborted, /// Anything else. Other, } impl fmt::Display for TransportError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str(match self { Self::Overloaded => "the server turned the connection away because it is overloaded; try again in a little while", Self::TimedOut => "the server did not answer in time; check the network connection and try again", Self::Unreachable => "the server could not be reached; check its address and the network connection", Self::Tls => "no secure connection could be set up, for example because the server's certificate is invalid", Self::BodyTooLarge => "the answer passed the size limit set for this request and was not read further", Self::RedirectRefused => "the server redirected the request elsewhere and the redirect was not followed", Self::Aborted => "the request was cancelled before it completed", Self::Other => "the connection failed in a way the transport did not classify", }) } } impl std::error::Error for TransportError {} /// Performs one HTTP exchange for the crate's asynchronous helpers. /// /// Before reading the response body, read [`HttpRequest::max_response_bytes`] and stop as soon as the body /// would pass it, returning [`TransportError::BodyTooLarge`] (see the module documentation). /// /// The returned future need not be `Send`, so that a browser transport can implement it; the crate's own /// futures are `Send` whenever the program's are. pub trait HttpExchange { /// Sends `request` and describes the response. fn exchange(&self, request: &HttpRequest) -> impl Future>; } #[cfg(test)] mod tests;