role_fu 0.4.0 → 0.6.0

data/lib/generators/role_fu/upgrade_generator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record"
+
+module RoleFu
+  module Generators
+    # Run after bumping the role_fu gem version. Does not track "which
+    # version you upgraded from" - there's nowhere reliable to read that from
+    # (Gemfile.lock only ever has the current version). Instead it inspects
+    # the actual schema/config already installed and generates whatever is
+    # missing, so it's safe to run regardless of how many versions you skipped,
+    # and safe to run again if nothing changed.
+    class UpgradeGenerator < ActiveRecord::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :name, type: :string, default: "upgrade"
+
+      def self.banner
+        "bin/rails generate role_fu:upgrade\n\n" \
+        "Detects which optional role_fu columns/config are missing for your\n" \
+        "installed models and generates the migrations needed to catch up."
+      end
+
+      desc ""
+
+      def run_upgrade_checks
+        applied = upgrade_checks.count { |check| send(check) }
+
+        say "role_fu is already up to date - nothing to generate.", :green if applied.zero?
+      end
+
+      private
+
+      # Each check returns true when it generated something or has a warning
+      # to report. Add new entries here as future optional columns/config land.
+      def upgrade_checks
+        [:check_permissions_field, :check_denormalized_role_names]
+      end
+
+      def check_permissions_field
+        return false unless table_exists?(:permissions)
+        return false if column_exists?(:permissions, :field)
+
+        say "Adding missing 'field' column to permissions (see README: Field-level granularity)", :yellow
+        migration_template "upgrade_permissions_field_migration.rb.erb", "db/migrate/role_fu_add_field_to_permissions.rb"
+        true
+      end
+
+      # Not auto-fixed: blindly renaming could collide two existing roles
+      # (e.g. "Admin" and "admin" both already present with their own
+      # role_assignments) into one, which needs a human to decide how to
+      # merge rather than a migration silently doing it.
+      def check_denormalized_role_names
+        role_class = RoleFu.configuration.role_class_name.safe_constantize
+        return false unless role_class&.table_exists?
+
+        denormalized = role_class.pluck(:name).any? { |name| name != RoleFu.normalize_role_name(name) }
+        return false unless denormalized
+
+        say "Found role names that don't match RoleFu's normalized format (e.g. \"Admin\" vs \"admin\").", :yellow
+        say "Not fixed automatically - two differently-cased roles may already coexist and need a human merge decision.", :yellow
+        say "Review, then backfill e.g.: UPDATE #{role_class.table_name} SET name = LOWER(name) WHERE name != LOWER(name)", :yellow
+        true
+      end
+
+      def table_exists?(name)
+        ActiveRecord::Base.connection.table_exists?(name.to_s)
+      rescue
+        false
+      end
+
+      def column_exists?(table, column)
+        ActiveRecord::Base.connection.column_exists?(table.to_s, column)
+      rescue
+        false
+      end
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]" if Rails::VERSION::MAJOR >= 5
+      end
+    end
+  end
+end

data/lib/role_fu/ability.rb

@@ -4,20 +4,55 @@ module RoleFu
   module Ability
     extend ActiveSupport::Concern
 
-    def role_fu_can?(action, _resource = nil)
-      role_fu_permissions.include?(action.to_s)
+    # @param action [String, Symbol] e.g. "posts.update"
+    # @param field [String, Symbol, nil] restrict the check to a single attribute
+    #   (e.g. :description). A permission granted with field: nil is a wildcard
+    #   that satisfies any field-scoped check for the same action.
+    def role_fu_can?(action, _resource = nil, field: nil)
+      fields = role_fu_permission_fields(action)
+      return false if fields.nil?
+
+      field.nil? || fields.include?(nil) || fields.include?(field.to_s)
+    end
+
+    # Fields explicitly granted for `action`.
+    # Returns :all when the action was granted without a field restriction,
+    # [] when the action isn't granted at all, or the explicit field list otherwise.
+    def role_fu_permitted_fields(action)
+      fields = role_fu_permission_fields(action)
+      return [] if fields.nil?
+      return :all if fields.include?(nil)
+
+      fields.to_a
     end
 
     def role_fu_permissions
+      role_fu_permissions_index.keys.to_set
+    end
+
+    private
+
+    def role_fu_permission_fields(action)
+      role_fu_permissions_index[action.to_s]
+    end
+
+    def role_fu_permissions_index
       return @_role_fu_permissions if defined?(@_role_fu_permissions) && @_role_fu_permissions
 
       permission_class = "Permission".safe_constantize
-      return Set.new unless permission_class
+      return (@_role_fu_permissions = {}) unless permission_class
 
       scope = roles
       scope = filter_expired(scope) if respond_to?(:filter_expired, true)
 
-      @_role_fu_permissions = scope.joins(:permissions).pluck("permissions.action").map(&:to_s).to_set
+      has_field_column = permission_class.column_names.include?("field")
+      columns = has_field_column ? %w[permissions.action permissions.field] : %w[permissions.action]
+      rows = scope.joins(:permissions).pluck(*columns)
+
+      @_role_fu_permissions = rows.each_with_object({}) do |row, index|
+        action, field = has_field_column ? row : [row, nil]
+        (index[action.to_s] ||= Set.new) << field
+      end
     end
   end
 end

data/lib/role_fu/adapters/cancancan.rb

@@ -13,11 +13,20 @@ module RoleFu
 
           if parts.size == 2
             subject_name, rule = parts
-            begin
-              subject_class = subject_name.classify.constantize
-              can rule.to_sym, subject_class
+            subject_class = begin
+              subject_name.classify.constantize
             rescue NameError
-              can rule.to_sym, subject_name.to_sym
+              subject_name.to_sym
+            end
+
+            # Field-scoped permissions map onto CanCanCan's own attribute
+            # restriction (`can :update, Post, :title`) instead of role_fu
+            # re-implementing attribute authorization itself.
+            fields = user.role_fu_permitted_fields(action)
+            if fields == :all
+              can rule.to_sym, subject_class
+            else
+              can rule.to_sym, subject_class, *fields.map(&:to_sym)
             end
           else
             can action.to_sym, :all

data/lib/role_fu/authorizable.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RoleFu
+  # Raised by RoleFu::Authorizable guard methods. Rescue it yourself
+  # (e.g. `rescue_from RoleFu::AccessDenied` in ApplicationController) —
+  # role_fu does not register a rescue handler on your behalf.
+  class AccessDenied < RoleFu::Error
+    def initialize(message = "You are not authorized to perform this action.")
+      super
+    end
+  end
+
+  # Minimal, framework-agnostic authorization guard for apps that don't want
+  # to pull in a full authorization gem just to raise on a missing role.
+  #
+  # This is deliberately NOT an `allow`/`deny` DSL or a rule-resolution
+  # engine — for anything beyond "raise unless this check passes", reach for
+  # the Pundit or CanCanCan adapters instead. Mixing this concern into a
+  # controller (or any object that responds to `current_user`, or overrides
+  # `role_fu_current_user`) just gives you two guard-clause helpers built on
+  # top of the `has_role?` / `role_fu_can?` methods you already have.
+  module Authorizable
+    extend ActiveSupport::Concern
+
+    # Override this if the current user isn't exposed via `current_user`
+    # (e.g. in a job or service object).
+    def role_fu_current_user
+      current_user if respond_to?(:current_user)
+    end
+
+    def role_fu_authorize!(role_name, resource = nil)
+      user = role_fu_current_user
+      raise RoleFu::AccessDenied unless user&.respond_to?(:has_role?) && user.has_role?(role_name, resource)
+
+      true
+    end
+
+    def role_fu_can!(action, resource = nil, field: nil)
+      user = role_fu_current_user
+      raise RoleFu::AccessDenied unless user&.respond_to?(:role_fu_can?) && user.role_fu_can?(action, resource, field: field)
+
+      true
+    end
+  end
+end

data/lib/role_fu/role.rb

@@ -15,7 +15,15 @@ module RoleFu
 
       belongs_to :resource, polymorphic: true, optional: true
 
+      before_validation :normalize_role_fu_name
+
       validates :name, presence: true, uniqueness: {scope: [:resource_type, :resource_id]}
     end
+
+    private
+
+    def normalize_role_fu_name
+      self.name = RoleFu.normalize_role_name(name) if name.present?
+    end
   end
 end

data/lib/role_fu/roleable.rb

@@ -24,7 +24,7 @@ module RoleFu
         role_table = RoleFu.role_class.table_name
         assignment_table = RoleFu.role_assignment_class.table_name
 
-        query = joins(:roles).where(role_table => {name: role_name.to_s})
+        query = joins(:roles).where(role_table => {name: RoleFu.normalize_role_name(role_name)})
 
         if RoleFu.role_assignment_class.column_names.include?("expires_at")
           query = query.where("#{assignment_table}.expires_at IS NULL OR #{assignment_table}.expires_at > ?", Time.current)
@@ -136,7 +136,7 @@ module RoleFu
       return false if role_name.nil?
 
       if resource == :any
-        filter_expired(roles.where(name: role_name.to_s)).exists?
+        filter_expired(roles.where(name: RoleFu.normalize_role_name(role_name))).exists?
       else
         return true if filter_expired(find_roles(role_name, resource)).any?
 
@@ -157,7 +157,7 @@ module RoleFu
     end
 
     def has_cached_role?(role_name, resource = nil)
-      role_name = role_name.to_s
+      role_name = RoleFu.normalize_role_name(role_name)
       roles.to_a.any? do |role|
         next false unless role.name == role_name
 
@@ -241,14 +241,14 @@ module RoleFu
 
     def find_or_create_role(role_name, resource)
       RoleFu.role_class.find_or_create_by(
-        name: role_name.to_s,
+        name: RoleFu.normalize_role_name(role_name),
         resource_type: resource_type_for(resource),
         resource_id: resource_id_for(resource)
       )
     end
 
     def find_roles(role_name, resource)
-      query = roles.where(name: role_name.to_s)
+      query = roles.where(name: RoleFu.normalize_role_name(role_name))
 
       if resource.is_a?(Class)
         query.where(resource_type: resource.to_s, resource_id: nil)

data/lib/role_fu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RoleFu
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

data/lib/role_fu.rb

@@ -3,6 +3,10 @@
 require "active_support/concern"
 require "active_support/core_ext/string/inflections"
 
+module RoleFu
+  class Error < StandardError; end
+end
+
 require_relative "role_fu/version"
 require_relative "role_fu/configuration"
 require_relative "role_fu/role"
@@ -11,14 +15,13 @@ require_relative "role_fu/roleable"
 require_relative "role_fu/resourceable"
 require_relative "role_fu/permission"
 require_relative "role_fu/ability"
+require_relative "role_fu/authorizable"
 require_relative "role_fu/cleanup"
 require_relative "role_fu/adapters/cancancan"
 require_relative "role_fu/adapters/pundit"
 require_relative "role_fu/railtie" if defined?(Rails)
 
 module RoleFu
-  class Error < StandardError; end
-
   class << self
     def with_actor(actor)
       Thread.current[:role_fu_actor] = actor
@@ -30,5 +33,15 @@ module RoleFu
     def current_actor
       Thread.current[:role_fu_actor]
     end
+
+    # Canonicalizes a role name so that "Admin", "admin", "Admin User" and
+    # "admin-user" all resolve to the same underlying Role row.
+    # Note: does NOT singularize (unlike acl9) — that silently mangles
+    # ordinary business terms (e.g. "sales" -> "sale").
+    def normalize_role_name(name)
+      return nil if name.nil?
+
+      name.to_s.strip.gsub(/[\s-]+/, "_").underscore
+    end
   end
 end

data/mise.toml

@@ -0,0 +1,14 @@
+[tools]
+ruby = "4.0.6"
+
+[tasks.test]
+description = "Run the RSpec suite"
+run = "bundle exec rake spec"
+
+[tasks.lint]
+description = "Run RuboCop"
+run = "bundle exec rubocop"
+
+[tasks.release]
+description = "Build and publish the gem (rake release)"
+run = "bundle exec rake release"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: role_fu
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Alexey Poimtsev
@@ -116,6 +116,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".ruby-version"
 - Appraisals
 - CHANGELOG.md
 - LICENSE.txt
@@ -142,10 +143,13 @@ files:
 - lib/generators/role_fu/templates/role.rb.erb
 - lib/generators/role_fu/templates/role_assignment.rb.erb
 - lib/generators/role_fu/templates/role_fu.rb
+- lib/generators/role_fu/templates/upgrade_permissions_field_migration.rb.erb
+- lib/generators/role_fu/upgrade_generator.rb
 - lib/role_fu.rb
 - lib/role_fu/ability.rb
 - lib/role_fu/adapters/cancancan.rb
 - lib/role_fu/adapters/pundit.rb
+- lib/role_fu/authorizable.rb
 - lib/role_fu/cleanup.rb
 - lib/role_fu/configuration.rb
 - lib/role_fu/permission.rb
@@ -156,6 +160,7 @@ files:
 - lib/role_fu/roleable.rb
 - lib/role_fu/version.rb
 - lib/tasks/role_fu.rake
+- mise.toml
 - sig/role_fu.rbs
 homepage: https://github.com/alec-c4/role_fu
 licenses:
@@ -164,6 +169,17 @@ metadata:
   homepage_uri: https://github.com/alec-c4/role_fu
   source_code_uri: https://github.com/alec-c4/role_fu
   changelog_uri: https://github.com/alec-c4/role_fu/blob/main/CHANGELOG.md
+post_install_message: |
+  Thanks for installing role_fu 0.6.0!
+
+  Upgrading from an older role_fu? Run this to pick up any missing
+  schema/data changes (it inspects your app, so it's a no-op if there's
+  nothing to do):
+
+    rails generate role_fu:upgrade
+    rails db:migrate
+
+  Full changelog: https://github.com/alec-c4/role_fu/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -171,14 +187,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A modern role management gem for Rails, replacing rolify.
 test_files: []