blib/lib/PAGI/Middleware/Lint.pm

filter: Statementstmt 75.2% 82 / 109 Branchbran 45.4% 30 / 66 Conditioncond 27.2% 6 / 22 MC/DCmcdc 7.6% 1 / 13 Subroutinesub 100% 13 / 13 Podpod 100% 1 / 1 totaltotal 59.3% 133 / 224 CC 45 SCAR 29.1
CC
45
Cov
60%
_lint_scope
32.1
_lint_response_start
21.8
__ANON__
21.1
CRAP 18.3
« lib/PAGI/App/SSE/Pubsub.pm ↑ Summary lib/PAGI/Middleware/Static.pm »
1 package PAGI::Middleware::Lint;
2 1 $PAGI::Middleware::Lint::VERSION = '0.002002';
3 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 1 ▶use parent 'PAGI::Middleware';
Subroutine BEGIN: called CC=1 SCAR=0.0
6 1 ▶use Future::AsyncAwait;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 =head1 NAME
9  
10 PAGI::Middleware::Lint - Validate PAGI application compliance
11  
12 =head1 SYNOPSIS
13  
14 use PAGI::Middleware::Builder;
15  
16 my $app = builder {
17 enable 'Lint',
18 strict => 1,
19 on_warning => sub {
20 my ($msg) = @_; warn "PAGI Lint: $msg\n" };
21 $my_app;
22 };
23  
24 =head1 DESCRIPTION
25  
26 PAGI::Middleware::Lint validates that wrapped applications follow the
27 PAGI specification. It checks for common mistakes and spec violations,
28 helping developers catch issues early.
29  
30 =head1 CONFIGURATION
31  
32 =over 4
33  
34 =item * strict (default: 0)
35  
36 In strict mode, violations throw exceptions instead of warnings.
37  
38 =item * on_warning (optional)
39  
40 Callback for lint warnings. Receives warning message.
41  
42 =item * enabled (default: 1)
43  
44 Set to false to completely disable lint checks.
45  
46 =back
47  
48 =cut
49  
50 5 ▶sub _init {
Subroutine _init: called CC=3 SCAR=11.0
51 5 my ($self, $config) = @_;
52  
53 5 ▶ $self->{strict} = $config->{strict} // 0;
Condition100%2/2
$config->{"strict"} // 0
l!l
23
MC/DC100%1/1
$config->{"strict"} // 0
$config->{"strict"}
Truth table100%2/2
A
A= $config->{"strict"}
Aresult
11
00
54 5 $self->{on_warning} = $config->{on_warning};
55 5 ▶ $self->{enabled} = $config->{enabled} // 1;
Condition50%1/2
$config->{"enabled"} // 1
l!l
05
MC/DC0%0/1
$config->{"enabled"} // 1
$config->{"enabled"}
Truth table50%1/2
A
A= $config->{"enabled"}
Aresult
11
00
56 }
57  
58 5 ▶sub wrap {
Subroutine wrap: called CC=1 SCAR=0.6
Pod documented
59 5 my ($self, $app) = @_;
60  
61 5 ▶ return async sub {
Subroutine __ANON__: called CC=12 SCAR=30.5
62 5 my ($scope, $receive, $send) = @_;
63 5 ▶ if (!$self->{enabled}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"enabled"}) 0 5 5
64 0 await $app->($scope, $receive, $send);
65 0 return;
66 }
67  
68 # Validate scope
69 5 $self->_lint_scope($scope);
70  
71 5 my $response_started = 0;
72 5 my $response_finished = 0;
73 5 my $body_started = 0;
74 5 my $event_count = 0;
75  
76 # Wrap send to validate outgoing events
77 4 ▶ my $wrapped_send = async sub {
Subroutine __ANON__: called CC=11 SCAR=30.2
78 4 my ($event) = @_;
79 4 $event_count++;
80  
81 4 $self->_lint_event($event, $scope->{type});
82  
83 4 ▶ if ($event->{type} eq 'http.response.start') {
Branch: 4 branches
BranchTrueFalseTotal
if ($event->{'type'} eq 'http.response.start') { } 1 3 4
elsif ($event->{'type'} eq 'http.response.body') { } 3 0 3
elsif ($event->{'type'} eq 'websocket.accept') { } 0 0 0
elsif ($event->{'type'} eq 'sse.start') { } 0 0 0
84 1 ▶ if ($response_started) {
Branch: 1 branch
BranchTrueFalseTotal
if ($response_started) 0 1 1
85 0 $self->_warn("http.response.start sent multiple times");
86 }
87 1 $response_started = 1;
88 1 $self->_lint_response_start($event);
89 } elsif ($event->{type} eq 'http.response.body') {
90 3 ▶ if (!$response_started) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($response_started) 2 1 3
91 2 $self->_warn("http.response.body sent before http.response.start");
92 }
93 2 ▶ if ($response_finished) {
Branch: 1 branch
BranchTrueFalseTotal
if ($response_finished) 0 2 2
94 0 $self->_warn("http.response.body sent after response finished (more=0)");
95 }
96 2 $body_started = 1;
97 2 ▶ if (!$event->{more}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($event->{"more"}) 2 0 2
98 2 $response_finished = 1;
99 }
100 2 $self->_lint_response_body($event);
101 } elsif ($event->{type} eq 'websocket.accept') {
102 0 ▶ if ($scope->{type} ne 'websocket') {
Branch: 1 branch
BranchTrueFalseTotal
if ($scope->{"type"} ne "websocket") 0 0 0
103 0 $self->_warn("websocket.accept sent for non-websocket scope");
104 }
105 } elsif ($event->{type} eq 'sse.start') {
106 0 ▶ if ($scope->{type} ne 'sse') {
Branch: 1 branch
BranchTrueFalseTotal
if ($scope->{"type"} ne "sse") 0 0 0
107 0 $self->_warn("sse.start sent for non-sse scope");
108 }
109 }
110  
111 3 await $send->($event);
112 5 };
113  
114 5 eval {
115 5 await $app->($scope, $receive, $wrapped_send);
116 };
117 5 my $err = $@;
118  
119 # If app threw an error, prioritize it but add lint context
120 5 ▶ if ($err) {
Branch: 1 branch
BranchTrueFalseTotal
if ($err) 2 3 5
121 2 my $lint_context = "";
122 2 ▶ if ($scope->{type} eq 'http' && !$response_started) {
Branch: 2 branches
BranchTrueFalseTotal
if ($scope->{'type'} eq 'http' and not $response_started) { } 2 0 2
elsif ($scope->{'type'} eq 'http' and $response_started and not $response_finished) { } 0 0 0
Condition33%1/3
$scope->{"type"} eq "http" and not $response_started
!ll&&!rl&&r
002
MC/DC0%0/2
$scope->{"type"} eq "http" and not $response_started
$scope->{"type"} eq "http" not $response_started
Truth table33%1/3
A and not(B)
A= $scope->{"type"} eq "http"B= not $response_started
ABresult
0X0
100
111
123 2 $lint_context = "\n(Lint note: app exited without sending http.response.start)";
124 ▶ } elsif ($scope->{type} eq 'http' && $response_started && !$response_finished) {
Condition0%0/6
$scope->{"type"} eq "http" and $response_started and not $response_finished
!ll&&!rl&&r
000
$scope->{"type"} eq "http" and $response_started
!ll&&!rl&&r
000
MC/DC0%0/3
$scope->{"type"} eq "http" and $response_started and not $response_finished
$scope->{"type"} eq "http" $response_started not $response_finished
Truth table0%0/4
A and B and not(C)
A= $scope->{"type"} eq "http"B= $response_startedC= not $response_finished
ABCresult
0XX0
10X0
1100
1111
125 0 $lint_context = "\n(Lint note: app exited without sending final http.response.body)";
126 }
127 2 die "$err$lint_context";
128 }
129  
130 # Post-completion checks (only if app completed without throwing)
131 3 ▶ if ($scope->{type} eq 'http') {
Branch: 1 branch
BranchTrueFalseTotal
if ($scope->{"type"} eq "http") 3 0 3
132 3 ▶ if (!$response_started) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($response_started) 2 1 3
133 2 $self->_warn(
134 "HTTP app completed without sending http.response.start. "
135 . "This usually means you forgot to 'await' your \$send calls, "
136 . "or used ->retain for response-affecting work. "
137 . "See PAGI::Tutorial for correct async patterns."
138 );
139 }
140 3 ▶ if ($response_started && !$response_finished) {
Branch: 1 branch
BranchTrueFalseTotal
if ($response_started and not $response_finished) 0 3 3
Condition66%2/3
$response_started and not $response_finished
!ll&&!rl&&r
210
MC/DC0%0/2
$response_started and not $response_finished
$response_started not $response_finished
Truth table66%2/3
A and not(B)
A= $response_startedB= not $response_finished
ABresult
0X0
100
111
141 0 $self->_warn(
142 "HTTP app completed without sending final http.response.body (more=0). "
143 . "Did you forget to 'await' the final \$send call?"
144 );
145 }
146 }
147 5 };
148 }
149  
150 5 ▶sub _lint_scope {
Subroutine _lint_scope: called CC=11 SCAR=34.7
151 5 my ($self, $scope) = @_;
152  
153 # Check required scope keys
154 5 ▶ unless (defined $scope->{type}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $scope->{"type"}) 0 5 5
155 0 $self->_warn("scope missing required 'type' key");
156 }
157  
158 5 ▶ if ($scope->{type} eq 'http') {
Branch: 1 branch
BranchTrueFalseTotal
if ($scope->{"type"} eq "http") 5 0 5
159 5 my @required = qw(method path scheme);
160 5 for my $key (@required) {
161 15 ▶ unless (defined $scope->{$key}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $scope->{$key}) 0 15 15
162 0 $self->_warn("HTTP scope missing required '$key' key");
163 }
164 }
165  
166 # Check headers format
167 5 ▶ if (exists $scope->{headers}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $scope->{"headers"}) 5 0 5
168 5 ▶ unless (ref $scope->{headers} eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $scope->{'headers'} eq 'ARRAY') { } 5 0 5
169 0 $self->_warn("scope headers must be arrayref, got " . ref($scope->{headers}));
170 } else {
171 5 for my $h (@{$scope->{headers}}) {
172 0 ▶ unless (ref $h eq 'ARRAY' && @$h == 2) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $h eq "ARRAY" and @$h == 2) 0 0 0
Condition0%0/3
ref $h eq "ARRAY" and @$h == 2
!ll&&!rl&&r
000
MC/DC0%0/2
ref $h eq "ARRAY" and @$h == 2
ref $h eq "ARRAY" @$h == 2
Truth table0%0/3
A and B
A= ref $h eq "ARRAY"B= @$h == 2
ABresult
0X0
100
111
173 0 $self->_warn("scope header must be [name, value] pair");
174 }
175 # Check lowercase header names
176 0 ▶ if ($h->[0] =~ /[A-Z]/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($h->[0] =~ /[A-Z]/) 0 0 0
177 0 $self->_warn("header name should be lowercase: '$h->[0]'");
178 }
179 }
180 }
181 }
182 }
183 }
184  
185 4 ▶sub _lint_event {
Subroutine _lint_event: called CC=3 SCAR=14.2
186 4 my ($self, $event, $scope_type) = @_;
187  
188 4 ▶ unless (ref $event eq 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $event eq "HASH") 0 4 4
189 0 $self->_warn("event must be hashref, got " . ref($event));
190 0 return;
191 }
192  
193 4 ▶ unless (defined $event->{type}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $event->{"type"}) 0 4 4
194 0 $self->_warn("event missing required 'type' key");
195 }
196 }
197  
198 1 ▶sub _lint_response_start {
Subroutine _lint_response_start: called CC=8 SCAR=30.8
199 1 my ($self, $event) = @_;
200  
201 1 ▶ unless (defined $event->{status}) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined $event->{'status'}) { } 1 0 1
if (do { not $event->{"status"} =~ /^\d{3}$/ }) 0 1 1
202 0 $self->_warn("http.response.start missing 'status' key");
203 0 } elsif ($event->{status} !~ /^\d{3}$/) {
204 0 $self->_warn("http.response.start status must be 3-digit code, got '$event->{status}'");
205 }
206  
207 1 ▶ if (exists $event->{headers}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $event->{"headers"}) 1 0 1
208 1 ▶ unless (ref $event->{headers} eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $event->{'headers'} eq 'ARRAY') { } 1 0 1
209 0 $self->_warn("response headers must be arrayref");
210 } else {
211 1 for my $h (@{$event->{headers}}) {
212 0 ▶ unless (ref $h eq 'ARRAY' && @$h == 2) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $h eq "ARRAY" and @$h == 2) 0 0 0
Condition0%0/3
ref $h eq "ARRAY" and @$h == 2
!ll&&!rl&&r
000
MC/DC0%0/2
ref $h eq "ARRAY" and @$h == 2
ref $h eq "ARRAY" @$h == 2
Truth table0%0/3
A and B
A= ref $h eq "ARRAY"B= @$h == 2
ABresult
0X0
100
111
213 0 $self->_warn("response header must be [name, value] pair");
214 }
215 }
216 }
217 }
218 }
219  
220 2 ▶sub _lint_response_body {
Subroutine _lint_response_body: called CC=1 SCAR=0.0
221 2 my ($self, $event) = @_;
222  
223 # 'more' key is optional - defaults to 0 (false) per PAGI spec
224 # No validation needed here
225 }
226  
227 4 ▶sub _warn {
Subroutine _warn: called CC=3 SCAR=11.2
228 4 my ($self, $msg) = @_;
229  
230 4 ▶ if ($self->{strict}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"strict"}) 1 3 4
231 1 die "PAGI Lint Error: $msg\n";
232 }
233  
234 3 ▶ if ($self->{on_warning}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'on_warning'}) { } 3 0 3
235 3 $self->{on_warning}->($msg);
236 } else {
237 0 warn "PAGI Lint Warning: $msg\n";
238 }
239 }
240  
241 1 1;
242  
243 __END__
« lib/PAGI/App/SSE/Pubsub.pm ↑ Summary lib/PAGI/Middleware/Static.pm »