From b6b060f75c5e5b5a1c2b859d458ffaa3f844b29e Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Thu, 18 May 2023 18:22:40 -0700 Subject: [PATCH] Document built-in data guards. --- core/lib/src/data/from_data.rs | 141 +++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) diff --git a/core/lib/src/data/from_data.rs b/core/lib/src/data/from_data.rs index 2bc1aa47..2b7465c3 100644 --- a/core/lib/src/data/from_data.rs +++ b/core/lib/src/data/from_data.rs @@ -52,6 +52,147 @@ impl<'r, S, E> IntoOutcome, Status)> for Result /// matches, Rocket will call the `FromData` implementation for the type `T`. /// The handler will only be called if the guard returns successfully. /// +/// ## Build-In Guards +/// +/// Rocket provides implementations for `FromData` for many types. Their +/// behavior is documented here: +/// +/// * `Data`: Returns the untouched `Data`. +/// +/// - **Fails:** Never. +/// +/// - **Succeeds:** Always. +/// +/// - **Forwards:** Never. +/// +/// * Strings: `Cow`, `&str`, `&RawStr`, `String` +/// +/// _Limited by the `string` [data limit]._ +/// +/// Reads the body data into a string via [`DataStream::into_string()`]. +/// +/// - **Fails:** If the body data is not valid UTF-8 or on I/O errors while +/// reading. The error type is [`io::Error`]. +/// +/// - **Succeeds:** If the body data _is_ valid UTF-8. If the limit is +/// exceeded, the string is truncated to the limit. +/// +/// - **Forwards:** Never. +/// +/// * Bytes: `&[u8]`, `Vec` +/// +/// _Limited by the `bytes` [data limit]._ +/// +/// Reads the body data into a byte vector via [`DataStream::into_bytes()`]. +/// +/// - **Fails:** On I/O errors while reading. The error type is +/// [`io::Error`]. +/// +/// - **Succeeds:** As long as no I/O error occurs. If the limit is +/// exceeded, the slice is truncated to the limit. +/// +/// - **Forwards:** Never. +/// +/// * [`TempFile`](crate::fs::TempFile) +/// +/// _Limited by the `file` and/or `file/$ext` [data limit]._ +/// +/// Streams the body data directly into a temporary file. The data is never +/// buffered in memory. +/// +/// - **Fails:** On I/O errors while reading data or creating the temporary +/// file. The error type is [`io::Error`]. +/// +/// - **Succeeds:** As long as no I/O error occurs and the temporary file +/// could be created. If the limit is exceeded, only data up to the limit is +/// read and subsequently written. +/// +/// - **Forwards:** Never. +/// +/// * Deserializers: [`Json`], [`MsgPack`] +/// +/// _Limited by the `json`, `msgpack` [data limit], respectively._ +/// +/// Reads up to the configured limit and deserializes the read data into `T` +/// using the respective format's parser. +/// +/// - **Fails:** On I/O errors while reading the data, or if the data fails +/// to parse as a `T` according to the deserializer. The error type for +/// `Json` is [`json::Error`](crate::serde::json::Error) and the error type +/// for `MsgPack` is [`msgpack::Error`](crate::serde::msgpack::Error). +/// +/// - **Succeeds:** As long as no I/O error occurs and the (limited) body +/// data was successfully deserialized as a `T`. +/// +/// - **Forwards:** Never. +/// +/// * Forms: [`Form`] +/// +/// _Limited by the `form` or `data-form` [data limit]._ +/// +/// Parses the incoming data stream into fields according to Rocket's [field +/// wire format], pushes each field to `T`'s [`FromForm`] [push parser], and +/// finalizes the form. Parsing is done on the stream without reading the +/// data into memory. If the request has as a [`ContentType::Form`], the +/// `form` limit is applied, otherwise if the request has a +/// [`ContentType::FormData`], the `data-form` limit is applied. +/// +/// - **Fails:** On I/O errors while reading the data, or if the data fails +/// to parse as a `T` according to its `FromForm` implementation. The errors +/// are collected into an [`Errors`](crate::form::Errors), the error type. +/// +/// - **Succeeds:** As long as no I/O error occurs and the (limited) body +/// data was successfully parsed as a `T`. +/// +/// - **Forwards:** If the request's `Content-Type` is neither +/// [`ContentType::Form`] nor [`ContentType::FormData`]. +/// +/// * `Option` +/// +/// Forwards to `T`'s `FromData` implementation, capturing the outcome. +/// +/// - **Fails:** Never. +/// +/// - **Succeeds:** Always. If `T`'s `FromData` implementation succeeds, the +/// parsed value is returned in `Some`. If its implementation forwards or +/// fails, `None` is returned. +/// +/// - **Forwards:** Never. +/// +/// * `Result` +/// +/// Forwards to `T`'s `FromData` implementation, capturing the outcome. +/// +/// - **Fails:** Never. +/// +/// - **Succeeds:** If `T`'s `FromData` implementation succeeds or fails. If +/// it succeeds, the value is returned in `Ok`. If it fails, the error value +/// is returned in `Err`. +/// +/// - **Forwards:** If `T`'s implementation forwards. +/// +/// * [`Capped`] +/// +/// Forwards to `T`'s `FromData` implementation, recording whether the data +/// was truncated (a.k.a. capped) due to `T`'s limit being exceeded. +/// +/// - **Fails:** If `T`'s implementation fails. +/// - **Succeeds:** If `T`'s implementation succeeds. +/// - **Forwards:** If `T`'s implementation forwards. +/// +/// [data limit]: crate::data::Limits#built-in-limits +/// [`DataStream::into_string()`]: crate::data::DataStream::into_string() +/// [`DataStream::into_bytes()`]: crate::data::DataStream::into_bytes() +/// [`io::Error`]: std::io::Error +/// [`Json`]: crate::serde::json::Json +/// [`MsgPack`]: crate::serde::msgpack::MsgPack +/// [`Form`]: crate::form::Form +/// [field wire format]: crate::form#field-wire-format +/// [`FromForm`]: crate::form::FromForm +/// [push parser]: crate::form::FromForm#push-parsing +/// [`ContentType::Form`]: crate::http::ContentType::Form +/// [`ContentType::FormData`]: crate::http::ContentType::FormData +/// /// ## Async Trait /// /// [`FromData`] is an _async_ trait. Implementations of `FromData` must be