lib/Plack/Session/State.pm

   1 package Plack::Session::State;
   2 use strict;
   3 use warnings;
   4
   5 our $VERSION   = '0.13';
   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, $res) = @_;
  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, $env) = @_;
  39     return Plack::Request->new($env)->param( $self->session_key );
  40 }
  41
  42 sub extract {
  43     my ($self, $env) = @_;
  44
  45     my $id = $self->get_session_id( $env );
  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, $res, $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 B<WARNING>: parameter based session ID management makes session
 102 fixation really easy, and that makes your website vulnerable. You
 103 should really avoid using this state in the production environment
 104 except when you have to deal with legacy HTTP clients that do not
 105 support cookies.
 106
 107 In the future this parameter based state handling will be removed from
 108 this base class and will be moved to its own State class.
 109
 110 =head1 METHODS
 111
 112 =over 4
 113
 114 =item B<new ( %params )>
 115
 116 The C<%params> can include I<session_key>, I<sid_generator> and I<sid_checker>
 117 however in both cases a default will be provided for you.
 118
 119 =item B<session_key>
 120
 121 This is the name of the session key, it defaults to 'plack_session'.
 122
 123 =item B<sid_generator>
 124
 125 This is a CODE ref used to generate unique session ids, by default
 126 it will generate a SHA1 using fairly sufficient entropy. If you are
 127 concerned or interested, just read the source.
 128
 129 =item B<sid_validator>
 130
 131 This is a regex used to validate requested session id.
 132
 133 =back
 134
 135 =head2 Session ID Managment
 136
 137 =over 4
 138
 139 =item B<get_session_id ( $env )>
 140
 141 This is the method used to extract the session id from a C<$env>.
 142 Subclasses will often only need to override this method and the
 143 C<finalize> method.
 144
 145 =item B<validate_session_id ( $session_id )>
 146
 147 This will use the C<sid_validator> regex and confirm that the
 148 C<$session_id> is valid.
 149
 150 =item B<extract ( $env )>
 151
 152 This will attempt to extract the session from a C<$env> by looking
 153 for the C<session_key> in the request params. It will then check to
 154 see if the session is valid and that it has not expired. It will return
 155 the session id if everything is good or undef otherwise.
 156
 157 =item B<generate ( $request )>
 158
 159 This will generate a new session id using the C<sid_generator> callback.
 160 The C<$request> argument is not used by this method but is there for
 161 use by subclasses. The C<$request> is expected to be a L<Plack::Request>
 162 instance or an object with an equivalent interface.
 163
 164 =item B<finalize ( $session_id, $response )>
 165
 166 Given a C<$session_id> and a C<$response> this will perform any
 167 finalization necessary to preserve state. This method is called by
 168 the L<Plack::Session> C<finalize> method. The C<$response> is expected
 169 to be a L<Plack::Response> instance or an object with an equivalent
 170 interface.
 171
 172 =back
 173
 174 =head2 Session Expiration Handling
 175
 176 =over 4
 177
 178 =item B<expire_session_id ( $id, $response )>
 179
 180 This will mark the session for C<$id> as expired. This method is called
 181 by the L<Plack::Session> C<expire> method.
 182
 183 =back
 184
 185 =head1 BUGS
 186
 187 All complex software has bugs lurking in it, and this module is no
 188 exception. If you find a bug please either email me, or add the bug
 189 to cpan-RT.
 190
 191 =head1 AUTHOR
 192
 193 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
 194
 195 =head1 COPYRIGHT AND LICENSE
 196
 197 Copyright 2009, 2010 Infinity Interactive, Inc.
 198
 199 L<http://www.iinteractive.com>
 200
 201 This library is free software; you can redistribute it and/or modify
 202 it under the same terms as Perl itself.
 203
 204 =cut
 205
 206