| addr.rs |
Socket Address filters. |
699 |
| any.rs |
A filter that matches any route. |
1831 |
| body.rs |
Body filters
Filters that extract a body for a route. |
10855 |
| compression.rs |
Compression Filters
Filters that compress the body of a response. |
8491 |
| cookie.rs |
Cookie Filters |
1380 |
| cors.rs |
CORS Filters |
18896 |
| ext.rs |
Request Extensions |
1101 |
| fs.rs |
File System Filters |
16608 |
| header.rs |
Header Filters
These filters are used to interact with the Request HTTP headers. Some
of them, like `exact` and `exact_ignore_case`, are just predicates,
they don't extract any values. The `header` filter allows parsing
a type from any header. |
6950 |
| host.rs |
Host ("authority") filter
|
3412 |
| log.rs |
Logger Filters |
7087 |
| method.rs |
HTTP Method filters.
The filters deal with the HTTP Method part of a request. Several here will
match the request `Method`, and if not matched, will reject the request
with a `405 Method Not Allowed`.
There is also [`warp::method()`](method), which never rejects
a request, and just extracts the method to be used in your filter chains. |
3846 |
| mod.rs |
Built-in Filters
This module mostly serves as documentation to group together the list of
built-in filters. Most of these are available at more convenient paths. |
629 |
| multipart.rs |
Multipart body filters
[`Filter`](crate::Filter)s that extract a multipart body for a route. |
6838 |
| path.rs |
Path Filters
The [`Filter`](crate::Filter)s here work on the "path" of requests.
- [`path`](./fn.path.html) matches a specific segment, like `/foo`.
- [`param`](./fn.param.html) tries to parse a segment into a type, like `/:u16`.
- [`end`](./fn.end.html) matches when the path end is found.
- [`path!`](../../macro.path.html) eases combining multiple `path` and `param` filters.
# Routing
Routing in warp is simple yet powerful.
First up, matching a single segment:
```
use warp::Filter;
// GET /hi
let hi = warp::path("hi").map(|| {
"Hello, World!"
});
```
How about multiple segments? It's easiest with the `path!` macro:
```
# use warp::Filter;
// GET /hello/from/warp
let hello_from_warp = warp::path!("hello" / "from" / "warp").map(|| {
"Hello from warp!"
});
```
Neat! But how do I handle **parameters** in paths?
```
# use warp::Filter;
// GET /sum/:u32/:u32
let sum = warp::path!("sum" / u32 / u32).map(|a, b| {
format!("{} + {} = {}", a, b, a + b)
});
```
In fact, any type that implements `FromStr` can be used, in any order:
```
# use warp::Filter;
// GET /:u16/times/:u16
let times = warp::path!(u16 / "times" / u16).map(|a, b| {
format!("{} times {} = {}", a, b, a * b)
});
```
Oh shoot, those math routes should be **mounted** at a different path,
is that possible? Yep!
```
# use warp::Filter;
# let sum = warp::any().map(warp::reply);
# let times = sum.clone();
// GET /math/sum/:u32/:u32
// GET /math/:u16/times/:u16
let math = warp::path("math");
let math_sum = math.and(sum);
let math_times = math.and(times);
```
What! `and`? What's that do?
It combines the filters in a sort of "this and then that" order. In fact,
it's exactly what the `path!` macro has been doing internally.
```
# use warp::Filter;
// GET /bye/:string
let bye = warp::path("bye")
.and(warp::path::param())
.map(|name: String| {
format!("Good bye, {}!", name)
});
```
Ah, so, can filters do things besides `and`?
Why, yes they can! They can also `or`! As you might expect, `or` creates a
"this or else that" chain of filters. If the first doesn't succeed, then
it tries the other.
So, those `math` routes could have been **mounted** all as one, with `or`.
```
# use warp::Filter;
# let sum = warp::path("sum");
# let times = warp::path("times");
// GET /math/sum/:u32/:u32
// GET /math/:u16/times/:u16
let math = warp::path("math")
.and(sum.or(times));
```
It turns out, using `or` is how you combine everything together into a
single API.
```
# use warp::Filter;
# let hi = warp::path("hi");
# let hello_from_warp = hi.clone();
# let bye = hi.clone();
# let math = hi.clone();
// GET /hi
// GET /hello/from/warp
// GET /bye/:string
// GET /math/sum/:u32/:u32
// GET /math/:u16/times/:u16
let routes = hi
.or(hello_from_warp)
.or(bye)
.or(math);
```
Note that you will generally want path filters to come **before** other filters
like `body` or `headers`. If a different type of filter comes first, a request
with an invalid body for route `/right-path-wrong-body` may try matching against `/wrong-path`
and return the error from `/wrong-path` instead of the correct body-related error. |
17345 |
| query.rs |
Query Filters |
2783 |
| reply.rs |
Reply Filters
These "filters" behave a little differently than the rest. Instead of
being used directly on requests, these filters "wrap" other filters.
## Wrapping a `Filter` (`with`)
```
use warp::Filter;
let with_server = warp::reply::with::header("server", "warp");
let route = warp::any()
.map(warp::reply)
.with(with_server);
```
Wrapping allows adding in conditional logic *before* the request enters
the inner filter (though the `with::header` wrapper does not). |
6839 |
| sse.rs |
Server-Sent Events (SSE)
# Example
```
use std::time::Duration;
use std::convert::Infallible;
use warp::{Filter, sse::Event};
use futures_util::{stream::iter, Stream};
fn sse_events() -> impl Stream<Item = Result<Event, Infallible>> {
iter(vec![
Ok(Event::default().data("unnamed event")),
Ok(
Event::default().event("chat")
.data("chat message")
),
Ok(
Event::default().id(13.to_string())
.event("chat")
.data("other chat message\nwith next line")
.retry(Duration::from_millis(5000))
)
])
}
let app = warp::path("push-notifications")
.and(warp::get())
.map(|| {
warp::sse::reply(warp::sse::keep_alive().stream(sse_events()))
});
```
Each field already is event which can be sent to client.
The events with multiple fields can be created by combining fields using tuples.
See also the [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) API,
which specifies the expected behavior of Server Sent Events.
|
14314 |
| trace.rs |
[`tracing`] filters.
[`tracing`] is a framework for instrumenting Rust programs to
collect scoped, structured, and async-aware diagnostics. This module
provides a set of filters for instrumenting Warp applications with `tracing`
spans. [`Spans`] can be used to associate individual events with a request,
and track contexts through the application.
[`tracing`]: https://crates.io/crates/tracing
[`Spans`]: https://docs.rs/tracing/latest/tracing/#spans |
8963 |
| ws.rs |
Websockets Filters |
13097 |