File Coverage

blib/lib/NetSDS/Session.pm

Criterion	Covered	Total	%
statement	13	15	86.6
branch			n/a
condition			n/a
subroutine	5	5	100.0
pod			n/a
total	18	20	90.0

#===============================================================================
#
#       MODULE:  NetSDS::Session
#
#  DESCRIPTION:  Memcached based session data storage
#
#       AUTHOR:  Michael Bochkaryov (Rattler),
#      COMPANY:  Net.Style
#
#===============================================================================

=head1 NAME

B - memcached based session storage API

=head1 SYNOPSIS

	use NetSDS::Session;

	# Connecting to Memcached server
	my $sess = NetSDS::Session->new(
		host => '12.34.56.78',
		port => '12345',
	);

	...

	# Retrieve session key somehow
	$session_key = $cgi->param('sess_key');

	$sess->open($session_key);

	my $filter = $sess->get('filter');
	...
	$sess->set('filter', $new_filter);
	...
	$sess->close();

	1;

=head1 DESCRIPTION

C module provides API to session data storage based on Memcached server.

Each session represented as hash reference structure identified by UUID string.
Most reasonable usage of this module is a temporary data storing for web based GUI
between HTTP requests. However it's possible to find some other tasks.

Internally session structure is transformed to/from JSON string when interacting with Memcached.

=cut

package NetSDS::Session;

use 5.8.0;
use strict;
use warnings;

use version; our $VERSION = '1.301';

use Cache::Memcached::Fast;
use JSON;

use base 'NetSDS::Class::Abstract';

=head1 CLASS API

=over

=item B - class constructor

Constructor establish connection to memcached server and set default session parameters.

Parameters:

	* host - memcached server hostname or IP address (default: 127.0.0.1)
	* port - memcached server TCP port (default: 11211)

Example:

	my $sess_hdl = NetSDS::Session->new(
		host => '12.34.56.78',
		port => '99999',
	);

=cut

sub new {

	my ( $class, %params ) = @_;

	my $self = $class->SUPER::new(
		session_id   => undef,    # session id (UUID string)
		session_data => {},       # session data as hash reference
		%params
	);

	# Prepare server address string (host:port)
	my $mc_host = $params{'host'} || '127.0.0.1';
	my $mc_port = $params{'port'} || '11211';

	# Initialize memcached handler
	$self->{memcached} = Cache::Memcached::Fast->new(
		{
			servers           => [                      { address => $mc_host . ':' . $mc_port } ],
			serialize_methods => [ \&JSON::encode_json, \&JSON::decode_json ],
		}
	);

	if ( $self->{memcached} ) {
		return $self;
	} else {
		return $class->error("Can't create memcached connection handler");
	}

} ## end sub new

=item B - open session

Retrieve session data from server by session key (UUID string)

If no session exists then empty hashref is returned.

=cut

sub open {

	my ( $self, $sess_id ) = @_;

	# Initialize session key and retrieve data
	$self->{_id}   = $sess_id;
	$self->{_data} = $self->{memcached}->get($sess_id);

	# If no such session stored then create empty hashref
	$self->{_data} ||= {};

	return $self;
}

=item B - get session id

Returns current session id.

Example:

	my $sess_id = $sess->id();

=cut

sub id {
	my $self = shift;
	return $self->{_id};
}

=item B - set session parameter

Set new session parameter value identified by it's key.

Example:

	$sess->set('order', 'id desc');

=cut

sub set {
	my ( $self, $key, $value ) = @_;
	$self->{_data}->{$key} = $value;
	return 1;
}

=item B - get session parameter

Return session parameter value by it's key.

Example:

	my $order = $sess->get('order');

=cut

sub get {
	my ( $self, $key ) = @_;
	return $self->{_data}->{$key};
}

=item B - delete session parameter by key

Delete session parameter by it's key.

Returns updated session data as hash reference.

Example:

	$sess->delete('order');

=cut

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

	delete $self->{_data}->{$key};
	return $self->{_data};
}

=item B - clear session data

This method clears all session data.

Example:

	$sess->clear();

=cut

sub clear {
	my $self = shift;
	$self->{_data} = {};
}

=item B - save session

Synchronize session data on Memcached server.

Example:

	$sess->sync();

=cut

sub sync {

	my $self = shift;

	return $self->id ? $self->{memcached}->set( $self->id, $self->{_data} ) : undef;

}

=item B - save and close session

This method save all data to server and clear current session id and data from object.

Example:

	$session->close();

=cut

sub close {

	my $self = shift;

	# Nothing to store for non existent session key
	unless ( $self->id ) {
		return undef;
	}

	# Store session data to memcached server
	# or clear it from server if it's empty
	if ( $self->{_data} == {} ) {
		$self->{memcached}->delete( $self->id );
	} else {
		$self->{memcached}->set( $self->id, $self->{_data} );
	}

	# Clear session id and data
	$self->{_id}   = undef;
	$self->{_data} = undef;

	return;
} ## end sub close

1;

__END__