permisi 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50d92f00f694bb0b93a36125736bbd3afae15446c6fe5c71e0a83027a136c5e8
-  data.tar.gz: f214d63982175a708e99f7c9238a778b10ec4b599b8baed0dbf09e62a3ad0ae4
+  metadata.gz: 6f5921c398a6ce7ae469c520df94b9fa41c9ee9e43008acfad87ad45c2252000
+  data.tar.gz: 467511ff2872e5a4b42cf01b18b4578ac3c8e45b42b4dba7ce2354ff65303d81
 SHA512:
-  metadata.gz: ea1cedd52afd42383027297028974947aa338eff64d0bb12daee7f3e73663dc054c983f792f6ec8a917f2273745cbb212ea17d12271d11de003a509f53111803
-  data.tar.gz: 395586b6b62fdedfe3c9ffc0ea824868cf27d76922af4a7501f161eabd06561c9d44d251a114685552e4d5a37c50923b721621d212ef3d956f98a025e93f4649
+  metadata.gz: 7740edf97adf3444c8051b6d126f148851467aad17c80b73ab43ff505a8201ba5eedb0c681ce85cadcac354e377a92a888b4f19b51a3b72ab353bdc3ec070ced
+  data.tar.gz: 491438a44e151e82cadf211a2ffd8d6cffd0fab84e321553a0089c10f29f95acc5463ca2acaa9ced5f888d5c9a50cbaf8c513cab5ca24c46dc73487b6a4927b7

data/.github/workflows/ci.yml

@@ -4,10 +4,15 @@ on:
   push:
     branches:
       - main
+    tags:
+      - '!*'
   pull_request:
+    paths:
+      - '!*.MD'
+      - '!*.md'
 
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
 
     steps:
@@ -44,3 +49,5 @@ jobs:
 
     - name: Run RSpec
       run: bundle exec rake spec
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+# 0.1.2
+
+- Fix namespaces/actions should no longer contain periods
+- Implement cache config for faster access to actor permissions
+
 # 0.1.1
 
 - General code refactoring
@@ -11,9 +16,9 @@
 
 Finished extraction work from my past projects.
 
-- Implemented ActiveRecord backend
-- Implemented `Actable` mixin
-- Implemented permissions hash sanitization and checking
+- Implement ActiveRecord backend
+- Implement `Actable` mixin
+- Implement permissions hash sanitization and checking
 
 # 0.0.1
 

data/Gemfile

@@ -11,3 +11,5 @@ gem "rspec", "~> 3.0"
 gem "rubocop", "~> 1.9"
 gem "simplecov", "~> 0.21.2"
 gem "sqlite3", "~> 1.4"
+
+gem "codecov", "~> 0.4.3"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    permisi (0.1.1)
+    permisi (0.1.2)
       activemodel (>= 3.2.0)
       activerecord (>= 3.2.0)
       activesupport (>= 3.2.0)
@@ -23,6 +23,8 @@ GEM
       zeitwerk (~> 2.3)
     ast (2.4.2)
     byebug (11.1.3)
+    codecov (0.4.3)
+      simplecov (>= 0.15, < 0.22)
     concurrent-ruby (1.1.8)
     diff-lcs (1.4.4)
     docile (1.3.5)
@@ -78,6 +80,7 @@ PLATFORMS
 
 DEPENDENCIES
   byebug (~> 11.1)
+  codecov (~> 0.4.3)
   permisi!
   rake (~> 13.0)
   rspec (~> 3.0)

data/README.md

@@ -1,3 +1,5 @@
+If you're viewing this at https://github.com/ukazap/permisi, you're reading the documentation for the main branch. [Go to specific version.](https://github.com/ukazap/permisi/tags)
+
 <table>
   <tr>
     <th>
@@ -9,8 +11,15 @@
       <h1>Permisi</h1>
       <p><em>Simple and dynamic role-based access control for Rails</em></p>
       <p>
-        <a href="https://badge.fury.io/rb/permisi"><img src="https://badge.fury.io/rb/permisi.svg" alt="Gem Version"></a>
-        <a href="https://codeclimate.com/github/ukazap/permisi/maintainability"><img src="https://api.codeclimate.com/v1/badges/0b1238302f2012b20740/maintainability" /></a>
+        <a href="https://badge.fury.io/rb/permisi">
+          <img src="https://badge.fury.io/rb/permisi.svg" alt="Gem Version">
+        </a>
+        <a href="https://codeclimate.com/github/ukazap/permisi/maintainability">
+          <img src="https://api.codeclimate.com/v1/badges/0b1238302f2012b20740/maintainability" />
+        </a>
+        <a href="https://codecov.io/gh/ukazap/permisi">
+          <img src="https://codecov.io/gh/ukazap/permisi/branch/main/graph/badge.svg?token=9YRMVFCDA8"/>
+        </a>
       </p>
     </th>
     <th>
@@ -143,11 +152,11 @@ admin_role.allows? "books.delete" # == true
 
 ## Configuring actors
 
-You can then give or take multiple roles to an actor which will allow or prevent them to perform certain actions in a flexible manner. But before you can do that, you have to wire up your user model with Permisi.
+You can then give or take multiple roles to an actor which will allow or prevent them to perform certain actions in a flexible manner. But before you can do that, you have to wire up your user model with Permisi using via `Permisi::Actable` mixin.
 
 Permisi does not hold an assumption that a specific model is present (e.g. User model). Instead, it keeps track of "actors" internally. The goal is to support multiple use cases such as actor polymorphism, user _groups_, etc.
 
-For example, you can map your user model to Permisi's actor model by including the `Permisi::Actable` mixin like so:
+For example, you can map your user model to Permisi's actor model like so:
 
 ```ruby
 # app/models/user.rb
@@ -157,21 +166,81 @@ class User < ApplicationRecord
 end
 ```
 
-You can then interact with the new `#permisi` method:
+You can then interact using `#permisi` method:
 
 ```ruby
 user = User.find_by_email "esther@example.com"
 user.permisi # => instance of Actor
 
-user.permisi.has_role? :admin # == false
-user.permisi.may? "books.delete" # == false
+admin_role = Permisi.roles.find_by_slug(:admin)
+admin_role.allows? "books.delete" # == true
+
+user.permisi.roles << admin_role
+
+user.permisi.role? :admin # == true
+user.permisi.has_role? :admin # == user.permisi.role? :admin
+
+user.permisi.may_i? "books.delete" # == true
+user.permisi.may? "books.delete" # == user.permisi.may_i? "books.delete"
+
+user.permisi.roles.destroy(admin_role)
+
+user.permisi.role? :admin # == false
+user.permisi.may_i? "books.delete" # == false
+```
+
+## Caching
+
+Permisi has several optimizations out of the box: actor roles eager loading, actor permissions memoization, and the optional actor permissions caching.
+
+### Actor roles eager loading
+
+Although checking whether an actor has a role goes against a good RBAC practice, it is still possible on Permisi. Calling `role?` multiple times will only make one call to the database:
+
+```ruby
+user = User.find_by_email "esther@example.com"
+user.role? :admin # eager loads roles
+user.role? :admin # uses the eager-loaded roles
+user.has_role? :admin # uses the eager-loaded roles
+```
+
+### Actor permissions memoization
+
+To check whether or not an actor is allowed to perform a specific action (`#may_i?`), Permisi will check on the actor's permissions which is constructed in the following steps:
+
+- get all roles an actor have (this will make a database call)
+- initialize an empty aggregate hash
+- for each roles, merge its permissions hash to the aggregate hash
 
-user.permisi.roles << Permisi.roles.find_by_slug(:admin)
+Deserializing the hashes from the database and deeply-merging them into an aggregate hash can be expensive, so it will only happen to an instance of actor only once through memoization.
 
-user.permisi.has_role? :admin # == true
-user.permisi.may? "books.delete" # == true
+### Actor permissions caching
+
+Although memoization helps, the permission hash construction will still occur everytime a actor is initialized. To alleviate this, we can introduce a caching layer so that we can skip the hash construction for fresh actors. You must configure a cache store to use caching:
+
+```ruby
+# config/initializers/permisi.rb
+
+Permisi.init do |config|
+  # You can use the default Rails cache store
+  config.cache_store = Rails.cache
+  # or use other cache stores
+  config.cache_store = ActiveSupport::Cache::RedisCacheStore.new(url: ENV['REDIS_URL'])
+  # or
+  config.cache_store = ActiveSupport::Cache::FileStore.new("/home/ukazap/permisi_cache/")
+end
 ```
 
+You can also roll your own [custom cache store](https://guides.rubyonrails.org/caching_with_rails.html#custom-cache-stores).
+
+### Cache/memo invalidation
+
+The following will trigger actor's permissions cache/memo invalidation:
+
+- adding roles to the actor
+- removing roles from the actor
+- editing roles that belongs to an actor
+
 ## Contributing
 
 For development and how to submit improvements, please refer to the [contribution guide](https://github.com/ukazap/permisi/blob/main/CONTRIBUTING.md).

data/lib/generators/permisi/templates/initializer.rb

@@ -10,4 +10,8 @@ Permisi.init do |config|
   # Define all permissions available in the system
   # See https://github.com/ukazap/permisi#configuring-permissions
   config.permissions = {}
+
+  # Define cache store
+  # See https://github.com/ukazap/permisi#caching
+  config.cache_store = Rails.cache
 end

data/lib/permisi.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "active_model/type"
-require "active_support/hash_with_indifferent_access"
+require "active_support"
 require "zeitwerk"
 
 module Permisi

data/lib/permisi/backend/active_record/actor.rb

@@ -8,15 +8,35 @@ module Permisi
         has_many :actor_roles, dependent: :destroy
         has_many :roles, through: :actor_roles
 
+        after_commit :reset_permissions
+
         def role?(role_slug)
           roles.load.any? { |role| role.slug == role_slug.to_s }
         end
 
-        def may?(action_path)
-          roles.load.any? { |role| role.allows?(action_path) }
+        def may_i?(action_path)
+          PermissionUtil.allows?(permissions, action_path)
+        end
+
+        # Memoized and cached actor permissions
+        def permissions
+          @permissions ||= Permisi.config.cache_store.fetch(cache_key) { aggregate_permissions }
+        end
+
+        # Aggregate permissions from all roles an actor plays
+        def aggregate_permissions
+          roles.load.inject(HashWithIndifferentAccess.new) do |aggregate, role|
+            aggregate.deep_merge(role.permissions) do |_key, effect, another_effect|
+              effect == true || another_effect == true
+            end
+          end
+        end
+
+        def reset_permissions
+          @permissions = nil
         end
 
-        alias may_i? may?
+        alias may? may_i?
         alias has_role? role?
       end
     end

data/lib/permisi/config.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-require "active_support/core_ext/class/attribute_accessors"
-
 module Permisi
   class Config
+    class InvalidCacheStore < StandardError; end
+
+    NULL_CACHE_STORE = ActiveSupport::Cache::NullStore.new
+
     attr_reader :permissions, :default_permissions
 
     def initialize
@@ -27,5 +29,15 @@ module Permisi
       @default_permissions = PermissionUtil.transform_namespace(permissions_hash)
       @permissions = permissions_hash
     end
+
+    def cache_store=(cache_store)
+      raise InvalidCacheStore unless cache_store.respond_to?(:fetch)
+
+      @cache_store = cache_store
+    end
+
+    def cache_store
+      @cache_store || NULL_CACHE_STORE
+    end
   end
 end

data/lib/permisi/permission_util.rb

@@ -20,14 +20,22 @@ module Permisi
       def transform_namespace(namespace, current_path: nil)
         HashWithIndifferentAccess.new.tap do |transformed|
           namespace.each_pair do |key, value|
-            unless value.is_a? Array
+            if !value.is_a? Array
               raise InvalidNamespace,
                     "`#{[current_path, key].compact.join(".")}` should be an array"
             end
 
+            if key.to_s.include?(".")
+              raise InvalidNamespace, "namespace or action should not contain period: `#{key}`"
+            end
+
             value.each.with_index do |arr_v, arr_i|
               case arr_v
               when Symbol
+                if arr_v.to_s.include?(".")
+                  raise InvalidNamespace, "namespace or action should not contain period: `#{arr_v}`"
+                end
+
                 transformed[key] ||= ::HashWithIndifferentAccess.new
                 if transformed[key].key? arr_v
                   raise InvalidNamespace, "duplicate entry: `#{[current_path, key, arr_v].compact.join(".")}`"

data/lib/permisi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Permisi
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permisi
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Ukaza Perdana
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-02-20 00:00:00.000000000 Z
+date: 2021-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -133,7 +133,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.3
 signing_key: 
 specification_version: 4
 summary: Simple and dynamic role-based access control for Rails