blib/lib/PAGI/Middleware/Builder.pm

filter: Statementstmt 99.2% 129 / 130 Branchbran 85.0% 34 / 40 Conditioncond 100% 5 / 5 MC/DCmcdc 100% 3 / 3 Subroutinesub 100% 22 / 22 Podpod 66.6% 6 / 9 totaltotal 95.2% 199 / 209 CC 25 SCAR 10.9
CC
25
Cov
96%
__ANON__
6.0
add_middleware_if
4.0
add_middleware
4.0
CRAP 3.0
« lib/PAGI/App/Redirect.pm ↑ Summary blib/lib/PAGI/Middleware/Session/State/Header.pm »
1 package PAGI::Middleware::Builder;
2 3 $PAGI::Middleware::Builder::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 Carp 'croak';
Subroutine BEGIN: called CC=1 SCAR=0.0
7 3 ▶use Scalar::Util qw(blessed);
Subroutine BEGIN: called CC=1 SCAR=0.0
8 3 ▶use PAGI::Utils ();
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 # Note: We use traditional Perl subs because prototypes don't work with signatures.
11  
12 =encoding UTF-8
13  
14 =head1 NAME
15  
16 PAGI::Middleware::Builder - DSL for composing PAGI middleware
17  
18 =head1 SYNOPSIS
19  
20 use PAGI::Middleware::Builder;
21  
22 # Functional DSL
23 my $app = builder {
24 enable 'ContentLength';
25 enable 'CORS', origins => ['*'];
26 enable_if { $_[0]->{path} =~ m{^/api/} } 'RateLimit', limit => 100;
27 mount '/static' => $static_app;
28 $my_app;
29 };
30  
31 # Object-oriented interface
32 my $builder = PAGI::Middleware::Builder->new;
33 $builder->enable('ContentLength');
34 $builder->enable('CORS', origins => ['*']);
35 $builder->mount('/admin', $admin_app);
36 my $app = $builder->to_app($my_app);
37  
38 =head1 DESCRIPTION
39  
40 PAGI::Middleware::Builder provides a DSL for composing middleware into
41 a PAGI application. It supports:
42  
43 =over 4
44  
45 =item * Enabling middleware with configuration
46  
47 =item * Conditional middleware application
48  
49 =item * Path-based routing (mount)
50  
51 =item * Middleware ordering
52  
53 =back
54  
55 =head1 EXPORTS
56  
57 =cut
58  
59 3 ▶use Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
60 3 our @EXPORT = qw(builder enable enable_if mount);
61  
62 # Current builder context for DSL
63 3 our $_current_builder;
64  
65 =head2 builder
66  
67 my $app = builder { ... };
68  
69 Create a composed application using the DSL. The block should
70 call enable(), enable_if(), mount(), and return the final app.
71 The final value of the block is coerced via L<PAGI::Utils/to_app>,
72 so you can return a component object or class name directly:
73  
74 my $app = builder {
75 enable 'ContentLength';
76 PAGI::App::NotFound->new;
77 };
78  
79 =cut
80  
81 4 ▶sub builder (&) {
Subroutine builder: called CC=1 SCAR=0.0
Pod documented
82 4 my ($block) = @_;
83 4 local $_current_builder = PAGI::Middleware::Builder->new;
84 4 my $app = $block->();
85 4 return $_current_builder->to_app($app);
86 }
87  
88 =head2 enable
89  
90 enable 'MiddlewareName', %config;
91 enable 'Auth::Basic', %config; # PAGI::Middleware::Auth::Basic
92 enable '^My::Custom::Middleware'; # My::Custom::Middleware (no prefix)
93 enable(PAGI::Middleware::GZip->new(level => 9)); # pre-configured instance
94  
95 Enable a middleware. The name is automatically prefixed with
96 'PAGI::Middleware::' unless it starts with '^', which indicates
97 a fully qualified class name (the '^' is stripped).
98  
99 When passed an already-configured middleware instance (an object with a
100 C<wrap> method), it is used directly. Passing config args alongside an
101 instance is an error — configure the instance at construction time.
102  
103 The parentheses are required for the instance form: C<enable $obj> without
104 them is parsed as an indirect method call and dies with a confusing error.
105  
106 =cut
107  
108 1 ▶sub enable {
Subroutine enable: called CC=2 SCAR=7.1
Pod documented
109 1 my ($name, %config) = @_;
110 1 ▶ croak "enable() must be called inside builder {}" unless $_current_builder;
Branch: 1 branch
BranchTrueFalseTotal
unless $PAGI::Middleware::Builder::_current_builder 0 1 1
111 1 $_current_builder->add_middleware($name, %config);
112 }
113  
114 =head2 enable_if
115  
116 enable_if { $condition } 'MiddlewareName', %config;
117 enable_if { $condition } (PAGI::Middleware::GZip->new(level => 9));
118  
119 Conditionally enable middleware. The condition block receives
120 the scope and returns true/false. A pre-configured middleware instance
121 may be passed instead of a class name; config args alongside an instance
122 are an error.
123  
124 =cut
125  
126 2 ▶sub enable_if (&$;@) {
Subroutine enable_if: called CC=2 SCAR=7.1
Pod documented
127 2 my ($condition, $name, %config) = @_;
128 2 ▶ croak "enable_if() must be called inside builder {}" unless $_current_builder;
Branch: 1 branch
BranchTrueFalseTotal
unless $PAGI::Middleware::Builder::_current_builder 0 2 2
129 2 $_current_builder->add_middleware_if($condition, $name, %config);
130 }
131  
132 =head2 mount
133  
134 mount '/path' => $app;
135 mount '/static' => PAGI::App::File->new(root => $dir);
136 mount '/api' => 'MyApp::API';
137  
138 Mount an application at a path prefix. Requests matching the
139 prefix are routed to the mounted app with adjusted paths. The app
140 argument accepts anything L<PAGI::Utils/to_app> accepts: a coderef,
141 a component object with C<to_app>, or a class name.
142  
143 =cut
144  
145 1 ▶sub mount {
Subroutine mount: called CC=2 SCAR=7.1
Pod documented
146 1 my ($path, $app) = @_;
147 1 ▶ croak "mount() must be called inside builder {}" unless $_current_builder;
Branch: 1 branch
BranchTrueFalseTotal
unless $PAGI::Middleware::Builder::_current_builder 0 1 1
148 1 $_current_builder->add_mount($path, $app);
149 }
150  
151 =head1 METHODS
152  
153 =head2 new
154  
155 my $builder = PAGI::Middleware::Builder->new;
156  
157 Create a new builder instance.
158  
159 =cut
160  
161 12 ▶sub new {
Subroutine new: called CC=1 SCAR=0.0
Pod documented
162 12 my ($class) = @_;
163 12 return bless {
164 middleware => [],
165 mounts => [],
166 }, $class;
167 }
168  
169 =head2 enable
170  
171 $builder->enable('MiddlewareName', %config);
172  
173 Add middleware to the stack (OO interface).
174  
175 =cut
176  
177 5 ▶sub add_middleware {
Subroutine add_middleware: called CC=4 SCAR=13.9
Pod undocumented
178 5 my ($self, $name, %config) = @_;
179  
180 5 ▶ if (blessed($name)) {
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($name)) 3 2 5
181 3 ▶ croak "enable() with a middleware instance takes no config"
Branch: 1 branch
BranchTrueFalseTotal
if %config 1 2 3
182 . " (configure it at construction time)" if %config;
183 2 ▶ croak ref($name) . " does not look like middleware (no wrap method)"
Branch: 1 branch
BranchTrueFalseTotal
unless $name->can("wrap") 1 1 2
184 unless $name->can('wrap');
185 1 push @{$self->{middleware}}, {
186 instance => $name,
187 condition => undef,
188 };
189 1 return $self;
190 }
191  
192 2 my $class = $self->_resolve_middleware($name);
193 2 push @{$self->{middleware}}, {
194 class => $class,
195 config => \%config,
196 condition => undef,
197 };
198 2 return $self;
199 }
200  
201 =head2 enable_if
202  
203 $builder->enable_if(\&condition, 'MiddlewareName', %config);
204  
205 Add conditional middleware to the stack (OO interface).
206  
207 =cut
208  
209 4 ▶sub add_middleware_if {
Subroutine add_middleware_if: called CC=4 SCAR=13.9
Pod undocumented
210 4 my ($self, $condition, $name, %config) = @_;
211  
212 4 ▶ if (blessed($name)) {
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($name)) 3 1 4
213 3 ▶ croak "enable_if() with a middleware instance takes no config"
Branch: 1 branch
BranchTrueFalseTotal
if %config 1 2 3
214 . " (configure it at construction time)" if %config;
215 2 ▶ croak ref($name) . " does not look like middleware (no wrap method)"
Branch: 1 branch
BranchTrueFalseTotal
unless $name->can("wrap") 0 2 2
216 unless $name->can('wrap');
217 2 push @{$self->{middleware}}, {
218 instance => $name,
219 condition => $condition,
220 };
221 2 return $self;
222 }
223  
224 1 my $class = $self->_resolve_middleware($name);
225 1 push @{$self->{middleware}}, {
226 class => $class,
227 config => \%config,
228 condition => $condition,
229 };
230 1 return $self;
231 }
232  
233 =head2 mount
234  
235 $builder->mount('/path', $app);
236  
237 Add a path-based mount point (OO interface).
238  
239 =cut
240  
241 2 ▶sub add_mount {
Subroutine add_mount: called CC=2 SCAR=7.0
Pod undocumented
242 2 my ($self, $path, $app) = @_;
243 # Normalize path (remove trailing slash, ensure leading slash)
244 2 $path =~ s{/$}{};
245 2 ▶ $path = "/$path" unless $path =~ m{^/};
Branch: 1 branch
BranchTrueFalseTotal
unless $path =~ m[^/] 0 2 2
246  
247 2 push @{$self->{mounts}}, {
248 path => $path,
249 app => PAGI::Utils::to_app($app),
250 };
251 2 return $self;
252 }
253  
254 =head2 to_app
255  
256 my $app = $builder->to_app($inner_app);
257  
258 Build the composed application. C<$inner_app> accepts anything
259 L<PAGI::Utils/to_app> accepts: a coderef, a component object with
260 C<to_app>, or a class name. This means C<builder { ...; $router }> and
261 C<builder { ...; PAGI::App::NotFound->new }> work without an explicit
262 C<< ->to_app >> call.
263  
264 =cut
265  
266 7 ▶sub to_app {
Subroutine to_app: called CC=3 SCAR=11.0
Pod documented
267 7 my ($self, $app) = @_;
268 7 $app = PAGI::Utils::to_app($app);
269  
270 # Apply mounts first (innermost)
271 7 ▶ if (@{$self->{mounts}}) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$self->{"mounts"};}) 2 5 7
272 2 $app = $self->_build_mount_app($app);
273 }
274  
275 # Apply middleware in reverse order (outermost first in execution)
276 7 for my $mw (reverse @{$self->{middleware}}) {
277 6 $app = $self->_wrap_middleware($mw, $app);
278 }
279  
280 7 return $app;
281 }
282  
283 # Private: resolve middleware class name
284 14 ▶sub _resolve_middleware {
Subroutine _resolve_middleware: called CC=3 SCAR=11.0
285 14 my ($self, $name) = @_;
286  
287 # Always prepend PAGI::Middleware::, then strip everything up to ^ if present
288 # Examples:
289 # 'GZIP' -> 'PAGI::Middleware::GZIP'
290 # 'Auth::Basic' -> 'PAGI::Middleware::Auth::Basic'
291 # '^My::Custom' -> 'My::Custom' (prefix removed)
292 # '^TopLevel' -> 'TopLevel' (prefix removed)
293 14 my $class = "PAGI::Middleware::$name" =~ s{^.+\^}{}r;
294  
295 # Load the module
296 14 my $file = $class;
297 14 $file =~ s{::}{/}g;
298 14 $file .= '.pm';
299  
300 14 eval { require $file };
301 14 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 7 7 14
302 # If loading fails, the error will surface when instantiating
303 # This allows for forward declarations
304 7 ▶ warn "Warning: Could not load $class: $@" if $ENV{PAGI_DEBUG};
Branch: 1 branch
BranchTrueFalseTotal
if $ENV{"PAGI_DEBUG"} 0 7 7
305 }
306  
307 14 return $class;
308 }
309  
310 # Private: wrap a middleware around an app
311 6 ▶sub _wrap_middleware {
Subroutine _wrap_middleware: called CC=4 SCAR=13.9
312 6 my ($self, $mw, $app) = @_;
313 6 my $condition = $mw->{condition};
314  
315 # Pre-configured instance path
316 6 ▶ if (my $instance = $mw->{instance}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $instance = $mw->{"instance"}) 3 3 6
317 3 my $wrapped = $instance->wrap($app);
318 3 ▶ return $wrapped unless $condition;
Branch: 1 branch
BranchTrueFalseTotal
unless $condition 1 2 3
319 2 ▶ return async sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
320 2 my ($scope, $receive, $send) = @_;
321 2 ▶ if ($condition->($scope)) {
Branch: 1 branch
BranchTrueFalseTotal
if (&$condition($scope)) { } 1 1 2
322 1 await $wrapped->($scope, $receive, $send);
323 } else {
324 1 await $app->($scope, $receive, $send);
325 }
326 2 };
327 }
328  
329 # Class name + config path
330 3 my $class = $mw->{class};
331 3 my $config = $mw->{config};
332  
333 3 ▶ if ($condition) {
Branch: 1 branch
BranchTrueFalseTotal
if ($condition) { } 1 2 3
334 # Conditional middleware
335 2 ▶ return async sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
336 2 my ($scope, $receive, $send) = @_;
337 2 ▶ if ($condition->($scope)) {
Branch: 1 branch
BranchTrueFalseTotal
if (&$condition($scope)) { } 1 1 2
338 1 my $instance = $class->new(%$config);
339 1 my $wrapped = $instance->wrap($app);
340 1 await $wrapped->($scope, $receive, $send);
341 } else {
342 1 await $app->($scope, $receive, $send);
343 }
344 1 };
345 } else {
346 # Unconditional middleware
347 2 my $instance = $class->new(%$config);
348 2 return $instance->wrap($app);
349 }
350 }
351  
352 # Private: build mount routing app
353 2 ▶sub _build_mount_app {
Subroutine _build_mount_app: called CC=1 SCAR=0.0
354 2 my ($self, $fallback_app) = @_;
355 0 my @mounts = sort { length($b->{path}) <=> length($a->{path}) } @{$self->{mounts}};
356  
357 5 ▶ return async sub {
Subroutine __ANON__: called CC=6 SCAR=17.9
358 5 my ($scope, $receive, $send) = @_;
359 5 my $path = $scope->{path};
360  
361 5 for my $mount (@mounts) {
362 5 my $prefix = $mount->{path};
363  
364 # Check if path matches mount point
365 5 ▶ if ($path eq $prefix || $path =~ m{^\Q$prefix\E/}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($path eq $prefix or $path =~ m[^\Q$prefix\E/]) 3 2 5
Condition100%3/3
$path eq $prefix or $path =~ m[^\Q$prefix\E/]
l!l&&r!l&&!r
122
MC/DC100%2/2
$path eq $prefix or $path =~ m[^\Q$prefix\E/]
$path eq $prefix $path =~ m[^\Q$prefix\E/]
Truth table100%3/3
A or B
A= $path eq $prefixB= $path =~ m[^\Q$prefix\E/]
ABresult
1X1
011
000
366 # Adjust path and root_path for mounted app
367 3 my $new_path = $path;
368 3 $new_path =~ s{^\Q$prefix\E}{};
369 3 ▶ $new_path = '/' if $new_path eq '';
Branch: 1 branch
BranchTrueFalseTotal
if $new_path eq "" 1 2 3
370  
371 3 ▶ my $new_root = ($scope->{root_path} // '') . $prefix;
Condition100%2/2
$scope->{"root_path"} // ""
l!l
21
MC/DC100%1/1
$scope->{"root_path"} // ""
$scope->{"root_path"}
Truth table100%2/2
A
A= $scope->{"root_path"}
Aresult
11
00
372  
373 3 my $mounted_scope = {
374 %$scope,
375 path => $new_path,
376 root_path => $new_root,
377 };
378  
379 3 await $mount->{app}->($mounted_scope, $receive, $send);
380 3 return;
381 }
382 }
383  
384 # No mount matched, use fallback
385 2 await $fallback_app->($scope, $receive, $send);
386 2 };
387 }
388  
389 3 1;
390  
391 __END__
« lib/PAGI/App/Redirect.pm ↑ Summary blib/lib/PAGI/Middleware/Session/State/Header.pm »