Mojo::Message(3) User Contributed Perl Documentation Mojo::Message(3)
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 {...}
sub start_line_size {...}
DESCRIPTION
Mojo::Message is an abstract base class for HTTP message containers,
based on RFC 7230 <https://tools.ietf.org/html/rfc7230>, RFC 7231
<https://tools.ietf.org/html/rfc7231> and RFC 2388
<https://tools.ietf.org/html/rfc2388>, like Mojo::Message::Request and
Mojo::Message::Response.
EVENTS
Mojo::Message inherits all events from Mojo::EventEmitter and can emit
the following new ones.
finish
$msg->on(finish => sub ($msg) {...});
Emitted after message building or parsing is finished.
my $before = time;
$msg->on(finish => sub ($msg) { $msg->headers->header('X-Parser-Time' => time - $before) });
progress
$msg->on(progress => sub ($msg) {...});
Emitted when message building or parsing makes progress.
# Building
$msg->on(progress => sub ($msg, $state, $offset) { say qq{Building "$state" at offset $offset} });
# Parsing
$msg->on(progress => sub ($msg) {
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 by "text" and to extract data from
"application/x-www-form-urlencoded" or "multipart/form-data" message
body, 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 8192 (8KiB).
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 16777216 (16MiB).
Setting the value to 0 will allow messages of indefinite size.
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".
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 16MiB limit
for requests and a 2GiB limit for responses by default.
# Get POST parameter names and values
my $hash = $msg->body_params->to_hash;
body_size
my $size = $msg->body_size;
Content size in bytes.
build_body
my $bytes = $msg->build_body;
Render whole body with "get_body_chunk".
build_headers
my $bytes = $msg->build_headers;
Render all headers with "get_header_chunk".
build_start_line
my $bytes = $msg->build_start_line;
Render start-line with "get_start_line_chunk".
cookie
my $cookie = $msg->cookie('foo');
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]');
Retrieve message body from "text" and turn it into a Mojo::DOM object,
an optional selector can be used to call the method "find" in Mojo::DOM
on it right away, which then 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 16MiB limit for requests and a 2GiB limit
for responses by default.
# Perform "find" right away
say $msg->dom('h1, h2, h3')->map('text')->join("\n");
# Use everything else Mojo::DOM has to offer
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'});
Get or set message error, an "undef" return value indicates that there
is no error.
# Connection or parser error
$msg->error({message => 'Connection refused'});
# 4xx/5xx response
$msg->error({message => 'Internal Server Error', code => 500});
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;
extract_start_line
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.
fix_headers
$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. Note that
it might not be possible to get the same chunk twice if content was
generated dynamically.
get_header_chunk
my $bytes = $msg->get_header_chunk($offset);
Get a chunk of header data, starting from a specific position. Note
that this method finalizes the message.
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.
header_size
my $size = $msg->header_size;
Size of headers in bytes. Note that this method finalizes the message.
headers
my $headers = $msg->headers;
Message headers, usually a Mojo::Headers object.
# Longer version
my $headers = $msg->content->headers;
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", "max_message_size",
"max_buffer_size" in Mojo::Content or "max_line_size" in Mojo::Headers.
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 16MiB
limit for requests and a 2GiB limit for responses 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.
save_to
$msg = $msg->save_to('/some/path/index.html');
Save message body to a file.
start_line_size
my $size = $msg->start_line_size;
Size of the start-line in bytes. Meant to be overloaded in a subclass.
text
my $str = $msg->text;
Retrieve "body" and try to decode it with "charset" in Mojo::Content or
"default_charset".
to_string
my $str = $msg->to_string;
Render whole message. Note that this method finalizes the message, and
that it might not be possible to render the same message twice if
content was generated dynamically.
upload
my $upload = $msg->upload('foo');
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.
# Names of all uploads
say $_->name for @{$msg->uploads};
SEE ALSO
Mojolicious(3), Mojolicious::Guides(3), <https://mojolicious.org>.
perl v5.32.1 2021-12-08 Mojo::Message(3)
mojolicious 9.260.0 - Generated Tue May 31 13:12:28 CDT 2022