docs: add doc-comments to client::response

This commit is contained in:
DarkCat09 2024-08-08 16:24:01 +04:00
parent de4903f1e6
commit 37196caf75
Signed by: DarkCat09
GPG key ID: 0A26CD5B3345D6E3

View file

@ -1,3 +1,5 @@
//! Client-side response structure
use crate::{status::Status, LibError, ReplyType}; use crate::{status::Status, LibError, ReplyType};
use bytes::Bytes; use bytes::Bytes;
@ -5,6 +7,8 @@ use tokio::io::AsyncReadExt;
type BodyStream = tokio::io::BufReader<tokio_rustls::client::TlsStream<tokio::net::TcpStream>>; type BodyStream = tokio::io::BufReader<tokio_rustls::client::TlsStream<tokio::net::TcpStream>>;
/// Client-side response structure wrapping a [`Status`],
/// a metadata string and a TLS stream
#[derive(Debug)] #[derive(Debug)]
pub struct Response { pub struct Response {
status: Status, status: Status,
@ -21,11 +25,25 @@ impl Response {
} }
} }
/// Check if status code is 2x (success).
#[inline] #[inline]
pub fn is_ok(&self) -> bool { pub fn is_ok(&self) -> bool {
self.status.reply_type() == ReplyType::Success self.status.reply_type() == ReplyType::Success
} }
/// Return `Ok(self)` if status code is 2x, otherwise `Err(self)`.
///
/// # Examples
/// ```
/// match client.request("gemini://dc09.ru").await?.ensure_ok() {
/// Ok(resp) => {
/// println!("{}", resp.text().await?);
/// }
/// Err(resp) => {
/// println!("{}", resp.message());
/// }
/// }
/// ```
pub fn ensure_ok(self) -> Result<Self, Self> { pub fn ensure_ok(self) -> Result<Self, Self> {
if self.status.reply_type() == ReplyType::Success { if self.status.reply_type() == ReplyType::Success {
Ok(self) Ok(self)
@ -34,28 +52,49 @@ impl Response {
} }
} }
/// Get the response status code as [`Status`].
pub fn status(&self) -> Status { pub fn status(&self) -> Status {
self.status self.status
} }
/// Get the response metadata -- the text after a status code + space.
/// - In 1x responses (input), it contains an input prompt message.
/// - In 2x responses (success), it contains a MIME type of the body.
/// - In 3x responses (redirect), it contains a URL.
/// - In 4x, 5x (fail), 6x (auth), it contains an error message.
pub fn message(&self) -> &str { pub fn message(&self) -> &str {
&self.message &self.message
} }
/// Get the response body MIME type by parsing the metadata field.
/// If you call this method on a non-2x response, you'll get a parse error.
/// It's strongly recommended to check the status code first
/// (most handy is [`Response::is_ok()`]).
pub fn mime(&self) -> Result<mime::Mime, LibError> { pub fn mime(&self) -> Result<mime::Mime, LibError> {
self.message.parse().map_err(LibError::InvalidMime) self.message.parse().map_err(LibError::InvalidMime)
} }
/// Borrow the wrapped TLS stream as `&mut`.
///
/// # Reminder
/// You can read data from one stream only once,
/// so calling `.bytes()` after `.stream().read_to_end(…)`
/// (or `.bytes()` twice, or `.text()` after `.bytes()` and vice versa)
/// on the same response will result in empty output.
pub fn stream(&mut self) -> &mut BodyStream { pub fn stream(&mut self) -> &mut BodyStream {
&mut self.stream &mut self.stream
} }
/// Read the whole response body and return as [`Bytes`].
/// See also [the note](#reminder) to `stream()`.
pub async fn bytes(&mut self) -> Result<Bytes, LibError> { pub async fn bytes(&mut self) -> Result<Bytes, LibError> {
let mut buf = Vec::new(); let mut buf = Vec::new();
self.stream.read_to_end(&mut buf).await?; self.stream.read_to_end(&mut buf).await?;
Ok(Bytes::from(buf)) Ok(Bytes::from(buf))
} }
/// Read the whole response body as a UTF-8 [`String`].
/// See also [the note](#reminder) to `stream()`.
pub async fn text(&mut self) -> Result<String, LibError> { pub async fn text(&mut self) -> Result<String, LibError> {
let mut buf = String::new(); let mut buf = String::new();
self.stream.read_to_string(&mut buf).await?; self.stream.read_to_string(&mut buf).await?;