Dancer::Session::Abstract - abstract class for session engine

Dancer documentation Contained in the Dancer distribution.

Index

Code Index:

NAME

Top

Dancer::Session::Abstract - abstract class for session engine

SPEC

Top

role

A Dancer::Session object represents a session engine and should provide anything needed to manipulate a session, whatever its storing engine is.

id

The session id will be written to a cookie, by default named dancer.session, it is assumed that a client must accept cookies to be able to use a session-aware Dancer webapp. (The cookie name can be change using the session_name config setting.)

storage engine

When the session engine is enabled, a before filter takes care to initialize the appropriate session engine (according to the setting session).

Then, the filter looks for a cookie named dancer.session (or whatever you've set the ssesion_name setting to, if you've used it) in order to retrieve the current session object. If not found, a new session object is created and its id written to the cookie.

Whenever a session call is made within a route handler, the singleton representing the current session object is modified.

After terminating the request, a flush is made to the session object.

DESCRIPTION

Top

This virtual class describes how to build a session engine for Dancer. This is done in order to allow multiple session storage backends with a common interface.

Any session engine must inherit from Dancer::Session::Abstract and implement the following abstract methods.

Configuration

These settings control how a session acts.

session_name

The default session name is "dancer_session". This can be set in your config file:

    setting session_name: "mydancer_session"

session_secure

The user's session id is stored in a cookie. If true, this cookie will be made "secure" meaning it will only be served over https.

session_expires

When the session should expire. The format is either the number of seconds in the future, or the human readable offset from expires in Dancer::Cookie.

By default, there is no expiration.

session_is_http_only

This setting defaults to 1 and instructs the session cookie to be created with the HttpOnly option active, meaning that JavaScript will not be able to access to its value.

Abstract Methods

retrieve($id)

Look for a session with the given id, return the session object if found, undef if not.

create()

Create a new session, return the session object.

flush()

Write the session object to the storage engine.

destroy()

Remove the current session object from the storage engine.

session_name (optional)

Returns a string with the name of cookie used for storing the session ID.

You should probably not override this; the user can control the cookie name using the session_name setting.

Inherited Methods

The following methods are not supposed to be overloaded, they are generic and should be OK for each session engine.

build_id

Build a new uniq id.

read_session_id

Reads the dancer.session cookie.

write_session_id

Write the current session id to the dancer.session cookie.

Dancer documentation Contained in the Dancer distribution. 
package Dancer::Session::Abstract;
use strict;
use warnings;
use Carp;

use base 'Dancer::Engine';

use Dancer::Config 'setting';
use Dancer::Cookies;
use File::Spec;

__PACKAGE__->attributes('id');

# args: ($class, $id)
# receives a session id and should return a session object if found, or undef
# otherwise.
sub retrieve {
    confess "retrieve not implemented";
}

# args: ($class)
# create a new empty session, flush it and return it.
sub create {
    confess "create not implemented";
}

# args: ($self)
# write the (serialized) current session to the session storage
sub flush {
    confess "flush not implemented";
}

# args: ($self)
# remove the session from the session storage
sub destroy {
    confess "destroy not implemented";
}

# does nothing in most cases (exception is YAML)
sub reset {
    return;
}

# This is the default constructor for the session object, the only mandatory
# attribute is 'id'. The whole object should be serialized by the session
# engine.
# If you override this constructor, remember to call $self->SUPER::init() so
# that the session ID is still generated.
sub init {
    my ($self) = @_;
    $self->id(build_id());
}

# this method can be overwritten in any Dancer::Session::* module
sub session_name {
    setting('session_name') || 'dancer.session';
}


# Methods below this this line should not be overloaded.

# we try to make the best random number
# with native Perl 5 code.
# to rebuild a session id, an attacker should know:
# - the running PID of the server
# - the current timestamp of the time it was built
# - the path of the installation directory
# - guess the correct number between 0 and 1000000000
# - should be able to reproduce that 3 times
sub build_id {
    my $session_id = "";
    foreach my $seed (rand(1000), rand(1000), rand(1000)) {
        my $c = 0;
        $c += ord($_) for (split //, File::Spec->rel2abs(File::Spec->curdir));
        my $current = int($seed * 1000000000) + time + $$ + $c;
        $session_id .= $current;
    }
    return $session_id;
}

sub read_session_id {
    my $name = session_name();
    my $c = Dancer::Cookies->cookies->{$name};
    return (defined $c) ? $c->value : undef;
}

sub write_session_id {
    my ($class, $id) = @_;

    my $name = session_name();
    my %cookie = (
        name   => $name,
        value  => $id,
        secure => setting('session_secure'),
        http_only => defined(setting("session_is_http_only")) ?
                     setting("session_is_http_only") : 1,
    );
    if (my $expires = setting('session_expires')) {
        # It's # of seconds from the current time
        # Otherwise just feed it through.
        $expires = Dancer::Cookie::_epoch_to_gmtstring(time + $expires) if $expires =~ /^\d+$/;
        $cookie{expires} = $expires;
    }

    my $c = Dancer::Cookie->new(%cookie);
    Dancer::Cookies->set_cookie_object($name => $c);
}

1;
__END__