Cook results from the CPAN

Cook

Apache-SessionManager

view release on metacpan or search on metacpan

	! Substituted each STDERR prints with $r->log_error mod_perl API calls
	! Bug fix: SessionManagerHeaderExclude skips check when header or its value
	  is undefined
	! Tested also with latest Apache/mod_perl release (2.0.52/1.99_17)
	
1.02    Tue Jun 19 12:00:00 2004
	+ Added SessionManagerHeaderExclude directive in order to exclude
	  incoming request containing particular header content
	+ Added SessionManagerIPExclude directive in order to exclude
	  incoming request matching remote IP
	+ Added compatibilty to libapreq2 (Apache::Cookie API differs from libapreq1
	  implementation). Thanks to Mike Whitaker <mike@wisdengroup.com> for 
	  reporting this
	! Bug fix (since 1.99_14): fix cleanup_register call. Thanks to Blair Sutton 
	  <bsdz@numeninest.com>
	! Removed a STDERR debug print
	! Updated docs and test for new features

1.01    Fri Jan 23 15:00:00 2004
	! Bug fix: port to MP2 Apache::URI->parse call to APR::URI->parse
	! Update cookpood. Fix pod tags. Moved all '=for html' sections.

Changes view on Meta::CPAN

	! Removed an exit() command from Makefile.PL in order to work with 
	  cpan/cpanplus shell when auto-installing required modules
	! Update NAME section in cookpod to Apache::SessionManager::cookpod
	! Minor corrections to cookpod 
	! Uncommentend __END__ line in SessionManager.pm - why it was commented? :-)

0.05    Thu Jul 10 20:00:00 2003
	+ Added syntax control over SessionManagerExpire directive. An explicit '0' 
	  value means no expiration time (if undefined the default value is 3600)
	+ Added syntax control over SessionManagerInactivity directive
	+ Removed dependency from Apache::Cookie. CGI::Cookie will be used instead
	  of Apache::Cookie if libapreq aren't installed
	+ Added Apache::SessionManager::cookpod pod HOWTO 
	+ Added PLP.pm patch (patches/PLP-3.18.patch) to add direcly $session into 
	  PLP Perl embedder
	+ Added patch (patches/Apache-Session-1.54-patch) for
	  Apache::Session::Lock::File
	+ Added authentication test handler t/lib/MyAuth.pm to show how 
	  Apache::SessionManager can work with authentication (see perldoc
	  Apache::SessionManager::cookpod)
	! Modified test handler t/lib/PrintEnv.pm to print $session dump
	! Updated module docs, added sections
	! Updated test and docs

0.04    Tue Oct 16 20:00:00 2002
	+ Set '/' as default path attribute for session cookies
	! Updated Makefile.PL in order to skip generation of Apache test section
	  in Makefile if 'use Apache::test' fails (notice by Jeroen Latour 
	  <jlatour@www.arens.nl>) 
	! Updated t/01real.t in order to skip it if 'use Apache::test' fails.

0.03    Wed Oct 04 12:00:00 2002
	+ Added 'SessionManagerCookieArgs' PerlSetVar directive in order to 
	  set cookie optional attributes.
	+ Added experimental support 'SessionManagerEnableModBackhand' 
	  PerlSetVar directive in order to support mod_backhand sticky 
	  cookie session load balancing.
	! Updated Makefile.PL httpd.conf extra lines
	! Updated docs (added pod for new directive 'SessionManagerCookieArgs')

0.02    Mon Sep 02 17:00:00 2002
	+ Added control to bypass expiration time check in new sessions
	+ Use of session in test handler t/lib/PrintEnv.pm
	+ Added successfully tested platforms in POD [BUGS] section
	! Corrected print on STDERR in _tieSession 
	! Corrected Makefile.PL httpd.conf extra lines
	! Updated pod (moved PerlTransHandler outside <Location> section in
	  a configuration example!)

Makefile.PL view on Meta::CPAN

#    die "Usage: $0 [-n]\n";
#}   

my($errors, $warnings);
my $necessary_modules = {
#	'Apache' => 'The Apache Perl API',
	'Apache::Session 1.54' => 'A persistence framework for session data'
};

my $optional_modules = {
	'Apache::Request 0.33' => 'Apache API to manage HTTP cookies (CGI::Cookie will be used instead)',
	'CGI::Cookie' => 'CGI library to manage HTTP cookies (used only if Apache::Request isn\'t installed)'
};

print "Checking for REQUIRED modules...\n";

# Check mod_perl version
my ($mp1,$mp2) = which_mod_perl();
print " --> mod_perl... ";
if ( ! $mp1 && ! $mp2 ) {
	$errors++;
	print "NOT FOUND\n";

Makefile.PL view on Meta::CPAN

PerlSetVar SessionManagerTracking On
PerlSetVar SessionManagerDebug 5

# These documents require cookies session
<Location /session>
	SetHandler perl-script
	PerlHandler PrintEnv
	PerlSetVar SessionManagerExpire 0
	PerlSetVar SessionManagerStore File
	PerlSetVar SessionManagerLock Null
	PerlSetVar SessionManagerCookieArgs "Path => /session, Secure => 0, Extras => some_value"
	PerlSetVar SessionManagerStoreArgs "Directory => /tmp"
	PerlSetVar SessionManagerSetEnv On
</Location>

# These documents require cookies session (OO Apache::SessionManager interface)
<Location /session-OO>
	SetHandler perl-script
	PerlHandler PrintEnvOO
	PerlSetVar SessionManagerStore File
	PerlSetVar SessionManagerLock Null
	PerlSetVar SessionManagerCookieArgs "Path => /session-OO, Secure => 0, Extras => some_value"
	PerlSetVar SessionManagerStoreArgs "Directory => /tmp"
	PerlSetVar SessionManagerSetEnv On
</Location>

# These documents require cookies session (OO Apache::SessionManager interface)
# with header exclusion list
<Location /session-header_exclude>
	SetHandler perl-script
	PerlHandler PrintEnvOO
	PerlSetVar SessionManagerStore File
	PerlSetVar SessionManagerLock Null
	PerlSetVar SessionManagerCookieArgs "Path => /session-header_exclude, Secure => 0"
	PerlSetVar SessionManagerStoreArgs "Directory => /tmp"
	PerlSetVar SessionManagerSetEnv On
	PerlSetVar SessionManagerHeaderExclude "User-Agent = > Opera\s*\d"
	PerlAddVar SessionManagerHeaderExclude "User-Agent => lynx"
	PerlAddVar SessionManagerHeaderExclude "Referer => ^http://localhost"		  
</Location>

# These documents require cookies session (OO Apache::SessionManager interface)
# with ip exclusion list
<Location /session-ip_exclude>
	SetHandler perl-script
	PerlHandler PrintEnvOO
	PerlSetVar SessionManagerStore File
	PerlSetVar SessionManagerLock Null
	PerlSetVar SessionManagerCookieArgs "Path => /session-ip_exclude, Secure => 0"
	PerlSetVar SessionManagerStoreArgs "Directory => /tmp"
	PerlSetVar SessionManagerSetEnv On
	PerlSetVar SessionManagerIPExclude "192.168.0.1 127.0.0.0/8"
</Location>

# These documents require cookies session w/authentication
<Location /session-auth>
	SetHandler perl-script
	PerlHandler PrintEnv
	PerlSetVar SessionManagerStore File
	PerlSetVar SessionManagerLock Null
	PerlSetVar SessionManagerCookieArgs "Path => /session-auth, Secure => 0"
	PerlSetVar SessionManagerStoreArgs "Directory => /tmp"
	PerlSetVar SessionManagerSetEnv On

	AuthName "Reserved Club"
	AuthType Basic
	require valid-user
	PerlAuthenHandler MyAuth
	PerlSetVar MyAuthLogin /protected/login.html 
</Location>

Makefile.PL view on Meta::CPAN

	PerlSetVar SessionManagerStoreArgs "Directory => /tmp"
	PerlSetVar SessionManagerSetEnv On
</LocationMatch>

# These documents require cookies session + mod_backhand cookie load-balancing
<Location /session-bh>
	SetHandler perl-script
	PerlHandler PrintEnv
	PerlSetVar SessionManagerStore File
	PerlSetVar SessionManagerLock Null
	PerlSetVar SessionManagerCookieArgs "Path => /session-bh"
	PerlSetVar SessionManagerStoreArgs "Directory => /tmp"
	PerlSetVar SessionManagerEnableModBackhand On
	PerlSetVar SessionManagerSetEnv On
</Location>


# These documents don't require cookies session
<Location /no-session>
	SetHandler perl-script
	PerlHandler PrintEnv

Makefile.PL view on Meta::CPAN

<IfDefine DBI>
	PerlModule Apache::DBI
	<Location /session-OO-DBI>
		SetHandler perl-script
		PerlHandler PrintEnvOO
		PerlSetVar SessionManagerName SESSION-MySQL
		PerlSetVar SessionManagerStore MySQL
		PerlSetVar SessionManagerStoreArgs "DataSource => dbi:mysql:sessions, \
		                                    UserName   => sesman, \
		                                    Password   => sesman"
		PerlSetVar SessionManagerCookieArgs "Path => /session-OO-DBI"
		PerlSetVar SessionManagerSetEnv On
	</Location>
</IfDefine>

README view on Meta::CPAN

     Password: *******
   % make install

Prerequisites
-------------
- mod_perl (of course) >= 1.24 with the appropriate call-back hooks (PERL_TRANS=1,
  PERL_HEADER_PARSER=1)
- Apache::Session >= 0.53 is required
     (http://www.cpan.org/modules/by-module/Apache/Apache-Session-x.yy.tar.gz)
- Apache::Request >= 0.33 (libapreq) is preferred but not required. If not
     present CGI::Cookie will be used instead.
     (http://www.cpan.org/modules/by-module/Apache/libapreq-x.yy.tar.gz)
  
Copyright (C) 2001-2004 Enrico Sorcinelli. All rights reserved.
This program is free software; you can redistribute it 
and/or modify it under the same terms as Perl itself. 

Author: Enrico Sorcinelli <enrico@sorcinelli.it>

Part of Makefile.PL contains Perl (cool!) code of Joshua Chamas
Apache-ASP Makefile.PL installation script

SessionManager.pm view on Meta::CPAN

		require APR::URI;
		require Apache::URI;
		#require Apache::Connection;  # for remote_ip
	}
	else {
		require Apache::Constants;
		Apache::Constants->import(qw(DECLINED REDIRECT));
		require Apache::URI;
	}
	# Test libapreq modules
	eval { require Apache::Cookie; Apache::Cookie->can('bake'); Apache::Cookie->can('fetch') };
	if ($@) {
		require CGI::Cookie;
		$libapreq = 0;
	}
	else {
		$libapreq = 1;
	}
}

sub handler {
	my $r = shift;
	my (%session_config,%session,$session_id,%cookie_options);

	return (MP2 ? Apache::DECLINED : Apache::Constants::DECLINED) unless $r->is_initial_req;

	my $debug_prefix = '[' . $r->connection->remote_ip . "] SessionManager ($$): ";
	$session_config{'SessionManagerDebug'} = $r->dir_config('SessionManagerDebug') || 0;
	foreach ( qw/SessionManagerURITracking SessionManagerTracking SessionManagerEnableModBackhand 
		          SessionManagerStoreArgs SessionManagerCookieArgs SessionManagerSetEnv SessionManagerExpire 
		          SessionManagerHeaderExclude SessionManagerIPExclude/ ) {
		$session_config{$_} = $r->dir_config($_);
	}

	$r->log_error($debug_prefix . '---START REQUEST: ' .  $r->uri . ' ---') if $session_config{'SessionManagerDebug'} > 0;
	#print STDERR "$debug_prefix ---START REQUEST: " .  $r->uri . " ---\n" if $session_config{'SessionManagerDebug'} > 0;

	# Get and remove session ID from URI
	if ( $session_config{'SessionManagerURITracking'} eq 'On' ) {
		$r->log_error($debug_prefix . 'start URI ' . $r->uri) if $session_config{'SessionManagerDebug'} > 0;

SessionManager.pm view on Meta::CPAN

			$r->log_error($debug_prefix . ' ' x 8 . "$_ = $session_config{$_}");
			#print STDERR "\t$_ = $session_config{$_}\n";
		}
	}

	# Get session ID from cookie
	unless ( $session_config{'SessionManagerURITracking'} eq 'On' ) {

		if ( $libapreq ) {
			# Test libapreq 1 or 2 version to use correct 'fetch' API
			my %cookies = $Apache::Request::VERSION >= 2 ? Apache::Cookie->fetch($r) : Apache::Cookie->fetch;
			$session_id = $cookies{$session_config{'SessionManagerName'}}->value if defined $cookies{$session_config{'SessionManagerName'}};
			$r->log_error($debug_prefix . 'Apache::Cookie fetch') if $session_config{'SessionManagerDebug'} >= 5;
			#print STDERR "$debug_prefix Apache::Cookie fetch\n" if $session_config{'SessionManagerDebug'} >= 5;
		}
		# Fetch cookies with CGI::Cookie				
		else {
			# At this phase (HeaderParser | Translation), no $ENV{'COOKIE'} var is set, so we use CGI::Cookie parse method by passing 'Cookie' HTTP header
			my %cookies = CGI::Cookie->parse($r->headers_in->{'Cookie'});
			$session_id = $cookies{$session_config{'SessionManagerName'}}->value if defined $cookies{$session_config{'SessionManagerName'}};
			$r->log_error($debug_prefix . 'CGI::Cookie fetch') if $session_config{'SessionManagerDebug'} >= 5;
			#print STDERR "$debug_prefix CGI::Cookie fetch\n" if $session_config{'SessionManagerDebug'} >= 5;
		}
	}

	# Prepare Apache::Session::Flex options parameters call
	my %apache_session_flex_options = (
		Store     => $session_config{'SessionManagerStore'},
		Lock      => $session_config{'SessionManagerLock'},
		Generate  => $session_config{'SessionManagerGenerate'},
		Serialize => $session_config{'SessionManagerSerialize'}
	);

SessionManager.pm view on Meta::CPAN

			#print STDERR "$debug_prefix URI redirect...\n" if $session_config{'SessionManagerDebug'} > 0;
			_redirect($r,$session_id);
			return MP2 ? Apache::REDIRECT : Apache::Constants::REDIRECT;
		}
		# ...or send cookie to browser
		else {
			$r->log_error($debug_prefix . 'sending cookie...') if $session_config{'SessionManagerDebug'} > 0;
			#print STDERR "$debug_prefix sending cookie...\n" if $session_config{'SessionManagerDebug'} > 0;
			
			# Load cookie specific parameters
			foreach my $arg ( split(/\s*,\s*/,$session_config{'SessionManagerCookieArgs'}) ) {
				my ($key,$value) = split(/\s*=>\s*/,$arg);
				$cookie_options{'-' . lc($key)} = $value if $key =~ /^(expires|domain|path|secure)$/i;
			}
			
			# Set default cookie path
			$cookie_options{'-path'} = '/' unless $cookie_options{'-path'};
			
			if ( $session_config{'SessionManagerDebug'} >= 5 ) {
				$r->log_error($debug_prefix . 'Cookie options:');
				#print STDERR "$debug_prefix Cookie options\n";
				foreach (sort keys %cookie_options)	{
					$r->log_error($debug_prefix . ' ' x 8 . "$_ = $cookie_options{$_}");
					#print STDERR "\t$_ = $cookie_options{$_}\n";
				}
			}

			# Set cookie with Apache::Cookie
			if ( $libapreq ) {
				my $cookie = Apache::Cookie->new($r,
					name => $session_config{'SessionManagerName'},
					value => $session_id,
					%cookie_options
				);
				$cookie->bake;
				
				$r->log_error($debug_prefix . 'Apache::Cookie bake ' . $cookie->as_string) if $session_config{'SessionManagerDebug'} >= 5;
				#print STDERR ("$debug_prefix Apache::Cookie bake " . $cookie->as_string . "\n") if $session_config{'SessionManagerDebug'} >= 5;
			}
			# Set cookie with CGI::Cookie
			else {
				my $cookie = CGI::Cookie->new(
					-name => $session_config{'SessionManagerName'},
					-value => $session_id,
					%cookie_options
				);
				$r->err_headers_out->{'Set-Cookie'} = "$cookie";
				
				$r->log_error($debug_prefix . "CGI::Cookie bake $cookie") if $session_config{'SessionManagerDebug'} >= 5;
				#print STDERR "$debug_prefix CGI::Cookie bake $cookie\n" if $session_config{'SessionManagerDebug'} >= 5;
			}
		}
	}

	$r->log_error($debug_prefix . '---END REQUEST---') if $session_config{'SessionManagerDebug'} > 0;
	#print STDERR "$debug_prefix ---END REQUEST---\n" if $session_config{'SessionManagerDebug'} > 0;
		
	return MP2 ? Apache::DECLINED : Apache::Constants::DECLINED;
}

SessionManager.pm view on Meta::CPAN


Prerequisites:

=over 4

=item * mod_perl 1.0 or 2.0 is required (of course) with the appropriate
call-back hooks (PERL_TRANS=1 PERL_HEADER_PARSER=1)

=item * Apache::Session >= 0.53 is required

=item * Apache::Cookie >= 0.33 (libapreq) is preferred but not required 
(CGI::Cookie will be used instead)

=item * CGI::Cookie (used only if Apache::Request isn't installed)

=back 

Installation as usual:

   % perl Makefile.PL
   % make
   % make test
   % su
     Password: *******

SessionManager.pm view on Meta::CPAN

put the user timestamp in a special session key  C<_session_timestamp>.

=item C<SessionManagerName> string

This single directive defines session cookie name

   PerlSetVar SessionManagerName PSESSID

The default value is C<PERLSESSIONID>

=item C<SessionManagerCookieArgs>

With this directive you can provide optional arguments  for cookie attributes
setting. The arguments are passed as comma-separated list of name/value pairs.
The only attributes accepted are:

=over 4

=item * Domain

Set the domain for the cookie.

SessionManager.pm view on Meta::CPAN

Set the secure flag for the cookie. 

=item * Expires

Set expire time for the cookie.

=back

For instance:

   PerlSetVar SessionManagerCookieArgs "Path   => /some-path, \
                                        Domain => .yourdomain.com, \
                                        Secure => 1"

Please see the documentation for L<Apache::Cookie|Apache::Cookie> or
L<CGI::Cookie|CGI::Cookie> in order to see more cookie arguments details.

=item C<SessionManagerStore> datastore

This single directive sets the session datastore used by
L<Apache::Session|Apache::Session> framework

   PerlSetVar SessionManagerStore File

The following datastore plugins are available with 
L<Apache::Session|Apache::Session> distribution:

SessionManager.pm view on Meta::CPAN

Patches are welcome and I'll update the module if any problems will be found.

=head1 VERSION

Version 1.03

=head1 SEE ALSO

L<Apache::SessionManager::cookpod|Apache::SessionManager::cookpod>,
L<Apache::Session|Apache::Session>, L<Apache::Session::Flex|Apache::Session::Flex>, 
L<Apache::Request|Apache::Request>, L<Apache::Cookie|Apache::Cookie>, 
L<CGI::Cookie|CGI::Cookie>, L<Apache|Apache>, perl(1)

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2001-2004 Enrico Sorcinelli. All rights reserved. 
This program is free software; you can redistribute it  and/or modify it under
the same terms as Perl itself. 

=cut

SessionManager/cookpod.pod view on Meta::CPAN

=pod

=head1 NAME

Apache::SessionManager::cookpod - Session management Cookpod with
Apache::SessionManager

=head1 INTRODUCTION

This HOWTO describes use of L<Apache::SessionManager|Apache::SessionManager>
with several application servers  and toolkits available designed to run (also)
under mod_perl. There are many ways to do it; this document will not describe
all possible configurations.

=head1 WHAT DOES Apache::SessionManager DO

SessionManager/cookpod.pod view on Meta::CPAN

      $session->{'foo'} = $foo;

      print $$session{'bar'};
   </%perl>

=head2 SEE ALSO

L<HTML::Mason|HTML::Mason>, L<Apache::Session|Apache::Session>,
L<Apache::Session::Flex|Apache::Session::Flex>,
L<Apache::SessionManager|Apache::SessionManager>,
L<Apache::Request|Apache::Request>, L<Apache::Cookie|Apache::Cookie>,
L<Apache|Apache>, perl(1)

=head1 Apache::SessionManager WITH PLP

=head2 INTRODUCTION

This section describes use of L<Apache::SessionManager|Apache::SessionManager>
with L<PLP|PLP>. L<PLP|PLP> (L<http://plp.juerd.nl/>) is yet another Perl
embedder, primarily for HTML documents.

SessionManager/cookpod.pod view on Meta::CPAN


   <:
      my $session = Apache::SessionManager::get_session(Apache->request);
   :>

=head2 SEE ALSO

L<PLP|PLP>, L<Apache::Session|Apache::Session>,
L<Apache::Session::Flex|Apache::Session::Flex>,
L<Apache::SessionManager|Apache::SessionManager>,
L<Apache::Request|Apache::Request>, L<Apache::Cookie|Apache::Cookie>,
L<Apache|Apache>, perl(1)

=head1 Apache::SessionManager WITH THE TEMPLATE TOOLKIT

=head2 INTRODUCTION

This section describes how to use
L<Apache::SessionManager|Apache::SessionManager> with Template Toolkit
(L<http://www.tt2.org>). The idea is to use the
L<Template::Plugin::Apache::SessionManager|Template::Plugin::Apache::SessionManager>

SessionManager/cookpod.pod view on Meta::CPAN


   %> lwp-download http://search.cpan.org/CPAN/authors/id/A/AM/AMS/Storable-2.07.tar.gz 
   %> tar -xzvf Storable-2.07.tar.gz  
   %> cd Storable-2.07   
   %> perl Makefile.PL PREFIX=/path/to/your/perl-lib
   %> make
   %> make test
   %> make install

The installation procedure for L<Digest::MD5|Digest::MD5> or
L<Apache::Cookie|Apache::Cookie> (libapreq) is almost the same.

=head2 INSTALLING Apache::Session

   %> lwp-download http://search.cpan.org/CPAN/authors/id/J/JB/JBAKER/Apache-Session-1.54.tar.gz 
   %> tar -xzvf Apache-Session-1.54.tar.gz
   %> cd Apache-Session-1.54
   %> perl Makefile.PL PREFIX=/path/to/your/perl-lib
   %> PERL5LIB=/path/to/your/perl-lib/lib make test
   %> make install

SessionManager/cookpod.pod view on Meta::CPAN

=head1 MOVING SESSION EXPIRATION POLICIES TO THE CLIENT SIDE

=head2 INTRODUCTION

This section describes how to move expiration policies on the client side by
setting expiration cookie properties appropriately.

=head2 CONFIGURATION

Practically, you must only add C<Expires> cookie attribute in
C<SessionManagerCookieArgs> module directive:

   <Location /sessions>
      SetHandler perl-script
      PerlHandler Apache::MyModule

      PerlSetVar SessionManagerExpire none
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerCookieArgs "Path => /sessions, Expires => +2d"
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp"
   </Location>

Optionally, you can set C<SessionManagerExpire> with value C<none>(or C<no> or
C<disable>) in order to disable expiration session control at server side.

However, it is not completely safe to left session expiration policies only on
the client side. A C<SessionManagerExpire> value should be always defined.

=head1 SEE ALSO

L<Apache::SessionManager|Apache::SessionManager>,L<Apache::Request|Apache::Request>,
L<Apache::Cookie|Apache::Cookie>, L<Apache|Apache>, perl(1)

=head1 AUTHORS

Enrico Sorcinelli <enrico@sorcinelli.it>

=head1 VERSION

0.06

=head1 BUGS

( run in 0.333 second using v1.01-cache-2.11-cpan-4e96b696675 )