Commit Graph

2269 Commits

Author SHA1 Message Date
Sergio Benitez 801e04bd53 Log guard failures, potential misuses.
This commit includes changes that improve how and what Rocket logs
automatically. Rocket now logs:

  * All guard errors, indicating the failing guard kind and type.
  * A warning when a 'TempFile' is used as a data guard for a request
    that specifies a 'form' Content-Type.
  * Only the top/sub of a request's format.

This commit makes the following breaking changes:

  * '<T as FromData>::Error' must implement 'Debug'.

Furthermore, this commit restores the previous behavior of always
logging launch info. It further restores the unspecified behavior of
modifying logging state only when the set logger is Rocket's logger.
2021-04-23 19:19:39 -07:00
Sergio Benitez 08c0701bdc Clarify internal sentinel docs. 2021-04-23 19:19:39 -07:00
Jeb Rosen e1307ddf48 Ensure synchronous database connections are not dropped from inside async tasks.
Fixes #1610.
2021-04-21 14:51:55 -07:00
Samuele Esposito c858bd2873 Fix typo in the guide. 2021-04-20 17:26:11 -07:00
Antoine Martin f6749e1b44 Fix misspelled link in '#[route]' attribute docs. 2021-04-20 17:26:08 -07:00
Sergio Benitez dd0c036461 Allow 'T: Deserialize' in JSON, MessagePack forms.
Previously, 'T: DeserializeOwned' was required needlessly. This allowed
'Json' and 'MsgPack' to borrow from the request.
2021-04-16 01:51:31 -07:00
Sergio Benitez 64e46b7107 Introduce sentinels: auto-discovered launch abort.
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.
2021-04-16 01:44:53 -07:00
Sergio Benitez 1872818570 Support type generics in 'Responder' derive. 2021-04-16 01:22:11 -07:00
Sergio Benitez fe4d0425e6 Remove unnecessary second 'Handler' lifetimes. 2021-04-14 22:17:21 -07:00
Sergio Benitez c49585bb39 Update examples on site index and overview. 2021-04-14 22:17:15 -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 887b2aed87 Move catcher, route types into eponymous modules.
In the course, significantly improve their documentation.
2021-04-13 18:58:05 -07:00
Sergio Benitez 4c96ae7b52 Add 'Rocket.toml' to templating example.
This allows 'template_dir' to be relative to the workspace as opposed to
relative to the CWD.
2021-04-13 18:20:41 -07:00
Sergio Benitez 7d5f7db9f4 Default 'pool_size' to 'workers * 4'.
The previous default was 'workers * 2'.
2021-04-13 18:19:14 -07:00
Sergio Benitez 33cff5938c Export 'const's for 'Config' parameter names. 2021-04-13 18:15:35 -07:00
Sergio Benitez fd8c9ce795 Use launch-inferred '_' in most example code. 2021-04-13 18:12:39 -07:00
Sergio Benitez c924ff7591 Impl 'Hash', 'Eq', 'PartialEq<&str>' for 'Origin'. 2021-04-13 17:45:41 -07:00
Sergio Benitez d7d7bb91ec Implement a more performant 'ReaderStream'. 2021-04-13 17:45:09 -07:00
Sergio Benitez dd1b51f681 Optimistically wait-free retry failed 'accept()'. 2021-04-13 17:42:05 -07:00
Sergio Benitez f8047f3d34 Improve 'local_cache!' example. 2021-04-13 17:41:10 -07:00
Sergio Benitez c16105dc58 Impl 'DerefMut', 'inner_mut()' for 'LocalRequest'. 2021-04-13 17:40:22 -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 50c9e88cf9 Completely revamp, redo examples.
The new examples directory...

  * Contains a `README.md` explaining each example.
  * Consolidates examples into more complete chunks.
  * Is just better.

Resolves #1447.
2021-04-07 23:09:05 -07:00
Sergio Benitez cfd5af38fe Set better default 'diesel::SQLite' options.
The options set WAL, a 1s busy timeout, and enables foreign keys.

This also adds a focused 'databases::Config::figment()', used to
retrieve a focused figment for a given config.
2021-04-07 23:09:05 -07:00
Sergio Benitez 5f568599a9 Log errors in 'Connection::get_one()'. 2021-04-07 23:09:05 -07:00
Sergio Benitez 5931d6704b Split 'AdHoc::on_launch' into two by fallibility.
The new 'AdHoc::try_on_launch()' replaces the previous 'on_launch'. The
new 'on_launch' returns a 'Rocket' directly.
2021-04-07 23:09:05 -07:00
Sergio Benitez 1c70df052c Return 422 for semantically bad Json, MessagePack. 2021-04-07 23:09:05 -07:00
Sergio Benitez c45a83897f Allow several 'field' attributes in all derives.
In particular, 'FromFormField' and 'UriDisplayQuery' now allow any
number of form 'field' attributes. For the former, multiple 'value's are
allowed, all of which are used to match against incoming fields - any
match wins. For the latter, multiple 'name' and 'value's are allowed;
the first of each is used to render the query value.

Additionally, 'UriDisplayQuery' can now be derived for C-like enums.
This brings the derive to parity with 'FromFormValue' and allows their
unified application on C-like enums.

Resolves #843.
2021-04-07 23:09:05 -07:00
Sergio Benitez fd03417188 Emit a dummy 'Origin' in failed 'uri!' expansions.
This significantly reduces the number of spurious, fallout compiler
errors when the 'uri!' macros fails.
2021-04-07 23:09:05 -07:00
Sergio Benitez 3535d08ff8 Impl 'FromFormField' for 'Cow', 'Capped<Cow>'. 2021-04-07 23:09:05 -07:00
Sergio Benitez e157904524 Parse empty bool values as 'true'.
This allows a field 'f: bool' to parse as true for the query '?f'.
2021-04-07 23:09:05 -07:00
Sergio Benitez b29b7bf413 Clarify non-specificity driven collisions. 2021-04-07 23:09:05 -07:00
Sergio Benitez 49b65c3ccc Filter out 'r2d2' log messages in non-debug. 2021-04-07 23:09:05 -07:00
Sergio Benitez 8d28e845d9 Rename 'Flash' 'name', 'msg' to 'kind', 'message'.
This is now consistent with the serialization of 'Flash' and better
illustrates the purpose of the late 'name' property.

Additionally, take 'Into<String>' instead of 'AsRef<str>' so we only
allocate when necessary.
2021-04-07 23:09:05 -07:00
Sergio Benitez 764ea06e90 Preserve non-'Config' values in 'Client::debug()'. 2021-04-07 23:09:05 -07:00
Sergio Benitez 8a2592c257 Use multithreaded runtime in blocking client.
The runtime uses a single worker thread. Using a multithreaded runtime
allows futures that require a multithreaded runtime to run.
2021-04-07 23:09:05 -07:00
Sergio Benitez 6ad14dc3f6 Takes URIs as 'TryInto<Origin>' in local client.
In particular, this allows passing in type-safe URIs constructed via the
'uri!' macro, which was not possible before.
2021-04-07 23:09:05 -07:00
Sergio Benitez cb4b8a3fef Add 'percent_encode', 'strip' methods to 'RawStr'. 2021-04-07 23:09:05 -07:00
Sergio Benitez e92b2adeaa Introduce 'RawStrBuf', use in 'Origin::map_path()'.
'RawStrBuf' is the owned analog of 'RawStr'. Thus, 'Cow<RawStr>' is
either 'RawStr' or 'RawStrBuf'.
2021-04-07 23:09:05 -07:00
Sergio Benitez c0564fa8dc Reexport, implement 'Responder' for 'Either'. 2021-04-07 23:09:04 -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 8d4d01106e Fix file name test for Windows. 2021-04-04 00:12:02 -07:00
Sergio Benitez c280a52a51 Fix compilation on Windows. 2021-04-03 19:40:58 -07:00
Sergio Benitez 579508d58f Make 'FileName' a DST. Improve sanitization.
Resolves #1594.
2021-04-03 17:09:00 -07:00
Jonah Brüchert fa1b75ba74 Allow accessing raw file name from 'DataField'. 2021-04-03 17:07:20 -07:00
Sergio Benitez 0654890e3d Add copy methods to 'TempFile'.
Resolves #1600.
2021-04-01 13:27:37 -07:00
Sergio Benitez 2893ce754d Introduce scoped catchers.
Catchers can now be scoped to paths, with preference given to the
longest-prefix, then the status code. This a breaking change for all
applications that register catchers:

  * `Rocket::register()` takes a base path to scope catchers under.
    - The previous behavior is recovered with `::register("/", ...)`.
  * Catchers now fallibly, instead of silently, collide.
  * `ErrorKind::Collision` is now `ErrorKind::Collisions`.

Related changes:

  * `Origin` implements `TryFrom<String>`, `TryFrom<&str>`.
  * All URI variants implement `TryFrom<Uri>`.
  * Added `Segments::prefix_of()`.
  * `Rocket::mount()` takes a  `TryInto<Origin<'_>>` instead of `&str`
    for the base mount point.
  * Extended `errors` example with scoped catchers.
  * Added scoped sections to catchers guide.

Internal changes:

  * Moved router code to `router/router.rs`.
2021-03-28 13:57:33 -07:00
Sergio Benitez c3bad3a287 Fix small typo in lib.rs. 2021-03-27 18:25:46 -07:00
Sergio Benitez feadb4dd16 Prefer '&str' in doc examples. 2021-03-27 16:25:39 -07:00
Sergio Benitez 3045e0ac63 Add doc notes on how to depend on '-dev' versions. 2021-03-27 14:20:43 -07:00