Posts tagged all

今日はAmon2-2.49のTriggerとPluggin。

Amon2::Trigger

クラスに対してもインスタンスに対してもフックがかけられ、それぞれ@Class::_trigger と $obj->{_trigger} を使って保存される。get_trigger_code を呼ぶと関連するハンドラを全て取得できるが、インスタンスに対して呼んだ場合はインスタンスに紐づくハンドラとそのクラスの継承ツリー上のクラスにぶら下がる全てのハンドラを得られる。ハンドラは親→子の順に並んでいる。厳密な順序に関しては、mro::get_linear_isa を使っているので現在設定されているmroの影響を受ける。

Amon2::Plugin::Web::

プラグインは $c->add_trigger でトリガを仕掛けたり、$c にメソッドを生やしたりしてYourProject::Web クラスを拡張する。

Web::FillInFormLite は$cにfillin_form メソッドを生やしてくれる。このメソッドに値をセットしておくとHTML_FILTER トリガーでフォームに値を埋めてくれる。

Amon2::Plugin::Web::NoCache はPragma とCache-Control ヘッダを設定するもので、AFTER_DISPATCH トリガーで処理される。

CSRFDefender はCSRF防止用のプラグインで、Sessionプラグインとの併用が前提*1。HTML_FILTER トリガーで<form>を見つけたら csrf_token というhiddenのinput要素を埋め込み、ここにセッションに保存されているトークンを埋め込む。BEFORE_DISPATCH トリガー内でPOSTされてきた*2トークンとセッション内のトークンを比較し、異なる場合は403ステータスで落とす。または手動で管理したい場合は、load_plugin 時の設定で no_validate_hook => 1 を渡してPOST時の自動チェックを抑止し、$cにget_csrf_defender_token と validate_csrf が生えているのでこれを使う。

HTTPSession は$cにsession() メソッドを生やし、こいつを呼ぶ度にHTTP::Session->new してインスタンスを作る。作られたインスタンスは$c->{'HTTP::Session'} に保管される。AFTER_DISPATCH トリガーで最後にresponse_filter と finalize する。HTTP::Session::Store:: と HTTP::Session::State:: はload_plugin 時に指定しておく必要がある。

PlackSessionとJSON はscaffold のコードではロードされない。PlackSessionは$cにsessionメソッドを生やして処理はPlack::Session にお任せ。

JSON は$c にrender_json を生やしてくれる。長いように見えるが、やっていることはブラウザごとのバットノウハウとセキュリティ絡みの考慮。Chrome表示の振り分けに利用されている X-Requested-With はjQuery などのフレームワークがセットする物なので、素のXMLHttpRequest を使う場合はこのヘッダをセットしてリクエストするようにしたほうがよい。

今日はAmon2-2.49のコンテキスト周りで、具体的には Amon2、Amon2::Web、Amon2::WebRequest、Amon2::WebResponse、ついでにAmon2::Config::Simple 。Dispatcher はこれらと粗結合なので、次回以降。他残っているのは、scaffoldのコードと、トリガーとプラグイン周り。

Amon2::Web と Amon2 の関係

Amon2::Web はAmon2(コンテキスト) を継承しておらず、コンストラクタも持っていない。YourProject::Web ではAmon2 と Amon2::Web の双方を継承して使う。という構造を考えると、Amon2::Web はAmon2 のサブクラスに対する Mix-in として働いていると見た方がわかりやすい。

Amon2::Web

scaffoldの YourProject/app.psgi内では YourProject::Web 内のto_app を呼んでPSGIアプリケーションを作成しているが、このメソッドの定義元はAmon2::Webであり、Amon2::Web がPSGIリクエストを処理する際のエントリポイントになっている。

生成されるPSGIアプリケーションは単純な物で、Amon2::Web::Request を作ってYourProject::Web->new をして、dispatch() を呼び出すだけ。ここで、Amon2::Web は1リクエスト1インスタンスのモデルを取っていることがわかる。dispatchを呼ぶ前後には BEFORE_DISPATCH と AFTER_DISPATCH という二つのトリガーがあり、呼ばれる。BEFORE_DISPATCH や dispatch() から返すレスポンスはPlack::Response のサブクラスを想定しており、Amon2::Web::Response もその1つとなっている。

YourProject::Web 内からレスポンスを返す方法として、Amon2::Web はredirect、res_404、renderの3つの方法を提供している。res_404 が最も単純で、404 Not Foundの画面を返すもの。これはAmon2::Web::Dispatcher:: 以下のクラスでも使っている。htmlもres_404 メソッドの中で定義されているので、404画面を置き換えたければYourProject::Web 内でこのメソッドをオーバーライドするのがいいと思われる。redirect はQUERY_STRING の扱いのためにコードは長いが302のレスポンスを返す以外の特別なことはしてない。render はcreate_view->render するだけ。create_view はYourProject::Web で自分で定義する必要がある(scaffoldに入っている)。HTML_FILTER のトリガはここで処理されるので、render 以外の方法でレスポンスを返すとHTML_FILTER トリガは呼ばれない。

Amon2::Web のやってることはこれだけ。リクエストをルーティングしたいときはdispatchメソッド内でAmon2::Web::Dispatcher:: へ処理を委譲する。その他の処理はプラグインをロードすることで実現する。その辺はscaffold にもデフォルトで書いてあるので、必要に応じていじくるとよい。

あと、Amon2::Web 内のencoding はhtmlやURLに含めるパラメータのエンコーディングを決めているので、UTF-8以外の文字コードを使いたければ encoding と html_content_type のメソッドをオーバーロードする。

Amon2::Web::Request, Response

Amon2::Response はマンマ Plack::Response。Amon2::Request はがっつりコードがあるように見えるが、これはparameters 系のメソッドを(バイト列ではなく)文字列を返すようにしているだけ。Plack::Request と同じ値が欲しければ、parameters_raw などを用いる。

ところで、Amon2::Web->url_for と Amon2::Web::Request->url_with の二つが存在してこれらがテンプレから使えるように YourProject::Web で設定されるが、これらは全く別もの。前者はベースURLを元にURLを作る物で、このアプリがルートにデプロイされない場合はこのメソッドを通してURLを作る必要がある。後者は現在のリクエストを元にQUERY_STRINGの部分だけ置き換え(もしくは追加した)リクエストを作る物で、Catalystに由来する。

Amon2

最後に、Amon2 クラスだが、これはコンテキストを表すクラス。言い換えれば、CLIでも使える機能をAmon2::Webから分離した物とも言え、プラグインのロードやコンフィグへのアクセスなどの機能を提供する。Amon2->context で現在のコンテキストを取得可能であり、WEBアプリだとYourProject::Web のインスタンスであり、CLIアプリだとAmon2クラス自身のインスタンスが入っている。

コンフィグ周りはAmon2::Config::Simple が面倒を見ているが、こいつはAmon2->mode_name と同じ名前の*.pl をdo して返す。この振る舞いが気に食わなければAmon2->mode_name とか Amon2->load_config をオーバーライドして動きを変えればよい。

load_plugin は指定されたプラグインをrequire してパラメータ(hash-ref)付きでinit() を呼ぶ。デフォルトでは Amon2::Plugin 以下のモジュール、+付きだと任意のパッケージ名のモジュールをロードするが、この仕事をしてるのは2.49の実装だとPlack::Util。プラグインはinit()メソッド内でコンテキストにメソッドを追加したりトリガを仕掛けたりして動作を拡張する。

load_plugins は一度に複数をload_plugin できる。Data::OptList::mkopt を噛ませてるお陰で、モジュール名とパラメータを混ぜた形式で指定ができる。

# YourProject::Web より
__PACKAGE__->load_plugins(
    'Web::FillInFormLite',
    'Web::NoCache', # do not cache the dynamic content by default
    'Web::CSRFDefender',
    'Web::HTTPSession' => {
        state => 'Cookie',
        store => HTTP::Session::Store::File->new(
            dir => File::Spec->tmpdir(),
        )
    },
);

ちなみに、base_dir と config は、2度目以降の呼び出しを高速にするために、初回実行時にサブクラス側で同名のメソッドを生やし、オーバーライドして自身を隠している。