From 1524b9a6b2636d150d5c59da61e7566b62bd1317 Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Tue, 18 Apr 2017 00:36:39 -0700 Subject: [PATCH] Document size limits. --- contrib/src/json.rs | 18 ++++++++++++++++++ contrib/src/msgpack.rs | 18 ++++++++++++++++++ lib/src/config/mod.rs | 11 +++++++++-- lib/src/request/form/mod.rs | 26 ++++++++++++++++++++------ 4 files changed, 65 insertions(+), 8 deletions(-) diff --git a/contrib/src/json.rs b/contrib/src/json.rs index b31ba43b..437c3022 100644 --- a/contrib/src/json.rs +++ b/contrib/src/json.rs @@ -18,6 +18,8 @@ pub use serde_json::error::Error as SerdeError; /// The JSON type: implements `FromData` and `Responder`, allowing you to easily /// consume and respond with JSON. /// +/// ## Receiving JSON +/// /// If you're receiving JSON data, simply add a `data` parameter to your route /// arguments and ensure the type of the parameter is a `JSON`, where `T` is /// some type you'd like to parse from JSON. `T` must implement `Deserialize` @@ -36,6 +38,8 @@ pub use serde_json::error::Error as SerdeError; /// doesn't specify "application/json" as its `Content-Type` header value will /// not be routed to the handler. /// +/// ## Sending JSON +/// /// If you're responding with JSON data, return a `JSON` type, where `T` /// implements `Serialize` from [Serde](https://github.com/serde-rs/json). The /// content type of the response is set to `application/json` automatically. @@ -48,6 +52,20 @@ pub use serde_json::error::Error as SerdeError; /// JSON(user_from_id) /// } /// ``` +/// +/// ## Incoming Data Limits +/// +/// The default size limit for incoming JSON data is 1MiB. Setting a limit +/// protects your application from denial of service (DOS) attacks and from +/// resource exhaustion through high memory consumption. The limit can be +/// increased by setting the `limits.json` configuration parameter. For +/// instance, to increase the JSON limit to 5MiB for all environments, you may +/// add the following to your `Rocket.toml`: +/// +/// ```toml +/// [global.limits] +/// json = 5242880 +/// ``` #[derive(Debug)] pub struct JSON(pub T); diff --git a/contrib/src/msgpack.rs b/contrib/src/msgpack.rs index 05927c96..ce417bcc 100644 --- a/contrib/src/msgpack.rs +++ b/contrib/src/msgpack.rs @@ -17,6 +17,8 @@ pub use self::rmp_serde::decode::Error as MsgPackError; /// The `MsgPack` type: implements `FromData` and `Responder`, allowing you to /// easily consume and respond with MessagePack data. /// +/// ## Receiving MessagePack +/// /// If you're receiving MessagePack data, simply add a `data` parameter to your /// route arguments and ensure the type of the parameter is a `MsgPack`, /// where `T` is some type you'd like to parse from MessagePack. `T` must @@ -38,6 +40,8 @@ pub use self::rmp_serde::decode::Error as MsgPackError; /// `application/msgpack`, `application/x-msgpack`, `bin/msgpack`, or /// `bin/x-msgpack`. /// +/// ## Sending MessagePack +/// /// If you're responding with MessagePack data, return a `MsgPack` type, /// where `T` implements `Serialize` from /// [Serde](https://github.com/serde-rs/serde). The content type of the response @@ -51,6 +55,20 @@ pub use self::rmp_serde::decode::Error as MsgPackError; /// MsgPack(user_from_id) /// } /// ``` +/// +/// ## Incoming Data Limits +/// +/// The default size limit for incoming MessagePack data is 1MiB. Setting a +/// limit protects your application from denial of service (DOS) attacks and +/// from resource exhaustion through high memory consumption. The limit can be +/// increased by setting the `limits.msgpack` configuration parameter. For +/// instance, to increase the MessagePack limit to 5MiB for all environments, +/// you may add the following to your `Rocket.toml`: +/// +/// ```toml +/// [global.limits] +/// msgpack = 5242880 +/// ``` #[derive(Debug)] pub struct MsgPack(pub T); diff --git a/lib/src/config/mod.rs b/lib/src/config/mod.rs index e03798a2..866c6c17 100644 --- a/lib/src/config/mod.rs +++ b/lib/src/config/mod.rs @@ -44,9 +44,13 @@ //! characters) to use as the session key //! * example: `"8Xui8SN4mI+7egV/9dlfYYLGQJeEx4+DwmSQLwDVXJg="` //! * **tls**: _[table]_ a table with two keys: 1) `certs`: _[string]_ a path -//! to a certificate chain in PEM format, and 2) `key`: _[string]_ a path to a -//! private key file in PEM format for the certificate in `certs` +//! to a certificate chain in PEM format, and 2) `key`: _[string]_ a path to a +//! private key file in PEM format for the certificate in `certs` //! * example: `{ certs = "/path/to/certs.pem", key = "/path/to/key.pem" }` +//! * **limits**: _[table]_ a table where the key _[string]_ corresponds to a +//! data type and the value _[u64]_ corresponds to the maximum size in bytes +//! Rocket should accept for that type. +//! * example: `{ forms = 65536 }` (maximum form size to 64KiB) //! //! ### Rocket.toml //! @@ -68,6 +72,7 @@ //! workers = max(number_of_cpus, 2) //! log = "normal" //! session_key = [randomly generated at launch] +//! limits = { forms = 32768 } //! //! [staging] //! address = "0.0.0.0" @@ -75,6 +80,7 @@ //! workers = max(number_of_cpus, 2) //! log = "normal" //! session_key = [randomly generated at launch] +//! limits = { forms = 32768 } //! //! [production] //! address = "0.0.0.0" @@ -82,6 +88,7 @@ //! workers = max(number_of_cpus, 2) //! log = "critical" //! session_key = [randomly generated at launch] +//! limits = { forms = 32768 } //! ``` //! //! The `workers` and `session_key` default parameters are computed by Rocket diff --git a/lib/src/request/form/mod.rs b/lib/src/request/form/mod.rs index 0fd9da52..b075142f 100644 --- a/lib/src/request/form/mod.rs +++ b/lib/src/request/form/mod.rs @@ -148,16 +148,30 @@ use outcome::Outcome::*; /// /// ## Performance and Correctness Considerations /// -/// Whether you should use a `str` or `String` in your `FromForm` type depends -/// on your use case. The primary question to answer is: _Can the input contain -/// characters that must be URL encoded?_ Note that this includes commmon -/// characters such as spaces. If so, then you must use `String`, whose +/// Whether you should use a `&RawStr` or `String` in your `FromForm` type +/// depends on your use case. The primary question to answer is: _Can the input +/// contain characters that must be URL encoded?_ Note that this includes +/// commmon characters such as spaces. If so, then you must use `String`, whose /// `FromFormValue` implementation deserializes the URL encoded string for you. /// Because the `str` references will refer directly to the underlying form /// data, they will be raw and URL encoded. /// -/// If your string values will not contain URL encoded characters, using `str` -/// will result in fewer allocation and is thus spreferred. +/// If your string values will not contain URL encoded characters, using +/// `RawStr` will result in fewer allocation and is thus preferred. +/// +/// ## Incoming Data Limits +/// +/// The default size limit for incoming form data is 32KiB. Setting a limit +/// protects your application from denial of service (DOS) attacks and from +/// resource exhaustion through high memory consumption. The limit can be +/// increased by setting the `limits.forms` configuration parameter. For +/// instance, to increase the forms limit to 512KiB for all environments, you +/// may add the following to your `Rocket.toml`: +/// +/// ```toml +/// [global.limits] +/// forms = 524288 +/// ``` pub struct Form<'f, T: FromForm<'f> + 'f> { object: T, form_string: String,