1 package Plack::Session::State;
7 use Plack::Util::Accessor qw[
14 my ($class, %params) = @_;
16 $params{'_expired'} ||= +{};
17 $params{'session_key'} ||= 'plack_session';
18 $params{'sid_generator'} ||= sub {
19 Digest::SHA1::sha1_hex(rand() . $$ . {} . time)
21 $params{'sid_validator'} ||= qr/\A[0-9a-f]{40}\Z/;
23 bless { %params } => $class;
26 sub expire_session_id {
28 $self->{'_expired'}->{ $id }++;
31 sub is_session_expired {
33 exists $self->{'_expired'}->{ $id }
38 return unless $id && not $self->is_session_expired( $id );
42 sub validate_request_session_id {
43 my ($self, $request) = @_;
45 my $reqest_session_id = $self->get_request_session_id($request);
46 my $sid_validator = $self->sid_validator;
48 defined $reqest_session_id && $reqest_session_id =~ m{$sid_validator};
52 my ($self, $request) = @_;
54 $self->validate_request_session_id($request)
56 $self->extract( $request )
59 $self->generate( $request )
62 sub get_request_session_id {
63 my ($self, $request ) = @_;
65 $request->param( $self->session_key );
69 my ($self, $request) = @_;
71 $self->check_expired( $self->get_request_session_id($request) );
76 $self->sid_generator->( @_ );
81 my ($self, $id, $response) = @_;
93 Plack::Session::State - Basic parameter-based session state
98 use Plack::Middleware::Session;
99 use Plack::Session::State;
102 return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello Foo' ] ];
107 state => Plack::Session::State->new;
113 This will maintain session state by passing the session through
114 the request params. It does not do this automatically though,
115 you are responsible for passing the session param.
117 This should be considered the state "base" class (although
118 subclassing is not a requirement) and defines the spec for
119 all B<Plack::Session::State::*> modules. You will only
120 need to override a couple methods if you do subclass. See
121 L<Plack::Session::State::Cookie> for an example of this.
127 =item B<new ( %params )>
129 The C<%params> can include I<session_key>, I<sid_generator> and I<sid_checker>
130 however in both cases a default will be provided for you.
134 This is the name of the session key, it default to 'plack_session'.
136 =item B<sid_generator>
138 This is a CODE ref used to generate unique session ids, by default
139 it will generate a SHA1 using fairly sufficient entropy. If you are
140 concerned or interested, just read the source.
142 =item B<sid_validator>
144 This is a regex used to validate requested session id,
148 =head2 Session ID Managment
152 =item B<get_session_id ( $request )>
154 Given a C<$request> this will first attempt to extract the session,
155 if the is expired or does not exist, it will then generate a new
156 session. The C<$request> is expected to be a L<Plack::Request> instance
157 or an object with an equivalent interface.
159 =item B<get_request_session_id ( $request )>
161 =item B<extract ( $request )>
163 This will attempt to extract the session from a C<$request> by looking
164 for the C<session_key> in the C<$request> params. It will then check to
165 see if the session has expired and return the session id if it is not.
166 The C<$request> is expected to be a L<Plack::Request> instance or an
167 object with an equivalent interface.
169 =item B<generate ( $request )>
171 This will generate a new session id using the C<sid_generator> callback.
172 The C<$request> argument is not used by this method but is there for
173 use by subclasses. The C<$request> is expected to be a L<Plack::Request>
174 instance or an object with an equivalent interface.
176 =item B<finalize ( $session_id, $response )>
178 Given a C<$session_id> and a C<$response> this will perform any
179 finalization nessecary to preserve state. This method is called by
180 the L<Plack::Session> C<finalize> method. The C<$response> is expected
181 to be a L<Plack::Response> instance or an object with an equivalent
186 =head2 Session Expiration Handling
190 =item B<expire_session_id ( $id )>
192 This will mark the session for C<$id> as expired. This method is called
193 by the L<Plack::Session> C<expire> method.
195 =item B<is_session_expired ( $id )>
197 This will check to see if the session C<$id> has been marked as
200 =item B<check_expired ( $id )>
202 Given an session C<$id> this will return C<undef> if the session is
203 expired or return the C<$id> if it is not.
209 All complex software has bugs lurking in it, and this module is no
210 exception. If you find a bug please either email me, or add the bug
215 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
217 =head1 COPYRIGHT AND LICENSE
219 Copyright 2009 Infinity Interactive, Inc.
221 L<http://www.iinteractive.com>
223 This library is free software; you can redistribute it and/or modify
224 it under the same terms as Perl itself.