64e46b7107
Sentinels resolve a long-standing usability and functional correctness
issue in Rocket: starting an application with guards and/or responders
that depend on state that isn't available. The canonical example is the
'State' guard. Prior to this commit, an application with routes that
queried unmanaged state via 'State' would fail at runtime. With this
commit, the application refuses to launch with a detailed error message.
The 'Sentinel' docs explains it as:
A sentinel, automatically run on ignition, can trigger a launch
abort should an instance fail to meet arbitrary conditions. Every
type that appears in a mounted route's type signature is eligible to
be a sentinel. Of these, those that implement 'Sentinel' have their
'abort()' method invoked automatically, immediately after ignition,
once for each unique type. Sentinels inspect the finalized instance
of 'Rocket' and can trigger a launch abort by returning 'true'.
The following types are now sentinels:
* 'contrib::databases::Connection' (any '#[database]' type)
* 'contrib::templates::Metadata'
* 'contrib::templates::Template'
* 'core::State'
The following are "specialized" sentinels, which allow sentinel
discovery even through type aliases:
* 'Option<T>', 'Debug<T>' if 'T: Sentinel'
* 'Result<T, E>', 'Either<T, E>' if 'T: Sentinel', 'E: Sentinel'
Closes #464.
|
||
|---|---|---|
| .. | ||
| config | ||
| cookies | ||
| databases | ||
| error-handling | ||
| fairings | ||
| forms | ||
| hello | ||
| manual-routing | ||
| pastebin | ||
| responders | ||
| serialization | ||
| state | ||
| static-files | ||
| templating | ||
| testing | ||
| tls | ||
| todo | ||
| uuid | ||
| Cargo.toml | ||
| README.md | ||
README.md
Rocket Examples
This directory contains projects showcasing Rocket's features.
Applications
-
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. -
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.
Feature Examples
-
config- Illustrates how to extract values from a RocketFigment, how to store and retrieve an application specific configuration in managed state usingAdHoc::config(), and how to set configuration values inRocket.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 ofsqlx,diesel, andrusqlite. Runs migrations automatically for the former two drivers. Usescontribdatabase support for the latter two drivers. -
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 customCounterfairing and usingAdHocfairings. -
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 likeunsafein 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,contentfor manually setting Content-Types, andEither. In the process, showcases usingTempFilefor raw uploads. Also illustrates the creation of a custom, derivedResponder. -
serialization- Showcases JSON and MessagePack (de)serialization support incontribby implementing a CRUD-like message API in JSON and a simply read/echo API in MessagePack. -
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- UsescontribStaticFilesserve static files. Also creates asecondmanual yet safe version. -
templating- Illustrates usingcontribtemplatessupport with identical examples for handlebars and tera. -
testing- Uses Rocket'slocallibraries to test an application. Showcases necessary use of theasyncClient. 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. -
uuid- Uses UUID support incontrib, converting betweencontrib::Uuidtype and theuuidcrateUuid.