Struct Upload 

pub struct Upload { /* private fields */ }

Something to upload: a file, bytes, a reader or a stream, with a file name and a media type.

An Upload becomes a request body (RequestBuilder::body(upload)) or a multipart part (Part::upload). Generated clients take one for every file parameter, and a PathBuf, &Path, Vec<u8> or Bytes converts into one.

Source	Length	Retried
Upload::bytes (Bytes, Vec<u8>, &'static [u8])	known	yes, without a copy
Upload::path, Upload::file	from the file’s metadata	yes: the file is opened again
Upload::from_fn	Upload::len	yes: the function makes a fresh stream
Upload::reader, Upload::stream	Upload::len	no, unless Upload::buffer_for_retry holds it all

When the length is known, the body (or the whole multipart form) is sent with a Content-Length, not chunked. A path’s length is read by Upload::resolve, which generated clients call; Upload::file is Upload::path(path).resolve().

use timvw_rust_runtime::Upload;

// Streamed from disk, named `photo.png`, `image/png` guessed from the extension.
let file = Upload::file("data/photo.png").await?;
// Bytes held in memory, with a name and a media type of your own.
let image = Upload::bytes(vec![0x89, b'P', b'N', b'G']).file_name("cat.png").mime("image/png");
// The second 5 MiB of a file, for an API that takes a large file in parts.
let part = Upload::path("data/big.bin").slice(5 << 20..10 << 20).resolve().await?;

Implementations

impl Upload

pub fn bytes(bytes: impl Into<Bytes>) -> Self

Bytes held in memory: their length is known, and a retry sends them again without a copy.

pub fn stream<S, B, E>(stream: S) -> Self

where S: Stream<Item = Result<B, E>> + MaybeSend + 'static, B: Into<Bytes> + 'static, E: Into<BoxError> + 'static,

A stream of chunks, read once: a retry cannot send it again unless Upload::buffer_for_retry holds it. Its length is unknown (the body is chunked) unless set with Upload::len. The stream must be Send, except on WebAssembly (MaybeSend).

pub fn from_fn<F, S, B, E>(make: F) -> Self

where F: Fn() -> S + MaybeSend + MaybeSync + 'static, S: Stream<Item = Result<B, E>> + MaybeSend + 'static, B: Into<Bytes> + 'static, E: Into<BoxError> + 'static,

A stream that make starts afresh for every attempt, so a retry sends it again. Its length is unknown (the body is chunked) unless set with Upload::len; every stream make returns must then have that length. make must be Send and Sync, and its streams Send, except on WebAssembly (MaybeSend, MaybeSync).

pub fn file_name(self, file_name: impl Into<Cow<'static, str>>) -> Self

Sets the file name (multipart filename). A path’s is its last component; a multipart part of an upload without one is named file.

pub fn mime(self, mime: impl Into<Cow<'static, str>>) -> Self

Sets the media type (the Content-Type of a multipart part), such as image/png. A path’s is guessed from its extension. A value that is not a valid header value is sent as application/octet-stream.

pub fn name(&self) -> Option<&str>

The file name: the one set with Upload::file_name, or a path’s last component. None for bytes, readers and streams without one.

pub fn media_type(&self) -> Option<&str>

The media type: the one set with Upload::mime, or guessed from a path’s extension.

pub fn len(self, len: u64) -> Self

Sets the length of the source in bytes, for a stream or a reader: the body is then sent with a Content-Length, and the stream must have exactly that many bytes.

pub fn slice(self, range: impl RangeBounds<u64>) -> Self

Only the bytes in range of the source (of the current slice, when sliced again): a file is read from the start of the range (a seek, no copy), bytes are sliced without a copy, a stream skips to it. For APIs that take a large file in parts.

pub fn buffer_for_retry(self, limit: usize) -> Self

Lets a retry send a stream or a reader again: Upload::resolve reads it into memory, up to limit bytes. A stream that ends within the limit becomes bytes (replayable, with a known length); a longer one is sent once, as if this were not set. Without resolve (which generated clients call) this has no effect.

pub fn content_length(&self) -> Option<u64>

The number of bytes the upload sends, when known: bytes, a resolved path, or a stream given a len.

pub fn is_replayable(&self) -> bool

Whether a retry can send the upload again: bytes, a path and Upload::from_fn can, a stream or a reader cannot (unless Upload::buffer_for_retry held it all when it was resolved).

pub async fn resolve(self) -> Result<Self, Error>

Gets the upload ready to send: reads a path’s length from its metadata (an error when the file does not exist), and reads a stream with Upload::buffer_for_retry into memory. Other uploads are returned as they are.

impl Upload

pub fn path(path: impl Into<PathBuf>) -> Self

Available on crate feature fs only.

A file, streamed from disk with tokio and opened again for each attempt, so a retry sends it again.

The file name is the path’s last component, the media type is guessed from its extension. Nothing is read until the request is sent; Upload::resolve (or Upload::file) reads the length, so the body is sent with a Content-Length, and fails early when the file does not exist.

On WebAssembly there is no file system: the upload fails (Upload::resolve, or the request) with an I/O error of kind Unsupported. The function is there so that code taking a PathBuf (a generated model with a file variant) compiles; send bytes or a stream instead.

impl Upload

pub async fn file(path: impl Into<PathBuf>) -> Result<Self, Error>

Available on crate feature fs and non-target_family=wasm only.

Upload::path, resolved: its length read from the file’s metadata, an error when there is no such file.

pub fn reader<R>(reader: R) -> Self

where R: AsyncRead + Send + 'static,

Available on crate feature fs and non-target_family=wasm only.

A tokio reader, read once in chunks: a retry cannot send it again unless Upload::buffer_for_retry holds it. Its length is unknown (the body is chunked) unless set with Upload::len.

Trait Implementations

impl Clone for Upload

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Upload

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&'static [u8]> for Upload

fn from(bytes: &'static [u8]) -> Self

Converts to this type from the input type.

impl From<&Path> for Upload

Available on crate feature fs only.

fn from(path: &Path) -> Self

Converts to this type from the input type.

impl From<&PathBuf> for Upload

Available on crate feature fs only.

fn from(path: &PathBuf) -> Self

Converts to this type from the input type.

impl From<&Upload> for Upload

fn from(upload: &Upload) -> Self

Converts to this type from the input type.

impl From<Bytes> for Upload

fn from(bytes: Bytes) -> Self

Converts to this type from the input type.

impl From<PathBuf> for Upload

Available on crate feature fs only.

fn from(path: PathBuf) -> Self

Converts to this type from the input type.

impl From<Upload> for Body

fn from(upload: Upload) -> Self

Converts to this type from the input type.

impl From<Vec<u8>> for Upload

fn from(bytes: Vec<u8>) -> Self

Converts to this type from the input type.

impl PartialEq for Upload

Two uploads are equal when they send the same thing: equal bytes, the same path, or the same stream or from_fn function (an upload and its clones), with the same file name, media type, length, slice and buffer_for_retry limit. Two streams are never equal to each other, even with the same contents: they are not read to compare them. A path is compared as a path, not by the file’s contents, and whether it was resolved does not matter.

It lets a model that holds an upload (a generated multipart union with a file variant) derive PartialEq.

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.