Struct surf::Body [−][src]
pub struct Body { /* fields omitted */ }
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
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());
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)));
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();
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));
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]);
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));
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");
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");
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");
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");
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?);
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));
Returns true
if the body has a length of zero, and false
otherwise.
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
Attempt to return the contents of the internal buffer, filling it with more data from the inner reader if it is empty. Read more
Attempt to read from the AsyncRead
into buf
. Read more
Auto Trait Implementations
Blanket Implementations
impl<R> AsyncBufReadExt for R where
R: AsyncBufRead + ?Sized,
impl<R> AsyncBufReadExt for R where
R: AsyncBufRead + ?Sized,
Returns the contents of the internal buffer, filling it with more data if empty. Read more
Reads all bytes and appends them into buf
until the delimiter byte
or EOF is found. Read more
Reads all bytes and appends them into buf
until a newline (the 0xA byte) or EOF is found. Read more
Returns a stream over the lines of this byte stream. Read more
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
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
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
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,
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
Creates an adapter which will read at most limit
bytes from it. Read more
Creates an adaptor which will chain this stream with another. Read more
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
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
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
Helper method for splitting this read/write object into two halves. Read more
Mutably borrows from an owned value. Read more
Instruments this type with the provided Span
, returning an
Instrumented
wrapper. Read more
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,
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
Reads the exact number of bytes required to fill buf
. Read more
Creates an adaptor which will read at most limit
bytes from it. Read more
Creates a “by reference” adaptor for this instance of Read
. Read more
Transforms this Read
instance to a Stream
over its bytes. Read more
pub fn vzip(self) -> V
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more