blib/lib/PAGI/Middleware.pm

filter: Statementstmt 97.3% 37 / 38 Branchbran 50.0% 3 / 6 Conditioncond 50.0% 2 / 4 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 100% 10 / 10 Podpod 100% 5 / 5 totaltotal 87.6% 57 / 65 CC 6 SCAR 9.6
CC
6
Cov
88%
buffer_request_body
5.5
modify_scope
2.0
BEGIN
1.0
CRAP 2.6
« blib/lib/PAGI/Middleware/Session/State/Callback.pm ↑ Summary blib/lib/PAGI/Test/ConnectionState.pm »
1 package PAGI::Middleware;
2 26 $PAGI::Middleware::VERSION = '0.002002';
3 26 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 26 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 26 ▶use Future::AsyncAwait;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 =head1 NAME
8  
9 PAGI::Middleware - Base class for PAGI middleware
10  
11 =head1 SYNOPSIS
12  
13 # Create a custom middleware
14 package My::Middleware;
15 use parent 'PAGI::Middleware';
16  
17 sub wrap {
18 my ($self, $app) = @_;
19  
20 return async sub {
21 my ($scope, $receive, $send) = @_;
22 # Modify scope for inner app
23 my $modified_scope = $self->modify_scope($scope, {
24 custom_key => 'custom_value',
25 });
26  
27 # Call inner app with modified scope
28 await $app->($modified_scope, $receive, $send);
29 };
30 }
31  
32 # Use the builder DSL
33 use PAGI::Middleware::Builder;
34  
35 my $app = builder {
36 enable 'My::Middleware', option => 'value';
37 enable_if { $_[0]->{path} =~ m{^/api/} } 'RateLimit', limit => 100;
38 mount '/static' => $static_app;
39 $my_app;
40 };
41  
42 =head1 DESCRIPTION
43  
44 PAGI::Middleware provides a base class for implementing middleware that wraps
45 PAGI applications. Middleware can modify the request scope, intercept responses,
46 or perform cross-cutting concerns like logging, authentication, or compression.
47  
48 =head1 METHODS
49  
50 =head2 new
51  
52 my $middleware = PAGI::Middleware->new(%config);
53  
54 Create a new middleware instance. Configuration options are stored and
55 accessible via C<$self-E<gt>{config}>.
56  
57 =cut
58  
59 222 ▶sub new {
Subroutine new: called CC=1 SCAR=0.0
Pod documented
60 222 my ($class, %config) = @_;
61  
62 222 my $self = bless {
63 config => \%config,
64 }, $class;
65 222 $self->_init(\%config);
66 219 return $self;
67 }
68  
69 =head2 _init
70  
71 $self->_init(\%config);
72  
73 Hook for subclasses to perform initialization. Called by new().
74 Default implementation does nothing.
75  
76 =cut
77  
78 25 ▶sub _init {
Subroutine _init: called CC=1 SCAR=0.0
79 25 my ($self, $config) = @_;
80  
81 # Subclasses can override
82 }
83  
84 =head2 wrap
85  
86 my $wrapped_app = $middleware->wrap($app);
87  
88 Wrap a PAGI application. Returns a new async sub that handles
89 the middleware logic. Subclasses MUST override this method.
90  
91 =cut
92  
93 1 ▶sub wrap {
Subroutine wrap: called CC=1 SCAR=0.0
Pod documented
94 1 my ($self, $app) = @_;
95  
96 1 die "Subclass must implement wrap()";
97 }
98  
99 =head2 modify_scope
100  
101 my $new_scope = $self->modify_scope($scope, \%additions);
102  
103 Return a new scope -- a shallow copy of C<$scope> with C<%additions> merged in --
104 B<without mutating the original>. This is the supported way to pass extra data to
105 inner apps, and the canonical middleware in this distribution use it.
106  
107 Why copy instead of writing C<< $scope->{key} = ... >> directly? Middleware form a
108 stack, and the scope you are handed is shared with the layers around you. Mutating
109 it in place lets your change leak B<upward> to parent and sibling layers (and, for
110 a long-lived WebSocket scope, persist across every event on the connection).
111 Copying keeps your additions B<downward only> -- seen by the inner app you call,
112 invisible to everyone above.
113  
114 The copy is B<shallow> on purpose. Top-level keys you add are private to the new
115 scope, but values that are B<references> -- the C<pagi.connection> object, the
116 lifespan C<state> namespace, the stash -- are shared, so the inner app still sees
117 the same connection state and shared objects. A deep copy would sever those. One
118 corollary worth knowing: a plain B<scalar> set as a top-level scope key does not
119 propagate back to outer layers, so to share mutable state across layers you mutate
120 B<through a reference> (see L<PAGI::Stash>). The full model -- and why it works
121 this way -- is in L<PAGI::Building/MIDDLEWARE>.
122  
123 =cut
124  
125 77 ▶sub modify_scope {
Subroutine modify_scope: called CC=2 SCAR=7.1
Pod documented
126 77 my ($self, $scope, $additions) = @_;
127 77 ▶ $additions //= {};
Condition50%1/2
$additions //= {}
l!l
770
MC/DC0%0/1
$additions //= {}
$additions
Truth table50%1/2
A
A= $additions
Aresult
11
00
128  
129 77 return { %$scope, %$additions };
130 }
131  
132 =head2 intercept_send
133  
134 my $wrapped_send = $self->intercept_send($send, \&interceptor);
135  
136 Wrap the $send callback to intercept outgoing events.
137 The interceptor is called with ($event, $original_send) and should
138 return a Future.
139  
140 my $wrapped_send = $self->intercept_send($send, async sub {
141 my ($event, $original_send) = @_;
142 if ($event->{type} eq 'http.response.start') {
143 # Modify headers
144 push @{$event->{headers}}, ['x-custom', 'value'];
145 }
146 await $original_send->($event);
147 });
148  
149 =cut
150  
151 2 ▶sub intercept_send {
Subroutine intercept_send: called CC=1 SCAR=0.0
Pod documented
152 2 my ($self, $send, $interceptor) = @_;
153  
154 3 ▶ return async sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
155 3 my ($event) = @_;
156 3 await $interceptor->($event, $send);
157 2 };
158 }
159  
160 =head2 buffer_request_body
161  
162 my ($body, $final_event) = await $self->buffer_request_body($receive);
163  
164 Collect all request body chunks into a single string.
165 Returns the complete body and the final http.request event.
166  
167 =cut
168  
169 1 ▶async sub buffer_request_body {
Subroutine buffer_request_body: called CC=5 SCAR=17.0
Pod documented
170 1 my ($self, $receive) = @_;
171  
172 1 my $body = '';
173 1 my $event;
174  
175 1 while (1) {
176 2 $event = await $receive->();
177  
178 2 ▶ if ($event->{type} eq 'http.request') {
Branch: 2 branches
BranchTrueFalseTotal
if ($event->{'type'} eq 'http.request') { } 2 0 2
elsif ($event->{'type'} eq 'http.disconnect') { } 0 0 0
179 2 ▶ $body .= $event->{body} // '';
Condition50%1/2
$event->{"body"} // ""
l!l
20
MC/DC0%0/1
$event->{"body"} // ""
$event->{"body"}
Truth table50%1/2
A
A= $event->{"body"}
Aresult
11
00
180 2 ▶ last unless $event->{more};
Branch: 1 branch
BranchTrueFalseTotal
unless $event->{"more"} 1 1 2
181 } elsif ($event->{type} eq 'http.disconnect') {
182 0 last;
183 }
184 }
185  
186 1 return ($body, $event);
187 26 }
188  
189  
190 26 1;
191  
192 __END__
« blib/lib/PAGI/Middleware/Session/State/Callback.pm ↑ Summary blib/lib/PAGI/Test/ConnectionState.pm »