OpenPlugin::Session - Save and retrieve session data

 my $session = {}
 $session->{camel_humps}     = "one";
 $session->{fish_in_the_sea} = "lots";
 $session->{stooges}         = "three";

 my $session_id = $OP->session->save( $session );

 ...

 my $session = $OP->session->fetch( $session_id );
 print "Humps:   $session->{camel_humps}\n";       # Prints "one"
 print "Fish:    $session->{fish_in_the_sea}\n";   # Prints "lots"
 print "Stooges: $session->{stooges}\n";           # Prints "three"

package OpenPlugin::Session;

# $Id: Session.pm,v 1.46 2003/04/28 17:43:49 andreychek Exp $

use strict;
use base                  qw( OpenPlugin::Plugin );

$OpenPlugin::Session::VERSION = sprintf("%d.%02d", q$Revision: 1.46 $ =~ /(\d+)\.(\d+)/);

sub OP   { return $_[0]->{_m}{OP} }
sub type { return 'session' }

# API

# Returns the session id
sub session_id {
    my ( $self ) = @_;
    return $self->state->{ session_id };
}

# This sub is defined in the individial drivers
sub get_session_data { return undef };

# Initiate a session and return a session_id
sub create {
    my ( $self ) = @_;
    my $session_id;

    my $session = $self->get_session_data();

    $session = $self->_init_session_data( $session, {} );

    if ( $self->_validate_session( $session ) ) {
        $session_id = $session->{_session_id};
    }
    else {
        $session_id = undef;
    }

    untie %{ $session };

    return $session_id;
}

# Retrieve all the values stored within a particular session
sub fetch {
    my ( $self, $session_id ) = @_;
    my $session_vals;

    $session_id = $self->_validate_session_id( $session_id );

    # Don't do anything if we weren't passed a valid session_id
    unless ( $session_id ) {
        $self->OP->log->info( "Invalid session_id given, can't fetch session.");
        return undef;
    }

    my $session = $self->get_session_data( $session_id );

    return undef unless defined $session;

    $session = $self->_init_session_data( $session, {} );

    # Verify that this session is legitimate
    if( $self->_validate_session( $session ) ) {

        $session->{_accessed} = time();

        # Set the session values, then untie the session
        foreach my $key ( keys %{ $session } ) {
            $session_vals->{ $key } = $session->{ $key };
        }
        untie %{ $session };
    }
    else {
        $session_vals = undef;
    }

    return $session_vals;

}

# Save data to a session
sub save {
    my ( $self, $data, $params ) = @_;

    # Make sure we were actually sent some values to save..
    unless ( scalar keys %{ $data } ) {
        $self->OP->log->info( "No session information to be saved." );
        return undef;
    }

    unless ( $params->{'id'}) {
        $params->{'id'} = $self->session_id() || $self->create();
    }

    # Validate the session ID if we were passed one (the ID itself, not the
    # data)
    $params->{'id'} = $self->_validate_session_id( $params->{'id'} ) if
                                                            $params->{'id'};

    # Initiate the session
    my $session = $self->get_session_data( $params->{'id'} );
    $session = $self->_init_session_data( $session, $params );

    # Make sure our session is good
    if ( $self->_validate_session( $session ) ) {

        # Set the session values.  Values starting with _ are readonly for
        # everything but this module
        foreach my $key ( keys %{ $data } ) {
            next if $data->{ $key } =~ m/^_/;

            $session->{ $key } = $data->{ $key };
        }
        $session->{_accessed} = time();

        $self->OP->log->debug( "Saving session ($session->{_session_id}).");
        untie %{ $session };
    }

    return $params->{ id };
}

sub delete {
    my ( $self, $session_id ) = @_;

    unless ( $session_id ) {
        $session_id = $self->session_id();
    }
    my $session = $self->get_session_data( $session_id );

    # Untaint the session_id so it can be properly deleted
    $session_id = $session->{_session_id};
    $session->{_session_id} = $self->_validate_session_id( $session_id );

    tied( %{ $session } )->delete if $session->{_session_id};

    return $session_id;
}

# Set up some values for our session
sub _init_session_data {
    my ( $self, $session, $params ) = @_;

    # When, if at all, the session will expire
    $session->{'_expires'} =
                        $params->{ expires } ||
                        $self->OP->config->{'plugin'}{'session'}{'expires'};

    # If _start exists, we've done this already
    return $session if exists $session->{'_start'};

    $self->OP->log->info( "Initiating session data.");

    # Time the session was created
    $session->{'_start'} = time();

    # Time the session was last accessed
    $session->{'_accessed'} = time();

    return $session;
}

# Validate and untaint the session ID given to us
sub _validate_session_id {
    my ( $self, $session_id ) = @_;

    $session_id ||= "";

    # Does our session ID look legitimate?
    # TODO -- this will only work for MD5 session ID's
    # Apache::Session only supports MD5.  But should something that validates
    #  the session ID string be part of the individual driver instead of here?
    #if( $self->OP->config->{plugin}{session}{parameters}{Generate} eq "MD5" ) {
        if ( $session_id =~ m/^([a-fA-F0-9]{32}$)/ ) {
            return $1;
        }
        else {
            $self->OP->log->info( "The session ID ($session_id) is an " .
                                  "invalid MD5 string.");
            return undef;
        }
    #}
    #else {
    #    $self->OP->log->log(1,  "Not using MD5 sessions, unable to validate " .
    #                            "session id ($session_id).  Continuing "      .
    #                            "anyway...");
    #    return $session_id;
    #}
}

# Validate the properties and expiration of our session
sub _validate_session {
    my ( $self, $session ) = @_;

    my $invalid = 0;

    return undef unless $session;

    # Make sure we have these already..
    $invalid = 1 unless (( exists $session->{_start} )          &&
                         ( exists $session->{_accessed} )       &&
                         ( exists $session->{_session_id} )     &&
                         ( exists $session->{_expires} ));

    # An expiration of -1 means it doesn't expire
    unless ( $session->{_expires} =~ /^-1$/ ) {

        $invalid = 1 if (time >
                    OpenPlugin::Utility->expire_calc( $session->{_expires},
                                                      $session->{_accessed} ));

    }

    if ( $invalid ) {
        $self->OP->log->info( "Session ($session->{_session_id}) is invalid." );

        # Untaint the session_id before we expire it
        $session->{_session_id} = $self->_validate_session_id( $session->{_session_id} );

        tied( %{ $session } )->delete if $session->{_session_id};
        return undef;
    }
    else {
        $self->OP->log->debug( "Session ($session->{_session_id}) is valid." );
        $self->state( 'session_id', $session->{_session_id} );
        return 1;
    }
}


1;

__END__