acts_as_joinable 1.1.0

data/README.rdoc

@@ -0,0 +1,53 @@
+== ActsAsJoinable
+
+This plugin adds access control to objects by giving them members, each with configurable permissions.
+
+== Overview
+
+Access control is achieved through the addition of three *acts_as* extensions and four models.
+
+== ActsAs Extensions
+
+acts_as_joinable - Added to the primary model to which access control is being added.
+acts_as_joinable_component - Added to all of the models which need to inherit their permissions from their parent joinable.
+acts_as_member - Added to a User model which can join joinables.
+
+== Models
+
+=== DefaultPermissionSet
+
+A set of permissions which any user automatically receives after joining the joinable. 
+The owner of a joinable can configure these. This allows joinables to be open to all Users.
+
+The permissions contained by the DefaultPermissionSet specify the *access model* for the joinable.
+There are three access models:
+
+* open - Users can join this joinable and receive a membership without submitting a MembershipRequest
+* closed - Users need to submit a MembershipRequest or accept a MembershipInvitation in order to join this joinable.
+* private - Users can *only* be added to the joinable after accepting a MembershipInvitation
+	
+The current access model is determined solely by the permission level of the DefaultPermissionSet.
+If the DefaultPermissionSet has a permission level which allows users to view the contents of the joinable.
+Then the access model is *open*. If the permission level allows any user to find the joinable, the access
+model is *closed*. If the permission level doesn't allow users not in the joinable to find the joinable,
+the access model is *private*.
+
+=== MembershipRequest
+
+Any user can submit a request to join any joinable which they can see. The managers of the joinable can
+then accept that request (and choose an appropriate permission level for the user) or deny it.
+
+=== MembershipInvitation
+
+The managers of a joinable can invite users to join a joinable. The invitation includes the permissions that
+the user will receive upon acceptance. 
+
+NOTE: A user cannot use the permissions given in the invitation until they accept the invitation.
+
+=== Membership
+
+Represents a set of permissions for a specific user in a specific joinable. Can be created in 3 ways:
+
+* Through the accepting of a MembershipRequest by the managers of a joinable
+* Through the accepting of a MembershipInvitation by the invitee
+* If the joinable has an *open* access model, a User can create a Membership directly

data/app/models/default_permission_set.rb

@@ -0,0 +1,40 @@
+class DefaultPermissionSet < ActiveRecord::Base
+  include Joinable::PermissionsAttributeWrapper
+    
+	belongs_to :joinable, :polymorphic => true
+
+  after_update :raise_existing_member_permissions
+  
+  def access_model
+    if has_permission?(:view)
+      return 'open'
+    elsif has_permission?(:find)
+      return 'closed'
+    else
+      return 'private'
+    end
+  end
+  
+  def access_model=(model)
+    case model.to_s
+    when 'open'
+      # Additional permissions are set explicitly so just grant the find and view permissions
+      self.grant_permissions([:find, :view])
+    when 'closed'
+      self.permissions = [:find]
+    when 'private'
+      self.permissions = []
+    else
+      raise "Access model invalid: #{model}"
+    end
+  end
+
+  private
+
+  def raise_existing_member_permissions
+    (joinable.memberships + joinable.membership_invitations).each do |membership|
+      membership.permissions = membership.permissions + permissions
+      membership.save!
+    end
+  end
+end

data/app/models/membership.rb

@@ -0,0 +1,59 @@
+class Membership < ActiveRecord::Base  
+  include Joinable::PermissionsAttributeWrapper
+
+  belongs_to :joinable, :polymorphic => true
+  belongs_to :user
+
+  before_save :prevent_locked_permission_changes, :normalize_owner_permissions
+
+  validates_presence_of :user_id
+  validates_uniqueness_of :user_id, :scope => [:joinable_type, :joinable_id] # Ensure that a User has only one Membership per Joinable
+  after_create :destroy_remnant_invitations_and_requests
+
+  attr_accessor :initiator, :locked
+  
+  def locked?
+    locked == 'true'
+  end
+  
+  def owner?
+    user == joinable.user
+  end
+
+  def permissions_locked?(current_user)
+    # Don't allow any changes to your own permissions
+    if current_user.eql?(user)
+      return true
+    # Don't allow any changes to the owner's permissions  
+    elsif owner?
+      return true
+    else
+      return false
+    end
+  end
+  
+  private
+
+  def prevent_locked_permission_changes
+    reload if locked?
+  end
+  
+  def normalize_owner_permissions
+    if owner?
+      self.permissions = joinable_type.constantize.permissions
+    else
+      self.permissions = permissions.reject {|level| level == :own}
+    end
+  end
+
+  def destroy_remnant_invitations_and_requests
+    # Make sure invitation is the first to be destroyed, for feed purposes.
+    if invitation = joinable.membership_invitation_for(user)
+      invitation.destroy
+    end
+
+    if request = joinable.membership_request_for(user)
+      request.destroy
+    end
+  end
+end

data/app/models/membership_invitation.rb

@@ -0,0 +1,42 @@
+class MembershipInvitation < ActiveRecord::Base
+  include Joinable::PermissionsAttributeWrapper
+  
+  belongs_to :joinable, :polymorphic => true
+  belongs_to :user
+  belongs_to :initiator, :class_name => "User"
+  validates_presence_of :user_id
+  validates_uniqueness_of :user_id, :scope => [:joinable_type, :joinable_id]
+
+  after_create :match_to_request_or_send_email
+  
+  def accept(current_user)
+    return false unless current_user == user
+    create_associated_membership_on_accept(current_user)
+  end
+  
+  def decline(current_user)
+    return false unless current_user == user
+    destroy_self_on_decline(current_user)
+  end
+
+  private
+
+  def create_associated_membership_on_accept(current_user)
+    Membership.create(:joinable => joinable, :user => user, :permissions => permissions)
+  end
+
+  def destroy_self_on_decline(current_user)
+    destroy
+  end
+
+  # When a User has already made a request and then someone invites this User to join the Joinable
+  # accept the invitation automatically on behalf of the user, otherwise notify the user
+  # that they have an invite waiting.
+  def match_to_request_or_send_email
+    if joinable.membership_request_for?(user)
+      accept(user)
+    else
+      UserMailer.invited_to_project_email(self).deliver
+    end
+  end
+end

data/app/models/membership_request.rb

@@ -0,0 +1,36 @@
+class MembershipRequest < ActiveRecord::Base
+  belongs_to :joinable, :polymorphic => true
+  belongs_to :user
+  
+  validates_presence_of :user_id
+  validates_uniqueness_of :user_id, :scope => [:joinable_type, :joinable_id]
+  
+  scope :for, lambda {|user|
+    joins("INNER JOIN memberships ON membership_requests.joinable_type = memberships.joinable_type AND membership_requests.joinable_id = memberships.joinable_id")
+    .where("memberships.user_id = ? AND 'manage' = ANY(memberships.permissions)", user.id)
+  }
+  
+  after_create :match_to_invitation_or_send_email
+  
+  def grant(current_user, permissions)
+    membership = create_associated_membership_on_grant(current_user, permissions)
+    UserMailer.project_membership_request_accepted_email(current_user, membership).deliver
+  end
+
+  private
+
+  def create_associated_membership_on_grant(current_user, permissions)
+    Membership.create(:joinable => joinable, :user => user, :permissions => permissions)
+  end
+
+  # If a user requests to join a joinable, make sure their isn't a matching invitation
+  # to join the joinable. If there is, then automatically accept the user into the joinable.
+  # Otherwise notify the managers of the project that their is a new request.
+  def match_to_invitation_or_send_email
+    if invitation = joinable.membership_invitation_for(user)
+      invitation.accept(invitation.user)
+    else
+      UserMailer.project_membership_request_created_email(joinable.who_can?(:manage), self).deliver
+    end
+  end
+end

data/app/models/permission_link.rb

@@ -0,0 +1,6 @@
+class PermissionLink < ActiveRecord::Base
+  belongs_to :joinable, :polymorphic => true
+  belongs_to :component, :polymorphic => true
+
+  validates_uniqueness_of :component_id, :scope => [:joinable_type, :joinable_id, :component_type]
+end

data/lib/acts_as_joinable.rb

@@ -0,0 +1,28 @@
+# GEM DEPENDENCIES
+require 'postgres_ext'
+
+require 'joinable/acts_as_permissable'
+require 'joinable/acts_as_joinable'
+require 'joinable/acts_as_joinable_component'
+require 'joinable/acts_as_member'
+
+require 'joinable/permissions_attribute_wrapper'
+
+module ActsAsJoinable
+  class Engine < Rails::Engine
+    initializer "acts_as_joinable.init" do
+      ActiveRecord::Base.send :extend, Joinable::ActsAsJoinable::ActMethod
+      ActiveRecord::Base.send :extend, Joinable::ActsAsJoinableComponent::ActMethod
+      ActiveRecord::Base.send :extend, Joinable::ActsAsMember::ActMethod
+    end   
+
+    config.to_prepare do
+      if defined?(ActsAsFeedable::Engine)
+        require 'joinable/feedable_extensions'
+        FeedableExtensions.add
+      else
+        puts "[ActsAsJoinable] ActsAsFeedable not loaded. Skipping extensions."
+      end
+    end
+  end
+end

data/lib/joinable/acts_as_joinable.rb

@@ -0,0 +1,326 @@
+module Joinable #:nodoc:
+  module ActsAsJoinable
+    module ActMethod
+      # Takes one option :component_permissions - a list of all of the permissions grouped by the component they affect
+      # eg. [{:labels => [:view, :apply, :remove, :create, :delete]}]
+      #
+      # The grouped permissions are unpacked to create distinct permissions (eg. view_labels, apply_labels, ...)
+      # These unpacked permissions are put into an array with the singular permissions (eg. find)
+      # and stored in a *permissions* class variable.
+      #
+      # In addition, The grouped permissions are stored in a separate *component_permissions_hashes* class variable.
+      # 
+      # NOTE: The permissions are passed in-order because in the view we expect to find certain permission patterns.
+      #       eg. the simple project permission level is determined by looking for a string of permissions that span
+      #       several components, (labels, writeboards, files, etc...).
+      # TODO: Remove the aforementioned order dependency      
+      def acts_as_joinable(options = {})
+        extend ClassMethods unless (class << self; included_modules; end).include?(ClassMethods)
+        include InstanceMethods unless included_modules.include?(InstanceMethods)
+
+        options.assert_valid_keys :component_permissions
+			  self.component_permissions_hashes = options[:component_permissions]
+
+			  self.permissions = [:find, :view]
+        add_flattened_component_permissions(options[:component_permissions])
+        self.permissions += [:manage, :own]
+      end
+
+      private
+
+      # Add explicit permissions to the permissions class accessor
+      # for each of the entries in the component_permission hashes
+      #
+      # eg. {:labels => [:view, :apply, :remove, :create, :delete]} becomes
+      #      [:view_labels, :apply_labels, :remove_labels, :create_labels, :delete_labels]
+      #      and is added to self.permissions
+      def add_flattened_component_permissions(component_permissions_hashes)
+        for component_permissions_hash in component_permissions_hashes
+  		    component_permissions_hash.each do |component_name, component_permissions|
+            component_permissions.each { |component_permission| self.permissions << "#{component_permission}_#{component_name}".to_sym }
+  		    end
+		    end
+      end
+    end
+
+    module ClassMethods
+      include Joinable::ActsAsPermissable::ClassMethods
+
+      def self.extended(base)
+        base.cattr_accessor :permissions, :component_permissions_hashes
+
+        base.has_many :membership_invitations, :as => :joinable, :dependent => :destroy, :before_add => :add_initiator
+  		  base.has_many :membership_requests, :as => :joinable, :dependent => :destroy
+  			base.has_many :memberships, :as => :joinable, :dependent => :destroy, :order => "id ASC", :before_remove => :add_initiator
+
+  			base.has_many :invitees, :class_name => "User", :through => :membership_invitations, :source => :user
+  		  base.has_many :requestees, :class_name => "User", :through => :membership_requests, :source => :user
+  		  base.has_many :members, :class_name => "User", :through => :memberships, :source => :user
+
+  			base.has_many :non_owner_memberships, :as => :joinable, :class_name => 'Membership', :conditions => "permissions NOT LIKE '%own%'"
+        base.has_one :owner_membership, :as => :joinable, :class_name => 'Membership', :conditions => "permissions LIKE '%own%'"
+
+  			base.has_many :permission_links, :as => :joinable, :dependent => :destroy
+
+  			base.has_one :default_permission_set, :as => :joinable, :dependent => :destroy
+
+  			base.after_create :add_owner_membership
+
+        base.class_eval do
+          # Return all *joinables* that a User is a member of with the appropriate permissions
+          scope :with_permission, lambda {|user, permission| where(with_permission_sql(user, permission)) }
+
+          #scope :open, lambda { where(default_permission_set_permission_exists_sql(joinable_type, joinable_id, 'find')) }
+
+          # TODO: Why is this NULLS LAST? Probably because we want the results in some specific order when joined with users, but couldn't we order manually in the find?
+          scope :with_member, lambda {|user| joins(:memberships).where(:memberships => {:user_id => (user.is_a?(User) ? user.id : user)}).order("memberships.created_at DESC NULLS LAST") }
+        end
+
+        base.accepts_nested_attributes_for :default_permission_set
+        base.accepts_nested_attributes_for :membership_invitations, :allow_destroy => true
+        base.accepts_nested_attributes_for :memberships, :allow_destroy => true, :reject_if => proc { |attributes| attributes['locked'] == 'true' }
+      end
+
+      def permissions_string
+        permissions.join(" ")
+      end
+
+      # Simple Permission Strings - Permission strings for four basic levels of permissions - viewer, collaborator, manager, owner
+      # =============================================
+      # Member can view everything but modify nothing
+      def viewer_permissions_string
+        viewer_permissions.join(" ")
+      end
+
+      def viewer_permissions
+        permissions.select { |permission| permission == :find || permission.to_s.starts_with?("view") }
+      end
+
+      # Member can view everything and modify everything except members
+      def collaborator_permissions_string
+        collaborator_permissions.join(" ")
+      end
+
+      def collaborator_permissions
+        permissions - [:manage, :own]
+      end
+
+      # Member can view everything, modify everything, and manage membership
+      def manager_permissions_string
+        (permissions - [:own]).join(" ")
+      end
+
+      # Member started the joinable
+      def owner_permissions_string
+        permissions_string
+      end
+      # =============================
+      # End Simple Permission Strings
+
+      # Returns the SQL necessary to find all joinables for which the user
+      # has a membership with a specific permission.
+      # 
+      # Permissions which require special handling:
+      #
+      # * find - In addition to memberships, invitations and default permission sets are checked for the permission. This is because
+      #          a joinable should be able to be found once an invitation has been extended or if it is findable by default. (even if the user isn't a member of it).
+      #
+      # * view_* - This is a class of permissions that start with the word 'view'. When determining if a user can view any aspect of a joinable, we also check
+      #            if the project is open.
+      #
+      # * join - This is a faux permission. A user has permission to join a joinable if they have an invitation to view it or if it is viewable by default.
+      #
+      # * collaborate - This is a faux permission. A user has permission to collaborate if they have any additional permissions above the standard viewer permissions.
+      def with_permission_sql(user, permission, options = {})
+        permission = permission.to_sym
+
+        case user
+        when String
+          user_id = user
+        when
+          user_id = user.id
+        end
+
+        joinable_type = options[:type_column] || name
+        joinable_id = options[:id_column] || table_name + ".id"
+
+        if permission == :find
+          "#{membership_permission_exists_sql(user_id, joinable_type, joinable_id, 'find')} OR #{membership_invitation_permission_exists_sql(user_id, joinable_type, joinable_id, 'find')} OR #{default_permission_set_permission_exists_sql(joinable_type, joinable_id, 'find')}"
+        elsif permission.to_s.starts_with?('view')
+          "#{membership_permission_exists_sql(user_id, joinable_type, joinable_id, permission)} OR #{default_permission_set_permission_exists_sql(joinable_type, joinable_id, permission)}"
+        elsif permission == :join
+          "#{membership_invitation_permission_exists_sql(user_id, joinable_type, joinable_id, 'view')} OR #{default_permission_set_permission_exists_sql(joinable_type, joinable_id, 'view')}"
+        elsif permission.to_s.starts_with?('join_and_')
+          default_permission_set_permission_exists_sql(joinable_type, joinable_id, permission.to_s.gsub('join_and_', ''))
+        elsif permission == :collaborate
+          "EXISTS (SELECT id FROM memberships WHERE memberships.joinable_type = '#{joinable_type}' AND memberships.joinable_id = #{joinable_id} AND memberships.user_id = #{user_id} AND memberships.permissions && '{#{(collaborator_permissions - viewer_permissions).join(",")}}')"
+        else
+          membership_permission_exists_sql(user_id, joinable_type, joinable_id, permission)
+        end
+      end
+
+      private
+
+      def membership_permission_exists_sql(user_id, joinable_type, joinable_id, permission)
+        "EXISTS (SELECT id FROM memberships WHERE memberships.joinable_type = '#{joinable_type}' AND memberships.joinable_id = #{joinable_id} AND memberships.user_id = #{user_id} AND #{permission_sql_condition('memberships.permissions', permission)})"
+      end
+
+      def membership_invitation_permission_exists_sql(user_id, joinable_type, joinable_id, permission)
+        "EXISTS (SELECT id FROM membership_invitations WHERE membership_invitations.joinable_type = '#{joinable_type}' AND membership_invitations.joinable_id = #{joinable_id} AND membership_invitations.user_id = #{user_id} AND #{permission_sql_condition('membership_invitations.permissions', permission)})"
+      end
+
+      def default_permission_set_permission_exists_sql(joinable_type, joinable_id, permission)
+        "EXISTS (SELECT id FROM default_permission_sets WHERE default_permission_sets.joinable_type = '#{joinable_type}' AND default_permission_sets.joinable_id = #{joinable_id} AND #{permission_sql_condition('default_permission_sets.permissions', permission)})"
+      end
+    end
+
+    module InstanceMethods
+      include Joinable::ActsAsPermissable::InstanceMethods
+
+      # Override attributes= to make sure that the user and initiator attributes are initialized before
+      # the membership_invitation and membership before_add callbacks are triggered
+      # since they reference these attributes
+      def attributes=(attributes_hash)
+        super(ActiveSupport::OrderedHash[attributes_hash.symbolize_keys.sort_by {|a| [:user, :user_id, :initiator].include?(a.first) ? 0 : 1}])
+      end
+      
+      def acts_like_joinable?
+        true
+      end
+
+      attr_accessor :cached_membership_request, :cached_membership_invitation, :cached_membership, :initiator
+
+      # Get the membership request (if any) for a specific
+      # user. This method also supports caching of a membership
+      # request in order to facilitate eager loading.
+      #
+      # eg. For all of the projects on the projects index page,
+      # we want to do something similar to
+      # Project.all(:include => :membership_requests).
+      #
+      # We can't do exactly that however because we only want the membership_requests
+      # related to the current_user, not all users.
+      #
+      # Instead, we fake it by doing a separate query
+      # which gets all the user's membership_requests related to
+      # all the projects being displayed. We then cache the request relevant to
+      # this project in the cached_membership_request instance variable for later use
+      # by the view.
+      def membership_request_for(user)
+        if cached_membership_request != nil
+          cached_membership_request
+        else
+          membership_requests.where(:user_id => user.id).first
+        end
+      end
+
+      # Find out whether this Joinable has a membership request for a certain user and return true, else false
+      def membership_request_for?(user)
+        !membership_request_for(user).nil?
+      end
+
+
+      # Get the membership invitation (if any) for a specific
+      # user. This method also supports caching of a membership
+      # request in order to facilitate eager loading.
+      #NOTE: See :membership_request_for documentation for an in depth example of this type of behaviour
+      def membership_invitation_for(user)
+        if cached_membership_invitation != nil
+          cached_membership_invitation
+        else
+          membership_invitations.where(:user_id => user.id).first
+        end
+      end
+      
+      # Find out whether this Joinable has a membership invitation for a certain user and return true, else false
+      def membership_invitation_for?(user)
+        !membership_invitation_for(user).nil?
+      end
+
+      # Get the membership (if any) for a specific
+      # user. This method also supports caching of a membership
+      # request in order to facilitate eager loading.
+      #NOTE: See :membership_request_for documentation for an in depth example of this type of behaviour
+      def membership_for(user)
+        if cached_membership != nil
+          cached_membership
+        else
+          memberships.where(:user_id => user.id).first
+        end
+      end
+
+      # Find out whether this Joinable has a membership for a certain user and return true, else false
+      def membership_for?(user)
+        !membership_for(user).nil?
+      end
+
+      # Returns the timestamp of the last time the memberships were updated for this joinable
+      def memberships_updated_at
+        memberships.maximum(:updated_at)
+      end
+
+      delegate :access_model, :to => :default_permission_set
+
+      def access_model=(model)
+        default_permission_set.access_model = model
+      end
+
+      # Returns true or false depending on whether or not the user has the specified permission for this object.
+      # Will cache the result if uncached.
+      def check_permission(user, permission_name)
+        permission_name = permission_name.to_s.dup
+
+        # Generate a cache path based on the factors that affect the user's permissions
+        # If User has membership
+        #  - depends on permissions
+        # Elsif User has been invited
+        #  - depends on existence of invitation and the default permissions (when checking the view permission)
+        # Else User doesn't have any membership
+        #  - depends on default permissions of the joinable
+        if membership = memberships.where(:user_id => user.id).first
+          key = "membership_#{membership.updated_at.to_f}"
+        elsif self.membership_invitations.where(:user_id => user.id).exists?
+          key = "default_permissions_#{self.default_permission_set.updated_at.to_f}_invitation_exists"
+        else
+          key = "default_permissions_#{self.default_permission_set.updated_at.to_f}"
+        end
+
+        cache_path = "permissions/#{self.class.table_name}/#{self.id}/user_#{user.id}_#{key}"
+
+        if defined?(RAILS_CACHE)
+          permissions = RAILS_CACHE.read(cache_path)
+          if permissions && (value = permissions[permission_name]) != nil
+            return value
+          end
+        end
+
+        # The permission isn't cached yet, so cache it
+        value = self.class.with_permission(user, permission_name).exists?(self.id)
+
+        if defined?(RAILS_CACHE)
+          if permissions
+            permissions = permissions.dup
+            permissions[permission_name] = value
+          else
+            permissions = {permission_name => value}
+          end
+          RAILS_CACHE.write(cache_path, permissions)
+        end
+        return value
+      end
+
+      private
+
+      # Adds an initiator to a membership or invitation to possibly use in feed generation
+      def add_initiator(membership)
+        membership.initiator = (initiator || user)
+      end
+
+      # Adds an permission entry with full access to the object by the user associated with the object if one does not already exist
+      def add_owner_membership
+       Membership.create(:joinable => self, :user => user, :permissions => self.class.permissions_string) unless Membership.where(:joinable_type => self.class.to_s, :joinable_id => self.id, :user_id => user.id).exists?
+      end
+    end
+  end
+end
+

data/lib/joinable/acts_as_joinable_component.rb

@@ -0,0 +1,223 @@
+module Joinable #:nodoc:
+  module ActsAsJoinableComponent
+    module ActMethod
+      # Inherits permissions of an a target object through the permission_links table
+      # An entry in the permission_links table is calculated by tracing the proxy object through to the target
+      # Takes a hash of params that specify which attached object the proxy should inherit its permissions from
+      def acts_as_joinable_component(options = {})
+        extend ClassMethods unless (class << self; included_modules; end).include?(ClassMethods)
+        include InstanceMethods unless included_modules.include?(InstanceMethods)
+        
+        options.assert_valid_keys :polymorphic, :parent, :view_permission
+        
+        class << self
+          attr_accessor :view_permission
+        end
+
+        self.view_permission = options[:view_permission]
+        
+        # If we inherit permissions from multiple types of objects (polymorphic)
+        if options[:polymorphic]
+          parent_klass = options[:parent] + '_type.constantize'
+          parent_id = options[:parent] + '_id'
+        # Else if we are not, and inherit permissions from only one type of object
+        else
+          parent_klass = options[:parent].camelize
+          parent_id = options[:parent] + '_id'
+        end
+        
+        # Rescue in case we haven't got a parent 
+        # TODO: this could probably be done better
+        class_eval <<-EOV
+          def next_link
+            begin
+              #{parent_klass}.find_by_id(#{parent_id})
+            rescue
+              nil
+            end
+          end
+        EOV
+      end
+    end
+
+    module ClassMethods
+      include Joinable::ActsAsPermissable::ClassMethods
+  
+      def self.extended(base)        
+        base.has_one :permission_link, :as => :component, :dependent => :destroy
+        base.after_create :find_joinable_and_create_permission_link
+
+        base.class_eval do
+          scope :with_permission, lambda { |user, permission| select("#{table_name}.*").where(with_permission_sql(user, permission)) }
+        end
+      end
+  
+      # Returns the SQL necessary to find all components for which there is no associated joinable or 
+      # the user has a membership with a specific permission.
+      # 
+      # Permissions which require special handling:
+      #
+      # * view_* - This is a class of permissions that start with the word 'view'. When determining if a user can view any aspect of a joinable, we also check
+      #            if the project is open.
+      #
+      # * join_and_* - This is a class of permissions that start with the words 'join_and_'. When determining if a user will have a certain permission
+      #                after they join a project, we need to check the default_permission_set of the project.
+      def with_permission_sql(user, permission, options = {})
+        permission = permission.to_s
+        
+        case user
+        when String
+          user_id = user
+        else
+          user_id = user.id
+        end
+    
+        component_type = options[:type_column] || name
+        component_id = options[:id_column] || table_name + ".id"
+
+        permission_without_join_and_prefix = permission.gsub('join_and_', '')
+        comparison_permission = permission_without_join_and_prefix == 'view' ? "permission_links.component_view_permission" : "'#{permission_without_join_and_prefix}'"
+
+        if permission.starts_with?('view')
+          "#{no_inherited_permissions_exist_sql(component_type, component_id)} OR #{membership_permission_exists_sql(user_id, component_type, component_id, comparison_permission)} OR #{default_permission_set_permission_exists_sql(component_type, component_id, comparison_permission)}"
+        elsif permission.starts_with?('join_and_')
+          default_permission_set_permission_exists_sql(component_type, component_id, comparison_permission)
+        else
+          "#{no_inherited_permissions_exist_sql(component_type, component_id)} OR #{membership_permission_exists_sql(user_id, component_type, component_id, comparison_permission)}"
+        end
+      end
+  
+      private
+  
+      # All components that don't have a permission link to a joinable
+      def no_inherited_permissions_exist_sql(component_type, component_id)
+        "NOT EXISTS (SELECT * FROM permission_links WHERE permission_links.component_type = '#{component_type}' AND permission_links.component_id = #{component_id})"
+      end
+  
+      # All components that have an associated membership with a specific permission
+      #
+      # The view permission requires special handling because it may be customized in the permission_link.
+      # For more information see the *recurse_to_inherit_custom_view_permission* method.
+      def membership_permission_exists_sql(user_id, component_type, component_id, comparison_permission)
+        "EXISTS (SELECT * FROM memberships 
+                               INNER JOIN permission_links ON memberships.joinable_type = permission_links.joinable_type
+                                    AND memberships.joinable_id = permission_links.joinable_id 
+                          WHERE permission_links.component_type = '#{component_type}' 
+                                AND permission_links.component_id = #{component_id} 
+                                AND memberships.user_id = #{user_id} 
+                                AND #{comparison_permission} = ANY(memberships.permissions))"
+      end
+
+      def default_permission_set_permission_exists_sql(component_type, component_id, comparison_permission)
+        "EXISTS (SELECT * FROM default_permission_sets
+                                 INNER JOIN permission_links ON default_permission_sets.joinable_type = permission_links.joinable_type
+                                      AND default_permission_sets.joinable_id = permission_links.joinable_id
+                            WHERE permission_links.component_type = '#{component_type}'
+                                  AND permission_links.component_id = #{component_id}
+                                  AND #{comparison_permission} = ANY(default_permission_sets.permissions))"
+      end
+    end
+
+    module InstanceMethods
+      include Joinable::ActsAsPermissable::InstanceMethods
+
+      def acts_like_joinable_component?
+        true
+      end
+      
+      # Used by unsaved joinable_components to return a list of users
+      # who will be able to view the component once it is saved.
+      # Useful for outputting information to the user while they 
+      # are creating a new component.
+      def who_will_be_able_to_view?
+        User.find_by_sql("SELECT users.* 
+                          FROM users JOIN memberships ON users.id = memberships.user_id 
+                          WHERE memberships.joinable_type = '#{joinable.class.to_s}' 
+                          AND memberships.joinable_id = #{joinable.id} 
+                          AND #{self.class.permission_sql_condition('memberships.permissions', recurse_to_inherit_custom_view_permission)}")
+      end
+
+      def check_permission(user, permission)
+        # You can't ask to join joinable_components so the find permission is actually the view permission
+        permission = :view if permission == :find
+        
+        if new_record?
+          if joinable.acts_like?(:joinable)
+            permission = recurse_to_inherit_custom_view_permission if permission == :view
+            joinable.check_permission(user, permission)
+          else
+            # The component isn't contained by a joinable so it is public.
+            true
+          end
+        else
+          self.class.with_permission(user, permission).exists?(id)
+        end
+      end
+  
+      # Returns the object that we should inherit permissions from
+      #
+      # Recurses until the target is reached, 
+      # if we reach a target that does not act as a joinable, call method again if it is a joinable component, 
+      # else fall out as the chain has no valid endpoint (eg. feed -> discussion -> item)
+      def joinable
+        if permission_link.present?
+          permission_link.joinable
+        else
+          parent = next_link
+          
+          # Our target is now joinable therefore our target is at the end (eg. feed -> discussion -> [project])
+          if parent && parent.acts_like?(:joinable)
+            return parent
+
+          # Our target is a joinable_component therefore our target somewhere between the beginning and the end (eg. feed -> [discussion] -> ??? -> project)
+          elsif parent && parent.acts_like?(:joinable_component)
+            return parent.joinable
+
+          # We've fallen out because there was either no target or the target was not joinable or a joinable_component
+          else
+            return parent
+          end
+        end
+      end
+
+      # inherited_view_permission is calculated by ascending up the chain of joinable components
+      # while view permission only takes into account the current joinable component.
+      # inherited_view_permission is for external use while view_permission should only be used internally.
+      def inherited_view_permission
+        permission_link.try(:component_view_permission)
+      end
+
+      def view_permission
+        klass_view_permission = self.class.view_permission
+        klass_view_permission = klass_view_permission.call(self) if klass_view_permission.respond_to?(:call)
+
+        # Allow view_permission to be set at the instance level
+        return @view_permission || klass_view_permission
+      end
+      attr_writer :view_permission
+
+
+      # Recurse up the tree to see if any of the intervening joinable_components have a customized view permission
+      # In that case, inherit that customized view permission. This allows searches of the form
+      # Feed.with_permission(:view) where feeds belong to joinable_components with custom view permissions.
+      # The query will then be able to return only the feeds which belong to joinable components that are viewable by the user
+      def recurse_to_inherit_custom_view_permission
+        parent = next_link
+
+        # If we've reached the last component in the chain or if this component provides a view permission
+        if parent.acts_like?(:joinable) || self.view_permission
+          return self.view_permission || :view
+        elsif parent.acts_like?(:joinable_component)
+          return parent.recurse_to_inherit_custom_view_permission
+        else
+          return nil
+        end
+      end
+
+      # Creates a link to the joinable that this component is associated with, if there is one.
+      def find_joinable_and_create_permission_link
+        self.create_permission_link(:joinable => joinable, :component_view_permission => recurse_to_inherit_custom_view_permission) if joinable.acts_like?(:joinable)
+      end
+    end
+  end
+end

data/lib/joinable/acts_as_member.rb

@@ -0,0 +1,43 @@
+# Adds useful methods to the User model which includes it.
+module Joinable #:nodoc:
+  module ActsAsMember  
+    module ActMethod
+      def acts_as_member
+        extend ClassMethods unless (class << self; included_modules; end).include?(ClassMethods)
+        include InstanceMethods unless included_modules.include?(InstanceMethods)
+      end
+    end
+
+    module ClassMethods
+      def self.extended(base)
+        base.has_many :memberships, :dependent => :destroy
+        base.has_many :membership_requests, :dependent => :destroy
+        base.has_many :membership_invitations, :dependent => :destroy
+      end
+    end
+
+    module InstanceMethods
+      # FIXME: no need to call permission_to? on non-permissables. 
+      # We should remove this extra code.
+      def permission_to?(permission, record)
+        if record.acts_like?(:permissable)
+          record.check_permission(self, permission)
+        else
+          if record.acts_like?(:visible_only_to_owner)
+            record.user == self
+          else
+            true
+          end
+        end
+      end
+    
+      def no_permission_to?(permission, record)
+        !permission_to?(permission, record)
+      end
+    
+      def membership_requests_for_managed_joinables
+        MembershipRequest.for(self)
+      end
+    end
+  end
+end

data/lib/joinable/acts_as_permissable.rb

@@ -0,0 +1,29 @@
+# Abstract Module that is included in both joinable and joinable_component. Includes useful methods that both share.
+module Joinable #:nodoc:
+  module ActsAsPermissable
+    module ClassMethods
+  		def find_with_privacy(record_id, user, options = {})
+  			record = find(record_id)
+			
+  			raise ActiveRecord::RecordNotFound, (options[:error_message] || "Couldn't find #{name}") unless user.permission_to?(:find, record)
+		
+  		  return record
+  		end
+  		
+  		def permission_sql_condition(column, permission)
+  		  "'#{permission}' = ANY(#{column})"
+		  end
+    end
+
+    module InstanceMethods
+      def acts_like_permissable?
+        true
+      end
+    
+      # Returns a list of users who either do or do not have the specified permission.
+      def who_can?(permission)
+        User.find_by_sql("SELECT * FROM users AS u1 WHERE #{self.class.with_permission_sql('u1.id', permission, :id_column => id)}")
+      end
+    end
+  end
+end

data/lib/joinable/feedable_extensions.rb

@@ -0,0 +1,34 @@
+module FeedableExtensions
+  def self.add
+    Feed.class_eval do
+      # Filter feeds about public joinables that you haven't joined, unless the feed is actually about you
+      scope :without_unjoined, lambda {|joinable_type, user| 
+        where("feeds.scoping_object_type IS NULL OR
+               feeds.scoping_object_type != '#{joinable_type}' OR
+               (feeds.feedable_type = 'User' AND feeds.feedable_id = #{user.id}) OR
+               EXISTS (SELECT * FROM memberships WHERE memberships.joinable_type = '#{joinable_type}' AND memberships.joinable_id = feeds.scoping_object_id AND memberships.user_id = ?)", user.id)
+      }
+
+      acts_as_joinable_component :parent => 'permission_inheritance_target', :polymorphic => true, :view_permission => lambda {|feed| :find if feed.feedable.acts_like?(:joinable) }
+      
+      # The scoping_object becomes the parent if the feed is delegated to a non-permissable or the feedable is deleted
+      # eg. a user (non-permissible) leaves a project, the parent of the feed is the project since a user isn't a permissable
+      # eg. a writeboard is destroyed, the parent of the feed is now the project
+      def permission_inheritance_target_type
+        if feedable.acts_like?(:permissable)
+          feedable_type
+        else
+          scoping_object_type
+        end
+      end
+      
+      def permission_inheritance_target_id
+        if feedable.acts_like?(:permissable)
+          feedable_id
+        else
+          scoping_object_id
+        end
+      end
+    end
+  end
+end

data/lib/joinable/permissions_attribute_wrapper.rb

@@ -0,0 +1,164 @@
+# Included in models which have a permissions field (Membership, MembershipInvitation, DefaultPermissionSet)
+# Wraps the permissions field to make it appear to the outside world as an array of symbols rather than the
+# string that it is stored in the database as. Also adds helpers for creating complex forms 
+# to configure permissions and validations to ensure consistent ordering of permissions in the database.
+module Joinable #:nodoc:
+  module PermissionsAttributeWrapper
+    def self.included(base)
+      base.before_save :verify_and_sort_permissions
+    end
+  
+    def permissions_string
+      self[:permissions].join(' ')
+    end
+  
+    # Returns an array of the permissions as symbols
+    def permissions
+      self[:permissions].collect(&:to_sym)
+    end
+  
+    def permissions=(permissions)
+      case permissions
+      when String
+        self[:permissions] = permissions.split(' ')
+      when Array
+        self[:permissions] = permissions
+      else
+        raise "Permissions were not passed to permissions writer in the appropriate format"
+      end
+    end
+  
+    # Used by advanced permission forms which group permissions by their associated component
+    # or using a single check box per permission.
+    def permission_attributes=(permissions)
+      self.permissions = [] # Reset permissions in anticipation for re-population
+    
+      permissions.each do |key, value|
+        key, value = key.dup, value.dup
+      
+        # Component Permissions
+        if key.ends_with? "_permissions"
+          grant_permissions(value)
+        # Singular Permission
+        elsif key.chomp! "_permission"
+          grant_permissions(key) if value.to_i != 0
+        end
+      end
+    end
+  
+    # Returns an array of the permissions allowed by the joinable
+    def allowed_permissions
+      if self[:joinable_type]
+        self[:joinable_type].constantize.permissions
+      else
+        raise "Cannot get allowed access levels because permission is not attached to a permissable yet: #{inspect}"
+      end
+    end
+
+    # Returns true if the object has all the permissions specified by +levels+
+    def has_permission?(*levels)
+      if levels.all? { |level| permissions.include? level.to_sym }
+        return true
+      else
+        return false
+      end
+    end
+
+    # Returns true if none of the permissions specified by +levels+ are present
+    def doesnt_have_permission?(*levels)
+      if permissions - levels == permissions
+        return true
+      else
+        return false
+      end
+    end
+
+    # Returns true if the object has an empty permission set
+    def no_permissions?
+      permissions.empty?
+    end
+
+    # Returns true if the object only has the permissions in +levels+
+    def only_permission_to?(*levels)
+      if permissions - levels == []
+        return true
+      else
+        return false
+      end
+    end
+  
+    def grant_permissions(permissions_to_grant)
+      case permissions_to_grant
+      when String
+        permissions_to_grant = permissions_to_grant.split(' ').collect(&:to_sym)
+      when Symbol
+        permissions_to_grant = [permissions_to_grant]
+      end
+    
+      self.permissions += permissions_to_grant
+    end
+  
+    private
+  
+    # Verifies that all the access levels are valid for the attached permissible
+    # Makes sure no permissions are duplicated
+    # Enforces the order of access levels in the access attribute using the order of the permissions array
+    def verify_and_sort_permissions
+      # DefaultPermissionSet is allowed to have blank permissions (private joinable), the other models need at least find and view
+      self.permissions += [:find, :view] unless is_a?(DefaultPermissionSet)
+    
+      raise "Invalid permissions: #{(permissions - allowed_permissions).inspect}. Must be one of #{allowed_permissions.inspect}" unless permissions.all? {|permission| allowed_permissions.include? permission}
+    
+      self.permissions = permissions.uniq.sort_by { |permission| allowed_permissions.index(permission) }
+    end
+  
+    # Adds readers for component permission groups and single permissions
+    #
+    # Used by advanced permission forms to determine how which options to select
+    # in the various fields. (eg. which option of f.select :labels_permissions to choose)
+    def method_missing(method_name, *args)
+      # add permission_for accessors and mutators
+    
+      # NOTE: Don't mess with the method_name variable (e.g. change it to a string)
+      # since upstream methods might assume it is a symbol.
+      # NOTE: Ensure we enforce some characters before the '_permission' suffix because Rails 3 creates 
+      if respond_to?(:joinable_type) && joinable_type.present?
+        if method_name.to_s =~ /.+_permissions/
+          return component_permissions_reader(method_name)
+        elsif method_name.to_s =~ /.+_permission/
+          return single_permission_reader(method_name)
+        else
+          super
+        end
+      else
+        super
+      end
+    end
+  
+    # Get a string of all of the permissions the object has for a specific joinable component
+    # eg. labels_permissions # returns 'view_labels apply_labels remove_labels'
+    def component_permissions_reader(method_name)
+      for component_permissions_hash in joinable_type.constantize.component_permissions_hashes
+        component_permissions_hash.each do |component_name, component_permissions|
+          if method_name.to_s == "#{component_name}_permissions"
+            return component_permissions.collect {|permission| "#{permission}_#{component_name}"}.select {|permission| has_permission?(permission)}.join(" ")
+          end
+        end
+      end
+    
+      raise "Unknown component_permissions_reader #{method_name.inspect}"
+    end
+  
+    # Access a single permission
+    # eg. manage_permission # returns true if we can manage
+    def single_permission_reader(method_name)
+      for permission in joinable_type.constantize.permissions
+        if method_name.to_s == "#{permission}_permission"
+          return has_permission?(permission)
+        end
+      end
+    
+      raise "Unknown single_permission_reader #{method_name.inspect}"
+    end
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: acts_as_joinable
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Ryan Wallace
+- Nicholas Jakobsen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: postgres_ext
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.2.2
+description: Adds access control to objects by giving them members, each with configurable
+  permissions.
+email: technical@rrnpilot.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- app/models/default_permission_set.rb
+- app/models/membership.rb
+- app/models/membership_invitation.rb
+- app/models/membership_request.rb
+- app/models/permission_link.rb
+- lib/acts_as_joinable.rb
+- lib/joinable/acts_as_joinable.rb
+- lib/joinable/acts_as_joinable_component.rb
+- lib/joinable/acts_as_member.rb
+- lib/joinable/acts_as_permissable.rb
+- lib/joinable/feedable_extensions.rb
+- lib/joinable/permissions_attribute_wrapper.rb
+- README.rdoc
+homepage: http://github.com/rrn/acts_as_joinable
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: An easy to use permissions system
+test_files: []