expanded documentation of Catalyst::Plugin::Session::FastMmap

[catagits/Catalyst-Plugin-Session-State-Cookie.git] / FastMmap.pm

diff --git a/FastMmap.pm b/FastMmap.pm
index 5b5e460..6980639 100644 (file)
--- a/FastMmap.pm
+++ b/FastMmap.pm
@@ -9,7 +9,7 @@ use URI;
 use URI::Find;
 use File::Temp 'tempdir';
 
-our $VERSION = '0.04';
+our $VERSION = '0.13';
 
 __PACKAGE__->mk_classdata('_session');
 __PACKAGE__->mk_accessors('sessionid');
@@ -21,46 +21,65 @@ Catalyst::Plugin::Session::FastMmap - FastMmap sessions for Catalyst
 =head1 SYNOPSIS
 
     use Catalyst 'Session::FastMmap';
+    
+    MyApp->config->{session} = {
+        expires => 3600,
+        rewrite => 1,
+        storage => '/tmp/session'
+    };
 
     $c->session->{foo} = 'bar';
     print $c->sessionid;
 
 =head1 DESCRIPTION
 
-Fast sessions.
+C<Catalyst::Plugin::Session::FastMmap> is a fast session plugin for
+Catalyst that uses an mmap'ed file to act as a shared memory
+interprocess cache.  It is based on C<Cache::FastMMap>.
+
 
 =head2 EXTENDED METHODS
 
-=head3 finalize
+=over 4
+
+=item finalize
 
 =cut
 
 sub finalize {
-    my $c        = shift;
-    my $redirect = $c->response->redirect;
-    $c->response->redirect( $c->uri($redirect) ) if $redirect;
+    my $c = shift;
+    if ( $c->config->{session}->{rewrite} ) {
+        my $redirect = $c->response->redirect;
+        $c->response->redirect( $c->uri($redirect) ) if $redirect;
+    }
     if ( my $sid = $c->sessionid ) {
         $c->_session->set( $sid, $c->session );
         my $set = 1;
         if ( my $cookie = $c->request->cookies->{session} ) {
             $set = 0 if $cookie->value eq $sid;
         }
-        $c->response->cookies->{session} = { value => $sid } if $set;
-        my $finder = URI::Find->new(
-            sub {
-                my ( $uri, $orig ) = @_;
-                my $base = $c->request->base;
-                return $orig unless $orig =~ /^$base/;
-                return $orig if $uri->path =~ /\/-\//;
-                return $c->uri($orig);
-            }
-        );
-        $finder->find( \$c->response->{output} );
+        if ( $set ) {
+            $c->response->cookies->{session} = { 
+                value => $sid
+            };
+        }
+        if ( $c->config->{session}->{rewrite} ) {
+            my $finder = URI::Find->new(
+                sub {
+                    my ( $uri, $orig ) = @_;
+                    my $base = $c->request->base;
+                    return $orig unless $orig =~ /^$base/;
+                    return $orig if $uri->path =~ /\/-\//;
+                    return $c->uri($orig);
+                }
+            );
+            $finder->find( \$c->res->{body} ) if $c->res->body;
+        }
     }
     return $c->NEXT::finalize(@_);
 }
 
-=head3 prepare_action
+=item prepare_action
 
 =cut
 
@@ -83,7 +102,10 @@ sub session {
     my $c = shift;
     return $c->{session} if $c->{session};
     my $sid = $c->sessionid;
-    if ( $sid && ( $c->{session} = $c->_session->get($sid) ) ) {
+    if (   $sid
+        && $c->_session
+        && ( $c->{session} = $c->_session->get($sid) ) )
+    {
         $c->log->debug(qq/Found session "$sid"/) if $c->debug;
         return $c->{session};
     }
@@ -95,34 +117,37 @@ sub session {
     }
 }
 
-=head3 setup
+=item setup
+
+Sets up the session cache file.
 
 =cut
 
 sub setup {
-    my $self               = shift;
-    my $cache_root         = $self->config->{cache_root} || tempdir;
-    my $default_expires_in = $self->config->{default_expires_in}
-      || 60 * 60 * 24;
-    my $auto_purge_interval = $self->config->{auto_purge_interval}
-      || 60 * 60 * 24;
-    my $auto_purge_on_set = $self->config->{auto_purge_on_set} || 1;
+    my $self = shift;
+    $self->config->{session}->{storage} ||= '/tmp/session';
+    $self->config->{session}->{expires} ||= 60 * 60 * 24;
+    $self->config->{session}->{rewrite} ||= 0;
+
     $self->_session(
         Cache::FastMmap->new(
-            cache_root          => $cache_root,
-            default_expires_in  => $default_expires_in,
-            auto_purge_interval => $auto_purge_interval,
-            auto_purge_on_set   => $auto_purge_on_set
+            share_file  => $self->config->{session}->{storage},
+            expire_time => $self->config->{session}->{expires}
         )
     );
+
     return $self->NEXT::setup(@_);
 }
 
+=back
+
 =head2 METHODS
 
-=head3 session
+=over 4
+
+=item session
 
-=head3 uri
+=item uri
 
 Extends an uri with session id if needed.
 
@@ -142,18 +167,51 @@ sub uri {
     return $uri;
 }
 
+=back
+
+=head2 CONFIG OPTIONS
+
+=over 4
+
+=item rewrite
+
+If set to a true value sessions are automatically stored in the url;
+defaults to false.
+
+=item storage
+
+Specifies the file to be used for the sharing of session data;
+defaults to C</tmp/session>. 
+
+Note that the file will be created with mode 0640, which means that it
+will only be writeable by processes running with the same uid as the
+process that creates the file.  If this may be a problem, for example
+if you may try to debug the program as one user and run it as another,
+specify a filename like C<< /tmp/session-$> >>, which includes the
+UID of the process in the filename.
+
+
+=item expires
+
+Specifies the session expiry time in seconds; defaults to 86,400,
+i.e. one day.
+
+=back
+
 =head1 SEE ALSO
 
-L<Catalyst>.
+L<Catalyst>, L<Cache::FastMmap>.
 
 =head1 AUTHOR
 
-Sebastian Riedel, C<sri@cpan.org>
+Sebastian Riedel E<lt>C<sri@cpan.org>E<gt>,
+Marcus Ramberg E<lt>C<mramberg@cpan.org>E<gt>,
+Andrew Ford E<lt>C<andrewf@cpan.org>E<gt>
 
 =head1 COPYRIGHT
 
-This program is free software, you can redistribute it and/or modify it under
-the same terms as Perl itself.
+This program is free software, you can redistribute it and/or modify it
+under the same terms as Perl itself.
 
 =cut