Module warp::filters::path

source ·
Expand description

Path Filters

The Filters here work on the “path” of requests.

  • path matches a specific segment, like /foo.
  • param tries to parse a segment into a type, like /:u16.
  • end matches when the path end is found.
  • path! 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:

// 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?

// 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:

// 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!

// 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.

// 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.

// 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.

// 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.

Modules§

Structs§

  • Exact
    A Filter matching an exact path segment.
  • FullPath
    Represents the full request path, returned by the full() filter.
  • Peek
    Represents the tail part of a request path, returned by the peek() filter.
  • Tail
    Represents the tail part of a request path, returned by the tail() filter.

Functions§