lib/Plack/Session/State.pm

   1 package Plack::Session::State;
   2 use strict;
   3 use warnings;
   4
   5 our $VERSION   = '0.09_01';
   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 =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 ( $env )>
 131
 132 This is the method used to extract the session id from a C<$env>.
 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 ( $env )>
 142
 143 This will attempt to extract the session from a C<$env> by looking
 144 for the C<session_key> in the 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.
 147
 148 =item B<generate ( $request )>
 149
 150 This will generate a new session id using the C<sid_generator> callback.
 151 The C<$request> argument is not used by this method but is there for
 152 use by subclasses. The C<$request> is expected to be a L<Plack::Request>
 153 instance or an object with an equivalent interface.
 154
 155 =item B<finalize ( $session_id, $response )>
 156
 157 Given a C<$session_id> and a C<$response> this will perform any
 158 finalization nessecary to preserve state. This method is called by
 159 the L<Plack::Session> C<finalize> method. The C<$response> is expected
 160 to be a L<Plack::Response> instance or an object with an equivalent
 161 interface.
 162
 163 =back
 164
 165 =head2 Session Expiration Handling
 166
 167 =over 4
 168
 169 =item B<expire_session_id ( $id, $response )>
 170
 171 This will mark the session for C<$id> as expired. This method is called
 172 by the L<Plack::Session> C<expire> method.
 173
 174 =back
 175
 176 =head1 BUGS
 177
 178 All complex software has bugs lurking in it, and this module is no
 179 exception. If you find a bug please either email me, or add the bug
 180 to cpan-RT.
 181
 182 =head1 AUTHOR
 183
 184 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
 185
 186 =head1 COPYRIGHT AND LICENSE
 187
 188 Copyright 2009, 2010 Infinity Interactive, Inc.
 189
 190 L<http://www.iinteractive.com>
 191
 192 This library is free software; you can redistribute it and/or modify
 193 it under the same terms as Perl itself.
 194
 195 =cut
 196
 197