Checking in changes prior to tagging of version 0.14.

[catagits/Web-Session.git] / lib / Plack / Session / State.pm

diff --git a/lib/Plack/Session/State.pm b/lib/Plack/Session/State.pm
index b369cd3..ed470d1 100644 (file)
--- a/lib/Plack/Session/State.pm
+++ b/lib/Plack/Session/State.pm
@@ -2,7 +2,7 @@ package Plack::Session::State;
 use strict;
 use warnings;
 
-our $VERSION   = '0.03';
+our $VERSION   = '0.14';
 our $AUTHORITY = 'cpan:STEVAN';
 
 use Digest::SHA1 ();
@@ -26,7 +26,7 @@ sub new {
 }
 
 sub expire_session_id {
-    my ($self, $id, $response) = @_;
+    my ($self, $id, $res) = @_;
 }
 
 sub validate_session_id {
@@ -35,14 +35,14 @@ sub validate_session_id {
 }
 
 sub get_session_id {
-    my ($self, $request) = @_;
-    return $request->param( $self->session_key );
+    my ($self, $env) = @_;
+    return Plack::Request->new($env)->param( $self->session_key );
 }
 
 sub extract {
-    my ($self, $request) = @_;
+    my ($self, $env) = @_;
 
-    my $id = $self->get_session_id( $request );
+    my $id = $self->get_session_id( $env );
     return unless defined $id;
 
     return $id if $self->validate_session_id( $id );
@@ -56,7 +56,7 @@ sub generate {
 
 
 sub finalize {
-    my ($self, $id, $response, $options) = @_;
+    my ($self, $id, $res, $options) = @_;
     ();
 }
 
@@ -98,6 +98,15 @@ all B<Plack::Session::State::*> modules. You will only
 need to override a couple methods if you do subclass. See
 L<Plack::Session::State::Cookie> for an example of this.
 
+B<WARNING>: parameter based session ID management makes session
+fixation really easy, and that makes your website vulnerable. You
+should really avoid using this state in the production environment
+except when you have to deal with legacy HTTP clients that do not
+support cookies.
+
+In the future this parameter based state handling will be removed from
+this base class and will be moved to its own State class.
+
 =head1 METHODS
 
 =over 4
@@ -109,7 +118,7 @@ however in both cases a default will be provided for you.
 
 =item B<session_key>
 
-This is the name of the session key, it default to 'plack_session'.
+This is the name of the session key, it defaults to 'plack_session'.
 
 =item B<sid_generator>
 
@@ -127,9 +136,9 @@ This is a regex used to validate requested session id.
 
 =over 4
 
-=item B<get_session_id ( $request )>
+=item B<get_session_id ( $env )>
 
-This is the method used to extract the session id from a C<$request>.
+This is the method used to extract the session id from a C<$env>.
 Subclasses will often only need to override this method and the
 C<finalize> method.
 
@@ -138,14 +147,12 @@ C<finalize> method.
 This will use the C<sid_validator> regex and confirm that the
 C<$session_id> is valid.
 
-=item B<extract ( $request )>
+=item B<extract ( $env )>
 
-This will attempt to extract the session from a C<$request> by looking
-for the C<session_key> in the C<$request> params. It will then check to
+This will attempt to extract the session from a C<$env> by looking
+for the C<session_key> in the request params. It will then check to
 see if the session is valid and that it has not expired. It will return
-the session id if everything is good or undef otherwise. The C<$request>
-is expected to be a L<Plack::Request> instance or an object with an
-equivalent interface.
+the session id if everything is good or undef otherwise.
 
 =item B<generate ( $request )>
 
@@ -157,7 +164,7 @@ instance or an object with an equivalent interface.
 =item B<finalize ( $session_id, $response )>
 
 Given a C<$session_id> and a C<$response> this will perform any
-finalization nessecary to preserve state. This method is called by
+finalization necessary to preserve state. This method is called by
 the L<Plack::Session> C<finalize> method. The C<$response> is expected
 to be a L<Plack::Response> instance or an object with an equivalent
 interface.