### Local Development Setup and Commands

Source: https://github.com/brownboxdev/rabarber/blob/main/CONTRIBUTING.md

Provides essential commands for setting up and interacting with the Rabarber project locally. This includes installing dependencies, running the console, executing tests, and performing linting.

```shell
bin/setup
# Installs development dependencies.
```

```shell
bin/console
# Starts the developer console.
```

```shell
bin/rspec
# Runs the project tests.
```

```shell
bin/rubocop
# Runs the project linter.
```

--------------------------------

### Installation

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Instructions for adding the Rabarber gem to your Rails project and generating necessary migrations for role storage.

```ruby
gem "rabarber"
```

```shell
bundle install
```

```shell
# For standard integer IDs
rails generate rabarber:roles users

# For UUID primary keys
rails generate rabarber:roles users --uuid
```

```shell
rails db:migrate
```

--------------------------------

### Controller Authorization Setup

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Demonstrates how to include the Rabarber authorization module in controllers and enable authorization either globally for all actions or selectively for specific actions.

```ruby
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
end
```

--------------------------------

### Contextual Authorization in Controllers

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Demonstrates how to apply authorization rules with contexts directly in controllers. This includes using class-based contexts, instance-based contexts via methods, and instance-based contexts via procs.

```ruby
class ProjectsController < ApplicationController
  # Class-based context
  grant_access roles: :admin, context: Project

  # Instance-based context (method)
  grant_access action: :show, roles: :member, context: :current_project
  def show
    # Accessible to Project admin and members of the current project
  end

  # Instance-based context (proc)
  grant_access action: :update, roles: :owner, context: -> { Project.find(params[:id]) }
  def update
    # Accessible to Project admin and owner of the current project
  end

  private

  def current_project
    @current_project ||= Project.find(params[:id])
  end
end
```

--------------------------------

### Include ApplicationHelper with Rabarber Helpers

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

This snippet shows how to include the Rabarber::Helpers module within your ApplicationHelper to make its methods available in your Rails views.

```ruby
module ApplicationHelper
  include Rabarber::Helpers
end
```

--------------------------------

### Dynamic Authorization Rules with Conditions

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Illustrates how to add conditional logic to authorization rules using `if` and `unless` options with methods or procs. This allows for more granular and dynamic access control based on application state.

```ruby
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_id == Order.find(params[:id]).company_id }
  def show
    # Accessible to company managers unless suspended, and to clients if the client's company matches the order's company
  end

  # Dynamic-only rules (no roles required, can be used with custom policies)
  grant_access action: :index, if: -> { OrdersPolicy.new(current_user).can_access?(:index) }
  def index
    # Accessible to company managers unless suspended, and to users based on custom policy logic
  end

  private

  def company_manager?
    current_user.manager_of?(Company.find(params[:company_id]))
  end

  def suspended?
    current_user.suspended?
  end
end
```

--------------------------------

### Contextual Role Assignment and Management

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Details how to manage roles within specific contexts (e.g., model instances or classes) using the `context` parameter. This is crucial for multi-tenant applications where roles might differ per tenant or resource.

```ruby
# Assign roles within a specific model instance
user.assign_roles(:owner, context: project)
user.assign_roles(:member, context: project)

# Assign roles within a model class (e.g., project admin)
user.assign_roles(:admin, context: Project)

# Check contextual roles
user.has_role?(:owner, context: project)
user.has_role?(:admin, context: Project)

# Revoke roles within a specific context
user.revoke_roles(:owner, context: project)

# Get roles within context
user.roles(context: project)

# Create a new role within a specific context
Rabarber::Role.add(:admin, context: Project)

# Rename a role within a specific context
Rabarber::Role.rename(:admin, :owner, context: Project)

# Remove a role within a specific context
Rabarber::Role.remove(:admin, context: project)

# Get roles within context
Rabarber::Role.names(context: Project)
```

--------------------------------

### Additive Authorization Rules

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Demonstrates how Rabarber's `grant_access` rules are additive across inheritance chains and for the same actions. Admins have broad access, while specific roles can be granted to controllers or actions.

```ruby
class BaseController < ApplicationController
  grant_access roles: :admin # Admin can access everything
end

class InvoicesController < BaseController
  grant_access roles: :accountant # Accountant can also access InvoicesController (along with admin)

  grant_access action: :index, roles: :manager
  grant_access action: :index, roles: :supervisor
  def index
    # Index is accessible to admin, accountant, manager, and supervisor
  end
end
```

--------------------------------

### Configuration

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

How to configure Rabarber settings in an initializer, including enabling caching, specifying the current user method, and setting the user model name. Also shows how to manually clear the role cache.

```ruby
Rabarber.configure do |config|
  config.cache_enabled = true                 # Enable role caching (default: true)
  config.current_user_method = :current_user  # Method to access current user (default: :current_user)
  config.user_model_name = "User"             # User model name (default: "User")
end
```

```ruby
Rabarber::Cache.clear
```

--------------------------------

### User Role Queries

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Methods to check if a user possesses specific roles and to retrieve the user's assigned roles, including options for grouping roles by context.

```ruby
# Check if user has any of the specified roles
user.has_role?(:accountant, :manager)

# Get user's roles
user.roles

# Get all roles grouped by context
user.all_roles
```

--------------------------------

### Controller Authorization Rules

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Shows how to define access rules using `grant_access` for controller-wide or action-specific authorization based on user roles.

```ruby
class TicketsController < ApplicationController
  # Controller-wide access
  grant_access roles: :admin

  # Action-specific access
  grant_access action: :index, roles: [:manager, :support]
  def index
    # Accessible to admin, manager, and support roles
  end
end
```

--------------------------------

### Controller Authorization Skipping

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Illustrates how to selectively skip authorization for certain actions within a controller while maintaining authorization for others.

```ruby
class TicketsController < ApplicationController
  skip_authorization except: [:create, :update, :destroy]
end
```

--------------------------------

### Unrestricted and Mixed Access Control

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Shows how to grant unrestricted access by omitting roles in `grant_access`. It also illustrates a mixed approach where some actions are unrestricted while others are role-specific.

```ruby
class UnrestrictedController < ApplicationController
  grant_access # Allow all users
end

class MixedController < ApplicationController
  grant_access action: :index # Unrestricted index action
  def index
    # Accessible to all users
  end

  grant_access action: :show, roles: :member # Restricted show action
  def show
    # Accessible to members only
  end
end
```

--------------------------------

### Conditional Rendering with Rabarber View Helpers

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Demonstrates how to use Rabarber's `visible_to` and `hidden_from` helpers for conditional rendering in ERB templates. These helpers allow you to control the visibility of content based on user roles and specific contexts.

```erb
<%= visible_to(:admin, :manager) do %>
  <div class="admin-panel">
    <!-- Admin/Manager content -->
  </div>
<% end %>

<%= hidden_from(:guest) do %>
  <div class="member-content">
    <!-- Content hidden from guests -->
  </div>
<% end %>

<%= visible_to(:owner, context: @project) do %>
  <div class="project-owner-panel">
    <!-- Content visible to project owners -->
  </div>
<% end %>
```

--------------------------------

### Context Migrations for Renaming or Deleting Models

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Provides utility methods for managing authorization contexts when models are renamed or deleted. `migrate_authorization_context!` renames contexts, while `delete_authorization_context!` removes orphaned context data.

```ruby
# 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)
delete_authorization_context!("Ticket")
```

--------------------------------

### Direct Role Operations

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Provides methods for managing roles directly, including adding, renaming, and removing roles. It also allows listing available roles and retrieving users assigned to a specific role, with options for forcing operations.

```ruby
# Create a new role
Rabarber::Role.add(:admin)

# Rename a role
Rabarber::Role.rename(:admin, :administrator)
Rabarber::Role.rename(:admin, :administrator, force: true) # Force if role is assigned to users

# Remove a role
Rabarber::Role.remove(:admin)
Rabarber::Role.remove(:admin, force: true) # Force if role is assigned to users

# List available roles
Rabarber::Role.names
Rabarber::Role.all_names # All roles grouped by context

# Get users assigned to a role
Rabarber::Role.assignees(:admin)
```

--------------------------------

### Custom Unauthorized Handling

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Explains how to customize the behavior when a user is unauthorized by overriding the `when_unauthorized` method in `ApplicationController`. The default behavior returns a 403 status or redirects.

```ruby
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
```

--------------------------------

### User Role Assignment

Source: https://github.com/brownboxdev/rabarber/blob/main/README.md

Methods for assigning and revoking roles for a user. Supports assigning existing roles only and revoking specific or all roles.

```ruby
# Assign roles (creates roles if they don't exist)
user.assign_roles(:accountant, :manager)

# Assign only existing roles
user.assign_roles(:accountant, :manager, create_new: false)

# Revoke specific roles
user.revoke_roles(:accountant, :manager)

# Revoke all roles
user.revoke_all_roles
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.