Struct rocket::data::Limits

pub struct Limits { /* private fields */ }

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 Name	Default	Type	Description
form	32KiB	Form	entire non-data-based form
data-form	2MiB	Form	entire data-based form
file	1MiB	TempFile	TempFile data guard or form field
file/$ext	N/A	TempFile	file form field with extension $ext
string	8KiB	String	data guard or form field
string	8KiB	&str	data guard or form field
bytes	8KiB	Vec<u8>	data guard
bytes	8KiB	[&[u8]]	data guard or form field
json	1MiB	Json	JSON data and form payloads
msgpack	1MiB	MsgPack	MessagePack 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

impl Limits

pub const FORM: ByteUnit = _

Default limit for value-based forms.

pub const DATA_FORM: ByteUnit = _

Default limit for data-based forms.

pub const FILE: ByteUnit = _

Default limit for temporary files.

pub const STRING: ByteUnit = _

Default limit for strings.

pub const BYTES: ByteUnit = _

Default limit for bytes.

pub const JSON: ByteUnit = _

Default limit for JSON payloads.

pub const MESSAGE_PACK: ByteUnit = _

Default limit for MessagePack payloads.

pub fn new() -> Self

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

pub fn limit<S: Into<Uncased<'static>>>(self, name: S, limit: ByteUnit) -> Self

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

pub fn get<S: AsRef<str>>(&self, name: S) -> Option<ByteUnit>

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

pub fn find<S: AsRef<str>, L: AsRef<[S]>>(&self, layers: L) -> Option<ByteUnit>

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

impl Clone for Limits

fn clone(&self) -> Limits

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Limits

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

Formats the value using the given formatter.

impl Default for Limits

fn default() -> Limits

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Limits

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Limits

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

Formats the value using the given formatter.

impl<'r> FromRequest<'r> for &'r Limits

type Error = Infallible

The associated error to be returned if derivation fails.

fn from_request<'life0, 'async_trait>( req: &'r Request<'life0> ) -> Pin<Box<dyn Future<Output = Outcome<Self, Self::Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Derives an instance of Self from the incoming request metadata.

impl PartialEq for Limits

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Limits

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Limits

impl StructuralPartialEq for Limits