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");

Creates a Body from a type, serializing it as JSON.

Mime

The encoding is set to application/json.

Examples

use http_types::{Body, convert::json};

let body = Body::from_json(&json!({ "name": "Chashu" }));

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.

Returns the mime type of this Body.

Sets the mime type of this 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

Attempt to return the contents of the internal buffer, filling it with more data from the inner reader if it is empty. Read more

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to poll_read. Read more

Attempt to read from the AsyncRead into buf. Read more

Attempt to read from the AsyncRead into bufs using vectored IO operations. Read more

Formats the value using the given formatter. Read more

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Returns the contents of the internal buffer, filling it with more data if empty. Read more

Consumes amt buffered bytes. 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

Returns a stream over the contents of this reader split on the specified byte. 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

A convenience for calling [AsyncBufRead::consume] on Unpin IO types. 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

Reads some bytes from the byte stream. Read more

Like [read()][AsyncReadExt::read()], except it reads into a slice of buffers. Read more

Reads the entire contents and appends them to a Vec. Read more

Reads the entire contents and appends them to a String. Read more

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

Converts this [AsyncRead] into a [Stream] of bytes. Read more

Creates an adapter which will chain this stream with another. Read more

Boxes the reader and changes its type to dyn AsyncRead + Send + 'a. 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

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

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

Creates an AsyncRead adapter which will read at most limit bytes from the underlying reader. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Reads all bytes into buf until the delimiter byte or EOF is reached. Read more

Reads all bytes and appends them into buf until a newline (the 0xA byte) is reached. Read more

Returns a stream over the lines of this byte stream. Read more

Returns a stream over the contents of this reader split on the byte byte. Read more

Performs the conversion.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Performs the conversion.

Reads some bytes from the byte stream. Read more

Like read, except that it reads into a slice of buffers. Read more

Reads all bytes from the byte stream. Read more

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

Creates an adaptor which will chain this stream with another. Read more

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

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