Rocket/examples
Sergio Benitez fbd1a0d069 Improve forwarding status code precision.
Previously, the `NotFound` status code was used to signal many kinds of
recoverable, forwarding errors. This included validation errors, incorrect
Content-Type errors, and more.

This commit modifies the status code used to forward in these instances to more
precisely indicate the forwarding condition. In particular:

  * Parameter `FromParam` errors now forward as 422 (`UnprocessableEntity`).
  * Query paramater errors now forward as 422 (`UnprocessableEntity`).
  * Use of incorrect form content-type forwards as 413 (`UnsupportedMediaType`).
  * `WebSocket` guard now forwards as 400 (`BadRequest`).
  * `&Host`, `&Accept`, `&ContentType`, `IpAddr`, and `SocketAddr` all forward
    with a 500 (`InternalServerError`).

Additionally, the `IntoOutcome` trait was overhauled to support functionality
previously offered by methods on `Outcome`. The `Outcome::forward()` method now
requires a status code to use for the forwarding outcome.

Finally, logging of `Outcome`s now includes the relevant status code.

Resolves #2626.
2023-10-31 18:44:37 -05:00
..
chat Improve chat example JavaScript code. 2023-09-20 13:55:59 -07:00
config Defend against configured known secret keys. 2023-03-23 14:57:54 -07:00
cookies Update 'cookie' to 0.18. 2023-09-28 23:50:29 -07:00
databases Work around bug in sqlx database example. 2023-08-25 17:59:29 -07:00
error-handling Improve forwarding status code precision. 2023-10-31 18:44:37 -05:00
fairings Migrate Rocket to Rust 2021 edition. 2022-04-19 18:35:38 -07:00
forms Fix off-by-one, improve style in forms example. 2023-10-27 15:19:48 -05:00
hello Improve forwarding status code precision. 2023-10-31 18:44:37 -05:00
manual-routing Improve forwarding status code precision. 2023-10-31 18:44:37 -05:00
pastebin Fix 'PasteId' 'use' in pastebin tutorial. 2022-05-08 18:30:13 -05:00
responders Fix SSE heartbeat so it never interrupts events. 2022-04-27 13:59:03 -07:00
serialization Improve forwarding status code precision. 2023-10-31 18:44:37 -05:00
state Migrate Rocket to Rust 2021 edition. 2022-04-19 18:35:38 -07:00
static-files Make trailing slashes significant during routing. 2023-04-10 12:40:39 -07:00
templating Migrate Rocket to Rust 2021 edition. 2022-04-19 18:35:38 -07:00
testing Migrate Rocket to Rust 2021 edition. 2022-04-19 18:35:38 -07:00
tls Update 'cookie' to 0.18. 2023-09-28 23:50:29 -07:00
todo Update diesel to 2.0, sqlx to 0.6. 2022-09-18 01:24:57 -07:00
upgrade Fully document the 'ws' contrib crate. 2023-04-03 16:09:45 -07:00
Cargo.toml Use 'resolver = 2' across workspaces. 2023-06-09 16:46:58 -07:00
README.md Add 'upgrade' example with WebSocket support. 2023-03-29 17:07:01 -07:00

README.md

Rocket Examples

This directory contains projects showcasing Rocket's features.

Applications

  • pastebin

    A simple, API-only pastebin application, similar to https://paste.rs. Stores pastes locally on the file system. Implements a custom parameter guard, PasteId, to parse and validate paste identifiers.

  • todo

    A todo app with a web UI to add, delete, and mark/unmark items. Uses a SQLite database driven by diesel. Runs migrations automatically at start-up. Uses tera to render templates.

  • chat

    A real-time, multi-room chat application using Server-Sent Events (SSE) and JavaScript's EventSource. Supports automatic reconnection with exponential backoff and live connection status.

Feature Examples

  • config - Illustrates how to extract values from a Rocket Figment, how to store and retrieve an application specific configuration in managed state using AdHoc::config(), and how to set configuration values in Rocket.toml.

  • cookies - Uses cookies to create a client-side message box. Uses private cookies for a session-based authentication.

  • databases - Implements a CRUD-like "blog" JSON API backed by a SQLite database driven by each of sqlx, diesel, and rusqlite. Runs migrations automatically for the former two drivers. Uses contrib database support for all drivers (rocket_db_pools for the first; rocket_sync_db_pools for the other latter two).

  • error-handling - Exhibits the use of scoped catchers; contains commented out lines that will cause a launch-time error with code to custom-display the error.

  • fairings - Exemplifies creating a custom Counter fairing and using AdHoc fairings.

  • forms - Showcases all of Rocket's form support features including multipart file uploads, ad-hoc validations, field renaming, and use of form context for staged forms.

  • hello - Basic example of Rocket's core features: route declaration with path and query parameters, both simple and compound, mounting, launching, testing, and returning simple responses. Also showcases using UTF-8 in route declarations and responses.

  • manual-routing - An example eschewing Rocket's codegen in favor of manual routing. This should be seen as last-ditch effort, much like unsafe in Rust, as manual routing also eschews many of Rocket's automatic web security guarantees.

  • responders - Illustrates the use of many of Rocket's built-in responders: Stream, Redirect, File, NamedFile, content for manually setting Content-Types, and Either. In the process, showcases using TempFile for raw uploads. Also illustrates the creation of a custom, derived Responder.

  • serialization - Showcases JSON and MessagePack (de)serialization support by implementing a CRUD-like message API in JSON and a simply read/echo API in MessagePack. Showcases UUID parsing support.

  • state - Illustrates the use of request-local state and managed state. Uses request-local state to cache "expensive" per-request operations. Uses managed state to implement a simple index hit counter. Also uses managed state to store, retrieve, and push/pop from a concurrent queue.

  • static-files - Uses FileServer to serve static files. Also creates a second manual yet safe version.

  • templating - Illustrates using contrib templates support with identical examples for handlebars and tera.

  • testing - Uses Rocket's local libraries to test an application. Showcases necessary use of the async Client. Note that all examples contains tests, themselves serving as examples for how to test Rocket applications.

  • tls - Illustrates configuring TLS with a variety of key pair kinds.

  • upgrade - Uses the connection upgrade API to implement WebSocket support using tungstenite.