shareable_models 0.5.0

data/README.md

@@ -0,0 +1,123 @@
+# Shareable Models
+
+Shareable models is a gem to share models between models. Is this strange? I will explain the functionality of this Gem with an example.
+
+Imagine you have an awesome Rails app for a publisher with three models:
+* Author: it creates books.
+* Book: a world behind words.
+* Group: a group of authors.
+
+An author can create many private books, but he wants to share it another author. Author class is a `sharer`, it can share and receive books. Books are things that can be shared, so they are `shareable`.
+
+Another author wants to share its book with multiple authors, all of them form a Group. Share a book with all authors in the group can be bored. However, you can set Group `shareable` and share the book with the entire group.
+
+Shareable Models use polymorphic relations to allow you to share resources between multiple models with no limitations.
+
+# Installation
+To use `ShareableModels` in your application, add this line to your Gemfile:
+
+```ruby
+  gem 'shareable_models', '~> 1.0.0'
+```
+
+After add it, run `bundle install`.
+
+Next you need to load migrations of this gem, so execute in your Rails application:
+
+```
+rake shareable_models:install:migrations
+rake db:migrate
+```
+
+Last step is to set your classes as `sharer` or `shareable`. To do this include these methods at top of yout models. For example:
+
+```ruby
+# File app/models/author.rb (sharer)
+class Author < ActiveRecord::Base
+  sharer
+
+  #...
+end
+
+# File app/models/book.rb (shareable)
+class Book < ActiveRecord::Base
+  # Owner define the creator of the book, to check edit/read permissions.
+  # See next sections
+  shareable owner: :author
+
+  #...
+end
+```
+
+# Models
+A model can be `sharer` or `shareable`. This methods include some relations and added new methods to your class.
+
+## Sharer
+Set a model as sharer. A sharer can share and receive resources. It has edit permissions on a resource if:
+
+* It creates the resource (see [Shareable](#shareable))
+* Another sharer shares the resource with him and edit permission is true.
+
+Importants methods defined by sharer (see sharer.rb for full documentation):
+
+* `share(resource, to, edit)`: share a resource with another model (to). You can set edit permissions (false by default).
+* `share_with_me(resource, from, edit)`: share a resource **from** another sharer to me. 
+* `can_edit?(resource)`: check if a model can edit a resource.
+* `can_read?(resource)`: check if a model can read a resource.
+* `throw_out(resource, sharer)`: throw out a sharer from a resource.
+* `leave(resource)`: to leave resource. A creator/owner of a shareable resource can't leave it.
+* `allow_edit?(resource, to)`: allow a model to edit a resource. If resource was never shared with model, a new relation is created.
+* `prevent_edit?(resource, to)`: disable an user to edit a resource. If resource was never shared with model, relation won't be created.
+
+## Shareable
+Set a model as shareable. You need to specify what's the name of the relation to find 'owner' or 'creator' of this shareable model:
+```ruby
+class User < ActiveRecord::Base
+  shareable owner: :user
+  # ...
+end
+```
+
+Shareable models can be shared between sharers. Importants methods defined by sharer (see sharer.rb for full documentation):
+
+* `share_it(from, to, edit)`: share the resource with **from** a model **to** another. You can set edit permissions (false by default).
+* `editable_by?(from)`: check if resource is editable by given model.
+* `readable_by?(from)`: check if resource is readable by given model.
+* `throw_out(from, to)`: a sharer (**from**) throw out another (**to**) from a resource.
+* `leave(sharer)`: sharer leaves resource. A creator/owner of a shareable resource can't leave it.
+* `allow_edit?(from, to)`: a sharer (**from**) allow another (**to**) to edit a resource. If resource was never shared with model, a new relation is created.
+* `prevent_edit?(from, to)`: a sharer (**from**) disable another (**to**) to edit a resource. If resource was never shared with model, relation won't be created.
+
+# Example of usage
+
+```ruby
+# We start at scenario described at introduction: Author, Book and Group. Instanced models:
+# * author1: it creates book1
+# * author2: another author. Anyone shared book1 with it.
+
+author1.can_read? book1         # -> true
+author1.can_edit? book1         # -> true
+author2.can_read? book1         # -> false
+author2.can_edit? book1         # -> false
+
+author1.share(book1, author2)   # -> true
+author2.can_read? book1         # -> true
+author2.can_edit? book1         # -> false
+
+author1.allow_edit(book1, author2)    # -> true
+author2.can_read? book1               # -> true
+author2.can_edit? book1               # -> true
+```
+
+# Contribute
+
+To contribute Shareable Models:
+
+* Create an issue with the contribution: bug, enhancement, feature...
+* Fork the repository and make all changes you need
+* Write test on new changes
+* Create a pull request when you finish
+
+# License
+
+ShareableModels gem is released under the Affero GPL license. Copyright [redBorder](http://redborder.net)

data/Rakefile

@@ -0,0 +1,25 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+# Load dummy app
+APP_RAKEFILE = File.expand_path('../spec/dummy/Rakefile', __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+Dir[File.join(File.dirname(__FILE__), 'tasks/**/*.rake')].each { |f| load f }
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc 'Run all specs in spec directory (excluding plugin specs)'
+
+# Load database
+ENV['RAILS_ENV'] ||= 'test'
+RSpec::Core::RakeTask.new(spec: 'app:db:test:prepare')
+
+# Set default rake task to run rspec
+task default: :spec

data/app/models/share_model.rb

@@ -0,0 +1,18 @@
+#
+# Class to connect shared resources with another models. Resources are every
+# class include shareable module. Shared_to can be any model with share_receiver
+# module included.
+#
+class ShareModel < ActiveRecord::Base
+  # Resource it's shared
+  belongs_to :resource, polymorphic: true
+  # Model with resource is shared
+  belongs_to :shared_to, polymorphic: true
+  # User who share resources
+  belongs_to :shared_from, polymorphic: true
+
+  validates :resource, :shared_to, :shared_from, presence: true
+  # Every resource only can be shared with one person from same sharer one time.
+  validates :resource_id, uniqueness: { scope: [:resource_type, :shared_to_id,
+                                                :shared_to_type] }
+end

data/lib/shareable_models/engine.rb

@@ -0,0 +1,13 @@
+#
+# Engine to add to main rails app
+#
+module ShareableModels
+  # Set the base engine to connect with rails
+  class Engine < ::Rails::Engine
+    engine_name 'shareable_models'
+
+    config.generators do |g|
+      g.test_framework :rspec, fixture: true
+    end
+  end
+end

data/lib/shareable_models/models/shareable.rb

@@ -0,0 +1,149 @@
+#
+# Namespace of Shareable.
+#
+module ShareableModels
+  #
+  # Modules to include in models that will use shareable options
+  #
+  module Models
+    #
+    # Define a model as shareable. A shareable model can be shared between
+    # other models called sharers. Imagine a platform with privates articles,
+    # you could want to share your awesome article with other person, so
+    # make it shareable.
+    #
+    module Shareable
+      #
+      # Method to determine if a model can be shared. It always true because
+      # the class includes this module.
+      #
+      # == Returns
+      # true
+      #
+      def shareable?
+        true
+      end
+
+      #
+      # Return the shareable owner
+      #
+      def shareable_owner
+        return nil if shareable_options.nil? || shareable_options[:owner].nil?
+        send(shareable_options[:owner])
+      end
+
+      #
+      # Share current element with a sharer model.
+      #
+      # == Parameters:
+      # from::
+      #   Instance of model with share this resource
+      # to::
+      #   Instance of model to share with
+      # edit::
+      #   True if the user has edit permission. False by default
+      #
+      # == Returns:
+      # true if its saved.
+      #
+      def share_it(from, to, edit = false)
+        from.share(self, to, edit)
+      end
+
+      #
+      # Throw out an user from this resource
+      #
+      # == Parameters:
+      # from::
+      #   Sharer that want to leave resource.
+      # to::
+      #   Sharer that want to leave resource.
+      #
+      # == Returns:
+      # True if it's ok
+      #
+      def throw_out(from, to)
+        from.throw_out(self, to)
+      end
+
+      #
+      # Allow given sharer to leave the resource
+      #
+      # == Parameters:
+      # sharer::
+      #   Sharer that want to leave resource.
+      #
+      # == Returns:
+      # True if it's ok
+      #
+      def leave_by(sharer)
+        sharer.leave(self)
+      end
+
+      #
+      # Permissions
+      # ----------------------------------------------------
+
+      #
+      # Check if a given sharer can edit this resource
+      #
+      # == Parameters:
+      # from::
+      #   Sharer that wants to edit the user.
+      #
+      # == Returns:
+      # true if the sharer can edit it
+      #
+      def editable_by?(from)
+        from.can_edit?(self)
+      end
+
+      #
+      # Check if a given sharer can see this resource
+      #
+      # == Parameters:
+      # from::
+      #   Sharer that wants to see the user.
+      #
+      # == Returns:
+      # true if the sharer can see it
+      #
+      def readable_by?(from)
+        from.can_read?(self)
+      end
+
+      #
+      # Allow a sharer to edit the resource
+      #
+      # == Parameters:
+      # from::
+      #   Sharer that want to allow another to edit resource
+      # to::
+      #   Sharer that will be able to edit the resource
+      #
+      # == Returns:
+      # True if it's ok
+      #
+      def allow_edit(from, to)
+        from.allow_edit(self, to)
+      end
+
+      #
+      # Prevent a sharer to edit the resource. First parameter is to set same
+      # format of allow_edit.
+      #
+      # == Parameters:
+      # from::
+      #   Sharer that want to allow another to edit resource
+      # to::
+      #   Sharer that will be able to edit the resource
+      #
+      # == Returns:
+      # True if it's ok
+      #
+      def prevent_edit(from, to)
+        from.prevent_edit(self, to)
+      end
+    end
+  end
+end

data/lib/shareable_models/models/sharer.rb

@@ -0,0 +1,232 @@
+#
+# Namespace of Shareable.
+#
+module ShareableModels
+  #
+  # Modules to include in models that will use shareable options
+  #
+  module Models
+    #
+    # Define a model as shareable. A shareable model can be shared between
+    # other models called sharers. Imagine a platform with privates articles,
+    # you could want to share your awesome article with other person, so
+    # make it shareable.
+    #
+    module Sharer
+      #
+      # Method to determine if a model can share and receive elements. It always
+      # true because the class include this module.
+      #
+      # == Returns
+      # true
+      #
+      def sharer?
+        true
+      end
+
+      #
+      # Share a given resource with a sharer model.
+      #
+      # == Parameters:
+      # resource::
+      #   Resource to share. It must includes shareable module
+      # to::
+      #   Model to share the resource. It must includes sharer module
+      # edit::
+      #   Boolean indicating if it has permissions to edit shared resources.
+      #   False by default.
+      #
+      # == Returns:
+      # True if it's saved
+      #
+      def share(resource, to, edit = false)
+        check_resource(resource)
+        check_sharer(to)
+        return false unless can_edit?(resource)
+        # Save new share
+        shared_resources.build(
+          shared_to: to,
+          resource: resource,
+          edit: edit
+        )
+        save!
+      end
+
+      #
+      # Share the given resource with this model. You can understand this method
+      # as inverse of share.
+      #
+      # == Parameters:
+      # resource::
+      #   Resource to share. It must includes shareable module
+      # from::
+      #   Model who share the resource. It must includes sharer module
+      # edit::
+      #   Boolean indicating if it has permissions to edit shared resources.
+      #   False by default.
+      #
+      # == Returns:
+      # True if it's saved
+      #
+      def share_with_me(resource, from, edit = false)
+        check_resource(resource)
+        check_sharer(from)
+        # Save new share
+        from.share(resource, self, edit)
+      end
+
+      #
+      # Stop sharing a shareable model with a sharer. You can throw out creator
+      # of shareable model.
+      #
+      # == Parameters:
+      # resource::
+      #   Resource to throw out the sharer.
+      # sharer::
+      #   Sharer model to disable share.
+      # edit::
+      #   Check if sharer has permissions to edit before throw out. It's true
+      #   by default, but if an user try to leave a resource we must not check
+      #   this.
+      #
+      # == Returns:
+      # True if it's ok
+      #
+      def throw_out(resource, sharer, edit = true)
+        check_resource(resource)
+        check_sharer(sharer)
+        return false if (edit && !self.can_edit?(resource)) ||
+                        resource.shareable_owner == sharer
+        relation = resource.shared_with.find_by(shared_to: sharer)
+        relation.nil? ? true : relation.destroy.destroyed?
+      end
+
+      #
+      # Current sharer leaves a shareable object.
+      #
+      # == Parameters:
+      # resource::
+      #   Resource to throw out the sharer.
+      #
+      # == Returns:
+      # True if it's ok
+      #
+      def leave(resource)
+        throw_out(resource, self, false)
+      end
+
+      #
+      # Permissions
+      # ----------------------------------------------------
+
+      #
+      # Check if the current sharer can edit a given resource. We need to check
+      # if the user share this element or someone share it with him.
+      #
+      # == Parameters:
+      # resource::
+      #   Resource model sharer wants to check
+      #
+      # == Returns:
+      # True or false based on permission
+      #
+      def can_edit?(resource)
+        check_resource(resource)
+        resource.shareable_owner == self ||
+          shared_with_me.where(edit: true).exists?(edit: true, resource: resource)
+      end
+
+      #
+      # Check if the current sharer can read a given resource. We need to check if
+      # the user share this element or someone share it with him.
+      #
+      # == Parameters:
+      # resource::
+      #   Resource model sharer wants to check
+      #
+      # == Returns:
+      # True or false
+      #
+      def can_read?(resource)
+        check_resource(resource)
+        resource.shareable_owner == self ||
+          shared_with_me.exists?(resource: resource)
+      end
+
+      #
+      # Allow a sharer to edit the resource
+      #
+      # == Parameters:
+      # resource::
+      #   Resource model to allow edit the user
+      # to::
+      #   Sharer that will be able to edit the resource
+      #
+      # == Returns:
+      # True if it's ok
+      #
+      def allow_edit(resource, to)
+        return false unless can_edit?(resource)
+        return true if to.can_edit?(resource)
+        share_resource = shared_resources.find_by(shared_to: to, resource: resource)
+        if share_resource.nil?
+          share(resource, to, true)
+        else
+          share_resource.update(edit: true)
+        end
+      end
+
+      #
+      # Prevent a sharer to edit the resource. First parameter is to set same
+      # format of allow_edit.
+      #
+      # == Parameters:
+      # resource::
+      #   Resource to prevent an user to edit
+      # to::
+      #   Sharer that will be able to edit the resource
+      #
+      # == Returns:
+      # True if it's ok
+      #
+      def prevent_edit(resource, to)
+        return false unless can_edit?(resource)
+        share_resource = shared_resources.find_by(shared_to: to, resource: resource)
+        return true if share_resource.nil?
+        share_resource.update(edit: false)
+      end
+
+      private
+
+      #
+      # Check if from and destination models have included the modules
+      #
+      # == Parameters:
+      # resource::
+      #   Instance of resource to share
+      #
+      # == Returns:
+      # Fail if there are a bad condition
+      #
+      def check_resource(resource)
+        fail "#{resource} class must include Shareable module" unless
+          resource.respond_to?(:shareable?)
+      end
+
+      #
+      # Check if given sharer include the correct module in the class.
+      #
+      # == Parameters:
+      # sharer::
+      #   Instance of model to share with
+      #
+      # == Returns:
+      # Fail if the class doesn't include Sharer module
+      #
+      def check_sharer(sharer)
+        fail "#{sharer} class must include Sharer module" unless
+          sharer.respond_to?(:sharer?)
+      end
+    end
+  end
+end

data/lib/shareable_models/share.rb

@@ -0,0 +1,50 @@
+#
+# Namespace of Shareable.
+#
+module ShareableModels
+  #
+  #  It's define the options to set a model as sharer or shareable
+  #
+  module Share
+    #
+    # Define a model as shareable. A shareable model can be shared between
+    # other models called sharers. Imagine a platform with privates articles,
+    # you could want to share your awesome article with other person, so
+    # make it shareable.
+    #
+    # == Parameters:
+    # options:
+    #   A hash with options to personalize the way to share the model.
+    #     - owner: name of relation that point to the create of resource.
+    #              For example, the author of an Article. Owners always can
+    #              read and edit the resources.
+    #
+    def shareable(options = {})
+      include ShareableModels::Models::Shareable
+
+      # Add some relations
+      has_many :shared_with, as: :resource, class_name: 'ShareModel'
+
+      class_attribute :shareable_options
+      self.shareable_options = options
+    end
+
+    #
+    # Define a model as sharer. A sharer model can share another models that
+    # it has edit permissions or it is owner. Following the example of Articles,
+    # Sharer model will be Author model.
+    #
+    # A sharer can only receive shareable elements too. For example, you could
+    # define a Group model that englobe multiple authors. Group can be a sharer
+    # that only receive shares from Authors (another shares) to share Article
+    # with multiple authors.
+    #
+    def sharer
+      include ShareableModels::Models::Sharer
+
+      # Add some relations
+      has_many :shared_resources, as: :shared_from, class_name: 'ShareModel'
+      has_many :shared_with_me, as: :shared_to, class_name: 'ShareModel'
+    end
+  end
+end

data/lib/shareable_models/version.rb

@@ -0,0 +1,7 @@
+#
+# Define the versions of the gem.
+#
+module ShareableModels
+  # Version of the gem
+  VERSION = '0.5.0'
+end

data/lib/shareable_models.rb

@@ -0,0 +1,15 @@
+# Require all files
+require 'shareable_models/models/shareable'
+require 'shareable_models/models/sharer'
+require 'shareable_models/share'
+require 'active_record'
+
+# Extend active record with share options
+ActiveRecord::Base.send :extend, ShareableModels::Share
+
+# Only require if rails is available
+require 'shareable_models/engine'
+
+# Base module
+module ShareableModels
+end

data/spec/dummy/Rakefile

@@ -0,0 +1,3 @@
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks

data/spec/dummy/app/models/resource.rb

@@ -0,0 +1,8 @@
+#
+# Resource that users can share
+#
+class Resource < ActiveRecord::Base
+  shareable owner: :user
+  # Owner
+  belongs_to :user
+end

data/spec/dummy/app/models/user.rb

@@ -0,0 +1,8 @@
+#
+# Basic user model
+#
+class User < ActiveRecord::Base
+  sharer
+  # Resources user create
+  has_many :resources
+end

data/spec/dummy/config/application.rb

@@ -0,0 +1,17 @@
+require File.expand_path('../boot', __FILE__)
+
+# Pick the frameworks you want:
+require "active_record/railtie"
+#require "sprockets/railtie"
+# require "rails/test_unit/railtie"
+
+Bundler.require(*Rails.groups)
+
+module Dummy
+  class Application < Rails::Application
+    # Do not swallow errors in after_commit/after_rollback callbacks.
+    config.active_record.raise_in_transactional_callbacks = true
+    config.encoding = "utf-8"
+    config.eager_load = false
+  end
+end

data/spec/dummy/config/boot.rb

@@ -0,0 +1,5 @@
+# Set up gems listed in the Gemfile.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../../../Gemfile', __FILE__)
+
+require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
+$LOAD_PATH.unshift File.expand_path('../../../../lib', __FILE__)