Previously, if a panic occurred with an 'Error' on the stack, 'Error'
would panic as usual during unwinding. This resulted in a double panic.
This commit makes 'Error' detect if a panic is already occurring and
omits its own panic if it is.
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.
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.
...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.
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`.
Prior to this commit, it was not possible to test Rocket crates in
production mode without setting a global secret key or bypassing secret
key checking - the testing script did the latter. The consequence is
that it became impossible to test secret key related failures because
the tests passed regardless.
This commit undoes this. As a consequence, all tests are now aware of
the difference between debug and release configurations, the latter of
which validates 'secret_key' by default. New 'Client::debug()' and
'Client::debug_with()' simplify creating an instance of 'Client' with
configuration in debug mode to avoid undesired test failures.
The summary of changes in this commit are:
* Config 'secret_key' success and failure are now tested.
* 'secret_key' validation was moved to pre-launch from 'Config:from()'.
* 'Config::from()' only extracts the config.
* Added 'Config::try_from()' for non-panicking extraction.
* 'Config' now knows the profile it was extracted from.
* The 'Config' provider sets a profile of 'Config.profile'.
* 'Rocket', 'Client', 'Fairings', implement 'Debug'.
* 'fairing::Info' implements 'Copy', 'Clone'.
* 'Fairings' keeps track of, logs attach fairings.
* 'Rocket::reconfigure()' was added to allow modifying a config.
Internally, the testing script was refactored to properly test the
codebase with the new changes. In particular, it no longer sets a rustc
'cfg' to avoid secret-key checking.
Resolves#1543.
Fixes#1564.
This commit completely revamps the way that codegen handles route URI
"parameters". The changes are largely internal. In summary, codegen code
is better organized, better written, and less subject to error.
There are three breaking changes:
* `path` is now `uri` in `route` attribute: `#[route(GET, path = "..")]`
becomes `#[route(GET, uri = "..")]`.
* the order of execution for path and query guards relative to
each-other is now unspecified
* URI normalization now normalizes the query part as well.
Several error messages were improved. A couple of bugs were fixed:
* Prior to this commit, Rocket would optimistically try to parse every
segment of a URI as an ident, in case one was needed in the future.
A bug in rustc results in codegen "panicking" if the segment
couldn't _lex_ as an ident. This panic didn't manifest until far
after expansion, unfortunately. This wasn't a problem before as we
only allowed ident-like segments (ASCII), but now that we allow any
UTF-8, the bug surfaced. This was fixed by never attempting to parse
non-idents as idents.
* Prior to this commit, it was impossible to generate typed URIs for
paths that ignored path parameters via the recently added syntax
`<_>`: the macro would panic. This was fixed by, well, handling
these ignored parameters.
Some minor additions:
* Added `RawStr::find()`, expanding its `Pattern`-based API.
* Added an internal mechanism to dynamically determine if a `UriPart`
is `Path` or `Query`.
So. Many. Changes.
This is an insane commit: simultaneously one of the best (because of all
the wonderful improvements!) and one of the worst (because it is just
massive) in the project's history.
Routing:
* All UTF-8 characters are accepted everywhere in route paths. (#998)
* `path` is now `uri` in `route` attribute: `#[route(GET, path = "..")]`
becomes `#[route(GET, uri = "..")]`.
Forms Revamp
* All form related types now reside in a new `form` module.
* Multipart forms are supported. (resolves#106)
* Collections are supported in forms and queries. (resolves#205)
* Nested structures in forms and queries are supported. (resolves#313)
* Form fields can be ad-hoc validated with `#[field(validate = expr)]`.
* `FromFormValue` is now `FromFormField`, blanket implements `FromForm`.
* Form field values are always percent-decoded apriori.
Temporary Files
* A new `TempFile` data and form guard allows streaming data directly to a
file which can then be persisted.
* A new `temp_dir` config parameter specifies where to store `TempFile`.
* The limits `file` and `file/$ext`, where `$ext` is the file extension,
determines the data limit for a `TempFile`.
Capped
* A new `Capped` type is used to indicate when data has been truncated due to
incoming data limits. It allows checking whether data is complete or
truncated.
* `DataStream` methods return `Capped` types.
* `DataStream` API has been revamped to account for `Capped` types.
* Several `Capped<T>` types implement `FromData`, `FromForm`.
* HTTP 413 (Payload Too Large) errors are now returned when data limits are
exceeded. (resolves#972)
Hierarchical Limits
* Data limits are now hierarchical, delimited with `/`. A limit of `a/b/c`
falls back to `a/b` then `a`.
Core
* `&RawStr` no longer implements `FromParam`.
* `&str` implements `FromParam`, `FromData`, `FromForm`.
* `FromTransformedData` was removed.
* `FromData` gained a lifetime for use with request-local data.
* The default error HTML is more compact.
* `&Config` is a request guard.
* The `DataStream` interface was entirely revamped.
* `State` is only exported via `rocket::State`.
* A `request::local_cache!()` macro was added for storing values in
request-local cache without consideration for type uniqueness by using a
locally generated anonymous type.
* `Request::get_param()` is now `Request::param()`.
* `Request::get_segments()` is now `Request::segments()`, takes a range.
* `Request::get_query_value()` is now `Request::query_value()`, can parse any
`FromForm` including sequences.
* `std::io::Error` implements `Responder` like `Debug<std::io::Error>`.
* `(Status, R)` where `R: Responder` implements `Responder` by overriding the
`Status` of `R`.
* The name of a route is printed first during route matching.
* `FlashMessage` now only has one lifetime generic.
HTTP
* `RawStr` implements `serde::{Serialize, Deserialize}`.
* `RawStr` implements _many_ more methods, in particular, those related to the
`Pattern` API.
* `RawStr::from_str()` is now `RawStr::new()`.
* `RawStr::url_decode()` and `RawStr::url_decode_lossy()` only allocate as
necessary, return `Cow`.
* `Status` implements `Default` with `Status::Ok`.
* `Status` implements `PartialEq`, `Eq`, `Hash`, `PartialOrd`, `Ord`.
* Authority and origin part of `Absolute` can be modified with new
`Absolute::{with,set}_authority()`, `Absolute::{with,set}_origin()` methods.
* `Origin::segments()` was removed in favor of methods split into query and
path parts and into raw and decoded versions.
* The `Segments` iterator is smarter, returns decoded `&str` items.
* `Segments::into_path_buf()` is now `Segments::to_path_buf()`.
* A new `QuerySegments` is the analogous query segment iterator.
* Once set, `expires` on private cookies is not overwritten. (resolves#1506)
* `Origin::path()` and `Origin::query()` return `&RawStr`, not `&str`.
Codegen
* Preserve more spans in `uri!` macro.
* Preserve spans `FromForm` field types.
* All dynamic parameters in a query string must typecheck as `FromForm`.
* `FromFormValue` derive removed; `FromFormField` added.
* The `form` `FromForm` and `FromFormField` field attribute is now named
`field`. `#[form(field = ..)]` is now `#[field(name = ..)]`.
Contrib
* `Json` implements `FromForm`.
* `MsgPack` implements `FromForm`.
* The `json!` macro is exported as `rocket_contrib::json::json!`.
* Added clarifying docs to `StaticFiles`.
Examples
* `form_validation` and `form_kitchen_sink` removed in favor of `forms`.
* The `hello_world` example uses unicode in paths.
* The `json` example only allocates as necessary.
Internal
* Codegen uses new `exports` module with the following conventions:
- Locals starts with `__` and are lowercased.
- Rocket modules start with `_` and are lowercased.
- `std` types start with `_` and are titlecased.
- Rocket types are titlecased.
* A `header` module was added to `http`, contains header types.
* `SAFETY` is used as doc-string keyword for `unsafe` related comments.
* The `Uri` parser no longer recognizes Rocket route URIs.
This commit completely overhauls Rocket's configuration systems, basing
it on the new Figment library. It includes many breaking changes
pertaining to configuration. They are:
* "Environments" are replaced by "profiles".
* 'ROCKET_PROFILE' takes the place of 'ROCKET_ENV'.
* Profile names are now arbitrary, but 'debug' and 'release' are given
special treatment as default profiles for the debug and release
compilation profiles.
* A 'default' profile now sits along-side the meta 'global' profile.
* The concept of "extras" is no longer present; users can extract any
values they want from the configured 'Figment'.
* The 'Poolable' trait takes an '&Config'.
* The 'secrets' feature is disabled by default.
* It is a hard error if 'secrets' is enabled under the 'release'
profile and no 'secret_key' is configured.
* 'ConfigBuilder' no longer exists: all fields of 'Config' are public
with public constructors for each type.
* 'keep_alive' is disabled with '0', not 'false' or 'off'.
* Inlined error variants into the 'Error' structure.
* 'LoggingLevel' is now 'LogLevel'.
* Limits can now be specified in SI units: "1 MiB".
The summary of other changes are:
* The default config file can be configured with 'ROCKET_CONFIG'.
* HTTP/1 and HTTP/2 keep-alive configuration is restored.
* 'ctrlc' is now a recognized config option.
* 'serde' is now a core dependency.
* TLS misconfiguration errors are improved.
* Several example use '_' as the return type of '#[launch]' fns.
* 'AdHoc::config()' was added for simple config extraction.
* Added more documentation for using 'Limits'.
* Launch information is no longer treated specially.
* The configuration guide was rewritten.
Resolves#852.
Resolves#209.
Closes#1404.
Closes#652.
The user-facing changes effected by this commit are:
* The 'http::Cookies<'_>' guard is now '&http::CookieJar<'_>'.
* The "one-at-a-time" jar restriction is no longer imposed.
* 'CookieJar' retrieval methods return 'http::CookieCrumb'.
* The 'private-cookies' feature is now called 'secrets'.
* Docs flag private cookie methods with feature cfg.
* Local, async request dispatching is never serialized.
* 'Client::cookies()' returns the tracked 'CookieJar'.
* 'LocalResponse::cookies()' returns a 'CookieJar'.
* 'Response::cookies()' returns an 'impl Iterator'.
* A path of '/' is set by default on all cookies.
* 'SameSite=strict' is set by default on all cookies.
* 'LocalRequest::cookies()' accepts any 'Cookie' iterator.
* The 'Debug' impl for 'Request' prints the cookie jar.
Resolves#1332.
* Implement `std::error::Error` for the new Error type.
* Document the new Error type.
* Remove `LaunchError`'s implementation of `Error::description`, which is deprecated.
Types can now implement the new 'Listener' trait, which means they can
report the address they are listening on and asynchronously accept
connections. 'Connection's are read/write streams that can additionally
report the remote address.
Listener is implemented for 'tokio_net::tcp::TcpListener' and for
the new 'rocket_http::tls::TlsListener' based on 'tokio-rustls'.
The new private function 'Rocket::listen_on()' now does the main setup
for launch and is generic over a Listener. In the future, a more refined
version of the API can be exposed so that applications can implement
their own listeners.
Prior to this change, Rocket emitted "white" text in much of its logging
output. On terminals with light backgrounds, the text was nearly
illegible. This PR stops using white coloring altogether, opting instead
to use the terminal's default color albeit with bold styling. On dark
terminals, this will likely be a light color, and on light terminals,
this will likely be a dark color. The end result is that Rocket's
logging output should be readable everywhere.
Resolves#639.
This is fairly large commit with several entangled logical changes.
The primary change in this commit is to completely overhaul how URI
handling in Rocket works. Prior to this commit, the `Uri` type acted as
an origin API. Its parser was minimal and lenient, allowing URIs that
were invalid according to RFC 7230. By contrast, the new `Uri` type
brings with it a strict RFC 7230 compliant parser. The `Uri` type now
represents any kind of valid URI, not simply `Origin` types. Three new
URI types were introduced:
* `Origin` - represents valid origin URIs
* `Absolute` - represents valid absolute URIs
* `Authority` - represents valid authority URIs
The `Origin` type replaces `Uri` in many cases:
* As fields and method inputs of `Route`
* The `&Uri` request guard is now `&Origin`
* The `uri!` macro produces an `Origin` instead of a `Uri`
The strict nature of URI parsing cascaded into the following changes:
* Several `Route` methods now `panic!` on invalid URIs
* The `Rocket::mount()` method is (correctly) stricter with URIs
* The `Redirect` constructors take a `TryInto<Uri>` type
* Dispatching of a `LocalRequest` correctly validates URIs
Overall, URIs are now properly and uniformly handled throughout Rocket's
codebase, resulting in a more reliable and correct system.
In addition to these URI changes, the following changes are also part of
this commit:
* The `LocalRequest::cloned_dispatch()` method was removed in favor of
chaining `.clone().dispatch()`.
* The entire Rocket codebase uses `crate` instead of `pub(crate)` as a
visibility modifier.
* Rocket uses the `crate_visibility_modifier` and `try_from` features.
A note on unsafety: this commit introduces many uses of `unsafe` in the
URI parser. All of these uses are a result of unsafely transforming byte
slices (`&[u8]` or similar) into strings (`&str`). The parser ensures
that these casts are safe, but of course, we must label their use
`unsafe`. The parser was written to be as generic and efficient as
possible and thus can parse directly from byte sources. Rocket, however,
does not make use of this fact and so would be able to remove all uses
of `unsafe` by parsing from an existing `&str`. This should be
considered in the future.
Fixes#443.
Resolves#263.
The directory structure has changed to better isolate crates serving
core and contrib. The new directory structure is:
contrib/
lib/ - the contrib library
core/
lib/ - the core Rocket library
codegen/ - the "compile extension" codegen library
codegen_next/ - the new proc-macro library
examples/ - unchanged
scripts/ - unchanged
site/ - unchanged
This commit also removes the following files:
appveyor.yml - AppVeyor (Rust on Windows) is far too spotty for use
rustfmt.toml - rustfmt is, unfortunately, not mature enough for use
Finally, all example Cargo crates were marked with 'publish = false'.
Sergio Benitez
Jeb Rosen
Jacob Pratt
Marc Schreiber
Sean Stangl