rodauth-rails 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34d196440d63f28b871b42b21686018546c3e98df2239f69611847a0b3a2546a
-  data.tar.gz: d73de73af3c8985be686bf512c7b15bdf9bf27ecda1bfe30ad8d8a21964f0de0
+  metadata.gz: 8643f8a912963b78be7d03a815b813688304f4e4b2777a1fdade807f79a4c712
+  data.tar.gz: 31aadb16115fc826750b7d160dcb572ae9c24255d99a7c640abef5fd157bd319
 SHA512:
-  metadata.gz: acddd3554346ce6f7048ac56a59e0f0439312668fbf8e94450fd23d4d2464ad82655e221e6e15cd5755ef9207c49fe56c6fb67d95bbb764989ec39c6ff4df46a
-  data.tar.gz: a2be70d18c1ac8f1d6fca8eaef39a54c88a468dc96140eff05b5bb6bf9c901b93de64fd71c9dc27ef302edf643d024e34141b9258b3879a75e0aa96af28b7a27
+  metadata.gz: dd27d717b3a01f0b5f43e346c0cd839e2703ee0db44f7503eb6ce80f7cffd4493f4ed9e208db474af56af536f675444170f16a6d47435e1f4ce2af38a7487916
+  data.tar.gz: bbac5b7492751e76886a5bcd275af78aada1026d2cd95ddee732817e8d7a5a154f559e5c27ce08606d444a1ffd4640f8522744bd13939f6491288d57c986fea0

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.1.0 (2022-01-16)
+
+* Automatically route the path prefix in `r.rodauth` if one has been set (@janko)
+
 ## 1.0.0 (2021-12-25)
 
 * Set Rodauth's email subject in the generated mailer (@janko)

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020 Janko Marohnić
+Copyright (c) 2020-2022 Janko Marohnić
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -95,8 +95,8 @@ config.action_mailer.default_url_options = { host: 'localhost', port: 3000 }
 
 ### Routes
 
-Because requests to Rodauth endpoints are handled by the Rodauth middleware, and
-not a Rails controller, Rodauth routes will not show in `rails routes`.
+Because requests to Rodauth endpoints are handled by a Rack middleware (and not
+a Rails controller), Rodauth routes will not show in `rails routes`.
 
 Use the `rodauth:routes` rake task to view the list of endpoints based on
 currently loaded features:
@@ -609,21 +609,12 @@ them under a name.
 ```rb
 # app/misc/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
-  # primary configuration
-  configure RodauthMain
-
-  # secondary configuration
-  configure RodauthAdmin, :admin
+  configure RodauthMain          # primary configuration
+  configure RodauthAdmin, :admin # secondary configuration
 
   route do |r|
-    r.rodauth
-
-    r.on "admin" do
-      r.rodauth(:admin)
-      break # allow routing of other /admin/* requests to continue to Rails
-    end
-
-    # ...
+    r.rodauth         # route primary rodauth requests
+    r.rodauth(:admin) # route secondary rodauth requests
   end
 end
 ```
@@ -635,7 +626,6 @@ class RodauthAdmin < Rodauth::Rails::Auth
     prefix "/admin"
     session_key_prefix "admin_"
     remember_cookie_key "_admin_remember" # if using remember feature
-    # ...
 
     # search views in `app/views/admin/rodauth` directory
     rails_controller { Admin::RodauthController }
@@ -717,10 +707,6 @@ RodauthApp.rodauth.verify_account(account_login: "user@example.com")
 RodauthApp.rodauth(:admin).close_account(account_login: "user@example.com")
 ```
 
-The rodauth-rails gem additionally updates the internal rack env hash with your
-`config.action_mailer.default_url_options`, which is used for generating email
-links.
-
 ### Generating URLs
 
 For generating authentication URLs outside of a request use the
@@ -781,104 +767,6 @@ Rodauth::Rails.rodauth(session: { two_factor_auth_setup: true })
 Rodauth::Rails.rodauth(:admin, params: { "param" => "value" })
 ```
 
-## How it works
-
-### Middleware
-
-rodauth-rails inserts a `Rodauth::Rails::Middleware` into your middleware
-stack, which calls your Rodauth app for each request, before the request
-reaches the Rails router.
-
-```sh
-$ rails middleware
-...
-use Rodauth::Rails::Middleware
-run MyApp::Application.routes
-```
-
-The Rodauth app stores the `Rodauth::Auth` instance in the Rack env hash, which
-is then available in your Rails app:
-
-```rb
-request.env["rodauth"]       #=> #<Rodauth::Auth>
-request.env["rodauth.admin"] #=> #<Rodauth::Auth> (if using multiple configurations)
-```
-
-For convenience, this object can be accessed via the `#rodauth` method in views
-and controllers:
-
-```rb
-class MyController < ApplicationController
-  def my_action
-    rodauth         #=> #<Rodauth::Auth>
-    rodauth(:admin) #=> #<Rodauth::Auth> (if using multiple configurations)
-  end
-end
-```
-```erb
-<% rodauth         #=> #<Rodauth::Auth> %>
-<% rodauth(:admin) #=> #<Rodauth::Auth> (if using multiple configurations) %>
-```
-
-### App
-
-The `Rodauth::Rails::App` class is a [Roda] subclass that provides Rails
-integration for Rodauth:
-
-* 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 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].
-
-```rb
-class RodauthApp < Rodauth::Rails::App
-  configure { ... }             # defining default Rodauth configuration
-  configure(json: true) { ... } # passing options to the Rodauth plugin
-  configure(:admin) { ... }     # defining multiple Rodauth configurations
-end
-```
-
-The `route` block is provided by Roda, and it's called on each request before
-it reaches the Rails router.
-
-```rb
-class RodauthApp < Rodauth::Rails::App
-  route do |r|
-    # ... called before each request ...
-  end
-end
-```
-
-Since `Rodauth::Rails::App` is just a Roda subclass, you can do anything you
-would with a Roda app, such as loading additional Roda plugins:
-
-```rb
-class RodauthApp < Rodauth::Rails::App
-  plugin :request_headers # easier access to request headers
-  plugin :typecast_params # methods for conversion of request params
-  plugin :default_headers, { "Foo" => "Bar" }
-  # ...
-end
-```
-
-### Sequel
-
-Rodauth uses the [Sequel] library for database queries, due to more advanced
-database usage (SQL expressions, database-agnostic date arithmetic, SQL
-function calls).
-
-If ActiveRecord is used in the application, the `rodauth:install` generator
-will have automatically configured Sequel to reuse ActiveRecord's database
-connection, using the [sequel-activerecord_connection] gem.
-
-This means that, from the usage perspective, Sequel can be considered just
-as an implementation detail of Rodauth.
-
 ## Configuring
 
 ### Configuration methods
@@ -897,23 +785,6 @@ methods:
 | `rails_controller`          | Controller class to use for rendering and CSRF protection.         |
 | `rails_account_model`       | Model class connected with the accounts table.                     |
 
-### General configuration
-
-The `Rodauth::Rails` module has a few config settings available as well:
-
-| Name         | Description                                                                                         |
-| :-----       | :----------                                                                                         |
-| `app`        | Constant name of your Rodauth app, which is called by the middleware.                               |
-| `middleware` | Whether to insert the middleware into the Rails application's middleware stack. Defaults to `true`. |
-
-```rb
-# config/initializers/rodauth.rb
-Rodauth::Rails.configure do |config|
-  config.app = "RodauthApp"
-  config.middleware = true
-end
-```
-
 For the list of configuration methods provided by Rodauth, see the [feature
 documentation].
 
@@ -926,7 +797,9 @@ auth class:
 ```rb
 class RodauthMain < Rodauth::Rails::Auth
   configure do
+    # ...
     password_match? { |password| ldap_valid?(password) }
+    # ...
   end
 
   # Example external identities table
@@ -1013,6 +886,172 @@ class RodauthApp < Rodauth::Rails::App
 end
 ```
 
+## How it works
+
+### Rack middleware
+
+The railtie inserts [`Rodauth::Rails::Middleware`](/lib/rodauth/rails/middleware.rb)
+at the end of the middleware stack, which calls your Rodauth app around each request.
+
+```sh
+$ rails middleware
+# ...
+# use Rodauth::Rails::Middleware
+# run MyApp::Application.routes
+```
+
+It can be inserted at any point in the middleware stack:
+
+```rb
+Rodauth::Rails.configure do |config|
+  config.middleware = false # disable auto-insertion
+end
+
+Rails.application.config.middleware.insert_before AnotherMiddleware, Rodauth::Rails::Middleware
+```
+
+The middleware retrieves the Rodauth app via `Rodauth::Rails.app`, which is
+specified as a string to keep the class autoloadable and reloadable in
+development.
+
+```rb
+Rodauth::Rails.configure do |config|
+  config.app = "RodauthApp"
+end
+```
+
+In addition to Zeitwerk compatibility, this extra layer catches Rodauth redirects
+that happen on the controller level (e.g. when calling
+`rodauth.require_authentication` in a `before_action` filter).
+
+### Roda app
+
+The [`Rodauth::Rails::App`](/lib/rodauth/rails/app.rb) class is a [Roda]
+subclass that provides a convenience layer for Rodauth:
+
+* uses Action Dispatch flash messages
+* provides syntax sugar for loading the rodauth plugin
+* saves Rodauth object(s) to Rack env hash
+* propagates edited headers to Rails responses
+
+#### Configure block
+
+The `configure` call loads the rodauth plugin. By convention, it receives an
+auth class and configuration name as positional arguments (forwarded as
+`:auth_class` and `:name` plugin options), a block for anonymous auth classes,
+and also accepts any additional plugin options.
+
+```rb
+class RodauthApp < Rodauth::Rails::App
+  # named auth class
+  configure(RodauthMain)
+  configure(RodauthAdmin, :admin)
+
+  # anonymous auth class
+  configure { ... }
+  configure(:admin) { ... }
+
+  # plugin options
+  configure(RodauthMain, json: :only)
+end
+```
+
+#### Route block
+
+The `route` block is called for each request, before it reaches the Rails
+router, and it's yielded the request object.
+
+```rb
+class RodauthApp < Rodauth::Rails::App
+  route do |r|
+    # called before each request
+  end
+end
+```
+
+#### Routing prefix
+
+If you use a routing prefix, you don't need to add a call to `r.on` like with
+vanilla Rodauth, as `r.rodauth` has been modified to automatically route the
+prefix.
+
+```rb
+class RodauthApp < Rodauth::Rails::App
+  configure do
+    prefix "/user"
+  end
+
+  route do |r|
+    r.rodauth # no need to wrap with `r.on("user") { ... }`
+  end
+end
+```
+
+### Auth class
+
+The [`Rodauth::Rails::Auth`](/lib/rodauth/rails/auth.rb) class is a subclass of
+`Rodauth::Auth`, which preloads the `rails` rodauth feature, sets [HMAC] secret to
+Rails' secret key base, and modifies some [configuration defaults](#rodauth-defaults).
+
+```rb
+class RodauthMain < Rodauth::Rails::Auth
+  configure do
+    # authentication configuration
+  end
+end
+```
+
+### Rodauth feature
+
+The [`rails`](/lib/rodauth/rails/feature.rb) Rodauth feature loaded by
+`Rodauth::Rails::Auth` provides the main part of the Rails integration for Rodauth:
+
+* uses Action View for template rendering
+* uses Action Dispatch for CSRF protection
+* runs Action Controller callbacks and rescue from blocks around Rodauth requests
+* uses Action Mailer to create and deliver emails
+* uses Action Controller instrumentation around Rodauth requests
+* uses Action Mailer's default URL options when calling Rodauth outside of a request
+
+### Controller
+
+The Rodauth app stores the `Rodauth::Rails::Auth` instances in the Rack env
+hash, which is then available in your Rails app:
+
+```rb
+request.env["rodauth"]       #=> #<RodauthMain>
+request.env["rodauth.admin"] #=> #<RodauthAdmin> (if using multiple configurations)
+```
+
+For convenience, this object can be accessed via the `#rodauth` method in views
+and controllers:
+
+```rb
+class MyController < ApplicationController
+  def my_action
+    rodauth         #=> #<RodauthMain>
+    rodauth(:admin) #=> #<RodauthAdmin> (if using multiple configurations)
+  end
+end
+```
+```erb
+<% rodauth         #=> #<RodauthMain> %>
+<% rodauth(:admin) #=> #<RodauthAdmin> (if using multiple configurations) %>
+```
+
+### Sequel
+
+Rodauth uses the [Sequel] library for database interaction, which offers
+powerful APIs for building advanced queries (it supports SQL expressions,
+database-agnostic date arithmetic, SQL function calls).
+
+If you're using Active Record in your application, the `rodauth:install`
+generator automatically configures Sequel to reuse ActiveRecord's database
+connection, using the [sequel-activerecord_connection] gem.
+
+This means that, from the usage perspective, Sequel can be considered just
+as an implementation detail of Rodauth.
+
 ## Rodauth defaults
 
 rodauth-rails changes some of the default Rodauth settings for easier setup:

data/lib/generators/rodauth/templates/app/misc/rodauth_app.rb

@@ -12,12 +12,9 @@ class RodauthApp < Rodauth::Rails::App
 <% end -%>
     r.rodauth # route rodauth requests
 
-    # ==> Authenticating Requests
+    # ==> Authenticating requests
     # Call `rodauth.require_authentication` for requests that you want to
-    # require authentication for. Some examples:
-    #
-    # next if r.path.start_with?("/docs") # skip authentication for documentation pages
-    # next if session[:admin] # skip authentication for admins
+    # require authentication for. For example:
     #
     # # authenticate /dashboard/* and /account/* requests
     # if r.path.start_with?("/dashboard") || r.path.start_with?("/account")
@@ -25,14 +22,6 @@ class RodauthApp < Rodauth::Rails::App
     # end
 
     # ==> Secondary configurations
-    # r.on "admin" do
-    #   r.rodauth(:admin)
-    #
-    #   unless rodauth(:admin).logged_in?
-    #     rodauth(:admin).require_http_basic_auth
-    #   end
-    #
-    #   break # allow the Rails app to handle other "/admin/*" requests
-    # end
+    # r.rodauth(:admin) # route admin rodauth requests
   end
 end

data/lib/rodauth/rails/app.rb

@@ -25,6 +25,8 @@ module Rodauth
         auth_class ||= Class.new(Rodauth::Rails::Auth)
 
         plugin :rodauth, auth_class: auth_class, name: name, csrf: false, flash: false, json: true, **options, &block
+
+        self::RodaRequest.include RequestMethods
       end
 
       before do
@@ -44,6 +46,21 @@ module Rodauth
       def self.rodauth!(name)
         rodauth(name) or fail ArgumentError, "unknown rodauth configuration: #{name.inspect}"
       end
+
+      module RequestMethods
+        def rodauth(name = nil)
+          prefix = scope.rodauth(name).prefix
+
+          if prefix.present? && remaining_path == path_info
+            on prefix[1..-1] do
+              super
+              break # forward other `{prefix}/*` requests to the rails router
+            end
+          else
+            super
+          end
+        end
+      end
     end
   end
 end

data/lib/rodauth/rails/version.rb

@@ -1,5 +1,5 @@
 module Rodauth
   module Rails
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rodauth-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-25 00:00:00.000000000 Z
+date: 2022-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties