Class: Clearance::SignInGuard

Inherits:
Object
  • Object
show all
Defined in:
lib/clearance/sign_in_guard.rb

Overview

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. = ["ConfirmationGuard"]
end

# in app/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.

Direct Known Subclasses

DefaultSignInGuard

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(session, stack = []) ⇒ SignInGuard

Creates an instance of a sign in guard.

This is called by Clearance::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.

Parameters:

  • session (Session) —

    The current clearance session

  • stack ([SignInGuard]) (defaults to: []) —

    The sign in guards that come after this guard in the stack



51
52
53
54
 
# File 'lib/clearance/sign_in_guard.rb', line 51

def initialize(session, stack = [])
  @session = session
  @stack = stack
end

Instance Attribute Details

#session ⇒ Object (readonly, private)

Returns the value of attribute session.



87
88
89
 
# File 'lib/clearance/sign_in_guard.rb', line 87

def session
  @session
end

#stack ⇒ Object (readonly, private)

Returns the value of attribute stack.



87
88
89
 
# File 'lib/clearance/sign_in_guard.rb', line 87

def stack
  @stack
end

Instance Method Details

#current_user ⇒ Object (private)

The user currently stored in the clearance environment.



95
96
97
 
# File 'lib/clearance/sign_in_guard.rb', line 95

def current_user
  session.current_user
end

#failure(message) ⇒ FailureStatus

Indicates this guard failed, and the entire sign in process should fail as a result.

Parameters:

  • message (String) —

    The reason the guard failed.

Returns:



73
74
75
 
# File 'lib/clearance/sign_in_guard.rb', line 73

def failure(message)
  FailureStatus.new(message)
end

#next_guard ⇒ SuccessStatus, FailureStatus

Passes off responsibility for determining success or failure to the next guard in the stack.

Returns:



81
82
83
 
# File 'lib/clearance/sign_in_guard.rb', line 81

def next_guard
  stack.call
end

#signed_in? ⇒ Boolean (private)

True if there is a currently a user stored in the clearance environment.

Returns:

  • (Boolean) 


90
91
92
 
# File 'lib/clearance/sign_in_guard.rb', line 90

def signed_in?
  session.signed_in?
end

#success ⇒ SuccessStatus

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.

Returns:



64
65
66
 
# File 'lib/clearance/sign_in_guard.rb', line 64

def success
  SuccessStatus.new
end