warden 0.5.3 → 0.6.0

data/History.rdoc

@@ -1,8 +1,11 @@
-=== Version 0.5.3
-* bug fixes
-  * authenticated? and unauthenticated? should return true or false, not the user or false.
+* enhancements
+  * added serializers, including session serializer (set by default) and a cookie serializer (josevalim)
+
+* deprecation
+  * serializer_into_session and serializer_from_session are deprecated, overwrite serialize and deserializer in Warden::Serializers::Session instead (josevalim)
+
+== Version 0.5.2 / 2009-11-09
 
-=== Version 0.5.2
 * enhancements
   * authenticated? always try to serialize the user from session (josevalim)
   * stored_in_session? checks if user information is stored in session, without serializing (josevalim)
@@ -22,7 +25,7 @@
   * Make scope available to strategies (josevalim)
 
 * bug fixes
-  * Do not consume opts twice, otherwise just the first will parse the scope. (josevalim)
+  * Do not consume opts twice, otherwise just the first will parse the scope (josevalim)
 
 === Version 0.3.2 / 2009-09-15
 

data/README.textile

@@ -7,5 +7,5 @@ I'm going to try and keep a list of all the contributors to this project.  If I'
 * Daniel Neighman (hassox)
 * Mick Staugaard (staugaard)
 * José Valim (josevalim)
-* Carlo Santoniodasilva (carlosantoniodasilva)
+* Carlos Antonio da Silva (carlosantoniodasilva)
 * Justin Smestad (jsmestad)

data/lib/warden.rb

@@ -1,14 +1,17 @@
 # encoding: utf-8
 require 'forwardable'
 $:.unshift File.join(File.dirname(__FILE__))
+
 require 'warden/mixins/common'
 require 'warden/proxy'
 require 'warden/manager'
 require 'warden/errors'
-require 'warden/authentication/hooks'
-require 'warden/authentication/strategy_base'
-require 'warden/authentication/strategies'
-
+require 'warden/strategies'
+require 'warden/strategies/base'
+require 'warden/serializers'
+require 'warden/serializers/base'
+require 'warden/serializers/cookie'
+require 'warden/serializers/session'
 
 module Warden
   class NotAuthenticated < StandardError; end

data/lib/warden/declarable.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+module Warden
+  module Declarable
+    
+    # Add a declaration and store it in a hash.
+    def add(label, declaration = nil, &block)
+      base = self.const_get(:Base)
+
+      declaration ||= Class.new(base)
+      declaration.class_eval(&block) if block_given?
+
+      check_validity!(label, declaration)
+      raise "#{label.inspect} is not a #{base}" unless declaration.ancestors.include?(base)
+
+      _declarations[label] = declaration
+    end
+
+    # Update a previously given declaration.
+    def update(label, &block)
+      declaration = _declarations[label]
+      raise "Unknown declaration #{label.inspect}" unless declaration
+      add(label, declaration, &block)
+    end
+
+    # Provides access to declarations by label
+    # :api: public
+    def [](label)
+      _declarations[label]
+    end
+
+    # Clears all declared.
+    # :api: public
+    def clear!
+      _declarations.clear
+    end
+
+    # :api: private
+    def _declarations
+      @declarations ||= {}
+    end
+    
+  end # Declarable
+end # Warden

data/lib/warden/hooks.rb

@@ -0,0 +1,121 @@
+# encoding: utf-8
+module Warden
+  module Hooks
+
+    # A callback hook set to run every time after a user is set.
+    # This will happen the first time the user is either authenticated, accessed or manually set
+    # during a request.  You can supply as many hooks as you like, and they will be run in order of decleration
+    #
+    # Parameters:
+    # <block> A block where you can set arbitrary logic to run every time a user is set
+    #   Block Parameters: |user, auth, opts|
+    #     user - The user object that is being set
+    #     auth - The raw authentication proxy object.
+    #     opts - any options passed into the set_user call includeing :scope
+    #
+    # Example:
+    #   Warden::Manager.after_set_user do |user,auth,opts|
+    #     scope = opts[:scope]
+    #     if auth.session["#{scope}.last_access"].to_i > (Time.now - 5.minutes)
+    #       auth.logout(scope)
+    #       throw(:warden, :scope => scope, :reason => "Times Up")
+    #     end
+    #     auth.session["#{scope}.last_access"] = Time.now
+    #   end
+    #
+    # :api: public
+    def after_set_user(&block)
+      raise BlockNotGiven unless block_given?
+      _after_set_user << block
+    end
+
+    # Provides access to the array of after_set_user blocks to run
+    # :api: private
+    def _after_set_user # :nodoc:
+      @_after_set_user ||= []
+    end
+
+    # A callback hook set to run after the first authentiation of a session.
+    # This will only happenwhen the session is first authenticated
+    #
+    # Parameters:
+    # <block> A block to contain logic for the callback
+    #   Block Parameters: |user, auth, opts|
+    #     user - The user object that is being set
+    #     auth - The raw authentication proxy object.
+    #     opts - any options passed into the authenticate call includeing :scope
+    #
+    # Example:
+    #
+    #   Warden::Manager.after_authentication do |user, auth, opts|
+    #     throw(:warden, opts) unless user.active?
+    #   end
+    #
+    # :api: public
+    def after_authentication(&block)
+      raise BlockNotGiven unless block_given?
+      _after_authentication << block
+    end
+
+    # Provides access to the array of after_authentication blocks
+    # :api: private
+    def _after_authentication
+      @_after_authentication ||= []
+    end
+
+    # A callback that runs just prior to the failur application being called.
+    # This callback occurs after PATH_INFO has been modified for the failure (default /unauthenticated)
+    # In this callback you can mutate the environment as required by the failure application
+    # If a Rails controller were used for the failure_app for example, you would need to set request[:params][:action] = :unauthenticated
+    #
+    # Parameters:
+    # <block> A block to contain logic for the callback
+    #   Block Parameters: |user, auth, opts|
+    #     env - The rack env hash
+    #     opts - any options passed into the authenticate call includeing :scope
+    #
+    # Example:
+    #   Warden::Manager.before_failure do |env, opts|
+    #     params = Rack::Request.new(env).params
+    #     params[:action] = :unauthenticated
+    #     params[:warden_failure] = opts
+    #   end
+    #
+    # :api: public
+    def before_failure(&block)
+      _before_failure << block
+    end
+
+    # Provides access to the callback array for before_failure
+    # :api: private
+    def _before_failure
+      @_before_failure ||= []
+    end
+
+    # A callback that runs just prior to the logout of each scope.
+    #
+    # Parameters:
+    # <block> A block to contain logic for the callback
+    #   Block Parameters: |user, auth, scope|
+    #     user - The authenticated user for the current scope
+    #     auth - The warden proxy object
+    #     scope - current logout scope
+    #
+    # Example:
+    #   Warden::Manager.before_logout do |user, auth, scope|
+    #     user.forget_me!
+    #   end
+    #
+    # :api: public
+    def before_logout(&block)
+      _before_logout << block
+    end
+
+    # Provides access to the callback array for before_logout
+    # :api: private
+    def _before_logout
+      @_before_logout ||= []
+    end
+
+  end # Hooks
+end # Warden

data/lib/warden/manager.rb

@@ -1,10 +1,14 @@
 # encoding: utf-8
+require 'warden/hooks'
+
 module Warden
   # The middleware for Rack Authentication
   # The middlware requires that there is a session upstream
   # The middleware injects an authentication object into
   # the rack environment hash
   class Manager
+    extend Warden::Hooks
+
     attr_accessor :config, :failure_app
 
     # initialize the middleware.
@@ -19,6 +23,11 @@ module Warden
       # Should ensure there is a failure application defined.
       @failure_app = config[:failure_app] if config[:failure_app]
       raise "No Failure App provided" unless @failure_app
+
+      # Set default configuration values.
+      @config[:default_strategies]  ||= []
+      @config[:default_serializers] ||= [ :session ]
+
       self
     end
 
@@ -28,6 +37,12 @@ module Warden
       @config[:silence_missing_strategies] = true
     end
 
+    # Do not raise an error if a missing serializer is given by default.
+    # :api: plugin
+    def silence_missing_serializers!
+      @config[:silence_missing_serializers] = true
+    end
+
     # Set the default strategies to use.
     # :api: public
     def default_strategies(*strategies)
@@ -38,6 +53,16 @@ module Warden
       end
     end
 
+    # Set the default serializers to use. By default, only session is enabled.
+    # :api: public
+    def default_serializers(*serializers)
+      if serializers.empty?
+        @config[:default_serializers]
+      else
+        @config[:default_serializers] = serializers.flatten
+      end
+    end
+
     # :api: private
     def call(env) # :nodoc:
       # if this is downstream from another warden instance, don't do anything.
@@ -64,21 +89,6 @@ module Warden
 
     class << self
 
-      # Does the work of storing the user in the session
-      # :api: private
-      def _store_user(user, session, scope = :default) # :nodoc:
-        return nil unless user
-        session["warden.user.#{scope}.key"] = serialize_into_session.call(user)
-      end
-
-      # Does the work of fetching the user from the session
-      # :api: private
-      def _fetch_user(session, scope = :default) # :nodoc:
-        key = session["warden.user.#{scope}.key"]
-        return nil unless key
-        serialize_from_session.call(key)
-      end
-
       # Prepares the user to serialize into the session.
       # Any object that can be serialized into the session in some way can be used as a "user" object
       # Generally however complex object should not be stored in the session.
@@ -87,10 +97,21 @@ module Warden
       # Example:
       #   Warden::Manager.serialize_into_session{ |user| user.id }
       #
+      # Deprecation:
+      #   This method was deprecated in favor of serializer in Session. You can set it while setting the middleware:
+      #
+      #   use Warden::Manager do |manager|
+      #     manager.update(:session) do
+      #       def serialize(user)
+      #         user.id
+      #       end
+      #     end
+      #   end
+      #
       # :api: public
       def serialize_into_session(&block)
-        @serialize_into_session = block if block_given?
-        @serialize_into_session ||= lambda{|user| user}
+        warn "[DEPRECATION] serialize_into_session is deprecated. Please overwrite the serialize method in Warden::Serializers::Session."
+        Warden::Serializers::Session.send :define_method, :serialize, &block
       end
 
       # Reconstitues the user from the session.
@@ -99,10 +120,21 @@ module Warden
       # Example:
       #   Warden::Manager.serialize_from_session{ |id| User.get(id) }
       #
+      # Deprecation:
+      #   This method was deprecated in favor of serializer in Session. You can set it while setting the middleware:
+      #
+      #   use Warden::Manager do |manager|
+      #     manager.update(:session) do
+      #       def deserialize(user)
+      #         User.get(id)
+      #       end
+      #     end
+      #   end
+      #
       # :api: public
-      def serialize_from_session(&blk)
-        @serialize_from_session = blk if block_given?
-        @serialize_from_session ||= lambda{|key| key}
+      def serialize_from_session(&block)
+        warn "[DEPRECATION] serialize_from_session is deprecated. Please overwrite the deserialize method in Warden::Serializers::Session."
+        Warden::Serializers::Session.send :define_method, :deserialize, &block
       end
     end
 
@@ -135,7 +167,6 @@ module Warden
 
         # Call the before failure callbacks
         Warden::Manager._before_failure.each{|hook| hook.call(env,opts)}
-
         @failure_app.call(env).to_a
       end
     end # call_failure_app

data/lib/warden/mixins/common.rb

@@ -8,14 +8,23 @@ module Warden
       def session
         env['rack.session']
       end # session
-      alias_method :raw_session, :session
 
-      # Convenience method to access the rack request
+      # Alias :session to :raw_session since the former will be user API for storing scoped data.
+      alias :raw_session :session
+
+      # Convenience method to access the rack request.
       # :api: public
       def request
         @request ||= Rack::Request.new(@env)
       end # request
 
+      # Convenience method to access the rack response. This should be replaced by the
+      # actual response returned to the client.
+      # :api: public
+      def response
+        @response ||= Rack::Response.new(@env)
+      end # response
+
       # Convenience method to access the rack request params
       # :api: public
       def params

data/lib/warden/proxy.rb

@@ -3,6 +3,7 @@ module Warden
   class UserNotSet < RuntimeError; end
 
   class Proxy
+    # An accessor to the wining strategy
     # :api: private
     attr_accessor :winning_strategy
 
@@ -16,7 +17,7 @@ module Warden
     # :api: private
     def_delegators :winning_strategy, :headers, :_status, :custom_response
 
-    def initialize(env, config = {}) # :nodoc:
+    def initialize(env, config = {}) #:nodoc:
       @env = env
       @config = config
       @strategies = @config.fetch(:default_strategies, [])
@@ -34,14 +35,16 @@ module Warden
     #
     # Example:
     #   env['warden'].authenticated?(:admin)
+    #
     # :api: public
     def authenticated?(scope = :default)
-      result = !!user(scope)
+      result = user(scope) || false
       yield if block_given? && result
       result
     end
 
     # Same API as authenticated, but returns false when authenticated.
+    # :api: public
     def unauthenticated?(scope = :default)
       result = !authenticated?(scope)
       yield if block_given? && result
@@ -59,6 +62,7 @@ module Warden
     #
     # Example:
     #   env['auth'].authenticate(:password, :basic, :scope => :sudo)
+    #
     # :api: public
     def authenticate(*args)
       scope, opts = _perform_authentication(*args)
@@ -83,11 +87,18 @@ module Warden
     #
     # Example
     #   env['warden'].set_user(@user)
-    #   env['warden'].stored_in_session? #=> true
+    #   env['warden'].stored?                     #=> true
+    #   env['warden'].stored?(:default)           #=> true
+    #   env['warden'].stored?(:default, :session) #=> true
+    #   env['warden'].stored?(:default, :cookie)  #=> false
     # 
     # :api: public
-    def stored_in_session?(scope = :default)
-      !!raw_session["warden.user.#{scope}.key"]
+    def stored?(scope = :default, serializer = nil)
+      if serializer
+        find_serializer(serializer).stored?(scope)
+      else
+        serializers.any? { |s| s.stored?(scope) }
+      end
     end
 
     # Manually set the user into the session and auth proxy
@@ -95,15 +106,15 @@ module Warden
     # Parameters:
     #   user - An object that has been setup to serialize into and out of the session.
     #   opts - An options hash.  Use the :scope option to set the scope of the user, set the :store option to false to skip serializing into the session.
+    #
     # :api: public
     def set_user(user, opts = {})
       scope = (opts[:scope] ||= :default)
-      Warden::Manager._store_user(user, raw_session, scope) unless opts[:store] == false# Get the user into the session
+      _store_user(user, scope) unless opts[:store] == false
 
       # Run the after hooks for setting the user
-      Warden::Manager._after_set_user.each{|hook| hook.call(user, self, opts)}
-
-      @users[scope] = user # Store the user in the proxy user object
+      Warden::Manager._after_set_user.each{ |hook| hook.call(user, self, opts) }
+      @users[scope] = user
     end
 
     # Provides acccess to the user object in a given scope for a request.
@@ -118,7 +129,7 @@ module Warden
     #
     # :api: public
     def user(scope = :default)
-      @users[scope] ||= lookup_user_from_session(scope)
+      @users[scope] ||= set_user(_fetch_user(scope), :scope => scope)
     end
 
     # Provides a scoped session data for authenticated users.
@@ -155,22 +166,20 @@ module Warden
     #
     # :api: public
     def logout(*scopes)
-      # Run before_logout hooks for each scoped user
-      @users.each do |scope, user|
-        next unless scopes.empty? || scopes.include?(scope)
-        Warden::Manager._before_logout.each { |hook| hook.call(user, self, scope) }
+      if scopes.empty?
+        scopes = @users.keys
+        reset_session = true
       end
 
-      if scopes.empty?
-        reset_session!
-        @users.clear
-      else
-        scopes.each do |s|
-          raw_session["warden.user.#{s}.key"] = nil
-          raw_session["warden.user.#{s}.session"] = nil
-          @users.delete(s)
-        end
+      scopes.each do |scope|
+        user = @users.delete(scope)
+        Warden::Manager._before_logout.each { |hook| hook.call(user, self, scope) }
+
+        raw_session.delete("warden.user.#{scope}.session")
+        _delete_user(user, scope)
       end
+
+      reset_session! if reset_session
     end
 
     # proxy methods through to the winning strategy
@@ -198,7 +207,24 @@ module Warden
       !!@custom_failure
     end
 
+    # Retrieve and initializer serializers.
+    # :api: private
+    def serializers # :nodoc:
+      @serializers ||= begin
+        array = []
+        @config[:default_serializers].each do |s|
+          unless Warden::Serializers[s]
+            raise "Invalid serializer #{s}" unless silence_missing_serializers?
+            next
+          end
+          array << Warden::Serializers[s].new(@env)
+        end
+        array
+      end
+    end
+
     private
+
     # :api: private
     def _perform_authentication(*args)
       scope = scope_from_args(args)
@@ -213,11 +239,8 @@ module Warden
 
       strategies.each do |s|
         unless Warden::Strategies[s]
-          if args.empty? && @config[:silence_missing_strategies]
-            next
-          else
-            raise "Invalid strategy #{s}"
-          end
+          raise "Invalid strategy #{s}" unless args.empty? && silence_missing_strategies?
+          next
         end
 
         strategy = Warden::Strategies[s].new(@env, scope, @conf)
@@ -239,18 +262,51 @@ module Warden
     end
 
     # :api: private
-    def scope_from_args(args)
+    def scope_from_args(args) # :nodoc:
       Hash === args.last ? args.last.fetch(:scope, :default) : :default
     end
 
     # :api: private
-    def opts_from_args(args)
+    def opts_from_args(args) # :nodoc:
       Hash === args.last ? args.pop : {}
     end
 
     # :api: private
-    def lookup_user_from_session(scope)
-      set_user(Warden::Manager._fetch_user(raw_session, scope), :scope => scope)
+    def silence_missing_strategies? # :nodoc:
+      @config[:silence_missing_strategies]
+    end
+    
+    # :api: private
+    def silence_missing_serializers? # :nodoc:
+      @config[:silence_missing_serializers]
+    end
+
+    # Does the work of storing the user in stores.
+    # :api: private
+    def _store_user(user, scope = :default) # :nodoc:
+      return unless user
+      serializers.each { |s| s.store(user, scope) }
+    end
+
+    # Does the work of fetching the user from the first store.
+    # :api: private
+    def _fetch_user(scope = :default) # :nodoc:
+      serializers.each do |s|
+        user = s.fetch(scope)
+        return user if user
+      end
+      nil
+    end
+
+    # Does the work of deleteing the user in all stores.
+    # :api: private
+    def _delete_user(user, scope = :default) # :nodoc:
+      serializers.each { |s| s.delete(scope, user) }
+    end
+
+    # :api: private
+    def find_serializer(name) # :nodoc:
+      serializers.find { |s| s.class == ::Warden::Serializers[name] }
     end
   end # Proxy
 end # Warden