rwf2
/
Rocket
mirror of https://github.com/rwf2/Rocket.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Use inter/intra-crate links in all documentation.

This commit is contained in:
Sergio Benitez 2018-10-06 06:25:17 -07:00
parent 2839aca8ce
commit 28f2a33abd
51 changed files with 484 additions and 544 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
contrib/lib/src/databases.rs
View File

@ -26,9 +26,6 @@
//! support can be easily extended by implementing the [`Poolable`] trait. See //! support can be easily extended by implementing the [`Poolable`] trait. See
//! [Extending](#extending) for more. //! [Extending](#extending) for more.
//! //!
//! [`r2d2`]: https://crates.io/crates/r2d2
//! [request guards]: [rocket::FromRequest]
//!
//! ## Example //! ## Example
//! //!
//! Before using this library, the feature corresponding to your database type //! Before using this library, the feature corresponding to your database type
@ -204,8 +201,6 @@
//! generates an implementation of the [`Deref`](::std::ops::Deref) trait with //! generates an implementation of the [`Deref`](::std::ops::Deref) trait with
//! the internal `Poolable` type as the target. //! the internal `Poolable` type as the target.
//! //!
//! [`FromRequest`]: /rocket/request/trait.FromRequest.html
//!
//! The macro will also generate two inherent methods on the decorated type: //! The macro will also generate two inherent methods on the decorated type:
//! //!
//! * `fn fairing() -> impl Fairing` //! * `fn fairing() -> impl Fairing`
@ -316,14 +311,14 @@
//! The list below includes all presently supported database adapters and their //! The list below includes all presently supported database adapters and their
//! corresponding [`Poolable`] type. //! corresponding [`Poolable`] type.
//! //!
//! | Kind | Driver | [`Poolable`] Type | Feature | //! | Kind | Driver | `Poolable` Type | Feature |
//! |----------|-----------------------|--------------------------------|------------------------| //! |----------|-----------------------|--------------------------------|------------------------|
//! | MySQL | [Diesel] | [`diesel::MysqlConnection`] | `diesel_mysql_pool` | //! | MySQL | [Diesel] | [`diesel::MysqlConnection`] | `diesel_mysql_pool` |
//! | MySQL | [`rust-mysql-simple`] | [`mysql::conn`] | `mysql_pool` | //! | MySQL | [`rust-mysql-simple`] | [`mysql::Conn`] | `mysql_pool` |
//! | Postgres | [Diesel] | [`diesel::PgConnection`] | `diesel_postgres_pool` | //! | Postgres | [Diesel] | [`diesel::PgConnection`] | `diesel_postgres_pool` |
//! | Postgres | [Rust-Postgres] | [`postgres::Connection`] | `postgres_pool` | //! | Postgres | [Rust-Postgres] | [`postgres::Connection`] | `postgres_pool` |
//! | Sqlite | [Diesel] | [`diesel::SqliteConnection`] | `diesel_sqlite_pool` | //! | Sqlite | [Diesel] | [`diesel::SqliteConnection`] | `diesel_sqlite_pool` |
//! | Sqlite | [`Rustqlite`] | [`rusqlite::Connection`] | `sqlite_pool` | //! | Sqlite | [Rustqlite] | [`rusqlite::Connection`] | `sqlite_pool` |
//! | Neo4j | [`rusted_cypher`] | [`rusted_cypher::GraphClient`] | `cypher_pool` | //! | Neo4j | [`rusted_cypher`] | [`rusted_cypher::GraphClient`] | `cypher_pool` |
//! | Redis | [`redis-rs`] | [`redis::Connection`] | `redis_pool` | //! | Redis | [`redis-rs`] | [`redis::Connection`] | `redis_pool` |
//! //!
@ -338,7 +333,7 @@
//! [`diesel::MysqlConnection`]: http://docs.diesel.rs/diesel/mysql/struct.MysqlConnection.html //! [`diesel::MysqlConnection`]: http://docs.diesel.rs/diesel/mysql/struct.MysqlConnection.html
//! [`redis-rs`]: https://github.com/mitsuhiko/redis-rs //! [`redis-rs`]: https://github.com/mitsuhiko/redis-rs
//! [`rusted_cypher`]: https://github.com/livioribeiro/rusted-cypher //! [`rusted_cypher`]: https://github.com/livioribeiro/rusted-cypher
//! [`Rustqlite`]: https://github.com/jgallagher/rusqlite //! [Rustqlite]: https://github.com/jgallagher/rusqlite
//! [Rust-Postgres]: https://github.com/sfackler/rust-postgres //! [Rust-Postgres]: https://github.com/sfackler/rust-postgres
//! [`rust-mysql-simple`]: https://github.com/blackbeam/rust-mysql-simple //! [`rust-mysql-simple`]: https://github.com/blackbeam/rust-mysql-simple
//! [`diesel::PgConnection`]: http://docs.diesel.rs/diesel/pg/struct.PgConnection.html //! [`diesel::PgConnection`]: http://docs.diesel.rs/diesel/pg/struct.PgConnection.html
@ -355,6 +350,10 @@
//! database-like struct that can be pooled by `r2d2`) is as easy as //! database-like struct that can be pooled by `r2d2`) is as easy as
//! implementing the [`Poolable`] trait. See the documentation for [`Poolable`] //! implementing the [`Poolable`] trait. See the documentation for [`Poolable`]
//! for more details on how to implement it. //! for more details on how to implement it.
//!
//! [`FromRequest`]: rocket::FromRequest
//! [request guards]: rocket::FromRequest
//! [`Poolable`]: databases::Poolable
pub extern crate r2d2; pub extern crate r2d2;
@ -455,7 +454,7 @@ pub enum DatabaseConfigError {
/// configuration. /// configuration.
MissingKey, MissingKey,
/// The configuration associated with the key isn't a /// The configuration associated with the key isn't a
/// [Table](/rocket/config/type.Table.html). /// [Table](::rocket::config::Table).
MalformedConfiguration, MalformedConfiguration,
/// The required `url` key is missing. /// The required `url` key is missing.
MissingUrl, MissingUrl,
@ -612,9 +611,6 @@ impl<'a> Display for DatabaseConfigError {
/// `foo::ConnectionManager` /// `foo::ConnectionManager`
/// * `foo::Error`, errors resulting from manager instantiation /// * `foo::Error`, errors resulting from manager instantiation
/// ///
/// [`r2d2`]: https://crates.io/crates/r2d2
/// [`r2d2::ManageConnection`]: http://docs.rs/r2d2/0.8/r2d2/trait.ManageConnection.html
///
/// In order for Rocket to generate the required code to automatically provision /// In order for Rocket to generate the required code to automatically provision
/// a r2d2 connection pool into application state, the `Poolable` trait needs to /// a r2d2 connection pool into application state, the `Poolable` trait needs to
/// be implemented for the connection type. The following example implements /// be implemented for the connection type. The following example implements
@ -622,10 +618,9 @@ impl<'a> Display for DatabaseConfigError {
/// ///
/// ```rust /// ```rust
/// use rocket_contrib::databases::{r2d2, DbError, DatabaseConfig, Poolable}; /// use rocket_contrib::databases::{r2d2, DbError, DatabaseConfig, Poolable};
///
/// # mod foo { /// # mod foo {
/// # use rocket_contrib::databases::r2d2;
/// # use std::fmt; /// # use std::fmt;
/// # use rocket_contrib::databases::r2d2;
/// # #[derive(Debug)] pub struct Error; /// # #[derive(Debug)] pub struct Error;
/// # impl ::std::error::Error for Error { } /// # impl ::std::error::Error for Error { }
/// # impl fmt::Display for Error { /// # impl fmt::Display for Error {
@ -637,6 +632,10 @@ impl<'a> Display for DatabaseConfigError {
/// # /// #
/// # type Result<T> = ::std::result::Result<T, Error>; /// # type Result<T> = ::std::result::Result<T, Error>;
/// # /// #
/// # impl ConnectionManager {
/// # pub fn new(url: &str) -> Result<Self> { Err(Error) }
/// # }
/// #
/// # impl self::r2d2::ManageConnection for ConnectionManager { /// # impl self::r2d2::ManageConnection for ConnectionManager {
/// # type Connection = Connection; /// # type Connection = Connection;
/// # type Error = Error; /// # type Error = Error;
@ -651,7 +650,6 @@ impl<'a> Display for DatabaseConfigError {
/// type Error = DbError<foo::Error>; /// type Error = DbError<foo::Error>;
/// ///
/// fn pool(config: DatabaseConfig) -> Result<r2d2::Pool<Self::Manager>, Self::Error> { /// fn pool(config: DatabaseConfig) -> Result<r2d2::Pool<Self::Manager>, Self::Error> {
/// # let _ = config; /*
/// let manager = foo::ConnectionManager::new(config.url) /// let manager = foo::ConnectionManager::new(config.url)
/// .map_err(DbError::Custom)?; /// .map_err(DbError::Custom)?;
/// ///
@ -659,8 +657,6 @@ impl<'a> Display for DatabaseConfigError {
/// .max_size(config.pool_size) /// .max_size(config.pool_size)
/// .build(manager) /// .build(manager)
/// .map_err(DbError::PoolError) /// .map_err(DbError::PoolError)
/// # */
/// # Err(DbError::Custom(foo::Error))
/// } /// }
/// } /// }
/// ``` /// ```

32
contrib/lib/src/json.rs
View File

@ -164,8 +164,8 @@ impl<T> DerefMut for Json<T> {
/// this type implements [`Responder`], allowing a value of this type to be /// this type implements [`Responder`], allowing a value of this type to be
/// returned directly from a handler. /// returned directly from a handler.
/// ///
/// [`Value`]: https://docs.rs/serde_json/1.0.2/serde_json/value/enum.Value.html /// [`Value`]: serde_json::value
/// [`Responder`]: /rocket/response/trait.Responder.html /// [`Responder`]: rocket::response::Responder
/// ///
/// # `Responder` /// # `Responder`
/// ///
@ -175,16 +175,18 @@ impl<T> DerefMut for Json<T> {
/// ///
/// # Usage /// # Usage
/// ///
/// A value of this type is constructed via the /// A value of this type is constructed via the [`json!`](json) macro. The macro
/// [`json!`](/rocket_contrib/macro.json.html) macro. The macro and this type /// and this type are typically used to construct JSON values in an ad-hoc
/// are typically used to construct JSON values in an ad-hoc fashion during /// fashion during request handling. This looks something like:
/// request handling. This looks something like:
/// ///
/// ```rust,ignore /// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro)]
/// # #[macro_use] extern crate rocket;
/// # #[macro_use] extern crate rocket_contrib;
/// use rocket_contrib::JsonValue; /// use rocket_contrib::JsonValue;
/// ///
/// #[get("/item")] /// #[get("/json")]
/// fn get_item() -> JsonValue { /// fn get_json() -> JsonValue {
/// json!({ /// json!({
/// "id": 83, /// "id": 83,
/// "values": [1, 2, 3, 4] /// "values": [1, 2, 3, 4]
@ -259,15 +261,17 @@ impl<'a> Responder<'a> for JsonValue {
/// To import the macro, add the `#[macro_use]` attribute to the `extern crate /// To import the macro, add the `#[macro_use]` attribute to the `extern crate
/// rocket_contrib` invocation: /// rocket_contrib` invocation:
/// ///
/// ```rust,ignore /// ```rust
/// #[macro_use] extern crate rocket_contrib; /// #[macro_use] extern crate rocket_contrib;
/// ``` /// ```
/// ///
/// The return type of a `json!` invocation is /// The return type of a `json!` invocation is [`JsonValue`]. A value created
/// [`JsonValue`](/rocket_contrib/struct.JsonValue.html). A value created with /// with this macro can be returned from a handler as follows:
/// this macro can be returned from a handler as follows:
/// ///
/// ```rust,ignore /// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro)]
/// # #[macro_use] extern crate rocket;
/// # #[macro_use] extern crate rocket_contrib;
/// use rocket_contrib::JsonValue; /// use rocket_contrib::JsonValue;
/// ///
/// #[get("/json")] /// #[get("/json")]

18
contrib/lib/src/lib.rs
View File

@ -10,28 +10,26 @@
//! //!
//! These libraries are always kept in-sync with the core Rocket library. They //! These libraries are always kept in-sync with the core Rocket library. They
//! provide common, but not fundamental, abstractions to be used by Rocket //! provide common, but not fundamental, abstractions to be used by Rocket
//! applications. In particular, contributor libraries typically export types //! applications.
//! implementing a combination of the `FromRequest`, `FromParam`, and
//! `Responder` traits.
//! //!
//! Each module in this library is held behind a feature flag, with the most //! Each module in this library is held behind a feature flag, with the most
//! common modules exposed by default. The present feature list is below, with //! common modules exposed by default. The present feature list is below, with
//! an asterisk next to the features that are enabled by default: //! an asterisk next to the features that are enabled by default:
//! //!
//! * [json*](struct.Json.html) //! * [json*](Json)
//! * [static_files*](static_files) //! * [static_files*](static_files)
//! * [msgpack](struct.MsgPack.html) //! * [msgpack](MsgPack)
//! * [handlebars_templates](struct.Template.html) //! * [handlebars_templates](Template)
//! * [tera_templates](struct.Template.html) //! * [tera_templates](Template)
//! * [uuid](struct.Uuid.html) //! * [uuid](Uuid)
//! * [${database}_pool](databases/index.html) //! * [${database}_pool](databases)
//! //!
//! The recommend way to include features from this crate via Cargo in your //! The recommend way to include features from this crate via Cargo in your
//! project is by adding a `[dependencies.rocket_contrib]` section to your //! project is by adding a `[dependencies.rocket_contrib]` section to your
//! `Cargo.toml` file, setting `default-features` to false, and specifying //! `Cargo.toml` file, setting `default-features` to false, and specifying
//! features manually. For example, to use the JSON module, you would add: //! features manually. For example, to use the JSON module, you would add:
//! //!
//! ```toml,ignore //! ```toml
//! [dependencies.rocket_contrib] //! [dependencies.rocket_contrib]
//! version = "*" //! version = "*"
//! default-features = false //! default-features = false

9
contrib/lib/src/templates/engine.rs
View File

@ -40,8 +40,8 @@ pub trait Engine: Send + Sync + 'static {
/// }); /// });
/// ``` /// ```
/// ///
/// [`tera::Value`]: https://docs.rs/tera/0.10.10/tera/enum.Value.html /// [`tera::Value`]: ::tera::Value
/// [`tera::Result`]: https://docs.rs/tera/0.10.10/tera/type.Result.html /// [`tera::Result`]: ::tera::Result
pub struct Engines { pub struct Engines {
#[cfg(feature = "tera_templates")] #[cfg(feature = "tera_templates")]
/// A [`Tera`] structure. This field is only available when the /// A [`Tera`] structure. This field is only available when the
@ -49,15 +49,14 @@ pub struct Engines {
/// instance, ensure you use types imported from `rocket_contrib::tera` to /// instance, ensure you use types imported from `rocket_contrib::tera` to
/// avoid version mismatches. /// avoid version mismatches.
/// ///
/// [`Tera`]: https://docs.rs/tera/0.10.10/tera/struct.Tera.html /// [`Tera`]: tera::Tera
pub tera: Tera, pub tera: Tera,
/// A [`Handlebars`] structure. This field is only available when the /// A [`Handlebars`] structure. This field is only available when the
/// `handlebars_templates` feature is enabled. When calling methods on the /// `handlebars_templates` feature is enabled. When calling methods on the
/// `Tera` instance, ensure you use types /// `Tera` instance, ensure you use types
/// imported from `rocket_contrib::handlebars` to avoid version mismatches. /// imported from `rocket_contrib::handlebars` to avoid version mismatches.
/// ///
/// [`Handlebars`]: /// [`Handlebars`]: handlebars::Handlebars
/// https://docs.rs/handlebars/0.29.1/handlebars/struct.Handlebars.html
#[cfg(feature = "handlebars_templates")] #[cfg(feature = "handlebars_templates")]
pub handlebars: Handlebars, pub handlebars: Handlebars,
} }

8
contrib/lib/src/templates/metadata.rs
View File

@ -4,13 +4,13 @@ use rocket::request::{self, FromRequest};
use super::ContextManager; use super::ContextManager;
/// The `TemplateMetadata` type: implements `FromRequest`, allowing dynamic /// Implements [`FromRequest`] for dynamiclly querying template metadata.
/// queries about template metadata.
/// ///
/// # Usage /// # Usage
/// ///
/// First, ensure that the template [fairing](`rocket::fairing`), /// First, ensure that the template [fairing](rocket::fairing),
/// [`Template::fairing()`] is attached to your Rocket application: /// [`Template::fairing()`](::Template::fairing()) is attached to your Rocket
/// application:
/// ///
/// ```rust /// ```rust
/// # extern crate rocket; /// # extern crate rocket;

24
contrib/lib/src/templates/mod.rs
View File

@ -69,14 +69,13 @@ const DEFAULT_TEMPLATE_DIR: &str = "templates";
/// Template discovery is actualized by the template fairing, which itself is /// Template discovery is actualized by the template fairing, which itself is
/// created via the [`Template::fairing()`] or [`Template::custom()`] method. In /// created via the [`Template::fairing()`] or [`Template::custom()`] method. In
/// order for _any_ templates to be rendered, the template fairing _must_ be /// order for _any_ templates to be rendered, the template fairing _must_ be
/// [attached](/rocket/struct.Rocket.html#method.attach) to the running Rocket /// [attached](rocket::Rocket::attach()) to the running Rocket instance. Failure
/// instance. Failure to do so will result in an error. /// to do so will result in an error.
/// ///
/// Templates are rendered with the `render` method. The method takes in the /// Templates are rendered with the `render` method. The method takes in the
/// name of a template and a context to render the template with. The context /// name of a template and a context to render the template with. The context
/// can be any type that implements `Serialize` from /// can be any type that implements [`Serialize`] from [`serde`] and would
/// [Serde](https://github.com/serde-rs/json) and would serialize to an `Object` /// serialize to an `Object` value.
/// value.
/// ///
/// In debug mode (without the `--release` flag passed to `cargo`), templates /// In debug mode (without the `--release` flag passed to `cargo`), templates
/// will be automatically reloaded from disk if any changes have been made to /// will be automatically reloaded from disk if any changes have been made to
@ -89,15 +88,15 @@ const DEFAULT_TEMPLATE_DIR: &str = "templates";
/// feature, or both, to the `rocket_contrib` dependencies section of your /// feature, or both, to the `rocket_contrib` dependencies section of your
/// `Cargo.toml`: /// `Cargo.toml`:
/// ///
/// ```toml,ignore /// ```toml
/// [dependencies.rocket_contrib] /// [dependencies.rocket_contrib]
/// version = "*" /// version = "*"
/// default-features = false /// default-features = false
/// features = ["handlebars_templates", "tera_templates"] /// features = ["handlebars_templates", "tera_templates"]
/// ``` /// ```
/// ///
/// Then, ensure that the template [fairing](/rocket/fairing/) is attached to /// Then, ensure that the template [`Fairing`] is attached to your Rocket
/// your Rocket application: /// application:
/// ///
/// ```rust /// ```rust
/// extern crate rocket; /// extern crate rocket;
@ -114,7 +113,7 @@ const DEFAULT_TEMPLATE_DIR: &str = "templates";
/// } /// }
/// ``` /// ```
/// ///
/// The `Template` type implements Rocket's `Responder` trait, so it can be /// The `Template` type implements Rocket's [`Responder`] trait, so it can be
/// returned from a request handler directly: /// returned from a request handler directly:
/// ///
/// ```rust,ignore /// ```rust,ignore
@ -130,9 +129,6 @@ const DEFAULT_TEMPLATE_DIR: &str = "templates";
/// You can use the [`Template::custom()`] method to construct a fairing with /// You can use the [`Template::custom()`] method to construct a fairing with
/// customized templating engines. Among other things, this method allows you to /// customized templating engines. Among other things, this method allows you to
/// register template helpers and register templates from strings. /// register template helpers and register templates from strings.
///
/// [`Template::custom()`]: /rocket_contrib/struct.Template.html#method.custom
/// [`Template::fairing()`]: /rocket_contrib/struct.Template.html#method.fairing
#[derive(Debug)] #[derive(Debug)]
pub struct Template { pub struct Template {
name: Cow<'static, str>, name: Cow<'static, str>,
@ -161,8 +157,6 @@ impl Template {
/// If you wish to customize the internal templating engines, use /// If you wish to customize the internal templating engines, use
/// [`Template::custom()`] instead. /// [`Template::custom()`] instead.
/// ///
/// [`Template::custom()`]: /rocket_contrib/struct.Template.html#method.custom
///
/// # Example /// # Example
/// ///
/// To attach this fairing, simple call `attach` on the application's /// To attach this fairing, simple call `attach` on the application's
@ -192,8 +186,6 @@ impl Template {
/// templating engines via the parameter `f`. Note that only the enabled /// templating engines via the parameter `f`. Note that only the enabled
/// templating engines will be accessible from the `Engines` type. /// templating engines will be accessible from the `Engines` type.
/// ///
/// [`Template::fairing()`]: /rocket_contrib/struct.Template.html#method.fairing
///
/// # Example /// # Example
/// ///
/// ```rust /// ```rust

4
contrib/lib/src/uuid.rs
View File

@ -9,8 +9,8 @@ use rocket::http::RawStr;
pub use self::uuid_ext::parser::ParseError as UuidParseError; pub use self::uuid_ext::parser::ParseError as UuidParseError;
/// Implements `FromParam` and `FormFormValue` for accepting UUID values from /// Implements [`FromParam`] and [`FromFormValue`] for accepting UUID values
/// the [uuid](https://github.com/rust-lang-nursery/uuid) crate. /// from the [`uuid`] crate.
/// ///
/// # Usage /// # Usage
/// ///

16
core/codegen_next/src/lib.rs
View File

@ -149,8 +149,8 @@
//! field name is expected. In this case, the `field` name in the attribute is //! field name is expected. In this case, the `field` name in the attribute is
//! used instead of the structure's actual field name when parsing a form. //! used instead of the structure's actual field name when parsing a form.
//! //!
//! [`FromForm`]: /rocket/request/trait.FromForm.html //! [`FromForm`]: rocket::request::FromForm
//! [`FromFormValue`]: /rocket/request/trait.FromFormValue.html //! [`FromFormValue`]: rocket::request::FromFormValue
//! //!
//! ### `FromFormValue` //! ### `FromFormValue`
//! //!
@ -306,9 +306,9 @@
//! The [`Response`] produced from the generated implementation will have its //! The [`Response`] produced from the generated implementation will have its
//! content-type overriden to this value. //! content-type overriden to this value.
//! //!
//! [`Responder`]: /rocket/response/trait.Responder.html //! [`Responder`]: rocket::response::Responder
//! [`Response`]: /rocket/struct.Response.html //! [`Response`]: rocket::Response
//! [`Response::set_header()`]: /rocket/struct.Response.html#method.set_header //! [`Response::set_header()`]: rocket::Response::set_header()
//! //!
//! ## Procedural Macros //! ## Procedural Macros
//! //!
@ -404,9 +404,9 @@
//! If a mount-point is provided, the mount-point is prepended to the route's //! If a mount-point is provided, the mount-point is prepended to the route's
//! URI. //! URI.
//! //!
//! [`Uri`]: /rocket/http/uri/struct.URI.html //! [`Uri`]: http::uri::URI
//! [`FromUriParam`]: /rocket/http/uri/trait.FromUriParam.html //! [`FromUriParam`]: http::uri::FromUriParam
//! [`UriDisplay`]: /rocket/http/uri/trait.UriDisplay.html //! [`UriDisplay`]: http::uri::UriDisplay
//! //!
//! # Debugging Codegen //! # Debugging Codegen
//! //!

15
core/http/src/accept.rs
View File

@ -120,19 +120,18 @@ impl PartialEq for AcceptParams {
/// The HTTP Accept header. /// The HTTP Accept header.
/// ///
/// An `Accept` header is composed of zero or more media types, each of which /// An `Accept` header is composed of zero or more media types, each of which
/// may have an optional quality value (a [`QMediaType`]). The header is sent by an HTTP client to /// may have an optional quality value (a [`QMediaType`]). The header is sent by
/// describe the formats it accepts as well as the order in which it prefers /// an HTTP client to describe the formats it accepts as well as the order in
/// different formats. /// which it prefers different formats.
/// ///
/// # Usage /// # Usage
/// ///
/// The Accept header of an incoming request can be retrieved via the /// The Accept header of an incoming request can be retrieved via the
/// [`Request::accept`] method. The [`preferred`] method can be used to retrieve /// [`Request::accept()`] method. The [`preferred()`] method can be used to
/// the client's preferred media type. /// retrieve the client's preferred media type.
/// ///
/// [`Request::accept`]: /rocket/struct.Request.html#method.accept /// [`Request::accept`]: ::rocket::Request::accept()
/// [`preferred`]: /rocket/http/struct.Accept.html#method.preferred /// [`preferred()`]: Accept::preferred()
/// [`QMediaType`]: /rocket/http/struct.QMediaType.html
/// ///
/// An `Accept` type with a single, common media type can be easily constructed /// An `Accept` type with a single, common media type can be easily constructed
/// via provided associated constants. /// via provided associated constants.

28
core/http/src/cookies.rs
View File

@ -16,18 +16,18 @@ use Header;
/// # Usage /// # Usage
/// ///
/// A type of `Cookies` can be retrieved via its `FromRequest` implementation as /// A type of `Cookies` can be retrieved via its `FromRequest` implementation as
/// a request guard or via the [`Request::cookies`] method. Individual cookies /// a request guard or via the [`Request::cookies()`] method. Individual cookies
/// can be retrieved via the [`get`] and [`get_private`] methods. Cookies can be /// can be retrieved via the [`get()`] and [`get_private()`] methods. Cookies
/// added or removed via the [`add`], [`add_private`], [`remove`], and /// can be added or removed via the [`add()`], [`add_private()`], [`remove()`],
/// [`remove_private`] methods. /// and [`remove_private()`] methods.
/// ///
/// [`get`]: /rocket/http/enum.Cookies.html#method.get /// [`Request::cookies()`]: ::rocket::Request::cookies()
/// [`get_private`]: /rocket/http/enum.Cookies.html#method.get_private /// [`get()`]: #method.get
/// [`add`]: /rocket/http/enum.Cookies.html#method.add /// [`get_private()`]: #method.get_private
/// [`add_private`]: /rocket/http/enum.Cookies.html#method.add_private /// [`add()`]: #method.add
/// [`remove`]: /rocket/http/enum.Cookies.html#method.remove /// [`add_private()`]: #method.add_private
/// [`remove_private`]: /rocket/http/enum.Cookies.html#method.remove_private /// [`remove()`]: #method.remove
/// [`Request::cookies`]: /rocket/struct.Request.html#method.cookies /// [`remove_private()`]: #method.remove_private
/// ///
/// ## Examples /// ## Examples
/// ///
@ -52,7 +52,7 @@ use Header;
/// as an integer, a `User` structure is validated. Otherwise, the guard /// as an integer, a `User` structure is validated. Otherwise, the guard
/// forwards. /// forwards.
/// ///
/// [private cookie]: /rocket/http/enum.Cookies.html#private-cookies /// [private cookie]: Cookies::add_private()
/// ///
/// ```rust /// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro, never_type)] /// # #![feature(proc_macro_hygiene, decl_macro, never_type)]
@ -89,8 +89,8 @@ use Header;
/// being signed and encrypted. /// being signed and encrypted.
/// ///
/// Private cookies can be retrieved, added, and removed from a `Cookies` /// Private cookies can be retrieved, added, and removed from a `Cookies`
/// collection via the [`get_private`], [`add_private`], and [`remove_private`] /// collection via the [`get_private()`], [`add_private()`], and
/// methods. /// [`remove_private()`] methods.
/// ///
/// ## Encryption Key /// ## Encryption Key
/// ///

5
core/http/src/header.rs
View File

@ -17,9 +17,8 @@ pub struct Header<'h> {
impl<'h> Header<'h> { impl<'h> Header<'h> {
/// Constructs a new header. This method should be used rarely and only for /// Constructs a new header. This method should be used rarely and only for
/// non-standard headers. Instead, prefer to use the `Into<Header>` /// non-standard headers. Instead, prefer to use the `Into<Header>`
/// implementations of many types, including /// implementations of many types, including [`ContentType`] and all of the
/// [ContentType](struct.ContentType.html) and all of the headers in /// headers in [`http::hyper::header`](hyper::header).
/// [http::hyper::header](hyper/header/index.html).
/// ///
/// # Examples /// # Examples
/// ///

6
core/http/src/lib.rs
View File

@ -8,9 +8,9 @@
//! //!
//! This module exports types that map to HTTP concepts or to the underlying //! This module exports types that map to HTTP concepts or to the underlying
//! HTTP library when needed. Because the underlying HTTP library is likely to //! HTTP library when needed. Because the underlying HTTP library is likely to
//! change (see <a //! change (see [#17]), types in [`hyper`] should be considered unstable.
//! href="https://github.com/SergioBenitez/Rocket/issues/17">#17</a>), types in //!
//! [hyper](hyper/index.html) should be considered unstable. //! [#17]: https://github.com/SergioBenitez/Rocket/issues/17
#[macro_use] #[macro_use]
extern crate pear; extern crate pear;

19
core/http/src/media_type.rs
View File

@ -62,19 +62,14 @@ impl Source {
/// A `MediaType` should rarely be used directly. Instead, one is typically used /// A `MediaType` should rarely be used directly. Instead, one is typically used
/// indirectly via types like [`Accept`] and [`ContentType`], which internally /// indirectly via types like [`Accept`] and [`ContentType`], which internally
/// contain `MediaType`s. Nonetheless, a `MediaType` can be created via the /// contain `MediaType`s. Nonetheless, a `MediaType` can be created via the
/// [`new`], [`with_params`], and [`from_extension`] methods. The preferred /// [`MediaType::new()`], [`MediaType::with_params()`], and
/// method, however, is to create a `MediaType` via an associated constant. /// [`MediaType::from_extension`()] methods. The preferred method, however, is
/// /// to create a `MediaType` via an associated constant.
/// [`Accept`]: /rocket/http/struct.Accept.html
/// [`ContentType`]: /rocket/http/struct.ContentType.html
/// [`new`]: /rocket/http/struct.MediaType.html#method.new
/// [`with_params`]: /rocket/http/struct.MediaType.html#method.with_params
/// [`from_extension`]: /rocket/http/struct.MediaType.html#method.from_extension
/// ///
/// ## Example /// ## Example
/// ///
/// A media type of `application/json` can be instantiated via the `JSON` /// A media type of `application/json` can be instantiated via the
/// constant: /// [`MediaType::JSON`] constant:
/// ///
/// ```rust /// ```rust
/// # extern crate rocket; /// # extern crate rocket;
@ -96,9 +91,7 @@ impl Source {
/// typically the comparison that is desired. /// typically the comparison that is desired.
/// ///
/// If an exact comparison is desired that takes into account parameters, the /// If an exact comparison is desired that takes into account parameters, the
/// [`exact_eq`] method can be used. /// [`exact_eq()`](MediaType::exact_eq()) method can be used.
///
/// [`exact_eq`]: /rocket/http/struct.MediaType.html#method.exact_eq
#[derive(Debug, Clone)] #[derive(Debug, Clone)]
pub struct MediaType { pub struct MediaType {
/// Storage for the entire media type string. /// Storage for the entire media type string.

37
core/http/src/raw_str.rs
View File

@ -19,21 +19,26 @@ use uncased::UncasedStr;
/// An `&RawStr` should be converted into one of the validated string input /// An `&RawStr` should be converted into one of the validated string input
/// types through methods on `RawStr`. These methods are summarized below: /// types through methods on `RawStr`. These methods are summarized below:
/// ///
/// * **[`url_decode`]** - used to decode a raw string in a form value context /// * **[`url_decode()`]** - used to decode a raw string in a form value
/// * **[`percent_decode`], [`percent_decode_lossy`]** - used to /// context
/// percent-decode a raw string, typically in a URL context /// * **[`percent_decode()`], [`percent_decode_lossy()`]** - used to
/// * **[`html_escape`]** - used to decode a string for use in HTML templates /// percent-decode a raw string, typically in a URL context
/// * **[`as_str`]** - used when the `RawStr` is known to be safe in the /// * **[`html_escape()`]** - used to decode a string for use in HTML
/// context of its intended use. Use sparingly and with care! /// templates
/// * **[`as_uncased_str`]** - used when the `RawStr` is known to be safe in /// * **[`as_str()`]** - used when the `RawStr` is known to be safe in the
/// the context of its intended, uncased use /// context of its intended use. Use sparingly and with care!
/// * **[`as_uncased_str()`]** - used when the `RawStr` is known to be safe in
/// the context of its intended, uncased use
/// ///
/// [`as_str`]: /rocket/http/struct.RawStr.html#method.as_str /// **Note:** Template engines like Tera and Handlebars all functions like
/// [`as_uncased_str`]: /rocket/http/struct.RawStr.html#method.as_uncased_str /// [`html_escape()`] on all rendered template outputs by default.
/// [`url_decode`]: /rocket/http/struct.RawStr.html#method.url_decode ///
/// [`html_escape`]: /rocket/http/struct.RawStr.html#method.html_escape /// [`as_str()`]: RawStr::as_str()
/// [`percent_decode`]: /rocket/http/struct.RawStr.html#method.percent_decode /// [`as_uncased_str()`]: RawStr::as_uncased_str()
/// [`percent_decode_lossy`]: /rocket/http/struct.RawStr.html#method.percent_decode_lossy /// [`url_decode()`]: RawStr::url_decode()
/// [`html_escape()`]: RawStr::html_escape()
/// [`percent_decode()`]: RawStr::percent_decode()
/// [`percent_decode_lossy()`]: RawStr::percent_decode_lossy()
/// ///
/// # Usage /// # Usage
/// ///
@ -42,8 +47,8 @@ use uncased::UncasedStr;
/// encounter an `&RawStr` as a parameter via [`FromParam`] or as a form value /// encounter an `&RawStr` as a parameter via [`FromParam`] or as a form value
/// via [`FromFormValue`]. /// via [`FromFormValue`].
/// ///
/// [`FromParam`]: /rocket/request/trait.FromParam.html /// [`FromParam`]: ::rocket::request::FromParam
/// [`FromFormValue`]: /rocket/request/trait.FromFormValue.html /// [`FromFormValue`]: ::rocket::request::FromFormValue
#[repr(transparent)] #[repr(transparent)]
#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct RawStr(str); pub struct RawStr(str);

2
core/http/src/status.rs
View File

@ -95,7 +95,7 @@ pub struct Status {
macro_rules! ctrs { macro_rules! ctrs {
($($code:expr, $code_str:expr, $name:ident => $reason:expr),+) => { ($($code:expr, $code_str:expr, $name:ident => $reason:expr),+) => {
$( $(
#[doc="[Status](struct.Status.html) with code <b>"] #[doc="[`Status`] with code <b>"]
#[doc=$code_str] #[doc=$code_str]
#[doc="</b> and reason <i>"] #[doc="</b> and reason <i>"]
#[doc=$reason] #[doc=$reason]

26
core/http/src/uri/from_uri_param.rs
View File

@ -1,8 +1,9 @@
use std::path::{Path, PathBuf}; use std::path::{Path, PathBuf};
use {RawStr, uri::UriDisplay}; use RawStr;
use uri::UriDisplay;
/// Conversion trait for parameters used in `uri!` invocations. /// Conversion trait for parameters used in [`uri!`] invocations.
/// ///
/// This trait is invoked once per expression passed into a [`uri!`] invocation. /// This trait is invoked once per expression passed into a [`uri!`] invocation.
/// In particular, for a route URI parameter of type `T` and a user-supplied /// In particular, for a route URI parameter of type `T` and a user-supplied
@ -19,16 +20,15 @@ use {RawStr, uri::UriDisplay};
/// impl<'a> FromUriParam<&'a str> for String { type Target = &'a str; } /// impl<'a> FromUriParam<&'a str> for String { type Target = &'a str; }
/// ``` /// ```
/// ///
/// Because the `Target` type is the same as the input type, the conversion is a /// Because the [`FromUriParam::Target`] type is the same as the input type, the
/// no-op and free of cost, allowing an `&str` to be used in place of a /// conversion is a no-op and free of cost, allowing an `&str` to be used in
/// `String` without penalty. A similar no-op conversion exists for [`&RawStr`]: /// place of a `String` without penalty. A similar no-op conversion exists for
/// [`&RawStr`](RawStr):
/// ///
/// ```rust,ignore /// ```rust,ignore
/// impl<'a, 'b> FromUriParam<&'a str> for &'b RawStr { type Target = &'a str; } /// impl<'a, 'b> FromUriParam<&'a str> for &'b RawStr { type Target = &'a str; }
/// ``` /// ```
/// ///
/// [`&RawStr`]: /rocket/http/struct.RawStr.html
///
/// # Implementing /// # Implementing
/// ///
/// Rocket provides a blanket implementation for all types that implement /// Rocket provides a blanket implementation for all types that implement
@ -46,8 +46,8 @@ use {RawStr, uri::UriDisplay};
/// case, it's desirable to allow an `&str` to be used in place of a `String`. /// case, it's desirable to allow an `&str` to be used in place of a `String`.
/// ///
/// When implementing `FromUriParam`, be aware that Rocket will use the /// When implementing `FromUriParam`, be aware that Rocket will use the
/// [`UriDisplay`] implementation of `Target`, _not_ of the source type. /// [`UriDisplay`] implementation of [`FromUriParam::Target`], _not_ of the
/// Incorrect implementations can result in creating unsafe URIs. /// source type. Incorrect implementations can result in creating unsafe URIs.
/// ///
/// # Example /// # Example
/// ///
@ -96,16 +96,16 @@ use {RawStr, uri::UriDisplay};
/// // => "/hey?name=Robert+Mike&nickname=Bob" /// // => "/hey?name=Robert+Mike&nickname=Bob"
/// ``` /// ```
/// ///
/// [`uri!`]: /rocket_codegen/#typed-uris-uri /// [`uri!`]: ::rocket_codegen::uri
/// [`UriDisplay`]: /rocket/http/uri/trait.UriDisplay.html /// [`UriDisplay`]: uri::UriDisplay
/// [`FromUriParam::Target`]: uri::FromUriParam::Target
pub trait FromUriParam<T> { pub trait FromUriParam<T> {
/// The resulting type of this conversion. /// The resulting type of this conversion.
type Target: UriDisplay; type Target: UriDisplay;
/// Converts a value of type `T` into a value of type `Self::Target`. The /// Converts a value of type `T` into a value of type `Self::Target`. The
/// resulting value of type `Self::Target` will be rendered into a URI using /// resulting value of type `Self::Target` will be rendered into a URI using
/// its [`UriDisplay`](/rocket/http/uri/trait.UriDisplay.html) /// its [`UriDisplay`](uri::UriDisplay) implementation.
/// implementation.
fn from_uri_param(param: T) -> Self::Target; fn from_uri_param(param: T) -> Self::Target;
} }

10
core/http/src/uri/origin.rs
View File

@ -63,8 +63,8 @@ use state::Storage;
/// # } /// # }
/// ``` /// ```
/// ///
/// The [`Origin::to_normalized()`] method can be used to normalize any /// The [`Origin::to_normalized()`](uri::Origin::to_normalized()) method can be
/// `Origin`: /// used to normalize any `Origin`:
/// ///
/// ```rust /// ```rust
/// # extern crate rocket; /// # extern crate rocket;
@ -178,9 +178,9 @@ impl<'a> Origin<'a> {
} }
/// Parses the string `string` into an `Origin`. Parsing will never /// Parses the string `string` into an `Origin`. Parsing will never
/// allocate. This method should be used instead of [`Origin::parse()`] when /// allocate. This method should be used instead of
/// the source URI is already a `String`. Returns an `Error` if `string` is /// [`Origin::parse()`](uri::Origin::parse()) when the source URI is already
/// not a valid origin URI. /// a `String`. Returns an `Error` if `string` is not a valid origin URI.
/// ///
/// # Example /// # Example
/// ///

20
core/http/src/uri/uri.rs
View File

@ -18,7 +18,7 @@ use uri::{Origin, Authority, Absolute, Error};
/// ///
/// Nevertheless, the `Uri` type is typically enountered as a conversion target. /// Nevertheless, the `Uri` type is typically enountered as a conversion target.
/// In particular, you will likely see generic bounds of the form: `T: /// In particular, you will likely see generic bounds of the form: `T:
/// TryInto<Uri>` (for instance, in [`Redirect`](rocket::response::Redirect) /// TryInto<Uri>` (for instance, in [`Redirect`](::rocket::response::Redirect)
/// methods). This means that you can provide any type `T` that implements /// methods). This means that you can provide any type `T` that implements
/// `TryInto<Uri>`, or, equivalently, any type `U` for which `Uri` implements /// `TryInto<Uri>`, or, equivalently, any type `U` for which `Uri` implements
/// `TryFrom<U>` or `From<U>`. These include `&str` and `String`, [`Origin`], /// `TryFrom<U>` or `From<U>`. These include `&str` and `String`, [`Origin`],
@ -37,15 +37,23 @@ use uri::{Origin, Authority, Absolute, Error};
/// ## Percent Encoding/Decoding /// ## Percent Encoding/Decoding
/// ///
/// This type also provides the following percent encoding/decoding helper /// This type also provides the following percent encoding/decoding helper
/// methods: [`Uri::percent_encode`], [`Uri::percent_decode`], and /// methods: [`Uri::percent_encode()`], [`Uri::percent_decode()`], and
/// [`Uri::percent_decode_lossy`]. /// [`Uri::percent_decode_lossy()`].
///
/// [`Origin`]: uri::Origin
/// [`Authority`]: uri::Authority
/// [`Absolute`]: uri::Absolute
/// [`Uri::parse()`]: uri::Uri::parse()
/// [`Uri::percent_encode()`]: uri::Uri::percent_encode()
/// [`Uri::percent_decode()`]: uri::Uri::percent_decode()
/// [`Uri::percent_decode_lossy()`]: uri::Uri::percent_decode_lossy()
#[derive(Debug, PartialEq, Clone)] #[derive(Debug, PartialEq, Clone)]
pub enum Uri<'a> { pub enum Uri<'a> {
/// An [`Origin`] URI. /// An origin URI.
Origin(Origin<'a>), Origin(Origin<'a>),
/// An [`Authority`] URI. /// An authority URI.
Authority(Authority<'a>), Authority(Authority<'a>),
/// An [`Absolute`] URI. /// An absolute URI.
Absolute(Absolute<'a>), Absolute(Absolute<'a>),
/// An asterisk: exactly `*`. /// An asterisk: exactly `*`.
Asterisk, Asterisk,

15
core/http/src/uri/uri_display.rs
View File

@ -74,7 +74,7 @@ use self::priv_encode_set::PATH_ENCODE_SET;
/// The implementation of `UriDisplay` for these types is identical to the /// The implementation of `UriDisplay` for these types is identical to the
/// `Display` implementation. /// `Display` implementation.
/// ///
/// * **[`&RawStr`](/rocket/http/struct.RawStr.html), `String`, `&str`, /// * **[`&RawStr`](RawStr), `String`, `&str`,
/// `Cow<str>`** /// `Cow<str>`**
/// ///
/// The string is percent encoded. /// The string is percent encoded.
@ -85,16 +85,17 @@ use self::priv_encode_set::PATH_ENCODE_SET;
/// ///
/// # Implementing /// # Implementing
/// ///
/// Implementing `UriDisplay` is similar to implementing `Display` with the /// Implementing `UriDisplay` is similar to implementing
/// caveat that extra care must be taken to ensure that the written string is /// [`Display`](::std::fmt::Display) with the caveat that extra care must be
/// URI-safe. As mentioned before, in practice, this means that the string must /// taken to ensure that the written string is URI-safe. As mentioned before, in
/// either be percent-encoded or consist only of characters that are /// practice, this means that the string must either be percent-encoded or
/// alphanumeric, "-", ".", "_", or "~". /// consist only of characters that are alphanumeric, "-", ".", "_", or "~".
/// ///
/// When manually implementing `UriDisplay` for your types, you should defer to /// When manually implementing `UriDisplay` for your types, you should defer to
/// existing implementations of `UriDisplay` as much as possible. In the example /// existing implementations of `UriDisplay` as much as possible. In the example
/// below, for instance, `Name`'s implementation defers to `String`'s /// below, for instance, `Name`'s implementation defers to `String`'s
/// implementation. To percent-encode a string, use [`Uri::percent_encode()`]. /// implementation. To percent-encode a string, use
/// [`Uri::percent_encode()`](uri::Uri::percent_encode()).
/// ///
/// ## Example /// ## Example
/// ///

7
core/lib/src/catcher.rs
View File

@ -10,8 +10,9 @@ use yansi::Color::*;
/// ///
/// Catchers are routes that run when errors occur. They correspond directly /// Catchers are routes that run when errors occur. They correspond directly
/// with the HTTP error status code they will be handling and are registered /// with the HTTP error status code they will be handling and are registered
/// with Rocket via the [`Rocket::register()`] method. For example, to handle /// with Rocket via [`Rocket::register()`](::Rocket::register()). For example,
/// "404 not found" errors, a catcher for the "404" status code is registered. /// to handle "404 not found" errors, a catcher for the "404" status code is
/// registered.
/// ///
/// Because error handlers are only called when all routes are exhausted, they /// Because error handlers are only called when all routes are exhausted, they
/// should not fail nor forward. If an error catcher fails, the user will /// should not fail nor forward. If an error catcher fails, the user will
@ -57,7 +58,7 @@ use yansi::Color::*;
/// ``` /// ```
/// ///
/// A function decorated with `catch` must take exactly zero or one arguments. /// A function decorated with `catch` must take exactly zero or one arguments.
/// If the catcher takes an argument, it must be of type `&Request`. /// If the catcher takes an argument, it must be of type [`&Request`](Request).
pub struct Catcher { pub struct Catcher {
/// The HTTP status code to match against. /// The HTTP status code to match against.
pub code: u16, pub code: u16,

3
core/lib/src/config/builder.rs
View File

@ -35,8 +35,7 @@ impl ConfigBuilder {
/// the given `environment`. The root configuration directory is set to the /// the given `environment`. The root configuration directory is set to the
/// current working directory. /// current working directory.
/// ///
/// This method is typically called indirectly via /// This method is typically called indirectly via [`Config::build()`].
/// [Config::build](/rocket/config/struct.Config.html#method.build).
/// ///
/// # Panics /// # Panics
/// ///

20
core/lib/src/config/config.rs
View File

@ -16,9 +16,8 @@ use http::Key;
/// ///
/// # Usage /// # Usage
/// ///
/// A `Config` structure is typically built using the [build](#method.build) /// A `Config` structure is typically built using [`Config::build()`] and
/// method and [ConfigBuilder](/rocket/config/struct.ConfigBuilder.html) /// builder methods on the returned [`ConfigBuilder`] structure:
/// methods:
/// ///
/// ```rust /// ```rust
/// use rocket::config::{Config, Environment}; /// use rocket::config::{Config, Environment};
@ -33,10 +32,8 @@ use http::Key;
/// ///
/// ## General Configuration /// ## General Configuration
/// ///
/// For more information about Rocket's configuration, see the [`config`] module /// For more information about Rocket's configuration, see the
/// documentation. /// [`config`](::config) module documentation.
///
/// [`config`]: /rocket/config/index.html
#[derive(Clone)] #[derive(Clone)]
pub struct Config { pub struct Config {
/// The environment that this configuration corresponds to. /// The environment that this configuration corresponds to.
@ -909,11 +906,10 @@ impl Config {
} }
} }
/// If `path` is a relative path, `path` is appended to the [`root`] at /// If `path` is a relative path, `path` is appended to the
/// which the configuration file for `self` is stored and the new path is /// [`Config::root()`] at which the configuration file for `self` is stored
/// returned. If `path` is absolute, `path` is returned unaltered. /// and the new path is returned. If `path` is absolute, `path` is returned
/// /// unaltered.
/// [`root`]: /rocket/struct.Config.html#method.root
/// ///
/// # Example /// # Example
/// ///

3
core/lib/src/config/custom_values.rs
View File

@ -59,8 +59,7 @@ pub struct TlsConfig;
/// ///
/// # Defaults /// # Defaults
/// ///
/// As documented in the [config module](/rocket/config/), the default limits /// As documented in [`config`](::config), the default limits are as follows:
/// are as follows:
/// ///
/// * **forms**: 32KiB /// * **forms**: 32KiB
/// ///

38
core/lib/src/config/mod.rs
View File

@ -31,30 +31,30 @@
//! not used by Rocket itself but can be used by external libraries. The //! not used by Rocket itself but can be used by external libraries. The
//! standard configuration parameters are: //! standard configuration parameters are:
//! //!
//! * **address**: _[string]_ an IP address or host the application will //! * **address**: _string_ an IP address or host the application will
//! listen on //! listen on
//! * examples: `"localhost"`, `"0.0.0.0"`, `"1.2.3.4"` //! * examples: `"localhost"`, `"0.0.0.0"`, `"1.2.3.4"`
//! * **port**: _[integer]_ a port number to listen on //! * **port**: _integer_ a port number to listen on
//! * examples: `"8000"`, `"80"`, `"4242"` //! * examples: `"8000"`, `"80"`, `"4242"`
//! * **workers**: _[integer]_ the number of concurrent workers to use //! * **workers**: _integer_ the number of concurrent workers to use
//! * examples: `12`, `1`, `4` //! * examples: `12`, `1`, `4`
//! * **keep_alive**: _[integer, 'false', or 'none']_ timeout, in seconds, for //! * **keep_alive**: _integer, 'false', or 'none'_ timeout, in seconds, for
//! HTTP keep-alive. disabled on 'false' or 'none' //! HTTP keep-alive. disabled on 'false' or 'none'
//! * examples: `5`, `60`, `false`, `"none"` //! * examples: `5`, `60`, `false`, `"none"`
//! * **log**: _[string]_ how much information to log; one of `"off"`, //! * **log**: _string_ how much information to log; one of `"off"`,
//! `"normal"`, `"debug"`, or `"critical"` //! `"normal"`, `"debug"`, or `"critical"`
//! * **secret_key**: _[string]_ a 256-bit base64 encoded string (44 //! * **secret_key**: _string_ a 256-bit base64 encoded string (44
//! characters) to use as the secret key //! characters) to use as the secret key
//! * example: `"8Xui8SN4mI+7egV/9dlfYYLGQJeEx4+DwmSQLwDVXJg="` //! * example: `"8Xui8SN4mI+7egV/9dlfYYLGQJeEx4+DwmSQLwDVXJg="`
//! * **tls**: _[table]_ a table with two keys: //! * **tls**: _table_ a table with two keys:
//! 1. `certs`: _[string]_ a path to a certificate chain in PEM format //! 1. `certs`: _string_ a path to a certificate chain in PEM format
//! 2. `key`: _[string]_ a path to a private key file in PEM format for the //! 2. `key`: _string_ a path to a private key file in PEM format for the
//! certificate in `certs` //! certificate in `certs`
//! //!
//! * example: `{ certs = "/path/to/certs.pem", key = "/path/to/key.pem" }` //! * example: `{ certs = "/path/to/certs.pem", key = "/path/to/key.pem" }`
//! * **limits**: _[table]_ a table where each key (_[string]_) corresponds to //! * **limits**: _table_ a table where each key (_string_) corresponds to a
//! a data type and the value (_[u64]_) corresponds to the maximum size in //! data type and the value (`u64`) corresponds to the maximum size in bytes
//! bytes Rocket should accept for that type. //! Rocket should accept for that type.
//! * example: `{ forms = 65536 }` (maximum form size to 64KiB) //! * example: `{ forms = 65536 }` (maximum form size to 64KiB)
//! //!
//! ### Rocket.toml //! ### Rocket.toml
@ -166,14 +166,13 @@
//! ## Retrieving Configuration Parameters //! ## Retrieving Configuration Parameters
//! //!
//! Configuration parameters for the currently active configuration environment //! Configuration parameters for the currently active configuration environment
//! can be retrieved via the [config](/rocket/struct.Rocket.html#method.config) //! can be retrieved via the [`Rocket::config()`] `Rocket` and `get_` methods on
//! method on an instance of `Rocket` and `get_` methods on the //! [`Config`] structure.
//! [Config](struct.Config.html) structure.
//! //!
//! The retrivial of configuration parameters usually occurs at launch time via //! The retrivial of configuration parameters usually occurs at launch time via
//! a [launch fairing](/rocket/fairing/trait.Fairing.html). If information about //! a [launch fairing](::fairing::Fairing). If information about the
//! the configuraiton is needed later in the program, an attach fairing can be //! configuraiton is needed later in the program, an attach fairing can be used
//! used to store the information as managed state. As an example of the latter, //! to store the information as managed state. As an example of the latter,
//! consider the following short program which reads the `token` configuration //! consider the following short program which reads the `token` configuration
//! parameter and stores the value or a default in a `Token` managed state //! parameter and stores the value or a default in a `Token` managed state
//! value: //! value:
@ -230,8 +229,7 @@ const GLOBAL_ENV_NAME: &str = "global";
const ENV_VAR_PREFIX: &str = "ROCKET_"; const ENV_VAR_PREFIX: &str = "ROCKET_";
const PREHANDLED_VARS: [&str; 2] = ["ROCKET_CODEGEN_DEBUG", CONFIG_ENV]; const PREHANDLED_VARS: [&str; 2] = ["ROCKET_CODEGEN_DEBUG", CONFIG_ENV];
/// Wraps `std::result` with the error type of /// Wraps `std::result` with the error type of [`ConfigError`].
/// [ConfigError](enum.ConfigError.html).
pub type Result<T> = ::std::result::Result<T, ConfigError>; pub type Result<T> = ::std::result::Result<T, ConfigError>;
#[doc(hidden)] #[doc(hidden)]

6
core/lib/src/data/data.rs
View File

@ -27,8 +27,8 @@ const PEEK_BYTES: usize = 512;
/// ///
/// This type is the only means by which the body of a request can be retrieved. /// This type is the only means by which the body of a request can be retrieved.
/// This type is not usually used directly. Instead, types that implement /// This type is not usually used directly. Instead, types that implement
/// [`FromData`] are used via code generation by specifying the `data = "<var>"` /// [`FromData`](::data::Data) are used via code generation by specifying the
/// route parameter as follows: /// `data = "<var>"` route parameter as follows:
/// ///
/// ```rust /// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro)] /// # #![feature(proc_macro_hygiene, decl_macro)]
@ -45,7 +45,7 @@ const PEEK_BYTES: usize = 512;
/// # Reading Data /// # Reading Data
/// ///
/// Data may be read from a `Data` object by calling either the /// Data may be read from a `Data` object by calling either the
/// [open](#method.open) or [peek](#method.peek) methods. /// [`open()`](Data::open()) or [`peek()`](Data::peek()) methods.
/// ///
/// The `open` method consumes the `Data` object and returns the raw data /// The `open` method consumes the `Data` object and returns the raw data
/// stream. The `Data` object is consumed for safety reasons: consuming the /// stream. The `Data` object is consumed for safety reasons: consuming the

6
core/lib/src/data/data_stream.rs
View File

@ -11,9 +11,9 @@ pub type InnerStream = Chain<Cursor<Vec<u8>>, BodyReader>;
/// Raw data stream of a request body. /// Raw data stream of a request body.
/// ///
/// This stream can only be obtained by calling /// This stream can only be obtained by calling
/// [Data::open](/rocket/data/struct.Data.html#method.open). The stream contains /// [`Data::open()`](::data::Data::open()). The stream contains all of the data
/// all of the data in the body of the request. It exposes no methods directly. /// in the body of the request. It exposes no methods directly. Instead, it must
/// Instead, it must be used as an opaque `Read` structure. /// be used as an opaque [`Read`] structure.
pub struct DataStream(crate InnerStream); pub struct DataStream(crate InnerStream);
// TODO: Have a `BufRead` impl for `DataStream`. At the moment, this isn't // TODO: Have a `BufRead` impl for `DataStream`. At the moment, this isn't

22
core/lib/src/data/from_data.rs
View File

@ -120,7 +120,7 @@ pub type Transformed<'a, T> =
/// Data guards are used as the target of the `data` route attribute parameter. /// Data guards are used as the target of the `data` route attribute parameter.
/// A handler can have at most one data guard. /// A handler can have at most one data guard.
/// ///
/// [request guard]: /rocket/request/trait.FromRequest.html /// [request guard]: ::request::FromRequest
/// ///
/// ## Example /// ## Example
/// ///
@ -235,26 +235,26 @@ pub type Transformed<'a, T> =
/// ///
/// # Outcomes /// # Outcomes
/// ///
/// The returned [Outcome](/rocket/outcome/index.html) of a `from_data` call /// The returned [`Outcome`] of a `from_data` call determines how the incoming
/// determines how the incoming request will be processed. /// request will be processed.
/// ///
/// * **Success**(S) /// * **Success**(S)
/// ///
/// If the `Outcome` is `Success`, then the `Success` value will be used as /// If the `Outcome` is [`Success`], then the `Success` value will be used as
/// the value for the data parameter. As long as all other parsed types /// the value for the data parameter. As long as all other parsed types
/// succeed, the request will be handled by the requesting handler. /// succeed, the request will be handled by the requesting handler.
/// ///
/// * **Failure**(Status, E) /// * **Failure**(Status, E)
/// ///
/// If the `Outcome` is `Failure`, the request will fail with the given status /// If the `Outcome` is [`Failure`], the request will fail with the given
/// code and error. The designated error /// status code and error. The designated error [`Catcher`](::Catcher) will be
/// [Catcher](/rocket/struct.Catcher.html) will be used to respond to the /// used to respond to the request. Note that users can request types of
/// request. Note that users can request types of `Result<S, E>` and /// `Result<S, E>` and `Option<S>` to catch `Failure`s and retrieve the error
/// `Option<S>` to catch `Failure`s and retrieve the error value. /// value.
/// ///
/// * **Forward**(Data) /// * **Forward**(Data)
/// ///
/// If the `Outcome` is `Forward`, the request will be forwarded to the next /// If the `Outcome` is [`Forward`], the request will be forwarded to the next
/// matching request. This requires that no data has been read from the `Data` /// matching request. This requires that no data has been read from the `Data`
/// parameter. Note that users can request an `Option<S>` to catch `Forward`s. /// parameter. Note that users can request an `Option<S>` to catch `Forward`s.
/// ///
@ -265,7 +265,7 @@ pub type Transformed<'a, T> =
/// ///
/// * **Data** /// * **Data**
/// ///
/// The identity implementation; simply returns `Data` directly. /// The identity implementation; simply returns [`Data`] directly.
/// ///
/// _This implementation always returns successfully._ /// _This implementation always returns successfully._
/// ///

5
core/lib/src/error.rs
View File

@ -27,9 +27,8 @@ pub enum LaunchErrorKind {
/// An error that occurs during launch. /// An error that occurs during launch.
/// ///
/// A `LaunchError` is returned by /// A `LaunchError` is returned by [`launch()`](::Rocket::launch()) when
/// [rocket::launch](/rocket/struct.Rocket.html#method.launch) when launching an /// launching an application fails.
/// application fails for some reason.
/// ///
/// # Panics /// # Panics
/// ///

10
core/lib/src/fairing/info_kind.rs
View File

@ -1,11 +1,11 @@
use std::ops::BitOr; use std::ops::BitOr;
/// Information about a [`Fairing`](/rocket/fairing/trait.Fairing.html). /// Information about a [`Fairing`](::fairing::Fairing).
/// ///
/// The `name` field is an arbitrary name for a fairing. The `kind` field is a /// The `name` field is an arbitrary name for a fairing. The `kind` field is a
/// is an `or`d set of [`Kind`](/rocket/fairing/struct.Kind.html) structures. /// is an `or`d set of [`Kind`] structures. Rocket uses the values set in `Kind`
/// Rocket uses the values set in `Kind` to determine which callbacks from a /// to determine which callbacks from a given `Fairing` implementation to
/// given `Fairing` implementation to actually call. /// actually call.
/// ///
/// # Example /// # Example
/// ///
@ -30,7 +30,7 @@ pub struct Info {
} }
/// A bitset representing the kinds of callbacks a /// A bitset representing the kinds of callbacks a
/// [`Fairing`](/rocket/fairing/trait.Fairing.html) wishes to receive. /// [`Fairing`](::fairing::Fairing) wishes to receive.
/// ///
/// A fairing can request any combination of any of the following kinds of /// A fairing can request any combination of any of the following kinds of
/// callbacks: /// callbacks:

125
core/lib/src/fairing/mod.rs
View File

@ -8,18 +8,16 @@
//! to perform an action once a Rocket application has launched. //! to perform an action once a Rocket application has launched.
//! //!
//! To learn more about writing a fairing, see the [`Fairing`] trait //! To learn more about writing a fairing, see the [`Fairing`] trait
//! documentation. You can also use [`AdHoc`] to create a fairing on-the-fly //! documentation. You can also use [`AdHoc`](fairing::AdHoc) to create a
//! from a closure or function. //! fairing on-the-fly from a closure or function.
//!
//! [`AdHoc`]: /rocket/fairing/enum.AdHoc.html
//! //!
//! ## Attaching //! ## Attaching
//! //!
//! You must inform Rocket about fairings that you wish to be active by calling //! You must inform Rocket about fairings that you wish to be active by calling
//! the [`attach`](/rocket/struct.Rocket.html#method.attach) method on the //! [`Rocket::attach()`] method on the application's [`Rocket`] instance and
//! [`Rocket`](/rocket/struct.Rocket.html) instance and passing in the //! passing in the appropriate [`Fairing`]. For instance, to attach fairings
//! appropriate [`Fairing`]. For instance, to attach fairings named //! named `req_fairing` and `res_fairing` to a new Rocket instance, you might
//! `req_fairing` and `res_fairing` to a new Rocket instance, you might write: //! write:
//! //!
//! ```rust //! ```rust
//! # use rocket::fairing::AdHoc; //! # use rocket::fairing::AdHoc;
@ -35,7 +33,7 @@
//! trait documentation for more information on the dispatching of fairing //! trait documentation for more information on the dispatching of fairing
//! methods. //! methods.
//! //!
//! [`Fairing`]: /rocket/fairing/trait.Fairing.html //! [`Fairing`]: ::fairing::Fairing
//! //!
//! ## Ordering //! ## Ordering
//! //!
@ -90,9 +88,9 @@ pub use self::info_kind::{Info, Kind};
/// entire application. On the other hand, you _should_ use a fairing to record /// entire application. On the other hand, you _should_ use a fairing to record
/// timing and/or usage statistics or to implement global security policies. /// timing and/or usage statistics or to implement global security policies.
/// ///
/// [request guard]: /rocket/request/trait.FromRequest.html /// [request guard]: ::request::FromRequest
/// [request guards]: /rocket/request/trait.FromRequest.html /// [request guards]: ::request::FromRequest
/// [data guards]: /rocket/data/trait.FromData.html /// [data guards]: ::data::FromData
/// ///
/// ## Fairing Callbacks /// ## Fairing Callbacks
/// ///
@ -105,13 +103,12 @@ pub use self::info_kind::{Info, Kind};
/// ///
/// * **Attach (`on_attach`)** /// * **Attach (`on_attach`)**
/// ///
/// An attach callback, represented by the /// An attach callback, represented by the [`Fairing::on_attach()`] method,
/// [`on_attach`](/rocket/fairing/trait.Fairing.html#method.on_attach) /// is called when a fairing is first attached via [`Rocket::attach()`]
/// method, is called when a fairing is first attached via the /// method. The state of the `Rocket` instance is, at this point, not
/// [`attach`](/rocket/struct.Rocket.html#method.attach) method. The state /// finalized, as the user may still add additional information to the
/// of the `Rocket` instance is, at this point, not finalized, as the user /// `Rocket` instance. As a result, it is unwise to depend on the state of
/// may still add additional information to the `Rocket` instance. As a /// the `Rocket` instance.
/// result, it is unwise to depend on the state of the `Rocket` instance.
/// ///
/// An attach callback can arbitrarily modify the `Rocket` instance being /// An attach callback can arbitrarily modify the `Rocket` instance being
/// constructed. It returns `Ok` if it would like launching to proceed /// constructed. It returns `Ok` if it would like launching to proceed
@ -121,43 +118,39 @@ pub use self::info_kind::{Info, Kind};
/// ///
/// * **Launch (`on_launch`)** /// * **Launch (`on_launch`)**
/// ///
/// A launch callback, represented by the /// A launch callback, represented by the [`Fairing::on_launch()`] method,
/// [`on_launch`](/rocket/fairing/trait.Fairing.html#method.on_launch) /// is called immediately before the Rocket application has launched. At
/// method, is called immediately before the Rocket application has /// this point, Rocket has opened a socket for listening but has not yet
/// launched. At this point, Rocket has opened a socket for listening but /// begun accepting connections. A launch callback can inspect the `Rocket`
/// has not yet begun accepting connections. A launch callback can inspect /// instance being launched.
/// the `Rocket` instance being launched.
/// ///
/// * **Request (`on_request`)** /// * **Request (`on_request`)**
/// ///
/// A request callback, represented by the /// A request callback, represented by the [`Fairing::on_request()`] method,
/// [`on_request`](/rocket/fairing/trait.Fairing.html#method.on_request) /// is called just after a request is received, immediately after
/// method, is called just after a request is received, immediately after
/// pre-processing the request with method changes due to `_method` form /// pre-processing the request with method changes due to `_method` form
/// fields. At this point, Rocket has parsed the incoming HTTP request into /// fields. At this point, Rocket has parsed the incoming HTTP request into
/// [`Request`](/rocket/struct.Request.html) and /// [`Request`] and [`Data`] structures but has not routed the request. A
/// [`Data`](/rocket/struct.Data.html) structures but has not routed the /// request callback can modify the request at will and [`Data::peek()`]
/// request. A request callback can modify the request at will and /// into the incoming data. It may not, however, abort or respond directly
/// [`peek`](/rocket/struct.Data.html#method.peek) into the incoming data. /// to the request; these issues are better handled via [request guards] or
/// It may not, however, abort or respond directly to the request; these /// via response callbacks. Any modifications to a request are persisted and
/// issues are better handled via [request /// can potentially alter how a request is routed.
/// guards](/rocket/request/trait.FromRequest.html) or via response ///=
/// callbacks. Any modifications to a request are persisted and can
/// potentially alter how a request is routed.
///
/// * **Response (`on_response`)** /// * **Response (`on_response`)**
/// ///
/// A response callback is called when a response is ready to be sent to the /// A response callback, represented by the [`Fairing::on_response()`]
/// client. At this point, Rocket has completed all routing, including to /// method, is called when a response is ready to be sent to the client. At
/// error catchers, and has generated the would-be final response. A /// this point, Rocket has completed all routing, including to error
/// response callback can modify the response at will. For example, a /// catchers, and has generated the would-be final response. A response
/// response callback can provide a default response when the user fails to /// callback can modify the response at will. For example, a response
/// handle the request by checking for 404 responses. Note that a given /// callback can provide a default response when the user fails to handle
/// `Request` may have changed between `on_request` and `on_response` /// the request by checking for 404 responses. Note that a given `Request`
/// invocations. Apart from any change made by other fairings, Rocket sets /// may have changed between `on_request` and `on_response` invocations.
/// the method for `HEAD` requests to `GET` if there is no matching `HEAD` /// Apart from any change made by other fairings, Rocket sets the method for
/// handler for that request. Additionally, Rocket will automatically strip /// `HEAD` requests to `GET` if there is no matching `HEAD` handler for that
/// the body for `HEAD` requests _after_ response fairings have run. /// request. Additionally, Rocket will automatically strip the body for
/// `HEAD` requests _after_ response fairings have run.
/// ///
/// # Implementing /// # Implementing
/// ///
@ -170,8 +163,7 @@ pub use self::info_kind::{Info, Kind};
/// ## Fairing `Info` /// ## Fairing `Info`
/// ///
/// Every `Fairing` must implement the [`info`] method, which returns an /// Every `Fairing` must implement the [`info`] method, which returns an
/// [`Info`](/rocket/fairing/struct.Info.html) structure. This structure is used /// [`Info`] structure. This structure is used by Rocket to:
/// by Rocket to:
/// ///
/// 1. Assign a name to the `Fairing`. /// 1. Assign a name to the `Fairing`.
/// ///
@ -181,32 +173,30 @@ pub use self::info_kind::{Info, Kind};
/// ///
/// 2. Determine which callbacks to actually issue on the `Fairing`. /// 2. Determine which callbacks to actually issue on the `Fairing`.
/// ///
/// This is the `kind` field of type /// This is the `kind` field of type [`Kind`]. This field is a bitset that
/// [`Kind`](/rocket/fairing/struct.Kind.html). This field is a bitset that
/// represents the kinds of callbacks the fairing wishes to receive. Rocket /// represents the kinds of callbacks the fairing wishes to receive. Rocket
/// will only invoke the callbacks that are flagged in this set. `Kind` /// will only invoke the callbacks that are flagged in this set. `Kind`
/// structures can be `or`d together to represent any combination of kinds /// structures can be `or`d together to represent any combination of kinds
/// of callbacks. For instance, to request launch and response callbacks, /// of callbacks. For instance, to request launch and response callbacks,
/// return a `kind` field with the value `Kind::Launch | Kind::Response`. /// return a `kind` field with the value `Kind::Launch | Kind::Response`.
/// ///
/// [`info`]: /rocket/fairing/trait.Fairing.html#tymethod.info /// [`info`]: Fairing::info()
/// ///
/// ## Restrictions /// ## Restrictions
/// ///
/// A `Fairing` must be `Send + Sync + 'static`. This means that the fairing /// A `Fairing` must be [`Send`] + [`Sync`] + `'static`. This means that the
/// must be sendable across thread boundaries (`Send`), thread-safe (`Sync`), /// fairing must be sendable across thread boundaries (`Send`), thread-safe
/// and have only `'static` references, if any (`'static`). Note that these /// (`Sync`), and have only `'static` references, if any (`'static`). Note that
/// bounds _do not_ prohibit a `Fairing` from holding state: the state need /// these bounds _do not_ prohibit a `Fairing` from holding state: the state
/// simply be thread-safe and statically available or heap allocated. /// need simply be thread-safe and statically available or heap allocated.
/// ///
/// ## Example /// ## Example
/// ///
/// Imagine that we want to record the number of `GET` and `POST` requests that /// Imagine that we want to record the number of `GET` and `POST` requests that
/// our application has received. While we could do this with [request /// our application has received. While we could do this with [request guards]
/// guards](/rocket/request/trait.FromRequest.html) and [managed /// and [managed state](::request::State), it would require us to annotate every
/// state](/rocket/request/struct.State.html), it would require us to annotate /// `GET` and `POST` request with custom types, polluting handler signatures.
/// every `GET` and `POST` request with custom types, polluting handler /// Instead, we can create a simple fairing that acts globally.
/// signatures. Instead, we can create a simple fairing that acts globally.
/// ///
/// The `Counter` fairing below records the number of all `GET` and `POST` /// The `Counter` fairing below records the number of all `GET` and `POST`
/// requests received. It makes these counts available at a special `'/counts'` /// requests received. It makes these counts available at a special `'/counts'`
@ -333,10 +323,9 @@ pub use self::info_kind::{Info, Kind};
/// [request-local state]: https://rocket.rs/guide/state/#request-local-state /// [request-local state]: https://rocket.rs/guide/state/#request-local-state
pub trait Fairing: Send + Sync + 'static { pub trait Fairing: Send + Sync + 'static {
/// Returns an [`Info`](/rocket/fairing/struct.Info.html) structure /// Returns an [`Info`] structure containing the `name` and [`Kind`] of this
/// containing the `name` and [`Kind`](/rocket/fairing/struct.Kind.html) of /// fairing. The `name` can be any arbitrary string. `Kind` must be an `or`d
/// this fairing. The `name` can be any arbitrary string. `Kind` must be an /// set of `Kind` variants.
/// `or`d set of `Kind` variants.
/// ///
/// This is the only required method of a `Fairing`. All other methods have /// This is the only required method of a `Fairing`. All other methods have
/// no-op default implementations. /// no-op default implementations.

65
core/lib/src/lib.rs
View File

@ -12,54 +12,51 @@
// TODO: Version URLs. // TODO: Version URLs.
#![doc(html_root_url = "https://api.rocket.rs")] #![doc(html_root_url = "https://api.rocket.rs")]
#![doc(html_favicon_url = "https://rocket.rs/favicon.ico")]
#![doc(html_logo_url = "https://rocket.rs/images/logo-boxed.png")]
//! # Rocket - Core API Documentation //! # Rocket - Core API Documentation
//! //!
//! Hello, and welcome to the core Rocket API documentation! //! Hello, and welcome to the core Rocket API documentation!
//! //!
//! This API documentation is highly technical and is purely a reference. //! This API documentation is highly technical and is purely a reference.
//! There's an [overview](https://rocket.rs/overview) of Rocket on the main site //! There's an [overview] of Rocket on the main site as well as a [full,
//! as well as a [full, detailed guide](https://rocket.rs/guide). If you'd like //! detailed guide]. If you'd like pointers on getting started, see the
//! pointers on getting started, see the //! [quickstart] or [getting started] chapters of the guide.
//! [quickstart](https://rocket.rs/guide/quickstart) or [getting
//! started](https://rocket.rs/guide/getting-started) chapters of the guide.
//! //!
//! You may also be interested in looking at the [contrib API //! You may also be interested in looking at the [`rocket_contrib`]
//! documentation](/rocket_contrib), which contains JSON and templating //! documentation, which contains automatic JSON (de)serialiazation, templating
//! support, among other features. //! support, static file serving, and other useful features.
//!
//! [overview]: https://rocket.rs/overview
//! [full, detailed guide]: https://rocket.rs/guide
//! [quickstart]: https://rocket.rs/guide/quickstart
//! [getting started]: https://rocket.rs/guide/getting-started
//! //!
//! ## Libraries //! ## Libraries
//! //!
//! Rocket's functionality is split into two crates: //! Rocket's functionality is split into two crates:
//! //!
//! 1. [Core](/rocket) - The core library. Needed by every Rocket application. //! 1. Core - This core library. Needed by every Rocket application.
//! 2. [Contrib](/rocket_contrib) - Provides useful functionality for many //! 2. [Contrib](rocket_contrib) - Provides useful functionality for many
//! Rocket applications. Completely optional. //! Rocket applications. Completely optional.
//! //!
//! ## Usage //! ## Usage
//! //!
//! The sanctioned way to use Rocket is via the code generation plugin. This //! First, depend on `rocket` in `Cargo.toml`:
//! makes Rocket easier and safer to use and allows a somewhat stable API as
//! Rocket matures. To use Rocket with the code generation plugin in your
//! Cargo-based project, add the following to `Cargo.toml`:
//! //!
//! ```rust,ignore //! ```toml
//! [dependencies] //! [dependencies]
//! rocket = "*" //! rocket = "0.4.0-dev"
//! ``` //! ```
//! //!
//! If you'll be deploying your project to [crates.io](https://crates.io),
//! you'll need to change the "*" to the current version of Rocket.
//!
//! Then, add the following to the top of your `main.rs` file: //! Then, add the following to the top of your `main.rs` file:
//! //!
//! ```rust //! ```rust
//! #![feature(proc_macro_hygiene, decl_macro)] //! #![feature(proc_macro_hygiene, decl_macro)]
//! //!
//! #[macro_use] extern crate rocket; //! #[macro_use] extern crate rocket;
//! # //! # #[get("/")] fn hello() { }
//! # #[get("/")]
//! # fn hello() { }
//! # fn main() { rocket::ignite().mount("/", routes![hello]); } //! # fn main() { rocket::ignite().mount("/", routes![hello]); }
//! ``` //! ```
//! //!
@ -87,16 +84,19 @@
//! //!
//! Rocket and Rocket libraries are configured via the `Rocket.toml` file and/or //! Rocket and Rocket libraries are configured via the `Rocket.toml` file and/or
//! `ROCKET_{PARAM}` environment variables. For more information on how to //! `ROCKET_{PARAM}` environment variables. For more information on how to
//! configure Rocket, see the [configuration //! configure Rocket, see the [configuration section] of the guide as well as
//! section](https://rocket.rs/guide/configuration/) of the guide as well as the //! the [`config`] module documentation.
//! [config](/rocket/config) module documentation. //!
//! [configuration section]: https://rocket.rs/guide/configuration/
//! //!
//! ## Testing //! ## Testing
//! //!
//! The [local](/rocket/local) module contains structures that facilitate unit //! The [`local`] module contains structures that facilitate unit and
//! and integration testing of a Rocket application. The [top-level `local` //! integration testing of a Rocket application. The top-level [`local`] module
//! module documentation](/rocket/local) and the [testing chapter of the //! documentation and the [testing chapter of the guide] include detailed
//! guide](https://rocket.rs/guide/testing/#testing) include detailed examples. //! examples.
//!
//! [testing chapter of the guide]: https://rocket.rs/guide/testing/#testing
#[allow(unused_imports)] #[macro_use] extern crate rocket_codegen_next; #[allow(unused_imports)] #[macro_use] extern crate rocket_codegen_next;
#[doc(hidden)] pub use rocket_codegen_next::*; #[doc(hidden)] pub use rocket_codegen_next::*;
@ -154,14 +154,13 @@ pub use request::{Request, State};
pub use catcher::Catcher; pub use catcher::Catcher;
pub use rocket::Rocket; pub use rocket::Rocket;
/// Alias to [Rocket::ignite()](/rocket/struct.Rocket.html#method.ignite). /// Alias to [`Rocket::ignite()`] Creates a new instance of `Rocket`.
/// Creates a new instance of `Rocket`.
pub fn ignite() -> Rocket { pub fn ignite() -> Rocket {
Rocket::ignite() Rocket::ignite()
} }
/// Alias to [Rocket::custom()](/rocket/struct.Rocket.html#method.custom). /// Alias to [`Rocket::custom()`]. Creates a new instance of `Rocket` with a
/// Creates a new instance of `Rocket` with a custom configuration. /// custom configuration.
pub fn custom(config: config::Config) -> Rocket { pub fn custom(config: config::Config) -> Rocket {
Rocket::custom(config) Rocket::custom(config)
} }

44
core/lib/src/local/client.rs
View File

@ -15,8 +15,7 @@ use error::LaunchError;
/// constructed, the [`LocalRequest`] constructor methods ([`get`], [`put`], /// constructed, the [`LocalRequest`] constructor methods ([`get`], [`put`],
/// [`post`], and so on) can be used to create a `LocalRequest` for dispatching. /// [`post`], and so on) can be used to create a `LocalRequest` for dispatching.
/// ///
/// See the [top-level documentation](/rocket/local/index.html) for more usage /// See the [top-level documentation](::local) for more usage information.
/// information.
/// ///
/// ## Cookie Tracking /// ## Cookie Tracking
/// ///
@ -49,7 +48,6 @@ use error::LaunchError;
/// ///
/// [`new`]: #method.new /// [`new`]: #method.new
/// [`untracked`]: #method.untracked /// [`untracked`]: #method.untracked
/// [`LocalRequest`]: /rocket/local/struct.LocalRequest.html
/// [`get`]: #method.get /// [`get`]: #method.get
/// [`put`]: #method.put /// [`put`]: #method.put
/// [`post`]: #method.post /// [`post`]: #method.post
@ -152,9 +150,8 @@ impl Client {
/// ///
/// When dispatched, the request will be served by the instance of Rocket /// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually /// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request. /// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// /// request.
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// ///
/// # Example /// # Example
/// ///
@ -173,9 +170,8 @@ impl Client {
/// ///
/// When dispatched, the request will be served by the instance of Rocket /// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually /// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request. /// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// /// request.
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// ///
/// # Example /// # Example
/// ///
@ -194,9 +190,8 @@ impl Client {
/// ///
/// When dispatched, the request will be served by the instance of Rocket /// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually /// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request. /// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// /// request.
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// ///
/// # Example /// # Example
/// ///
@ -219,9 +214,8 @@ impl Client {
/// ///
/// When dispatched, the request will be served by the instance of Rocket /// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually /// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request. /// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// /// request.
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// ///
/// # Example /// # Example
/// ///
@ -242,9 +236,8 @@ impl Client {
/// ///
/// When dispatched, the request will be served by the instance of Rocket /// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually /// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request. /// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// /// request.
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// ///
/// # Example /// # Example
/// ///
@ -265,9 +258,8 @@ impl Client {
/// ///
/// When dispatched, the request will be served by the instance of Rocket /// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually /// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request. /// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// /// request.
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// ///
/// # Example /// # Example
/// ///
@ -288,9 +280,8 @@ impl Client {
/// ///
/// When dispatched, the request will be served by the instance of Rocket /// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually /// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request. /// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// /// request.
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// ///
/// # Example /// # Example
/// ///
@ -311,9 +302,8 @@ impl Client {
/// ///
/// When dispatched, the request will be served by the instance of Rocket /// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually /// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request. /// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// /// request.
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// ///
/// # Example /// # Example
/// ///

6
core/lib/src/local/mod.rs
View File

@ -95,10 +95,8 @@
//! } //! }
//! ``` //! ```
//! //!
//! [`Client`]: /rocket/local/struct.Client.html //! [`Client`]: local::Client
//! [`LocalRequest`]: /rocket/local/struct.LocalRequest.html //! [`LocalRequest`]: local::LocalRequest
//! [`Rocket`]: /rocket/struct.Rocket.html
//!
mod request; mod request;
mod client; mod client;

18
core/lib/src/local/request.rs
View File

@ -56,7 +56,7 @@ use local::Client;
/// same request needs to be dispatched multiple times, the request can first be /// same request needs to be dispatched multiple times, the request can first be
/// cloned and then dispatched: `request.clone().dispatch()`. /// cloned and then dispatched: `request.clone().dispatch()`.
/// ///
/// [`Client`]: /rocket/local/struct.Client.html /// [`Client`]: ::local::Client
/// [`header`]: #method.header /// [`header`]: #method.header
/// [`add_header`]: #method.add_header /// [`add_header`]: #method.add_header
/// [`cookie`]: #method.cookie /// [`cookie`]: #method.cookie
@ -159,8 +159,8 @@ impl<'c> LocalRequest<'c> {
/// Any type that implements `Into<Header>` can be used here. Among others, /// Any type that implements `Into<Header>` can be used here. Among others,
/// this includes [`ContentType`] and [`Accept`]. /// this includes [`ContentType`] and [`Accept`].
/// ///
/// [`ContentType`]: /rocket/http/struct.ContentType.html /// [`ContentType`]: ::http::ContentType
/// [`Accept`]: /rocket/http/struct.Accept.html /// [`Accept`]: ::http::Accept
/// ///
/// # Examples /// # Examples
/// ///
@ -266,7 +266,7 @@ impl<'c> LocalRequest<'c> {
/// Add a [private cookie] to this request. /// Add a [private cookie] to this request.
/// ///
/// [private cookie]: /rocket/http/enum.Cookies.html#private-cookies /// [private cookie]: ::http::Cookies::add_private()
/// ///
/// # Examples /// # Examples
/// ///
@ -438,12 +438,10 @@ impl<'c> fmt::Debug for LocalRequest<'c> {
/// A structure representing a response from dispatching a local request. /// A structure representing a response from dispatching a local request.
/// ///
/// This structure is a thin wrapper around [`Response`]. It implements no /// This structure is a thin wrapper around [`Response`]. It implements no
/// methods of its own; all functionality is exposed via the `Deref` and /// methods of its own; all functionality is exposed via the [`Deref`] and
/// `DerefMut` implementations with a target of `Response`. In other words, when /// [`DerefMut`] implementations with a target of `Response`. In other words,
/// invoking methods, a `LocalResponse` can be treated exactly as if it were a /// when invoking methods, a `LocalResponse` can be treated exactly as if it
/// `Response`. /// were a `Response`.
///
/// [`Response`]: /rocket/struct.Response.html
pub struct LocalResponse<'c> { pub struct LocalResponse<'c> {
_request: Rc<Request<'c>>, _request: Rc<Request<'c>>,
response: Response<'c>, response: Response<'c>,

11
core/lib/src/outcome.rs
View File

@ -9,11 +9,9 @@
//! processing next. //! processing next.
//! //!
//! The `Outcome` type is the return type of many of the core Rocket traits, //! The `Outcome` type is the return type of many of the core Rocket traits,
//! including [FromRequest](/rocket/request/trait.FromRequest.html), //! including [`FromRequest`](::request::FromRequest),
//! [FromData](/rocket/data/trait.FromData.html), and //! [`FromData`](::data::FromData), and [`Responder`](::response::Responder). It
//! [Responder](/rocket/response/trait.Responder.html). It is also the return //! is also the return type of request handlers via the [`Response`] type.
//! type of request handlers via the
//! [Response](/rocket/response/struct.Response.html) type.
//! //!
//! # Success //! # Success
//! //!
@ -89,8 +87,7 @@ use self::Outcome::*;
/// An enum representing success (`Success`), failure (`Failure`), or /// An enum representing success (`Success`), failure (`Failure`), or
/// forwarding (`Forward`). /// forwarding (`Forward`).
/// ///
/// See the [top level documentation](/rocket/outcome/) for detailed /// See the [top level documentation](::outcome) for detailed information.
/// information.
#[must_use] #[must_use]
#[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Hash)] #[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Hash)]
pub enum Outcome<S, E, F> { pub enum Outcome<S, E, F> {

7
core/lib/src/request/form/error.rs
View File

@ -1,7 +1,8 @@
use std::io; use std::io;
use http::RawStr; use http::RawStr;
/// Error returned by the [`FromForm`] derive on form parsing errors. /// Error returned by the [`FromForm`](::request::FromForm) derive on form
/// parsing errors.
/// ///
/// If multiple errors occur while parsing a form, the first error in the /// If multiple errors occur while parsing a form, the first error in the
/// following precedence, from highest to lowest, is returned: /// following precedence, from highest to lowest, is returned:
@ -21,8 +22,8 @@ pub enum FormParseError<'f> {
Missing(&'f RawStr), Missing(&'f RawStr),
} }
/// Error returned by the [`FromData`] implementations of [`Form`] and /// Error returned by the [`FromData`](::data::FromData) implementations of
/// [`LenientForm`]. /// [`Form`](::request::Form) and [`LenientForm`](::request::LenientForm).
#[derive(Debug)] #[derive(Debug)]
pub enum FormDataError<'f, E> { pub enum FormDataError<'f, E> {
Io(io::Error), Io(io::Error),

10
core/lib/src/request/form/form.rs
View File

@ -7,7 +7,7 @@ use http::{Status, uri::FromUriParam};
/// A data guard for parsing [`FromForm`] types strictly. /// A data guard for parsing [`FromForm`] types strictly.
/// ///
/// This type implements the [`FromData]` trait. It provides a generic means to /// This type implements the [`FromData`] trait. It provides a generic means to
/// parse arbitrary structures from incoming form data. /// parse arbitrary structures from incoming form data.
/// ///
/// # Strictness /// # Strictness
@ -17,7 +17,7 @@ use http::{Status, uri::FromUriParam};
/// error on missing and/or extra fields. For instance, if an incoming form /// error on missing and/or extra fields. For instance, if an incoming form
/// contains the fields "a", "b", and "c" while `T` only contains "a" and "c", /// contains the fields "a", "b", and "c" while `T` only contains "a" and "c",
/// the form _will not_ parse as `Form<T>`. If you would like to admit extra /// the form _will not_ parse as `Form<T>`. If you would like to admit extra
/// fields without error, see [`LenientForm`]. /// fields without error, see [`LenientForm`](::request::LenientForm).
/// ///
/// # Usage /// # Usage
/// ///
@ -96,9 +96,9 @@ use http::{Status, uri::FromUriParam};
/// depends on your use case. The primary question to answer is: _Can the input /// 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 /// contain characters that must be URL encoded?_ Note that this includes
/// common characters such as spaces. If so, then you must use `String`, whose /// common characters such as spaces. If so, then you must use `String`, whose
/// [`FromFormValue`] implementation automatically URL decodes strings. Because /// [`FromFormValue`](::request::FromFormValue) implementation automatically URL
/// the `&RawStr` references will refer directly to the underlying form data, /// decodes strings. Because the `&RawStr` references will refer directly to the
/// they will be raw and URL encoded. /// underlying form data, they will be raw and URL encoded.
/// ///
/// If your string values will not contain URL encoded characters, using /// If your string values will not contain URL encoded characters, using
/// `&RawStr` will result in fewer allocation and is thus preferred. /// `&RawStr` will result in fewer allocation and is thus preferred.

16
core/lib/src/request/form/form_items.rs
View File

@ -41,17 +41,17 @@ use http::RawStr;
/// associated key/value pairs of the form item, either directly access them via /// associated key/value pairs of the form item, either directly access them via
/// the [`key`](FormItem.key) and [`value`](FormItem.value) fields, use the /// the [`key`](FormItem.key) and [`value`](FormItem.value) fields, use the
/// [`FormItem::key_value()`] method to get a tuple of the _raw_ `(key, value)`, /// [`FormItem::key_value()`] method to get a tuple of the _raw_ `(key, value)`,
/// or use the [`FormItems::key_value_decoded()`] method to get a tuple of the /// or use the [`key_value_decoded()`](FormItem::key_value_decoded()) method to
/// decoded (`key`, `value`). /// get a tuple of the decoded (`key`, `value`).
/// ///
/// # Completion /// # Completion
/// ///
/// The iterator keeps track of whether the form string was parsed to completion /// The iterator keeps track of whether the form string was parsed to completion
/// to determine if the form string was malformed. The iterator can be queried /// to determine if the form string was malformed. The iterator can be queried
/// for completion via the [completed](#method.completed) method, which returns /// for completion via the [`completed()`](#method.completed) method, which
/// `true` if the iterator parsed the entire string that was passed to it. The /// returns `true` if the iterator parsed the entire string that was passed to
/// iterator can also attempt to parse any remaining contents via /// it. The iterator can also attempt to parse any remaining contents via
/// [exhaust](#method.exhaust); this method returns `true` if exhaustion /// [`exhaust()`](#method.exhaust); this method returns `true` if exhaustion
/// succeeded. /// succeeded.
/// ///
/// This iterator guarantees that all valid form strings are parsed to /// This iterator guarantees that all valid form strings are parsed to
@ -123,13 +123,13 @@ pub struct FormItem<'f> {
/// ///
/// **Note:** The key is _not_ URL decoded. To URL decode the raw strings, /// **Note:** The key is _not_ URL decoded. To URL decode the raw strings,
/// use the [`RawStr::url_decode()`] method or access key-value pairs with /// use the [`RawStr::url_decode()`] method or access key-value pairs with
/// [`FromItem::key_value_decoded()`]. /// [`key_value_decoded()`](FormItem::key_value_decoded()).
pub key: &'f RawStr, pub key: &'f RawStr,
/// The value for the item, which may be empty if `key` is nonempty. /// The value for the item, which may be empty if `key` is nonempty.
/// ///
/// **Note:** The value is _not_ URL decoded. To URL decode the raw strings, /// **Note:** The value is _not_ URL decoded. To URL decode the raw strings,
/// use the [`RawStr::url_decode()`] method or access key-value pairs with /// use the [`RawStr::url_decode()`] method or access key-value pairs with
/// [`FromItem::key_value_decoded()`]. /// [`key_value_decoded()`](FormItem::key_value_decoded()).
pub value: &'f RawStr pub value: &'f RawStr
} }

27
core/lib/src/request/form/from_form.rs
View File

@ -1,22 +1,21 @@
use request::FormItems; use request::FormItems;
/// Trait to create an instance of some type from an HTTP form. /// Trait to create an instance of some type from an HTTP form.
/// [Form](struct.Form.html) requires its generic type to implement this trait. /// [`Form`](::request::Form) requires its generic type to implement this trait.
/// ///
/// # Deriving /// # Deriving
/// ///
/// This trait can be automatically derived. When deriving `FromForm`, every /// This trait can be automatically derived. When deriving `FromForm`, every
/// field in the structure must implement [`FromFormValue`]. Rocket validates /// field in the structure must implement
/// each field in the structure by calling its `FromFormValue` implementation. /// [`FromFormValue`](::request::FromFormValue). Rocket validates each field in
/// You may wish to implement `FromFormValue` for your own types for custom, /// the structure by calling its `FromFormValue` implementation. You may wish to
/// automatic validation. /// implement `FromFormValue` for your own types for custom, automatic
/// validation.
/// ///
/// ```rust /// ```rust
/// #![feature(proc_macro_hygiene, decl_macro)] /// # #![feature(proc_macro_hygiene, decl_macro)]
/// # #![allow(deprecated, dead_code, unused_attributes)] /// # #![allow(deprecated, dead_code, unused_attributes)]
/// /// # #[macro_use] extern crate rocket;
/// #[macro_use] extern crate rocket;
///
/// #[derive(FromForm)] /// #[derive(FromForm)]
/// struct TodoTask { /// struct TodoTask {
/// description: String, /// description: String,
@ -49,11 +48,11 @@ use request::FormItems;
/// Implementing `FromForm` should be a rare occurrence. Prefer instead to use /// Implementing `FromForm` should be a rare occurrence. Prefer instead to use
/// Rocket's built-in derivation. /// Rocket's built-in derivation.
/// ///
/// When implementing `FromForm`, use the [FormItems](struct.FormItems.html) /// When implementing `FromForm`, use the [`FormItems`] iterator to iterate
/// iterator to iterate through the raw form key/value pairs. Be aware that form /// through the raw form key/value pairs. Be aware that form fields that are
/// fields that are typically hidden from your application, such as `_method`, /// typically hidden from your application, such as `_method`, will be present
/// will be present while iterating. Ensure that you adhere to the properties of /// while iterating. Ensure that you adhere to the properties of the `strict`
/// the `strict` parameter, as detailed in the documentation below. /// parameter, as detailed in the documentation below.
/// ///
/// ## Example /// ## Example
/// ///

4
core/lib/src/request/form/from_form_value.rs
View File

@ -4,7 +4,7 @@ use std::str::FromStr;
use http::RawStr; use http::RawStr;
/// Trait to create instance of some type from a form value; expected from field /// Trait to create instance of some type from a form value; expected from field
/// types in structs deriving `FromForm`. /// types in structs deriving [`FromForm`](::request::FromForm).
/// ///
/// When deriving the `FromForm` trait, Rocket uses the `FromFormValue` /// When deriving the `FromForm` trait, Rocket uses the `FromFormValue`
/// implementation of each field's type to validate the form input. To /// implementation of each field's type to validate the form input. To
@ -67,7 +67,7 @@ use http::RawStr;
/// `"false"`, `"off"`, or not present. In any other case, the raw form /// `"false"`, `"off"`, or not present. In any other case, the raw form
/// value is returned in the `Err` value. /// value is returned in the `Err` value.
/// ///
/// * **&[RawStr](/rocket/http/struct.RawStr.html)** /// * **[`&RawStr`](RawStr)**
/// ///
/// _This implementation always returns successfully._ /// _This implementation always returns successfully._
/// ///

47
core/lib/src/request/from_request.rs
View File

@ -66,26 +66,26 @@ impl<S, E> IntoOutcome<S, (Status, E), ()> for Result<S, E> {
/// ///
/// # Outcomes /// # Outcomes
/// ///
/// The returned [Outcome](/rocket/outcome/index.html) of a `from_request` call /// The returned [`Outcome`] of a `from_request` call determines how the
/// determines how the incoming request will be processed. /// incoming request will be processed.
/// ///
/// * **Success**(S) /// * **Success**(S)
/// ///
/// If the `Outcome` is `Success`, then the `Success` value will be used as /// If the `Outcome` is [`Success`], then the `Success` value will be used as
/// the value for the corresponding parameter. As long as all other guards /// the value for the corresponding parameter. As long as all other guards
/// succeed, the request will be handled. /// succeed, the request will be handled.
/// ///
/// * **Failure**(Status, E) /// * **Failure**(Status, E)
/// ///
/// If the `Outcome` is `Failure`, the request will fail with the given status /// If the `Outcome` is [`Failure`], the request will fail with the given
/// code and error. The designated error /// status code and error. The designated error [`Catcher`](::Catcher) will be
/// [Catcher](/rocket/struct.Catcher.html) will be used to respond to the /// used to respond to the request. Note that users can request types of
/// request. Note that users can request types of `Result<S, E>` and /// `Result<S, E>` and `Option<S>` to catch `Failure`s and retrieve the error
/// `Option<S>` to catch `Failure`s and retrieve the error value. /// value.
/// ///
/// * **Forward** /// * **Forward**
/// ///
/// If the `Outcome` is `Forward`, the request will be forwarded to the next /// If the `Outcome` is [`Forward`], the request will be forwarded to the next
/// matching request. Note that users can request an `Option<S>` to catch /// matching request. Note that users can request an `Option<S>` to catch
/// `Forward`s. /// `Forward`s.
/// ///
@ -96,45 +96,40 @@ impl<S, E> IntoOutcome<S, (Status, E), ()> for Result<S, E> {
/// ///
/// * **Method** /// * **Method**
/// ///
/// Extracts the [Method](/rocket/http/enum.Method.html) from the incoming /// Extracts the [`Method`] from the incoming request.
/// request.
/// ///
/// _This implementation always returns successfully._ /// _This implementation always returns successfully._
/// ///
/// * **&Origin** /// * **&Origin**
/// ///
/// Extracts the [`Origin`](/rocket/http/uri/struct.Origin.html) URI from /// Extracts the [`Origin`] URI from the incoming request.
/// the incoming request.
/// ///
/// _This implementation always returns successfully._ /// _This implementation always returns successfully._
/// ///
/// * **&Route** /// * **&Route**
/// ///
/// Extracts the [Route](/rocket/struct.Route.html) from the request if one /// Extracts the [`Route`] from the request if one is available. If a route
/// is available. If a route is not available, the request is forwarded. /// is not available, the request is forwarded.
/// ///
/// For information on when an `&Route` is available, see the /// For information on when an `&Route` is available, see
/// [`Request::route`](/rocket/struct.Request.html#method.route) /// [`Request::route()`].
/// documentation.
/// ///
/// * **Cookies** /// * **Cookies**
/// ///
/// Returns a borrow to the [Cookies](/rocket/http/enum.Cookies.html) in /// Returns a borrow to the [`Cookies`] in the incoming request. Note that
/// the incoming request. Note that `Cookies` implements internal /// `Cookies` implements internal mutability, so a handle to `Cookies`
/// mutability, so a handle to `Cookies` allows you to get _and_ set cookies /// allows you to get _and_ set cookies in the request.
/// in the request.
/// ///
/// _This implementation always returns successfully._ /// _This implementation always returns successfully._
/// ///
/// * **ContentType** /// * **ContentType**
/// ///
/// Extracts the [ContentType](/rocket/http/struct.ContentType.html) from /// Extracts the [`ContentType`] from the incoming request. If the request
/// the incoming request. If the request didn't specify a Content-Type, the /// didn't specify a Content-Type, the request is forwarded.
/// request is forwarded.
/// ///
/// * **SocketAddr** /// * **SocketAddr**
/// ///
/// Extracts the remote address of the incoming request as a `SocketAddr`. /// Extracts the remote address of the incoming request as a [`SocketAddr`].
/// If the remote address is not known, the request is forwarded. /// If the remote address is not known, the request is forwarded.
/// ///
/// _This implementation always returns successfully._ /// _This implementation always returns successfully._

16
core/lib/src/request/param.rs
View File

@ -79,7 +79,7 @@ use http::{RawStr, uri::{Segments, SegmentError}};
/// type returns successfully. Otherwise, the raw path segment is returned /// type returns successfully. Otherwise, the raw path segment is returned
/// in the `Err` value. /// in the `Err` value.
/// ///
/// * **&[`RawStr`](/rocket/http/struct.RawStr.html)** /// * **[`&RawStr`](RawStr)**
/// ///
/// _This implementation always returns successfully._ /// _This implementation always returns successfully._
/// ///
@ -116,7 +116,7 @@ use http::{RawStr, uri::{Segments, SegmentError}};
/// ///
/// Say you want to parse a segment of the form: /// Say you want to parse a segment of the form:
/// ///
/// ```ignore /// ```text
/// [a-zA-Z]+:[0-9]+ /// [a-zA-Z]+:[0-9]+
/// ``` /// ```
/// ///
@ -271,13 +271,11 @@ impl<'a, T: FromParam<'a>> FromParam<'a> for Option<T> {
/// Trait to convert _many_ dynamic path segment strings to a concrete value. /// Trait to convert _many_ dynamic path segment strings to a concrete value.
/// ///
/// This is the `..` analog to [FromParam](trait.FromParam.html), and its /// This is the `..` analog to [`FromParam`], and its functionality is identical
/// functionality is identical to it with one exception: this trait applies to /// to it with one exception: this trait applies to segment parameters of the
/// segment parameters of the form `<param..>`, where `param` is of some type /// form `<param..>`, where `param` is of some type `T` that implements
/// `T` that implements `FromSegments`. `T::from_segments` is called to convert /// `FromSegments`. `T::from_segments` is called to convert the matched segments
/// the matched segments (via the /// (via the [`Segments`] iterator) into the implementing type.
/// [Segments](/rocket/http/uri/struct.Segments.html) iterator) into the
/// implementing type.
/// ///
/// # Provided Implementations /// # Provided Implementations
/// ///

43
core/lib/src/request/request.rs
View File

@ -23,8 +23,7 @@ type Indices = (usize, usize);
/// The type of an incoming web request. /// The type of an incoming web request.
/// ///
/// This should be used sparingly in Rocket applications. In particular, it /// This should be used sparingly in Rocket applications. In particular, it
/// should likely only be used when writing /// should likely only be used when writing [`FromRequest`] implementations. It
/// [FromRequest](/rocket/request/trait.FromRequest.html) implementations. It
/// contains all of the information for a given web request except for the body /// contains all of the information for a given web request except for the body
/// data. This includes the HTTP method, URI, cookies, headers, and more. /// data. This includes the HTTP method, URI, cookies, headers, and more.
#[derive(Clone)] #[derive(Clone)]
@ -124,7 +123,7 @@ impl<'r> Request<'r> {
self._set_method(method); self._set_method(method);
} }
/// Borrow the `Origin` URI from `self`. /// Borrow the [`Origin`] URI from `self`.
/// ///
/// # Example /// # Example
/// ///
@ -271,9 +270,8 @@ impl<'r> Request<'r> {
/// Returns a wrapped borrow to the cookies in `self`. /// Returns a wrapped borrow to the cookies in `self`.
/// ///
/// [`Cookies`](/rocket/http/enum.Cookies.html) implements internal /// [`Cookies`] implements internal mutability, so this method allows you to
/// mutability, so this method allows you to get _and_ add/remove cookies in /// get _and_ add/remove cookies in `self`.
/// `self`.
/// ///
/// # Example /// # Example
/// ///
@ -303,8 +301,7 @@ impl<'r> Request<'r> {
} }
} }
/// Returns a [`HeaderMap`](/rocket/http/struct.HeaderMap.html) of all of /// Returns a [`HeaderMap`] of all of the headers in `self`.
/// the headers in `self`.
/// ///
/// # Example /// # Example
/// ///
@ -323,8 +320,7 @@ impl<'r> Request<'r> {
/// Add `header` to `self`'s headers. The type of `header` can be any type /// Add `header` to `self`'s headers. The type of `header` can be any type
/// that implements the `Into<Header>` trait. This includes common types /// that implements the `Into<Header>` trait. This includes common types
/// such as [`ContentType`](/rocket/http/struct.ContentType.html) and /// such as [`ContentType`] and [`Accept`].
/// [`Accept`](/rocket/http/struct.Accept.html).
/// ///
/// # Example /// # Example
/// ///
@ -509,16 +505,26 @@ impl<'r> Request<'r> {
/// ///
/// Assuming a `User` request guard exists, invoke it: /// Assuming a `User` request guard exists, invoke it:
/// ///
/// ```rust,ignore /// ```rust
/// # use rocket::Request;
/// # use rocket::http::Method;
/// # type User = Method;
/// # Request::example(Method::Get, "/uri", |request| {
/// let outcome = request.guard::<User>(); /// let outcome = request.guard::<User>();
/// # });
/// ``` /// ```
/// ///
/// Retrieve managed state inside of a guard implementation: /// Retrieve managed state inside of a guard implementation:
/// ///
/// ```rust,ignore /// ```rust
/// # use rocket::Request;
/// # use rocket::http::Method;
/// use rocket::State; /// use rocket::State;
/// ///
/// let pool = request.guard::<State<Pool>>()?; /// # type Pool = usize;
/// # Request::example(Method::Get, "/uri", |request| {
/// let pool = request.guard::<State<Pool>>();
/// # });
/// ``` /// ```
#[inline(always)] #[inline(always)]
pub fn guard<'a, T: FromRequest<'a, 'r>>(&'a self) -> Outcome<T, T::Error> { pub fn guard<'a, T: FromRequest<'a, 'r>>(&'a self) -> Outcome<T, T::Error> {
@ -535,10 +541,9 @@ impl<'r> Request<'r> {
/// ```rust /// ```rust
/// # use rocket::http::Method; /// # use rocket::http::Method;
/// # use rocket::Request; /// # use rocket::Request;
/// # struct User; /// # type User = ();
/// fn current_user(request: &Request) -> User { /// fn current_user(request: &Request) -> User {
/// // Validate request for a given user, load from database, etc. /// // Validate request for a given user, load from database, etc.
/// # User
/// } /// }
/// ///
/// # Request::example(Method::Get, "/uri", |request| { /// # Request::example(Method::Get, "/uri", |request| {
@ -596,8 +601,7 @@ impl<'r> Request<'r> {
/// Retrieves and parses into `T` all of the path segments in the request /// Retrieves and parses into `T` all of the path segments in the request
/// URI beginning and including the 0-indexed `n`th non-empty segment. `T` /// URI beginning and including the 0-indexed `n`th non-empty segment. `T`
/// must implement [FromSegments](/rocket/request/trait.FromSegments.html), /// must implement [`FromSegments`], which is used to parse the segments.
/// which is used to parse the segments.
/// ///
/// This method exists only to be used by manual routing. To retrieve /// This method exists only to be used by manual routing. To retrieve
/// segments from a request, use Rocket's code generation facilities. /// segments from a request, use Rocket's code generation facilities.
@ -676,11 +680,6 @@ impl<'r> Request<'r> {
/// assert_eq!(value(req, "/?a=apple&z=zebra", "apple").as_str(), "n/a"); /// assert_eq!(value(req, "/?a=apple&z=zebra", "apple").as_str(), "n/a");
/// # }); /// # });
/// ``` /// ```
/// # Example
///
/// If the request query is `"/?apple=value_for_a&z=zebra"`, then
/// `request.get_query_value::<T>("z")` will attempt to parse `"zebra"` as
/// type `T`.
#[inline] #[inline]
pub fn get_query_value<'a, T>(&'a self, key: &str) -> Option<Result<T, T::Error>> pub fn get_query_value<'a, T>(&'a self, key: &str) -> Option<Result<T, T::Error>>
where T: FromFormValue<'a> where T: FromFormValue<'a>

21
core/lib/src/request/state.rs
View File

@ -9,10 +9,10 @@ use http::Status;
/// This type can be used as a request guard to retrieve the state Rocket is /// This type can be used as a request guard to retrieve the state Rocket is
/// managing for some type `T`. This allows for the sharing of state across any /// managing for some type `T`. This allows for the sharing of state across any
/// number of handlers. A value for the given type must previously have been /// number of handlers. A value for the given type must previously have been
/// registered to be managed by Rocket via the /// registered to be managed by Rocket via
/// [manage](/rocket/struct.Rocket.html#method.manage) method. The type being /// [`Rocket::manage()`](::Rocket::manage()). The type being managed must be
/// managed must be thread safe and sendable across thread boundaries. In other /// thread safe and sendable across thread boundaries. In other words, it must
/// words, it must implement `Send + Sync + 'static`. /// implement [`Send`] + [`Sync`] + 'static`.
/// ///
/// # Example /// # Example
/// ///
@ -59,11 +59,9 @@ use http::Status;
/// ///
/// Because `State` is itself a request guard, managed state can be retrieved /// Because `State` is itself a request guard, managed state can be retrieved
/// from another request guard's implementation. In the following code example, /// from another request guard's implementation. In the following code example,
/// `Item` retrieves the `MyConfig` managed state in its `FromRequest` /// `Item` retrieves the `MyConfig` managed state in its [`FromRequest`]
/// implementation using the [`Request::guard()`] method. /// implementation using the [`Request::guard()`] method.
/// ///
/// [`Request::guard()`]: /rocket/struct.Request.html#method.guard
///
/// ```rust /// ```rust
/// use rocket::State; /// use rocket::State;
/// use rocket::request::{self, Request, FromRequest}; /// use rocket::request::{self, Request, FromRequest};
@ -86,10 +84,10 @@ pub struct State<'r, T: Send + Sync + 'static>(&'r T);
impl<'r, T: Send + Sync + 'static> State<'r, T> { impl<'r, T: Send + Sync + 'static> State<'r, T> {
/// Retrieve a borrow to the underlying value with a lifetime of `'r`. /// Retrieve a borrow to the underlying value with a lifetime of `'r`.
/// ///
/// Using this method is typically unnecessary as `State` implements `Deref` /// Using this method is typically unnecessary as `State` implements
/// with a `Target` of `T`. This means Rocket will automatically coerce a /// [`Deref`] with a [`Deref::Target`] of `T`. This means Rocket will
/// `State<T>` to an `&T` as required. This method should only be used when /// automatically coerce a `State<T>` to an `&T` as required. This method
/// a longer lifetime is required. /// should only be used when a longer lifetime is required.
/// ///
/// # Example /// # Example
/// ///
@ -116,7 +114,6 @@ impl<'r, T: Send + Sync + 'static> State<'r, T> {
} }
} }
// TODO: Doc.
impl<'a, 'r, T: Send + Sync + 'static> FromRequest<'a, 'r> for State<'r, T> { impl<'a, 'r, T: Send + Sync + 'static> FromRequest<'a, 'r> for State<'r, T> {
type Error = (); type Error = ();

15
core/lib/src/response/flash.rs
View File

@ -12,8 +12,7 @@ use std::sync::atomic::{AtomicBool, Ordering};
const FLASH_COOKIE_NAME: &str = "_flash"; const FLASH_COOKIE_NAME: &str = "_flash";
/// Sets a "flash" cookie that will be removed when it is accessed. The /// Sets a "flash" cookie that will be removed when it is accessed. The
/// analogous request type is /// analogous request type is [`FlashMessage`].
/// [FlashMessage](/rocket/request/type.FlashMessage.html).
/// ///
/// This type makes it easy to send messages across requests. It is typically /// This type makes it easy to send messages across requests. It is typically
/// used for "status" messages after redirects. For instance, if a user attempts /// used for "status" messages after redirects. For instance, if a user attempts
@ -30,9 +29,8 @@ const FLASH_COOKIE_NAME: &str = "_flash";
/// [error](#method.error) constructors create messages with the corresponding /// [error](#method.error) constructors create messages with the corresponding
/// names. /// names.
/// ///
/// Messages can be retrieved on the request side via the /// Messages can be retrieved on the request side via the [`FlashMessage`] type
/// [FlashMessage](/rocket/request/type.FlashMessage.html) type and the /// and the [name](#method.name) and [msg](#method.msg) methods.
/// [name](#method.name) and [msg](#method.msg) methods.
/// ///
/// # Response /// # Response
/// ///
@ -89,8 +87,7 @@ pub struct Flash<R> {
inner: R, inner: R,
} }
/// Type alias to retrieve [`Flash`](/rocket/response/struct.Flash.html) /// Type alias to retrieve [`Flash`] messages from a request.
/// messages from a request.
/// ///
/// # Flash Cookie /// # Flash Cookie
/// ///
@ -101,8 +98,8 @@ pub struct Flash<R> {
/// The flash cookie is cleared if either the [`name()`] or [`msg()`] method is /// The flash cookie is cleared if either the [`name()`] or [`msg()`] method is
/// called. If neither method is called, the flash cookie is not cleared. /// called. If neither method is called, the flash cookie is not cleared.
/// ///
/// [`name()`]: /rocket/response.struct.Flash.html#method.name /// [`name()`]: Flash::name()
/// [`msg()`]: /rocket/response.struct.Flash.html#method.msg /// [`msg()`]: Flash::msg()
pub type FlashMessage<'a, 'r> = ::response::Flash<&'a Request<'r>>; pub type FlashMessage<'a, 'r> = ::response::Flash<&'a Request<'r>>;
impl<'r, R: Responder<'r>> Flash<R> { impl<'r, R: Responder<'r>> Flash<R> {

11
core/lib/src/response/mod.rs
View File

@ -1,8 +1,9 @@
//! Types and traits to build and send responses. //! Types and traits to build and send responses.
//! //!
//! The return type of a Rocket handler can be any type that implements the //! The return type of a Rocket handler can be any type that implements the
//! [Responder](trait.Responder.html) trait. Among other things, this module //! [`Responder`](::response::Responder) trait, which means that the type knows
//! contains several such types. //! how to generate a [`Response`]. Among other things, this module contains
//! several such types.
//! //!
//! # Composing //! # Composing
//! //!
@ -15,9 +16,9 @@
//! //!
//! # Contrib //! # Contrib
//! //!
//! The [`contrib` crate](/rocket_contrib) contains several useful `Responder`s //! The [`contrib` crate](rocket_contrib) contains several useful `Responder`s
//! including [`Template`](/rocket_contrib/struct.Template.html) and //! including [`Template`](rocket_contrib::Template) and
//! [`Json`](/rocket_contrib/struct.Json.html). //! [`Json`](rocket_contrib::Json).
mod responder; mod responder;
mod redirect; mod redirect;

9
core/lib/src/response/named_file.rs
View File

@ -19,7 +19,7 @@ impl NamedFile {
/// ///
/// This function will return an error if path does not already exist. Other /// This function will return an error if path does not already exist. Other
/// errors may also be returned according to /// errors may also be returned according to
/// [OpenOptions::open](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.open). /// [`OpenOptions::open()`](std::fs::OpenOptions::open()).
/// ///
/// # Examples /// # Examples
/// ///
@ -75,10 +75,9 @@ impl NamedFile {
/// Streams the named file to the client. Sets or overrides the Content-Type in /// Streams the named file to the client. Sets or overrides the Content-Type in
/// the response according to the file's extension if the extension is /// the response according to the file's extension if the extension is
/// recognized. See /// recognized. See [`ContentType::from_extension()`] for more information. If
/// [ContentType::from_extension](/rocket/http/struct.ContentType.html#method.from_extension) /// you would like to stream a file with a different Content-Type than that
/// for more information. If you would like to stream a file with a different /// implied by its extension, use a [`File`] directly.
/// Content-Type than that implied by its extension, use a `File` directly.
impl<'r> Responder<'r> for NamedFile { impl<'r> Responder<'r> for NamedFile {
fn respond_to(self, req: &Request) -> response::Result<'r> { fn respond_to(self, req: &Request) -> response::Result<'r> {
let mut response = self.1.respond_to(req)?; let mut response = self.1.respond_to(req)?;

22
core/lib/src/response/responder.rs
View File

@ -9,14 +9,18 @@ use request::Request;
/// Trait implemented by types that generate responses for clients. /// Trait implemented by types that generate responses for clients.
/// ///
/// Types that implement this trait can be used as the return type of a handler, /// Types that implement this trait can be used as the return type of a handler,
/// as illustrated below: /// as illustrated below with `T`:
/// ///
/// ```rust,ignore /// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro)]
/// # #[macro_use] extern crate rocket;
/// # type T = ();
/// #
/// #[get("/")] /// #[get("/")]
/// fn index() -> T { ... } /// fn index() -> T { /* ... */ }
/// ``` /// ```
/// ///
/// In this example, `T` can be any type that implements `Responder`. /// In this example, `T` can be any type, as long as it implements `Responder`.
/// ///
/// # Return Value /// # Return Value
/// ///
@ -66,8 +70,7 @@ use request::Request;
/// ///
/// Responds with a streamed body containing the data in the `File`. No /// Responds with a streamed body containing the data in the `File`. No
/// `Content-Type` is set. To automatically have a `Content-Type` set based /// `Content-Type` is set. To automatically have a `Content-Type` set based
/// on the file's extension, use /// on the file's extension, use [`NamedFile`](::response::NamedFile).
/// [`NamedFile`](/rocket/response/struct.NamedFile.html).
/// ///
/// * **()** /// * **()**
/// ///
@ -107,10 +110,9 @@ use request::Request;
/// ## Joining and Merging /// ## Joining and Merging
/// ///
/// When chaining/wrapping other `Responder`s, use the /// When chaining/wrapping other `Responder`s, use the
/// [merge](/rocket/struct.Response.html#method.merge) or /// [`merge()`](Response::merge()) or [`join()`](Response::join()) methods on
/// [join](/rocket/struct.Response.html#method.join) methods on the `Response` /// the `Response` or `ResponseBuilder` struct. Ensure that you document the
/// or `ResponseBuilder` struct. Ensure that you document the merging or joining /// merging or joining behavior appropriately.
/// behavior appropriately.
/// ///
/// ## Inspecting Requests /// ## Inspecting Requests
/// ///

47
core/lib/src/response/response.rs
View File

@ -98,19 +98,19 @@ impl<T> fmt::Debug for Body<T> {
/// Type for easily building `Response`s. /// Type for easily building `Response`s.
/// ///
/// Building a [Response](struct.Response.html) can be a low-level ordeal; this /// Building a [`Response`] can be a low-level ordeal; this structure presents a
/// structure presents a higher-level API that simplifies building `Response`s. /// higher-level API that simplifies building `Response`s.
/// ///
/// # Usage /// # Usage
/// ///
/// `ResponseBuilder` follows the builder pattern and is usually obtained by /// `ResponseBuilder` follows the builder pattern and is usually obtained by
/// calling [build](struct.Response.html#method.build) on `Response`. Almost all /// calling [`Response::build()`] on `Response`. Almost all methods take the
/// methods take the current builder as a mutable reference and return the same /// current builder as a mutable reference and return the same mutable reference
/// mutable reference with field(s) modified in the `Responder` being built. /// with field(s) modified in the `Responder` being built. These method calls
/// These method calls can be chained: `build.a().b()`. /// can be chained: `build.a().b()`.
/// ///
/// To finish building and retrieve the built `Response`, use the /// To finish building and retrieve the built `Response`, use the
/// [finalize](#method.finalize) or [ok](#method.ok) methods. /// [`finalize()`](#method.finalize) or [`ok()`](#method.ok) methods.
/// ///
/// ## Headers /// ## Headers
/// ///
@ -223,9 +223,8 @@ impl<'r> ResponseBuilder<'r> {
/// value will remain. /// value will remain.
/// ///
/// The type of `header` can be any type that implements `Into<Header>`. /// The type of `header` can be any type that implements `Into<Header>`.
/// This includes `Header` itself, /// This includes `Header` itself, [`ContentType`](::http::ContentType) and
/// [ContentType](/rocket/http/struct.ContentType.html) and [hyper::header /// [hyper::header types](::http::hyper::header).
/// types](/rocket/http/hyper/header/index.html).
/// ///
/// # Example /// # Example
/// ///
@ -254,9 +253,8 @@ impl<'r> ResponseBuilder<'r> {
/// potentially different values to be present in the `Response`. /// potentially different values to be present in the `Response`.
/// ///
/// The type of `header` can be any type that implements `Into<Header>`. /// The type of `header` can be any type that implements `Into<Header>`.
/// This includes `Header` itself, /// This includes `Header` itself, [`ContentType`](::http::ContentType) and
/// [ContentType](/rocket/http/struct.ContentType.html) and [hyper::header /// [hyper::header types](::http::hyper::header).
/// types](/rocket/http/hyper/header/index.html).
/// ///
/// # Example /// # Example
/// ///
@ -557,7 +555,7 @@ impl<'r> ResponseBuilder<'r> {
} }
} }
/// A response, as returned by `Responder`s. /// A response, as returned by types implementing [`Responder`].
#[derive(Default)] #[derive(Default)]
pub struct Response<'r> { pub struct Response<'r> {
status: Option<Status>, status: Option<Status>,
@ -720,8 +718,7 @@ impl<'r> Response<'r> {
cookies cookies
} }
/// Returns a [`HeaderMap`](/rocket/http/struct.HeaderMap.html) of all of /// Returns a [`HeaderMap`] of all of the headers in `self`.
/// the headers in `self`.
/// ///
/// # Example /// # Example
/// ///
@ -746,8 +743,8 @@ impl<'r> Response<'r> {
/// Sets the header `header` in `self`. Any existing headers with the name /// Sets the header `header` in `self`. Any existing headers with the name
/// `header.name` will be lost, and only `header` will remain. The type of /// `header.name` will be lost, and only `header` will remain. The type of
/// `header` can be any type that implements `Into<Header>`. This includes /// `header` can be any type that implements `Into<Header>`. This includes
/// `Header` itself, [`ContentType`](/rocket/http/struct.ContentType.html) /// `Header` itself, [`ContentType`](::http::ContentType) and
/// and [`hyper::header` types](/rocket/http/hyper/header/index.html). /// [`hyper::header` types](::http::hyper::header).
/// ///
/// # Example /// # Example
/// ///
@ -802,8 +799,8 @@ impl<'r> Response<'r> {
/// name `header.name`, another header with the same name and value /// name `header.name`, another header with the same name and value
/// `header.value` is added. The type of `header` can be any type that /// `header.value` is added. The type of `header` can be any type that
/// implements `Into<Header>`. This includes `Header` itself, /// implements `Into<Header>`. This includes `Header` itself,
/// [`ContentType`](/rocket/http/struct.ContentType.html) and /// [`ContentType`](::http::ContentType) and [`hyper::header`
/// [`hyper::header` types](/rocket/http/hyper/header/index.html). /// types](::http::hyper::header).
/// ///
/// # Example /// # Example
/// ///
@ -828,9 +825,9 @@ impl<'r> Response<'r> {
/// Adds a custom header with name `name` and value `value` to `self`. If /// Adds a custom header with name `name` and value `value` to `self`. If
/// `self` already contains headers with the name `name`, another header /// `self` already contains headers with the name `name`, another header
/// with the same `name` and `value` is added. The type of `header` can be /// with the same `name` and `value` is added. The type of `header` can be
/// any type that implements `Into<Header>`. This includes `Header` itself, /// any type implements `Into<Header>`. This includes `Header` itself,
/// [`ContentType`](/rocket/http/struct.ContentType.html) and /// [`ContentType`](::http::ContentType) and [`hyper::header`
/// [`hyper::header` types](/rocket/http/hyper/header/index.html). /// types](::http::hyper::header).
/// ///
/// # Example /// # Example
/// ///
@ -1018,8 +1015,8 @@ impl<'r> Response<'r> {
/// Sets the body of `self` to be `body`, which will be streamed. The chunk /// Sets the body of `self` to be `body`, which will be streamed. The chunk
/// size of the stream is /// size of the stream is
/// [DEFAULT_CHUNK_SIZE](/rocket/response/constant.DEFAULT_CHUNK_SIZE.html). /// [DEFAULT_CHUNK_SIZE](::response::DEFAULT_CHUNK_SIZE). Use
/// Use [set_chunked_body](#method.set_chunked_body) for custom chunk sizes. /// [set_chunked_body](#method.set_chunked_body) for custom chunk sizes.
/// ///
/// # Example /// # Example
/// ///

17
core/lib/src/rocket.rs
View File

@ -330,11 +330,11 @@ impl Rocket {
/// Create a new `Rocket` application using the configuration information in /// Create a new `Rocket` application using the configuration information in
/// `Rocket.toml`. If the file does not exist or if there is an I/O error /// `Rocket.toml`. If the file does not exist or if there is an I/O error
/// reading the file, the defaults are used. See the /// reading the file, the defaults are used. See the [`config`]
/// [config](/rocket/config/index.html) documentation for more information /// documentation for more information on defaults.
/// on defaults.
/// ///
/// This method is typically called through the `rocket::ignite` alias. /// This method is typically called through the
/// [`rocket::ignite()`](::ignite) alias.
/// ///
/// # Panics /// # Panics
/// ///
@ -570,10 +570,9 @@ impl Rocket {
/// refers to a different `T`. /// refers to a different `T`.
/// ///
/// Managed state can be retrieved by any request handler via the /// Managed state can be retrieved by any request handler via the
/// [State](/rocket/struct.State.html) request guard. In particular, if a /// [`State`](::State) request guard. In particular, if a value of type `T`
/// value of type `T` is managed by Rocket, adding `State<T>` to the list of /// is managed by Rocket, adding `State<T>` to the list of arguments in a
/// arguments in a request handler instructs Rocket to retrieve the managed /// request handler instructs Rocket to retrieve the managed value.
/// value.
/// ///
/// # Panics /// # Panics
/// ///
@ -670,8 +669,6 @@ impl Rocket {
/// without first being inspected. See the [`LaunchError`] documentation for /// without first being inspected. See the [`LaunchError`] documentation for
/// more information. /// more information.
/// ///
/// [`LaunchError`]: /rocket/error/struct.LaunchError.html
///
/// # Example /// # Example
/// ///
/// ```rust /// ```rust

1
scripts/bump_version.sh
View File

@ -12,6 +12,7 @@ fi
today=$(date "+%b %d, %Y") today=$(date "+%b %d, %Y")
find . -name "lib.rs" | xargs sed -i.bak "s/${1}/${2}/g"
find . -name "*.toml" | xargs sed -i.bak "s/${1}/${2}/g" find . -name "*.toml" | xargs sed -i.bak "s/${1}/${2}/g"
find site/ -name "*.md" | xargs sed -i.bak "s/${1}/${2}/g" find site/ -name "*.md" | xargs sed -i.bak "s/${1}/${2}/g"
sed -i.bak "s/^date.*/date = \"$today\"/" site/index.toml sed -i.bak "s/^date.*/date = \"$today\"/" site/index.toml