blib/lib/PAGI/Response.pm

filter: Statementstmt 100% 313 / 313 Branchbran 91.5% 119 / 130 Conditioncond 89.8% 62 / 69 MC/DCmcdc 81.0% 30 / 37 Subroutinesub 100% 57 / 57 Podpod 100% 31 / 31 totaltotal 96.0% 612 / 637 CC 98 SCAR 17.6
CC
98
Cov
96%
cors
14.0
send_file
14.0
respond
8.0
CRAP 5.8
« blib/lib/PAGI/Middleware/Rewrite.pm ↑ Summary lib/PAGI/App/Throttle.pm »
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
BranchTrueFalseTotal
if defined $scope and ref $scope ne "HASH" 1 182 183
Condition100%3/3
defined $scope and ref $scope ne "HASH"
!ll&&!rl&&r
451371
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"
ABresult
0X0
100
111
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
BranchTrueFalseTotal
if @_ == 1 138 61 199
Condition100%2/2
$self->{"_status"} // 200
l!l
5187
MC/DC100%1/1
$self->{"_status"} // 200
$self->{"_status"}
Truth table100%2/2
A
A= $self->{"_status"}
Aresult
11
00
1033 61 ▶ croak("Status must be a number between 100-599")
Branch: 1 branch
BranchTrueFalseTotal
unless $code =~ /^\d+$/ and $code >= 100 and $code <= 599 3 58 61
Condition100%6/6
$code =~ /^\d+$/ and $code >= 100 and $code <= 599
!ll&&!rl&&r
2158
$code =~ /^\d+$/ and $code >= 100
!ll&&!rl&&r
1159
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
ABCresult
0XX0
10X0
1100
1111
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
BranchTrueFalseTotal
if exists $self->{"_status"} 3 7 10
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
BranchTrueFalseTotal
unless defined $name 0 67 67
1048 67 ▶ return $self->{_headers}->get($name) if @_ == 2; # getter: last value
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 2 2 65 67
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
BranchTrueFalseTotal
unless defined $name 0 1 1
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
BranchTrueFalseTotal
unless defined $name 0 1 1
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
BranchTrueFalseTotal
if @_ == 1 83 39 122
1077 39 ▶ if (defined $type) { $self->{_headers}->set('content-type', $type) }
Branch: 1 branch
BranchTrueFalseTotal
if (defined $type) { } 38 1 39
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
BranchTrueFalseTotal
exists $self->{'_status'} ? : 2 1 3
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
BranchTrueFalseTotal
exists $self->{'_body'} || exists $self->{'_stream'} || exists $self->{'_file'} ? : 10 2 12
Condition100%6/6
exists $self->{"_body"} or exists $self->{"_stream"} or exists $self->{"_file"}
l!l&&r!l&&!r
912
exists $self->{"_body"} or exists $self->{"_stream"}
l!l&&r!l&&!r
813
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"}
ABCresult
1XX1
01X1
0011
0000
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
BranchTrueFalseTotal
if defined $default_type 82 38 120
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"
l!l
377
MC/DC100%1/1
$charset //= "utf-8"
$charset
Truth table100%2/2
A
A= $charset
Aresult
11
00
1119 80 ▶ return $self unless $self->has_content_type;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->has_content_type 0 80 80
1120 80 my $ct = $self->content_type;
1121 80 ▶ return $self if $ct =~ /charset=/i;
Branch: 1 branch
BranchTrueFalseTotal
if $ct =~ /charset=/i 45 35 80
1122 35 my ($type) = $ct =~ m{^\s*([^;]+)};
1123 35 ▶ $type //= '';
Condition50%1/2
$type //= ""
l!l
350
MC/DC0%0/1
$type //= ""
$type
Truth table50%1/2
A
A= $type
Aresult
11
00
1124 35 $type =~ s/\s+\z//;
1125 35 ▶ return $self if lc($type) eq 'application/json' || $type =~ /\+json\z/i;
Branch: 1 branch
BranchTrueFalseTotal
if lc $type eq "application/json" or $type =~ /\+json\z/i 29 6 35
Condition100%3/3
lc $type eq "application/json" or $type =~ /\+json\z/i
l!l&&r!l&&!r
2816
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
ABresult
1X1
011
000
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
BranchTrueFalseTotal
if (defined $extra_len) 109 26 135
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'
!ll&&!rl&&r
11135
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'
ABresult
0X0
100
111
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
BranchTrueFalseTotal
unless ref $send eq "CODE" 0 130 130
1149  
1150 130 ▶ if ($self->{_stream}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"_stream"}) 15 115 130
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
BranchTrueFalseTotal
unless $writer->is_closed 2 13 15
1159 15 return;
1160 }
1161  
1162 115 ▶ if ($self->{_file}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"_file"}) 6 109 115
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
BranchTrueFalseTotal
if exists $fd->{"offset"} 3 3 6
1175 6 ▶ $body_event->{length} = $fd->{length} if exists $fd->{length};
Branch: 1 branch
BranchTrueFalseTotal
if exists $fd->{"length"} 1 5 6
1176 6 await $send->($body_event);
1177 6 return;
1178 }
1179  
1180 109 ▶ my $body = $self->{_body} // '';
Condition50%1/2
$self->{"_body"} // ""
l!l
1090
MC/DC0%0/1
$self->{"_body"} // ""
$self->{"_body"}
Truth table50%1/2
A
A= $self->{"_body"}
Aresult
11
00
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
BranchTrueFalseTotal
$self->{'scope'} ? : 7 0 7
1202 7 ▶ return 0 unless $conn; # no connection object: server-less / not started
Branch: 1 branch
BranchTrueFalseTotal
unless $conn 0 7 7
1203 7 ▶ Carp::croak("pagi.connection lacks response_started (non-conforming server)")
Branch: 1 branch
BranchTrueFalseTotal
unless $conn->can("response_started") 1 6 7
1204 unless $conn->can('response_started');
1205 6 ▶ return $conn->response_started ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$conn->response_started ? : 3 3 6
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
BranchTrueFalseTotal
ref $proto ? : 135 11 146
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"
l!l
350
MC/DC100%1/1
$charset //= "utf-8"
$charset
Truth table100%2/2
A
A= $charset
Aresult
11
00
1221 53 ▶ return encode($charset, $str // '', FB_CROAK);
Condition50%1/2
$str // ""
l!l
530
MC/DC0%0/1
$str // ""
$str
Truth table50%1/2
A
A= $str
Aresult
11
00
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
BranchTrueFalseTotal
unless $_RESPONSE_OPTS{$k} 1 8 9
1231 }
1232 103 ▶ $self->status($opts{status}) if defined $opts{status};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opts{"status"} 5 98 103
1233 103 ▶ $self->content_type($opts{content_type}) if defined $opts{content_type};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opts{"content_type"} 1 102 103
1234 103 ▶ if (my $h = $opts{headers}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $h = $opts{"headers"}) 2 101 103
1235 2 ▶ croak "headers must be an even-length arrayref [ name => value, ... ]"
Branch: 1 branch
BranchTrueFalseTotal
if @$h % 2 1 1 2
1236 if @$h % 2;
1237 1 my @pairs = @$h;
1238 1 ▶ while (@pairs) {
Branch: 1 branch
BranchTrueFalseTotal
if (@pairs) 1 1 2
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 // ""
l!l
170
MC/DC0%0/1
$body // ""
$body
Truth table50%1/2
A
A= $body
Aresult
11
00
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"
l!l
03
MC/DC0%0/1
$opts{"charset"} // "utf-8"
$opts{"charset"}
Truth table50%1/2
A
A= $opts{"charset"}
Aresult
11
00
1258 3 my $encoded = _enc($body, $charset);
1259 3 ▶ $self->content_type("text/plain; charset=$charset") unless $self->has_content_type;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->has_content_type 2 1 3
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
l!l
94
MC/DC100%1/1
$status // 302
$status
Truth table100%2/2
A
A= $status
Aresult
11
00
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
BranchTrueFalseTotal
if defined $opts{"max_age"} 2 3 5
1315 5 ▶ push @parts, "Expires=$opts{expires}" if defined $opts{expires};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opts{"expires"} 0 5 5
1316 5 ▶ push @parts, "Path=$opts{path}" if defined $opts{path};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opts{"path"} 1 4 5
1317 5 ▶ push @parts, "Domain=$opts{domain}" if defined $opts{domain};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opts{"domain"} 1 4 5
1318 5 ▶ push @parts, "Secure" if $opts{secure};
Branch: 1 branch
BranchTrueFalseTotal
if $opts{"secure"} 1 4 5
1319 5 ▶ push @parts, "HttpOnly" if $opts{httponly};
Branch: 1 branch
BranchTrueFalseTotal
if $opts{"httponly"} 1 4 5
1320 5 ▶ push @parts, "SameSite=$opts{samesite}" if defined $opts{samesite};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opts{"samesite"} 1 4 5
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"} // "*"
l!l
42
MC/DC100%1/1
$opts{"origin"} // "*"
$opts{"origin"}
Truth table100%2/2
A
A= $opts{"origin"}
Aresult
11
00
1340 6 ▶ my $credentials = $opts{credentials} // 0;
Condition100%2/2
$opts{"credentials"} // 0
l!l
24
MC/DC100%1/1
$opts{"credentials"} // 0
$opts{"credentials"}
Truth table100%2/2
A
A= $opts{"credentials"}
Aresult
11
00
1341 6 ▶ my $methods = $opts{methods} // [qw(GET POST PUT DELETE PATCH OPTIONS)];
Condition100%2/2
$opts{"methods"} // ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
l!l
15
MC/DC100%1/1
$opts{"methods"} // ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
$opts{"methods"}
Truth table100%2/2
A
A= $opts{"methods"}
Aresult
11
00
1342 6 ▶ my $headers = $opts{headers} // [qw(Content-Type Authorization X-Requested-With)];
Condition100%2/2
$opts{"headers"} // ["Content-Type", "Authorization", "X-Requested-With"]
l!l
15
MC/DC100%1/1
$opts{"headers"} // ["Content-Type", "Authorization", "X-Requested-With"]
$opts{"headers"}
Truth table100%2/2
A
A= $opts{"headers"}
Aresult
11
00
1343 6 ▶ my $expose = $opts{expose} // [];
Condition100%2/2
$opts{"expose"} // []
l!l
15
MC/DC100%1/1
$opts{"expose"} // []
$opts{"expose"}
Truth table100%2/2
A
A= $opts{"expose"}
Aresult
11
00
1344 6 ▶ my $max_age = $opts{max_age} // 86400;
Condition100%2/2
$opts{"max_age"} // 86400
l!l
15
MC/DC100%1/1
$opts{"max_age"} // 86400
$opts{"max_age"}
Truth table100%2/2
A
A= $opts{"max_age"}
Aresult
11
00
1345 6 ▶ my $preflight = $opts{preflight} // 0;
Condition100%2/2
$opts{"preflight"} // 0
l!l
15
MC/DC100%1/1
$opts{"preflight"} // 0
$opts{"preflight"}
Truth table100%2/2
A
A= $opts{"preflight"}
Aresult
11
00
1346  
1347 # Determine the origin to send back
1348 6 my $allow_origin;
1349 6 ▶ if ($origin eq '*' && $credentials) {
Branch: 1 branch
BranchTrueFalseTotal
if ($origin eq '*' and $credentials) { } 1 5 6
Condition100%3/3
$origin eq "*" and $credentials
!ll&&!rl&&r
321
MC/DC100%2/2
$origin eq "*" and $credentials
$origin eq "*" $credentials
Truth table100%3/3
A and B
A= $origin eq "*"B= $credentials
ABresult
0X0
100
111
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"} // "*"
l!l
10
MC/DC0%0/1
$opts{"request_origin"} // "*"
$opts{"request_origin"}
Truth table50%1/2
A
A= $opts{"request_origin"}
Aresult
11
00
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
BranchTrueFalseTotal
if ($credentials) 2 4 6
1361 2 $self->header('Access-Control-Allow-Credentials', 'true');
1362 }
1363  
1364 6 ▶ if (@$expose) {
Branch: 1 branch
BranchTrueFalseTotal
if (@$expose) 1 5 6
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
BranchTrueFalseTotal
if ($preflight) 1 5 6
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
BranchTrueFalseTotal
unless ref $send eq "CODE" 0 6 6
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
BranchTrueFalseTotal
if $self->{"_writer_started"} 1 5 6
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"
l!l
16
$ext // ""
l!l
25
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 // "")}
Aresult
11
00
Truth table100%2/2
A
A= $ext
Aresult
11
00
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
BranchTrueFalseTotal
unless -f $path 1 10 11
1436 10 ▶ croak("Cannot read file: $path") unless -r $path;
Branch: 1 branch
BranchTrueFalseTotal
unless -r $path 0 10 10
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
l!l
55
MC/DC100%1/1
$opts{"offset"} // 0
$opts{"offset"}
Truth table100%2/2
A
A= $opts{"offset"}
Aresult
11
00
1443 10 my $length = $opts{length};
1444  
1445 # Validate offset
1446 10 ▶ croak("offset must be non-negative") if $offset < 0;
Branch: 1 branch
BranchTrueFalseTotal
if $offset < 0 1 9 10
1447 9 ▶ croak("offset exceeds file size") if $offset > $file_size;
Branch: 1 branch
BranchTrueFalseTotal
if $offset > $file_size 1 8 9
1448  
1449 # Calculate actual length to send
1450 8 my $max_length = $file_size - $offset;
1451 8 ▶ if (defined $length) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $length) { } 3 5 8
1452 3 ▶ croak("length must be non-negative") if $length < 0;
Branch: 1 branch
BranchTrueFalseTotal
if $length < 0 1 2 3
1453 2 ▶ $length = $max_length if $length > $max_length;
Branch: 1 branch
BranchTrueFalseTotal
if $length > $max_length 1 1 2
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
BranchTrueFalseTotal
if ($opts{'inline'}) { } 1 6 7
elsif ($opts{'filename'}) { } 1 5 6
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
BranchTrueFalseTotal
if $disposition 2 5 7
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
BranchTrueFalseTotal
if $offset > 0 3 4 7
1480 7 ▶ $file_desc->{length} = $length if $length < $max_length;
Branch: 1 branch
BranchTrueFalseTotal
if $length < $max_length 1 6 7
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
BranchTrueFalseTotal
if $opts{"on_close"} 1 19 20
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
BranchTrueFalseTotal
if $self->{"closed"} 2 15 17
1509 15 ▶ $self->{bytes_written} += length($chunk // '');
Condition50%1/2
$chunk // ""
l!l
150
MC/DC0%0/1
$chunk // ""
$chunk
Truth table50%1/2
A
A= $chunk
Aresult
11
00
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
BranchTrueFalseTotal
if $self->{"closed"} 0 17 17
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
BranchTrueFalseTotal
if (builtin::blessed($r) and $r->isa("Future")) 2 12 14
Condition100%3/3
builtin::blessed($r) and $r->isa("Future")
!ll&&!rl&&r
1112
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")
ABresult
0X0
100
111
1530 2 await $r;
1531 }
1532 };
1533 15 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 2 13 15
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;
« blib/lib/PAGI/Middleware/Rewrite.pm ↑ Summary lib/PAGI/App/Throttle.pm »