troles 0.5.0

data/lib/troles/adapters/active_record/config.rb

@@ -0,0 +1,51 @@
+module Troles::ActiveRecord
+  class Config < Troles::Common::Config  
+
+    attr_accessor :role_join_model
+    
+    def initialize clazz, options = {}
+      super 
+    end
+    
+    def configure_relation
+      case strategy
+      when :ref_many
+        return configure_join_model if role_join_model
+        has_and_belongs_many clazz, role_model, :key => :accounts         
+      when :embed_many
+        raise "Embed many configuration not yet implemented for ActiveRecord" 
+      end
+    end
+
+    # AR sets this up ont its own using DB Table info
+    def configure_field
+    end
+    
+    protected
+
+    def join_key
+      make_key role_join_model
+    end
+    
+    def join_model
+      # UserAccount
+      # has_many :troles, :class_name => 'Role', :through => :users_roles
+      has_many_for clazz, role_model, :through => join_key 
+      # has_many :user_roles, :class_name => 'UserRole'
+      has_many_for clazz, role_join_model, :key => join_key
+
+      # UserRole (custom join class name)
+      # belongs_to :user, :class_name => 'UserAccount'      
+      belongs_to_for role_join_model, clazz
+      # belongs_to :role, :class_name => 'Role'      
+      belongs_to_for role_join_model, role_model
+
+      # Role
+      # has_many :accounts, :class_name => 'User', :through => :user_roles      
+      has_many_for role, clazz, :through => join_key, :key => :accounts
+
+      # has_many :user_roles, :class_name => 'UserRole'
+      has_many_for role, role_join_model, :key => join_key      
+    end
+  end
+end

data/lib/troles/adapters/active_record/storage/embed_many.rb

@@ -0,0 +1,8 @@
+# Could use the AR serializer feature, to save the embedded roles as YAML
+module Troles::ActiveRecord::Storage
+  class StringMany < Troles::Storage::StringMany
+    def initialize role_subject
+      super
+    end
+  end
+end

data/lib/troles/adapters/active_record/storage.rb

@@ -0,0 +1,5 @@
+module Troles::ActiveRecord
+  module Storage
+    autoload :EmbedMany,    'troles/adapters/active_record/strategy/embed_many'
+  end
+end

data/lib/troles/adapters/active_record/strategy.rb

@@ -0,0 +1,11 @@
+module Troles::ActiveRecord
+  module Strategy    
+    module BaseMany
+      # @param [Class] the role subject class for which to include the Role strategy (fx User Account)
+      #
+      def self.included(base)
+        base.send :include, Troles::Strategy::BaseMany        
+      end      
+    end
+  end
+end

data/lib/troles/adapters/active_record.rb

@@ -0,0 +1,8 @@
+module Troles
+  module ActiveRecord
+    autoload :Config,     'troles/adapters/active_record/config'
+    # autoload :Api,        'troles/adapters/active_record/api'
+    autoload :Storage,    'troles/adapters/active_record/storage'
+    autoload :Strategy,   'troles/adapters/active_record/strategy'
+  end
+end

data/lib/troles/adapters/mongoid/Design Notes.textile

@@ -0,0 +1,3 @@
+h1. Design Notes for Mongoid adapter
+
+We have to come up with an easier way to initialize the Config object than to do the whole API thing!

data/lib/troles/adapters/mongoid/config.rb

@@ -0,0 +1,45 @@
+module Troles::Mongoid
+  class Config < Troles::Common::Config  
+    
+    def initialize clazz, options = {}
+      super
+    end
+
+    # more likely, strategy should be part of configuration options directly when Config object is created!
+    def configure_relation
+      case strategy
+      when :ref_many      
+        has_many_for clazz, :role, :through => join_key 
+        
+        belongs_to_for join_model, :user
+        belongs_to_for join_model, :role
+
+        has_many_for role, :user, :through => join_key 
+        
+      when :embed_many
+        embeds_many clazz, :role
+      end
+    end
+    
+    def configure_field
+      type = case strategy
+      when :bit_many
+        Integer
+      when :string_many
+        String
+      end
+      # field :name, :type => String       
+      clazz.send(:field, role_field, type_opts(type)) if type      
+    end     
+    
+    def type_opts type
+      { :type => type }
+    end
+    
+    protected
+    
+    def embeds_many from, to
+      make_relationship :embeds_many, from, to
+    end    
+  end
+end

data/lib/troles/adapters/mongoid.rb

@@ -0,0 +1,8 @@
+module Troles
+  module Mongoid
+    autoload :Config,     'troles/adapters/mongoid/config'
+    # autoload :Api,        'troles/adapters/mongoid/api'
+    # autoload :Storage,    'troles/adapters/mongoid/storage'
+    # autoload :Strategy,   'troles/adapters/mongoid/strategy'
+  end
+end

data/lib/troles/api/cache.rb

@@ -0,0 +1,4 @@
+module Troles::Api
+  module Cache
+  end
+end

data/lib/troles/api/config.rb

@@ -0,0 +1,9 @@
+# 
+# @author Kristian Mandrup
+#
+# Many roles Config Api
+#
+module Troles::Api
+  module Config
+  end  
+end

data/lib/troles/api/core.rb

@@ -0,0 +1,9 @@
+module Troles::Api
+  module Core    
+    module ClassMethods      
+      def role_field
+        troles_config.role_field
+      end      
+    end
+  end
+end

data/lib/troles/api/event.rb

@@ -0,0 +1,4 @@
+module Troles::Api
+  module Event
+  end
+end

data/lib/troles/api/read.rb

@@ -0,0 +1,4 @@
+module Troles::Api
+  module Read
+  end
+end

data/lib/troles/api/validation.rb

@@ -0,0 +1,4 @@
+module Troles::Api
+  module Validation
+  end
+end

data/lib/troles/api/write.rb

@@ -0,0 +1,4 @@
+module Troles::Api
+  module Write
+  end
+end

data/lib/troles/api.rb

@@ -0,0 +1,40 @@
+# 
+# @author Kristian Mandrup
+#
+# Many roles Api to be included directly on the role subject class (fx User or User Account)
+#
+module Troles
+  module Api
+    autoload :Core,       'troles/api/core'
+    autoload :Config,     'troles/api/config'
+    autoload :Cache,      'troles/api/cache'
+            
+    autoload :Event,      'troles/api/event'
+    autoload :Read,       'troles/api/read'
+    autoload :Store,      'troles/api/store'    
+    autoload :Validation, 'troles/api/validation'
+    autoload :Write,      'troles/api/write'
+
+    module ClassMethods      
+      #
+      # When the Troles::Api is included by the Role Subject class (fx a User Account)
+      # first include methods from Troles Common API      
+      # then include Troles API on top
+      #
+      # @param [Class] the role subject class (fx User or UserAccount)
+      #
+      def included(base)
+        base.send :include, Troles::Common::Api
+        self.extend Troles::Common::Api::ClassMethods # draws in the #apis method from Common Api
+        apis.each do |api|
+          begin
+            base.send :include, "Troles::Api::#{api.to_s.camelize}".constantize
+            base.extend "Troles::Api::#{api.to_s.camelize}::ClassMethods".constantize
+          rescue
+          end
+        end
+      end      
+    end
+    extend ClassMethods
+  end
+end

data/lib/troles/common/api/cache.rb

@@ -0,0 +1,12 @@
+#
+# @author Kristian Mandrup
+#
+# Caching Api to ensure the role list of a role subject is cached and invalidated on role change 
+#
+module Troles::Common::Api
+  module Cache
+    def invalidate_role_cache!
+      @role_list = nil      
+    end
+  end  
+end

data/lib/troles/common/api/config.rb

@@ -0,0 +1,4 @@
+module Troles::Common::Api
+  module Config
+  end
+end

data/lib/troles/common/api/core.rb

@@ -0,0 +1,52 @@
+#
+# @author Kristian Mandrup
+#
+# Core Troles API functions
+#
+module Troles::Common::Api
+  module Core
+    
+    # Access to the Troles operations API
+    # @return [Troles::Operations] the operations API object 
+    def roles
+      @roles ||= Troles::Operations.new(self)
+    end       
+
+    # Sets the roles of the subject
+    # (see #set_roles)
+    def roles= *new_roles
+      roles.set_roles new_roles
+    end       
+
+    # If this role subject instance should have static (immutable) roles
+    # @return [true, false] defaults to false so a role subject is allowed to change roles 
+    def static_roles?
+      false
+    end
+
+    def troles_config
+      self.class.troles_config      
+    end
+        
+    module ClassMethods            
+      
+      def valid_roles
+        troles_config.valid_roles
+      end
+
+      # # TODO: make sure alphanumeric only
+      # def valid_roles= *roles
+      #   troles_config.valid_roles = *roles
+      # end
+
+      # If all role subjects using this strategy should have static (immutable) roles
+      #
+      # @note Should also proxy Config object?      
+      #
+      # @return [true, false] if role subjects have static roles or not (default: false)
+      def static_roles?
+        troles_config.static_roles_for_class?
+      end           
+    end
+  end
+end

data/lib/troles/common/api/event.rb

@@ -0,0 +1,39 @@
+#
+# @author Kristian Mandrup
+# 
+# Event API
+#
+module Troles::Common::Api
+  module Event
+    # A change to the roles of the user should be published to an event handler
+    # this can be used to update both the Role cache of the user and fx the RolePermit cache.
+    # A Role Groups listener can also subscribe to this event
+    def update_roles
+      publish_change(:roles) if role_field_changed?(troles_config.role_field)
+    end
+
+    # Check if a field on the model changed
+    # For Rails 3, See http://api.rubyonrails.org/classes/ActiveModel/Dirty.html
+    # @param [String] the field to test for change
+    def role_field_changed? name
+      begin
+        send :"#{name}_changed?"
+      rescue
+        false
+      end
+    end
+
+    # Publishes change event to the EventManager configured
+    # The EventManager is notied of the even type and who (which instance) sent it
+    # @param [Symbol] the event
+    def publish_change event
+      send :invalidate_role_cache! if event == :roles
+      event_manager.publish_change event, :from => self
+    end
+
+    # @return [Trole::EventManager] The event manager singleton (class) to use to handle role events 
+    def event_manager
+      Troles::Common::EventManager
+    end
+  end
+end

data/lib/troles/common/api/read.rb

@@ -0,0 +1,44 @@
+# @author Kristian Mandrup
+#
+# Common Read API
+#
+require 'set'
+
+module Troles::Common::Api
+  module Read
+
+    # Ensures that the common API methods always have a common underlying model to work on
+    # @note This Set should be cached and only invalidated when the user has a change of roles    
+    # @return Array<Symbol> Set of role names
+    def role_list        
+      @role_list ||= begin
+        store.display_roles.flatten
+      end
+    end
+        
+    # Does the role subject has the role or not?
+    # @return [true, false]
+    def has_role? role
+      role_list.include? role.to_sym
+    end
+
+    # Does the role subject have ONLY that role or not?
+    # @return [true, false]
+    def is_role? role
+      role_list.first == role.to_sym && role_list.size == 1
+    end
+    
+    # Checks if the role subject has any of the listed roles
+    # @param [Array<Symbol>]
+    # @return [true, false]
+    def has_roles? *roles
+      (roles.to_symbols - role_list).empty?
+    end
+
+    # Checks if the role subject has any of the listed roles
+    # (see #has_roles?)
+    def has_any_role? *roles
+      !(role_list & roles.to_symbols).empty?
+    end    
+  end
+end

data/lib/troles/common/api/validation.rb

@@ -0,0 +1,44 @@
+#
+# @author Kristian Mandrup
+# 
+# Common Validation API
+#
+module Troles::Common::Api
+  module Validation
+
+    # @return [Symbol, false] returns the role if it's valid, false if not
+    def check_valid_role? role
+      return role if valid_roles.include? role.to_sym
+      false
+    end
+
+    # @return [Array<Symbol>] returns the valid roles or empty list if no valid roles
+    def check_valid_roles? *roles
+      valid_roles & roles.to_symbols     
+    end
+    
+    protected
+
+    # Ensures the role is valid
+    # @param [Symbol] role name
+    # @return [Symbol, false, Error] a valid role name, false if invalid, or Error on some error
+    def make_valid_role role
+      raise ArgumentError, "Role to set must be a Symbol or String" if !role.kind_of_label?
+      check_valid_role? role.to_s.alpha_numeric
+    end
+
+    # Ensures the role are valid
+    # @param [Symbol] list of roles
+    # @return [Array<Symbol>] the valid roles from the list of roles given
+    def make_valid_roles *roles      
+      roles = roles.to_symbols_uniq
+      return [] if roles.empty?                
+      check_valid_roles? roles.map{|r| r.to_s.alpha_numeric}
+    end
+
+    # @return [Array<Symbol>] the valid roles of the role subject
+    def valid_roles
+      self.class.troles_config.valid_roles
+    end
+  end
+end

data/lib/troles/common/api/write.rb

@@ -0,0 +1,76 @@
+# @author Kristian Mandrup
+#
+# @note all methods should operate on the data store via the #store
+#
+module Troles::Common::Api
+  module Write
+
+    # Do we need a static_roles! method? I think so!
+    def static_role! role_name
+      raise ArgumentError, "Take a single role name, was: #{role_name}" if !role_name || !role_name.kind_of_label?
+      troles_config.add_valid_roles role_name
+      if set_roles role_name      
+        define_method :static_roles? do
+          true
+        end
+      end
+    end
+        
+    # Add a single new role to the roles of the subject
+    # @param  [Symbol] role to add
+    # @return (see #add_roles)
+    def add_role role_name
+      raise ArgumentError, "Take a single role name, was: #{role_name}" if !role_name || !role_name.kind_of_label?
+      add_roles role_name
+    end  
+
+    # Remove a single role from the roles of the subject
+    # @param  [Symbol] role to remove
+    # @return (see #remove_roles)
+    def remove_role role_name
+      raise ArgumentError, "Take a single role name, was: #{role_name}" if !role_name || !role_name.kind_of_label?
+      remove_roles role_name
+    end    
+
+    # Adds a set of new roles to the roles of the subject
+    # @param  [Array<Symbol>] list of roles to add
+    # @return [true, false, Error] true if ok, false if static or invalid, Error on some error
+    def add_roles *new_roles      
+      store.set_roles (role_list | new_roles.to_symbols_uniq) # Set Union (joined set)
+    end  
+
+    # Removes a set of new roles to the roles of the subject
+    # (see #add_roles)
+    def remove_roles *the_roles
+      store.set_roles (role_list - the_roles.to_symbols_uniq)
+    end  
+
+    # Sets new roles for the subject
+    # @param [Array<Symbol>] list of role names
+    # @return [true, false, Error] true if set ok, false if any roles were invalid, Error on some error 
+    def set_roles *roles
+      roles_to_set = make_valid_roles(*roles).flat_uniq
+      return false if !roles_to_set || roles_to_set.empty?
+      store.set_roles(roles_to_set) 
+    end  
+
+    # Clears all the roles of the subject
+    # @return [true, false, Error] true if ok, false if roles are static, Error on some error 
+    def clear_roles!
+      store.clear!
+    end  
+    
+    module ClassMethods
+      # Sets which roles are valid for the role subject class (fx User or UserAccount)
+      #
+      # @note this in effect limits what roles can be assigned to any instance of the class
+      #
+      # @param [Array<Symbol>] list of role names
+      def set_valid_roles *roles
+        roles = roles.to_symbols_uniq
+        raise ArgumentError, "Roles must contain Symbols or Strings" if roles.empty?
+        @valid_roles = roles
+      end      
+    end          
+  end
+end

data/lib/troles/common/api.rb

@@ -0,0 +1,28 @@
+module Troles::Common
+  module Api
+    autoload :Core,       'troles/common/api/core'
+    autoload :Cache,      'troles/common/api/cache'
+    autoload :Config,     'troles/common/api/config'
+    autoload :Event,      'troles/common/api/event'
+    autoload :Read,       'troles/common/api/read'
+    autoload :Write,      'troles/common/api/write'
+    autoload :Validation, 'troles/common/api/validation'
+
+
+    module ClassMethods
+      def apis
+        [:core, :cache, :config, :event, :read, :validation, :write]
+      end
+
+      def included(base)
+        apis.each do |api|
+          begin
+            base.include_and_extend :"#{api.to_s.camelize}"
+          rescue
+          end
+        end      
+      end
+    end
+    extend ClassMethods
+  end
+end

data/lib/troles/common/config/schema.rb

@@ -0,0 +1,72 @@
+module Troles::Common
+  class Config
+    module Schema
+      attr_accessor :join_model
+
+      def configure_role_field
+        configure_generic
+        configure_field
+        configure_relation
+      end         
+
+      def configure_generic                    
+        clazz.send(:attr_accessor, role_field)  if generic? || orm == :generic # create troles accessor      
+      end
+
+      # Adapter should customize this as needed 
+      def configure_field
+      end
+
+      # Adapter should customize this as needed 
+      def configure_relation
+      end
+
+      def join_model
+        @join_model ||= begin
+          return UsersRoles if defined? UsersRoles
+          raise "Join model not defined"
+        end
+      end
+
+      def join_model= model_class
+        @join_model = model_class and return if model_class.kind_of?(Class)
+        raise "The role model must be a Class, was: #{model_class}"
+      end
+
+      # Sets the role model to use
+      # allows different role subject classes (fx User Accounts) to have different role schemas
+      # @param [Class] the model class
+      def role_model= model_class
+        @role_model = model_class.to_s and return if model_class.any_kind_of?(Class, String, Symbol)
+        raise "The role model must be a Class, was: #{model_class}"
+      end
+
+      # Gets the role model to be used
+      # see (#role_model=)
+      # @return [Class] the model class (defaults to Role)
+      def role_model
+        @role_model_found ||= begin
+          models = [@role_model, 'Role'].select do |class_name|
+            try_class(class_name.to_s)
+          end.compact
+          # puts "role models found: #{models}"
+          raise "No Role class defined, define Role one or set using #role_model method on config" if models.empty?
+          models.first.to_s.constantize
+        end
+      end
+
+      protected
+
+      def try_class clazz
+        begin
+          clazz = clazz.constantize if clazz.kind_of?(String)
+          clazz
+        rescue          
+          false
+        end
+      end
+                     
+      include SchemaHelpers
+ end
+  end
+end