Middlewares: execution order + docs (#156)

While documenting the execution order of middlewares, I realised that
the existing implementation resulted in some unintuitive behaviour (i.e.
a middleware would apply to all routes in the same `Blueprint`, even if
the middleware was registered after a route).
This PR changes the behaviour to align with the user's intuition.

## Internals

Refactorings lead to other refactorings: I had to change the internal
representation of a `Blueprint` to fix the issue with middlewares. I
took the opportunity to remove the `internals` module from `pavex`
entirely. It is now in a separate crate, `pavex_bp_schema`, which is not
exposed through `pavex`'s public API. It is an (implicit) dependency of
`Blueprint::persist` and `Blueprint::load`.

doc_examples/guide/middleware/core_concepts/project-basic.snap

@@ -0,0 +1,15 @@
+```rust title="src/core/mw.rs"
+use pavex::middleware::Next;
+use pavex::response::Response;
+use std::future::IntoFuture;
+
+pub async fn middleware<C>(next: Next<C>) -> Response
+where
+    C: IntoFuture<Output = Response>,
+{
+    println!("Before the handler");
+    let response = next.await;
+    println!("After the handler");
+    response
+}
+```

doc_examples/guide/middleware/core_concepts/project-error_handler.snap

@@ -0,0 +1,8 @@
+```rust title="src/fallible/errors.rs"
+use pavex::response::Response;
+use tokio::time::error::Elapsed;
+
+pub fn timeout_error_handler(_e: &Elapsed) -> Response {
+    Response::internal_server_error()
+}
+```

doc_examples/guide/middleware/core_concepts/project-fallible.snap

@@ -0,0 +1,14 @@
+```rust title="src/fallible/mw.rs"
+use pavex::middleware::Next;
+use pavex::response::Response;
+use std::future::IntoFuture;
+use tokio::time::error::Elapsed;
+
+pub async fn timeout<C>(next: Next<C>) -> Result<Response, Elapsed>
+where
+    C: IntoFuture<Output = Response>,
+{
+    let max_duration = std::time::Duration::from_secs(20);
+    tokio::time::timeout(max_duration, next.into_future()).await
+}
+```

doc_examples/guide/middleware/core_concepts/project-into_future.snap

@@ -0,0 +1,14 @@
+```rust title="src/logging/mw.rs" hl_lines="11"
+use pavex::middleware::Next;
+use pavex::response::Response;
+use std::future::IntoFuture;
+use tracing::Instrument;
+
+pub async fn middleware<C>(next: Next<C>) -> Response
+where
+    C: IntoFuture<Output = Response>,
+{
+    let span = tracing::info_span!("Request processing");
+    next.into_future().instrument(span).await
+}
+```

doc_examples/guide/middleware/core_concepts/project-mw_after_handler.snap

@@ -0,0 +1,13 @@
+```rust title="src/order2.rs" hl_lines="7 8 9"
+use pavex::blueprint::router::GET;
+use pavex::blueprint::Blueprint;
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.wrap(f!(crate::first));
+    bp.route(GET, "/", f!(crate::handler));
+    bp.wrap(f!(crate::second)); // (1)!
+    bp
+}
+```

doc_examples/guide/middleware/core_concepts/project-mw_after_nested.snap

@@ -0,0 +1,19 @@
+```rust title="src/order3.rs" hl_lines="7 8 9"
+use pavex::blueprint::router::GET;
+use pavex::blueprint::Blueprint;
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.wrap(f!(crate::first)); // (1)!
+    bp.nest(nested());
+    bp.wrap(f!(crate::second)); // (2)!
+    bp
+}
+
+pub fn nested() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET, "/", f!(crate::handler));
+    bp
+}
+```

doc_examples/guide/middleware/core_concepts/project-registration.snap

@@ -0,0 +1,12 @@
+```rust title="src/core/blueprint.rs" hl_lines="7"
+use pavex::blueprint::router::GET;
+use pavex::blueprint::Blueprint;
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.wrap(f!(crate::core::middleware));
+    bp.route(GET, "/", f!(crate::core::handler));
+    bp
+}
+```

doc_examples/guide/middleware/core_concepts/project-registration_with_error_handler.snap

@@ -0,0 +1,13 @@
+```rust title="src/fallible/blueprint.rs"
+use pavex::blueprint::router::GET;
+use pavex::blueprint::Blueprint;
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.wrap(f!(crate::fallible::timeout))
+        .error_handler(f!(crate::fallible::timeout_error_handler));
+        // [...]
+    bp
+}
+```

doc_examples/guide/middleware/core_concepts/project-signalers.snap

@@ -0,0 +1,30 @@
+```rust title="src/mw.rs"
+use pavex::middleware::Next;
+use pavex::response::Response;
+use std::future::IntoFuture;
+
+pub async fn first<C>(next: Next<C>) -> Response
+where
+    C: IntoFuture<Output = Response>,
+{
+    println!("First - start");
+    let r = next.await;
+    println!("First - end");
+    r
+}
+
+pub async fn second<C>(next: Next<C>) -> Response
+where
+    C: IntoFuture<Output = Response>,
+{
+    println!("Second - start");
+    let r = next.await;
+    println!("Second - end");
+    r
+}
+
+pub async fn handler() -> Response {
+    println!("Handler");
+    Response::ok()
+}
+```

doc_examples/guide/middleware/core_concepts/project-vanilla_order.snap

@@ -0,0 +1,13 @@
+```rust title="src/order1.rs"
+use pavex::blueprint::router::GET;
+use pavex::blueprint::Blueprint;
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.wrap(f!(crate::first));
+    bp.wrap(f!(crate::second));
+    bp.route(GET, "/", f!(crate::handler));
+    bp
+}
+```

doc_examples/guide/middleware/core_concepts/project/.gitignore

@@ -0,0 +1 @@
+/target