warpのFilter定義

warpはRustのWebサーバーフレームワークの1つです。
gRPCフレームワークの Tonicと同じhyperの上に構築されています。

warpの特徴は、 Filterを用いたルーティング定義です。

従来のWebフレームワークは、Config定義でルーティングするものが主流ですが、warpは関数の組み合わせで定義します。

トップレベル定義

フィルタの関数の定義方法は自由ですが、ルートが増えてくると構造が分かりにくくなるため、個別の定義は別関数に切り出す構成が多くなるでしょう。

パスごとにルート定義する場合、以下のような構造になります。

fn routes() -> impl Filter<Extract = impl warp::Reply, Error = warp::Rejection> + Clone {

    warp::get()
        .and(page1())
        .or(page2())
        .or(page3())
        .or(page4())
        .or(page5())
        .recover(handle_rejection)
}

page1()からpage5()はサブフィルタとして定義します。
各フィルタの最終処理でそれぞれimpl warp::Reply(HTTPレスポンスを表すトレイト)を返す構造をとるとトラブルが少ないでしょう。

recover()はErr<warp::Rejection>を受け取った際の異常系レスポンスを処理するフィルタです。
一般的なResult型のコンビネータと同様に、right-hand sideの処理を集約できます。

recover()の使い方については、サンプルコードのhandle_rejection()の実装が参考になります。

ルートが増えてきた場合、トップレベルの定義を別の関数に分割できます。
その際の注意点は、戻り型をトップレベルに合わせることです。後述のBoxedFilterを返す関数では型が合わないケースがあります。

サブフィルタ

サブフィルタは、上流で該当条件を限定するフィルタを書き、下流でレスポンスを返すフィルタを書きます。

この例ではトップレベルのprefixと合わせて、Rails風に書けば/app/page1/:nameというpathにマッチするリクエストをハンドルしています。

マッチしない場合には、page1()の下流ハンドラは適用されず、or()で併記した別のサブフィルタでチェックされます。

なお、or()は上から順に評価されるため、条件の緩いフィルタを上に置くとより厳しいフィルタに到達しないので注意しましょう。
想定外のルートが適用されていると切り分けに手間どります。

後半のレンダリングでは、上流でキャプチャしたnameを引数にとる関数を定義しています。
この例では変数は1つですが、キャプチャした変数の数と引数のアリティは一致する必要があります。

fn page1() -> BoxedFilter<(impl warp::Reply, )> {
    let prefix = warp::path!("app" / ..);

    prefix
        .add(warp::path!("page1" / String))
        .map(render_page1)
        .boxed()
}

fn render_page1(name: String) -> (warp::reply::Html<String>, ) {
        (warp::reply::html(format!("<html><body><h1>Hello, {}!</h1></body></html>", name), )
}

boxed()は、BoxedFilter型を返すメソッドで、戻り値のシグネチャ簡素化のため、おそらく多用することになります。

なお、ハンドラに処理を渡すコンビネータは、Result型を踏襲しているため、 Result型のコンビネータに習熟しておくと良いでしょう。

map()や and_then()などがあります。 and_then()はエラーを返すことがあるケースで利用します。

map()とand_then()では戻り値の型が異なり、and_then()はTryFuture型を返す必要があるため、以下のようなシグネチャになります。

async fn render_page1(name: String) -> Result<(warp::reply::Html<String>, ), warp::Rejection> {
}

なおエラー型はRejectionに固定されています。

エラー処理

各フィルタに定義するwarpのレスポンスはResult<impl Reply, Rejection>という型です。
なお、404 NotFoundや403 ForbiddenなどのHTTPエラーレスポンスはOk(impl Reply)のバリアントです。

Rejectionは、例外処理のようなフロー制御のオブジェクトで、そのまま後続処理がなければUnhandledrejectionとなり500 InternalServerErrorを返します。

多くのアプリケーションは、500エラーを返すケースを限定したいはずです。
そこで、フィルタのrecover()メソッドを用いてOk(warp::reply::with_status(warp::reply(), warp::http:StatusCode:NOT_FOUND))のような値を返します。

充実したフィルタ

上の例では分かりやすさのためパス一致に絞りましたが、warpはビルトイン・フィルタが充実しており、HTTPメソッドやHTTPヘッダー、POSTのJSONリクエストボディなど多彩なパラメータを条件に利用できます。

また、レンダリングに用いるパラメータもRust関数で任意の加工が可能であるため、ルーティングが複雑になるほど実力を発揮します。

ものすごく複雑なロジックを書いたとしても、warp上で動作させる部分についてはきわめて高速かつ省リソースで処理できるはずです。
この点がwarpのハイライトと言えます。

各フィルタ実装のポイントとして、極力パスの判定を最初に終える(冒頭に定義する)ことが重要です。
一般的にパスごとに処理が異なるため、リクエストが適切なパスにルートされることが暗黙の前提になります。
この点を徹底しておかないと、どのフィルタに処理が渡っているのかが分からなくなり、デバッグが迷宮入りします。

ポイント

warpはルーティング・プロセスでリクエストからパラメータを柔軟に抽出する機能に特化したフレームワークです。
適切な設計には、まず理解度をひき上げることが有効です。

warp::Filterのドキュメントにフィルタの設計意図が多少書かれているため、理解の補助に使える
フィルタのコンビネータはResultと似ている。エラー型の主役は Rejectionとそのための rejectモジュール
戻り値の型が分かりにくいため、サブフィルタの関数が何を返すべきなのかに注意。コンパイルエラーが出る場合、コンパイラが検出した型をシグネチャに流用するのも一手
とくに正常系のレスポンスとして、タプルを常用している点が独特
パス判定が最重要。path()とpath!()は挙動が異なる
warp::post()などのビルトインフィルタは特定のメソッドのみに対応するため一見便利だが、405 Method Not Allowedを返すためアタックに対するヒントが増えてしまう。GET/POSTで2つのAPIを提供する場合以外は避けた方が良い