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 as described in RFC
2616 and RFC 2388.
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.
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 5242880. 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!');
my $cb = $msg->body(sub {...});
Access "content" data or replace all subscribers of the
"read" event.
$msg->body(sub {
my ($msg, $bytes) = @_;
say "Streaming: $bytes";
});
body_params¶
my $params = $msg->body_params;
"POST" parameters extracted from "x-application-urlencoded",
"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.
# 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 @cookies = $msg->cookie('foo');
Access message cookies, usually Mojo::Cookie::Request or Mojo::Cookie::Response
objects. 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
perform a "find" 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.
# Perform "find" right away
say $msg->dom('h1, h2, h3')->pluck('text');
# Use everything else Mojo::DOM has to offer
say $msg->dom->at('title')->text;
say $msg->dom->html->body->children->pluck('type')->uniq;
error¶
my $err = $msg->error;
my ($err, $code) = $msg->error;
$msg = $msg->error('Parser error');
$msg = $msg->error('Parser error', 500);
Error and code.
my $success = $msg->extract_start_line(\$string);
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.
has_leftovers¶
my $success = $msg->has_leftovers;
Check if there are leftovers.
my $size = $msg->header_size;
Size of headers in bytes.
my $headers = $msg->headers;
Message headers, usually a Mojo::Headers object.
is_chunked¶
my $success = $msg->is_chunked;
Check if content is chunked.
is_dynamic¶
my $success = $msg->is_dynamic;
Check if content will be dynamically generated, which prevents "clone"
from working.
is_finished¶
my $success = $msg->is_finished;
Check if message parser/generator is finished.
is_limit_exceeded¶
my $success = $msg->is_limit_exceeded;
Check if message has exceeded "max_line_size" or
"max_message_size".
is_multipart¶
my $success = $msg->is_multipart;
Check if content is a Mojo::Content::MultiPart object.
json¶
my $hash = $msg->json;
my $array = $msg->json;
my $value = $msg->json('/foo/bar');
Decode JSON message body directly using Mojo::JSON if possible, returns
"undef" otherwise. 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.
# Extract JSON values
say $msg->json->{foo}{bar}[23];
say $msg->json('/foo/bar/23');
leftovers¶
my $bytes = $msg->leftovers;
Get leftover data from content parser.
param¶
my @names = $msg->param;
my $foo = $msg->param('foo');
my @foo = $msg->param('foo');
Access "POST" parameters. Note that this method caches all data, so it
should not be called before the entire message body has been received.
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.
to_string¶
my $string = $msg->to_string;
Render whole message.
upload¶
my $upload = $msg->upload('foo');
my @uploads = $msg->upload('foo');
Access "multipart/form-data" file uploads, usually Mojo::Upload
objects. 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.
write¶
$msg = $msg->write($bytes);
$msg = $msg->write($bytes => sub {...});
Write dynamic content non-blocking, the optional drain callback will be invoked
once all data has been written.
write_chunk¶
$msg = $msg->write_chunk($bytes);
$msg = $msg->write_chunk($bytes => sub {...});
Write dynamic content non-blocking with "chunked" transfer encoding,
the optional drain callback will be invoked once all data has been written.
SEE ALSO¶
Mojolicious, Mojolicious::Guides, <
http://mojolicio.us>.
