| 1 | package PAGI::Response; | ||||||||||||||||||||||||||||||||||||||||||
| 2 | 20 | $PAGI::Response::VERSION = '0.002002'; | |||||||||||||||||||||||||||||||||||||||||
| 3 | 20 | ▶ | use strict; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 4 | 20 | ▶ | use warnings; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 5 | |||||||||||||||||||||||||||||||||||||||||||
| 6 | 20 | ▶ | use Future::AsyncAwait; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 7 | 20 | ▶ | use Carp qw(croak); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 8 | 20 | ▶ | use Encode qw(encode FB_CROAK); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 9 | 20 | ▶ | use JSON::MaybeXS (); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 10 | 20 | ▶ | use PAGI::Headers (); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 11 | |||||||||||||||||||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||||||||||||||||
| 13 | =encoding UTF-8 | ||||||||||||||||||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||||||||||||||||
| 15 | =head1 NAME | ||||||||||||||||||||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||||||||||||||||||||
| 17 | PAGI::Response - Fluent response builder for PAGI applications | ||||||||||||||||||||||||||||||||||||||||||
| 18 | |||||||||||||||||||||||||||||||||||||||||||
| 19 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||||||||||||||||
| 20 | |||||||||||||||||||||||||||||||||||||||||||
| 21 | use PAGI::Response; | ||||||||||||||||||||||||||||||||||||||||||
| 22 | use Future::AsyncAwait; | ||||||||||||||||||||||||||||||||||||||||||
| 23 | |||||||||||||||||||||||||||||||||||||||||||
| 24 | # A response is a VALUE: build it, then send it (or return it, or mount it). | ||||||||||||||||||||||||||||||||||||||||||
| 25 | |||||||||||||||||||||||||||||||||||||||||||
| 26 | # Raw PAGI app: build the value, send it with respond($send) | ||||||||||||||||||||||||||||||||||||||||||
| 27 | async sub app ($scope, $receive, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 28 | my $res = PAGI::Response->new($scope); # detached -- no connection | ||||||||||||||||||||||||||||||||||||||||||
| 29 | await $res->status(200) | ||||||||||||||||||||||||||||||||||||||||||
| 30 | ->header('X-Custom' => 'value') | ||||||||||||||||||||||||||||||||||||||||||
| 31 | ->json({ message => 'Hello' }) # sets the body, returns $self | ||||||||||||||||||||||||||||||||||||||||||
| 32 | ->respond($send); # the single send step | ||||||||||||||||||||||||||||||||||||||||||
| 33 | } | ||||||||||||||||||||||||||||||||||||||||||
| 34 | |||||||||||||||||||||||||||||||||||||||||||
| 35 | # In an endpoint you just RETURN it; dispatch sends it for you: | ||||||||||||||||||||||||||||||||||||||||||
| 36 | async sub get ($self, $ctx) { | ||||||||||||||||||||||||||||||||||||||||||
| 37 | return $ctx->json({ message => 'Hello' }, status => 200); | ||||||||||||||||||||||||||||||||||||||||||
| 38 | } | ||||||||||||||||||||||||||||||||||||||||||
| 39 | |||||||||||||||||||||||||||||||||||||||||||
| 40 | # Class-method factories build a detached response in one call; | ||||||||||||||||||||||||||||||||||||||||||
| 41 | # status/content_type/headers go as trailing options: | ||||||||||||||||||||||||||||||||||||||||||
| 42 | my $res = PAGI::Response->text("Hello World"); | ||||||||||||||||||||||||||||||||||||||||||
| 43 | my $res = PAGI::Response->html("<h1>Hello</h1>"); | ||||||||||||||||||||||||||||||||||||||||||
| 44 | my $res = PAGI::Response->json({ data => 'value' }); | ||||||||||||||||||||||||||||||||||||||||||
| 45 | my $res = PAGI::Response->json({ error => 'not found' }, status => 404); | ||||||||||||||||||||||||||||||||||||||||||
| 46 | my $res = PAGI::Response->redirect('/login'); | ||||||||||||||||||||||||||||||||||||||||||
| 47 | |||||||||||||||||||||||||||||||||||||||||||
| 48 | # Because it's a value, it works anywhere an app does: | ||||||||||||||||||||||||||||||||||||||||||
| 49 | $router->mount('/health' => PAGI::Response->json({ ok => \1 })); | ||||||||||||||||||||||||||||||||||||||||||
| 50 | |||||||||||||||||||||||||||||||||||||||||||
| 51 | # Streaming: the callback runs at send time (auto-closes when done) | ||||||||||||||||||||||||||||||||||||||||||
| 52 | await PAGI::Response->new($scope) | ||||||||||||||||||||||||||||||||||||||||||
| 53 | ->content_type('text/csv') | ||||||||||||||||||||||||||||||||||||||||||
| 54 | ->stream(async sub ($writer) { | ||||||||||||||||||||||||||||||||||||||||||
| 55 | await $writer->write("id,name\n"); | ||||||||||||||||||||||||||||||||||||||||||
| 56 | await $writer->write("1,Alice\n"); | ||||||||||||||||||||||||||||||||||||||||||
| 57 | }) | ||||||||||||||||||||||||||||||||||||||||||
| 58 | ->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 59 | |||||||||||||||||||||||||||||||||||||||||||
| 60 | # File downloads: | ||||||||||||||||||||||||||||||||||||||||||
| 61 | await PAGI::Response->new($scope) | ||||||||||||||||||||||||||||||||||||||||||
| 62 | ->send_file('/path/to/file.pdf', filename => 'doc.pdf') | ||||||||||||||||||||||||||||||||||||||||||
| 63 | ->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 64 | |||||||||||||||||||||||||||||||||||||||||||
| 65 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||||||||||||||||
| 66 | |||||||||||||||||||||||||||||||||||||||||||
| 67 | PAGI::Response provides a fluent interface for building HTTP responses in | ||||||||||||||||||||||||||||||||||||||||||
| 68 | PAGI applications. It is a detached value object: it holds status, headers, | ||||||||||||||||||||||||||||||||||||||||||
| 69 | and body but has no connection. Sending is done via L</respond> or L</to_app>. | ||||||||||||||||||||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||||||||||||||||||||
| 71 | B<Chainable methods> (C<status>, C<header>, C<content_type>, C<cookie>) | ||||||||||||||||||||||||||||||||||||||||||
| 72 | return C<$self> for fluent chaining. | ||||||||||||||||||||||||||||||||||||||||||
| 73 | |||||||||||||||||||||||||||||||||||||||||||
| 74 | B<Body methods> (C<text>, C<html>, C<json>, C<redirect>, etc.) set the | ||||||||||||||||||||||||||||||||||||||||||
| 75 | response body and also return C<$self>. They can be called as class-method | ||||||||||||||||||||||||||||||||||||||||||
| 76 | factories (C<< PAGI::Response->json($data) >>) or as instance methods | ||||||||||||||||||||||||||||||||||||||||||
| 77 | (C<< $res->json($data) >>). | ||||||||||||||||||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||||||||||||||||||
| 79 | =head1 CONSTRUCTOR | ||||||||||||||||||||||||||||||||||||||||||
| 80 | |||||||||||||||||||||||||||||||||||||||||||
| 81 | =head2 new | ||||||||||||||||||||||||||||||||||||||||||
| 82 | |||||||||||||||||||||||||||||||||||||||||||
| 83 | my $res = PAGI::Response->new; | ||||||||||||||||||||||||||||||||||||||||||
| 84 | my $res = PAGI::Response->new($scope); | ||||||||||||||||||||||||||||||||||||||||||
| 85 | |||||||||||||||||||||||||||||||||||||||||||
| 86 | Creates a detached response value. The response holds no connection and no | ||||||||||||||||||||||||||||||||||||||||||
| 87 | C<$send> callback — it is a pure value object that accumulates status, | ||||||||||||||||||||||||||||||||||||||||||
| 88 | headers, and body via the chainer methods. | ||||||||||||||||||||||||||||||||||||||||||
| 89 | |||||||||||||||||||||||||||||||||||||||||||
| 90 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 91 | |||||||||||||||||||||||||||||||||||||||||||
| 92 | =item C<$scope> - Optional. A PAGI scope hashref. When provided it is stored | ||||||||||||||||||||||||||||||||||||||||||
| 93 | inert (for accessors like C<scope()> and helpers like L<PAGI::Stash>). | ||||||||||||||||||||||||||||||||||||||||||
| 94 | It is B<not> used as a connection — no C<$send> is stored here. | ||||||||||||||||||||||||||||||||||||||||||
| 95 | |||||||||||||||||||||||||||||||||||||||||||
| 96 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 97 | |||||||||||||||||||||||||||||||||||||||||||
| 98 | To actually send the response, call L</respond> with the C<$send> callback, | ||||||||||||||||||||||||||||||||||||||||||
| 99 | or mount it as a PAGI app via L</to_app>. | ||||||||||||||||||||||||||||||||||||||||||
| 100 | |||||||||||||||||||||||||||||||||||||||||||
| 101 | Because the constructor stores no connection, the same response value can be | ||||||||||||||||||||||||||||||||||||||||||
| 102 | served to multiple connections (re-entrantly) by calling C<respond> more than | ||||||||||||||||||||||||||||||||||||||||||
| 103 | once. | ||||||||||||||||||||||||||||||||||||||||||
| 104 | |||||||||||||||||||||||||||||||||||||||||||
| 105 | =head1 CHAINABLE METHODS | ||||||||||||||||||||||||||||||||||||||||||
| 106 | |||||||||||||||||||||||||||||||||||||||||||
| 107 | These methods return C<$self> for fluent chaining. | ||||||||||||||||||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||||||||||||||||
| 109 | =head2 status | ||||||||||||||||||||||||||||||||||||||||||
| 110 | |||||||||||||||||||||||||||||||||||||||||||
| 111 | $res->status(404); | ||||||||||||||||||||||||||||||||||||||||||
| 112 | my $code = $res->status; | ||||||||||||||||||||||||||||||||||||||||||
| 113 | |||||||||||||||||||||||||||||||||||||||||||
| 114 | Set or get the HTTP status code (100-599). Returns C<$self> when setting | ||||||||||||||||||||||||||||||||||||||||||
| 115 | for fluent chaining. When getting, returns 200 if no status has been set. | ||||||||||||||||||||||||||||||||||||||||||
| 116 | |||||||||||||||||||||||||||||||||||||||||||
| 117 | my $res = PAGI::Response->new($scope); | ||||||||||||||||||||||||||||||||||||||||||
| 118 | $res->status; # 200 (default, nothing set yet) | ||||||||||||||||||||||||||||||||||||||||||
| 119 | $res->has_status; # false | ||||||||||||||||||||||||||||||||||||||||||
| 120 | $res->status(201); # set explicitly | ||||||||||||||||||||||||||||||||||||||||||
| 121 | $res->has_status; # true | ||||||||||||||||||||||||||||||||||||||||||
| 122 | |||||||||||||||||||||||||||||||||||||||||||
| 123 | =head2 status_try | ||||||||||||||||||||||||||||||||||||||||||
| 124 | |||||||||||||||||||||||||||||||||||||||||||
| 125 | $res->status_try(404); | ||||||||||||||||||||||||||||||||||||||||||
| 126 | |||||||||||||||||||||||||||||||||||||||||||
| 127 | Set the HTTP status code only if one hasn't been set yet. Useful in | ||||||||||||||||||||||||||||||||||||||||||
| 128 | middleware or error handlers to provide fallback status codes without | ||||||||||||||||||||||||||||||||||||||||||
| 129 | overriding choices made by the application: | ||||||||||||||||||||||||||||||||||||||||||
| 130 | |||||||||||||||||||||||||||||||||||||||||||
| 131 | $res->status_try(202); # sets to 202 (nothing was set) | ||||||||||||||||||||||||||||||||||||||||||
| 132 | $res->status_try(500); # no-op, 202 already set | ||||||||||||||||||||||||||||||||||||||||||
| 133 | |||||||||||||||||||||||||||||||||||||||||||
| 134 | =head2 header | ||||||||||||||||||||||||||||||||||||||||||
| 135 | |||||||||||||||||||||||||||||||||||||||||||
| 136 | $res->header('X-Custom' => 'value'); | ||||||||||||||||||||||||||||||||||||||||||
| 137 | my $value = $res->header('X-Custom'); | ||||||||||||||||||||||||||||||||||||||||||
| 138 | |||||||||||||||||||||||||||||||||||||||||||
| 139 | Add a response header. Can be called multiple times to add multiple headers. | ||||||||||||||||||||||||||||||||||||||||||
| 140 | If called with only a name, returns the last value for that header or C<undef>. | ||||||||||||||||||||||||||||||||||||||||||
| 141 | |||||||||||||||||||||||||||||||||||||||||||
| 142 | =head2 headers | ||||||||||||||||||||||||||||||||||||||||||
| 143 | |||||||||||||||||||||||||||||||||||||||||||
| 144 | my $headers = $res->headers; | ||||||||||||||||||||||||||||||||||||||||||
| 145 | |||||||||||||||||||||||||||||||||||||||||||
| 146 | Returns the response headers as a L<PAGI::Headers> object. The object's C<@{}> | ||||||||||||||||||||||||||||||||||||||||||
| 147 | overload yields a copy of the C<[name, value]> pairs in insertion order, so | ||||||||||||||||||||||||||||||||||||||||||
| 148 | existing code that iterates C<@{$res->headers}> continues to work. | ||||||||||||||||||||||||||||||||||||||||||
| 149 | |||||||||||||||||||||||||||||||||||||||||||
| 150 | =head2 header_all | ||||||||||||||||||||||||||||||||||||||||||
| 151 | |||||||||||||||||||||||||||||||||||||||||||
| 152 | my @values = $res->header_all('Set-Cookie'); | ||||||||||||||||||||||||||||||||||||||||||
| 153 | |||||||||||||||||||||||||||||||||||||||||||
| 154 | Returns all values for the given header name (case-insensitive). | ||||||||||||||||||||||||||||||||||||||||||
| 155 | |||||||||||||||||||||||||||||||||||||||||||
| 156 | =head2 header_try | ||||||||||||||||||||||||||||||||||||||||||
| 157 | |||||||||||||||||||||||||||||||||||||||||||
| 158 | $res->header_try('X-Custom' => 'value'); | ||||||||||||||||||||||||||||||||||||||||||
| 159 | |||||||||||||||||||||||||||||||||||||||||||
| 160 | Add a response header only if that header name has not already been set. | ||||||||||||||||||||||||||||||||||||||||||
| 161 | |||||||||||||||||||||||||||||||||||||||||||
| 162 | =head2 remove_header | ||||||||||||||||||||||||||||||||||||||||||
| 163 | |||||||||||||||||||||||||||||||||||||||||||
| 164 | $res->remove_header('X-Custom'); | ||||||||||||||||||||||||||||||||||||||||||
| 165 | |||||||||||||||||||||||||||||||||||||||||||
| 166 | Remove all instances of the named header (case-insensitive). Returns C<$self> | ||||||||||||||||||||||||||||||||||||||||||
| 167 | for fluent chaining. No-op if the header was not set. | ||||||||||||||||||||||||||||||||||||||||||
| 168 | |||||||||||||||||||||||||||||||||||||||||||
| 169 | =head2 content_type | ||||||||||||||||||||||||||||||||||||||||||
| 170 | |||||||||||||||||||||||||||||||||||||||||||
| 171 | $res->content_type('text/html; charset=utf-8'); | ||||||||||||||||||||||||||||||||||||||||||
| 172 | my $type = $res->content_type; | ||||||||||||||||||||||||||||||||||||||||||
| 173 | $res->content_type(undef); # clears Content-Type so a body method can re-default it | ||||||||||||||||||||||||||||||||||||||||||
| 174 | |||||||||||||||||||||||||||||||||||||||||||
| 175 | Set the Content-Type header, replacing any existing one. Passing C<undef> | ||||||||||||||||||||||||||||||||||||||||||
| 176 | removes Content-Type entirely, which lets a subsequent body method (C<html>, | ||||||||||||||||||||||||||||||||||||||||||
| 177 | C<text>, C<json>) re-apply its default. | ||||||||||||||||||||||||||||||||||||||||||
| 178 | |||||||||||||||||||||||||||||||||||||||||||
| 179 | =head2 content_type_try | ||||||||||||||||||||||||||||||||||||||||||
| 180 | |||||||||||||||||||||||||||||||||||||||||||
| 181 | $res->content_type_try('text/html; charset=utf-8'); | ||||||||||||||||||||||||||||||||||||||||||
| 182 | |||||||||||||||||||||||||||||||||||||||||||
| 183 | Set the Content-Type header only if it has not already been set. | ||||||||||||||||||||||||||||||||||||||||||
| 184 | |||||||||||||||||||||||||||||||||||||||||||
| 185 | =head2 cookie | ||||||||||||||||||||||||||||||||||||||||||
| 186 | |||||||||||||||||||||||||||||||||||||||||||
| 187 | $res->cookie('session' => 'abc123', | ||||||||||||||||||||||||||||||||||||||||||
| 188 | max_age => 3600, | ||||||||||||||||||||||||||||||||||||||||||
| 189 | path => '/', | ||||||||||||||||||||||||||||||||||||||||||
| 190 | domain => 'example.com', | ||||||||||||||||||||||||||||||||||||||||||
| 191 | secure => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 192 | httponly => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 193 | samesite => 'Strict', | ||||||||||||||||||||||||||||||||||||||||||
| 194 | ); | ||||||||||||||||||||||||||||||||||||||||||
| 195 | |||||||||||||||||||||||||||||||||||||||||||
| 196 | Set a response cookie. Options: max_age, expires, path, domain, secure, | ||||||||||||||||||||||||||||||||||||||||||
| 197 | httponly, samesite. | ||||||||||||||||||||||||||||||||||||||||||
| 198 | |||||||||||||||||||||||||||||||||||||||||||
| 199 | =head2 delete_cookie | ||||||||||||||||||||||||||||||||||||||||||
| 200 | |||||||||||||||||||||||||||||||||||||||||||
| 201 | $res->delete_cookie('session'); | ||||||||||||||||||||||||||||||||||||||||||
| 202 | |||||||||||||||||||||||||||||||||||||||||||
| 203 | Delete a cookie by setting it with Max-Age=0. | ||||||||||||||||||||||||||||||||||||||||||
| 204 | |||||||||||||||||||||||||||||||||||||||||||
| 205 | =head2 scope | ||||||||||||||||||||||||||||||||||||||||||
| 206 | |||||||||||||||||||||||||||||||||||||||||||
| 207 | my $scope = $res->scope; | ||||||||||||||||||||||||||||||||||||||||||
| 208 | |||||||||||||||||||||||||||||||||||||||||||
| 209 | Returns the raw PAGI scope hashref. Useful for constructing helper | ||||||||||||||||||||||||||||||||||||||||||
| 210 | objects like L<PAGI::Stash> and L<PAGI::Session>: | ||||||||||||||||||||||||||||||||||||||||||
| 211 | |||||||||||||||||||||||||||||||||||||||||||
| 212 | my $stash = PAGI::Stash->new($res); | ||||||||||||||||||||||||||||||||||||||||||
| 213 | |||||||||||||||||||||||||||||||||||||||||||
| 214 | =head2 Per-Request Shared State | ||||||||||||||||||||||||||||||||||||||||||
| 215 | |||||||||||||||||||||||||||||||||||||||||||
| 216 | See L<PAGI::Stash> for per-request shared state. Construct from a | ||||||||||||||||||||||||||||||||||||||||||
| 217 | Response object or from the shared scope: | ||||||||||||||||||||||||||||||||||||||||||
| 218 | |||||||||||||||||||||||||||||||||||||||||||
| 219 | use PAGI::Stash; | ||||||||||||||||||||||||||||||||||||||||||
| 220 | my $stash = PAGI::Stash->new($res); | ||||||||||||||||||||||||||||||||||||||||||
| 221 | |||||||||||||||||||||||||||||||||||||||||||
| 222 | =head2 is_sent | ||||||||||||||||||||||||||||||||||||||||||
| 223 | |||||||||||||||||||||||||||||||||||||||||||
| 224 | if ($res->is_sent) { | ||||||||||||||||||||||||||||||||||||||||||
| 225 | warn "Response already sent, cannot send error"; | ||||||||||||||||||||||||||||||||||||||||||
| 226 | return; | ||||||||||||||||||||||||||||||||||||||||||
| 227 | } | ||||||||||||||||||||||||||||||||||||||||||
| 228 | |||||||||||||||||||||||||||||||||||||||||||
| 229 | Returns true if the server-owned C<pagi.connection> object for this request | ||||||||||||||||||||||||||||||||||||||||||
| 230 | reports C<response_started> — meaning the response has started on this | ||||||||||||||||||||||||||||||||||||||||||
| 231 | connection (headers have been emitted). Reflects a server-owned fact, not a | ||||||||||||||||||||||||||||||||||||||||||
| 232 | flag on this Response value. | ||||||||||||||||||||||||||||||||||||||||||
| 233 | |||||||||||||||||||||||||||||||||||||||||||
| 234 | Returns 0 if there is no C<pagi.connection> in scope (server-less / not | ||||||||||||||||||||||||||||||||||||||||||
| 235 | started). Dies (C<croak>) if a C<pagi.connection> is present but lacks the | ||||||||||||||||||||||||||||||||||||||||||
| 236 | C<response_started> method, which indicates a non-conforming server. | ||||||||||||||||||||||||||||||||||||||||||
| 237 | |||||||||||||||||||||||||||||||||||||||||||
| 238 | =head2 has_status | ||||||||||||||||||||||||||||||||||||||||||
| 239 | |||||||||||||||||||||||||||||||||||||||||||
| 240 | if ($res->has_status) { ... } | ||||||||||||||||||||||||||||||||||||||||||
| 241 | |||||||||||||||||||||||||||||||||||||||||||
| 242 | Returns true if a status code has been explicitly set via C<status> or | ||||||||||||||||||||||||||||||||||||||||||
| 243 | C<status_try>. | ||||||||||||||||||||||||||||||||||||||||||
| 244 | |||||||||||||||||||||||||||||||||||||||||||
| 245 | =head2 has_header | ||||||||||||||||||||||||||||||||||||||||||
| 246 | |||||||||||||||||||||||||||||||||||||||||||
| 247 | if ($res->has_header('content-type')) { ... } | ||||||||||||||||||||||||||||||||||||||||||
| 248 | |||||||||||||||||||||||||||||||||||||||||||
| 249 | Returns true if the given header name has been set via C<header> or | ||||||||||||||||||||||||||||||||||||||||||
| 250 | C<header_try>. Header names are case-insensitive. | ||||||||||||||||||||||||||||||||||||||||||
| 251 | |||||||||||||||||||||||||||||||||||||||||||
| 252 | =head2 has_content_type | ||||||||||||||||||||||||||||||||||||||||||
| 253 | |||||||||||||||||||||||||||||||||||||||||||
| 254 | if ($res->has_content_type) { ... } | ||||||||||||||||||||||||||||||||||||||||||
| 255 | |||||||||||||||||||||||||||||||||||||||||||
| 256 | Returns true if Content-Type has been explicitly set via C<content_type>, | ||||||||||||||||||||||||||||||||||||||||||
| 257 | C<content_type_try>, or C<header>/C<header_try> with a Content-Type name. | ||||||||||||||||||||||||||||||||||||||||||
| 258 | |||||||||||||||||||||||||||||||||||||||||||
| 259 | =head2 has_body_source | ||||||||||||||||||||||||||||||||||||||||||
| 260 | |||||||||||||||||||||||||||||||||||||||||||
| 261 | if ($res->has_body_source) { ... } | ||||||||||||||||||||||||||||||||||||||||||
| 262 | |||||||||||||||||||||||||||||||||||||||||||
| 263 | Returns true if a B<body source> has been registered on the response — a | ||||||||||||||||||||||||||||||||||||||||||
| 264 | buffered body (via C<text>/C<html>/C<json>/C<send>/C<send_raw>/C<empty>/ | ||||||||||||||||||||||||||||||||||||||||||
| 265 | C<redirect>), a file (via C<send_file>), or a stream callback (via C<stream>). | ||||||||||||||||||||||||||||||||||||||||||
| 266 | |||||||||||||||||||||||||||||||||||||||||||
| 267 | This is a B<build-phase, intent-level> signal. It answers "did the handler | ||||||||||||||||||||||||||||||||||||||||||
| 268 | register something to send?", B<not> "have any bytes been produced or sent": | ||||||||||||||||||||||||||||||||||||||||||
| 269 | |||||||||||||||||||||||||||||||||||||||||||
| 270 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 271 | |||||||||||||||||||||||||||||||||||||||||||
| 272 | =item * For a C<stream>, it is true the instant the callback is registered, | ||||||||||||||||||||||||||||||||||||||||||
| 273 | B<before> C<respond> runs it and before a single byte is written. A registered | ||||||||||||||||||||||||||||||||||||||||||
| 274 | stream that has produced zero bytes still reports C<has_body_source> true — that | ||||||||||||||||||||||||||||||||||||||||||
| 275 | is the only coherent meaning, since C<respond> is what drives the stream. | ||||||||||||||||||||||||||||||||||||||||||
| 276 | |||||||||||||||||||||||||||||||||||||||||||
| 277 | =item * An B<intentional empty body> counts: C<empty>, C<redirect>, and | ||||||||||||||||||||||||||||||||||||||||||
| 278 | C<send_raw('')> all register a body (the empty string), so they report true. | ||||||||||||||||||||||||||||||||||||||||||
| 279 | A response that has had no body method called reports false. | ||||||||||||||||||||||||||||||||||||||||||
| 280 | |||||||||||||||||||||||||||||||||||||||||||
| 281 | =item * It is independent of L</is_sent>. C<has_body_source> describes the | ||||||||||||||||||||||||||||||||||||||||||
| 282 | value; C<is_sent> describes whether the value has gone out on a connection. For | ||||||||||||||||||||||||||||||||||||||||||
| 283 | "has the response been emitted", use C<is_sent>; for "has the stream finished", | ||||||||||||||||||||||||||||||||||||||||||
| 284 | C<await> the Future returned by C<respond>. | ||||||||||||||||||||||||||||||||||||||||||
| 285 | |||||||||||||||||||||||||||||||||||||||||||
| 286 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 287 | |||||||||||||||||||||||||||||||||||||||||||
| 288 | A response whose handler set only a status or a header (no body method) reports | ||||||||||||||||||||||||||||||||||||||||||
| 289 | C<has_body_source> false even though it is a legitimate response (e.g. a bare | ||||||||||||||||||||||||||||||||||||||||||
| 290 | C<204> or a redirect built only via C<status> + C<header>). Frameworks deciding | ||||||||||||||||||||||||||||||||||||||||||
| 291 | whether to auto-send should therefore test C<< $res->has_body_source || | ||||||||||||||||||||||||||||||||||||||||||
| 292 | $res->has_status >>. See the L<PAGI::Cookbook/RESPONSE STATE & LIFECYCLE> | ||||||||||||||||||||||||||||||||||||||||||
| 293 | section for the full state model. | ||||||||||||||||||||||||||||||||||||||||||
| 294 | |||||||||||||||||||||||||||||||||||||||||||
| 295 | =head2 cors | ||||||||||||||||||||||||||||||||||||||||||
| 296 | |||||||||||||||||||||||||||||||||||||||||||
| 297 | # Allow all origins (simplest case) | ||||||||||||||||||||||||||||||||||||||||||
| 298 | $res->cors->json({ data => 'value' }); | ||||||||||||||||||||||||||||||||||||||||||
| 299 | |||||||||||||||||||||||||||||||||||||||||||
| 300 | # Allow specific origin | ||||||||||||||||||||||||||||||||||||||||||
| 301 | $res->cors(origin => 'https://example.com')->json($data); | ||||||||||||||||||||||||||||||||||||||||||
| 302 | |||||||||||||||||||||||||||||||||||||||||||
| 303 | # Full configuration | ||||||||||||||||||||||||||||||||||||||||||
| 304 | $res->cors( | ||||||||||||||||||||||||||||||||||||||||||
| 305 | origin => 'https://example.com', | ||||||||||||||||||||||||||||||||||||||||||
| 306 | methods => [qw(GET POST PUT DELETE)], | ||||||||||||||||||||||||||||||||||||||||||
| 307 | headers => [qw(Content-Type Authorization)], | ||||||||||||||||||||||||||||||||||||||||||
| 308 | expose => [qw(X-Request-Id X-RateLimit-Remaining)], | ||||||||||||||||||||||||||||||||||||||||||
| 309 | credentials => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 310 | max_age => 86400, | ||||||||||||||||||||||||||||||||||||||||||
| 311 | preflight => 0, | ||||||||||||||||||||||||||||||||||||||||||
| 312 | )->json($data); | ||||||||||||||||||||||||||||||||||||||||||
| 313 | |||||||||||||||||||||||||||||||||||||||||||
| 314 | Add CORS (Cross-Origin Resource Sharing) headers to the response. | ||||||||||||||||||||||||||||||||||||||||||
| 315 | Returns C<$self> for chaining. | ||||||||||||||||||||||||||||||||||||||||||
| 316 | |||||||||||||||||||||||||||||||||||||||||||
| 317 | B<Options:> | ||||||||||||||||||||||||||||||||||||||||||
| 318 | |||||||||||||||||||||||||||||||||||||||||||
| 319 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 320 | |||||||||||||||||||||||||||||||||||||||||||
| 321 | =item * C<origin> - Allowed origin. Default: C<'*'> (all origins). | ||||||||||||||||||||||||||||||||||||||||||
| 322 | Can be a specific origin like C<'https://example.com'> or C<'*'> for any. | ||||||||||||||||||||||||||||||||||||||||||
| 323 | |||||||||||||||||||||||||||||||||||||||||||
| 324 | =item * C<methods> - Arrayref of allowed HTTP methods for preflight. | ||||||||||||||||||||||||||||||||||||||||||
| 325 | Default: C<[qw(GET POST PUT DELETE PATCH OPTIONS)]>. | ||||||||||||||||||||||||||||||||||||||||||
| 326 | |||||||||||||||||||||||||||||||||||||||||||
| 327 | =item * C<headers> - Arrayref of allowed request headers for preflight. | ||||||||||||||||||||||||||||||||||||||||||
| 328 | Default: C<[qw(Content-Type Authorization X-Requested-With)]>. | ||||||||||||||||||||||||||||||||||||||||||
| 329 | |||||||||||||||||||||||||||||||||||||||||||
| 330 | =item * C<expose> - Arrayref of response headers to expose to the client. | ||||||||||||||||||||||||||||||||||||||||||
| 331 | By default, only simple headers (Cache-Control, Content-Language, etc.) | ||||||||||||||||||||||||||||||||||||||||||
| 332 | are accessible. Use this to expose custom headers. | ||||||||||||||||||||||||||||||||||||||||||
| 333 | |||||||||||||||||||||||||||||||||||||||||||
| 334 | =item * C<credentials> - Boolean. If true, sets | ||||||||||||||||||||||||||||||||||||||||||
| 335 | C<Access-Control-Allow-Credentials: true>, allowing cookies and | ||||||||||||||||||||||||||||||||||||||||||
| 336 | Authorization headers. Default: C<0>. | ||||||||||||||||||||||||||||||||||||||||||
| 337 | |||||||||||||||||||||||||||||||||||||||||||
| 338 | =item * C<max_age> - How long (in seconds) browsers should cache preflight | ||||||||||||||||||||||||||||||||||||||||||
| 339 | results. Default: C<86400> (24 hours). | ||||||||||||||||||||||||||||||||||||||||||
| 340 | |||||||||||||||||||||||||||||||||||||||||||
| 341 | =item * C<preflight> - Boolean. If true, includes preflight response headers | ||||||||||||||||||||||||||||||||||||||||||
| 342 | (Allow-Methods, Allow-Headers, Max-Age). Set this when handling OPTIONS | ||||||||||||||||||||||||||||||||||||||||||
| 343 | requests. Default: C<0>. | ||||||||||||||||||||||||||||||||||||||||||
| 344 | |||||||||||||||||||||||||||||||||||||||||||
| 345 | =item * C<request_origin> - The Origin header value from the request. | ||||||||||||||||||||||||||||||||||||||||||
| 346 | Required when C<credentials> is true and C<origin> is C<'*'>, because | ||||||||||||||||||||||||||||||||||||||||||
| 347 | the CORS spec forbids using C<'*'> with credentials. Pass the actual | ||||||||||||||||||||||||||||||||||||||||||
| 348 | request origin to echo it back. | ||||||||||||||||||||||||||||||||||||||||||
| 349 | |||||||||||||||||||||||||||||||||||||||||||
| 350 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 351 | |||||||||||||||||||||||||||||||||||||||||||
| 352 | B<Important CORS Notes:> | ||||||||||||||||||||||||||||||||||||||||||
| 353 | |||||||||||||||||||||||||||||||||||||||||||
| 354 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 355 | |||||||||||||||||||||||||||||||||||||||||||
| 356 | =item * When C<credentials> is true, you cannot use C<< origin => '*' >>. | ||||||||||||||||||||||||||||||||||||||||||
| 357 | Either specify an exact origin, or pass C<request_origin> with the | ||||||||||||||||||||||||||||||||||||||||||
| 358 | client's actual Origin header. | ||||||||||||||||||||||||||||||||||||||||||
| 359 | |||||||||||||||||||||||||||||||||||||||||||
| 360 | =item * The C<Vary: Origin> header is always set to ensure proper caching | ||||||||||||||||||||||||||||||||||||||||||
| 361 | when origin-specific responses are used. | ||||||||||||||||||||||||||||||||||||||||||
| 362 | |||||||||||||||||||||||||||||||||||||||||||
| 363 | =item * For preflight (OPTIONS) requests, set C<< preflight => 1 >> and | ||||||||||||||||||||||||||||||||||||||||||
| 364 | typically respond with C<< $res->status(204)->empty() >>. | ||||||||||||||||||||||||||||||||||||||||||
| 365 | |||||||||||||||||||||||||||||||||||||||||||
| 366 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 367 | |||||||||||||||||||||||||||||||||||||||||||
| 368 | =head1 SEND PRIMITIVE AND APP MOUNTING | ||||||||||||||||||||||||||||||||||||||||||
| 369 | |||||||||||||||||||||||||||||||||||||||||||
| 370 | =head2 respond | ||||||||||||||||||||||||||||||||||||||||||
| 371 | |||||||||||||||||||||||||||||||||||||||||||
| 372 | await $res->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 373 | |||||||||||||||||||||||||||||||||||||||||||
| 374 | The single send primitive for a detached response value. Reads the | ||||||||||||||||||||||||||||||||||||||||||
| 375 | accumulated status, headers, and body from C<$self> and emits the | ||||||||||||||||||||||||||||||||||||||||||
| 376 | appropriate PAGI protocol events via C<$send>. | ||||||||||||||||||||||||||||||||||||||||||
| 377 | |||||||||||||||||||||||||||||||||||||||||||
| 378 | C<$send> must be a coderef (the PAGI send callback). C<respond> does | ||||||||||||||||||||||||||||||||||||||||||
| 379 | B<not> mutate the response object, so the same response value can be | ||||||||||||||||||||||||||||||||||||||||||
| 380 | passed to C<respond> multiple times for different connections. | ||||||||||||||||||||||||||||||||||||||||||
| 381 | |||||||||||||||||||||||||||||||||||||||||||
| 382 | For streaming responses (set up via the C<_stream> slot), C<respond> | ||||||||||||||||||||||||||||||||||||||||||
| 383 | sends the start event, runs the stream callback with a | ||||||||||||||||||||||||||||||||||||||||||
| 384 | L<PAGI::Response::Writer>, and ensures the writer is closed. | ||||||||||||||||||||||||||||||||||||||||||
| 385 | |||||||||||||||||||||||||||||||||||||||||||
| 386 | Returns a L<Future>. | ||||||||||||||||||||||||||||||||||||||||||
| 387 | |||||||||||||||||||||||||||||||||||||||||||
| 388 | =head2 to_app | ||||||||||||||||||||||||||||||||||||||||||
| 389 | |||||||||||||||||||||||||||||||||||||||||||
| 390 | my $app = $res->to_app; | ||||||||||||||||||||||||||||||||||||||||||
| 391 | |||||||||||||||||||||||||||||||||||||||||||
| 392 | Returns a PAGI application coderef C<sub ($scope, $receive, $send)> that | ||||||||||||||||||||||||||||||||||||||||||
| 393 | calls L</respond> with the given C<$send> when invoked. Use this to mount | ||||||||||||||||||||||||||||||||||||||||||
| 394 | a response value directly as a PAGI app: | ||||||||||||||||||||||||||||||||||||||||||
| 395 | |||||||||||||||||||||||||||||||||||||||||||
| 396 | my $not_found = PAGI::Response->new | ||||||||||||||||||||||||||||||||||||||||||
| 397 | ->status(404) | ||||||||||||||||||||||||||||||||||||||||||
| 398 | ->_set_body('Not Found', 'text/plain'); | ||||||||||||||||||||||||||||||||||||||||||
| 399 | |||||||||||||||||||||||||||||||||||||||||||
| 400 | # Mount as a fallback app | ||||||||||||||||||||||||||||||||||||||||||
| 401 | my $app = $not_found->to_app; | ||||||||||||||||||||||||||||||||||||||||||
| 402 | |||||||||||||||||||||||||||||||||||||||||||
| 403 | =head1 BODY METHODS | ||||||||||||||||||||||||||||||||||||||||||
| 404 | |||||||||||||||||||||||||||||||||||||||||||
| 405 | These methods set the response body and return C<$self>. Sending happens via | ||||||||||||||||||||||||||||||||||||||||||
| 406 | L</respond> / L</to_app> or the endpoint return contract. | ||||||||||||||||||||||||||||||||||||||||||
| 407 | |||||||||||||||||||||||||||||||||||||||||||
| 408 | Each method works as both a B<class-method factory> and an B<instance method>: | ||||||||||||||||||||||||||||||||||||||||||
| 409 | |||||||||||||||||||||||||||||||||||||||||||
| 410 | # Class-method factory — creates a new detached response and returns it | ||||||||||||||||||||||||||||||||||||||||||
| 411 | return $ctx->json($data); # instance method on existing $res | ||||||||||||||||||||||||||||||||||||||||||
| 412 | return PAGI::Response->json($data); # factory shorthand | ||||||||||||||||||||||||||||||||||||||||||
| 413 | |||||||||||||||||||||||||||||||||||||||||||
| 414 | # Chain body with other setters before sending | ||||||||||||||||||||||||||||||||||||||||||
| 415 | PAGI::Response->json($data)->status(201)->respond($send)->get; | ||||||||||||||||||||||||||||||||||||||||||
| 416 | |||||||||||||||||||||||||||||||||||||||||||
| 417 | The Content-Type these methods set is a B<default>: an explicit C<content_type> | ||||||||||||||||||||||||||||||||||||||||||
| 418 | set beforehand is preserved, not overridden. | ||||||||||||||||||||||||||||||||||||||||||
| 419 | |||||||||||||||||||||||||||||||||||||||||||
| 420 | These helpers UTF-8-encode the body, so they make the Content-Type advertise | ||||||||||||||||||||||||||||||||||||||||||
| 421 | that encoding. When you preset a charset-less type they append C<; charset=utf-8> | ||||||||||||||||||||||||||||||||||||||||||
| 422 | to it — C<< content_type('application/xml')->html($xml) >> sends | ||||||||||||||||||||||||||||||||||||||||||
| 423 | C<application/xml; charset=utf-8> (charset is meaningful for XML and C<text/*>, | ||||||||||||||||||||||||||||||||||||||||||
| 424 | RFC 7303). The exceptions are C<application/json> and the C<+json> structured-suffix | ||||||||||||||||||||||||||||||||||||||||||
| 425 | types, which are left bare: JSON is always UTF-8 and defines no charset parameter | ||||||||||||||||||||||||||||||||||||||||||
| 426 | (RFC 8259). An explicit charset you set yourself is never overridden. If you need | ||||||||||||||||||||||||||||||||||||||||||
| 427 | a body in some other encoding, encode it yourself and use L</send_raw>. | ||||||||||||||||||||||||||||||||||||||||||
| 428 | |||||||||||||||||||||||||||||||||||||||||||
| 429 | =head2 Trailing options (status, content_type, headers) | ||||||||||||||||||||||||||||||||||||||||||
| 430 | |||||||||||||||||||||||||||||||||||||||||||
| 431 | The body methods C<text>, C<html>, C<json>, C<send_raw>, and C<empty> accept | ||||||||||||||||||||||||||||||||||||||||||
| 432 | trailing named options as a convenience so you can set status, content-type, | ||||||||||||||||||||||||||||||||||||||||||
| 433 | and extra headers in a single call without chaining: | ||||||||||||||||||||||||||||||||||||||||||
| 434 | |||||||||||||||||||||||||||||||||||||||||||
| 435 | PAGI::Response->json($data, status => 404); | ||||||||||||||||||||||||||||||||||||||||||
| 436 | PAGI::Response->text('Hi', status => 201, headers => ['X-Foo' => 'bar']); | ||||||||||||||||||||||||||||||||||||||||||
| 437 | PAGI::Response->send_raw($bytes, content_type => 'application/octet-stream'); | ||||||||||||||||||||||||||||||||||||||||||
| 438 | PAGI::Response->empty(status => 304); | ||||||||||||||||||||||||||||||||||||||||||
| 439 | |||||||||||||||||||||||||||||||||||||||||||
| 440 | Recognised options: | ||||||||||||||||||||||||||||||||||||||||||
| 441 | |||||||||||||||||||||||||||||||||||||||||||
| 442 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 443 | |||||||||||||||||||||||||||||||||||||||||||
| 444 | =item B<status> — HTTP status code (integer). | ||||||||||||||||||||||||||||||||||||||||||
| 445 | |||||||||||||||||||||||||||||||||||||||||||
| 446 | =item B<content_type> — sets the Content-Type header, overriding any default. | ||||||||||||||||||||||||||||||||||||||||||
| 447 | |||||||||||||||||||||||||||||||||||||||||||
| 448 | =item B<headers> — a flat arrayref of C<< name => value >> pairs to append. | ||||||||||||||||||||||||||||||||||||||||||
| 449 | Example: C<< headers => ['X-Foo' => 'bar', 'X-Baz' => 'qux'] >>. | ||||||||||||||||||||||||||||||||||||||||||
| 450 | |||||||||||||||||||||||||||||||||||||||||||
| 451 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 452 | |||||||||||||||||||||||||||||||||||||||||||
| 453 | An unrecognised option name causes an immediate C<croak>, catching typos such | ||||||||||||||||||||||||||||||||||||||||||
| 454 | as C<status_code => 404> before they silently send 200. | ||||||||||||||||||||||||||||||||||||||||||
| 455 | |||||||||||||||||||||||||||||||||||||||||||
| 456 | The existing chaining form C<< ->json($data)->status(404) >> keeps working. | ||||||||||||||||||||||||||||||||||||||||||
| 457 | |||||||||||||||||||||||||||||||||||||||||||
| 458 | =head2 text | ||||||||||||||||||||||||||||||||||||||||||
| 459 | |||||||||||||||||||||||||||||||||||||||||||
| 460 | $res->text("Hello World"); | ||||||||||||||||||||||||||||||||||||||||||
| 461 | PAGI::Response->text("Hello World"); | ||||||||||||||||||||||||||||||||||||||||||
| 462 | PAGI::Response->text("Not found", status => 404); | ||||||||||||||||||||||||||||||||||||||||||
| 463 | |||||||||||||||||||||||||||||||||||||||||||
| 464 | Set body to the UTF-8–encoded string with Content-Type: text/plain; charset=utf-8. | ||||||||||||||||||||||||||||||||||||||||||
| 465 | Accepts trailing options (C<status>, C<content_type>, C<headers>). Returns C<$self>. | ||||||||||||||||||||||||||||||||||||||||||
| 466 | |||||||||||||||||||||||||||||||||||||||||||
| 467 | =head2 html | ||||||||||||||||||||||||||||||||||||||||||
| 468 | |||||||||||||||||||||||||||||||||||||||||||
| 469 | $res->html("<h1>Hello</h1>"); | ||||||||||||||||||||||||||||||||||||||||||
| 470 | PAGI::Response->html("<h1>Hello</h1>"); | ||||||||||||||||||||||||||||||||||||||||||
| 471 | PAGI::Response->html("<p>Error</p>", status => 500); | ||||||||||||||||||||||||||||||||||||||||||
| 472 | |||||||||||||||||||||||||||||||||||||||||||
| 473 | Set body to the UTF-8–encoded string with Content-Type: text/html; charset=utf-8. | ||||||||||||||||||||||||||||||||||||||||||
| 474 | Accepts trailing options (C<status>, C<content_type>, C<headers>). Returns C<$self>. | ||||||||||||||||||||||||||||||||||||||||||
| 475 | |||||||||||||||||||||||||||||||||||||||||||
| 476 | =head2 json | ||||||||||||||||||||||||||||||||||||||||||
| 477 | |||||||||||||||||||||||||||||||||||||||||||
| 478 | $res->json({ message => 'Hello' }); | ||||||||||||||||||||||||||||||||||||||||||
| 479 | PAGI::Response->json({ message => 'Hello' }); | ||||||||||||||||||||||||||||||||||||||||||
| 480 | PAGI::Response->json({ error => 'nope' }, status => 404); | ||||||||||||||||||||||||||||||||||||||||||
| 481 | |||||||||||||||||||||||||||||||||||||||||||
| 482 | Set body to the JSON-encoded data with Content-Type: application/json. No charset | ||||||||||||||||||||||||||||||||||||||||||
| 483 | parameter is added — JSON is always UTF-8 and C<application/json> defines none | ||||||||||||||||||||||||||||||||||||||||||
| 484 | (RFC 8259). Accepts trailing options (C<status>, C<content_type>, C<headers>). | ||||||||||||||||||||||||||||||||||||||||||
| 485 | Returns C<$self>. | ||||||||||||||||||||||||||||||||||||||||||
| 486 | |||||||||||||||||||||||||||||||||||||||||||
| 487 | =head2 redirect | ||||||||||||||||||||||||||||||||||||||||||
| 488 | |||||||||||||||||||||||||||||||||||||||||||
| 489 | $res->redirect('/login'); | ||||||||||||||||||||||||||||||||||||||||||
| 490 | $res->redirect('/new-url', 301); | ||||||||||||||||||||||||||||||||||||||||||
| 491 | PAGI::Response->redirect('/login'); | ||||||||||||||||||||||||||||||||||||||||||
| 492 | |||||||||||||||||||||||||||||||||||||||||||
| 493 | Set an empty body and a Location header. Default status is 302. Returns C<$self>. | ||||||||||||||||||||||||||||||||||||||||||
| 494 | |||||||||||||||||||||||||||||||||||||||||||
| 495 | B<Why no body?> While RFC 7231 suggests including a short HTML body with a | ||||||||||||||||||||||||||||||||||||||||||
| 496 | hyperlink for clients that don't auto-follow redirects, all modern browsers | ||||||||||||||||||||||||||||||||||||||||||
| 497 | and HTTP clients ignore redirect bodies. If you need a body for legacy | ||||||||||||||||||||||||||||||||||||||||||
| 498 | compatibility, set it explicitly after calling C<redirect>. | ||||||||||||||||||||||||||||||||||||||||||
| 499 | |||||||||||||||||||||||||||||||||||||||||||
| 500 | =head2 empty | ||||||||||||||||||||||||||||||||||||||||||
| 501 | |||||||||||||||||||||||||||||||||||||||||||
| 502 | $res->empty; | ||||||||||||||||||||||||||||||||||||||||||
| 503 | PAGI::Response->new->empty; | ||||||||||||||||||||||||||||||||||||||||||
| 504 | PAGI::Response->empty(status => 304); | ||||||||||||||||||||||||||||||||||||||||||
| 505 | |||||||||||||||||||||||||||||||||||||||||||
| 506 | Set an empty body with status 204 No Content (or keep a previously set status). | ||||||||||||||||||||||||||||||||||||||||||
| 507 | Accepts trailing options (C<status>, C<content_type>, C<headers>); an explicit | ||||||||||||||||||||||||||||||||||||||||||
| 508 | C<status> option overrides the 204 default. Returns C<$self>. | ||||||||||||||||||||||||||||||||||||||||||
| 509 | |||||||||||||||||||||||||||||||||||||||||||
| 510 | =head2 send | ||||||||||||||||||||||||||||||||||||||||||
| 511 | |||||||||||||||||||||||||||||||||||||||||||
| 512 | $res->send($text); | ||||||||||||||||||||||||||||||||||||||||||
| 513 | $res->send($text, charset => 'iso-8859-1'); | ||||||||||||||||||||||||||||||||||||||||||
| 514 | |||||||||||||||||||||||||||||||||||||||||||
| 515 | Set body to the encoded text (UTF-8 by default, or the specified charset). | ||||||||||||||||||||||||||||||||||||||||||
| 516 | Defaults the Content-Type to C<text/plain> and appends the charset to a | ||||||||||||||||||||||||||||||||||||||||||
| 517 | charset-less type, on the same rules as L</text> (C<application/json> and | ||||||||||||||||||||||||||||||||||||||||||
| 518 | C<+json> types stay bare). Returns C<$self>. | ||||||||||||||||||||||||||||||||||||||||||
| 519 | |||||||||||||||||||||||||||||||||||||||||||
| 520 | =head2 send_raw | ||||||||||||||||||||||||||||||||||||||||||
| 521 | |||||||||||||||||||||||||||||||||||||||||||
| 522 | $res->send_raw($bytes); | ||||||||||||||||||||||||||||||||||||||||||
| 523 | PAGI::Response->send_raw($bytes, content_type => 'application/octet-stream'); | ||||||||||||||||||||||||||||||||||||||||||
| 524 | |||||||||||||||||||||||||||||||||||||||||||
| 525 | Set body to raw bytes without any encoding. Use for binary data or pre-encoded | ||||||||||||||||||||||||||||||||||||||||||
| 526 | content. Accepts trailing options (C<status>, C<content_type>, C<headers>). | ||||||||||||||||||||||||||||||||||||||||||
| 527 | Returns C<$self>. | ||||||||||||||||||||||||||||||||||||||||||
| 528 | |||||||||||||||||||||||||||||||||||||||||||
| 529 | =head2 stream | ||||||||||||||||||||||||||||||||||||||||||
| 530 | |||||||||||||||||||||||||||||||||||||||||||
| 531 | $res->stream(async sub { | ||||||||||||||||||||||||||||||||||||||||||
| 532 | my ($writer) = @_; | ||||||||||||||||||||||||||||||||||||||||||
| 533 | await $writer->write("chunk1"); | ||||||||||||||||||||||||||||||||||||||||||
| 534 | await $writer->write("chunk2"); | ||||||||||||||||||||||||||||||||||||||||||
| 535 | await $writer->close(); | ||||||||||||||||||||||||||||||||||||||||||
| 536 | }); | ||||||||||||||||||||||||||||||||||||||||||
| 537 | PAGI::Response->stream($callback); | ||||||||||||||||||||||||||||||||||||||||||
| 538 | |||||||||||||||||||||||||||||||||||||||||||
| 539 | Store a streaming callback. When the response is sent via L</respond>, the callback | ||||||||||||||||||||||||||||||||||||||||||
| 540 | receives a L<PAGI::Response::Writer> and streams chunks. Returns C<$self>. | ||||||||||||||||||||||||||||||||||||||||||
| 541 | |||||||||||||||||||||||||||||||||||||||||||
| 542 | =head2 writer | ||||||||||||||||||||||||||||||||||||||||||
| 543 | |||||||||||||||||||||||||||||||||||||||||||
| 544 | my $writer = await $res->writer($send); | ||||||||||||||||||||||||||||||||||||||||||
| 545 | my $writer = await $res->writer($send, on_close => sub { cleanup() }); | ||||||||||||||||||||||||||||||||||||||||||
| 546 | my $writer = await $res->writer($send, on_close => async sub { await cleanup() }); | ||||||||||||||||||||||||||||||||||||||||||
| 547 | |||||||||||||||||||||||||||||||||||||||||||
| 548 | Returns a L<PAGI::Response::Writer> directly, sending headers immediately. | ||||||||||||||||||||||||||||||||||||||||||
| 549 | Unlike C<stream()>, the writer is not scoped to a callback — you own it | ||||||||||||||||||||||||||||||||||||||||||
| 550 | and must call C<close()> when done. | ||||||||||||||||||||||||||||||||||||||||||
| 551 | |||||||||||||||||||||||||||||||||||||||||||
| 552 | C<$send> must be a coderef (the PAGI send callback). This is the same | ||||||||||||||||||||||||||||||||||||||||||
| 553 | C<$send> you would pass to L</respond>. | ||||||||||||||||||||||||||||||||||||||||||
| 554 | |||||||||||||||||||||||||||||||||||||||||||
| 555 | This is useful when the writer needs to be passed to event handlers, | ||||||||||||||||||||||||||||||||||||||||||
| 556 | pub/sub callbacks, timers, or other contexts outside a single function: | ||||||||||||||||||||||||||||||||||||||||||
| 557 | |||||||||||||||||||||||||||||||||||||||||||
| 558 | async sub live_feed { | ||||||||||||||||||||||||||||||||||||||||||
| 559 | my ($self, $ctx) = @_; | ||||||||||||||||||||||||||||||||||||||||||
| 560 | my $writer = await $ctx->response | ||||||||||||||||||||||||||||||||||||||||||
| 561 | ->content_type('text/plain') | ||||||||||||||||||||||||||||||||||||||||||
| 562 | ->writer($ctx->send, on_close => sub { $bus->unsubscribe($id) }); | ||||||||||||||||||||||||||||||||||||||||||
| 563 | |||||||||||||||||||||||||||||||||||||||||||
| 564 | my $id = $bus->subscribe(async sub ($line) { | ||||||||||||||||||||||||||||||||||||||||||
| 565 | await $writer->write("$line\n"); | ||||||||||||||||||||||||||||||||||||||||||
| 566 | }); | ||||||||||||||||||||||||||||||||||||||||||
| 567 | |||||||||||||||||||||||||||||||||||||||||||
| 568 | await $ctx->receive; # wait for disconnect | ||||||||||||||||||||||||||||||||||||||||||
| 569 | await $writer->close; | ||||||||||||||||||||||||||||||||||||||||||
| 570 | } | ||||||||||||||||||||||||||||||||||||||||||
| 571 | |||||||||||||||||||||||||||||||||||||||||||
| 572 | The optional C<on_close> callback is registered before headers are sent, | ||||||||||||||||||||||||||||||||||||||||||
| 573 | eliminating any race window with fast client disconnects. Sync and async | ||||||||||||||||||||||||||||||||||||||||||
| 574 | callbacks are both supported — see L</on_close> under L</WRITER OBJECT>. | ||||||||||||||||||||||||||||||||||||||||||
| 575 | |||||||||||||||||||||||||||||||||||||||||||
| 576 | =head2 send_file | ||||||||||||||||||||||||||||||||||||||||||
| 577 | |||||||||||||||||||||||||||||||||||||||||||
| 578 | $res->send_file('/path/to/file.pdf'); | ||||||||||||||||||||||||||||||||||||||||||
| 579 | $res->send_file('/path/to/file.pdf', | ||||||||||||||||||||||||||||||||||||||||||
| 580 | filename => 'download.pdf', | ||||||||||||||||||||||||||||||||||||||||||
| 581 | inline => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 582 | ); | ||||||||||||||||||||||||||||||||||||||||||
| 583 | PAGI::Response->send_file('/path/to/file.pdf'); | ||||||||||||||||||||||||||||||||||||||||||
| 584 | |||||||||||||||||||||||||||||||||||||||||||
| 585 | # Partial file (for range requests) | ||||||||||||||||||||||||||||||||||||||||||
| 586 | $res->send_file('/path/to/video.mp4', | ||||||||||||||||||||||||||||||||||||||||||
| 587 | offset => 1024, # Start from byte 1024 | ||||||||||||||||||||||||||||||||||||||||||
| 588 | length => 65536, # Send 64KB | ||||||||||||||||||||||||||||||||||||||||||
| 589 | ); | ||||||||||||||||||||||||||||||||||||||||||
| 590 | |||||||||||||||||||||||||||||||||||||||||||
| 591 | Set the response to serve a file. Stats the file and sets Content-Type, | ||||||||||||||||||||||||||||||||||||||||||
| 592 | Content-Length, and Content-Disposition at call time. The PAGI protocol's | ||||||||||||||||||||||||||||||||||||||||||
| 593 | C<file> key is used for efficient server-side streaming (file not read into | ||||||||||||||||||||||||||||||||||||||||||
| 594 | memory) when L</respond> is called. Returns C<$self>. | ||||||||||||||||||||||||||||||||||||||||||
| 595 | |||||||||||||||||||||||||||||||||||||||||||
| 596 | For production, use L<PAGI::Middleware::XSendfile> to delegate file serving | ||||||||||||||||||||||||||||||||||||||||||
| 597 | to your reverse proxy. | ||||||||||||||||||||||||||||||||||||||||||
| 598 | |||||||||||||||||||||||||||||||||||||||||||
| 599 | B<Options:> | ||||||||||||||||||||||||||||||||||||||||||
| 600 | |||||||||||||||||||||||||||||||||||||||||||
| 601 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 602 | |||||||||||||||||||||||||||||||||||||||||||
| 603 | =item * C<filename> - Set Content-Disposition attachment filename | ||||||||||||||||||||||||||||||||||||||||||
| 604 | |||||||||||||||||||||||||||||||||||||||||||
| 605 | =item * C<inline> - Use Content-Disposition: inline instead of attachment | ||||||||||||||||||||||||||||||||||||||||||
| 606 | |||||||||||||||||||||||||||||||||||||||||||
| 607 | =item * C<offset> - Start position in bytes (default: 0). For range requests. | ||||||||||||||||||||||||||||||||||||||||||
| 608 | |||||||||||||||||||||||||||||||||||||||||||
| 609 | =item * C<length> - Number of bytes to send. Defaults to file size minus offset. | ||||||||||||||||||||||||||||||||||||||||||
| 610 | |||||||||||||||||||||||||||||||||||||||||||
| 611 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 612 | |||||||||||||||||||||||||||||||||||||||||||
| 613 | B<Range Request Example:> | ||||||||||||||||||||||||||||||||||||||||||
| 614 | |||||||||||||||||||||||||||||||||||||||||||
| 615 | # Manual range request handling | ||||||||||||||||||||||||||||||||||||||||||
| 616 | async sub handle_video { | ||||||||||||||||||||||||||||||||||||||||||
| 617 | my ($req, $send) = @_; | ||||||||||||||||||||||||||||||||||||||||||
| 618 | my $path = '/videos/movie.mp4'; | ||||||||||||||||||||||||||||||||||||||||||
| 619 | my $size = -s $path; | ||||||||||||||||||||||||||||||||||||||||||
| 620 | |||||||||||||||||||||||||||||||||||||||||||
| 621 | my $range = $req->header('Range'); | ||||||||||||||||||||||||||||||||||||||||||
| 622 | if ($range && $range =~ /bytes=(\d+)-(\d*)/) { | ||||||||||||||||||||||||||||||||||||||||||
| 623 | my $start = $1; | ||||||||||||||||||||||||||||||||||||||||||
| 624 | my $end = $2 || ($size - 1); | ||||||||||||||||||||||||||||||||||||||||||
| 625 | my $length = $end - $start + 1; | ||||||||||||||||||||||||||||||||||||||||||
| 626 | |||||||||||||||||||||||||||||||||||||||||||
| 627 | return await PAGI::Response->new | ||||||||||||||||||||||||||||||||||||||||||
| 628 | ->status(206) | ||||||||||||||||||||||||||||||||||||||||||
| 629 | ->header('Content-Range' => "bytes $start-$end/$size") | ||||||||||||||||||||||||||||||||||||||||||
| 630 | ->header('Accept-Ranges' => 'bytes') | ||||||||||||||||||||||||||||||||||||||||||
| 631 | ->send_file($path, offset => $start, length => $length) | ||||||||||||||||||||||||||||||||||||||||||
| 632 | ->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 633 | } | ||||||||||||||||||||||||||||||||||||||||||
| 634 | |||||||||||||||||||||||||||||||||||||||||||
| 635 | return await PAGI::Response->new | ||||||||||||||||||||||||||||||||||||||||||
| 636 | ->header('Accept-Ranges' => 'bytes') | ||||||||||||||||||||||||||||||||||||||||||
| 637 | ->send_file($path) | ||||||||||||||||||||||||||||||||||||||||||
| 638 | ->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 639 | } | ||||||||||||||||||||||||||||||||||||||||||
| 640 | |||||||||||||||||||||||||||||||||||||||||||
| 641 | B<Note:> For production file serving with full features (ETag caching, | ||||||||||||||||||||||||||||||||||||||||||
| 642 | automatic range request handling, conditional GETs, directory indexes), | ||||||||||||||||||||||||||||||||||||||||||
| 643 | use L<PAGI::App::File> instead: | ||||||||||||||||||||||||||||||||||||||||||
| 644 | |||||||||||||||||||||||||||||||||||||||||||
| 645 | use PAGI::App::File; | ||||||||||||||||||||||||||||||||||||||||||
| 646 | my $files = PAGI::App::File->new(root => '/var/www/static'); | ||||||||||||||||||||||||||||||||||||||||||
| 647 | my $app = $files->to_app; | ||||||||||||||||||||||||||||||||||||||||||
| 648 | |||||||||||||||||||||||||||||||||||||||||||
| 649 | =head1 EXAMPLES | ||||||||||||||||||||||||||||||||||||||||||
| 650 | |||||||||||||||||||||||||||||||||||||||||||
| 651 | =head2 Complete Raw PAGI Application | ||||||||||||||||||||||||||||||||||||||||||
| 652 | |||||||||||||||||||||||||||||||||||||||||||
| 653 | use Future::AsyncAwait; | ||||||||||||||||||||||||||||||||||||||||||
| 654 | use PAGI::Request; | ||||||||||||||||||||||||||||||||||||||||||
| 655 | use PAGI::Response; | ||||||||||||||||||||||||||||||||||||||||||
| 656 | |||||||||||||||||||||||||||||||||||||||||||
| 657 | my $app = async sub ($scope, $receive, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 658 | return await handle_lifespan($scope, $receive, $send) | ||||||||||||||||||||||||||||||||||||||||||
| 659 | if $scope->{type} eq 'lifespan'; | ||||||||||||||||||||||||||||||||||||||||||
| 660 | |||||||||||||||||||||||||||||||||||||||||||
| 661 | my $req = PAGI::Request->new($scope, $receive); | ||||||||||||||||||||||||||||||||||||||||||
| 662 | my $res = $req->response; | ||||||||||||||||||||||||||||||||||||||||||
| 663 | |||||||||||||||||||||||||||||||||||||||||||
| 664 | if ($req->method eq 'GET' && $req->path eq '/') { | ||||||||||||||||||||||||||||||||||||||||||
| 665 | return await $res->html('<h1>Welcome</h1>')->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 666 | } | ||||||||||||||||||||||||||||||||||||||||||
| 667 | |||||||||||||||||||||||||||||||||||||||||||
| 668 | if ($req->method eq 'POST' && $req->path eq '/api/users') { | ||||||||||||||||||||||||||||||||||||||||||
| 669 | my $data = await $req->json; | ||||||||||||||||||||||||||||||||||||||||||
| 670 | # ... create user ... | ||||||||||||||||||||||||||||||||||||||||||
| 671 | return await $res->status(201) | ||||||||||||||||||||||||||||||||||||||||||
| 672 | ->header('Location' => '/api/users/123') | ||||||||||||||||||||||||||||||||||||||||||
| 673 | ->json({ id => 123, name => $data->{name} }) | ||||||||||||||||||||||||||||||||||||||||||
| 674 | ->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 675 | } | ||||||||||||||||||||||||||||||||||||||||||
| 676 | |||||||||||||||||||||||||||||||||||||||||||
| 677 | return await $res->status(404)->json({ error => 'Not Found' })->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 678 | }; | ||||||||||||||||||||||||||||||||||||||||||
| 679 | |||||||||||||||||||||||||||||||||||||||||||
| 680 | =head2 Form Validation with Error Response | ||||||||||||||||||||||||||||||||||||||||||
| 681 | |||||||||||||||||||||||||||||||||||||||||||
| 682 | async sub handle_contact ($req, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 683 | my $res = $req->response; | ||||||||||||||||||||||||||||||||||||||||||
| 684 | my $form = await $req->form_params; | ||||||||||||||||||||||||||||||||||||||||||
| 685 | |||||||||||||||||||||||||||||||||||||||||||
| 686 | my @errors; | ||||||||||||||||||||||||||||||||||||||||||
| 687 | my $email = $form->get('email') // ''; | ||||||||||||||||||||||||||||||||||||||||||
| 688 | my $message = $form->get('message') // ''; | ||||||||||||||||||||||||||||||||||||||||||
| 689 | |||||||||||||||||||||||||||||||||||||||||||
| 690 | push @errors, 'Email required' unless $email; | ||||||||||||||||||||||||||||||||||||||||||
| 691 | push @errors, 'Invalid email' unless $email =~ /@/; | ||||||||||||||||||||||||||||||||||||||||||
| 692 | push @errors, 'Message required' unless $message; | ||||||||||||||||||||||||||||||||||||||||||
| 693 | |||||||||||||||||||||||||||||||||||||||||||
| 694 | if (@errors) { | ||||||||||||||||||||||||||||||||||||||||||
| 695 | return await $res->status(422) | ||||||||||||||||||||||||||||||||||||||||||
| 696 | ->json({ error => 'Validation failed', errors => \@errors }) | ||||||||||||||||||||||||||||||||||||||||||
| 697 | ->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 698 | } | ||||||||||||||||||||||||||||||||||||||||||
| 699 | |||||||||||||||||||||||||||||||||||||||||||
| 700 | # Process valid form... | ||||||||||||||||||||||||||||||||||||||||||
| 701 | return await $res->json({ success => 1 })->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 702 | } | ||||||||||||||||||||||||||||||||||||||||||
| 703 | |||||||||||||||||||||||||||||||||||||||||||
| 704 | =head2 Authentication with Cookies | ||||||||||||||||||||||||||||||||||||||||||
| 705 | |||||||||||||||||||||||||||||||||||||||||||
| 706 | async sub handle_login ($req, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 707 | my $res = $req->response; | ||||||||||||||||||||||||||||||||||||||||||
| 708 | my $data = await $req->json; | ||||||||||||||||||||||||||||||||||||||||||
| 709 | |||||||||||||||||||||||||||||||||||||||||||
| 710 | my $user = authenticate($data->{email}, $data->{password}); | ||||||||||||||||||||||||||||||||||||||||||
| 711 | |||||||||||||||||||||||||||||||||||||||||||
| 712 | unless ($user) { | ||||||||||||||||||||||||||||||||||||||||||
| 713 | return await $res->status(401)->json({ error => 'Invalid credentials' })->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 714 | } | ||||||||||||||||||||||||||||||||||||||||||
| 715 | |||||||||||||||||||||||||||||||||||||||||||
| 716 | my $session_id = create_session($user); | ||||||||||||||||||||||||||||||||||||||||||
| 717 | |||||||||||||||||||||||||||||||||||||||||||
| 718 | return await $res->cookie('session' => $session_id, | ||||||||||||||||||||||||||||||||||||||||||
| 719 | path => '/', | ||||||||||||||||||||||||||||||||||||||||||
| 720 | httponly => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 721 | secure => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 722 | samesite => 'Strict', | ||||||||||||||||||||||||||||||||||||||||||
| 723 | max_age => 86400, # 24 hours | ||||||||||||||||||||||||||||||||||||||||||
| 724 | ) | ||||||||||||||||||||||||||||||||||||||||||
| 725 | ->json({ user => { id => $user->{id}, name => $user->{name} } }) | ||||||||||||||||||||||||||||||||||||||||||
| 726 | ->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 727 | } | ||||||||||||||||||||||||||||||||||||||||||
| 728 | |||||||||||||||||||||||||||||||||||||||||||
| 729 | async sub handle_logout ($req, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 730 | my $res = $req->response; | ||||||||||||||||||||||||||||||||||||||||||
| 731 | |||||||||||||||||||||||||||||||||||||||||||
| 732 | return await $res->delete_cookie('session', path => '/') | ||||||||||||||||||||||||||||||||||||||||||
| 733 | ->json({ logged_out => 1 }) | ||||||||||||||||||||||||||||||||||||||||||
| 734 | ->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 735 | } | ||||||||||||||||||||||||||||||||||||||||||
| 736 | |||||||||||||||||||||||||||||||||||||||||||
| 737 | =head2 File Download | ||||||||||||||||||||||||||||||||||||||||||
| 738 | |||||||||||||||||||||||||||||||||||||||||||
| 739 | async sub handle_download ($req, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 740 | my $res = $req->response; | ||||||||||||||||||||||||||||||||||||||||||
| 741 | my $file_id = $req->path_param('id'); | ||||||||||||||||||||||||||||||||||||||||||
| 742 | |||||||||||||||||||||||||||||||||||||||||||
| 743 | my $file = get_file($file_id); # Be sure to clean $file | ||||||||||||||||||||||||||||||||||||||||||
| 744 | unless ($file && -f $file->{path}) { | ||||||||||||||||||||||||||||||||||||||||||
| 745 | return await $res->status(404)->json({ error => 'File not found' })->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 746 | } | ||||||||||||||||||||||||||||||||||||||||||
| 747 | |||||||||||||||||||||||||||||||||||||||||||
| 748 | return await $res->send_file($file->{path}, | ||||||||||||||||||||||||||||||||||||||||||
| 749 | filename => $file->{original_name}, | ||||||||||||||||||||||||||||||||||||||||||
| 750 | )->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 751 | } | ||||||||||||||||||||||||||||||||||||||||||
| 752 | |||||||||||||||||||||||||||||||||||||||||||
| 753 | =head2 Streaming Large Data | ||||||||||||||||||||||||||||||||||||||||||
| 754 | |||||||||||||||||||||||||||||||||||||||||||
| 755 | async sub handle_export ($req, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 756 | my $res = $req->response; | ||||||||||||||||||||||||||||||||||||||||||
| 757 | |||||||||||||||||||||||||||||||||||||||||||
| 758 | await $res->content_type('text/csv') | ||||||||||||||||||||||||||||||||||||||||||
| 759 | ->header('Content-Disposition' => 'attachment; filename="export.csv"') | ||||||||||||||||||||||||||||||||||||||||||
| 760 | ->stream(async sub ($writer) { | ||||||||||||||||||||||||||||||||||||||||||
| 761 | # Write CSV header | ||||||||||||||||||||||||||||||||||||||||||
| 762 | await $writer->write("id,name,email\n"); | ||||||||||||||||||||||||||||||||||||||||||
| 763 | |||||||||||||||||||||||||||||||||||||||||||
| 764 | # Stream rows from database | ||||||||||||||||||||||||||||||||||||||||||
| 765 | my $cursor = get_all_users_cursor(); | ||||||||||||||||||||||||||||||||||||||||||
| 766 | while (my $user = $cursor->next) { | ||||||||||||||||||||||||||||||||||||||||||
| 767 | await $writer->write("$user->{id},$user->{name},$user->{email}\n"); | ||||||||||||||||||||||||||||||||||||||||||
| 768 | } | ||||||||||||||||||||||||||||||||||||||||||
| 769 | }) | ||||||||||||||||||||||||||||||||||||||||||
| 770 | ->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 771 | } | ||||||||||||||||||||||||||||||||||||||||||
| 772 | |||||||||||||||||||||||||||||||||||||||||||
| 773 | =head2 Server-Sent Events Style Streaming | ||||||||||||||||||||||||||||||||||||||||||
| 774 | |||||||||||||||||||||||||||||||||||||||||||
| 775 | async sub handle_events ($req, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 776 | my $res = $req->response; | ||||||||||||||||||||||||||||||||||||||||||
| 777 | |||||||||||||||||||||||||||||||||||||||||||
| 778 | await $res->content_type('text/event-stream') | ||||||||||||||||||||||||||||||||||||||||||
| 779 | ->header('Cache-Control' => 'no-cache') | ||||||||||||||||||||||||||||||||||||||||||
| 780 | ->stream(async sub ($writer) { | ||||||||||||||||||||||||||||||||||||||||||
| 781 | for my $i (1..10) { | ||||||||||||||||||||||||||||||||||||||||||
| 782 | await $writer->write("data: Event $i\n\n"); | ||||||||||||||||||||||||||||||||||||||||||
| 783 | await some_delay(1); # Wait 1 second | ||||||||||||||||||||||||||||||||||||||||||
| 784 | } | ||||||||||||||||||||||||||||||||||||||||||
| 785 | }) | ||||||||||||||||||||||||||||||||||||||||||
| 786 | ->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 787 | } | ||||||||||||||||||||||||||||||||||||||||||
| 788 | |||||||||||||||||||||||||||||||||||||||||||
| 789 | =head2 Conditional Responses | ||||||||||||||||||||||||||||||||||||||||||
| 790 | |||||||||||||||||||||||||||||||||||||||||||
| 791 | async sub handle_resource ($req, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 792 | my $res = $req->response; | ||||||||||||||||||||||||||||||||||||||||||
| 793 | my $etag = '"abc123"'; | ||||||||||||||||||||||||||||||||||||||||||
| 794 | |||||||||||||||||||||||||||||||||||||||||||
| 795 | # Check If-None-Match for caching | ||||||||||||||||||||||||||||||||||||||||||
| 796 | my $if_none_match = $req->header('If-None-Match') // ''; | ||||||||||||||||||||||||||||||||||||||||||
| 797 | if ($if_none_match eq $etag) { | ||||||||||||||||||||||||||||||||||||||||||
| 798 | return await $res->status(304)->empty()->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 799 | } | ||||||||||||||||||||||||||||||||||||||||||
| 800 | |||||||||||||||||||||||||||||||||||||||||||
| 801 | return await $res->header('ETag' => $etag) | ||||||||||||||||||||||||||||||||||||||||||
| 802 | ->header('Cache-Control' => 'max-age=3600') | ||||||||||||||||||||||||||||||||||||||||||
| 803 | ->json({ data => 'expensive computation result' }) | ||||||||||||||||||||||||||||||||||||||||||
| 804 | ->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 805 | } | ||||||||||||||||||||||||||||||||||||||||||
| 806 | |||||||||||||||||||||||||||||||||||||||||||
| 807 | =head2 CORS API Endpoint | ||||||||||||||||||||||||||||||||||||||||||
| 808 | |||||||||||||||||||||||||||||||||||||||||||
| 809 | # Simple CORS - allow all origins | ||||||||||||||||||||||||||||||||||||||||||
| 810 | async sub handle_api ($scope, $receive, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 811 | my $res = PAGI::Response->new($scope); | ||||||||||||||||||||||||||||||||||||||||||
| 812 | |||||||||||||||||||||||||||||||||||||||||||
| 813 | return await $res->cors->json({ status => 'ok' })->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 814 | } | ||||||||||||||||||||||||||||||||||||||||||
| 815 | |||||||||||||||||||||||||||||||||||||||||||
| 816 | # CORS with credentials (e.g., cookies, auth headers) | ||||||||||||||||||||||||||||||||||||||||||
| 817 | async sub handle_api_with_auth ($scope, $receive, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 818 | my $req = PAGI::Request->new($scope, $receive); | ||||||||||||||||||||||||||||||||||||||||||
| 819 | my $res = $req->response; | ||||||||||||||||||||||||||||||||||||||||||
| 820 | |||||||||||||||||||||||||||||||||||||||||||
| 821 | # Get the Origin header from request | ||||||||||||||||||||||||||||||||||||||||||
| 822 | my $origin = $req->header('Origin'); | ||||||||||||||||||||||||||||||||||||||||||
| 823 | |||||||||||||||||||||||||||||||||||||||||||
| 824 | return await $res->cors( | ||||||||||||||||||||||||||||||||||||||||||
| 825 | origin => 'https://myapp.com', # Or use request_origin | ||||||||||||||||||||||||||||||||||||||||||
| 826 | credentials => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 827 | expose => [qw(X-Request-Id)], | ||||||||||||||||||||||||||||||||||||||||||
| 828 | )->json({ user => 'authenticated' })->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 829 | } | ||||||||||||||||||||||||||||||||||||||||||
| 830 | |||||||||||||||||||||||||||||||||||||||||||
| 831 | =head2 CORS Preflight Handler | ||||||||||||||||||||||||||||||||||||||||||
| 832 | |||||||||||||||||||||||||||||||||||||||||||
| 833 | # Handle OPTIONS preflight requests | ||||||||||||||||||||||||||||||||||||||||||
| 834 | async sub app ($scope, $receive, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 835 | my $req = PAGI::Request->new($scope, $receive); | ||||||||||||||||||||||||||||||||||||||||||
| 836 | my $res = $req->response; | ||||||||||||||||||||||||||||||||||||||||||
| 837 | |||||||||||||||||||||||||||||||||||||||||||
| 838 | # Handle preflight | ||||||||||||||||||||||||||||||||||||||||||
| 839 | if ($req->method eq 'OPTIONS') { | ||||||||||||||||||||||||||||||||||||||||||
| 840 | return await $res->cors( | ||||||||||||||||||||||||||||||||||||||||||
| 841 | origin => 'https://myapp.com', | ||||||||||||||||||||||||||||||||||||||||||
| 842 | methods => [qw(GET POST PUT DELETE)], | ||||||||||||||||||||||||||||||||||||||||||
| 843 | headers => [qw(Content-Type Authorization X-Custom-Header)], | ||||||||||||||||||||||||||||||||||||||||||
| 844 | credentials => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 845 | max_age => 86400, | ||||||||||||||||||||||||||||||||||||||||||
| 846 | preflight => 1, # Include preflight headers | ||||||||||||||||||||||||||||||||||||||||||
| 847 | )->status(204)->empty()->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 848 | } | ||||||||||||||||||||||||||||||||||||||||||
| 849 | |||||||||||||||||||||||||||||||||||||||||||
| 850 | # Handle actual request | ||||||||||||||||||||||||||||||||||||||||||
| 851 | return await $res->cors( | ||||||||||||||||||||||||||||||||||||||||||
| 852 | origin => 'https://myapp.com', | ||||||||||||||||||||||||||||||||||||||||||
| 853 | credentials => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 854 | )->json({ data => 'response' })->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 855 | } | ||||||||||||||||||||||||||||||||||||||||||
| 856 | |||||||||||||||||||||||||||||||||||||||||||
| 857 | =head2 Dynamic CORS Origin | ||||||||||||||||||||||||||||||||||||||||||
| 858 | |||||||||||||||||||||||||||||||||||||||||||
| 859 | # Allow multiple origins dynamically | ||||||||||||||||||||||||||||||||||||||||||
| 860 | my %ALLOWED_ORIGINS = map { $_ => 1 } qw( | ||||||||||||||||||||||||||||||||||||||||||
| 861 | https://app1.example.com | ||||||||||||||||||||||||||||||||||||||||||
| 862 | https://app2.example.com | ||||||||||||||||||||||||||||||||||||||||||
| 863 | https://localhost:3000 | ||||||||||||||||||||||||||||||||||||||||||
| 864 | ); | ||||||||||||||||||||||||||||||||||||||||||
| 865 | |||||||||||||||||||||||||||||||||||||||||||
| 866 | async sub handle_api ($scope, $receive, $send) { | ||||||||||||||||||||||||||||||||||||||||||
| 867 | my $req = PAGI::Request->new($scope, $receive); | ||||||||||||||||||||||||||||||||||||||||||
| 868 | my $res = $req->response; | ||||||||||||||||||||||||||||||||||||||||||
| 869 | |||||||||||||||||||||||||||||||||||||||||||
| 870 | my $request_origin = $req->header('Origin') // ''; | ||||||||||||||||||||||||||||||||||||||||||
| 871 | |||||||||||||||||||||||||||||||||||||||||||
| 872 | # Check if origin is allowed | ||||||||||||||||||||||||||||||||||||||||||
| 873 | if ($ALLOWED_ORIGINS{$request_origin}) { | ||||||||||||||||||||||||||||||||||||||||||
| 874 | return await $res->cors( | ||||||||||||||||||||||||||||||||||||||||||
| 875 | origin => $request_origin, # Echo back the allowed origin | ||||||||||||||||||||||||||||||||||||||||||
| 876 | credentials => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 877 | )->json({ data => 'allowed' })->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 878 | } | ||||||||||||||||||||||||||||||||||||||||||
| 879 | |||||||||||||||||||||||||||||||||||||||||||
| 880 | # Origin not allowed - respond without CORS headers | ||||||||||||||||||||||||||||||||||||||||||
| 881 | return await $res->status(403)->json({ error => 'Origin not allowed' })->respond($send); | ||||||||||||||||||||||||||||||||||||||||||
| 882 | } | ||||||||||||||||||||||||||||||||||||||||||
| 883 | |||||||||||||||||||||||||||||||||||||||||||
| 884 | =head1 WRITER OBJECT | ||||||||||||||||||||||||||||||||||||||||||
| 885 | |||||||||||||||||||||||||||||||||||||||||||
| 886 | The C<stream()> method passes a writer object to its callback, and | ||||||||||||||||||||||||||||||||||||||||||
| 887 | C<writer()> returns one directly. The writer has the following methods: | ||||||||||||||||||||||||||||||||||||||||||
| 888 | |||||||||||||||||||||||||||||||||||||||||||
| 889 | =head3 write | ||||||||||||||||||||||||||||||||||||||||||
| 890 | |||||||||||||||||||||||||||||||||||||||||||
| 891 | await $writer->write($chunk); | ||||||||||||||||||||||||||||||||||||||||||
| 892 | |||||||||||||||||||||||||||||||||||||||||||
| 893 | Write a chunk of data to the response stream. Returns a L<Future>. | ||||||||||||||||||||||||||||||||||||||||||
| 894 | |||||||||||||||||||||||||||||||||||||||||||
| 895 | Writing after close returns a failed L<Future> rather than throwing. | ||||||||||||||||||||||||||||||||||||||||||
| 896 | This allows cleanup code that races with close to handle the error | ||||||||||||||||||||||||||||||||||||||||||
| 897 | gracefully via C<await>. | ||||||||||||||||||||||||||||||||||||||||||
| 898 | |||||||||||||||||||||||||||||||||||||||||||
| 899 | =head3 close | ||||||||||||||||||||||||||||||||||||||||||
| 900 | |||||||||||||||||||||||||||||||||||||||||||
| 901 | await $writer->close; | ||||||||||||||||||||||||||||||||||||||||||
| 902 | |||||||||||||||||||||||||||||||||||||||||||
| 903 | Close the stream. Returns a L<Future>. Calling close multiple times is | ||||||||||||||||||||||||||||||||||||||||||
| 904 | safe — subsequent calls are no-ops. | ||||||||||||||||||||||||||||||||||||||||||
| 905 | |||||||||||||||||||||||||||||||||||||||||||
| 906 | =head3 bytes_written | ||||||||||||||||||||||||||||||||||||||||||
| 907 | |||||||||||||||||||||||||||||||||||||||||||
| 908 | my $n = $writer->bytes_written; | ||||||||||||||||||||||||||||||||||||||||||
| 909 | |||||||||||||||||||||||||||||||||||||||||||
| 910 | Returns the total number of bytes written so far. | ||||||||||||||||||||||||||||||||||||||||||
| 911 | |||||||||||||||||||||||||||||||||||||||||||
| 912 | =head3 on_close | ||||||||||||||||||||||||||||||||||||||||||
| 913 | |||||||||||||||||||||||||||||||||||||||||||
| 914 | # Sync callback | ||||||||||||||||||||||||||||||||||||||||||
| 915 | $writer->on_close(sub { cleanup() }); | ||||||||||||||||||||||||||||||||||||||||||
| 916 | |||||||||||||||||||||||||||||||||||||||||||
| 917 | # Async callback — return value is awaited automatically | ||||||||||||||||||||||||||||||||||||||||||
| 918 | $writer->on_close(async sub { | ||||||||||||||||||||||||||||||||||||||||||
| 919 | await notify_stream_ended(); | ||||||||||||||||||||||||||||||||||||||||||
| 920 | }); | ||||||||||||||||||||||||||||||||||||||||||
| 921 | |||||||||||||||||||||||||||||||||||||||||||
| 922 | # Chaining | ||||||||||||||||||||||||||||||||||||||||||
| 923 | $writer->on_close(sub { ... }) | ||||||||||||||||||||||||||||||||||||||||||
| 924 | ->on_close(sub { ... }); | ||||||||||||||||||||||||||||||||||||||||||
| 925 | |||||||||||||||||||||||||||||||||||||||||||
| 926 | Registers a callback to fire when the writer closes (either explicitly | ||||||||||||||||||||||||||||||||||||||||||
| 927 | or via C<stream()> auto-close). Callbacks can be regular subs or async | ||||||||||||||||||||||||||||||||||||||||||
| 928 | subs — async results are automatically awaited. Multiple callbacks run | ||||||||||||||||||||||||||||||||||||||||||
| 929 | in registration order. Exceptions are caught and warned but do not | ||||||||||||||||||||||||||||||||||||||||||
| 930 | prevent other callbacks from running. Returns C<$self> for chaining. | ||||||||||||||||||||||||||||||||||||||||||
| 931 | |||||||||||||||||||||||||||||||||||||||||||
| 932 | B<Circular reference note:> If your callback captures the writer | ||||||||||||||||||||||||||||||||||||||||||
| 933 | object in a closure, use C<Scalar::Util::weaken> to avoid a memory leak: | ||||||||||||||||||||||||||||||||||||||||||
| 934 | |||||||||||||||||||||||||||||||||||||||||||
| 935 | use Scalar::Util qw(weaken); | ||||||||||||||||||||||||||||||||||||||||||
| 936 | my $weak_writer = $writer; | ||||||||||||||||||||||||||||||||||||||||||
| 937 | weaken($weak_writer); | ||||||||||||||||||||||||||||||||||||||||||
| 938 | $writer->on_close(sub { $weak_writer->... if $weak_writer }); | ||||||||||||||||||||||||||||||||||||||||||
| 939 | |||||||||||||||||||||||||||||||||||||||||||
| 940 | The callback array is cleared after firing, so any cycle via a closure | ||||||||||||||||||||||||||||||||||||||||||
| 941 | is broken when the writer closes, but C<weaken> prevents the object | ||||||||||||||||||||||||||||||||||||||||||
| 942 | from being kept alive until that point. | ||||||||||||||||||||||||||||||||||||||||||
| 943 | |||||||||||||||||||||||||||||||||||||||||||
| 944 | =head3 is_closed | ||||||||||||||||||||||||||||||||||||||||||
| 945 | |||||||||||||||||||||||||||||||||||||||||||
| 946 | if ($writer->is_closed) { ... } | ||||||||||||||||||||||||||||||||||||||||||
| 947 | |||||||||||||||||||||||||||||||||||||||||||
| 948 | Returns true if the writer has been closed. | ||||||||||||||||||||||||||||||||||||||||||
| 949 | |||||||||||||||||||||||||||||||||||||||||||
| 950 | The writer automatically closes when the C<stream()> callback completes, | ||||||||||||||||||||||||||||||||||||||||||
| 951 | but calling C<close()> explicitly is recommended for clarity. | ||||||||||||||||||||||||||||||||||||||||||
| 952 | |||||||||||||||||||||||||||||||||||||||||||
| 953 | =head1 ERROR AND ALTERNATE RESPONSES | ||||||||||||||||||||||||||||||||||||||||||
| 954 | |||||||||||||||||||||||||||||||||||||||||||
| 955 | A response is a value, so "produce a 404 instead" is just returning a different | ||||||||||||||||||||||||||||||||||||||||||
| 956 | value -- no exceptions needed: | ||||||||||||||||||||||||||||||||||||||||||
| 957 | |||||||||||||||||||||||||||||||||||||||||||
| 958 | async sub show ($self, $ctx) { | ||||||||||||||||||||||||||||||||||||||||||
| 959 | my $user = await find_user($ctx->req->path_param('id')); | ||||||||||||||||||||||||||||||||||||||||||
| 960 | return PAGI::Response->json({ error => 'not found' }, status => 404) | ||||||||||||||||||||||||||||||||||||||||||
| 961 | unless $user; | ||||||||||||||||||||||||||||||||||||||||||
| 962 | return $ctx->json($user); | ||||||||||||||||||||||||||||||||||||||||||
| 963 | } | ||||||||||||||||||||||||||||||||||||||||||
| 964 | |||||||||||||||||||||||||||||||||||||||||||
| 965 | For cases that recur across handlers, prefer modeling the absence as a value | ||||||||||||||||||||||||||||||||||||||||||
| 966 | (a "null object") whose own method returns the right response, instead of | ||||||||||||||||||||||||||||||||||||||||||
| 967 | throwing from deep in the stack: | ||||||||||||||||||||||||||||||||||||||||||
| 968 | |||||||||||||||||||||||||||||||||||||||||||
| 969 | my $user = await find_user($ctx) // UnauthenticatedUser->new($ctx); | ||||||||||||||||||||||||||||||||||||||||||
| 970 | return $user->dashboard; # a real user renders; an UnauthenticatedUser | ||||||||||||||||||||||||||||||||||||||||||
| 971 | # returns a 401 / login response | ||||||||||||||||||||||||||||||||||||||||||
| 972 | |||||||||||||||||||||||||||||||||||||||||||
| 973 | Here C<UnauthenticatedUser> is a class you define; its C<dashboard> method | ||||||||||||||||||||||||||||||||||||||||||
| 974 | returns a C<PAGI::Response> just as a real user's would. | ||||||||||||||||||||||||||||||||||||||||||
| 975 | |||||||||||||||||||||||||||||||||||||||||||
| 976 | =head1 SUBCLASSING (FRAMEWORK INTEGRATION) | ||||||||||||||||||||||||||||||||||||||||||
| 977 | |||||||||||||||||||||||||||||||||||||||||||
| 978 | Framework authors can subclass C<PAGI::Response> to add their own response | ||||||||||||||||||||||||||||||||||||||||||
| 979 | sugar while reusing the value machinery. The contract is small and stable: | ||||||||||||||||||||||||||||||||||||||||||
| 980 | |||||||||||||||||||||||||||||||||||||||||||
| 981 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 982 | |||||||||||||||||||||||||||||||||||||||||||
| 983 | =item * B<Construct via> C<< $class->new($scope) >>. The scope is optional and | ||||||||||||||||||||||||||||||||||||||||||
| 984 | inert (used only for C<scope()> and helpers like L<PAGI::Stash>); a response | ||||||||||||||||||||||||||||||||||||||||||
| 985 | never holds a connection. A Moose subclass can C<extends 'PAGI::Response'> and | ||||||||||||||||||||||||||||||||||||||||||
| 986 | provide C<FOREIGNBUILDARGS> returning C<($scope)>. | ||||||||||||||||||||||||||||||||||||||||||
| 987 | |||||||||||||||||||||||||||||||||||||||||||
| 988 | =item * B<Override> C<< respond($send) >> to customize how the response is sent. | ||||||||||||||||||||||||||||||||||||||||||
| 989 | Call C<< $self->SUPER::respond($send) >> to do the actual emission. The | ||||||||||||||||||||||||||||||||||||||||||
| 990 | connection (C<$send>) arrives as the argument; do not store or re-bind it -- a | ||||||||||||||||||||||||||||||||||||||||||
| 991 | response value is connection-free until the moment it is sent. | ||||||||||||||||||||||||||||||||||||||||||
| 992 | |||||||||||||||||||||||||||||||||||||||||||
| 993 | =item * B<Build on the public surface> -- C<status>, C<header>, C<headers>, | ||||||||||||||||||||||||||||||||||||||||||
| 994 | C<content_type>, C<cookie>, C<cors>, C<is_sent>, the C<has_*> predicates | ||||||||||||||||||||||||||||||||||||||||||
| 995 | (C<has_status>, C<has_header>, C<has_content_type>, C<has_body_source>), and | ||||||||||||||||||||||||||||||||||||||||||
| 996 | the body methods (C<text>/C<html>/C<json>/C<send_raw>/C<empty>/C<redirect>/ | ||||||||||||||||||||||||||||||||||||||||||
| 997 | C<stream>/C<send_file>, with trailing options). Do B<not> reach into the | ||||||||||||||||||||||||||||||||||||||||||
| 998 | C<_>-prefixed internals (C<_headers>, C<_body>, C<_status>, C<_stream>, ...); | ||||||||||||||||||||||||||||||||||||||||||
| 999 | they are private and may change. | ||||||||||||||||||||||||||||||||||||||||||
| 1000 | |||||||||||||||||||||||||||||||||||||||||||
| 1001 | =item * Adding response sugar via a role/mixin works unchanged -- a role that | ||||||||||||||||||||||||||||||||||||||||||
| 1002 | calls the public chainers and body methods needs no special support. | ||||||||||||||||||||||||||||||||||||||||||
| 1003 | |||||||||||||||||||||||||||||||||||||||||||
| 1004 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 1005 | |||||||||||||||||||||||||||||||||||||||||||
| 1006 | A response value never needs C<$send> until it is sent, so "I don't have a | ||||||||||||||||||||||||||||||||||||||||||
| 1007 | connection here" just means "I am not sending yet": hold the value and call | ||||||||||||||||||||||||||||||||||||||||||
| 1008 | C<respond> (or return it from an endpoint, where dispatch sends it) when a | ||||||||||||||||||||||||||||||||||||||||||
| 1009 | connection is available. | ||||||||||||||||||||||||||||||||||||||||||
| 1010 | |||||||||||||||||||||||||||||||||||||||||||
| 1011 | =head1 SEE ALSO | ||||||||||||||||||||||||||||||||||||||||||
| 1012 | |||||||||||||||||||||||||||||||||||||||||||
| 1013 | L<PAGI>, L<PAGI::Request>, L<PAGI::Server> | ||||||||||||||||||||||||||||||||||||||||||
| 1014 | |||||||||||||||||||||||||||||||||||||||||||
| 1015 | =head1 AUTHOR | ||||||||||||||||||||||||||||||||||||||||||
| 1016 | |||||||||||||||||||||||||||||||||||||||||||
| 1017 | PAGI Contributors | ||||||||||||||||||||||||||||||||||||||||||
| 1018 | |||||||||||||||||||||||||||||||||||||||||||
| 1019 | =cut | ||||||||||||||||||||||||||||||||||||||||||
| 1020 | |||||||||||||||||||||||||||||||||||||||||||
| 1021 | 183 | ▶ | sub new { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
new: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1022 | 183 | my ($class, $scope) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1023 | 183 | ▶ | croak("scope must be a hashref") if defined $scope && ref($scope) ne 'HASH'; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
defined $scope and ref $scope ne "HASH"
MC/DC100%2/2
defined $scope and ref $scope ne "HASH"
defined $scope
ref $scope ne "HASH"
Truth table100%3/3
A and B
A= defined $scopeB= ref $scope ne "HASH"
| |||||||||||||||||||||||||||||||||||||||||||
| 1024 | 182 | return bless { | |||||||||||||||||||||||||||||||||||||||||
| 1025 | scope => $scope, # optional, inert (accessors / Stash); NOT a connection | ||||||||||||||||||||||||||||||||||||||||||
| 1026 | _headers => PAGI::Headers->new, | ||||||||||||||||||||||||||||||||||||||||||
| 1027 | }, $class; | ||||||||||||||||||||||||||||||||||||||||||
| 1028 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1029 | |||||||||||||||||||||||||||||||||||||||||||
| 1030 | 199 | ▶ | sub status { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
status: called CC=6 SCAR=17.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1031 | 199 | my ($self, $code) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1032 | 199 | ▶ | return $self->{_status} // 200 if @_ == 1; # lazy default | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%2/2
$self->{"_status"} // 200
MC/DC100%1/1
$self->{"_status"} // 200
$self->{"_status"}
Truth table100%2/2
A
A= $self->{"_status"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1033 | 61 | ▶ | croak("Status must be a number between 100-599") | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%6/6
$code =~ /^\d+$/ and $code >= 100 and $code <= 599
$code =~ /^\d+$/ and $code >= 100
MC/DC100%3/3
$code =~ /^\d+$/ and $code >= 100 and $code <= 599
$code =~ /^\d+$/
$code >= 100
$code <= 599
Truth table100%4/4
A and B and C
A= $code =~ /^\d+$/B= $code >= 100C= $code <= 599
| |||||||||||||||||||||||||||||||||||||||||||
| 1034 | unless $code =~ /^\d+$/ && $code >= 100 && $code <= 599; | ||||||||||||||||||||||||||||||||||||||||||
| 1035 | 58 | $self->{_status} = $code; | |||||||||||||||||||||||||||||||||||||||||
| 1036 | 58 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1037 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1038 | |||||||||||||||||||||||||||||||||||||||||||
| 1039 | 10 | ▶ | sub status_try { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
status_try: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1040 | 10 | my ($self, $code) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1041 | 10 | ▶ | return $self if exists $self->{_status}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1042 | 7 | return $self->status($code); | |||||||||||||||||||||||||||||||||||||||||
| 1043 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1044 | |||||||||||||||||||||||||||||||||||||||||||
| 1045 | 67 | ▶ | sub header { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
header: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1046 | 67 | my ($self, $name, $value) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1047 | 67 | ▶ | croak("Header name is required") unless defined $name; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1048 | 67 | ▶ | return $self->{_headers}->get($name) if @_ == 2; # getter: last value | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1049 | 65 | $self->{_headers}->add($name, $value); # setter: append | |||||||||||||||||||||||||||||||||||||||||
| 1050 | 65 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1051 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1052 | |||||||||||||||||||||||||||||||||||||||||||
| 1053 | 4 | ▶ | sub headers { return $_[0]->{_headers} } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
headers: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1054 | |||||||||||||||||||||||||||||||||||||||||||
| 1055 | 1 | ▶ | sub header_all { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
header_all: called CC=2 SCAR=7.1
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1056 | 1 | my ($self, $name) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1057 | 1 | ▶ | croak("Header name is required") unless defined $name; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1058 | 1 | return $self->{_headers}->get_all($name); | |||||||||||||||||||||||||||||||||||||||||
| 1059 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1060 | |||||||||||||||||||||||||||||||||||||||||||
| 1061 | 2 | ▶ | sub header_try { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
header_try: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1062 | 2 | my ($self, $name, $value) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1063 | 2 | $self->{_headers}->set_default($name, $value); | |||||||||||||||||||||||||||||||||||||||||
| 1064 | 2 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1065 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1066 | |||||||||||||||||||||||||||||||||||||||||||
| 1067 | 1 | ▶ | sub remove_header { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
remove_header: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1068 | 1 | my ($self, $name) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1069 | 1 | ▶ | croak("Header name is required") unless defined $name; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1070 | 1 | $self->{_headers}->remove($name); | |||||||||||||||||||||||||||||||||||||||||
| 1071 | 1 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1072 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1073 | |||||||||||||||||||||||||||||||||||||||||||
| 1074 | 122 | ▶ | sub content_type { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
content_type: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1075 | 122 | my ($self, $type) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1076 | 122 | ▶ | return $self->{_headers}->get('content-type') if @_ == 1; # getter | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1077 | 39 | ▶ | if (defined $type) { $self->{_headers}->set('content-type', $type) } | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1078 | 1 | else { $self->{_headers}->remove('content-type') } # content_type(undef) clears | |||||||||||||||||||||||||||||||||||||||||
| 1079 | 39 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1080 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1081 | |||||||||||||||||||||||||||||||||||||||||||
| 1082 | 91 | ▶ | sub content_type_try { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
content_type_try: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1083 | 91 | my ($self, $type) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1084 | 91 | $self->{_headers}->set_default('content-type', $type); | |||||||||||||||||||||||||||||||||||||||||
| 1085 | 91 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1086 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1087 | |||||||||||||||||||||||||||||||||||||||||||
| 1088 | 3 | ▶ | sub has_status { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
has_status: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1089 | 3 | my ($self) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1090 | 3 | ▶ | return exists $self->{_status} ? 1 : 0; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1091 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1092 | |||||||||||||||||||||||||||||||||||||||||||
| 1093 | 4 | ▶ | sub has_header { return $_[0]->{_headers}->has($_[1]) } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
has_header: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1094 | 86 | ▶ | sub has_content_type { return $_[0]->{_headers}->has('content-type') } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
has_content_type: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1095 | |||||||||||||||||||||||||||||||||||||||||||
| 1096 | 12 | ▶ | sub has_body_source { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
has_body_source: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1097 | 12 | my ($self) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1098 | 12 | ▶ | return (exists $self->{_body} || exists $self->{_stream} || exists $self->{_file}) ? 1 : 0; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%6/6
exists $self->{"_body"} or exists $self->{"_stream"} or exists $self->{"_file"}
exists $self->{"_body"} or exists $self->{"_stream"}
MC/DC100%3/3
exists $self->{"_body"} or exists $self->{"_stream"} or exists $self->{"_file"}
exists $self->{"_body"}
exists $self->{"_stream"}
exists $self->{"_file"}
Truth table100%4/4
A or B or C
A= exists $self->{"_body"}B= exists $self->{"_stream"}C= exists $self->{"_file"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1099 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1100 | |||||||||||||||||||||||||||||||||||||||||||
| 1101 | 8 | ▶ | sub scope { shift->{scope} } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
scope: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1102 | |||||||||||||||||||||||||||||||||||||||||||
| 1103 | 120 | ▶ | sub _set_body { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_set_body: called CC=2 SCAR=6.9
| |||||||||||||||||||||||||||||||||||||||||||
| 1104 | 120 | my ($self, $bytes, $default_type) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1105 | 120 | $self->{_body} = $bytes; | |||||||||||||||||||||||||||||||||||||||||
| 1106 | 120 | ▶ | $self->content_type_try($default_type) if defined $default_type; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1107 | 120 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1108 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1109 | |||||||||||||||||||||||||||||||||||||||||||
| 1110 | # The UTF-8 text body helpers call this so the Content-Type advertises the | ||||||||||||||||||||||||||||||||||||||||||
| 1111 | # encoding they just applied. A charset is appended only when the type both | ||||||||||||||||||||||||||||||||||||||||||
| 1112 | # lacks one and actually defines a charset parameter. application/json and the | ||||||||||||||||||||||||||||||||||||||||||
| 1113 | # structured-suffix +json types define none — JSON is always UTF-8 per RFC 8259 | ||||||||||||||||||||||||||||||||||||||||||
| 1114 | # — so they are left bare; application/xml, text/*, and the +xml types do carry | ||||||||||||||||||||||||||||||||||||||||||
| 1115 | # charset (RFC 7303), so they get it. | ||||||||||||||||||||||||||||||||||||||||||
| 1116 | 80 | ▶ | sub _ensure_charset { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_ensure_charset: called CC=7 SCAR=19.5
| |||||||||||||||||||||||||||||||||||||||||||
| 1117 | 80 | my ($self, $charset) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1118 | 80 | ▶ | $charset //= 'utf-8'; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$charset //= "utf-8"
MC/DC100%1/1
$charset //= "utf-8"
$charset
Truth table100%2/2
A
A= $charset
| |||||||||||||||||||||||||||||||||||||||||||
| 1119 | 80 | ▶ | return $self unless $self->has_content_type; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1120 | 80 | my $ct = $self->content_type; | |||||||||||||||||||||||||||||||||||||||||
| 1121 | 80 | ▶ | return $self if $ct =~ /charset=/i; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1122 | 35 | my ($type) = $ct =~ m{^\s*([^;]+)}; | |||||||||||||||||||||||||||||||||||||||||
| 1123 | 35 | ▶ | $type //= ''; | ||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$type //= ""
MC/DC0%0/1
$type //= ""
$type
Truth table50%1/2
A
A= $type
| |||||||||||||||||||||||||||||||||||||||||||
| 1124 | 35 | $type =~ s/\s+\z//; | |||||||||||||||||||||||||||||||||||||||||
| 1125 | 35 | ▶ | return $self if lc($type) eq 'application/json' || $type =~ /\+json\z/i; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
lc $type eq "application/json" or $type =~ /\+json\z/i
MC/DC100%2/2
lc $type eq "application/json" or $type =~ /\+json\z/i
lc $type eq "application/json"
$type =~ /\+json\z/i
Truth table100%3/3
A or B
A= lc $type eq "application/json"B= $type =~ /\+json\z/i
| |||||||||||||||||||||||||||||||||||||||||||
| 1126 | 6 | $self->content_type("$ct; charset=$charset"); | |||||||||||||||||||||||||||||||||||||||||
| 1127 | 6 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1128 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1129 | |||||||||||||||||||||||||||||||||||||||||||
| 1130 | 135 | ▶ | sub _render_headers { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_render_headers: called CC=3 SCAR=11.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1131 | 135 | my ($self, $extra_len) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1132 | 135 | my $pairs = $self->{_headers}->to_pairs; | |||||||||||||||||||||||||||||||||||||||||
| 1133 | 135 | ▶ | if (defined $extra_len) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1134 | # Buffered response: Content-Length is authoritative. Drop any user-set | ||||||||||||||||||||||||||||||||||||||||||
| 1135 | # Content-Length (no duplicates) and any Transfer-Encoding (CL+TE is a | ||||||||||||||||||||||||||||||||||||||||||
| 1136 | # request-smuggling vector), then append the one true length. | ||||||||||||||||||||||||||||||||||||||||||
| 1137 | @$pairs = grep { | ||||||||||||||||||||||||||||||||||||||||||
| 1138 | 109 | (my $k = $_->[0]) =~ tr/A-Z/a-z/; # ASCII fold (field names are ASCII tokens) | |||||||||||||||||||||||||||||||||||||||||
| 1139 | 137 | ▶ | $k ne 'content-length' && $k ne 'transfer-encoding' | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%3/3
$k ne 'content-length' && $k ne 'transfer-encoding'
MC/DC100%2/2
$k ne 'content-length' && $k ne 'transfer-encoding'
$k ne 'content-length'
$k ne 'transfer-encoding'
Truth table100%3/3
A && B
A= $k ne 'content-length'B= $k ne 'transfer-encoding'
| |||||||||||||||||||||||||||||||||||||||||||
| 1140 | } @$pairs; | ||||||||||||||||||||||||||||||||||||||||||
| 1141 | 109 | push @$pairs, ['content-length', $extra_len]; | |||||||||||||||||||||||||||||||||||||||||
| 1142 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1143 | 135 | return $pairs; | |||||||||||||||||||||||||||||||||||||||||
| 1144 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1145 | |||||||||||||||||||||||||||||||||||||||||||
| 1146 | 130 | ▶ | async sub respond { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
respond: called CC=8 SCAR=20.8
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1147 | 130 | my ($self, $send) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1148 | 130 | ▶ | croak("send must be a coderef") unless ref($send) eq 'CODE'; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1149 | |||||||||||||||||||||||||||||||||||||||||||
| 1150 | 130 | ▶ | if ($self->{_stream}) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1151 | 15 | await $send->({ | |||||||||||||||||||||||||||||||||||||||||
| 1152 | type => 'http.response.start', | ||||||||||||||||||||||||||||||||||||||||||
| 1153 | status => $self->status, | ||||||||||||||||||||||||||||||||||||||||||
| 1154 | headers => $self->_render_headers(undef), | ||||||||||||||||||||||||||||||||||||||||||
| 1155 | }); | ||||||||||||||||||||||||||||||||||||||||||
| 1156 | 15 | my $writer = PAGI::Response::Writer->new($send); | |||||||||||||||||||||||||||||||||||||||||
| 1157 | 15 | await $self->{_stream}->($writer); | |||||||||||||||||||||||||||||||||||||||||
| 1158 | 15 | ▶ | await $writer->close() unless $writer->is_closed; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1159 | 15 | return; | |||||||||||||||||||||||||||||||||||||||||
| 1160 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1161 | |||||||||||||||||||||||||||||||||||||||||||
| 1162 | 115 | ▶ | if ($self->{_file}) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1163 | 6 | my $fd = $self->{_file}; | |||||||||||||||||||||||||||||||||||||||||
| 1164 | # Headers (incl. content-length) were set at send_file() build time. | ||||||||||||||||||||||||||||||||||||||||||
| 1165 | 6 | await $send->({ | |||||||||||||||||||||||||||||||||||||||||
| 1166 | type => 'http.response.start', | ||||||||||||||||||||||||||||||||||||||||||
| 1167 | status => $self->status, | ||||||||||||||||||||||||||||||||||||||||||
| 1168 | headers => $self->_render_headers(undef), | ||||||||||||||||||||||||||||||||||||||||||
| 1169 | }); | ||||||||||||||||||||||||||||||||||||||||||
| 1170 | my $body_event = { | ||||||||||||||||||||||||||||||||||||||||||
| 1171 | type => 'http.response.body', | ||||||||||||||||||||||||||||||||||||||||||
| 1172 | file => $fd->{path}, | ||||||||||||||||||||||||||||||||||||||||||
| 1173 | 6 | }; | |||||||||||||||||||||||||||||||||||||||||
| 1174 | 6 | ▶ | $body_event->{offset} = $fd->{offset} if exists $fd->{offset}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1175 | 6 | ▶ | $body_event->{length} = $fd->{length} if exists $fd->{length}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1176 | 6 | await $send->($body_event); | |||||||||||||||||||||||||||||||||||||||||
| 1177 | 6 | return; | |||||||||||||||||||||||||||||||||||||||||
| 1178 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1179 | |||||||||||||||||||||||||||||||||||||||||||
| 1180 | 109 | ▶ | my $body = $self->{_body} // ''; | ||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$self->{"_body"} // ""
MC/DC0%0/1
$self->{"_body"} // ""
$self->{"_body"}
Truth table50%1/2
A
A= $self->{"_body"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1181 | 109 | await $send->({ | |||||||||||||||||||||||||||||||||||||||||
| 1182 | type => 'http.response.start', | ||||||||||||||||||||||||||||||||||||||||||
| 1183 | status => $self->status, | ||||||||||||||||||||||||||||||||||||||||||
| 1184 | headers => $self->_render_headers(length $body), | ||||||||||||||||||||||||||||||||||||||||||
| 1185 | }); | ||||||||||||||||||||||||||||||||||||||||||
| 1186 | 109 | await $send->({ type => 'http.response.body', body => $body, more => 0 }); | |||||||||||||||||||||||||||||||||||||||||
| 1187 | 109 | return; | |||||||||||||||||||||||||||||||||||||||||
| 1188 | 20 | } | |||||||||||||||||||||||||||||||||||||||||
| 1189 | |||||||||||||||||||||||||||||||||||||||||||
| 1190 | 1 | ▶ | sub to_app { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
to_app: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1191 | 1 | my ($self) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1192 | 1 | ▶ | return async sub { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1193 | 1 | my ($scope, $receive, $send) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1194 | 1 | await $self->respond($send); | |||||||||||||||||||||||||||||||||||||||||
| 1195 | 1 | }; | |||||||||||||||||||||||||||||||||||||||||
| 1196 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1197 | |||||||||||||||||||||||||||||||||||||||||||
| 1198 | |||||||||||||||||||||||||||||||||||||||||||
| 1199 | 7 | ▶ | sub is_sent { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
is_sent: called CC=5 SCAR=16.3
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1200 | 7 | my ($self) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1201 | 7 | ▶ | my $conn = $self->{scope} ? $self->{scope}{'pagi.connection'} : undef; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1202 | 7 | ▶ | return 0 unless $conn; # no connection object: server-less / not started | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1203 | 7 | ▶ | Carp::croak("pagi.connection lacks response_started (non-conforming server)") | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1204 | unless $conn->can('response_started'); | ||||||||||||||||||||||||||||||||||||||||||
| 1205 | 6 | ▶ | return $conn->response_started ? 1 : 0; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1206 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1207 | |||||||||||||||||||||||||||||||||||||||||||
| 1208 | # Returns the invocant if it is already an instance; otherwise creates a new | ||||||||||||||||||||||||||||||||||||||||||
| 1209 | # detached instance from the class name. Allows finisher methods to be called | ||||||||||||||||||||||||||||||||||||||||||
| 1210 | # as either class-method factories or instance methods. | ||||||||||||||||||||||||||||||||||||||||||
| 1211 | 146 | ▶ | sub _self_or_new { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_self_or_new: called CC=2 SCAR=6.9
| |||||||||||||||||||||||||||||||||||||||||||
| 1212 | 146 | my ($proto) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1213 | 146 | ▶ | return ref($proto) ? $proto : $proto->new; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1214 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1215 | |||||||||||||||||||||||||||||||||||||||||||
| 1216 | # Encode a text string to UTF-8 bytes, croaking on invalid characters. | ||||||||||||||||||||||||||||||||||||||||||
| 1217 | # Replicates the encoding used by the old send() method. | ||||||||||||||||||||||||||||||||||||||||||
| 1218 | 53 | ▶ | sub _enc { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_enc: called CC=3 SCAR=11.1
| |||||||||||||||||||||||||||||||||||||||||||
| 1219 | 53 | my ($str, $charset) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1220 | 53 | ▶ | $charset //= 'utf-8'; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$charset //= "utf-8"
MC/DC100%1/1
$charset //= "utf-8"
$charset
Truth table100%2/2
A
A= $charset
| |||||||||||||||||||||||||||||||||||||||||||
| 1221 | 53 | ▶ | return encode($charset, $str // '', FB_CROAK); | ||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$str // ""
MC/DC0%0/1
$str // ""
$str
Truth table50%1/2
A
A= $str
| |||||||||||||||||||||||||||||||||||||||||||
| 1222 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1223 | |||||||||||||||||||||||||||||||||||||||||||
| 1224 | 20 | my %_RESPONSE_OPTS = map { $_ => 1 } qw(status content_type headers); | |||||||||||||||||||||||||||||||||||||||||
| 1225 | |||||||||||||||||||||||||||||||||||||||||||
| 1226 | 104 | ▶ | sub _apply_opts { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_apply_opts: called CC=8 SCAR=20.8
| |||||||||||||||||||||||||||||||||||||||||||
| 1227 | 104 | my ($self, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1228 | 104 | for my $k (keys %opts) { | |||||||||||||||||||||||||||||||||||||||||
| 1229 | croak "Unknown response option '$k' (known: status, content_type, headers)" | ||||||||||||||||||||||||||||||||||||||||||
| 1230 | 9 | ▶ | unless $_RESPONSE_OPTS{$k}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1231 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1232 | 103 | ▶ | $self->status($opts{status}) if defined $opts{status}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1233 | 103 | ▶ | $self->content_type($opts{content_type}) if defined $opts{content_type}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1234 | 103 | ▶ | if (my $h = $opts{headers}) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1235 | 2 | ▶ | croak "headers must be an even-length arrayref [ name => value, ... ]" | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1236 | if @$h % 2; | ||||||||||||||||||||||||||||||||||||||||||
| 1237 | 1 | my @pairs = @$h; | |||||||||||||||||||||||||||||||||||||||||
| 1238 | 1 | ▶ | while (@pairs) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1239 | 1 | my ($name, $value) = splice(@pairs, 0, 2); | |||||||||||||||||||||||||||||||||||||||||
| 1240 | 1 | $self->header($name, $value); | |||||||||||||||||||||||||||||||||||||||||
| 1241 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1242 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1243 | 102 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1244 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1245 | |||||||||||||||||||||||||||||||||||||||||||
| 1246 | 17 | ▶ | sub send_raw { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
send_raw: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1247 | 17 | my ($proto, $body, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1248 | 17 | my $self = $proto->_self_or_new; | |||||||||||||||||||||||||||||||||||||||||
| 1249 | 17 | ▶ | $self->_set_body($body // '', undef); | ||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$body // ""
MC/DC0%0/1
$body // ""
$body
Truth table50%1/2
A
A= $body
| |||||||||||||||||||||||||||||||||||||||||||
| 1250 | 17 | $self->_apply_opts(%opts); | |||||||||||||||||||||||||||||||||||||||||
| 1251 | 17 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1252 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1253 | |||||||||||||||||||||||||||||||||||||||||||
| 1254 | 3 | ▶ | sub send { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
send: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1255 | 3 | my ($proto, $body, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1256 | 3 | my $self = $proto->_self_or_new; | |||||||||||||||||||||||||||||||||||||||||
| 1257 | 3 | ▶ | my $charset = $opts{charset} // 'utf-8'; | ||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$opts{"charset"} // "utf-8"
MC/DC0%0/1
$opts{"charset"} // "utf-8"
$opts{"charset"}
Truth table50%1/2
A
A= $opts{"charset"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1258 | 3 | my $encoded = _enc($body, $charset); | |||||||||||||||||||||||||||||||||||||||||
| 1259 | 3 | ▶ | $self->content_type("text/plain; charset=$charset") unless $self->has_content_type; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1260 | 3 | $self->_ensure_charset($charset); | |||||||||||||||||||||||||||||||||||||||||
| 1261 | 3 | $self->{_body} = $encoded; | |||||||||||||||||||||||||||||||||||||||||
| 1262 | 3 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1263 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1264 | |||||||||||||||||||||||||||||||||||||||||||
| 1265 | 43 | ▶ | sub text { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
text: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1266 | 43 | my ($proto, $body, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1267 | 43 | my $self = $proto->_self_or_new; | |||||||||||||||||||||||||||||||||||||||||
| 1268 | 43 | $self->_set_body(_enc($body), 'text/plain; charset=utf-8'); | |||||||||||||||||||||||||||||||||||||||||
| 1269 | 43 | $self->_apply_opts(%opts); | |||||||||||||||||||||||||||||||||||||||||
| 1270 | 42 | $self->_ensure_charset; | |||||||||||||||||||||||||||||||||||||||||
| 1271 | 42 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1272 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1273 | |||||||||||||||||||||||||||||||||||||||||||
| 1274 | 7 | ▶ | sub html { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
html: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1275 | 7 | my ($proto, $body, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1276 | 7 | my $self = $proto->_self_or_new; | |||||||||||||||||||||||||||||||||||||||||
| 1277 | 7 | $self->_set_body(_enc($body), 'text/html; charset=utf-8'); | |||||||||||||||||||||||||||||||||||||||||
| 1278 | 7 | $self->_apply_opts(%opts); | |||||||||||||||||||||||||||||||||||||||||
| 1279 | 7 | $self->_ensure_charset; | |||||||||||||||||||||||||||||||||||||||||
| 1280 | 7 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1281 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1282 | |||||||||||||||||||||||||||||||||||||||||||
| 1283 | 29 | ▶ | sub json { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
json: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1284 | 29 | my ($proto, $data, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1285 | 29 | my $self = $proto->_self_or_new; | |||||||||||||||||||||||||||||||||||||||||
| 1286 | 29 | my $body = JSON::MaybeXS->new(utf8 => 1, canonical => 1)->encode($data); | |||||||||||||||||||||||||||||||||||||||||
| 1287 | 29 | $self->_set_body($body, 'application/json'); | |||||||||||||||||||||||||||||||||||||||||
| 1288 | 29 | $self->_apply_opts(%opts); | |||||||||||||||||||||||||||||||||||||||||
| 1289 | 28 | $self->_ensure_charset; | |||||||||||||||||||||||||||||||||||||||||
| 1290 | 28 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1291 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1292 | |||||||||||||||||||||||||||||||||||||||||||
| 1293 | 13 | ▶ | sub redirect { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
redirect: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1294 | 13 | my ($proto, $url, $status) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1295 | 13 | my $self = $proto->_self_or_new; | |||||||||||||||||||||||||||||||||||||||||
| 1296 | 13 | ▶ | $self->status($status // 302)->header('location', $url); | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$status // 302
MC/DC100%1/1
$status // 302
$status
Truth table100%2/2
A
A= $status
| |||||||||||||||||||||||||||||||||||||||||||
| 1297 | 13 | $self->_set_body('', undef); | |||||||||||||||||||||||||||||||||||||||||
| 1298 | 13 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1299 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1300 | |||||||||||||||||||||||||||||||||||||||||||
| 1301 | 8 | ▶ | sub empty { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
empty: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1302 | 8 | my ($proto, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1303 | 8 | my $self = $proto->_self_or_new; | |||||||||||||||||||||||||||||||||||||||||
| 1304 | 8 | $self->status_try(204); | |||||||||||||||||||||||||||||||||||||||||
| 1305 | 8 | $self->_set_body('', undef); | |||||||||||||||||||||||||||||||||||||||||
| 1306 | 8 | $self->_apply_opts(%opts); | |||||||||||||||||||||||||||||||||||||||||
| 1307 | 8 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1308 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1309 | |||||||||||||||||||||||||||||||||||||||||||
| 1310 | 5 | ▶ | sub cookie { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
cookie: called CC=8 SCAR=20.8
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1311 | 5 | my ($self, $name, $value, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1312 | 5 | my @parts = ("$name=$value"); | |||||||||||||||||||||||||||||||||||||||||
| 1313 | |||||||||||||||||||||||||||||||||||||||||||
| 1314 | 5 | ▶ | push @parts, "Max-Age=$opts{max_age}" if defined $opts{max_age}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1315 | 5 | ▶ | push @parts, "Expires=$opts{expires}" if defined $opts{expires}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1316 | 5 | ▶ | push @parts, "Path=$opts{path}" if defined $opts{path}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1317 | 5 | ▶ | push @parts, "Domain=$opts{domain}" if defined $opts{domain}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1318 | 5 | ▶ | push @parts, "Secure" if $opts{secure}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1319 | 5 | ▶ | push @parts, "HttpOnly" if $opts{httponly}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1320 | 5 | ▶ | push @parts, "SameSite=$opts{samesite}" if defined $opts{samesite}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1321 | |||||||||||||||||||||||||||||||||||||||||||
| 1322 | 5 | my $cookie_str = join('; ', @parts); | |||||||||||||||||||||||||||||||||||||||||
| 1323 | 5 | $self->{_headers}->add('set-cookie', $cookie_str); | |||||||||||||||||||||||||||||||||||||||||
| 1324 | |||||||||||||||||||||||||||||||||||||||||||
| 1325 | 5 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1326 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1327 | |||||||||||||||||||||||||||||||||||||||||||
| 1328 | 1 | ▶ | sub delete_cookie { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
delete_cookie: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1329 | 1 | my ($self, $name, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1330 | return $self->cookie($name, '', | ||||||||||||||||||||||||||||||||||||||||||
| 1331 | max_age => 0, | ||||||||||||||||||||||||||||||||||||||||||
| 1332 | path => $opts{path}, | ||||||||||||||||||||||||||||||||||||||||||
| 1333 | domain => $opts{domain}, | ||||||||||||||||||||||||||||||||||||||||||
| 1334 | 1 | ); | |||||||||||||||||||||||||||||||||||||||||
| 1335 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1336 | |||||||||||||||||||||||||||||||||||||||||||
| 1337 | 6 | ▶ | sub cors { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
cors: called CC=14 SCAR=26.4
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1338 | 6 | my ($self, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1339 | 6 | ▶ | my $origin = $opts{origin} // '*'; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$opts{"origin"} // "*"
MC/DC100%1/1
$opts{"origin"} // "*"
$opts{"origin"}
Truth table100%2/2
A
A= $opts{"origin"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1340 | 6 | ▶ | my $credentials = $opts{credentials} // 0; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$opts{"credentials"} // 0
MC/DC100%1/1
$opts{"credentials"} // 0
$opts{"credentials"}
Truth table100%2/2
A
A= $opts{"credentials"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1341 | 6 | ▶ | my $methods = $opts{methods} // [qw(GET POST PUT DELETE PATCH OPTIONS)]; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$opts{"methods"} // ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
MC/DC100%1/1
$opts{"methods"} // ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
$opts{"methods"}
Truth table100%2/2
A
A= $opts{"methods"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1342 | 6 | ▶ | my $headers = $opts{headers} // [qw(Content-Type Authorization X-Requested-With)]; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$opts{"headers"} // ["Content-Type", "Authorization", "X-Requested-With"]
MC/DC100%1/1
$opts{"headers"} // ["Content-Type", "Authorization", "X-Requested-With"]
$opts{"headers"}
Truth table100%2/2
A
A= $opts{"headers"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1343 | 6 | ▶ | my $expose = $opts{expose} // []; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$opts{"expose"} // []
MC/DC100%1/1
$opts{"expose"} // []
$opts{"expose"}
Truth table100%2/2
A
A= $opts{"expose"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1344 | 6 | ▶ | my $max_age = $opts{max_age} // 86400; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$opts{"max_age"} // 86400
MC/DC100%1/1
$opts{"max_age"} // 86400
$opts{"max_age"}
Truth table100%2/2
A
A= $opts{"max_age"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1345 | 6 | ▶ | my $preflight = $opts{preflight} // 0; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$opts{"preflight"} // 0
MC/DC100%1/1
$opts{"preflight"} // 0
$opts{"preflight"}
Truth table100%2/2
A
A= $opts{"preflight"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1346 | |||||||||||||||||||||||||||||||||||||||||||
| 1347 | # Determine the origin to send back | ||||||||||||||||||||||||||||||||||||||||||
| 1348 | 6 | my $allow_origin; | |||||||||||||||||||||||||||||||||||||||||
| 1349 | 6 | ▶ | if ($origin eq '*' && $credentials) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
$origin eq "*" and $credentials
MC/DC100%2/2
$origin eq "*" and $credentials
$origin eq "*"
$credentials
Truth table100%3/3
A and B
A= $origin eq "*"B= $credentials
| |||||||||||||||||||||||||||||||||||||||||||
| 1350 | # With credentials, can't use wildcard - use request_origin if provided | ||||||||||||||||||||||||||||||||||||||||||
| 1351 | 1 | ▶ | $allow_origin = $opts{request_origin} // '*'; | ||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$opts{"request_origin"} // "*"
MC/DC0%0/1
$opts{"request_origin"} // "*"
$opts{"request_origin"}
Truth table50%1/2
A
A= $opts{"request_origin"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1352 | } else { | ||||||||||||||||||||||||||||||||||||||||||
| 1353 | 5 | $allow_origin = $origin; | |||||||||||||||||||||||||||||||||||||||||
| 1354 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1355 | |||||||||||||||||||||||||||||||||||||||||||
| 1356 | # Core CORS headers (always set) | ||||||||||||||||||||||||||||||||||||||||||
| 1357 | 6 | $self->header('Access-Control-Allow-Origin', $allow_origin); | |||||||||||||||||||||||||||||||||||||||||
| 1358 | 6 | $self->header('Vary', 'Origin'); | |||||||||||||||||||||||||||||||||||||||||
| 1359 | |||||||||||||||||||||||||||||||||||||||||||
| 1360 | 6 | ▶ | if ($credentials) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1361 | 2 | $self->header('Access-Control-Allow-Credentials', 'true'); | |||||||||||||||||||||||||||||||||||||||||
| 1362 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1363 | |||||||||||||||||||||||||||||||||||||||||||
| 1364 | 6 | ▶ | if (@$expose) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1365 | 1 | $self->header('Access-Control-Expose-Headers', join(', ', @$expose)); | |||||||||||||||||||||||||||||||||||||||||
| 1366 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1367 | |||||||||||||||||||||||||||||||||||||||||||
| 1368 | # Preflight headers (for OPTIONS responses or when explicitly requested) | ||||||||||||||||||||||||||||||||||||||||||
| 1369 | 6 | ▶ | if ($preflight) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1370 | 1 | $self->header('Access-Control-Allow-Methods', join(', ', @$methods)); | |||||||||||||||||||||||||||||||||||||||||
| 1371 | 1 | $self->header('Access-Control-Allow-Headers', join(', ', @$headers)); | |||||||||||||||||||||||||||||||||||||||||
| 1372 | 1 | $self->header('Access-Control-Max-Age', $max_age); | |||||||||||||||||||||||||||||||||||||||||
| 1373 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1374 | |||||||||||||||||||||||||||||||||||||||||||
| 1375 | 6 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1376 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1377 | |||||||||||||||||||||||||||||||||||||||||||
| 1378 | 15 | ▶ | sub stream { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
stream: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1379 | 15 | my ($proto, $callback) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1380 | 15 | my $self = $proto->_self_or_new; | |||||||||||||||||||||||||||||||||||||||||
| 1381 | 15 | $self->{_stream} = $callback; | |||||||||||||||||||||||||||||||||||||||||
| 1382 | 15 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1383 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1384 | |||||||||||||||||||||||||||||||||||||||||||
| 1385 | 6 | ▶ | async sub writer { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
writer: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1386 | 6 | my ($self, $send, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1387 | 6 | ▶ | croak("send must be a coderef") unless ref($send) eq 'CODE'; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1388 | # A writer takes over the connection for live streaming; it can only be | ||||||||||||||||||||||||||||||||||||||||||
| 1389 | # taken once on a given response value. (The cross-stack "did a response | ||||||||||||||||||||||||||||||||||||||||||
| 1390 | # start" fact lives on pagi.connection; this is a local single-takeover guard.) | ||||||||||||||||||||||||||||||||||||||||||
| 1391 | 6 | ▶ | croak("Response already sent") if $self->{_writer_started}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1392 | 5 | $self->{_writer_started} = 1; | |||||||||||||||||||||||||||||||||||||||||
| 1393 | |||||||||||||||||||||||||||||||||||||||||||
| 1394 | # Send headers | ||||||||||||||||||||||||||||||||||||||||||
| 1395 | 5 | await $send->({ | |||||||||||||||||||||||||||||||||||||||||
| 1396 | type => 'http.response.start', | ||||||||||||||||||||||||||||||||||||||||||
| 1397 | status => $self->status, | ||||||||||||||||||||||||||||||||||||||||||
| 1398 | headers => $self->_render_headers(undef), | ||||||||||||||||||||||||||||||||||||||||||
| 1399 | }); | ||||||||||||||||||||||||||||||||||||||||||
| 1400 | |||||||||||||||||||||||||||||||||||||||||||
| 1401 | 5 | return PAGI::Response::Writer->new($send, %opts); | |||||||||||||||||||||||||||||||||||||||||
| 1402 | 20 | } | |||||||||||||||||||||||||||||||||||||||||
| 1403 | |||||||||||||||||||||||||||||||||||||||||||
| 1404 | # Simple MIME type mapping | ||||||||||||||||||||||||||||||||||||||||||
| 1405 | 20 | my %MIME_TYPES = ( | |||||||||||||||||||||||||||||||||||||||||
| 1406 | '.html' => 'text/html', | ||||||||||||||||||||||||||||||||||||||||||
| 1407 | '.htm' => 'text/html', | ||||||||||||||||||||||||||||||||||||||||||
| 1408 | '.txt' => 'text/plain', | ||||||||||||||||||||||||||||||||||||||||||
| 1409 | '.css' => 'text/css', | ||||||||||||||||||||||||||||||||||||||||||
| 1410 | '.js' => 'application/javascript', | ||||||||||||||||||||||||||||||||||||||||||
| 1411 | '.json' => 'application/json', | ||||||||||||||||||||||||||||||||||||||||||
| 1412 | '.xml' => 'application/xml', | ||||||||||||||||||||||||||||||||||||||||||
| 1413 | '.pdf' => 'application/pdf', | ||||||||||||||||||||||||||||||||||||||||||
| 1414 | '.zip' => 'application/zip', | ||||||||||||||||||||||||||||||||||||||||||
| 1415 | '.png' => 'image/png', | ||||||||||||||||||||||||||||||||||||||||||
| 1416 | '.jpg' => 'image/jpeg', | ||||||||||||||||||||||||||||||||||||||||||
| 1417 | '.jpeg' => 'image/jpeg', | ||||||||||||||||||||||||||||||||||||||||||
| 1418 | '.gif' => 'image/gif', | ||||||||||||||||||||||||||||||||||||||||||
| 1419 | '.svg' => 'image/svg+xml', | ||||||||||||||||||||||||||||||||||||||||||
| 1420 | '.ico' => 'image/x-icon', | ||||||||||||||||||||||||||||||||||||||||||
| 1421 | '.woff' => 'font/woff', | ||||||||||||||||||||||||||||||||||||||||||
| 1422 | '.woff2'=> 'font/woff2', | ||||||||||||||||||||||||||||||||||||||||||
| 1423 | ); | ||||||||||||||||||||||||||||||||||||||||||
| 1424 | |||||||||||||||||||||||||||||||||||||||||||
| 1425 | 7 | ▶ | sub _mime_type { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_mime_type: called CC=3 SCAR=11.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1426 | 7 | my ($path) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1427 | 7 | my ($ext) = $path =~ /(\.[^.]+)$/; | |||||||||||||||||||||||||||||||||||||||||
| 1428 | 7 | ▶ | return $MIME_TYPES{lc($ext // '')} // 'application/octet-stream'; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%4/4
$MIME_TYPES{lc($ext // "")} // "application/octet-stream"
$ext // ""
MC/DC100%1/1
$MIME_TYPES{lc($ext // "")} // "application/octet-stream"
$MIME_TYPES{lc($ext // "")}
MC/DC100%1/1
$ext // ""
$ext
Truth table100%2/2
A
A= $MIME_TYPES{lc($ext // "")}
Truth table100%2/2
A
A= $ext
| |||||||||||||||||||||||||||||||||||||||||||
| 1429 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1430 | |||||||||||||||||||||||||||||||||||||||||||
| 1431 | 11 | ▶ | sub send_file { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
send_file: called CC=14 SCAR=26.4
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 1432 | 11 | my ($proto, $path, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1433 | 11 | my $self = $proto->_self_or_new; | |||||||||||||||||||||||||||||||||||||||||
| 1434 | |||||||||||||||||||||||||||||||||||||||||||
| 1435 | 11 | ▶ | croak("File not found: $path") unless -f $path; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1436 | 10 | ▶ | croak("Cannot read file: $path") unless -r $path; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1437 | |||||||||||||||||||||||||||||||||||||||||||
| 1438 | # Get file size | ||||||||||||||||||||||||||||||||||||||||||
| 1439 | 10 | my $file_size = -s $path; | |||||||||||||||||||||||||||||||||||||||||
| 1440 | |||||||||||||||||||||||||||||||||||||||||||
| 1441 | # Handle offset and length for range requests | ||||||||||||||||||||||||||||||||||||||||||
| 1442 | 10 | ▶ | my $offset = $opts{offset} // 0; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$opts{"offset"} // 0
MC/DC100%1/1
$opts{"offset"} // 0
$opts{"offset"}
Truth table100%2/2
A
A= $opts{"offset"}
| |||||||||||||||||||||||||||||||||||||||||||
| 1443 | 10 | my $length = $opts{length}; | |||||||||||||||||||||||||||||||||||||||||
| 1444 | |||||||||||||||||||||||||||||||||||||||||||
| 1445 | # Validate offset | ||||||||||||||||||||||||||||||||||||||||||
| 1446 | 10 | ▶ | croak("offset must be non-negative") if $offset < 0; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1447 | 9 | ▶ | croak("offset exceeds file size") if $offset > $file_size; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1448 | |||||||||||||||||||||||||||||||||||||||||||
| 1449 | # Calculate actual length to send | ||||||||||||||||||||||||||||||||||||||||||
| 1450 | 8 | my $max_length = $file_size - $offset; | |||||||||||||||||||||||||||||||||||||||||
| 1451 | 8 | ▶ | if (defined $length) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1452 | 3 | ▶ | croak("length must be non-negative") if $length < 0; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1453 | 2 | ▶ | $length = $max_length if $length > $max_length; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1454 | } else { | ||||||||||||||||||||||||||||||||||||||||||
| 1455 | 5 | $length = $max_length; | |||||||||||||||||||||||||||||||||||||||||
| 1456 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1457 | |||||||||||||||||||||||||||||||||||||||||||
| 1458 | # Set content-type if not already set | ||||||||||||||||||||||||||||||||||||||||||
| 1459 | 7 | $self->content_type_try(_mime_type($path)); | |||||||||||||||||||||||||||||||||||||||||
| 1460 | |||||||||||||||||||||||||||||||||||||||||||
| 1461 | # Set content-length based on actual bytes to send | ||||||||||||||||||||||||||||||||||||||||||
| 1462 | 7 | $self->header('content-length', $length); | |||||||||||||||||||||||||||||||||||||||||
| 1463 | |||||||||||||||||||||||||||||||||||||||||||
| 1464 | # Set content-disposition | ||||||||||||||||||||||||||||||||||||||||||
| 1465 | 7 | my $disposition; | |||||||||||||||||||||||||||||||||||||||||
| 1466 | 7 | ▶ | if ($opts{inline}) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||||||||||||||||
| 1467 | 1 | $disposition = 'inline'; | |||||||||||||||||||||||||||||||||||||||||
| 1468 | } elsif ($opts{filename}) { | ||||||||||||||||||||||||||||||||||||||||||
| 1469 | # Sanitize filename for header | ||||||||||||||||||||||||||||||||||||||||||
| 1470 | 1 | my $safe_filename = $opts{filename}; | |||||||||||||||||||||||||||||||||||||||||
| 1471 | 1 | $safe_filename =~ s/["\r\n]//g; | |||||||||||||||||||||||||||||||||||||||||
| 1472 | 1 | $disposition = "attachment; filename=\"$safe_filename\""; | |||||||||||||||||||||||||||||||||||||||||
| 1473 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1474 | 7 | ▶ | $self->header('content-disposition', $disposition) if $disposition; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1475 | |||||||||||||||||||||||||||||||||||||||||||
| 1476 | # Store the file send descriptor; respond() handles the actual emission. | ||||||||||||||||||||||||||||||||||||||||||
| 1477 | # offset/length are stored only when they narrow the full-file default. | ||||||||||||||||||||||||||||||||||||||||||
| 1478 | 7 | my $file_desc = { path => $path }; | |||||||||||||||||||||||||||||||||||||||||
| 1479 | 7 | ▶ | $file_desc->{offset} = $offset if $offset > 0; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1480 | 7 | ▶ | $file_desc->{length} = $length if $length < $max_length; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1481 | 7 | $self->{_file} = $file_desc; | |||||||||||||||||||||||||||||||||||||||||
| 1482 | |||||||||||||||||||||||||||||||||||||||||||
| 1483 | 7 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1484 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1485 | |||||||||||||||||||||||||||||||||||||||||||
| 1486 | # Writer class for streaming responses | ||||||||||||||||||||||||||||||||||||||||||
| 1487 | 20 | package PAGI::Response::Writer { | |||||||||||||||||||||||||||||||||||||||||
| 1488 | 20 | ▶ | use strict; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1489 | 20 | ▶ | use warnings; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1490 | 20 | ▶ | use Future::AsyncAwait; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1491 | 20 | ▶ | use Carp qw(croak); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1492 | 20 | ▶ | use Scalar::Util qw(blessed); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1493 | |||||||||||||||||||||||||||||||||||||||||||
| 1494 | 20 | ▶ | sub new { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
new: called CC=2 SCAR=6.9
| |||||||||||||||||||||||||||||||||||||||||||
| 1495 | 20 | my ($class, $send, %opts) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1496 | 20 | my $self = bless { | |||||||||||||||||||||||||||||||||||||||||
| 1497 | send => $send, | ||||||||||||||||||||||||||||||||||||||||||
| 1498 | bytes_written => 0, | ||||||||||||||||||||||||||||||||||||||||||
| 1499 | closed => 0, | ||||||||||||||||||||||||||||||||||||||||||
| 1500 | _on_close => [], | ||||||||||||||||||||||||||||||||||||||||||
| 1501 | }, $class; | ||||||||||||||||||||||||||||||||||||||||||
| 1502 | 20 | ▶ | push @{$self->{_on_close}}, $opts{on_close} if $opts{on_close}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1503 | 20 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1504 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1505 | |||||||||||||||||||||||||||||||||||||||||||
| 1506 | 17 | ▶ | async sub write { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
write: called CC=3 SCAR=11.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1507 | 17 | my ($self, $chunk) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1508 | 17 | ▶ | die 'Writer already closed' if $self->{closed}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1509 | 15 | ▶ | $self->{bytes_written} += length($chunk // ''); | ||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$chunk // ""
MC/DC0%0/1
$chunk // ""
$chunk
Truth table50%1/2
A
A= $chunk
| |||||||||||||||||||||||||||||||||||||||||||
| 1510 | 15 | await $self->{send}->({ | |||||||||||||||||||||||||||||||||||||||||
| 1511 | type => 'http.response.body', | ||||||||||||||||||||||||||||||||||||||||||
| 1512 | body => $chunk, | ||||||||||||||||||||||||||||||||||||||||||
| 1513 | more => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 1514 | }); | ||||||||||||||||||||||||||||||||||||||||||
| 1515 | 20 | } | |||||||||||||||||||||||||||||||||||||||||
| 1516 | |||||||||||||||||||||||||||||||||||||||||||
| 1517 | 17 | ▶ | async sub close { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
close: called CC=6 SCAR=17.9
| |||||||||||||||||||||||||||||||||||||||||||
| 1518 | 17 | my ($self) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1519 | 17 | ▶ | return if $self->{closed}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1520 | 17 | $self->{closed} = 1; | |||||||||||||||||||||||||||||||||||||||||
| 1521 | 17 | await $self->{send}->({ | |||||||||||||||||||||||||||||||||||||||||
| 1522 | type => 'http.response.body', | ||||||||||||||||||||||||||||||||||||||||||
| 1523 | body => '', | ||||||||||||||||||||||||||||||||||||||||||
| 1524 | more => 0, | ||||||||||||||||||||||||||||||||||||||||||
| 1525 | }); | ||||||||||||||||||||||||||||||||||||||||||
| 1526 | 17 | for my $cb (@{$self->{_on_close}}) { | |||||||||||||||||||||||||||||||||||||||||
| 1527 | 15 | eval { | |||||||||||||||||||||||||||||||||||||||||
| 1528 | 15 | my $r = $cb->(); | |||||||||||||||||||||||||||||||||||||||||
| 1529 | 14 | ▶ | if (blessed($r) && $r->isa('Future')) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
builtin::blessed($r) and $r->isa("Future")
MC/DC100%2/2
builtin::blessed($r) and $r->isa("Future")
builtin::blessed($r)
$r->isa("Future")
Truth table100%3/3
A and B
A= builtin::blessed($r)B= $r->isa("Future")
| |||||||||||||||||||||||||||||||||||||||||||
| 1530 | 2 | await $r; | |||||||||||||||||||||||||||||||||||||||||
| 1531 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1532 | }; | ||||||||||||||||||||||||||||||||||||||||||
| 1533 | 15 | ▶ | if ($@) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1534 | 2 | warn "PAGI::Response::Writer on_close callback error: $@"; | |||||||||||||||||||||||||||||||||||||||||
| 1535 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1536 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1537 | |||||||||||||||||||||||||||||||||||||||||||
| 1538 | # Clear callback array to break any closure-based cycles | ||||||||||||||||||||||||||||||||||||||||||
| 1539 | 17 | $self->{_on_close} = []; | |||||||||||||||||||||||||||||||||||||||||
| 1540 | 20 | } | |||||||||||||||||||||||||||||||||||||||||
| 1541 | |||||||||||||||||||||||||||||||||||||||||||
| 1542 | 14 | ▶ | sub on_close { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
on_close: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1543 | 14 | my ($self, $cb) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 1544 | 14 | push @{$self->{_on_close}}, $cb; | |||||||||||||||||||||||||||||||||||||||||
| 1545 | 14 | return $self; | |||||||||||||||||||||||||||||||||||||||||
| 1546 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1547 | |||||||||||||||||||||||||||||||||||||||||||
| 1548 | 18 | ▶ | sub is_closed { $_[0]->{closed} } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
is_closed: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1549 | |||||||||||||||||||||||||||||||||||||||||||
| 1550 | 1 | ▶ | sub bytes_written { $_[0]->{bytes_written} } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
bytes_written: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 1551 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1552 | 20 | $PAGI::Response::Writer::VERSION = '0.002002'; | |||||||||||||||||||||||||||||||||||||||||
| 1553 | |||||||||||||||||||||||||||||||||||||||||||
| 1554 | 20 | 1; | |||||||||||||||||||||||||||||||||||||||||