Commit | Line | Data |
fc7ec1d9 |
1 | package Catalyst::Response; |
2 | |
059c085b |
3 | use Moose; |
6680c772 |
4 | use HTTP::Headers; |
faa02805 |
5 | use Moose::Util::TypeConstraints; |
6 | use namespace::autoclean; |
fc7ec1d9 |
7 | |
531f1ab6 |
8 | with 'MooseX::Emulate::Class::Accessor::Fast'; |
9 | |
faa02805 |
10 | has _response_cb => ( |
11 | is => 'ro', |
12 | isa => 'CodeRef', |
13 | writer => '_set_response_cb', |
14 | clearer => '_clear_response_cb', |
15 | predicate => '_has_response_cb', |
16 | ); |
17 | |
18 | subtype 'Catalyst::Engine::Types::Writer', |
19 | as duck_type([qw(write close)]); |
20 | |
21 | has _writer => ( |
22 | is => 'ro', |
23 | isa => 'Catalyst::Engine::Types::Writer', |
24 | writer => '_set_writer', |
25 | clearer => '_clear_writer', |
26 | predicate => '_has_writer', |
27 | ); |
28 | |
e37f92f5 |
29 | has write_fh => ( |
30 | is=>'ro', |
31 | predicate=>'has_write_fh', |
eb1f4b49 |
32 | lazy=>1, |
1f2a8069 |
33 | builder=>'_build_write_fh', |
34 | ); |
35 | |
36 | sub _build_write_fh { |
37 | my $self = shift; |
38 | $self->_context->finalize_headers unless |
39 | $self->finalized_headers; |
40 | $self->_writer; |
41 | }; |
e37f92f5 |
42 | |
43 | sub DEMOLISH { |
44 | my $self = shift; |
45 | return if $self->has_write_fh; |
46 | if($self->_has_writer) { |
47 | $self->_writer->close |
48 | } |
49 | } |
faa02805 |
50 | |
6680c772 |
51 | has cookies => (is => 'rw', default => sub { {} }); |
ffb43803 |
52 | has body => (is => 'rw', default => undef); |
53 | sub has_body { defined($_[0]->body) } |
99a543ee |
54 | |
059c085b |
55 | has location => (is => 'rw'); |
6680c772 |
56 | has status => (is => 'rw', default => 200); |
57 | has finalized_headers => (is => 'rw', default => 0); |
059c085b |
58 | has headers => ( |
59 | is => 'rw', |
9c331634 |
60 | isa => 'HTTP::Headers', |
059c085b |
61 | handles => [qw(content_encoding content_length content_type header)], |
6680c772 |
62 | default => sub { HTTP::Headers->new() }, |
63 | required => 1, |
64 | lazy => 1, |
059c085b |
65 | ); |
258733f1 |
66 | has _context => ( |
67 | is => 'rw', |
68 | weak_ref => 1, |
69 | clearer => '_clear_context', |
70 | ); |
fc7ec1d9 |
71 | |
059c085b |
72 | sub output { shift->body(@_) } |
73 | |
aa9e8261 |
74 | sub code { shift->status(@_) } |
75 | |
9c4288ea |
76 | sub write { |
77 | my ( $self, $buffer ) = @_; |
78 | |
79 | # Finalize headers if someone manually writes output |
89ba65d5 |
80 | $self->_context->finalize_headers unless $self->finalized_headers; |
9c4288ea |
81 | |
82 | $buffer = q[] unless defined $buffer; |
83 | |
84 | my $len = length($buffer); |
85 | $self->_writer->write($buffer); |
86 | |
87 | return $len; |
88 | } |
89 | |
9c4288ea |
90 | sub finalize_headers { |
91 | my ($self) = @_; |
92 | |
93 | # This is a less-than-pretty hack to avoid breaking the old |
94 | # Catalyst::Engine::PSGI. 5.9 Catalyst::Engine sets a response_cb and |
95 | # expects us to pass headers to it here, whereas Catalyst::Enngine::PSGI |
96 | # just pulls the headers out of $ctx->response in its run method and never |
97 | # sets response_cb. So take the lack of a response_cb as a sign that we |
98 | # don't need to set the headers. |
99 | |
100 | return unless $self->_has_response_cb; |
101 | |
102 | # If we already have a writer, we already did this, so don't do it again |
103 | return if $self->_has_writer; |
104 | |
105 | my @headers; |
106 | $self->headers->scan(sub { push @headers, @_ }); |
107 | |
108 | my $writer = $self->_response_cb->([ $self->status, \@headers ]); |
109 | $self->_set_writer($writer); |
110 | $self->_clear_response_cb; |
111 | |
112 | return; |
113 | } |
114 | |
fc7ec1d9 |
115 | =head1 NAME |
116 | |
910410b8 |
117 | Catalyst::Response - stores output responding to the current client request |
fc7ec1d9 |
118 | |
119 | =head1 SYNOPSIS |
120 | |
fbcc39ad |
121 | $res = $c->response; |
122 | $res->body; |
aa9e8261 |
123 | $res->code; |
fbcc39ad |
124 | $res->content_encoding; |
125 | $res->content_length; |
126 | $res->content_type; |
127 | $res->cookies; |
fbcc39ad |
128 | $res->header; |
129 | $res->headers; |
130 | $res->output; |
131 | $res->redirect; |
132 | $res->status; |
133 | $res->write; |
b22c6668 |
134 | |
fc7ec1d9 |
135 | =head1 DESCRIPTION |
136 | |
910410b8 |
137 | This is the Catalyst Response class, which provides methods for responding to |
46372e65 |
138 | the current client request. The appropriate L<Catalyst::Engine> for your environment |
139 | will turn the Catalyst::Response into a HTTP Response and return it to the client. |
b22c6668 |
140 | |
141 | =head1 METHODS |
fc7ec1d9 |
142 | |
08a2c908 |
143 | =head2 $res->body( $text | $fh | $iohandle_object ) |
e060fe05 |
144 | |
145 | $c->response->body('Catalyst rocks!'); |
06e1b616 |
146 | |
46372e65 |
147 | Sets or returns the output (text or binary data). If you are returning a large body, |
2f381252 |
148 | you might want to use a L<IO::Handle> type of object (Something that implements the read method |
46372e65 |
149 | in the same fashion), or a filehandle GLOB. Catalyst |
150 | will write it piece by piece into the response. |
06e1b616 |
151 | |
02570318 |
152 | =head2 $res->has_body |
153 | |
154 | Predicate which returns true when a body has been set. |
155 | |
aa9e8261 |
156 | =head2 $res->code |
157 | |
158 | Alias for $res->status. |
159 | |
b5ecfcf0 |
160 | =head2 $res->content_encoding |
b5176d9e |
161 | |
910410b8 |
162 | Shortcut for $res->headers->content_encoding. |
b5176d9e |
163 | |
b5ecfcf0 |
164 | =head2 $res->content_length |
b5176d9e |
165 | |
910410b8 |
166 | Shortcut for $res->headers->content_length. |
b5176d9e |
167 | |
b5ecfcf0 |
168 | =head2 $res->content_type |
b5176d9e |
169 | |
910410b8 |
170 | Shortcut for $res->headers->content_type. |
b5176d9e |
171 | |
87e9f9ab |
172 | This value is typically set by your view or plugin. For example, |
173 | L<Catalyst::Plugin::Static::Simple> will guess the mime type based on the file |
174 | it found, while L<Catalyst::View::TT> defaults to C<text/html>. |
175 | |
b5ecfcf0 |
176 | =head2 $res->cookies |
fc7ec1d9 |
177 | |
910410b8 |
178 | Returns a reference to a hash containing cookies to be set. The keys of the |
179 | hash are the cookies' names, and their corresponding values are hash |
7e743798 |
180 | references used to construct a L<CGI::Simple::Cookie> object. |
fc7ec1d9 |
181 | |
182 | $c->response->cookies->{foo} = { value => '123' }; |
183 | |
7e743798 |
184 | The keys of the hash reference on the right correspond to the L<CGI::Simple::Cookie> |
910410b8 |
185 | parameters of the same name, except they are used without a leading dash. |
186 | Possible parameters are: |
ac965e92 |
187 | |
b0ad47c1 |
188 | =over |
ac965e92 |
189 | |
71453caf |
190 | =item value |
ac965e92 |
191 | |
71453caf |
192 | =item expires |
ac965e92 |
193 | |
71453caf |
194 | =item domain |
ac965e92 |
195 | |
71453caf |
196 | =item path |
197 | |
198 | =item secure |
199 | |
b21bc468 |
200 | =item httponly |
201 | |
71453caf |
202 | =back |
ac965e92 |
203 | |
b5ecfcf0 |
204 | =head2 $res->header |
fbcc39ad |
205 | |
910410b8 |
206 | Shortcut for $res->headers->header. |
fbcc39ad |
207 | |
b5ecfcf0 |
208 | =head2 $res->headers |
fc7ec1d9 |
209 | |
910410b8 |
210 | Returns an L<HTTP::Headers> object, which can be used to set headers. |
fc7ec1d9 |
211 | |
212 | $c->response->headers->header( 'X-Catalyst' => $Catalyst::VERSION ); |
213 | |
b5ecfcf0 |
214 | =head2 $res->output |
fc7ec1d9 |
215 | |
910410b8 |
216 | Alias for $res->body. |
fc7ec1d9 |
217 | |
b5ecfcf0 |
218 | =head2 $res->redirect( $url, $status ) |
fc7ec1d9 |
219 | |
2f381252 |
220 | Causes the response to redirect to the specified URL. The default status is |
221 | C<302>. |
fc7ec1d9 |
222 | |
73a52566 |
223 | $c->response->redirect( 'http://slashdot.org' ); |
224 | $c->response->redirect( 'http://slashdot.org', 307 ); |
225 | |
2f381252 |
226 | This is a convenience method that sets the Location header to the |
227 | redirect destination, and then sets the response status. You will |
ee24f3a8 |
228 | want to C< return > or C<< $c->detach() >> to interrupt the normal |
2f381252 |
229 | processing flow if you want the redirect to occur straight away. |
230 | |
824a5eb0 |
231 | B<Note:> do not give a relative URL as $url, i.e: one that is not fully |
232 | qualified (= C<http://...>, etc.) or that starts with a slash |
233 | (= C</path/here>). While it may work, it is not guaranteed to do the right |
234 | thing and is not a standard behaviour. You may opt to use uri_for() or |
235 | uri_for_action() instead. |
236 | |
73a52566 |
237 | =cut |
238 | |
239 | sub redirect { |
240 | my $self = shift; |
fbcc39ad |
241 | |
242 | if (@_) { |
73a52566 |
243 | my $location = shift; |
f1bbebac |
244 | my $status = shift || 302; |
73a52566 |
245 | |
246 | $self->location($location); |
247 | $self->status($status); |
248 | } |
249 | |
250 | return $self->location; |
251 | } |
fc7ec1d9 |
252 | |
059c085b |
253 | =head2 $res->location |
254 | |
255 | Sets or returns the HTTP 'Location'. |
256 | |
b5ecfcf0 |
257 | =head2 $res->status |
fc7ec1d9 |
258 | |
910410b8 |
259 | Sets or returns the HTTP status. |
fc7ec1d9 |
260 | |
261 | $c->response->status(404); |
aa9e8261 |
262 | |
263 | $res->code is an alias for this, to match HTTP::Response->code. |
b0ad47c1 |
264 | |
b5ecfcf0 |
265 | =head2 $res->write( $data ) |
fbcc39ad |
266 | |
267 | Writes $data to the output stream. |
268 | |
e37f92f5 |
269 | =head2 $res->write_fh |
270 | |
271 | Returns a PSGI $writer object that has two methods, write and close. You can |
272 | close over this object for asynchronous and nonblocking applications. For |
273 | example (assuming you are using a supporting server, like L<Twiggy> |
274 | |
275 | package AsyncExample::Controller::Root; |
276 | |
277 | use Moose; |
278 | |
279 | BEGIN { extends 'Catalyst::Controller' } |
280 | |
281 | sub prepare_cb { |
282 | my $write_fh = pop; |
283 | return sub { |
284 | my $message = shift; |
285 | $write_fh->write("Finishing: $message\n"); |
286 | $write_fh->close; |
287 | }; |
288 | } |
289 | |
290 | sub anyevent :Local :Args(0) { |
291 | my ($self, $c) = @_; |
292 | my $cb = $self->prepare_cb($c->res->write_fh); |
293 | |
294 | my $watcher; |
295 | $watcher = AnyEvent->timer( |
296 | after => 5, |
297 | cb => sub { |
298 | $cb->(scalar localtime); |
299 | undef $watcher; # cancel circular-ref |
300 | }); |
301 | } |
302 | |
e4cc83b2 |
303 | =head2 $res->print( @data ) |
304 | |
305 | Prints @data to the output stream, separated by $,. This lets you pass |
306 | the response object to functions that want to write to an L<IO::Handle>. |
307 | |
8738b8fe |
308 | =head2 $self->finalize_headers($c) |
309 | |
310 | Writes headers to response if not already written |
311 | |
faa02805 |
312 | =head2 DEMOLISH |
313 | |
314 | Ensures that the response is flushed and closed at the end of the |
315 | request. |
316 | |
317 | =head2 meta |
318 | |
319 | Provided by Moose |
320 | |
e4cc83b2 |
321 | =cut |
322 | |
323 | sub print { |
324 | my $self = shift; |
325 | my $data = shift; |
326 | |
327 | defined $self->write($data) or return; |
328 | |
329 | for (@_) { |
330 | defined $self->write($,) or return; |
331 | defined $self->write($_) or return; |
332 | } |
fe3083a8 |
333 | defined $self->write($\) or return; |
b0ad47c1 |
334 | |
e4cc83b2 |
335 | return 1; |
336 | } |
337 | |
910410b8 |
338 | =head1 AUTHORS |
fc7ec1d9 |
339 | |
2f381252 |
340 | Catalyst Contributors, see Catalyst.pm |
fc7ec1d9 |
341 | |
342 | =head1 COPYRIGHT |
343 | |
b0ad47c1 |
344 | This library is free software. You can redistribute it and/or modify |
61b1e958 |
345 | it under the same terms as Perl itself. |
fc7ec1d9 |
346 | |
347 | =cut |
348 | |
e5ecd5bc |
349 | __PACKAGE__->meta->make_immutable; |
350 | |
fc7ec1d9 |
351 | 1; |