cancancan-system 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 94f86f5710ad3064cb2fbd31f4894fda9bc079b26701f7ed351c5a52ad59821f
+  data.tar.gz: e81ae0727b09aa9e0a137962c46927c0ca313bdc2480aa964c661fa11e09d882
+SHA512:
+  metadata.gz: a35d4aac231b628f6b3223b46308719f5916d030f5b5f07d48a502db0ba4cc5c8f717d372b92059c7f556bccae684646ab21b11918608890f1f0b02389c28ecc
+  data.tar.gz: c88efd88664474247b41b0b2b91672f594140d55f5f3c0d7eed44ba8127d0d541ad926a82f5357aa1f04aafadeaaff4654cc0f351eea0c5be71235f7ec35e080

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+### master
+
+* nothing yet
+
+### 1.0.0 - 2018/01/20
+
+* initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Jonas Hübotter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,331 @@
+# CanCanCan System
+
+[![Gem Version](https://badge.fury.io/rb/cancancan-system.svg)](https://badge.fury.io/rb/cancancan-system) <img src="https://travis-ci.org/jonhue/cancancan-system.svg?branch=master" />
+
+Conventions & helpers simplifying the use of CanCanCan in complex Rails applications. CanCanCan System simplifies authorizing collaborations, memberships and more across a complex structure of models.
+
+To describe complex abilities CanCanCan System relies on two different constructs: ActiveRecord **objects**, and **relationships** of users to those objects.
+
+CanCanCan System uses two attributes on *objects* to describe abilities:
+
+* **ability:** Describes the default ability of users without a special relationship with an object.
+* **visiblity:** Specifies whether an object is visible to other users than the creator.
+
+CanCanCan System uses one attribute on *relationships* to describe abilities:
+
+* **ability:** Describes the ability of a user with the related object.
+
+`ability` can have any CanCanCan permission, `'admin'` (`:manage`), `'user'` (`:modify`) or `'guest'` (`:read`) as value while `visiblity` is limited to `public` and `private`.
+
+---
+
+## Table of Contents
+
+* [Installation](#installation)
+* [Usage](#usage)
+    * [Defining abilities](#defining-abilities)
+        * [Public abilities](#public-abilities)
+        * [acts_as_belongable abilities](#acts_as_belongable-abilities)
+        * [Membership abilities](#membership-abilities)
+    * [Get abilities](#get-abilities)
+* [To Do](#to-do)
+* [Contributing](#contributing)
+    * [Contributors](#contributors)
+    * [Semantic versioning](#semantic-versioning)
+* [License](#license)
+
+---
+
+## Installation
+
+CanCanCan System works with Rails 5 onwards. You can add it to your `Gemfile` with:
+
+```ruby
+gem 'cancancan-system'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install cancancan-system
+
+If you always want to be up to date fetch the latest from GitHub in your `Gemfile`:
+
+```ruby
+gem 'cancancan-system', github: 'jonhue/cancancan-system'
+```
+
+Now run the generator:
+
+    $ rails g cancancan_system
+
+To wrap things up, migrate the changes to your database:
+
+    $ rails db:migrate
+
+---
+
+## Usage
+
+To get started add CanCanCan System to your `Ability` class (`app/models/ability.rb`) and add the required `:modify` alias:
+
+```ruby
+class Ability
+
+    include CanCan::Ability
+    include CanCanCan::System::Ability
+
+    def initialize user
+        modify [:create, :read, :update, :destroy]
+    end
+
+end
+```
+
+**Note:** The aliases (`:create, :read, :update, :destroy`) can be custom.
+
+### Defining Abilities
+
+CanCanCan System makes an `abilities` method available which simplifies setting up common abilities:
+
+```ruby
+def initialize user
+    abilities Post, user
+end
+```
+
+This is equivalent to:
+
+```ruby
+def initialize user
+    public_abilities Post
+    can :manage, Post, user_id: user.id if user
+end
+```
+
+You can also use the `abilities` method with custom column names and polymorphic associations. This comes in handy when using the [NotificationsRails gem](https://github.com/jonhue/notifications-rails):
+
+```ruby
+def initialize user
+    abilities Notification, user, column: 'target', polymorphic: true, public_abilities: false
+end
+```
+
+This is equivalent to:
+
+```ruby
+def initialize user
+    can :manage, Notification, target_id: user.id, target_type: user.class.name if user
+end
+```
+
+Learn more about the `public_abilities` method [here](#public-abilities).
+
+#### Public abilities
+
+The `public_abilities` method defines the object-abilities without a `user` being present:
+
+```ruby
+def initialize user
+    public_abilities Post
+end
+```
+
+This is equivalent to:
+
+```ruby
+def initialize user
+    can :manage, Post, ability: 'admin', visibility: 'public'
+    can :modify, Post, ability: 'user', visibility: 'public'
+    can :read, Post, ability: 'guest', visibility: 'public'
+end
+```
+
+#### acts_as_belongable abilities
+
+CanCanCan System integrates with the [acts_as_belongable gem](https://github.com/jonhue/acts_as_belongable) to make defining abilities for relationships dead simple.
+
+Let's say our users can be a member of multiple organizations:
+
+```ruby
+class User < ApplicationRecord
+    acts_as_belongable
+    belongable :member_of_organizations, 'Organization', scope: :membership
+    has_many :organizations
+end
+
+class Organization < ApplicationRecord
+    acts_as_belonger
+    belonger :members, 'User', scope: :membership
+    belongs_to :user
+end
+```
+
+We would then just do:
+
+```ruby
+def initialize user
+    abilities Organization, user do
+        belonger_abilities Organization, user, scope: :membership
+    end
+end
+```
+
+**Note:** This can be done in the same way with `belongable_abilities` for `belongable` relationships.
+
+Now we are able to add members to our organizations and set their abilities:
+
+```ruby
+Organization.first.add_belongable User.first, scope: :membership, ability: 'admin'
+```
+
+**Note:** The `scope` option is optional. If omitted, the defined abilities will apply to all belongings regardless of their scope.
+
+#### Membership abilities
+
+Now, let us assume that we have another model: `Post`.
+
+```ruby
+class User < ApplicationRecord
+    acts_as_belongable
+    belongable :member_of_organizations, 'Organization', scope: :membership
+    has_many :posts
+    has_many :organizations
+end
+
+class Organization < ApplicationRecord
+    acts_as_belonger
+    belonger :members, 'User', scope: :membership
+    has_many :posts
+    belongs_to :user
+end
+
+class Post < ApplicationRecord
+    belongs_to :user
+    belongs_to :organization
+end
+```
+
+You want the posts of an organization to be accessible for its members. It doesn't get any simpler than this:
+
+```ruby
+def initialize user
+    abilities Post, user do
+        organization_abilities Post, user, scope: :membership
+    end
+end
+```
+
+**Note:** The `scope` option is optional. If omitted, the defined abilities will apply to all belongings regardless of their scope.
+
+You are also able to perform some customization:
+
+```ruby
+class Post < ApplicationRecord
+    belongs_to :user
+    belongs_to :object, polymorphic: true
+end
+```
+
+```ruby
+def initialize user
+    abilities Post, user do
+        organization_abilities Post, user, scope: :membership, column: 'object', polymorphic: true
+    end
+end
+```
+
+Another option is to use the [acts_as_belongable gem](https://github.com/jonhue/acts_as_belongable) to associate posts with organizations:
+
+```ruby
+class Organization < ApplicationRecord
+    acts_as_belonger
+    belonger :members, 'User', scope: :membership
+    belonger :posts, 'Post'
+    has_many :posts
+    belongs_to :user
+end
+
+class Post < ApplicationRecord
+    acts_as_belongable
+    belongable :organizations, 'Organization'
+    belongs_to :user
+end
+```
+
+```ruby
+def initialize user
+    abilities Post, user do
+        organization_abilities Post, user, scope: :membership, acts_as_belongable: true
+    end
+end
+```
+
+**Note:** If your `acts_as_belongable` association in the `Post` model is not following the CanCanCan System naming convention, you can override it by passing the `column` option.
+
+### Get abilities
+
+You can use the `ability` method to get the ability of an ActiveRecord object:
+
+```ruby
+Organization.first.ability
+# => 'guest'
+
+ability Organization.first
+# => :read
+```
+
+It returns a symbol or `nil`.
+
+---
+
+## To Do
+
+[Here](https://github.com/jonhue/cancancan-system/projects/1) is the full list of current projects.
+
+To propose your ideas, initiate the discussion by adding a [new issue](https://github.com/jonhue/cancancan-system/issues/new).
+
+---
+
+## Contributing
+
+We hope that you will consider contributing to CanCanCan System. Please read this short overview for some information about how to get started:
+
+[Learn more about contributing to this repository](CONTRIBUTING.md), [Code of Conduct](CODE_OF_CONDUCT.md)
+
+### Contributors
+
+Give the people some :heart: who are working on this project. See them all at:
+
+https://github.com/jonhue/cancancan-system/graphs/contributors
+
+### Semantic Versioning
+
+CanCanCan System follows Semantic Versioning 2.0 as defined at http://semver.org.
+
+## License
+
+MIT License
+
+Copyright (c) 2018 Jonas Hübotter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/app/models/concerns/cancancan/system/ability.rb

@@ -0,0 +1,149 @@
+module CanCanCan
+    module System
+        module Ability
+
+            extend ActiveSupport::Concern
+
+            def method_missing m, *args
+                if m.to_s[/(.+)_abilities/]
+                    membership_abilities $1, args
+                else
+                    super
+                end
+            end
+
+            def respond_to? m, include_private = false
+                super || m.to_s[/(.+)_abilities/]
+            end
+
+            private
+
+            def modify aliases
+                alias_action aliases, to: :modify
+            end
+
+            def abilities record_class, user, options = {}
+                defaults = {
+                    column: 'user',
+                    polymorphic: false,
+                    public_abilities: true
+                }
+                options = defaults.merge options
+
+                public_abilities record_class if options[:public_abilities]
+                if user
+                    if options[:polymorphic]
+                        can :manage, record_class, "#{options[:column]}_id": user.id, "#{options[:column]}_type": user.class.name
+                    else
+                        can :manage, record_class, "#{options[:column]}_id": user.id
+                    end
+                    yield
+                end
+            end
+
+            def membership_abilities class_name, record_class, user, options = {}
+                defaults = {
+                    scope: :membership,
+                    column: nil,
+                    polymorphic: false,
+                    acts_as_belongable: false
+                }
+                options = defaults.merge options
+
+                user.belongable_belongings.where(scope: options[:scope].to_s).each do |belonging|
+                    if belonging.belonger_type == class_name.camelize
+                        ability = ability belonging
+                        if options[:acts_as_belongable]
+                            can ability, record_class, "#{column || class_name.pluralize}": { id: belonging.belonger_id }
+                        else
+                            if options[:polymorphic]
+                                can ability, record_class, "#{column || class_name}_id": belonging.belonger_id, "#{column || class_name}_type": belonging.belonger_type
+                            else
+                                can ability, record_class, "#{column || class_name}_id": belonging.belonger_id
+                            end
+                        end
+                    end
+                end
+                user.send("#{class_name.pluralize}").each do |object|
+                    if options[:acts_as_belongable]
+                        can :manage, record_class, "#{column || class_name.pluralize}": { id: object.id }
+                    else
+                        if options[:polymorphic]
+                            can :manage, record_class, "#{column || class_name}_id": object.id, "#{column || class_name}_type": object.class.name
+                        else
+                            can :manage, record_class, "#{column || class_name}_id": object.id
+                        end
+                    end
+                end
+            end
+
+            def belongable_abilities record_class, user, options = {}
+                defaults = {
+                    scope: nil
+                }
+                options = defaults.merge options
+
+                if scope.nil?
+                    user.belongable_belongings.each do |belonging|
+                        belongable_belonging belonging
+                    end
+                else
+                    user.belongable_belongings.where(scope: scope.to_s).each do |belonging|
+                        belongable_belonging belonging
+                    end
+                end
+            end
+            def belongable_belonging belonging
+                if belonging.belonger_type == record_class.name
+                    ability = ability belonging
+                    can ability, record_class, id: belonging.belonger_id if ability
+                end
+            end
+
+            def belonger_abilities record_class, user, options = {}
+                defaults = {
+                    scope: nil
+                }
+                options = defaults.merge options
+
+                if scope.nil?
+                    user.belonger_belongings.each do |belonging|
+                        belonger_belonging belonging
+                    end
+                else
+                    user.belonger_belongings.where(scope: scope.to_s).each do |belonging|
+                        belonger_belonging belonging
+                    end
+                end
+            end
+            def belonger_belonging belonging
+                if belonging.belongable_type == record_class.name
+                    ability = ability belonging
+                    can ability, record_class, id: belonging.belongable_id if ability
+                end
+            end
+
+            def public_abilities record_class
+                can :manage, record_class, ability: 'admin', visibility: 'public'
+                can :modify, record_class, ability: 'user', visibility: 'public'
+                can :read, record_class, ability: 'guest', visibility: 'public'
+            end
+
+            def ability object
+                case object.ability
+                when 'admin'
+                    :manage
+                when 'user'
+                    :modify
+                when 'guest'
+                    :read
+                when nil
+                    nil
+                else
+                    object.ability.to_sym
+                end
+            end
+
+        end
+    end
+end

data/lib/cancancan-system.rb

@@ -0,0 +1,11 @@
+require 'cancancan'
+require 'acts_as_belongable'
+require 'cancancan-system/version'
+
+module CanCanCan
+    module System
+
+        require 'cancancan-system/engine'
+
+    end
+end

data/lib/cancancan-system/engine.rb

@@ -0,0 +1,8 @@
+require 'rails/railtie'
+
+module CanCanCan
+    module System
+        class Engine < Rails::Engine
+        end
+    end
+end

data/lib/cancancan-system/version.rb

@@ -0,0 +1,7 @@
+module CanCanCan
+    module System
+
+        VERSION = '1.0.0'
+
+    end
+end

data/lib/generators/cancancan_system_generator.rb

@@ -0,0 +1,35 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+class CancancanSystemGenerator < Rails::Generators::Base
+
+    include Rails::Generators::Migration
+
+    source_root File.join File.dirname(__FILE__), 'templates'
+    desc 'Install CanCanCan System'
+
+    def self.next_migration_number dirname
+        if ActiveRecord::Base.timestamped_migrations
+            Time.now.utc.strftime '%Y%m%d%H%M%S'
+        else
+            "%.3d" % ( current_migration_number(dirname) + 1 )
+        end
+    end
+
+    def create_migration_file
+        migration_template 'migration.rb.erb', 'db/migrate/cancancan_system_migration.rb', migration_version: migration_version
+    end
+
+    def show_readme
+        readme 'README.md'
+    end
+
+    private
+
+    def migration_version
+        if Rails.version >= '5.0.0'
+            "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+        end
+    end
+
+end

data/lib/generators/templates/README.md

@@ -0,0 +1 @@
+Now run `rails db:migrate` to add CanCanCan System to your database.

data/lib/generators/templates/migration.rb.erb

@@ -0,0 +1,5 @@
+class CancancanSystemMigration < ActiveRecord::Migration<%= migration_version %>
+    def change
+        add_column :belongings, :ability, :string, default: 'guest'
+    end
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: cancancan-system
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jonas Hübotter
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: cancancan
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: acts_as_belongable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.52'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.52'
+description: Conventions & helpers simplifying the use of CanCanCan in complex Rails
+  applications.
+email: me@jonhue.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/models/concerns/cancancan/system/ability.rb
+- lib/cancancan-system.rb
+- lib/cancancan-system/engine.rb
+- lib/cancancan-system/version.rb
+- lib/generators/cancancan_system_generator.rb
+- lib/generators/templates/README.md
+- lib/generators/templates/migration.rb.erb
+homepage: https://github.com/jonhue/cancancan-system
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.4
+signing_key: 
+specification_version: 4
+summary: Conventions & helpers simplifying the use of CanCanCan in complex Rails applications
+test_files: []