blib/lib/PAGI/Session.pm

filter: Statementstmt 100% 64 / 64 Branchbran 87.5% 21 / 24 Conditioncond 58.3% 7 / 12 MC/DCmcdc 37.5% 3 / 8 Subroutinesub 100% 16 / 16 Podpod 100% 13 / 13 totaltotal 90.5% 124 / 137 CC 20 SCAR 13.2
CC
20
Cov
92%
new
7.2
get
6.1
set
4.0
CRAP 3.7
« blib/lib/PAGI/Endpoint/WebSocket.pm ↑ Summary blib/lib/PAGI/Utils/SecureCompare.pm »
1 package PAGI::Session;
2 4 $PAGI::Session::VERSION = '0.002002';
3 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 4 ▶use Scalar::Util 'blessed';
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 =head1 NAME
8  
9 PAGI::Session - Standalone helper object for session data access
10  
11 =head1 SYNOPSIS
12  
13 use PAGI::Session;
14  
15 # Construct from scope or request object
16 my $session = PAGI::Session->new($scope);
17 my $session = PAGI::Session->new($req); # any object with ->scope
18 my $session = PAGI::Session->new(@_); # extra args ignored
19  
20 # Test convenience - wrap raw data directly
21 my $session = PAGI::Session->from_data({ _id => 'test', user_id => 42 });
22  
23 # Strict get - dies if key doesn't exist (catches typos)
24 my $user_id = $session->get('user_id');
25  
26 # Safe get with default for optional keys
27 my $theme = $session->get('theme', 'light');
28  
29 # Set, delete, check existence
30 $session->set('cart_count', 3);
31 $session->delete('cart_count');
32 if ($session->exists('user_id')) { ... }
33  
34 # List user keys (excludes internal _prefixed keys)
35 my @keys = $session->keys;
36  
37 # Session lifecycle
38 $session->regenerate; # Request new session ID
39 $session->destroy; # Mark session for deletion
40  
41 =head1 DESCRIPTION
42  
43 PAGI::Session wraps the raw session data hashref and provides a clean
44 accessor interface with strict key checking. It is a standalone helper
45 that is not attached to any request or protocol object.
46  
47 The strict C<get()> method dies when a key does not exist, catching
48 typos at runtime. Use the two-argument form C<get($key, $default)>
49 for keys that may or may not be present.
50  
51 =head1 CONSTRUCTOR
52  
53 =head2 new
54  
55 my $session = PAGI::Session->new($scope);
56 my $session = PAGI::Session->new($request); # any object with ->scope
57 my $session = PAGI::Session->new(@_); # extra args ignored
58  
59 Scope-based constructor. Resolves to the C<< $scope->{'pagi.session'} >>
60 hashref. Accepts a scope hashref directly, or any blessed object with a
61 C<scope()> method. Extra positional arguments (C<$receive>, C<$send>) are
62 silently ignored, so you can write C<< PAGI::Session->new(@_) >> in a
63 handler.
64  
65 Dies if the scope does not contain a C<pagi.session> key (session
66 middleware must run first).
67  
68 =head2 from_data
69  
70 my $session = PAGI::Session->from_data({ _id => 'test', user_id => 42 });
71  
72 Test convenience constructor. Wraps a raw hashref directly as the backing
73 data, bypassing scope resolution. The returned object behaves identically
74 to one created via C<new()>.
75  
76 =cut
77  
78 17 ▶sub new {
Subroutine new: called CC=7 SCAR=19.8
Pod documented
79 17 my ($class, @args) = @_;
80  
81 17 my $arg = $args[0];
82  
83 # Object with ->scope method (e.g., PAGI::Request, PAGI::SSE)
84 17 ▶ if (blessed($arg) && $arg->can('scope')) {
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($arg) and $arg->can("scope")) 2 15 17
Condition66%2/3
builtin::blessed($arg) and $arg->can("scope")
!ll&&!rl&&r
1502
MC/DC50%1/2
builtin::blessed($arg) and $arg->can("scope")
builtin::blessed($arg) $arg->can("scope")
Truth table66%2/3
A and B
A= builtin::blessed($arg)B= $arg->can("scope")
ABresult
0X0
100
111
85 2 my $scope = $arg->scope;
86 die "PAGI::Session requires scope hashref with 'pagi.session' key\n"
87 2 ▶ unless ref $scope eq 'HASH' && exists $scope->{'pagi.session'};
Branch: 1 branch
BranchTrueFalseTotal
unless ref $scope eq "HASH" and exists $scope->{"pagi.session"} 0 2 2
Condition33%1/3
ref $scope eq "HASH" and exists $scope->{"pagi.session"}
!ll&&!rl&&r
002
MC/DC0%0/2
ref $scope eq "HASH" and exists $scope->{"pagi.session"}
ref $scope eq "HASH" exists $scope->{"pagi.session"}
Truth table33%1/3
A and B
A= ref $scope eq "HASH"B= exists $scope->{"pagi.session"}
ABresult
0X0
100
111
88 2 return bless { _data => $scope->{'pagi.session'} }, $class;
89 }
90  
91 # Scope hashref - must have pagi.session key
92 15 ▶ if (ref $arg eq 'HASH' && exists $arg->{'pagi.session'}) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $arg eq "HASH" and exists $arg->{"pagi.session"}) 6 9 15
Condition100%3/3
ref $arg eq "HASH" and exists $arg->{"pagi.session"}
!ll&&!rl&&r
636
MC/DC100%2/2
ref $arg eq "HASH" and exists $arg->{"pagi.session"}
ref $arg eq "HASH" exists $arg->{"pagi.session"}
Truth table100%3/3
A and B
A= ref $arg eq "HASH"B= exists $arg->{"pagi.session"}
ABresult
0X0
100
111
93 6 return bless { _data => $arg->{'pagi.session'} }, $class;
94 }
95  
96 9 die "PAGI::Session requires a scope hashref (with 'pagi.session' key) or object with ->scope method\n";
97 }
98  
99 33 ▶sub from_data {
Subroutine from_data: called CC=2 SCAR=7.1
Pod documented
100 33 my ($class, $data) = @_;
101 33 ▶ die "from_data() requires a hashref\n" unless ref $data eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $data eq "HASH" 0 33 33
102 33 return bless { _data => $data }, $class;
103 }
104  
105 =head1 METHODS
106  
107 =head2 id
108  
109 my $id = $session->id;
110  
111 Returns the session ID from C<< $data->{_id} >>.
112  
113 =cut
114  
115 9 ▶sub id {
Subroutine id: called CC=1 SCAR=0.0
Pod documented
116 9 my ($self) = @_;
117 9 return $self->{_data}{_id};
118 }
119  
120 =head2 data
121  
122 my $href = $session->data;
123 $href->{key} = $value; # direct mutation
124  
125 Returns the raw backing hashref. Mutations are visible through
126 C<get()>/C<set()> since they operate on the same reference.
127  
128 =cut
129  
130 4 ▶sub data {
Subroutine data: called CC=1 SCAR=0.0
Pod documented
131 4 my ($self) = @_;
132 4 return $self->{_data};
133 }
134  
135 =head2 get
136  
137 my $value = $session->get('key'); # dies if missing
138 my $value = $session->get('key', $default); # returns $default if missing
139  
140 Retrieves a value from the session. With one argument, dies with an
141 error including the key name if the key does not exist. With a default
142 argument, returns the default when the key is missing (even if the
143 default is C<undef>).
144  
145 =cut
146  
147 23 ▶sub get {
Subroutine get: called CC=6 SCAR=18.0
Pod documented
148 23 my ($self, @args) = @_;
149 23 ▶ die "get() requires 1 or 2 arguments\n" if @args == 0 || @args > 2;
Branch: 1 branch
BranchTrueFalseTotal
if @args == 0 or @args > 2 0 23 23
Condition33%1/3
@args == 0 or @args > 2
l!l&&r!l&&!r
0023
MC/DC0%0/2
@args == 0 or @args > 2
@args == 0 @args > 2
Truth table33%1/3
A or B
A= @args == 0B= @args > 2
ABresult
1X1
011
000
150 23 my ($key, @rest) = @args;
151 23 ▶ if (!exists $self->{_data}{$key}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->{"_data"}{$key}) 7 16 23
152 7 ▶ return $rest[0] if @rest;
Branch: 1 branch
BranchTrueFalseTotal
if @rest 3 4 7
153 4 my @user_keys = sort grep { !/^_/ } keys %{$self->{_data}};
154 4 ▶ if (@user_keys <= 10) {
Branch: 1 branch
BranchTrueFalseTotal
if (@user_keys <= 10) { } 3 1 4
155 3 die "Session key '$key' does not exist. Available keys: "
156 . join(', ', @user_keys) . "\n";
157 }
158 else {
159 1 die "Session key '$key' does not exist (session has "
160 . scalar(@user_keys) . " user keys)\n";
161 }
162 }
163 16 return $self->{_data}{$key};
164 }
165  
166 =head2 set
167  
168 $session->set('key', $value);
169 $session->set(user_id => 42, role => 'admin', email => 'john@example.com');
170 $session->set('a', 1)->set('b', 2); # chaining
171  
172 Sets one or more keys in the session data. Accepts key-value pairs.
173 Returns C<$self> for method chaining. With zero arguments, acts as a
174 no-op returning C<$self>. Dies if given an odd number of arguments.
175  
176 =cut
177  
178 18 ▶sub set {
Subroutine set: called CC=4 SCAR=13.9
Pod documented
179 18 my ($self, @args) = @_;
180 18 ▶ return $self unless @args;
Branch: 1 branch
BranchTrueFalseTotal
unless @args 1 17 18
181 17 ▶ die "set() requires key => value pairs\n" if @args % 2;
Branch: 1 branch
BranchTrueFalseTotal
if @args % 2 3 14 17
182 14 my %pairs = @args;
183 14 $self->{_data}{$_} = $pairs{$_} for CORE::keys %pairs;
184 14 return $self;
185 }
186  
187 =head2 exists
188  
189 if ($session->exists('key')) { ... }
190  
191 Returns true if the key exists in the session data.
192  
193 =cut
194  
195 7 ▶sub exists {
Subroutine exists: called CC=2 SCAR=6.9
Pod documented
196 7 my ($self, $key) = @_;
197 7 ▶ return exists $self->{_data}{$key} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
exists $self->{'_data'}{$key} ? : 2 5 7
198 }
199  
200 =head2 delete
201  
202 $session->delete('key');
203 $session->delete('k1', 'k2', 'k3');
204 $session->delete('a')->delete('b'); # chaining
205  
206 Removes one or more keys from the session data. Returns C<$self> for
207 method chaining.
208  
209 =cut
210  
211 5 ▶sub delete {
Subroutine delete: called CC=2 SCAR=6.9
Pod documented
212 5 my ($self, @keys) = @_;
213 5 delete $self->{_data}{$_} for @keys;
214 5 return $self;
215 }
216  
217 =head2 keys
218  
219 my @keys = $session->keys;
220  
221 Returns a list of user keys, filtering out internal keys that start
222 with an underscore (e.g. C<_id>, C<_created>, C<_last_access>).
223  
224 =cut
225  
226 4 ▶sub keys {
Subroutine keys: called CC=1 SCAR=0.0
Pod documented
227 4 my ($self) = @_;
228 4 return grep { !/^_/ } keys %{$self->{_data}};
229 }
230  
231 =head2 slice
232  
233 my %data = $session->slice('user_id', 'role', 'email');
234  
235 Returns a hash of key-value pairs for the requested keys. Keys that
236 do not exist in the session are silently skipped (unlike C<get()>,
237 which dies on missing keys).
238  
239 =cut
240  
241 3 ▶sub slice {
Subroutine slice: called CC=2 SCAR=6.9
Pod documented
242 3 my ($self, @keys) = @_;
243 3 ▶ return map { CORE::exists($self->{_data}{$_}) ? ($_ => $self->{_data}{$_}) : () } @keys;
Branch: 1 branch
BranchTrueFalseTotal
exists $self->{'_data'}{$_} ? : 3 4 7
244 }
245  
246 =head2 clear
247  
248 $session->clear;
249  
250 Removes all user keys from the session, preserving internal
251 C<_>-prefixed keys (C<_id>, C<_created>, C<_last_access>, etc.).
252 Use this for a "soft logout" that keeps the session ID but wipes
253 application data.
254  
255 =cut
256  
257 2 ▶sub clear {
Subroutine clear: called CC=2 SCAR=6.9
Pod documented
258 2 my ($self) = @_;
259 2 for my $key ($self->keys) {
260 3 delete $self->{_data}{$key};
261 }
262 }
263  
264 =head2 regenerate
265  
266 $session->regenerate;
267  
268 Requests session ID regeneration. The middleware will generate a new
269 session ID, delete the old session from the store, save session data
270 under the new ID, and update the client cookie/header.
271  
272 B<Security:> Always call this after authentication (login) to prevent
273 session fixation attacks.
274  
275 =cut
276  
277 1 ▶sub regenerate {
Subroutine regenerate: called CC=1 SCAR=0.0
Pod documented
278 1 my ($self) = @_;
279 1 $self->{_data}{_regenerated} = 1;
280 }
281  
282 =head2 destroy
283  
284 $session->destroy;
285  
286 Marks the session for destruction. The middleware will delete the
287 session data from the store and clear the client-side state (e.g.,
288 expire the cookie). Use this for logout.
289  
290 =cut
291  
292 1 ▶sub destroy {
Subroutine destroy: called CC=1 SCAR=0.0
Pod documented
293 1 my ($self) = @_;
294 1 $self->{_data}{_destroyed} = 1;
295 }
296  
297 4 1;
298  
299 __END__
« blib/lib/PAGI/Endpoint/WebSocket.pm ↑ Summary blib/lib/PAGI/Utils/SecureCompare.pm »