blib/lib/PAGI/Request/BodyStream.pm

filter: Statementstmt 91.5% 98 / 107 Branchbran 65.0% 39 / 60 Conditioncond 59.2% 16 / 27 MC/DCmcdc 31.2% 5 / 16 Subroutinesub 92.3% 12 / 13 Podpod 100% 7 / 7 totaltotal 76.9% 177 / 230 CC 42 SCAR 23.6
CC
42
Cov
79%
next_chunk
17.1
_decode_chunk
12.2
stream_to_file
11.8
CRAP 10.6
« lib/PAGI/Middleware/ContentLength.pm ↑ Summary blib/lib/PAGI/Test/Client.pm »
1 package PAGI::Request::BodyStream;
2 23 $PAGI::Request::BodyStream::VERSION = '0.002002';
3 23 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 23 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 23 ▶use Future::AsyncAwait;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 23 ▶use Encode qw(decode FB_CROAK FB_DEFAULT LEAVE_SRC);
Subroutine BEGIN: called CC=1 SCAR=0.0
8 23 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10  
11 =head1 NAME
12  
13 PAGI::Request::BodyStream - Streaming body consumption for PAGI requests
14  
15 =head1 SYNOPSIS
16  
17 use PAGI::Request::BodyStream;
18 use Future::AsyncAwait;
19  
20 # Basic streaming
21 my $stream = PAGI::Request::BodyStream->new(receive => $receive);
22  
23 while (!$stream->is_done) {
24 my $chunk = await $stream->next_chunk;
25 last unless defined $chunk;
26 print "Got chunk: ", length($chunk), " bytes\n";
27 }
28  
29 # With size limit
30 my $stream = PAGI::Request::BodyStream->new(
31 receive => $receive,
32 max_bytes => 1024 * 1024, # 1MB limit
33 );
34  
35 # With UTF-8 decoding
36 my $stream = PAGI::Request::BodyStream->new(
37 receive => $receive,
38 decode => 'UTF-8',
39 );
40  
41 # Stream to file
42 await $stream->stream_to_file('/tmp/upload.dat');
43  
44 # Stream to custom sink
45 await $stream->stream_to(async sub ($chunk) {
46 # Process chunk
47 print STDERR "Processing: ", length($chunk), " bytes\n";
48 });
49  
50 =head1 DESCRIPTION
51  
52 PAGI::Request::BodyStream provides streaming body consumption for large request
53 bodies. This is useful when you need to process request data incrementally
54 without loading the entire body into memory.
55  
56 The stream is pull-based: you call C<next_chunk()> to receive the next chunk
57 of data. The stream handles:
58  
59 =over 4
60  
61 =item * Size limits with customizable error messages
62  
63 =item * UTF-8 decoding with proper handling of incomplete sequences at chunk boundaries
64  
65 =item * Client disconnect detection
66  
67 =item * Convenient file streaming with C<stream_to_file()>
68  
69 =back
70  
71 B<Important>: Streaming is mutually exclusive with buffered body methods like
72 C<body()>, C<json()>, C<form()> in L<PAGI::Request>. Once you start streaming,
73 you cannot use those methods.
74  
75 =head1 CONSTRUCTOR
76  
77 =head2 new
78  
79 my $stream = PAGI::Request::BodyStream->new(
80 receive => $receive, # Required: PAGI receive callback
81 max_bytes => 10485760, # Optional: max body size
82 decode => 'UTF-8', # Optional: decode to UTF-8
83 strict => 1, # Optional: strict UTF-8 (croak on invalid)
84 limit_name => 'body_size', # Optional: name for limit error message
85 );
86  
87 Creates a new body stream.
88  
89 =over 4
90  
91 =item * C<receive> - Required. The PAGI receive callback.
92  
93 =item * C<max_bytes> - Optional. Maximum bytes to read. Throws error if exceeded.
94  
95 =item * C<decode> - Optional. Encoding to decode chunks to (typically 'UTF-8').
96  
97 =item * C<strict> - Optional. If true, throw on invalid UTF-8. If false (default),
98 use replacement characters.
99  
100 =item * C<limit_name> - Optional. Name to use in error message when max_bytes
101 is exceeded (default: 'max_bytes').
102  
103 =back
104  
105 =cut
106  
107 15 ▶sub new {
Subroutine new: called CC=4 SCAR=13.9
Pod documented
108 15 my ($class, %args) = @_;
109 15 ▶ my $receive = $args{receive} // croak("receive is required");
Condition100%2/2
$args{"receive"} // croak("receive is required")
l!l
141
MC/DC100%1/1
$args{"receive"} // croak("receive is required")
$args{"receive"}
Truth table100%2/2
A
A= $args{"receive"}
Aresult
11
00
110  
111 my $self = bless {
112 receive => $receive,
113 max_bytes => $args{max_bytes},
114 decode => $args{decode},
115 strict => $args{strict} // 0,
116 14 ▶ limit_name => $args{limit_name} // 'max_bytes',
Condition100%4/4
$args{"strict"} // 0
l!l
113
$args{"limit_name"} // "max_bytes"
l!l
113
MC/DC100%1/1
$args{"strict"} // 0
$args{"strict"}
MC/DC100%1/1
$args{"limit_name"} // "max_bytes"
$args{"limit_name"}
Truth table100%2/2
A
A= $args{"strict"}
Aresult
11
00
Truth table100%2/2
A
A= $args{"limit_name"}
Aresult
11
00
117 _bytes_read => 0,
118 _done => 0,
119 _error => undef,
120 _buffer => '', # For incomplete UTF-8 sequences
121 }, $class;
122  
123 14 return $self;
124 }
125  
126 =head1 METHODS
127  
128 =head2 next_chunk
129  
130 my $chunk = await $stream->next_chunk;
131  
132 Returns a Future that resolves to the next chunk of data, or undef when the
133 stream is exhausted or client disconnects.
134  
135 If C<decode> was specified in the constructor, chunks are decoded to the
136 specified encoding. UTF-8 decoding properly handles incomplete multi-byte
137 sequences at chunk boundaries.
138  
139 Throws an exception if C<max_bytes> is exceeded.
140  
141 =cut
142  
143 20 ▶async sub next_chunk {
Subroutine next_chunk: called CC=14 SCAR=28.4
Pod documented
144 20 my ($self) = @_;
145 20 ▶ return undef if $self->{_done};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"_done"} 0 20 20
146 20 ▶ return undef if $self->{_error};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"_error"} 0 20 20
147  
148 20 my $message = await $self->{receive}->();
149  
150 # Handle disconnect
151 20 ▶ if (!$message || $message->{type} eq 'http.disconnect') {
Branch: 1 branch
BranchTrueFalseTotal
if (not $message or $message->{"type"} eq "http.disconnect") 1 19 20
Condition66%2/3
not $message or $message->{"type"} eq "http.disconnect"
l!l&&r!l&&!r
0119
MC/DC50%1/2
not $message or $message->{"type"} eq "http.disconnect"
not $message $message->{"type"} eq "http.disconnect"
Truth table66%2/3
not(A) or B
A= not $messageB= $message->{"type"} eq "http.disconnect"
ABresult
1X1
011
000
152 1 $self->{_done} = 1;
153 # Flush any remaining buffered data from incomplete UTF-8 sequences
154 1 ▶ if ($self->{decode} && length($self->{_buffer})) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"decode"} and length $self->{"_buffer"}) 0 1 1
Condition33%1/3
$self->{"decode"} and length $self->{"_buffer"}
!ll&&!rl&&r
100
MC/DC0%0/2
$self->{"decode"} and length $self->{"_buffer"}
$self->{"decode"} length $self->{"_buffer"}
Truth table33%1/3
A and B
A= $self->{"decode"}B= length $self->{"_buffer"}
ABresult
0X0
100
111
155 0 my $final = $self->_decode_chunk('', 1); # flush=1
156 0 ▶ return $final if length($final);
Branch: 1 branch
BranchTrueFalseTotal
if length $final 0 0 0
157 }
158 1 return undef;
159 }
160  
161 # Extract body chunk
162 19 ▶ my $chunk = $message->{body} // '';
Condition50%1/2
$message->{"body"} // ""
l!l
190
MC/DC0%0/1
$message->{"body"} // ""
$message->{"body"}
Truth table50%1/2
A
A= $message->{"body"}
Aresult
11
00
163 19 ▶ my $more = $message->{more} // 0;
Condition50%1/2
$message->{"more"} // 0
l!l
190
MC/DC0%0/1
$message->{"more"} // 0
$message->{"more"}
Truth table50%1/2
A
A= $message->{"more"}
Aresult
11
00
164  
165 # Check size limit before processing
166 19 ▶ if (defined $self->{max_bytes}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{"max_bytes"}) 2 17 19
167 2 my $new_total = $self->{_bytes_read} + length($chunk);
168 2 ▶ if ($new_total > $self->{max_bytes}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($new_total > $self->{"max_bytes"}) 2 0 2
169 2 $self->{_error} = "Request body $self->{limit_name} exceeded";
170 2 $self->{_done} = 1;
171 2 croak($self->{_error});
172 }
173 }
174  
175 17 $self->{_bytes_read} += length($chunk);
176  
177 # Mark done if no more chunks
178 17 ▶ $self->{_done} = 1 unless $more;
Branch: 1 branch
BranchTrueFalseTotal
unless $more 8 9 17
179  
180 # Decode if requested
181 17 ▶ if ($self->{decode}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"decode"}) 4 13 17
182 4 $chunk = $self->_decode_chunk($chunk, !$more);
183 }
184  
185 16 return $chunk;
186 23 }
187  
188 =head2 bytes_read
189  
190 my $total = $stream->bytes_read;
191  
192 Returns the total number of raw bytes read so far (before any decoding).
193  
194 =cut
195  
196 5 ▶sub bytes_read {
Subroutine bytes_read: called CC=1 SCAR=0.0
Pod documented
197 5 my ($self) = @_;
198 5 return $self->{_bytes_read};
199 }
200  
201 =head2 is_done
202  
203 if ($stream->is_done) { ... }
204  
205 Returns true if the stream has been exhausted (no more chunks available).
206  
207 =cut
208  
209 13 ▶sub is_done {
Subroutine is_done: called CC=1 SCAR=0.0
Pod documented
210 13 my ($self) = @_;
211 13 return $self->{_done};
212 }
213  
214 =head2 error
215  
216 my $error = $stream->error;
217  
218 Returns any error that occurred during streaming, or undef.
219  
220 =cut
221  
222 0 ▶sub error {
Subroutine error: not called CC=1 SCAR=6.9
Pod documented
223 0 my ($self) = @_;
224 0 return $self->{_error};
225 }
226  
227 =head2 stream_to_file
228  
229 await $stream->stream_to_file($path);
230  
231 Streams the entire request body to a file. Returns a Future that resolves
232 to the number of bytes written.
233  
234 This is efficient for large uploads as it doesn't load the entire body into
235 memory - chunks are written incrementally as they arrive from the network.
236  
237 B<Note:> File writes are B<blocking> (synchronous I/O). Since chunks are
238 typically small (e.g., 64KB), each write completes quickly. The method
239 remains async overall because it awaits network chunks between writes.
240  
241 B<Note:> Cannot be used with the C<decode> option as that would corrupt binary
242 data. Use C<stream_to()> with a custom handler if you need decoded chunks
243 written to a file.
244  
245 For fully non-blocking file I/O, use C<stream_to()> with your preferred
246 async file library:
247  
248 # Non-blocking alternative (bring your own async file library)
249 await $stream->stream_to(async sub {
250 my ($chunk) = @_;
251 await $my_async_file_writer->write($chunk);
252 });
253  
254 =cut
255  
256 2 ▶async sub stream_to_file {
Subroutine stream_to_file: called CC=11 SCAR=24.7
Pod documented
257 2 my ($self, $path) = @_;
258 2 ▶ croak("path is required") unless defined $path;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $path 0 2 2
259 croak("stream_to_file() cannot be used with decode option - use stream_to() instead")
260 2 ▶ if $self->{decode};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"decode"} 1 1 2
261  
262 1 my $bytes_written = 0;
263 1 my $fh;
264  
265 1 ▶ while (!$self->is_done) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->is_done) 2 1 3
266 2 my $chunk = await $self->next_chunk;
267 2 ▶ last unless defined $chunk;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $chunk 0 2 2
268 2 ▶ next unless length $chunk;
Branch: 1 branch
BranchTrueFalseTotal
unless length $chunk 0 2 2
269  
270 # Open file on first chunk (truncate mode)
271 2 ▶ unless ($fh) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($fh) 1 1 2
272 1 ▶ open $fh, '>:raw', $path
Branch: 1 branch
BranchTrueFalseTotal
open $fh, ">:raw", $path or croak("Cannot open $path for writing: $!") 1 0 1
273 or croak("Cannot open $path for writing: $!");
274 }
275  
276 # Blocking write - typically fast for small chunks
277 2 ▶ print $fh $chunk
Branch: 1 branch
BranchTrueFalseTotal
print $fh $chunk or croak("Cannot write to ${path}: $!") 2 0 2
278 or croak("Cannot write to $path: $!");
279  
280 2 $bytes_written += length($chunk);
281 }
282  
283 # Close file if we opened it
284 1 ▶ if ($fh) {
Branch: 1 branch
BranchTrueFalseTotal
if ($fh) 1 0 1
285 1 ▶ close $fh
Branch: 1 branch
BranchTrueFalseTotal
close $fh or croak("Cannot close ${path}: $!") 1 0 1
286 or croak("Cannot close $path: $!");
287 }
288  
289 1 return $bytes_written;
290 23 }
291  
292 =head2 stream_to
293  
294 await $stream->stream_to(async sub ($chunk) {
295 # Process chunk
296 });
297  
298 Streams the entire request body to a custom sink callback. The callback
299 receives each chunk and can be async (return a Future).
300  
301 Returns a Future that resolves to the number of bytes processed.
302  
303 =cut
304  
305 1 ▶async sub stream_to {
Subroutine stream_to: called CC=7 SCAR=20.7
Pod documented
306 1 my ($self, $callback) = @_;
307 1 ▶ croak("callback is required") unless $callback;
Branch: 1 branch
BranchTrueFalseTotal
unless $callback 0 1 1
308  
309 1 my $bytes_processed = 0;
310  
311 1 ▶ while (!$self->is_done) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->is_done) 2 1 3
312 2 my $chunk = await $self->next_chunk;
313 2 ▶ last unless defined $chunk;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $chunk 0 2 2
314 2 ▶ next unless length $chunk;
Branch: 1 branch
BranchTrueFalseTotal
unless length $chunk 0 2 2
315  
316 # Call callback - it may be async
317 2 my $result = $callback->($chunk);
318 2 ▶ if (ref($result) && $result->can('get')) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $result and $result->can("get")) 0 2 2
Condition33%1/3
ref $result and $result->can("get")
!ll&&!rl&&r
200
MC/DC0%0/2
ref $result and $result->can("get")
ref $result $result->can("get")
Truth table33%1/3
A and B
A= ref $resultB= $result->can("get")
ABresult
0X0
100
111
319 0 await $result;
320 }
321  
322 2 $bytes_processed += length($chunk);
323 }
324  
325 1 return $bytes_processed;
326 23 }
327  
328 =head1 INTERNAL METHODS
329  
330 =head2 _decode_chunk
331  
332 Internal method to decode a chunk with proper handling of incomplete UTF-8
333 sequences at boundaries.
334  
335 =cut
336  
337 4 ▶sub _decode_chunk {
Subroutine _decode_chunk: called CC=10 SCAR=25.0
338 4 my ($self, $chunk, $flush) = @_;
339 4 ▶ $flush //= 0;
Condition50%1/2
$flush //= 0
l!l
40
MC/DC0%0/1
$flush //= 0
$flush
Truth table50%1/2
A
A= $flush
Aresult
11
00
340 4 my $encoding = $self->{decode};
341 4 ▶ return $chunk unless $encoding;
Branch: 1 branch
BranchTrueFalseTotal
unless $encoding 0 4 4
342  
343 # Combine with buffered incomplete sequence from previous chunk
344 4 my $data = $self->{_buffer} . $chunk;
345  
346 # Use Encode::FB_QUIET for incremental decoding - the standard approach
347 # recommended by Encode documentation for handling partial multi-byte sequences
348 4 my $decoded = eval {
349 4 ▶ if ($flush || !length($data)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($flush or not length $data) { } 3 1 4
Condition66%2/3
$flush or not length $data
l!l&&r!l&&!r
301
MC/DC50%1/2
$flush or not length $data
$flush not length $data
Truth table66%2/3
A or not(B)
A= $flushB= not length $data
ABresult
1X1
011
000
350 # Final chunk or empty - decode everything
351 3 $self->{_buffer} = '';
352 3 ▶ my $flag = $self->{strict} ? (Encode::FB_CROAK | Encode::LEAVE_SRC) : (Encode::FB_DEFAULT | Encode::LEAVE_SRC);
Branch: 1 branch
BranchTrueFalseTotal
$self->{'strict'} ? : 1 2 3
353 3 return decode($encoding, $data, $flag);
354 } else {
355 # Incremental decoding with FB_QUIET
356 # FB_QUIET modifies $data in place, removing the decoded portion
357 # and leaving incomplete sequences in $data for next time
358 1 my $result = decode($encoding, $data, Encode::FB_QUIET);
359  
360 # Whatever remains in $data is incomplete - buffer it
361 1 $self->{_buffer} = $data;
362  
363 # In strict mode, check if buffered data is invalid (not just incomplete)
364 1 ▶ if ($self->{strict} && length($self->{_buffer}) > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"strict"} and length $self->{"_buffer"} > 0) 0 1 1
Condition33%1/3
$self->{"strict"} and length $self->{"_buffer"} > 0
!ll&&!rl&&r
100
MC/DC0%0/2
$self->{"strict"} and length $self->{"_buffer"} > 0
$self->{"strict"} length $self->{"_buffer"} > 0
Truth table33%1/3
A and B
A= $self->{"strict"}B= length $self->{"_buffer"} > 0
ABresult
0X0
100
111
365 0 my $test = $self->{_buffer};
366 0 eval { decode($encoding, $test, Encode::FB_CROAK | Encode::LEAVE_SRC); };
367 0 ▶ die $@ if $@; # Propagate if invalid UTF-8
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 0 0
368 }
369  
370 1 return $result;
371 }
372 };
373  
374 4 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 1 3 4
375 1 $self->{_error} = "Failed to decode chunk: $@";
376 1 $self->{_done} = 1;
377 1 croak($self->{_error});
378 }
379  
380 3 return $decoded;
381 }
382  
383 23 1;
384  
385 __END__
« lib/PAGI/Middleware/ContentLength.pm ↑ Summary blib/lib/PAGI/Test/Client.pm »