1Mojo::Message(3) User Contributed Perl Documentation Mojo::Message(3)
2
3
4
6 Mojo::Message - HTTP message base class
7
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
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
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
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
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
325 Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.
326
327
328
329perl v5.36.0 2023-01-20 Mojo::Message(3)