Mojo::Message(3pm)

1Mojo::Message(3)      User Contributed Perl Documentation     Mojo::Message(3)
2
3
4

NAME

6       Mojo::Message - HTTP message base class
7

SYNOPSIS

9         package Mojo::Message::MyMessage;
10         use Mojo::Base 'Mojo::Message';
11
12         sub cookies              {...}
13         sub extract_start_line   {...}
14         sub get_start_line_chunk {...}
15         sub start_line_size      {...}
16

DESCRIPTION

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

EVENTS

25       Mojo::Message inherits all events from Mojo::EventEmitter and can emit
26       the following new ones.
27
28   finish
29         $msg->on(finish => sub {
30           my $msg = shift;
31           ...
32         });
33
34       Emitted after message building or parsing is finished.
35
36         my $before = time;
37         $msg->on(finish => sub {
38           my $msg = shift;
39           $msg->headers->header('X-Parser-Time' => time - $before);
40         });
41
42   progress
43         $msg->on(progress => sub {
44           my $msg = shift;
45           ...
46         });
47
48       Emitted when message building or parsing makes progress.
49
50         # Building
51         $msg->on(progress => sub {
52           my ($msg, $state, $offset) = @_;
53           say qq{Building "$state" at offset $offset};
54         });
55
56         # 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

ATTRIBUTES

65       Mojo::Message implements the following attributes.
66
67   content
68         my $msg = $msg->content;
69         $msg    = $msg->content(Mojo::Content::Single->new);
70
71       Message content, defaults to a Mojo::Content::Single object.
72
73   default_charset
74         my $charset = $msg->default_charset;
75         $msg        = $msg->default_charset('UTF-8');
76
77       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
81   max_line_size
82         my $size = $msg->max_line_size;
83         $msg     = $msg->max_line_size(1024);
84
85       Maximum start-line size in bytes, defaults to the value of the
86       "MOJO_MAX_LINE_SIZE" environment variable or 8192 (8KiB).
87
88   max_message_size
89         my $size = $msg->max_message_size;
90         $msg     = $msg->max_message_size(1024);
91
92       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
96   version
97         my $version = $msg->version;
98         $msg        = $msg->version('1.1');
99
100       HTTP version of message, defaults to 1.1.
101

METHODS

103       Mojo::Message inherits all methods from Mojo::EventEmitter and
104       implements the following new ones.
105
106   body
107         my $bytes = $msg->body;
108         $msg      = $msg->body('Hello!');
109
110       Slurp or replace "content".
111
112   body_params
113         my $params = $msg->body_params;
114
115       "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
123         # Get POST parameter names and values
124         my $hash = $msg->body_params->to_hash;
125
126   body_size
127         my $size = $msg->body_size;
128
129       Content size in bytes.
130
131   build_body
132         my $bytes = $msg->build_body;
133
134       Render whole body with "get_body_chunk".
135
136   build_headers
137         my $bytes = $msg->build_headers;
138
139       Render all headers with "get_header_chunk".
140
141   build_start_line
142         my $bytes = $msg->build_start_line;
143
144       Render start-line with "get_start_line_chunk".
145
146   cookie
147         my $cookie = $msg->cookie('foo');
148
149       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
155         # Get cookie value
156         say $msg->cookie('foo')->value;
157
158   cookies
159         my $cookies = $msg->cookies;
160
161       Access message cookies. Meant to be overloaded in a subclass.
162
163   dom
164         my $dom        = $msg->dom;
165         my $collection = $msg->dom('a[href]');
166
167       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
176         # Perform "find" right away
177         say $msg->dom('h1, h2, h3')->map('text')->join("\n");
178
179         # 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
183   error
184         my $err = $msg->error;
185         $msg    = $msg->error({message => 'Parser error'});
186
187       Get or set message error, an "undef" return value indicates that there
188       is no error.
189
190         # Connection or parser error
191         $msg->error({message => 'Connection refused'});
192
193         # 4xx/5xx response
194         $msg->error({message => 'Internal Server Error', code => 500});
195
196   every_cookie
197         my $cookies = $msg->every_cookie('foo');
198
199       Similar to "cookie", but returns all message cookies sharing the same
200       name as an array reference.
201
202         # Get first cookie value
203         say $msg->every_cookie('foo')->[0]->value;
204
205   every_upload
206         my $uploads = $msg->every_upload('foo');
207
208       Similar to "upload", but returns all file uploads sharing the same name
209       as an array reference.
210
211         # Get content of first uploaded file
212         say $msg->every_upload('foo')->[0]->asset->slurp;
213
214   extract_start_line
215         my $bool = $msg->extract_start_line(\$str);
216
217       Extract start-line from string. Meant to be overloaded in a subclass.
218
219   finish
220         $msg = $msg->finish;
221
222       Finish message parser/generator.
223
224   fix_headers
225         $msg = $msg->fix_headers;
226
227       Make sure message has all required headers.
228
229   get_body_chunk
230         my $bytes = $msg->get_body_chunk($offset);
231
232       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
236   get_header_chunk
237         my $bytes = $msg->get_header_chunk($offset);
238
239       Get a chunk of header data, starting from a specific position. Note
240       that this method finalizes the message.
241
242   get_start_line_chunk
243         my $bytes = $msg->get_start_line_chunk($offset);
244
245       Get a chunk of start-line data starting from a specific position. Meant
246       to be overloaded in a subclass.
247
248   header_size
249         my $size = $msg->header_size;
250
251       Size of headers in bytes. Note that this method finalizes the message.
252
253   headers
254         my $headers = $msg->headers;
255
256       Message headers, usually a Mojo::Headers object.
257
258         # Longer version
259         my $headers = $msg->content->headers;
260
261   is_finished
262         my $bool = $msg->is_finished;
263
264       Check if message parser/generator is finished.
265
266   is_limit_exceeded
267         my $bool = $msg->is_limit_exceeded;
268
269       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
272   json
273         my $value = $msg->json;
274         my $value = $msg->json('/foo/bar');
275
276       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
285         # Extract JSON values
286         say $msg->json->{foo}{bar}[23];
287         say $msg->json('/foo/bar/23');
288
289   parse
290         $msg = $msg->parse('HTTP/1.1 200 OK...');
291
292       Parse message chunk.
293
294   save_to
295         $msg = $msg->save_to('/some/path/index.html');
296
297       Save message body to a file.
298
299   start_line_size
300         my $size = $msg->start_line_size;
301
302       Size of the start-line in bytes. Meant to be overloaded in a subclass.
303
304   text
305         my $str = $msg->text;
306
307       Retrieve "body" and try to decode it with "charset" in Mojo::Content or
308       "default_charset".
309
310   to_string
311         my $str = $msg->to_string;
312
313       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
317   upload
318         my $upload = $msg->upload('foo');
319
320       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
326         # Get content of uploaded file
327         say $msg->upload('foo')->asset->slurp;
328
329   uploads
330         my $uploads = $msg->uploads;
331
332       All "multipart/form-data" file uploads, usually Mojo::Upload objects.
333
334         # Names of all uploads
335         say $_->name for @{$msg->uploads};
336

NAME

SYNOPSIS

DESCRIPTION

EVENTS

ATTRIBUTES

METHODS

SEE ALSO