NAME

Apache::Session::Counted - Session management via a File::CounterFile

SYNOPSIS

 tie %s, 'Apache::Session::Counted', $sessionid, {
                                Directory => <root of directory tree>,
                                DirLevels => <number of dirlevels>,
                                CounterFile => <filename for File::CounterFile>,
                                AlwaysSave => <boolean>,
                                HostID => <string>,
                                HostURL => <callback>,
                                Timeout => <seconds>,
                                                 }

DESCRIPTION

This session module is based on Apache::Session, but it persues a different notion of a session, so you probably have to adjust your expectations a little.

The dialog that is implemented within an HTTP based application is a nonlinear chain of events. The user can decide to use the back button at any time without informing the application about it. A proper session management must be prepared for this and must maintain the state of every single event. For handling the notion of a session and the notion of a registered user, the application has to differentiate carefully between global state of user data and a user's session related state. Some data may expire after a day, others may be regarded as unexpirable. This module is solely responsible for handling session related data. Saving unexpirable user related data must be handled by the calling application.

In Apache::Session::Counted, a session-ID only lasts from one request to the next at which point a new session-ID is computed by the File::CounterFile module. Thus what you have to treat differently than in Apache::Session are those parts that rely on the session-ID as a fixed token per user. Accordingly, there is no option to delete a session. The remove method is simply disabled as old session data will be overwritten as soon as the counter is reset to zero.

The usage of the module is via a tie as described in the synopsis. The arguments have the following meaning:

Directory, DirLevels

Works similar to filestore but as most file systems are slow on large directories, works in a tree of subdirectories.

CounterFile

A filename to be used by the File::CounterFile module. By changing that file or the filename periodically, you can achieve arbitrary patterns of key generation. If you do not specify a CounterFile, you promise that in this session there is no need to generate a new ID and that the whole purpose of this object is to retrieve previously stored session data. Thus no new session file will be written. If you break your promise and write something to the session hash, the retrieved session file will be overwritten.

AlwaysSave

A boolean which, if true, forces storing of session data in any case. If false, only a STORE, DELETE or CLEAR trigger that the session file will be written when the tied hash goes out of scope. This has the advantage that you can retrieve an old session without storing its state again.

HostID

A string that serves as an identifier for the host we are running on. This string will become part of the session-ID and must not contain a colon. This can be used in a cluster environment so that a load balancer or other interested parties can retrieve the session data again.

HostURL

A callback that returns the service URL that can be called to get at the session data from another host. This is needed in a cluster environment. Two arguments are passed to this callback: HostID and Session-ID. The URL must return the serialized data in Storable's nfreeze format. The Apache::Session::Counted module can be used to set such an URL up. If HostURL is not defined, the default is

    sprintf "http://%s/?SESSIONID=%s";, <host>, <session-ID>;

The callback can return false to signal that there is no session to retrieve (e.g. when the host or id argument is illegal).

Timeout

Sets the timeout for LWP::UserAgent for retrieving a session from a different host. Default is 10 seconds.

What this model buys you

storing state selectively: You need not store session data for each and every request of a particular user. There are so many CGI requests that can easily be handled with two hidden fields and do not need any session support on the server side, and there are others where you definitely need session support. Both can appear within the same application. Apache::Session::Counted allows you to switch session writing on and off during your application without effort. (In fact, this advantage is shared with the clean persistence model of Apache::Session)
keeping track of transactions: As each request of a single user remains stored until you restart the counter, there are all previous states of a single session close at hand. The user presses the back button 5 times and changes a decision and simply opens a new branch of the same session. This can be an advantage and a disadvantage. I tend to see it as a very strong feature. Your milage may vary.
counter: You get a counter for free which you can control just like File::CounterFile (because it is File::CounterFile).
cleanup: Your data storage area cleans up itself automatically. Whenever you reset your counter via File::CounterFile, the storage area in use is being reused. Old files are being overwritten in the same order they were written, giving you a lot of flexibility to control session storage time and session storage disk space.
performance: The notion of daisy-chained sessions simplifies the code of the session handler itself quite a bit and it is likely that this simplification results in an improved performance (not tested yet due to lack of benchmarking apps for sessions). There are less file stats and less sections that need locking, but without real world figures, it's hard to tell.

As with other modules in the Apache::Session collection, the tied hash contains a key _session_id. You must be aware that the value of this hash entry is not the same as the one you passed in when you retrieved the session (if you retrieved a session at all). So you have to make sure that you send your users a new session-id in each response, and that this is never the old one.

As an implemenation detail it may be of interest to you, that the session ID in Apache::Session::Counted consists of two or three parts: an optional host alias given by the HostID paramter, followed by a colon. Then an ordinary number which is a simple counter which is followed by an underscore. And finally a session-ID like the one in Apache::Session. The number part is used as an identifier of the session and the ID part is used as a password. The number part is easily predictable, but the second part is reasonable unpredictable. We use the first part for implementation details like storage on the disk and the second part to verify the ownership of that token.

PREREQUISITES

Apache::Session::Counted needs Apache::Session and File::CounterFile, all available from the CPAN. The HostID and HostURL parameters for a cluster solution need LWP installed.

EXAMPLES

The following example resets the counter every 24 hours and keeps the totals of every day as a side effect:

  my(@t) = localtime;
  tie %session, 'Apache::Session::Counted', $sid,
  {
   Directory => ...,
   DirLevels => ...,
   CounterFile => sprintf("/some/dir/%04d-%02d-%02d", $t[5]+1900,$t[4]+1,$t[3])
  };

The same effect can be accomplished with a fixed filename and an external cronjob that resets the counter like so:

  use File::CounterFile;
  $c=File::CounterFile->new("/usr/local/apache/data/perl/sessiondemo/counter");
  $c->lock;
  $c-- while $c>0;
  $c->unlock;

AUTHOR

Andreas Koenig <andreas.koenig@anima.de>

COPYRIGHT

This software is copyright(c) 1999-2002 Andreas Koenig. It is free software and can be used under the same terms as perl, i.e. either the GNU Public Licence or the Artistic License.

Apache::Session::Counted - Session management via a File::CounterFile