1 package Plack::Session::State;
6 our $AUTHORITY = 'cpan:STEVAN';
10 use Plack::Util::Accessor qw[
17 my ($class, %params) = @_;
19 $params{'_expired'} ||= +{};
20 $params{'session_key'} ||= 'plack_session';
21 $params{'sid_generator'} ||= sub {
22 Digest::SHA1::sha1_hex(rand() . $$ . {} . time)
24 $params{'sid_validator'} ||= qr/\A[0-9a-f]{40}\Z/;
26 bless { %params } => $class;
29 sub expire_session_id {
31 $self->{'_expired'}->{ $id }++;
34 sub is_session_expired {
36 exists $self->{'_expired'}->{ $id }
41 return if $self->is_session_expired( $id );
45 sub validate_session_id {
47 $id =~ $self->sid_validator;
51 my ($self, $request) = @_;
52 return $request->param( $self->session_key );
56 my ($self, $request) = @_;
58 my $id = $self->get_session_id( $request );
59 return unless defined $id;
61 $self->validate_session_id( $id )
63 $self->check_expired( $id );
68 $self->sid_generator->( @_ );
73 my ($self, $id, $response) = @_;
85 Plack::Session::State - Basic parameter-based session state
90 use Plack::Middleware::Session;
91 use Plack::Session::State;
94 return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello Foo' ] ];
99 state => Plack::Session::State->new;
105 This will maintain session state by passing the session through
106 the request params. It does not do this automatically though,
107 you are responsible for passing the session param.
109 This should be considered the state "base" class (although
110 subclassing is not a requirement) and defines the spec for
111 all B<Plack::Session::State::*> modules. You will only
112 need to override a couple methods if you do subclass. See
113 L<Plack::Session::State::Cookie> for an example of this.
119 =item B<new ( %params )>
121 The C<%params> can include I<session_key>, I<sid_generator> and I<sid_checker>
122 however in both cases a default will be provided for you.
126 This is the name of the session key, it default to 'plack_session'.
128 =item B<sid_generator>
130 This is a CODE ref used to generate unique session ids, by default
131 it will generate a SHA1 using fairly sufficient entropy. If you are
132 concerned or interested, just read the source.
134 =item B<sid_validator>
136 This is a regex used to validate requested session id.
140 =head2 Session ID Managment
144 =item B<get_session_id ( $request )>
146 This is the method used to extract the session id from a C<$request>.
147 Subclasses will often only need to override this method and the
150 =item B<validate_session_id ( $session_id )>
152 This will use the C<sid_validator> regex and confirm that the
153 C<$session_id> is valid.
155 =item B<extract ( $request )>
157 This will attempt to extract the session from a C<$request> by looking
158 for the C<session_key> in the C<$request> params. It will then check to
159 see if the session is valid and that it has not expired. It will return
160 the session id if everything is good or undef otherwise. The C<$request>
161 is expected to be a L<Plack::Request> instance or an object with an
162 equivalent interface.
164 =item B<generate ( $request )>
166 This will generate a new session id using the C<sid_generator> callback.
167 The C<$request> argument is not used by this method but is there for
168 use by subclasses. The C<$request> is expected to be a L<Plack::Request>
169 instance or an object with an equivalent interface.
171 =item B<finalize ( $session_id, $response )>
173 Given a C<$session_id> and a C<$response> this will perform any
174 finalization nessecary to preserve state. This method is called by
175 the L<Plack::Session> C<finalize> method. The C<$response> is expected
176 to be a L<Plack::Response> instance or an object with an equivalent
181 =head2 Session Expiration Handling
185 =item B<expire_session_id ( $id )>
187 This will mark the session for C<$id> as expired. This method is called
188 by the L<Plack::Session> C<expire> method.
190 =item B<is_session_expired ( $id )>
192 This will check to see if the session C<$id> has been marked as
195 =item B<check_expired ( $id )>
197 Given an session C<$id> this will return C<undef> if the session is
198 expired or return the C<$id> if it is not.
204 All complex software has bugs lurking in it, and this module is no
205 exception. If you find a bug please either email me, or add the bug
210 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
212 =head1 COPYRIGHT AND LICENSE
214 Copyright 2009, 2010 Infinity Interactive, Inc.
216 L<http://www.iinteractive.com>
218 This library is free software; you can redistribute it and/or modify
219 it under the same terms as Perl itself.