4f3511786c
The core 'Rocket' type is parameterized: 'Rocket<P: Phase>', where
'Phase' is a newly introduced, sealed marker trait. The trait is
implemented by three new marker types representing the three launch
phases: 'Build', 'Ignite', and 'Orbit'. Progression through these three
phases, in order, is enforced, as are the invariants guaranteed by each
phase. In particular, an instance of 'Rocket' is guaranteed to be in its
final configuration after the 'Build' phase and represent a running
local or public server in the 'Orbit' phase. The 'Ignite' phase serves
as an intermediate, enabling inspection of a finalized but stationary
instance. Transition between phases validates the invariants required
by the transition.
All APIs have been adjusted appropriately, requiring either an instance
of 'Rocket' in a particular phase ('Rocket<Build>', 'Rocket<Ignite>', or
'Rocket<Orbit>') or operating generically on a 'Rocket<P>'.
Documentation is also updated and substantially improved to mention
required and guaranteed invariants.
Additionally, this commit makes the following relevant changes:
* 'Rocket::ignite()' is now a public interface.
* 'Rocket::{build,custom}' methods can no longer panic.
* 'Launch' fairings are now 'ignite' fairings.
* 'Liftoff' fairings are always run, even in local mode.
* All 'ignite' fairings run concurrently at ignition.
* Launch logging occurs on launch, not any point prior.
* Launch log messages have improved formatting.
* A new launch error kind, 'Config', was added.
* A 'fairing::Result' type alias was introduced.
* 'Shutdown::shutdown()' is now 'Shutdown::notify()'.
Some internal changes were also introduced:
* Fairing 'Info' name for 'Templates' is now 'Templating'.
* Shutdown is implemented using 'tokio::sync::Notify'.
* 'Client::debug()' is used nearly universally in tests.
Resolves #1154.
Resolves #1136.
|
||
|---|---|---|
| .. | ||
| 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 | ||
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.