Provided by: libmojolicious-perl_9.35+dfsg-1_all bug

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, Mojolicious::Guides, <https://mojolicious.org>.