docs: add doc-comments to client::response
This commit is contained in:
parent
de4903f1e6
commit
37196caf75
1 changed files with 39 additions and 0 deletions
|
@ -1,3 +1,5 @@
|
|||
//! Client-side response structure
|
||||
|
||||
use crate::{status::Status, LibError, ReplyType};
|
||||
|
||||
use bytes::Bytes;
|
||||
|
@ -5,6 +7,8 @@ use tokio::io::AsyncReadExt;
|
|||
|
||||
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)]
|
||||
pub struct Response {
|
||||
status: Status,
|
||||
|
@ -21,11 +25,25 @@ impl Response {
|
|||
}
|
||||
}
|
||||
|
||||
/// Check if status code is 2x (success).
|
||||
#[inline]
|
||||
pub fn is_ok(&self) -> bool {
|
||||
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> {
|
||||
if self.status.reply_type() == ReplyType::Success {
|
||||
Ok(self)
|
||||
|
@ -34,28 +52,49 @@ impl Response {
|
|||
}
|
||||
}
|
||||
|
||||
/// Get the response status code as [`Status`].
|
||||
pub fn 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 {
|
||||
&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> {
|
||||
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 {
|
||||
&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> {
|
||||
let mut buf = Vec::new();
|
||||
self.stream.read_to_end(&mut buf).await?;
|
||||
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> {
|
||||
let mut buf = String::new();
|
||||
self.stream.read_to_string(&mut buf).await?;
|
||||
|
|
Loading…
Reference in a new issue