NAME

MVC::Neaf::X::Session - Session engine base class for Not Even A Framework

DESCRIPTION

A framework, even a toy one, is incomplete until it can handle user sessions.

This class offers managing sessions via a cookie ("session" by default) plus a user-defined backend storage mechanism.

Whatever is stored in the session, stays in the session - until it's deleted.

Within the application, session is available through Request methods session(), save_session(), and delete_session(). During the setup phase, MVC::Neaf->set_session_handler( $engine ) must be called in order to make use of those.

This class is base class for such $engine.

To actually manage sessions, it MUST be subclassed with methods save_session() and load_session() implemented. For a working implementation, please see MVC::Neaf::X::Session::File.

This module's interface is still under development and details MAY change in the future.

SINOPSYS

    use MVC::Neaf;
    use MVC::Neaf::X::Session;

    # somewhere in the beginning
    {
        package My::Session;

        sub save_session {
            my ($self, $id, $data) = @_;
            $self->{data}{ $id } = $data;
            return { id => $id };
        };

        sub load_session {
            my ($self, $id) = @_;
            return { data => $self->{data}{ $id } };
        };
    };
    MVC::Neaf->set_session_handler( My::Session->new );

    # somewhere in the controller
    sub {
        my $req = shift;

        $req->session; # {} 1st time, { user => ... } later on
        $req->session->{user} = $user;
        $req->save_session;
    };

This of course is only going to work as a standalone application server (plackup, twiggy...), but not CGI or Apache/mod_perl.

METHODS

new( %options )

The default constructor just happily closes over whatever is given to it.

session_id_regex()

This is supposed to be a constant regular expression compatible with whatever get_session_id generates.

If none given, a sane default is supplied.

get_session_id( [$user_salt] )

Generate a new, shiny, unique, unpredictable session id. Id is base64-encoded.

The default is using two rounds of md5 with time, process id, hostname, and random salt. Should be unique and reasonably hard to guess.

If argument is given, it's also added to the mix.

Set $MVC::Neaf::X::Session::Hash to other function (e.g. Digest::SHA::sha224) if md5 is not secure enough.

Set $MVC::Neaf::X::Session::Host to something unique if you know better. Default is hostname.

Set $MVC::Neaf::X::Session::Truncate to the desired length (e.g. if length constraint in database). Default (0) means return however many chars are generated by hash+base64.

session_ttl()

create_session()

Create a new session. The default is to return an empty hash.

save_session( $id, $data )

Save session data in the storage.

This method MUST be implemented in specific session driver class.

It MUST return a hashref with the following fields:

• id - the id of session (either supplied, or a new one). If this value is absent or false, saving is considered unsuccessful.

• expire - the expiration time of the session as Unix time. This is optional.

load_session( $id )

Return session data from the storage.

This MUST be implemented in specific session driver class.

It MUST return either false, or a hashref with the following fields:

• data - the session data that was passed to corresponding save_session() call. If absent or false, loading is considered unsuccessful.

• id - if present, this means that session has to be refreshed. The session cookie will be sent again to the user.

• expire - if id present, this would set new session expiration date.

delete_session( $id )

Remove session from storage.

The default is do nothing and wait for session data to rot by itself.

NOTE It is usually a good idea to cleanup session storage from time to time since some users may go away without logging out (cleaned cookies, laptop eaten by crocodiles etc).

cpanm MVC::Neaf

perl -MCPAN -e shell
install MVC::Neaf