rabarber 5.2.3 → 5.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58580c8850cc6cde86318dee64ffcf28bf9daea4ced15eddaf8ff6e0148670bc
-  data.tar.gz: 6bd2d216d86d2c30d650cb190f7da17948b693bb9e0f7acd8df0cab2dfdae8ae
+  metadata.gz: 23cc4a1c2e65a3b450653b65df49633601756ada11844173b0c6314c41067ca9
+  data.tar.gz: 95153a3172c58bf636cb4d17981ba70336a292368f6bac26c2b6a107c4fcbaaa
 SHA512:
-  metadata.gz: '085794b488e723adbc08a8b0ec13005cd4352612b452df86ee85364ef3cdbe76288cc0f77d088844b6843134119048d26eb256c8999a0c86cdc0a9505aa5a4eb'
-  data.tar.gz: 5c105b394e8984e8f3951c59e2a21b1c96508047a624fd86299ad6471d05d3e4bd6715363ecdf18d845fc6d788f569c7e4d5c6c41cec7cfb75eabaaf754f5d99
+  metadata.gz: 180407341e8e4e700fff624ab12de40d9aa66ed4e132e8ddc92c0c9cb4c010309194e7b37bc825a9a92a0e9baf64022a165788055ccba6b41e60aab8d040fc20
+  data.tar.gz: 882d08be5cab1db66d0056ef5e0ace724d2d8ce633cdf75af808d28980faeadbdf9e56c4362e3b7197a89b0de80925f77b2dafb12c5f6e44b1f21cb43be0730d

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## v5.2.5
+
+### Misc:
+
+- Added support for Ruby 4
+
+## v5.2.4
+
+### Misc:
+
+- Added support for Rails 8.1
+
 ## v5.2.3
 
 ### Bugs:
@@ -85,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,15 +5,13 @@
 [![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.
+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.
 
-**Key Features:**
+**Example of Usage:**
 
-- Role-based authorization
-- Controller-level access control
-- Multi-tenancy support through contextual roles
-- Dynamic authorization with conditional logic
-- View helpers for role-based content rendering
+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 this is how your controller might look with Rabarber:
 
@@ -23,25 +21,28 @@ class TicketsController < ApplicationController
 
   grant_access action: :index, roles: :manager
   def index
-    # Accessible to admin and manager roles
+    # ...
   end
 
   def destroy
-    # Accessible to admin role 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:**
@@ -64,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
@@ -82,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|
@@ -92,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
@@ -106,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
@@ -136,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
@@ -159,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
@@ -212,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
@@ -232,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
@@ -254,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.
+
+## Context / Multi-tenancy
 
-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.
+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.
 
-### Contextual Role Assignment
+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
@@ -329,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)
@@ -353,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
@@ -377,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
@@ -389,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.3"
+  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"
@@ -27,5 +29,5 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "dry-configurable", "~> 1.1"
   spec.add_dependency "dry-types", "~> 1.7"
-  spec.add_dependency "rails", ">= 7.1", "< 8.1"
+  spec.add_dependency "rails", ">= 7.1", "< 8.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rabarber
 version: !ruby/object:Gem::Version
-  version: 5.2.3
+  version: 5.2.5
 platform: ruby
 authors:
 - enjaku4
@@ -47,7 +47,7 @@ dependencies:
         version: '7.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: '8.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -57,12 +57,11 @@ dependencies:
         version: '7.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.1'
-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
+        version: '8.2'
+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:
   - - ">="