Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Revamp Tide, dropping Extractors and simplifying the framework
This commit reworks Tide, with the goal of reducing the total number of concepts
in the framework. The key new idea is to remove the notion of `Extractor`s, which
in turn allows us to remove or simplify several other concepts in Tide.
We'll first lay out the new design, and then discuss the tradeoffs made in this
simplification.
Here's a full list of the concepts in Tide after this commit:
| Concept | Description |
| ----- | ----------- |
| `App` | Builder for Tide applications |
| `Route` | Builder for an individual route |
| `Endpoint` | Trait for actual endpoints |
| `Context` | The request context for an endpoint |
| `IntoResponse` | A trait for converting into a `Response` |
| `Middleware` | A trait for Tide middleware |
Previously, the `Endpoint` trait was treated as a somewhat magical internal
abstraction, and we used a macro to provide `Endpoint` implementations for
actual endpoints (with varying numbers of extractor arguments).
In this commit, an `Endpoint` is just an asynchronous function from a `Context`
to a `Response`:
```rust
pub trait Endpoint<AppData>: Send + Sync + 'static {
/// The async result of `call`.
type Fut: Future<Output = Response> + Send + 'static;
/// Invoke the endpoint.
fn call(&self, cx: Context<AppData>) -> Self::Fut;
}
```
For convenience, this trait is implemented for async functions that return any
value that implements `IntoResponse`:
```rust
impl<AppData, F, Fut> Endpoint<AppData> for F
where
F: Fn(Context<AppData>) -> Fut,
Fut: Future
Fut::Output: IntoResponse,
// ...
```
This implementation is in contrast to the macro-generated implementations we
previously had, which allowed endpoints with varying numbers of `Extractor`
arguments. The intent is for endpoints to perform their own extraction directly
on the `Context`, as we'll see next.
The `Context` type contains all of the request and middleware context an
endpoint operates on. You can think of it as wrapping an `http_service::Request`
with some additional data.
It's easiest to understand `Context` through the APIs it provides. First, we have
methods for getting basic http request information, mirroring the `http` APIs:
```rust
impl<AppData> Context<AppData> {
pub fn method(&self) -> &Method;
pub fn uri(&self) -> &Uri;
pub fn version(&self) -> Version;
pub fn headers(&self) -> &HeaderMap;
}
```
The context also has a handle to application data, which typically would store
database connection pools and other "application-global" state. This API
replaces the old `AppData` extractor:
```rust
impl<AppData> Context<AppData> {
pub fn app_data(&self) -> &AppData {
&self.app_data
}
}
```
Similarly, we provide a *direct* API for extracting any "route parameters"
(i.e. placeholders in the route URL), replacing the need for `NamedSegment` and
the like:
```rust
impl<AppData> Context<AppData> {
pub fn route_param(&self, key: &str) -> Option<&str>;
}
```
Basic body extraction is likewise built in via `Context` methods, replacing the
`Str`, `Bytes`, and `Json` extractors:
```rust
impl<AppData> Context<AppData> {
pub async fn body_bytes(&mut self) -> std::io::Result<Vec<u8>>;
pub async fn body_string(&mut self) -> std::io::Result<String>;
pub async fn body_json<T: serde::de::DeserializeOwned>(&mut self) -> std::io::Result<T>;
}
```
Looking at the [message database example](https://github.com/rustasync/tide/blob/master/examples/messages.rs#L44),
we previously had endpoints like this:
```rust
async fn new_message(mut db: AppData<Database>, msg: body::Json<Message>) -> String {
db.insert(msg.clone()).to_string()
}
async fn set_message(
mut db: AppData<Database>,
id: head::Path<usize>,
msg: body::Json<Message>,
) -> Result<(), StatusCode> {
if db.set(*id, msg.clone()) {
Ok(())
} else {
Err(StatusCode::NOT_FOUND)
}
}
```
These endpoints would now be written something like this (where `Error` is
intended as a general error type, convertible into a response):
```rust
async fn new_message(cx: Context<Database>) -> Result<String, Error> {
let msg = await!(cx.body_json())?;
cx.app_data().insert(msg).to_string()
}
async fn set_message(cx: Context<Database>) -> Result<(), Error> {
let msg = await!(cx.body_json())?;
if cx.app_data().set(cx.route_param("id"), msg) {
Ok(())
} else {
Err(StatusCode::NOT_FOUND)
}
}
```
The endpoint code is a bit more verbose, but also arguably easier to follow,
since the extraction (and error handling) is more clear.
In addition, the basic extraction approach is *more discoverable*, since it
operates via normal methods on `Context`.
Part of the idea of the old `Extractor` trait was that Tide would provide an
*extensible* system of extractors; you could always introduce new types that
implement `Extractor`. But now most of the existing extractors are built-in
`Context` methods. How do we recover extensibility?
Easy: we use Rust's ability to extend existing types with new methods, via
traits! (Note: this is directly inspired by the Gotham framework).
Let's say we want to provide cookie extraction. Previously, we'd have a `Cookies`
type that you could use as an endpoint argument for extraction. Now, instead, we
can introduce a `Cookies` *trait* that's used to extend `Context` with new APIs:
```rust
trait Cookies {
fn cookies(&self) -> CookieJar;
}
impl<AppData> Cookies for Context<AppData> { ... }
```
This pattern is called an "extension trait" -- a trait whose sole purpose is to
extend an existing type with new methods. There are several nice properties of
this approach:
- The resulting extraction API is just a direct and natural as the built-in
ones: just a method call on the `Context` object.
- The methods that are available on `Context` are controlled by what traits are
in scope. In other words, if you want to use a custom extractor from the
ecosystem, you just bring its trait into scope, and then the method is
available. That makes it easy to build a robust ecosystem around a small set
of core Tide APIs.
One of the major benefits of moving extraction into the endpoint body, rather
than via `Extractor` arguments, is that it's much simpler to provide
configuration. For example, we could easily provide a customized json body
extractor that limited the maximum size of the body or other such options:
```rust
impl<AppData> Context<AppData> {
pub async fn body_json_cfg<T: serde::de::DeserializeOwned>(&mut self, cfg: JsonConfig) -> std::io::Result<T>;
}
```
As a result, we can drop much of the complexity in `App` around configuration.
Following the spirit of the changes to extractors, response generation for
non-standard Rust types is now just done via a free function:
```rust
mod response {
pub fn json<T: serde::Serialize>(t: T) -> Response { ... }
}
```
As before, there's a top-level `App` type for building up a Tide application.
However, the API has been drastically simplified:
- It no longer provides a configuration system, since extractors can now be
configured directly.
- It no longer allows for the middleware list to be customized per route;
instead, middleware is set up only at the top level.
These simplifications make the programming model much easier to understand;
previously, there were inconsistencies between the way that middleware nesting
and configuration nesting worked. The hope is that we can get away with this
much simpler, top-level model.
When actually adding routes via `at`, you get a `Route` object (which used to be
`Resource`). This object now provides a *builder-style* API for adding
endpoints, allowing you to chain several endpoints. Altogether, this means we
can drop nested routing as well.
The middleware trait is more or less as it was before, adjusted to use `Context`
objects and otherwise slightly cleaned up.
This commit also switches to using the route-recognizer crate, rather than the
path-table crate, as the underlying routing mechanism. In addition to being more
efficient, route-recognizer provides a more intuitive semantics for "ambiguous"
routing situations. See issue #12 and issue #141 for more details.- Loading branch information
