NAME

WebApp::Session - A session

VERSION

  Time-stamp: <2006-04-25 14:10:20 mailto:attila@stalphonsos.com>
  $Id: Session.pm,v 1.17 2006/04/26 03:52:03 attila Exp $

SYNOPSIS

 use WebApp::Session;
 # md5-style: lookup existing session
 $session = new WebApp::Session(dbh => $dbh, md5 => $md5);

 # userauth-style: start new session if none exists
 $session = new WebApp::Session(dbh => $dbh,
                                user => $user,
                                password => $pass,
                                remote => $remote_ip);

 $user   = $session->user();
 $md5    = $session->md5();
 $ip     = $session->remote();
 $scalar = $session->get('varname');
 $bool   = $session->defined('varname');
 $errmsg = $session->set('varname','val');
 $errmsg = $session->add('varname','val');
 $errmsg = $session->unset('varname');
 @vector = $session->names(['regexp']);

 $session->store([dbh]);
 $session->delete([dbh]);

 WebApp::Session::GC($dbh,$verbose);
 @list = WebApp::Session::List($dbh);

 # In all cases, $WebApp::Session::ERROR has the last error
 # message that any exported interface produced

DESCRIPTION

WebApp::Session implements persistent sessions in a DBI database. Sessions consist of one or more variables, each of which can have a scalar value.

DETAILED DOCUMENTATION

List $dbh

Return a list of valid session IDs in the given database.

CalcMD5 $dbh,$user,$remote_ip,[$remote_port[,$uniq]]

Return the MD5 cookie we would issue for a session against the given database handle, for the given user name, with the given remote IP address. The hash is salted with some random bits so that we do not return the same value for the same inputs. It is a good idea to specify as many of the arguments as you can, anyway, because we do not use a particularly good random number generator.

CalcExpireTime $dbh,$user

Returns the absolute time, as a standard Unix time_t value, at which a session for the given user should expire. $user can either be a WebApp::User object or a user ID as a string. If the user cannot be found, we try to query the default configuration object for

   [Session]
   default_ttl

and default to 90 days if it is not set.

Delete $dbh,$md5

Class-method style of session deletion. Both arguments are required. The named session is deleted.

Login dbh=>$dbh, session=>$existing_session, remote => $remote_ip, uname => $username, password => $password, hdrs => $hdrs, cookie_name => $cname, ttl => $clife

Log a user in. Does a combination of things, and is meant as a general purpose front end to a bunch of other things for many common uses of WebApp::Session. Currently, this convenience function assumes the app is using cookies. Not yet suitable for all situations.

Logout dbh=>$dbh,session=>$session,hdrs=>$hdrs,cookie_value=>$cval,cookie_name=>$cname

Log a user out, again assuming that we are using cookies.

GC $dbh,[$verbose[,$dont]]

Given a live DBI handle, garbage-collect sessions whose expiration times have passed. If $verbose is non-zero, we produce messages on STDERR. If $dont is non-zero, then we do not delete anything, we just count how many sessions we would have deleted.

We return the number of sessions garbage-collected (or the number that would have been).

expires [$abs]

Returns the expiration time. If called with a non-zero argument, we return the absolute time as a standard Unix time_t integral value, other wise we return the number of seconds from now that the session will expire; if this number is negative, then the session expired that many seconds ago.

expired [$revive]

Returns true if this session has expired. If called with a non-zero argument, we revive the session from the dead and update its expiration time in the database. In any case, we return true or false as of the time the method is invoked.

security_check $remote[,$cfg]

Enforce certain basic security constraints as per this apps configuration. The configuration options we pay attention to are:

    [Session]
    strict_client_ip=1|0        # default: 0
    strict_client_ip_mask=1..32 # default: 32

            If turned on, we only accept a cookie for a session from
            the same IP address or IP address range.  If we get a
            cookie that is valid, but came from a non-matching IP
            address, we reset the cookie in that client (or try with
            Set-Cookie) and do not accept the cookie.  If you set
            strict_client_ip_mask to e.g. 24, then we will accept IPs
            in the same /24 of the original IP.

We return undef if there is no problem, and a string containing an error message if there was. Nothing is done to the database or the session object otherwise - it is purely a matter for the application itself to decide what to do if a session object fails, because WebApp is not concerned with setting policy for apps, only for making the most common things simple and easy to do (we suspect that one of the reasons why many webapps are not very secure has to do with how much code the application writer to produce in order to get this kind of thing right).

user

Return the WebApp::User object behind this session. See WebApp::User for details. If the session is just a temporary shill object, then we return undef.

is_user $user

Return true if this session is owned by the given user, which can be either a WebApp::User object, or a string user ID.

md5

Return the md5 cookie for this session as a 32-byte string.

remote

Returns the remote IP address from which the session was originally created.

get $var

Get the value of a variable in the session.

defined $var

Check if a variable name is defined.

set $var,$val

Set the value of a variable. If it does not exist, add it.

init $var,$val

Like set, but only changes the value if it is not defined

add $var,$val

Add a variable to a session. Just like set except that we return an error if the variable was already defined.

unset $var

Remove a variable from a session.

names[,$regexp]

Return all the names of variables in this session. If our option $regexp argument is given, we only return those variable names that match the given regular expression (case-sensitive).

store

Store ourselves into the database.

renew

Update our expiration time in the database, if possible. Invoked automatically by store, and possibly by expired.

delete

Delete this session from the database.

valid

Return true if the session is not just a placeholder object

dump [$fh]

Dump a human-readable representation of our state to the given file handle, or STDERR if none is given.

as_string

Return string representation of ourselves suitable for framing.

copy_vars $hashref

Merge values from $hashref into our own variables. Used to initialize a sessions current state from e.g. a users saved state, when the user logs in.

dbh

Return database handle, if any.

new dbh => $dbh, { md5 => $md5 | user => $user, remote => $remote }

Constructor. Create a new session or load an existing session from the database if the md5 argument is given. Our calling sequence is actually

   my($obj,$err) = new WebApp::Session(args...);

If $obj is undef afterwards, $err is guaranteed to have an error message.

DDL [$dbh|$dsn]

Class method to run our DDL against a fresh database. Should probably not be invoked by hand; use the webapp command, or at least the WebApp module, instead.

AUTHOR

Sean Levy <mailto:snl@cluefactory.com>

COPYRIGHT AND LICENSE

(C) 2002-2006 by Sean Levy <mailto:snl@cluefactory.com>. all rights reserved.

This code is released under a BSD license. Please see the LICENSE file that came with the source distribution or visit http://cluefactory.com/oss/WebApp/license.html