Struct DataStream

pub struct DataStream<'r> { /* private fields */ }

Raw data stream of a request body.

This stream can only be obtained by calling Data::open() with a data limit. The stream contains all of the data in the body of the request.

Reading from a DataStream is accomplished via the various methods on the structure. In general, methods exists in two variants: those that check whether the entire stream was read and those that don’t. The former either directly or indirectly (via Capped) return an N which allows checking if the stream was read to completion while the latter do not.

Read Into	Method	Notes
String	DataStream::into_string()	Completeness checked. Preferred.
String	AsyncReadExt::read_to_string()	Unchecked w/existing String.
Vec<u8>	DataStream::into_bytes()	Checked. Preferred.
Vec<u8>	DataStream::stream_to(&mut vec)	Checked w/existing Vec.
Vec<u8>	DataStream::stream_precise_to()	Unchecked w/existing Vec.
File	DataStream::into_file()	Checked. Preferred.
File	DataStream::stream_to(&mut file)	Checked w/ existing File.
File	DataStream::stream_precise_to()	Unchecked w/ existing File.
T	DataStream::stream_to()	Checked. Any T: AsyncWrite.
T	DataStream::stream_precise_to()	Unchecked. Any T: AsyncWrite.

Implementations

impl<'r> DataStream<'r>

pub fn hint(&self) -> usize

Number of bytes a full read from self will definitely read.

Example

use rocket::data::{Data, ToByteUnit};

async fn f(data: Data<'_>) {
    let definitely_have_n_bytes = data.open(1.kibibytes()).hint();
}

pub async fn stream_to<W>(self, writer: W) -> Result<N>

where W: AsyncWrite + Unpin,

A helper method to write the body of the request to any AsyncWrite type. Returns an N which indicates how many bytes were written and whether the entire stream was read. An additional read from self may be required to check if all of the stream has been read. If that information is not needed, use DataStream::stream_precise_to().

This method is identical to tokio::io::copy(&mut self, &mut writer) except in that it returns an N to check for completeness.

Example

use std::io;
use rocket::data::{Data, ToByteUnit};

async fn data_guard(mut data: Data<'_>) -> io::Result<String> {
    // write all of the data to stdout
    let written = data.open(512.kibibytes())
        .stream_to(tokio::io::stdout()).await?;

    Ok(format!("Wrote {} bytes.", written))
}

pub async fn stream_precise_to<W>(self, writer: W) -> Result<u64>

where W: AsyncWrite + Unpin,

Like DataStream::stream_to() except that no end-of-stream check is conducted and thus read/write completeness is unknown.

Example

use std::io;
use rocket::data::{Data, ToByteUnit};

async fn data_guard(mut data: Data<'_>) -> io::Result<String> {
    // write all of the data to stdout
    let written = data.open(512.kibibytes())
        .stream_precise_to(tokio::io::stdout()).await?;

    Ok(format!("Wrote {} bytes.", written))
}

pub async fn into_bytes(self) -> Result<Capped<Vec<u8>>>

A helper method to write the body of the request to a Vec<u8>.

Example

use std::io;
use rocket::data::{Data, ToByteUnit};

async fn data_guard(data: Data<'_>) -> io::Result<Vec<u8>> {
    let bytes = data.open(4.kibibytes()).into_bytes().await?;
    if !bytes.is_complete() {
        println!("there are bytes remaining in the stream");
    }

    Ok(bytes.into_inner())
}

pub async fn into_string(self) -> Result<Capped<String>>

A helper method to write the body of the request to a String.

Example

use std::io;
use rocket::data::{Data, ToByteUnit};

async fn data_guard(data: Data<'_>) -> io::Result<String> {
    let string = data.open(10.bytes()).into_string().await?;
    if !string.is_complete() {
        println!("there are bytes remaining in the stream");
    }

    Ok(string.into_inner())
}

pub async fn into_file<P: AsRef<Path>>(self, path: P) -> Result<Capped<File>>

A helper method to write the body of the request to a file at the path determined by path. If a file at the path already exists, it is overwritten. The opened file is returned.

Example

use std::io;
use rocket::data::{Data, ToByteUnit};

async fn data_guard(mut data: Data<'_>) -> io::Result<String> {
    let file = data.open(1.megabytes()).into_file("/static/file").await?;
    if !file.is_complete() {
        println!("there are bytes remaining in the stream");
    }

    Ok(format!("Wrote {} bytes to /static/file", file.n))
}

Trait Implementations

impl AsyncRead for DataStream<'_>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.