hippo-fw 0.9.1

data/lib/hippo/concerns/code_identifier.rb

@@ -0,0 +1,43 @@
+module Hippo
+    module Concerns
+
+        # @see ClassMethods
+        module CodeIdentifier
+
+            extend ActiveSupport::Concern
+
+            # ### Code Identifier Concern
+            # This adds the {#has_code_identifier} class method
+            module ClassMethods
+
+                # A 2-10 character string that identifies an entity, such as a Customer, Vendor, or SKU.
+                # The code is often assigned by the user, but may also
+                # be auto-generated by {Skr::Strings.code_identifier}
+                #
+                # @param max_length [Integer] how long the code is allowed to be
+                # @param from [Symbol], method to call for a string to base the code upon
+                def has_code_identifier( from: nil, max_length: 10 )
+
+                    validates :code, :length=>2..max_length, :presence=>true, :uniqueness=>true
+
+                    alias_attribute :record_identifier, :code
+
+                    if from
+                        before_validation(:on=>:create) do
+                            source = self[from]
+                            if code.blank? && !source.blank?
+                                self.code = Hippo::Strings.code_identifier(source, length:max_length, padding: '')
+                            end
+                        end
+                    end
+
+                    before_validation do
+                        self.code = self.code.upcase unless self.code.blank?
+                    end
+                end
+
+            end
+
+        end
+    end
+end

data/lib/hippo/concerns/export_associations.rb

@@ -0,0 +1,52 @@
+module Hippo::Concerns
+
+    # @see ClassMethods
+    module ExportAssociations
+        extend ActiveSupport::Concern
+
+        included do
+            class_attribute :exported_associations
+        end
+
+        module ClassMethods
+            # Mark associations as exported, meaning they can be quered against and optionally written to
+            # @param associations [list of Symbols]
+            # @option options [Boolean] :writable should the associations accept nested attributes
+            # @option options [Boolean] :mandatory should the association be included with it's parent at all times?
+            # @option options [Symbol referring to a method, lambda] :limit restrict to Users for whom true is returned
+            def export_associations( *associations )
+                self.exported_associations ||= {}
+                associations.flatten!
+                options = associations.extract_options!
+                associations.each do | assoc_name |
+                    self.exported_associations[ assoc_name.to_sym ] = options
+                    if options[:writable]
+                        accepts_nested_attributes_for( assoc_name, options.except(:writable, :optional) )
+                    end
+                    if false == options[:optional]
+                        self.export_methods( *assoc_name, { :optional=>false })
+                    end
+                end
+            end
+
+            # If the association is exported it may be queried against and it's data included
+            # along with the parent record.  It may not be written to unless the :writable flag
+            # was set, in which case it'll be allowed by has_exported_association?
+            def has_exported_association?( association, user )
+                self.exported_associations &&
+                    ( options = self.exported_associations[ association.to_sym ] ) &&
+                    evaluate_export_limit( user, :association, association, options[:limit] )
+            end
+
+            # Does the association allow writes?  True if the association has been exported
+            # and it accepts nested attributes
+            def has_exported_nested_attribute?( association, user )
+                self.nested_attributes_options[ association.to_sym ] &&
+                    self.has_exported_association?( association, user )
+            end
+
+        end
+
+    end
+
+end

data/lib/hippo/concerns/export_join_tables.rb

@@ -0,0 +1,39 @@
+module Hippo::Concerns
+
+    module ExportJoinTables
+
+        extend ActiveSupport::Concern
+
+        included do
+            class_attribute :exported_join_tables
+        end
+
+        module ClassMethods
+            # Mark a joined table as safe to be included in a query
+            # Primarily used for joining a model to a view for access to summarized data
+            def export_join_tables( *tables )
+                include ExportedLimitEvaluator
+                self.exported_join_tables ||= []
+                tables.flatten!
+                options = tables.extract_options!
+                tables.each do | join_name |
+                    self.exported_join_tables << {
+                        name: join_name,
+                        limit: options[:limit]
+                    }
+                end
+
+            end
+
+            # Has the join been marked as safe?
+            def has_exported_join_table?(name, user)
+                return true if name == 'details' # "details" is reserved for views and is always allowed
+                self.exported_join_tables && self.exported_join_tables.detect{ | join |
+                    join[:name] == name && evaluate_export_limit( user, :join, join[:name], join[:limit] )
+                }
+            end
+
+        end
+    end
+
+end

data/lib/hippo/concerns/export_methods.rb

@@ -0,0 +1,104 @@
+module Hippo::Concerns
+
+    # @see ClassMethods
+    module ExportMethods
+        extend ActiveSupport::Concern
+
+        included do
+
+            # methods that the model has exported.  Not intended for querying directly.
+            # The API and interested parties should call {#has_exported_method?}
+            class_attribute :exported_methods
+        end
+
+        module ClassMethods
+
+            # Called by a model to export methods to the API
+            # An exported method will be called and it's results returned along with the models
+            # JSON representation.
+            # @option options [Boolean] :optional if false, the method will always be called and included
+            # @option options [Symbol, Array of Symbols] :depends name(s) of associations that should
+            #     be pre-loaded before calling method. Intended to prevent N+1 queries
+            def export_methods( *method_names )
+                method_names.flatten!
+                options = method_names.extract_options!
+                self.exported_methods ||= {}
+                method_names.map do | name |
+                    exported_methods[ name.to_sym] = options
+                end
+            end
+
+            # Convenience method to create a Rails delegation and export the resulting method
+            # @example
+            #     class Foo < Hippo::Model
+            #           belongs_to :bar
+            #           delegate_and_export :bar_name, :optional=>false
+            #     end
+            #
+            #     foo = Foo.new
+            #     foo.bar_name #=> calls foo.bar.name
+            #     Foo.has_exported_method?( :bar_name )  #=> true
+            #     hippo_to_json( foo ) #=> will first load the bar association, then
+            #                            call foo.bar_name and include it's result in the JSON
+            def delegate_and_export( *names )
+                options = names.extract_options!
+                names.each do | name |
+                    target,field = name.to_s.split(/_(?=[^_]+(?: |$))| /)
+                    delegate_and_export_field( target, field, optional: options[:optional], limit: options[:limit] )
+                end
+            end
+
+            # For situations where the delegate_and_export method guesses wrong on the association and field names
+            # @param target [Association] association to delegate to
+            # @param field  [Symbol] method on Association to call
+            # @param optional [Boolean] should the method be called and results included all the time,
+            #                    or only if specifically requested
+            # @param limit [Symbol referring to a method, lambda] restrict to Users for whom true is returned
+            # @example
+            #     class PoLine < Hippo::Model
+            #           belongs_to :purchase_order
+            #           delegate_and_export :purchase_order_visible_id
+            #     end
+            # would generate a method ``purchase_order_visible_id`` that would call ``purchase_order_visible.id``
+            # This would do the right thing:
+            #     class PoLine < Hippo::Model
+            #           belongs_to :purchase_order
+            #           delegate_and_export_field :purchase_order, :visible_id
+            #     end
+            def delegate_and_export_field( target, field, optional: true, limit: nil )
+                delegate field, to: target, prefix: target, allow_nil: true
+                self.export_methods( "#{target}_#{field}", { depends: target.to_sym,
+                                                             optional: optional,
+                                                             limit: limit } )
+            end
+
+            # Check if the method can be called by user
+            def has_exported_method?( name, user )
+                if self.exported_methods && ( method_options = self.exported_methods[ name.to_sym ] )
+                    return evaluate_export_limit( user, :method, name, method_options[:limit] )
+                else
+                    return false
+                end
+            end
+
+            # Retrieve the list of dependent associations for the given methods
+            # Also includes methods that were exported as ``optional: false``
+            # @param requested_methods [Array] methods that the user has requested be executed and added to the JSON payload
+            # @return [Array] list of associations that should be included in query
+            def exported_method_dependancies( requested_methods )
+                requested_methods.map!(&:to_sym)
+                return [] if self.exported_methods.blank?
+                depends = self.exported_methods.each_with_object(Array.new) do | kv, result |
+                    ( export, options ) = kv
+                    if options[:depends] && ( false == options[:optional] || requested_methods.include?(export) )
+                        result << options[:depends]
+                    end
+                end
+                depends.uniq
+            end
+        end
+
+
+    end
+
+end

data/lib/hippo/concerns/export_scope.rb

@@ -0,0 +1,64 @@
+require_relative 'exported_limit_evaluator'
+
+module Hippo::Concerns
+
+    # @see ClassMethods
+    module ExportScope
+        extend ActiveSupport::Concern
+
+        included do
+            # scopes that the model has exported.  Not intended for querying directly.
+            # The API and interested parties should call {#has_exported_scope?}
+            class_attribute :exported_scopes
+            extend ExportedLimitEvaluator
+        end
+
+        # ### Mark a scope as "exportable"
+        #
+        # An exported scope is safe for querying by external clients over the API.
+        # The scope should always:
+        #
+        #  * Safely escape data *(should __ALWAYS__ do this anyway, but it bears mentioning again)*
+        #  * Be relatively simple and complete quickly.
+        #  * Provide value to the client that it cannot obtain by using normal query method
+        class_methods do
+            def scope(name, body, options = {}, &block)
+                super(name, body, &block)
+                if (export = options[:export])
+                    export_scope(name, limit: (export == true ? nil : export[:limit]))
+                end
+            end
+
+            # Mark scope as query-able by the API.
+            # @param name [Symbol,String] Rails will create a class method with this name
+            # @param query [lambda] Arel query.  This is passed off to Rail's for setting up the scope.
+            # @param limit [Symbol referring to a Class method name, lambda]
+            # If given, this will be queried by the API to determining if a given user may call the scope
+            # @return nil
+            def export_scope(name, limit: nil)
+                include ExportedLimitEvaluator
+
+                self.exported_scopes ||= Hash.new
+                self.exported_scopes[name.to_sym] = {
+                    name: name, limit: limit
+                }
+                nil
+            end
+
+            # The api can query this to determine if the scope is safe to be called
+            # from the API by [user]
+            # @param name [Symbol,String] name of scope
+            # @param user [User] who is performing the request.
+            #   This is passed off to the method or lambda that was given as the limit  argument in {#export_scope}
+
+            def has_exported_scope?(name, user)
+                if self.exported_scopes && ( scope_options = self.exported_scopes[ name.to_sym ] )
+                    return evaluate_export_limit( user, :scope, name, scope_options[:limit] )
+                else
+                    return false
+                end
+            end
+
+        end
+    end
+end

data/lib/hippo/concerns/exported_limit_evaluator.rb

@@ -0,0 +1,17 @@
+module Hippo::Concerns
+
+    module ExportedLimitEvaluator
+
+        def evaluate_export_limit( user, type, name, limit )
+            if limit.nil?
+                true
+            elsif limit.is_a?(Symbol)
+                self.send( limit, user, type, name )
+            else
+                limit.call( user, type, name )
+            end
+        end
+
+    end
+
+end

data/lib/hippo/concerns/pub_sub.rb

@@ -0,0 +1,127 @@
+module Hippo::Concerns
+
+    # Event subscription and publishing for Models
+    # Every model has certain built-in events (:save, :create, :update, :destroy)
+    # And may also implement custom events that reflect the models domain
+    # @example Send an email when a customer's name is updated
+    #   Customer.observe(:update) do |customer|
+    #       Mailer.notify_billing(customer).deliver if customer.name_changed?
+    #   end
+    # @example Update some stats when a Sku's qty is changed
+    #   Sku.observe(:qty_changed) do | sku, location, old_qty, new_qty |
+    #       Stats.refresh( location )
+    #   end
+    module PubSub
+        extend ActiveSupport::Concern
+
+
+        module PendingListeners
+            # @private
+            @@listeners = Hash.new{ |hash, klass|
+                hash[klass] = Hash.new{ |kh, event|
+                    kh[event]=Array.new
+                }
+            }
+            class << self
+
+                # @api private
+                def claim(class_name)
+                    if @@listeners.has_key?(class_name)
+                        return @@listeners.delete(class_name)
+                    else
+                        return {}
+                    end
+                end
+
+                # @api private
+                def add(class_name)
+                    @@listeners[class_name]
+                end
+            end
+        end
+
+
+        class InvalidEvent < RuntimeError
+        end
+
+        included do | base |
+
+            class_attribute :valid_event_names
+            class_attribute :_event_listeners
+            base.valid_event_names = [ :save, :create, :update, :destroy ]
+
+            base.after_save    :fire_after_save_pubsub_events
+            base.after_create  :fire_after_create_pubsub_events
+            base.after_update  :fire_after_update_pubsub_events
+            base.after_destroy :fire_after_destroy_pubsub_events
+        end
+
+        module ClassMethods
+            def inherited(base)
+                super
+                klass = base.to_s.demodulize
+                events = PubSub::PendingListeners.claim( klass )
+                events.each{ | name, procs |
+                    procs.each{|pr|
+                        base.send(:_add_event_listener, name, &pr)
+                    }
+                }
+            end
+
+            def observe( event, &block )
+                unless self.valid_event_names.include?(event.to_sym)
+                    raise InvalidEvent.new("#{event} is not a valid event for #{self}")
+                end
+                _add_event_listener( event.to_sym, &block )
+            end
+
+            protected
+
+            def has_additional_events( *names )
+                self.valid_event_names += names.map{ |name| name.to_sym }
+            end
+
+            private
+
+            def _add_event_listener(name, &block)
+                self._event_listeners ||= Hash.new{ |hash, key| hash[key]=Array.new }
+                listeners = self._event_listeners[name].dup
+                listeners << block
+                self._event_listeners = self._event_listeners.dup
+                self._event_listeners[name] = listeners
+            end
+        end
+
+        protected
+
+        def fire_after_destroy_pubsub_events
+            fire_pubsub_event(:update, self)
+        end
+
+        def fire_after_update_pubsub_events
+            fire_pubsub_event(:update, self)
+        end
+
+        def fire_after_create_pubsub_events
+            fire_pubsub_event(:create, self)
+        end
+
+        def fire_after_save_pubsub_events
+            fire_pubsub_event(:save, self)
+        end
+
+        def fire_pubsub_event(name, *arguments)
+            return if self.class._event_listeners.nil? ||
+                      !self.class._event_listeners.has_key?(name.to_sym)
+            self.class._event_listeners[ name.to_sym ].each{ | block |
+                block.call(*arguments)
+            }
+        end
+
+        private
+
+        def _fire_pubsub_event( name, *arguments )
+        end
+    end
+
+end