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 <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 finish
29 $msg->on(finish => sub ($msg) {...});
30 Emitted after message building or parsing is finished.
32 my $before = time;
34 $msg->on(finish => sub ($msg) { $msg->headers->header('X-Parser-Time' => time - $before) });
35 progress
37 $msg->on(progress => sub ($msg) {...});
38 Emitted when message building or parsing makes progress.
40 # Building
42 $msg->on(progress => sub ($msg, $state, $offset) { say qq{Building "$state" at offset $offset} });
43 # 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 content
55 my $msg = $msg->content;
56 $msg = $msg->content(Mojo::Content::Single->new);
57 Message content, defaults to a Mojo::Content::Single object.
59 default_charset
61 my $charset = $msg->default_charset;
62 $msg = $msg->default_charset('UTF-8');
63 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 max_line_size
69 my $size = $msg->max_line_size;
70 $msg = $msg->max_line_size(1024);
71 Maximum start-line size in bytes, defaults to the value of the
73 "MOJO_MAX_LINE_SIZE" environment variable or 8192 (8KiB).
74 max_message_size
76 my $size = $msg->max_message_size;
77 $msg = $msg->max_message_size(1024);
78 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 version
84 my $version = $msg->version;
85 $msg = $msg->version('1.1');
86 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 body
94 my $bytes = $msg->body;
95 $msg = $msg->body('Hello!');
96 Slurp or replace "content".
98 body_params
100 my $params = $msg->body_params;
101 "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 # Get POST parameter names and values
111 my $hash = $msg->body_params->to_hash;
112 body_size
114 my $size = $msg->body_size;
115 Content size in bytes.
117 build_body
119 my $bytes = $msg->build_body;
120 Render whole body with "get_body_chunk".
122 build_headers
124 my $bytes = $msg->build_headers;
125 Render all headers with "get_header_chunk".
127 build_start_line
129 my $bytes = $msg->build_start_line;
130 Render start-line with "get_start_line_chunk".
132 cookie
134 my $cookie = $msg->cookie('foo');
135 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 # Get cookie value
143 say $msg->cookie('foo')->value;
144 cookies
146 my $cookies = $msg->cookies;
147 Access message cookies. Meant to be overloaded in a subclass.
149 dom
151 my $dom = $msg->dom;
152 my $collection = $msg->dom('a[href]');
153 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 # Perform "find" right away
164 say $msg->dom('h1, h2, h3')->map('text')->join("\n");
165 # 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 error
171 my $err = $msg->error;
172 $msg = $msg->error({message => 'Parser error'});
173 Get or set message error, an "undef" return value indicates that there
175 is no error.
176 # Connection or parser error
178 $msg->error({message => 'Connection refused'});
179 # 4xx/5xx response
181 $msg->error({message => 'Internal Server Error', code => 500});
182 every_cookie
184 my $cookies = $msg->every_cookie('foo');
185 Similar to "cookie", but returns all message cookies sharing the same
187 name as an array reference.
188 # Get first cookie value
190 say $msg->every_cookie('foo')->[0]->value;
191 every_upload
193 my $uploads = $msg->every_upload('foo');
194 Similar to "upload", but returns all file uploads sharing the same name
196 as an array reference.
197 # Get content of first uploaded file
199 say $msg->every_upload('foo')->[0]->asset->slurp;
200 extract_start_line
202 my $bool = $msg->extract_start_line(\$str);
203 Extract start-line from string. Meant to be overloaded in a subclass.
205 finish
207 $msg = $msg->finish;
208 Finish message parser/generator.
210 fix_headers
212 $msg = $msg->fix_headers;
213 Make sure message has all required headers.
215 get_body_chunk
217 my $bytes = $msg->get_body_chunk($offset);
218 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 get_header_chunk
224 my $bytes = $msg->get_header_chunk($offset);
225 Get a chunk of header data, starting from a specific position. Note
227 that this method finalizes the message.
228 get_start_line_chunk
230 my $bytes = $msg->get_start_line_chunk($offset);
231 Get a chunk of start-line data starting from a specific position. Meant
233 to be overloaded in a subclass.
234 header_size
236 my $size = $msg->header_size;
237 Size of headers in bytes. Note that this method finalizes the message.
239 headers
241 my $headers = $msg->headers;
242 Message headers, usually a Mojo::Headers object.
244 # Longer version
246 my $headers = $msg->content->headers;
247 is_finished
249 my $bool = $msg->is_finished;
250 Check if message parser/generator is finished.
252 is_limit_exceeded
254 my $bool = $msg->is_limit_exceeded;
255 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 json
260 my $value = $msg->json;
261 my $value = $msg->json('/foo/bar');
262 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 # Extract JSON values
273 say $msg->json->{foo}{bar}[23];
274 say $msg->json('/foo/bar/23');
275 parse
277 $msg = $msg->parse('HTTP/1.1 200 OK...');
278 Parse message chunk.
280 save_to
282 $msg = $msg->save_to('/some/path/index.html');
283 Save message body to a file.
285 start_line_size
287 my $size = $msg->start_line_size;
288 Size of the start-line in bytes. Meant to be overloaded in a subclass.
290 text
292 my $str = $msg->text;
293 Retrieve "body" and try to decode it with "charset" in Mojo::Content or
295 "default_charset".
296 to_string
298 my $str = $msg->to_string;
299 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 upload
305 my $upload = $msg->upload('foo');
306 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 # Get content of uploaded file
314 say $msg->upload('foo')->asset->slurp;
315 uploads
317 my $uploads = $msg->uploads;
318 All "multipart/form-data" file uploads, usually Mojo::Upload objects.
320 # Names of all uploads
322 say $_->name for @{$msg->uploads};
323
325 Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.
326perl v5.38.0 2023-09-11 Mojo::Message(3)