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 <https://tools.ietf.org/html/rfc7230>, RFC 7231
20       <https://tools.ietf.org/html/rfc7231> and RFC 2388
21       <https://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 ($msg) {...});
30
31       Emitted after message building or parsing is finished.
32
33         my $before = time;
34         $msg->on(finish => sub ($msg) { $msg->headers->header('X-Parser-Time' => time - $before) });
35
36   progress
37         $msg->on(progress => sub ($msg) {...});
38
39       Emitted when message building or parsing makes progress.
40
41         # Building
42         $msg->on(progress => sub ($msg, $state, $offset) { say qq{Building "$state" at offset $offset} });
43
44         # Parsing
45         $msg->on(progress => sub ($msg) {
46           return unless my $len = $msg->headers->content_length;
47           my $size = $msg->content->progress;
48           say 'Progress: ', $size == $len ? 100 : int($size / ($len / 100)), '%';
49         });
50

ATTRIBUTES

52       Mojo::Message implements the following attributes.
53
54   content
55         my $msg = $msg->content;
56         $msg    = $msg->content(Mojo::Content::Single->new);
57
58       Message content, defaults to a Mojo::Content::Single object.
59
60   default_charset
61         my $charset = $msg->default_charset;
62         $msg        = $msg->default_charset('UTF-8');
63
64       Default charset used by "text" and to extract data from
65       "application/x-www-form-urlencoded" or "multipart/form-data" message
66       body, defaults to "UTF-8".
67
68   max_line_size
69         my $size = $msg->max_line_size;
70         $msg     = $msg->max_line_size(1024);
71
72       Maximum start-line size in bytes, defaults to the value of the
73       "MOJO_MAX_LINE_SIZE" environment variable or 8192 (8KiB).
74
75   max_message_size
76         my $size = $msg->max_message_size;
77         $msg     = $msg->max_message_size(1024);
78
79       Maximum message size in bytes, defaults to the value of the
80       "MOJO_MAX_MESSAGE_SIZE" environment variable or 16777216 (16MiB).
81       Setting the value to 0 will allow messages of indefinite size.
82
83   version
84         my $version = $msg->version;
85         $msg        = $msg->version('1.1');
86
87       HTTP version of message, defaults to 1.1.
88

METHODS

90       Mojo::Message inherits all methods from Mojo::EventEmitter and
91       implements the following new ones.
92
93   body
94         my $bytes = $msg->body;
95         $msg      = $msg->body('Hello!');
96
97       Slurp or replace "content".
98
99   body_params
100         my $params = $msg->body_params;
101
102       "POST" parameters extracted from "application/x-www-form-urlencoded" or
103       "multipart/form-data" message body, usually a Mojo::Parameters object.
104       Note that this method caches all data, so it should not be called
105       before the entire message body has been received. Parts of the message
106       body need to be loaded into memory to parse "POST" parameters, so you
107       have to make sure it is not excessively large. There's a 16MiB limit
108       for requests and a 2GiB limit for responses by default.
109
110         # Get POST parameter names and values
111         my $hash = $msg->body_params->to_hash;
112
113   body_size
114         my $size = $msg->body_size;
115
116       Content size in bytes.
117
118   build_body
119         my $bytes = $msg->build_body;
120
121       Render whole body with "get_body_chunk".
122
123   build_headers
124         my $bytes = $msg->build_headers;
125
126       Render all headers with "get_header_chunk".
127
128   build_start_line
129         my $bytes = $msg->build_start_line;
130
131       Render start-line with "get_start_line_chunk".
132
133   cookie
134         my $cookie = $msg->cookie('foo');
135
136       Access message cookies, usually Mojo::Cookie::Request or
137       Mojo::Cookie::Response objects. If there are multiple cookies sharing
138       the same name, and you want to access more than just the last one, you
139       can use "every_cookie". Note that this method caches all data, so it
140       should not be called before all headers have been received.
141
142         # Get cookie value
143         say $msg->cookie('foo')->value;
144
145   cookies
146         my $cookies = $msg->cookies;
147
148       Access message cookies. Meant to be overloaded in a subclass.
149
150   dom
151         my $dom        = $msg->dom;
152         my $collection = $msg->dom('a[href]');
153
154       Retrieve message body from "text" and turn it into a Mojo::DOM object,
155       an optional selector can be used to call the method "find" in Mojo::DOM
156       on it right away, which then returns a Mojo::Collection object. Note
157       that this method caches all data, so it should not be called before the
158       entire message body has been received. The whole message body needs to
159       be loaded into memory to parse it, so you have to make sure it is not
160       excessively large. There's a 16MiB limit for requests and a 2GiB limit
161       for responses by default.
162
163         # Perform "find" right away
164         say $msg->dom('h1, h2, h3')->map('text')->join("\n");
165
166         # Use everything else Mojo::DOM has to offer
167         say $msg->dom->at('title')->text;
168         say $msg->dom->at('body')->children->map('tag')->uniq->join("\n");
169
170   error
171         my $err = $msg->error;
172         $msg    = $msg->error({message => 'Parser error'});
173
174       Get or set message error, an "undef" return value indicates that there
175       is no error.
176
177         # Connection or parser error
178         $msg->error({message => 'Connection refused'});
179
180         # 4xx/5xx response
181         $msg->error({message => 'Internal Server Error', code => 500});
182
183   every_cookie
184         my $cookies = $msg->every_cookie('foo');
185
186       Similar to "cookie", but returns all message cookies sharing the same
187       name as an array reference.
188
189         # Get first cookie value
190         say $msg->every_cookie('foo')->[0]->value;
191
192   every_upload
193         my $uploads = $msg->every_upload('foo');
194
195       Similar to "upload", but returns all file uploads sharing the same name
196       as an array reference.
197
198         # Get content of first uploaded file
199         say $msg->every_upload('foo')->[0]->asset->slurp;
200
201   extract_start_line
202         my $bool = $msg->extract_start_line(\$str);
203
204       Extract start-line from string. Meant to be overloaded in a subclass.
205
206   finish
207         $msg = $msg->finish;
208
209       Finish message parser/generator.
210
211   fix_headers
212         $msg = $msg->fix_headers;
213
214       Make sure message has all required headers.
215
216   get_body_chunk
217         my $bytes = $msg->get_body_chunk($offset);
218
219       Get a chunk of body data starting from a specific position. Note that
220       it might not be possible to get the same chunk twice if content was
221       generated dynamically.
222
223   get_header_chunk
224         my $bytes = $msg->get_header_chunk($offset);
225
226       Get a chunk of header data, starting from a specific position. Note
227       that this method finalizes the message.
228
229   get_start_line_chunk
230         my $bytes = $msg->get_start_line_chunk($offset);
231
232       Get a chunk of start-line data starting from a specific position. Meant
233       to be overloaded in a subclass.
234
235   header_size
236         my $size = $msg->header_size;
237
238       Size of headers in bytes. Note that this method finalizes the message.
239
240   headers
241         my $headers = $msg->headers;
242
243       Message headers, usually a Mojo::Headers object.
244
245         # Longer version
246         my $headers = $msg->content->headers;
247
248   is_finished
249         my $bool = $msg->is_finished;
250
251       Check if message parser/generator is finished.
252
253   is_limit_exceeded
254         my $bool = $msg->is_limit_exceeded;
255
256       Check if message has exceeded "max_line_size", "max_message_size",
257       "max_buffer_size" in Mojo::Content or "max_line_size" in Mojo::Headers.
258
259   json
260         my $value = $msg->json;
261         my $value = $msg->json('/foo/bar');
262
263       Decode JSON message body directly using Mojo::JSON if possible, an
264       "undef" return value indicates a bare "null" or that decoding failed.
265       An optional JSON Pointer can be used to extract a specific value with
266       Mojo::JSON::Pointer.  Note that this method caches all data, so it
267       should not be called before the entire message body has been received.
268       The whole message body needs to be loaded into memory to parse it, so
269       you have to make sure it is not excessively large.  There's a 16MiB
270       limit for requests and a 2GiB limit for responses by default.
271
272         # Extract JSON values
273         say $msg->json->{foo}{bar}[23];
274         say $msg->json('/foo/bar/23');
275
276   parse
277         $msg = $msg->parse('HTTP/1.1 200 OK...');
278
279       Parse message chunk.
280
281   save_to
282         $msg = $msg->save_to('/some/path/index.html');
283
284       Save message body to a file.
285
286   start_line_size
287         my $size = $msg->start_line_size;
288
289       Size of the start-line in bytes. Meant to be overloaded in a subclass.
290
291   text
292         my $str = $msg->text;
293
294       Retrieve "body" and try to decode it with "charset" in Mojo::Content or
295       "default_charset".
296
297   to_string
298         my $str = $msg->to_string;
299
300       Render whole message. Note that this method finalizes the message, and
301       that it might not be possible to render the same message twice if
302       content was generated dynamically.
303
304   upload
305         my $upload = $msg->upload('foo');
306
307       Access "multipart/form-data" file uploads, usually Mojo::Upload
308       objects. If there are multiple uploads sharing the same name, and you
309       want to access more than just the last one, you can use "every_upload".
310       Note that this method caches all data, so it should not be called
311       before the entire message body has been received.
312
313         # Get content of uploaded file
314         say $msg->upload('foo')->asset->slurp;
315
316   uploads
317         my $uploads = $msg->uploads;
318
319       All "multipart/form-data" file uploads, usually Mojo::Upload objects.
320
321         # Names of all uploads
322         say $_->name for @{$msg->uploads};
323

SEE ALSO

325       Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.
326
327
328
329perl v5.38.0                      2023-09-11                  Mojo::Message(3)
Impressum