authlogic 1.4.3 → 2.0.0

data/lib/authlogic/session/{perishability.rb → perishable_token.rb}

@@ -1,17 +1,17 @@
 module Authlogic
   module Session
-    # = Perishability
-    #
     # Maintains the perishable token, which is helpful for confirming records or authorizing records to reset their password. All that this
     # module does is reset it after a session have been saved, just keep it changing. The more it changes, the tighter the security.
-    module Perishability
+    #
+    # See Authlogic::ActsAsAuthentic::PerishableToken for more information.
+    module PerishableToken
       def self.included(klass)
         klass.after_save :reset_perishable_token!
       end
       
       private
         def reset_perishable_token!
-          record.send("reset_#{perishable_token_field}") if record.respond_to?("reset_#{perishable_token_field}") && !record.send("disable_#{perishable_token_field}_maintenance?")
+          record.reset_perishable_token if record.respond_to?(:reset_perishable_token) && !record.disable_perishable_token_maintenance?
         end
     end
   end

data/lib/authlogic/session/persistence.rb

@@ -0,0 +1,70 @@
+module Authlogic
+  module Session
+    # Responsible for allowing you to persist your sessions.
+    module Persistence
+      def self.included(klass)
+        klass.class_eval do
+          extend ClassMethods
+          include InstanceMethods
+        end
+      end
+      
+      module ClassMethods
+        # This is how you persist a session. This finds the record for the current session using
+        # a variety of methods. It basically tries to "log in" the user without the user having
+        # to explicitly log in. Check out the other Authlogic::Session modules for more information.
+        #
+        # The best way to use this method is something like:
+        #
+        #   helper_method :current_user_session, :current_user
+        #
+        #   def current_user_session
+        #     return @current_user_session if defined?(@current_user_session)
+        #     @current_user_session = UserSession.find
+        #   end
+        #
+        #   def current_user
+        #     return @current_user if defined?(@current_user)
+        #     @current_user = current_user_session && current_user_session.user
+        #   end
+        #
+        # Also, this method accepts a single parameter as the id, to find session that you marked with an id:
+        #
+        #   UserSession.find(:secure)
+        #
+        # See the id method for more information on ids.
+        def find(id = nil, priority_record = nil)
+          session = new({:priority_record => priority_record}, id)
+          session.priority_record = priority_record
+          if session.persisting?
+            session
+          else
+            nil
+          end
+        end
+      end
+      
+      module InstanceMethods
+        # Let's you know if the session is being persisted or not, meaning the user does not have to explicitly log in
+        # in order to be logged in. If the session has no associated record, it will try to find a record and persis
+        # the session. This is the method that the class level method find uses to ultimately persist the session.
+        def persisting?
+          return true if !record.nil?
+          self.attempted_record = nil
+          before_persisting
+          persist
+          ensure_authentication_attempted
+          if errors.empty? && !attempted_record.nil?
+            self.record = attempted_record
+            after_persisting
+            save_record
+            self.new_session = false
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/authlogic/session/priority_record.rb

@@ -0,0 +1,34 @@
+module Authlogic
+  module Session
+    # The point of this module is to avoid the StaleObjectError raised when lock_version is implemented in ActiveRecord.
+    # We accomplish this by using a "priority record". Meaning this record is used if possible, it gets priority.
+    # This way we don't save a record behind the scenes thus making an object being used stale.
+    module PriorityRecord
+      def self.included(klass)
+        klass.class_eval do
+          attr_accessor :priority_record
+        end
+      end
+      
+      # Setting priority record if it is passed. The only way it can be passed is through an array:
+      #
+      #   session.credentials = [real_user_object, priority_user_object]
+      def credentials=(value)
+        super
+        values = value.is_a?(Array) ? value : [value]
+        self.priority_record = values.second if values.second.class < ::ActiveRecord::Base
+      end
+      
+      private
+        def attempted_record=(value)
+          value = priority_record if value == priority_record
+          super
+        end
+        
+        def save_record(alternate_record = nil)
+          r = alternate_record || record
+          super if r != priority_record
+        end
+    end
+  end
+end

data/lib/authlogic/session/scopes.rb

@@ -1,55 +1,15 @@
 module Authlogic
   module Session
-    # = Scopes
+    # Authentication can be scoped, and it's easy, you just need to define how you want to scope everything. This should help you:
     #
-    # Authentication can be scoped, but scoping authentication can get a little tricky. Checkout the section "Scoping" in the readme for more details.
-    #
-    # What with_scopes focuses on is scoping the query when finding the object and the name of the cookie / session. It works very similar to
-    # ActiveRecord::Base#with_scopes. It accepts a hash with any of the following options:
-    #
-    # * <tt>find_options:</tt> any options you can pass into ActiveRecord::Base.find. This is used when trying to find the record.
-    # * <tt>id:</tt> The id of the session, this gets merged with the real id. For information ids see the id method.
-    #
-    # Here is how you use it:
-    #
-    #   UserSession.with_scope(:find_options => {:conditions => "account_id = 2"}, :id => "account_2") do
-    #     UserSession.find
-    #   end
-    #
-    # Eseentially what the above does is scope the searching of the object with the sql you provided. So instead of:
-    #
-    #   User.find(:first, :conditions => "login = 'ben'")
-    #
-    # it would be:
-    #
-    #   User.find(:first, :conditions => "login = 'ben' and account_id = 2")
-    #
-    # You will also notice the :id option. This works just like the id method. It scopes your cookies. So the name of your cookie will be:
-    #
-    #   account_2_user_credentials
-    #
-    # instead of:
-    #
-    #   user_credentials
-    #
-    # What is also nifty about scoping with an :id is that it merges your id's. So if you do:
-    #
-    #   UserSession.with_scope(:find_options => {:conditions => "account_id = 2"}, :id => "account_2") do
-    #     session = UserSession.new
-    #     session.id = :secure
-    #   end
-    #
-    # The name of your cookies will be:
-    #
-    #   secure_account_2_user_credentials
+    # 1. Want to scope by a parent object? Ex: An account has many users. Checkout Authlogic::AuthenticatesMany
+    # 2. Want to scope the validations in your model? Ex: 2 users can have the same login under different accounts. See Authlogic::ActsAsAuthentic::Scope
     module Scopes # :nodoc:
       def self.included(klass)
-        klass.extend(ClassMethods)
-        klass.send(:include, InstanceMethods)
         klass.class_eval do
+          extend ClassMethods
+          include InstanceMethods
           attr_writer :scope
-          alias_method_chain :initialize, :scopes
-          alias_method_chain :search_for_record, :scopes
         end
       end
       
@@ -60,7 +20,44 @@ module Authlogic
           Thread.current[:authlogic_scope]
         end
         
-        # See the documentation for this class for more information on how to use this method.
+        # What with_scopes focuses on is scoping the query when finding the object and the name of the cookie / session. It works very similar to
+        # ActiveRecord::Base#with_scopes. It accepts a hash with any of the following options:
+        #
+        # * <tt>find_options:</tt> any options you can pass into ActiveRecord::Base.find. This is used when trying to find the record.
+        # * <tt>id:</tt> The id of the session, this gets merged with the real id. For information ids see the id method.
+        #
+        # Here is how you use it:
+        #
+        #   UserSession.with_scope(:find_options => {:conditions => "account_id = 2"}, :id => "account_2") do
+        #     UserSession.find
+        #   end
+        #
+        # Eseentially what the above does is scope the searching of the object with the sql you provided. So instead of:
+        #
+        #   User.find(:first, :conditions => "login = 'ben'")
+        #
+        # it would be:
+        #
+        #   User.find(:first, :conditions => "login = 'ben' and account_id = 2")
+        #
+        # You will also notice the :id option. This works just like the id method. It scopes your cookies. So the name of your cookie will be:
+        #
+        #   account_2_user_credentials
+        #
+        # instead of:
+        #
+        #   user_credentials
+        #
+        # What is also nifty about scoping with an :id is that it merges your id's. So if you do:
+        #
+        #   UserSession.with_scope(:find_options => {:conditions => "account_id = 2"}, :id => "account_2") do
+        #     session = UserSession.new
+        #     session.id = :secure
+        #   end
+        #
+        # The name of your cookies will be:
+        #
+        #   secure_account_2_user_credentials
         def with_scope(options = {}, &block)
           raise ArgumentError.new("You must provide a block") unless block_given?
           self.scope = options
@@ -76,21 +73,28 @@ module Authlogic
       end
       
       module InstanceMethods
-        def initialize_with_scopes(*args) # :nodoc:
+        # Setting the scope if it exists upon instantiation.
+        def initialize(*args)
           self.scope = self.class.scope
-          initialize_without_scopes(*args)
+          super
         end
         
-        # See the documentation for this class for more information on how to use this method.
+        # The scope of the current object
         def scope
           @scope ||= {}
         end
         
-        def search_for_record_with_scopes(*args) # :nodoc:
-          klass.send(:with_scope, :find => (scope[:find_options] || {})) do
-            search_for_record_without_scopes(*args)
+        private
+          # Used for things like cookie_key, session_key, etc.
+          def build_key(last_part)
+            [scope[:id], super].compact.join("_")
+          end
+          
+          def search_for_record(*args)
+            klass.send(:with_scope, :find => (scope[:find_options] || {})) do
+              klass.send(*args)
+            end
           end
-        end
       end
     end
   end

data/lib/authlogic/session/session.rb

@@ -1,45 +1,60 @@
 module Authlogic
   module Session
-    # = Session
-    #
     # Handles all parts of authentication that deal with sessions. Such as persisting a session and saving / destroy a session.
     module Session
       def self.included(klass)
-        klass.after_save :update_session, :if => :persisting?
-        klass.after_destroy :update_session, :if => :persisting?
-        klass.after_find :update_session, :if => :persisting? # to continue persisting the session after an http_auth request
+        klass.class_eval do
+          extend Config
+          include InstanceMethods
+          persist :persist_by_session
+          after_save :update_session
+          after_destroy :update_session
+          after_persisting :update_session, :unless => :single_access?
+        end
       end
       
-      # Tries to validate the session from information in the session
-      def valid_session?
-        persistence_token, record_id = session_credentials
-        if !persistence_token.blank?
-          if record_id
-            record = search_for_record("find_by_#{klass.primary_key}", record_id)
-            self.unauthorized_record = record if record && record.send(persistence_token_field) == persistence_token
-          else
-            # For backwards compatibility, will eventually be removed, just need to let the sessions update theirself
-            record = search_for_record("find_by_#{persistence_token_field}", persistence_token)
-            if record
-              controller.session["#{session_key}_id"] = record.send(record.class.primary_key)
-              self.unauthorized_record = record
-            end
-          end
-          valid?
-        else
-          false
+      # Configuration for the session feature.
+      module Config
+        # Works exactly like cookie_key, but for sessions. See cookie_key for more info.
+        #
+        # * <tt>Default:</tt> cookie_key
+        # * <tt>Accepts:</tt> Symbol or String
+        def session_key(value = nil)
+          config(:session_key, value, cookie_key)
         end
+        alias_method :session_key=, :session_key
       end
       
-      private
-        def session_credentials
-          [controller.session[session_key], controller.session["#{session_key}_id"]].compact
-        end
+      # Instance methods for the session feature.
+      module InstanceMethods
+        private
+          # Tries to validate the session from information in the session
+          def persist_by_session
+            persistence_token, record_id = session_credentials
+            if !persistence_token.nil?
+              # Allow finding by persistence token, because when records are created the session is maintained in a before_save, when there is no id.
+              # This is done for performance reasons and to save on queries.
+              record = record_id.nil? ? search_for_record("find_by_persistence_token", persistence_token) : search_for_record("find_by_#{klass.primary_key}", record_id)
+              self.unauthorized_record = record if record && record.persistence_token == persistence_token
+              valid?
+            else
+              false
+            end
+          end
+          
+          def session_credentials
+            [controller.session[session_key], controller.session["#{session_key}_#{klass.primary_key}"]].compact
+          end
+          
+          def session_key
+            build_key(self.class.session_key)
+          end
         
-        def update_session
-          controller.session[session_key] = record && record.send(persistence_token_field)
-          controller.session["#{session_key}_id"] = record && record.send(record.class.primary_key)
-        end
+          def update_session
+            controller.session[session_key] = record && record.persistence_token
+            controller.session["#{session_key}_#{klass.primary_key}"] = record && record.send(record.class.primary_key)
+          end
+      end
     end
   end
 end

data/lib/authlogic/session/timeout.rb

@@ -1,48 +1,82 @@
 module Authlogic
   module Session
-    # = Timeout
+    # Think about financial websites, if you are inactive for a certain period of time you will be asked to
+    # log back in on your next request. You can do this with Authlogic easily, there are 2 parts to this:
     #
-    # This is reponsibile for determining if the session is stale or fresh. It is also responsible for maintaining the last_request_at value if the column is present.
+    # 1. Define the timeout threshold:
     #
-    # Think about how financial websites work. If you are inactive after a certain period of time you must log back in. By default this is disabled, but if enabled this
-    # module kicks in. See the logout_on_timeout configuration option for how to turn this on.
+    #   acts_as_authentic do |c|
+    #     c.logged_in_timeout = 10.minutes # default is 10.minutes
+    #   end
+    #
+    # 2. Enable logging out on timeouts
+    #
+    #   class UserSession < Authlogic::Session::Base
+    #     logout_on_timeout true # default if false
+    #   end
+    #
+    # This will require a user to log back in if they are inactive for more than 10 minutes. In order for
+    # this feature to be used you must have a last_request_at datetime column in your table for whatever model
+    # you are authenticating with.
     module Timeout
       def self.included(klass)
         klass.class_eval do
-          alias_method_chain :find_record, :timeout
-          before_find :reset_stale_state
-          after_find :set_last_request_at
-          before_save :set_last_request_at
+          extend Config
+          include InstanceMethods
+          before_persisting :reset_stale_state
+          after_persisting :enforce_timeout
+          attr_accessor :stale_record
         end
       end
       
-      # This implements the stale functionality when trying to find a session. If the session is stale the record will be cleared, but the session object will still be
-      # returned. This allows you to perform a current_user_session.stale? query in order to inform your users of why they need to log back in.
-      def find_record_with_timeout
-        result = find_record_without_timeout
-        if result && stale?
-          self.record = nil
-          @stale = true
+      # Configuration for the timeout feature.
+      module Config
+        # With acts_as_authentic you get a :logged_in_timeout configuration option. If this is set, after this amount of time has passed the user
+        # will be marked as logged out. Obviously, since web based apps are on a per request basis, we have to define a time limit threshold that
+        # determines when we consider a user to be "logged out". Meaning, if they login and then leave the website, when do mark them as logged out?
+        # I recommend just using this as a fun feature on your website or reports, giving you a ballpark number of users logged in and active. This is
+        # not meant to be a dead accurate representation of a users logged in state, since there is really no real way to do this with web based apps.
+        # Think about a user that logs in and doesn't log out. There is no action that tells you that the user isn't technically still logged in and
+        # active.
+        #
+        # That being said, you can use that feature to require a new login if their session timesout. Similar to how financial sites work. Just set this option to
+        # true and if your record returns true for stale? then they will be required to log back in.
+        #
+        # Lastly, UserSession.find will still return a object is the session is stale, but you will not get a record. This allows you to determine if the
+        # user needs to log back in because their session went stale, or because they just aren't logged in. Just call current_user_session.stale? as your flag.
+        #
+        # * <tt>Default:</tt> false
+        # * <tt>Accepts:</tt> Boolean
+        def logout_on_timeout(value = nil)
+          config(:logout_on_timeout, value, false)
         end
-        result
+        alias_method :logout_on_timeout=, :logout_on_timeout
       end
-    
-      # Tells you if the record is stale or not. Meaning the record has timed out. This will only return true if you set logout_on_timeout to true in your configuration.
-      # Basically how a bank website works. If you aren't active over a certain period of time your session becomes stale and requires you to log back in.
-      def stale?
-        @stale == true || (logout_on_timeout? && record && record.logged_out?)
-      end
-    
-      private
-        def reset_stale_state
-          @stale = nil
+      
+      # Instance methods for the timeout feature.
+      module InstanceMethods
+        # Tells you if the record is stale or not. Meaning the record has timed out. This will only return true if you set logout_on_timeout to true in your configuration.
+        # Basically how a bank website works. If you aren't active over a certain period of time your session becomes stale and requires you to log back in.
+        def stale?
+          !stale_record.nil? || (logout_on_timeout? && record && record.logged_out?)
         end
-
-        def set_last_request_at
-          if record && record.class.column_names.include?("last_request_at") && (record.last_request_at.blank? || last_request_at_threshold.to_i.seconds.ago >= record.last_request_at)
-            record.last_request_at = klass.default_timezone == :utc ? Time.now.utc : Time.now
+    
+        private
+          def reset_stale_state
+            self.stale_record = nil
           end
-        end
+          
+          def enforce_timeout
+            if stale?
+              self.stale_record = record
+              self.record = nil
+            end
+          end
+          
+          def logout_on_timeout?
+            self.class.logout_on_timeout == true
+          end
+      end
     end
   end
 end