1Mojo::Message(3) User Contributed Perl Documentation Mojo::Message(3)
2
6 Mojo::Message - HTTP message base class
7
9 package Mojo::Message::MyMessage;
10 use Mojo::Base 'Mojo::Message';
11 sub cookies {...}
13 sub extract_start_line {...}
14 sub get_start_line_chunk {...}
15 sub start_line_size {...}
16
18 Mojo::Message is an abstract base class for HTTP message containers,
19 based on RFC 7230 <http://tools.ietf.org/html/rfc7230>, RFC 7231
20 <http://tools.ietf.org/html/rfc7231> and RFC 2388
21 <http://tools.ietf.org/html/rfc2388>, like Mojo::Message::Request and
22 Mojo::Message::Response.
23
25 Mojo::Message inherits all events from Mojo::EventEmitter and can emit
26 the following new ones.
27 finish
29 $msg->on(finish => sub {
30 my $msg = shift;
31 ...
32 });
33 Emitted after message building or parsing is finished.
35 my $before = time;
37 $msg->on(finish => sub {
38 my $msg = shift;
39 $msg->headers->header('X-Parser-Time' => time - $before);
40 });
41 progress
43 $msg->on(progress => sub {
44 my $msg = shift;
45 ...
46 });
47 Emitted when message building or parsing makes progress.
49 # Building
51 $msg->on(progress => sub {
52 my ($msg, $state, $offset) = @_;
53 say qq{Building "$state" at offset $offset};
54 });
55 # Parsing
57 $msg->on(progress => sub {
58 my $msg = shift;
59 return unless my $len = $msg->headers->content_length;
60 my $size = $msg->content->progress;
61 say 'Progress: ', $size == $len ? 100 : int($size / ($len / 100)), '%';
62 });
63
65 Mojo::Message implements the following attributes.
66 content
68 my $msg = $msg->content;
69 $msg = $msg->content(Mojo::Content::Single->new);
70 Message content, defaults to a Mojo::Content::Single object.
72 default_charset
74 my $charset = $msg->default_charset;
75 $msg = $msg->default_charset('UTF-8');
76 Default charset used by "text" and to extract data from
78 "application/x-www-form-urlencoded" or "multipart/form-data" message
79 body, defaults to "UTF-8".
80 max_line_size
82 my $size = $msg->max_line_size;
83 $msg = $msg->max_line_size(1024);
84 Maximum start-line size in bytes, defaults to the value of the
86 "MOJO_MAX_LINE_SIZE" environment variable or 8192 (8KiB).
87 max_message_size
89 my $size = $msg->max_message_size;
90 $msg = $msg->max_message_size(1024);
91 Maximum message size in bytes, defaults to the value of the
93 "MOJO_MAX_MESSAGE_SIZE" environment variable or 16777216 (16MiB).
94 Setting the value to 0 will allow messages of indefinite size.
95 version
97 my $version = $msg->version;
98 $msg = $msg->version('1.1');
99 HTTP version of message, defaults to 1.1.
101
103 Mojo::Message inherits all methods from Mojo::EventEmitter and
104 implements the following new ones.
105 body
107 my $bytes = $msg->body;
108 $msg = $msg->body('Hello!');
109 Slurp or replace "content".
111 body_params
113 my $params = $msg->body_params;
114 "POST" parameters extracted from "application/x-www-form-urlencoded" or
116 "multipart/form-data" message body, usually a Mojo::Parameters object.
117 Note that this method caches all data, so it should not be called
118 before the entire message body has been received. Parts of the message
119 body need to be loaded into memory to parse "POST" parameters, so you
120 have to make sure it is not excessively large. There's a 16MiB limit
121 for requests and a 2GiB limit for responses by default.
122 # Get POST parameter names and values
124 my $hash = $msg->body_params->to_hash;
125 body_size
127 my $size = $msg->body_size;
128 Content size in bytes.
130 build_body
132 my $bytes = $msg->build_body;
133 Render whole body with "get_body_chunk".
135 build_headers
137 my $bytes = $msg->build_headers;
138 Render all headers with "get_header_chunk".
140 build_start_line
142 my $bytes = $msg->build_start_line;
143 Render start-line with "get_start_line_chunk".
145 cookie
147 my $cookie = $msg->cookie('foo');
148 Access message cookies, usually Mojo::Cookie::Request or
150 Mojo::Cookie::Response objects. If there are multiple cookies sharing
151 the same name, and you want to access more than just the last one, you
152 can use "every_cookie". Note that this method caches all data, so it
153 should not be called before all headers have been received.
154 # Get cookie value
156 say $msg->cookie('foo')->value;
157 cookies
159 my $cookies = $msg->cookies;
160 Access message cookies. Meant to be overloaded in a subclass.
162 dom
164 my $dom = $msg->dom;
165 my $collection = $msg->dom('a[href]');
166 Retrieve message body from "text" and turn it into a Mojo::DOM object,
168 an optional selector can be used to call the method "find" in Mojo::DOM
169 on it right away, which then returns a Mojo::Collection object. Note
170 that this method caches all data, so it should not be called before the
171 entire message body has been received. The whole message body needs to
172 be loaded into memory to parse it, so you have to make sure it is not
173 excessively large. There's a 16MiB limit for requests and a 2GiB limit
174 for responses by default.
175 # Perform "find" right away
177 say $msg->dom('h1, h2, h3')->map('text')->join("\n");
178 # Use everything else Mojo::DOM has to offer
180 say $msg->dom->at('title')->text;
181 say $msg->dom->at('body')->children->map('tag')->uniq->join("\n");
182 error
184 my $err = $msg->error;
185 $msg = $msg->error({message => 'Parser error'});
186 Get or set message error, an "undef" return value indicates that there
188 is no error.
189 # Connection or parser error
191 $msg->error({message => 'Connection refused'});
192 # 4xx/5xx response
194 $msg->error({message => 'Internal Server Error', code => 500});
195 every_cookie
197 my $cookies = $msg->every_cookie('foo');
198 Similar to "cookie", but returns all message cookies sharing the same
200 name as an array reference.
201 # Get first cookie value
203 say $msg->every_cookie('foo')->[0]->value;
204 every_upload
206 my $uploads = $msg->every_upload('foo');
207 Similar to "upload", but returns all file uploads sharing the same name
209 as an array reference.
210 # Get content of first uploaded file
212 say $msg->every_upload('foo')->[0]->asset->slurp;
213 extract_start_line
215 my $bool = $msg->extract_start_line(\$str);
216 Extract start-line from string. Meant to be overloaded in a subclass.
218 finish
220 $msg = $msg->finish;
221 Finish message parser/generator.
223 fix_headers
225 $msg = $msg->fix_headers;
226 Make sure message has all required headers.
228 get_body_chunk
230 my $bytes = $msg->get_body_chunk($offset);
231 Get a chunk of body data starting from a specific position. Note that
233 it might not be possible to get the same chunk twice if content was
234 generated dynamically.
235 get_header_chunk
237 my $bytes = $msg->get_header_chunk($offset);
238 Get a chunk of header data, starting from a specific position. Note
240 that this method finalizes the message.
241 get_start_line_chunk
243 my $bytes = $msg->get_start_line_chunk($offset);
244 Get a chunk of start-line data starting from a specific position. Meant
246 to be overloaded in a subclass.
247 header_size
249 my $size = $msg->header_size;
250 Size of headers in bytes. Note that this method finalizes the message.
252 headers
254 my $headers = $msg->headers;
255 Message headers, usually a Mojo::Headers object.
257 # Longer version
259 my $headers = $msg->content->headers;
260 is_finished
262 my $bool = $msg->is_finished;
263 Check if message parser/generator is finished.
265 is_limit_exceeded
267 my $bool = $msg->is_limit_exceeded;
268 Check if message has exceeded "max_line_size", "max_message_size",
270 "max_buffer_size" in Mojo::Content or "max_line_size" in Mojo::Headers.
271 json
273 my $value = $msg->json;
274 my $value = $msg->json('/foo/bar');
275 Decode JSON message body directly using Mojo::JSON if possible, an
277 "undef" return value indicates a bare "null" or that decoding failed.
278 An optional JSON Pointer can be used to extract a specific value with
279 Mojo::JSON::Pointer. Note that this method caches all data, so it
280 should not be called before the entire message body has been received.
281 The whole message body needs to be loaded into memory to parse it, so
282 you have to make sure it is not excessively large. There's a 16MiB
283 limit for requests and a 2GiB limit for responses by default.
284 # Extract JSON values
286 say $msg->json->{foo}{bar}[23];
287 say $msg->json('/foo/bar/23');
288 parse
290 $msg = $msg->parse('HTTP/1.1 200 OK...');
291 Parse message chunk.
293 save_to
295 $msg = $msg->save_to('/some/path/index.html');
296 Save message body to a file.
298 start_line_size
300 my $size = $msg->start_line_size;
301 Size of the start-line in bytes. Meant to be overloaded in a subclass.
303 text
305 my $str = $msg->text;
306 Retrieve "body" and try to decode it with "charset" in Mojo::Content or
308 "default_charset".
309 to_string
311 my $str = $msg->to_string;
312 Render whole message. Note that this method finalizes the message, and
314 that it might not be possible to render the same message twice if
315 content was generated dynamically.
316 upload
318 my $upload = $msg->upload('foo');
319 Access "multipart/form-data" file uploads, usually Mojo::Upload
321 objects. If there are multiple uploads sharing the same name, and you
322 want to access more than just the last one, you can use "every_upload".
323 Note that this method caches all data, so it should not be called
324 before the entire message body has been received.
325 # Get content of uploaded file
327 say $msg->upload('foo')->asset->slurp;
328 uploads
330 my $uploads = $msg->uploads;
331 All "multipart/form-data" file uploads, usually Mojo::Upload objects.
333 # Names of all uploads
335 say $_->name for @{$msg->uploads};
336
338 Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.
339perl v5.28.1 2018-11-22 Mojo::Message(3)