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 $self->extract( $request )
54 $self->generate( $request )
57 sub get_session_id_from_request {
58 my ($self, $request) = @_;
59 $request->param( $self->session_key );
63 my ($self, $request) = @_;
65 my $id = $self->get_session_id_from_request( $request );
66 return unless defined $id;
68 $self->validate_session_id( $id )
70 $self->check_expired( $id );
75 $self->sid_generator->( @_ );
80 my ($self, $id, $response) = @_;
92 Plack::Session::State - Basic parameter-based session state
97 use Plack::Middleware::Session;
98 use Plack::Session::State;
101 return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello Foo' ] ];
106 state => Plack::Session::State->new;
112 This will maintain session state by passing the session through
113 the request params. It does not do this automatically though,
114 you are responsible for passing the session param.
116 This should be considered the state "base" class (although
117 subclassing is not a requirement) and defines the spec for
118 all B<Plack::Session::State::*> modules. You will only
119 need to override a couple methods if you do subclass. See
120 L<Plack::Session::State::Cookie> for an example of this.
126 =item B<new ( %params )>
128 The C<%params> can include I<session_key>, I<sid_generator> and I<sid_checker>
129 however in both cases a default will be provided for you.
133 This is the name of the session key, it default to 'plack_session'.
135 =item B<sid_generator>
137 This is a CODE ref used to generate unique session ids, by default
138 it will generate a SHA1 using fairly sufficient entropy. If you are
139 concerned or interested, just read the source.
141 =item B<sid_validator>
143 This is a regex used to validate requested session id.
147 =head2 Session ID Managment
151 =item B<get_session_id ( $request )>
153 Given a C<$request> this will first attempt to extract the session,
154 if the is expired or does not exist, it will then generate a new
155 session. The C<$request> is expected to be a L<Plack::Request> instance
156 or an object with an equivalent interface.
158 =item B<get_session_id_from_request ( $request )>
160 This is the method used to extract the session id from a C<$request>.
161 Subclasses will often only need to override this method and the
164 =item B<validate_session_id ( $session_id )>
166 This will use the C<sid_validator> regex and confirm that the
167 C<$session_id> is valid.
169 =item B<extract ( $request )>
171 This will attempt to extract the session from a C<$request> by looking
172 for the C<session_key> in the C<$request> params. It will then check to
173 see if the session is valid and that it has not expired. It will return
174 the session id if everything is good or undef otherwise. The C<$request>
175 is expected to be a L<Plack::Request> instance or an object with an
176 equivalent interface.
178 =item B<generate ( $request )>
180 This will generate a new session id using the C<sid_generator> callback.
181 The C<$request> argument is not used by this method but is there for
182 use by subclasses. The C<$request> is expected to be a L<Plack::Request>
183 instance or an object with an equivalent interface.
185 =item B<finalize ( $session_id, $response )>
187 Given a C<$session_id> and a C<$response> this will perform any
188 finalization nessecary to preserve state. This method is called by
189 the L<Plack::Session> C<finalize> method. The C<$response> is expected
190 to be a L<Plack::Response> instance or an object with an equivalent
195 =head2 Session Expiration Handling
199 =item B<expire_session_id ( $id )>
201 This will mark the session for C<$id> as expired. This method is called
202 by the L<Plack::Session> C<expire> method.
204 =item B<is_session_expired ( $id )>
206 This will check to see if the session C<$id> has been marked as
209 =item B<check_expired ( $id )>
211 Given an session C<$id> this will return C<undef> if the session is
212 expired or return the C<$id> if it is not.
218 All complex software has bugs lurking in it, and this module is no
219 exception. If you find a bug please either email me, or add the bug
224 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
226 =head1 COPYRIGHT AND LICENSE
228 Copyright 2009 Infinity Interactive, Inc.
230 L<http://www.iinteractive.com>
232 This library is free software; you can redistribute it and/or modify
233 it under the same terms as Perl itself.