GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MOJO::MESSAGE (3)

.ds Aq ’

NAME

Mojo::Message - HTTP message base class

CONTENTS

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 <http://tools.ietf.org/html/rfc7230>, RFC 7231 <http://tools.ietf.org/html/rfc7231> and RFC 2388 <http://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 {
    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 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 (8KB).

    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 (16MB). 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 16MB limit 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 16MB limit 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 16MB 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. 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, <http://mojolicious.org>.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MOJO::MESSAGE (3) 2016-03-15

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.