lib/Plack/Session/State.pm

   1 package Plack::Session::State;
   2 use strict;
   3 use warnings;
   4
   5 use Digest::SHA1 ();
   6
   7 use Plack::Util::Accessor qw[
   8     session_key
   9     sid_generator
  10 ];
  11
  12 sub new {
  13     my ($class, %params) = @_;
  14
  15     $params{'_expired'}      ||= +{};
  16     $params{'session_key'}   ||= 'plack_session';
  17     $params{'sid_generator'} ||= sub {
  18         Digest::SHA1::sha1_hex(rand() . $$ . {} . time)
  19     };
  20
  21     bless { %params } => $class;
  22 }
  23
  24 sub expire_session_id {
  25     my ($self, $id) = @_;
  26     $self->{'_expired'}->{ $id }++;
  27 }
  28
  29 sub is_session_expired {
  30     my ($self, $id) = @_;
  31     exists $self->{'_expired'}->{ $id }
  32 }
  33
  34 sub check_expired {
  35     my ($self, $id) = @_;
  36     return unless $id && not $self->is_session_expired( $id );
  37     return $id;
  38 }
  39
  40 sub get_session_id {
  41     my ($self, $request) = @_;
  42     $self->extract( $request )
  43         ||
  44     $self->generate( $request )
  45 }
  46
  47 sub extract {
  48     my ($self, $request) = @_;
  49     $self->check_expired( $request->param( $self->session_key ) );
  50 }
  51
  52 sub generate {
  53     my $self = shift;
  54     $self->sid_generator->( @_ );
  55 }
  56
  57
  58 sub finalize {
  59     my ($self, $id, $response) = @_;
  60     ();
  61 }
  62
  63 1;
  64
  65 __END__
  66
  67 =pod
  68
  69 =head1 NAME
  70
  71 Plack::Session::State - Basic parameter-based session state
  72
  73 =head1 SYNOPSIS
  74
  75   use Plack::Builder;
  76   use Plack::Middleware::Session;
  77   use Plack::Session::State;
  78
  79   my $app = sub {
  80       return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello Foo' ] ];
  81   };
  82
  83   builder {
  84       enable 'Session',
  85           state => Plack::Session::State->new;
  86       $app;
  87   };
  88
  89 =head1 DESCRIPTION
  90
  91 This will maintain session state by passing the session through
  92 the request params. It does not do this automatically though,
  93 you are responsible for passing the session param.
  94
  95 This should be considered the state "base" class (although
  96 subclassing is not a requirement) and defines the spec for
  97 all B<Plack::Session::State::*> modules. You will only
  98 need to override a couple methods if you do subclass. See
  99 L<Plack::Session::State::Cookie> for an example of this.
 100
 101 =head1 METHODS
 102
 103 =over 4
 104
 105 =item B<new ( %params )>
 106
 107 The C<%params> can include I<session_key> and I<sid_generator>,
 108 however in both cases a default will be provided for you.
 109
 110 =item B<session_key>
 111
 112 This is the name of the session key, it default to 'plack_session'.
 113
 114 =item B<sid_generator>
 115
 116 This is a CODE ref used to generate unique session ids, by default
 117 it will generate a SHA1 using fairly sufficient entropy. If you are
 118 concerned or interested, just read the source.
 119
 120 =back
 121
 122 =head2 Session ID Managment
 123
 124 =over 4
 125
 126 =item B<get_session_id ( $request )>
 127
 128 Given a C<$request> this will first attempt to extract the session,
 129 if the is expired or does not exist, it will then generate a new
 130 session. The C<$request> is expected to be a L<Plack::Request> instance
 131 or an object with an equivalent interface.
 132
 133 =item B<extract ( $request )>
 134
 135 This will attempt to extract the session from a C<$request> by looking
 136 for the C<session_key> in the C<$request> params. It will then check to
 137 see if the session has expired and return the session id if it is not.
 138 The C<$request> is expected to be a L<Plack::Request> instance or an
 139 object with an equivalent interface.
 140
 141 =item B<generate ( $request )>
 142
 143 This will generate a new session id using the C<sid_generator> callback.
 144 The C<$request> argument is not used by this method but is there for
 145 use by subclasses. The C<$request> is expected to be a L<Plack::Request>
 146 instance or an object with an equivalent interface.
 147
 148 =item B<finalize ( $session_id, $response )>
 149
 150 Given a C<$session_id> and a C<$response> this will perform any
 151 finalization nessecary to preserve state. This method is called by
 152 the L<Plack::Session> C<finalize> method. The C<$response> is expected
 153 to be a L<Plack::Response> instance or an object with an equivalent
 154 interface.
 155
 156 =back
 157
 158 =head2 Session Expiration Handling
 159
 160 =over 4
 161
 162 =item B<expire_session_id ( $id )>
 163
 164 This will mark the session for C<$id> as expired. This method is called
 165 by the L<Plack::Session> C<expire> method.
 166
 167 =item B<is_session_expired ( $id )>
 168
 169 This will check to see if the session C<$id> has been marked as
 170 expired.
 171
 172 =item B<check_expired ( $id )>
 173
 174 Given an session C<$id> this will return C<undef> if the session is
 175 expired or return the C<$id> if it is not.
 176
 177 =back
 178
 179 =head1 BUGS
 180
 181 All complex software has bugs lurking in it, and this module is no
 182 exception. If you find a bug please either email me, or add the bug
 183 to cpan-RT.
 184
 185 =head1 AUTHOR
 186
 187 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
 188
 189 =head1 COPYRIGHT AND LICENSE
 190
 191 Copyright 2009 Infinity Interactive, Inc.
 192
 193 L<http://www.iinteractive.com>
 194
 195 This library is free software; you can redistribute it and/or modify
 196 it under the same terms as Perl itself.
 197
 198 =cut
 199
 200