diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md deleted file mode 100644 index ae161595c2..0000000000 --- a/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,55 +0,0 @@ -Hello, and thanks for opening a new issue about Rocket! - -Before opening your issue, we ask that you search through existing issues and -pull requests to see if your bug report, concern, request, or comment has -already been addressed. Ensure to search through both open and closed issues and -pull requests. If this is a question, feature request, or general comment, -please ensure that you have read the relevant sections of the documentation -before posting your issue. Finally, consider asking questions on IRC or Matrix -before opening an issue. - -If you feel confident that your issue is unique, please include the following -information, selecting the category that best describes your issue: - -## Bug Reports - -Bug reports _must_ include: - - 1. The version of Rocket you're using. Ensure it's the latest, if possible. - - 2. The operating system (distribution and version) where the issue occurs. - - 3. A brief description of the bug that includes: - * The nature of the bug. - * When the bug occurs. - * What you expected vs. what actually happened. - - 4. How you uncovered the bug. Short, reproducible tests are especially useful. - - 5. Ideas, if any, about what Rocket is doing incorrectly. - -## Questions - -Any questions _must_ include: - - 1. The version of Rocket this question is based on, if any. - - 2. What steps you've taken to answer the question yourself. - - 3. What documentation you believe should include an answer to this question. - -## Feature Requests - -Feature requests _must_ include: - - 1. Why you believe this feature is necessary. - - 2. A convincing use-case for this feature. - - 3. Why this feature can't or shouldn't exist outside of Rocket. - -## General Comments - -Feel free to comment at will. We simply ask that your comments are well -constructed and actionable. Consider whether IRC or Matrix would be a better -venue for discussion. diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md new file mode 100644 index 0000000000..35055bb14d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -0,0 +1,28 @@ +--- +name: Bug Report +about: Report behavior that deviates from specification or expectation +title: '' +labels: triage +assignees: '' +--- + +**Description** + +A clear and concise description of what the bug is. This should include links to documentation that is contradicted or an explanation of why the present functionality doesn't match your expectation. + +**To Reproduce** + +How to reproduce the bug. A fully working code example (`main.rs` + `Cargo.toml`) is preferred. + +**Expected Behavior** + +A clear and concise description of what you expected to happen. + +**Environment:** + + - OS Distribution and Kernel: [e.g. Arch Linux 4.16.13, macOS 11.2.1] + - Rocket Version: [e.g. 0.4.12, master@abf996b] + +**Additional Context** + +Add any other context about the problem here, for example, how you uncovered the bug or if you have ideas about what/where Rocket is going wrong. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000000..4bd24de5ca --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Question + url: https://github.com/SergioBenitez/Rocket/discussions + about: Please ask questions or raise indefinite concerns on Dicussions diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md new file mode 100644 index 0000000000..72401bf4a8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -0,0 +1,31 @@ +--- +name: Feature Request +about: Propose a change that introduces new functionality +title: '' +labels: request +assignees: '' +--- + +**Is your feature request motivated by a concrete problem? Please describe.** + +A clear and concise description of what the problem is. Examples: + +- "I frequently want to do X, but Rocket makes it hard. It would be nice if Rocket..." +- "I want to do X but Rocket makes it impossible because..." +- "Feature Z exists, but it has these drawbacks. What if..." + +**Why this feature can't or shouldn't live outside of Rocket** + +Rocket is designed to have a small but pluggable core. Feature requests that can be implemented outside of Rocket are typically declined. Make a case for why this feature can't or shouldn't be implemented outside of Rocket. + +**Ideal Solution** + +If you have an idea for a solution, propose it with a clear and concise description. + +**Alternatives Considered** + +A clear and concise description of any alternative solutions or features you've considered. + +**Additional Context** + +Add any other context here, for example, descriptions of elegant solutions in other software. diff --git a/.github/ISSUE_TEMPLATE/suggestion.md b/.github/ISSUE_TEMPLATE/suggestion.md new file mode 100644 index 0000000000..8a07c2ae10 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/suggestion.md @@ -0,0 +1,26 @@ +--- +name: Suggestion +about: Suggest a change or improvement to existing functionality +title: '' +labels: suggestion +assignees: '' +--- + +**Existing Functionality** + +A clear and concise description of existing functionality and why it is insufficient. Examples: + +- "I frequently want to do X, but Rocket makes it hard. It would be nice if..." +- "Feature Z exists, but it has these drawbacks. What if..." + +**Suggested Changes** + +If you have a concrete idea for an improvement, propose it with a clear and concise description. + +**Alternatives Considered** + +A clear and concise description of any alternative solutions using existing features or new features you've considered. + +**Additional Context** + +Add any other context here, for example, descriptions of elegant solutions in other software. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 990252277d..0718c8e832 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,7 +5,6 @@ on: [push, pull_request] env: CARGO_TERM_COLOR: always - jobs: test: name: "${{ matrix.platform.name }} ${{ matrix.test.name }} (${{ matrix.platform.toolchain }})" @@ -23,13 +22,11 @@ jobs: - { name: Contrib, flag: "--contrib" } - { name: Examples, flag: "--examples" } include: - - platform: { name: Linux, distro: ubuntu-latest, toolchain: stable } + - platform: { name: Linux, distro: ubuntu-latest, toolchain: nightly } test: { name: Core, flag: "--core" } - platform: { name: Linux, distro: ubuntu-latest, toolchain: stable } test: { name: Release, flag: "--release" } - continue-on-error: ${{ matrix.platform.toolchain == 'nightly' }} - runs-on: ${{ matrix.platform.distro }} steps: @@ -67,19 +64,21 @@ jobs: profile: minimal toolchain: ${{ matrix.platform.toolchain }} override: true + components: rust-src - name: Cache Example Workspace if: matrix.test.name == 'Examples' - uses: Swatinem/rust-cache@v1 + uses: Swatinem/rust-cache@v2 with: - working-directory: "examples" + workspaces: examples + key: ${{ matrix.test.name }} - name: Cache Root Workspace if: matrix.test.name != 'Examples' - uses: Swatinem/rust-cache@v1 + uses: Swatinem/rust-cache@v2 with: key: ${{ matrix.test.name }} - name: Run Tests - run: ./scripts/test.sh ${{ matrix.test.flag }} + run: ./scripts/test.sh ${{ matrix.test.flag }} -q shell: bash diff --git a/.gitignore b/.gitignore index c041e07a2a..636355078f 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,8 @@ target # Generated databases db.sqlite +db.sqlite-shm +db.sqlite-wal # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html diff --git a/CHANGELOG.md b/CHANGELOG.md index f648c645e4..ae6b331da7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,656 @@ +# Version 0.5.0-rc.2 (May 09, 2022) + +## Major Features and Improvements + + * Introduced [`rocket_db_pools`] for asynchronous database pooling. + * Introduced support for [mutual TLS] and client [`Certificate`]s. + * Added a [`local_cache_once!`] macro for request-local storage. + * Added a [v0.4 to v0.5 migration guide] and [FAQ] to Rocket's website. + * Introduced [shutdown fairings]. + +## Breaking Changes + + * `Hash` `impl`s for `MediaType` and `ContentType` no longer consider media type parameters. + * TLS config values are only available when the `tls` feature is enabled. + * [`MediaType::with_params()`] and [`ContentType::with_params()`] are now builder methods. + * Content-Type [`content`] responder type names are now prefixed with `Raw`. + * The `content::Plain` responder is now called `content::RawText`. + * The `content::Custom` responder was removed in favor of [`(ContentType, T)`]. + * TLS config structs are now only available when the `tls` feature is enabled. + * Removed `CookieJar::get_private_pending()` in favor of [`CookieJar::get_pending()`]. + * The [`local_cache!`] macro accepts fewer types. Use [`local_cache_once!`] as appropriate. + * When requested, the `FromForm` implementations of `Vec` and `Map`s are now properly lenient. + * To concord with browsers, the `[` and `]` characters are now accepted in URI paths. + * The `[` and `]` characters are no longer encoded by [`uri!`]. + * [`Rocket::launch()`] allows `Rocket` recovery by returning the instance after shutdown. + * `ErrorKind::Runtime` was removed; [`ErrorKind::Shutdown`] was added. + +## General Improvements + + * [`Rocket`] is now `#[must_use]`. + * Support for HTTP/2 can be disabled by disabling the default `http2` crate feature. + * Added [`rocket::execute()`] for executing Rocket's `launch()` future. + * Added the [`context!`] macro to [`rocket_dyn_templates`] for ad-hoc template contexts. + * The `time` crate is re-exported from the crate root. + * The `FromForm`, `Responder`, and `UriDisplay` derives now fully support generics. + * Added helper functions to `serde` submodules. + * The [`Shield`] HSTS preload header now includes `includeSubdomains`. + * Logging ignores `write!` errors if `stdout` disappears, preventing panics. + * Added [`Client::terminate()`] to run graceful shutdown in testing. + * Shutdown now terminates the `async` runtime, never the process. + +### HTTP + + * Introduced [`Host`] and the [`&Host`] request guard. + * Added `Markdown` (`text/markdown`) as a known media type. + * Added [`RawStr::percent_encode_bytes()`]. + * `NODELAY` is now enabled on all connections by default. + * The TLS implementation handles handshakes off the main task, improving DoS resistance. + +### Request + + * Added [`Request::host()`] to retrieve the client-requested host. + +### Trait Implementations + + * `Arc`, `Box` where `T: Responder` now implement `Responder`. + * [`Method`] implements `Serialize` and `Deserialize`. + * [`MediaType`] and [`ContentType`] implement `Eq`. + +### Updated Dependencies + + * The `time` dependency was updated to `0.3`. + * The `handlebars` dependency was updated to `4.0`. + * The `memcache` dependency was updated to `0.16`. + * The `rustls` dependency was updated to `0.20`. + +## Infrastructure + + * Rocket now uses the 2021 edition of Rust. + +[`(ContentType, T)`]: https://api.rocket.rs/v0.5-rc/rocket/response/content/index.html#usage +[v0.4 to v0.5 migration guide]: https://rocket.rs/v0.5-rc/guide/upgrading/ +[FAQ]: https://rocket.rs/v0.5-rc/guide/faq/ +[`Rocket::launch()`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html#method.launch +[`ErrorKind::Shutdown`]: https://api.rocket.rs/v0.5-rc/rocket/error/enum.ErrorKind.html#variant.Shutdown +[shutdown fairings]: https://api.rocket.rs/v0.5-rc/rocket/fairing/trait.Fairing.html#shutdown +[`Client::terminate()`]: https://api.rocket.rs/v0.5-rc/rocket/local/blocking/struct.Client.html#method.terminate +[`rocket::execute()`]: https://api.rocket.rs/v0.5-rc/rocket/fn.execute.html +[`CookieJar::get_pending()`]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.CookieJar.html#method.get_pending + +# Version 0.5.0-rc.1 (Jun 09, 2021) + +## Major Features and Improvements + +This release introduces the following major features and improvements: + + * Support for [compilation on Rust's stable] release channel. + * A rewritten, fully asynchronous core with support for [`async`/`await`]. + * [Feature-complete forms support] including multipart, collections, [ad-hoc validation], and + [context](https://rocket.rs/v0.5-rc/guide/requests/#context). + * [Sentinels]: automatic verification of application state at start-up to prevent runtime errors. + * [Graceful shutdown] with configurable signaling, grace periods, notification via [`Shutdown`]. + * An entirely new, flexible and robust [configuration system] based on [Figment]. + * Typed [asynchronous streams] and [Server-Sent Events] with generator syntax. + * Automatic support for HTTP/2 including `h2` ALPN. + * Graduation of `json`, `msgpack`, and `uuid` `rocket_contrib` [features into core]. + * An automatically enabled [`Shield`]: security and privacy headers for all responses. + * Type-system enforced [incoming data limits] to mitigate memory-based DoS attacks. + * Compile-time URI literals via a fully revamped [`uri!`] macro. + * Full support for [UTF-8 characters] in routes and catchers. + * Precise detection of unmanaged state and missing database, template fairings with [sentinels]. + * Typed [build phases] with strict application-level guarantees. + * [Ignorable segments]: wildcard route matching with no typing restrictions. + * First-class [support for `serde`] for built-in guards and types. + * New application launch attributes: + [`#[launch]`](https://api.rocket.rs/v0.5-rc/rocket/attr.launch.html) and + [`#[rocket::main]`](https://api.rocket.rs/v0.5-rc/rocket/attr.main.html). + * [Default catchers] via `#[catch(default)]`, which handle _any_ status code. + * [Catcher scoping] to narrow the scope of a catcher to a URI prefix. + * Built-in libraries and support for [asynchronous testing]. + * A [`TempFile`] data and form guard for automatic uploading to a temporary file. + * A [`Capped`] data and form guard which enables detecting truncation due to data limits. + * Support for dynamic and static prefixing and suffixing of route URIs in [`uri!`]. + * Support for custom config profiles and [automatic typed config extraction]. + * Rewritten, zero-copy, RFC compliant URI parsers with support for URI-[`Reference`]s. + * Multi-segment parameters (``) which match _zero_ segments. + * A [`request::local_cache!`] macro for request-local storage of non-uniquely typed values. + * A [`CookieJar`] without "one-at-a-time" limitations. + * [Singleton fairings] with replacement and guaranteed uniqueness. + * [Data limit declaration in SI units]: "2 MiB", `2.mebibytes()`. + * Optimistic responding even when data is left unread or limits are exceeded. + * Fully decoded borrowed strings as dynamic parameters, form and data guards. + * Borrowed byte slices as data and form guards. + * Fail-fast behavior for [misconfigured secrets], file serving paths. + * Support for generics and custom generic bounds in + [`#[derive(Responder)]`](https://api.rocket.rs/v0.5-rc/rocket/derive.Responder.html). + * [Default ranking colors], which prevent more routing collisions automatically. + * Improved error logging with suggestions when common errors are detected. + * Completely rewritten examples including a new real-time [`chat`] application. + +## Support for Rust Stable + +As a result of support for Rust stable (Rust 2021 Edition and beyond), the +`#![feature(..)]` crate attribute is no longer required for Rocket applications. +The complete canonical example with a single `hello` route becomes: + +```rust +#[macro_use] extern crate rocket; + +#[get("//")] +fn hello(name: &str, age: u8) -> String { + format!("Hello, {} year old named {}!", age, name) +} + +#[launch] +fn rocket() -> _ { + rocket::build().mount("/hello", routes![hello]) +} +``` + +
+ See a diff of the changes from v0.4. + +```diff +- #![feature(proc_macro_hygiene, decl_macro)] +- + #[macro_use] extern crate rocket; + + #[get("//")] +- fn hello(name: String, age: u8) -> String { ++ fn hello(name: &str, age: u8) -> String { + format!("Hello, {} year old named {}!", age, name) +} + +- fn main() { +- rocket::ignite().mount("/hello", routes![hello]).launch(); +- } ++ #[launch] ++ fn rocket() -> _ { ++ rocket::build().mount("/hello", routes![hello]) ++ } +``` + +
+ +## Breaking Changes + +This release includes many breaking changes. The most significant changes are listed below. + +### Silent Changes + +These changes are invisible to the compiler and will _not_ yield errors or warnings at compile-time. +We **strongly** advise all application authors to review this list carefully. + + * Blocking I/O (long running compute, synchronous `sleep()`, `Mutex`, `RwLock`, etc.) may prevent + the server from making progress and should be avoided, replaced with an `async` variant, or + performed in a worker thread. This is a consequence of Rust's cooperative `async` multitasking. + For details, see the new [multitasking] section of the guide. + * `ROCKET_ENV` is now `ROCKET_PROFILE`. A warning is emitted a launch time if the former is set. + * The default profile for debug builds is now `debug`, not `dev`. + * The default profile for release builds is now `release`, not `prod`. + * `ROCKET_LOG` is now `ROCKET_LOG_LEVEL`. A warning is emitted a launch time if the former is set. + * `ROCKET_ADDRESS` accepts only IP addresses, no longer resolves hostnames like `localhost`. + * `ROCKET_CLI_COLORS` accepts booleans `true`, `false` in place of strings `"on"`, `"off"`. + * It is a launch-time error if `secrets` is enabled in non-`debug` profiles without a configured + `secret_key`. + * A misconfigured `template_dir` is reported as an error at launch time. + * [`FileServer::new()`] fails immediately if the provided directory does not exist. + * Catcher collisions result in a launch failure as opposed to a warning. + * Default ranks now range from `-12` to `-1`. There is no breaking change if only code generated + routes are used. Manually configured routes with negative ranks may collide or be considered in + a different order than before. + * The order of execution of path and query guards relative to each other is now unspecified. + * URIs beginning with `:` are properly recognized as invalid and rejected. + * URI normalization now normalizes the query part as well. + * The `Segments` iterator now returns percent-decoded `&str`s. + * Forms are now parsed leniently by the [`Form` guard]. Use [`Strict`] for the previous behavior. + * The `Option` form guard defaults to `None` instead of the default value for `T`. + * When data limits are exceeded, a `413 Payload Too Large` status is returned to the client. + * The default catcher now returns JSON when the client indicates preference via the `Accept` + header. + * Empty boolean form values parse as `true`: the query string `?f` is the same as `?f=true`. + * [`Created`] does not automatically send an `ETag` header if `R: Hash`. Use + [`Created::tagged_body`] instead. + * `FileServer` now forwards when a file is not found instead of failing with `404 Not Found`. + * [`Shield`] is enabled by default. You may need to disable or change policies if your application + depends on typically insecure browser features or if you wish to opt-in to different policies + than the defaults. + * [`CookieJar`] `get()`s do not return cookies added during request handling. See + [`CookieJar`#pending]. + +### Contrib Graduation + + * The `rocket_contrib` crate has been deprecated and should no longer be used. + * Several features previously in `rocket_contrib` were merged into `rocket` itself: + * `json`, `msgpack`, and `uuid` are now [features of `rocket`]. + * Moved `rocket_contrib::json` to [`rocket::serde::json`]. + * Moved `rocket_contrib::msgpack` to [`rocket::serde::msgpack`]. + * Moved `rocket_contrib::uuid` to [`rocket::serde::uuid`]. + * Moved `rocket_contrib::helmet` to [`rocket::shield`]. [`Shield`] is enabled by default. + * Moved `rocket_contrib::serve` to [`rocket::fs`], `StaticFiles` to [`rocket::fs::FileServer`]. + * Removed the now unnecessary `Uuid` and `JsonValue` wrapper types. + * Removed headers in `Shield` that are no longer respected by browsers. + * The remaining features from `rocket_contrib` are now provided by separate crates: + * Replaced `rocket_contrib::templates` with [`rocket_dyn_templates`]. + * Replaced `rocket_contrib::databases` with [`rocket_sync_db_pools`] and [`rocket_db_pools`]. + * These crates are versioned and released independently of `rocket`. + * `rocket_contrib::databases::DbError` is now `rocket_sync_db_pools::Error`. + * Removed `redis`, `mongodb`, and `mysql` integrations which have upstream `async` drivers. + * The [`#[database]`](https://api.rocket.rs/v0.5-rc/rocket_sync_db_pools/attr.database.html) + attribute generates an [`async run()`] method instead of `Deref` implementations. + +### General + + * [`Rocket`] is now generic over a [phase] marker: + * APIs operate on `Rocket`, `Rocket`, `Rocket`, or `Rocket` as + needed. + * The phase marker statically enforces state transitions in `Build`, `Ignite`, `Orbit` order. + * `rocket::ignite()` is now [`rocket::build()`], returns a `Rocket`. + * [`Rocket::ignite()`] transitions to the `Ignite` phase. This is run automatically on launch as + needed. + * Ignition finalizes configuration, runs `ignite` fairings, and verifies [sentinels]. + * [`Rocket::launch()`] transitions into the `Orbit` phase and starts the server. + * Methods like [`Request::rocket()`] that refer to a live Rocket instance return an + `&Rocket`. + * [Fairings] have been reorganized and restructured for `async`: + * Replaced `attach` fairings with `ignite` fairings. Unlike `attach` fairings, which ran + immediately at the time of attachment, `ignite` fairings are run when transitioning into the + `Ignite` phase. + * Replaced `launch` fairings with `liftoff` fairings. `liftoff` fairings are always run, even in + local clients, after the server begins listening and the concrete port is known. + * Introduced a new [configuration system] based on [Figment]: + * The concept of "environments" is replaced with "profiles". + * `ROCKET_ENV` is superseded by `ROCKET_PROFILE`. + * `ROCKET_LOG` is superseded by `ROCKET_LOG_LEVEL`. + * Profile names can now be arbitrarily chosen. The `dev`, `stage`, and `prod` profiles carry no + special meaning. + * The `debug` and `release` profiles are the default profiles for the debug and release + compilation profiles. + * A new specially recognized `default` profile specifies defaults for all profiles. + * The `global` profile has highest precedence, followed by the selected profile, followed by + `default`. + * Added support for limits specified in SI units: "1 MiB". + * Renamed `LoggingLevel` to [`LogLevel`]. + * Inlined error variants into the [`Error`] structure. + * Changed the type of `workers` to `usize` from `u16`. + * Changed accepted values for `keep_alive`: it is disabled with `0`, not `false` or `off`. + * Disabled the `secrets` feature (for private cookies) by default. + * Removed APIs related to "extras". Typed values can be extracted from the configured `Figment`. + * Removed `ConfigBuilder`: all fields of [`Config`] are public with constructors for each field + type. + * Many functions, traits, and trait bounds have been modified for `async`: + * [`FromRequest`], [`Fairing`], [`catcher::Handler`], [`route::Handler`], and [`FromData`] use + `#[async_trait]`. + * [`NamedFile::open`] is now an `async` function. + * Added [`Request::local_cache_async()`] for use in async request guards. + * Unsized `Response` bodies must be [`AsyncRead`] instead of `Read`. + * Automatically sized `Response` bodies must be [`AsyncSeek`] instead of `Seek`. + * The `local` module is split into two: [`rocket::local::asynchronous`] and + [`rocket::local::blocking`]. + * Functionality and features requiring Rust nightly were removed: + * Removed the `Try` implementation on [`Outcome`] which allowed using `?` with `Outcome`s. The + recommended replacement is the [`rocket::outcome::try_outcome!`] macro or the various + combinator functions on `Outcome`. + * [`Result` implements `Responder`] only when both `T` and `E` implement `Responder`. The + new [`Debug`] wrapping responder replaces `Result`. + * APIs which used the `!` type to now use [`std::convert::Infallible`]. + * [`Rocket::register()`] now takes a base path to scope catchers under as its first argument. + * `ErrorKind::Collision` has been renamed to [`ErrorKind::Collisions`]. + +[phase]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html#phases + +### Routing and URIs + + * In `#[route(GET, path = "...")]`, `path` is now `uri`: `#[route(GET, uri = "...")]`. + * Multi-segment paths (`/`) now match _zero_ or more segments. + * Codegen improvements preclude identically named routes and modules in the same namespace. + * A route URI like (`//`) now collides with (`/`), requires a `rank` to resolve. + * All catcher related types and traits moved to [`rocket::catcher`]. + * All route related types and traits moved to [`rocket::route`]. + * URI formatting types and traits moved to [`rocket::http::uri::fmt`]. + * `T` no longer converts to `Option` or `Result` for [`uri!`] query parameters. + * For optional query parameters, [`uri!`] requires using a wrapped value or `_`. + * `&RawStr` no longer implements `FromParam`: use `&str` instead. + * Percent-decoding is performed before calling `FromParam` implementations. + * `RawStr::url_decode()` and `RawStr::url_decode_lossy()` allocate as necessary, return `Cow`. + * `RawStr::from_str()` was replaced with `RawStr::new()`. + * `Origin::segments()` was replaced with `Origin.path().segments()`. + * `Origin::path()` and `Origin::query()` return `&RawStr` instead of `&str`. + * The type of `Route::name` is now `Option>`. + * `Route::set_uri` was replaced with [`Route::map_base()`]. + * `Route::uri()` returns a new [`RouteUri`] type. + * `Route::base` was removed in favor of `Route.uri().base()`. + +[`RouteUri`]: https://api.rocket.rs/v0.5-rc/rocket/route/struct.RouteUri.html + +### Data and Forms + + * `Data` now has a lifetime: `Data<'r>`. + * [`Data::open()`] indelibly requires a data limit. + * Removed `FromDataSimple`. Use [`FromData`] and [`local_cache!`] or [`local_cache_once!`]. + * All [`DataStream`] APIs require limits and return [`Capped`] types. + * Form types and traits were moved from `rocket::request` to [`rocket::form`]. + * Removed `FromQuery`. Dynamic query parameters (`#[get("/?")]`) use [`FromForm`] instead. + * Replaced `FromFormValue` with [`FromFormField`]. All `T: FromFormField` implement `FromForm`. + * Form field values are percent-decoded before calling [`FromFormField`] implementations. + * Renamed the `#[form(field = ...)]` attribute to `#[field(name = ...)]`. + +### Request Guards + + * Renamed `Cookies` to [`CookieJar`]. Its methods take `&self`. + * Renamed `Flash.name` to `Flash.kind`, `Flash.msg` to `Flash.message`. + * Replaced `Request::get_param()` with `Request::param()`. + * Replaced `Request::get_segments()` to `Request::segments()`. + * Replaced `Request::get_query_value()` with `Request::query_value()`. + * Replaced `Segments::into_path_buf()` with `Segments::to_path_buf()`. + * Replaced `Segments` and `QuerySegments` with [`Segments` and `Segments`]. + * [`Flash`] constructors to take `Into` instead of `AsRef`. + * The `State<'_, T>` request guard is now `&State`. + * Removed a lifetime from [`FromRequest`]: `FromRequest<'r>`. + * Removed a lifetime from [`FlashMessage`]: `FlashMessage<'_>`. + * Removed all `State` reexports except [`rocket::State`]. + +### Responders + + * Moved `NamedFile` to `rocket::fs::NamedFile` + * Replaced `Content` with `content::Custom`. + * `Response::body` and `Response::body_mut` are now infallible methods. + * Renamed `ResponseBuilder` to `Builder`. + * Removed direct `Response` body reading methods. Use methods on `r.body_mut()` instead. + * Removed inaccurate "chunked body" types and variants. + * Removed `Responder` `impl` for `Response`. Prefer custom responders with `#[derive(Responder)]`. + * Removed the unused reason phrase from `Status`. + +## General Improvements + +In addition to new features and major improvements, Rocket saw the following improvements: + +### General + + * Added support for [raw identifiers] in the `FromForm` derive, `#[route]` macros, and `uri!`. + * Added support for uncased derived form fields: `#[field(name = uncased(...))]`. + * Added support for [default form field values]: `#[field(default = expr())]`. + * Added support for multiple `#[field]` attributes on struct fields. + * Added support for base16-encoded (a.k.a. hex-encoded) secret keys. + * Added [`Config::ident`] for configuring or removing the global `Server` header. + * Added [`Rocket::figment()`] and [`Rocket::catchers()`]. + * Added [`LocalRequest::json()`] and [`LocalResponse::json()`]. + * Added [`LocalRequest::msgpack()`] and [`LocalResponse::msgpack()`]. + * Added support for `use m::route; routes![route]` instead of needing `routes![m::route]`. + * Added support for [hierarchical data limits]: a limit of `a/b/c` falls back to `a/b` then `a`. + * Added [`LocalRequest::inner_mut()`]. `LocalRequest` implements `DerefMut` to `Request`. + * Added support for ECDSA and EdDSA TLS keys. + * Added associated constants in `Config` for all config parameter names. + * Added `ErrorKind::Config` to represent errors in configuration at runtime. + * Added `rocket::fairing::Result` type alias, returned by `Fairing::on_ignite()`. + * All guard failures are logged at runtime. + * `Rocket::mount()` now accepts a base value of any type that implements `TryInto>`. + * The default error catcher's HTML has been compacted. + * The default error catcher returns JSON if requested by the client. + * Panics in routes or catchers are caught and forwarded to `500` error catcher. + * A detailed warning is emitted if a route or catcher panics. + * Emoji characters are no longer output on Windows. + * Fixed [`Error`] to not panic if a panic is already in progress. + * Introduced [`Reference`] and [`Asterisk`] URI types. + * Added support to [`UriDisplayQuery`] for C-like enums. + * The [`UriDisplayQuery`] derive now recognizes the `#[field]` attribute for field renaming. + * `Client` method builders accept `TryInto` allowing a `uri!()` to be used directly. + * [`Redirect`] now accepts a `TryFrom`, allowing fragment parts. + +### HTTP + + * Added support for HTTP/2, enabled by default via the `http2` crate feature. + * Added AVIF (`image/avif`) as a known media type. + * Added `EventStream` (`text/event-stream`) as a known media type. + * Added a `const` constructor for `MediaType`. + * Added aliases `Text`, `Bytes` for the `Plain`, `Binary` media types, respectively. + * Introduced [`RawStrBuf`], an owned `RawStr`. + * Added many new "pattern" methods to [`RawStr`]. + * Added [`RawStr::percent_encode()`] and [`RawStr::strip()`]. + * Added support for unencoded query characters in URIs that are frequently sent by browsers. + +### Request + + * Added support for all UTF-8 characters in route paths. + * Added support for percent-encoded `:` in socket or IP address values in [`FromFormValue`]. + * Added [`Request::rocket()`] to access the active `Rocket` instance. + * `Request::uri()` now returns an `&Origin<'r>` instead of `&Origin<'_>`. + * `Request::accept()`, `Request::content_type()` reflect changes to `Accept`, `Content-Type`. + * `Json`, `MsgPack` accept `T: Deserialize`, not only `T: DeserializeOwned`. + * Diesel SQLite connections in `rocket_sync_db_pools` use better defaults. + * The default number of workers for synchronous database pools is now `workers * 4`. + +### Response + + * Added [`Template::try_custom()`] for fallible template engine customization. + * Manually registered templates can now be rendered with `Template::render()`. + * Added support for the `X-DNS-Prefetch-Control` header to `Shield`. + * Added support for manually-set `expires` values for private cookies. + * Added support for type generics and custom generic bounds to + [`#[derive(Responder)]`](https://api.rocket.rs/v0.5-rc/rocket/derive.Responder.html). + * The `Server` header is only set if one isn't already set. + * Accurate `Content-Length` headers are sent even for partially read `Body`s. + +### Trait Implementations + + * Implemented `Clone` for `State`. + * Implemented `Copy` and `Clone` for `fairing::Info`. + * Implemented `Debug` for `Rocket` and `Client`. + * Implemented `Default` for `Status` (returns `Status::Ok`). + * Implemented `PartialEq`, `Eq`, `Hash`, `PartialOrd`, and `Ord` for `Status`. + * Implemented `Eq`, `Hash`, and `PartialEq<&str>` for `Origin`. + * Implemented `PartialEq>>` for `RawStr`. + * Implemented `std::error::Error` for `Error`. + * Implemented `Deref` and `DerefMut` for `LocalRequest` (to `Request`). + * Implemented `DerefMut` for `Form`, `LenientForm`. + * Implemented `From` for `Json`, `MsgPack`. + * Implemented `TryFrom` and `TryFrom<&str>` for `Origin`. + * Implemented `TryFrom` for each of the specific URI variants. + * Implemented `FromRequest` for `&Config`. + * Implemented `FromRequest` for `IpAddr`. + * Implemented `FromParam` for `PathBuf` + * Implemented `FromParam`, `FromData`, and `FromForm` for `&str`. + * Implemented `FromForm` for `Json`, `MsgPack`. + * Implemented `FromFormField` for `Cow` and `Capped>` + * Implemented `Responder` for `tokio::fs::File`. + * Implemented `Responder` for `(ContentType, R) where R: Responder`. + * Implemented `Responder` for `(Status, R) where R: Responder` which overrides `R`'s status. + * Implemented `Responder` for `std::io::Error` (behaves as `Debug`). + * Implemented `Responder` for `Either`, equivalently to `Result`. + * Implemented `Serialize` for `Flash`. + * Implemented `Serialize`, `Deserialize`, `UriDisplay` and `FromUriParam` for `uuid::Uuid` + * Implemented `Serialize`, `Deserialize` for `RawStr`. + * Implemented `Serialize`, `Deserialize` for all URI types. + +### Updated Dependencies + + * The `serde` dependency was introduced (`1.0`). + * The `futures` dependency was introduced (`0.3`). + * The `state` dependency was updated to `0.5`. + * The `time` dependency was updated to `0.2`. + * The `binascii` dependency was introduced (`0.1`). + * The `ref-cast` dependency was introduced (`1.0`). + * The `atomic` dependency was introduced (`0.5`). + * The `parking_lot` dependency was introduced (`0.11`). + * The `ubtye` dependency was introduced (`0.10`). + * The `figment` dependency was introduced (`0.10`). + * The `rand` dependency was introduced (`0.8`). + * The `either` dependency was introduced (`1.0`). + * The `pin-project-lite` dependency was introduced (`0.2`). + * The `indexmap` dependency was introduced (`1.0`). + * The `tempfile` dependency was introduced (`3.0`). + * The `async-trait` dependency was introduced (`0.1`). + * The `async-stream` dependency was introduced (`0.3`). + * The `multer` dependency was introduced (`2.0`). + * The `tokio` dependency was introduced (`1.6.1`). + * The `tokio-util` dependency was introduced (`0.6`). + * The `tokio-stream` dependency was introduced (`0.1.6`). + * The `bytes` dependency was introduced (`1.0`). + * The `rmp-serde` dependency was updated to `0.15`. + * The `uuid` dependency was updated to `0.8`. + * The `tera` dependency was updated to `1.10`. + * The `handlebars` dependency was updated to `3.0`. + * The `normpath` dependency was introduced (`0.3`). + * The `postgres` dependency was updated to `0.19`. + * The `rusqlite` dependency was updated to `0.25`. + * The `r2d2_sqlite` dependency was updated to `0.18`. + * The `memcache` dependency was updated to `0.15`. + +## Infrastructure + + * Rocket now uses the 2018 edition of Rust. + * Added visible `use` statements to examples in the guide. + * Split examples into a separate workspace from the non-example crates. + * Updated documentation for all changes. + * Fixed many typos, errors, and broken links throughout documentation and examples. + * Improved the general robustness of macros, and the quality and frequency of error messages. + * Benchmarks now use `criterion` and datasets extracted from real-world projects. + * Fixed the SPDX license expressions in `Cargo.toml` files. + * Added support to `test.sh` for a `+` flag (e.g. `+stable`) to pass to `cargo`. + * Added support to `test.sh` for extra flags to be passed on to `cargo`. + * Migrated CI to Github Actions. + +[`async`/`await`]: https://rocket.rs/v0.5-rc/guide/overview/#async-routes +[compilation on Rust's stable]: https://rocket.rs/v0.5-rc/guide/getting-started/#installing-rust +[Feature-complete forms support]: https://rocket.rs/v0.5-rc/guide/requests/#forms +[configuration system]: https://rocket.rs/v0.5-rc/guide/configuration/#configuration +[graceful shutdown]: https://api.rocket.rs/v0.5-rc/rocket/config/struct.Shutdown.html#summary +[asynchronous testing]: https://rocket.rs/v0.5-rc/guide/testing/#asynchronous-testing +[UTF-8 characters]: https://rocket.rs/v0.5-rc/guide/requests/#static-parameters +[ignorable segments]: https://rocket.rs/v0.5-rc/guide/requests/#ignored-segments +[Catcher scoping]: https://rocket.rs/v0.5-rc/guide/requests/#scoping +[ad-hoc validation]: https://rocket.rs/v0.5-rc/guide/requests#ad-hoc-validation +[incoming data limits]: https://rocket.rs/v0.5-rc/guide/requests/#streaming +[build phases]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html#phases +[Singleton fairings]: https://api.rocket.rs/v0.5-rc/rocket/fairing/trait.Fairing.html#singletons +[features into core]: https://api.rocket.rs/v0.5-rc/rocket/index.html#features +[features of `rocket`]: https://api.rocket.rs/v0.5-rc/rocket/index.html#features +[Data limit declaration in SI units]: https://api.rocket.rs/v0.5-rc/rocket/data/struct.ByteUnit.html +[support for `serde`]: https://api.rocket.rs/v0.5-rc/rocket/serde/index.html +[automatic typed config extraction]: https://api.rocket.rs/v0.5-rc/rocket/fairing/struct.AdHoc.html#method.config +[misconfigured secrets]: https://api.rocket.rs/v0.5-rc/rocket/config/struct.SecretKey.html +[default ranking colors]: https://rocket.rs/v0.5-rc/guide/requests/#default-ranking +[`chat`]: https://github.com/SergioBenitez/Rocket/tree/v0.5-rc/examples/chat +[`Form` guard]: https://api.rocket.rs/v0.5-rc/rocket/form/struct.Form.html +[`Strict`]: https://api.rocket.rs/v0.5-rc/rocket/form/struct.Strict.html +[`CookieJar`#pending]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.CookieJar.html#pending +[`rocket::serde::json`]: https://api.rocket.rs/v0.5-rc/rocket/serde/json/index.html +[`rocket::serde::msgpack`]: https://api.rocket.rs/v0.5-rc/rocket/serde/msgpack/index.html +[`rocket::serde::uuid`]: https://api.rocket.rs/v0.5-rc/rocket/serde/uuid/index.html +[`rocket::shield`]: https://api.rocket.rs/v0.5-rc/rocket/shield/index.html +[`rocket::fs`]: https://api.rocket.rs/v0.5-rc/rocket/fs/index.html +[`async run()`]: https://api.rocket.rs/v0.5-rc/rocket_sync_db_pools/index.html#handlers +[`LocalRequest::json()`]: https://api.rocket.rs/v0.5-rc/rocket/local/blocking/struct.LocalRequest.html#method.json +[`LocalRequest::msgpack()`]: https://api.rocket.rs/v0.5-rc/rocket/local/blocking/struct.LocalRequest.html#method.msgpack +[`LocalResponse::json()`]: https://api.rocket.rs/v0.5-rc/rocket/local/blocking/struct.LocalResponse.html#method.json +[`LocalResponse::msgpack()`]: https://api.rocket.rs/v0.5-rc/rocket/local/blocking/struct.LocalResponse.html#method.msgpack +[hierarchical data limits]: https://api.rocket.rs/v0.5-rc/rocket/data/struct.Limits.html#hierarchy +[default form field values]: https://rocket.rs/v0.5-rc/guide/requests/#defaults +[`Config::ident`]: https://api.rocket.rs/rocket/struct.Config.html#structfield.ident +[`tokio`]: https://tokio.rs/ +[Figment]: https://docs.rs/figment/0.10/figment/ +[`TempFile`]: https://api.rocket.rs/v0.5-rc/rocket/fs/enum.TempFile.html +[`Contextual`]: https://rocket.rs/v0.5-rc/guide/requests/#context +[`Capped`]: https://api.rocket.rs/v0.5-rc/rocket/data/struct.Capped.html +[default catchers]: https://rocket.rs/v0.5-rc/guide/requests/#default-catchers +[URI types]: https://api.rocket.rs/v0.5-rc/rocket/http/uri/index.html +[`uri!`]: https://api.rocket.rs/v0.5-rc/rocket/macro.uri.html +[`Reference`]: https://api.rocket.rs/v0.5-rc/rocket/http/uri/struct.Reference.html +[`Asterisk`]: https://api.rocket.rs/v0.5-rc/rocket/http/uri/struct.Asterisk.html +[`Redirect`]: https://api.rocket.rs/v0.5-rc/rocket/response/struct.Redirect.html +[`UriDisplayQuery`]: https://api.rocket.rs/v0.5-rc/rocket/derive.UriDisplayQuery.html +[`Shield`]: https://api.rocket.rs/v0.5-rc/rocket/shield/struct.Shield.html +[Sentinels]: https://api.rocket.rs/v0.5-rc/rocket/trait.Sentinel.html +[`local_cache!`]: https://api.rocket.rs/v0.5-rc/rocket/request/macro.local_cache.html +[`local_cache_once!`]: https://api.rocket.rs/v0.5-rc/rocket/request/macro.local_cache_once.html +[`CookieJar`]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.CookieJar.html +[asynchronous streams]: https://rocket.rs/v0.5-rc/guide/responses/#async-streams +[Server-Sent Events]: https://api.rocket.rs/v0.5-rc/rocket/response/stream/struct.EventStream.html +[`fs::relative!`]: https://api.rocket.rs/v0.5-rc/rocket/fs/macro.relative.html +[`Shutdown`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Shutdown.html +[`Rocket`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html +[`rocket::build()`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html#method.build +[`Rocket::ignite()`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html#method.ignite +[`Rocket::launch()`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html#method.launch +[`Request::rocket()`]: https://api.rocket.rs/v0.5-rc/rocket/request/struct.Request.html#method.rocket +[Fairings]: https://rocket.rs/v0.5-rc/guide/fairings/ +[configuration system]: https://rocket.rs/v0.5-rc/guide/configuration/ +[`Poolable`]: https://api.rocket.rs/v0.5-rc/rocket_sync_db_pools/trait.Poolable.html +[`Config`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Config.html +[`Error`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Error.html +[`LogLevel`]: https://api.rocket.rs/v0.5-rc/rocket/config/enum.LogLevel.html +[`Rocket::register()`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html#method.register +[`NamedFile::open`]: https://api.rocket.rs/v0.5-rc/rocket/fs/struct.NamedFile.html#method.open +[`Request::local_cache_async()`]: https://api.rocket.rs/v0.5-rc/rocket/request/struct.Request.html#method.local_cache_async +[`FromRequest`]: https://api.rocket.rs/v0.5-rc/rocket/request/trait.FromRequest.html +[`Fairing`]: https://api.rocket.rs/v0.5-rc/rocket/fairing/trait.Fairing.html +[`catcher::Handler`]: https://api.rocket.rs/v0.5-rc/rocket/catcher/trait.Handler.html +[`route::Handler`]: https://api.rocket.rs/v0.5-rc/rocket/route/trait.Handler.html +[`FromData`]: https://api.rocket.rs/v0.5-rc/rocket/data/trait.FromData.html +[`AsyncRead`]: https://docs.rs/tokio/1/tokio/io/trait.AsyncRead.html +[`AsyncSeek`]: https://docs.rs/tokio/1/tokio/io/trait.AsyncSeek.html +[`rocket::local::asynchronous`]: https://api.rocket.rs/v0.5-rc/rocket/local/asynchronous/index.html +[`rocket::local::blocking`]: https://api.rocket.rs/v0.5-rc/rocket/local/blocking/index.html +[`Outcome`]: https://api.rocket.rs/v0.5-rc/rocket/outcome/enum.Outcome.html +[`rocket::outcome::try_outcome!`]: https://api.rocket.rs/v0.5-rc/rocket/outcome/macro.try_outcome.html +[`Result` implements `Responder`]: https://api.rocket.rs/v0.5-rc/rocket/response/trait.Responder.html#provided-implementations +[`Debug`]: https://api.rocket.rs/v0.5-rc/rocket/response/struct.Debug.html +[`std::convert::Infallible`]: https://doc.rust-lang.org/stable/std/convert/enum.Infallible.html +[`ErrorKind::Collisions`]: https://api.rocket.rs/v0.5-rc/rocket/error/enum.ErrorKind.html#variant.Collisions +[`rocket::http::uri::fmt`]: https://api.rocket.rs/v0.5-rc/rocket/http/uri/fmt/index.html +[`Data::open()`]: https://api.rocket.rs/v0.5-rc/rocket/data/struct.Data.html#method.open +[`DataStream`]: https://api.rocket.rs/v0.5-rc/rocket/data/struct.DataStream.html +[`rocket::form`]: https://api.rocket.rs/v0.5-rc/rocket/form/index.html +[`FromFormField`]: https://api.rocket.rs/v0.5-rc/rocket/form/trait.FromFormField.html +[`FromForm`]: https://api.rocket.rs/v0.5-rc/rocket/form/trait.FromForm.html +[`FlashMessage`]: https://api.rocket.rs/v0.5-rc/rocket/request/type.FlashMessage.html +[`Flash`]: https://api.rocket.rs/v0.5-rc/rocket/response/struct.Flash.html +[`rocket::State`]: https://api.rocket.rs/v0.5-rc/rocket/struct.State.html +[`Segments` and `Segments`]: https://api.rocket.rs/v0.5-rc/rocket/http/uri/struct.Segments.html +[`Route::map_base()`]: https://api.rocket.rs/v0.5-rc/rocket/route/struct.Route.html#method.map_base +[`uuid` support]: https://api.rocket.rs/v0.5-rc/rocket/serde/uuid/index.html +[`json`]: https://api.rocket.rs/v0.5-rc/rocket/serde/json/index.html +[`msgpack`]: https://api.rocket.rs/v0.5-rc/rocket/serde/msgpack/index.html +[`rocket::serde::json::json!`]: https://api.rocket.rs/v0.5-rc/rocket/serde/json/macro.json.html +[`rocket::shield::Shield`]: https://api.rocket.rs/v0.5-rc/rocket/shield/struct.Shield.html +[`rocket::fs::FileServer`]: https://api.rocket.rs/v0.5-rc/rocket/fs/struct.FileServer.html +[`rocket_dyn_templates`]: https://api.rocket.rs/v0.5-rc/rocket_dyn_templates/index.html +[`rocket_sync_db_pools`]: https://api.rocket.rs/v0.5-rc/rocket_sync_db_pools/index.html +[multitasking]: https://rocket.rs/v0.5-rc/guide/overview/#multitasking +[`Created`]: https://api.rocket.rs/v0.5-rc/rocket/response/status/struct.Created.html +[`Created::tagged_body`]: https://api.rocket.rs/v0.5-rc/rocket/response/status/struct.Created.html#method.tagged_body +[raw identifiers]: https://doc.rust-lang.org/1.51.0/book/appendix-01-keywords.html#raw-identifiers +[`Rocket::config()`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html#method.config +[`Rocket::figment()`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html#method.figment +[`Rocket::state()`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html#method.state +[`Rocket::catchers()`]: https://api.rocket.rs/v0.5-rc/rocket/struct.Rocket.html#method.catchers +[`LocalRequest::inner_mut()`]: https://api.rocket.rs/v0.5-rc/rocket/local/blocking/struct.LocalRequest.html#method.inner_mut +[`RawStrBuf`]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.RawStrBuf.html +[`RawStr`]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.RawStr.html +[`RawStr::percent_encode()`]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.RawStr.html#method.percent_encode +[`RawStr::percent_encode_bytes()`]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.RawStr.html#method.percent_encode_bytes +[`RawStr::strip()`]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.RawStr.html#method.strip_prefix +[`rocket::catcher`]: https://api.rocket.rs/v0.5-rc/rocket/catcher/index.html +[`rocket::route`]: https://api.rocket.rs/v0.5-rc/rocket/route/index.html +[`Segments::prefix_of()`]: https://api.rocket.rs/v0.5-rc/rocket/http/uri/struct.Segments.html#method.prefix_of +[`Template::try_custom()`]: https://api.rocket.rs/v0.5-rc/rocket_dyn_templates/struct.Template.html#method.try_custom +[`Template::custom`]: https://api.rocket.rs/v0.5-rc/rocket_dyn_templates/struct.Template.html#method.custom +[`FileServer::new()`]: https://api.rocket.rs/v0.5-rc/rocket/fs/struct.FileServer.html#method.new +[`content`]: https://api.rocket.rs/v0.5-rc/rocket/response/content/index.html +[`rocket_db_pools`]: https://api.rocket.rs/v0.5-rc/rocket_db_pools/index.html +[mutual TLS]: https://rocket.rs/v0.5-rc/guide/configuration/#mutual-tls +[`Certificate`]: https://api.rocket.rs/v0.5-rc/rocket/mtls/struct.Certificate.html +[`MediaType::with_params()`]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.MediaType.html#method.with_params +[`ContentType::with_params()`]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.ContentType.html#method.with_params +[`Host`]: https://api.rocket.rs/v0.5-rc/rocket/http/uri/struct.Host.html +[`&Host`]: https://api.rocket.rs/v0.5-rc/rocket/http/uri/struct.Host.html +[`Request::host()`]: https://api.rocket.rs/v0.5-rc/rocket/request/struct.Request.html#method.host +[`context!`]: https://api.rocket.rs/v0.5-rc/rocket_dyn_templates/macro.context.html +[`MediaType`]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.MediaType.html +[`ContentType`]: https://api.rocket.rs/v0.5-rc/rocket/http/struct.ContentType.html +[`Method`]: https://api.rocket.rs/v0.5-rc/rocket/http/enum.Method.html + # Version 0.4.10 (May 21, 2021) ## Core @@ -150,7 +803,7 @@ ## Core * Replaced use of `FnBox` with `Box`. - * Removed the stablized feature gates `try_from` and `transpose_result`. + * Removed the stable feature gates `try_from` and `transpose_result`. * Derive macros are reexported alongside their respective traits. * Minimum required `rustc` is `1.35.0-nightly (2019-04-05)`. @@ -903,7 +1556,7 @@ This release includes the following new features: * `&Route` is now a request guard. * The base mount path of a [`Route`] can be retrieved via `Route::base` or `Route::base()`. - * [`Cookies`] supports _private_ (authenticated encryption) cookies, encryped + * [`Cookies`] supports _private_ (authenticated encryption) cookies, encrypted with the `secret_key` config key. * `Config::{development, staging, production}` constructors were added for [`Config`]. @@ -1062,7 +1715,7 @@ applications. * **[`ContentType::from_extension()`] returns an `Option`.** - For the old behvavior, use `.unwrap_or(ContentType::Any)`. + For the old behavior, use `.unwrap_or(ContentType::Any)`. * **The `IntoValue` config trait was removed in favor of `Into`.** @@ -1095,7 +1748,7 @@ applications. In addition to new features, Rocket saw the following improvements: - * "Rocket" is now capatilized in the `Server` HTTP header. + * "Rocket" is now capitalized in the `Server` HTTP header. * The generic parameter of `rocket_contrib::Json` defaults to `json::Value`. * The trailing '...' in the launch message was removed. * The launch message prints regardless of the config environment. @@ -1475,7 +2128,7 @@ now implements its own `Request` and `Response` types. * `ContentType` uses associated constants instead of static methods. * `StatusCode` removed in favor of new `Status` type. - * `Response` type alias superceded by `Response` type. + * `Response` type alias superseded by `Response` type. * `Responder::respond` no longer takes in hyper type. * `Responder::respond` returns `Response`, takes `self` by move. * `Handler` returns `Outcome` instead of `Response` type alias. @@ -1613,4 +2266,3 @@ the Rocket APIs. They are summarized through the following API changes: ## Testing * Add a significant number of codegen tests. - diff --git a/Cargo.toml b/Cargo.toml index 52fc6a68b5..8ec081ef00 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,6 +3,8 @@ members = [ "core/lib/", "core/codegen/", "core/http/", + "contrib/db_pools/codegen/", + "contrib/db_pools/lib/", "contrib/sync_db_pools/codegen/", "contrib/sync_db_pools/lib/", "contrib/dyn_templates/", diff --git a/README.md b/README.md index 2ec2da9090..bb061b5e1a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Rocket Homepage](https://img.shields.io/badge/web-rocket.rs-red.svg?style=flat&label=https&colorB=d33847)](https://rocket.rs) [![Current Crates.io Version](https://img.shields.io/crates/v/rocket.svg)](https://crates.io/crates/rocket) [![Matrix: #rocket:mozilla.org](https://img.shields.io/badge/style-%23rocket:mozilla.org-blue.svg?style=flat&label=[m])](https://chat.mozilla.org/#/room/#rocket:mozilla.org) -[![IRC: #rocket on chat.freenode.net](https://img.shields.io/badge/style-%23rocket-blue.svg?style=flat&label=freenode)](https://kiwiirc.com/client/chat.freenode.net/#rocket) +[![IRC: #rocket on irc.libera.chat](https://img.shields.io/badge/style-%23rocket-blue.svg?style=flat&label=Libera.Chat)](https://kiwiirc.com/client/irc.libera.chat/#rocket) Rocket is an async web framework for Rust with a focus on usability, security, extensibility, and speed. @@ -45,14 +45,14 @@ Rocket is extensively documented: [API Documentation]: https://api.rocket.rs/rocket/ The official community support channels are [`#rocket:mozilla.org`] on Matrix -and the bridged [`#rocket`] IRC channel on Freenode at `chat.freenode.net`. We +and the bridged [`#rocket`] IRC channel on Libera.Chat at `irc.libera.chat`. We recommend joining us on [Matrix via Element]. If your prefer IRC, you can join via the [Kiwi IRC client] or a client of your own. [`#rocket:mozilla.org`]: https://chat.mozilla.org/#/room/#rocket:mozilla.org -[`#rocket`]: https://kiwiirc.com/client/chat.freenode.net/#rocket +[`#rocket`]: https://kiwiirc.com/client/irc.libera.chat/#rocket [Matrix via Element]: https://chat.mozilla.org/#/room/#rocket:mozilla.org -[Kiwi IRC Client]: https://kiwiirc.com/client/chat.freenode.net/#rocket +[Kiwi IRC Client]: https://kiwiirc.com/client/irc.libera.chat/#rocket ## Examples diff --git a/benchmarks/Cargo.toml b/benchmarks/Cargo.toml index ab1893f4c1..fb97a0fc15 100644 --- a/benchmarks/Cargo.toml +++ b/benchmarks/Cargo.toml @@ -1,12 +1,16 @@ [package] name = "rocket-benchmarks" version = "0.0.0" -edition = "2018" +edition = "2021" publish = false [workspace] -[dependencies] +[[bench]] +name = "main" +path = "src/bench.rs" +harness = false + +[dev-dependencies] rocket = { path = "../core/lib/" } criterion = "0.3" -criterion-macro = "0.3" diff --git a/benchmarks/src/bench.rs b/benchmarks/src/bench.rs new file mode 100644 index 0000000000..8a76d89edd --- /dev/null +++ b/benchmarks/src/bench.rs @@ -0,0 +1,3 @@ +mod routing; + +criterion::criterion_main!(routing::routing); diff --git a/benchmarks/src/main.rs b/benchmarks/src/main.rs deleted file mode 100644 index c0e4f47032..0000000000 --- a/benchmarks/src/main.rs +++ /dev/null @@ -1,11 +0,0 @@ -#![feature(custom_test_frameworks)] -#![test_runner(criterion::runner)] - -#[cfg_attr(test, macro_use)] -extern crate criterion_macro; - -#[cfg(test)] mod routing; - -pub fn main() { - eprintln!("help: cargo bench"); -} diff --git a/benchmarks/src/routing.rs b/benchmarks/src/routing.rs index a0521cea91..c4fb8238a9 100644 --- a/benchmarks/src/routing.rs +++ b/benchmarks/src/routing.rs @@ -1,12 +1,12 @@ use std::collections::hash_set::HashSet; -use criterion::Criterion; +use criterion::{criterion_group, Criterion}; use rocket::{route, config, Request, Data, Route, Config}; use rocket::http::{Method, RawStr, ContentType, Accept, Status}; use rocket::local::blocking::{Client, LocalRequest}; -fn dummy_handler<'r>(req: &'r Request, _: Data) -> route::BoxFuture<'r> { +fn dummy_handler<'r>(req: &'r Request, _: Data<'r>) -> route::BoxFuture<'r> { route::Outcome::from(req, ()).pin() } @@ -84,6 +84,7 @@ fn client(routes: Vec) -> Client { cli_colors: false, shutdown: config::Shutdown { ctrlc: false, + #[cfg(unix)] signals: HashSet::new(), ..Default::default() }, @@ -99,7 +100,6 @@ fn client(routes: Vec) -> Client { } } -#[criterion] pub fn bench_rust_lang_routes(c: &mut Criterion) { let table = include_str!("../static/rust-lang.routes"); let routes = parse_routes_table(table); @@ -113,7 +113,6 @@ pub fn bench_rust_lang_routes(c: &mut Criterion) { })); } -#[criterion] pub fn bench_bitwarden_routes(c: &mut Criterion) { let table = include_str!("../static/bitwarden_rs.routes"); let routes = parse_routes_table(table); @@ -127,3 +126,4 @@ pub fn bench_bitwarden_routes(c: &mut Criterion) { })); } +criterion_group!(routing, bench_rust_lang_routes, bench_bitwarden_routes); diff --git a/contrib/db_pools/README.md b/contrib/db_pools/README.md new file mode 100644 index 0000000000..b5b1fde509 --- /dev/null +++ b/contrib/db_pools/README.md @@ -0,0 +1,67 @@ +# `db_pools` [![ci.svg]][ci] [![crates.io]][crate] [![docs.svg]][crate docs] + +[crates.io]: https://img.shields.io/crates/v/rocket_db_pools.svg +[crate]: https://crates.io/crates/rocket_db_pools +[docs.svg]: https://img.shields.io/badge/web-master-red.svg?style=flat&label=docs&colorB=d33847 +[crate docs]: https://api.rocket.rs/v0.5-rc/rocket_db_pools +[ci.svg]: https://github.com/SergioBenitez/Rocket/workflows/CI/badge.svg +[ci]: https://github.com/SergioBenitez/Rocket/actions + +Asynchronous database driver integration for Rocket. See the [crate docs] for +full usage details. + +## Usage + +1. Add `rocket_db_pools` as a dependency with one or more [database driver + features] enabled: + + ```toml + [dependencies.rocket_db_pools] + version = "0.1.0-rc.2" + features = ["sqlx_sqlite"] + ``` + +2. Choose a name for your database, here `sqlite_logs`. [Configure] _at least_ a + URL for the database: + + ```toml + [default.databases.sqlite_logs] + url = "/path/to/database.sqlite" + ``` + +3. [Derive `Database`] for a unit type (`Logs` here) which + wraps the selected driver's [`Pool`] type and is decorated with + `#[database("name")]`. Attach `Type::init()` to your application's `Rocket` + to initialize the database pool: + + ```rust + use rocket_db_pools::{Database, Connection}; + + #[derive(Database)] + #[database("sqlite_logs")] + struct Logs(sqlx::SqlitePool); + + #[launch] + fn rocket() -> _ { + rocket::build().attach(Logs::init()) + } + ``` + +4. Use [`Connection`] as a request guard to retrieve an + active database connection: + + ```rust + #[get("/")] + async fn read(mut db: Connection, id: i64) -> Result { + sqlx::query!("SELECT content FROM logs WHERE id = ?", id) + .fetch_one(&mut *db) + .map_ok(|r| Log(r.content)) + .await + } + ``` + +[database driver features]: https://api.rocket.rs/v0.5-rc/rocket_db_pools/index.html#supported-drivers +[`Pool`]: https://api.rocket.rs/v0.5-rc/rocket_db_pools/index.html#supported-drivers +[Configure]: https://api.rocket.rs/v0.5-rc/rocket_db_pools/index.html#configuration +[Derive `Database`]: https://api.rocket.rs/v0.5-rc/rocket_db_pools/derive.Database.html +[`Connection`]: https://api.rocket.rs/v0.5-rc/rocket_db_pools/struct.Connection.html diff --git a/contrib/db_pools/codegen/Cargo.toml b/contrib/db_pools/codegen/Cargo.toml new file mode 100644 index 0000000000..3ad2e78b45 --- /dev/null +++ b/contrib/db_pools/codegen/Cargo.toml @@ -0,0 +1,24 @@ +[package] +name = "rocket_db_pools_codegen" +version = "0.1.0-rc.2" +authors = ["Sergio Benitez ", "Jeb Rosen "] +description = "Procedural macros for rocket_db_pools." +repository = "https://github.com/SergioBenitez/Rocket/contrib/db_pools" +readme = "../README.md" +keywords = ["rocket", "framework", "database", "pools"] +license = "MIT OR Apache-2.0" +edition = "2021" +rust-version = "1.56" + +[lib] +proc-macro = true + +[dependencies] +devise = "0.3" +quote = "1" + +[dev-dependencies] +rocket = { path = "../../../core/lib", default-features = false } +rocket_db_pools = { path = "../lib", features = ["deadpool_postgres"] } +trybuild = "1.0" +version_check = "0.9" diff --git a/contrib/db_pools/codegen/src/database.rs b/contrib/db_pools/codegen/src/database.rs new file mode 100644 index 0000000000..837aa6c8ac --- /dev/null +++ b/contrib/db_pools/codegen/src/database.rs @@ -0,0 +1,110 @@ +use proc_macro::TokenStream; + +use devise::{DeriveGenerator, FromMeta, MapperBuild, Support, ValidatorBuild}; +use devise::proc_macro2_diagnostics::SpanDiagnosticExt; +use devise::syn::{self, spanned::Spanned}; + +const ONE_DATABASE_ATTR: &str = "missing `#[database(\"name\")]` attribute"; +const ONE_UNNAMED_FIELD: &str = "struct must have exactly one unnamed field"; + +#[derive(Debug, FromMeta)] +struct DatabaseAttribute { + #[meta(naked)] + name: String, +} + +pub fn derive_database(input: TokenStream) -> TokenStream { + DeriveGenerator::build_for(input, quote!(impl rocket_db_pools::Database)) + .support(Support::TupleStruct) + .validator(ValidatorBuild::new() + .struct_validate(|_, s| { + if s.fields.len() == 1 { + Ok(()) + } else { + Err(s.span().error(ONE_UNNAMED_FIELD)) + } + }) + ) + .outer_mapper(MapperBuild::new() + .struct_map(|_, s| { + let pool_type = match &s.fields { + syn::Fields::Unnamed(f) => &f.unnamed[0].ty, + _ => unreachable!("Support::TupleStruct"), + }; + + let decorated_type = &s.ident; + let db_ty = quote_spanned!(decorated_type.span() => + <#decorated_type as rocket_db_pools::Database> + ); + + quote_spanned! { decorated_type.span() => + impl From<#pool_type> for #decorated_type { + fn from(pool: #pool_type) -> Self { + Self(pool) + } + } + + impl std::ops::Deref for #decorated_type { + type Target = #pool_type; + + fn deref(&self) -> &Self::Target { + &self.0 + } + } + + impl std::ops::DerefMut for #decorated_type { + fn deref_mut(&mut self) -> &mut Self::Target { + &mut self.0 + } + } + + #[rocket::async_trait] + impl<'r> rocket::request::FromRequest<'r> for &'r #decorated_type { + type Error = (); + + async fn from_request( + req: &'r rocket::request::Request<'_> + ) -> rocket::request::Outcome { + match #db_ty::fetch(req.rocket()) { + Some(db) => rocket::outcome::Outcome::Success(db), + None => rocket::outcome::Outcome::Failure(( + rocket::http::Status::InternalServerError, ())) + } + } + } + + impl rocket::Sentinel for &#decorated_type { + fn abort(rocket: &rocket::Rocket) -> bool { + #db_ty::fetch(rocket).is_none() + } + } + } + }) + ) + .outer_mapper(quote!(#[rocket::async_trait])) + .inner_mapper(MapperBuild::new() + .try_struct_map(|_, s| { + let db_name = DatabaseAttribute::one_from_attrs("database", &s.attrs)? + .map(|attr| attr.name) + .ok_or_else(|| s.span().error(ONE_DATABASE_ATTR))?; + + let fairing_name = format!("'{}' Database Pool", db_name); + + let pool_type = match &s.fields { + syn::Fields::Unnamed(f) => &f.unnamed[0].ty, + _ => unreachable!("Support::TupleStruct"), + }; + + Ok(quote_spanned! { pool_type.span() => + type Pool = #pool_type; + + const NAME: &'static str = #db_name; + + fn init() -> rocket_db_pools::Initializer { + rocket_db_pools::Initializer::with_name(#fairing_name) + } + }) + }) + ) + .to_tokens() +} diff --git a/contrib/db_pools/codegen/src/lib.rs b/contrib/db_pools/codegen/src/lib.rs new file mode 100644 index 0000000000..00c423efd7 --- /dev/null +++ b/contrib/db_pools/codegen/src/lib.rs @@ -0,0 +1,61 @@ +#![recursion_limit="256"] +#![warn(rust_2018_idioms)] + +//! # `rocket_db_pool` - Code Generation +//! +//! Implements the code generation portion of the `rocket_db_pool` crate. This +//! is an implementation detail. This create should never be depended on +//! directly. + +#[macro_use] extern crate quote; + +mod database; + +/// Automatic derive for the [`Database`] trait. +/// +/// ```rust +/// use rocket_db_pools::Database; +/// # type PoolType = rocket_db_pools::deadpool_postgres::Pool; +/// +/// #[derive(Database)] +/// #[database("database_name")] +/// struct Db(PoolType); +/// ``` +/// +/// The derive generates an implementation of [`Database`] as follows: +/// +/// * [`Database::NAME`] is set to the value in the `#[database("name")]` +/// attribute. +/// +/// This names the database, providing an anchor to configure the database via +/// `Rocket.toml` or any other configuration source. Specifically, the +/// configuration in `databases.name` is used to configure the driver. +/// +/// * [`Database::Pool`] is set to the wrapped type: `PoolType` above. The type +/// must implement [`Pool`]. +/// +/// To meet the required [`Database`] supertrait bounds, this derive also +/// generates implementations for: +/// +/// * `From` +/// +/// * `Deref` +/// +/// * `DerefMut` +/// +/// * `FromRequest<'_> for &Db` +/// +/// * `Sentinel for &Db` +/// +/// The `Deref` impls enable accessing the database pool directly from +/// references `&Db` or `&mut Db`. To force a dereference to the underlying +/// type, use `&db.0` or `&**db` or their `&mut` variants. +/// +/// [`Database`]: ../rocket_db_pools/trait.Database.html +/// [`Database::NAME`]: ../rocket_db_pools/trait.Database.html#associatedconstant.NAME +/// [`Database::Pool`]: ../rocket_db_pools/trait.Database.html#associatedtype.Pool +/// [`Pool`]: ../rocket_db_pools/trait.Pool.html +#[proc_macro_derive(Database, attributes(database))] +pub fn derive_database(input: proc_macro::TokenStream) -> proc_macro::TokenStream { + crate::database::derive_database(input) +} diff --git a/contrib/db_pools/codegen/tests/ui-fail-nightly/database-syntax.rs b/contrib/db_pools/codegen/tests/ui-fail-nightly/database-syntax.rs new file mode 120000 index 0000000000..717e99bd0e --- /dev/null +++ b/contrib/db_pools/codegen/tests/ui-fail-nightly/database-syntax.rs @@ -0,0 +1 @@ +../ui-fail/database-syntax.rs \ No newline at end of file diff --git a/contrib/db_pools/codegen/tests/ui-fail-nightly/database-syntax.stderr b/contrib/db_pools/codegen/tests/ui-fail-nightly/database-syntax.stderr new file mode 100644 index 0000000000..052998eab0 --- /dev/null +++ b/contrib/db_pools/codegen/tests/ui-fail-nightly/database-syntax.stderr @@ -0,0 +1,109 @@ +error: invalid value: expected string literal + --> tests/ui-fail-nightly/database-syntax.rs:4:12 + | +4 | #[database(123)] + | ^^^ + | +note: error occurred while deriving `Database` + --> tests/ui-fail-nightly/database-syntax.rs:3:10 + | +3 | #[derive(Database)] + | ^^^^^^^^ + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: expected key/value `key = value` + --> tests/ui-fail-nightly/database-syntax.rs:8:25 + | +8 | #[database("some-name", "another")] + | ^^^^^^^^^ + | +note: error occurred while deriving `Database` + --> tests/ui-fail-nightly/database-syntax.rs:7:10 + | +7 | #[derive(Database)] + | ^^^^^^^^ + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: unexpected attribute parameter: `name` + --> tests/ui-fail-nightly/database-syntax.rs:12:25 + | +12 | #[database("some-name", name = "another")] + | ^^^^^^^^^^^^^^^^ + | +note: error occurred while deriving `Database` + --> tests/ui-fail-nightly/database-syntax.rs:11:10 + | +11 | #[derive(Database)] + | ^^^^^^^^ + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: enums are not supported + --> tests/ui-fail-nightly/database-syntax.rs:16:1 + | +16 | / #[database("foo")] +17 | | enum D { } + | |___________^ + | +note: error occurred while deriving `Database` + --> tests/ui-fail-nightly/database-syntax.rs:15:10 + | +15 | #[derive(Database)] + | ^^^^^^^^ + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: missing `#[database("name")]` attribute + --> tests/ui-fail-nightly/database-syntax.rs:20:1 + | +20 | struct E(deadpool_postgres::Pool); + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +note: error occurred while deriving `Database` + --> tests/ui-fail-nightly/database-syntax.rs:19:10 + | +19 | #[derive(Database)] + | ^^^^^^^^ + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: struct must have exactly one unnamed field + --> tests/ui-fail-nightly/database-syntax.rs:23:1 + | +23 | / #[database("foo")] +24 | | struct F; + | |_________^ + | +note: error occurred while deriving `Database` + --> tests/ui-fail-nightly/database-syntax.rs:22:10 + | +22 | #[derive(Database)] + | ^^^^^^^^ + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: struct must have exactly one unnamed field + --> tests/ui-fail-nightly/database-syntax.rs:27:1 + | +27 | / #[database("foo")] +28 | | struct G(deadpool_postgres::Pool, deadpool_postgres::Pool); + | |___________________________________________________________^ + | +note: error occurred while deriving `Database` + --> tests/ui-fail-nightly/database-syntax.rs:26:10 + | +26 | #[derive(Database)] + | ^^^^^^^^ + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: named structs are not supported + --> tests/ui-fail-nightly/database-syntax.rs:31:1 + | +31 | / #[database("foo")] +32 | | struct H { +33 | | foo: deadpool_postgres::Pool, +34 | | } + | |_^ + | +note: error occurred while deriving `Database` + --> tests/ui-fail-nightly/database-syntax.rs:30:10 + | +30 | #[derive(Database)] + | ^^^^^^^^ + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) diff --git a/contrib/db_pools/codegen/tests/ui-fail-nightly/database-types.rs b/contrib/db_pools/codegen/tests/ui-fail-nightly/database-types.rs new file mode 120000 index 0000000000..98c58fba54 --- /dev/null +++ b/contrib/db_pools/codegen/tests/ui-fail-nightly/database-types.rs @@ -0,0 +1 @@ +../ui-fail/database-types.rs \ No newline at end of file diff --git a/contrib/db_pools/codegen/tests/ui-fail-nightly/database-types.stderr b/contrib/db_pools/codegen/tests/ui-fail-nightly/database-types.stderr new file mode 100644 index 0000000000..2be0fb4ad3 --- /dev/null +++ b/contrib/db_pools/codegen/tests/ui-fail-nightly/database-types.stderr @@ -0,0 +1,25 @@ +error[E0277]: the trait bound `Unknown: Pool` is not satisfied + --> tests/ui-fail-nightly/database-types.rs:7:10 + | +7 | struct A(Unknown); + | ^^^^^^^ the trait `Pool` is not implemented for `Unknown` + | + = help: the trait `Pool` is implemented for `deadpool::managed::Pool` +note: required by a bound in `rocket_db_pools::Database::Pool` + --> $WORKSPACE/contrib/db_pools/lib/src/database.rs + | + | type Pool: Pool; + | ^^^^ required by this bound in `rocket_db_pools::Database::Pool` + +error[E0277]: the trait bound `Vec: Pool` is not satisfied + --> tests/ui-fail-nightly/database-types.rs:11:10 + | +11 | struct B(Vec); + | ^^^^^^^^ the trait `Pool` is not implemented for `Vec` + | + = help: the trait `Pool` is implemented for `deadpool::managed::Pool` +note: required by a bound in `rocket_db_pools::Database::Pool` + --> $WORKSPACE/contrib/db_pools/lib/src/database.rs + | + | type Pool: Pool; + | ^^^^ required by this bound in `rocket_db_pools::Database::Pool` diff --git a/contrib/db_pools/codegen/tests/ui-fail-stable/database-syntax.rs b/contrib/db_pools/codegen/tests/ui-fail-stable/database-syntax.rs new file mode 120000 index 0000000000..717e99bd0e --- /dev/null +++ b/contrib/db_pools/codegen/tests/ui-fail-stable/database-syntax.rs @@ -0,0 +1 @@ +../ui-fail/database-syntax.rs \ No newline at end of file diff --git a/contrib/db_pools/codegen/tests/ui-fail-stable/database-syntax.stderr b/contrib/db_pools/codegen/tests/ui-fail-stable/database-syntax.stderr new file mode 100644 index 0000000000..8f3a58160e --- /dev/null +++ b/contrib/db_pools/codegen/tests/ui-fail-stable/database-syntax.stderr @@ -0,0 +1,111 @@ +error: invalid value: expected string literal + --> $DIR/database-syntax.rs:4:12 + | +4 | #[database(123)] + | ^^^ + +error: [note] error occurred while deriving `Database` + --> $DIR/database-syntax.rs:3:10 + | +3 | #[derive(Database)] + | ^^^^^^^^ + | + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: expected key/value `key = value` + --> $DIR/database-syntax.rs:8:25 + | +8 | #[database("some-name", "another")] + | ^^^^^^^^^ + +error: [note] error occurred while deriving `Database` + --> $DIR/database-syntax.rs:7:10 + | +7 | #[derive(Database)] + | ^^^^^^^^ + | + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: unexpected attribute parameter: `name` + --> $DIR/database-syntax.rs:12:25 + | +12 | #[database("some-name", name = "another")] + | ^^^^ + +error: [note] error occurred while deriving `Database` + --> $DIR/database-syntax.rs:11:10 + | +11 | #[derive(Database)] + | ^^^^^^^^ + | + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: enums are not supported + --> $DIR/database-syntax.rs:16:1 + | +16 | #[database("foo")] + | ^ + +error: [note] error occurred while deriving `Database` + --> $DIR/database-syntax.rs:15:10 + | +15 | #[derive(Database)] + | ^^^^^^^^ + | + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: missing `#[database("name")]` attribute + --> $DIR/database-syntax.rs:20:1 + | +20 | struct E(deadpool_postgres::Pool); + | ^^^^^^ + +error: [note] error occurred while deriving `Database` + --> $DIR/database-syntax.rs:19:10 + | +19 | #[derive(Database)] + | ^^^^^^^^ + | + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: struct must have exactly one unnamed field + --> $DIR/database-syntax.rs:23:1 + | +23 | #[database("foo")] + | ^ + +error: [note] error occurred while deriving `Database` + --> $DIR/database-syntax.rs:22:10 + | +22 | #[derive(Database)] + | ^^^^^^^^ + | + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: struct must have exactly one unnamed field + --> $DIR/database-syntax.rs:27:1 + | +27 | #[database("foo")] + | ^ + +error: [note] error occurred while deriving `Database` + --> $DIR/database-syntax.rs:26:10 + | +26 | #[derive(Database)] + | ^^^^^^^^ + | + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) + +error: named structs are not supported + --> $DIR/database-syntax.rs:31:1 + | +31 | #[database("foo")] + | ^ + +error: [note] error occurred while deriving `Database` + --> $DIR/database-syntax.rs:30:10 + | +30 | #[derive(Database)] + | ^^^^^^^^ + | + = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info) diff --git a/contrib/db_pools/codegen/tests/ui-fail-stable/database-types.rs b/contrib/db_pools/codegen/tests/ui-fail-stable/database-types.rs new file mode 120000 index 0000000000..98c58fba54 --- /dev/null +++ b/contrib/db_pools/codegen/tests/ui-fail-stable/database-types.rs @@ -0,0 +1 @@ +../ui-fail/database-types.rs \ No newline at end of file diff --git a/contrib/db_pools/codegen/tests/ui-fail-stable/database-types.stderr b/contrib/db_pools/codegen/tests/ui-fail-stable/database-types.stderr new file mode 100644 index 0000000000..9ea3e10e2c --- /dev/null +++ b/contrib/db_pools/codegen/tests/ui-fail-stable/database-types.stderr @@ -0,0 +1,25 @@ +error[E0277]: the trait bound `Unknown: Pool` is not satisfied + --> tests/ui-fail-stable/database-types.rs:7:10 + | +7 | struct A(Unknown); + | ^^^^^^^ the trait `Pool` is not implemented for `Unknown` + | + = help: the trait `Pool` is implemented for `deadpool::managed::Pool` +note: required by a bound in `rocket_db_pools::Database::Pool` + --> $WORKSPACE/contrib/db_pools/lib/src/database.rs + | + | type Pool: Pool; + | ^^^^ required by this bound in `rocket_db_pools::Database::Pool` + +error[E0277]: the trait bound `Vec: Pool` is not satisfied + --> tests/ui-fail-stable/database-types.rs:11:10 + | +11 | struct B(Vec); + | ^^^^^^^^ the trait `Pool` is not implemented for `Vec` + | + = help: the trait `Pool` is implemented for `deadpool::managed::Pool` +note: required by a bound in `rocket_db_pools::Database::Pool` + --> $WORKSPACE/contrib/db_pools/lib/src/database.rs + | + | type Pool: Pool; + | ^^^^ required by this bound in `rocket_db_pools::Database::Pool` diff --git a/contrib/db_pools/codegen/tests/ui-fail.rs b/contrib/db_pools/codegen/tests/ui-fail.rs new file mode 100644 index 0000000000..1cd5552a93 --- /dev/null +++ b/contrib/db_pools/codegen/tests/ui-fail.rs @@ -0,0 +1,10 @@ +#[test] +fn ui() { + let path = match version_check::is_feature_flaggable() { + Some(true) => "ui-fail-nightly", + _ => "ui-fail-stable" + }; + + let t = trybuild::TestCases::new(); + t.compile_fail(format!("tests/{}/*.rs", path)); +} diff --git a/contrib/db_pools/codegen/tests/ui-fail/database-syntax.rs b/contrib/db_pools/codegen/tests/ui-fail/database-syntax.rs new file mode 100644 index 0000000000..a90e105daa --- /dev/null +++ b/contrib/db_pools/codegen/tests/ui-fail/database-syntax.rs @@ -0,0 +1,36 @@ +use rocket_db_pools::{deadpool_postgres, Database}; + +#[derive(Database)] +#[database(123)] +struct A(deadpool_postgres::Pool); + +#[derive(Database)] +#[database("some-name", "another")] +struct B(deadpool_postgres::Pool); + +#[derive(Database)] +#[database("some-name", name = "another")] +struct C(deadpool_postgres::Pool); + +#[derive(Database)] +#[database("foo")] +enum D { } + +#[derive(Database)] +struct E(deadpool_postgres::Pool); + +#[derive(Database)] +#[database("foo")] +struct F; + +#[derive(Database)] +#[database("foo")] +struct G(deadpool_postgres::Pool, deadpool_postgres::Pool); + +#[derive(Database)] +#[database("foo")] +struct H { + foo: deadpool_postgres::Pool, +} + +fn main() { } diff --git a/contrib/db_pools/codegen/tests/ui-fail/database-types.rs b/contrib/db_pools/codegen/tests/ui-fail/database-types.rs new file mode 100644 index 0000000000..d4e1c58596 --- /dev/null +++ b/contrib/db_pools/codegen/tests/ui-fail/database-types.rs @@ -0,0 +1,13 @@ +#[macro_use] extern crate rocket_db_pools; + +struct Unknown; + +#[derive(Database)] +#[database("foo")] +struct A(Unknown); + +#[derive(Database)] +#[database("bar")] +struct B(Vec); + +fn main() { } diff --git a/contrib/db_pools/lib/Cargo.toml b/contrib/db_pools/lib/Cargo.toml new file mode 100644 index 0000000000..6c20349d53 --- /dev/null +++ b/contrib/db_pools/lib/Cargo.toml @@ -0,0 +1,73 @@ +[package] +name = "rocket_db_pools" +version = "0.1.0-rc.2" +authors = ["Sergio Benitez ", "Jeb Rosen "] +description = "Rocket async database pooling support" +repository = "https://github.com/SergioBenitez/Rocket/contrib/db_pools" +readme = "../README.md" +keywords = ["rocket", "framework", "database", "pools"] +license = "MIT OR Apache-2.0" +edition = "2021" +rust-version = "1.56" + +[package.metadata.docs.rs] +all-features = true + +[features] +# deadpool features +deadpool_postgres = ["deadpool-postgres", "deadpool"] +deadpool_redis = ["deadpool-redis", "deadpool"] +# sqlx features +sqlx_mysql = ["sqlx", "sqlx/mysql"] +sqlx_postgres = ["sqlx", "sqlx/postgres"] +sqlx_sqlite = ["sqlx", "sqlx/sqlite"] +sqlx_mssql = ["sqlx", "sqlx/mssql"] +sqlx_macros = ["sqlx/macros"] +# implicit features: mongodb + +[dependencies.rocket] +path = "../../../core/lib" +version = "0.5.0-rc.2" +default-features = false + +[dependencies.rocket_db_pools_codegen] +path = "../codegen" +version = "0.1.0-rc.2" + +[dependencies.deadpool] +version = "0.9" +default-features = false +features = ["rt_tokio_1", "managed"] +optional = true + +[dependencies.deadpool-postgres] +version = "0.10" +default-features = false +features = ["rt_tokio_1"] +optional = true + +[dependencies.deadpool-redis] +version = "0.10" +default-features = false +features = ["rt_tokio_1"] +optional = true + +[dependencies.mongodb] +version = "2" +default-features = false +features = ["tokio-runtime"] +optional = true + +[dependencies.sqlx] +version = "0.6" +default-features = false +features = ["runtime-tokio-rustls"] +optional = true + +[dev-dependencies.rocket] +path = "../../../core/lib" +default-features = false +features = ["json"] + +[build-dependencies] +version_check = "0.9" diff --git a/contrib/db_pools/lib/src/config.rs b/contrib/db_pools/lib/src/config.rs new file mode 100644 index 0000000000..fcbbc345b7 --- /dev/null +++ b/contrib/db_pools/lib/src/config.rs @@ -0,0 +1,83 @@ +use rocket::serde::{Deserialize, Serialize}; + +/// Base configuration for all database drivers. +/// +/// A dictionary matching this structure is extracted from the active +/// [`Figment`](crate::figment::Figment), scoped to `databases.name`, where +/// `name` is the name of the database, by the +/// [`Initializer`](crate::Initializer) fairing on ignition and used to +/// configure the relevant database and database pool. +/// +/// With the default provider, these parameters are typically configured in a +/// `Rocket.toml` file: +/// +/// ```toml +/// [default.databases.db_name] +/// url = "/path/to/db.sqlite" +/// +/// # only `url` is required. `Initializer` provides defaults for the rest. +/// min_connections = 64 +/// max_connections = 1024 +/// connect_timeout = 5 +/// idle_timeout = 120 +/// ``` +/// +/// Alternatively, a custom provider can be used. For example, a custom `Figment` +/// with a global `databases.name` configuration: +/// +/// ```rust +/// # use rocket::launch; +/// #[launch] +/// fn rocket() -> _ { +/// let figment = rocket::Config::figment() +/// .merge(("databases.name", rocket_db_pools::Config { +/// url: "db:specific@config&url".into(), +/// min_connections: None, +/// max_connections: 1024, +/// connect_timeout: 3, +/// idle_timeout: None, +/// })); +/// +/// rocket::custom(figment) +/// } +/// ``` +/// +/// For general information on configuration in Rocket, see [`rocket::config`]. +/// For higher-level details on configuring a database, see the [crate-level +/// docs](crate#configuration). +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] +#[serde(crate = "rocket::serde")] +pub struct Config { + /// Database-specific connection and configuration URL. + /// + /// The format of the URL is database specific; consult your database's + /// documentation. + pub url: String, + /// Minimum number of connections to maintain in the pool. + /// + /// **Note:** `deadpool` drivers do not support and thus ignore this value. + /// + /// _Default:_ `None`. + pub min_connections: Option, + /// Maximum number of connections to maintain in the pool. + /// + /// _Default:_ `workers * 4`. + pub max_connections: usize, + /// Number of seconds to wait for a connection before timing out. + /// + /// If the timeout elapses before a connection can be made or retrieved from + /// a pool, an error is returned. + /// + /// _Default:_ `5`. + pub connect_timeout: u64, + /// Maximum number of seconds to keep a connection alive for. + /// + /// After a connection is established, it is maintained in a pool for + /// efficient connection retrieval. When an `idle_timeout` is set, that + /// connection will be closed after the timeout elapses. If an + /// `idle_timeout` is not specified, the behavior is driver specific but + /// typically defaults to keeping a connection active indefinitely. + /// + /// _Default:_ `None`. + pub idle_timeout: Option, +} diff --git a/contrib/db_pools/lib/src/database.rs b/contrib/db_pools/lib/src/database.rs new file mode 100644 index 0000000000..61b10cedc5 --- /dev/null +++ b/contrib/db_pools/lib/src/database.rs @@ -0,0 +1,316 @@ +use std::marker::PhantomData; +use std::ops::{Deref, DerefMut}; + +use rocket::{error, info_, Build, Ignite, Phase, Rocket, Sentinel, Orbit}; +use rocket::fairing::{self, Fairing, Info, Kind}; +use rocket::request::{FromRequest, Outcome, Request}; +use rocket::http::Status; + +use rocket::yansi::Paint; +use rocket::figment::providers::Serialized; + +use crate::Pool; + +/// Derivable trait which ties a database [`Pool`] with a configuration name. +/// +/// This trait should rarely, if ever, be implemented manually. Instead, it +/// should be derived: +/// +/// ```rust +/// # #[cfg(feature = "deadpool_redis")] mod _inner { +/// # use rocket::launch; +/// use rocket_db_pools::{deadpool_redis, Database}; +/// +/// #[derive(Database)] +/// #[database("memdb")] +/// struct Db(deadpool_redis::Pool); +/// +/// #[launch] +/// fn rocket() -> _ { +/// rocket::build().attach(Db::init()) +/// } +/// # } +/// ``` +/// +/// See the [`Database` derive](derive@crate::Database) for details. +pub trait Database: From + DerefMut + Send + Sync + 'static { + /// The [`Pool`] type of connections to this database. + /// + /// When `Database` is derived, this takes the value of the `Inner` type in + /// `struct Db(Inner)`. + type Pool: Pool; + + /// The configuration name for this database. + /// + /// When `Database` is derived, this takes the value `"name"` in the + /// `#[database("name")]` attribute. + const NAME: &'static str; + + /// Returns a fairing that initializes the database and its connection pool. + /// + /// # Example + /// + /// ```rust + /// # #[cfg(feature = "deadpool_postgres")] mod _inner { + /// # use rocket::launch; + /// use rocket_db_pools::{deadpool_postgres, Database}; + /// + /// #[derive(Database)] + /// #[database("pg_db")] + /// struct Db(deadpool_postgres::Pool); + /// + /// #[launch] + /// fn rocket() -> _ { + /// rocket::build().attach(Db::init()) + /// } + /// # } + /// ``` + fn init() -> Initializer { + Initializer::new() + } + + /// Returns a reference to the initialized database in `rocket`. The + /// initializer fairing returned by `init()` must have already executed for + /// `Option` to be `Some`. This is guaranteed to be the case if the fairing + /// is attached and either: + /// + /// * Rocket is in the [`Orbit`](rocket::Orbit) phase. That is, the + /// application is running. This is always the case in request guards + /// and liftoff fairings, + /// * _or_ Rocket is in the [`Build`](rocket::Build) or + /// [`Ignite`](rocket::Ignite) phase and the `Initializer` fairing has + /// already been run. This is the case in all fairing callbacks + /// corresponding to fairings attached _after_ the `Initializer` + /// fairing. + /// + /// # Example + /// + /// Run database migrations in an ignite fairing. It is imperative that the + /// migration fairing be registered _after_ the `init()` fairing. + /// + /// ```rust + /// # #[cfg(feature = "sqlx_sqlite")] mod _inner { + /// # use rocket::launch; + /// use rocket::{Rocket, Build}; + /// use rocket::fairing::{self, AdHoc}; + /// + /// use rocket_db_pools::{sqlx, Database}; + /// + /// #[derive(Database)] + /// #[database("sqlite_db")] + /// struct Db(sqlx::SqlitePool); + /// + /// async fn run_migrations(rocket: Rocket) -> fairing::Result { + /// if let Some(db) = Db::fetch(&rocket) { + /// // run migrations using `db`. get the inner type with &db.0. + /// Ok(rocket) + /// } else { + /// Err(rocket) + /// } + /// } + /// + /// #[launch] + /// fn rocket() -> _ { + /// rocket::build() + /// .attach(Db::init()) + /// .attach(AdHoc::try_on_ignite("DB Migrations", run_migrations)) + /// } + /// # } + /// ``` + fn fetch(rocket: &Rocket

) -> Option<&Self> { + if let Some(db) = rocket.state() { + return Some(db); + } + + let dbtype = std::any::type_name::(); + let fairing = Paint::default(format!("{}::init()", dbtype)).bold(); + error!("Attempted to fetch unattached database `{}`.", Paint::default(dbtype).bold()); + info_!("`{}` fairing must be attached prior to using this database.", fairing); + None + } +} + +/// A [`Fairing`] which initializes a [`Database`] and its connection pool. +/// +/// A value of this type can be created for any type `D` that implements +/// [`Database`] via the [`Database::init()`] method on the type. Normally, a +/// value of this type _never_ needs to be constructed directly. This +/// documentation exists purely as a reference. +/// +/// This fairing initializes a database pool. Specifically, it: +/// +/// 1. Reads the configuration at `database.db_name`, where `db_name` is +/// [`Database::NAME`]. +/// +/// 2. Sets [`Config`](crate::Config) defaults on the configuration figment. +/// +/// 3. Calls [`Pool::init()`]. +/// +/// 4. Stores the database instance in managed storage, retrievable via +/// [`Database::fetch()`]. +/// +/// The name of the fairing itself is `Initializer`, with `D` replaced with +/// the type name `D` unless a name is explicitly provided via +/// [`Self::with_name()`]. +pub struct Initializer(Option<&'static str>, PhantomData D>); + +/// A request guard which retrieves a single connection to a [`Database`]. +/// +/// For a database type of `Db`, a request guard of `Connection` retrieves a +/// single connection to `Db`. +/// +/// The request guard succeeds if the database was initialized by the +/// [`Initializer`] fairing and a connection is available within +/// [`connect_timeout`](crate::Config::connect_timeout) seconds. +/// * If the `Initializer` fairing was _not_ attached, the guard _fails_ with +/// status `InternalServerError`. A [`Sentinel`] guards this condition, and so +/// this type of failure is unlikely to occur. A `None` error is returned. +/// * If a connection is not available within `connect_timeout` seconds or +/// another error occurs, the gaurd _fails_ with status `ServiceUnavailable` +/// and the error is returned in `Some`. +/// +/// ## Deref +/// +/// A type of `Connection` dereferences, mutably and immutably, to the +/// native database connection type. The [driver table](crate#supported-drivers) +/// lists the concrete native `Deref` types. +/// +/// # Example +/// +/// ```rust +/// # #[cfg(feature = "sqlx_sqlite")] mod _inner { +/// # use rocket::get; +/// # type Pool = rocket_db_pools::sqlx::SqlitePool; +/// use rocket_db_pools::{Database, Connection}; +/// +/// #[derive(Database)] +/// #[database("db")] +/// struct Db(Pool); +/// +/// #[get("/")] +/// async fn db_op(db: Connection) { +/// // use `&*db` to get an immutable borrow to the native connection type +/// // use `&mut *db` to get a mutable borrow to the native connection type +/// } +/// # } +/// ``` +pub struct Connection(::Connection); + +impl Initializer { + /// Returns a database initializer fairing for `D`. + /// + /// This method should never need to be called manually. See the [crate + /// docs](crate) for usage information. + pub fn new() -> Self { + Self(None, std::marker::PhantomData) + } + + /// Returns a database initializer fairing for `D` with name `name`. + /// + /// This method should never need to be called manually. See the [crate + /// docs](crate) for usage information. + pub fn with_name(name: &'static str) -> Self { + Self(Some(name), std::marker::PhantomData) + } +} + +impl Connection { + /// Returns the internal connection value. See the [`Connection` Deref + /// column](crate#supported-drivers) for the expected type of this value. + /// + /// Note that `Connection` derefs to the internal connection type, so + /// using this method is likely unnecessary. See [deref](Connection#deref) + /// for examples. + /// + /// # Example + /// + /// ```rust + /// # #[cfg(feature = "sqlx_sqlite")] mod _inner { + /// # use rocket::get; + /// # type Pool = rocket_db_pools::sqlx::SqlitePool; + /// use rocket_db_pools::{Database, Connection}; + /// + /// #[derive(Database)] + /// #[database("db")] + /// struct Db(Pool); + /// + /// #[get("/")] + /// async fn db_op(db: Connection) { + /// let inner = db.into_inner(); + /// } + /// # } + /// ``` + pub fn into_inner(self) -> ::Connection { + self.0 + } +} + +#[rocket::async_trait] +impl Fairing for Initializer { + fn info(&self) -> Info { + Info { + name: self.0.unwrap_or(std::any::type_name::()), + kind: Kind::Ignite | Kind::Shutdown, + } + } + + async fn on_ignite(&self, rocket: Rocket) -> fairing::Result { + let workers: usize = rocket.figment() + .extract_inner(rocket::Config::WORKERS) + .unwrap_or_else(|_| rocket::Config::default().workers); + + let figment = rocket.figment() + .focus(&format!("databases.{}", D::NAME)) + .merge(Serialized::default("max_connections", workers * 4)) + .merge(Serialized::default("connect_timeout", 5)); + + match ::init(&figment).await { + Ok(pool) => Ok(rocket.manage(D::from(pool))), + Err(e) => { + error!("failed to initialize database: {}", e); + Err(rocket) + } + } + } + + async fn on_shutdown(&self, rocket: &Rocket) { + if let Some(db) = D::fetch(rocket) { + db.close().await; + } + } +} + +#[rocket::async_trait] +impl<'r, D: Database> FromRequest<'r> for Connection { + type Error = Option<::Error>; + + async fn from_request(req: &'r Request<'_>) -> Outcome { + match D::fetch(req.rocket()) { + Some(db) => match db.get().await { + Ok(conn) => Outcome::Success(Connection(conn)), + Err(e) => Outcome::Failure((Status::ServiceUnavailable, Some(e))), + }, + None => Outcome::Failure((Status::InternalServerError, None)), + } + } +} + +impl Sentinel for Connection { + fn abort(rocket: &Rocket) -> bool { + D::fetch(rocket).is_none() + } +} + +impl Deref for Connection { + type Target = ::Connection; + + fn deref(&self) -> &Self::Target { + &self.0 + } +} + +impl DerefMut for Connection { + fn deref_mut(&mut self) -> &mut Self::Target { + &mut self.0 + } +} diff --git a/contrib/db_pools/lib/src/error.rs b/contrib/db_pools/lib/src/error.rs new file mode 100644 index 0000000000..69bae1066f --- /dev/null +++ b/contrib/db_pools/lib/src/error.rs @@ -0,0 +1,35 @@ +use std::fmt; + +/// A general error type for use by [`Pool`](crate::Pool#implementing) +/// implementors and returned by the [`Connection`](crate::Connection) request +/// guard. +#[derive(Debug)] +pub enum Error { + /// An error that occured during database/pool initialization. + Init(A), + + /// An error that ocurred while retrieving a connection from the pool. + Get(B), + + /// A [`Figment`](crate::figment::Figment) configuration error. + Config(crate::figment::Error), +} + +impl fmt::Display for Error { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Error::Init(e) => write!(f, "failed to initialize database: {}", e), + Error::Get(e) => write!(f, "failed to get db connection: {}", e), + Error::Config(e) => write!(f, "bad configuration: {}", e), + } + } +} + +impl std::error::Error for Error + where A: fmt::Debug + fmt::Display, B: fmt::Debug + fmt::Display {} + +impl From for Error { + fn from(e: crate::figment::Error) -> Self { + Self::Config(e) + } +} diff --git a/contrib/db_pools/lib/src/lib.rs b/contrib/db_pools/lib/src/lib.rs new file mode 100644 index 0000000000..bf8fc726dd --- /dev/null +++ b/contrib/db_pools/lib/src/lib.rs @@ -0,0 +1,248 @@ +//! Asynchronous database driver connection pooling integration for Rocket. +//! +//! # Quickstart +//! +//! 1. Add `rocket_db_pools` as a dependency with one or more [database driver +//! features](#supported-drivers) enabled: +//! +//! ```toml +//! [dependencies.rocket_db_pools] +//! version = "0.1.0-rc.2" +//! features = ["sqlx_sqlite"] +//! ``` +//! +//! 2. Choose a name for your database, here `sqlite_logs`. +//! [Configure](#configuration) _at least_ a URL for the database: +//! +//! ```toml +//! [default.databases.sqlite_logs] +//! url = "/path/to/database.sqlite" +//! ``` +//! +//! 3. [Derive](derive@Database) [`Database`] for a unit type (`Logs` here) +//! which wraps the selected driver's [`Pool`] type (see [the driver +//! table](#supported-drivers)) and is decorated with `#[database("name")]`. +//! Attach `Type::init()` to your application's `Rocket` to initialize the +//! database pool: +//! +//! ```rust +//! # #[cfg(feature = "sqlx_sqlite")] mod _inner { +//! # use rocket::launch; +//! use rocket_db_pools::{sqlx, Database}; +//! +//! #[derive(Database)] +//! #[database("sqlite_logs")] +//! struct Logs(sqlx::SqlitePool); +//! +//! #[launch] +//! fn rocket() -> _ { +//! rocket::build().attach(Logs::init()) +//! } +//! # } +//! ``` +//! +//! 4. Use [`Connection`](Connection) as a request guard to retrieve an +//! active database connection, which dereferences to the native type in the +//! [`Connection` deref](#supported-drivers) column. +//! +//! ```rust +//! # #[cfg(feature = "sqlx_sqlite")] mod _inner { +//! # use rocket::{get, response::Responder}; +//! # use rocket_db_pools::{sqlx, Database}; +//! # #[derive(Database)] +//! # #[database("sqlite_logs")] +//! # struct Logs(sqlx::SqlitePool); +//! # +//! # #[derive(Responder)] +//! # struct Log(String); +//! # +//! use rocket_db_pools::Connection; +//! use rocket_db_pools::sqlx::Row; +//! +//! #[get("/")] +//! async fn read(mut db: Connection, id: i64) -> Option { +//! sqlx::query("SELECT content FROM logs WHERE id = ?").bind(id) +//! .fetch_one(&mut *db).await +//! .and_then(|r| Ok(Log(r.try_get(0)?))) +//! .ok() +//! } +//! # } +//! ``` +//! +//! Alternatively, use a reference to the database type as a request guard to +//! retrieve the entire pool, but note that unlike retrieving a `Connection`, +//! doing so does _not_ guarantee that a connection is available: +//! +//! ```rust +//! # #[cfg(feature = "sqlx_sqlite")] mod _inner { +//! # use rocket::{get, response::Responder}; +//! # use rocket_db_pools::{sqlx, Database}; +//! # #[derive(Database)] +//! # #[database("sqlite_logs")] +//! # struct Logs(sqlx::SqlitePool); +//! # +//! # #[derive(Responder)] +//! # struct Log(String); +//! # +//! use rocket_db_pools::sqlx::Row; +//! +//! #[get("/")] +//! async fn read(db: &Logs, id: i64) -> Option { +//! sqlx::query("SELECT content FROM logs WHERE id = ?").bind(id) +//! .fetch_one(&db.0).await +//! .and_then(|r| Ok(Log(r.try_get(0)?))) +//! .ok() +//! } +//! # } +//! ``` +//! +//! # Supported Drivers +//! +//! At present, this crate supports _three_ drivers: [`deadpool`], [`sqlx`], and +//! [`mongodb`]. Each driver may support multiple databases. Drivers have a +//! varying degree of support for graceful shutdown, affected by the +//! `Type::init()` fairing on Rocket shutdown. +//! +//! ## `deadpool` (v0.9) +//! +//! | Database | Feature | [`Pool`] Type | [`Connection`] Deref | +//! |----------|---------------------|-----------------------------|---------------------------------------| +//! | Postgres | `deadpool_postgres` | [`deadpool_postgres::Pool`] | [`deadpool_postgres::ClientWrapper`] | +//! | Redis | `deadpool_redis` | [`deadpool_redis::Pool`] | [`deadpool_redis::Connection`] | +//! +//! On shutdown, new connections are denied. Shutdown _does not_ wait for +//! connections to be returned. +//! +//! ## `sqlx` (v0.6) +//! +//! | Database | Feature | [`Pool`] Type | [`Connection`] Deref | +//! |----------|-----------------|----------------------|------------------------------------------| +//! | Postgres | `sqlx_postgres` | [`sqlx::PgPool`] | [`sqlx::pool::PoolConnection`] | +//! | MySQL | `sqlx_mysql` | [`sqlx::MySqlPool`] | [`sqlx::pool::PoolConnection`] | +//! | SQLite | `sqlx_sqlite` | [`sqlx::SqlitePool`] | [`sqlx::pool::PoolConnection`] | +//! | MSSQL | `sqlx_mssql` | [`sqlx::MssqlPool`] | [`sqlx::pool::PoolConnection`] | +//! +//! [`sqlx::PgPool`]: https://docs.rs/sqlx/0.6/sqlx/type.PgPool.html +//! [`sqlx::MySqlPool`]: https://docs.rs/sqlx/0.6/sqlx/type.MySqlPool.html +//! [`sqlx::SqlitePool`]: https://docs.rs/sqlx/0.6/sqlx/type.SqlitePool.html +//! [`sqlx::MssqlPool`]: https://docs.rs/sqlx/0.6/sqlx/type.MssqlPool.html +//! [`sqlx::PoolConnection`]: https://docs.rs/sqlx/0.6/sqlx/pool/struct.PoolConnection.html +//! [`sqlx::PoolConnection`]: https://docs.rs/sqlx/0.6/sqlx/pool/struct.PoolConnection.html +//! [`sqlx::PoolConnection`]: https://docs.rs/sqlx/0.6/sqlx/pool/struct.PoolConnection.html +//! [`sqlx::PoolConnection`]: https://docs.rs/sqlx/0.6/sqlx/pool/struct.PoolConnection.html +//! +//! On shutdown, new connections are denied. Shutdown waits for connections to +//! be returned. +//! +//! ## `mongodb` (v2) +//! +//! | Database | Feature | [`Pool`] Type and [`Connection`] Deref | +//! |----------|-----------|----------------------------------------| +//! | MongoDB | `mongodb` | [`mongodb::Client`] | +//! +//! Graceful shutdown is not supported. +//! +//! ## Enabling Additional Driver Features +//! +//! Only the minimal features for each driver crate are enabled by +//! `rocket_db_pools`. To use additional driver functionality exposed via its +//! crate's features, you'll need to depend on the crate directly with those +//! features enabled in `Cargo.toml`: +//! +//! ```toml +//! [dependencies.sqlx] +//! version = "0.5" +//! default-features = false +//! features = ["macros", "offline", "migrate"] +//! +//! [dependencies.rocket_db_pools] +//! version = "0.1.0-rc.2" +//! features = ["sqlx_sqlite"] +//! ``` +//! +//! # Configuration +//! +//! Configuration for a database named `db_name` is deserialized from a +//! `databases.db_name` configuration parameter into a [`Config`] structure via +//! Rocket's [configuration facilities](rocket::config). By default, +//! configuration can be provided in `Rocket.toml`: +//! +//! ```toml +//! [default.databases.db_name] +//! url = "db.sqlite" +//! +//! # only `url` is required. the rest have defaults and are thus optional +//! min_connections = 64 +//! max_connections = 1024 +//! connect_timeout = 5 +//! idle_timeout = 120 +//! ``` +//! +//! Or via environment variables: +//! +//! ```sh +//! ROCKET_DATABASES='{db_name={url="db.sqlite",idle_timeout=120}}' +//! ``` +//! +//! See [`Config`] for details on configuration parameters. +//! +//! **Note:** `deadpool` drivers do not support and thus ignore the +//! `min_connections` value. +//! +//! ## Driver Defaults +//! +//! Some drivers provide configuration defaults different from the underyling +//! database's defaults. A best-effort attempt is made to document those +//! differences below: +//! +//! * `sqlx_sqlite` +//! +//! - foreign keys : `enabled` +//! - journal mode : `WAL` +//! - create-missing : `enabled` +//! - synchronous : `full` (even when `WAL`) +//! - busy timeout : `connection_timeout` +//! +//! * `sqlx_postgres` +//! +//! - sslmode : `prefer` +//! - statement-cache-capacity : `100` +//! - user : result of `whoami` +//! +//! * `sqlx_mysql` +//! +//! - sslmode : `PREFERRED` +//! - statement-cache-capacity : `100` +//! +//! # Extending +//! +//! Any database driver can implement support for this libary by implementing +//! the [`Pool`] trait. + +#![doc(html_root_url = "https://api.rocket.rs/master/rocket_db_pools")] +#![doc(html_favicon_url = "https://rocket.rs/images/favicon.ico")] +#![doc(html_logo_url = "https://rocket.rs/images/logo-boxed.png")] + +#![deny(missing_docs)] + +/// Re-export of the `figment` crate. +#[doc(inline)] +pub use rocket::figment; + +pub use rocket; +#[cfg(feature = "deadpool_postgres")] pub use deadpool_postgres; +#[cfg(feature = "deadpool_redis")] pub use deadpool_redis; +#[cfg(feature = "mongodb")] pub use mongodb; +#[cfg(feature = "sqlx")] pub use sqlx; + +mod database; +mod error; +mod pool; +mod config; + +pub use self::database::{Connection, Database, Initializer}; +pub use self::error::Error; +pub use self::pool::Pool; +pub use self::config::Config; + +pub use rocket_db_pools_codegen::*; diff --git a/contrib/db_pools/lib/src/pool.rs b/contrib/db_pools/lib/src/pool.rs new file mode 100644 index 0000000000..9f313eaa0b --- /dev/null +++ b/contrib/db_pools/lib/src/pool.rs @@ -0,0 +1,297 @@ +use rocket::figment::Figment; + +#[allow(unused_imports)] +use {std::time::Duration, crate::{Error, Config}}; + +/// Generic [`Database`](crate::Database) driver connection pool trait. +/// +/// This trait provides a generic interface to various database pooling +/// implementations in the Rust ecosystem. It can be implemented by anyone, but +/// this crate provides implementations for common drivers. +/// +/// **Implementations of this trait outside of this crate should be rare. You +/// _do not_ need to implement this trait or understand its specifics to use +/// this crate.** +/// +/// ## Async Trait +/// +/// [`Pool`] is an _async_ trait. Implementations of `Pool` must be decorated +/// with an attribute of `#[async_trait]`: +/// +/// ```rust +/// # #[macro_use] extern crate rocket; +/// use rocket::figment::Figment; +/// use rocket_db_pools::Pool; +/// +/// # struct MyPool; +/// # type Connection = (); +/// # type Error = std::convert::Infallible; +/// #[rocket::async_trait] +/// impl Pool for MyPool { +/// type Connection = Connection; +/// +/// type Error = Error; +/// +/// async fn init(figment: &Figment) -> Result { +/// todo!("initialize and return an instance of the pool"); +/// } +/// +/// async fn get(&self) -> Result { +/// todo!("fetch one connection from the pool"); +/// } +/// +/// async fn close(&self) { +/// todo!("gracefully shutdown connection pool"); +/// } +/// } +/// ``` +/// +/// ## Implementing +/// +/// Implementations of `Pool` typically trace the following outline: +/// +/// 1. The `Error` associated type is set to [`Error`]. +/// +/// 2. A [`Config`] is [extracted](Figment::extract()) from the `figment` +/// passed to init. +/// +/// 3. The pool is initialized and returned in `init()`, wrapping +/// initialization errors in [`Error::Init`]. +/// +/// 4. A connection is retrieved in `get()`, wrapping errors in +/// [`Error::Get`]. +/// +/// Concretely, this looks like: +/// +/// ```rust +/// use rocket::figment::Figment; +/// use rocket_db_pools::{Pool, Config, Error}; +/// # +/// # type InitError = std::convert::Infallible; +/// # type GetError = std::convert::Infallible; +/// # type Connection = (); +/// # +/// # struct MyPool(Config); +/// # impl MyPool { +/// # fn new(c: Config) -> Result { +/// # Ok(Self(c)) +/// # } +/// # +/// # fn acquire(&self) -> Result { +/// # Ok(()) +/// # } +/// # +/// # async fn shutdown(&self) { } +/// # } +/// +/// #[rocket::async_trait] +/// impl Pool for MyPool { +/// type Connection = Connection; +/// +/// type Error = Error; +/// +/// async fn init(figment: &Figment) -> Result { +/// // Extract the config from `figment`. +/// let config: Config = figment.extract()?; +/// +/// // Read config values, initialize `MyPool`. Map errors of type +/// // `InitError` to `Error` with `Error::Init`. +/// let pool = MyPool::new(config).map_err(Error::Init)?; +/// +/// // Return the fully intialized pool. +/// Ok(pool) +/// } +/// +/// async fn get(&self) -> Result { +/// // Get one connection from the pool, here via an `acquire()` method. +/// // Map errors of type `GetError` to `Error<_, GetError>`. +/// self.acquire().map_err(Error::Get) +/// } +/// +/// async fn close(&self) { +/// self.shutdown().await; +/// } +/// } +/// ``` +#[rocket::async_trait] +pub trait Pool: Sized + Send + Sync + 'static { + /// The connection type managed by this pool, returned by [`Self::get()`]. + type Connection; + + /// The error type returned by [`Self::init()`] and [`Self::get()`]. + type Error: std::error::Error; + + /// Constructs a pool from a [Value](rocket::figment::value::Value). + /// + /// It is up to each implementor of `Pool` to define its accepted + /// configuration value(s) via the `Config` associated type. Most + /// integrations provided in `rocket_db_pools` use [`Config`], which + /// accepts a (required) `url` and an (optional) `pool_size`. + /// + /// ## Errors + /// + /// This method returns an error if the configuration is not compatible, or + /// if creating a pool failed due to an unavailable database server, + /// insufficient resources, or another database-specific error. + async fn init(figment: &Figment) -> Result; + + /// Asynchronously retrieves a connection from the factory or pool. + /// + /// ## Errors + /// + /// This method returns an error if a connection could not be retrieved, + /// such as a preconfigured timeout elapsing or when the database server is + /// unavailable. + async fn get(&self) -> Result; + + /// Shutdown the connection pool, disallowing any new connections from being + /// retrieved and waking up any tasks with active connections. + /// + /// The returned future may either resolve when all connections are known to + /// have closed or at any point prior. Details are implementation specific. + async fn close(&self); +} + +#[cfg(feature = "deadpool")] +mod deadpool_postgres { + use deadpool::{managed::{Manager, Pool, PoolError, Object, BuildError}, Runtime}; + use super::{Duration, Error, Config, Figment}; + + pub trait DeadManager: Manager + Sized + Send + Sync + 'static { + fn new(config: &Config) -> Result; + } + + #[cfg(feature = "deadpool_postgres")] + impl DeadManager for deadpool_postgres::Manager { + fn new(config: &Config) -> Result { + Ok(Self::new(config.url.parse()?, deadpool_postgres::tokio_postgres::NoTls)) + } + } + + #[cfg(feature = "deadpool_redis")] + impl DeadManager for deadpool_redis::Manager { + fn new(config: &Config) -> Result { + Self::new(config.url.as_str()) + } + } + + #[rocket::async_trait] + impl>> crate::Pool for Pool + where M::Type: Send, C: Send + Sync + 'static, M::Error: std::error::Error + { + type Error = Error, PoolError>; + + type Connection = C; + + async fn init(figment: &Figment) -> Result { + let config: Config = figment.extract()?; + let manager = M::new(&config).map_err(|e| Error::Init(BuildError::Backend(e)))?; + + Pool::builder(manager) + .max_size(config.max_connections) + .wait_timeout(Some(Duration::from_secs(config.connect_timeout))) + .create_timeout(Some(Duration::from_secs(config.connect_timeout))) + .recycle_timeout(config.idle_timeout.map(Duration::from_secs)) + .runtime(Runtime::Tokio1) + .build() + .map_err(Error::Init) + } + + async fn get(&self) -> Result { + self.get().await.map_err(Error::Get) + } + + async fn close(&self) { + >::close(self) + } + } +} + +#[cfg(feature = "sqlx")] +mod sqlx { + use sqlx::ConnectOptions; + use super::{Duration, Error, Config, Figment}; + use rocket::config::LogLevel; + + type Options = <::Connection as sqlx::Connection>::Options; + + // Provide specialized configuration for particular databases. + fn specialize(__options: &mut dyn std::any::Any, __config: &Config) { + #[cfg(feature = "sqlx_sqlite")] + if let Some(o) = __options.downcast_mut::() { + *o = std::mem::take(o) + .busy_timeout(Duration::from_secs(__config.connect_timeout)) + .create_if_missing(true); + } + } + + #[rocket::async_trait] + impl crate::Pool for sqlx::Pool { + type Error = Error; + + type Connection = sqlx::pool::PoolConnection; + + async fn init(figment: &Figment) -> Result { + let config = figment.extract::()?; + let mut opts = config.url.parse::>().map_err(Error::Init)?; + specialize(&mut opts, &config); + + opts.disable_statement_logging(); + if let Ok(level) = figment.extract_inner::(rocket::Config::LOG_LEVEL) { + if !matches!(level, LogLevel::Normal | LogLevel::Off) { + opts.log_statements(level.into()) + .log_slow_statements(level.into(), Duration::default()); + } + } + + sqlx::pool::PoolOptions::new() + .max_connections(config.max_connections as u32) + .acquire_timeout(Duration::from_secs(config.connect_timeout)) + .idle_timeout(config.idle_timeout.map(Duration::from_secs)) + .min_connections(config.min_connections.unwrap_or_default()) + .connect_with(opts) + .await + .map_err(Error::Init) + } + + async fn get(&self) -> Result { + self.acquire().await.map_err(Error::Get) + } + + async fn close(&self) { + >::close(self).await; + } + } +} + +#[cfg(feature = "mongodb")] +mod mongodb { + use mongodb::{Client, options::ClientOptions}; + use super::{Duration, Error, Config, Figment}; + + #[rocket::async_trait] + impl crate::Pool for Client { + type Error = Error; + + type Connection = Client; + + async fn init(figment: &Figment) -> Result { + let config = figment.extract::()?; + let mut opts = ClientOptions::parse(&config.url).await.map_err(Error::Init)?; + opts.min_pool_size = config.min_connections; + opts.max_pool_size = Some(config.max_connections as u32); + opts.max_idle_time = config.idle_timeout.map(Duration::from_secs); + opts.connect_timeout = Some(Duration::from_secs(config.connect_timeout)); + opts.server_selection_timeout = Some(Duration::from_secs(config.connect_timeout)); + Client::with_options(opts).map_err(Error::Init) + } + + async fn get(&self) -> Result { + Ok(self.clone()) + } + + async fn close(&self) { + // nothing to do for mongodb + } + } +} diff --git a/contrib/db_pools/lib/tests/databases.rs b/contrib/db_pools/lib/tests/databases.rs new file mode 100644 index 0000000000..ce0bd36975 --- /dev/null +++ b/contrib/db_pools/lib/tests/databases.rs @@ -0,0 +1,67 @@ +macro_rules! check_types_match { + ($feature:expr, $name:ident, $Pool:ty, $Conn:ty $(,)?) => ( + #[cfg(feature = $feature)] + mod $name { + use rocket::*; + use rocket_db_pools::{Connection, Database}; + + #[derive(Database)] + #[database("foo")] + struct Db($Pool); + + #[get("/")] + fn _db(conn: Connection) { + let _: &$Conn = &*conn; + } + } + ) +} + +check_types_match!( + "deadpool_postgres", + deadpool_postgres, + deadpool_postgres::Pool, + deadpool_postgres::ClientWrapper, +); + +check_types_match!( + "deadpool_redis", + deadpool_redis, + deadpool_redis::Pool, + deadpool_redis::Connection, +); + +check_types_match!( + "sqlx_postgres", + sqlx_postgres, + sqlx::PgPool, + sqlx::pool::PoolConnection, +); + +check_types_match!( + "sqlx_mysql", + sqlx_mysql, + sqlx::MySqlPool, + sqlx::pool::PoolConnection, +); + +check_types_match!( + "sqlx_sqlite", + sqlx_sqlite, + sqlx::SqlitePool, + sqlx::pool::PoolConnection, +); + +check_types_match!( + "sqlx_mssql", + sqlx_mssql, + sqlx::MssqlPool, + sqlx::pool::PoolConnection, +); + +check_types_match!( + "mongodb", + mongodb, + mongodb::Client, + mongodb::Client, +); diff --git a/contrib/dyn_templates/Cargo.toml b/contrib/dyn_templates/Cargo.toml index 5da9731321..168f38d055 100644 --- a/contrib/dyn_templates/Cargo.toml +++ b/contrib/dyn_templates/Cargo.toml @@ -1,39 +1,39 @@ [package] name = "rocket_dyn_templates" -version = "0.1.0-dev" +version = "0.1.0-rc.2" authors = ["Sergio Benitez "] description = "Dynamic templating engine integration for Rocket." -documentation = "https://api.rocket.rs/master/rocket_dyn_templates/" +documentation = "https://api.rocket.rs/v0.5-rc/rocket_dyn_templates/" homepage = "https://rocket.rs" -repository = "https://github.com/SergioBenitez/Rocket/contrib/dyn_templates" +repository = "https://github.com/SergioBenitez/Rocket/tree/master/contrib/dyn_templates" readme = "README.md" keywords = ["rocket", "framework", "templates", "templating", "engine"] license = "MIT OR Apache-2.0" -edition = "2018" +edition = "2021" +rust-version = "1.56" [features] -tera = ["_tera"] -handlebars = ["_handlebars"] +tera = ["tera_"] +handlebars = ["handlebars_"] [dependencies] -serde = "1.0" -serde_json = "1.0.26" glob = "0.3" -notify = "4.0.6" +notify = "5.0.0" normpath = "0.3" [dependencies.rocket] +version = "0.5.0-rc.2" path = "../../core/lib" default-features = false -[dependencies._tera] +[dependencies.tera_] package = "tera" version = "1.10.0" optional = true -[dependencies._handlebars] +[dependencies.handlebars_] package = "handlebars" -version = "3.0" +version = "4.1" optional = true [package.metadata.docs.rs] diff --git a/contrib/dyn_templates/README.md b/contrib/dyn_templates/README.md index 0fe4425b6b..a01e891207 100644 --- a/contrib/dyn_templates/README.md +++ b/contrib/dyn_templates/README.md @@ -3,7 +3,7 @@ [crates.io]: https://img.shields.io/crates/v/rocket_dyn_templates.svg [crate]: https://crates.io/crates/rocket_dyn_templates [docs.svg]: https://img.shields.io/badge/web-master-red.svg?style=flat&label=docs&colorB=d33847 -[crate docs]: https://api.rocket.rs/master/rocket_dyn_templates +[crate docs]: https://api.rocket.rs/v0.5-rc/rocket_dyn_templates [ci.svg]: https://github.com/SergioBenitez/Rocket/workflows/CI/badge.svg [ci]: https://github.com/SergioBenitez/Rocket/actions @@ -22,7 +22,7 @@ supports [Handlebars] and [Tera]. ```toml [dependencies.rocket_dyn_templates] - version = "0.1.0-dev" + version = "0.1.0-rc.2" features = ["handlebars", "tera"] ``` @@ -35,17 +35,17 @@ supports [Handlebars] and [Tera]. last two extensions**: ```rust - use rocket_dyn_templates::Template; + use rocket_dyn_templates::{Template, context}; + + #[get("/")] + fn index() -> Template { + Template::render("template-name", context! { field: "value" }) + } #[launch] fn rocket() -> _ { rocket::build().attach(Template::fairing()) } - - #[get("/")] - fn index() -> Template { - Template::render("template-name", &context) - } ``` See the [crate docs] for full details. diff --git a/contrib/dyn_templates/src/context.rs b/contrib/dyn_templates/src/context.rs index aa53ac9afb..cf698823d9 100644 --- a/contrib/dyn_templates/src/context.rs +++ b/contrib/dyn_templates/src/context.rs @@ -115,7 +115,7 @@ mod manager { use std::sync::{RwLock, Mutex}; use std::sync::mpsc::{channel, Receiver}; - use notify::{raw_watcher, RawEvent, RecommendedWatcher, RecursiveMode, Watcher}; + use notify::{recommended_watcher, Error, Event, RecommendedWatcher, RecursiveMode, Watcher}; use super::{Callback, Context}; @@ -125,14 +125,14 @@ mod manager { /// The current template context, inside an RwLock so it can be updated. context: RwLock, /// A filesystem watcher and the receive queue for its events. - watcher: Option<(RecommendedWatcher, Mutex>)>, + watcher: Option<(RecommendedWatcher, Mutex>>)>, } impl ContextManager { pub fn new(ctxt: Context) -> ContextManager { let (tx, rx) = channel(); - let watcher = raw_watcher(tx).and_then(|mut watcher| { - watcher.watch(ctxt.root.canonicalize()?, RecursiveMode::Recursive)?; + let watcher = recommended_watcher(tx).and_then(|mut watcher| { + watcher.watch(&ctxt.root.canonicalize()?, RecursiveMode::Recursive)?; Ok(watcher) }); diff --git a/contrib/dyn_templates/src/engine.rs b/contrib/dyn_templates/src/engine.rs index d4bc0d7790..eba7230737 100644 --- a/contrib/dyn_templates/src/engine.rs +++ b/contrib/dyn_templates/src/engine.rs @@ -1,7 +1,7 @@ use std::path::Path; use std::collections::HashMap; -use serde::Serialize; +use rocket::serde::Serialize; use crate::TemplateInfo; @@ -60,7 +60,7 @@ pub struct Engines { pub tera: Tera, /// The Handlebars templating engine. This field is only available when the /// `handlebars_templates` feature is enabled. When calling methods on the - /// `Tera` instance, ensure you use types imported from + /// `Handlebars` instance, ensure you use types imported from /// `rocket_dyn_templates::handlebars` to avoid version mismatches. #[cfg(feature = "handlebars")] pub handlebars: Handlebars<'static>, diff --git a/contrib/dyn_templates/src/fairing.rs b/contrib/dyn_templates/src/fairing.rs index 52aa2798f4..08e1c76800 100644 --- a/contrib/dyn_templates/src/fairing.rs +++ b/contrib/dyn_templates/src/fairing.rs @@ -65,7 +65,7 @@ impl Fairing for TemplateFairing { } #[cfg(debug_assertions)] - async fn on_request(&self, req: &mut rocket::Request<'_>, _data: &mut rocket::Data) { + async fn on_request(&self, req: &mut rocket::Request<'_>, _data: &mut rocket::Data<'_>) { let cm = req.rocket().state::() .expect("Template ContextManager registered in on_ignite"); diff --git a/contrib/dyn_templates/src/handlebars_templates.rs b/contrib/dyn_templates/src/handlebars_templates.rs index f36e7efd35..82a1302272 100644 --- a/contrib/dyn_templates/src/handlebars_templates.rs +++ b/contrib/dyn_templates/src/handlebars_templates.rs @@ -1,6 +1,6 @@ use std::path::Path; -use serde::Serialize; +use rocket::serde::Serialize; use crate::engine::Engine; pub use crate::handlebars::Handlebars; @@ -29,12 +29,8 @@ impl Engine for Handlebars<'static> { return None; } - match Handlebars::render(self, name, &context) { - Ok(string) => Some(string), - Err(e) => { - error_!("Error rendering Handlebars template '{}': {}", name, e); - None - } - } + Handlebars::render(self, name, &context) + .map_err(|e| error_!("Handlebars: {}", e)) + .ok() } } diff --git a/contrib/dyn_templates/src/lib.rs b/contrib/dyn_templates/src/lib.rs index d39653a7fe..2b6519b462 100644 --- a/contrib/dyn_templates/src/lib.rs +++ b/contrib/dyn_templates/src/lib.rs @@ -12,7 +12,7 @@ //! //! ```toml //! [dependencies.rocket_dyn_templates] -//! version = "0.1.0-dev" +//! version = "0.1.0-rc.2" //! features = ["handlebars", "tera"] //! ``` //! @@ -26,18 +26,17 @@ //! //! ```rust //! # #[macro_use] extern crate rocket; -//! use rocket_dyn_templates::Template; +//! use rocket_dyn_templates::{Template, context}; +//! +//! #[get("/")] +//! fn index() -> Template { +//! Template::render("template-name", context! { field: "value" }) +//! } //! //! #[launch] //! fn rocket() -> _ { //! rocket::build().attach(Template::fairing()) //! } -//! -//! #[get("/")] -//! fn index() -> Template { -//! # let context = (); -//! Template::render("template-name", &context) -//! } //! ``` //! //! ## Naming @@ -49,7 +48,7 @@ //! //! Templates that are _not_ discovered by Rocket, such as those registered //! directly via [`Template::custom()`], are _not_ renamed. Use the name with -//! which the template was orginally registered. +//! which the template was originally registered. //! //! ## Content Type //! @@ -67,7 +66,7 @@ //! template directory is configured via the `template_dir` configuration //! parameter and defaults to `templates/`. The path set in `template_dir` is //! relative to the Rocket configuration file. See the [configuration -//! chapter](https://rocket.rs/master/guide/configuration) of the guide for more +//! chapter](https://rocket.rs/v0.5-rc/guide/configuration) of the guide for more //! information on configuration. //! //! The corresponding templating engine used for a given template is based on a @@ -77,10 +76,10 @@ //! | Engine | Version | Extension | //! |--------------|---------|-----------| //! | [Tera] | 1 | `.tera` | -//! | [Handlebars] | 3 | `.hbs` | +//! | [Handlebars] | 4 | `.hbs` | //! //! [Tera]: https://docs.rs/crate/tera/1 -//! [Handlebars]: https://docs.rs/crate/handlebars/3 +//! [Handlebars]: https://docs.rs/crate/handlebars/4 //! //! Any file that ends with one of these extension will be discovered and //! rendered with the corresponding templating engine. The _name_ of the @@ -116,10 +115,15 @@ //! //! ## Rendering //! -//! 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 -//! can be any type that implements [`Serialize`] from [`serde`] and would -//! serialize to an `Object` value. +//! Templates are typically rendered indirectly via [`Template::render()`] which +//! returns a `Template` responder which renders the template at response time. +//! To render a template directly into a `String`, use [`Metadata::render()`] +//! instead. +//! +//! Both methods take in a template name and context to use while rendering. The +//! context can be any [`Serialize`] type that serializes to an `Object` (a +//! dictionary) value. The [`context!`] macro may be used to create inline +//! `Serialize`-able context objects. //! //! ## Automatic Reloading //! @@ -127,10 +131,8 @@ //! will be automatically reloaded from disk if any changes have been made to //! the templates directory since the previous request. In release builds, //! template reloading is disabled to improve performance and cannot be enabled. -//! -//! [`Serialize`]: serde::Serialize -#![doc(html_root_url = "https://api.rocket.rs/master/rocket_dyn_templates")] +#![doc(html_root_url = "https://api.rocket.rs/v0.5-rc/rocket_dyn_templates")] #![doc(html_favicon_url = "https://rocket.rs/images/favicon.ico")] #![doc(html_logo_url = "https://rocket.rs/images/logo-boxed.png")] @@ -142,7 +144,7 @@ compile_error!("at least one of \"tera\" or \"handlebars\" features must be enab /// The tera templating engine library, reexported. #[doc(inline)] #[cfg(feature = "tera")] -pub use _tera as tera; +pub use tera_ as tera; #[cfg(feature = "tera")] mod tera_templates; @@ -150,7 +152,7 @@ mod tera_templates; /// The handlebars templating engine library, reexported. #[doc(inline)] #[cfg(feature = "handlebars")] -pub use _handlebars as handlebars; +pub use handlebars_ as handlebars; #[cfg(feature = "handlebars")] mod handlebars_templates; @@ -166,18 +168,19 @@ pub use self::metadata::Metadata; use self::fairing::TemplateFairing; use self::context::{Context, ContextManager}; -use serde::Serialize; -use serde_json::{Value, to_value}; - use std::borrow::Cow; use std::path::PathBuf; -use std::error::Error; + +#[doc(hidden)] +pub use rocket::serde; use rocket::{Rocket, Orbit, Ignite, Sentinel}; use rocket::request::Request; use rocket::fairing::Fairing; use rocket::response::{self, Responder}; use rocket::http::{ContentType, Status}; +use rocket::figment::{value::Value, error::Error}; +use rocket::serde::Serialize; const DEFAULT_TEMPLATE_DIR: &str = "templates"; @@ -191,7 +194,7 @@ const DEFAULT_TEMPLATE_DIR: &str = "templates"; #[derive(Debug)] pub struct Template { name: Cow<'static, str>, - value: Option + value: Result } #[derive(Debug)] @@ -299,33 +302,47 @@ impl Template { /// } /// ``` pub fn try_custom(f: F) -> impl Fairing - where F: Fn(&mut Engines) -> Result<(), Box> + where F: Fn(&mut Engines) -> Result<(), Box> { TemplateFairing { callback: Box::new(f) } } /// Render the template named `name` with the context `context`. The - /// `context` can be of any type that implements `Serialize`. This is - /// typically a `HashMap` or a custom `struct`. + /// `context` is typically created using the [`context!`] macro, but it can + /// be of any type that implements `Serialize`, such as `HashMap` or a + /// custom `struct`. /// - /// # Example + /// To render a template directly into a string, use [`Metadata::render()`]. + /// + /// # Examples + /// + /// Using the `context` macro: + /// + /// ```rust + /// use rocket_dyn_templates::{Template, context}; + /// + /// let template = Template::render("index", context! { + /// foo: "Hello, world!", + /// }); + /// ``` + /// + /// Using a `HashMap` as the context: /// /// ```rust /// use std::collections::HashMap; /// use rocket_dyn_templates::Template; /// - /// // Create a `context`. Here, just an empty `HashMap`. + /// // Create a `context` from a `HashMap`. /// let mut context = HashMap::new(); + /// context.insert("foo", "Hello, world!"); /// - /// # context.insert("test", "test"); - /// # #[allow(unused_variables)] /// let template = Template::render("index", context); /// ``` #[inline] pub fn render(name: S, context: C) -> Template where S: Into>, C: Serialize { - Template { name: name.into(), value: to_value(context).ok() } + Template { name: name.into(), value: Value::serialize(context) } } /// Render the template named `name` with the context `context` into a @@ -357,9 +374,7 @@ impl Template { /// /// // Create a `context`. Here, just an empty `HashMap`. /// let mut context = HashMap::new(); - /// /// # context.insert("test", "test"); - /// # #[allow(unused_variables)] /// let template = Template::show(client.rocket(), "index", context); /// } /// ``` @@ -374,25 +389,25 @@ impl Template { None })?; - Template::render(name, context).finalize(&ctxt).ok().map(|v| v.0) + Template::render(name, context).finalize(&ctxt).ok().map(|v| v.1) } /// Actually render this template given a template context. This method is /// called by the `Template` `Responder` implementation as well as /// `Template::show()`. #[inline(always)] - fn finalize(self, ctxt: &Context) -> Result<(String, ContentType), Status> { + fn finalize(self, ctxt: &Context) -> Result<(ContentType, String), Status> { let name = &*self.name; let info = ctxt.templates.get(name).ok_or_else(|| { let ts: Vec<_> = ctxt.templates.keys().map(|s| s.as_str()).collect(); error_!("Template '{}' does not exist.", name); - info_!("Known templates: {}", ts.join(", ")); + info_!("Known templates: {}.", ts.join(", ")); info_!("Searched in {:?}.", ctxt.root); Status::InternalServerError })?; - let value = self.value.ok_or_else(|| { - error_!("The provided template context failed to serialize."); + let value = self.value.map_err(|e| { + error_!("Template context failed to serialize: {}.", e); Status::InternalServerError })?; @@ -401,7 +416,7 @@ impl Template { Status::InternalServerError })?; - Ok((string, info.data_type.clone())) + Ok((info.data_type.clone(), string)) } } @@ -410,18 +425,16 @@ impl Template { /// rendering fails, an `Err` of `Status::InternalServerError` is returned. impl<'r> Responder<'r, 'static> for Template { fn respond_to(self, req: &'r Request<'_>) -> response::Result<'static> { - let (render, content_type) = { - let ctxt = req.rocket().state::().ok_or_else(|| { + let ctxt = req.rocket() + .state::() + .ok_or_else(|| { error_!("Uninitialized template context: missing fairing."); info_!("To use templates, you must attach `Template::fairing()`."); info_!("See the `Template` documentation for more information."); Status::InternalServerError - })?.context(); + })?; - self.finalize(&ctxt)? - }; - - (content_type, render).respond_to(req) + self.finalize(&ctxt.context())?.respond_to(req) } } @@ -439,3 +452,106 @@ impl Sentinel for Template { false } } + +/// A macro to easily create a template rendering context. +/// +/// Invocations of this macro expand to a value of an anonymous type which +/// implements [`serde::Serialize`]. Fields can be literal expressions or +/// variables captured from a surrounding scope, as long as all fields implement +/// `Serialize`. +/// +/// # Examples +/// +/// The following code: +/// +/// ```rust +/// # #[macro_use] extern crate rocket; +/// # use rocket_dyn_templates::{Template, context}; +/// #[get("/")] +/// fn render_index(foo: u64) -> Template { +/// Template::render("index", context! { +/// // Note that shorthand field syntax is supported. +/// // This is equivalent to `foo: foo,` +/// foo, +/// bar: "Hello world", +/// }) +/// } +/// ``` +/// +/// is equivalent to the following, but without the need to manually define an +/// `IndexContext` struct: +/// +/// ```rust +/// # use rocket_dyn_templates::Template; +/// # use rocket::serde::Serialize; +/// # use rocket::get; +/// #[derive(Serialize)] +/// # #[serde(crate = "rocket::serde")] +/// struct IndexContext<'a> { +/// foo: u64, +/// bar: &'a str, +/// } +/// +/// #[get("/")] +/// fn render_index(foo: u64) -> Template { +/// Template::render("index", IndexContext { +/// foo, +/// bar: "Hello world", +/// }) +/// } +/// ``` +/// +/// ## Nesting +/// +/// Nested objects can be created by nesting calls to `context!`: +/// +/// ```rust +/// # use rocket_dyn_templates::context; +/// # fn main() { +/// let ctx = context! { +/// planet: "Earth", +/// info: context! { +/// mass: 5.97e24, +/// radius: "6371 km", +/// moons: 1, +/// }, +/// }; +/// # } +/// ``` +#[macro_export] +macro_rules! context { + ($($key:ident $(: $value:expr)?),*$(,)?) => {{ + use $crate::serde::ser::{Serialize, Serializer, SerializeMap}; + use ::std::fmt::{Debug, Formatter}; + use ::std::result::Result; + + #[allow(non_camel_case_types)] + struct ContextMacroCtxObject<$($key: Serialize),*> { + $($key: $key),* + } + + #[allow(non_camel_case_types)] + impl<$($key: Serialize),*> Serialize for ContextMacroCtxObject<$($key),*> { + fn serialize(&self, serializer: S) -> Result + where S: Serializer, + { + let mut map = serializer.serialize_map(None)?; + $(map.serialize_entry(stringify!($key), &self.$key)?;)* + map.end() + } + } + + #[allow(non_camel_case_types)] + impl<$($key: Debug + Serialize),*> Debug for ContextMacroCtxObject<$($key),*> { + fn fmt(&self, f: &mut Formatter<'_>) -> ::std::fmt::Result { + f.debug_struct("context!") + $(.field(stringify!($key), &self.$key))* + .finish() + } + } + + ContextMacroCtxObject { + $($key $(: $value)?),* + } + }}; +} diff --git a/contrib/dyn_templates/src/metadata.rs b/contrib/dyn_templates/src/metadata.rs index b119c12967..feceab36d3 100644 --- a/contrib/dyn_templates/src/metadata.rs +++ b/contrib/dyn_templates/src/metadata.rs @@ -1,8 +1,11 @@ +use std::borrow::Cow; + use rocket::{Request, Rocket, Ignite, Sentinel}; -use rocket::http::Status; +use rocket::http::{Status, ContentType}; use rocket::request::{self, FromRequest}; +use rocket::serde::Serialize; -use crate::context::ContextManager; +use crate::{Template, context::ContextManager}; /// Request guard for dynamically querying template metadata. /// @@ -14,13 +17,12 @@ use crate::context::ContextManager; /// ```rust /// # #[macro_use] extern crate rocket; /// # #[macro_use] extern crate rocket_dyn_templates; -/// use rocket_dyn_templates::{Template, Metadata}; +/// use rocket_dyn_templates::{Template, Metadata, context}; /// /// #[get("/")] /// fn homepage(metadata: Metadata) -> Template { -/// # use std::collections::HashMap; -/// # let context: HashMap = HashMap::new(); /// // Conditionally render a template if it's available. +/// # let context = (); /// if metadata.contains_template("some-template") { /// Template::render("some-template", &context) /// } else { @@ -78,6 +80,47 @@ impl Metadata<'_> { pub fn reloading(&self) -> bool { self.0.is_reloading() } + + /// Directly render the template named `name` with the context `context` + /// into a `String`. Also returns the template's detected `ContentType`. See + /// [`Template::render()`] for more details on rendering. + /// + /// # Examples + /// + /// ```rust + /// # #[macro_use] extern crate rocket; + /// use rocket::http::ContentType; + /// use rocket_dyn_templates::{Metadata, Template, context}; + /// + /// #[get("/")] + /// fn send_email(metadata: Metadata) -> Option<()> { + /// let (mime, string) = metadata.render("email", context! { + /// field: "Hello, world!" + /// })?; + /// + /// # /* + /// send_email(mime, string).await?; + /// # */ + /// Some(()) + /// } + /// + /// #[get("/")] + /// fn raw_render(metadata: Metadata) -> Option<(ContentType, String)> { + /// metadata.render("index", context! { field: "Hello, world!" }) + /// } + /// + /// // Prefer the following, however, which is nearly identical but pithier: + /// + /// #[get("/")] + /// fn render() -> Template { + /// Template::render("index", context! { field: "Hello, world!" }) + /// } + /// ``` + pub fn render(&self, name: S, context: C) -> Option<(ContentType, String)> + where S: Into>, C: Serialize + { + Template::render(name.into(), context).finalize(&self.0.context()).ok() + } } impl Sentinel for Metadata<'_> { diff --git a/contrib/dyn_templates/src/tera_templates.rs b/contrib/dyn_templates/src/tera_templates.rs index a98bb92d1b..36d17cbfd5 100644 --- a/contrib/dyn_templates/src/tera_templates.rs +++ b/contrib/dyn_templates/src/tera_templates.rs @@ -1,7 +1,7 @@ use std::path::Path; use std::error::Error; -use serde::Serialize; +use rocket::serde::Serialize; use crate::engine::Engine; @@ -42,16 +42,9 @@ impl Engine for Tera { return None; }; - let tera_ctx = match Context::from_serialize(context) { - Ok(ctx) => ctx, - Err(_) => { - error_!( - "Error generating context when rendering Tera template '{}'.", - name - ); - return None; - } - }; + let tera_ctx = Context::from_serialize(context) + .map_err(|e| error_!("Tera context error: {}.", e)) + .ok()?; match Tera::render(self, name, &tera_ctx) { Ok(string) => Some(string), diff --git a/contrib/dyn_templates/tests/templates.rs b/contrib/dyn_templates/tests/templates.rs index 1d91abb0a7..c73927f94a 100644 --- a/contrib/dyn_templates/tests/templates.rs +++ b/contrib/dyn_templates/tests/templates.rs @@ -4,14 +4,13 @@ use std::path::{Path, PathBuf}; use rocket::{Rocket, Build}; use rocket::config::Config; -use rocket_dyn_templates::{Template, Metadata}; +use rocket::figment::value::Value; +use rocket::serde::{Serialize, Deserialize}; +use rocket_dyn_templates::{Template, Metadata, context}; #[get("//")] fn template_check(md: Metadata<'_>, engine: &str, name: &str) -> Option<()> { - match md.contains_template(&format!("{}/{}", engine, name)) { - true => Some(()), - false => None - } + md.contains_template(&format!("{}/{}", engine, name)).then(|| ()) } #[get("/is_reloading")] @@ -98,36 +97,165 @@ fn test_sentinel() { Client::debug_with(routes![always_ok_sentinel]).expect("no sentinel abort"); } +#[test] +fn test_context_macro() { + macro_rules! assert_same_object { + ($ctx:expr, $obj:expr $(,)?) => {{ + let ser_ctx = Value::serialize(&$ctx).unwrap(); + let deser_ctx = ser_ctx.deserialize().unwrap(); + assert_eq!($obj, deser_ctx); + }}; + } + + { + #[derive(Deserialize, PartialEq, Debug)] + #[serde(crate = "rocket::serde")] + struct Empty { } + + assert_same_object!(context! { }, Empty { }); + } + + { + #[derive(Deserialize, PartialEq, Debug)] + #[serde(crate = "rocket::serde")] + struct Object { + a: u32, + b: String, + } + + let a = 93; + let b = "Hello".to_string(); + + fn make_context() -> impl Serialize { + let b = "Hello".to_string(); + + context! { a: 93, b: b } + } + + assert_same_object!( + make_context(), + Object { a, b }, + ); + } + + { + #[derive(Deserialize, PartialEq, Debug)] + #[serde(crate = "rocket::serde")] + struct Outer { + s: String, + inner: Inner, + } + + #[derive(Deserialize, PartialEq, Debug)] + #[serde(crate = "rocket::serde")] + struct Inner { + center: Center, + } + + #[derive(Deserialize, PartialEq, Debug)] + #[serde(crate = "rocket::serde")] + struct Center { + value_a: bool, + value_b: u8, + } + + let a = true; + let value_b = 123; + let outer_string = String::from("abc 123"); + + assert_same_object!( + context! { + s: &outer_string, + inner: context! { + center: context! { + value_a: a, + value_b, + }, + }, + }, + Outer { + s: outer_string, + inner: Inner { + center: Center { + value_a: a, + value_b, + }, + }, + }, + ); + } + + { + #[derive(Deserialize, PartialEq, Debug)] + #[serde(crate = "rocket::serde")] + struct Object { + a: String, + } + + let owned = String::from("foo"); + let ctx = context! { a: &owned }; + assert_same_object!(ctx, Object { a: "foo".into() }); + drop(ctx); + drop(owned); + } +} + #[cfg(feature = "tera")] mod tera_tests { use super::*; use std::collections::HashMap; - use rocket::http::Status; - use rocket::local::blocking::Client; + use rocket::http::{ContentType, Status}; + use rocket::request::FromRequest; const UNESCAPED_EXPECTED: &'static str = "\nh_start\ntitle: _test_\nh_end\n\n\n + +

+ "#) +} + +#[get("/progress", format = "text/event-stream", rank = 1)] +fn progress_stream() -> EventStream![] { + let stream = EventStream! { + let mut interval = time::interval(Duration::from_secs(1)); + + for count in 0..100 { + interval.tick().await; + yield Event::data(count.to_string()).event("progress"); + } + + yield Event::data("").event("done"); + }; + + stream.heartbeat(Duration::from_secs(3)) +} + /***************************** `Redirect` Responder ***************************/ use rocket::response::Redirect; @@ -89,26 +125,26 @@ fn maybe_redir(name: &str) -> Result<&'static str, Redirect> { use rocket::Request; use rocket::response::content; -// NOTE: This example explicitly uses the `Json` type from `response::content` -// for demonstration purposes. In a real application, _always_ prefer to use -// `rocket::serde::json::Json` instead! +// NOTE: This example explicitly uses the `RawJson` type from +// `response::content` for demonstration purposes. In a real application, +// _always_ prefer to use `rocket::serde::json::Json` instead! // In a `GET` request and all other non-payload supporting request types, the // preferred media type in the Accept header is matched against the `format` in // the route attribute. Because the client can use non-specific media types like // `*/*` in `Accept`, these first two routes would collide without `rank`. #[get("/content", format = "xml", rank = 1)] -fn xml() -> content::Xml<&'static str> { - content::Xml("I'm here") +fn xml() -> content::RawXml<&'static str> { + content::RawXml("I'm here") } #[get("/content", format = "json", rank = 2)] -fn json() -> content::Json<&'static str> { - content::Json(r#"{ "payload": "I'm here" }"#) +fn json() -> content::RawJson<&'static str> { + content::RawJson(r#"{ "payload": "I'm here" }"#) } #[catch(404)] -fn not_found(request: &Request<'_>) -> content::Html { +fn not_found(request: &Request<'_>) -> content::RawHtml { let html = match request.format() { Some(ref mt) if !(mt.is_xml() || mt.is_html()) => { format!("

'{}' requests are not supported.

", mt) @@ -118,24 +154,24 @@ fn not_found(request: &Request<'_>) -> content::Html { request.uri()) }; - content::Html(html) + content::RawHtml(html) } /******************************* `Either` Responder ***************************/ use rocket::Either; -use rocket::response::content::{Json, MsgPack}; +use rocket::response::content::{RawJson, RawMsgPack}; use rocket::http::uncased::AsUncased; // NOTE: In a real application, we'd use `Json` and `MsgPack` from // `rocket::serde`, which perform automatic serialization of responses and // automatically set the `Content-Type`. #[get("/content/")] -fn json_or_msgpack(kind: &str) -> Either, MsgPack<&'static [u8]>> { +fn json_or_msgpack(kind: &str) -> Either, RawMsgPack<&'static [u8]>> { if kind.as_uncased() == "msgpack" { - Either::Right(MsgPack(&[162, 104, 105])) + Either::Right(RawMsgPack(&[162, 104, 105])) } else { - Either::Left(Json("\"hi\"")) + Either::Left(RawJson("\"hi\"")) } } @@ -143,7 +179,7 @@ fn json_or_msgpack(kind: &str) -> Either, MsgPack<&'static [u use std::borrow::Cow; -use rocket::response::content::Html; +use rocket::response::content::RawHtml; #[derive(Responder)] enum StoredData { @@ -151,7 +187,7 @@ enum StoredData { String(Cow<'static, str>), Bytes(Vec), #[response(status = 401)] - NotAuthorized(Html<&'static str>), + NotAuthorized(RawHtml<&'static str>), } #[derive(FromFormField, UriDisplayQuery)] @@ -170,7 +206,7 @@ async fn custom(kind: Option) -> StoredData { }, Some(Kind::String) => StoredData::String("Hey, I'm some data.".into()), Some(Kind::Bytes) => StoredData::Bytes(vec![72, 105]), - None => StoredData::NotAuthorized(Html("No no no!")) + None => StoredData::NotAuthorized(RawHtml("No no no!")) } } @@ -178,6 +214,7 @@ async fn custom(kind: Option) -> StoredData { fn rocket() -> _ { rocket::build() .mount("/", routes![many_his, one_hi_per_ms, file, upload, delete]) + .mount("/", routes![progress_stream, progress_page]) .mount("/", routes![redir_root, redir_login, maybe_redir]) .mount("/", routes![xml, json, json_or_msgpack]) .mount("/", routes![custom]) diff --git a/examples/serialization/Cargo.toml b/examples/serialization/Cargo.toml index 1175b33277..b53b924f33 100644 --- a/examples/serialization/Cargo.toml +++ b/examples/serialization/Cargo.toml @@ -2,7 +2,7 @@ name = "serialization" version = "0.0.0" workspace = "../" -edition = "2018" +edition = "2021" publish = false [dependencies.rocket] diff --git a/examples/serialization/src/json.rs b/examples/serialization/src/json.rs index b49a8fe74f..e0cfd61d15 100644 --- a/examples/serialization/src/json.rs +++ b/examples/serialization/src/json.rs @@ -39,7 +39,7 @@ async fn update(id: Id, message: Json>, list: Messages<'_>) -> Optio } #[get("/", format = "json")] -async fn get<'r>(id: Id, list: Messages<'r>) -> Option>> { +async fn get(id: Id, list: Messages<'_>) -> Option>> { let list = list.lock().await; Some(Json(Message { diff --git a/examples/serialization/src/msgpack.rs b/examples/serialization/src/msgpack.rs index f5cd77fdbd..6eccb2a0f4 100644 --- a/examples/serialization/src/msgpack.rs +++ b/examples/serialization/src/msgpack.rs @@ -13,7 +13,7 @@ fn get(id: usize) -> MsgPack> { } #[post("/", data = "", format = "msgpack")] -fn echo<'r>(data: MsgPack>) -> &'r str { +fn echo(data: MsgPack>) -> &str { data.message } diff --git a/examples/serialization/src/uuid.rs b/examples/serialization/src/uuid.rs index 56225028df..15c804b733 100644 --- a/examples/serialization/src/uuid.rs +++ b/examples/serialization/src/uuid.rs @@ -9,9 +9,9 @@ struct People(HashMap); #[get("/people/")] fn people(id: Uuid, people: &State) -> Result { - Ok(people.0.get(&id) + people.0.get(&id) .map(|person| format!("We found: {}", person)) - .ok_or_else(|| format!("Missing person for UUID: {}", id))?) + .ok_or_else(|| format!("Missing person for UUID: {}", id)) } pub fn stage() -> rocket::fairing::AdHoc { diff --git a/examples/state/Cargo.toml b/examples/state/Cargo.toml index 41117c6eb5..c2f518f566 100644 --- a/examples/state/Cargo.toml +++ b/examples/state/Cargo.toml @@ -2,7 +2,7 @@ name = "state" version = "0.0.0" workspace = "../" -edition = "2018" +edition = "2021" publish = false [dependencies] diff --git a/examples/state/src/managed_hit_count.rs b/examples/state/src/managed_hit_count.rs index 6138eead8d..1b02ce7b3b 100644 --- a/examples/state/src/managed_hit_count.rs +++ b/examples/state/src/managed_hit_count.rs @@ -1,15 +1,15 @@ use std::sync::atomic::{AtomicUsize, Ordering}; use rocket::State; -use rocket::response::content; +use rocket::response::content::RawHtml; use rocket::fairing::AdHoc; struct HitCount(AtomicUsize); #[get("/")] -fn index(hit_count: &State) -> content::Html { +fn index(hit_count: &State) -> RawHtml { let count = hit_count.0.fetch_add(1, Ordering::Relaxed) + 1; - content::Html(format!("Your visit is recorded!

Visits: {}", count)) + RawHtml(format!("Your visit is recorded!

Visits: {}", count)) } pub fn stage() -> AdHoc { diff --git a/examples/static-files/Cargo.toml b/examples/static-files/Cargo.toml index 4fab9ba512..0f5cafb18a 100644 --- a/examples/static-files/Cargo.toml +++ b/examples/static-files/Cargo.toml @@ -2,7 +2,7 @@ name = "static-files" version = "0.0.0" workspace = "../" -edition = "2018" +edition = "2021" publish = false [dependencies] diff --git a/examples/templating/Cargo.toml b/examples/templating/Cargo.toml index 9d2146ee1d..1fcee3c365 100644 --- a/examples/templating/Cargo.toml +++ b/examples/templating/Cargo.toml @@ -2,7 +2,7 @@ name = "templating" version = "0.0.0" workspace = "../" -edition = "2018" +edition = "2021" publish = false [dependencies] diff --git a/examples/templating/src/hbs.rs b/examples/templating/src/hbs.rs index 87865ac3ce..5dd3b9eaca 100644 --- a/examples/templating/src/hbs.rs +++ b/examples/templating/src/hbs.rs @@ -1,21 +1,10 @@ use rocket::Request; use rocket::response::Redirect; -use rocket::serde::Serialize; -use rocket_dyn_templates::{Template, handlebars}; +use rocket_dyn_templates::{Template, handlebars, context}; use self::handlebars::{Handlebars, JsonRender}; -#[derive(Serialize)] -#[serde(crate = "rocket::serde")] -struct TemplateContext<'r> { - title: &'r str, - name: Option<&'r str>, - items: Vec<&'r str>, - // This special key tells handlebars which template is the parent. - parent: &'static str, -} - #[get("/")] pub fn index() -> Redirect { Redirect::to(uri!("/hbs", hello(name = "Your Name"))) @@ -23,27 +12,26 @@ pub fn index() -> Redirect { #[get("/hello/")] pub fn hello(name: &str) -> Template { - Template::render("hbs/index", &TemplateContext { + Template::render("hbs/index", context! { title: "Hello", name: Some(name), items: vec!["One", "Two", "Three"], - parent: "hbs/layout", }) } #[get("/about")] pub fn about() -> Template { - let mut map = std::collections::HashMap::new(); - map.insert("title", "About"); - map.insert("parent", "hbs/layout"); - Template::render("hbs/about.html", &map) + Template::render("hbs/about.html", context! { + title: "About", + parent: "hbs/layout", + }) } #[catch(404)] pub fn not_found(req: &Request<'_>) -> Template { - let mut map = std::collections::HashMap::new(); - map.insert("path", req.uri().path().raw()); - Template::render("hbs/error/404", &map) + Template::render("hbs/error/404", context! { + uri: req.uri() + }) } fn wow_helper( @@ -72,6 +60,6 @@ pub fn customize(hbs: &mut Handlebars) { {{/inline}} - {{~> (parent)~}} + {{> hbs/layout}} "#).expect("valid HBS template"); } diff --git a/examples/templating/src/main.rs b/examples/templating/src/main.rs index 72dff9acac..e849f427b7 100644 --- a/examples/templating/src/main.rs +++ b/examples/templating/src/main.rs @@ -5,12 +5,12 @@ mod tera; #[cfg(test)] mod tests; -use rocket::response::content::Html; +use rocket::response::content::RawHtml; use rocket_dyn_templates::Template; #[get("/")] -fn index() -> Html<&'static str> { - Html(r#"See Tera or Handlebars."#) +fn index() -> RawHtml<&'static str> { + RawHtml(r#"See Tera or Handlebars."#) } #[launch] diff --git a/examples/templating/src/tera.rs b/examples/templating/src/tera.rs index 25ea9439a9..8e5e0b8372 100644 --- a/examples/templating/src/tera.rs +++ b/examples/templating/src/tera.rs @@ -1,18 +1,7 @@ -use std::collections::HashMap; - use rocket::Request; use rocket::response::Redirect; -use rocket::serde::Serialize; - -use rocket_dyn_templates::{Template, tera::Tera}; -#[derive(Serialize)] -#[serde(crate = "rocket::serde")] -struct TemplateContext<'r> { - title: &'r str, - name: Option<&'r str>, - items: Vec<&'r str> -} +use rocket_dyn_templates::{Template, tera::Tera, context}; #[get("/")] pub fn index() -> Redirect { @@ -21,7 +10,7 @@ pub fn index() -> Redirect { #[get("/hello/")] pub fn hello(name: &str) -> Template { - Template::render("tera/index", &TemplateContext { + Template::render("tera/index", context! { title: "Hello", name: Some(name), items: vec!["One", "Two", "Three"], @@ -30,16 +19,16 @@ pub fn hello(name: &str) -> Template { #[get("/about")] pub fn about() -> Template { - let mut map = HashMap::new(); - map.insert("title", "About"); - Template::render("tera/about.html", &map) + Template::render("tera/about.html", context! { + title: "About", + }) } #[catch(404)] pub fn not_found(req: &Request<'_>) -> Template { - let mut map = HashMap::new(); - map.insert("path", req.uri().path().raw()); - Template::render("tera/error/404", &map) + Template::render("tera/error/404", context! { + uri: req.uri() + }) } pub fn customize(tera: &mut Tera) { diff --git a/examples/templating/src/tests.rs b/examples/templating/src/tests.rs index 65ca39cd36..afdbc0450c 100644 --- a/examples/templating/src/tests.rs +++ b/examples/templating/src/tests.rs @@ -2,7 +2,7 @@ use super::rocket; use rocket::http::{RawStr, Status, Method::*}; use rocket::local::blocking::Client; -use rocket_dyn_templates::Template; +use rocket_dyn_templates::{Template, context}; fn test_root(kind: &str) { // Check that the redirect works. @@ -18,9 +18,8 @@ fn test_root(kind: &str) { // Check that other request methods are not accepted (and instead caught). for method in &[Post, Put, Delete, Options, Trace, Connect, Patch] { - let mut map = std::collections::HashMap::new(); - map.insert("path", format!("/{}", kind)); - let expected = Template::show(client.rocket(), format!("{}/error/404", kind), &map); + let context = context! { uri: format!("/{}", kind) }; + let expected = Template::show(client.rocket(), format!("{}/error/404", kind), &context); let response = client.req(*method, format!("/{}", kind)).dispatch(); assert_eq!(response.status(), Status::NotFound); @@ -45,7 +44,7 @@ fn test_404(base: &str) { let response = client.get(&path).dispatch(); assert_eq!(response.status(), Status::NotFound); - let response = dbg!(response.into_string().unwrap()); + let response = response.into_string().unwrap(); assert!(response.contains(base)); assert! { diff --git a/examples/templating/templates/hbs/error/404.html.hbs b/examples/templating/templates/hbs/error/404.html.hbs index 81fbc477c8..b1921f4251 100644 --- a/examples/templating/templates/hbs/error/404.html.hbs +++ b/examples/templating/templates/hbs/error/404.html.hbs @@ -6,6 +6,6 @@

404: Hey! There's nothing here.

- The page at {{ path }} does not exist! + The page at {{ uri }} does not exist! diff --git a/examples/templating/templates/hbs/index.html.hbs b/examples/templating/templates/hbs/index.html.hbs index f5b778b8f4..78b237cf7e 100644 --- a/examples/templating/templates/hbs/index.html.hbs +++ b/examples/templating/templates/hbs/index.html.hbs @@ -16,4 +16,4 @@ {{/inline}} -{{~> (parent)~}} +{{> hbs/layout}} diff --git a/examples/templating/templates/tera/error/404.html.tera b/examples/templating/templates/tera/error/404.html.tera index 748f17542c..afda653d20 100644 --- a/examples/templating/templates/tera/error/404.html.tera +++ b/examples/templating/templates/tera/error/404.html.tera @@ -6,6 +6,6 @@

404: Hey! There's nothing here.

- The page at {{ path }} does not exist! + The page at {{ uri }} does not exist! diff --git a/examples/testing/Cargo.toml b/examples/testing/Cargo.toml index 79d053f168..f15eac40c7 100644 --- a/examples/testing/Cargo.toml +++ b/examples/testing/Cargo.toml @@ -2,7 +2,7 @@ name = "testing" version = "0.0.0" workspace = "../" -edition = "2018" +edition = "2021" publish = false [dependencies] diff --git a/examples/tls/Cargo.toml b/examples/tls/Cargo.toml index bb9cb82040..50eb6511e5 100644 --- a/examples/tls/Cargo.toml +++ b/examples/tls/Cargo.toml @@ -2,8 +2,8 @@ name = "tls" version = "0.0.0" workspace = "../" -edition = "2018" +edition = "2021" publish = false [dependencies] -rocket = { path = "../../core/lib", features = ["tls"] } +rocket = { path = "../../core/lib", features = ["tls", "mtls"] } diff --git a/examples/tls/Rocket.toml b/examples/tls/Rocket.toml index 0a1a082781..85f081ba08 100644 --- a/examples/tls/Rocket.toml +++ b/examples/tls/Rocket.toml @@ -9,6 +9,10 @@ certs = "private/rsa_sha256_cert.pem" key = "private/rsa_sha256_key.pem" +[default.tls.mutual] +ca_certs = "private/ca_cert.pem" +mandatory = false + [rsa_sha256.tls] certs = "private/rsa_sha256_cert.pem" key = "private/rsa_sha256_key.pem" diff --git a/examples/tls/private/ca_cert.pem b/examples/tls/private/ca_cert.pem index 8dd268b1cb..55c19e34af 100644 --- a/examples/tls/private/ca_cert.pem +++ b/examples/tls/private/ca_cert.pem @@ -1,33 +1,32 @@ -----BEGIN CERTIFICATE----- -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 +xRjI -----END CERTIFICATE----- diff --git a/examples/tls/private/ca_key.pem b/examples/tls/private/ca_key.pem index 09033c6f7a..6c368b9149 100644 --- a/examples/tls/private/ca_key.pem +++ b/examples/tls/private/ca_key.pem @@ -1,51 +1,51 @@ -----BEGIN RSA PRIVATE KEY----- -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 -----END RSA PRIVATE KEY----- diff --git a/examples/tls/private/ecdsa_nistp256_sha256.p12 b/examples/tls/private/ecdsa_nistp256_sha256.p12 new file mode 100644 index 0000000000..0263e6e1b2 Binary files /dev/null and b/examples/tls/private/ecdsa_nistp256_sha256.p12 differ diff --git a/examples/tls/private/ecdsa_nistp256_sha256_cert.pem b/examples/tls/private/ecdsa_nistp256_sha256_cert.pem index 802e5cec45..3d331d6b33 100644 --- a/examples/tls/private/ecdsa_nistp256_sha256_cert.pem +++ b/examples/tls/private/ecdsa_nistp256_sha256_cert.pem @@ -1,20 +1,21 @@ -----BEGIN CERTIFICATE----- -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 +p2mcGCY= -----END CERTIFICATE----- diff --git a/examples/tls/private/ecdsa_nistp256_sha256_key_pkcs8.pem b/examples/tls/private/ecdsa_nistp256_sha256_key_pkcs8.pem index 13a007ea54..995f4a78e7 100644 --- a/examples/tls/private/ecdsa_nistp256_sha256_key_pkcs8.pem +++ b/examples/tls/private/ecdsa_nistp256_sha256_key_pkcs8.pem @@ -1,5 +1,5 @@ -----BEGIN PRIVATE KEY----- -MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgyomM+167aYfudwIs -7T9VyM7FGJr2cYfpKOOOaeBIzyuhRANCAAQzqFmEN1a7P/mKHJHGgKOpLTFf3KFu -hzC5aUsz3vXSgclet6DxTwGeew5MRxBE9Wom8gS4UHlZL5eVaUyQeKor +MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgz5+60CMzUC7X2U50 +S8KIDYQ6MHUtwMTsHcUrbDhLfLahRANCAAQ7QL6wwC1f2Rrq0iXaERQ7wdquz7HY +1lr8xVr0KK7VM5ll7hTuO0CfL5apbg7UCiu4B5jZtdDKw5NqNIqTJK80 -----END PRIVATE KEY----- diff --git a/examples/tls/private/ecdsa_nistp384_sha384.p12 b/examples/tls/private/ecdsa_nistp384_sha384.p12 new file mode 100644 index 0000000000..786536718f Binary files /dev/null and b/examples/tls/private/ecdsa_nistp384_sha384.p12 differ diff --git a/examples/tls/private/ecdsa_nistp384_sha384_cert.pem b/examples/tls/private/ecdsa_nistp384_sha384_cert.pem index c5754305d2..ce82a9d312 100644 --- a/examples/tls/private/ecdsa_nistp384_sha384_cert.pem +++ b/examples/tls/private/ecdsa_nistp384_sha384_cert.pem @@ -1,21 +1,21 @@ -----BEGIN CERTIFICATE----- -MIIDczCCAVugAwIBAgIJAOIfNU0ricf5MA0GCSqGSIb3DQEBDAUAMEcxCzAJBgNV -BAYTAlVTMQswCQYDVQQIEwJDQTESMBAGA1UEChMJUm9ja2V0IENBMRcwFQYDVQQD -Ew5Sb2NrZXQgUm9vdCBDQTAeFw0yMTAzMTAxNjA4MThaFw0zMTAzMDgxNjA4MTha -MD8xCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJDQTEPMA0GA1UECgwGUm9ja2V0MRIw -EAYDVQQDDAlsb2NhbGhvc3QwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAR69JeIdYW8 -x2qkkOAWZSOQYy2Y1S3biBmalAmJdaH+76mfmkMKTlcGyT5Pxns85sp9sZbBiBxm -Odnh3uMZbqh5ej4zNfIP27NjsnmrQzm1HQqgmgU16e3FZ1Sn4Mbi6kCjGDAWMBQG -A1UdEQQNMAuCCWxvY2FsaG9zdDANBgkqhkiG9w0BAQwFAAOCAgEAg/XC/unGAtLZ -1OOKQcBrCRcHWyw9MpnXL7MnmM1yRWsoSbrYzueU1rpEh/i9wa/hkyVhtdYJ5USf -UFjqUW8OV+sElLMdm8VWxT61DxYxUdZIZB3BtWhI/tQXDhIwv9L2UbFMZHoYiTUA -bgPflpNtZtsPabX0PsusUber/GhkSCnwGADmbnPtre2m9ODvSxYfLVcbDn5kF9rE -/c2lnJMROYlNaAb9+P9hH+k8X++MT0xfbB26y/c3dJsp0JKGajT6ki9NlfitnWvy -csmgIo4QdVOTsbUIrfZX6khOCk18fiqYfHRjg6MnbTiRTncC9iuYYdsRH7Q6/q36 -wUMyh7XOto3R+ejERDTpS0V34SBL9Q+998LNQMAKpU/gUyU9whD/zhTn2GD2uYe8 -8hlYjUy9nSU8qzybPEQUQotgd7AcvMat12ZcQqoUdB/2Rwqw/KQvqtwkcDz1N4Dt -+oJ3jCH6DnC4Ov1Qeyu/PWnc92DRxTmynOv11P/quDoQGrXPKZ+PxEEHktC1yyGi -nff8EPTRzRqLYe+sFPS12MvrWhg7CoMLKxXhqezAH0gmf++bRrOrnkGkmMDbyFFh -YraGkqZaG6X6dK7JyLIXndXv3rx7EfVdEmicIwQ04l7XsirxvYs1ei/wlSzn63k4 -uNj+AnJ0PNOmktTAHzfgHLv+fVgIlcM= +MIIDfjCCAWagAwIBAgIUB+Ff5LDKhcdjusOuaCqjePqScwQwDQYJKoZIhvcNAQEM +BQAwRzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRIwEAYDVQQKDAlSb2NrZXQg +Q0ExFzAVBgNVBAMMDlJvY2tldCBSb290IENBMB4XDTIxMDcwOTIzMzMzM1oXDTMx +MDcwNzIzMzMzM1owPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMQ8wDQYDVQQK +DAZSb2NrZXQxEjAQBgNVBAMMCWxvY2FsaG9zdDB2MBAGByqGSM49AgEGBSuBBAAi +A2IABNkp8NiqSoUc8bwJq0fIRFyvdDN0jUT4+9MdoJ/CJyKHjeVVBcMWXBJbKTmo +rFbkJ6WcUbBU30K0+KTvqX9tFLXOmpwUZDyqmkeU78VV7DJrDKSy5Hgxz5hXJ309 +lz+Kr6MYMBYwFAYDVR0RBA0wC4IJbG9jYWxob3N0MA0GCSqGSIb3DQEBDAUAA4IC +AQATXjqJmDfj0/C1KzSoFgvuiDK6NseMJijkKauaGdHUSGf2P06izvwke8xW3P/b +VifOkpKX3K9RxY4R7xDenTXIEDnKYlp2a77djbef8mBL914ZQSXBFF8Lhz1QD/QC +sIM8exCuelgHbfPh/UdLY1CmEcYOlHQYUpIMYkH7U0KbLvqafY3d7WkERuXwzAUd +kYCAV2V23f2HiuOaX616QYW7Ow6jPrhU1RwEW25Y/Ubw+jQKDSRE6NF+inR7WPot +2GN0ELY+6trxe0w0DL0syOsfF9SVkvgfKhwBKVCsJvCp4HmOIBDlZL40NhrnXK6L +HmUsyckVVMSmPRrvNrIy7m6CoCbdb8wWPlhpygMrOFfhpGJ2fIMzf4JzQnsAKHO9 +1D5mtzaHNNcwBdWNTvVOojy0BRsRrNYcO/Lkf5+VwZ3+AQVPPwG04kk7fA/iONQx +hraiVy6Majl4pFfbWcAOaSDDSMsZ8Joc6AmCiPQGVelrqzZ1wa+a12BBfibqYdm7 +ab831J7KrkK2rfCC84ZdUcICcWkPCisMfPeoaQsp2R4Zw7Rcuyfce8UVZYZsmZ9X +rmgp6O3oIWK31iHkgpb+bQM0YXykbK/fp7vxqnfk2kq+IadSlDwOJ/U8sdNMVHdK +mct9ke+F1KFB+J8UU5w/JK/Tn7HtWY8lf9VTuK8pAkyQAg== -----END CERTIFICATE----- diff --git a/examples/tls/private/ecdsa_nistp384_sha384_key_pkcs8.pem b/examples/tls/private/ecdsa_nistp384_sha384_key_pkcs8.pem index 2ab68ff3dc..a79acff328 100644 --- a/examples/tls/private/ecdsa_nistp384_sha384_key_pkcs8.pem +++ b/examples/tls/private/ecdsa_nistp384_sha384_key_pkcs8.pem @@ -1,6 +1,6 @@ -----BEGIN PRIVATE KEY----- -MIG2AgEAMBAGByqGSM49AgEGBSuBBAAiBIGeMIGbAgEBBDDUm43VOrG74fBAQT7y -CqoKnDbOotrUHGbm/NR5KE3axbiccbQx349ZmvDUqOaZZNChZANiAAR69JeIdYW8 -x2qkkOAWZSOQYy2Y1S3biBmalAmJdaH+76mfmkMKTlcGyT5Pxns85sp9sZbBiBxm -Odnh3uMZbqh5ej4zNfIP27NjsnmrQzm1HQqgmgU16e3FZ1Sn4Mbi6kA= +MIG2AgEAMBAGByqGSM49AgEGBSuBBAAiBIGeMIGbAgEBBDClF5pKlKs9J5iaOAJE +He7v7RfcSt14yMjrp6y1jntK9j9jzTXAGtHCyWwdW0GYTVmhZANiAATZKfDYqkqF +HPG8CatHyERcr3QzdI1E+PvTHaCfwicih43lVQXDFlwSWyk5qKxW5CelnFGwVN9C +tPik76l/bRS1zpqcFGQ8qppHlO/FVewyawyksuR4Mc+YVyd9PZc/iq8= -----END PRIVATE KEY----- diff --git a/examples/tls/private/ed25519.p12 b/examples/tls/private/ed25519.p12 new file mode 100644 index 0000000000..5bbe3a77d1 Binary files /dev/null and b/examples/tls/private/ed25519.p12 differ diff --git a/examples/tls/private/ed25519_cert.pem b/examples/tls/private/ed25519_cert.pem index 0c294cbb07..12997bdb20 100644 --- a/examples/tls/private/ed25519_cert.pem +++ b/examples/tls/private/ed25519_cert.pem @@ -1,20 +1,20 @@ -----BEGIN CERTIFICATE----- -MIIDMjCCARqgAwIBAgIUNAiGpJKcWHB80qLj99td7IXO6QcwDQYJKoZIhvcNAQEL -BQAwRzELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRIwEAYDVQQKEwlSb2NrZXQg -Q0ExFzAVBgNVBAMTDlJvY2tldCBSb290IENBMB4XDTIxMDMxMDE5NDg1MVoXDTMx -MDMwODE5NDg1MVowPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMQ8wDQYDVQQK -DAZSb2NrZXQxEjAQBgNVBAMMCWxvY2FsaG9zdDAqMAUGAytlcAMhAAnWZ6qQExvf -pIrjevFoIX8Yo+VCqPq69fhF93GNNU7PoxgwFjAUBgNVHREEDTALgglsb2NhbGhv -c3QwDQYJKoZIhvcNAQELBQADggIBAJQz+xaTgQ9J8tKLMIGWgK7b8W9YbaXFfKvi -zGUrrP9YKTOVuYF38u99B+mMsDKEEpreFz53viKrN3CK6RgfETMPMWloDdS3yI3z -z+FsJM5jsv2AVdGH0RLZyD8lkZfElzHfSjE3tvAQFe43AWnOliRqjze2Vf8JmJfv -TLJGMUNERI8BKvhdd+q9nubi4SlurRjmPVMDUhJChB7eupOe4OSHEfAwEE3JYEBH -U0xfoGi7LbxE61Ew7GFCgzNKllOgkY5RqrfvjVPjwj5Bl9bleuqqhLfaPyJaftVH -LS9FgK8fCLKqmU7XA98qeAXKy+t17OXteDMV+NuT5Us2b/xGECm9J1+NJDQPRHCT -RMYbh4B/6mzR7Jjw87ByJOjzWnl6XWJ2kvf3ZI2Y3uQeUV7mjZbg2YGfEZFirr9T -+C85BivcN+XLLVYbonqK/sD2dUjh4s9jIELkrcFm9XydGBVRvcrZCFu661Fg8Ro+ -QOBMUH+T0/45s4VKf14S3d7wZAXE1w5yJdz7/yXw1zpeGojgMZrGBZzFRDI9eh9J -1+MrtLKbvxQcQHni696PJ1BkIMX6f8Wjp6gIr4m+MWoJrNi2VIfTQldVbQVhqVmF -URikFHfMDxMpJxsZ45fAwSfHRO5+jwMyB6KOmaSQhS6y4YpLb6Y3j6QG1KL6+kjf -/IPYS11c +MIIDMjCCARqgAwIBAgIUdMGHQoLHGcks+Hnw7dC5dEl0/ogwDQYJKoZIhvcNAQEL +BQAwRzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRIwEAYDVQQKDAlSb2NrZXQg +Q0ExFzAVBgNVBAMMDlJvY2tldCBSb290IENBMB4XDTIxMDcwOTIzMzMzM1oXDTMx +MDcwNzIzMzMzM1owPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMQ8wDQYDVQQK +DAZSb2NrZXQxEjAQBgNVBAMMCWxvY2FsaG9zdDAqMAUGAytlcAMhAP7ORUynwg2q +IbwJwpOThFhc/IhiWxIIACcaiNKPtdEzoxgwFjAUBgNVHREEDTALgglsb2NhbGhv +c3QwDQYJKoZIhvcNAQELBQADggIBAKcrsLA9ijRjE/h8FUNbEz547a8wCy6NskRh +vCLIsC3k3pfhmKatM3BSwrpePFv6iSPIlp6rY9rTYx+vnLGVnT5bjPDA3Q5VwyIF +lAYnbZP7VSQKWr2hLqFd/3sUvg7kSL16nVi4GaRYTAH2W9IQWyx+GKqv6lRmDFwS +TCoPu2YnoboWTYMFdsrxdkzvBkQX+IF45aVTnUbAcLAc7hgZdK6+ZAhIk4ymDDWj +FeGi/hJ5zF9a/zdV+62CHuIwgCT3ETUXeVLKWf6+v2pOMYXmpdPJf5g06zsrpcYY +i+ZdYPXFs4/yzwcUpgYdkpszMJcxgUSn/u2E9/9BFtJa/kwDbHCDItyR2rSeDoUI +2mQY6Kjm8BucM8hBoNYh9HOHEn1450PHIyWzcSMFkhfqSAKzngVcuSmRkUYhIdHu +bUu29CLJzvOCTFxAWd4uWO2EbH5QFOeD9sQjqzadw0KX5kZl3Oe0wJqLswpKXd7m +uQzcIjGNhY3STk722z0sFuZOvZPoi2d46ZKRBIJ9OYQfUzLDWW1PjqIuX7gWOUfe +PaSs8K2qQlfniPJzHFQ3XHB4KJoWP2BcTUh5mkmpq5st5Buox8JUeAH+SalltR+K +Skvvyv6hIhKyUDrgqV3dhIdTiexRLsmosXdps7ifJdmDtJcuWVp5hCS05X5oHTk/ +6WWSkctl -----END CERTIFICATE----- diff --git a/examples/tls/private/ed25519_key.pem b/examples/tls/private/ed25519_key.pem index b66c30ff41..2a1c1e112f 100644 --- a/examples/tls/private/ed25519_key.pem +++ b/examples/tls/private/ed25519_key.pem @@ -1,3 +1,3 @@ -----BEGIN PRIVATE KEY----- -MC4CAQAwBQYDK2VwBCIEIBkz65y9k4wYXTNXgNDhKfJnCiEosnD95sFoVIxWmOzL +MC4CAQAwBQYDK2VwBCIEIKzhuOs4KVtmEBw86yumn8ID4tYm/aPmz8QtBIrlJkTE -----END PRIVATE KEY----- diff --git a/examples/tls/private/gen_certs.sh b/examples/tls/private/gen_certs.sh index edd9c2a732..86e5d5a9b1 100755 --- a/examples/tls/private/gen_certs.sh +++ b/examples/tls/private/gen_certs.sh @@ -46,6 +46,9 @@ function gen_rsa_sha256() { -CA ca_cert.pem -CAkey ca_key.pem -CAcreateserial \ -in server.csr -out rsa_sha256_cert.pem + openssl pkcs12 -export -password pass:rocket \ + -in rsa_sha256_cert.pem -inkey rsa_sha256_key.pem -out rsa_sha256.p12 + rm ca_cert.srl server.csr } @@ -55,10 +58,14 @@ function gen_ed25519() { openssl genpkey -algorithm ED25519 > ed25519_key.pem openssl req -new -key ed25519_key.pem -subj "${SUBJECT}" -out server.csr + openssl x509 -req -extfile <(printf "subjectAltName=${ALT}") -days 3650 \ -CA ca_cert.pem -CAkey ca_key.pem -CAcreateserial \ -in server.csr -out ed25519_cert.pem + openssl pkcs12 -export -password pass:rocket \ + -in ed25519_cert.pem -inkey ed25519_key.pem -out ed25519.p12 + rm ca_cert.srl server.csr } @@ -78,6 +85,9 @@ function gen_ecdsa_nistp256_sha256() { -CA ca_cert.pem -CAkey ca_key.pem -CAcreateserial \ -in server.csr -out ecdsa_nistp256_sha256_cert.pem + openssl pkcs12 -export -password pass:rocket -in ecdsa_nistp256_sha256_cert.pem \ + -inkey ecdsa_nistp256_sha256_key_pkcs8.pem -out ecdsa_nistp256_sha256.p12 + rm ca_cert.srl server.csr ecdsa_nistp256_sha256_key.pem } @@ -97,6 +107,9 @@ function gen_ecdsa_nistp384_sha384() { -CA ca_cert.pem -CAkey ca_key.pem -CAcreateserial \ -in server.csr -out ecdsa_nistp384_sha384_cert.pem + openssl pkcs12 -export -password pass:rocket -in ecdsa_nistp384_sha384_cert.pem \ + -inkey ecdsa_nistp384_sha384_key_pkcs8.pem -out ecdsa_nistp384_sha384.p12 + rm ca_cert.srl server.csr ecdsa_nistp384_sha384_key.pem } diff --git a/examples/tls/private/rsa_sha256.p12 b/examples/tls/private/rsa_sha256.p12 new file mode 100644 index 0000000000..0bf766c35a Binary files /dev/null and b/examples/tls/private/rsa_sha256.p12 differ diff --git a/examples/tls/private/rsa_sha256_cert.pem b/examples/tls/private/rsa_sha256_cert.pem index 17552ab20c..230f0e6d6e 100644 --- a/examples/tls/private/rsa_sha256_cert.pem +++ b/examples/tls/private/rsa_sha256_cert.pem @@ -1,30 +1,30 @@ -----BEGIN CERTIFICATE----- -MIIFITCCAwmgAwIBAgIJAII1fQkonYEEMA0GCSqGSIb3DQEBCwUAMEcxCzAJBgNV -BAYTAlVTMQswCQYDVQQIEwJDQTESMBAGA1UEChMJUm9ja2V0IENBMRcwFQYDVQQD -Ew5Sb2NrZXQgUm9vdCBDQTAeFw0xNzA5MDExMDAyMjhaFw0yNzA4MzAxMDAyMjha -MD8xCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJDQTEPMA0GA1UEChMGUm9ja2V0MRIw -EAYDVQQDEwlsb2NhbGhvc3QwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoIC -AQDqe/Ps0tJf11HBuxJ4HvgC4VJeeiSl3D4P8ZT6uamCj8XD0MPtfRjGgfZPRjfY -ksiYRs4Wg3Wy3aiQR6IVrNAxtfU1ZA3vRGCBwV0oWkfyPJKQOtF0Ih0/MhmYdiWG -gDqs5qF/6B9K8qbinexal8v1oXpwQC5dod/NOuSLZQtQfkiYIeNqo0BbxtcaNE2u -kgOYg1Cvc9ui3KPNA2JTN+Uzq6A8n4Pej6erG2NeCAoov9nrkPyustDWLQ76wdTp -5YU6zwwsl+fJtb5scNUmagujoXTTqn06WoCMDUsSjC/jlGMIrzmx90Wq8Dg6HBGn -Cscz3M/AUXYzJtShkxMNZCsdxH+8x5oyO/RrtyeRyN8iDiOolz+SfQROVXMU0zkx -nRl7hIxgB/QeDi6MMXGLTd08vpIAohk3hnycsGgTwTCT5LxWJnorpm4wdr1bDmCY -InUO5hX0rFWtS0ij78GTUbpajkNTEXIXXwa1VnSE2kIeUX6aiKhJsm3KWp496JuM -ahIR7XCP9PyGclWI+Pa0eq5L8nnuSfqUAwCeOvvwdBOxUvKmecly1IHLoUXGnhy0 -46MjYo80yYFqrGgop6lUEZ0ThYpDpMxq+JIeUoyGaCJFDvundzt0u0sh9i+hUCVe -v3zsgxwvBeJy0L1G1uGkpCqERkYJQt9O+qLM8i7hf7ONkQIDAQABoxgwFjAUBgNV -HREEDTALgglsb2NhbGhvc3QwDQYJKoZIhvcNAQELBQADggIBAAcXycXdWVvwLl+7 -ryG8V7FpB9bp0lHNA4q3DpEINCNyuA2cbnVU/u2L3ddvroTcrPjE+hhNbcVaz/NH -w4sQqlDzkV+G9kZ4qBTlk5zon6aGGow181J+B5SVznt6lO4/KYYpEN0vX+uMvsgK -OG7ydsRMDxPpsnVS9SFx0Ke8AlmUet5S/NGYCfedd4rwCu+oJHUWhXNwFZqLF3Yn -s8lg3xdM0kJt8g4m1/KUpunanX3w+DdZaIwbltEZs4NriXn0VVbEPRpHyiGMosgf -mEUV2z49f6S2joEnSn2Y/ILOdKFQ2mKFXtXJP43Qzj8Mr5mSb2bXyABlrn0pl/+o -HBkyVyDx5BKqWKe5uK3YCDsbIJj026AkCdTKF+BSBWfB+EqdSIOvVrpHtQK7BwFx -pS5rdQBLA86f1NC0e235L6pwFKm+imazr6Jn7fbbwq1y9PSL36rUn4e/+R2Yoia9 -S7zDOqGbnyv9h7eE3Muiy26kJsJfCrjse/dmce+6YnB1FC5RKPn7kM86t7MyDrgx -W60xRMdgmcGfPjei2V4MdVM6ysOlNoeh39DizjkV9+r8iGl4vngplJrPgAIvywQz -v1pLk6dSlSOwgqY94hqxqNvG80xSoYsmMjDrPmtBVERjhbffsdIDHjcPVsJKH6l6 -8wg+/u6aK2bMHt41f3XE/UTY+A57 +MIIFLDCCAxSgAwIBAgIUNMz1ihOL/c1J1sgYy1c3ehB5z2cwDQYJKoZIhvcNAQEL +BQAwRzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRIwEAYDVQQKDAlSb2NrZXQg +Q0ExFzAVBgNVBAMMDlJvY2tldCBSb290IENBMB4XDTIxMDcwOTIzMzMzM1oXDTMx +MDcwNzIzMzMzM1owPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMQ8wDQYDVQQK +DAZSb2NrZXQxEjAQBgNVBAMMCWxvY2FsaG9zdDCCAiIwDQYJKoZIhvcNAQEBBQAD +ggIPADCCAgoCggIBAMdnhZbeSDVddiKDOf+ZXjlChpgsiIizflHLHu4sWob3ZrwW +BiICo2fezTZojcvFaMJooojlShENuLLxnPgc5O6WZiElR8vwAV/1ZJBzSdtplj/F +NeT2AwR9Maw/XfQ7/Mg7z+svCrXwWq95RHs2Dd4Mci6WrQuDEs2rTlodNoA1KHu/ +ll+YTkAn9rhSjkMu3hM2MLYO0dGhAKm2FTEmeYvmbo5ZIoiMcC7I5jJpWlnA/niE +jCvku0CWXJSIrlFU36G0FzbkJOvnl/RlSr5jjEs8607Wf26wlCP6R880BzZKdNoi +zzbc2Vj76kHuyOX2LAQ7v51p9n8PNuxnFJtJFnEPVXYlMenwgf63ElqQx8SoemlT +ZT/yJv49qYHPXOEs8aoxeT9QhZ+3DtB43LOkxbUSsIQs7RNWTbZQIqi7eHi1PkFg +yoHUKnWGLo1narDdlr0yvBz4FrnBTcb6JHCYK1dVm2+y7XspKDX4/8ymG3VOaPf6 +AoafSHoL/eF2sfK7DL4pTv5sDDQiBafL3+KWOMRD/UoVEvriPdgnuwf9sNGdM/rY +1vHjUgVnsD3UnkIoT7mhLKF+budS6KUaSh3ZA8+C8a82Zyeznxf9luR7hs7edt7G +ehcyTJ3WfNOKslmXnvrwhJ7zHpd//TU9hkBJLyve1zNtZPsJH7N94wfUYd1nAgMB +AAGjGDAWMBQGA1UdEQQNMAuCCWxvY2FsaG9zdDANBgkqhkiG9w0BAQsFAAOCAgEA +r7yYMGxmRTtDyN49y+pMbyiIjpKj8VW2TEfPFQvvOIRlGj6GT6EQMdeTigp9t+Sl +v0lyMv6DjNPANzFAPvMdtQBU3SC1Grd1CtvRXqy290B2WV01Kpj4Yfi7+HMQgy6G +FEytkm+FEUQjF2fwxsiMrSVeaVX7a67fSxXqzzANQToE994IdW/qQmlCuQvh0J8D +N6IGY5N7tVIWDKJpH/YmKbe20dFdSk2NTHTZpLLm4Eqe/gG8qIUf6RBJgiqxJV0y +YPKM3qXdwmwVFe/+EkX6BO3xqDmjqCi4eQRAbTDEmHqO4zVdXBQMkeRTWwH68r4D +zRvZOA+ZDpnIMiSKozn6ZKM1py5m8BT2rD1ZRoMxNpaVauZzIu4V90oOB7Bii7hC +HZDsHeX9kiGdeslSsyWYBEpeEeuf0MEz11pfROG2/zwk6StGPvK0xaKkRFifiTFq +I1RSV0vG78zS73eTm5EABfAsAQTjQjkfnJEiTueMqoD8NMCgyogeuVr6p7DzDHgh +3VlzcImwOMSt1P1IRS5zty9AZR60Vrup33jYjCBj+GOQvU55etoHZV9PazEXbmN0 +v/zzIVvK3wF9NluX/ItSGTJkX+EDSCbFbp2U9C27XRHAIi+vRLYIZuWi3oLU8uLN +bLlrSSTY/OmBxlmyayzPFElY5Qd8FHLQPF+his89eP4= -----END CERTIFICATE----- diff --git a/examples/tls/private/rsa_sha256_key.pem b/examples/tls/private/rsa_sha256_key.pem index afcf14a3e8..bf953e6b5a 100644 --- a/examples/tls/private/rsa_sha256_key.pem +++ b/examples/tls/private/rsa_sha256_key.pem @@ -1,51 +1,52 @@ ------BEGIN RSA PRIVATE KEY----- -MIIJKAIBAAKCAgEA6nvz7NLSX9dRwbsSeB74AuFSXnokpdw+D/GU+rmpgo/Fw9DD -7X0YxoH2T0Y32JLImEbOFoN1st2okEeiFazQMbX1NWQN70RggcFdKFpH8jySkDrR -dCIdPzIZmHYlhoA6rOahf+gfSvKm4p3sWpfL9aF6cEAuXaHfzTrki2ULUH5ImCHj -aqNAW8bXGjRNrpIDmINQr3PbotyjzQNiUzflM6ugPJ+D3o+nqxtjXggKKL/Z65D8 -rrLQ1i0O+sHU6eWFOs8MLJfnybW+bHDVJmoLo6F006p9OlqAjA1LEowv45RjCK85 -sfdFqvA4OhwRpwrHM9zPwFF2MybUoZMTDWQrHcR/vMeaMjv0a7cnkcjfIg4jqJc/ -kn0ETlVzFNM5MZ0Ze4SMYAf0Hg4ujDFxi03dPL6SAKIZN4Z8nLBoE8Ewk+S8ViZ6 -K6ZuMHa9Ww5gmCJ1DuYV9KxVrUtIo+/Bk1G6Wo5DUxFyF18GtVZ0hNpCHlF+moio -SbJtylqePeibjGoSEe1wj/T8hnJViPj2tHquS/J57kn6lAMAnjr78HQTsVLypnnJ -ctSBy6FFxp4ctOOjI2KPNMmBaqxoKKepVBGdE4WKQ6TMaviSHlKMhmgiRQ77p3c7 -dLtLIfYvoVAlXr987IMcLwXictC9RtbhpKQqhEZGCULfTvqizPIu4X+zjZECAwEA -AQKCAgAxmpc3ekHW1I4PFawKjUKaGWB7bAtkqvrWFJ0XjT82x4NmsTtBej1LgSLC -EnCt+B9HV3MxgA3eENYf74dyXmSMn5mH+eqYuzZPPMCgULj3najDqi21C6J0Q/z2 -K8g0c9v1x7RSgqBcEokLV60wXPxgshBcvrcQR7Y4jETc2DtUg+KHjGO3o2FyCNZo -TLhCPdFU6jKfazsDcPmV3SlnwWNTUvNK39PduTYXFGwo8Dp19F/9XWaW7m0PYejR -Uz/fWxacIkDJDjmSikgGWLg+sCBWNUmpnV9wgMTA2+8NtWpMEpAAvlDOPSkXyEmc -wWNamwUZC5VHcfQ3TfedVqepJY+ZDNNaZ6O+GH7Qe33jxdyXbt8CSEI52lDDotfX -rwjI8//qnoDGmwzBNThBTjXyrAbwn/KzfYXvPMfMd1GB2YPG0WmcZhFNuEm6f4Pf -5vhQldT/Wd1RBbGTVDYo/49uSNAwTu9ObW7o50obUfyW0bUgopBaZBwRfOBFJ1QU -PFCRqCv16STPr8AaeP2nlZawsC5ECbzdBRxvHG6P2FCOdgclWhZNlMdRydFTI5QJ -aAfgkHYT8DFtZ/P0fbc2csFaOWNd3vSp07TCgqff6vgR8jGJDRnC+Oq4Q8rERiFw -A7O/TzjYskY8aMkM4mvSfmnqo7Qqv+XPgDbfWi9tq8nrDYzSAQKCAQEA+VAUqyCN -DvtkMGbd8AyYNx738K3Sea+/t+y2X1V1q93+TKypcrpZ0KhrnKGxf2UnJZx31NOX -vdXUwNu/I9/lnOuJlR7yVC0E185v+j0GQRZRjwTv6qUEBnHRViEkpy0j3INiVg8t -aLbrg5NoD4vlgocSFP2IDD+dFkDS4oKebXfuQFtvW8qd769RzjQAGHTje+Fk1US/ -ADgDPINoZOyhuyA9r8Q9BfrhksliB80a3q+ieHPpaYAa+9NT6B3SZfVgzblj4mfs -nHDAor4ZYpJ6sLB5pcUG5DILVx1ncO2S0qO53w3P5j4jatz4KZWheOSQQkSCWwP5 -qAEMw28tv0ezmQKCAQEA8MYM8v/3FRlct/lLCzA+Smq+ZvdXyTpM9fICvSaBD6WT -/xYguTUbzWB8WBzMCDK3quttBrWCMIRWzEfEPE51db+0MycoAjM7sw2nql3tgFy5 -OZV4g5lzPnWsh76ba8xq2x5h8j1sbsvTWZoxD5/fcXEEAvwMFTvgm39T+NyMoAZ0 -PMO3x7sZiI5GLLZ5wmjlb1dEbxHujPIJNuSJtdNjecRhyhPcairK8dfjQaStgyE3 -O9hGCBYOzz0n4O76dJmH1g1HAmG4RvZU6zC3lDITXhgQ9pVH50qS1oI7jLhn3QoY -SfdZ+LDC/8nDVcPLX+JFL95ha80o/K5PQ7uWXXNkuQKCAQEAuASwzMLg+x75C3TR -+d4B+CWGkoJqaWEcnHA/CEz25t2bVxLWm5UKuCWoEFuUvNh3tZ4xIMjxJrCPMa7A -/YTEYTfFPGk0Kod0HKoGIukqFZ6YonzdbQ9R0kPuZKlf+XkrEBd13NmlBbaGTX7e -/yKeS+LQqOedpJTLqOI+BeytbVVpaN1Ua6c5PfHk6tOdAnA8fHKYT4ZHiKzPTrob -suqqUYlxnqu08xYDq6mzDtkILTfsLwY3UaS5xghs1VY1twYP5qkhHbrhfXMH7Ndt -u0EtB/+qOn4cIREDJ9DPSh5BEfLBPe9e9a4FzFm/XkpQfgAOrqsMoItlmej0d8g3 -NwmAeQKCAQBNfiDK0RFQLCKIX+cESdmyj9qKP090x5vfiK3S/SKKy6rvbcrIcUxq -dIRww4vzk4dDrpQflam6Pc3F389L7aCmbjXsRMz+sEiln154WdTH/I/s9audB3Vt -A+iso+9X6an2rjeuBJDytA1pCFSEB9udolc9Mqwc5XGr+nYnYaytEIa2y/NJiHF2 -Xvw9Bdn4dVRq2nZ/HRFfMcM/dJzR9aBNn6QtqujFDtLUtbxB82OZEca6LyiTD65i -ivdb0O6xOnzaqtlQ7eymgj/gloRvYRKUtUA4bOGAkqLiAXZzGyLqpIYewEqn3RRV -yTViVCsPyD6mYneOf7CSavO+BBEoMKyZAoIBAAF2bGafAIIfxG2wT19Trd6NTFeA -5GuejnWZBJUJPlIMiwhiorOMOxhJjsfDQxVv/jhWOf86gpLctMIFBHqwIVAwLRVB -SX0vx6/BUkDsnqEEsyp8x2MKsojvG63QX2R5DJTlP6/YrtVJj46euboygc6j+mV8 -alhiH3UfKKs2GtbIhd34tafRYs9/SvJ95QeoJyVoYy7mLgrFgQN2g2TMwDle/F2h -kmko+yuLbj5CNe/x4/9pTRTFdoF75RLkaWuf81FHO4c1Z5D5niEX+0a94Y3LglWe -2YIWhS3TbGPAfyGsnmnTsDtsbriNDwLkmMW7wr6Um+L/LoRVeJhoKxv8LsQ= ------END RSA PRIVATE KEY----- +-----BEGIN PRIVATE KEY----- +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 +P8TQRNCBnG+P8u4TcF4+aFcjAlBHOUg= +-----END PRIVATE KEY----- diff --git a/examples/tls/src/main.rs b/examples/tls/src/main.rs index 9ec332547f..7cd59828ef 100644 --- a/examples/tls/src/main.rs +++ b/examples/tls/src/main.rs @@ -2,7 +2,14 @@ #[cfg(test)] mod tests; +use rocket::mtls::Certificate; + #[get("/")] +fn mutual(cert: Certificate<'_>) -> String { + format!("Hello! Here's what we know: [{}] {}", cert.serial(), cert.subject()) +} + +#[get("/", rank = 2)] fn hello() -> &'static str { "Hello, world!" } @@ -10,5 +17,6 @@ fn hello() -> &'static str { #[launch] fn rocket() -> _ { // See `Rocket.toml` and `Cargo.toml` for TLS configuration. - rocket::build().mount("/", routes![hello]) + // Run `./private/gen_certs.sh` to generate a CA and key pairs. + rocket::build().mount("/", routes![hello, mutual]) } diff --git a/examples/todo/Cargo.toml b/examples/todo/Cargo.toml index a6bc43a3da..3aac187464 100644 --- a/examples/todo/Cargo.toml +++ b/examples/todo/Cargo.toml @@ -2,16 +2,16 @@ name = "todo" version = "0.0.0" workspace = "../" -edition = "2018" +edition = "2021" publish = false [dependencies] rocket = { path = "../../core/lib" } -diesel = { version = "1.3", features = ["sqlite", "r2d2"] } -diesel_migrations = "1.3" +diesel = { version = "2.0.0", features = ["sqlite", "r2d2"] } +diesel_migrations = "2.0.0" [dev-dependencies] -parking_lot = "0.11" +parking_lot = "0.12" rand = "0.8" [dependencies.rocket_sync_db_pools] diff --git a/examples/todo/src/main.rs b/examples/todo/src/main.rs index fb36aacc05..96763545aa 100644 --- a/examples/todo/src/main.rs +++ b/examples/todo/src/main.rs @@ -1,7 +1,6 @@ #[macro_use] extern crate rocket; -#[macro_use] extern crate diesel; -#[macro_use] extern crate diesel_migrations; #[macro_use] extern crate rocket_sync_db_pools; +#[macro_use] extern crate diesel; #[cfg(test)] mod tests; @@ -93,13 +92,14 @@ async fn index(flash: Option>, conn: DbConn) -> Template { } async fn run_migrations(rocket: Rocket) -> Rocket { - // This macro from `diesel_migrations` defines an `embedded_migrations` - // module containing a function named `run`. This allows the example to be - // run and tested without any outside setup of the database. - embed_migrations!(); + use diesel_migrations::{embed_migrations, EmbeddedMigrations, MigrationHarness}; + + const MIGRATIONS: EmbeddedMigrations = embed_migrations!("migrations"); - let conn = DbConn::get_one(&rocket).await.expect("database connection"); - conn.run(|c| embedded_migrations::run(c)).await.expect("can run migrations"); + DbConn::get_one(&rocket).await + .expect("database connection") + .run(|conn| { conn.run_pending_migrations(MIGRATIONS).expect("diesel migrations"); }) + .await; rocket } diff --git a/examples/todo/src/task.rs b/examples/todo/src/task.rs index ce4067c1a0..eb93ffe74c 100644 --- a/examples/todo/src/task.rs +++ b/examples/todo/src/task.rs @@ -12,14 +12,14 @@ mod schema { } use self::schema::tasks; -use self::schema::tasks::dsl::{tasks as all_tasks, completed as task_completed}; use crate::DbConn; #[derive(Serialize, Queryable, Insertable, Debug, Clone)] #[serde(crate = "rocket::serde")] -#[table_name="tasks"] +#[diesel(table_name = tasks)] pub struct Task { + #[serde(skip_deserializing)] pub id: Option, pub description: String, pub completed: bool @@ -33,7 +33,7 @@ pub struct Todo { impl Task { pub async fn all(conn: &DbConn) -> QueryResult> { conn.run(|c| { - all_tasks.order(tasks::id.desc()).load::(c) + tasks::table.order(tasks::id.desc()).load::(c) }).await } @@ -48,21 +48,24 @@ impl Task { /// Returns the number of affected rows: 1. pub async fn toggle_with_id(id: i32, conn: &DbConn) -> QueryResult { conn.run(move |c| { - let task = all_tasks.find(id).get_result::(c)?; + let task = tasks::table.filter(tasks::id.eq(id)).get_result::(c)?; let new_status = !task.completed; - let updated_task = diesel::update(all_tasks.find(id)); - updated_task.set(task_completed.eq(new_status)).execute(c) + let updated_task = diesel::update(tasks::table.filter(tasks::id.eq(id))); + updated_task.set(tasks::completed.eq(new_status)).execute(c) }).await } /// Returns the number of affected rows: 1. pub async fn delete_with_id(id: i32, conn: &DbConn) -> QueryResult { - conn.run(move |c| diesel::delete(all_tasks.find(id)).execute(c)).await + conn.run(move |c| diesel::delete(tasks::table) + .filter(tasks::id.eq(id)) + .execute(c)) + .await } /// Returns the number of affected rows. #[cfg(test)] pub async fn delete_all(conn: &DbConn) -> QueryResult { - conn.run(|c| diesel::delete(all_tasks).execute(c)).await + conn.run(|c| diesel::delete(tasks::table).execute(c)).await } } diff --git a/examples/todo/src/tests.rs b/examples/todo/src/tests.rs index 286f73aed8..5c2eadd7bd 100644 --- a/examples/todo/src/tests.rs +++ b/examples/todo/src/tests.rs @@ -138,9 +138,8 @@ fn test_bad_form_submissions() { .dispatch() .await; - let mut cookies = res.headers().get("Set-Cookie"); + assert!(!res.cookies().iter().any(|c| c.value().contains("error"))); assert_eq!(res.status(), Status::UnprocessableEntity); - assert!(!cookies.any(|value| value.contains("error"))); // Submit a form with an empty description. We look for 'error' in the // cookies which corresponds to flash message being set as an error. @@ -150,8 +149,18 @@ fn test_bad_form_submissions() { .dispatch() .await; - let mut cookies = res.headers().get("Set-Cookie"); - assert!(cookies.any(|value| value.contains("error"))); + // Check that the flash cookie set and that we're redirected to index. + assert!(res.cookies().iter().any(|c| c.value().contains("error"))); + assert_eq!(res.status(), Status::SeeOther); + + // The flash cookie should still be present and the error message should + // be rendered the index. + let body = client.get("/").dispatch().await.into_string().await.unwrap(); + assert!(body.contains("Description cannot be empty.")); + + // Check that the flash is cleared upon another visit to the index. + let body = client.get("/").dispatch().await.into_string().await.unwrap(); + assert!(!body.contains("Description cannot be empty.")); // Submit a form without a description. Expect a 422 but no flash error. let res = client.post("/todo") @@ -160,8 +169,7 @@ fn test_bad_form_submissions() { .dispatch() .await; - let mut cookies = res.headers().get("Set-Cookie"); + assert!(!res.cookies().iter().any(|c| c.value().contains("error"))); assert_eq!(res.status(), Status::UnprocessableEntity); - assert!(!cookies.any(|value| value.contains("error"))); }) } diff --git a/examples/todo/static/index.html.tera b/examples/todo/static/index.html.tera index 369ae3643c..a6f77f1db0 100644 --- a/examples/todo/static/index.html.tera +++ b/examples/todo/static/index.html.tera @@ -23,10 +23,10 @@
- {% if msg %} - - {{ msg.1 }} + class="u-full-width {% if flash %}field-{{flash.0}}{% endif %}" /> + {% if flash %} + + {{ flash.1 }} {% endif %}
diff --git a/scripts/config.sh b/scripts/config.sh index c52d810e13..07c3ab65d5 100755 --- a/scripts/config.sh +++ b/scripts/config.sh @@ -41,6 +41,7 @@ CORE_ROOT=$(relative "core") || exit $? CONTRIB_ROOT=$(relative "contrib") || exit $? SITE_ROOT=$(relative "site") || exit $? BENCHMARKS_ROOT=$(relative "benchmarks") || exit $? +FUZZ_ROOT=$(relative "core/lib/fuzz") || exit $? # Root of project-like directories. CORE_LIB_ROOT=$(relative "core/lib") || exit $? @@ -64,7 +65,7 @@ PRE_RELEASE=true case $PRE_RELEASE in true) CODENAME="${VIRTUAL_CODENAME}" - DOC_VERSION="${CODENAME}-$(future_date)" + DOC_VERSION="${VERSION}-$(future_date)" ;; false) CODENAME="${PHYSICAL_CODENAME}" @@ -72,14 +73,30 @@ case $PRE_RELEASE in ;; esac -ALL_PROJECT_DIRS=( +CORE_CRATE_ROOTS=( "${CORE_HTTP_ROOT}" "${CORE_CODEGEN_ROOT}" "${CORE_LIB_ROOT}" ) -CONTRIB_LIB_DIRS=( - "${CONTRIB_ROOT}/sync_db_pools" +CONTRIB_SYNC_DB_POOLS_CRATE_ROOTS=( + "${CONTRIB_ROOT}/sync_db_pools/lib" + "${CONTRIB_ROOT}/sync_db_pools/codegen" +) + +CONTRIB_DB_POOLS_CRATE_ROOTS=( + "${CONTRIB_ROOT}/db_pools/lib" + "${CONTRIB_ROOT}/db_pools/codegen" +) + +ALL_CRATE_ROOTS=( + "${CORE_HTTP_ROOT}" + "${CORE_CODEGEN_ROOT}" + "${CORE_LIB_ROOT}" + "${CONTRIB_ROOT}/sync_db_pools/codegen" + "${CONTRIB_ROOT}/sync_db_pools/lib" + "${CONTRIB_ROOT}/db_pools/codegen" + "${CONTRIB_ROOT}/db_pools/lib" "${CONTRIB_ROOT}/dyn_templates" ) @@ -87,6 +104,8 @@ function print_environment() { echo " VERSION: ${VERSION}" echo " MAJOR_VERSION: ${MAJOR_VERSION}" echo " CODENAME: ${CODENAME}" + echo " PHYSICAL_CODENAME: ${PHYSICAL_CODENAME}" + echo " VIRTUAL_CODENAME: ${VIRTUAL_CODENAME}" echo " DOC_VERSION: ${DOC_VERSION}" echo " CURRENT_RELEASE: ${CURRENT_RELEASE}" echo " PRE_RELEASE: ${PRE_RELEASE}" @@ -102,8 +121,7 @@ function print_environment() { echo " GUIDE_TESTS_ROOT: ${GUIDE_TESTS_ROOT}" echo " EXAMPLES_DIR: ${EXAMPLES_DIR}" echo " DOC_DIR: ${DOC_DIR}" - echo " ALL_PROJECT_DIRS: ${ALL_PROJECT_DIRS[*]}" - echo " CONTRIB_LIB_DIRS: ${CONTRIB_LIB_DIRS[*]}" + echo " ALL_CRATE_ROOTS: ${ALL_CRATE_ROOTS[*]}" echo " date(): $(future_date)" } diff --git a/scripts/mk-docs.sh b/scripts/mk-docs.sh index e91550ada5..bb0c7375a6 100755 --- a/scripts/mk-docs.sh +++ b/scripts/mk-docs.sh @@ -21,7 +21,8 @@ echo ":::: Generating the docs..." pushd "${PROJECT_ROOT}" > /dev/null 2>&1 # Set the crate version and fill in missing doc URLs with docs.rs links. RUSTDOCFLAGS="-Zunstable-options --crate-version ${DOC_VERSION}" \ - cargo doc -p rocket -p rocket_sync_db_pools -p rocket_dyn_templates \ + cargo doc -p rocket \ + -p rocket_sync_db_pools -p rocket_dyn_templates -p rocket_db_pools \ -Zrustdoc-map --no-deps --all-features popd > /dev/null 2>&1 diff --git a/scripts/publish.sh b/scripts/publish.sh index 986eddd28d..cdef8aed98 100755 --- a/scripts/publish.sh +++ b/scripts/publish.sh @@ -9,14 +9,6 @@ set -e SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" source "${SCRIPT_DIR}/config.sh" -function strip_dev_dependencies() { - perl -i.bak -p0e 's/\[dev-dependencies\].*//smg' "${1}/Cargo.toml" -} - -function restore_dev_dependencies() { - mv "${1}/Cargo.toml.bak" "${1}/Cargo.toml" -} - if ! [ -z "$(git status --porcelain)" ]; then echo "There are uncommitted changes! Aborting." exit 1 @@ -28,23 +20,13 @@ cargo clean bash "${SCRIPT_DIR}/test.sh" +stable --all bash "${SCRIPT_DIR}/test.sh" +stable --all --release -# Temporarily remove dev-dependencies so crates.io verifies. -echo ":::: Stripping [dev-dependencies]..." -for dir in "${ALL_PROJECT_DIRS[@]}"; do - strip_dev_dependencies "${dir}" -done - # Publish all the things. -for dir in "${ALL_PROJECT_DIRS[@]}"; do +for dir in "${ALL_CRATE_ROOTS[@]}"; do pushd "${dir}" echo ":::: Publishing '${dir}'..." # We already checked things ourselves. Don't spend time reverifying. cargo publish --no-verify --allow-dirty ${@:1} + # Give the index some time to update so the deps are there if we need them. + sleep 5 popd done - -# Restore dev-dependencies. -echo ":::: Restoring [dev-dependencies]..." -for dir in "${ALL_PROJECT_DIRS[@]}"; do - restore_dev_dependencies "${dir}" -done diff --git a/scripts/test.sh b/scripts/test.sh index 616d78306c..7f8607b040 100755 --- a/scripts/test.sh +++ b/scripts/test.sh @@ -8,6 +8,7 @@ source "${SCRIPT_DIR}/config.sh" # Add Cargo to PATH. export PATH=${HOME}/.cargo/bin:${PATH} export CARGO_INCREMENTAL=0 +export RUSTC_BOOTSTRAP=1 CARGO="cargo" # Checks that the versions for Cargo projects $@ all match @@ -56,9 +57,33 @@ function check_style() { echo "${matches}" exit 1 fi + + local pattern='tail -n 1 % | grep -q "^$" && echo %' + local matches=$(git grep -z -Il '' | xargs -0 -P 16 -I % sh -c "${pattern}") + if ! [ -z "${matches}" ]; then + echo "Trailing new line(s) found in the following:" + echo "${matches}" + exit 1 + fi +} + +function indir() { + local dir="${1}" + shift + pushd "${dir}" > /dev/null 2>&1 ; $@ ; popd > /dev/null 2>&1 } function test_contrib() { + DB_POOLS_FEATURES=( + deadpool_postgres + deadpool_redis + sqlx_mysql + sqlx_postgres + sqlx_sqlite + sqlx_mssql + mongodb + ) + SYNC_DB_POOLS_FEATURES=( diesel_postgres_pool diesel_sqlite_pool @@ -73,6 +98,11 @@ function test_contrib() { handlebars ) + for feature in "${DB_POOLS_FEATURES[@]}"; do + echo ":: Building and testing db_pools [$feature]..." + $CARGO test -p rocket_db_pools --no-default-features --features $feature $@ + done + for feature in "${SYNC_DB_POOLS_FEATURES[@]}"; do echo ":: Building and testing sync_db_pools [$feature]..." $CARGO test -p rocket_sync_db_pools --no-default-features --features $feature $@ @@ -88,53 +118,57 @@ function test_core() { FEATURES=( secrets tls + mtls + http2 json msgpack uuid ) - pushd "${CORE_LIB_ROOT}" > /dev/null 2>&1 - echo ":: Building and testing core [no features]..." - $CARGO test --no-default-features $@ + echo ":: Building and checking core [no features]..." + RUSTDOCFLAGS="-Zunstable-options --no-run" \ + indir "${CORE_LIB_ROOT}" $CARGO test --no-default-features $@ - for feature in "${FEATURES[@]}"; do - echo ":: Building and testing core [${feature}]..." - $CARGO test --no-default-features --features "${feature}" $@ - done - popd > /dev/null 2>&1 + for feature in "${FEATURES[@]}"; do + echo ":: Building and checking core [${feature}]..." + RUSTDOCFLAGS="-Zunstable-options --no-run" \ + indir "${CORE_LIB_ROOT}" $CARGO test --no-default-features --features "${feature}" $@ + done } function test_examples() { + # Cargo compiles Rocket once with the `secrets` feature enabled, so when run + # in production, we need a secret key or tests will fail needlessly. We test + # in core that secret key failing/not failing works as expected, but here we + # provide a valid secret_key so tests don't fail. echo ":: Building and testing examples..." - - pushd "${EXAMPLES_DIR}" > /dev/null 2>&1 - # Rust compiles Rocket once with the `secrets` feature enabled, so when run - # in production, we need a secret key or tests will fail needlessly. We - # test in core that secret key failing/not failing works as expected. - ROCKET_SECRET_KEY="itlYmFR2vYKrOmFhupMIn/hyB6lYCCTXz4yaQX89XVg=" \ - $CARGO test --all $@ - popd > /dev/null 2>&1 -} + indir "${EXAMPLES_DIR}" $CARGO update + ROCKET_SECRET_KEY="itlYmFR2vYKrOmFhupMIn/hyB6lYCCTXz4yaQX89XVg=" \ + indir "${EXAMPLES_DIR}" $CARGO test --all $@ + } function test_default() { echo ":: Building and testing core libraries..." + indir "${PROJECT_ROOT}" $CARGO test --all --all-features $@ - pushd "${PROJECT_ROOT}" > /dev/null 2>&1 - $CARGO test --all --all-features $@ - popd > /dev/null 2>&1 + echo ":: Checking benchmarks..." + indir "${BENCHMARKS_ROOT}" $CARGO update + indir "${BENCHMARKS_ROOT}" $CARGO check --benches --all-features $@ + + echo ":: Checking fuzzers..." + indir "${FUZZ_ROOT}" $CARGO update + indir "${FUZZ_ROOT}" $CARGO check --all --all-features $@ } function run_benchmarks() { echo ":: Running benchmarks..." - - pushd "${BENCHMARKS_ROOT}" > /dev/null 2>&1 - $CARGO bench $@ - popd > /dev/null 2>&1 + indir "${BENCHMARKS_ROOT}" $CARGO update + indir "${BENCHMARKS_ROOT}" $CARGO bench $@ } if [[ $1 == +* ]]; then - CARGO="$CARGO $1" - shift + CARGO="$CARGO $1" + shift fi # The kind of test we'll be running. @@ -142,8 +176,8 @@ TEST_KIND="default" KINDS=("contrib" "benchmarks" "core" "examples" "default" "all") if [[ " ${KINDS[@]} " =~ " ${1#"--"} " ]]; then - TEST_KIND=${1#"--"} - shift + TEST_KIND=${1#"--"} + shift fi echo ":: Preparing. Environment is..." @@ -151,8 +185,14 @@ print_environment echo " CARGO: $CARGO" echo " EXTRA FLAGS: $@" -echo ":: Ensuring all crate versions match..." -check_versions_match "${ALL_PROJECT_DIRS[@]}" +echo ":: Ensuring core crate versions match..." +check_versions_match "${CORE_CRATE_ROOTS[@]}" + +echo ":: Ensuring contrib sync_db_pools versions match..." +check_versions_match "${CONTRIB_SYNC_DB_POOLS_CRATE_ROOTS[@]}" + +echo ":: Ensuring contrib db_pools versions match..." +check_versions_match "${CONTRIB_SYNC_DB_POOLS_CRATE_ROOTS[@]}" echo ":: Ensuring minimum style requirements are met..." check_style diff --git a/site/README.md b/site/README.md index 72bf794464..1bd8a6842a 100644 --- a/site/README.md +++ b/site/README.md @@ -13,7 +13,7 @@ This directory contains the following: * `news/*.md` - News articles linked to from `news/index.toml`. * `guide/*.md` - Guide pages linked to from `guide.md`. -[Rocket Programming Guide]: https://rocket.rs/master/guide/ +[Rocket Programming Guide]: https://rocket.rs/v0.5-rc/guide/ ### Guide Links diff --git a/site/guide/01-upgrading.md b/site/guide/01-upgrading.md new file mode 100644 index 0000000000..d94fd087a0 --- /dev/null +++ b/site/guide/01-upgrading.md @@ -0,0 +1,822 @@ +# Upgrading + +Rocket v0.5 bring many new features and improvements over Rocket v0.4. Rocket +v0.5 also includes many changes that improve the overall usability, stability, +and security of the framework and applications written in it. While the Rust +compiler can guide you through many of these changes, others require special +attention. The intent of this guide is to guide you through these changes and +more, migrating your Rocket application to 0.5 and reaping the benefits of new +features and improvements. + +This guide is _not_ intended to replace, but instead complement, a reading of +the [CHANGELOG]. The [CHANGELOG] should be considered required reading for all +developers wishing to migrate their applications to Rocket v0.5. + +[CHANGELOG]: @github/CHANGELOG.md + +! note Don't panic! + + Simply upgrading Rocket's version string to the `0.5` series will result in + _many_ `rustc` compiler errors. But don't let this phase you! The vast + majority of changes are simple renames and `#[async_trait]` attributions which + manifest in a cascading of errors. As such, resolving _one_ top-level issue, + typically requiring minimal, trivial changes, often resolves _many_ errors in + one go. + +## Crate Organization + +Rocket v0.5 incorporates an improved module structure and crate ecosystem. +Modules and items that have been moved or removed will trigger a compiler error. +We encourage users to search through the [CHANGELOG] or [API docs](@api/rocket) +for the v0.5 analog. All previously existing functionality, except for that +incompatible with async I/O, is available in v0.5. + +### Off-by-Default Secrets + +The `private-cookies` crate feature, which was previously enabled by default, +has been renamed to `secrets` and is disabled by default. If you are using +private cookies, you _must_ enable the `secrets` feature in `Cargo.toml`: + +```toml +[dependencies] +rocket = { version = "0.5.0-rc.2", features = ["secrets"] } +``` + +### Contrib Deprecation + +The `rocket_contrib` crate is deprecated and is wholly incompatible with Rocket +0.5. _All_ users of `rocket_contrib` _must_: + + * Remove all dependencies and references to `rocket_contrib`. + * For templating support, depend on the new [`rocket_dyn_templates`] crate. + * For database pools, depend on the new [`rocket_sync_db_pools`] and/or + [`rocket_db_pools`] crates. + * Enable [features in `rocket`] as necessary. + +For example, to make use of JSON and Tera templates, make the following changes +to `Cargo.toml`: + +```diff +[dependencies] +- rocket = "0.4" +- rocket_contrib = { version = "0.4", features = ["json"], default-features = false } ++ rocket = { version = "0.5.0-rc.2", features = ["json"] } ++ rocket_dyn_templates = { version = "0.1.0-rc.2", features = ["tera"] } +``` + +! note: `rocket_dyn_templates` (and co.) _does not_ follow in version lock-step +with the `rocket` crate. + + This is intentional. The crate depends on many external dependencies which may + evolve at a different pace than Rocket itself. Allowing their versions to + diverge enables keeping dependencies up-to-date without breaking `rocket` + itself. + +All features previously in `rocket_contrib` are available. Consult the [contrib +graduation] section of the CHANGELOG for full details. + +[`rocket_dyn_templates`]: @api/rocket_dyn_templates +[`rocket_sync_db_pools`]: @api/rocket_sync_db_pools +[`rocket_db_pools`]: @api/rocket_db_pools +[features in `rocket`]: @api/rocket/#features +[contrib graduation]: @github/CHANGELOG.md#contrib-graduation + +## Stable and Async Support + +Rocket v0.5 compiles and builds on Rust stable with an entirely asynchronous +core. You are encouraged to: + + * Switch to the Rust stable release channel for production builds. + * Remove the previously required `#![feature(..)]` crate attribute. + +All application authors _must_: + + * Use `rocket::build()` instead of `rocket::ignite()`. + * Use either the `#[launch]` or `#[rocket::main]` async entry attribute. + * Use `async` versions of any blocking I/O or execute it in another thread. + +Application authors _may_: + + * Prefer to explicitly import macros via `use` instead of `#[macro_use]`. + +The rest of the section describes making these changes in detail. + +### Stable Release Channel + +If you prefer to use Rust's stable release channel, you can switch to it using +`rustup`: + +```sh +## switch globally +rustup default stable + +## switch locally +rustup override set stable +``` + +Using the stable release channel ensures that _no_ breakages will occur when +upgrading your Rust compiler or Rocket. That being said, Rocket continues to +take advantage of features only present in the nightly channel. As a result, the +development experience will be superior on nightly for the forseeable future. +For example, compiler diagnostics on `nightly` are more detailed and accurate: + +
+Example Diagnostic on Nightly + +```rust,ignore +error: invalid parameters for `has_two` route uri + --> $DIR/typed-uris-bad-params.rs:55:18 + | +55 | uri!(has_two(id = 100, cookies = "hi")); + | ^^^^^^^^^^^^^^^^^^^^^^^^ + | + = note: uri parameters are: id: i32, name: String + = help: missing parameter: `name` +help: unknown parameter: `cookies` + --> $DIR/typed-uris-bad-params.rs:55:28 + | +55 | uri!(has_two(id = 100, cookies = "hi")); + | ^^^^^^^ +``` + +
+ +
+Example Diagnostic on Stable + +```rust,ignore +error: invalid parameters for `has_two` route uri + --- note: uri parameters are: id: i32, name: String + --- help: missing parameter: `name` + --> $DIR/typed-uris-bad-params.rs:55:18 + | +55 | uri!(has_two(id = 100, cookies = "hi")); + | ^^ + +error: [help] unknown parameter: `cookies` + --> $DIR/typed-uris-bad-params.rs:55:28 + | +55 | uri!(has_two(id = 100, cookies = "hi")); + | ^^^^^^^ +``` + +
+ +Our **recommendation** is to develop locally on the nightly channel but build +and deploy for production on the stable channel. + +### Feature Attribute + +As a result support for the stable release channel, Rocket applications no +longer need to enable any features to be used. You should **remove any +`#[feature(..)]` crate attributes:** + +```diff +- #![feature(proc_macro_hygiene, decl_macro)] +- + #[macro_use] extern crate rocket; + + fn main() { .. } +``` + +### Updates to Launch + +The new asynchronous core requires an async runtime to run. The new +[`launch`] and [`main`] attributes simplify starting a runtime suitable for +running Rocket applications. You should use [`launch`] whenever possible. + +Additionally, the `rocket::ignite()` function has been renamed to +[`rocket::build()`]; calls to the function or method should be replaced +accordingly. Together, these two changes result in the following diff to what +was previously the `main` function: + +```diff +- fn main() { +- rocket::ignite().mount("/hello", routes![hello]).launch(); +- } ++ #[launch] ++ fn rocket() -> _ { ++ rocket::build().mount("/hello", routes![hello]) ++ } +``` + +[`launch`]: @api/rocket/attr.launch.html +[`main`]: @api/rocket/attr.main.html +[`rocket::build()`]: @api/rocket/struct.Rocket.html#method.build + +### Blocking I/O + +Rocket v0.5 takes advantage of the latest developments in async I/O in Rust by +migrating to a fully asynchronous core powered by [`tokio`]. Specifically, +_every_ request is handled by an asynchronous task which internally calls one or +more request handlers. Asynchronous tasks are multiplexed on a [configurable +number of worker threads]. Though there is no limit to the number of tasks that +can run concurrently, at most `worker` tasks can run in parallel. + +The runtime can switch between tasks in a single worker thread _iff_ (_if +and only if_) an `await` point in reached. In other words, context +switching is _cooperative_, _not_ preemptive. This _iff_ is critical: if an +`await` point is _not_ reached, no task switching can occur. As such, it is +important that `await` points occur periodically in a task so that tasks waiting +to be scheduled are not starved. + +In general, when working with `async` APIs, await points occur naturally. +However, an application written for synchronous I/O, including all Rocket +applications prior to v0.5, must take great care to convert all synchronous, +blocking I/O, to `async` I/O. This is because, as the name implies, blocking I/O +blocks a thread from making progress until the I/O result is available, meaning +that no tasks can be scheduled on the waiting thread, wasting valuable resources +and significantly degrading performance. + +Common sources of blocking I/O and their `async` replacements include: + + * Anything in `std::fs`: replace with `rocket::tokio::fs`. + * Anything in `std::sync`: replace with `rocket::tokio::sync`. + * Anything in `std::net`: replace with `rocket::tokio::net`. + * Anything in `std::io`: replace with `rocket::tokio::io`. + * Sleep or timers: replace with `rocket::tokio::time`. + * Any networking: replace with `rocket::tokio::net`. + * Any file system access: replace with `rocket::tokio::fs`. + +Unfortunately, the Rust compiler provides no support for identifying blocking +I/O via lints or compile-time checks: it is up to you to scan your application +for sources of blocking I/O and replace them with their `async` counterpart. If +no such counterpart exists, you should execute the relevant I/O in its own +thread by using [`rocket::tokio::task::spawn_blocking`]. + +All of Rocket's I/O APIs have been updated to be `async`-safe. +This results in requiring `.await` calls for common APIs like [`NamedFile`]. To +use `.await` in a route, the handler must be marked with `async`: + +```rust +# use rocket::get; +use rocket::fs::NamedFile; + +#[get("/")] +async fn index() -> Option { + NamedFile::open("index.html").await.ok() +} +``` + +! warning: Non-`async` routes are _also_ executed on the `async` runtime. + + A route that _isn't_ declared as `async` is _still_ executed on the `async` + runtime. As a result, it should not execute blocking I/O. + +
+See a diff of the changes from v0.4. + +```diff +- use rocket::response::NamedFile; ++ use rocket::fs::NamedFile; + +#[get("/")] +- fn index() -> Option { +- NamedFile::open("index.html").ok() ++ async fn index() -> Option { ++ NamedFile::open("index.html").await.ok() +} +``` + +
+ +[`tokio`]: https://tokio.rs +[configurable number of worker threads]: ../configuration/#workers +[`NamedFile`]: @api/rocket/fs/struct.NamedFile.html +[`rocket::tokio::task::spawn_blocking`]: @tokio/task/fn.spawn_blocking.html + +### Blocking Compute + +By the same reasoning, performing large amounts of compute (really, just another +form of I/O) can prevent other tasks from executing in a timely manner. If you +are performing long computations in a handler, you should execute the +computation in its own thread, again using [`rocket::tokio::task::spawn_blocking`]: + +```rust +# use rocket::get; +use rocket::tokio::task; +use rocket::response::Debug; + +#[get("/")] +async fn expensive() -> Result<(), Debug> { + let result = task::spawn_blocking(move || { + // perform the computation + }).await?; + + Ok(result) +} +``` + +### Async Traits + +To support `async` methods in traits, Rocket provides the [`async_trait`] +attribute. The attribute _must_ be applied to all implementations of _async +traits_ like [`FromRequest`] and [`Fairing`]: + +```diff +use rocket::request::{self, Request, FromRequest}; + ++ #[rocket::async_trait] +impl<'r> FromRequest<'r> for MyType { + type Error = MyError; + +- fn from_request(req: &'r Request<'_>) -> request::Outcome { ++ async fn from_request(req: &'r Request<'_>) -> request::Outcome { + /* .. */ + } +} +``` + +All trait documentation has been updated to call out such traits with an example +implementation that includes the invocation. The example implementation also +serves as better documentation for trait and trait method signatures than the +rustdocs. Because `async_trait` modifies these signatures, the rustdocs diverge +from what is written in source. For example, rustdoc renders: + +```rust,ignore +fn from_request<'life0, 'async_trait>( + request: &'r Request<'life0> +) -> Pin> + Send + 'async_trait>>; +``` + +...whereas the source looks like: + +```rust,ignore +async fn from_request(req: &'r Request<'_>) -> Outcome; +``` + +Unfortunately, rustdoc does not provide a mechanism to render the source as it +is written. As such, we encourage all authors to use the examples as the source +of truth for trait and method signatures. + +[`async_trait`]: @api/rocket/attr.async_trait.html +[`FromRequest`]: @api/rocket/request/trait.FromRequest.html +[`Fairing`]: @api/rocket/fairing/trait.Fairing.html + +## Configuration + +Rocket's configuration system has been entirely revamped for v0.5. The +[configuration](../configuration) section of the guide contains a full +walkthrough of the new system while the [general changes] section of the +CHANGELOG contains further details on configuration changes. We call out the +most important of these changes here. All users _must_: + + * Replace `ROCKET_ENV` environment variable use with `ROCKET_PROFILE`. + * Replace `ROCKET_LOG` environment variable with `ROCKET_LOG_LEVEL`. + * Use only IP addreses for the `address` configuration parameter. + * Replace the `dev` or `development` profile with `debug`. + * Note that the `stage`, `staging`, `prod`, and `production` profiles carry no + special meaning in v0.5. + * Use `0` to disable `keep_alive` instead of `false` or `off`. + * Replace uses of "extras" with [typed extraction]. + +Rocket will emit warnings at launch time if use of the previous functionality is +detected. + +### Profiles + +The new system deals with "profiles" where there were previously "environments". +As opposed to environments, profiles: + + * Can be arbitrarily named and any number can exist. + * Match Rust profiles in naming: `debug` and `release` are the default + profiles for the respective Rust compilation profile. + * Are programmatically selectable and configurable. + * Have a `default` profile with fallback values for all profiles. + * Have a `global` profile with overrides for all profiles. + +Authors should read the new [configuration](../configuration) section of the +guide to determine the scope of changes required. This likely includes: + + * Defining most configuration in the `default` profile instead. + * Using the `debug` profile where `dev` or `development` was used. + * Using the `release` profile where `prod` or `production` was used. + +[general changes]: @github/CHANGELOG.md#general +[typed extraction]: ../configuration/#extracting-values + +### Typed Extraction + +The "extras" configuration in v0.4 is entirely replaced by [typed extraction], +which allows any `Deserialize` structure to be derived from configuration +sources. All users _should_ make use of typed extraction where "extras" were +being used previously. The diff below illustrates one such example: + +```diff +use rocket::fairing::AdHoc; + ++ #[derive(Deserialize)] +struct AppConfig { + id: Option, + port: u16, +} + +- fn main() { +- rocket::ignite() +- .attach(AdHoc::on_attach("Token Config", |rocket| { +- println!("Adding token managed state from config..."); +- let id = match rocket.config().get_int("id") { +- Ok(v) if v >= 0 => Some(v as usize), +- _ => None, +- }; +- +- let port = match rocket.config().get_int("port") { +- Ok(v) if v => 0 && v < 1 << 16 => v as u16, +- _ => return Err(rocket) +- }; +- +- Ok(rocket.manage(AppConfig { id, port })) +- })) +- } + ++ #[launch] ++ fn rocket() -> _ { ++ rocket::build().attach(AdHoc::config::()) ++ } +``` + +## Routing + +Rocket v0.5 brings several major changes that affect routing: + + 1. [Default ranking] is more precise, so fewer routes need manual ranking. + 2. Multi-segment route parameters (``) now match _zero_ or more + segments. + 3. Parameters are _always_ percent-decoded, so `&RawStr` no longer implements + `FromParam`. + 4. Query parameters parse with [`FromForm`] instead of `FromQuery` and support + arbitrarily collections, nesting, structures, etc. + 5. All UTF-8 characters are allowed in static path components: `#[get("/❤️")]`. + 6. The [`register()`] method require a path to [scope catchers] under. Using + `"/"` emulates the previous behavior. + +[Default ranking]: ../requests#default-ranking +[`FromForm`]: @api/rocket/form/trait.FromForm.html +[`FromParam`]: @api/rocket/request/trait.FromParam.html +[`register()`]: @api/rocket/struct.Rocket.html#method.register +[scope catchers]: ../requests/#scoping + +### Default Ranks + +Default route ranking now takes into account partially dynamic paths, increasing +the range of default ranks from `[-6, -1]` to `[-12, -1]`. The net effect is +that fewer routes collide by default, requiring less manual ranking. For +example, the following two routes collide in v0.4 but not in v0.5: + +```rust +# use rocket::get; + +#[get("/foo/<_>/bar")] +fn foo_bar() { } + +#[get("/<_..>")] +fn everything() { } +``` + +
+See a diff of the changes from v0.4. + +```diff +- #[get("/foo/<_>/bar", rank = 1)] ++ #[get("/foo/<_>/bar")] + fn foo_bar() { } + +- #[get("/<_..>", rank = 2)] ++ #[get("/<_..>")] + fn everything() { } +``` +
+ +**The recommendation** is to remove all unnecessary manual ranking parameters. +For smaller applications, you may find that _all_ manual ranks can be removed. +Larger applications may still require ranks to resolve ambiguities. + +### Kleene Multi-Segments + +The multi-segment route parameter `` now matches _zero or more_ segments, +a change from the previous _one_ or more segments. The implication is two-fold: + + 1. Where previously two routes were required to match a prefix and its + suffixes, now one suffices: + + ```diff + - #[get("/")] + - fn index(); + + - #[get("/")] + - fn rest(path: PathBuf); + + + #[get("/")] + + fn all(path: PathBuf); + ``` + + 2. A prefix collides with a route that matches all of its suffixes. For + example, `index` and `rest` above collide. + +Most applications will likely benefit from this change by allowing the extra +prefix-only route to be removed entirely. If the previous functionality of +requiring at least one segment is desired, a route that explicitly matches the +first segment can be used: + +```rust +# use std::path::PathBuf; +# use rocket::get; + +#[get("//")] +fn rest(first: PathBuf, rest: PathBuf) { /* .. */ } +``` + +### Fewer Raw Strings + +Rocket v0.5 makes a concerted effort to limit the exposure to strings from the +raw HTTP payload. In line with this philosophy, Rocket now percent-decodes all +incoming parameters automatically as opposed to doing so on-demand. The +corollary is three-fold: + + 1. The `&RawStr` type no longer implements [`FromParam`]. + 2. The `&str` type now implements [`FromParam`] and is fully decoded. + 3. The `String` parameter type is identical to the `&str` type and should be + avoided. + +Most applications can simply swap uses of `&RawStr` and `String` for `&str` in +routes, forms, and so on to benefit from the increase web-safety and +performance. For instance, the front-page example becomes: + +```diff + #[get("//")] +- fn hello(name: String, age: u8) -> String { ++ fn hello(name: &str, age: u8) -> String { + format!("Hello, {} year old named {}!", age, name) +} +``` + +A form that previously used `String` becomes: + +```diff +#[derive(FromForm)] +- struct MyForm { ++ struct MyForm<'r> { +- value: String, ++ value: &'r str, +} +``` + +### Queries as Forms + +Query strings in Rocket v0.5 are in parity with forms and support their [full +breadth](../requests#forms). Single segment query parameters (``) should +require little to no changes, except that they now support collections, +structures, and any other `FromForm` type. This implies that the majority, if +not _all_ custom `FromQuery` implementations, should be derivable via `FromForm` +or have a built-in equivalent like `Vec`: + +```rust +# use rocket::post; + +#[post("/?")] +fn form(numbers: Vec) { /* .. */ } +``` + +Multi-segment query parameters (``) no longer require the use of a +`Form` guard. Instead, `T` can be used directly: + +```diff +#[derive(FromForm)] +struct Person { /* .. */ } + +#[get("/hello?")] +- fn hello(person: Option>) ++ fn hello(person: Option) +``` + +## Forms + +Rocket v0.5 introduces entirely revamped [forms] with support for: + + * [Multipart uploads.](../requests#multipart) + * [Collections: maps, vectors, and more.](../requests#collections) + * [Nesting.](../requests#nesting) + * [Ad-Hoc validation.](../requests#ad-hoc-validation) + +Additionally, the [`FromForm` derive] has been substantially improved so that +nearly all custom implementations of `FromForm` or [`FromFormField`], which +replaces `FromFormValue` from v0.4, can be derived. Altogether, this means that +any external crate dependency for form handling and most custom `FromForm` or +`FromFormValue` implementations are unnecessary and should be removed. + +[`FromFormField`]: @api/rocket/form/trait.FromFormField.html + +### Multipart + +If your application used an external crate to accept multipart form submissions, +the dependency should be removed: Rocket v0.5 natively handles multipart. A file +upload can be accepted via the [`TempFile`] form guard: + +```rust +# #[macro_use] extern crate rocket; + +use rocket::form::Form; +use rocket::fs::TempFile; + +#[derive(FromForm)] +struct Upload<'r> { + save: bool, + file: TempFile<'r>, +} + +#[post("/upload", data = "")] +fn upload(upload: Form>) { /* .. */ } +``` + +[`TempFile`]: @api/rocket/fs/enum.TempFile.html + +### Field Validation + +In Rocket v0.4, it was encouraged and often required to implement +`FromFormValue` to introduce typed field validation. In v0.5, this can be +accomplished by [deriving `FromForm`]: + +```diff +- use rocket::request::FromFormValue; +- use rocket::http::RawStr; +- +- struct AdultAge(usize); +- +- impl<'v> FromFormValue<'v> for AdultAge { +- type Error = &'v RawStr; +- +- fn from_form_value(form_value: &'v RawStr) -> Result { +- match form_value.parse::() { +- Ok(age) if age >= 21 => Ok(AdultAge(age)), +- _ => Err(form_value), +- } +- } +- } + ++ #[derive(FromForm)] ++ #[field(validate = range(21..))] ++ struct AdultAge(usize); +``` + +If a given validation is used once, a new type may offer no additional safety. +The validation can be performed directly on a field: + +```rust +use rocket::form::FromForm; + +#[derive(FromForm)] +struct MyForm { + #[field(validate = range(21..))] + age: usize, +} +``` + +[forms]: ../requests#forms +[`FromForm` derive]: @api/rocket/derive.FromForm.html +[deriving `FromForm`]: @api/rocket/derive.FromForm.html + +## Notable New Features + +Rocket v0.5 brings an abundance of new features that enable new functionality, +increase productivity, and make existing applications more robust. We encourage +all users to take advantage of these new features. + +### Sentinels + +Rocket v0.5 introduces [sentinels]. Entirely unique to Rocket, sentinels offer +an automatic last line of defense against runtime errors by enabling any type +that appears in a route to abort application launch if invalid conditions are +detected. For example, the [`&State`] guard in v0.5 is a [`Sentinel`] that +aborts launch if the type `T` is not in managed state, thus preventing +associated runtime errors. + +You should consider implementing `Sentinel` for your types if you have guards +(request, data, form, etc.) or responders that depend on `Rocket` state to +function properly. For example, consider a `MyResponder` that expects: + + * An error catcher to be registered for the `400` status code. + * A specific type `T` to be in managed state. + +Making `MyResponder` a sentinel that guards against these conditions is as +simple as: + +```rust +use rocket::{Rocket, Ignite, Sentinel}; +# struct MyResponder; +# struct T; + +impl Sentinel for MyResponder { + fn abort(r: &Rocket) -> bool { + !r.catchers().any(|c| c.code == Some(400)) || r.state::().is_none() + } +} +``` + +[sentinels]: @api/rocket/trait.Sentinel.html +[`Sentinel`]: @api/rocket/trait.Sentinel.html +[`&State`]: @api/rocket/struct.State.html + +### More Typed URIs + +Rocket v0.5 brings a completely overhauled [`uri!()`] macro and support for +typed URIs in more APIs. Notably, the `uri!()` macro now: + + * Allows URIs to be constructed from static values: + + ```rust + # use rocket::uri; + use rocket::http::uri::Absolute; + + const HOST: Absolute<'static> = uri!("http://localhost:8000"); + ``` + + * Allows static and dynamic [prefixes and suffixes] to route URIs to be + specified: + + ```rust + # use rocket::{uri, get}; + + #[get("/person/?")] + fn person(name: &str, age: Option) { } + + let uri = uri!("https://rocket.rs/", person("Bob", Some(28)), "#woo"); + assert_eq!(uri.to_string(), "https://rocket.rs/person/Bob?age=28#woo"); + + let host = uri!("http://bob.me"); + let uri = uri!(host, person("Bob", Some(28))); + assert_eq!(uri.to_string(), "http://bob.me/person/Bob?age=28"); + ``` + +APIs like [`Redirect`] and [`Client`] now accept typed URIs: + +```rust +# #[macro_use] extern crate rocket; + +use rocket::response::Redirect; + +#[get("/bye//")] +fn bye(name: &str, age: u8) -> Redirect { + Redirect::to(uri!("https://rocket.rs", bye(name, age), "?bye#now")) +} + +#[test] +fn test() { + use rocket::local::blocking::Client; + + let client = Client::new(rocket::build()); + let r = client.get(uri!(super::bye("Bob", 30))).dispatch(); +} +``` + +[URI types] have been overhauled accordingly. A new [`Reference`] type encodes +URI-references. Additionally, all URI types are now `Serialize` and +`Deserialize`, allowing URIs to be used in configuration and passed over the +wire. + +[`Redirect`]: @api/rocket/response/struct.Redirect.html +[`Client`]: @api/rocket/local/index.html +[prefixes and suffixes]: @api/rocket/macro.uri.html#prefixes-and-suffixes +[`uri!()`]: @api/rocket/macro.uri.html +[URI types]: @api/rocket/http/uri/index.html +[`Reference`]: @api/rocket/http/uri/struct.Reference.html + +### Real-Time Streams + +Rocket v0.5 introduces real-time, typed, `async` [streams]. The new [async +streams] section of the guide contains further details, and we encourage all +interested parties to see the new real-time, multi-room [chat example]. + +As a taste of what's possible, the following `stream` route emits a `"ping"` +Server-Sent Event every `n` seconds, defaulting to `1`: + +```rust +# use rocket::*; +use rocket::response::stream::{Event, EventStream};; +use rocket::tokio::time::{interval, Duration}; + +#[get("/ping?")] +fn stream(n: Option) -> EventStream![] { + EventStream! { + let mut timer = interval(Duration::from_secs(n.unwrap_or(1))); + loop { + yield Event::data("ping"); + timer.tick().await; + } + } +} +``` + +[streams]: @api/rocket/response/stream/index.html +[async streams]: ../responses/#async-streams +[chat example]: @example/chat + +## Getting Help + +If you run into any issues upgrading, we encourage you to ask questions via +[GitHub discussions] or via chat at [`#rocket:mozilla.org`] on Matrix or the +bridged [`#rocket`] IRC channel at `irc.libera.chat`. The [FAQ](../faq/) also +provides answers to commonly asked questions. + +[GitHub discussions]: https://github.com/SergioBenitez/Rocket/discussions +[`#rocket:mozilla.org`]: https://chat.mozilla.org/#/room/#rocket:mozilla.org +[`#rocket`]: https://kiwiirc.com/client/irc.libera.chat/#rocket diff --git a/site/guide/1-quickstart.md b/site/guide/1-quickstart.md index c9254a6def..5d43c1003b 100644 --- a/site/guide/1-quickstart.md +++ b/site/guide/1-quickstart.md @@ -14,7 +14,7 @@ For instance, the following set of commands runs the `hello` example: ```sh git clone https://github.com/SergioBenitez/Rocket cd Rocket -git checkout master +git checkout v0.5-rc cd examples/hello cargo run ``` diff --git a/site/guide/10-pastebin-tutorial.md b/site/guide/10-pastebin-tutorial.md new file mode 100644 index 0000000000..fbbc6dfb1c --- /dev/null +++ b/site/guide/10-pastebin-tutorial.md @@ -0,0 +1,545 @@ +# Pastebin Tutorial + +This section of the guide is a tutorial intended to demonstrate how real-world +Rocket applications are crafted. We'll build a simple pastebin service that +allows users to upload a file from any HTTP client, including `curl`. The +service will respond back with a URL to the uploaded file. + +! note: What's a pastebin? + + A pastebin is a simple web application that allows users to upload a document + and later retrieve it via a special URL. They're often used to share code + snippets, configuration files, and error logs. + +## Finished Product + +A souped-up, completed version of the application you're about to build is +deployed live at [paste.rs](https://paste.rs). Feel free to play with the +application to get a feel for how it works. For example, to upload a text +document named `test.txt`, you can run: + +```sh +curl --data-binary @test.txt https://paste.rs/ +# => https://paste.rs/IYu +``` + +The finished product is composed of the following routes: + + * `index` - `#[get("/")]` + + returns a simple HTML page with instructions about how to use the service + + * `upload` - `#[post("/")]` + + accepts raw data in the body of the request and responds with a URL of a + page containing the body's content + + * `retrieve` - `#[get("/")]` + + retrieves the content for the paste with id `` + +## Getting Started + +Let's get started! First, create a fresh Cargo binary project named +`rocket-pastebin`: + +```sh +cargo new --bin rocket-pastebin +cd rocket-pastebin +``` + +Then add the usual Rocket dependencies to the `Cargo.toml` file: + +```toml +[dependencies] +rocket = "0.5.0-rc.2" +``` + +And finally, create a skeleton Rocket application to work off of in +`src/main.rs`: + +```rust +#[macro_use] extern crate rocket; + +#[launch] +fn rocket() -> _ { + rocket::build() +} +``` + +Ensure everything works by running the application: + +```sh +cargo run +``` + +At this point, we haven't declared any routes or handlers, so visiting any page +will result in Rocket returning a **404** error. Throughout the rest of the +tutorial, we'll create the three routes and accompanying handlers. + +## Index + +The first route we'll create is `index`. This is the page users will see when +they first visit the service. As such, the route should handle `GET /`. We +declare the route and its handler by adding the `index` function below to +`src/main.rs`: + +```rust +# #[macro_use] extern crate rocket; + +#[get("/")] +fn index() -> &'static str { + " + USAGE + + POST / + + accepts raw data in the body of the request and responds with a URL of + a page containing the body's content + + GET / + + retrieves the content for the paste with id `` + " +} +``` + +This declares the `index` route for requests to `GET /` as returning a static +string with the specified contents. Rocket will take the string and return it as +the body of a fully formed HTTP response with `Content-Type: text/plain`. You +can read more about how Rocket formulates responses in the [responses section] +of the guide or at the [API documentation for the Responder +trait](@api/rocket/response/trait.Responder.html). + +[responses section]: ../responses + +Remember that routes first need to be mounted before Rocket dispatches requests +to them. To mount the `index` route, modify the main function so that it reads: + +```rust +# #[macro_use] extern crate rocket; +# #[get("/")] fn index() { } + +#[launch] +fn rocket() -> _ { + rocket::build().mount("/", routes![index]) +} +``` + +You should now be able to `cargo run` the application and visit the root path +(`/`) to see the text. + +## Design + +Before we continue, we'll need to make a few design decisions. + + * **Where should pastes be stored?** + + To keep things simple, we'll store uploaded pastes on the file system inside + of an `upload/` directory. Let's create that directory next to `src/` in our + project now: + + ```sh + mkdir upload + ``` + + Our project tree now looks like: + + ```sh + . + ├── Cargo.toml + ├── src + │   └── main.rs + └── upload + ``` + + * **What should we name the uploaded paste files?** + + Similarly, we'll keep things simple by naming paste files a string of random + but readable characters. We'll call this random string the paste's "ID". To + represent, generate, and store the ID, we'll create a `PasteId` structure in + a new module file named `paste_id.rs` with the following contents: + + ```rust + use std::borrow::Cow; + use std::path::{Path, PathBuf}; + + use rand::{self, Rng}; + + /// A _probably_ unique paste ID. + pub struct PasteId<'a>(Cow<'a, str>); + + impl PasteId<'_> { + /// Generate a _probably_ unique ID with `size` characters. For readability, + /// the characters used are from the sets [0-9], [A-Z], [a-z]. The + /// probability of a collision depends on the value of `size` and the number + /// of IDs generated thus far. + pub fn new(size: usize) -> PasteId<'static> { + const BASE62: &[u8] = b"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"; + + let mut id = String::with_capacity(size); + let mut rng = rand::thread_rng(); + for _ in 0..size { + id.push(BASE62[rng.gen::() % 62] as char); + } + + PasteId(Cow::Owned(id)) + } + + /// Returns the path to the paste in `upload/` corresponding to this ID. + pub fn file_path(&self) -> PathBuf { + let root = concat!(env!("CARGO_MANIFEST_DIR"), "/", "upload"); + Path::new(root).join(self.0.as_ref()) + } + } + ``` + + We've given you the ID and path generation code for free. Our project tree + now looks like: + + ```sh + . + ├── Cargo.toml + ├── src + │   ├── main.rs + │   └── paste_id.rs # new! contains `PasteId` + └── upload + ``` + + We'll import the new module and struct in `src/main.rs`, after the `extern + crate rocket`: + + ```rust + # /* + mod paste_id; + # */ mod paste_id { pub struct PasteId; } + + use paste_id::PasteId; + ``` + + You'll notice that our code to generate paste IDs uses the `rand` crate, so + we'll need to add it as a dependency in our `Cargo.toml` file: + + ```toml + [dependencies] + ## existing Rocket dependencies... + rand = "0.8" + ``` + + Ensure that your application builds with the new code: + + ```sh + cargo build + ``` + + You'll likely see many "unused" warnings for the new code we've added: that's + okay and expected. We'll be using the new code soon. + +With these design decisions made, we're ready to continue writing our +application. + +## Retrieving Pastes + +We'll proceed with a `retrieve` route which, given an ``, will return the +corresponding paste if it exists or otherwise **404**. As we now know, that +means we'll be reading the contents of the file corresponding to `` in the +`upload/` directory and return them to the user. + +Here's a first take at implementing the `retrieve` route. The route below takes +in an `` as a dynamic path element. The handler uses the `id` to construct a +path to the paste inside `upload/`, and then attempts to open the file at that +path, optionally returning the `File` if it exists. Rocket treats a `None` +[Responder](@api/rocket/response/trait.Responder.html#provided-implementations) +as a **404** error, which is exactly what we want to return when the requested +paste doesn't exist. + +```rust +# #[macro_use] extern crate rocket; + +use std::path::Path; +use rocket::tokio::fs::File; + +#[get("/")] +async fn retrieve(id: &str) -> Option { + let upload_dir = concat!(env!("CARGO_MANIFEST_DIR"), "/", "upload"); + let filename = Path::new(upload_dir).join(id); + File::open(&filename).await.ok() +} +``` + +Make sure that the route is mounted at the root path: + +```rust +# #[macro_use] extern crate rocket; + +# #[get("/")] fn index() {} +# #[get("/")] fn retrieve(id: String) {} + +#[launch] +fn rocket() -> _ { + rocket::build().mount("/", routes![index, retrieve]) +} +``` + +Give it a try! Create some fake pastes in the `upload/` directory, run the +application, and try to retrieve them by visiting the corresponding URL. + +### A Problem + +Unfortunately, there's a problem with this code. Can you spot the issue? The +`&str` type in `retrieve` should tip you off! We've crafted a wonderful type to +represent paste IDs but have ignored it! + +The issue is that the _user_ controls the value of `id`, and as a result, can +coerce the service into opening files inside `upload/` that aren't meant to be +opened. For instance, imagine that you later decide that a special file +`upload/_credentials.txt` will store some important, private information. If the +user issues a `GET` request to `/_credentials.txt`, the server will read and +return the `upload/_credentials.txt` file, leaking the sensitive information. +This is a big problem; it's known as the [full path disclosure +attack](https://www.owasp.org/index.php/Full_Path_Disclosure), and Rocket +provides the tools to prevent this and other kinds of attacks from happening. + +### The Solution + +To prevent the attack, we need to _validate_ `id` before we use it. We do so by +using a type more specific than `&str` to represent IDs and then asking Rocket +to validate the untrusted `id` input as that type. If validation fails, Rocket +will take care to not call our routes with bad input. + +Typed validation for dynamic paramters like `id` is implemented via the +[`FromParam`] trait. Rocket uses `FromParam` to automatically validate and parse +dynamic path parameters like `id`. We already have a type that represents valid +paste IDs, `PasteId`, so we'll simply need to implement `FromParam` for +`PasteId`. + +Here's the `FromParam` implementation for `PasteId` in `src/paste_id.rs`: + +[`FromParam`]: @api/rocket/request/trait.FromParam.html + +```rust +use rocket::request::FromParam; +# use std::borrow::Cow; +# pub struct PasteId<'a>(Cow<'a, str>); + +/// Returns an instance of `PasteId` if the path segment is a valid ID. +/// Otherwise returns the invalid ID as the `Err` value. +impl<'a> FromParam<'a> for PasteId<'a> { + type Error = &'a str; + + fn from_param(param: &'a str) -> Result { + param.chars().all(|c| c.is_ascii_alphanumeric()) + .then(|| PasteId(param.into())) + .ok_or(param) + } +} +``` + +! note: This implementation, while secure, could be improved. + + Our `from_param` function is simplistic and could be improved by, for example, + checking that the length of the `id` is within some known bound, introducing + stricter character checks, checking for the existing of a paste file, and/or + potentially blacklisting sensitive files as needed. + +Given this implementation, we can change the type of `id` in `retrieve` to +`PasteId`. Rocket will then ensure that `` represents a valid `PasteId` +before calling the `retrieve` route, preventing the previous attack entirely: + +```rust +# #[macro_use] extern crate rocket; + +use rocket::tokio::fs::File; +# use std::borrow::Cow; +# use std::path::PathBuf; +# use rocket::request::FromParam; +# pub struct PasteId<'a>(Cow<'a, str>); +# impl PasteId<'_> { +# pub fn new(size: usize) -> PasteId<'static> { todo!() } +# pub fn file_path(&self) -> PathBuf { todo!() } +# } +# impl<'a> FromParam<'a> for PasteId<'a> { +# type Error = &'a str; +# fn from_param(param: &'a str) -> Result { todo!() } +# } + +#[get("/")] +async fn retrieve(id: PasteId<'_>) -> Option { + File::open(id.file_path()).await.ok() +} +``` + +Notice how much nicer this implementation is! And this time, it's secure. + +The wonderful thing about using `FromParam` and other Rocket traits is that they +centralize policies. For instance, here, we've centralized the policy for valid +`PasteId`s in dynamic parameters. At any point in the future, if other routes +are added that require a `PasteId`, no further work has to be done: simply use +the type in the signature and Rocket takes care of the rest. + + +## Uploading + +Now that we can retrieve pastes safely, it's time to actually store them. We'll +write an `upload` route that, according to our design, takes a paste's contents +and writes them to a file with a randomly generated ID inside of the `upload/` +directory. It'll return a URL to the client for the paste corresponding to the +`retrieve` route we just route. + +### Streaming Data + +To stream the incoming paste data to a file, we'll make use of [`Data`], a [data +guard] that represents an unopened stream to the incoming request body data. +Before we show you the code, you should attempt to write the route yourself. +Here's a hint: one possible route and handler signature look like this: + +```rust +# #[macro_use] extern crate rocket; +use rocket::Data; + +#[post("/", data = "")] +async fn upload(paste: Data<'_>) -> std::io::Result { + /* .. */ + # Ok("".into()) +} +``` + +[`Data`]: @api/rocket/data/struct.Data.html +[data guard]: ../requests/#body-data + +Your code should: + + 1. Create a new `PasteId` of a length of your choosing. + 2. Construct a path to the `PasteId` inside of `upload/`. + 3. Stream the `Data` to the file at the constructed path. + 4. Construct a URL for the `PasteId`. + 5. Return the URL to the client. + +### Solution + +Here's our version: + +```rust +# #[macro_use] extern crate rocket; + +// We derive `UriDisplayPath` for `PasteId` in `paste_id.rs`: +# use std::borrow::Cow; +# use std::path::{Path, PathBuf}; +# use rocket::request::FromParam; + +#[derive(UriDisplayPath)] +pub struct PasteId<'a>(Cow<'a, str>); + +# impl PasteId<'_> { +# pub fn new(size: usize) -> PasteId<'static> { todo!() } +# pub fn file_path(&self) -> PathBuf { todo!() } +# } +# +# impl<'a> FromParam<'a> for PasteId<'a> { +# type Error = &'a str; +# fn from_param(param: &'a str) -> Result { todo!() } +# } +// We implement the `upload` route in `main.rs`: + +use rocket::data::{Data, ToByteUnit}; +use rocket::http::uri::Absolute; +# use rocket::tokio::fs::File; + +// In a real application, these would be retrieved dynamically from a config. +const ID_LENGTH: usize = 3; +const HOST: Absolute<'static> = uri!("http://localhost:8000"); +# #[get("/")] fn index() -> &'static str { "" } +# #[get("/")] fn retrieve(id: PasteId<'_>) -> Option { todo!() } + +#[post("/", data = "")] +async fn upload(paste: Data<'_>) -> std::io::Result { + let id = PasteId::new(ID_LENGTH); + paste.open(128.kibibytes()).into_file(id.file_path()).await?; + Ok(uri!(HOST, retrieve(id)).to_string()) +} +``` + +We note the following Rocket APIs being used in our implementation: + + * The [`kibibytes()`] method, which comes from the [`ToByteUnit`] trait. + * [`Data::open()`] to open [`Data`] as a [`DataStream`]. + * [`DataStream::into_file()`] for writing the data stream into a file. + * The [`UriDisplayPath`] derive, allowing `PasteId` to be used in [`uri!`]. + * The [`uri!`] macro to crate type-safe, URL-safe URIs. + +[`Data::open()`]: @api/rocket/data/struct.Data.html#method.open +[`Data`]: @api/rocket/data/struct.Data.html +[`DataStream`]: @api/rocket/data/struct.DataStream.html +[`DataStream::into_file()`]: @api/rocket/data/struct.DataStream.html#method.into_file +[`uri!`]: @api/rocket/macro.uri.html +[`kibibytes()`]: @api/rocket/data/trait.ToByteUnit.html#tymethod.kibibytes +[`ToByteUnit`]: @api/rocket/data/trait.ToByteUnit.html +[`UriDisplayPath`]: @api/rocket/derive.UriDisplayPath.html + +Ensure that the route is mounted at the root path: + +```rust +# #[macro_use] extern crate rocket; + +# #[get("/")] fn index() {} +# #[get("/")] fn retrieve(id: &str) {} +# #[post("/")] fn upload() {} + +#[launch] +fn rocket() -> _ { + rocket::build().mount("/", routes![index, retrieve, upload]) +} +``` + +Test that your route works via `cargo run`. From a separate terminal, upload a +file using `curl` then retrieve the paste using the returned URL. + +```sh +## in the project root +cargo run + +## in a separate terminal +echo "Hello, Rocket!" | curl --data-binary @- http://localhost:8000 +## => http://localhost:8000/eGs + +## confirm we can retrieve the paste (replace with URL from above) +curl http://localhost:8000/eGs + +## we can check the contents of `upload/` as well + # kill running process +ls upload # ensure the upload is there +cat upload/* # ensure that contents are correct +``` + +## Conclusion + +That's it! Ensure that all of your routes are mounted and test your application. +You've now written a simple (~75 line!) pastebin in Rocket! There are many +potential improvements to this small application, and we encourage you to work +through some of them to get a better feel for Rocket. Here are some ideas: + + * Add a web form to the `index` where users can manually input new pastes. + Accept the form at `POST /`. Use `format` and/or `rank` to specify which of + the two `POST /` routes should be called. + * Support **deletion** of pastes by adding a new `DELETE /` route. Use + `PasteId` to validate ``. + * Indicate **partial uploads** with a **206** partial status code. If the user + uploads a paste that meets or exceeds the allowed limit, return a **206** + partial status code. Otherwise, return a **201** created status code. + * Set the `Content-Type` of the return value in `upload` and `retrieve` to + `text/plain`. + * **Return a unique "key"** after each upload and require that the key is + present and matches when doing deletion. Use one of Rocket's core traits to + do the key validation. + * Add a `PUT /` route that allows a user with the key for `` to + replace the existing paste, if any. + * Add a new route, `GET //` that syntax highlights the paste with ID + `` for language ``. If `` is not a known language, do no + highlighting. Possibly validate `` with `FromParam`. + * Use the [`local` module](@api/rocket/local/) to write unit tests for your + pastebin. + * Dispatch a thread before `launch`ing Rocket in `main` that periodically + cleans up idling old pastes in `upload/`. + +You can find the full source code for the [completed pastebin tutorial on +GitHub](@example/pastebin). diff --git a/site/guide/10-pastebin.md b/site/guide/10-pastebin.md deleted file mode 100644 index a3004943f9..0000000000 --- a/site/guide/10-pastebin.md +++ /dev/null @@ -1,450 +0,0 @@ -# Pastebin - -To give you a taste of what a real Rocket application looks like, this section -of the guide is a tutorial on how to create a Pastebin application in Rocket. A -pastebin is a simple web application that allows users to upload a text document -and later retrieve it via a special URL. They're often used to share code -snippets, configuration files, and error logs. In this tutorial, we'll build a -simple pastebin service that allows users to upload a file from their terminal. -The service will respond back with a URL to the uploaded file. - -## Finished Product - -A souped-up, completed version of the application you're about to build is -deployed live at [paste.rs](https://paste.rs). Feel free to play with the -application to get a feel for how it works. For example, to upload a text -document named `test.txt`, you can do: - -```sh -curl --data-binary @test.txt https://paste.rs/ -# => https://paste.rs/IYu -``` - -The finished product is composed of the following routes: - - * index: **`GET /`** - returns a simple HTML page with instructions about how - to use the service - * upload: **`POST /`** - accepts raw data in the body of the request and - responds with a URL of a page containing the body's content - * retrieve: **`GET /`** - retrieves the content for the paste with id - `` - -## Getting Started - -Let's get started! First, create a fresh Cargo binary project named -`rocket-pastebin`: - -```sh -cargo new --bin rocket-pastebin -cd rocket-pastebin -``` - -Then add the usual Rocket dependencies to the `Cargo.toml` file: - -```toml -[dependencies] -rocket = "0.5.0-dev" -``` - -And finally, create a skeleton Rocket application to work off of in -`src/main.rs`: - -```rust -#[macro_use] extern crate rocket; - -#[launch] -fn rocket() -> _ { - rocket::build() -} -``` - -Ensure everything works by running the application: - -```sh -cargo run -``` - -At this point, we haven't declared any routes or handlers, so visiting any page -will result in Rocket returning a **404** error. Throughout the rest of the -tutorial, we'll create the three routes and accompanying handlers. - -## Index - -The first route we'll create is the `index` route. This is the page users will -see when they first visit the service. As such, the route should field requests -of the form `GET /`. We declare the route and its handler by adding the `index` -function below to `src/main.rs`: - -```rust -# #[macro_use] extern crate rocket; - -#[get("/")] -fn index() -> &'static str { - " - USAGE - - POST / - - accepts raw data in the body of the request and responds with a URL of - a page containing the body's content - - GET / - - retrieves the content for the paste with id `` - " -} -``` - -This declares the `index` route for requests to `GET /` as returning a static -string with the specified contents. Rocket will take the string and return it as -the body of a fully formed HTTP response with `Content-Type: text/plain`. You -can read more about how Rocket formulates responses at the [API documentation -for the Responder - trait](@api/rocket/response/trait.Responder.html). - -Remember that routes first need to be mounted before Rocket dispatches requests -to them. To mount the `index` route, modify the main function so that it reads: - -```rust -# #[macro_use] extern crate rocket; -# #[get("/")] fn index() { } - -#[launch] -fn rocket() -> _ { - rocket::build().mount("/", routes![index]) -} -``` - -You should now be able to `cargo run` the application and visit the root path -(`/`) to see the text being displayed. - -## Uploading - -The most complicated aspect of the pastebin, as you might imagine, is handling -upload requests. When a user attempts to upload a pastebin, our service needs to -generate a unique ID for the upload, read the data, write it out to a file or -database, and then return a URL with the ID. We'll take each of these one step -at a time, beginning with generating IDs. - -### Unique IDs - -Generating a unique and useful ID is an interesting topic, but it is outside the -scope of this tutorial. Instead, we simply provide the code for a `PasteId` -structure that represents a _probably_ unique ID. Read through the code, then -copy/paste it into a new file named `paste_id.rs` in the `src/` directory: - -```rust -use std::fmt; -use std::borrow::Cow; - -use rand::{self, Rng}; - -/// Table to retrieve base62 values from. -const BASE62: &[u8] = b"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"; - -/// A _probably_ unique paste ID. -pub struct PasteId<'a>(Cow<'a, str>); - -impl<'a> PasteId<'a> { - /// Generate a _probably_ unique ID with `size` characters. For readability, - /// the characters used are from the sets [0-9], [A-Z], [a-z]. The - /// probability of a collision depends on the value of `size` and the number - /// of IDs generated thus far. - pub fn new(size: usize) -> PasteId<'static> { - let mut id = String::with_capacity(size); - let mut rng = rand::thread_rng(); - for _ in 0..size { - id.push(BASE62[rng.gen::() % 62] as char); - } - - PasteId(Cow::Owned(id)) - } -} -``` - -Then, in `src/main.rs`, add the following after `extern crate rocket`: - -```rust -# /* -mod paste_id; -# */ mod paste_id { pub struct PasteId; } - -use paste_id::PasteId; -``` - -Finally, add a dependency for the `rand` crate to the `Cargo.toml` file: - -```toml -[dependencies] -# existing Rocket dependencies... -rand = "0.8" -``` - -Then, ensure that your application builds with the new code: - -```sh -cargo build -``` - -You'll likely see many "unused" warnings for the new code we've added: that's -okay and expected. We'll be using the new code soon. - -### Processing - -Believe it or not, the hard part is done! (_whew!_). - -To process the upload, we'll need a place to store the uploaded files. To -simplify things, we'll store the uploads in a directory named `upload/`. Create -an `upload` directory next to the `src` directory: - -```sh -mkdir upload -``` - -For the `upload` route, we'll need to import `Data`: - -```rust -use rocket::Data; -``` - -The [Data](@api/rocket/data/struct.Data.html) structure is key -here: it represents an unopened stream to the incoming request body data. We'll -use it to efficiently stream the incoming request to a file. - -### Upload Route - -We're finally ready to write the `upload` route. Before we show you the code, -you should attempt to write the route yourself. Here's a hint: a possible route -and handler signature look like this: - -```rust -# #[macro_use] extern crate rocket; - -use rocket::Data; -use rocket::response::Debug; - -#[post("/", data = "")] -fn upload(paste: Data) -> std::io::Result { - # unimplemented!() - /* .. */ -} -``` - -Your code should: - - 1. Create a new `PasteId` of a length of your choosing. - 2. Construct a filename inside `upload/` given the `PasteId`. - 3. Stream the `Data` to the file with the constructed filename. - 4. Construct a URL given the `PasteId`. - 5. Return the URL to the client. - -Here's our version (in `src/main.rs`): - -```rust -# #[macro_use] extern crate rocket; -# fn main() {} - -# use std::fmt; -# struct PasteId; -# impl PasteId { fn new(n: usize) -> Self { PasteId } } -# impl fmt::Display for PasteId { -# fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { Ok(()) } -# } - -use rocket::response::Debug; -use rocket::data::{Data, ToByteUnit}; - -#[post("/", data = "")] -async fn upload(paste: Data) -> Result> { - let id = PasteId::new(3); - let filename = format!("upload/{id}", id = id); - let url = format!("{host}/{id}\n", host = "http://localhost:8000", id = id); - - // Write the paste out, limited to 128KiB, and return the URL. - paste.open(128.kibibytes()).into_file(filename).await?; - Ok(url) -} -``` - -Note the [`kibibytes()`] method call: this method comes from the [`ToByteUnit`] -extension trait. Ensure that the route is mounted at the root path: - -```rust -# #[macro_use] extern crate rocket; - -# #[get("/")] fn index() {} -# #[post("/")] fn upload() {} - -#[launch] -fn rocket() -> _ { - rocket::build().mount("/", routes![index, upload]) -} -``` - -Test that your route works via `cargo run`. From a separate terminal, upload a -file using `curl`. Then verify that the file was saved to the `upload` directory -with the correct ID: - -```sh -# in the project root -cargo run - -# in a separate terminal -echo "Hello, world." | curl --data-binary @- http://localhost:8000 -# => http://localhost:8000/eGs - -# back to the terminal running the pastebin - # kill running process -ls upload # ensure the upload is there -cat upload/* # ensure that contents are correct -``` - -Note that since we haven't created a `GET /` route, visiting the returned URL -will result in a **404**. We'll fix that now. - -[`kibibytes()`]: @api/rocket/data/trait.ToByteUnit.html#tymethod.kibibytes -[`ToByteUnit`]: @api/rocket/data/trait.ToByteUnit.html - -## Retrieving Pastes - -The final step is to create the `retrieve` route which, given an ``, will -return the corresponding paste if it exists. - -Here's a first take at implementing the `retrieve` route. The route below takes -in an `` as a dynamic path element. The handler uses the `id` to construct a -path to the paste inside `upload/`, and then attempts to open the file at that -path, optionally returning the `File` if it exists. Rocket treats a `None` -[Responder](@api/rocket/response/trait.Responder.html#provided-implementations) -as a **404** error, which is exactly what we want to return when the requested -paste doesn't exist. - -```rust -# #[macro_use] extern crate rocket; - -use rocket::tokio::fs::File; - -#[get("/")] -async fn retrieve(id: &str) -> Option { - let filename = format!("upload/{id}", id = id); - File::open(&filename).await.ok() -} -``` - -Make sure that the route is mounted at the root path: - -```rust -# #[macro_use] extern crate rocket; - -# #[get("/")] fn index() {} -# #[post("/")] fn upload() {} -# #[get("/")] fn retrieve(id: String) {} - -#[launch] -fn rocket() -> _ { - rocket::build().mount("/", routes![index, upload, retrieve]) -} -``` - -Unfortunately, there's a problem with this code. Can you spot the issue? The -`&str` type should tip you off! - -The issue is that the _user_ controls the value of `id`, and as a result, can -coerce the service into opening files inside `upload/` that aren't meant to be -opened. For instance, imagine that you later decide that a special file -`upload/_credentials.txt` will store some important, private information. If the -user issues a `GET` request to `/_credentials.txt`, the server will read and -return the `upload/_credentials.txt` file, leaking the sensitive information. -This is a big problem; it's known as the [full path disclosure -attack](https://www.owasp.org/index.php/Full_Path_Disclosure), and Rocket -provides the tools to prevent this and other kinds of attacks from happening. - -To prevent the attack, we need to _validate_ `id` before we use it. Since the -`id` is a dynamic parameter, we can use Rocket's -[FromParam](@api/rocket/request/trait.FromParam.html) trait to -implement the validation and ensure that the `id` is a valid `PasteId` before -using it. We do this by implementing `FromParam` for `PasteId` in -`src/paste_id.rs`, as below: - -```rust -use std::borrow::Cow; - -use rocket::request::FromParam; - -/// A _probably_ unique paste ID. -pub struct PasteId<'a>(Cow<'a, str>); - -/// Returns an instance of `PasteId` if the path segment is a valid ID. -/// Otherwise returns the invalid ID as the `Err` value. -impl<'a> FromParam<'a> for PasteId<'a> { - type Error = &'a str; - - fn from_param(param: &'a str) -> Result { - match param.chars().all(|c| c.is_ascii_alphanumeric()) { - true => Ok(PasteId(param.into())), - false => Err(param) - } - } -} -``` - -Then, we simply need to change the type of `id` in the handler to `PasteId`. -Rocket will then ensure that `` represents a valid `PasteId` before calling -the `retrieve` route, preventing attacks on the `retrieve` route: - -```rust -# #[macro_use] extern crate rocket; - -# use std::borrow::Cow; -# use rocket::tokio::fs::File; - -# type PasteId<'a> = &'a str; - -#[get("/")] -async fn retrieve(id: PasteId<'_>) -> Option { - let filename = format!("upload/{id}", id = id); - File::open(&filename).await.ok() -} -``` - -Note that our `from_param` function is simplistic and could be improved by, for -example, checking that the length of the `id` is within some known bound or -potentially blacklisting sensitive files as needed. - -The wonderful thing about using `FromParam` and other Rocket traits is that they -centralize policies. For instance, here, we've centralized the policy for valid -`PasteId`s in dynamic parameters. At any point in the future, if other routes -are added that require a `PasteId`, no further work has to be done: simply use -the type in the signature and Rocket takes care of the rest. - -## Conclusion - -That's it! Ensure that all of your routes are mounted and test your application. -You've now written a simple (~75 line!) pastebin in Rocket! There are many -potential improvements to this small application, and we encourage you to work -through some of them to get a better feel for Rocket. Here are some ideas: - - * Add a web form to the `index` where users can manually input new pastes. - Accept the form at `POST /`. Use `format` and/or `rank` to specify which of - the two `POST /` routes should be called. - * Support **deletion** of pastes by adding a new `DELETE /` route. Use - `PasteId` to validate ``. - * Indicate **partial uploads** with a **206** partial status code. If the user - uploads a paste that meets or exceeds the allowed limit, return a **206** - partial status code. Otherwise, return a **201** created status code. - * Set the `Content-Type` of the return value in `upload` and `retrieve` to - `text/plain`. - * **Return a unique "key"** after each upload and require that the key is - present and matches when doing deletion. Use one of Rocket's core traits to - do the key validation. - * Add a `PUT /` route that allows a user with the key for `` to - replace the existing paste, if any. - * Add a new route, `GET //` that syntax highlights the paste with ID - `` for language ``. If `` is not a known language, do no - highlighting. Possibly validate `` with `FromParam`. - * Use the [`local` module](@api/rocket/local/) to write unit tests for your - pastebin. - * Dispatch a thread before `launch`ing Rocket in `main` that periodically - cleans up idling old pastes in `upload/`. - -You can find the full source code for the [completed pastebin tutorial on -GitHub](@example/pastebin). diff --git a/site/guide/11-conclusion.md b/site/guide/11-conclusion.md index 79ee2ad048..5c057e63f7 100644 --- a/site/guide/11-conclusion.md +++ b/site/guide/11-conclusion.md @@ -9,14 +9,15 @@ we're happy to take the best ideas. If you have something in mind, please If you find yourself having trouble developing Rocket applications, you can get help via chat at [`#rocket:mozilla.org`] on Matrix or the bridged [`#rocket`] -IRC channel on Freenode at `chat.freenode.net`. We recommend joining us on +IRC channel on Libera.Chat at `irc.libera.chat`. We recommend joining us on [Matrix via Element]. If you prefer IRC, you can join via the [Kiwi IRC client] -or a client of your own. +or a client of your own. The [FAQ](../faq/) also provides answers to commonly +asked questions. [`#rocket:mozilla.org`]: https://chat.mozilla.org/#/room/#rocket:mozilla.org -[`#rocket`]: https://kiwiirc.com/client/chat.freenode.net/#rocket +[`#rocket`]: https://kiwiirc.com/client/irc.libera.chat/#rocket [Matrix via Element]: https://chat.mozilla.org/#/room/#rocket:mozilla.org -[Kiwi IRC Client]: https://kiwiirc.com/client/chat.freenode.net/#rocket +[Kiwi IRC Client]: https://kiwiirc.com/client/irc.libera.chat/#rocket ## What's next? diff --git a/site/guide/12-faq.md b/site/guide/12-faq.md new file mode 100644 index 0000000000..4b565f9a61 --- /dev/null +++ b/site/guide/12-faq.md @@ -0,0 +1,663 @@ +# FAQ + +Below you'll find a collection of commonly asked questions and answers. If you +have suggestions for questions you'd like to see answered here, [comment on the +discussion thread]. + +[comment on the discussion thread]: https://github.com/SergioBenitez/Rocket/discussions/1836 + +## About Rocket + +
+ +Is Rocket a monolithic framework like Rails? Or is it more like Flask? +# + +
+ +Neither! + +Rocket's core is small yet complete with respect to security and correctness. It +mainly consists of: + + * Guard traits like [`FromRequest`] and [`FromData`]. + * Derive macros for all common traits. + * Attribute macros for routing. + * Thorough compile and launch-time checking. + * Zero-copy parsers and validators for common formats like multipart and SSE. + * Syntax sugar extensions for features like async streams and traits. + * Optional features for functionality like TLS, secrets, and so on. + +The goal is for functionality like templating, sessions, ORMs, and so on to be +implemented entirely outside of Rocket while maintaining a first-class feel and +experience. Indeed, crates like [`rocket_dyn_templates`] and [`rocket_db_pools`] +do just this. As a result, Rocket is neither "bare-bones" nor is it a kitchen +sink for all possible features. + +Unlike other frameworks, Rocket makes it its mission to help you avoid security +and correctness blunders. It does this by including, out-of-the-box: + + * A flexible, type-based [configuration](../configuration/) system. + * [Security and privacy headers](@api/rocket/shield/) by default. + * Zero-Copy RFC compliant [URI parsers](@api/rocket/http/uri). + * Safe, [typed URIs](@api/rocket/macro.uri.html) with compile-time checking. + * [Compile-time and launch-time route checking](@api/rocket/attr.route.html). + * A [testing framework](@api/rocket/local) with sync and `async` variants. + * Safe, exclusive access to fully decoded HTTP values. + * Mandatory [data limits](@api/rocket/data/struct.Limits.html) to prevent + trivial DoS attacks. + +Of course, this functionality comes at a compile-time cost (but notably, _not_ +at a runtime cost), impacting Rocket's clean build-time. For comparison, here's +what building "Hello, world!" for the first time in popular Rust web frameworks +looks like: + +| Framework | Dependencies | Build Time | +|----------------------|--------------|------------| +| Rocket 0.5-rc.2 | 151 | 50s | +| Actix-Web 4.0.1 | 155 | 40s | +| Tide 0.16 | 202 | 37s | +| Warp 0.3.2 | 132 | 30s | +| Axum 0.5.4 | 81 | 18s | + +· Measurements taken on a MacBookPro15,1 Intel Core i9 @ 2.9GHZ, macOS +12.1, Rust 1.60 stable. Best of 3.
+· Rocket includes features like multipart parsing and static file +serving that would require additional deps in other frameworks. + +Of course, iterative build-time is nearly identical for all frameworks, and the +time can be further reduced by using faster linkers like `lld`. We think the +trade-off is worth it. Rocket will never compromise security, correctness, or +usability to "win" at benchmarks of any sort. + +
+
+ +[`rocket_dyn_templates`]: @api/rocket_dyn_templates +[`rocket_db_pools`]: @api/rocket_db_pools + +
+ +I want a small and compact web framework. Is Rocket it? +# + +
+ +We think so! See ["Is Rocket a monolithic framework like Rails?"](#monolithic) +
+
+ +
+ +I want a web framework with all the bells and whistles. Is Rocket it? +# + +
+ +We think so! See ["Is Rocket a monolithic framework like Rails?"](#monolithic) +
+
+ +
+ +Can I use Rocket in production? Should I? It's only v0.x! +# + +
+ +We **enthusiastically** recommend using Rocket in production, with the following +non-exhaustive list of caveats: + + 1. Run Rocket behind a reverse proxy like HAProxy or in a production load + balancing environment. Rocket (Hyper) doesn't employ any defenses against + DDoS attacks or certain DoS attacks which can be mitigated by an external + service. + + 2. Use a TLS termination proxy (perhaps from 1.) for zero-downtime certificate + rotation. + + 3. Properly configure your databases and database pools, especially with + respect to the pool size. + + 4. Ensure no blocking I/O happens outside of `spawn_blocking()` invocations. + +While Rocket _is_ still in the `0.x` phase, the version number is purely a +stylistic choice. In fact, we consider Rocket to be the most mature web +framework in the Rust ecosystem. To our knowledge, Rocket is the only Rust web +framework that correctly implements: + + * Server-Sent Events + * Graceful Shutdown + * Form Parsing with Arbitrarily Structure + * Zero-Copy, RFC Conforming URI Types + * Ambiguity-Free Routing + * Streamed Multipart Uploads + +If you're coming from a different ecosystem, you should feel comfortable +considering Rocket's `v0.x` as someone else's `vx.0`. Rust and Cargo's semver +policy, and Rocket's strict adherence to it, ensures that Rocket will _never_ +break your application when upgrading from `0.x.y` to `0.x.z`, where `z >= y`. +Furthermore, we backport _all_ security and correctness patches to the previous +major release (`0.{x-1}.y`), so your application remains secure if you need time +to upgrade. + +
+
+ +
+ +Is Rocket slow? Is Rocket fast? +# + +
+ +Rocket is pretty fast. + +A commonly repeated myth is that Rocket's great usability comes at the cost of +runtime performance. _**This is false.**_ Rocket's usability derives largely +from compile-time checks with _zero_ bearing on runtime performance. + +So what about benchmarks? Well, benchmarking is _hard_, and besides often being +conducted incorrectly*, often appear to say more than they do. So, when +you see a benchmark for "Hello, world!", you should know that the benchmark's +relevance doesn't extend far beyond those specific "Hello, world!" servers and +the specific way the measurement was taken. In other words, it provides _some_ +baseline that is hard to extrapolate to real-world use-cases, _your_ use-case. + +Nevertheless, here are some things you can consider as _generally_ true about +Rocket applications: + + * They'll perform much, _much_ better than those written in scripting + languages like Python or Ruby. + * They'll perform much better than those written in VM or JIT languages like + JavaScript or Java. + * They'll perform a bit better than those written in compiled-to-native but + GC'd languages like Go. + * They'll perform competitively with those written in compiled-to-native, + non-GC'd languages like Rust or C. + +Again, we emphasize _generally_ true. It is trivial to write a Rocket +application that is slower than a similar Python application. + +Besides a framework's _internal_ performance, you should also consider whether +it enables your _application itself_ to perform well. Rocket takes great care to +enable your application to perform as little work as possible through +unique-to-Rocket features like [managed state], [request-local state], and +zero-copy parsing and deserialization. + +* A common mistake is to pit against Rocket's "Hello, world!" without +normalizing for response size, especially security headers. + +
+
+ +[managed state]: ../state/#managed-state +[request-local state]: ../state/#request-local-state + +
+ +What are some examples of "big" apps written in Rocket? +# + +
+ +Here are some notable projects and websites in Rocket we're aware of: + + * [Vaultwarden] - A BitWarden Server + * [Rust-Lang.org] - Rust Language Website + * [Plume] - Federated Blogging Engine + * [Hagrid] - OpenPGP KeyServer ([keys.openpgp.org](https://keys.openpgp.org/)) + * [SourceGraph Syntax Highlighter] - Syntax Highlighting API + +[Let us know] if you have a notable, public facing application written in Rocket +you'd like to see here! + +[Vaultwarden]: https://github.com/dani-garcia/vaultwarden +[Conduit]: https://conduit.rs/ +[Rust-Lang.org]: https://www.rust-lang.org/ +[Plume]: https://github.com/Plume-org/Plume +[Hagrid]: https://gitlab.com/hagrid-keyserver/hagrid/ +[SourceGraph Syntax Highlighter]: https://github.com/sourcegraph/sourcegraph/tree/main/docker-images/syntax-highlighter +[Let us know]: https://github.com/SergioBenitez/Rocket/discussions/categories/show-and-tell + +
+
+ +
+ +When will version `$y` be released? Why does it take so long? +# + +
+ +Rocket represents an ecosystem-wide effort to create a web framework that +enables writing web applications with unparalleled security, performance, and +usability. From design to implementation to documentation, Rocket is carefully +crafted to ensure the greatest productivity and reliability with the fewest +surprises. Our goal is to make Rocket a compelling choice across _all_ +languages. + +Accomplishing this takes time, and our efforts extend to the entire ecosystem. +For example, work for Rocket v0.5 included: + + * [Fixing correctness issues in `x509-parser`.](https://github.com/rusticata/x509-parser/pull/90) + * [Reporting multiple](https://github.com/bikeshedder/deadpool/issues/114) + [correctness issues](https://github.com/bikeshedder/deadpool/issues/113) in `deadpool`. + * [Fixing a major usability issue in `async-stream`.](https://github.com/tokio-rs/async-stream/pull/57) + * [Creating a brand new configuration library.](https://github.com/SergioBenitez/Figment) + * [Updating](https://github.com/rousan/multer-rs/pull/21), + [fixing](https://github.com/rousan/multer-rs/pull/29), and + [maintaining](https://github.com/rousan/multer-rs/commit/2758e778e6aa2785b737c82fe45e58026bea2f01) `multer`. + * [Significantly improving `async_trait` correctness and usability.](https://github.com/dtolnay/async-trait/pull/143) + * [Porting `Pattern` APIs to stable.](https://github.com/SergioBenitez/stable-pattern) + * [Porting macro diagnostics to stable.](https://github.com/SergioBenitez/proc-macro2-diagnostics) + * [Creating a brand new byte unit library.](https://github.com/SergioBenitez/ubyte) + * [Fixing a bug in `rustc`'s `libtest`.](https://github.com/rust-lang/rust/pull/78227) + +A version of Rocket is released whenever it is feature-complete and exceeds +feature, security, and usability parity with the previous version. As a result, +specifying a release date is nearly impossible. We are _always_ willing to delay +a release if these properties are not readily evident. + +We know it can be frustrating, but we hope you'll agree that Rocket is worth the +wait. + +
+
+ +## How To + +
+ +Can I, and if so how, do I use WebSockets? +# + +
+ +Rocket doesn't support WebSockets quite yet. We're [working on it]. + +That being said, Rocket _does_ suport [Server-Sent Events], which allows for +real-time _unidirectional_ communication from the server to the client. This is +often sufficient for many of the applications that WebSockets are typically used +for. For instance, the [chat example] uses SSE to implement a real-time, +multiroom chat application. +
+
+ +[working on it]: https://github.com/SergioBenitez/Rocket/issues/90 +[Server-Sent Events]: @api/rocket/response/stream/struct.EventStream.html +[chat example]: @example/chat + +
+ +Should I use global state via something like `lazy_static!`? +# + +
+ +No. Rocket's [managed state] provides a better alternative. + +While it may be convenient or comfortable to use global state, the downsides are +numerous. They include: + + * The inability to test your application with different state. + * The inability to run your application on different threads with different + state. + * The inability to know the state a route accesses by looking at its + signature. +
+
+ +[managed state]: ../state/#managed-state + +
+ +How do I handle file uploads? What is this "multipart" in my stream? +# + +
+ +For a quick example on how to handle file uploads, see [multipart forms]. The +gist is: use `Form` as a data guard. + +File uploads are encoded and transmitted by the browser as [multipart] forms. +The raw stream, as seen by [`Data`] for example, thus contains the necessary +metadata to encode the form. Rocket's [`Form`] data guard can parse these form +submissions into any type that implements [`FromForm`]. This includes types like +[`TempFile`] which streams the decoded data to disk for persistence. +
+
+ +[multipart]: https://datatracker.ietf.org/doc/html/rfc7578 +[multipart forms]: ../requests/#multipart +[`DataField`]: @api/rocket/form/struct.DataField.html +[`TempFile`]: @api/rocket/fs/enum.TempFile.html +[`DataField`]: @api/rocket/data/struct.Data.html +[`Form`]: @api/rocket/form/struct.Form.html +[`FromForm`]: @api/rocket/form/trait.FromForm.html +[`Data`]: @api/rocket/struct.Data.html + +
+ +How do I get an `&Request` in a handler? +# + +
+ +You don't! + +Rocket's [philosophy] is that as much of the request should be validated and +converted into useful typed values _before_ being processed. Allowing a +`Request` to be handled directly is incompatible with this idea. + +Instead, Rocket's handlers work through _guards_, reified as traits, which +validate and extract parts of a request as needed. Rocket automatically invokes +these guards for you, so custom guards are write-once-use-everywhere. Rocket +won't invoke a handler with failing guards. This way, handlers only deal with +fully validated, typed, secure values. + +Rocket provides all of the guard implementations you would expect +out-of-the-box, and you can implement your own, too. See the following: + + * Parameter Guards: [`FromParam`] + * Multi-Segment Guards: [`FromSegments`] + * Data Guards: [`FromData`] + * Form Guards: [`FromFrom`] + * Request Guards: [`FromRequest`] +
+
+ +[philosophy]: ../introduction/#foreword +[`FromParam`]: @api/rocket/request/trait.FromParam.html +[`FromSegments`]: @api/rocket/request/trait.FromSegments.html +[`FromData`]: @api/rocket/data/trait.FromData.html +[`FromFrom`]: @api/rocket/form/trait.FromForm.html +[`FromRequest`]: @api/rocket/request/trait.FromRequest.html + +
+ +How do I add a header to a response? +# + +
+ +That depends on the header! + +Any "transport" headers (`Content-Length`, `Transfer-Encoding`, etc.) are +automatically set by Rocket and cannot be directly overridden for correctness +reasons. The rest are set by a route's [`Responder`]. + +**Status** + +Rocket automatically sets a `Status` header for all responses. If a `Responder` +doesn't explicitly set a status, it defaults to `200`. Some responders, like +`Option`, do set a status. See [`Responder`] and the [`status`] module for +details on setting a custom `Status` or overriding an existing one. + +**Content-Type** + +Rocket automatically sets a `Content-Type` header for types it implements +`Responder` for, so in the common case, there's nothing to do. This includes +types like `&str`, `&[u8]`, `NamedFile`, and so on. The [`content`] module docs +details setting a custom `Content-Type` or overriding an existing one. + +**Everything Else** + +To add a custom header, you'll need a custom [`Responder`]. Not to worry! +[`Responder` can be derived](@api/rocket/derive.Responder.html) in almost all +cases. If a type for the header you want to add already exists, you can directly +derive `Responder` for a struct that contains the header value, which adds the +header to the response: + +```rust +# #[macro_use] extern crate rocket; +# use rocket::http::Header; + +# type HeaderType = Header<'static>; + +# impl From for MyResponder { +# fn from(inner: T) -> Self { +# MyResponder { inner, header: Header::new("X-My-Header", "some value") } +# } +# } + +#[derive(Responder)] +struct MyResponder { + inner: T, + header: HeaderType, +} + +#[get("/")] +fn with_header() -> MyResponder<&'static str> { + MyResponder::from("Hello, world!") +} +``` + +A `HeaderType` won't exist for custom headers, but you can define your own type. +As long as it implements `Into
` for Rocket's [`Header`], the type can be +used as a field in derived struct. + +Alternatively, you can always implement `Responder` directly. Make sure to +leverage existing responders in your implementation. For example, _don't_ +serialize JSON manually. Instead, use the existing [`Json`] responder, like in +the example below: + +```rust +# #[derive(rocket::serde::Serialize)] +# #[serde(crate = "rocket::serde")] +# struct Person { name: String, age: usize }; + +use rocket::request::Request; +use rocket::response::{self, Response, Responder}; +use rocket::serde::json::Json; + +impl<'r> Responder<'r, 'static> for Person { + fn respond_to(self, req: &'r Request<'_>) -> response::Result<'static> { + Response::build_from(Json(&self).respond_to(req)?) + .raw_header("X-Person-Name", self.name) + .raw_header("X-Person-Age", self.age.to_string()) + .ok() + } +} +``` + +
+
+ +[`Responder`]: @api/rocket/response/trait.Responder.html +[`content`]: @api/rocket/response/content/index.html +[`status`]: @api/rocket/response/status/index.html +[`Header`]: @api/rocket/http/struct.Header.html +[`Json`]: @api/rocket/serde/json/struct.Json.html + +
+ +How do I make one handler return different responses or status codes? +# + +
+ +If you're returning _two_ different responses, use a `Result` or an +[`Either`]. + +If you need to return _more_ than two kinds, [derive a custom `Responder`] `enum`: + +```rust +# use rocket::response::Responder; +use rocket::fs::NamedFile; +use rocket::http::ContentType; + +#[derive(Responder)] +enum Error<'r, T> { + #[response(status = 400)] + Unauthorized(T), + #[response(status = 404)] + NotFound(NamedFile), + #[response(status = 500)] + A(&'r str, ContentType), +} +``` + +
+
+ +[`Either`]: https://docs.rs/either/1/either/enum.Either.html +[derive a custom `Responder`]: @api/rocket/derive.Responder.html + +
+ +How do I make Rocket reload automatically when I change source code? +# + +
+ +In debug mode, Rocket automatically reloads templates for you. So if all you +need is live template reloading, Rocket's got you covered. + +For everything else, you'll need to use an external tool like [`cargo-watch`], +[`watchexec`] or [`entr`]. With `cargo-watch`, you can automatically rebuild and +run a Rocket application by executing: + +```sh +cargo watch -x run +``` + +To only restart on successful compilations, see [this note]. +
+
+ +[`cargo-watch`]: https://github.com/watchexec/cargo-watch +[`watchexec`]: https://github.com/watchexec/watchexec +[`entr`]: http://eradman.com/entrproject/ +[this note]: https://github.com/watchexec/cargo-watch/tree/b75ce2c260874dea480f4accfd46ab28709ec56a#restarting-an-application-only-if-the-buildcheck-succeeds + +
+ +How do I access managed state outside of a Rocket-related context? +# + +
+ +Use an `Arc`, like this: + +```rust +# use rocket::*; +use std::sync::Arc; + +#[launch] +fn rocket() -> _ { + # struct MyState; + let state = Arc::new(MyState); + + let external = state.clone(); + std::thread::spawn(move || { + let use_state = external; + }); + + rocket::build().manage(state) +} +``` + +
+
+ +
+ +How do I make Rocket a _part_ of my application as opposed to the whole thing? +# + +
+ +Use the `#[main]` attribute and manually call [`launch()`]: + +```rust,no_run +#[rocket::main] +async fn main() { + # let should_start_server = false; + if should_start_server { + let result = rocket::build().launch().await; + } else { + // do something else + } +} +``` + +The cost to using the attribute is imperceptible and guarantees compatibility +with Rocket's async I/O. + +
+
+ +[`launch()`]: @api/rocket/struct.Rocket.html#method.launch + +## Debugging + +
+ +Is example `foo` broken? It doesn't work for me. +# + +
+ +Almost certainly not. + +Every example and code snippet you see in published documentation is tested by +the CI on every commit, and we only publish docs that pass the CI. Unless the CI +environment is broken, the examples _cannot_ be wrong. + +Common mistakes when running examples include: + + * Looking at an example for version `y` but depending on version `x`. Select + the proper git tag! + * Looking at outdated examples on StackOverflow or Google. Check the + date/version! + * Not configuring the correct dependencies. See the example's `Cargo.toml`! +
+
+ +
+ +The trait bound `rocket::Responder` (`FromRequest`, etc.) is not satisfied. +# + +
+ +If you're fairly certain a type implements a given Rocket trait but still get an +error like: + +```rust,ignore +error[E0277]: the trait bound `Foo: Responder<'_, '_>` is not satisfied + --> src\main.rs:4:20 + | +4 | fn foo() -> Foo + | ^^^ the trait `Responder<'_, '_>` is not implemented for `Foo` + | + = note: required by `respond_to` +``` + +...then you're almost certainly depending, perhaps transitively, on _two +different versions_ of a single library. For example, you may be depending on +`rocket` which depends on `time 0.3` while also depending directly on `time +0.2`. Or you may depending on `rocket` from `crates.io` while depending on a +library that depends on `rocket` from `git`. A common instance of this mistake +is to depend on a `contrib` library from git while also depending on a +`crates.io` version of Rocket or vice-versa: + +```toml +rocket = "0.5.0-rc.2" +rocket_db_pools = { git = "https://github.com/SergioBenitez/Rocket.git" } +``` + +This is _never_ correct. If libraries or applications interact via types from a +common library, those libraries or applications _must_ specify the _same_ +version of that common library. This is because in Rust, types from two +different versions of a library or from different providers (like `git` vs. +`crates.io`) are _always_ considered distinct, even if they have the same name. +Therefore, even if a type implements a trait from one library, it _does not_ +implement the trait from the other library (since it is considered to be a +_different_, _distinct_ library). In other words, you can _never_ mix two +different published versions of Rocket, a published version and a `git` version, +or two instances from different `git` revisions. + +
+
diff --git a/site/guide/2-getting-started.md b/site/guide/2-getting-started.md index f4edd14393..168fd8024b 100644 --- a/site/guide/2-getting-started.md +++ b/site/guide/2-getting-started.md @@ -12,7 +12,7 @@ installation of the latest Rust compiler, feel free to skip to the next section. To install the latest version of Rust, we recommend using `rustup`. Install `rustup` by following the instructions on [its website](https://rustup.rs/). -Once `rustup` is installed, ensure the latest toolchain is installled by running +Once `rustup` is installed, ensure the latest toolchain is installed by running the command: ```sh @@ -43,7 +43,7 @@ Now, add Rocket as a dependency in your `Cargo.toml`: ```toml [dependencies] -rocket = "0.5.0-dev" +rocket = "0.5.0-rc.2" ``` ! warning: Development versions must be _git_ dependencies. @@ -103,5 +103,5 @@ Visit `http://localhost:8000` to see your first Rocket application in action! ! tip: Don't like colors or emoji? You can disable colors and emoji by setting the `ROCKET_CLI_COLORS` - environment variable to `0` or `off` when running a Rocket binary: - `ROCKET_CLI_COLORS=off cargo run`. + environment variable to `0` or `false` when running a Rocket binary: + `ROCKET_CLI_COLORS=false cargo run`. diff --git a/site/guide/3-overview.md b/site/guide/3-overview.md index a01bab9f68..499a75579a 100644 --- a/site/guide/3-overview.md +++ b/site/guide/3-overview.md @@ -141,7 +141,7 @@ Rocket begins serving requests after being _launched_, which starts a multi-threaded asynchronous server and dispatches requests to matching routes as they arrive. -There are two mechnisms by which a `Rocket` can be launched. The first and +There are two mechanisms by which a `Rocket` can be launched. The first and preferred approach is via the `#[launch]` route attribute, which generates a `main` function that sets up an async runtime and starts the server. With `#[launch]`, our complete _Hello, world!_ application looks like: @@ -209,11 +209,13 @@ runtime but unlike `#[launch]`, allows _you_ to start the server: # } #[rocket::main] -async fn main() { - rocket::build() +async fn main() -> Result<(), rocket::Error> { + let _rocket = rocket::build() .mount("/hello", routes![world]) .launch() - .await; + .await?; + + Ok(()) } ``` @@ -228,7 +230,7 @@ is desired, or when the return value of [`launch()`] is to be inspected. The Rocket uses Rust [`Future`]s for concurrency. Asynchronous programming with `Future`s and `async/await` allows route handlers to perform wait-heavy I/O such -as filesystem and network access while still allowing other requests to be make +as filesystem and network access while still allowing other requests to make progress. For an overview of Rust `Future`s, see [Asynchronous Programming in Rust](https://rust-lang.github.io/async-book/). @@ -258,7 +260,7 @@ You can find async-ready libraries on [crates.io](https://crates.io) with the ! note - Rocket master uses the tokio runtime. The runtime is started for you if you + Rocket v0.5 uses the tokio runtime. The runtime is started for you if you use `#[launch]` or `#[rocket::main]`, but you can still `launch()` a Rocket instance on a custom-built runtime by not using _either_ attribute. diff --git a/site/guide/4-requests.md b/site/guide/4-requests.md index c943d5b02a..96c0cb9e38 100644 --- a/site/guide/4-requests.md +++ b/site/guide/4-requests.md @@ -58,7 +58,7 @@ your application explicitly handles. ### Reinterpreting -Because HTML forms can only be directly submitted as `GET` or `POST` requests, +Because web browsers only support submitting HTML forms as `GET` or `POST` requests, Rocket _reinterprets_ request methods under certain conditions. If a `POST` request contains a body of `Content-Type: application/x-www-form-urlencoded` and the form's **first** field has the name `_method` and a valid HTTP method name @@ -149,7 +149,7 @@ async fn files(file: PathBuf) -> Option { } ``` -[path traversal attacks]: https://www.owasp.org/index.php/Path_Traversal +[path traversal attacks]: https://owasp.org/www-community/attacks/Path_Traversal ! tip: Rocket makes it even _easier_ to serve static files! @@ -161,9 +161,39 @@ async fn files(file: PathBuf) -> Option { [`FileServer`]: @api/rocket/fs/struct.FileServer.html [`FromSegments`]: @api/rocket/request/trait.FromSegments.html +### Ignored Segments + +A component of a route can be fully ignored by using `<_>`, and multiple +components can be ignored by using `<_..>`. In other words, the wildcard name +`_` is a dynamic parameter name that ignores that dynamic parameter. An ignored +parameter must not appear in the function argument list. A segment declared as +`<_>` matches anything in a single segment while segments declared as `<_..>` +match any number of segments with no conditions. + +As an example, the `foo_bar` route below matches any `GET` request with a +3-segment URI that starts with `/foo/` and ends with `/bar`. The `everything` +route below matches _every_ GET request. + +```rust +# #[macro_use] extern crate rocket; + +#[get("/foo/<_>/bar")] +fn foo_bar() -> &'static str { + "Foo _____ bar!" +} + +#[get("/<_..>")] +fn everything() -> &'static str { + "Hey, you're here." +} + +# // Ensure there are no collisions. +# rocket_guide_tests::client(routes![foo_bar, everything]); +``` + ## Forwarding -Let's take a closer look at the route attribute and signature pair from a +Let's take a closer look at this route attribute and signature pair from a previous example: ```rust @@ -181,7 +211,7 @@ there are no remaining routes to try. When there are no remaining routes, a customizable **404 error** is returned. Routes are attempted in increasing _rank_ order. Rocket chooses a default -ranking from -6 to -1, detailed in the next section, but a route's rank can also +ranking from -12 to -1, detailed in the next section, but a route's rank can also be manually set with the `rank` attribute. To illustrate, consider the following routes: @@ -247,6 +277,7 @@ queries: the _more_ static a route's path and query are, the higher its precedence. There are three "colors" to paths and queries: + 1. `static`, meaning all components are static 2. `partial`, meaning at least one component is dynamic 3. `wild`, meaning all components are dynamic @@ -269,7 +300,25 @@ and wild paths. This results in the following default ranking table: | wild | wild | -2 | | wild | none | -1 | -Recall that _lower_ ranks have _higher_ precedence. +Recall that _lower_ ranks have _higher_ precedence. As an example, consider this +application from before: + +```rust +# #[macro_use] extern crate rocket; + +#[get("/foo/<_>/bar")] +fn foo_bar() { } + +#[get("/<_..>")] +fn everything() { } + +# // Ensure there are no collisions. +# rocket_guide_tests::client(routes![foo_bar, everything]); +``` + +Default ranking ensures that `foo_bar`, with a "partial" path color, has higher +precedence than `everything` with a "wild" path color. This default ranking +prevents what would have otherwise been a routing collision. ## Request Guards @@ -478,13 +527,13 @@ feature: ```toml ## in Cargo.toml -rocket = { version = "0.5.0-dev", features = ["secrets"] } +rocket = { version = "0.5.0-rc.2", features = ["secrets"] } ``` The API for retrieving, adding, and removing private cookies is identical except -methods are suffixed with `_private`. These methods are: [`get_private`], -[`get_private_pending`], [`add_private`], and [`remove_private`]. An example of -their usage is below: +that most methods are suffixed with `_private`. These methods are: +[`get_private`], [`get_pending`], [`add_private`], and [`remove_private`]. An +example of their usage is below: ```rust # #[macro_use] extern crate rocket; @@ -527,7 +576,6 @@ For more information on configuration, see the [Configuration](../configuration) section of the guide. [`get_private`]: @api/rocket/http/struct.CookieJar.html#method.get_private -[`get_private_pending`]: @api/rocket/http/struct.CookieJar.html#method.get_private_pending [`add_private`]: @api/rocket/http/struct.CookieJar.html#method.add_private [`remove_private`]: @api/rocket/http/struct.CookieJar.html#method.remove_private @@ -549,7 +597,7 @@ As an example, consider the following route: # #[macro_use] extern crate rocket; # fn main() {} -# type User = rocket::data::Data; +# type User = String; #[post("/user", format = "application/json", data = "")] fn new_user(user: User) { /* ... */ } @@ -598,7 +646,7 @@ trait. It looks like this, where `T` is assumed to implement `FromData`: ```rust # #[macro_use] extern crate rocket; -# type T = rocket::data::Data; +# type T = String; #[post("/", data = "")] fn new(input: T) { /* .. */ } @@ -610,7 +658,7 @@ Any type that implements [`FromData`] is also known as _a data guard_. ### JSON -The [`Json`](@api/rocket/serde/json/struct.Json.html) guard deserialzies body +The [`Json`](@api/rocket/serde/json/struct.Json.html) guard deserializes body data as JSON. The only condition is that the generic type `T` implements the `Deserialize` trait from [`serde`](https://serde.rs). @@ -620,6 +668,7 @@ data as JSON. The only condition is that the generic type `T` implements the use rocket::serde::{Deserialize, json::Json}; #[derive(Deserialize)] +#[serde(crate = "rocket::serde")] struct Task<'r> { description: &'r str, complete: bool @@ -629,14 +678,40 @@ struct Task<'r> { fn new(task: Json>) { /* .. */ } ``` -See the [JSON example] on GitHub for a complete example. +! warning: Using Rocket's `serde` derive re-exports requires a bit more effort. + + For convenience, Rocket re-exports `serde`'s `Serialize` and `Deserialize` + traits and derive macros from `rocket::serde`. However, due to Rust's limited + support for derive macro re-exports, using the re-exported derive macros + requires annotating structures with `#[serde(crate = "rocket::serde")]`. If + you'd like to avoid this extra annotation, you must depend on `serde` directly + via your crate's `Cargo.toml`: + + ` + serde = { version = "1.0", features = ["derive"] } + ` -[JSON example]: @example/json + We always use the extra annotation in the guide, but you may prefer the + alternative. + +See the [JSON example](@example/serialization/src/json.rs) on GitHub for a +complete example. + +! note: JSON support requires enabling Rocket's `json` feature flag. + + Rocket intentionally places JSON support, as well support for other data + formats and features, behind feature flags. See [the api + docs](@api/rocket/#features) for a list of available features. The `json` + feature can be enabled in the `Cargo.toml`: + + ` + rocket = { version = "0.5.0-rc.2", features = ["json"] } + ` ### Temporary Files The [`TempFile`] data guard streams data directly to a temporary file which can -the be persisted. It makes accepting file uploads trivial: +then be persisted. It makes accepting file uploads trivial: ```rust # #[macro_use] extern crate rocket; @@ -650,7 +725,7 @@ async fn upload(mut file: TempFile<'_>) -> std::io::Result<()> { } ``` -[`TempFile`]: @api/rocket/fs/struct.TempFile.html +[`TempFile`]: @api/rocket/fs/enum.TempFile.html ### Streaming @@ -666,7 +741,7 @@ use rocket::tokio; use rocket::data::{Data, ToByteUnit}; #[post("/debug", data = "")] -async fn debug(data: Data) -> std::io::Result<()> { +async fn debug(data: Data<'_>) -> std::io::Result<()> { // Stream at most 512KiB all of the body data to stdout. data.open(512.kibibytes()) .stream_to(tokio::io::stdout()) @@ -714,15 +789,16 @@ struct Task<'r> { fn new(task: Form>) { /* .. */ } ``` -The [`Form`] type implements the `FromData` trait as long as its generic -parameter implements the [`FromForm`] trait. In the example, we've derived the -`FromForm` trait automatically for the `Task` structure. `FromForm` can be -derived for any structure whose fields implement [`FromForm`], or equivalently, -[`FromFormField`]. If a `POST /todo` request arrives, the form data will -automatically be parsed into the `Task` structure. If the data that arrives -isn't of the correct Content-Type, the request is forwarded. If the data doesn't -parse or is simply invalid, a customizable error is returned. As before, a -forward or failure can be caught by using the `Option` and `Result` types: +[`Form`] is data guard as long as its generic parameter implements the +[`FromForm`] trait. In the example, we've derived the `FromForm` trait +automatically for `Task`. `FromForm` can be derived for any structure whose +fields implement [`FromForm`], or equivalently, [`FromFormField`]. + +If a `POST /todo` request arrives, the form data will automatically be parsed +into the `Task` structure. If the data that arrives isn't of the correct +Content-Type, the request is forwarded. If the data doesn't parse or is simply +invalid, a customizable error is returned. As before, a forward or failure can +be caught by using the `Option` and `Result` types: ```rust # use rocket::{post, form::Form}; @@ -732,8 +808,32 @@ forward or failure can be caught by using the `Option` and `Result` types: fn new(task: Option>>) { /* .. */ } ``` +### Multipart + +Multipart forms are handled transparently, with no additional effort. Most +`FromForm` types can parse themselves from the incoming data stream. For +example, here's a form and route that accepts a multipart file upload using +[`TempFile`]: + +```rust +# #[macro_use] extern crate rocket; + +use rocket::form::Form; +use rocket::fs::TempFile; + +#[derive(FromForm)] +struct Upload<'r> { + save: bool, + file: TempFile<'r>, +} + +#[post("/upload", data = "")] +fn upload_form(upload: Form>) { /* .. */ } +``` + [`Form`]: @api/rocket/form/struct.Form.html [`FromForm`]: @api/rocket/form/trait.FromForm.html +[`FromFormField`]: @api/rocket/form/trait.FromFormField.html ### Parsing Strategy @@ -810,10 +910,10 @@ struct MyForm<'v> { # rocket_guide_tests::assert_form_parses_ok!(MyForm, ""); ``` -The default can be overridden or unset using the `#[field(default = expr)` field -attribute. If `expr` is not literally `None`, the parameter sets the default -value of the field to be `expr.into()`. If `expr` _is_ `None`, the parameter -_unsets_ the default value of the field, if any. +The default can be overridden or unset using the `#[field(default = expr)]` +field attribute. If `expr` is not literally `None`, the parameter sets the +default value of the field to be `expr.into()`. If `expr` _is_ `None`, the +parameter _unsets_ the default value of the field, if any. ```rust # use rocket::form::FromForm; @@ -950,14 +1050,14 @@ struct Password<'r> { In reality, the expression after `validate =` can be _any_ expression as long as it evaluates to a value of type `Result<(), Errors<'_>>` (aliased by [`form::Result`]), where an `Ok` value means that validation was successful while -an `Err` of [`Errors<'_>`] indicates the error(s) that occured. For instance, if +an `Err` of [`Errors<'_>`] indicates the error(s) that occurred. For instance, if you wanted to implement an ad-hoc Luhn validator for credit-card-like numbers, you might write: ```rust # #[macro_use] extern crate rocket; -extern crate time; +use rocket::time::Date; use rocket::form::{self, Error}; #[derive(FromForm)] @@ -966,10 +1066,10 @@ struct CreditCard { number: u64, #[field(validate = range(..9999))] cvv: u16, - expiration: time::Date, + expiration: Date, } -fn luhn<'v>(number: &u64, cvv: u16, exp: &time::Date) -> form::Result<'v, ()> { +fn luhn<'v>(number: &u64, cvv: u16, exp: &Date) -> form::Result<'v, ()> { # let valid = false; if !valid { Err(Error::validation("invalid credit card number"))?; @@ -983,6 +1083,42 @@ If a field's validation doesn't depend on other fields (validation is _local_), it is validated prior to those fields that do. For `CreditCard`, `cvv` and `expiration` will be validated prior to `number`. +### Wrapping Validators + +If a particular validation is applied in more than once place, prefer creating a +type that encapsulates and represents the validated value. For example, if your +application often validates `age` fields, consider creating a custom `Age` form +guard that always applies the validation: + +```rust +# use rocket::form::FromForm; + +#[derive(FromForm)] +#[field(validate = range(18..150))] +struct Age(u16); +``` + +This approach is also useful when a custom validator already exists in some +other form. For instance, the following example leverages [`try_with`] and an +existing `FromStr` implementation on a `Token` type to validate a string: + +```rust +# use rocket::form::FromForm; + +# impl FromStr for Token<'_> { +# type Err = &'static str; +# fn from_str(s: &str) -> Result { todo!() } +# } + +use std::str::FromStr; + +#[derive(FromForm)] +#[field(validate = try_with(|s| Token::from_str(s)))] +struct Token<'r>(&'r str); +``` + +[`try_with`]: rocket/form/validate/fn.try_with.html + ### Collections Rocket's form support allows your application to express _any_ structure with @@ -1596,7 +1732,7 @@ Query strings are URL-encoded forms that appear in the URL of a request. Query parameters are declared like path parameters but otherwise handled like regular URL-encoded form fields. The table below summarizes the analogy: -| Path Synax | Query Syntax | Path Type Bound | Query Type Bound | +| Path Syntax | Query Syntax | Path Type Bound | Query Type Bound | |-------------|--------------|------------------|------------------| | `` | `` | [`FromParam`] | [`FromForm`] | | `` | `` | [`FromSegments`] | [`FromForm`] | @@ -1686,15 +1822,17 @@ fn hello(name: &str, color: Vec, person: Person<'_>, other: Option } // A request with these query segments matches as above. -# rocket_guide_tests::client(routes![hello]).get("/?\ -color=reg&\ +# let status = rocket_guide_tests::client(routes![hello]).get("/?\ +name=George&\ +color=red&\ color=green&\ person.pet.name=Fi+Fo+Alex&\ color=green&\ -person.pet.age=1\ +person.pet.age=1&\ color=blue&\ extra=yes\ -# ").dispatch(); +# ").dispatch().status(); +# assert_eq!(status, rocket::http::Status::Ok); ``` Note that, like forms, parsing is field-ordering insensitive and lenient by @@ -1726,11 +1864,13 @@ fn user(id: usize, user: User<'_>) { } // A request with these query segments matches as above. -# rocket_guide_tests::client(routes![user]).get("/?\ +# let status = rocket_guide_tests::client(routes![user]).get("/?\ +hello&\ name=Bob+Smith&\ -id=1337\ +id=1337&\ active=yes\ -# ").dispatch(); +# ").dispatch().status(); +# assert_eq!(status, rocket::http::Status::Ok); ``` ## Error Catchers diff --git a/site/guide/5-responses.md b/site/guide/5-responses.md index fa7834d6aa..23b69e9119 100644 --- a/site/guide/5-responses.md +++ b/site/guide/5-responses.md @@ -50,7 +50,7 @@ fn new(id: usize) -> status::Accepted { Similarly, the types in the [`content` module](@api/rocket/response/content/) can be used to override the Content-Type of a response. For instance, to set the Content-Type of `&'static str` to JSON, as well as setting the status code to an -arbitrary one like `418 I'm a teapot`, combine [`content::Json`] with +arbitrary one like `418 I'm a teapot`, combine [`content::RawJson`] with [`status::Custom`]: ```rust @@ -59,16 +59,16 @@ use rocket::http::Status; use rocket::response::{content, status}; #[get("/")] -fn json() -> status::Custom> { - status::Custom(Status::ImATeapot, content::Json("{ \"hi\": \"world\" }")) +fn json() -> status::Custom> { + status::Custom(Status::ImATeapot, content::RawJson("{ \"hi\": \"world\" }")) } ``` ! warning: This is _not_ the same as [`serde::json::Json`]! The built-in `(Status, R)` and `(ContentType, R)` responders, where `R: -Responder`, are short-hands for the `status::Custom` and `content::Custom` -responders: +Responder`, also override the `Status` and `Content-Type` of responses, +respectively: ```rust # #[macro_use] extern crate rocket; @@ -144,7 +144,7 @@ generated by `Status` for these and other codes: | 100, [200, 205] | Empty with given status. | | All others. | Invalid. Errors to `500` catcher. | -[`Status`]: https://api.rocket.rs/master/rocket/http/struct.Status.html +[`Status`]: @api/rocket/http/struct.Status.html ## Custom Responders @@ -300,11 +300,10 @@ async fn files(file: PathBuf) -> Result> { Some of Rocket's best features are implemented through responders. Among these are: - * [`Content`] - Used to override the Content-Type of a response. * [`NamedFile`] - Streams a file to the client; automatically sets the Content-Type based on the file's extension. * [`Redirect`] - Redirects the client to a different URI. - * [`Stream`] - Streams a response to a client from an arbitrary `Read`er type. + * [`content`] - Contains types that override the Content-Type a response. * [`status`] - Contains types that override the status code of a response. * [`Flash`] - Sets a "flash" cookie that is removed when accessed. * [`Json`] - Automatically serializes values into JSON. @@ -312,20 +311,22 @@ are: * [`Template`] - Renders a dynamic template using handlebars or Tera. [`status`]: @api/rocket/response/status/ +[`content`]: @api/rocket/response/content/ [`response`]: @api/rocket/response/ -[`NamedFile`]: @api/rocket/response/struct.NamedFile.html -[`Content`]: @api/rocket/response/struct.Content.html +[`NamedFile`]: @api/rocket/fs/struct.NamedFile.html [`Redirect`]: @api/rocket/response/struct.Redirect.html -[`Stream`]: @api/rocket/response/struct.Stream.html [`Flash`]: @api/rocket/response/struct.Flash.html [`MsgPack`]: @api/rocket/serde/msgpack/struct.MsgPack.html [`Template`]: @api/rocket_dyn_templates/struct.Template.html ### Async Streams -The [`stream`] responders allow serving potentially infinite async [`Stream`]s. +The [`stream`] responders allow serving potentially infinite [async `Stream`]s. A stream can be created from any async `Stream` or `AsyncRead` type, or via -generator syntax using the [`stream!`] macro and its typed equivalents. +generator syntax using the [`stream!`] macro and its typed equivalents. Streams +are the building blocks for unidirectional real-time communication. For +instance, the [`chat` example] uses an [`EventStream`] to implement a real-time, +multi-room chat application using Server-Sent Events (SSE). The simplest version creates a [`ReaderStream`] from a single `AsyncRead` type. For example, to stream from a TCP connection, we might write: @@ -351,14 +352,14 @@ returns an infinite [`TextStream`] that produces one `"hello"` every second: ```rust # use rocket::get; -use rocket::tokio::time::{self, Duration}; +use rocket::tokio::time::{Duration, interval}; use rocket::response::stream::TextStream; /// Produce an infinite series of `"hello"`s, one per second. #[get("/infinite-hellos")] fn hello() -> TextStream![&'static str] { TextStream! { - let mut interval = time::interval(Duration::from_secs(1)); + let mut interval = interval(Duration::from_secs(1)); loop { yield "hello"; interval.tick().await; @@ -372,9 +373,11 @@ how to detect and handle graceful shutdown requests. [`stream`]: @api/rocket/response/stream/index.html [`stream!`]: @api/rocket/response/stream/macro.stream.html -[`Stream`]: https://docs.rs/futures/0.3/futures/stream/trait.Stream.html +[async `Stream`]: https://docs.rs/futures/0.3/futures/stream/trait.Stream.html [`ReaderStream`]: @api/rocket/response/stream/struct.ReaderStream.html [`TextStream`]: @api/rocket/response/stream/struct.TextStream.html +[`EventStream`]: @api/rocket/response/stream/struct.EventStream.html +[`chat` example]: @example/chat ### JSON @@ -392,6 +395,7 @@ write: use rocket::serde::{Serialize, json::Json}; #[derive(Serialize)] +#[serde(crate = "rocket::serde")] struct Task { /* .. */ } #[get("/todo")] @@ -438,6 +442,24 @@ a template and a context to render the template with. The context can be any type that implements `Serialize` and serializes into an `Object` value, such as structs, `HashMaps`, and others. +You can also use [`context!`] to create ad-hoc templating contexts without +defining a new type: + +```rust +# #[macro_use] extern crate rocket; +# #[macro_use] extern crate rocket_dyn_templates; +# fn main() {} + +use rocket_dyn_templates::Template; + +#[get("/")] +fn index() -> Template { + Template::render("index", context! { + foo: 123, + }) +} +``` + For a template to be renderable, it must first be registered. The `Template` fairing automatically registers all discoverable templates when attached. The [Fairings](../fairings) sections of the guide provides more information on @@ -469,6 +491,8 @@ used. the name `"index"` in templates, i.e, `{% extends "index" %}` or `{% extends "base" %}` for `base.html.tera`. +[`context`]: @api/rocket_dyn_templates/macro.context.html + ### Live Reloading When your application is compiled in `debug` mode (without the `--release` flag @@ -482,7 +506,7 @@ including how to customize a template engine to add custom helpers and filters. The [templating example](@example/templating) uses both Tera and Handlebars templating to implement the same application. -[configurable]: ../configuration/#extras +[configurable]: ../configuration ## Typed URIs @@ -646,12 +670,12 @@ generated. ```rust # #[macro_use] extern crate rocket; -# #[get("//?")] -# fn person(id: Option, name: &str, age: Option) { /* .. */ } +#[get("//?")] +fn person(id: Option, name: &str, age: Option) { /* .. */ } -/// Note that `id` is `Option` in the route, but `id` in `uri!` _cannot_ -/// be an `Option`. `age`, on the other hand, _must_ be an `Option` (or `Result` -/// or `_`) as its in the query part and is allowed to be ignored. +// Note that `id` is `Option` in the route, but `id` in `uri!` _cannot_ +// be an `Option`. `age`, on the other hand, _must_ be an `Option` (or `Result` +// or `_`) as its in the query part and is allowed to be ignored. let mike = uri!(person(id = 101, name = "Mike", age = Some(28))); assert_eq!(mike.to_string(), "/101/Mike?age=28"); ``` @@ -713,14 +737,14 @@ uri!(person(id = 100, details = "a/b/c")); See the [`FromUriParam`] documentation for further details. [`Origin`]: @api/rocket/http/uri/struct.Origin.html -[`Part`]: @api/rocket/http/uri/trait.Part.html +[`Part`]: @api/rocket/http/uri/fmt/trait.Part.html [`Uri`]: @api/rocket/http/uri/enum.Uri.html [`Redirect::to()`]: @api/rocket/response/struct.Redirect.html#method.to [`uri!`]: @api/rocket/macro.uri.html -[`UriDisplay`]: @api/rocket/http/uri/trait.UriDisplay.html -[`FromUriParam`]: @api/rocket/http/uri/trait.FromUriParam.html -[`Path`]: @api/rocket/http/uri/enum.Path.html -[`Query`]: @api/rocket/http/uri/enum.Query.html -[`Ignorable`]: @api/rocket/http/uri/trait.Ignorable.html +[`UriDisplay`]: @api/rocket/http/uri/fmt/trait.UriDisplay.html +[`FromUriParam`]: @api/rocket/http/uri/fmt/trait.FromUriParam.html +[`Path`]: @api/rocket/http/uri/fmt/enum.Path.html +[`Query`]: @api/rocket/http/uri/fmt/enum.Query.html +[`Ignorable`]: @api/rocket/http/uri/fmt/trait.Ignorable.html [`UriDisplayPath`]: @api/rocket/derive.UriDisplayPath.html [`UriDisplayQuery`]: @api/rocket/derive.UriDisplayQuery.html diff --git a/site/guide/6-state.md b/site/guide/6-state.md index ae04e72bae..fb16e51635 100644 --- a/site/guide/6-state.md +++ b/site/guide/6-state.md @@ -113,7 +113,7 @@ example on GitHub](@example/state) and learn more about the [`manage` method](@api/rocket/struct.Rocket.html#method.manage) and [`State` type](@api/rocket/struct.State.html) in the API docs. -# Within Guards +### Within Guards Because `State` is itself a request guard, managed state can be retrieved from another request guard's implementation using either [`Request::guard()`] or @@ -216,147 +216,108 @@ request-local state to implement request timing. ## Databases -Rocket includes built-in, ORM-agnostic support for databases. In particular, -Rocket provides a procedural macro that allows you to easily connect your Rocket -application to databases through connection pools. A _database connection pool_ -is a data structure that maintains active database connections for later use in -the application. This implementation of connection pooling support is based on -[`r2d2`] and exposes connections through request guards. Databases are -individually configured through Rocket's regular configuration mechanisms: a -`Rocket.toml` file, environment variables, or procedurally. - -Connecting your Rocket application to a database using this library occurs in -three simple steps: - - 1. Configure the databases in `Rocket.toml`. - 2. Associate a request guard type and fairing with each database. - 3. Use the request guard to retrieve and use a connection in a handler. - -Presently, Rocket provides built-in support for the following databases: - - -| Kind | Driver | Version | `Poolable` Type | Feature | -|----------|-----------------------|-----------|--------------------------------|------------------------| -| MySQL | [Diesel] | `1` | [`diesel::MysqlConnection`] | `diesel_mysql_pool` | -| Postgres | [Diesel] | `1` | [`diesel::PgConnection`] | `diesel_postgres_pool` | -| Postgres | [Rust-Postgres] | `0.19` | [`postgres::Client`] | `postgres_pool` | -| Sqlite | [Diesel] | `1` | [`diesel::SqliteConnection`] | `diesel_sqlite_pool` | -| Sqlite | [`Rusqlite`] | `0.24` | [`rusqlite::Connection`] | `sqlite_pool` | -| Memcache | [`memcache`] | `0.15` | [`memcache::Client`] | `memcache_pool` | - -[`r2d2`]: https://crates.io/crates/r2d2 -[Diesel]: https://diesel.rs -[`rusqlite::Connection`]: https://docs.rs/rusqlite/0.23.0/rusqlite/struct.Connection.html -[`diesel::SqliteConnection`]: https://docs.diesel.rs/diesel/prelude/struct.SqliteConnection.html -[`postgres::Client`]: https://docs.rs/postgres/0.19/postgres/struct.Client.html -[`diesel::PgConnection`]: https://docs.diesel.rs/diesel/pg/struct.PgConnection.html -[`diesel::MysqlConnection`]: https://docs.diesel.rs/diesel/mysql/struct.MysqlConnection.html -[`Rusqlite`]: https://github.com/jgallagher/rusqlite -[Rust-Postgres]: https://github.com/sfackler/rust-postgres -[`diesel::PgConnection`]: https://docs.diesel.rs/diesel/pg/struct.PgConnection.html -[`memcache`]: https://github.com/aisk/rust-memcache -[`memcache::Client`]: https://docs.rs/memcache/0.15/memcache/struct.Client.html - -### Usage - -To connect your Rocket application to a given database, first identify the -"Kind" and "Driver" in the table that matches your environment. The feature -corresponding to your database type must be enabled. This is the feature -identified in the "Feature" column. For instance, for Diesel-based SQLite -databases, you'd write in `Cargo.toml`: +Rocket includes built-in, ORM-agnostic support for databases via +[`rocket_db_pools`]. The library simplifies accessing one or more databases via +connection pools: data structures that maintain active database connections for +use in the application. Database configuration occurs via Rocket's regular +[configuration](../configuration) mechanisms. + +Connecting your Rocket application to a database using `rocket_db_pools` happens +in three simple steps: + +1. Choose your database(s) from the [supported database driver list]. Add + `rocket_db_pools` as a dependency in `Cargo.toml` with respective database + driver feature(s) enabled: + + ```toml + [dependencies.rocket_db_pools] + version = "0.1.0-rc.2" + features = ["sqlx_sqlite"] + ``` + +2. Choose a name for your database, here `sqlite_logs`. [Configure] _at least_ + a URL for the database under `databases.$name` (here, in `Rocket.toml`), + where `$name` is your choice of database name: + + ```toml + [default.databases.sqlite_logs] + url = "/path/to/database.sqlite" + ``` + +3. [Derive `Database`] for a unit `Type` (`Logs` here) which wraps the selected + driver's `Pool` type from the [supported database driver list]. Decorated the + struct with `#[database("$name")]` with the `$name` from `2.`. Attach + `$Type::init()` to your application's `Rocket` to initialize the database + pool and use [`Connection<$Type>`] as a request guard to retrieve an active + database connection: + + ```rust + #[macro_use] extern crate rocket; + + use rocket_db_pools::{Database, Connection}; + use rocket_db_pools::sqlx::{self, Row}; + + #[derive(Database)] + #[database("sqlite_logs")] + struct Logs(sqlx::SqlitePool); + + #[get("/")] + async fn read(mut db: Connection, id: i64) -> Option { + sqlx::query("SELECT content FROM logs WHERE id = ?").bind(id) + .fetch_one(&mut *db).await + .and_then(|r| Ok(r.try_get(0)?)) + .ok() + } + + #[launch] + fn rocket() -> _ { + rocket::build().attach(Logs::init()).mount("/", routes![read]) + } + ``` + +For complete usage details, see [`rocket_db_pools`]. + +[`rocket_db_pools`]: @api/rocket_db_pools/index.html +[supported database driver list]: @api/rocket_db_pools/index.html#supported-drivers +[database driver features]: @api/rocket_db_pools/index.html#supported-drivers +[`Pool`]: @api/rocket_db_pools/index.html#supported-drivers +[Configure]: @api/rocket_db_pools/index.html#configuration +[Derive `Database`]: @api/rocket_db_pools/derive.Database.html +[`Connection<$Type>`]: @api/rocket_db_pools/struct.Connection.html + +### Driver Features + +Only the minimal features for each driver crate are enabled by +`rocket_db_pools`. To use additional driver functionality exposed via its +crate's features, you'll need to depend on the crate directly with those +features enabled in `Cargo.toml`: ```toml -[dependencies.rocket_sync_db_pools] -version = "0.1.0-dev" +[dependencies.sqlx] +version = "0.6" default-features = false -features = ["diesel_sqlite_pool"] -``` - -Then, in `Rocket.toml` or the equivalent via environment variables, configure -the URL for the database in the `databases` table: - -```toml -[global.databases] -sqlite_logs = { url = "/path/to/database.sqlite" } -``` - -In your application's source code, create a unit-like struct with one internal -type. This type should be the type listed in the "`Poolable` Type" column. Then -decorate the type with the `#[database]` attribute, providing the name of the -database that you configured in the previous step as the only parameter. You -will need to either add `#[macro_use] extern crate rocket_sync_db_pools` to the -crate root or have a `use rocket_sync_db_pools::database` in scope, otherwise -the `database` attribute will not be available. Finally, attach the fairing -returned by `YourType::fairing()`, which was generated by the `#[database]` -attribute: - -```rust -# #[macro_use] extern crate rocket; - -use rocket_sync_db_pools::{diesel, database}; - -#[database("sqlite_logs")] -struct LogsDbConn(diesel::SqliteConnection); - -#[launch] -fn rocket() -> _ { - rocket::build().attach(LogsDbConn::fairing()) -} -``` - -That's it! Whenever a connection to the database is needed, use your type as a -request guard. The database can be accessed by calling the `run` method: +features = ["macros", "offline", "migrate"] -```rust -# #[macro_use] extern crate rocket; -# fn main() {} - -# use rocket_sync_db_pools::{diesel, database}; - -# #[database("sqlite_logs")] -# struct LogsDbConn(diesel::SqliteConnection); -# type Logs = (); - -#[get("/logs/")] -async fn get_logs(conn: LogsDbConn, id: usize) -> Logs { - # /* - conn.run(|c| logs::filter(id.eq(log_id)).load(c)).await - # */ -} +[dependencies.rocket_db_pools] +version = "0.1.0-rc.2" +features = ["sqlx_sqlite"] ``` -! note The above examples uses [Diesel] with some fictional `Logs` type. - - The example above contains the use of a `Logs` type that is application - specific and not built into Rocket. It also uses [Diesel]'s query-building - syntax. Rocket does not provide an ORM. It is up to you to decide how to model - your application's data. +### Synchronous ORMs - +While [`rocket_db_pools`] provides support for `async` ORMs and should thus be +the preferred solution, Rocket also provides support for synchronous, blocking +ORMs like [Diesel] via the [`rocket_sync_db_pools`] library, which you may wish +to explore. Usage is similar, but not identical, to `rocket_db_pools`. See the +crate docs for complete usage details. -! note: Rocket wraps synchronous databases in an `async` API. - - The database engines supported by `#[database]` are *synchronous*. Normally, - using such a database would block the thread of execution. To prevent this, - the `run()` function automatically uses a thread pool so that database access - does not interfere with other in-flight requests. See - [Multitasking](../overview/#multitasking) for more information on why this is - necessary. - -If your application uses features of a database engine that are not available -by default, for example support for `chrono` or `uuid`, you may enable those -features by adding them in `Cargo.toml` like so: - -```toml -[dependencies] -postgres = { version = "0.15", features = ["with-chrono"] } -``` +[`rocket_sync_db_pools`]: @api/rocket_sync_db_pools/index.html +[diesel]: https://diesel.rs/ -For more on Rocket's sanctioned database support, see the -[`rocket_sync_db_pools`] library documentation. For examples of CRUD-like "blog" -JSON APIs backed by a SQLite database driven by each of `sqlx`, `diesel`, and -`rusqlite` with migrations run automatically for the former two drivers and -Rocket's database support use for the latter two drivers, see the [databases -example](@example/databases). +### Examples -[`rocket_sync_db_pools`]: @api/rocket_sync_db_pools/index.html +For examples of CRUD-like "blog" JSON APIs backed by a SQLite database driven by +each of `sqlx`, `diesel`, and `rusqlite`, with migrations run automatically for +the former two drivers, see the [databases example](@example/databases). The +`sqlx` example uses `rocket_db_pools` while the `diesel` and `rusqlite` examples +use `rocket_sync_db_pools`. diff --git a/site/guide/7-fairings.md b/site/guide/7-fairings.md index 55e6dbd57d..f36e47d19d 100644 --- a/site/guide/7-fairings.md +++ b/site/guide/7-fairings.md @@ -32,7 +32,7 @@ that can be used to solve problems in a clean, composable, and robust manner. effected through fairings. You should **_not_** use a fairing to implement authentication or authorization (preferring to use a [request guard] instead) _unless_ the authentication or authorization applies to all or the - overwhelming majority application. On the other hand, you _should_ use a + overwhelming majority of the application. On the other hand, you _should_ use a fairing to record timing and usage statistics or to enforce global security policies. @@ -72,13 +72,13 @@ order in which fairings are attached may be significant. ### Callbacks -There are four events for which Rocket issues fairing callbacks. Each of these -events is described below: +There are five events for which Rocket issues fairing callbacks. Each of these +events is breifly described below and in details in the [`Fairing`] trait docs: * **Ignite (`on_ignite`)** An ignite callback is called during [ignition] An ignite callback can - arbitrarily modify the `Rocket` instance being build. They are are commonly + arbitrarily modify the `Rocket` instance being built. They are commonly used to parse and validate configuration values, aborting on bad configurations, and inserting the parsed value into managed state for later retrieval. @@ -106,7 +106,16 @@ events is described below: example, response fairings can also be used to inject headers into all outgoing responses. + * **Shutdown (`on_shutdown`)** + + A shutdown callback is called when [shutdown is triggered]. At this point, + graceful shutdown has commenced but not completed; no new requests are + accepted but the application may still be actively serving existing + requests. All registered shutdown fairings are run concurrently; resolution + of all fairings is awaited before resuming shutdown. + [ignition]: @api/rocket/struct.Rocket.html#method.ignite +[shutdown is triggered]: @api/rocket/config/struct.Shutdown.html#triggers ## Implementing @@ -115,8 +124,8 @@ Recall that a fairing is any type that implements the [`Fairing`] trait. A [`Info`] structure. This structure is used by Rocket to assign a name to the fairing and determine the set of callbacks the fairing is registering for. A `Fairing` can implement any of the available callbacks: [`on_ignite`], -[`on_liftoff`], [`on_request`], and [`on_response`]. Each callback has a default -implementation that does absolutely nothing. +[`on_liftoff`], [`on_request`], [`on_response`], and [`on_shutdown`]. Each +callback has a default implementation that does absolutely nothing. [`Info`]: @api/rocket/fairing/struct.Info.html [`info`]: @api/rocket/fairing/trait.Fairing.html#tymethod.info @@ -124,6 +133,7 @@ implementation that does absolutely nothing. [`on_liftoff`]: @api/rocket/fairing/trait.Fairing.html#method.on_liftoff [`on_request`]: @api/rocket/fairing/trait.Fairing.html#method.on_request [`on_response`]: @api/rocket/fairing/trait.Fairing.html#method.on_response +[`on_shutdown`]: @api/rocket/fairing/trait.Fairing.html#method.on_shutdown ### Requirements @@ -171,7 +181,7 @@ impl Fairing for Counter { } // Increment the counter for `GET` and `POST` requests. - async fn on_request(&self, request: &mut Request<'_>, _: &mut Data) { + async fn on_request(&self, request: &mut Request<'_>, _: &mut Data<'_>) { match request.method() { Method::Get => self.get.fetch_add(1, Ordering::Relaxed), Method::Post => self.post.fetch_add(1, Ordering::Relaxed), @@ -204,17 +214,16 @@ documentation](@api/rocket/fairing/trait.Fairing.html#example). ## Ad-Hoc Fairings -For simple occasions, implementing the `Fairing` trait can be cumbersome. This -is why Rocket provides the [`AdHoc`] type, which creates a fairing from a simple +For simpler cases, implementing the `Fairing` trait can be cumbersome. This is +why Rocket provides the [`AdHoc`] type, which creates a fairing from a simple function or closure. Using the `AdHoc` type is easy: simply call the -`on_ignite`, `on_liftoff`, `on_request`, or `on_response` constructors on -`AdHoc` to create an `AdHoc` structure from a function or closure. +`on_ignite`, `on_liftoff`, `on_request`, `on_response`, or `on_shutdown` +constructors on `AdHoc` to create a fairing from a function or closure. As an example, the code below creates a `Rocket` instance with two attached -ad-hoc fairings. The first, a liftoff fairing named "Liftoff Printer", simply -prints a message indicating that the application has launched. The second named -"Put Rewriter", a request fairing, rewrites the method of all requests to be -`PUT`. +ad-hoc fairings. The first, a liftoff fairing named "Liftoff Printer", prints a +message indicating that the application has launched. The second named "Put +Rewriter", a request fairing, rewrites the method of all requests to be `PUT`. ```rust use rocket::fairing::AdHoc; @@ -226,6 +235,9 @@ rocket::build() }))) .attach(AdHoc::on_request("Put Rewriter", |req, _| Box::pin(async move { req.set_method(Method::Put); + }))) + .attach(AdHoc::on_shutdown("Shutdown Printer", |_| Box::pin(async move { + println!("...shutdown has commenced!"); }))); ``` diff --git a/site/guide/8-testing.md b/site/guide/8-testing.md index ce18159944..2b62ea2d03 100644 --- a/site/guide/8-testing.md +++ b/site/guide/8-testing.md @@ -111,7 +111,7 @@ use rocket::http::{ContentType, Status}; # let rocket = rocket::build().mount("/", routes![hello]); # let client = Client::debug(rocket).expect("valid rocket instance"); -let mut response = client.get("/").dispatch(); +let mut response = client.get(uri!(hello)).dispatch(); assert_eq!(response.status(), Status::Ok); assert_eq!(response.content_type(), Some(ContentType::Plain)); @@ -187,13 +187,18 @@ Then, we create a new `GET /` request and dispatch it, getting back our application's response: ```rust +# use rocket::uri; # #[rocket::launch] # fn rocket() -> _ { # rocket::build().configure(rocket::Config::debug_default()) # } + +# #[rocket::get("/")] +# fn hello() -> &'static str { "Hello, world!" } + # use rocket::local::blocking::Client; # let client = Client::tracked(rocket()).expect("valid rocket instance"); -let mut response = client.get("/").dispatch(); +let mut response = client.get(uri!(hello)).dispatch(); ``` Finally, we ensure that the response contains the information we expect it to. @@ -215,7 +220,7 @@ use rocket::http::{ContentType, Status}; # # let rocket = rocket::build().mount("/", routes![hello]); # let client = Client::debug(rocket).expect("valid rocket instance"); -# let mut response = client.get("/").dispatch(); +# let mut response = client.get(uri!(hello)).dispatch(); assert_eq!(response.status(), Status::Ok); assert_eq!(response.into_string(), Some("Hello, world!".into())); @@ -256,7 +261,7 @@ mod test { let client = Client::tracked(rocket()).expect("valid rocket instance"); # */ # let client = Client::debug(rocket()).expect("valid rocket instance"); - let mut response = client.get("/").dispatch(); + let mut response = client.get(uri!(super::hello)).dispatch(); assert_eq!(response.status(), Status::Ok); assert_eq!(response.into_string().unwrap(), "Hello, world!"); } diff --git a/site/guide/9-configuration.md b/site/guide/9-configuration.md index d0ee047e69..e8fdc6d3a1 100644 --- a/site/guide/9-configuration.md +++ b/site/guide/9-configuration.md @@ -17,38 +17,41 @@ is configured with. This means that no matter which configuration provider Rocket is asked to use, it must be able to read the following configuration values: -| key | kind | description | debug/release default | -|----------------|-----------------|-------------------------------------------------|-----------------------| -| `address` | `IpAddr` | IP address to serve on | `127.0.0.1` | -| `port` | `u16` | Port to serve on. | `8000` | -| `workers` | `usize` | Number of threads to use for executing futures. | cpu core count | -| `keep_alive` | `u32` | Keep-alive timeout seconds; disabled when `0`. | `5` | -| `log_level` | `LogLevel` | Max level to log. (off/normal/debug/critical) | `normal`/`critical` | -| `cli_colors` | `bool` | Whether to use colors and emoji when logging. | `true` | -| `secret_key` | `SecretKey` | Secret key for signing and encrypting values. | `None` | -| `tls` | `TlsConfig` | TLS configuration, if any. | `None` | -| `tls.key` | `&[u8]`/`&Path` | Path/bytes to DER-encoded ASN.1 PKCS#1/#8 key. | | -| `tls.certs` | `&[u8]`/`&Path` | Path/bytes to DER-encoded X.509 TLS cert chain. | | -| `limits` | `Limits` | Streaming read size limits. | [`Limits::default()`] | -| `limits.$name` | `&str`/`uint` | Read limit for `$name`. | forms = "32KiB" | -| `ctrlc` | `bool` | Whether `ctrl-c` initiates a server shutdown. | `true` | +| key | kind | description | debug/release default | +|-----------------|-------------------|-------------------------------------------------|-------------------------| +| `address` | `IpAddr` | IP address to serve on | `127.0.0.1` | +| `port` | `u16` | Port to serve on. | `8000` | +| `workers`* | `usize` | Number of threads to use for executing futures. | cpu core count | +| `max_blocking`* | `usize` | Limit on threads to start for blocking tasks. | `512` | +| `ident` | `string`, `false` | If and how to identify via the `Server` header. | `"Rocket"` | +| `keep_alive` | `u32` | Keep-alive timeout seconds; disabled when `0`. | `5` | +| `log_level` | [`LogLevel`] | Max level to log. (off/normal/debug/critical) | `normal`/`critical` | +| `cli_colors` | `bool` | Whether to use colors and emoji when logging. | `true` | +| `secret_key` | [`SecretKey`] | Secret key for signing and encrypting values. | `None` | +| `tls` | [`TlsConfig`] | TLS configuration, if any. | `None` | +| `limits` | [`Limits`] | Streaming read size limits. | [`Limits::default()`] | +| `limits.$name` | `&str`/`uint` | Read limit for `$name`. | form = "32KiB" | +| `ctrlc` | `bool` | Whether `ctrl-c` initiates a server shutdown. | `true` | +| `shutdown`* | [`Shutdown`] | Graceful shutdown configuration. | [`Shutdown::default()`] | + +* Note: the `workers`, `max_blocking`, and `shutdown.force` configuration +parameters are only read from the [default provider](#default-provider). ### Profiles Configurations can be arbitrarily namespaced by [`Profile`]s. Rocket's [`Config`] and [`Config::figment()`] providers automatically set the configuration profile to "debug" when compiled in "debug" mode and "release" -when compiled in release mode. With the exception of `log_level`, which changes -from `normal` in debug to `critical` in release, all of the default -configuration values are the same in all profiles. What's more, all -configuration values _have_ defaults, so no configuration needs to be supplied -to get an application going. +when compiled in release mode, but you can arbitrarily name and set profiles to +your desire. For example, with the [default provider](#default-provider), you +can set the selected profile via `ROCKET_PROFILE`. This results in Rocket +preferring the values in the `ROCKET_PROFILE` profile. In addition to any profiles you declare, there are two meta-profiles, `default` and `global`, which can be used to provide values that apply to _all_ profiles. Values provided in a `default` profile are used as fall-back values when the -selected profile doesn't contain a requested values, while values in the -`global` profile supplant any values with the same name in any profile. +selected profile doesn't contain a requested value, while values in the `global` +profile supplant any values with the same name in any profile. [`Provider`]: @figment/trait.Provider.html [`Profile`]: @figment/struct.Profile.html @@ -56,91 +59,38 @@ selected profile doesn't contain a requested values, while values in the [`Config::figment()`]: @api/rocket/struct.Config.html#method.figment [`Toml`]: @figment/providers/struct.Toml.html [`Json`]: @figment/providers/struct.Json.html -[`Figment`]: @api/rocket/struct.Figment.html +[`Figment`]: @figment/struct.Figment.html [`Deserialize`]: @api/rocket/serde/trait.Deserialize.html +[`LogLevel`]: @api/rocket/config/enum.LogLevel.html +[`Limits`]: @api/rocket/data/struct.Limits.html [`Limits::default()`]: @api/rocket/data/struct.Limits.html#impl-Default - -### Secret Key - -The `secret_key` parameter configures a cryptographic key to use when encrypting -application values. In particular, the key is used to encrypt [private cookies], -which are available only when the `secrets` crate feature is enabled. - -When compiled in debug mode, a fresh key is generated automatically. In release -mode, Rocket requires you to set a secret key if the `secrets` feature is -enabled. Failure to do so results in a hard error at launch time. The value of -the parameter may either be a 256-bit base64 or hex string or a slice of 32 -bytes. - -[private cookies]: ../requests/#private-cookies - -### Limits - -The `limits` parameter configures the maximum amount of data Rocket will accept -for a given data type. The value is expected to be a dictionary table where each -key corresponds to a data type and each value corresponds to the maximum size in -bytes Rocket should accept for that type. Rocket can parse both integers -(`32768`) or SI unit based strings (`"32KiB"`) as limits. - -By default, Rocket specifies a `32 KiB` limit for incoming forms. Since Rocket -requires specifying a read limit whenever data is read, external data guards may -also choose to have a configure limit via the `limits` parameter. The -[`Json`](@api/rocket/serde/json/struct.Json.html) type, for instance, uses the -`limits.json` parameter. - -### TLS - -Rocket includes built-in, native support for TLS >= 1.2 (Transport Layer -Security). In order for TLS support to be enabled, Rocket must be compiled with -the `"tls"` feature: - -```toml -[dependencies] -rocket = { version = "0.5.0-dev", features = ["tls"] } -``` - -TLS is configured through the `tls` configuration parameter. The value of `tls` -is a dictionary with two keys: `certs` and `key`, described in the table above. -Each key's value may be either a path to a file or raw bytes corresponding to -the expected value. When a path is configured in a file source, such as -`Rocket.toml`, relative paths are interpreted as being relative to the source -file's directory. - -! warning: Rocket's built-in TLS implements only TLS 1.2 and 1.3. As such, it - may not be suitable for production use. - -### Workers - -The `workers` parameter sets the number of threads used for parallel task -execution; there is no limit to the number of concurrent tasks. Due to a -limitation in upstream async executers, unlike other values, the `workers` -configuration value cannot be reconfigured or be configured from sources other -than those provided by [`Config::figment()`], detailed below. In other words, -only the values set by the `ROCKET_WORKERS` environment variable or in the -`workers` property of `Rocket.toml` will be considered - all other `workers` -values are ignored. +[`SecretKey`]: @api/rocket/config/struct.SecretKey.html +[`TlsConfig`]: @api/rocket/config/struct.TlsConfig.html +[`Shutdown`]: @api/rocket/config/struct.Shutdown.html +[`Shutdown::default()`]: @api/rocket/config/struct.Shutdown.html#fields ## Default Provider Rocket's default configuration provider is [`Config::figment()`]; this is the provider that's used when calling [`rocket::build()`]. -The default figment merges, at a per-key level, and reads from the following -sources, in ascending priority order: +The default figment reads from and merges, at a per-key level, the following +sources in ascending priority order: - 1. [`Config::default()`] - which provides default values for all parameters. + 1. [`Config::default()`], which provides default values for all parameters. 2. `Rocket.toml` _or_ TOML file path in `ROCKET_CONFIG` environment variable. 3. `ROCKET_` prefixed environment variables. The selected profile is the value of the `ROCKET_PROFILE` environment variable, or if it is not set, "debug" when compiled in debug mode and "release" when -compiled in release mode. +compiled in release mode. With the exception of `log_level`, which changes from +`normal` in debug to `critical` in release, all of the default configuration +values are the same in all profiles. What's more, all configuration values +_have_ defaults, so no configuration is needed to get started. -As a result, without any effort, Rocket's server can be configured via a -`Rocket.toml` file and/or via environment variables, the latter of which take -precedence over the former. Note that neither the file nor any environment -variables need to be present as [`Config::default()`] is a complete -configuration source. +As a result of `Config::figment()`, without any effort, Rocket can be configured +via a `Rocket.toml` file and/or via environment variables, the latter of which +take precedence over the former. [`Config::default()`]: @api/rocket/struct.Config.html#method.default @@ -150,7 +100,7 @@ Rocket searches for `Rocket.toml` or the filename in a `ROCKET_CONFIG` environment variable starting at the current working directory. If it is not found, the parent directory, its parent, and so on, are searched until the file is found or the root is reached. If the path set in `ROCKET_CONFIG` is absolute, -no such search occurs, and the set path is used directly. +no such search occurs and the set path is used directly. The file is assumed to be _nested_, so each top-level key declares a profile and its values the value for the profile. The following is an example of what such a @@ -160,12 +110,12 @@ file might look like: ## defaults for _all_ profiles [default] address = "0.0.0.0" -limits = { forms = "64 kB", json = "1 MiB" } +limits = { form = "64 kB", json = "1 MiB" } ## set only when compiled in debug mode, i.e, `cargo build` [debug] port = 8000 -## only the `json` key from `default` will be overridden; `forms` will remain +## only the `json` key from `default` will be overridden; `form` will remain limits = { json = "10MiB" } ## set only when the `nyc` profile is selected @@ -179,6 +129,42 @@ port = 9999 secret_key = "hPRYyVRiMyxpw5sBB1XeCMN1kFsDCqKvBi2QJxBVHQk=" ``` +The following is a `Rocket.toml` file with all configuration options set for +demonstration purposes. You **do not** and _should not_ set a value for +configuration options needlessly, preferring to use the default value when +sensible. + +```toml +[default] +address = "127.0.0.1" +port = 8000 +workers = 16 +max_blocking = 512 +keep_alive = 5 +ident = "Rocket" +log_level = "normal" +temp_dir = "/tmp" +cli_colors = true +## NOTE: Don't (!) use this key! Generate your own! +secret_key = "hPRYyVRiMyxpw5sBB1XeCMN1kFsDCqKvBi2QJxBVHQk=" + +[default.limits] +form = "64 kB" +json = "1 MiB" +msgpack = "2 MiB" +"file/jpg" = "5 MiB" + +[default.tls] +certs = "path/to/cert-chain.pem" +key = "path/to/key.pem" + +[default.shutdown] +ctrlc = true +signals = ["term", "hup"] +grace = 5 +mercy = 5 +``` + ### Environment Variables Rocket reads all environment variable names prefixed with `ROCKET_` using the @@ -188,15 +174,207 @@ in `Rocket.toml`. Values are parsed as loose form of TOML syntax. Consider the following examples: ```sh -ROCKET_INTEGER=1 ROCKET_FLOAT=3.14 -ROCKET_STRING=Hello -ROCKET_STRING="Hello" -ROCKET_BOOL=true ROCKET_ARRAY=[1,"b",3.14] -ROCKET_DICT={key="abc",val=123} +ROCKET_STRING=Hello +ROCKET_STRING="Hello There" + +ROCKET_KEEP_ALIVE=1 +ROCKET_IDENT=Rocket +ROCKET_IDENT="Hello Rocket" +ROCKET_IDENT=false +ROCKET_TLS={certs="abc",key="foo/bar"} +ROCKET_LIMITS={form="64 KiB"} +``` + +## Configuration Parameters + +### Secret Key + +The `secret_key` parameter configures a cryptographic key to use when encrypting +application values. In particular, the key is used to encrypt [private cookies], +which are available only when the `secrets` crate feature is enabled. + +Generating a string suitable for use as a `secret_key` configuration value is +usually done through tools like `openssl`. Using `openssl`, a 256-bit base64 key +can be generated with the command `openssl rand -base64 32`. + +When compiled in debug mode, a fresh key is generated automatically. In release +mode, Rocket requires you to set a secret key if the `secrets` feature is +enabled. Failure to do so results in a hard error at launch time. The value of +the parameter may either be a 256-bit base64 or hex string or a slice of 32 +bytes. + +[private cookies]: ../requests/#private-cookies + +### Limits + +The `limits` parameter configures the maximum amount of data Rocket will accept +for a given data type. The value is expected to be a dictionary table where each +key corresponds to a data type and each value corresponds to the maximum size in +bytes Rocket should accept for that type. Rocket can parse both integers +(`32768`) or SI unit based strings (`"32KiB"`) as limits. + +By default, Rocket specifies a `32 KiB` limit for incoming forms. Since Rocket +requires specifying a read limit whenever data is read, external data guards may +also choose to have a configure limit via the `limits` parameter. The +[`Json`](@api/rocket/serde/json/struct.Json.html) type, for instance, uses the +`limits.json` parameter. + +### TLS + +Rocket includes built-in, native support for TLS >= 1.2 (Transport Layer +Security). To enable TLS support: + + 1. Enable the `tls` crate feature in `Cargo.toml`: + + ```toml,ignore + [dependencies] + rocket = { version = "0.5.0-rc.2", features = ["tls"] } + ``` + + 2. Configure a TLS certificate chain and private key via the `tls.key` and + `tls.certs` configuration parameters. With the default provider, this can + be done via `Rocket.toml` as: + + ```toml,ignore + [default.tls] + key = "path/to/key.pem" # Path or bytes to DER-encoded ASN.1 PKCS#1/#8 key. + certs = "path/to/certs.pem" # Path or bytes to DER-encoded X.509 TLS cert chain. + ``` + +The `tls` parameter is expected to be a dictionary that deserializes into a +[`TlsConfig`] structure: + +| key | required | type | +|------------------------------|-----------|-------------------------------------------------------| +| `key` | **_yes_** | Path or bytes to DER-encoded ASN.1 PKCS#1/#8 key. | +| `certs` | **_yes_** | Path or bytes to DER-encoded X.509 TLS cert chain. | +| `ciphers` | no | Array of [`CipherSuite`]s to enable. | +| `prefer_server_cipher_order` | no | Boolean for whether to [prefer server cipher suites]. | +| `mutual` | no | A map with [mutual TLS] configuration. | + +[`CipherSuite`]: @api/rocket/config/enum.CipherSuite.html +[prefer server cipher suites]: @api/rocket/config/struct.TlsConfig.html#method.with_preferred_server_cipher_order +[mutual TLS]: #mutual-tls + +When specified via TOML or other serialized formats, each [`CipherSuite`] is +written as a string representation of the respective variant. For example, +`CipherSuite::TLS_AES_256_GCM_SHA384` is `"TLS_AES_256_GCM_SHA384"`. In TOML, +the defaults (with an arbitrary `certs` and `key`) are written: + +```toml +[default.tls] +certs = "/ssl/cert.pem" +key = "/ssl/key.pem" +prefer_server_cipher_order = false +ciphers = [ + "TLS_CHACHA20_POLY1305_SHA256", + "TLS_AES_256_GCM_SHA384", + "TLS_AES_128_GCM_SHA256", + "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256", + "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256", + "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", + "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", + "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", + "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", +] +``` + +### Mutual TLS + +Rocket supports mutual TLS client authentication. Configuration works in concert +with the [`mtls`] module, which provides a request guard to validate, verify, +and retrieve client certificates in routes. + +By default, mutual TLS is disabled and client certificates are not required, +validated or verified. To enable mutual TLS, the `mtls` feature must be +enabled and support configured via the `tls.mutual` config parameter: + + 1. Enable the `mtls` crate feature in `Cargo.toml`: + + ```toml,ignore + [dependencies] + rocket = { version = "0.5.0-rc.2", features = ["mtls"] } + ``` + + This implicitly enables the `tls` feature. + + 2. Configure a CA certificate chain via the `tls.mutual.ca_certs` + configuration parameter. With the default provider, this can be done via + `Rocket.toml` as: + + ```toml,ignore + [default.tls.mutual] + ca_certs = "path/to/ca_certs.pem" # Path or bytes to DER-encoded X.509 TLS cert chain. + mandatory = true # when absent, defaults to false + ``` + +The `tls.mutual` parameter is expected to be a dictionary that deserializes into a +[`MutualTls`] structure: + +| key | required | type | +|-------------|-----------|-------------------------------------------------------------| +| `ca_certs` | **_yes_** | Path or bytes to DER-encoded X.509 TLS cert chain. | +| `mandatory` | no | Boolean controlling whether the client _must_ authenticate. | + +[`MutualTls`]: @api/rocket/config/struct.MutualTls.html +[`mtls`]: @api/rocket/mtls/index.html + +Rocket reports if TLS and/or mTLS are enabled at launch time: + +```text +🔧 Configured for debug. + ... + >> tls: enabled w/mtls +``` + +Once mutual TLS is properly enabled, the [`mtls::Certificate`] request guard can +be used to retrieve validated, verified client certificates: + +```rust +# #[macro_use] extern crate rocket; +use rocket::mtls::Certificate; + +#[get("/auth")] +fn auth(cert: Certificate<'_>) { + // This handler only runs when a valid certificate was presented. +} ``` +The [TLS example](@example/tls) illustrates a fully configured TLS server with +mutual TLS. + +! warning: Rocket's built-in TLS supports only TLS 1.2 and 1.3. This may not be + suitable for production use. + +[`mtls::Certificate`]: @api/rocket/mtls/struct.Certificate.html + +### Workers + +The `workers` parameter sets the number of threads used for parallel task +execution; there is no limit to the number of concurrent tasks. Due to a +limitation in upstream async executers, unlike other values, the `workers` +configuration value cannot be reconfigured or be configured from sources other +than those provided by [`Config::figment()`]. In other words, only the values +set by the `ROCKET_WORKERS` environment variable or in the `workers` property of +`Rocket.toml` will be considered - all other `workers` values are ignored. + +The `max_blocking` parameter sets an upper limit on the number of threads the +underlying `async` runtime will spawn to execute potentially blocking, +synchronous tasks via [`spawn_blocking`] or equivalent. Similar to the `workers` +parameter, `max_blocking` cannot be reconfigured or be configured from sources +other than those provided by [`Config::figment()`]. Unlike `workers`, threads +corresponding to `max_blocking` are not always active and will exit if idling. +In general, the default value of `512` should not be changed unless physical or +virtual resources are scarce. Rocket only executes work on blocking threads when +required such as when performing file system I/O via [`TempFile`] or wrapping +synchronous work via [`rocket_sync_db_pools`]. + +[`spawn_blocking`]: @tokio/task/fn.spawn_blocking.html +[`TempFile`]: @api/rocket/fs/enum.TempFile.html +[`rocket_sync_db_pools`]: @api/rocket_sync_db_pools/index.html + ## Extracting Values Your application can extract any configuration that implements [`Deserialize`] @@ -213,6 +391,7 @@ fn rocket() -> _ { let figment = rocket.figment(); #[derive(Deserialize)] + #[serde(crate = "rocket::serde")] struct Config { port: u16, custom: Vec, @@ -241,6 +420,7 @@ Because it is common to store configuration in managed state, Rocket provides an # #[macro_use] extern crate rocket; # use rocket::serde::Deserialize; # #[derive(Deserialize)] +# #[serde(crate = "rocket::serde")] # struct Config { # port: u16, # custom: Vec, @@ -280,7 +460,7 @@ more complex cases. crate. As such, you may need to import crates directly: ` - figment = { version = "0.9", features = ["env", "toml", "json"] } + figment = { version = "0.10", features = ["env", "toml", "json"] } ` As a first example, we override configuration values at runtime by merging @@ -316,6 +496,7 @@ use rocket::fairing::AdHoc; use figment::{Figment, Profile, providers::{Format, Toml, Serialized, Env}}; #[derive(Debug, Deserialize, Serialize)] +#[serde(crate = "rocket::serde")] struct Config { app_value: usize, /* and so on.. */ @@ -341,7 +522,7 @@ fn rocket() -> _ { } ``` -Rocket will extract it's configuration from the configured provider. This means +Rocket will extract its configuration from the configured provider. This means that if values like `port` and `address` are configured in `Config`, `App.toml` or `APP_` environment variables, Rocket will make use of them. The application can also extract its configuration, done here via the `Adhoc::config()` fairing. diff --git a/site/guide/index.md b/site/guide/index.md index 10e4efd83a..82b2f099fc 100644 --- a/site/guide/index.md +++ b/site/guide/index.md @@ -2,7 +2,7 @@ Welcome to Rocket! -This is the official guide for Rocket master. It is designed to serve as a +This is the official guide for Rocket v0.5. It is designed to serve as a starting point to writing web applications with Rocket and Rust. The guide is also designed to be a reference for experienced Rocket developers. This guide is conversational in tone. For purely technical documentation with examples, see @@ -14,6 +14,7 @@ aspect of Rocket. The sections are: - **[Introduction](introduction/):** introduces Rocket and its philosophy. - **[Quickstart](quickstart/):** presents the minimal steps necessary to run your first Rocket application. + - **[Upgrading from v0.4](upgrading/):** a migration guide from v0.4 to v0.5. - **[Getting Started](getting-started/):** a gentle introduction to getting your first Rocket application running. - **[Overview](overview/):** describes the core concepts of Rocket. @@ -26,19 +27,22 @@ aspect of Rocket. The sections are: - **[Testing](testing/):** how to unit and integration test a Rocket application. - **[Configuration](configuration/):** how to configure a Rocket application. - - **[Pastebin](pastebin/):** a tutorial on how to create a pastebin with - Rocket. + - **[Pastebin Tutorial](pastebin-tutorial/):** a tutorial creating a pastebin + with Rocket. - **[Conclusion](conclusion/):** concludes the guide and discusses next steps for learning. + - **[FAQ](faq/):** answers to frequently asked questions about Rocket and + using it. ## Getting Help The official community support channels are [`#rocket:mozilla.org`] on Matrix -and the bridged [`#rocket`] IRC channel on Freenode at `chat.freenode.net`. We +and the bridged [`#rocket`] IRC channel on Libera.Chat at `irc.libera.chat`. We recommend joining us on [Matrix via Element]. If you prefer IRC, you can join -via the [Kiwi IRC client] or a client of your own. +via the [Kiwi IRC client] or a client of your own. The [FAQ](../faq/) also +provides answers to commonly asked questions. [`#rocket:mozilla.org`]: https://chat.mozilla.org/#/room/#rocket:mozilla.org -[`#rocket`]: https://kiwiirc.com/client/chat.freenode.net/#rocket +[`#rocket`]: https://kiwiirc.com/client/irc.libera.chat/#rocket [Matrix via Element]: https://chat.mozilla.org/#/room/#rocket:mozilla.org -[Kiwi IRC Client]: https://kiwiirc.com/client/chat.freenode.net/#rocket +[Kiwi IRC Client]: https://kiwiirc.com/client/irc.libera.chat/#rocket diff --git a/site/index.toml b/site/index.toml index a844ca787e..e2d5ac38c7 100644 --- a/site/index.toml +++ b/site/index.toml @@ -3,8 +3,8 @@ ############################################################################### [release] -version = "0.5.0-dev" -date = "Apr 13, 2021" +version = "0.5.0-rc.2" +date = "May 09, 2022" ############################################################################### # Top features: displayed in the header under the introductory text. @@ -61,8 +61,7 @@ code = ''' ''' text = ''' This is a **complete Rocket application**. It does exactly what you would - expect. If you were to visit **http://localhost:8000/hello/John/58**, you’d - see: + expect. If you were to visit **/hello/John/58**, you’d see: Hello, 58 year old named John! @@ -76,27 +75,26 @@ title = "Forms? Check!" code = ''' #[derive(FromForm)] struct Task<'r> { + #[field(validate = len(1..))] description: &'r str, completed: bool } #[post("/", data = "")] fn new(task: Form>) -> Flash { - if task.description.is_empty() { - Flash::error(Redirect::to(uri!(home)), "Cannot be empty.") - } else { - Flash::success(Redirect::to(uri!(home)), "Task added.") - } + Flash::success(Redirect::to(uri!(home)), "Task added.") } ''' text = ''' - Handling forms **is simple and easy**. Simply derive `FromForm` for your - structure and let Rocket know which parameter to use. Rocket **parses and - validates** the form request, creates the structure, and calls your function. - - Bad form request? Rocket doesn’t call your function! What if you want to know - if the form was bad? Simple! Change the type of `task` to `Option` or - `Result`! + Form handling **is simple, declarative, and complete**: derive + [`FromForm`](@api/rocket/derive.FromForm.html) for your structure and set the + `data` parameter to a `Form` type. Rocket automatically **parses and + validates** the form data into your structure and calls your function. + + Bad form request? Rocket doesn’t call your function! Need to know what went + wrong? Use a `data` parameter of `Result`! Want to rerender the form with user + input and errors? Use [`Context`](guide/requests/#context)! File uploads? A + breeze with [`TempFile`](@api/rocket/fs/enum.TempFile.html). ''' [[sections]] @@ -108,7 +106,7 @@ code = ''' } #[put("/", data = "")] - fn update(db: &Db, id: Id, msg: Json>) -> JsonValue { + fn update(db: &Db, id: Id, msg: Json>) -> Value { if db.contains_key(&id) { db.insert(id, msg.contents); json!({ "status": "ok" }) @@ -121,11 +119,12 @@ text = ''' Rocket has first-class support for JSON, right out of the box. Simply derive `Deserialize` or `Serialize` to receive or return JSON, respectively. - Like other important features, JSON works through Rocket’s `FromData` trait, - Rocket’s approach to deriving types from body data. It works like this: - specify a `data` route parameter of any type that implements `FromData`. A - value of that type will then be created automatically from the incoming - request body. Best of all, you can implement `FromData` for your types! + Look familiar? Forms, JSON, and all kinds of body data types work through + Rocket’s [`FromData`](@api/rocket/data/trait.FromData.html) trait, Rocket’s + approach to deriving types from body data. A `data` route parameter can be + _any_ type that implements `FromData`. A value of that type will be + deserialized automatically from the incoming request body. You can even + implement `FromData` for your own types! ''' ############################################################################### @@ -150,19 +149,19 @@ color = 'purple' margin = -6 [[bottom_features]] -title = 'Streams' -text = "Rocket streams all incoming and outgoing data, so size isn't a concern." +title = 'Async Streams' +text = "Create and return potentially infinite async streams of data with ease." image = 'streams-icon' -url = 'guide/requests/#streaming' +url = 'guide/responses/#async-streams' button = 'Learn More' color = 'red' margin = -29 [[bottom_features]] -title = 'Config Environments' -text = "Configure your application your way for development, staging, and production." +title = 'Config Profiles' +text = "Configure your application your way for debug, release, or anything else!" image = 'config-icon' -url = 'guide/configuration/#environment' +url = 'guide/configuration/#profiles' button = 'Learn More' color = 'yellow' margin = -3 diff --git a/site/news/2017-02-06-version-0.2.md b/site/news/2017-02-06-version-0.2.md index c1cd824fee..246c5dcdee 100644 --- a/site/news/2017-02-06-version-0.2.md +++ b/site/news/2017-02-06-version-0.2.md @@ -46,7 +46,7 @@ state's type in the function signature. It works in two easy steps: value passed into `manage`. Rocket takes care of the rest! `State` works through Rocket's [request -guards](../../guide/requests/#request-guards). You can call `manage` any number +guards](@guide-v0.3/requests/#request-guards). You can call `manage` any number of times, as long as each call corresponds to a value of a different type. As a simple example, consider the following "hit counter" example application: @@ -110,14 +110,14 @@ help: maybe add a call to 'manage' here? | ^^^^^^^^^^^^^^^^ ``` -You can read more about managed state in the [guide](../../guide/state/), the -API docs for [manage](@api/rocket/struct.Rocket.html#method.manage), and the API -docs for [State](@api/rocket/struct.State.html). +You can read more about managed state in the [guide](@guide-v0.3/state/), the +API docs for [manage](@api-v0.3/rocket/struct.Rocket.html#method.manage), and the API +docs for [State](@api-v0.3/rocket/struct.State.html). ### Unmounted Routes Lint A common mistake that new Rocketeers make is forgetting to -[mount](../../guide/overview/#mounting) declared routes. In Rocket v0.2, Rocket +[mount](@guide-v0.3/overview/#mounting) declared routes. In Rocket v0.2, Rocket adds a _lint_ that results in a compile-time warning for unmounted routes. As a simple illustration, consider the canonical "Hello, world!" Rocket application below, and note that we've forgotten to mount the `hello` route: @@ -156,7 +156,7 @@ help: maybe add a call to 'mount' here? The lint can be disabled selectively per route by adding an `#[allow(unmounted_route)]` annotation to a given route declaration. It can also be disabled globally by adding `#![allow(unmounted_route)]`. You can read more -about this lint in the [codegen documentation](@api/rocket_codegen/index.html). +about this lint in the [codegen documentation](@api-v0.3/rocket_codegen/index.html). ### Configuration via Environment Variables @@ -174,7 +174,7 @@ Configuration parameters set via environment variables take precedence over parameters set via the `Rocket.toml` configuration file. Note that _any_ parameter can be set via an environment variable, include _extras_. For more about configuration in Rocket, see the [configuration section of the -guide](../../guide/overview#configuration). +guide](@guide-v0.3/overview#configuration). ### And Plenty More! @@ -391,4 +391,4 @@ contributing! Not already using Rocket? Rocket is extensively documented, making it easy for you to start writing your web applications in Rocket! See the [overview](../../overview) or start writing code immediately by reading through -[the guide](../../guide). +[the guide](@guide-v0.3). diff --git a/site/news/2017-07-14-version-0.3.md b/site/news/2017-07-14-version-0.3.md index be77a938a6..566fe64db0 100644 --- a/site/news/2017-07-14-version-0.3.md +++ b/site/news/2017-07-14-version-0.3.md @@ -21,7 +21,7 @@ sacrificing flexibility or type safety. All with minimal code. Not already using Rocket? Join the thousands of users and dozens of companies happily using Rocket today! Rocket's extensive documentation makes it easy. Get -started now by [reading through the guide](../../guide) or learning more from +started now by [reading through the guide](@guide-v0.3) or learning more from [the overview](../../overview). ## What's New? @@ -61,8 +61,8 @@ limitations and abilities, and includes implementation examples. I encourage you to experiment with fairings and report your experiences. As always, feedback is instrumental in solidifying a robust design. -[`Fairing`]: @api/rocket/fairing/trait.Fairing.html -[fairings guide]: ../../guide/fairings +[`Fairing`]: @api-v0.3/rocket/fairing/trait.Fairing.html +[fairings guide]: @guide-v0.3/fairings ### Native TLS Support @@ -88,7 +88,7 @@ For more details on Rocket's TLS support, see the [configuring TLS] section of the guide. [`rustls`]: https://github.com/ctz/rustls -[configuring TLS]: ../../guide/configuration/#configuring-tls +[configuring TLS]: @guide-v0.3/configuration/#configuring-tls ### Private Cookies @@ -126,11 +126,11 @@ automatically generates a fresh key at launch. For more details on private cookies, see the [private cookies] section of the guide. -[`Cookies`]: @api/rocket/http/enum.Cookies.html -[`get_private`]: @api/rocket/http/enum.Cookies.html#method.get_private -[`add_private`]: @api/rocket/http/enum.Cookies.html#method.add_private -[`remove_private`]: @api/rocket/http/enum.Cookies.html#method.remove_private -[private cookies]: ../../guide/requests/#private-cookies +[`Cookies`]: @api-v0.3/rocket/http/enum.Cookies.html +[`get_private`]: @api-v0.3/rocket/http/enum.Cookies.html#method.get_private +[`add_private`]: @api-v0.3/rocket/http/enum.Cookies.html#method.add_private +[`remove_private`]: @api-v0.3/rocket/http/enum.Cookies.html#method.remove_private +[private cookies]: @guide-v0.3/requests/#private-cookies ### Form Field Naming @@ -163,9 +163,9 @@ struct External { Rocket will automatically match the form field named "type" to the structure field named `api_type`. For more details on form field naming, see the [field -renaming](../../guide/requests/#field-renaming) section of the guide. +renaming](@guide-v0.3/requests/#field-renaming) section of the guide. -[`FromForm`]: @api/rocket/request/trait.FromForm.html +[`FromForm`]: @api-v0.3/rocket/request/trait.FromForm.html ### And Plenty More! @@ -189,7 +189,7 @@ following new features: * [`Response::content_type()`] was added to retrieve the Content-Type header of a response. * Data limits on incoming data are [now - configurable](../../guide/configuration/#data-limits). + configurable](@guide-v0.3/configuration/#data-limits). * [`Request::limits()`] was added to retrieve incoming data limits. * Responders may dynamically adjust their response based on the incoming request. @@ -211,28 +211,28 @@ following new features: * The [`NotFound`] responder was added for simple **404** response construction. -[`MsgPack`]: @api/rocket_contrib/msgpack/struct.MsgPack.html -[`Rocket::launch()`]: @api/rocket/struct.Rocket.html#method.launch -[`LaunchError`]: @api/rocket/error/struct.LaunchError.html -[Default rankings]: @api/rocket/struct.Route.html -[`&Route`]: @api/rocket/struct.Route.html -[`Route`]: @api/rocket/struct.Route.html -[`Accept`]: @api/rocket/http/struct.Accept.html -[`Request::accept()`]: @api/rocket/struct.Request.html#method.accept -[`contrib`]: @api/rocket_contrib/ -[`Rocket::routes()`]: @api/rocket/struct.Rocket.html#method.routes -[`Response::body_string()`]: @api/rocket/struct.Response.html#method.body_string -[`Response::body_bytes()`]: @api/rocket/struct.Response.html#method.body_bytes -[`Response::content_type()`]: @api/rocket/struct.Response.html#method.content_type -[`Request::guard()`]: @api/rocket/struct.Request.html#method.guard -[`Request::limits()`]: @api/rocket/struct.Request.html#method.limits -[`Request::route()`]: @api/rocket/struct.Request.html#method.route -[`Config`]: @api/rocket/struct.Config.html -[`Cookies`]: @api/rocket/http/enum.Cookies.html -[`Config::get_datetime()`]: @api/rocket/struct.Config.html#method.get_datetime -[`LenientForm`]: @api/rocket/request/struct.LenientForm.html -[configuration parameters]: @api/rocket/config/index.html#environment-variables -[`NotFound`]: @api/rocket/response/status/struct.NotFound.html +[`MsgPack`]: @api-v0.3/rocket_contrib/msgpack/struct.MsgPack.html +[`Rocket::launch()`]: @api-v0.3/rocket/struct.Rocket.html#method.launch +[`LaunchError`]: @api-v0.3/rocket/error/struct.LaunchError.html +[Default rankings]: @api-v0.3/rocket/struct.Route.html +[`&Route`]: @api-v0.3/rocket/struct.Route.html +[`Route`]: @api-v0.3/rocket/struct.Route.html +[`Accept`]: @api-v0.3/rocket/http/struct.Accept.html +[`Request::accept()`]: @api-v0.3/rocket/struct.Request.html#method.accept +[`contrib`]: @api-v0.3/rocket_contrib/ +[`Rocket::routes()`]: @api-v0.3/rocket/struct.Rocket.html#method.routes +[`Response::body_string()`]: @api-v0.3/rocket/struct.Response.html#method.body_string +[`Response::body_bytes()`]: @api-v0.3/rocket/struct.Response.html#method.body_bytes +[`Response::content_type()`]: @api-v0.3/rocket/struct.Response.html#method.content_type +[`Request::guard()`]: @api-v0.3/rocket/struct.Request.html#method.guard +[`Request::limits()`]: @api-v0.3/rocket/struct.Request.html#method.limits +[`Request::route()`]: @api-v0.3/rocket/struct.Request.html#method.route +[`Config`]: @api-v0.3/rocket/struct.Config.html +[`Cookies`]: @api-v0.3/rocket/http/enum.Cookies.html +[`Config::get_datetime()`]: @api-v0.3/rocket/struct.Config.html#method.get_datetime +[`LenientForm`]: @api-v0.3/rocket/request/struct.LenientForm.html +[configuration parameters]: @api-v0.3/rocket/config/index.html#environment-variables +[`NotFound`]: @api-v0.3/rocket/response/status/struct.NotFound.html ## Breaking Changes @@ -267,9 +267,9 @@ In addition to new features, Rocket saw the following improvements: * The format of a request is always logged when available. [`yansi`]: https://crates.io/crates/yansi -[`Request`]: @api/rocket/struct.Request.html -[`State`]: @api/rocket/struct.State.html -[`Config`]: @api/rocket/struct.Config.html +[`Request`]: @api-v0.3/rocket/struct.Request.html +[`State`]: @api-v0.3/rocket/struct.State.html +[`Config`]: @api-v0.3/rocket/struct.Config.html ## What's Next? @@ -300,7 +300,7 @@ and usability. The following major features are planned: type-checks. In the next release, a `url!` macro will be available to automatically generate URLs for routes in a type-safe manner. -[much wordier than necessary]: ../../guide/state/#databases +[much wordier than necessary]: @guide-v0.3/state/#databases ## Contributors to v0.3 diff --git a/site/news/2018-10-31-version-0.4-rc.md b/site/news/2018-10-31-version-0.4-rc.md index 8a2b9dac57..5958bd3d65 100644 --- a/site/news/2018-10-31-version-0.4-rc.md +++ b/site/news/2018-10-31-version-0.4-rc.md @@ -26,7 +26,7 @@ Friday, November 9th for the general release! [GitHub issue tracker]: https://github.com/SergioBenitez/Rocket/issues [API docs]: https://api.rocket.rs/v0.4/rocket/ -[guide]: ../../guide +[guide]: @guide-v0.4 [CHANGELOG]: https://github.com/SergioBenitez/Rocket/tree/v0.4/CHANGELOG.md#version-040-rc-oct-31-2018 ## About Rocket @@ -37,5 +37,5 @@ sacrificing flexibility or type safety. All with minimal code. Not already using Rocket? Join the tens of thousands of users and hundreds of companies happily using Rocket today! Rocket's extensive documentation makes it -easy. Get started now by [reading through the guide](../../guide) or learning +easy. Get started now by [reading through the guide](@guide-v0.4) or learning more from [the overview](../../overview). diff --git a/site/news/2018-11-30-version-0.4-rc-2.md b/site/news/2018-11-30-version-0.4-rc-2.md index f5bea22c1b..048a729b7f 100644 --- a/site/news/2018-11-30-version-0.4-rc-2.md +++ b/site/news/2018-11-30-version-0.4-rc-2.md @@ -32,8 +32,8 @@ We're excited for your feedback, and we look forward to seeing you again on Wednesday, December 5th for the general release! [GitHub issue tracker]: https://github.com/SergioBenitez/Rocket/issues -[API docs]: https://api.rocket.rs/v0.4/rocket/ -[guide]: ../../guide +[API docs]: @api-v0.4 +[guide]: @guide-v0.4 [CHANGELOG]: https://github.com/SergioBenitez/Rocket/tree/v0.4/CHANGELOG.md#version-040-rc2-nov-30-2018 ## About Rocket @@ -44,5 +44,5 @@ sacrificing flexibility or type safety. All with minimal code. Not already using Rocket? Join the tens of thousands of users and hundreds of companies happily using Rocket today! Rocket's extensive documentation makes it -easy. Get started now by [reading through the guide](../../guide) or learning +easy. Get started now by [reading through the guide](@guide-v0.4) or learning more from [the overview](../../overview). diff --git a/site/news/2018-12-08-version-0.4.md b/site/news/2018-12-08-version-0.4.md index db69dbcdf5..4eb606b897 100644 --- a/site/news/2018-12-08-version-0.4.md +++ b/site/news/2018-12-08-version-0.4.md @@ -23,7 +23,7 @@ without sacrificing flexibility or type safety. Not already using Rocket? Join the tens of thousands of users and hundreds of companies happily using Rocket today! Rocket's extensive documentation makes it -easy. Get started now by [reading through the guide](../../guide) or learning +easy. Get started now by [reading through the guide](@guide-v0.4) or learning more from [the overview](../../overview). ## What's New? @@ -151,8 +151,8 @@ We recommend that `uri!` is exclusively used when constructing route URIs. For more information on typed URIs, see the new [Typed URIs] guide section and the [`uri!`] macro documentation. -[`uri!`]: @api/rocket_codegen/macro.uri.html -[Typed URIs]: ../../guide/responses/#typed-uris +[`uri!`]: @api-v0.4/rocket_codegen/macro.uri.html +[Typed URIs]: @guide-v0.4/responses/#typed-uris ### Database Support @@ -197,8 +197,8 @@ fn get_logs(conn: LogsDbConn, id: usize) -> Result { For more information on Rocket's database support, see the new [Database] guide section and the [`rocket_contrib::databases`] module documentation. -[Database]: ../../guide/state/#databases -[`rocket_contrib::databases`]: @api/rocket_contrib/databases/index.html +[Database]: @guide-v0.4/state/#databases +[`rocket_contrib::databases`]: @api-v0.4/rocket_contrib/databases/index.html ### Revamped Queries @@ -241,10 +241,10 @@ and [`FromFormValue`] can be derived. For more details on handling query strings, see the new [Query Strings] guide section and the updated [`route` attribute] documentation. -[`FromFormValue`]: @api/rocket/request/trait.FromFormValue.html -[`FromQuery`]: @api/rocket/request/trait.FromQuery.html -[`route` attribute]: @api/rocket_codegen/attr.get.html -[Query Strings]: ../../guide/requests/#query-strings +[`FromFormValue`]: @api-v0.4/rocket/request/trait.FromFormValue.html +[`FromQuery`]: @api-v0.4/rocket/request/trait.FromQuery.html +[`route` attribute]: @api-v0.4/rocket_codegen/attr.get.html +[Query Strings]: @guide-v0.4/requests/#query-strings [#608]: https://github.com/SergioBenitez/Rocket/issues/608 ### Stateful Handlers @@ -269,8 +269,8 @@ fn main() { We encourage users to explore the new `Handler` API and contribute libraries with pluggable handlers! For more details, see the [`Handler`] documentation. -[`Handler`]: @api/rocket/trait.Handler.html -[`StaticFiles`]: @api/rocket_contrib/serve/struct.StaticFiles.html +[`Handler`]: @api-v0.4/rocket/trait.Handler.html +[`StaticFiles`]: @api-v0.4/rocket_contrib/serve/struct.StaticFiles.html ### Responder Derive @@ -319,9 +319,9 @@ headers to the response (here, `ContentType`). For more on using the `Responder` derive, see the new [Custom Responders] guide section and the [`Responder` derive] documentation. -[Custom Responders]: ../../guide/responses/#custom-responders -[`Responder` derive]: @api/rocket_codegen/derive.Responder.html -[`Responder`]: @api/rocket/response/trait.Responder.html +[Custom Responders]: @guide-v0.4/responses/#custom-responders +[`Responder` derive]: @api-v0.4/rocket_codegen/derive.Responder.html +[`Responder`]: @api-v0.4/rocket/response/trait.Responder.html ### Live Template Reloading @@ -465,17 +465,17 @@ In addition to new features, Rocket saw the following improvements: * The `cookie` dependency was updated to `0.11`. [Tera templates example]: @github/examples/tera_templates -[`FormItems`]: @api/rocket/request/enum.FormItems.html -[`Config::active()`]: @api/rocket/config/struct.Config.html#method.active -[`Flash`]: @api/rocket/response/struct.Flash.html -[`AdHoc::on_attach()`]: @api/rocket/fairing/struct.AdHoc.html#method.on_attach -[`AdHoc::on_launch()`]: @api/rocket/fairing/struct.AdHoc.html#method.on_launch -[`Config::root_relative()`]: @api/rocket/struct.Config.html#method.root_relative -[`Config::tls_enabled()`]: @api/rocket/struct.Config.html#method.tls_enabled -[`rocket_codegen`]: @api/rocket_codegen/index.html -[`FromParam`]: @api/rocket/request/trait.FromParam.html -[`FromFormValue`]: @api/rocket/request/trait.FromFormValue.html -[`Data`]: @api/rocket/struct.Data.html +[`FormItems`]: @api-v0.4/rocket/request/enum.FormItems.html +[`Config::active()`]: @api-v0.4/rocket/config/struct.Config.html#method.active +[`Flash`]: @api-v0.4/rocket/response/struct.Flash.html +[`AdHoc::on_attach()`]: @api-v0.4/rocket/fairing/struct.AdHoc.html#method.on_attach +[`AdHoc::on_launch()`]: @api-v0.4/rocket/fairing/struct.AdHoc.html#method.on_launch +[`Config::root_relative()`]: @api-v0.4/rocket/struct.Config.html#method.root_relative +[`Config::tls_enabled()`]: @api-v0.4/rocket/struct.Config.html#method.tls_enabled +[`rocket_codegen`]: @api-v0.4/rocket_codegen/index.html +[`FromParam`]: @api-v0.4/rocket/request/trait.FromParam.html +[`FromFormValue`]: @api-v0.4/rocket/request/trait.FromFormValue.html +[`Data`]: @api-v0.4/rocket/struct.Data.html [`Form`]: https://api.rocket.rs/v0.4/rocket/request/struct.Form.html [`LenientForm`]: https://api.rocket.rs/v0.4/rocket/request/struct.LenientForm.html diff --git a/site/news/2021-06-09-version-0.5-rc.1.md b/site/news/2021-06-09-version-0.5-rc.1.md new file mode 100644 index 0000000000..18792e438a --- /dev/null +++ b/site/news/2021-06-09-version-0.5-rc.1.md @@ -0,0 +1,43 @@ +# Rocket v0.5 Release Candidate + +

+ Posted by Sergio Benitez on June 09, 2021 +

+ +Rocket `0.5.0-rc.1`, a release candidate for Rocket v0.5, is now available. + +This release actualizes over _two years_ of development, bringing Rocket to Rust +stable and `async` to Rocket. Every facet, from core request handling to error +messages, has been subjected to Rocket's exacting standards. + +This release candidate is an opportunity to discover issues with Rocket v0.5 and +its documentation before a general release. We encourage all users to migrate +their applications to the release candidate. All documentation, including the +[guide] and [API docs], has been updated in full for v0.5. Please report issues +to the [GitHub issue tracker]. Questions or concerns should instead be raised on +Rocket's newly available [GitHub discussions]. + +The Rocket v0.5 general release is planned for Friday, June 18th. A complete +migration guide and news article will accompany the general release. Until then, +the [CHANGELOG] contains every feature addition, change, and improvement since +v0.4. + +We hope you enjoy Rocket v0.5 as much as we enjoyed creating it. We look forward +to your feedback! + +[GitHub issue tracker]: https://github.com/SergioBenitez/Rocket/issues +[GitHub discussions]: https://github.com/SergioBenitez/Rocket/discussions +[CHANGELOG]: https://github.com/SergioBenitez/Rocket/blob/v0.5-rc/CHANGELOG.md#version-050-rc1-jun-9-2021 +[API docs]: @api +[guide]: ../../guide + +## About Rocket + +Rocket is a web framework for Rust with a focus on usability, security, +extensibility, and speed. Rocket makes it simple to write fast, secure web +applications without sacrificing usability. + +Not already using Rocket? Join the tens of thousands of users and hundreds of +companies happily using Rocket today! Rocket's extensive documentation makes it +easy: get started by [reading through the guide](../../guide) or learning more +from [the overview](../../overview). diff --git a/site/news/2022-05-09-version-0.5-rc.2.md b/site/news/2022-05-09-version-0.5-rc.2.md new file mode 100644 index 0000000000..c3d9c00ede --- /dev/null +++ b/site/news/2022-05-09-version-0.5-rc.2.md @@ -0,0 +1,43 @@ +# Rocket's 2nd v0.5 Release Candidate + +

+ Posted by Sergio Benitez on May 09, 2022 +

+ +Rocket `0.5.0-rc.2`, a release candidate for Rocket v0.5, is now available. + +This release builds on the previous release candidate and brings further +features, improvements, and fixes to Rocket. As before, this is an opportunity +to discover issues with Rocket v0.5 and its documentation before its general +release. We encourage all users to migrate their applications to the second +release candidate and report any issues to the [GitHub issue tracker]. Please +see the new [migration guide] for complete details on how to upgrade from Rocket +v0.4. For changes since Rocket v0.5.0-rc.1, please see the [CHANGELOG]. + +Barring any major issues, of which none are expected, the general release of +Rocket v0.5 is planned for late May 2022, when we'll post a full news article +covering the biggest features and changes in Rocket v0.5. Until then, the +[CHANGELOG] contains every feature addition, change, and improvement since +v0.5.0-rc.1 and v0.4. All documentation, including the [guide] and [API docs], +has been updated in full for the second release candidate. + +We're excited for your feedback, and we look forward to seeing you again soon +for the general release! + +[GitHub issue tracker]: https://github.com/SergioBenitez/Rocket/issues +[GitHub discussions]: https://github.com/SergioBenitez/Rocket/discussions +[migration guide]: ../../guide/upgrading +[CHANGELOG]: https://github.com/SergioBenitez/Rocket/blob/v0.5-rc/CHANGELOG.md#version-050-rc2-may-9-2022 +[API docs]: @api +[guide]: ../../guide + +## About Rocket + +Rocket is a web framework for Rust with a focus on usability, security, +extensibility, and speed. Rocket makes it simple to write fast, secure web +applications without sacrificing usability. + +Not already using Rocket? Join the tens of thousands of users and hundreds of +companies happily using Rocket today! Rocket's extensive documentation makes it +easy: get started by [reading through the guide](../../guide) or learning more +from [the overview](../../overview). diff --git a/site/news/index.toml b/site/news/index.toml index a2c53c5de2..bd238b5a24 100644 --- a/site/news/index.toml +++ b/site/news/index.toml @@ -1,3 +1,36 @@ +[[articles]] +title = """ + Rocket's 2nd v0.5 Release Candidate +""" +slug = "2022-05-09-version-0.5-rc.2" +author = "Sergio Benitez" +author_url = "https://sergio.bz" +date = "May 09, 2022" +snippet = """ +Rocket `0.5.0-rc.2`, a release candidate for Rocket v0.5, is now available. + +This release builds on the previous release candidate and brings further +features, improvements, and fixes to Rocket. As before, this is an opportunity +to discover issues with Rocket v0.5 and its documentation before its general +release. +""" + +[[articles]] +title = """ + Rocket v0.5 Release Candidate +""" +slug = "2021-06-09-version-0.5-rc.1" +author = "Sergio Benitez" +author_url = "https://sergio.bz" +date = "June 09, 2021" +snippet = """ +Rocket `0.5.0-rc.1`, a release candidate for Rocket v0.5, is now available. + +This release actualizes over _two years_ of development, bringing Rocket to Rust +stable and `async` to Rocket. Every facet, from core request handling to error +messages, has been subjected to Rocket's exacting standards. +""" + [[articles]] title = """ Rocket v0.4: Typed URIs, Database Support, Revamped Queries, & More! diff --git a/site/overview.toml b/site/overview.toml index 96df81d663..c37384c391 100644 --- a/site/overview.toml +++ b/site/overview.toml @@ -17,64 +17,65 @@ As an example, consider the simple route below: ```rust #[get("/")] fn index() -> &'static str { - "Hello, world!" + "Hello, world!" } ``` -This route, named `index`, will match against incoming HTTP `GET` requests to -the `/` path, the index. The request handler returns a string. Rocket will use -the string as the body of a fully formed HTTP response. +This `index` route matches any incoming HTTP `GET` request to `/`, the index. +The handler returns a `String`. Rocket automatically converts the string into a +well-formed HTTP response that includes the appropriate `Content-Type` and body +encoding metadata. ''' [[panels]] name = "Dynamic Params" content = ''' -Rocket allows you to interpret segments of a request path dynamically. To -illustrate, let's use the following route: +Rocket automatically parses dynamic data in path segments into any desired type. +To illustrate, let's use the following route: ```rust #[get("/hello//")] -fn hello(name: String, age: u8) -> String { +fn hello(name: &str, age: u8) -> String { format!("Hello, {} year old named {}!", age, name) } ``` -The `hello` route above matches two dynamic path segments declared inside -brackets in the path: `` and ``. _Dynamic_ means that the segment can -be _any_ value the end-user desires. +This `hello` route has two dynamic parameters, identified with angle brackets, +declared in the route URI: `` and ``. Rocket maps each parameter to +an identically named function argument: `name: &str` and `age: u8`. The dynamic +data in the incoming request is parsed automatically into a value of the +argument's type. The route is called only when parsing succeeds. -Each dynamic parameter (`name` and `age`) must have a type, here `&str` and -`u8`, respectively. Rocket will attempt to parse the string in the parameter's -position in the path into that type. The route will only be called if parsing -succeeds. To parse the string, Rocket uses the -[FromParam](@api/rocket/request/trait.FromParam.html) trait, -which you can implement for your own types! +Parsing is directed by the +[`FromParam`](@api/rocket/request/trait.FromParam.html) trait. Rocket implements +`FromParam` for many standard types, including both `&str` and `u8`. You can +implement it for your own types, too! ''' [[panels]] name = "Handling Data" content = ''' -Request body data is handled in a special way in Rocket: via the -[FromData](@api/rocket/data/trait.FromData.html) trait. Any type that implements -`FromData` can be derived from incoming body data. To tell Rocket that you're -expecting request body data, the `data` route argument is used with the name of -the parameter in the request handler: +Rocket can automatically parse body data, too! ```rust -#[post("/login", data = "")] -fn login(user_form: Form) -> String { - format!("Hello, {}!", user_form.name) +#[post("/login", data = "")] +fn login(login: Form) -> String { + format!("Hello, {}!", login.name) } ``` -The `login` route above says that it expects `data` of type `Form` in -the `user_form` parameter. The [Form](@api/rocket/request/struct.Form.html) type -is a built-in Rocket type that knows how to parse web forms into structures. -Rocket will automatically attempt to parse the request body into the `Form` and -call the `login` handler if parsing succeeds. Other built-in `FromData` types -include [`Data`](@api/rocket/struct.Data.html), +The dynamic parameter declared in the `data` route attribute parameter again +maps to a function argument. Here, `login` maps to `login: Form`. +Parsing is again trait-directed, this time by the +[`FromData`](@api/rocket/data/trait.FromData.html) trait. + +The [`Form`](@api/rocket/form/struct.Form.html) type is Rocket's [robust form +data parser](@guide/requests/#forms). It automatically parses the request body into the internal type, +here `UserLogin`. Other built-in `FromData` types include +[`Data`](@api/rocket/struct.Data.html), [`Json`](@api/rocket/serde/json/struct.Json.html), and -[`Flash`](@api/rocket/response/struct.Flash.html). +[`MsgPack`](@api/rocket/serde/msgpack/struct.MsgPack.html). As always, you can +implement `FromData` for your own types, too! ''' [[panels]] @@ -107,7 +108,7 @@ invariants through types. name = "Responders" content = ''' The return type of a request handler can be any type that implements -[Responder](@api/rocket/response/trait.Responder.html): +[`Responder`](@api/rocket/response/trait.Responder.html): ```rust #[get("/")] @@ -117,9 +118,9 @@ fn route() -> T { ... } Above, T must implement `Responder`. Rocket implements `Responder` for many of the standard library types including `&str`, `String`, `File`, `Option`, and `Result`. Rocket also implements custom responders such as -[Redirect](@api/rocket/response/struct.Redirect.html), -[Flash](@api/rocket/response/struct.Flash.html), and -[Template](@api/rocket_dyn_templates/struct.Template.html). +[`Redirect`](@api/rocket/response/struct.Redirect.html), +[`Flash`](@api/rocket/response/struct.Flash.html), and +[`Template`](@api/rocket_dyn_templates/struct.Template.html). The task of a `Responder` is to generate a [`Response`](@api/rocket/response/struct.Response.html), if possible. @@ -135,10 +136,9 @@ fn not_found() -> T { ... } [[panels]] name = "Launching" content = ''' -Launching a Rocket application is the funnest part! For Rocket to begin -dispatching requests to routes, routes need to be _mounted_. After mounting, the -application needs to be _launched_. These two steps, usually done in a `rocket` -function, look like: +Finally, we get to launch our application! Rocket begins dispatching requests to +routes after they've been _mounted_ and the application has been _launched_. +These two steps, usually wrtten in a `rocket` function, look like: ```rust #[launch] @@ -147,15 +147,14 @@ fn rocket() -> _ { } ``` -The `mount` call takes a base path and a set of routes via the `routes!` macro. -The base path (`/base` above) is prepended to the path of every route in the -list. This namespaces the routes, allowing for composition. The `#[launch]` -attribute creates a `main` function that starts the server. In development, -Rocket prints useful information to the console to let you know everything is -okay. +The `mount` call takes a _base_ and a set of routes via the `routes!` macro. The +base path (`/base` above) is prepended to the path of every route in the list, +effectively namespacing the routes. `#[launch]` creates a `main` function that +starts the server. In development, Rocket prints useful information to the +console to let you know everything is okay. ```sh -🚀 Rocket has launched from http://localhost:8000 +🚀 Rocket has launched from http://127.0.0.1:8000 ``` ''' @@ -176,7 +175,7 @@ customizable **404** error is returned. ```rust #[post("/user", data = "")] fn new_user(admin: AdminUser, new_user: Form) -> T { - ... + ... } ``` diff --git a/site/tests/Cargo.toml b/site/tests/Cargo.toml index 384a8f2b9d..05be94464a 100644 --- a/site/tests/Cargo.toml +++ b/site/tests/Cargo.toml @@ -1,24 +1,22 @@ [package] name = "rocket_guide_tests" -version = "0.5.0-dev" +version = "0.5.0-rc.2" workspace = "../../" -edition = "2018" +edition = "2021" publish = false [dependencies] rocket = { path = "../../core/lib", features = ["secrets"] } [dev-dependencies] -rocket = { path = "../../core/lib", features = ["secrets", "json"] } -serde = { version = "1.0", features = ["derive"] } +rocket = { path = "../../core/lib", features = ["secrets", "json", "mtls"] } rand = "0.8" figment = { version = "0.10", features = ["toml", "env"] } -time = "0.2" [dev-dependencies.rocket_dyn_templates] path = "../../contrib/dyn_templates" features = ["tera"] -[dev-dependencies.rocket_sync_db_pools] -path = "../../contrib/sync_db_pools/lib" -features = ["diesel_sqlite_pool"] +[dev-dependencies.rocket_db_pools] +path = "../../contrib/db_pools/lib" +features = ["sqlx_sqlite"]