Mojo::Message - HTTP message base class
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 is an abstract base class for HTTP message containers, based on RFC 7230, RFC 7231 and RFC 2388, like Mojo::Message::Request and Mojo::Message::Response.
Mojo::Message inherits all events from Mojo::EventEmitter and can emit the following new ones.
$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) });
$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)), '%';
});
Mojo::Message implements the following attributes.
my $msg = $msg->content;
$msg = $msg->content(Mojo::Content::Single->new);
Message content, defaults to a Mojo::Content::Single object.
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
.
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).
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.
my $version = $msg->version;
$msg = $msg->version('1.1');
HTTP version of message, defaults to 1.1
.
Mojo::Message inherits all methods from Mojo::EventEmitter and implements the following new ones.
my $bytes = $msg->body;
$msg = $msg->body('Hello!');
Slurp or replace "content".
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;
my $size = $msg->body_size;
Content size in bytes.
my $bytes = $msg->build_body;
Render whole body with "get_body_chunk".
my $bytes = $msg->build_headers;
Render all headers with "get_header_chunk".
my $bytes = $msg->build_start_line;
Render start-line with "get_start_line_chunk".
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;
my $cookies = $msg->cookies;
Access message cookies. Meant to be overloaded in a subclass.
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");
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});
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;
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.
$msg = $msg->finish;
Finish message parser/generator.
$msg = $msg->fix_headers;
Make sure message has all required headers.
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.
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.
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. Note that this method finalizes the message.
my $headers = $msg->headers;
Message headers, usually a Mojo::Headers object.
# Longer version
my $headers = $msg->content->headers;
my $bool = $msg->is_finished;
Check if message parser/generator is finished.
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.
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');
$msg = $msg->parse('HTTP/1.1 200 OK...');
Parse message chunk.
$msg = $msg->save_to('/some/path/index.html');
Save message body to a file.
my $size = $msg->start_line_size;
Size of the start-line in bytes. Meant to be overloaded in a subclass.
my $str = $msg->text;
Retrieve "body" and try to decode it with "charset" in Mojo::Content or "default_charset".
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.
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;
my $uploads = $msg->uploads;
All multipart/form-data
file uploads, usually Mojo::Upload objects.
# Names of all uploads
say $_->name for @{$msg->uploads};