This follows the completed graduation of stable contrib features into
core, removing 'rocket_contrib' in its entirety in favor of two new
crates. These crates are versioned independently of Rocket's core
libraries, allowing upgrades to dependencies without consideration for
versions in core libraries.
'rocket_dyn_templates' replaces the contrib 'templates' features. While
largely a 1-to-1 copy, it makes the following changes:
* the 'tera_templates' feature is now 'tera'
* the 'handlebars_templates' feature is now 'handlebars'
* fails to compile if neither 'tera' nor 'handlebars' is enabled
'rocket_sync_db_pools' replaces the contrib 'database' features. It
makes no changes to the replaced features except that the `database`
attribute is properly documented at the crate root.
This has the following nice benefits:
* The 'JsonValue' wrapper type is gone.
* 'Local{Request, Response}' natively support JSON/MessagePack.
* The 'json' and 'msgpack' limits are officially recognized.
* Soon, Rocket application will not require an explicit 'serde' dep.
This marks the beginning of the end of 'rocket_contrib'.
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.
The new examples directory...
* Contains a `README.md` explaining each example.
* Consolidates examples into more complete chunks.
* Is just better.
Resolves#1447.
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.
This allows us to test all of the "core" crates (and the guide) by
testing the root workspace, and all of the examples by testing in the
examples workspace.
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 reverts most of dea940c7 and d89c7024. The "fix" is to run
attach fairings on a new thread. If a runtime is already running, it is
used. Otherwise, the future is executed in a single-threaded executor.
In brief, this commit:
* Updates to the latest upstream 'cookie', fixing a memory leak.
* Make changes to 'CookieJar' observable only through 'pending()'.
* Deprecates 'Client::new()' in favor of 'Client::tracked()'.
* Makes 'dispatch()' on tracked 'Client's synchronize on cookies.
* Makes 'Client::untracked()' actually untracked.
This commit updates to the latest 'cookie' which removes support for
'Sync' cookie jars. Instead of relying on 'cookie', this commit
implements an op-log based 'CookieJar' which internally keeps track of
changes. The API is such that changes are only observable through
specialized '_pending()' methods.
The connection guard type generated by `#[database]` no longer
implements `Deref` and `DerefMut`. Instead, it provides an `async fn
run()` that gives access to the underlying connection on a closure run
through `spawn_blocking()`.
Additionally moves most of the implementation of `#[database]` out
of generated code and into library code for better type-checking.
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 commit adds the 'local::blocking' module and moves the existing
asynchronous testing to 'local::asynchronous'. It also includes several
changes to improve the local API, bringing it to parity (and beyond)
with master. These changes are:
* 'LocalRequest' implements 'Clone'.
* 'LocalResponse' doesn't implement 'DerefMut<Target=Response>'.
Instead, direct methods on the type, such as 'into_string()', can
be used to read the 'Response'.
* 'Response::body()' returns an '&ResponseBody' as opposed to '&mut
ResponseBody', which is returned by a new 'Response::body_mut()'.
* '&ResponseBody' implements 'known_size()` to retrieve a body's size,
if it is known.
Co-authored-by: Jeb Rosen <jeb@jebrosen.com>
The attribute is applied everywhere it can be across the codebase and is
the newly preferred method for launching an application. This commit
also makes '#[rocket::main]` stricter by warning when it is applied to
functions other than 'main'.
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'.
* body_string_wait and body_bytes_wait are removed; use `.await` instead
* `dispatch()` is now an async fn and must be .await-ed
* Add `#[rocket::async_test]` macro, similar in purpose to `tokio::test`
* Tests now use either `rocket::async_test(async { })` or
`#[rocket::async_test]` in order to `.await` the futures returned
from `dispatch()` and `body_{string,bytes}()`
* Update 'test.sh' to reflect the tests that should be passing.
Broken:
* Cloned dispatch and mut_dispatch() with a live previous response now both fail, due to a (partial) check for mutable aliasing in LocalRequest.
* Some tests are still failing and need example-specific changes.
This commits also implement the query reform from #608. It also consists
of many, many breaking changes. Among them are:
* Query parts in route paths use new query reform syntax.
* Routing for queries is now lenient.
- Default ranking has changed to reflect query reform.
* Format routing matching has been fixed.
- Routes with formats matching "accept" will always collide.
- Routes with formats matching "content-type" require requests to
have an equivalent content-type header to match.
- Requests with imprecise content-types are treated as not having a
content-type.
* Generated routes and catchers respect visibility modifiers.
* Raw getter methods from request were renamed and retooled.
- In particular, the index parameter is based on segments in the
route path, not dynamic parameters.
* The method-based attributes no longer accept a keyed 'path'.
* The 'rocket_codegen' crate is gone and will no longer be public.
* The 'FormItems' iterator emits values of type 'FormItem'.
- The internal form items' string can no longer be retrieved.
* In general, routes are more strictly validated.
* Logging from codegen now funnels through logging infrastructure.
* Routing has been optimized by caching routing metadata.
Resolves#93.
Resolves#608.
Resolves#693.
Resolves#476.
