Catalyst::Authentication::Realm - Base class for realm objects.

package Catalyst::Authentication::Realm;

use strict;
use warnings;

use base qw/Class::Accessor::Fast/;

BEGIN {
    __PACKAGE__->mk_accessors(qw/store credential name config/);
};

## Add use_session config item to realm.

sub new {
    my ($class, $realmname, $config, $app) = @_;

    my $self = { config => $config };
    bless $self, $class;
    
    $self->name($realmname);
    
    if (!exists($self->config->{'use_session'})) {
        if (exists($app->config->{'Plugin::Authentication'}{'use_session'})) {
            $self->config->{'use_session'} = $app->config->{'Plugin::Authentication'}{'use_session'};
        } else {
            $self->config->{'use_session'} = 1;
        }
    }

    $app->log->debug("Setting up auth realm $realmname") if $app->debug;

    # use the Null store as a default - Don't complain if the realm class is being overridden, 
    # as the new realm may behave differently.
    if( ! exists($config->{store}{class}) ) {
        $config->{store}{class} = '+Catalyst::Authentication::Store::Null';
        if (! exists($config->{class})) {
            $app->log->debug( qq(No Store specified for realm "$realmname", using the Null store.) );
        }
    } 
    my $storeclass = $config->{'store'}{'class'};
    
    ## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
    ## taken to mean C::P::A::Store::(specifiedclass)
    if ($storeclass !~ /^\+(.*)$/ ) {
        $storeclass = "Catalyst::Authentication::Store::${storeclass}";
    } else {
        $storeclass = $1;
    }

    # a little niceness - since most systems seem to use the password credential class, 
    # if no credential class is specified we use password.
    $config->{credential}{class} ||= '+Catalyst::Authentication::Credential::Password';

    my $credentialclass = $config->{'credential'}{'class'};
    
    ## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
    ## taken to mean C::A::Credential::(specifiedclass)
    if ($credentialclass !~ /^\+(.*)$/ ) {
        $credentialclass = "Catalyst::Authentication::Credential::${credentialclass}";
    } else {
        $credentialclass = $1;
    }
    
    # if we made it here - we have what we need to load the classes
    
    ### BACKWARDS COMPATIBILITY - DEPRECATION WARNING:  
    ###  we must eval the ensure_class_loaded - because we might need to try the old-style
    ###  ::Plugin:: module naming if the standard method fails. 
    
    ## Note to self - catch second exception and bitch in detail?
    
    eval {
        Catalyst::Utils::ensure_class_loaded( $credentialclass );
    };
    
    if ($@) {
        # If the file is missing, then try the old-style fallback, 
        # but re-throw anything else for the user to deal with.
        die unless $@ =~ /^Can't locate/;
        $app->log->warn( qq(Credential class "$credentialclass" not found, trying deprecated ::Plugin:: style naming. ) );
        my $origcredentialclass = $credentialclass;
        $credentialclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;

        eval { Catalyst::Utils::ensure_class_loaded( $credentialclass ); };
        if ($@) {
            # Likewise this croak is useful if the second exception is also "not found",
            # but would be confusing if it's anything else.
            die unless $@ =~ /^Can't locate/;
            Carp::croak "Unable to load credential class, " . $origcredentialclass . " OR " . $credentialclass . 
                        " in realm " . $self->name;
        }
    }
    
    eval {
        Catalyst::Utils::ensure_class_loaded( $storeclass );
    };
    
    if ($@) {
        # If the file is missing, then try the old-style fallback, 
        # but re-throw anything else for the user to deal with.
        die unless $@ =~ /^Can't locate/;
        $app->log->warn( qq(Store class "$storeclass" not found, trying deprecated ::Plugin:: style naming. ) );
        my $origstoreclass = $storeclass;
        $storeclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;
        eval { Catalyst::Utils::ensure_class_loaded( $storeclass ); };
        if ($@) {
            # Likewise this croak is useful if the second exception is also "not found",
            # but would be confusing if it's anything else.
            die unless $@ =~ /^Can't locate/;
            Carp::croak "Unable to load store class, " . $origstoreclass . " OR " . $storeclass . 
                        " in realm " . $self->name;
        }
    }
    
    # BACKWARDS COMPATIBILITY - if the store class does not define find_user, we define it in terms 
    # of get_user and add it to the class.  this is because the auth routines use find_user, 
    # and rely on it being present. (this avoids per-call checks)
    if (!$storeclass->can('find_user')) {
        no strict 'refs';
        *{"${storeclass}::find_user"} = sub {
                                                my ($self, $info) = @_;
                                                my @rest = @{$info->{rest}} if exists($info->{rest});
                                                $self->get_user($info->{id}, @rest);
                                            };
    }
    
    ## a little cruft to stay compatible with some poorly written stores / credentials
    ## we'll remove this soon.
    if ($storeclass->can('new')) {
        $self->store($storeclass->new($config->{'store'}, $app, $self));
    } else {
        $app->log->error("THIS IS DEPRECATED: $storeclass has no new() method - Attempting to use uninstantiated");
        $self->store($storeclass);
    }
    if ($credentialclass->can('new')) {
        $self->credential($credentialclass->new($config->{'credential'}, $app, $self));
    } else {
        $app->log->error("THIS IS DEPRECATED: $credentialclass has no new() method - Attempting to use uninstantiated");
        $self->credential($credentialclass);
    }
    
    return $self;
}

sub find_user {
    my ( $self, $authinfo, $c ) = @_;

    my $res = $self->store->find_user($authinfo, $c);
    
    if (!$res) {
      if ($self->config->{'auto_create_user'} && $self->store->can('auto_create_user') ) {
          $res = $self->store->auto_create_user($authinfo, $c);
      }
    } elsif ($self->config->{'auto_update_user'} && $self->store->can('auto_update_user')) {
        $res = $self->store->auto_update_user($authinfo, $c, $res);
    } 
    
    return $res;
}

sub authenticate {
     my ($self, $c, $authinfo) = @_;

     my $user = $self->credential->authenticate($c, $self, $authinfo);
     if (ref($user)) {
         $c->set_authenticated($user, $self->name);
         return $user;
     } else {
         return undef;
     }
}

sub user_is_restorable {
    my ($self, $c) = @_;
    
    return unless
         $c->can('session')
         and $self->config->{'use_session'}
         and $c->session_is_valid;

    return $c->session->{__user};
}

sub restore_user {
    my ($self, $c, $frozen_user) = @_;
    
    $frozen_user ||= $self->user_is_restorable($c);
    return unless defined($frozen_user);

    my $user = $self->from_session( $c, $frozen_user );
    
    if ($user) {
        $c->_user( $user );
    
        # this sets the realm the user originated in.
        $user->auth_realm($self->name);
    } 
    else {
        $self->failed_user_restore($c) ||
            $c->error("Store claimed to have a restorable user, but restoration failed.  Did you change the user's id_field?");
	}
	 
    return $user;
}

## this occurs if there is a session but the thing the session refers to
## can not be found.  Do what you must do here.
## Return true if you can fix the situation and find a user, false otherwise
sub failed_user_restore {
	my ($self, $c) = @_;
	
	$self->remove_persisted_user($c);
	return;
}

sub persist_user {
    my ($self, $c, $user) = @_;
    
    if (
        $c->can('session')
        and $self->config->{'use_session'}
        and $user->supports("session") 
    ) {
        $c->session->{__user_realm} = $self->name;
    
        # we want to ask the store for a user prepared for the session.
        # but older modules split this functionality between the user and the
        # store.  We try the store first.  If not, we use the old method.
        if ($self->store->can('for_session')) {
            $c->session->{__user} = $self->store->for_session($c, $user);
        } else {
            $c->session->{__user} = $user->for_session;
        }
    }
    return $user;
}

sub remove_persisted_user {
    my ($self, $c) = @_;
    
    if (
        $c->can('session')
        and $self->config->{'use_session'}
        and $c->session_is_valid
    ) {
        delete @{ $c->session }{qw/__user __user_realm/};
    }    
}

## backwards compatibility - I don't think many people wrote realms since they
## have only existed for a short time - but just in case.
sub save_user_in_session {
    my ( $self, $c, $user ) = @_;

    return $self->persist_user($c, $user);
}

sub from_session {
    my ($self, $c, $frozen_user) = @_;
    
    return $self->store->from_session($c, $frozen_user);
}


__PACKAGE__;

__END__