PermissionSettings - Changelog

PermissionSettings allows to dynamically set, retrieve and check permissions of your resource model. Under the hood it uses Rails Settings gem for storing settings in database. Main idea is to store permissions in yaml files that can be divided by resource models and roles. It alos allows to change permissions without restarting the application that gives you more flexibility in build a permissions system.

• 3.0.2

• Rails 6.1 or newer (including Rails 7.0)

Include the gem in your Gemfile and run bundle to install it:

gem 'permission_settings', '~> 0.1.0'

Generate and run the migration to create the settings table that is used to store the permissions:

rails g rails_settings:migration
rails db:migrate

You can configure the gem by calling PermissionSettings.configure method in an initializer:

# config/initializers/permission_settings.rb

PermissionSettings.configure do |config|
  config.permissions_dir_path = 'config/permissions'
  config.role_access_method = :role
end

• permissions_dir_path - configuration option for setting path to permissions directory
• role_access_method - configuration option for setting method name to access role of the resource instance

You can create different yaml files for different resource models to keep permissions separated. by default it looks for yaml files in config/permissions directory.

Gem will load permissions from yaml files into database on application start.

The permissions file should be a yaml file and should be the same as the name of the resource model.

For example, if you have a User model, you can create a user.yml file in config/permissions directory with the following structure:

# config/permissions/person.yml

admin:
  notifications:
    read: true
    create: true
    edit: true
    delete: true

manager:
  notifications:
    read: true
    create: false
    edit: false
    delete: false

In this file we should divided permissions into roles. If not following this structure gem won't find permissions that are defined for a specific role of that calling instance. If you experience a PersistentSettings::NotFoundError error, please check if you have defined permissions for that role inside the permissions file of resource model.

To connect permissions to the resource model you need just to include PersmissionSettings module in the model class:

Calling model:

class User < ApplicationRecord
  include PermissionSettings
end

Resource model:

class Person < ApplicationRecord
  include PermissionSettings
end

In order to check permissions of the resource instance you need to pass it as a named argument resource to the #can? method.

Take into account that the resource model should have a role field or method that returns a role name of the calling instance or you can configure the gem to use another method name by setting role_access_method configuration option.

You can check permissions of the resource instance by calling #can? method:

user = User.first # => #<User id: 1, name: "John", role: "manager">
person = Person.last # => #<Person id: 2, name: "Jane", role: "client">
user.can?(:read, :notifications, resource: person) # => true

Method can? accepts 2 arguments:

• *permission_keys - this keys will be used to find permissions in the settings. It can be a string or an array of strings. Required argument.
• *resource - Named argument resource. Instance towards which the permissions will be checked. Required argument.

You can also access permissions of the resource or calling instance by calling #settings method:

person = Person.last # => #<Person id: 2, name: "Jane", role: "client">
person.permissions[:admin][:notifications][:read] # => false

More about settings you can read in Rails Settings gem documentation.

You can override default settings by calling #has_settings method in the resource model class:

custom_permissions = {
  admin: {
    notifications: {
      read: false,
      create: false,
      edit: false,
      delete: false
    }
  }
}
admin = User.first # => #<User id: 1, name: "John", role: "admin">
person = Person.last # => #<User id: 2, name: "Jane", role: "client">

admin.can?(:read, :notifications, resource: person) # => true

person.settings(PermissionSettings.configuration.scope_name).update(custom_permissions)

admin.can?(:read, :notifications, resource: person) # => false

If you will unset your custom settings, default settings will be used:

custom_permissions = {
  admin: {
    notifications: {
      read: false,
      create: false,
      edit: false,
      delete: false
    }
  }
}

admin = User.first # => #<User id: 1, name: "John", role: "admin">
person = Person.last # => #<User id: 2, name: "Jane", role: "client">

policy_scope = PermissionSettings.configuration.scope_name(User)
person.settings(policy_scope).update(custom_permissions)

admin.can?(:read, :notifications, resource: person) # => false

person.settings(policy_scope).update({ admin: { notifications: nil } })

admin.can?(:read, :notifications, resource: person) # => true

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at Permission Settings. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the PermissionSettings project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.