NAME¶
Mojo::Message - HTTP message base class
SYNOPSIS¶
package Mojo::Message::MyMessage;
use Mojo::Base 'Mojo::Message';
sub cookies {...}
sub extract_start_line {...}
sub get_start_line_chunk {...}
DESCRIPTION¶
Mojo::Message is an abstract base class for HTTP messages based on RFC 7230
<
http://tools.ietf.org/html/rfc7230>, RFC 7231
<
http://tools.ietf.org/html/rfc7231> and RFC 2388
<
http://tools.ietf.org/html/rfc2388>.
EVENTS¶
Mojo::Message inherits all events from Mojo::EventEmitter and can emit the
following new ones.
finish¶
$msg->on(finish => sub {
my $msg = shift;
...
});
Emitted after message building or parsing is finished.
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;
...
});
Emitted when message building or parsing makes progress.
# Building
$msg->on(progress => sub {
my ($msg, $state, $offset) = @_;
say qq{Building "$state" at offset $offset};
});
# Parsing
$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)), '%';
});
ATTRIBUTES¶
Mojo::Message implements the following attributes.
content¶
my $msg = $msg->content;
$msg = $msg->content(Mojo::Content::Single->new);
Message content, defaults to a Mojo::Content::Single object.
default_charset¶
my $charset = $msg->default_charset;
$msg = $msg->default_charset('UTF-8');
Default charset used for form-data parsing, defaults to "UTF-8".
max_line_size¶
my $size = $msg->max_line_size;
$msg = $msg->max_line_size(1024);
Maximum start line size in bytes, defaults to the value of the
"MOJO_MAX_LINE_SIZE" environment variable or 10240 (10KB).
max_message_size¶
my $size = $msg->max_message_size;
$msg = $msg->max_message_size(1024);
Maximum message size in bytes, defaults to the value of the
"MOJO_MAX_MESSAGE_SIZE" environment variable or 10485760 (10MB).
Setting the value to 0 will allow messages of indefinite size. Note that
increasing this value can also drastically increase memory usage, should you
for example attempt to parse an excessively large message body with the
"body_params", "dom" or "json" methods.
version¶
my $version = $msg->version;
$msg = $msg->version('1.1');
HTTP version of message, defaults to 1.1.
METHODS¶
Mojo::Message inherits all methods from Mojo::EventEmitter and implements the
following new ones.
body¶
my $bytes = $msg->body;
$msg = $msg->body('Hello!');
Slurp or replace "content", Mojo::Content::MultiPart will be
automatically downgraded to Mojo::Content::Single.
body_params¶
my $params = $msg->body_params;
"POST" parameters extracted from
"application/x-www-form-urlencoded" or
"multipart/form-data" message body, usually a Mojo::Parameters
object. Note that this method caches all data, so it should not be called
before the entire message body has been received. Parts of the message body
need to be loaded into memory to parse "POST" parameters, so you
have to make sure it is not excessively large, there's a 10MB limit by
default.
# Get POST parameter value
say $msg->body_params->param('foo');
body_size¶
my $size = $msg->body_size;
Content size in bytes.
build_body¶
my $bytes = $msg->build_body;
Render whole body.
my $bytes = $msg->build_headers;
Render all headers.
build_start_line¶
my $bytes = $msg->build_start_line;
Render start line.
cookie¶
my $cookie = $msg->cookie('foo');
my ($foo, $bar) = $msg->cookie(['foo', 'bar']);
Access message cookies, usually Mojo::Cookie::Request or Mojo::Cookie::Response
objects. If there are multiple cookies sharing the same name, and you want to
access more than just the last one, you can use "every_cookie". Note
that this method caches all data, so it should not be called before all
headers have been received.
# Get cookie value
say $msg->cookie('foo')->value;
cookies¶
my $cookies = $msg->cookies;
Access message cookies. Meant to be overloaded in a subclass.
dom¶
my $dom = $msg->dom;
my $collection = $msg->dom('a[href]');
Turns message body into a Mojo::DOM object and takes an optional selector to
call the method "find" in Mojo::DOM on it right away, which returns
a Mojo::Collection object. Note that this method caches all data, so it should
not be called before the entire message body has been received. The whole
message body needs to be loaded into memory to parse it, so you have to make
sure it is not excessively large, there's a 10MB limit by default.
# Perform "find" right away
say $msg->dom('h1, h2, h3')->text;
# Use everything else Mojo::DOM has to offer
say $msg->dom->at('title')->text;
say $msg->dom->html->body->children->type->uniq;
error¶
my $err = $msg->error;
$msg = $msg->error({message => 'Parser error', advice => 500});
Get or set message error, an "undef" return value indicates that there
is no error.
every_cookie¶
my $cookies = $msg->every_cookie('foo');
Similar to "cookie", but returns all message cookies sharing the same
name as an array reference.
# Get first cookie value
say $msg->every_cookie('foo')->[0]->value;
every_upload¶
my $uploads = $msg->every_upload('foo');
Similar to "upload", but returns all file uploads sharing the same
name as an array reference.
# Get content of first uploaded file
say $msg->every_upload('foo')->[0]->asset->slurp;
my $bool = $msg->extract_start_line(\$str);
Extract start line from string. Meant to be overloaded in a subclass.
finish¶
$msg = $msg->finish;
Finish message parser/generator.
$msg = $msg->fix_headers;
Make sure message has all required headers.
get_body_chunk¶
my $bytes = $msg->get_body_chunk($offset);
Get a chunk of body data starting from a specific position.
my $bytes = $msg->get_header_chunk($offset);
Get a chunk of header data, starting from a specific position.
get_start_line_chunk¶
my $bytes = $msg->get_start_line_chunk($offset);
Get a chunk of start line data starting from a specific position. Meant to be
overloaded in a subclass.
my $size = $msg->header_size;
Size of headers in bytes.
my $headers = $msg->headers;
Message headers, usually a Mojo::Headers object.
is_finished¶
my $bool = $msg->is_finished;
Check if message parser/generator is finished.
is_limit_exceeded¶
my $bool = $msg->is_limit_exceeded;
Check if message has exceeded "max_line_size" or
"max_message_size".
json¶
my $value = $msg->json;
my $value = $msg->json('/foo/bar');
Decode JSON message body directly using Mojo::JSON if possible, an
"undef" return value indicates a bare "null" or that
decoding failed. An optional JSON Pointer can be used to extract a specific
value with Mojo::JSON::Pointer. Note that this method caches all data, so it
should not be called before the entire message body has been received. The
whole message body needs to be loaded into memory to parse it, so you have to
make sure it is not excessively large, there's a 10MB limit by default.
# Extract JSON values
say $msg->json->{foo}{bar}[23];
say $msg->json('/foo/bar/23');
parse¶
$msg = $msg->parse('HTTP/1.1 200 OK...');
Parse message chunk.
start_line_size¶
my $size = $msg->start_line_size;
Size of the start line in bytes.
text¶
my $str = $msg->text;
Retrieve "body" and try to decode it if a charset could be extracted
with "charset" in Mojo::Content.
to_string¶
my $str = $msg->to_string;
Render whole message.
upload¶
my $upload = $msg->upload('foo');
my ($foo, $bar) = $msg->upload(['foo', 'bar']);
Access "multipart/form-data" file uploads, usually Mojo::Upload
objects. If there are multiple uploads sharing the same name, and you want to
access more than just the last one, you can use "every_upload". Note
that this method caches all data, so it should not be called before the entire
message body has been received.
# Get content of uploaded file
say $msg->upload('foo')->asset->slurp;
uploads¶
my $uploads = $msg->uploads;
All "multipart/form-data" file uploads, usually Mojo::Upload objects.
SEE ALSO¶
Mojolicious, Mojolicious::Guides, <
http://mojolicio.us>.
