rabarber 5.2.4 → 5.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b6af1a1a593e84b481d92883ca7adf385e2ee1fc9a3fb5615818169fc595444
-  data.tar.gz: 97738fdc3bb6e3463b8e331088982a4dcd40e62e4251977ee63cc8b742fcb96a
+  metadata.gz: 23cc4a1c2e65a3b450653b65df49633601756ada11844173b0c6314c41067ca9
+  data.tar.gz: 95153a3172c58bf636cb4d17981ba70336a292368f6bac26c2b6a107c4fcbaaa
 SHA512:
-  metadata.gz: 535dc707a59522461ad3b5bd26d0e394008454c738ff52e84fa6cd7ebfdd26bb441405326563b2ba4a2229008d0ddcf3b6b426dc9d21186896e53aadf99b5fa6
-  data.tar.gz: b32d8c3983deb895e7cefe2e3d273cbad0542477c1bad134a7681ac5ae1e390725f7e34b964de4c0f264fcb1b0d21546cb70b7d89ca29cb3c513e831d281c89c
+  metadata.gz: 180407341e8e4e700fff624ab12de40d9aa66ed4e132e8ddc92c0c9cb4c010309194e7b37bc825a9a92a0e9baf64022a165788055ccba6b41e60aab8d040fc20
+  data.tar.gz: 882d08be5cab1db66d0056ef5e0ace724d2d8ce633cdf75af808d28980faeadbdf9e56c4362e3b7197a89b0de80925f77b2dafb12c5f6e44b1f21cb43be0730d

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## v5.2.5
+
+### Misc:
+
+- Added support for Ruby 4
+
 ## v5.2.4
 
 ### Misc:
@@ -91,7 +97,7 @@ To upgrade to v5.0.0, please refer to the [migration guide](https://github.com/e
 
 - Optimized various parts of the code and database queries for improved performance
 - Streamlined the authorization process by requiring the user to be authenticated before access is verified
-- Rabarber now skips roles with missing instance context and prunes them automatically; missing class context still raises errors
+- Rabarber now skips roles with missing instance context; missing class context still raises errors
 
 ## v4.1.4
 

data/README.md

@@ -5,49 +5,44 @@
 [![Github Actions badge](https://github.com/enjaku4/rabarber/actions/workflows/ci.yml/badge.svg)](https://github.com/enjaku4/rabarber/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/enjaku4/rabarber.svg)](LICENSE)
 
-Rabarber is a role-based authorization library for Ruby on Rails that focuses on controller-level access control. Rather than answering domain questions like "can this user create a post?", Rabarber answers "can this user access the create post endpoint?", providing a clean separation between authorization and business logic. It supports multi-tenancy through contextual roles, dynamic authorization with conditional logic, and includes view helpers for role-based content rendering.
+Rabarber is a role-based authorization library for Ruby on Rails. It provides a set of tools for managing user roles and defining access rules, with support for multi-tenancy through context.
 
 **Example of Usage:**
 
-Consider a CRM system where users with different roles have distinct access levels. For instance, the role `accountant` can interact with invoices but cannot access marketing information, while the role `analyst` has access to marketing-related data. You can define such authorization rules easily with Rabarber.
+Consider a CRM system where users with different roles have distinct access levels. For instance, the role `accountant` can access invoice data but not marketing information, while the role `analyst` can view marketing data but not detailed financial records. You can define such authorization rules easily with Rabarber.
 
-And here's how your controller might look:
+___
+
+And this is how your controller might look with Rabarber:
 
 ```rb
-class InvoicesController < ApplicationController
-  grant_access roles: :admin # Admin can access everything
+class TicketsController < ApplicationController
+  grant_access roles: :admin
 
-  grant_access action: :index, roles: [:accountant, :analyst]
+  grant_access action: :index, roles: :manager
   def index
-    # Accessible to both analysts and accountants
-  end
-
-  grant_access action: :show, roles: :accountant
-  def show
-    # Accessible to accountants
-  end
-
-  grant_access action: :analytics, roles: :analyst
-  def analytics
-    # Accessible to analysts
+    # ...
   end
 
   def destroy
-    # Accessible to admins only
+    # ...
   end
 end
 ```
 
+This means that `admin` users can access everything in `TicketsController`, while the `manager` role can access only the `index` action.
+
 ## Table of Contents
 
 **Gem Usage:**
   - [Installation](#installation)
   - [Configuration](#configuration)
   - [User Role Methods](#user-role-methods)
-  - [Role Management](#role-management)
-  - [Controller Authorization](#controller-authorization)
-  - [Dynamic Rules](#dynamic-rules)
-  - [Multi-tenancy / Context](#multi-tenancy--context)
+  - [Direct Role Management](#direct-role-management)
+  - [Authorization](#authorization)
+  - [Dynamic Authorization Rules](#dynamic-authorization-rules)
+  - [When Unauthorized](#when-unauthorized)
+  - [Context / Multi-tenancy](#context--multi-tenancy)
   - [View Helpers](#view-helpers)
 
 **Community Resources:**
@@ -70,7 +65,7 @@ Install the gem:
 bundle install
 ```
 
-Generate the migration for role storage (replace `users` with your user table name if different):
+Generate the migration to store roles (replace `users` with your table name if different):
 
 ```shell
 # For standard integer IDs
@@ -88,7 +83,7 @@ rails db:migrate
 
 ## Configuration
 
-Configure Rabarber in an initializer if customization is needed:
+Create an initializer to customize Rabarber's behavior (optional):
 
 ```rb
 Rabarber.configure do |config|
@@ -98,7 +93,7 @@ Rabarber.configure do |config|
 end
 ```
 
-Roles are cached by default for performance. To clear the role cache manually:
+Roles are cached by default for better performance. Clear the cache manually when needed:
 
 ```rb
 Rabarber::Cache.clear
@@ -112,13 +107,13 @@ Your user model is automatically augmented with role management methods:
 
 ```rb
 # Assign roles (creates roles if they don't exist)
-user.assign_roles(:accountant, :manager)
+user.assign_roles(:admin, :manager)
 
-# Assign only existing roles
+# Assign only existing roles (don't create new ones)
 user.assign_roles(:accountant, :manager, create_new: false)
 
 # Revoke specific roles
-user.revoke_roles(:accountant, :manager)
+user.revoke_roles(:admin, :manager)
 
 # Revoke all roles
 user.revoke_all_roles
@@ -142,9 +137,9 @@ user.all_roles
 User.with_role(:admin, :manager)
 ```
 
-## Role Management
+## Direct Role Management
 
-### Direct Role Operations
+You can also manage roles directly:
 
 ```rb
 # Create a new role
@@ -165,41 +160,39 @@ Rabarber.roles
 Rabarber.all_roles
 ```
 
-> **Note:** Some methods have been deprecated in favor of the new API shown above. The deprecated methods still work but will be removed in a future major version. See the [changelog](https://github.com/enjaku4/rabarber/blob/main/CHANGELOG.md#v520) for the complete list of deprecated methods and their new counterparts.
+> **Note:** Some methods have been deprecated in favor of the new API shown above. Deprecated methods still work but will be removed in a future major version. See the [changelog](https://github.com/enjaku4/rabarber/blob/main/CHANGELOG.md#v520) for the complete list of deprecated methods and their replacements.
 
-## Controller Authorization
+## Authorization
 
-### Basic Setup
+### Setup
 
-Include the authorization module and configure protection:
+Include `Rabarber::Authorization` module in your controllers and configure protection:
 
 ```rb
 class ApplicationController < ActionController::Base
   include Rabarber::Authorization
 
-  with_authorization # Enable authorization for all actions
-end
-
-class InvoicesController < ApplicationController
-  with_authorization only: [:update, :destroy] # Selective authorization
+  with_authorization # Enable authorization check for all actions in all controllers by default
 end
 ```
 
-Authorization requires an authenticated user to be present.
-
-### Skip Authorization
-
-You can also selectively skip authorization:
+You can also enable authorization checks selectively. Both `with_authorization` and `skip_authorization` work exactly the same as Rails' `before_action` and `skip_before_action` methods:
 
 ```rb
 class TicketsController < ApplicationController
-  skip_authorization except: [:create, :update, :destroy]
+  skip_authorization only: [:index, :show] # Skip authorization for specific actions
+end
+
+class InvoicesController < ApplicationController
+  with_authorization except: [:index] # Enable authorization for all actions except index
 end
 ```
 
+Authorization requires an authenticated user. Rabarber will raise an error if no user is found via the configured `current_user_method`. Ensure authentication happens before authorization.
+
 ### Authorization Rules
 
-Define access rules using `grant_access`:
+Define authorization rules using `grant_access`:
 
 ```rb
 class TicketsController < ApplicationController
@@ -218,9 +211,7 @@ class TicketsController < ApplicationController
 end
 ```
 
-### Additive Rules
-
-Rules are additive across inheritance chains and for the same actions:
+Authorization rules are additive - they combine across inheritance chains and when defined multiple times for the same action:
 
 ```rb
 class BaseController < ApplicationController
@@ -238,9 +229,7 @@ class InvoicesController < BaseController
 end
 ```
 
-### Unrestricted Access
-
-Omit roles to allow unrestricted access:
+It's possible to omit roles to allow unrestricted access:
 
 ```rb
 class UnrestrictedController < ApplicationController
@@ -260,64 +249,78 @@ class MixedController < ApplicationController
 end
 ```
 
-### Custom Unauthorized Handling
+## Dynamic Authorization Rules
 
-Override `when_unauthorized` method to customize unauthorized access behavior:
+For more complex scenarios, Rabarber supports dynamic authorization rules:
 
 ```rb
-class ApplicationController < ActionController::Base
-  include Rabarber::Authorization
+class OrdersController < ApplicationController
+  grant_access roles: :manager, unless: -> { current_user.suspended? }
 
-  with_authorization
+  grant_access action: :show, roles: :client, if: :user_company_matches_order?
+  def show
+    # ...
+  end
 
   private
 
-  def when_unauthorized
-    head :not_found # Custom behavior to hide existence of protected resources
+  def user_company_matches_order?
+    current_user.company == Order.find(params[:id]).company
   end
 end
 ```
 
-By default, when unauthorized, Rabarber will redirect back (HTML format) or return 403 (other formats).
-
-## Dynamic Rules
+You can pass a dynamic rule as an `if` or `unless` argument, which can be a symbol or a proc. Symbols refer to instance methods, and procs are evaluated in the controller at request time.
 
-Add conditional logic to authorization rules:
+Dynamic rules can also be used without roles at all, allowing you to define custom logic or even delegate to custom policy objects:
 
 ```rb
-class OrdersController < ApplicationController
-  # Method-based conditions
-  grant_access roles: :manager, if: :company_manager?, unless: :suspended?
-
-  # Proc-based conditions
-  grant_access action: :show, roles: :client, if: -> { current_user.company == Order.find(params[:id]).company }
-  def show
-    # Accessible to company managers unless suspended, and to clients if the client's company matches the order's company
+class InvoicesController < ApplicationController
+  grant_access action: :update, unless: -> { Date.current.on_weekend? }
+  def update
+    # ...
   end
 
-  # Dynamic-only rules (no roles required, can be used with custom policies)
-  grant_access action: :index, if: -> { OrdersPolicy.new(current_user).index? }
-  def index
-    # Accessible to company managers unless suspended, and to users based on custom policy logic
+  grant_access action: :destroy, if: :destroy_allowed?
+  def destroy
+    # ...
   end
 
   private
 
-  def company_manager?
-    current_user.manager_of?(Company.find(params[:company_id]))
+  def destroy_allowed?
+    InvoicePolicy.new(current_user).destroy?(Invoice.find(params[:id]))
   end
+end
+```
+
+## When Unauthorized
 
-  def suspended?
-    current_user.suspended?
+By default, when unauthorized, Rabarber will redirect back (HTML format) or return 403 (other formats). You can override `when_unauthorized` method to customize unauthorized access behavior:
+
+```rb
+class ApplicationController < ActionController::Base
+  include Rabarber::Authorization
+
+  with_authorization
+
+  private
+
+  def when_unauthorized
+    head :not_found # Custom behavior to hide existence of protected resources
   end
 end
 ```
 
-## Multi-tenancy / Context
+The `when_unauthorized` method can be overridden in any controller to provide controller-specific unauthorized access handling.
 
-All Rabarber methods accept a `context` parameter, allowing you to work with roles within specific scopes. By default, context is `nil`, meaning roles are global.
+## Context / Multi-tenancy
 
-### Contextual Role Assignment
+Rabarber supports multi-tenancy through its context feature. All Rabarber methods accept a `context` parameter, allowing you to work with roles within specific scopes. By default, context is `nil`, meaning roles are global. Context can also be an instance of an `ActiveRecord` model or a class.
+
+For example, in a project management app, you might want users to have different roles in different projects - someone could be an `owner` in one project but just a `member` in another.
+
+### Contextual Role Assignment and Queries
 
 ```rb
 # Assign roles within a specific model instance
@@ -335,7 +338,7 @@ user.has_role?(:admin, context: Project)
 user.revoke_roles(:owner, context: project)
 
 # Get user roles
-user.roles(context: Project)
+user.roles(context: project)
 
 # Get users with a role
 User.with_role(:member, context: project)
@@ -359,6 +362,8 @@ Rabarber.roles(context: project)
 
 ### Contextual Authorization
 
+In authorization rules, in addition to specifying context explicitly, you can also provide a proc or a symbol (similar to dynamic rules):
+
 ```rb
 class ProjectsController < ApplicationController
   grant_access roles: :admin, context: Project
@@ -383,11 +388,11 @@ class ProjectsController < ApplicationController
 end
 ```
 
-### Orphaned Context
+### Orphaned Contextual Roles
 
 When a context object is deleted from your database, its associated roles become orphaned and ignored by Rabarber.
 
-To clean up orphaned context roles, use:
+To clean up orphaned roles, use:
 
 ```rb
 Rabarber.prune
@@ -395,13 +400,13 @@ Rabarber.prune
 
 ### Context Migrations
 
-Handle context changes when models are renamed or removed. These are irreversible data migrations.
+When you rename or remove models used as contexts, you need to update Rabarber's stored context data accordingly. Use these irreversible data migrations:
 
 ```rb
 # Rename a context class (e.g., when you rename your Ticket model to Task)
 migrate_authorization_context!("Ticket", "Task")
 
-# Remove orphaned context data (e.g., when you delete the Ticket model entirely)
+# Remove context data (e.g., when you delete the Ticket model entirely)
 delete_authorization_context!("Ticket")
 ```
 

data/lib/rabarber/controllers/concerns/authorization.rb

@@ -61,7 +61,7 @@ module Rabarber
     end
 
     def when_unauthorized
-      request.format.html? ? redirect_back(fallback_location: root_path) : head(:forbidden)
+      request.format.html? ? redirect_back_or_to(root_path) : head(:forbidden)
     end
   end
 end

data/lib/rabarber/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rabarber
-  VERSION = "5.2.4"
+  VERSION = "5.2.5"
 end

data/rabarber.gemspec

@@ -6,18 +6,20 @@ Gem::Specification.new do |spec|
   spec.name = "rabarber"
   spec.version = Rabarber::VERSION
   spec.authors = ["enjaku4", "trafium"]
-  spec.email = ["enjaku4@icloud.com"]
+  spec.email = ["contact@brownbox.dev"]
   spec.homepage = "https://github.com/enjaku4/rabarber"
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
   spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
   spec.metadata["documentation_uri"] = "#{spec.homepage}/blob/main/README.md"
+  spec.metadata["mailing_list_uri"] = "#{spec.homepage}/discussions"
+  spec.metadata["funding_uri"] = "https://github.com/sponsors/enjaku4"
   spec.metadata["rubygems_mfa_required"] = "true"
   spec.summary = "Simple role-based authorization library for Ruby on Rails"
-  spec.description = "Rabarber provides role-based authorization for Ruby on Rails applications with support for multi-tenancy, dynamic rules, and clean controller-level access control that separates authorization from business logic"
+  spec.description = "Simple role-based authorization for Rails applications with multi-tenancy support"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.2", "< 3.5"
+  spec.required_ruby_version = ">= 3.2", "< 4.1"
 
   spec.files = [
     "rabarber.gemspec", "README.md", "CHANGELOG.md", "LICENSE.txt"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rabarber
 version: !ruby/object:Gem::Version
-  version: 5.2.4
+  version: 5.2.5
 platform: ruby
 authors:
 - enjaku4
@@ -58,11 +58,10 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.2'
-description: Rabarber provides role-based authorization for Ruby on Rails applications
-  with support for multi-tenancy, dynamic rules, and clean controller-level access
-  control that separates authorization from business logic
+description: Simple role-based authorization for Rails applications with multi-tenancy
+  support
 email:
-- enjaku4@icloud.com
+- contact@brownbox.dev
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -106,6 +105,8 @@ metadata:
   changelog_uri: https://github.com/enjaku4/rabarber/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/enjaku4/rabarber/issues
   documentation_uri: https://github.com/enjaku4/rabarber/blob/main/README.md
+  mailing_list_uri: https://github.com/enjaku4/rabarber/discussions
+  funding_uri: https://github.com/sponsors/enjaku4
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -117,7 +118,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.2'
   - - "<"
     - !ruby/object:Gem::Version
-      version: '3.5'
+      version: '4.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="