clearance 1.10.1 → 1.17.0

data/lib/clearance/testing/helpers.rb

@@ -1,31 +1,15 @@
+require "clerance/testing/controller_helpers"
+
 module Clearance
   module Testing
+    # @deprecated Use Clearance::Testing::ControllerHelpers
     module Helpers
-      def setup_controller_request_and_response
-        super
-        @request.env[:clearance] = Clearance::Session.new(@request.env)
-      end
-
-      def sign_in
-        unless defined?(FactoryGirl)
-          raise(
-            RuntimeError,
-            "Clearance's `sign_in` helper requires factory_girl"
-          )
-        end
-
-        factory = Clearance.configuration.user_model.to_s.underscore.to_sym
-        sign_in_as FactoryGirl.create(factory)
-      end
-
-      def sign_in_as(user)
-        @controller.sign_in user
-        user
-      end
-
-      def sign_out
-        @controller.sign_out
-      end
+      warn(
+        "#{Kernel.caller.first} [DEPRECATION] Clearance::Testing::Helpers is "\
+        "deprecated and has been replaced with " \
+        "Clearance::Testing::ControllerHelpers. Require " \
+        "clearance/testing/controller_helpers instead."
+      )
     end
   end
 end

data/lib/clearance/testing/view_helpers.rb

@@ -0,0 +1,32 @@
+module Clearance
+  module Testing
+    # Provides helpers to your view and helper specs.
+    # Using these helpers makes `current_user`, `signed_in?` and `signed_out?`
+    # behave properly in view and helper specs.
+    module ViewHelpers
+      # Sets current_user on the view under test to a new instance of your user
+      # model.
+      def sign_in
+        view.current_user = Clearance.configuration.user_model.new
+      end
+
+      # Sets current_user on the view under test to the supplied user.
+      def sign_in_as(user)
+        view.current_user = user
+      end
+
+      # @api private
+      module CurrentUser
+        attr_accessor :current_user
+
+        def signed_in?
+          current_user.present?
+        end
+
+        def signed_out?
+          !signed_in?
+        end
+      end
+    end
+  end
+end

data/lib/clearance/token.rb

@@ -1,5 +1,12 @@
 module Clearance
+  # Random token used for password reset and remember 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

@@ -1,25 +1,142 @@
 require 'digest/sha1'
+require 'active_model'
 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
+  #   @deprecated Dirty tracking is now handled automatically.
+  #
+  # @!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
 
     included do
-      attr_accessor :password_changing
       attr_reader :password
 
       include Validations
       include Callbacks
       include password_strategy
+
+      def password=(value)
+        encrypted_password_will_change!
+        super
+      end
+
+      def password_changing
+        warn "#{Kernel.caller.first}: [DEPRECATION] " \
+          "The `password_changing` attribute is deprecated. Clearance uses " \
+          "the dirty state of the `encrypted_password` field to track this " \
+          "automatically."
+
+        @password_changing
+      end
+
+      def password_changing=(value)
+        warn "#{Kernel.caller.first}: [DEPRECATION] " \
+          "The `password_changing` attribute is deprecated. Clearance uses " \
+          "the dirty state of the `encrypted_password` field to track this " \
+          "automatically."
+
+        @password_changing = value
+      end
     end
 
+    # @api private
     module ClassMethods
       def authenticate(email, password)
         if user = find_by_normalized_email(email)
           if password.present? && user.authenticated?(password)
-            return user
+            user
           end
         end
       end
@@ -39,6 +156,7 @@ module Clearance
       end
     end
 
+    # @api private
     module Validations
       extend ActiveSupport::Concern
 
@@ -53,6 +171,7 @@ module Clearance
       end
     end
 
+    # @api private
     module Callbacks
       extend ActiveSupport::Concern
 
@@ -62,18 +181,48 @@ 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
 
       if valid?
@@ -86,28 +235,58 @@ 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)
+      password_optional? ||
+        (encrypted_password.present? && !encrypted_password_changed?)
     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 save 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

data/lib/clearance/version.rb

@@ -1,3 +1,3 @@
 module Clearance
-  VERSION = "1.10.1"
+  VERSION = "1.17.0".freeze
 end

data/lib/generators/clearance/install/install_generator.rb

@@ -23,11 +23,12 @@ module Clearance
         if File.exist? "app/models/user.rb"
           inject_into_file(
             "app/models/user.rb",
-            "include Clearance::User\n\n",
-            after: "class User < ActiveRecord::Base\n"
+            "  include Clearance::User\n\n",
+            after: "class User < #{models_inherit_from}\n",
           )
         else
-          copy_file 'user.rb', 'app/models/user.rb'
+          @inherit_from = models_inherit_from
+          template("user.rb.erb", "app/models/user.rb")
         end
       end
 
@@ -35,7 +36,7 @@ module Clearance
         if users_table_exists?
           create_add_columns_migration
         else
-          copy_migration 'create_users.rb'
+          copy_migration "create_users"
         end
       end
 
@@ -52,16 +53,16 @@ module Clearance
             new_indexes: new_indexes
           }
 
-          copy_migration('add_clearance_to_users.rb', config)
+          copy_migration("add_clearance_to_users", config)
         end
       end
 
       def copy_migration(migration_name, config = {})
         unless migration_exists?(migration_name)
           migration_template(
-            "db/migrate/#{migration_name}",
-            "db/migrate/#{migration_name}",
-            config
+            "db/migrate/#{migration_name}.rb.erb",
+            "db/migrate/#{migration_name}.rb",
+            config.merge(migration_version: migration_version),
           )
         end
       end
@@ -101,7 +102,11 @@ module Clearance
       end
 
       def users_table_exists?
-        ActiveRecord::Base.connection.table_exists?(:users)
+        if ActiveRecord::Base.connection.respond_to?(:data_source_exists?)
+          ActiveRecord::Base.connection.data_source_exists?(:users)
+        else
+          ActiveRecord::Base.connection.table_exists?(:users)
+        end
       end
 
       def existing_users_columns
@@ -116,6 +121,20 @@ module Clearance
       def self.next_migration_number(dir)
         ActiveRecord::Generators::Base.next_migration_number(dir)
       end
+
+      def migration_version
+        if Rails.version >= "5.0.0"
+          "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+        end
+      end
+
+      def models_inherit_from
+        if Rails.version >= "5.0.0"
+          "ApplicationRecord"
+        else
+          "ActiveRecord::Base"
+        end
+      end
     end
   end
 end

data/lib/generators/clearance/install/templates/README

@@ -27,6 +27,6 @@ Next steps:
 
 3. Migrate:
 
-    rake db:migrate
+    rails db:migrate
 
 *******************************************************************************

data/lib/generators/clearance/install/templates/clearance.rb

@@ -1,3 +1,4 @@
 Clearance.configure do |config|
   config.mailer_sender = "reply@example.com"
+  config.rotate_csrf_on_sign_in = true
 end

data/lib/generators/clearance/install/templates/db/migrate/{add_clearance_to_users.rb → add_clearance_to_users.rb.erb}

@@ -1,6 +1,6 @@
-class AddClearanceToUsers < ActiveRecord::Migration
+class AddClearanceToUsers < ActiveRecord::Migration<%= migration_version %>
   def self.up
-    change_table :users  do |t|
+    change_table :users do |t|
 <% config[:new_columns].values.each do |column| -%>
       <%= column %>
 <% end -%>
@@ -24,7 +24,7 @@ class AddClearanceToUsers < ActiveRecord::Migration
   def self.down
     change_table :users do |t|
 <% if config[:new_columns].any? -%>
-      t.remove <%= new_columns.keys.map { |column| ":#{column}" }.join(",") %>
+      t.remove <%= new_columns.keys.map { |column| ":#{column}" }.join(", ") %>
 <% end -%>
     end
   end

data/lib/generators/clearance/install/templates/db/migrate/{create_users.rb → create_users.rb.erb}

@@ -1,6 +1,6 @@
-class CreateUsers < ActiveRecord::Migration
+class CreateUsers < ActiveRecord::Migration<%= migration_version %>
   def change
-    create_table :users  do |t|
+    create_table :users do |t|
       t.timestamps null: false
       t.string :email, null: false
       t.string :encrypted_password, limit: 128, null: false

data/lib/generators/clearance/install/templates/user.rb.erb

@@ -0,0 +1,3 @@
+class User < <%= @inherit_from %>
+  include Clearance::User
+end

data/lib/generators/clearance/routes/routes_generator.rb

@@ -9,6 +9,14 @@ module Clearance
         route(clearance_routes)
       end
 
+      def disable_clearance_internal_routes
+        inject_into_file(
+          "config/initializers/clearance.rb",
+          "  config.routes = false\n",
+          after: "Clearance.configure do |config|\n",
+        )
+      end
+
       private
 
       def clearance_routes
@@ -18,6 +26,21 @@ module Clearance
       def routes_file_path
         File.expand_path(find_in_source_paths('routes.rb'))
       end
+
+      def route(routing_code)
+        log :route, "all clearance routes"
+        sentinel = /\.routes\.draw do\s*\n/m
+
+        in_root do
+          inject_into_file(
+            "config/routes.rb",
+            routing_code,
+            after: sentinel,
+            verbose: false,
+            force: true,
+          )
+        end
+      end
     end
   end
 end

data/lib/generators/clearance/routes/templates/routes.rb

@@ -1,12 +1,12 @@
-resources :passwords, controller: 'clearance/passwords', only: [:create, :new]
-  resource :session, controller: 'clearance/sessions', only: [:create]
+  resources :passwords, controller: "clearance/passwords", only: [:create, :new]
+  resource :session, controller: "clearance/sessions", only: [:create]
 
-  resources :users, controller: 'clearance/users', only: [:create] do
+  resources :users, controller: "clearance/users", only: [:create] do
     resource :password,
-      controller: 'clearance/passwords',
+      controller: "clearance/passwords",
       only: [:create, :edit, :update]
   end
 
-  get '/sign_in' => 'clearance/sessions#new', as: 'sign_in'
-  delete '/sign_out' => 'clearance/sessions#destroy', as: 'sign_out'
-  get '/sign_up' => 'clearance/users#new', as: 'sign_up'
+  get "/sign_in" => "clearance/sessions#new", as: "sign_in"
+  delete "/sign_out" => "clearance/sessions#destroy", as: "sign_out"
+  get "/sign_up" => "clearance/users#new", as: "sign_up"

data/lib/generators/clearance/specs/templates/factories/clearance.rb

@@ -1,10 +1,10 @@
-FactoryGirl.define do
+FactoryBot.define do
   sequence :email do |n|
     "user#{n}@example.com"
   end
 
   factory :user do
     email
-    password "password"
+    password { "password" }
   end
 end

data/lib/generators/clearance/specs/templates/features/clearance/user_signs_out_spec.rb.tt

@@ -1,7 +1,7 @@
 require "<%= @helper_file %>"
 require "support/features/clearance_helpers"
 
-feature "User signs out" do
+RSpec.feature "User signs out" do
   scenario "signs out" do
     sign_in
     sign_out

data/lib/generators/clearance/specs/templates/features/clearance/visitor_resets_password_spec.rb.tt

@@ -1,8 +1,17 @@
 require "<%= @helper_file %>"
 require "support/features/clearance_helpers"
 
-feature "Visitor resets password" do
+RSpec.feature "Visitor resets password" do
   before { ActionMailer::Base.deliveries.clear }
+<% if defined?(ActiveJob) -%>
+
+  around do |example|
+    original_adapter = ActiveJob::Base.queue_adapter
+    ActiveJob::Base.queue_adapter = :inline
+    example.run
+    ActiveJob::Base.queue_adapter = original_adapter
+  end
+<% end -%>
 
   scenario "by navigating to the page" do
     visit sign_in_path
@@ -33,7 +42,7 @@ feature "Visitor resets password" do
     expect_mailer_to_have_delivery(
       user.email,
       "password",
-      user.confirmation_token
+      user.confirmation_token,
     )
   end
 
@@ -47,7 +56,7 @@ feature "Visitor resets password" do
     message = ActionMailer::Base.deliveries.any? do |email|
       email.to == [recipient] &&
         email.subject =~ /#{subject}/i &&
-        email.html_part.body =~ /#{body}/
+        email.html_part.body =~ /#{body}/ &&
         email.text_part.body =~ /#{body}/
     end
 

data/lib/generators/clearance/specs/templates/features/clearance/visitor_signs_in_spec.rb.tt

@@ -1,7 +1,7 @@
 require "<%= @helper_file %>"
 require "support/features/clearance_helpers"
 
-feature "Visitor signs in" do
+RSpec.feature "Visitor signs in" do
   scenario "with valid email and password" do
     create_user "user@example.com", "password"
     sign_in_with "user@example.com", "password"
@@ -34,12 +34,12 @@ feature "Visitor signs in" do
   private
 
   def create_user(email, password)
-    FactoryGirl.create(:user, email: email, password: password)
+    FactoryBot.create(:user, email: email, password: password)
   end
 
   def expect_page_to_display_sign_in_error
     expect(page.body).to include(
-      I18n.t("flashes.failure_after_create", sign_up_path: sign_up_path)
+      I18n.t("flashes.failure_after_create", sign_up_path: sign_up_path),
     )
   end
 end

data/lib/generators/clearance/specs/templates/features/clearance/visitor_signs_up_spec.rb.tt

@@ -1,7 +1,7 @@
 require "<%= @helper_file %>"
 require "support/features/clearance_helpers"
 
-feature "Visitor signs up" do
+RSpec.feature "Visitor signs up" do
   scenario "by navigating to the page" do
     visit sign_in_path
 

data/lib/generators/clearance/specs/templates/features/clearance/visitor_updates_password_spec.rb.tt

@@ -1,7 +1,7 @@
 require "<%= @helper_file %>"
 require "support/features/clearance_helpers"
 
-feature "Visitor updates password" do
+RSpec.feature "Visitor updates password" do
   scenario "with valid password" do
     user = user_with_reset_password
     update_password user, "newpassword"
@@ -37,7 +37,7 @@ feature "Visitor updates password" do
   def visit_password_reset_page_for(user)
     visit edit_user_password_path(
       user_id: user,
-      token: user.confirmation_token
+      token: user.confirmation_token,
     )
   end
 

data/lib/generators/clearance/specs/templates/support/features/clearance_helpers.rb

@@ -8,7 +8,7 @@ module Features
 
     def sign_in
       password = "password"
-      user = FactoryGirl.create(:user, password: password)
+      user = FactoryBot.create(:user, password: password)
       sign_in_with user.email, password
     end
 
@@ -40,7 +40,7 @@ module Features
     end
 
     def user_with_reset_password
-      user = FactoryGirl.create(:user)
+      user = FactoryBot.create(:user)
       reset_password_for user.email
       user.reload
     end