Struct ajars_surf::surf::http::Body
[−]pub struct Body { /* private fields */ }
Expand description
A streaming HTTP body.
Body
represents the HTTP body of both Request
and Response
. It’s completely
streaming, and implements AsyncBufRead
to make reading from it both convenient and
performant.
Both Request
and Response
take Body
by Into<Body>
, which means that passing string
literals, byte vectors, but also concrete Body
instances are all valid. This makes it
easy to create both quick HTTP requests, but also have fine grained control over how bodies
are streamed out.
Examples
use http_types::{Body, Response, StatusCode};
use async_std::io::Cursor;
let mut req = Response::new(StatusCode::Ok);
req.set_body("Hello Chashu");
let mut req = Response::new(StatusCode::Ok);
let cursor = Cursor::new("Hello Nori");
let body = Body::from_reader(cursor, Some(10)); // set the body length
req.set_body(body);
Length
One of the details of Body
to be aware of is the length
parameter. The value of
length
is used by HTTP implementations to determine how to treat the stream. If a length
is known ahead of time, it’s strongly recommended to pass it.
Casting from Vec<u8>
, String
, or similar to Body
will automatically set the value of
length
.
Content Encoding
By default Body
will come with a fallback Mime type that is used by Request
and
Response
if no other type has been set, and no other Mime type can be inferred.
It’s strongly recommended to always set a mime type on both the Request
and Response
,
and not rely on the fallback mechanisms. However, they’re still there if you need them.
Implementations
impl Body
impl Body
pub fn empty() -> Body
pub fn empty() -> Body
Create a new empty Body
.
The body will have a length of 0
, and the Mime type set to application/octet-stream
if
no other mime type has been set or can be sniffed.
Examples
use http_types::{Body, Response, StatusCode};
let mut req = Response::new(StatusCode::Ok);
req.set_body(Body::empty());
pub fn from_reader(
reader: impl AsyncBufRead + Unpin + Send + Sync + 'static,
len: Option<usize>
) -> Body
pub fn from_reader(
reader: impl AsyncBufRead + Unpin + Send + Sync + 'static,
len: Option<usize>
) -> Body
Create a Body
from a reader with an optional length.
The Mime type is set to application/octet-stream
if no other mime type has been set or can
be sniffed. If a Body
has no length, HTTP implementations will often switch over to
framed messages such as Chunked
Encoding.
Examples
use http_types::{Body, Response, StatusCode};
use async_std::io::Cursor;
let mut req = Response::new(StatusCode::Ok);
let cursor = Cursor::new("Hello Nori");
let len = 10;
req.set_body(Body::from_reader(cursor, Some(len)));
pub fn into_reader(
self
) -> Box<dyn AsyncBufRead + Sync + Send + Unpin + 'static, Global>
pub fn into_reader(
self
) -> Box<dyn AsyncBufRead + Sync + Send + Unpin + 'static, Global>
Get the inner reader from the Body
Examples
use http_types::Body;
use async_std::io::Cursor;
let cursor = Cursor::new("Hello Nori");
let body = Body::from_reader(cursor, None);
let _ = body.into_reader();
pub fn from_bytes(bytes: Vec<u8, Global>) -> Body
pub fn from_bytes(bytes: Vec<u8, Global>) -> Body
Create a Body
from a Vec of bytes.
The Mime type is set to application/octet-stream
if no other mime type has been set or can
be sniffed. If a Body
has no length, HTTP implementations will often switch over to
framed messages such as Chunked
Encoding.
Examples
use http_types::{Body, Response, StatusCode};
use async_std::io::Cursor;
let mut req = Response::new(StatusCode::Ok);
let input = vec![1, 2, 3];
req.set_body(Body::from_bytes(input));
pub async fn into_bytes(self) -> Result<Vec<u8, Global>, Error>
pub async fn into_bytes(self) -> Result<Vec<u8, Global>, Error>
Parse the body into a Vec<u8>
.
Examples
use http_types::Body;
let bytes = vec![1, 2, 3];
let body = Body::from_bytes(bytes);
let bytes: Vec<u8> = body.into_bytes().await?;
assert_eq!(bytes, vec![1, 2, 3]);
pub fn from_string(s: String) -> Body
pub fn from_string(s: String) -> Body
Create a Body
from a String
The Mime type is set to text/plain
if no other mime type has been set or can
be sniffed. If a Body
has no length, HTTP implementations will often switch over to
framed messages such as Chunked
Encoding.
Examples
use http_types::{Body, Response, StatusCode};
use async_std::io::Cursor;
let mut req = Response::new(StatusCode::Ok);
let input = String::from("hello Nori!");
req.set_body(Body::from_string(input));
pub async fn into_string(self) -> Result<String, Error>
pub async fn into_string(self) -> Result<String, Error>
Read the body as a string
Examples
use http_types::Body;
use async_std::io::Cursor;
let cursor = Cursor::new("Hello Nori");
let body = Body::from_reader(cursor, None);
assert_eq!(&body.into_string().await.unwrap(), "Hello Nori");
pub async fn into_json<T>(self) -> Result<T, Error> where
T: DeserializeOwned,
pub async fn into_json<T>(self) -> Result<T, Error> where
T: DeserializeOwned,
Parse the body as JSON, serializing it to a struct.
Examples
use http_types::Body;
use http_types::convert::{Serialize, Deserialize};
#[derive(Debug, Serialize, Deserialize)]
struct Cat { name: String }
let cat = Cat { name: String::from("chashu") };
let body = Body::from_json(&cat)?;
let cat: Cat = body.into_json().await?;
assert_eq!(&cat.name, "chashu");
pub fn from_form(form: &impl Serialize) -> Result<Body, Error>
pub fn from_form(form: &impl Serialize) -> Result<Body, Error>
Creates a Body
from a type, serializing it using form encoding.
Mime
The encoding is set to application/x-www-form-urlencoded
.
Errors
An error will be returned if the encoding failed.
Examples
use http_types::Body;
use http_types::convert::{Serialize, Deserialize};
#[derive(Debug, Serialize, Deserialize)]
struct Cat { name: String }
let cat = Cat { name: String::from("chashu") };
let body = Body::from_form(&cat)?;
let cat: Cat = body.into_form().await?;
assert_eq!(&cat.name, "chashu");
pub async fn into_form<T>(self) -> Result<T, Error> where
T: DeserializeOwned,
pub async fn into_form<T>(self) -> Result<T, Error> where
T: DeserializeOwned,
Parse the body from form encoding into a type.
Errors
An error is returned if the underlying IO stream errors, or if the body could not be deserialized into the type.
Examples
use http_types::Body;
use http_types::convert::{Serialize, Deserialize};
#[derive(Debug, Serialize, Deserialize)]
struct Cat { name: String }
let cat = Cat { name: String::from("chashu") };
let body = Body::from_form(&cat)?;
let cat: Cat = body.into_form().await?;
assert_eq!(&cat.name, "chashu");
pub async fn from_file<P>(path: P) -> Result<Body, Error> where
P: AsRef<Path>,
pub async fn from_file<P>(path: P) -> Result<Body, Error> where
P: AsRef<Path>,
Create a Body
from a file.
The Mime type set to application/octet-stream
if no other mime type has
been set or can be sniffed.
Examples
use http_types::{Body, Response, StatusCode};
let mut res = Response::new(StatusCode::Ok);
res.set_body(Body::from_file("/path/to/file").await?);
pub fn len(&self) -> Option<usize>
pub fn len(&self) -> Option<usize>
Get the length of the body in bytes.
Examples
use http_types::Body;
use async_std::io::Cursor;
let cursor = Cursor::new("Hello Nori");
let len = 10;
let body = Body::from_reader(cursor, Some(len));
assert_eq!(body.len(), Some(10));
pub fn is_empty(&self) -> Option<bool>
pub fn is_empty(&self) -> Option<bool>
Returns true
if the body has a length of zero, and false
otherwise.
pub fn chain(self, other: Body) -> Body
pub fn chain(self, other: Body) -> Body
Create a Body by chaining another Body after this one, consuming both.
If both Body instances have a length, and their sum does not overflow, the resulting Body will have a length.
If both Body instances have the same fallback MIME type, the resulting
Body will have the same fallback MIME type; otherwise, the resulting
Body will have the fallback MIME type application/octet-stream
.
Examples
use http_types::Body;
use async_std::io::Cursor;
let cursor = Cursor::new("Hello ");
let body = Body::from_reader(cursor, None).chain(Body::from("Nori"));
assert_eq!(&body.into_string().await.unwrap(), "Hello Nori");
Trait Implementations
impl AsyncBufRead for Body
impl AsyncBufRead for Body
impl AsyncRead for Body
impl AsyncRead for Body
impl<'__pin> Unpin for Body where
__Origin<'__pin>: Unpin,
Auto Trait Implementations
Blanket Implementations
impl<R> AsyncBufReadExt for R where
R: AsyncBufRead + ?Sized,
impl<R> AsyncBufReadExt for R where
R: AsyncBufRead + ?Sized,
fn fill_buf(&mut self) -> FillBuf<'_, Self> where
Self: Unpin,
fn fill_buf(&mut self) -> FillBuf<'_, Self> where
Self: Unpin,
Returns the contents of the internal buffer, filling it with more data if empty. Read more
fn read_until(
&'a mut self,
byte: u8,
buf: &'a mut Vec<u8, Global>
) -> ReadUntilFuture<'a, Self> where
Self: Unpin,
fn read_until(
&'a mut self,
byte: u8,
buf: &'a mut Vec<u8, Global>
) -> ReadUntilFuture<'a, Self> where
Self: Unpin,
Reads all bytes and appends them into buf
until the delimiter byte
or EOF is found. Read more
fn read_line(&'a mut self, buf: &'a mut String) -> ReadLineFuture<'a, Self> where
Self: Unpin,
fn read_line(&'a mut self, buf: &'a mut String) -> ReadLineFuture<'a, Self> where
Self: Unpin,
Reads all bytes and appends them into buf
until a newline (the 0xA byte) or EOF is found. Read more
impl<R> AsyncBufReadExt for R where
R: AsyncBufRead + ?Sized,
impl<R> AsyncBufReadExt for R where
R: AsyncBufRead + ?Sized,
fn fill_buf(&mut self) -> FillBuf<'_, Self> where
Self: Unpin,
fn fill_buf(&mut self) -> FillBuf<'_, Self> where
Self: Unpin,
Creates a future which will wait for a non-empty buffer to be available from this I/O object or EOF to be reached. Read more
fn consume_unpin(&mut self, amt: usize) where
Self: Unpin,
fn consume_unpin(&mut self, amt: usize) where
Self: Unpin,
fn read_until(
&'a mut self,
byte: u8,
buf: &'a mut Vec<u8, Global>
) -> ReadUntil<'a, Self> where
Self: Unpin,
fn read_until(
&'a mut self,
byte: u8,
buf: &'a mut Vec<u8, Global>
) -> ReadUntil<'a, Self> where
Self: Unpin,
Creates a future which will read all the bytes associated with this I/O
object into buf
until the delimiter byte
or EOF is reached.
This method is the async equivalent to BufRead::read_until
. Read more
fn read_line(&'a mut self, buf: &'a mut String) -> ReadLine<'a, Self> where
Self: Unpin,
fn read_line(&'a mut self, buf: &'a mut String) -> ReadLine<'a, Self> where
Self: Unpin,
Creates a future which will read all the bytes associated with this I/O
object into buf
until a newline (the 0xA byte) or EOF is reached,
This method is the async equivalent to BufRead::read_line
. Read more
fn lines(self) -> Lines<Self>
fn lines(self) -> Lines<Self>
Returns a stream over the lines of this reader.
This method is the async equivalent to BufRead::lines
. Read more
impl<R> AsyncReadExt for R where
R: AsyncRead + ?Sized,
impl<R> AsyncReadExt for R where
R: AsyncRead + ?Sized,
fn read(&'a mut self, buf: &'a mut [u8]) -> ReadFuture<'a, Self> where
Self: Unpin,
fn read(&'a mut self, buf: &'a mut [u8]) -> ReadFuture<'a, Self> where
Self: Unpin,
Reads some bytes from the byte stream. Read more
fn read_vectored(
&'a mut self,
bufs: &'a mut [IoSliceMut<'a>]
) -> ReadVectoredFuture<'a, Self> where
Self: Unpin,
fn read_vectored(
&'a mut self,
bufs: &'a mut [IoSliceMut<'a>]
) -> ReadVectoredFuture<'a, Self> where
Self: Unpin,
Like [read()
][AsyncReadExt::read()
], except it reads into a slice of buffers. Read more
fn read_to_end(
&'a mut self,
buf: &'a mut Vec<u8, Global>
) -> ReadToEndFuture<'a, Self> where
Self: Unpin,
fn read_to_end(
&'a mut self,
buf: &'a mut Vec<u8, Global>
) -> ReadToEndFuture<'a, Self> where
Self: Unpin,
fn read_to_string(
&'a mut self,
buf: &'a mut String
) -> ReadToStringFuture<'a, Self> where
Self: Unpin,
fn read_to_string(
&'a mut self,
buf: &'a mut String
) -> ReadToStringFuture<'a, Self> where
Self: Unpin,
fn read_exact(&'a mut self, buf: &'a mut [u8]) -> ReadExactFuture<'a, Self> where
Self: Unpin,
fn read_exact(&'a mut self, buf: &'a mut [u8]) -> ReadExactFuture<'a, Self> where
Self: Unpin,
Reads the exact number of bytes required to fill buf
. Read more
fn take(self, limit: u64) -> Take<Self>
fn take(self, limit: u64) -> Take<Self>
Creates an adapter which will read at most limit
bytes from it. Read more
impl<R> AsyncReadExt for R where
R: AsyncRead + ?Sized,
impl<R> AsyncReadExt for R where
R: AsyncRead + ?Sized,
fn chain<R>(self, next: R) -> Chain<Self, R> where
R: AsyncRead,
fn chain<R>(self, next: R) -> Chain<Self, R> where
R: AsyncRead,
Creates an adaptor which will chain this stream with another. Read more
fn read(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self> where
Self: Unpin,
fn read(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self> where
Self: Unpin,
Tries to read some bytes directly into the given buf
in asynchronous
manner, returning a future type. Read more
fn read_vectored(
&'a mut self,
bufs: &'a mut [IoSliceMut<'a>]
) -> ReadVectored<'a, Self> where
Self: Unpin,
fn read_vectored(
&'a mut self,
bufs: &'a mut [IoSliceMut<'a>]
) -> ReadVectored<'a, Self> where
Self: Unpin,
Creates a future which will read from the AsyncRead
into bufs
using vectored
IO operations. Read more
fn read_exact(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self> where
Self: Unpin,
fn read_exact(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self> where
Self: Unpin,
Creates a future which will read exactly enough bytes to fill buf
,
returning an error if end of file (EOF) is hit sooner. Read more
fn read_to_end(
&'a mut self,
buf: &'a mut Vec<u8, Global>
) -> ReadToEnd<'a, Self> where
Self: Unpin,
fn read_to_end(
&'a mut self,
buf: &'a mut Vec<u8, Global>
) -> ReadToEnd<'a, Self> where
Self: Unpin,
Creates a future which will read all the bytes from this AsyncRead
. Read more
fn read_to_string(&'a mut self, buf: &'a mut String) -> ReadToString<'a, Self> where
Self: Unpin,
fn read_to_string(&'a mut self, buf: &'a mut String) -> ReadToString<'a, Self> where
Self: Unpin,
Creates a future which will read all the bytes from this AsyncRead
. Read more
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T> BufReadExt for T where
T: AsyncBufRead + ?Sized,
impl<T> BufReadExt for T where
T: AsyncBufRead + ?Sized,
fn read_until(
&'a mut self,
byte: u8,
buf: &'a mut Vec<u8, Global>
) -> ReadUntilFuture<'a, Self> where
Self: Unpin,
fn read_until(
&'a mut self,
byte: u8,
buf: &'a mut Vec<u8, Global>
) -> ReadUntilFuture<'a, Self> where
Self: Unpin,
Reads all bytes into buf
until the delimiter byte
or EOF is reached. Read more
fn read_line(&'a mut self, buf: &'a mut String) -> ReadLineFuture<'a, Self> where
Self: Unpin,
fn read_line(&'a mut self, buf: &'a mut String) -> ReadLineFuture<'a, Self> where
Self: Unpin,
Reads all bytes and appends them into buf
until a newline (the 0xA byte) is
reached. Read more
impl<T> ReadExt for T where
T: AsyncRead + ?Sized,
impl<T> ReadExt for T where
T: AsyncRead + ?Sized,
fn read(&'a mut self, buf: &'a mut [u8]) -> ReadFuture<'a, Self> where
Self: Unpin,
fn read(&'a mut self, buf: &'a mut [u8]) -> ReadFuture<'a, Self> where
Self: Unpin,
Reads some bytes from the byte stream. Read more
fn read_vectored(
&'a mut self,
bufs: &'a mut [IoSliceMut<'a>]
) -> ReadVectoredFuture<'a, Self> where
Self: Unpin,
fn read_vectored(
&'a mut self,
bufs: &'a mut [IoSliceMut<'a>]
) -> ReadVectoredFuture<'a, Self> where
Self: Unpin,
fn read_to_end(
&'a mut self,
buf: &'a mut Vec<u8, Global>
) -> ReadToEndFuture<'a, Self> where
Self: Unpin,
fn read_to_end(
&'a mut self,
buf: &'a mut Vec<u8, Global>
) -> ReadToEndFuture<'a, Self> where
Self: Unpin,
Reads all bytes from the byte stream. Read more
fn read_to_string(
&'a mut self,
buf: &'a mut String
) -> ReadToStringFuture<'a, Self> where
Self: Unpin,
fn read_to_string(
&'a mut self,
buf: &'a mut String
) -> ReadToStringFuture<'a, Self> where
Self: Unpin,
Reads all bytes from the byte stream and appends them into a string. Read more
fn read_exact(&'a mut self, buf: &'a mut [u8]) -> ReadExactFuture<'a, Self> where
Self: Unpin,
fn read_exact(&'a mut self, buf: &'a mut [u8]) -> ReadExactFuture<'a, Self> where
Self: Unpin,
Reads the exact number of bytes required to fill buf
. Read more
fn take(self, limit: u64) -> Take<Self>
fn take(self, limit: u64) -> Take<Self>
Creates an adaptor which will read at most limit
bytes from it. Read more