rodauth-rails 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0d00b7ad2f6198fff3a5cc3c720c6f30d9296898e3fd764ddf7408e36232a6d
-  data.tar.gz: 9ba008116fc5521c98ed62dda5b1f6b2eccd733d06ccb0a2c5b9b4db8df94539
+  metadata.gz: 00d7ab9dd749cbae17cddc2788005d8570d8d46f89f427ad624c7e61fe177665
+  data.tar.gz: d62aed32823b0be9c74d7281de80650b8faf600c01db22ad941a35f30bfeb002
 SHA512:
-  metadata.gz: 848873e599cfb8dc8a5d274ac5fec5987cf4c895c77757a4b21529ddcd9a635ba8086c037f55c55ef097ae926549234e5abebb97a5300f0ead6118927d737d91
-  data.tar.gz: aa75fb48217e79c40000cf1f226f36a65fdffdcb764233572ae45341b7ab9dd2f1d8f8470e593d8260495962b1b5c352e62d0d5e71fed0cb96891da93a0f344c
+  metadata.gz: 7ab0afe5e95fab1af706b64ef5c494252fac49481d49dad1c2ef3510c17ca96050c58bf0832a36af761673137f2fd63d7d49a692656bcf06748840de96f60875
+  data.tar.gz: 729bf3b5887647c23f4b11d821d3829c4b4d290c546d2f19ba6b393dd47bf0b357d128577e877ac3e0a4352972b79325d4217d62935d4a683e78ff8e910d13a2

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.6.0 (2020-11-22)
+
+* Add `Rodauth::Rails.rodauth` method for retrieving Rodauth instance outside of request context (@janko)
+
+* Add default Action Dispatch response headers in Rodauth responses (@janko)
+
+* Run controller rescue handlers around Rodauth actions (@janko)
+
+* Run controller action callbacks around Rodauth actions (@janko)
+
 ## 0.5.0 (2020-11-16)
 
 * Support more Active Record adapters in `rodauth:install` generator (@janko)

data/README.md

@@ -4,16 +4,22 @@ Provides Rails integration for the [Rodauth] authentication framework.
 
 ## Resources
 
+Useful links:
+
 * [Rodauth documentation](http://rodauth.jeremyevans.net/documentation.html)
-* [rodauth-rails wiki](https://github.com/janko/rodauth-rails/wiki)
 * [Rails demo](https://github.com/janko/rodauth-demo-rails)
 
+Articles:
+
+* [Rodauth: A Refreshing Authentication Solution for Ruby](https://janko.io/rodauth-a-refreshing-authentication-solution-for-ruby/)
+* [Adding Authentication in Rails 6 with Rodauth](https://janko.io/adding-authentication-in-rails-with-rodauth/)
+
 ## Installation
 
 Add the gem to your Gemfile:
 
 ```rb
-gem "rodauth-rails", "~> 0.4"
+gem "rodauth-rails", "~> 0.6"
 
 # gem "jwt",      require: false # for JWT feature
 # gem "rotp",     require: false # for OTP feature
@@ -111,8 +117,9 @@ end
 
 ### Controller
 
-Your Rodauth app will by default use `RodauthController` for view rendering
-and CSRF protection.
+Your Rodauth app will by default use `RodauthController` for view rendering,
+CSRF protection, and running controller callbacks and rescue handlers around
+Rodauth actions.
 
 ```rb
 # app/controllers/rodauth_controller.rb
@@ -131,9 +138,11 @@ class Account < ApplicationRecord
 end
 ```
 
-## Getting started
+## Usage
 
-First, let's see what routes our Rodauth middleware will handle:
+### Routes
+
+We can see the list of routes our Rodauth middleware handles:
 
 ```sh
 $ rails rodauth:routes
@@ -155,8 +164,8 @@ Routes handled by RodauthApp:
   /close-account           rodauth.close_account_path
 ```
 
-We can use this information to add some basic authentication navigation links
-to our home page:
+Using this information, we could add some basic authentication links to our
+navigation header:
 
 ```erb
 <ul>
@@ -169,40 +178,45 @@ to our home page:
 </ul>
 ```
 
-These links are fully functional, feel free to visit them and interact with the
+These routes are fully functional, feel free to visit them and interact with the
 pages. The templates that ship with Rodauth aim to provide a complete
 authentication experience, and the forms use [Bootstrap] markup.
 
-Let's also load the account record for authenticated requests and expose it via
-`#current_account`:
+### Current account
+
+To be able to fetch currently authenticated account, let's define a
+`#current_account` method that fetches the account id from session and
+retrieves the corresponding account record:
 
 ```rb
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
-  before_action :load_account, if: -> { rodauth.authenticated? }
+  before_action :current_account, if: -> { rodauth.authenticated? }
 
   private
 
-  def load_account
-    @current_account = Account.find(rodauth.session_value)
+  def current_account
+    @current_account ||= Account.find(rodauth.session_value)
   rescue ActiveRecord::RecordNotFound
     rodauth.logout
     rodauth.login_required
   end
-
-  attr_reader   :current_account
   helper_method :current_account
 end
 ```
+
+This allows us to access the current account in controllers and views:
+
 ```erb
 <p>Authenticated as: <%= current_account.email %></p>
 ```
 
 ### Requiring authentication
 
-Next, we'll likely want to require authentication for certain sections/pages of
-our app. We can do this in our Rodauth app's routing block, which helps keep
-the authentication logic encapsulated:
+We'll likely want to require authentication for certain parts of our app,
+redirecting the user to the login page if they're not logged in. We can do this
+in our Rodauth app's routing block, which helps keep the authentication logic
+encapsulated:
 
 ```rb
 # app/lib/rodauth_app.rb
@@ -260,9 +274,9 @@ end
 
 ### Views
 
-The templates built into Rodauth are useful when getting started, but at some
-point we'll probably want more control over the markup. For that we can run the
-following command:
+The templates built into Rodauth are useful when getting started, but soon
+you'll want to start editing the markup. You can run the following command to
+copy Rodauth templates into your Rails app:
 
 ```sh
 $ rails generate rodauth:views
@@ -286,7 +300,7 @@ $ rails generate rodauth:views --all
 ```
 
 You can also tell the generator to create views into another directory (in this
-case make sure to rename the Rodauth controller accordingly).
+case make sure to rename the Rodauth controller accordingly):
 
 ```sh
 # generates views into app/views/authentication
@@ -366,8 +380,8 @@ end
 ```
 
 You can then uncomment the lines in your Rodauth configuration to have it call
-your mailer. If you've enabled additional authentication features, make sure to
-override their `send_*_email` methods as well.
+your mailer. If you've enabled additional authentication features that send
+emails, make sure to override their `send_*_email` methods as well.
 
 ```rb
 # app/lib/rodauth_app.rb
@@ -408,10 +422,11 @@ end
 
 ### Migrations
 
-The install generator will have created some default tables, but you can use
-the migration generator to create tables for any additional Rodauth features:
+The install generator will create a migration for tables used by the Rodauth
+features enabled by default. For any additional features, you can use the
+migration generator to create the corresponding tables:
 
-```
+```sh
 $ rails generate rodauth:migration otp sms_codes recovery_codes
 ```
 ```rb
@@ -456,6 +471,25 @@ the configure method.
 Make sure to store the `jwt_secret` in a secure place, such as Rails
 credentials or environment variables.
 
+### Rodauth instance
+
+In some cases you might need to use Rodauth more programmatically, and perform
+Rodauth operations outside of the request context. rodauth-rails gives you the
+ability to retrieve the Rodauth instance:
+
+```rb
+rodauth = Rodauth::Rails.rodauth # or Rodauth::Rails.rodauth(:secondary)
+
+rodauth.login_url #=> "https://example.com/login"
+rodauth.account_from_login("user@example.com") # loads user by email
+rodauth.password_match?("secret") #=> true
+rodauth.setup_account_verification
+rodauth.close_account
+```
+
+This Rodauth instance will be initialized with basic Rack env that allows is it
+to generate URLs, using `config.action_mailer.default_url_options` options.
+
 ## How it works
 
 ### Middleware
@@ -500,11 +534,12 @@ end
 The `Rodauth::Rails::App` class is a [Roda] subclass that provides Rails
 integration for Rodauth:
 
-* uses Rails' flash instead of Roda's
-* uses Rails' CSRF protection instead of Roda's
+* uses Action Dispatch flash instead of Roda's
+* uses Action Dispatch CSRF protection instead of Roda's
 * sets [HMAC] secret to Rails' secret key base
-* uses ActionController for rendering templates
-* uses ActionMailer for sending emails
+* uses Action Controller for rendering templates
+* runs Action Controller callbacks & rescue handlers around Rodauth actions
+* uses Action Mailer for sending emails
 
 The `configure { ... }` method wraps configuring the Rodauth plugin, forwarding
 any additional [plugin options].
@@ -635,15 +670,11 @@ Rodauth method for creating database functions:
 # db/migrate/*_create_rodauth_database_functions.rb
 class CreateRodauthDatabaseFunctions < ActiveRecord::Migration
   def up
-    # ...
     Rodauth.create_database_authentication_functions(DB)
-    # ...
   end
 
   def down
-    # ...
     Rodauth.drop_database_authentication_functions(DB)
-    # ...
   end
 end
 ```
@@ -700,7 +731,6 @@ conduct](https://github.com/janko/rodauth-rails/blob/master/CODE_OF_CONDUCT.md).
 
 [Rodauth]: https://github.com/jeremyevans/rodauth
 [Sequel]: https://github.com/jeremyevans/sequel
-[rendering views outside of controllers]: https://blog.bigbinary.com/2016/01/08/rendering-views-outside-of-controllers-in-rails-5.html
 [feature documentation]: http://rodauth.jeremyevans.net/documentation.html
 [JWT feature]: http://rodauth.jeremyevans.net/rdoc/files/doc/jwt_rdoc.html
 [JWT gem]: https://github.com/jwt/ruby-jwt

data/lib/rodauth/rails.rb

@@ -9,14 +9,33 @@ module Rodauth
     # This allows the developer to avoid loading Rodauth at boot time.
     autoload :App, "rodauth/rails/app"
 
-    def self.configure
-      yield self
-    end
-
     @app = nil
     @middleware = true
 
     class << self
+      def rodauth(name = nil)
+        url_options = ActionMailer::Base.default_url_options
+
+        scheme   = url_options[:protocol] || "http"
+        port     = url_options[:port]
+        port   ||= Rack::Request::DEFAULT_PORTS[scheme] if Gem::Version.new(Rack.release) < Gem::Version.new("2.0")
+        host     = url_options[:host]
+        host    += ":#{port}" if port
+
+        rack_env = {
+          "HTTP_HOST"       => host,
+          "rack.url_scheme" => scheme,
+        }
+
+        scope = app.new(rack_env)
+
+        scope.rodauth(name)
+      end
+
+      def configure
+        yield self
+      end
+
       attr_writer :app
       attr_writer :middleware
 

data/lib/rodauth/rails/app.rb

@@ -10,7 +10,7 @@ module Rodauth
 
       def self.configure(name = nil, **options, &block)
         unless options[:json] == :only
-          require "rodauth/rails/app/flash"
+          require "rodauth/rails/flash"
           plugin Flash
         end
 

data/lib/rodauth/rails/feature.rb

@@ -9,10 +9,11 @@ module Rodauth
       :rails_csrf_param,
       :rails_csrf_token,
       :rails_check_csrf!,
-      :rails_controller_instance,
       :rails_controller,
     )
 
+    auth_cached_method :rails_controller_instance
+
     # Renders templates with layout. First tries to render a user-defined
     # template, otherwise falls back to Rodauth's template.
     def view(page, *)
@@ -28,6 +29,11 @@ module Rodauth
         super
     end
 
+    # Render Rails CSRF tags in Rodauth templates.
+    def csrf_tag(*)
+      rails_csrf_tag
+    end
+
     # Verify Rails' authenticity token.
     def check_csrf
       rails_check_csrf!
@@ -38,11 +44,6 @@ module Rodauth
       true
     end
 
-    # Render Rails CSRF tags in Rodauth templates.
-    def csrf_tag(*)
-      rails_csrf_tag
-    end
-
     # Default the flash error key to Rails' default :alert.
     def flash_error_key
       :alert
@@ -50,6 +51,59 @@ module Rodauth
 
     private
 
+    # Runs controller callbacks and rescue handlers around Rodauth actions.
+    def _around_rodauth(&block)
+      result = nil
+
+      rails_controller_rescue do
+        rails_controller_callbacks do
+          result = catch(:halt) { super(&block) }
+        end
+      end
+
+      if rails_controller_instance.performed?
+        rails_controller_response
+      else
+        result[1].merge!(rails_controller_instance.response.headers)
+        throw :halt, result
+      end
+    end
+
+    # Runs any #(before|around|after)_action controller callbacks.
+    def rails_controller_callbacks
+      # don't verify CSRF token as part of callbacks, Rodauth will do that
+      rails_controller_instance.allow_forgery_protection = false
+
+      rails_controller_instance.run_callbacks(:process_action) do
+        # turn the setting back to default so that form tags generate CSRF tags
+        rails_controller_instance.allow_forgery_protection = rails_controller.allow_forgery_protection
+
+        yield
+      end
+    end
+
+    # Runs any registered #rescue_from controller handlers.
+    def rails_controller_rescue
+      yield
+    rescue Exception => exception
+      rails_controller_instance.rescue_with_handler(exception) || raise
+
+      unless rails_controller_instance.performed?
+        raise Rodauth::Rails::Error, "rescue_from handler didn't write any response"
+      end
+    end
+
+    # Returns Roda response from controller response if set.
+    def rails_controller_response
+      controller_response = rails_controller_instance.response
+
+      response.status = controller_response.status
+      response.headers.merge! controller_response.headers
+      response.write controller_response.body
+
+      request.halt
+    end
+
     # Create emails with ActionMailer which uses configured delivery method.
     def create_email_to(to, subject, body)
       Mailer.create_email(to: to, from: email_from, subject: "#{email_subject_prefix}#{subject}", body: body)
@@ -64,11 +118,14 @@ module Rodauth
     def rails_render(*args)
       return if only_json?
 
-      begin
-        rails_controller_instance.render_to_string(*args)
-      rescue ActionView::MissingTemplate
-        nil
-      end
+      rails_controller_instance.render_to_string(*args)
+    rescue ActionView::MissingTemplate
+      nil
+    end
+
+    # Calls the controller to verify the authenticity token.
+    def rails_check_csrf!
+      rails_controller_instance.send(:verify_authenticity_token)
     end
 
     # Hidden tag with Rails CSRF token inserted into Rodauth templates.
@@ -86,13 +143,8 @@ module Rodauth
       rails_controller_instance.send(:form_authenticity_token)
     end
 
-    # Calls the controller to verify the authenticity token.
-    def rails_check_csrf!
-      rails_controller_instance.send(:verify_authenticity_token)
-    end
-
     # Instances of the configured controller with current request's env hash.
-    def rails_controller_instance
+    def _rails_controller_instance
       request  = ActionDispatch::Request.new(scope.env)
       instance = rails_controller.new
 

data/lib/rodauth/rails/flash.rb

@@ -0,0 +1,48 @@
+module Rodauth
+  module Rails
+    # Roda plugin that sets up Rails flash integration.
+    module Flash
+      def self.load_dependencies(app)
+        app.plugin :hooks
+      end
+
+      def self.configure(app)
+        app.before { request.flash }        # load flash
+        app.after  { request.commit_flash } # save flash
+      end
+
+      module InstanceMethods
+        def flash
+          request.flash
+        end
+      end
+
+      module RequestMethods
+        # If the redirect would bubble up outside of the Roda app, the after
+        # hook would never get called, so we make sure to commit the flash.
+        def redirect(*)
+          commit_flash
+          super
+        end
+
+        def flash
+          rails_request.flash
+        end
+
+        def commit_flash
+          if ActionPack.version >= Gem::Version.new("5.0")
+            rails_request.commit_flash
+          else
+            # ActionPack 4.2 automatically commits flash
+          end
+        end
+
+        private
+
+        def rails_request
+          ActionDispatch::Request.new(env)
+        end
+      end
+    end
+  end
+end

data/lib/rodauth/rails/tasks.rake

@@ -3,19 +3,16 @@ namespace :rodauth do
     app = Rodauth::Rails.app
 
     puts "Routes handled by #{app}:"
-    puts
 
-    app.opts[:rodauths].each do |rodauth_name, rodauth_class|
-      route_names = rodauth_class.routes
-        .map { |handle_method| handle_method.to_s.sub(/\Ahandle_/, "") }
-        .uniq
+    app.opts[:rodauths].each_key do |rodauth_name|
+      rodauth = Rodauth::Rails.rodauth(rodauth_name)
 
-      rodauth = rodauth_class.allocate
+      routes = rodauth.class.routes.map do |handle_method|
+        path_method = "#{handle_method.to_s.sub(/\Ahandle_/, "")}_path"
 
-      routes = route_names.map do |name|
         [
-          rodauth.public_send(:"#{name}_path"),
-          "rodauth#{rodauth_name && "(:#{rodauth_name})"}.#{name}_path",
+          rodauth.public_send(path_method),
+          "rodauth#{rodauth_name && "(:#{rodauth_name})"}.#{path_method}",
         ]
       end
 
@@ -25,8 +22,7 @@ namespace :rodauth do
         "#{path.ljust(padding)}  #{code}"
       end
 
-      puts "  #{route_lines.join("\n  ")}"
-      puts
+      puts "\n  #{route_lines.join("\n  ")}"
     end
   end
 end

data/lib/rodauth/rails/version.rb

@@ -1,5 +1,5 @@
 module Rodauth
   module Rails
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

data/rodauth-rails.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "railties", ">= 4.2", "< 7"
-  spec.add_dependency "rodauth", "~> 2.1"
+  spec.add_dependency "rodauth", "~> 2.6"
   spec.add_dependency "sequel-activerecord_connection", "~> 1.1"
   spec.add_dependency "tilt"
   spec.add_dependency "bcrypt"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rodauth-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-11-16 00:00:00.000000000 Z
+date: 2020-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.6'
 - !ruby/object:Gem::Dependency
   name: sequel-activerecord_connection
   requirement: !ruby/object:Gem::Requirement
@@ -190,9 +190,9 @@ files:
 - lib/rodauth/features/rails.rb
 - lib/rodauth/rails.rb
 - lib/rodauth/rails/app.rb
-- lib/rodauth/rails/app/flash.rb
 - lib/rodauth/rails/controller_methods.rb
 - lib/rodauth/rails/feature.rb
+- lib/rodauth/rails/flash.rb
 - lib/rodauth/rails/middleware.rb
 - lib/rodauth/rails/railtie.rb
 - lib/rodauth/rails/tasks.rake

data/lib/rodauth/rails/app/flash.rb

@@ -1,50 +0,0 @@
-module Rodauth
-  module Rails
-    class App
-      # Sets up Rails' flash integration.
-      module Flash
-        def self.load_dependencies(app)
-          app.plugin :hooks
-        end
-
-        def self.configure(app)
-          app.before { request.flash }        # load flash
-          app.after  { request.commit_flash } # save flash
-        end
-
-        module InstanceMethods
-          def flash
-            request.flash
-          end
-        end
-
-        module RequestMethods
-          # If the redirect would bubble up outside of the Roda app, the after
-          # hook would never get called, so we make sure to commit the flash.
-          def redirect(*)
-            commit_flash
-            super
-          end
-
-          def flash
-            rails_request.flash
-          end
-
-          def commit_flash
-            if ActionPack.version >= Gem::Version.new("5.0")
-              rails_request.commit_flash
-            else
-              # ActionPack 4.2 automatically commits flash
-            end
-          end
-
-          private
-
-          def rails_request
-            ActionDispatch::Request.new(env)
-          end
-        end
-      end
-    end
-  end
-end