Document returning filters from functions about warp

[danbruder]

FYI for those of you coming to this thread - impl Filter<Extract = impl Reply> is allowed now!

[seanmonstar]

There's two ways to return a Filter from a function:

With impl Filter<Extract = T, Error = Rejection>

pub fn index() -> impl warp::Filter<Extract = (), Error = Rejection> {
    warp::path::index()
}

pub fn index_ok() -> impl warp::Filter<Extract = (StatusCode,), Error = Rejection> {
    index()
        .map(|| StatusCode::OK)
}

With Filter::boxed()

pub fn get_routes() -> BoxedFilter<(impl Reply,)> {
    some_filter()
        .or(some_other())
        .or(a_third)
        .with(my_log)
        // etc
        .boxed()
}

There's reasons you might pick one over the other.

• impl Filter
  • allows monomorphization, and so possibly better performance or optimizations.
• BoxedFilter
  • Uses dynamic dispatch, which can dramatic improve compile times.
  • You can't use nested impl Trait, so impl Filter<Extract = impl Reply> isn't legal Rust (yet). You can use with a concrete type, like BoxedFilter<impl Reply>.

[blm768]

That makes more sense. I'd looked at BoxedFilter, but I hadn't managed to figure out what type arguments to give it.
Do you think that this is a significant enough topic to have an example for it, or would it belong somewhere else in the documentation? I'd be happy to submit a PR with an example or doc updates.

[seanmonstar]

Yes, examples or docs are sorely needed. I've been meaning to flesh out the warp::test section of docs showing this off, but maybe there's better places.

And unfortunately, since trait specialization isn't stable, it isn't immediately obvious that a filter extracting just 1 value needs to set Extract = (Foo,), not Extract = Foo.

[blm768]

I can think of a couple of places in the docs that could be tweaked to give people with intermediate Rust experience enough to figure things out; an inline example of the correct type signature in BoxedFilter or Filter::boxed() might do it. I should be able to draft something up tomorrow.

[blm768]

Oh, wow. Just realized that Filter::boxed() already had examples. Apparently I need to learn how to read. But I've thrown together an example and put a basic example in the BoxedFilter docs, so I'll submit a PR.

[seanmonstar]

This was done, thanks!