Struct rocket::data::Limits[][src]

pub struct Limits { /* fields omitted */ }
Expand description

Mapping from (hierarchical) data types to size limits.

A Limits structure contains a mapping from a given hierarchical data type (“form”, “data-form”, “ext/pdf”, and so on) to the maximum size in bytes that should be accepted by Rocket for said data type. For instance, if the limit for “form” is set to 256, only 256 bytes from an incoming non-data form (that is, url-encoded) will be accepted.

To help in preventing DoS attacks, all incoming data reads must capped by a limit. As such, all data guards impose a limit. The name of the limit is dictated by the data guard or type itself. For instance, Form imposes the form limit for value-based forms and data-form limit for data-based forms.

If a limit is exceeded, a guard will typically fail. The Capped type allows retrieving some data types even when the limit is exceeded.

Hierarchy

Data limits are hierarchical. The / (forward slash) character delimits the levels, or layers, of a given limit. To obtain a limit value for a given name, layers are peeled from right to left until a match is found, if any. For example, fetching the limit named pet/dog/bingo will return the first of pet/dog/bingo, pet/dog or pet:

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

let limits = Limits::default()
    .limit("pet", 64.kibibytes())
    .limit("pet/dog", 128.kibibytes())
    .limit("pet/dog/bingo", 96.kibibytes());

assert_eq!(limits.get("pet/dog/bingo"), Some(96.kibibytes()));
assert_eq!(limits.get("pet/dog/ralph"), Some(128.kibibytes()));
assert_eq!(limits.get("pet/cat/bingo"), Some(64.kibibytes()));

assert_eq!(limits.get("pet/dog/bingo/hat"), Some(96.kibibytes()));

Built-in Limits

The following table details recognized built-in limits used by Rocket.

Limit NameDefaultTypeDescription
form32KiBFormentire non-data-based form
data-form2MiBFormentire data-based form
file1MiBTempFileTempFile data guard or form field
file/$extN/ATempFilefile form field with extension $ext
string8KiBStringdata guard or data form field
bytes8KiBVec<u8>data guard
json1MiBJsonJSON data and form payloads
msgpack1MiBMsgPackMessagePack data and form payloads

Usage

A Limits structure is created following the builder pattern:

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

// Set a limit of 64KiB for forms, 3MiB for PDFs, and 1MiB for JSON.
let limits = Limits::default()
    .limit("form", 64.kibibytes())
    .limit("file/pdf", 3.mebibytes())
    .limit("json", 2.mebibytes());

The Limits::default() method populates the Limits structure with default limits in the table above. A configured limit can be retrieved via the &Limits request guard:

use std::io;

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

#[post("/echo", data = "<data>")]
async fn echo(data: Data<'_>, limits: &Limits) -> io::Result<String> {
    let limit = limits.get("data").unwrap_or(1.mebibytes());
    Ok(data.open(limit).into_string().await?.value)
}

…or via the Request::limits() method:

use rocket::request::Request;
use rocket::data::{self, Data, FromData};

#[rocket::async_trait]
impl<'r> FromData<'r> for MyType {
    type Error = MyError;

    async fn from_data(req: &'r Request<'_>, data: Data<'r>) -> data::Outcome<'r, Self> {
        let limit = req.limits().get("my-data-type");
        /* .. */
    }
}

Implementations

Default limit for value-based forms.

Default limit for data-based forms.

Default limit for temporary files.

Default limit for strings.

Default limit for bytes.

Default limit for JSON payloads.

Default limit for MessagePack payloads.

Construct a new Limits structure with no limits set.

Example

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

let limits = Limits::default();
assert_eq!(limits.get("form"), Some(32.kibibytes()));

let limits = Limits::new();
assert_eq!(limits.get("form"), None);

Adds or replaces a limit in self, consuming self and returning a new Limits structure with the added or replaced limit.

Example

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

let limits = Limits::default();
assert_eq!(limits.get("form"), Some(32.kibibytes()));
assert_eq!(limits.get("json"), Some(1.mebibytes()));
assert_eq!(limits.get("cat"), None);

let limits = limits.limit("cat", 1.mebibytes());
assert_eq!(limits.get("form"), Some(32.kibibytes()));
assert_eq!(limits.get("cat"), Some(1.mebibytes()));

let limits = limits.limit("json", 64.mebibytes());
assert_eq!(limits.get("json"), Some(64.mebibytes()));

Returns the limit named name, proceeding hierarchically from right to left until one is found, or returning None if none is found.

Example

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

let limits = Limits::default()
    .limit("json", 2.mebibytes())
    .limit("file/jpeg", 4.mebibytes())
    .limit("file/jpeg/special", 8.mebibytes());

assert_eq!(limits.get("form"), Some(32.kibibytes()));
assert_eq!(limits.get("json"), Some(2.mebibytes()));
assert_eq!(limits.get("data-form"), Some(Limits::DATA_FORM));

assert_eq!(limits.get("file"), Some(1.mebibytes()));
assert_eq!(limits.get("file/png"), Some(1.mebibytes()));
assert_eq!(limits.get("file/jpeg"), Some(4.mebibytes()));
assert_eq!(limits.get("file/jpeg/inner"), Some(4.mebibytes()));
assert_eq!(limits.get("file/jpeg/special"), Some(8.mebibytes()));

assert!(limits.get("cats").is_none());

Returns the limit for the name created by joining the strings in layers with / as a separator, then proceeding like Limits::get(), hierarchically from right to left until one is found, or returning None if none is found.

This methods exists to allow finding hierarchical limits without constructing a string to call get() with but otherwise returns the same results.

Example

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

let limits = Limits::default()
    .limit("json", 2.mebibytes())
    .limit("file/jpeg", 4.mebibytes())
    .limit("file/jpeg/special", 8.mebibytes());

assert_eq!(limits.find(["json"]), Some(2.mebibytes()));
assert_eq!(limits.find(["json", "person"]), Some(2.mebibytes()));

assert_eq!(limits.find(["file"]), Some(1.mebibytes()));
assert_eq!(limits.find(["file", "png"]), Some(1.mebibytes()));
assert_eq!(limits.find(["file", "jpeg"]), Some(4.mebibytes()));
assert_eq!(limits.find(["file", "jpeg", "inner"]), Some(4.mebibytes()));
assert_eq!(limits.find(["file", "jpeg", "special"]), Some(8.mebibytes()));

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Deserialize this value from the given Serde deserializer. Read more

Formats the value using the given formatter. Read more

The associated error to be returned if derivation fails.

Derives an instance of Self from the incoming request metadata. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

Serialize this value into the given Serde serializer. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Converts self into T using Into<T>. Read more

Converts self into a target type. Read more

Compare self to key and return true if they are equal.

Causes self to use its Binary implementation when Debug-formatted.

Causes self to use its Display implementation when Debug-formatted. Read more

Causes self to use its LowerExp implementation when Debug-formatted. Read more

Causes self to use its LowerHex implementation when Debug-formatted. Read more

Causes self to use its Octal implementation when Debug-formatted.

Causes self to use its Pointer implementation when Debug-formatted. Read more

Causes self to use its UpperExp implementation when Debug-formatted. Read more

Causes self to use its UpperHex implementation when Debug-formatted. 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

Performs the conversion.

Converts self into a collection.

Pipes by value. This is generally the method you want to use. Read more

Borrows self and passes that borrow into the pipe function. Read more

Mutably borrows self and passes that borrow into the pipe function. Read more

Borrows self, then passes self.borrow() into the pipe function. Read more

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more

Borrows self, then passes self.as_ref() into the pipe function.

Mutably borrows self, then passes self.as_mut() into the pipe function. Read more

Borrows self, then passes self.deref() into the pipe function.

Mutably borrows self, then passes self.deref_mut() into the pipe function. Read more

Pipes a value into a function that cannot ordinarily be called in suffix position. Read more

Pipes a trait borrow into a function that cannot normally be called in suffix position. Read more

Pipes a trait mutable borrow into a function that cannot normally be called in suffix position. Read more

Pipes a trait borrow into a function that cannot normally be called in suffix position. Read more

Pipes a trait mutable borrow into a function that cannot normally be called in suffix position. Read more

Pipes a dereference into a function that cannot normally be called in suffix position. Read more

Pipes a mutable dereference into a function that cannot normally be called in suffix position. Read more

Pipes a reference into a function that cannot ordinarily be called in suffix position. Read more

Pipes a mutable reference into a function that cannot ordinarily be called in suffix position. Read more

Should always be Self

Immutable access to a value. Read more

Mutable access to a value. Read more

Immutable access to the Borrow<B> of a value. Read more

Mutable access to the BorrowMut<B> of a value. Read more

Immutable access to the AsRef<R> view of a value. Read more

Mutable access to the AsMut<R> view of a value. Read more

Immutable access to the Deref::Target of a value. Read more

Mutable access to the Deref::Target of a value. Read more

Calls .tap() only in debug builds, and is erased in release builds.

Calls .tap_mut() only in debug builds, and is erased in release builds. Read more

Calls .tap_borrow() only in debug builds, and is erased in release builds. Read more

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds. Read more

Calls .tap_ref() only in debug builds, and is erased in release builds. Read more

Calls .tap_ref_mut() only in debug builds, and is erased in release builds. Read more

Calls .tap_deref() only in debug builds, and is erased in release builds. Read more

Calls .tap_deref_mut() only in debug builds, and is erased in release builds. Read more

Provides immutable access for inspection. Read more

Calls tap in debug builds, and does nothing in release builds.

Provides mutable access for modification. Read more

Calls tap_mut in debug builds, and does nothing in release builds.

Provides immutable access to the reference for inspection.

Calls tap_ref in debug builds, and does nothing in release builds.

Provides mutable access to the reference for modification.

Calls tap_ref_mut in debug builds, and does nothing in release builds.

Provides immutable access to the borrow for inspection. Read more

Calls tap_borrow in debug builds, and does nothing in release builds.

Provides mutable access to the borrow for modification.

Calls tap_borrow_mut in debug builds, and does nothing in release builds. Read more

Immutably dereferences self for inspection.

Calls tap_deref in debug builds, and does nothing in release builds.

Mutably dereferences self for modification.

Calls tap_deref_mut in debug builds, and does nothing in release builds. Read more

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

Attempts to convert self into T using TryInto<T>. Read more

Attempts to convert self into a target type. Read more

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.