[RFC] Apache::SessionManager

[Enrico Sorcinelli <en...@sorcinelli.it>]

Hi all,

I would like to propose a new Apache module before I send it off to
CPAN. The namespace I've chosen is Apache::SessionManager.

This module is a an Apache/mod_perl module and use Apache::Session to 
track user's sessions over HTTP request.
Simply Apache::SessionManager help me with session management.

Apache::SessionManager creates an object session (in Header parsing phase, 
but not obligatorily) and make it available to all other handlers 
transparently by putting in pnotes. Others handlers can retrieve session
directly from pnotes or by calling the simple function 
Apache::SessionManager::get_session($r)

After some search on CPAN I haven't found a mod_perl module that does 
the same thing (right?). 
The module is work in progress, of course, even if already I use it.

Some sample code in a mod_perl handler:

sub handler {
   # get session
   my $session = Apache::SessionManager::get_session($sr)
   
   # set a session value
   $$session{'key'} = $value;

   #read value session
   print "$$session{'key'}";

   # destroy a session
   Apache::SessionManager::destroy_session($sr)

   ...
}

For module installation, configuration and directives see:

	perldoc Apache::SessionManager 

(also I've attached the pod below).

The module can be downloaded from here:

	http://www.sestante.net/Apache-SessionManager-0.01.tar.gz
	or
	http://www.sorcinelli.it/Apache-SessionManager-0.01.tar.gz

Feel free to do whatever you want with the code... Comment and/or criticism
are welcome! I'll post to CPAN if anyone thinks it's worth it. 
Also suggestions about the namespace are welcome.

Thanks in advance,

	- Enrico

----------

NAME
    Apache::SessionManager - simple mod_perl extension to manage sessions
    over HTTP requests

SYNOPSIS
            In httpd.conf:
        
       PerlModule Apache::SessionManager
       PerlHeaderParserHandler Apache::SessionManager
          
       <Location /my-app-with-session>
          SetHandler perl-script
          PerlHandler MyModule
                
          PerlSetVar SessionTracking On
          PerlSetVar SessionExpire 60
          PerlSetVar SessionName PERLSESSIONID
          PerlSetVar SessionDirectory "/tmp/apache_session_data"
          PerlSetVar SessionLockDirectory "/tmp/apache_session_data/lock"
       </Location>  

       <Location /my-app-without-sessions>
          PerlSetVar SessionTracking Off
       </Location>

DESCRIPTION
    Apache::SessionManager is a mod_perl module that help with session
    management. This simple module create an object session and make it to
    all other hadler by putting in pnotes. In a mod_perl handler you can
    retrieve the session object directly from pnotes with predefined key
    'SESSION_HANDLE':

       my $session = $r->pnotes('SESSION_HANDLE') ? $r->pnotes('SESSION_HANDLE')
: ();

    In a CGI Apache::Registry script:

       my $r = Apache->request;
       my $session = $r->pnotes('SESSION_HANDLE') ? $r->pnotes('SESSION_HANDLE')
: (); 

    then is possible to set a value in current session with:

       $$session{'key'} = $value;

    or read value session with:

       print "$$session{'key'}";

    The following functions also are provided (but not yet exported) by this
    module:

    Apache::SessionManager::get_session($sr)
        Return an hash reference to current session object

    Apache::SessionManager::destroy_session($sr)
        Destroy the current session object

INSTALLATION
    In order to install and use this package you will need Perl version
    5.005 or better.

    Prerequisites:

    Apache::Request >= 0.33 (libapreq) is required 
    Apache::Session >= 0.53 is required

    Installation as usual:

       % perl Makefile.PL
       % make
       % make test
       % su
         Password: *******
       % make install
  
CONFIGURATION
    To enable session tracking with this module you should modify a
    configuration in httpd.conf by adding the following lines:

       PerlModule Apache::SessionManager
       PerlHeaderParserHandler Apache::SessionManager
       PerlSetVar SessionTracking On

    This will activate the session manager over each request. Is posibible
    to activate this module by location or directory:

       <Location /my-app-dir>
          PerlHeaderParserHandler Apache::SessionManager
          PerlSetVar SessionTracking On
       </Location>

    Also, is possible to deactivate session management per directory or per
    location explicitly:

       <Location /my-app-dir-without>
          PerlSetVar SessionTracking Off
       </Location>

DIRECTIVES
    You can control the behavior of this module by configuring the following
    variable with `PerlSetVar' directive in the httpd.conf.

    `SessionTracking' On|Off
        This single directive enable session tracking

           PerlSetVar SessionTracking On

        The default value is `Off'

    `SessionExpire' number
        This single directive define global sessions expiration time.

           PerlSetVar SessionExpire 600

        The default value is `900' seconds

    `SessionName' string
        This single directive define session name

           PerlSetVar SessionName PSESSID

        The default value is `PERLSESSIONID'

    `SessionStore' file|db|ram|db_file
        This single directive set the session datastore used by
        Apache::Session framework

           PerlSetVar SessionStore file

        * file
            Store session in file system

        * db
            Not (yet) implemented

        * ram
            Not (yet) implemented

        * db_file
            Not (yet) implemented

        The default values is `file'

    `SessionDirectory' path
        This single directive define the directory for the object store when
        `SessionStore' is set to `file'.

           PerlSetVar SessionDirectory /tmp/apache_session

        The default value is `/tmp'

    `SessionLockDirectory' path
        This single directive define the locking directory for the object
        store.

           PerlSetVar SessionLockDirectory /tmp/apache_session/lock

        The default value is `/tmp'

    `SessionItemExclude' string|regex
        This single directive define the exclusion string For example:

           PerlSetVar SessionItemExclude exclude_string

        Alle the HTTP request containing the 'exclude_string' string will be
        declined. Also is possible to use regex:

           PerlSetVar SessionItemExclude "\.m.*$"

        and all the request (URI) ending by ".mpeg", ".mpg" or ".mp3" will
        be declined.

        The default value is

        `"(\.gif|\.jpg|\.jpeg|\.png|\.css|\.js|\.mpg|\.mpeg|\.txt|\.mp3|\.wa
        v|\.swf|\.avi|\.au|\.ram|\.rm)$"'

TODO
    * Implement wrapper for RAM, DB and db_file session datastore 
    * Include into the distro the session cleanup script (the scripts I use
    for cleanup actually)
    * Embed the cleanup policies not in a extern scripts but in a
    register_cleanup method
    * Consider user inactivity for session expiration policy
    * Test, test ,test

AUTHORS
    Enrico Sorcinelli <en...@sorcinelli.it>

BUGS
    Send bug reports and comments to: enrico@sorcinelli.it In each report
    please include the version module, the Perl, Apache, and 
    mod_perl version and your SO. If the problem is browser dependent please
    include also browser name and version.

SEE ALSO
    Apache::Session, Apache::Request, Apache, perl(1)

COPYRIGHT
    Copyright (C) 2001,2002 Enrico Sorcinelli

----------


================================================================
Enrico Sorcinelli - E-mail: enrico@sorcinelli.it
e.sorcinelli@pisa.iol.it - Gruppo E-Comm - Italia On Line S.p.a.
================================================================