lib/Plack/Session/State.pm

   1 package Plack::Session::State;
   2 use strict;
   3 use warnings;
   4
   5 our $VERSION   = '0.03';
   6 our $AUTHORITY = 'cpan:STEVAN';
   7
   8 use Digest::SHA1 ();
   9
  10 use Plack::Util::Accessor qw[
  11     session_key
  12     sid_generator
  13     sid_validator
  14 ];
  15
  16 sub new {
  17     my ($class, %params) = @_;
  18
  19     $params{'session_key'}   ||= 'plack_session';
  20     $params{'sid_generator'} ||= sub {
  21         Digest::SHA1::sha1_hex(rand() . $$ . {} . time)
  22     };
  23     $params{'sid_validator'} ||= qr/\A[0-9a-f]{40}\Z/;
  24
  25     bless { %params } => $class;
  26 }
  27
  28 sub expire_session_id {
  29     my ($self, $id, $response) = @_;
  30 }
  31
  32 sub validate_session_id {
  33     my ($self, $id) = @_;
  34     $id =~ $self->sid_validator;
  35 }
  36
  37 sub get_session_id {
  38     my ($self, $request) = @_;
  39     return $request->param( $self->session_key );
  40 }
  41
  42 sub extract {
  43     my ($self, $request) = @_;
  44
  45     my $id = $self->get_session_id( $request );
  46     return unless defined $id;
  47
  48     return $id if $self->validate_session_id( $id );
  49     return;
  50 }
  51
  52 sub generate {
  53     my $self = shift;
  54     $self->sid_generator->( @_ );
  55 }
  56
  57
  58 sub finalize {
  59     my ($self, $id, $response, $options) = @_;
  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>, I<sid_generator> and I<sid_checker>
 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 =item B<sid_validator>
 121
 122 This is a regex used to validate requested session id.
 123
 124 =back
 125
 126 =head2 Session ID Managment
 127
 128 =over 4
 129
 130 =item B<get_session_id ( $request )>
 131
 132 This is the method used to extract the session id from a C<$request>.
 133 Subclasses will often only need to override this method and the
 134 C<finalize> method.
 135
 136 =item B<validate_session_id ( $session_id )>
 137
 138 This will use the C<sid_validator> regex and confirm that the
 139 C<$session_id> is valid.
 140
 141 =item B<extract ( $request )>
 142
 143 This will attempt to extract the session from a C<$request> by looking
 144 for the C<session_key> in the C<$request> params. It will then check to
 145 see if the session is valid and that it has not expired. It will return
 146 the session id if everything is good or undef otherwise. The C<$request>
 147 is expected to be a L<Plack::Request> instance or an object with an
 148 equivalent interface.
 149
 150 =item B<generate ( $request )>
 151
 152 This will generate a new session id using the C<sid_generator> callback.
 153 The C<$request> argument is not used by this method but is there for
 154 use by subclasses. The C<$request> is expected to be a L<Plack::Request>
 155 instance or an object with an equivalent interface.
 156
 157 =item B<finalize ( $session_id, $response )>
 158
 159 Given a C<$session_id> and a C<$response> this will perform any
 160 finalization nessecary to preserve state. This method is called by
 161 the L<Plack::Session> C<finalize> method. The C<$response> is expected
 162 to be a L<Plack::Response> instance or an object with an equivalent
 163 interface.
 164
 165 =back
 166
 167 =head2 Session Expiration Handling
 168
 169 =over 4
 170
 171 =item B<expire_session_id ( $id, $response )>
 172
 173 This will mark the session for C<$id> as expired. This method is called
 174 by the L<Plack::Session> C<expire> method.
 175
 176 =back
 177
 178 =head1 BUGS
 179
 180 All complex software has bugs lurking in it, and this module is no
 181 exception. If you find a bug please either email me, or add the bug
 182 to cpan-RT.
 183
 184 =head1 AUTHOR
 185
 186 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
 187
 188 =head1 COPYRIGHT AND LICENSE
 189
 190 Copyright 2009, 2010 Infinity Interactive, Inc.
 191
 192 L<http://www.iinteractive.com>
 193
 194 This library is free software; you can redistribute it and/or modify
 195 it under the same terms as Perl itself.
 196
 197 =cut
 198
 199