Document size limits.

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<T>`, 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<T>` 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<T = Value>(pub T);
 

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<T>`,
 /// 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<T>` 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<T>(pub T);
 

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

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,