blib/lib/PAGI/App/File.pm

filter: Statementstmt 37.1% 39 / 105 Branchbran 0.0% 0 / 36 Conditioncond 13.0% 6 / 46 MC/DCmcdc 0.0% 0 / 28 Subroutinesub 90.9% 10 / 11 Podpod 0.0% 0 / 2 totaltotal 24.1% 55 / 228 CC 40 SCAR 65.2
CC
40
Cov
24%
__ANON__
1056.0
new
7.9
_get_header
5.0
CRAP 677.4
↑ Summary lib/PAGI/App/WebSocket/Chat.pm »
1 package PAGI::App::File;
2 3 $PAGI::App::File::VERSION = '0.002002';
3 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 3 ▶use Future::AsyncAwait;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 3 ▶use Digest::MD5 qw(md5_hex);
Subroutine BEGIN: called CC=1 SCAR=0.0
7 3 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 3 ▶use Cwd (); # For realpath
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 =head1 NAME
11  
12 PAGI::App::File - Serve static files
13  
14 =head1 SYNOPSIS
15  
16 use PAGI::App::File;
17  
18 my $app = PAGI::App::File->new(
19 root => '/var/www/static',
20 )->to_app;
21  
22 =head1 DESCRIPTION
23  
24 PAGI::App::File serves static files from a configured root directory.
25  
26 =head2 Features
27  
28 =over 4
29  
30 =item * Efficient streaming (no memory bloat for large files)
31  
32 =item * ETag caching with If-None-Match support (304 Not Modified)
33  
34 =item * Range requests (HTTP 206 Partial Content)
35  
36 =item * Automatic MIME type detection for common file types
37  
38 =item * Index file resolution (index.html, index.htm)
39  
40 =back
41  
42 =head2 Security
43  
44 This module implements multiple layers of path traversal protection:
45  
46 =over 4
47  
48 =item * Null byte injection blocking
49  
50 =item * Double-dot and triple-dot component blocking
51  
52 =item * Backslash normalization (Windows path separator)
53  
54 =item * Hidden file blocking (dotfiles like .htaccess, .env)
55  
56 =item * Symlink escape detection via realpath verification
57  
58 =back
59  
60 =cut
61  
62 3 our %MIME_TYPES = (
63 html => 'text/html',
64 htm => 'text/html',
65 css => 'text/css',
66 js => 'application/javascript',
67 json => 'application/json',
68 xml => 'application/xml',
69 txt => 'text/plain',
70 pl => 'text/plain',
71 md => 'text/plain',
72 png => 'image/png',
73 jpg => 'image/jpeg',
74 jpeg => 'image/jpeg',
75 gif => 'image/gif',
76 svg => 'image/svg+xml',
77 ico => 'image/x-icon',
78 webp => 'image/webp',
79 woff => 'font/woff',
80 woff2=> 'font/woff2',
81 ttf => 'font/ttf',
82 pdf => 'application/pdf',
83 zip => 'application/zip',
84 mp3 => 'audio/mpeg',
85 mp4 => 'video/mp4',
86 webm => 'video/webm',
87 );
88  
89 4 ▶sub new {
Subroutine new: called CC=6 SCAR=20.7
Pod undocumented
90 4 my ($class, %args) = @_;
91  
92 4 ▶ my $root = $args{root} // '.';
Condition50%1/2
$args{"root"} // "."
l!l
40
MC/DC0%0/1
$args{"root"} // "."
$args{"root"}
Truth table50%1/2
A
A= $args{"root"}
Aresult
11
00
93 # Resolve root to absolute path for security comparisons
94 4 ▶ my $abs_root = Cwd::realpath($root) // $root;
Condition33%1/3
Cwd::realpath($root) // $root
l!l&&r!l&&!r
400
MC/DC0%0/2
Cwd::realpath($root) // $root
Cwd::realpath($root) $root
Truth table33%1/3
A // B
A= Cwd::realpath($root)B= $root
ABresult
1X1
011
000
95  
96 my $self = bless {
97 root => $abs_root,
98 default_type => $args{default_type} // 'application/octet-stream',
99 index => $args{index} // ['index.html', 'index.htm'],
100 4 ▶ handle_ranges => $args{handle_ranges} // 1,
Condition50%3/6
$args{"default_type"} // "application/octet-stream"
l!l
04
$args{"index"} // ["index.html", "index.htm"]
l!l
04
$args{"handle_ranges"} // 1
l!l
04
MC/DC0%0/1
$args{"default_type"} // "application/octet-stream"
$args{"default_type"}
MC/DC0%0/1
$args{"index"} // ["index.html", "index.htm"]
$args{"index"}
MC/DC0%0/1
$args{"handle_ranges"} // 1
$args{"handle_ranges"}
Truth table50%1/2
A
A= $args{"default_type"}
Aresult
11
00
Truth table50%1/2
A
A= $args{"index"}
Aresult
11
00
Truth table50%1/2
A
A= $args{"handle_ranges"}
Aresult
11
00
101 }, $class;
102 4 return $self;
103 }
104  
105 4 ▶sub to_app {
Subroutine to_app: called CC=1 SCAR=6.6
Pod undocumented
106 4 my ($self) = @_;
107  
108 4 my $root = $self->{root};
109  
110 0 ▶ return async sub {
Subroutine __ANON__: not called CC=32 SCAR=69.6
111 0 my ($scope, $receive, $send) = @_;
112 0 ▶ die "Unsupported scope type: $scope->{type}" if $scope->{type} ne 'http';
Branch: 1 branch
BranchTrueFalseTotal
if $scope->{"type"} ne "http" 0 0 0
113  
114 0 ▶ my $method = uc($scope->{method} // '');
Condition0%0/2
$scope->{"method"} // ""
l!l
00
MC/DC0%0/1
$scope->{"method"} // ""
$scope->{"method"}
Truth table0%0/2
A
A= $scope->{"method"}
Aresult
11
00
115 0 ▶ unless ($method eq 'GET' || $method eq 'HEAD') {
Branch: 1 branch
BranchTrueFalseTotal
unless ($method eq "GET" or $method eq "HEAD") 0 0 0
Condition0%0/3
$method eq "GET" or $method eq "HEAD"
l!l&&r!l&&!r
000
MC/DC0%0/2
$method eq "GET" or $method eq "HEAD"
$method eq "GET" $method eq "HEAD"
Truth table0%0/3
A or B
A= $method eq "GET"B= $method eq "HEAD"
ABresult
1X1
011
000
116 0 await $self->_send_error($send, 405, 'Method Not Allowed');
117 0 return;
118 }
119  
120 0 ▶ my $path = $scope->{path} // '/';
Condition0%0/2
$scope->{"path"} // "/"
l!l
00
MC/DC0%0/1
$scope->{"path"} // "/"
$scope->{"path"}
Truth table0%0/2
A
A= $scope->{"path"}
Aresult
11
00
121  
122 # Security: Block null byte injection
123 0 ▶ if ($path =~ /\0/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($path =~ /\0/) 0 0 0
124 0 await $self->_send_error($send, 400, 'Bad Request');
125 0 return;
126 }
127  
128 # Security: Normalize backslashes to forward slashes
129 0 $path =~ s{\\}{/}g;
130  
131 # Security: Split path and validate each component
132 # Use -1 limit to preserve trailing empty strings
133 0 my @components = split m{/}, $path, -1;
134 0 for my $component (@components) {
135 # Block components with 2+ dots (.. , ..., ....)
136 0 ▶ if ($component =~ /^\.{2,}$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($component =~ /^\.{2,}$/) 0 0 0
137 0 await $self->_send_error($send, 403, 'Forbidden');
138 0 return;
139 }
140 # Block hidden files (dotfiles) - components starting with .
141 0 ▶ if ($component =~ /^\./ && $component ne '') {
Branch: 1 branch
BranchTrueFalseTotal
if ($component =~ /^\./ and $component ne "") 0 0 0
Condition0%0/3
$component =~ /^\./ and $component ne ""
!ll&&!rl&&r
000
MC/DC0%0/2
$component =~ /^\./ and $component ne ""
$component =~ /^\./ $component ne ""
Truth table0%0/3
A and B
A= $component =~ /^\./B= $component ne ""
ABresult
0X0
100
111
142 0 await $self->_send_error($send, 403, 'Forbidden');
143 0 return;
144 }
145 }
146  
147 # Build file path using File::Spec for portability
148 0 $path =~ s{^/+}{};
149 0 my $file_path = File::Spec->catfile($root, $path);
150  
151 # Check for index files if directory
152 0 ▶ if (-d $file_path) {
Branch: 1 branch
BranchTrueFalseTotal
if (-d $file_path) 0 0 0
153 0 for my $index (@{$self->{index}}) {
154 0 my $index_path = File::Spec->catfile($file_path, $index);
155 0 ▶ if (-f $index_path) {
Branch: 1 branch
BranchTrueFalseTotal
if (-f $index_path) 0 0 0
156 0 $file_path = $index_path;
157 0 last;
158 }
159 }
160 }
161  
162 0 ▶ unless (-f $file_path && -r $file_path) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-f $file_path and -r $file_path) 0 0 0
Condition0%0/3
-f $file_path and -r $file_path
!ll&&!rl&&r
000
MC/DC0%0/2
-f $file_path and -r $file_path
-f $file_path -r $file_path
Truth table0%0/3
A and B
A= -f $file_pathB= -r $file_path
ABresult
0X0
100
111
163 0 await $self->_send_error($send, 404, 'Not Found');
164 0 return;
165 }
166  
167 # Security: Verify resolved path stays within root (prevents symlink escape)
168 0 my $real_path = Cwd::realpath($file_path);
169 0 ▶ unless ($real_path && index($real_path, $root) == 0) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($real_path and index($real_path, $root) == 0) 0 0 0
Condition0%0/3
$real_path and index($real_path, $root) == 0
!ll&&!rl&&r
000
MC/DC0%0/2
$real_path and index($real_path, $root) == 0
$real_path index($real_path, $root) == 0
Truth table0%0/3
A and B
A= $real_pathB= index($real_path, $root) == 0
ABresult
0X0
100
111
170 0 await $self->_send_error($send, 403, 'Forbidden');
171 0 return;
172 }
173  
174 0 my @stat = stat($file_path);
175 0 my $size = $stat[7];
176 0 my $mtime = $stat[9];
177 0 my $etag = '"' . md5_hex("$mtime-$size") . '"';
178  
179 # Check If-None-Match
180 0 my $if_none_match = $self->_get_header($scope, 'if-none-match');
181 0 ▶ if ($if_none_match && $if_none_match eq $etag) {
Branch: 1 branch
BranchTrueFalseTotal
if ($if_none_match and $if_none_match eq $etag) 0 0 0
Condition0%0/3
$if_none_match and $if_none_match eq $etag
!ll&&!rl&&r
000
MC/DC0%0/2
$if_none_match and $if_none_match eq $etag
$if_none_match $if_none_match eq $etag
Truth table0%0/3
A and B
A= $if_none_matchB= $if_none_match eq $etag
ABresult
0X0
100
111
182 0 await $send->({
183 type => 'http.response.start',
184 status => 304,
185 headers => [['etag', $etag]],
186 });
187 0 await $send->({ type => 'http.response.body', body => '', more => 0 });
188 0 return;
189 }
190  
191 # Determine MIME type
192 0 my ($ext) = $file_path =~ /\.([^.]+)$/;
193 0 ▶ my $content_type = $MIME_TYPES{lc($ext // '')} // $self->{default_type};
Condition0%0/5
$PAGI::App::File::MIME_TYPES{lc($ext // "")} // $self->{"default_type"}
l!l&&r!l&&!r
000
$ext // ""
l!l
00
MC/DC0%0/2
$PAGI::App::File::MIME_TYPES{lc($ext // "")} // $self->{"default_type"}
$PAGI::App::File::MIME_TYPES{lc($ext // "")} $self->{"default_type"}
MC/DC0%0/1
$ext // ""
$ext
Truth table0%0/3
A // B
A= $PAGI::App::File::MIME_TYPES{lc($ext // "")}B= $self->{"default_type"}
ABresult
1X1
011
000
Truth table0%0/2
A
A= $ext
Aresult
11
00
194  
195 # Check for Range request (only if handle_ranges is enabled)
196 0 ▶ my $range = $self->{handle_ranges} ? $self->_get_header($scope, 'range') : undef;
Branch: 1 branch
BranchTrueFalseTotal
$self->{'handle_ranges'} ? : 0 0 0
197 0 ▶ if ($range && $range =~ /bytes=(\d*)-(\d*)/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($range and $range =~ /bytes=(\d*)-(\d*)/) 0 0 0
Condition0%0/3
$range and $range =~ /bytes=(\d*)-(\d*)/
!ll&&!rl&&r
000
MC/DC0%0/2
$range and $range =~ /bytes=(\d*)-(\d*)/
$range $range =~ /bytes=(\d*)-(\d*)/
Truth table0%0/3
A and B
A= $rangeB= $range =~ /bytes=(\d*)-(\d*)/
ABresult
0X0
100
111
198 0 my ($start, $end) = ($1, $2);
199 0 ▶ $start = 0 if $start eq '';
Branch: 1 branch
BranchTrueFalseTotal
if $start eq "" 0 0 0
200 0 ▶ $end = $size - 1 if $end eq '' || $end >= $size;
Branch: 1 branch
BranchTrueFalseTotal
if $end eq "" or $end >= $size 0 0 0
Condition0%0/3
$end eq "" or $end >= $size
l!l&&r!l&&!r
000
MC/DC0%0/2
$end eq "" or $end >= $size
$end eq "" $end >= $size
Truth table0%0/3
A or B
A= $end eq ""B= $end >= $size
ABresult
1X1
011
000
201  
202 0 ▶ if ($start > $end || $start >= $size) {
Branch: 1 branch
BranchTrueFalseTotal
if ($start > $end or $start >= $size) 0 0 0
Condition0%0/3
$start > $end or $start >= $size
l!l&&r!l&&!r
000
MC/DC0%0/2
$start > $end or $start >= $size
$start > $end $start >= $size
Truth table0%0/3
A or B
A= $start > $endB= $start >= $size
ABresult
1X1
011
000
203 0 await $self->_send_error($send, 416, 'Range Not Satisfiable');
204 0 return;
205 }
206  
207 0 my $length = $end - $start + 1;
208  
209 0 await $send->({
210 type => 'http.response.start',
211 status => 206,
212 headers => [
213 ['content-type', $content_type],
214 ['content-length', $length],
215 ['content-range', "bytes $start-$end/$size"],
216 ['accept-ranges', 'bytes'],
217 ['etag', $etag],
218 ],
219 });
220  
221 # Use file response with offset/length for efficient streaming
222 0 ▶ if ($method eq 'HEAD') {
Branch: 1 branch
BranchTrueFalseTotal
if ($method eq 'HEAD') { } 0 0 0
223 0 await $send->({ type => 'http.response.body', body => '', more => 0 });
224 }
225 else {
226 0 await $send->({
227 type => 'http.response.body',
228 file => $file_path,
229 offset => $start,
230 length => $length,
231 });
232 }
233 0 return;
234 }
235  
236 # Full file response
237 await $send->({
238 type => 'http.response.start',
239 status => 200,
240 headers => [
241 ['content-type', $content_type],
242 ['content-length', $size],
243 ['accept-ranges', 'bytes'],
244 ['etag', $etag],
245 ],
246 0 });
247  
248 # Use file response for efficient streaming (sendfile or worker pool)
249 0 ▶ if ($method eq 'HEAD') {
Branch: 1 branch
BranchTrueFalseTotal
if ($method eq 'HEAD') { } 0 0 0
250 0 await $send->({ type => 'http.response.body', body => '', more => 0 });
251 }
252 else {
253 0 await $send->({
254 type => 'http.response.body',
255 file => $file_path,
256 });
257 }
258 4 };
259 }
260  
261 1 ▶sub _get_header {
Subroutine _get_header: called CC=4 SCAR=16.1
262 1 my ($self, $scope, $name) = @_;
263  
264 1 $name = lc($name);
265 1 ▶ for my $h (@{$scope->{headers} // []}) {
Condition50%1/2
$scope->{"headers"} // []
l!l
10
MC/DC0%0/1
$scope->{"headers"} // []
$scope->{"headers"}
Truth table50%1/2
A
A= $scope->{"headers"}
Aresult
11
00
266 0 ▶ return $h->[1] if lc($h->[0]) eq $name;
Branch: 1 branch
BranchTrueFalseTotal
if lc $h->[0] eq $name 0 0 0
267 }
268 1 return;
269 }
270  
271 2 ▶async sub _send_error {
Subroutine _send_error: called CC=1 SCAR=0.0
272 2 my ($self, $send, $status, $message) = @_;
273  
274 2 await $send->({
275 type => 'http.response.start',
276 status => $status,
277 headers => [['content-type', 'text/plain'], ['content-length', length($message)]],
278 });
279 2 await $send->({ type => 'http.response.body', body => $message, more => 0 });
280 3 }
281  
282 3 1;
283  
284 __END__
↑ Summary lib/PAGI/App/WebSocket/Chat.pm »