File Coverage

blib/lib/Rubric/WebApp/Login.pm

Criterion	Covered	Total	%
statement	21	24	87.5
branch	6	10	60.0
condition	1	3	33.3
subroutine	7	10	70.0
pod	8	8	100.0
total	43	55	78.1

use strict;
use warnings;
package Rubric::WebApp::Login;
# ABSTRACT: web login processing
$Rubric::WebApp::Login::VERSION = '0.156';
#pod =head1 DESCRIPTION
#pod
#pod This module checks for information needed to confirm that a user is logged into
#pod the Rubric.
#pod
#pod =head1 METHODS
#pod
#pod =head2 Rubric::WebApp::Login->check_for_login($webapp)
#pod
#pod This method is called by the WebApp's C, and checks for a login
#pod attempt in the submitted request.
#pod
#pod It looks for a login username by calling C, then converts
#pod the login name to a Rubric name by calling C and returns
#pod immediately if the name can't be shown valid by calling C.
#pod
#pod It retrieves the User object by calling C or, if needed,
#pod C, and returns if it can't get a User object.  It tries to
#pod authenticate by calling C.  If the user is authorized but
#pod isn't verified, he won't be logged in and the C parameter will be
#pod set on the Rubric::WebApp object.  Otherwise, he will be logged in with
#pod C.
#pod
#pod Most of the methods above are virtual methods in this class, and should be
#pod implemented in subclasses.  The bundled L (the
#pod default) and L serve as examples.
#pod
#pod =cut

sub check_for_login {
	my ($self, $webapp) = @_;

	return unless my $username = $self->get_login_username($webapp);

	$username = $self->map_username($username);
	return unless $self->valid_username($username);
	return unless my $user =
		$self->get_login_user($username) || $self->autocreate_user($username);
	return unless $self->authenticate_login($webapp, $user);
	if ($user->verification_code) {
		$webapp->param('user_pending', 1);
	} else {
		$self->set_current_user($webapp, $user);
	}
}

#pod =head2 get_login_username($webapp)
#pod
#pod This method returns the login username taken from the request.  It is not
#pod necessarily the name of a Rubric user (see C).
#pod
#pod This must be implemented by the login subclass.
#pod
#pod =cut

sub get_login_username { die "get_login_username unimplemented" }

#pod =head2 map_username($username)
#pod
#pod This method returns the Rubric username to which the login name maps.  By
#pod default, it returns the C<$username> verbatim.
#pod
#pod =cut

sub map_username { $_[1] }

#pod =head2 valid_username($username)
#pod
#pod Returns a true or false value, depending on whether the given username string
#pod is a valid username.
#pod
#pod =cut

sub valid_username {
	my ($self, $username) = @_;
	$username =~ /^[\pL\d_]+$/;
}

#pod =head2 get_login_user($username)
#pod
#pod Given a username, this method returns the Rubric::User object for the user.
#pod
#pod =cut

sub get_login_user {
	my ($self, $username) = @_;
	Rubric::User->retrieve($username);
}

#pod =head2 autocreate_user($username)
#pod
#pod If C can't find a user, this method is called to try to create
#pod the user automatically.  By default, it always returns nothing.  It may be
#pod subclassed for implementation.  (For example, one could create domain users
#pod from a directory.)
#pod
#pod =cut

sub autocreate_user { }

#pod =head2 authenticate_login($webapp, $user)
#pod
#pod This method attempts to authenticate the user's login, checking the given
#pod password or performing any other needed check.  It returns true or false.
#pod
#pod This must be implemented by the login subclass.
#pod
#pod =cut

sub authenticate_login { die "authenticate_login unimplemented" }

#pod =head2 set_current_user($webapp, $user)
#pod
#pod This method sets the current user on the WebApp by setting the WebApp's
#pod "current_user" attribute to the Rubric::User object.
#pod
#pod =cut

sub set_current_user {
	my ($self, $webapp, $user) = @_;

	$webapp->param(current_user => $user);
}

1;

__END__