Commit Graph

18 Commits

Author SHA1 Message Date
Roger Mo 9dc70936a2 Fix typos in fairings guide: 'are are', 'build' -> 'built'. 2021-06-14 19:36:03 -07:00
Sergio Benitez 4c6562cd29 Drop 'Data' after sending a response, not before.
This allows responses to be sent to the client even when data is only
partially read, significantly improving the experience for the client
from one with a "connection closed" error to one with a proper response.
The consequence is a lifetime in 'Data'.

Though other non-lifetime-introducing solutions exist, the introduction
of a lifetime to 'Data' is a longstanding desire as it prevents
smuggling 'Data' into a longer-lived context. Use of 'Data' in that
context was unspecified with various runtime consequences. The addition
of a lifetime bound by the request prevents this error statically.

In summary, the changes are:
  * Clients receive responses even when data isn't fully read.
  * 'Data' becomes 'Data<'r>'. 'FromData' changes accordingly.
  * Route 'Outcome's are strictly tied to the request lifetime.

Tangentially, the invalid length form field validation error message has
improved to format length in byte units if it exceeds 1024.
2021-06-08 13:26:16 -07:00
Sergio Benitez 267cb9396f Introduce 'Singleton' fairings.
A singleton fairing is guaranteed to be the only instance of its type at
launch time. If more than one instance of a singleton fairing is
attached, only the last instance is retained.
2021-05-22 11:01:00 -07:00
Sergio Benitez 4f3511786c Introduce statically-enforced 'Rocket' phasing.
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.
2021-04-13 19:26:45 -07:00
Sergio Benitez fd8c9ce795 Use launch-inferred '_' in most example code. 2021-04-13 18:12:39 -07:00
Sergio Benitez ad36b769bc Rename 'rocket::ignite()' to 'rocket::build()'.
...because loading up a Rocket while it's ignited is a bad idea.

More seriously, because 'Rocket.ignite()' will become an "execute
everything up to here" method.
2021-04-08 01:07:52 -07:00
Sergio Benitez 0bdb6b7bc7 Remove 'attach' fairings. Add 'liftoff' fairings.
Launch fairings are now fallible and take the place of attach fairings,
but they are only run, as the name implies, at launch time.

This is is a fundamental shift from eager execution of set-up routines,
including the now defunct attach fairings, to lazy execution,
precipitated by the transition to `async`. The previous functionality,
while simple, caused grave issues:

  1. A instance of 'Rocket' with async attach fairings requires an async
     runtime to be constructed.
  2. The instance is accessible in non-async contexts.
  3. The async attach fairings have no runtime in which to be run.

Here's an example:

```rust
let rocket = rocket::ignite()
    .attach(AttachFairing::from(|rocket| async {
        Ok(rocket.manage(load_from_network::<T>().await))
    }));

let state = rocket.state::<T>();
```

This had no real meaning previously yet was accepted by running the
attach fairing future in an isolated runtime. In isolation, this causes
no issue, but when attach fairing futures share reactor state with other
futures in Rocket, panics ensue.

The new Rocket application lifecycle is this:

  * Build - A Rocket instance is constructed. No fairings are run.
  * Ignition - All launch fairings are run.
  * Liftoff - If all launch fairings succeeded, the server is started.

New 'liftoff' fairings are run in this third phase.
2021-04-07 23:09:00 -07:00
Sergio Benitez 7337321efb Take '&mut Data' in 'on_request' fairings.
Resolves #1438.
2020-10-20 20:22:32 -07:00
Jonathan Dickinson f3beb68491 Remove superfluous lifetimes in 'Fairing' methods. 2020-07-23 21:32:20 -07:00
Sergio Benitez adc79016cd Rearrange top-level exports. Use '#[launch]'.
This commits makes the following high-level changes:

  * 'ShutdownHandle' is renamed to 'Shutdown'.
  * 'Rocket::shutdown_handle()' is renamed to 'Rocket::shutdown()'.
  * '#[launch]` is preferred to '#[rocket::launch]'.
  * Various docs phrasings are improved.
  * Fixed various broken links in docs.

This commits rearranges top-level exports as follows:

  * 'shutdown' module is no longer exported.
  * 'Shutdown' is exported from the crate root.
  * 'Outcome' is not longer exported from the root.
  * 'Handler', 'ErrorHandler' are no longer exported from the root.
2020-07-22 16:10:02 -07:00
Jeb Rosen 2b3d8110f1 Use '#[rocket::launch]' in guide examples. 2020-07-11 10:07:37 -07:00
Jeb Rosen 2c82b3e1d5 Update and fix guide tests. 2020-07-11 10:07:37 -07:00
Jeb Rosen f2487ccec5 Update the guide for async-related API changes. 2020-07-11 09:24:29 -07:00
Sergio Benitez 95c981de79 Test all guide code examples.
Every code example is now fully runnable and testable. As a result, all
examples are now tested and include imports. Relevant imports are shown
by default. Code examples can be expanded to show all imports.

Fixes #432.
2020-02-15 04:02:19 -08:00
Noah Rosenzweig fb1f7482ee Fix typo in fairings guide: 'to the launch' -> 'to launch'. 2019-01-31 20:13:25 -08:00
Sergio Benitez 3903ffdb47 Update guide in full for current 0.4.0-dev. 2018-10-22 14:50:57 -07:00
Sergio Benitez 2d56af504d Fix broken site URLs and typos. 2018-10-16 04:01:17 -07:00
Sergio Benitez 26ee132782 Update site content for restructure. 2018-10-15 22:53:05 -07:00