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.

Author: aturon

Cargo.toml

@@ -15,10 +15,11 @@ version = "0.0.5"
 [dependencies]
 cookie = "0.11"
 futures-preview = "0.3.0-alpha.13"
+fnv = "1.0.6"
 http = "0.1"
 http-service = "0.1.4"
-path-table = "1.0.0"
 pin-utils = "0.1.0-alpha.4"
+route-recognizer = "0.1.12"
 serde = "1.0.80"
 serde_derive = "1.0.80"
 serde_json = "1.0.32"
@@ -46,3 +47,5 @@ basic-cookies = "0.1.3"
 juniper = "0.10.0"
 structopt = "0.2.14"
 http-service-mock = "0.1.0"
+serde = "1.0.80"
+serde_derive = "1.0.80"

examples/body_types.rs

@@ -1,56 +1,51 @@
-#![feature(async_await, futures_api)]
+#![feature(async_await, futures_api, await_macro)]
 
 #[macro_use]
 extern crate serde_derive;
-use tide::body;
+
+use tide::{
+    error::ResultExt,
+    forms::{self, ExtractForms},
+    response, App, Context, EndpointResult,
+};
 
 #[derive(Serialize, Deserialize, Clone, Debug)]
 struct Message {
     author: Option<String>,
     contents: String,
 }
 
-async fn echo_string(msg: body::Str) -> String {
-    println!("String: {}", *msg);
-    format!("{}", *msg)
-}
-
-async fn echo_string_lossy(msg: body::StrLossy) -> String {
-    println!("String: {}", *msg);
-    format!("{}", *msg)
-}
-
-async fn echo_vec(msg: body::Bytes) -> Vec<u8> {
-    println!("Vec<u8>: {:?}", *msg);
-    msg.to_vec()
-}
-
-async fn echo_bytes(msg: body::Bytes) -> body::Bytes {
-    println!("Bytes: {:?}", *msg);
+async fn echo_string(mut cx: Context<()>) -> String {
+    let msg = await!(cx.body_string()).unwrap();
+    println!("String: {}", msg);
     msg
 }
 
-async fn echo_json(msg: body::Json<Message>) -> body::Json<Message> {
-    println!("JSON: {:?}", *msg);
-
+async fn echo_bytes(mut cx: Context<()>) -> Vec<u8> {
+    let msg = await!(cx.body_bytes()).unwrap();
+    println!("Bytes: {:?}", msg);
     msg
 }
 
-async fn echo_form(msg: body::Form<Message>) -> body::Form<Message> {
-    println!("Form: {:?}", *msg);
+async fn echo_json(mut cx: Context<()>) -> EndpointResult {
+    let msg = await!(cx.body_json()).client_err()?;
+    println!("JSON: {:?}", msg);
+    Ok(response::json(msg))
+}
 
-    msg
+async fn echo_form(mut cx: Context<()>) -> EndpointResult {
+    let msg = await!(cx.body_form())?;
+    println!("Form: {:?}", msg);
+    Ok(forms::form(msg))
 }
 
 fn main() {
-    let mut app = tide::App::new(());
+    let mut app = App::new(());
 
     app.at("/echo/string").post(echo_string);
-    app.at("/echo/string_lossy").post(echo_string_lossy);
-    app.at("/echo/vec").post(echo_vec);
     app.at("/echo/bytes").post(echo_bytes);
     app.at("/echo/json").post(echo_json);
     app.at("/echo/form").post(echo_form);
 
-    app.serve();
+    app.serve("127.0.0.1:8000").unwrap();
 }

examples/catch_all.rs

@@ -1,14 +1,14 @@
 #![feature(async_await, futures_api)]
 
-async fn echo_path(path: tide::head::Path<String>) -> String {
-    format!("Your path is: {}", *path)
+use tide::Context;
+
+async fn echo_path(cx: Context<()>) -> String {
+    let path: String = cx.param("path").unwrap();
+    format!("Your path is: {}", path)
 }
 
 fn main() {
     let mut app = tide::App::new(());
-    app.at("/echo_path").nest(|router| {
-        router.at("*").get(echo_path);
-    });
-
-    app.serve();
+    app.at("/echo_path/:path*").get(echo_path);
+    app.serve("127.0.0.1:8000").unwrap();
 }

examples/cli_parsing.rs

@@ -1,18 +1,15 @@
 #![feature(async_await, futures_api)]
 
-use tide::Cookies;
+use tide::{cookies::ExtractCookies, Context};
 
 /// Tide will use the the `Cookies`'s `Extract` implementation to build this parameter.
 ///
-async fn hello_cookies(cookies: Cookies) -> String {
-    format!("hello cookies: {:?}", cookies)
+async fn hello_cookies(mut cx: Context<()>) -> String {
+    format!("hello cookies: {:?}", cx.cookie("hello"))
 }
 
 fn main() {
     let mut app = tide::App::new(());
     app.at("/").get(hello_cookies);
-
-    let address = "127.0.0.1:8000".to_owned();
-    println!("Server is listening on http://{}", address);
-    app.serve();
+    app.serve("127.0.0.1:8000").unwrap();
 }

examples/computed_values.rs

@@ -11,7 +11,7 @@ fn main() {
             .header("X-Server", "Tide"),
     );
 
-    app.at("/").get(async || "Hello, world!");
+    app.at("/").get(async move |_| "Hello, world!");
 
-    app.serve();
+    app.serve("127.0.0.1:8000").unwrap();
 }

examples/configuration.rs

@@ -3,26 +3,26 @@
 //
 // [the Juniper book]: https://graphql-rust.github.io/
 
-#![feature(async_await, futures_api)]
+#![feature(async_await, futures_api, await_macro)]
 
 use http::status::StatusCode;
 use juniper::graphql_object;
 use std::sync::{atomic, Arc};
-use tide::{body, App, AppData, IntoResponse, Response};
+use tide::{error::ResultExt, response, App, Context, EndpointResult};
 
-// First, we define `Context` that holds accumulator state. This is accessible as App data in
+// First, we define `Data` that holds accumulator state. This is accessible as App data in
 // Tide, and as executor context in Juniper.
 #[derive(Clone, Default)]
-struct Context(Arc<atomic::AtomicIsize>);
+struct Data(Arc<atomic::AtomicIsize>);
 
-impl juniper::Context for Context {}
+impl juniper::Context for Data {}
 
 // We define `Query` unit struct here. GraphQL queries will refer to this struct. The struct itself
 // doesn't have any associated data (and there's no need to do so), but instead it exposes the
 // accumulator state from the context.
 struct Query;
 
-graphql_object!(Query: Context |&self| {
+graphql_object!(Query: Data |&self| {
     // GraphQL integers are signed and 32 bits long.
     field accumulator(&executor) -> i32 as "Current value of the accumulator" {
         executor.context().0.load(atomic::Ordering::Relaxed) as i32
@@ -33,7 +33,7 @@ graphql_object!(Query: Context |&self| {
 // `Query`, but it provides the way to "mutate" the accumulator state.
 struct Mutation;
 
-graphql_object!(Mutation: Context |&self| {
+graphql_object!(Mutation: Data |&self| {
     field add(&executor, by: i32) -> i32 as "Add given value to the accumulator." {
         executor.context().0.fetch_add(by as isize, atomic::Ordering::Relaxed) as i32 + by
     }
@@ -45,23 +45,21 @@ type Schema = juniper::RootNode<'static, Query, Mutation>;
 
 // Finally, we'll bridge between Tide and Juniper. `GraphQLRequest` from Juniper implements
 // `Deserialize`, so we use `Json` extractor to deserialize the request body.
-async fn handle_graphql(
-    ctx: AppData<Context>,
-    query: body::Json<juniper::http::GraphQLRequest>,
-) -> Response {
-    let response = query.execute(&Schema::new(Query, Mutation), &ctx);
+async fn handle_graphql(mut cx: Context<Data>) -> EndpointResult {
+    let query: juniper::http::GraphQLRequest = await!(cx.body_json()).client_err()?;
+    let response = query.execute(&Schema::new(Query, Mutation), cx.app_data());
     let status = if response.is_ok() {
         StatusCode::OK
     } else {
         StatusCode::BAD_REQUEST
     };
-    body::Json(response).with_status(status).into_response()
+    let mut resp = response::json(response);
+    *resp.status_mut() = status;
+    Ok(resp)
 }
 
 fn main() {
-    let mut app = App::new(Context::default());
-
+    let mut app = App::new(Data::default());
     app.at("/graphql").post(handle_graphql);
-
-    app.serve();
+    app.serve("127.0.0.1:8000").unwrap();
 }

examples/cookie_extractor.rs

@@ -2,7 +2,6 @@
 
 fn main() {
     let mut app = tide::App::new(());
-    app.at("/").get(async || "Hello, world!");
-
-    app.serve();
+    app.at("/").get(async move |_| "Hello, world!");
+    app.serve("127.0.0.1:8000").unwrap();
 }