class Clearance::SignInGuard

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:

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.

Attributes

session[R]
stack[R]

Public Class Methods

new(session, stack = []) click to toggle source

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
# File lib/clearance/sign_in_guard.rb, line 51
def initialize(session, stack = [])
  @session = session
  @stack = stack
end

Public Instance Methods

failure(message) click to toggle source

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]

# File lib/clearance/sign_in_guard.rb, line 73
def failure(message)
  FailureStatus.new(message)
end
next_guard() click to toggle source

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

@return [SuccessStatus, FailureStatus]

# File lib/clearance/sign_in_guard.rb, line 81
def next_guard
  stack.call
end
success() click to toggle source

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]

# File lib/clearance/sign_in_guard.rb, line 64
def success
  SuccessStatus.new
end

Private Instance Methods

current_user() click to toggle source

The user currently stored in the clearance environment.

# File lib/clearance/sign_in_guard.rb, line 95
def current_user
  session.current_user
end
signed_in?() click to toggle source

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

# File lib/clearance/sign_in_guard.rb, line 90
def signed_in?
  session.signed_in?
end