From: Chris W. <la...@us...> - 2003-07-28 03:01:57
|
Update of /cvsroot/openinteract/OpenInteract2/lib/OpenInteract2/Auth In directory sc8-pr-cvs1:/tmp/cvs-serv12049 Modified Files: User.pm Log Message: add docs; modify all routines except 'get_user' to be internal but documented for subclassers Index: User.pm =================================================================== RCS file: /cvsroot/openinteract/OpenInteract2/lib/OpenInteract2/Auth/User.pm,v retrieving revision 1.10 retrieving revision 1.11 diff -C2 -d -r1.10 -r1.11 *** User.pm 3 Jul 2003 05:37:08 -0000 1.10 --- User.pm 28 Jul 2003 03:01:55 -0000 1.11 *************** *** 18,32 **** # Check to see if the user is in the session ! my $user_refresh = $server_config->{session_info}{cache_user}; ! ( $user, $user_id ) = $class->get_cached_user( $user_refresh ); if ( $user ) { $is_logged_in++; } else { ! $user_id ||= $class->get_user_id; if ( $user_id ) { $log->is_debug && $log->debug( "Found user ID [$user_id]; fetching user" ); ! $user = eval { $class->fetch_user( $user_id ) }; # If there's a failure fetching the user, we need to ensure that --- 18,31 ---- # Check to see if the user is in the session ! ( $user, $user_id ) = $class->_get_cached_user; if ( $user ) { $is_logged_in++; } else { ! $user_id ||= $class->_get_user_id; if ( $user_id ) { $log->is_debug && $log->debug( "Found user ID [$user_id]; fetching user" ); ! $user = eval { $class->_fetch_user( $user_id ) }; # If there's a failure fetching the user, we need to ensure that *************** *** 36,46 **** if ( $@ or ! $user ) { my $error = $@ || 'User not found'; ! $class->fetch_user_failed( $user_id, $error ); } else { $log->is_debug && $log->debug( "User found [$user->{login_name}]" ); ! $class->check_first_login( $user ); ! $class->set_cached_user( $user, $user_refresh ); $is_logged_in++; } --- 35,45 ---- if ( $@ or ! $user ) { my $error = $@ || 'User not found'; ! $class->_fetch_user_failed( $user_id, $error ); } else { $log->is_debug && $log->debug( "User found [$user->{login_name}]" ); ! $class->_check_first_login( $user ); ! $class->_set_cached_user( $user ); $is_logged_in++; } *************** *** 57,61 **** # If no user info found, check to see if the user logged in ! $user = $class->login_user_from_input; # If so, see if it's the first one and if we should 'remember' the --- 56,60 ---- # If no user info found, check to see if the user logged in ! $user = $class->_login_user_from_input; # If so, see if it's the first one and if we should 'remember' the *************** *** 63,69 **** if ( $user ) { ! $class->check_first_login( $user ); ! $class->remember_login( $user ); ! $class->set_cached_user( $user, $user_refresh ); $is_logged_in++; } --- 62,68 ---- if ( $user ) { ! $class->_check_first_login( $user ); ! $class->_remember_login( $user ); ! $class->_set_cached_user( $user ); $is_logged_in++; } *************** *** 78,82 **** delete $session->{user_id}; } ! $user = $class->create_nologin_user; } return ( $user, $is_logged_in ); --- 77,82 ---- delete $session->{user_id}; } ! $user = $class->_create_nologin_user; ! $is_logged_in = 0; } return ( $user, $is_logged_in ); *************** *** 86,94 **** # TODO: I don't like that this returns a user and user_id... ! sub get_cached_user { ! my ( $class, $user_refresh ) = @_; my $log = get_logger( LOG_AUTH ); - return unless ( $user_refresh > 0 ); my ( $user, $user_id ); my $session = CTX->request->session; --- 86,96 ---- # TODO: I don't like that this returns a user and user_id... ! sub _get_cached_user { ! my ( $class ) = @_; ! my $user_refresh = CTX->lookup_session_config->{cache_user}; ! return unless ( $user_refresh > 0 ); ! my $log = get_logger( LOG_AUTH ); my ( $user, $user_id ); my $session = CTX->request->session; *************** *** 115,121 **** # Just grab the user_id from somewhere ! sub get_user_id { my ( $class ) = @_; my $session = CTX->request->session; --- 117,138 ---- + sub _set_cached_user { + my ( $class, $user ) = @_; + my $user_refresh = CTX->lookup_session_config->{cache_user}; + return unless ( $user_refresh > 0 ); + + my $log = get_logger( LOG_AUTH ); + + my $session = CTX->request->session; + $session->{_oi_cache}{user} = $user; + $session->{_oi_cache}{user_refresh_on} = time + ( $user_refresh * 60 ); + $log->is_debug && + $log->debug( "Set user to session cache, expires in ", + "[$user_refresh] minutes" ); + } + # Just grab the user_id from somewhere ! sub _get_user_id { my ( $class ) = @_; my $session = CTX->request->session; *************** *** 127,131 **** # fetch(), this should die if it fails) ! sub fetch_user { my ( $class, $user_id ) = @_; return CTX->lookup_object( 'user' ) --- 144,148 ---- # fetch(), this should die if it fails) ! sub _fetch_user { my ( $class, $user_id ) = @_; return CTX->lookup_object( 'user' ) *************** *** 136,140 **** # What to do if the user fetch fails ! sub fetch_user_failed { my ( $class, $user_id, $error ) = @_; my $log = get_logger( LOG_AUTH ); --- 153,157 ---- # What to do if the user fetch fails ! sub _fetch_user_failed { my ( $class, $user_id, $error ) = @_; my $log = get_logger( LOG_AUTH ); *************** *** 147,157 **** # passed in; if so, try and login the user and track the info ! sub login_user_from_input { my ( $class ) = @_; my $log = get_logger( LOG_AUTH ); ! my $server_config = CTX->server_config; ! ! my $login_field = $server_config->{login}{login_field}; ! my $password_field = $server_config->{login}{password_field}; unless ( $login_field and $password_field ) { $log->error( "No login/password field configured; please set ", --- 164,173 ---- # passed in; if so, try and login the user and track the info ! sub _login_user_from_input { my ( $class ) = @_; my $log = get_logger( LOG_AUTH ); ! my $login_config = CTX->lookup_login_config; ! my $login_field = $login_config->{login_field}; ! my $password_field = $login_config->{password_field}; unless ( $login_field and $password_field ) { $log->error( "No login/password field configured; please set ", *************** *** 205,209 **** # TODO: Check if this is working, if it's needed, ... ! sub check_first_login { my ( $class, $user ) = @_; my $log = get_logger( LOG_AUTH ); --- 221,225 ---- # TODO: Check if this is working, if it's needed, ... ! sub _check_first_login { my ( $class, $user ) = @_; my $log = get_logger( LOG_AUTH ); *************** *** 228,237 **** # If we created a user, make the expiration transient unless told otherwise. ! sub remember_login { my ( $class, $user ) = @_; my $log = get_logger( LOG_AUTH ); ! my $server_config = CTX->server_config; ! if ( $server_config->{login}{always_remember} ) { $log->is_debug && $log->debug( "Configured to always remember users" ); --- 244,253 ---- # If we created a user, make the expiration transient unless told otherwise. ! sub _remember_login { my ( $class, $user ) = @_; my $log = get_logger( LOG_AUTH ); ! my $login_config = CTX->lookup_login_config; ! if ( $login_config->{always_remember} ) { $log->is_debug && $log->debug( "Configured to always remember users" ); *************** *** 240,244 **** my $request = CTX->request; ! my $remember_field = $server_config->{login}{remember_field}; my ( $do_remember ); if ( $remember_field ) { --- 256,260 ---- my $request = CTX->request; ! my $remember_field = $login_config->{remember_field}; my ( $do_remember ); if ( $remember_field ) { *************** *** 254,260 **** # Create a 'dummy' user ! sub create_nologin_user { my ( $class ) = @_; ! my $default_theme_id = CTX->server_config->{default_objects}{theme}; return CTX->lookup_object( 'user' ) ->new({ login_name => 'anonymous', --- 270,276 ---- # Create a 'dummy' user ! sub _create_nologin_user { my ( $class ) = @_; ! my $default_theme_id = CTX->default_object_id( 'theme' ); return CTX->lookup_object( 'user' ) ->new({ login_name => 'anonymous', *************** *** 265,283 **** } - sub set_cached_user { - my ( $class, $user, $user_refresh ) = @_; - my $log = get_logger( LOG_AUTH ); - - return unless ( $user_refresh > 0 ); - my $session = CTX->request->session; - $session->{_oi_cache}{user} = $user; - $session->{_oi_cache}{user_refresh_on} = time + ( $user_refresh * 60 ); - $log->is_debug && - $log->debug( "Set user to session cache, expires in ", - "[$user_refresh] minutes" ); - } - - - 1; --- 281,284 ---- *************** *** 290,306 **** =head1 SYNOPSIS =head1 DESCRIPTION =head1 METHODS ! =head1 BUGS ! None known. ! =head1 TO DO ! Nothing known. ! =head1 SEE ALSO =head1 COPYRIGHT --- 291,429 ---- =head1 SYNOPSIS + # Called by OI2::Auth + + my ( $user, $is_logged_in ) = + OpenInteract2::Auth::User->get_user; + print "User ", $user->login_name, " logged in? ", $is_logged_in, "\n"; + =head1 DESCRIPTION + Handles retrieving a user object. If no user is logged in should still + return a user object, just one that isn't persisted to a database. + =head1 METHODS ! =head2 Public Interface ! B<get_user()> ! Returns a user and a flag indicating whether the user is logged ! in. Here's the process it uses: ! =over 4 ! =item * ! ! It first checks a cache (calling C<_get_cached_user()>), which generally ! means the session. You control whether the user object is cached in ! the session with the 'session_info.cache_user' key. ! ! If a user is found in the cache we set the 'logged-in' flag set to ! true. ! ! =item * ! ! If no user is found in the cache it checks for a user ID (calling ! C<_get_user_id()>). ! ! =item * ! ! If a user ID is found it tries to fetch the user matching it (calling ! C<_fetch_user()>). If that fetch fails we call ! C<_fetch_user_failed()>, passing along the user ID we tried to fetch ! and an error message. ! ! =item * ! ! If the fetch succeeds we call C<_check_first_login()> with the user ! object to run any initialization routines and then ! C<_set_cached_user()> with the user object so that it may be cached if ! necessary. We also flip the 'logged-in' flag to true. ! ! =back ! ! At this point if we have a user object we return it with the ! 'logged-in' flag. ! ! =over 4 ! ! =item * ! ! Next we try to fetch the user information from the request input. This ! maps to someone logging in using a GET/POST form. ! ! =item * ! ! If we find the user from the request input we pass the user to each of ! the following calls: C<_check_first_login()> (same as above), ! C<_remember_login()> (sets a flag for the session to pickup whether ! the session is transient or permanent) and C<_set_cached_user()> (same ! as above). We also flip the 'logged-in' flag. ! ! =item * ! ! If we don't find the user from the request input we call ! C<_create_nologin_user()> to return a transient user object; we also ! set the 'logged-in' flag to false. ! ! =back ! ! Finally we return the user object and logged-in flag. ! ! =head2 Overridable Methods ! ! The following methods are overridable by subclasses. Mix and match ! however you like. ! ! B<_get_cached_user()> ! ! Retrieves the user from a cache. By default this looks in the session, ! but you can use other means. ! ! Returns: two-item list, user object and user ID. ! ! B<_set_cached_user( $user )> ! ! If a cache is configured saves C<$user> there. Otherwise does nothing. ! ! B<_get_user_id()> ! ! Returns the user ID associated with this session. ! ! B<_fetch_user( $user_id )> ! ! Retrieves the user from permanent storage matching ID C<$user_id>. If ! the operation fails it should throw an exception. ! ! B<_fetch_user_failed( $user_id, $error_msg )> ! ! Called when C<_fetch_user()> throws an exception or fails to return a ! user. ! ! B<_login_user_from_input()> ! ! Finds the username from the request field specified in ! 'login.login_field' and the password from 'login.password_field' and ! tries to fetch a user by the name and log her in. ! ! If a user is found and authenticated, return the user ! object. Otherwise return undef. ! ! B<_check_first_login( $user )> ! ! See if C<$user> has logged in for the first time and perform any ! necessary actions. ! ! B<_remember_login( $user )> ! ! If the value for the request field specified in 'login.remember_field' ! is set to true then we 'remember' the user by default. This generally ! means the session won't expire when the user closes her browser. ! ! B<_create_nologin_user()> ! ! Return a transient user object. This object should normally not be ! saved to the database but created on the fly with a known username and ! ID. The ID of the theme should be set to 'default_objects.theme'. =head1 COPYRIGHT |