fd294049c7
This commit completely rewrites Rocket's HTTP serving. In addition to
significant internal cleanup, this commit introduces the following major
features:
* Support for custom, external listeners in the `listener` module.
The new `listener` module contains new `Bindable`, `Listener`, and
`Connection` traits which enable composable, external
implementations of connection listeners. Rocket can launch on any
`Listener`, or anything that can be used to create a listener
(`Bindable`), via a new `launch_on()` method.
* Support for Unix domain socket listeners out of the box.
The default listener backwards compatibly supports listening on Unix
domain sockets. To do so, configure an `address` of
`unix:path/to/socket` and optional set `reuse` to `true` (the
default) or `false` which controls whether Rocket will handle
creating and deleting the unix domain socket.
In addition to these new features, this commit makes the following major
improvements:
* Rocket now depends on hyper 1.
* Rocket no longer depends on hyper to handle connections. This allows
us to handle more connection failure conditions which results in an
overall more robust server with fewer dependencies.
* Logic to work around hyper's inability to reference incoming request
data in the response results in a 15% performance improvement.
* `Client`s can be marked secure with `Client::{un}tracked_secure()`,
allowing Rocket to treat local connections as running under TLS.
* The `macros` feature of `tokio` is no longer used by Rocket itself.
Dependencies can take advantage of this reduction in compile-time
cost by disabling the new default feature `tokio-macros`.
* A new `TlsConfig::validate()` method allows checking a TLS config.
* New `TlsConfig::{certs,key}_reader()`,
`MtlsConfig::ca_certs_reader()` methods return `BufReader`s, which
allow reading the configured certs and key directly.
* A new `NamedFile::open_with()` constructor allows specifying
`OpenOptions`.
These improvements resulted in the following breaking changes:
* The MSRV is now 1.74.
* `hyper` is no longer exported from `rocket::http`.
* `IoHandler::io` takes `Box<Self>` instead of `Pin<Box<Self>>`.
- Use `Box::into_pin(self)` to recover the previous type.
* `Response::upgrade()` now returns an `&mut dyn IoHandler`, not
`Pin<& mut _>`.
* `Config::{address,port,tls,mtls}` methods have been removed.
- Use methods on `Rocket::endpoint()` instead.
* `TlsConfig` was moved to `tls::TlsConfig`.
* `MutualTls` was renamed and moved to `mtls::MtlsConfig`.
* `ErrorKind::TlsBind` was removed.
* The second field of `ErrorKind::Shutdown` was removed.
* `{Local}Request::{set_}remote()` methods take/return an `Endpoint`.
* `Client::new()` was removed; it was previously deprecated.
Internally, the following major changes were made:
* A new `async_bound` attribute macro was introduced to allow setting
bounds on futures returned by `async fn`s in traits while
maintaining good docs.
* All utility functionality was moved to a new `util` module.
Resolves #2671.
Resolves #1070.
|
||
|---|---|---|
| .. | ||
| chat | ||
| config | ||
| cookies | ||
| databases | ||
| error-handling | ||
| fairings | ||
| forms | ||
| hello | ||
| manual-routing | ||
| pastebin | ||
| responders | ||
| serialization | ||
| state | ||
| static-files | ||
| templating | ||
| testing | ||
| tls | ||
| todo | ||
| upgrade | ||
| Cargo.toml | ||
| README.md | ||
Rocket Examples
This directory contains projects showcasing Rocket's features.
Applications
-
A simple, API-only pastebin application, similar to https://paste.rs. Stores pastes locally on the file system. Implements a custom parameter guard,
PasteId, to parse and validate paste identifiers. -
A todo app with a web UI to add, delete, and mark/unmark items. Uses a SQLite database driven by diesel. Runs migrations automatically at start-up. Uses tera to render templates.
-
A real-time, multi-room chat application using Server-Sent Events (SSE) and JavaScript's
EventSource. Supports automatic reconnection with exponential backoff and live connection status.
Feature Examples
-
config- Illustrates how to extract values from a RocketFigment, how to store and retrieve an application specific configuration in managed state usingAdHoc::config(), and how to set configuration values inRocket.toml. -
cookies- Uses cookies to create a client-side message box. Uses private cookies for a session-based authentication. -
databases- Implements a CRUD-like "blog" JSON API backed by a SQLite database driven by each ofsqlx,diesel, andrusqlite. Runs migrations automatically for the former two drivers. Usescontribdatabase support for all drivers (rocket_db_poolsfor the first;rocket_sync_db_poolsfor the other latter two). -
error-handling- Exhibits the use of scoped catchers; contains commented out lines that will cause a launch-time error with code to custom-display the error. -
fairings- Exemplifies creating a customCounterfairing and usingAdHocfairings. -
forms- Showcases all of Rocket's form support features including multipart file uploads, ad-hoc validations, field renaming, and use of form context for staged forms. -
hello- Basic example of Rocket's core features: route declaration with path and query parameters, both simple and compound, mounting, launching, testing, and returning simple responses. Also showcases using UTF-8 in route declarations and responses. -
manual-routing- An example eschewing Rocket's codegen in favor of manual routing. This should be seen as last-ditch effort, much likeunsafein Rust, as manual routing also eschews many of Rocket's automatic web security guarantees. -
responders- Illustrates the use of many of Rocket's built-in responders:Stream,Redirect,File,NamedFile,contentfor manually setting Content-Types, andEither. In the process, showcases usingTempFilefor raw uploads. Also illustrates the creation of a custom, derivedResponder. -
serialization- Showcases JSON and MessagePack (de)serialization support by implementing a CRUD-like message API in JSON and a simply read/echo API in MessagePack. Showcases UUID parsing support. -
state- Illustrates the use of request-local state and managed state. Uses request-local state to cache "expensive" per-request operations. Uses managed state to implement a simple index hit counter. Also uses managed state to store, retrieve, and push/pop from a concurrent queue. -
static-files- UsesFileServerto serve static files. Also creates asecondmanual yet safe version. -
templating- Illustrates usingcontribtemplatessupport with identical examples for handlebars and tera. -
testing- Uses Rocket'slocallibraries to test an application. Showcases necessary use of theasyncClient. Note that all examples contains tests, themselves serving as examples for how to test Rocket applications. -
tls- Illustrates configuring TLS with a variety of key pair kinds. -
upgrade- Uses the connection upgrade API to implement WebSocket support using tungstenite.