clearance 1.11.0 → 1.12.0

data/lib/clearance/session_status.rb

@@ -1,17 +1,24 @@
 module Clearance
+  # Indicates a user was successfully signed in, passing all {SignInGuard}s.
   class SuccessStatus
+    # Is true, indicating that the sign in was successful.
     def success?
       true
     end
   end
 
+  # Indicates a failure in the {SignInGuard} stack which prevented successful
+  # sign in.
   class FailureStatus
+    # The reason the sign in failed.
     attr_reader :failure_message
 
+    # @param [String] failure_message The reason the sign in failed.
     def initialize(failure_message)
       @failure_message = failure_message
     end
 
+    # Is false, indicating that the sign in was unsuccessful.
     def success?
       false
     end

data/lib/clearance/sign_in_guard.rb

@@ -1,20 +1,83 @@
 require 'clearance/session_status'
 
 module Clearance
+  # The base class for {DefaultSignInGuard} and all custom sign in guards.
+  #
+  # Sign in guards provide you with fine-grained control over the process of
+  # signing in a user. Each guard is run in order and can do one of the
+  # following:
+  #
+  # * Fail the sign in process
+  # * Call the next guard in the stack
+  # * Short circuit all remaining guards, declaring sign in successfull.
+  #
+  # Sign In Guards could be used, for instance, to require that a user confirm
+  # their email address before being allowed to sign in.
+  #
+  #     # in config/initializers/clearance.rb
+  #     Clearance.configure do |config|
+  #       config.sign_in_guards = [ConfirmationGuard]
+  #     end
+  #
+  #     # in lib/guards/confirmation_guard.rb
+  #     class ConfirmationGuard < Clearance::SignInGuard
+  #       def call
+  #         if signed_in? && current_user.email_confirmed?
+  #           next_guard
+  #         else
+  #           failure("You must confirm your email address.")
+  #         end
+  #       end
+  #     end
+  #
+  # Calling `success` or `failure` in any guard short circuits all of the
+  # remaining guards in the stack. In most cases, you will want to either call
+  # `failure` or `next_guard`. The {DefaultSignInGuard} will always be the final
+  # guard called and will handle calling `success` if appropriate.
+  #
+  # The stack is designed such that calling `call` will eventually return
+  # {SuccessStatus} or {FailureStatus}, thus halting the chain.
   class SignInGuard
+    # Creates an instance of a sign in guard.
+    #
+    # This is called by {Session} automatically using the array of guards
+    # configured in {Configuration#sign_in_guards} and the {DefaultSignInGuard}.
+    # There is no reason for users of Clearance to concern themselves with the
+    # initialization of each guard or the stack as a whole.
+    #
+    # @param [Session] session The current clearance session
+    # @param [[SignInGuard]] stack The sign in guards that come after this
+    #   guard in the stack
     def initialize(session, stack = [])
       @session = session
       @stack = stack
     end
 
+    # Indicates the entire sign in operation is successful and that no further
+    # guards should be run.
+    #
+    # In most cases your guards will want to delegate this responsibility to the
+    # {DefaultSignInGuard}, allowing the entire stack to execute. In that case,
+    # your custom guard would likely want to call `next_guard` instead.
+    #
+    # @return [SuccessStatus]
     def success
       SuccessStatus.new
     end
 
+    # Indicates this guard failed, and the entire sign in process should fail as
+    # a result.
+    #
+    # @param [String] message The reason the guard failed.
+    # @return [FailureStatus]
     def failure(message)
       FailureStatus.new(message)
     end
 
+    # Passes off responsibility for determining success or failure to the next
+    # guard in the stack.
+    #
+    # @return [SuccessStatus, FailureStatus]
     def next_guard
       stack.call
     end
@@ -23,10 +86,12 @@ module Clearance
 
     attr_reader :stack, :session
 
+    # True if there is a currently a user stored in the clearance environment.
     def signed_in?
       session.signed_in?
     end
 
+    # The user currently stored in the clearance environment.
     def current_user
       session.current_user
     end

data/lib/clearance/testing/controller_helpers.rb

@@ -1,7 +1,11 @@
 module Clearance
   module Testing
+    # Provides helpers to your controller specs.
+    # These are typically used in tests by requiring `clearance/rspec` or
+    # `clearance/test_unit` as appropriate in your `rails_helper.rb` or
+    # `test_helper.rb` files.
     module ControllerHelpers
-      # @private
+      # @api private
       def setup_controller_request_and_response
         super
         @request.env[:clearance] = Clearance::Session.new(@request.env)
@@ -10,6 +14,7 @@ module Clearance
       # Signs in a user that is created using FactoryGirl.
       # The factory name is derrived from your `user_class` Clearance
       # configuration.
+      #
       # @raise [RuntimeError] if FactoryGirl is not defined.
       def sign_in
         unless defined?(FactoryGirl)
@@ -21,12 +26,16 @@ module Clearance
       end
 
       # Signs in the provided user.
+      #
+      # @return user
       def sign_in_as(user)
         @controller.sign_in user
         user
       end
 
       # Signs out a user that may be signed in.
+      #
+      # @return [void]
       def sign_out
         @controller.sign_out
       end

data/lib/clearance/testing/deny_access_matcher.rb

@@ -1,10 +1,40 @@
 module Clearance
   module Testing
+    # Provides matchers to be used in your controller specs.
+    # These are typically exposed to your controller specs by
+    # requiring `clearance/rspec` or `clearance/test_unit` as
+    # appropriate in your `rails_helper.rb` or `test_helper.rb`
+    # files.
     module Matchers
+      # The `deny_access` matcher is used to assert that a
+      #   request is denied access by clearance.
+      # @option opts [String] :flash The expected flash notice message. Defaults
+      #   to nil, which means the flash will not be checked.
+      # @option opts [String] :redirect The expected redirect url. Defaults to
+      #   `'/'` if signed in or the `sign_in_url` if signed out.
+      #
+      #       class PostsController < ActionController::Base
+      #         before_action :require_login
+      #
+      #         def index
+      #           @posts = Post.all
+      #         end
+      #       end
+      #
+      #       describe PostsController do
+      #         describe "#index" do
+      #           it "denies access to users not signed in" do
+      #             get :index
+      #
+      #             expect(controller).to deny_access
+      #           end
+      #         end
+      #       end
       def deny_access(opts = {})
         DenyAccessMatcher.new(self, opts)
       end
 
+      # @api private
       class DenyAccessMatcher
         attr_reader :failure_message, :failure_message_when_negated
 

data/lib/clearance/testing/view_helpers.rb

@@ -15,7 +15,7 @@ module Clearance
         view.current_user = user
       end
 
-      # @private
+      # @api private
       module CurrentUser
         attr_accessor :current_user
 

data/lib/clearance/token.rb

@@ -1,5 +1,12 @@
 module Clearance
+  # Random token used for password reset tokens and password reset tokens.
+  # Clearance tokens are also public API and are inteded to be used anywhere you
+  # need a random token to correspond to a given user (e.g. you added an email
+  # confirmation token).
   class Token
+    # Generate a new random, 20 byte hex token.
+    #
+    # @return [String]
     def self.new
       SecureRandom.hex(20).encode('UTF-8')
     end

data/lib/clearance/user.rb

@@ -3,6 +3,102 @@ require 'email_validator'
 require 'clearance/token'
 
 module Clearance
+  # Required to be included in your configued user class, which is `User` by
+  # default, but can be changed with {Configuration#user_model=}.
+  #
+  #     class User
+  #       include Clearance::User
+  #
+  #       # ...
+  #     end
+  #
+  # This will also include methods exposed by your password strategy, which can
+  # be configured with {Configuration#password_strategy=}. By default, this is
+  # {PasswordStrategies::BCrypt}.
+  #
+  # ## Validations
+  #
+  # These validations are added to the class that the {User} module is mixed
+  # into.
+  #
+  # * If {#email_optional?} is false, {#email} is validated for presence,
+  #   uniqueness and email format (using the `email_validator` gem in strict
+  #   mode).
+  # * If {#skip_password_validation?} is false, {#password} is validated
+  #   for presence.
+  #
+  # ## Callbacks
+  #
+  # * {#normalize_email} will be called on `before_validation`
+  # * {#generate_remember_token} will be called on `before_create`
+  #
+  # @!attribute email
+  #   @return [String] The user's email.
+  #
+  # @!attribute encrypted_password
+  #   @return [String] The user's encrypted password.
+  #
+  # @!attribute remember_token
+  #   @return [String] The value used to identify this user in their {Session}
+  #     cookie.
+  #
+  # @!attribute confirmation_token
+  #   @return [String] The value used to identify this user in the password
+  #     reset link.
+  #
+  # @!attribute password_changing
+  #   @return [String] Transient (non-persisted) attribute that is set to
+  #     `true` when {#update_password} is called. This value is read by
+  #     {#skip_password_validation?} to determine if password validations need
+  #     to be run.
+  #
+  # @!attribute [r] password
+  #   @return [String] Transient (non-persisted) attribute that is set when
+  #     updating a user's password. Only the {#encrypted_password} is persisted.
+  #
+  # @!method password=
+  #   Sets the user's encrypted_password by using the configured Password
+  #   Strategy's `password=` method. By default, this will be
+  #   {PasswordStrategies::BCrypt#password=}, but can be changed with
+  #   {Configuration#password_strategy}.
+  #
+  #   @see PasswordStrategies
+  #   @return [void]
+  #
+  # @!method authenticated?
+  #   Check's the provided password against the user's encrypted password using
+  #   the configured password strategy. By default, this will be
+  #   {PasswordStrategies::BCrypt#authenticated?}, but can be changed with
+  #   {Configuration#password_strategy}.
+  #
+  #   @see PasswordStrategies
+  #   @param [String] password
+  #     The password to check.
+  #   @return [Boolean]
+  #     True if the password provided is correct for the user.
+  #
+  # @!method self.authenticate
+  #   Finds the user with the given email and authenticates them with the
+  #   provided password. If the email corresponds to a user and the provided
+  #   password is correct for that user, this method will return that user.
+  #   Otherwise it will return nil.
+  #
+  #   @return [User, nil]
+  #
+  # @!method self.find_by_normalized_email
+  #   Finds the user with the given email. The email with be normalized via
+  #   {#normalize_email}.
+  #
+  #   @return [User, nil]
+  #
+  # @!method self.normalize_email
+  #   Normalizes the provided email by downcasing and removing all spaces.
+  #   This is used by {find_by_normalized_email} and is also called when
+  #   validating a user to ensure only normalized emails are stored in the
+  #   database.
+  #
+  #   @return [String]
+  #
   module User
     extend ActiveSupport::Concern
 
@@ -15,6 +111,7 @@ module Clearance
       include password_strategy
     end
 
+    # @api private
     module ClassMethods
       def authenticate(email, password)
         if user = find_by_normalized_email(email)
@@ -39,6 +136,7 @@ module Clearance
       end
     end
 
+    # @api private
     module Validations
       extend ActiveSupport::Concern
 
@@ -53,6 +151,7 @@ module Clearance
       end
     end
 
+    # @api private
     module Callbacks
       extend ActiveSupport::Concern
 
@@ -62,16 +161,47 @@ module Clearance
       end
     end
 
+    # Generates a {#confirmation_token} for the user, which allows them to reset
+    # their password via an email link.
+    #
+    # Calling `forgot_password!` will cause the user model to be saved without
+    # validations. Any other changes you made to this user instance will also
+    # be persisted, without validation. It is inteded to be called on an
+    # instance with no changes (`dirty? == false`).
+    #
+    # @return [Boolean] Was the save successful?
     def forgot_password!
       generate_confirmation_token
       save validate: false
     end
 
+    # Generates a new {#remember_token} for the user, which will have the effect
+    # of signing all of the user's current sessions out. This is called
+    # internally by {Session#sign_out}.
+    #
+    # Calling `reset_remember_token!` will cause the user model to be saved
+    # without validations. Any other changes you made to this user instance will
+    # also be persisted, without validation. It is inteded to be called on an
+    # instance with no changes (`dirty? == false`).
+    #
+    # @return [Boolean] Was the save successful?
     def reset_remember_token!
       generate_remember_token
       save validate: false
     end
 
+    # Sets the user's password to the new value, using the `password=` method on
+    # the configured password strategy. By default, this is
+    # {PasswordStrategies::BCrypt#password=}.
+    #
+    # This also has the side-effect of blanking the {#confirmation_token} and
+    # rotating the `#remember_token`.
+    #
+    # Validations will be run as part of this update. If the user instance is
+    # not valid, the password change will not be persisted, and this method will
+    # return `false`.
+    #
+    # @return [Boolean] Was the save successful?
     def update_password(new_password)
       self.password_changing = true
       self.password = new_password
@@ -86,28 +216,57 @@ module Clearance
 
     private
 
+    # Sets the email on this instance to the value returned by
+    # {.normalize_email}
+    #
+    # @return [String]
     def normalize_email
       self.email = self.class.normalize_email(email)
     end
 
+    # Always false. Override this method in your user model to allow for other
+    # forms of user authentication (username, Facebook, etc).
+    #
+    # @return [false]
     def email_optional?
       false
     end
 
+    # Always false. Override this method in your user model to allow for other
+    # forms of user authentication (username, Facebook, etc).
+    #
+    # @return [false]
     def password_optional?
       false
     end
 
+    # True if {#password_optional?} is true or if the user already has an
+    # {#encrypted_password} that is not changing.
+    #
+    # @return [Boolean]
     def skip_password_validation?
       password_optional? || (encrypted_password.present? && !password_changing)
     end
 
+    # Sets the {#confirmation_token} on the instance to a new value generated by
+    # {Token.new}. The change is not automatically persisted. If you would like
+    # to generate and save in a single method call, use {#forgot_password!}.
+    #
+    # @return [String] The new confirmation token
     def generate_confirmation_token
       self.confirmation_token = Clearance::Token.new
     end
 
+    # Sets the {#remember_token} on the instance to a new value generated by
+    # {Token.new}. The change is not automatically persisted. If you would like
+    # to generate and sace in a single method call, use
+    # {#reset_remember_token!}.
+    #
+    # @return [String] The new remember token
     def generate_remember_token
       self.remember_token = Clearance::Token.new
     end
+
+    private_constant :Callbacks, :ClassMethods, :Validations
   end
 end