Mojo::Message - HTTPメッセージの基底クラス - Mojoliciousドキュメント日本語訳

名前

package Mojo::Message::MyMessage;
use Mojo::Base 'Mojo::Message';

sub cookies              {...}
sub extract_start_line   {...}
sub get_start_line_chunk {...}
sub start_line_size      {...}

説明

Mojo::Messageは、 RFC 7230、 RFC 7231、 RFC 2388、に基づく、 Mojo::Message::Requestや Mojo::Message::Responseなどの HTTPメッセージの抽象基底クラスです。

イベント

Mojo::MessageはMojo::EventEmitterからすべてのイベントを継承しており、次のイベントを発行することができます。

finish

$msg->on(finish => sub {
  my $msg = shift;
  ...
});

メッセージが構築され、解析が終了した後に発行されます。

my $before = time;
$msg->on(finish => sub {
  my $msg = shift;
  $msg->headers->header('X-Parser-Time' => time - $before);
});

progress

$msg->on(progress => sub {
  my $msg = shift;
  ...
});

メッセージが構築され、解析されているときに発行されます。

# 構築
$msg->on(progress => sub {
  my ($msg, $state, $offset) = @_;
  say qq{Building "$state" at offset $offset};
});

# 解析
$msg->on(progress => sub {
  my $msg = shift;
  return unless my $len = $msg->headers->content_length;
  my $size = $msg->content->progress;
  say 'Progress: ', $size == $len ? 100 : int($size / ($len / 100)), '%';
});

メソッド

Mojo::MessageはMojo::EventEmitterからすべてのメソッドを継承しており、次の新しいメソッドを実装しています。

body

my $bytes = $msg->body;
$msg      = $msg->body('Hello!');

contentを取得あるいは置換します。 Mojo::Content::MultiPartは自動的にMojo::Content::Singleをダウングレードされます。

body_params

my $params = $msg->body_params;

x-application-urlencoded,c,あるいはmultipart/form-data メッセージボディから展開されたPOSTパラメーター。通常はMojo::Parametersオブジェクトです。このメソッドはすべてのデータをキャッシュするので、完全なメッセージボディが到着する前に呼び出してはいけないということに注意してください。メッセージボディの各部分はPOSTパラメーターを解析するためにメモリ上にロードされるので、大きすぎないようにする必要があります。デフォルトで、リクエストに対して16MiBの制限と、レスポンスに対して2GiBの制限があります。

# POSTパラメーターの値を取得します
say $msg->body_params->param('foo');

body_size

my $size = $msg->body_size;

コンテンツのバイトサイズ。

build_body

my $bytes = $msg->build_body;

"get_body_chunk"で、ボディ全体を描画します。

build_headers

my $bytes = $msg->build_headers;

"get_header_chunk"で、すべてのヘッダーを描画します。

build_start_line

my $bytes = $msg->build_start_line;

"get_start_line_chunk"で、スタートラインを描画します。

cookie

my $cookie = $msg->cookie('foo');

メッセージのクッキーにアクセスします。通常はMojo::Cookie::RequestかMojo::Cookie::Responseオブジェクトです。もし同じ名前で共有されている複数のクッキーがあり、最後のひとつより多くの値にアクセスしたい場合は、 every_cookieを使うことができます。このメソッドはすべてのデータをキャッシュするので、すべてのヘッダーが到着する前によびだしてはいけないということに注意してください。

# クッキーの値を取得
say $msg->cookie('foo')->value;

cookies

my $cookies = $msg->cookies;

メッセージクッキーへのアクセス。サブクラスでオーバーロードされます。

dom

my $dom        = $msg->dom;
my $collection = $msg->dom('a[href]');

textからメッセージボディを取り出し、コンテンツをMojo::DOMオブジェクトに変換します。オプションでセレクタを与えるとすぐにfindを実行し、集合を返却します。これはMojo::Collectionオブジェクトです。このメソッドはすべてのデータをキャッシュするので、完全なメッセージボディが到着するまで、呼び出してはいけません。メッセージボデ全体がメモリ上にロードされるので、大きすぎないようにする必要があります。デフォルトで、リクエストに対して16MiBの制限と、レスポンスに対して2GiBの制限があります。

# "find"をすぐに実行
say $msg->dom('h1, h2, h3')->map('text')->join("\n");

# それ以外はMojo::DOMが提供するものを使う
say $msg->dom->at('title')->text;
say $msg->dom->at('body')->children->map('tag')->uniq->join("\n");

error

my $err = $msg->error;
$msg    = $msg->error({message => 'Parser error'});

エラーメッセージを取得、設定します。 undefという戻り値は、エラーが無かったことを意味します。

# 接続エラー、あるいは解析エラー
$msg->error({message => 'Connection refused'});

# 4xx/5xx レスポンス
$msg->error({message => 'Internal Server Error', code => 500});

every_cookie

my $cookies = $msg->every_cookie('foo');

cookieと似ていますが、同じ名前で共有されている、すべてのメッセージクッキーを、配列のリファレンスとして取得します。

# 最初のクッキーの値を取得
say $msg->every_cookie('foo')->[0]->value;

every_upload

my $uploads = $msg->every_upload('foo');

uploadと似ていますが、同じ名前で共有されているすべてのファイルアップロードを配列のリファレンスとして、取得します。

# 最初にアップロードされたファイルの内容を取得
say $msg->every_upload('foo')->[0]->asset->slurp;

extract_start_line

my $bool = $msg->extract_start_line(\$str);

文字列からスタートラインを抽出します。これはサブクラスでオーバーロードされます。

finish

$msg = $msg->finish;

メッセージの解析/生成を終了します。

fix_headers

$msg = $msg->fix_headers;

メッセーが現在のHTTPのバージョンに要求されるすべてのヘッダーを持っていることを確かにします。

get_body_chunk

my $string = $msg->get_body_chunk($offset);

特定の位置から開始して、ボディのデータの断片を取得します。コンテンツが動的に生成されている場合は、同じチャンクを二度取得することはできないことに注意してください。

get_header_chunk

my $string = $msg->get_header_chunk($offset);

特定の位置から開始して、ヘッダーのデータの断片を取得します。このメソッドはメッセージをファイナライズすることに注意してください。

get_start_line_chunk

my $string = $msg->get_start_line_chunk($offset);

特定の位置から開始して、スタートラインのデータの断片を取得します。サブクラスでオーバーロードされることが予定されています。

header_size

# 長いバージョン
my $headers = $msg->content->headers;

ヘッダーのバイトサイズ。このメソッドはメッセージをファイナライズすることに注意してください。

headers

my $headers = $msg->headers;
$msg    = $msg->headers(Mojo::Headers->new);

メッセージのヘッダ。通常はMojo::Headersオブジェクト。

# 長いバージョン
my $headers = $msg->content->headers;

is_finished

my $bool = $msg->is_finished;

メッセージの解析/生成が終了しているかどうかをチェックします。

is_limit_exceeded

my $bool = $msg->is_limit_exceeded;

メッセージがmax_line_sizeあるいはmax_message_size、Mojo::Contentの"max_buffer_size"、Mojo::Headersの"max_line_size"を超えていないかをチェックします。

json

my $value = $msg->json;
my $value = $msg->json('/foo/bar');

可能であればMojo::JSONを使ってJSONのメッセージボディを直接でコードします。 undefという戻り値は、生のnullあるいは、デコードが失敗したことを意味します。オプションとして、Mojo::JSON::Pointerを使って、JSONポインタで特定の値を抽出することができます。

このメソッドはすべてのデータをキャッシュするので、完全なメッセージボディが到着するまで、呼び出してはいけません。メッセージボデ全体がメモリ上にロードされるので、大きすぎないようにする必要があります。デフォルトで、リクエストに対して16MiBの制限と、レスポンスに対して2GiBの制限があります。

# JSONの値を抽出
say $msg->json->{foo}{bar}[23];
say $msg->json('/foo/bar/23');

parse

$msg = $msg->parse('HTTP/1.1 200 OK...');

メッセージの断片を解析します。

save_to

$msg = $msg->save_to('/some/path/index.html');

メッセージボディをファイルに保存します。

start_line_size

my $size = $msg->start_line_size;

スタートラインのバイトサイズ。サブクラスでオーバーロードすることが予定されています。

text

my $str = $msg->text;

bodyを取り出して、キャラクターセットがMojo::Contentのcharsetで抽出できれば、デコードしようと試みます。

to_string

my $string = $msg->to_string;

メッセージ全体を描画します。このメソッドは、メッセージをファイナライズすることと、コンテンツが動的に生成された場合は、同じメッセージを二回描画できないことに注意してください。

upload

my $upload = $msg->upload('foo');

multipart/form-dataでアップロードされたファイルにアクセスします。通常はMojo::Uploadです。もし同じ名前で共有される複数のアップロードがあるなら、最後のひとつの値より多くの値にアクセスしたい場合は、 every_uploadを使ってください。このメソッドはすべてのデータをキャッシュするので、完全なメッセージボディが到着する前に呼び出さないように注意する必要があります。

# アップロードされたファイルのコンテンツを取得
say $msg->upload('foo')->asset->slurp;

uploads

my $uploads = $msg->uploads;

multipart/form-dataアップロードされたすべてのファイル。通常はMojo::Uploadオブジェクトです。

# すべてのアップロードの名前
say $_->name for @{$msg->uploads};

参考

Mojolicious, Mojolicious::Guides, http://mojolicio.us.

(Mojolicious 8.12を反映。2019年5月23日)

関連情報