clearance 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6a5021a3a8f7df39932a7292ca2fe1c4156208c3
-  data.tar.gz: 9b3370145ee988d6d3454caf60b40726b41aa891
+  metadata.gz: 4f19deed642e596906454bdc24af4a8a130f0da6
+  data.tar.gz: f0424abac9bb5dfd7a5fca4bca85896ab639931c
 SHA512:
-  metadata.gz: 652f59e34e1b09d920c078c61bf3ebdecf6bb7d076b76b2af8318feb5661696e820bb4b6cf0a79958b05ec13295ea935a417de4eddb8a9d3c2bbf624fd832df3
-  data.tar.gz: 07178616436a36b4572dc24501aba0b75361cf080847d5f2382459fa1bc5d917a14f003e53843febe6061f93f8f8d9dd9968249637c2f986ca5cd5bb3d176208
+  metadata.gz: 3fc54c3cc46fbecb48a627487c34047c3212e85f3831f4db9589c5d1c6da793d217b9cbda2f4fae71a0db37baf3bc5cd7203b11b7b34c9d69cfb1eb4fbac6bda
+  data.tar.gz: 887f7bf44074ef55c242c90c537c0855e5ef5790c88fece43c2067cd89007f76ab3dbf1c56b108961086605823b0c2345079158f131f66027f144cbee614ca47

data/.travis.yml

@@ -6,8 +6,8 @@ language:
 rvm:
   - 1.9.3
   - 2.0.0
-  - 2.1.6
-  - 2.2.2
+  - 2.1.7
+  - 2.2.3
 
 install:
   - "travis_retry bin/setup"

data/.yardopts

@@ -1,3 +1,6 @@
+--protected
+--private
+--hide-api private
 --exclude templates
 --markup markdown
 --markup-provider redcarpet

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    clearance (1.11.0)
+    clearance (1.12.0)
       bcrypt
       email_validator (~> 1.4)
       rails (>= 3.1)
@@ -9,42 +9,42 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    actionmailer (4.2.1)
-      actionpack (= 4.2.1)
-      actionview (= 4.2.1)
-      activejob (= 4.2.1)
+    actionmailer (4.2.5)
+      actionpack (= 4.2.5)
+      actionview (= 4.2.5)
+      activejob (= 4.2.5)
       mail (~> 2.5, >= 2.5.4)
       rails-dom-testing (~> 1.0, >= 1.0.5)
-    actionpack (4.2.1)
-      actionview (= 4.2.1)
-      activesupport (= 4.2.1)
+    actionpack (4.2.5)
+      actionview (= 4.2.5)
+      activesupport (= 4.2.5)
       rack (~> 1.6)
       rack-test (~> 0.6.2)
       rails-dom-testing (~> 1.0, >= 1.0.5)
-      rails-html-sanitizer (~> 1.0, >= 1.0.1)
-    actionview (4.2.1)
-      activesupport (= 4.2.1)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (4.2.5)
+      activesupport (= 4.2.5)
       builder (~> 3.1)
       erubis (~> 2.7.0)
       rails-dom-testing (~> 1.0, >= 1.0.5)
-      rails-html-sanitizer (~> 1.0, >= 1.0.1)
-    activejob (4.2.1)
-      activesupport (= 4.2.1)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    activejob (4.2.5)
+      activesupport (= 4.2.5)
       globalid (>= 0.3.0)
-    activemodel (4.2.1)
-      activesupport (= 4.2.1)
+    activemodel (4.2.5)
+      activesupport (= 4.2.5)
       builder (~> 3.1)
-    activerecord (4.2.1)
-      activemodel (= 4.2.1)
-      activesupport (= 4.2.1)
+    activerecord (4.2.5)
+      activemodel (= 4.2.5)
+      activesupport (= 4.2.5)
       arel (~> 6.0)
-    activesupport (4.2.1)
+    activesupport (4.2.5)
       i18n (~> 0.7)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
       thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
-    ammeter (1.1.2)
+    ammeter (1.1.3)
       activesupport (>= 3.0)
       railties (>= 3.0)
       rspec-rails (>= 2.2)
@@ -55,14 +55,14 @@ GEM
     arel (6.0.3)
     bcrypt (3.1.10)
     builder (3.2.2)
-    capybara (2.4.4)
+    capybara (2.5.0)
       mime-types (>= 1.16)
       nokogiri (>= 1.3.3)
       rack (>= 1.0.0)
       rack-test (>= 0.5.4)
       xpath (~> 2.0)
     coderay (1.1.0)
-    database_cleaner (1.4.1)
+    database_cleaner (1.5.1)
     diff-lcs (1.2.5)
     email_validator (1.6.0)
       activemodel
@@ -76,78 +76,78 @@ GEM
       activesupport (>= 4.1.0)
     i18n (0.7.0)
     json (1.8.3)
-    loofah (2.0.2)
+    loofah (2.0.3)
       nokogiri (>= 1.5.9)
     mail (2.6.3)
       mime-types (>= 1.16, < 3)
     method_source (0.8.2)
-    mime-types (2.6.1)
+    mime-types (2.6.2)
     mini_portile (0.6.2)
-    minitest (5.7.0)
-    nokogiri (1.6.6.2)
+    minitest (5.8.3)
+    nokogiri (1.6.6.3)
       mini_portile (~> 0.6.0)
-    pry (0.10.1)
+    pry (0.10.3)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
       slop (~> 3.4)
-    rack (1.6.1)
+    rack (1.6.4)
     rack-test (0.6.3)
       rack (>= 1.0)
-    rails (4.2.1)
-      actionmailer (= 4.2.1)
-      actionpack (= 4.2.1)
-      actionview (= 4.2.1)
-      activejob (= 4.2.1)
-      activemodel (= 4.2.1)
-      activerecord (= 4.2.1)
-      activesupport (= 4.2.1)
+    rails (4.2.5)
+      actionmailer (= 4.2.5)
+      actionpack (= 4.2.5)
+      actionview (= 4.2.5)
+      activejob (= 4.2.5)
+      activemodel (= 4.2.5)
+      activerecord (= 4.2.5)
+      activesupport (= 4.2.5)
       bundler (>= 1.3.0, < 2.0)
-      railties (= 4.2.1)
+      railties (= 4.2.5)
       sprockets-rails
     rails-deprecated_sanitizer (1.0.3)
       activesupport (>= 4.2.0.alpha)
-    rails-dom-testing (1.0.6)
+    rails-dom-testing (1.0.7)
       activesupport (>= 4.2.0.beta, < 5.0)
       nokogiri (~> 1.6.0)
       rails-deprecated_sanitizer (>= 1.0.1)
     rails-html-sanitizer (1.0.2)
       loofah (~> 2.0)
-    railties (4.2.1)
-      actionpack (= 4.2.1)
-      activesupport (= 4.2.1)
+    railties (4.2.5)
+      actionpack (= 4.2.5)
+      activesupport (= 4.2.5)
       rake (>= 0.8.7)
       thor (>= 0.18.1, < 2.0)
     rake (10.4.2)
-    rspec-core (3.3.0)
-      rspec-support (~> 3.3.0)
-    rspec-expectations (3.3.0)
+    rspec-core (3.4.0)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.3.0)
-    rspec-mocks (3.3.0)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.3.0)
-    rspec-rails (3.3.0)
+      rspec-support (~> 3.4.0)
+    rspec-rails (3.4.0)
       actionpack (>= 3.0, < 4.3)
       activesupport (>= 3.0, < 4.3)
       railties (>= 3.0, < 4.3)
-      rspec-core (~> 3.3.0)
-      rspec-expectations (~> 3.3.0)
-      rspec-mocks (~> 3.3.0)
-      rspec-support (~> 3.3.0)
-    rspec-support (3.3.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.0)
     shoulda-matchers (2.8.0)
       activesupport (>= 3.0.0)
     slop (3.6.0)
-    sprockets (3.2.0)
-      rack (~> 1.0)
-    sprockets-rails (2.3.2)
+    sprockets (3.4.0)
+      rack (> 1, < 3)
+    sprockets-rails (2.3.3)
       actionpack (>= 3.0)
       activesupport (>= 3.0)
       sprockets (>= 2.8, < 4.0)
-    sqlite3 (1.3.10)
+    sqlite3 (1.3.11)
     thor (0.19.1)
     thread_safe (0.3.5)
-    timecop (0.7.4)
+    timecop (0.8.0)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
     xpath (2.0.0)
@@ -171,4 +171,4 @@ DEPENDENCIES
   timecop (~> 0.6)
 
 BUNDLED WITH
-   1.10.5
+   1.10.6

data/NEWS.md

@@ -3,6 +3,23 @@
 The noteworthy changes for each Clearance version are included here. For a
 complete changelog, see the git history for each version via the version links.
 
+## [1.12.0] - November 17, 2015
+
+### Added
+- Users will now see a flash message when redirected to sign in by
+  `require_login`. This I18n key for this message is
+  `flashes.failure_when_not_signed_in` and defaults to "Please sign in to
+  continue".
+- Added significant API documentation. API documentation effort is ongoing.
+
+### Fixed
+- Fixed expectation in the generated `visitor_resets_password_spec.rb` file.
+- Corrected indentation of routes inserted by the routes generator.
+- Corrected indentation of `include Clearance::User` when the install generator
+  adds it to an existing user class.
+
+[1.12.0]: https://github.com/thoughtbot/clearance/compare/v1.11.0...v1.12.0
+
 ## [1.11.0] - August 21, 2015
 
 ### Added

data/config/locales/clearance.en.yml

@@ -12,6 +12,7 @@ en:
     failure_after_update: Password can't be blank.
     failure_when_forbidden: Please double check the URL or try submitting
       the form again.
+    failure_when_not_signed_in: Please sign in to continue.
   helpers:
     label:
       password:

data/lib/clearance/authentication.rb

@@ -16,40 +16,88 @@ module Clearance
       )
     end
 
+    # Authenticate a user with a provided email and password
+    # @param [ActionController::Parameters] params The parameters from the
+    #   sign in form. `params[:session][:email]` and
+    #   `params[:session][:password]` are required.
+    # @return [User, nil] The user or nil if authentication fails.
     def authenticate(params)
       Clearance.configuration.user_model.authenticate(
         params[:session][:email], params[:session][:password]
       )
     end
 
+    # Get the user from the current clearance session. Exposed as a
+    # `helper_method`, making it visible to views. Prefer {#signed_in?} or
+    # {#signed_out?} if you only want to check for the presence of a current
+    # user rather than access the actual user.
+    #
+    # @return [User, nil] The user if one is signed in or nil otherwise.
     def current_user
       clearance_session.current_user
     end
 
+    # @deprecated Use the {#sign_in} method instead.
     def current_user=(user)
       warn "#{Kernel.caller.first}: [DEPRECATION] " +
         'Assigning the current_user has been deprecated. Use the sign_in method instead.'
       clearance_session.sign_in user
     end
 
+    # Sign in the provided user.
+    # @param [User] user
+    #
+    # Signing in will run the stack of {Configuration#sign_in_guards}.
+    #
+    # You can provide a block to this method to handle the result of that stack.
+    # Your block will receive either a {SuccessStatus} or {FailureStatus}
+    #
+    #     sign_in(user) do |status|
+    #       if status.success?
+    #         # ...
+    #       else
+    #         # ...
+    #       end
+    #     end
+    #
+    # For an example of how clearance uses this internally, see
+    # {SessionsController#create}.
     def sign_in(user, &block)
       clearance_session.sign_in user, &block
     end
 
+    # Destroy the current user's Clearance session.
+    # See {Session#sign_out} for specifics.
     def sign_out
       clearance_session.sign_out
     end
 
+    # True if there is a currently-signed-in user. Exposed as a `helper_method`,
+    # making it available to views.
+    #
+    # Using `signed_in?` is preferable to checking {#current_user} against nil
+    # as it will allow you to introduce a null user object more simply at a
+    # later date.
+    #
+    # @return [Boolean]
     def signed_in?
       clearance_session.signed_in?
     end
 
+    # True if there is no currently-signed-in user. Exposed as a
+    # `helper_method`, making it available to views.
+    #
+    # Usings `signed_out?` is preferable to checking for presence of
+    # {#current_user} as it will allow you to introduce a null user object more
+    # simply at a later date.
     def signed_out?
       !signed_in?
     end
 
     # CSRF protection in Rails >= 3.0.4
+    #
     # http://weblog.rubyonrails.org/2011/2/8/csrf-protection-bypass-in-ruby-on-rails
+    # @private
     def handle_unverified_request
       super
       sign_out
@@ -57,6 +105,7 @@ module Clearance
 
     protected
 
+    # @api private
     def clearance_session
       request.env[:clearance]
     end

data/lib/clearance/authorization.rb

@@ -6,12 +6,24 @@ module Clearance
       hide_action :authorize, :deny_access, :require_login
     end
 
+    # Use as a `before_action` to require a user be signed in to proceed.
+    # {Authentication#signed_in?} is used to determine if there is a signed in
+    # user or not.
+    #
+    #     class PostsController < ApplicationController
+    #       before_action :require_login
+    #
+    #       def index
+    #         # ...
+    #       end
+    #     end
     def require_login
       unless signed_in?
-        deny_access
+        deny_access(I18n.t("flashes.failure_when_not_signed_in"))
       end
     end
 
+    # @deprecated use {#require_login}
     def authorize
       warn "[DEPRECATION] Clearance's `authorize` before_filter is " +
         "deprecated. Use `require_login` instead. Be sure to update any " +
@@ -20,6 +32,23 @@ module Clearance
       require_login
     end
 
+    # Responds to unauthorized requests in a manner fitting the request format.
+    # `js`, `json`, and `xml` requests will receive a 401 with no body. All
+    # other formats will be redirected appropriately and can optionally have the
+    # flash message set.
+    #
+    # When redirecting, the originally requested url will be stored in the
+    # session (`session[:return_to]`), allowing it to be used as a redirect url
+    # once the user has successfully signed in.
+    #
+    # If there is a signed in user, the request will be redirected according to
+    # the value returned from {#url_after_denied_access_when_signed_in}.
+    #
+    # If there is no signed in user, the request will be redirected according to
+    # the value returned from {#url_after_denied_access_when_signed_out}.
+    # For the exact redirect behavior, see {#redirect_request}.
+    #
+    # @param [String] flash_message
     def deny_access(flash_message = nil)
       respond_to do |format|
         format.any(:js, :json, :xml) { head :unauthorized }
@@ -29,6 +58,7 @@ module Clearance
 
     protected
 
+    # @api private
     def redirect_request(flash_message)
       store_location
 
@@ -43,21 +73,25 @@ module Clearance
       end
     end
 
+    # @api private
     def clear_return_to
       session[:return_to] = nil
     end
 
+    # @api private
     def store_location
       if request.get?
         session[:return_to] = request.original_fullpath
       end
     end
 
+    # @api private
     def redirect_back_or(default)
       redirect_to(return_to || default)
       clear_return_to
     end
 
+    # @api private
     def return_to
       if return_to_url
         uri = URI.parse(return_to_url)
@@ -65,14 +99,23 @@ module Clearance
       end
     end
 
+    # @api private
     def return_to_url
       session[:return_to]
     end
 
+    # Used as the redirect location when {#deny_access} is called and there is a
+    # currently signed in user.
+    #
+    # @return [String]
     def url_after_denied_access_when_signed_in
       Clearance.configuration.redirect_url
     end
 
+    # Used as the redirect location when {#deny_access} is called and there is
+    # no currently signed in user.
+    #
+    # @return [String]
     def url_after_denied_access_when_signed_out
       sign_in_url
     end