=pod

=head1 NAME

CGI::Session::AUS - Session management for Schema::RDBMS::AUS

=head1 SYNOPSIS

  use CGI::Session::AUS;
  $ENV{AUS_DB_DSN} = 'DBI:Pg:';
  $session = new CGI::Session::AUS();
  $session->login($user, $password);
  $session->param('foo');
  etc..

=head1 DESCRIPTION

CGI::Session::AUS is a subclass of L<CGI::Session|CGI::Session> that
provides access to sessions being used under
L<Schema::RDBMS::AUS|Schema::RDBMS::AUS>. It automatically configures
the session object to use AUS's driver, and also provides access to the
extra information that is stored on a session in the AUS schema.

=head1 USAGE

Create a CGI::Session::AUS object the same way as you would create 
a CGI::Session object; just always make sure the C<driver> is specified
as "C<aus>". By default, CGI::Session::AUS will use the L<Storable|Storable>
serializer to save information to the database. For full details on the
CGI::Session interface, see L<CGI::Session>. The extensions that 
CGI::Session::AUS provides are described below:

=head1 USER METHODS

The following methods help tie sessions to users (also see the "user"
method in L</METADATA METHODS> below):

=over

=item login($user, $pass, %log_options)

Attempt to log a user in with the given username and password.
%log_options is a hash of additional options to pass to
L<Schema::RDBMS::AUS::User|Schema::RDBMS::AUS::User>'s
L<login|Schema::RDBMS::AUS::User/login> method. Some options (ip, etc) will
be automatically set for you by C<log_opts>, documented below.
Any additional parameters passed in will end up in the user's
authentication log.

Logging a user in implicitly flushes the session to the database.

=item logout(%log_options)

If this session has a logged in user, log that user out and disassociate
them from the session.

Logging a user out implicitly flushes the session to the database.

=back

=head1 METADATA METHODS

The following methods can be used to obtain extra information about the
session:

=over

=item user

Returns a L<Schema::RDBMS::AUS::User|Schema::RDBMS::AUS::User> object if
this session is logged in, C<undef> otherwise.

When a session is flushed, if there is an associated user, that user is
always saved as well. B<However>, a session is only flushed if it has
changed. If you have only changed the user and have not changed the
session, you will have to save the user yourself!

=item created

Returns the time that this session was created. The format of this time
will depend on your database engine. Future versions I<may> convert this
to epoch for you (I'm still debating this).

=item time_last

Returns the last time that this session was used.

=back

=head1 UTILITY METHODS

These methods are used internally by C<CGI::Session::AUS>, but you 
might find them nifty too:

=over

=item remote_ip

Returns the remote IP address detected for this session. This comes from
one of two places:

=over

=item The REMOTE_ADDR environment variable

This is set in most CGI and mod_perl environments and is considered the
most accurate.

=item The _SESSION_REMOTE_ADDR session parameter

L<CGI::Session|CGI::Session> does it's own IP detection and puts the
detected remote IP here. If REMOTE_ADDR is not set, we will use this
as the remote IP.

=back

If neither of these sources are filled in, remote_ip returns C<undef>.

=item log_opts

Returns a hash containing options suitable to pass to
L<Schema::RDBMS::AUS::User|Schema::RDBMS::AUS::User>'s C<login> and
C<logout> methods, to provide information to write in the authentication
log. The following key/value pairs can be returned:

=over

=item ip

The user's remote IP address, as returned by C<remote_ip> (documented above).

=item session_id

This session's unique ID string.

=item name

If we are logged in, the logged in user's name.

=item id

If we are logged in, the logged in user's ID.

=item _dbh

Our database handle, so that it can be shared with the user object.

=back

=back

=head1 OVERRIDDEN METHODS

The whole purpose of CGI::Session::AUS is to integrate
L<Schema::RDBMS::AUS::User|Schema::RDBMS::AUS::User> with
L<CGI::Session|CGI::Session>. In order to facilitate this,
the following CGI::Session methods have been overridden in
CGI::Session::AUS:

=over

=item flush

=over

=item *

When a CGI::Session::AUS session is flushed, we store some
meta-data about the session in the AUS schema as well. 

=item *

When a deleted session is flushed, we delete the metadata from
the session object along with the regular session data.

=back

=item load

=over

=item *

If a session ID is not specified, we look in the AUS_SESSION_ID
environment variable for a default value. This variable is set by
higher-level handlers like L<Apache2::AUS|Apache2::AUS>.

=item *

We use L<CGI::Session::Serialize::yaml|CGI::Session::Serialize::yaml>
as our default serializer to encourage compatibility with other programming
languages.

=item *

Whenever a session is loaded, we load it's metadata (including a
L<Schema::RDBMS::AUS::User|Schema::RDBMS::AUS::User> object if the session
is logged in) along with it.

=back

=back

=head1 AUTHOR

Tyler "Crackerjack" MacDonald <japh@crackerjack.net>

=head1 LICENSE

Copyright 2006 Tyler "Crackerjack" MacDonald <japh@crackerjack.net>

This is free software; You may distribute it under the same terms as perl
itself.

=head1 SEE ALSO

L<CGI::Session>, L<Schema::RDBMS::AUS>, L<Schema::RDBMS::AUS::User>.

=cut