This commit improves the 'Error' type such that:
- It is now fully documented.
- The `ErrorKind` enum variant fields are all publicly reachable.
- The `Sentry` type is exposed.
This is a breaking change:
- `ErrorKind::Collisions` is now struct-like with two fields.
This commit:
- Removes painting outside trace subscriber in core.
- Removes all non-subscriber uses of yansi.
- Removes all uses of old log macros.
- Fix trace exports.
This commit allow routes to be declared for methods outside of the
standard HTTP method set. Specifically, it enables declaring routes for
any method in the IANA Method Registry:
```rust
#[route(LINK, uri = "/<foo>")]
fn link() { ... }
#[route("VERSION-CONTROL", uri = "/<foo>")]
fn version_control() { ... }
```
The `Method` type has gained variants for each registered method.
Breaking changes:
- `Method::from_str()` no longer parses mixed-case method names.
- `Method` is marked as non-exhaustive.
- `Method::supports_payload()` removed in favor of
`Method::allows_request_body()`.
Resolves#232.
This commit is a codebase-wide cleanup driven by clippy warnings. In
addition to fixing every reasonable warning, the following new
functionality was introduced:
* `Accept::new()` now takes any `T: Into<QMediaType>` iterator.
* `TempFile::is_empty()` was added.
* `HeaderMap` now implements `IntoIterator`.
This commit makes the following breaking changes:
* The `IntoCollection` trait is gone. Generics previously bound by the
trait are now bound by `IntoIterator`. This affects:
- `Accept::new()`
- `ContentType::with_params()`
- `Permission::{allow, allowed}()`
* `MediaType`, `QMediaType`, and `Allow` implement `IntoIterator`,
enabling most existing code to continue working without change.
* The inherent `HeaderMap::into_iter()` method was removed.
* The `Ok` variant in ErrorKind::Liftoff` is now `Box<Rocket<Orbit>>`.
This commit adds support for HTTP/3 and QUIC under a disabled-by-default
feature `http3-preview`. The current implementation depends on modified
versions of h3 and s2n-quic-h3 which will need to be upstreamed and
published before a release is possible.
During the course of development various facets of Rocket's internal
connection handling and recent listener APIs were improved. The complete
list of changes included in this PR is:
* A `shutdown` module was introduced.
* `config::Shutdown` was renamed to `ShutdownConfig` and moved to
`shutdown` while being re-exported from `config`.
* `ListenerAddr` is now called `Endpoint`. Various methods which
previously referred to "addresses" now refer to "endpoints".
* `Rocket::endpoint()` was renamed to `Rocket::endpoints()` and now
returns an iterator over the endpoints Rocket is listening on.
* `Endpoint` acquired various query utility methods.
* The `{set_}remote()` methods now take/produce `Endpoint`s.
* `TlsBindable` only accepts single-phase internal interfaces.
* Bind error messages include candidate endpoint info when possible.
* The warning message when a secret key is not configured now includes
information about its effect on private cookies.
Internal changes include:
* Config module tests were moved to `config/tests.rs`.
* The cancellable I/O implementation was significantly simplified.
* The `TripWire` implementation was simplified.
* Individual shutdown stages can now be awaited on via `Stages`.
* The `Shield` implementation was simplified.
Resolves#2723.
This commit exposes four new methods:
* `Route::collides_with(&Route)`
* `Route::matches(&Request)`
* `Catcher::collides_with(&Catcher)`
* `Catcher::matches(Status, &Request)`
Each method checks the corresponding condition: whether two routes
collide, whether a route matches a request, whether two catchers
collide, and whether a catcher matches an error arising from a request.
This functionality is used internally by Rocket to make routing
decisions. By exposing these methods, external libraries can use
guaranteed consistent logic to check the same routing conditions.
Resolves#1561.
This commit modifies request routing in a backwards incompatible manner.
The change is summarized as: trailing slashes are now significant and
never transparently disregarded. This has the following implications,
all representing behavior that differs from that before this change:
* Route URIs with trailing slashes (`/foo/`, `/<a>/`) are legal.
* A request `/foo/` is routed to route `/foo/` but not `/foo`.
* Similarly, a request `/bar/` is routed to `/<a>/` but not `/<a>`.
* A request `/bar/foo` is not routed to `/<a>/<b>/<c..>`.
A new `AdHoc::uri_normalizer()` fairing was added that recovers the
previous behavior.
In addition to the above, the `Options::NormalizeDirs` `FileServer`
option is now enabled by default to remain consistent with the above
changes and reduce breaking changes at the `FileServer` level.
The fuzzing target introduced in this commit attemps to assert
"collision safety". Formally, this is the property that:
matches(request, route) := request is matched to route
collides(route1, route2) := there is a a collision between routes
forall requests req. !exist routes r1, r2 s.t.
matches(req, r1) AND matches(req, r2) AND not collides(r1, r2)
Alternatively:
forall requests req, routes r1, r2.
matches(req, r1) AND matches(req, r2) => collides(r1, r2)
The target was run for 20 CPU hours without failure.
The net effect of this commit is three-fold:
* A request to `/` now matches `/<a>`. `/foo/` matches `/<a>/<b>`.
* A segment matched to a dynamic parameter may be empty.
* A request to `/foo/` no longer matches `/foo` or `/<a>`. Instead,
such a request would match `/foo/<a>` or `/foo/`.
The `&str` and `String` parameter guards were updated to reflect this
change: they now error, with a newly introduced error type `Empty` in
the `rocket::error` module, when the parameter is empty. As this was the
only built-in parameter guard that would be effected by this change (all
other guards already required nonempty parameters to succeed), the
majority of applications will see no effect as a result.
For applications wanting the previous functionality, a new
`AdHoc::uri_normalizer()` fairing was introduced.
* Trailing slashes are now allowed in all normalized URI paths, except
for route attribute URIs: `/foo/` is considered normalized.
* Query parts of URIs may now be empty: `/foo?` and `/foo/?` are now
considered normalized.
* The `base` field of `Catcher` is now only accessible via a new
getter method: `Catcher::base()`.
* `RawStr::split()` returns a `DoubleEndedIterator`.
* Introduced a second normalization for `Origin`, "nontrailing", and
associated methods: `Origin::normalize_nontrailing()`, and
`Origin::is_normalized_nontrailing()`.
* Added `Origin::has_trailing_slash()`.
* The `Segments<Path>` iterator will now return an empty string if
there is a trailing slash in the referenced path.
* `Segments::len()` is now `Segments::num()`.
* Added `RawStr::trim()`.
Resolves#2512.
This commit entirely rewrites Rocket's URI parsing routines and
overhauls the 'uri!' macro resolving all known issues and removing any
potential limitations for compile-time URI creation. This commit:
* Introduces a new 'Reference' URI variant for URI-references.
* Modifies 'Redirect' to accept 'TryFrom<Reference>'.
* Introduces a new 'Asterisk' URI variant for parity.
* Allows creation of any URI type from a string literal via 'uri!'.
* Enables dynamic/static prefixing/suffixing of route URIs in 'uri!'.
* Unifies 'Segments' and 'QuerySegments' into one generic 'Segments'.
* Consolidates URI formatting types/traits into a 'uri::fmt' module.
* Makes APIs more symmetric across URI types.
It also includes the following less-relevant changes:
* Implements 'FromParam' for a single-segment 'PathBuf'.
* Adds 'FileName::is_safe()'.
* No longer reparses upstream request URIs.
Resolves#842.
Resolves#853.
Resolves#998.
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.
...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`.
This surfaced a dormant concurrency related issue. Prior to this commit,
the router used `routed_segments()` to retrieve the path segments of the
request. This was okay as there was no route in the request, and matched
segments were retrieved eagerly.
This commit makes segment matching lazy, so no matching occurs if
unnecessary. Between two matches, a `route` is atomically set of
`Request`. This is now visible in `routed_segments()`, which should not
have considered the current route in the first place. This was fixed.
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 changes core routing so that '<path..>' in a route URI matches zero
or more segments. Previously, '<path..>' matched _1_ or more.
* Routes '$a' and '$b/<p..>' collide if $a and $b previously collided.
* For example, '/' now collides with '/<p..>'.
* Request '$a' matches route '$b/<p..>' if $a previously matched $b.
* For example, request '/' matches route '/<p..>'.
Resolves#985.
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.
Prior to this commit, it was impossible to 'use' a route from a separate
namespace for use in a 'routes!' macro. Naturally, this was a common
source of confusion amongst users. This commit obviates this deficiency
by generating a "proxy" structure that can be imported and converted
into a 'Route'/'Catcher' or their static variants.
This change is largely backwards compatible but can break existing code
when routes are named identically to other types in the namespace.
The bulk of the changes in this commit are for creating an
'ErrorHandler' trait that works like the 'Handler' trait, but for
errors. Furthermore, Rocket's default catcher now responds with a JSON
payload if the preferred 'Accept' media type is JSON.
This commit also fixes a bug in 'LocalRequest' where the internal
'Request' contained an correct 'URI'.
This commit aims to make it impossible to modify a 'Route' structure in
a way that violates expectations of a code-generated 'Route'. It removes
'Route::set_uri()' in favor of 'Route::map_base()', which allows for
safe modifications of the route's base.
In a similar vain, this commit also includes the following changes:
* 'Route::path()' was added to safely retrieve the route's 'path'.
* The base of a 'Route' is underlined during launch printing.
* 'Origin::into_normalized()' replaces 'Origin::to_normalized()'.
Fixes#1262.
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.
This is largely an internal change. Prior to this commit, the 'Manifest'
type, now replaced with the 'Cargo' type, robbed responsibility from the
core 'Rocket' type. This new construction restores the previous
responsibility and makes it clear that 'Cargo' is _only_ for freezing,
and representing the stability of, Rocket's internal state.
In summary, this commit modifies 'Responder' so that:
* ..it is no longer 'async'. To accommodate, the 'sized_body' methods
in 'Response' and 'ResponseBuilder' are no longer 'async' and accept
an optional size directly. If none is supplied, Rocket will attempt
to compute the size, by seeking, before writing out the response.
The 'Body' type was also changed to differentiate between its sized
'Seek' and chunked body variants.
* ..'&Request' gains a lifetime: 'r, and the returned 'Response' is
parameterized by a new 'o: 'r. This allows responders to return
references from the request or those that live longer.
observed.
This is a prerequisite for async on_attach fairings. 'Rocket' is now a
builder wrapper around the 'Manifest' type, with operations being
applied when needed by 'launch()', 'Client::new()', or 'inspect()'.
'inspect()' returns an '&Manifest', which now provides the methods that
could be called on an '&Rocket'.
Also:
* Remove 'response::ResultFuture'.
* Re-export 'tokio' and 'futures' from the crate root.
* Make 'ResponseBuilder::sized_body()' and 'async fn'.
* Remove the 'Future' implementation for 'ResponseBuilder'.
* Add 'ResponseBuilder::finalize()' for finalizing the builder.
* Update 'tokio', 'tokio-rustls', and 'hyper'.
* Remove unused dependencies on some `futures-*` crates.
* Rework 'spawn_on', which is now 'serve'.
* Simplify Ctrl-C handling.
Use I/O traits and types from 'tokio-io' as much as possible.
A few adapters only exist in futures-io-preview and use
futures-tokio-compat as a bridge for now.
