bullet_train-roles 0.1.0

data/bullet_train-roles.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "lib/bullet_train//roles/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "bullet_train-roles"
+  spec.version = Roles::VERSION
+  spec.authors = ["Prabin Poudel", "Andrew Culver"]
+  spec.email = %w[andrew.culver@gmail.com]
+
+  spec.summary = "Yaml-backed ApplicationHash for CanCan Roles"
+  spec.description = "Yaml-backed ApplicationHash for CanCan Roles"
+  spec.homepage = "https://github.com/bullet-train-co/bullet_train-roles"
+  spec.license = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.4.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/bullet-train-co/bullet_train-roles"
+  spec.metadata["changelog_uri"] = "https://github.com/bullet-train-co/bullet_train-roles/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "byebug", "~> 11.1.0"
+  spec.add_development_dependency "factory_bot_rails", "~> 6.2.0"
+  spec.add_development_dependency "knapsack_pro", "~> 3.1.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "pg", "~> 1.2.0"
+  spec.add_development_dependency "rails", "~> 7.0.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "standard", "~> 1.5.0"
+
+  spec.add_runtime_dependency "active_hash"
+  spec.add_runtime_dependency "activesupport"
+  spec.add_runtime_dependency "cancancan"
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/bullet_train/roles/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Roles
+  VERSION = "0.1.0"
+end

data/lib/bullet_train/roles.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "roles/version"
+
+require_relative "../models/role"
+require_relative "../roles/permit"
+require_relative "../roles/support"
+
+module Roles
+  class Error < StandardError; end
+end

data/lib/generators/bullet_train/roles/install/USAGE

@@ -0,0 +1,11 @@
+Description:
+  Install required configuration
+
+Example:
+    rails generate bullet_train:roles:install
+
+    This will:
+        create config/models/roles.yml
+        create migration file to add role_ids to top level model
+        add include Role::Support to top level model
+        add permit line to app/models/ability.rb

data/lib/generators/bullet_train/roles/install/install_generator.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "rails/generators"
+
+module BulletTrain
+  module Roles
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def add_roles_config_file
+        puts("Creating role.yml inside config/models with default roles\n")
+
+        copy_file "roles.yml", "config/models/roles.yml"
+
+        puts("Success 🎉🎉\n\n")
+      end
+
+      def configure_models
+        json_data_type_identifier = find_json_data_type_identifier
+
+        top_level_model = ask("Which model do you want to use as a top-level model that represents Membership? (Defaults to Membership)") || "Membership"
+
+        generate_migration_to_add_role_ids(top_level_model, json_data_type_identifier)
+
+        include_role_support_in_top_level_model(top_level_model)
+
+        associated_model = ask("Which model/association of #{top_level_model} do you consider to be the Team? (Default to Team)") || "Team"
+
+        # Asks for a model we can setup some default permissions for.
+        # TODO: follow back Andrew on question about this in Slack
+
+        add_permit_to_ability_model(top_level_model, associated_model)
+      end
+
+      private
+
+      def ask(question)
+        puts(question)
+
+        answer = gets.chomp
+
+        return if answer.blank?
+
+        answer
+      end
+
+      def db_adapter
+        allowed_adapter_types = %w[mysql sqlite postgresql]
+
+        adapter_name = ActiveRecord::Base.connection.adapter_name.downcase
+
+        if allowed_adapter_types.exclude?(adapter_name)
+          raise NotImplementedError, "'#{adapter_name}' is not supported!"
+        end
+
+        adapter_name
+      end
+
+      def find_json_data_type_identifier
+        adapter_name = db_adapter
+
+        case adapter_name
+        when "postgresql"
+          "jsonb"
+        else
+          "json"
+        end
+      end
+
+      def add_in_file(file_location, line_to_match, content_to_add)
+        update_file_content = []
+
+        file_lines = File.readlines(file_location)
+
+        file_lines.each do |line|
+          line_pattern = line_to_match
+          updated_line = line
+
+          if line.include?(line_pattern)
+            trimmed_line = line.tr("\n", "")
+
+            updated_line = "#{trimmed_line}#{content_to_add}"
+          end
+
+          update_file_content.push(updated_line)
+        end
+
+        File.write(file_location, update_file_content.join)
+      end
+
+      def add_default_value_to_migration(file_name, table_name)
+        file_location = Dir["db/migrate/*_#{file_name}.rb"].last
+        line_to_match = "add_column :#{table_name.downcase}, :role_ids"
+        content_to_add = ", default: []\n"
+
+        add_in_file(file_location, line_to_match, content_to_add)
+      end
+
+      def migration_file_exists?(file_name)
+        file_location = Dir["db/migrate/*_#{file_name}.rb"].last
+
+        file_location.present?
+      end
+
+      def file_already_exists(message)
+        puts(message)
+      end
+
+      def generate_migration_to_add_role_ids(top_level_model, json_data_type_identifier)
+        top_level_model_table_name = top_level_model.underscore.pluralize
+
+        migration_file_name = "add_role_ids_to_#{top_level_model_table_name}"
+
+        return file_already_exists("Migration file already exists!!\n\n") if migration_file_exists?(migration_file_name)
+
+        puts("Generating migration to add role_ids to #{top_level_model}")
+
+        generate "migration", "#{migration_file_name} role_ids:#{json_data_type_identifier}"
+
+        add_default_value_to_migration(migration_file_name, top_level_model_table_name)
+
+        puts("Success 🎉🎉\n\n")
+      end
+
+      def line_exists_in_file?(file_location, line_to_compare)
+        file_lines = File.readlines(file_location)
+
+        file_lines.join.include?(line_to_compare)
+      end
+
+      def line_already_exists(message)
+        puts(message)
+      end
+
+      def remove_new_lines_and_spaces(line)
+        line.tr("\n", "").strip
+      end
+
+      def include_role_support_in_top_level_model(model_name)
+        # converts 👇
+        # Membership to membership
+        # Admin::Membership to admin/membership
+        # TeamMember to team_member
+        file_location = "app/models/#{model_name.underscore}.rb"
+        line_to_match = "class #{model_name.classify} < ApplicationRecord"
+        content_to_add = "\n  include Roles::Support\n"
+
+        puts("Adding 'include Roles::Support' to #{model_name}\n\n")
+
+        if line_exists_in_file?(file_location, content_to_add)
+          message = "'#{remove_new_lines_and_spaces(content_to_add)}' already exists in #{model_name}!!\n\n"
+
+          return line_already_exists(message)
+        end
+
+        add_in_file(file_location, line_to_match, content_to_add)
+
+        puts("Success 🎉🎉\n\n")
+      end
+
+      def add_permit_to_ability_model(top_level_model, associated_model)
+        # TODO: need to make this more smart e.g.
+        # 1. should know what parameter is used for user e.g. def initialize(user)
+        # 2. what if code doesn't include "if user.present?", maybe we need to handle that, consult with Andrew
+        file_location = "app/models/ability.rb"
+        line_to_match = "if user.present?"
+        content_to_add = "\n      permit user, through: :#{top_level_model.downcase.pluralize}, parent: :#{associated_model.downcase}\n"
+
+        puts("Adding 'permit user, through: :#{top_level_model.downcase}, parent: :#{associated_model.downcase}' to #{associated_model}\n\n")
+
+        if line_exists_in_file?(file_location, content_to_add)
+          message = "#{remove_new_lines_and_spaces(content_to_add)} already exists in #{associated_model}!!\n\n"
+
+          return line_already_exists(message)
+        end
+
+        add_in_file(file_location, line_to_match, content_to_add)
+
+        puts("Success 🎉🎉\n\n")
+      end
+    end
+  end
+end

data/lib/generators/bullet_train/roles/install/templates/roles.yml

@@ -0,0 +1,15 @@
+default:
+  models:
+    -
+
+editor:
+  models:
+    -
+  manageable_roles:
+    - editor
+
+admin:
+  includes:
+    - editor
+  manageable_roles:
+    - admin

data/lib/models/role.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "active_hash"
+
+class RemovingLastTeamAdminException < RuntimeError; end
+
+class Role < ActiveYaml::Base
+  include ActiveYaml::Aliases
+  set_root_path "config/models"
+  set_filename "roles"
+
+  field :includes, default: []
+  field :models, default: []
+  field :manageable_roles, default: []
+
+  def self.admin
+    find_by_key("admin")
+  end
+
+  def self.default
+    find_by_key("default")
+  end
+
+  def self.includes(role_or_key)
+    role_key = role_or_key.is_a?(Role) ? role_or_key.key : role_or_key
+
+    role = Role.find_by_key(role_key)
+
+    return Role.all.select(&:assignable?) if role.default?
+
+    result = []
+
+    all.each do |role|
+      result << role if role.includes.include?(role_key)
+    end
+
+    result
+  end
+
+  def self.assignable
+    all.reject(&:default?)
+  end
+
+  def self.find(key)
+    all.find { |role| role.key == key }
+  end
+
+  # We don't want to ever use the automatically generated ids from ActiveYaml.  These are created based on the order of objects in the yml file
+  # so if someone ever changed the order of that file around, they would really mess up the user permissions. Instead, we're using the key attribute.
+  def id
+    key
+  end
+
+  def included_by
+    Role.includes(self)
+  end
+
+  # We need to search for memberships that have this role included directly OR any memberships that have this role _through_ it being included in another role they have
+  def key_plus_included_by_keys
+    # get direct parent roles
+    (included_by.map(&:key_plus_included_by_keys).flatten + [id]).uniq
+  end
+
+  def default?
+    key == "default"
+  end
+
+  def admin?
+    key == "admin"
+  end
+
+  def included_roles
+    default_roles = []
+
+    default_roles << Role.default unless default?
+
+    (default_roles + includes.map { |included_key| Role.find_by_key(included_key) }).uniq.compact
+  end
+
+  def manageable_by?(role_or_roles)
+    return true if default?
+
+    roles = role_or_roles.is_a?(Array) ? role_or_roles : [role_or_roles]
+
+    roles.each do |role|
+      return true if role.manageable_roles.include?(key)
+
+      role.included_roles.each do |included_role|
+        return true if manageable_by?([included_role])
+      end
+    end
+
+    false
+  end
+
+  def assignable?
+    !default?
+  end
+
+  def ability_generator(user, through, parent)
+    models.each do |model_name, _|
+      ag = AbilityGenerator.new(self, model_name, user, through, parent)
+      yield(ag)
+    end
+  end
+
+  # The only purpose of this class is to allow developers to do things like:
+  # Membership.first.roles << Role.admin
+  # Membership.first.roles.delete Role.admin
+  # It basically makes the role_ids column act like a Rails `has_many through` collection - this includes automatically saving changes when you add or remove from the array.
+  class Collection < Array
+    def initialize(model, ary)
+      @model = model
+
+      super(ary)
+    end
+
+    def <<(role)
+      return true if include?(role)
+
+      role_ids = @model.role_ids
+
+      role_ids << role.id
+
+      @model.update(role_ids: role_ids)
+    end
+
+    def delete(role)
+      @model.role_ids -= [role.key]
+
+      @model.save
+    end
+  end
+
+  class AbilityGenerator
+    attr_reader :model
+
+    def initialize(role, model_name, user, through, parent_name)
+      begin
+        @model = model_name.constantize
+      rescue NameError
+        raise "#{model_name} model is used in `config/models/roles.yml` for the #{role.key} role but is not defined in `app/models`."
+      end
+
+      @role = role
+      @ability_data = role.models[model_name]
+      @through = through
+      @parent = user.send(through).reflect_on_association(parent_name)&.klass
+      @parent_ids = user.parent_ids_for(@role, @through, parent_name) if @parent
+    end
+
+    def valid?
+      actions.present? && model.present? && condition.present?
+    end
+
+    def actions
+      return @actions if @actions
+
+      actions = (@ability_data["actions"] if @ability_data.is_a?(Hash)) || @ability_data
+
+      actions = [actions] unless actions.is_a?(Array)
+
+      @actions = actions.map!(&:to_sym)
+    end
+
+    def possible_parent_associations
+      ary = @parent.to_s.split("::").map(&:underscore)
+
+      possibilities = []
+      current = nil
+
+      until ary.empty?
+        current = "#{ary.pop}#{"_" unless current.nil?}#{current}"
+        possibilities << current
+      end
+
+      possibilities.map(&:to_sym)
+    end
+
+    def condition
+      return @condition if @condition
+
+      return nil unless @parent_ids
+
+      if @model == @parent
+        return @condition = {id: @parent_ids}
+      end
+
+      parent_association = possible_parent_associations.find { |association| @model.method_defined? association }
+
+      return nil unless parent_association.present?
+
+      @condition = {parent_association => {id: @parent_ids}}
+    end
+  end
+end

data/lib/roles/permit.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Roles
+  module Permit
+    def permit(user, through:, parent:, debug: false)
+      # Without this, you need to restart the server each time you make changes to the config/models/role.yml file
+      Role.reload(true) if Rails.env.development?
+
+      # When changing permissions during development, you may also want to do this on each request:
+      # User.update_all ability_cache: nil if Rails.env.development?
+
+      output = []
+      added_roles = Set.new
+
+      user.send(through).map(&:roles).flatten.uniq.each do |role|
+        unless added_roles.include?(role)
+          output << "########### ROLE: #{role.key}"
+
+          output += add_abilities_for(role, user, through, parent)
+
+          added_roles << role
+        end
+
+        role.included_roles.each do |included_role|
+          unless added_roles.include?(included_role)
+            output << "############# INCLUDED ROLE: #{included_role.key}"
+
+            output += add_abilities_for(included_role, user, through, parent)
+          end
+        end
+      end
+
+      if debug
+        puts "###########################"
+        puts "Auto generated `ability.rb` content:"
+        puts output
+        puts "############################"
+      end
+    end
+
+    def add_abilities_for(role, user, through, parent)
+      output = []
+
+      role.ability_generator(user, through, parent) do |ag|
+        if ag.valid?
+          output << "can #{ag.actions}, #{ag.model}, #{ag.condition}"
+
+          can(ag.actions, ag.model, ag.condition)
+        else
+          output << "# #{ag.model} does not respond to #{parent} so we're not going to add an ability for the #{through} context"
+        end
+      end
+
+      output
+    end
+  end
+end

data/lib/roles/support.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "active_support"
+
+module Roles
+  module Support
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def roles_only(*roles)
+        @allowed_roles = roles.map(&:to_sym)
+      end
+
+      def assignable_roles
+        return Role.assignable if @allowed_roles.nil?
+
+        Role.assignable.select { |role| @allowed_roles.include?(role.key.to_sym) }
+      end
+
+      # Note default_role is an ActiveRecord core class method so we need to use something else here
+      def default_roles
+        default_role = Role.default
+
+        return [default_role] if @allowed_roles.nil?
+
+        @allowed_roles.include?(default_role.key.to_sym) ? [default_role] : []
+      end
+    end
+
+    included do
+      validate :validate_roles
+
+      # This query will return records that have a role "included" in a different role they have.
+      # For example, if you do with_roles(editor) it will return admin users if the admin role includes the editor role
+      scope :with_roles, ->(roles) { where("#{table_name}.role_ids ?| array[:keys]", keys: roles.map(&:key_plus_included_by_keys).flatten.uniq.map(&:to_s)) }
+
+      # This query will return roles that include the given role.  See with_roles above for details
+      scope :with_role, ->(role) { role.nil? ? all : with_roles([role]) }
+      scope :viewers, -> { where("#{table_name}.role_ids = ?", [].to_json) }
+      scope :editors, -> { with_role(Role.find_by_key("editor")) }
+      scope :admins, -> { with_role(Role.find_by_key("admin")) }
+
+      after_save :invalidate_cache
+      after_destroy :invalidate_cache
+
+      def validate_roles
+        self.role_ids = role_ids.select(&:present?)
+
+        return if @allowed_roles.nil?
+
+        roles.each do |role|
+          errors.add(:roles, :invalid) unless @allowed_roles.include?(role.key.to_sym)
+        end
+      end
+
+      def roles
+        Role::Collection.new(self, (self.class.default_roles + roles_without_defaults).compact.uniq)
+      end
+
+      def roles=(roles)
+        self.role_ids = roles.map(&:key)
+      end
+
+      def assignable_roles
+        roles.select(&:assignable?)
+      end
+
+      def roles_without_defaults
+        role_ids.map { |role_id| Role.find(role_id) }
+      end
+
+      def manageable_roles
+        roles.map(&:manageable_roles).flatten.uniq.map { |role_key| Role.find_by_key(role_key) }
+      end
+
+      def can_manage_role?(role)
+        manageable_roles.include?(role)
+      end
+
+      def admin?
+        roles.select(&:admin?).any?
+      end
+
+      def invalidate_cache
+        user&.invalidate_ability_cache
+      end
+    end
+  end
+end