troles 0.5.0 → 0.5.1

data/Gemfile.lock

@@ -129,7 +129,7 @@ GEM
       rack (~> 1.0)
       tilt (!= 1.3.0, ~> 1.1)
     sqlite3 (1.3.3)
-    sugar-high (0.4.4.1)
+    sugar-high (0.4.4.2)
     thor (0.14.6)
     tilt (1.3.2)
     treetop (1.4.9)

data/README.textile

@@ -6,23 +6,61 @@ The project currently consists of:
 
 * Trole - for single role strategies 
 * Troles - for many roles strategies
+* TroleGroups - for groups of roles
 
 The Troles project uses _role caching_ to optimize performance! 
 The roles list cache of a role subject (fx a user) is only updated (retrieved from data store) when the roles of the role subject changes!
 
 Note: Troles is a full redesign of _roles generic_ and company, using lessons learned. Troles uses a much cleaner design. It is aimed at being easy to extend and easy to create adapters for etc.
 
-h2. Status June 2, 2011
+h2. Status June 7, 2011 
 
-Trole and Troles are now mostly implemented. Looks like a very clean and intuitive design, and now (almost) fully documented!
-The specs are mostly in place, but there is a need to test more usage of the APIs to ensure corner cases are covered
-with ArgumentException raised and such. Also needs some debugging/finetuning in various places. 
+I'm now in the process of implementing TroleGroups! Finally a fully integrated role groups solution for Ruby and Rails ;)
+Due to the flexible design ot troles and trole, I can reuse the same infrastructure/design/architecture to implement trole_groups! 
+*Yiii...haaa!*   
+                 
+"A RoleGroup is simply another role_subject and can thus be configured with a given role strategy!" 
 
-h3. Active Record specs!!!
+Simple and Sweet :)
 
-The Active Record specs infrastructure is finally set up and ready. Try: @$ rspec spec/active_record/strategies/many/string_many.rb@
+h2. The Ruby Class Decorator (RCD) pattern is born!!!
 
-h3. Yard docu
+I realized a while ago that I had come upon a very cool kind of "class decorator" design pattern that can be generalized to any gem that "decorates" a class (or perhaps multiple classes) with certain behavior. Gems such as _act_as_xxx_ come to mind fx.
+
+I will soon try to generalize this pattern into a separate project and then have trole, troles and trole_groups all use this to leverage their functionality. Also, I will make use of an idea that I just had while taking a cold shower (try it sometime if you have a mind block!). 
+The idea is to have an internal default API, and an exposed API that by default is a reflection of the internal API. However the user is free to block parts of the API from being loaded or define his own external API that utilizes the inner API.
+
+Since this is a general purpose decorator pattern, there should also be a kind of Index where you can see which decorators have been applied to an object and what API each such decorator exposes! Cool stuff!!!!  
+
+Some example usage:
+<pre>
+return if !User.has_decorator?(:troles_group)
+# do some trole group stuff!!!
+
+# later ...
+
+# list all decorators currently applied to the User class
+puts User.decorators
+
+# print the methods of the public Write API for the :troles_group decorator :)
+puts User.decorator(:troles_group).public_api(:write).methods.sort
+
+# print the methods of the internal Write API for the :troles_group decorator :)
+puts User.decorator(:troles_group).internal_api(:write).methods.sort
+</pre>
+
+I will use the new Decorator API very soon... sth like this:
+
+<pre>
+User.decorator(:trole_groups).configure(:strategy) :ref_one do |strategy|
+  strategy.orm = :mongoid
+  strategy.auto_load = true
+end.configure!  
+</pre>
+
+Awesome! 
+
+h3. Yard documentation
 
 I'm using "Yard":http://rubydoc.info/docs/yard/file/docs/GettingStarted.md for documentation.
 
@@ -197,17 +235,17 @@ A custom Config class for _:single_ role strategies using _Mongoid_ could look s
 module Trole::Mongoid
   class Config < Troles::Common::Config  
 
-    def initialize clazz, options = {}
+    def initialize subject_class, options = {}
       super
     end
   
     def configure_relation
       case strategy
       when :ref_one
-        has_one_for clazz, :role
-        belongs_to_for role_model, :user
+        has_one_for subject_class, object_model
+        belongs_to_for object_model, subject_class
       when :embed_one
-        embeds_one_for clazz, :role
+        embeds_one_for subject_class, object_model
       end
     end
     
@@ -218,7 +256,7 @@ module Trole::Mongoid
       when :string_one
         String
       end
-      clazz.send(:field, role_field, type) if type      
+      subject_class.send(:field, role_field, type) if type      
     end
 </pre>                     
 
@@ -231,7 +269,7 @@ Example: Config class for :many roles strategies with _Mongoid_
 module Troles::Mongoid
   class Config < Troles::Common::Config  
 
-    def initialize clazz, options = {}
+    def initialize subject_class, options = {}
       super
     end
   
@@ -248,7 +286,7 @@ module Troles::Mongoid
       when :string_many
         String
       end
-      clazz.send(:field, role_field, type: => type) if type      
+      subject_class.send(:field, role_field, type: => type) if type      
     end
 </pre>
 
@@ -497,9 +535,9 @@ User.troles_strategy :bit_one, :orm => :active_record do |c|
   c.auto_load = false
   c.valid_roles = [:troll_commander, :troll_warrior]
 
-  c.static_roles = true # note: false by default
+  c.auto_config[:relations] = false # to take over control of setting up model relationships
 
-end.configure! :role_model => 'Troll', :join_model => 'UserTroll'
+end.configure! :role_model => 'Troll', :role_join_model => 'UserTroll'
 </pre>
 
 Enjoy :)  
@@ -511,6 +549,9 @@ The following is a list of the global Troles common configuration options:
 * default_orm
 * auto_load (true|false)
 * log_on (true|false)
+* auto_config[:models] (true|false)
+* auto_config[:fields] (true|false)
+* auto_config[:relations] (true|false)
 
 Examples:
 
@@ -526,6 +567,24 @@ Ensures the adapter is autoloaded from the troles internal _/adapter_ folder. Le
 
 Turns on some logging to make it easier to debug what goes on behind the curtain (note: to be improved...). 
 
+@Troles::Common::Config.auto_config[:models] = false@
+
+Disables troles auto configuration of models, allowing you full control. 
+
+@Troles::Common::Config.auto_config[:relations] = false@
+
+Disables troles auto configuration of model relationships (has_many, belongs_to and such), allowing you full control. 
+
+@Troles::Common::Config.auto_config[:fields] = false@
+
+Disables troles auto configuration of model fields (for data stores such as Data Mapper, Mongoid etc that have the concept of data fields), allowing you full control. 
+
+Note: For all the global on/off options you can opt to use same option on an individual strategy basis as part of an individual strategy configuration.
+
+In the strategy Config class they can be used like this 
+
+@if auto_config?(:fields)@
+
 h2. Other notes on Application-User control
 
 _troles_ will be part of a larger project under development that will go under the name "dancing tango with trolls". This will be a rework of _cream_ and _cancan-permits_ that will target use in apllications with multiple user accounts and multiple sub applications. In this new system, _dancing_ will be the replacement of _cream_ and _tango_ the replacement of _cancan-permits_. I hope to give a talk on RubyConf 2011 about this system. 

data/VERSION

@@ -1 +1 @@
-0.5.0
+0.5.1

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

@@ -1,15 +1,15 @@
 module Trole::ActiveRecord
   class Config < Troles::Common::Config  
     
-    def initialize clazz, options = {}
+    def initialize subject_class, options = {}
       super
     end
     
     def configure_relation
       case strategy
       when :ref_one
-        belongs_to_for clazz, role_model, :key => role_field 
-        has_many_for role_model, clazz
+        belongs_to_for subject_class, object_model, :key => main_field 
+        has_many_for object_model, subject_class
       when :embed_one
         raise "EmbedOne is currently not supported by the Active Record adapter. It will be soon..."
         #clazz.send(:embeds_many, role_model_key, :class_name => role_model_class_name)      

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

@@ -1,17 +1,17 @@
 module Trole::Mongoid
   class Config < Troles::Common::Config  
     
-    def initialize clazz, options = {}
+    def initialize subject_class, options = {}
       super
     end
     
     def configure_relation
       case strategy
       when :ref_one
-        has_one_for clazz, :role
-        belongs_to_for role_model, :user
+        has_one_for subject_class, object_model
+        belongs_to_for object_model, subject_class
       when :embed_one
-        embeds_one clazz, :role
+        embeds_one subject_class, object_model
       end
     end
     
@@ -22,7 +22,7 @@ module Trole::Mongoid
       when :string_one
         String
       end
-      clazz.send(:field, role_field, type) if type      
+      subject_class.send(:field, role_field, type) if type      
     end   
     
     protected

data/lib/trole/config.rb

@@ -1,10 +1,10 @@
 module Trole
   class Config < Troles::Common::Config    
-    def initialize clazz, options = {}
+    def initialize subject_class, options = {}
       super
     end
 
-    def configure_role_field
+    def configure_models
       super
     end       
         

data/lib/trole_groups.rb

@@ -0,0 +1,10 @@
+require 'troles/common'
+require 'troles/macros'
+
+module TroleGroups  
+  autoload :Config,         'trole_groups/config'
+  autoload :Api,            'trole_groups/api'
+  autoload :Operations,     'trole_groups/operations'
+  autoload :Strategy,       'trole_groups/strategy'
+  autoload :Storage,        'trole_groups/storage'
+end

data/lib/trole_groups/READ THIS.textile

@@ -0,0 +1,4 @@
+h1. Important Trole Groups considerations
+
+When role groups are enabled, it makes no sense to only enable a single role group, hence no need for :one strategies.
+I will thus only implement the :many strategies similar to troles.

data/lib/trole_groups/Rolegroups design.textile

@@ -0,0 +1,218 @@
+h1. Role groups
+
+A RoleGroup is simply another role_subject and can thus be configured with a given role strategy! Sweet :)
+
+In some scenarios it makes sense to allow a user to be assigned one or more role groups.
+
+<pre>
+  Rolegroup.get(:bloggers).set_roles :blog_admin, :admin
+  Rolegroup.get(:super_admin).set_roles :blog_admin, :admin
+  Rolegroup.create(:super_admin, :roles => [:blog_admin, :admin])
+
+  Rolegroup.create(:super_admin).set_roles :blog_admin, :admin
+</pre>
+
+<pre>
+  user.rolegroups << [:bloggers, :admins]
+  user.in_rolegroup? :bloggers  
+</pre>
+
+many rolegroups from a set of valid rolegroups 
+
+
+Multiple roles strategy
+
+Schema
+  Integer (bitmap) field on the User class
+  String of comma delimited role groups on User class
+  References to multiple RoleGroups
+  Embeds multiple RoleGroups (document store)
+
+Field stored in the datastore
+
+trolegroups
+
+The field is named trolegroups, in order not to conflict with the method #rolegroups used in the role group DSL.
+
+These strategies can be named:
+
+  bit_many
+  string_many
+  ref_many
+  embed_many
+
+These strategies can be implemented for any data store using any schema format.
+
+<pre>
+User
+ include Troles::GroupAdapter::RefMany  
+</pre>
+
+When a user is assigned a given role group, he is automatically treated as having the roles of that role group. The role group cache of the user thus changes when he is assigned or removed from a role group.
+
+The role group however can also change, and this will effect all users assigned to that role group. The RoleGroups::EventManager must be called in all these cases.
+
+Roles API
+The Roles API can be divided into
+
+ * Read operations
+ * Write operations and related functionality
+
+RoleGroup Read API
+These methods are available on the User instance
+
+<pre>
+  # any? on rolegroups_list
+  def in_rolegroup? rolegroup
+
+  # rolegroup_list has one element which is rolegroup
+  def is_rolegroup? rolegroup
+
+  # subtraction of role_groups from rolegroups_list is empty
+  def has_all_rolegroups? rolegroups
+
+  # union of rolegroups and rolegroups_list is not empty
+  def in_any_rolegroup? rolegroups
+
+  # return roles of that rolegroup
+  def roles_of rolegroup
+
+  # return Set of symbols,where each symbol is a rolegroup name
+  # This set should be cached and only invalidated when the user has a change of roles
+  def rolegroups_list  
+</pre>
+
+RoleGroup Write API
+
+The User class should have an event trigger after save to see if the roles were changed.
+If the roles were changed, an even should be sent to an event manager to handle this, invalidating role caches etc.
+
+<pre>
+  User
+   after_save: update_role_groups # add event handler  
+</pre>
+
+These methods are available on the User instance
+
+<pre>
+  # 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.
+  # Both (and potentially others, fx for Role Groups) can subscribe to this event!
+  def update_role_groups
+   publish_change(:role_groups) if field_changed?(rolegroups_field)
+  end
+
+  # check if a field on the model changed
+  # See http://api.rubyonrails.org/classes/ActiveModel/Dirty.html
+  def field_changed? name
+   send :“#{name}_changed?”
+  end
+
+  # can be customized
+  # here uses singleton EventManager
+  def publish_change event
+   Roles::EventManager.publish_change event, :from => self
+  end
+
+  # return the role field used, fx :rolegroup_value etc.
+  # should NOT be mutable
+  def rolegroups_field
+    :rolegroup_value
+  end
+
+  def add_rolegroup
+  role_groups << role
+  end
+
+  def remove_rolegroup
+  role_groups << role
+  end
+
+  # should return a RoleGroups::Operations object
+  def role_groups
+   TRoles::RoleGroups::Operations.new(self)
+
+  class TRoles::RoleGroups:: Operations
+   include ReadOperations
+   include WriteOperations
+
+   def initialize user
+   end
+  end  
+</pre>
+
+<pre>
+  module TRoles: RoleGroups::ReadOperations
+   # check if any of the rolegroups have the given role
+
+   def contains? role_group
+     list.include? role_group
+   end
+   alias_method :includes?, :contains?
+
+   # symbol list of role groups
+   def list
+
+   # Set of roles from all role groups
+   def roles_list
+
+   def get *role_groups
+
+  end  
+</pre>
+
+<pre>
+  module TRoles: RoleGroups::WriteOperations
+   def + # add role group
+   alias_method <<
+
+   def - # remove role groups
+  end
+
+  user.roles_groups.get(:bloggers) => returns :bloggers if in roles_list, or raises error
+  user.roles_groups.get(:bloggers, :admins) => returns [:bloggers, :admins], or error
+
+  if user.role_groups.roles_list == [:admin, :blogger]
+  if user.role_groups.have_role? :blogger
+
+  user.role_groups.add :bloggers
+  user.role_groups << :bloggers
+  user.role_groups + [:bloggers, :editors]
+  user.role_groups - :admins  
+</pre>
+
+Relational schema
+
+<pre>
+RoleGroup
+ has_many :roles  
+</pre>
+
+<pre>
+Role
+ belongs_to :role_group
+ belongs_to :user  
+</pre>
+
+If the RoleGroup is used in a Relational schema model, the RoleGroup should belong to a user and a Role should belong to a Group.
+
+Roles field on RoleGroup
+
+<pre>
+  RoleGroup
+   def valid_roles
+
+   belongs_to :user
+   field roles (String, Integer bitmap)  
+</pre>
+
+In a non-relational schema model, the RoleGroup would still belong to a User but the roles could be a field of either String or Integer (bitmap) instead of a relation to a Role model.
+If an integer bitmap is used, the bits would map onto the valid_roles list that returns a list of role symbols.
+
+The valid_roles method should get the list of valid roles from a singleton such as TRoles::Configuration. The actual implementation could either use a static list, pull it from a yaml file or perhaps execute all_roles on Role.
+
+<pre>
+class Role
+ scope :role_list, lambda { all.map {|r| name.to_sym} }
+end  
+</pre>