lanes 0.0.1

data/lib/lanes/concerns/export_join_tables.rb

@@ -0,0 +1,39 @@
+module Lanes::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/lanes/concerns/export_methods.rb

@@ -0,0 +1,104 @@
+module Lanes::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 < Lanes::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
+            #     lanes_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 < Lanes::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 < Lanes::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/lanes/concerns/export_scope.rb

@@ -0,0 +1,66 @@
+require_relative 'exported_limit_evaluator'
+
+module Lanes::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 methods
+        module ClassMethods
+            def scope(name, body, options = {}, &block)
+                super(name, body, &block)
+                if (export = options[:export])
+                    export_scope(name, body, 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, query, limit: nil)
+                include ExportedLimitEvaluator
+
+                self.exported_scopes ||= Hash.new
+                self.exported_scopes[name.to_sym] = {
+                    scope: scope(name, query),
+                    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/lanes/concerns/exported_limit_evaluator.rb

@@ -0,0 +1,17 @@
+module Lanes::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/lanes/concerns/immutable_model.rb

@@ -0,0 +1,32 @@
+module Lanes
+    module Concerns
+
+        module ImmutableModel
+
+            extend ActiveSupport::Concern
+
+            module ClassMethods
+
+                # Once it's created it may not be updated or destroyed.
+                # @raise [ActiveRecord::ReadOnlyRecord] if destroy, delete or save is called after it's been created.
+                def is_immutable(options = {})
+
+                    options[:except] = [*options[:except]].map{|name| name.to_s } # make sure except is present and an array
+
+                    before_destroy do
+                        raise ActiveRecord::ReadOnlyRecord.new( "Can not destroy #{self.class.model_name}, only create is allowed" )
+                    end
+
+                    before_update do
+                        unless ( changes.keys - change_tracking_fields - options[:except] ).blank?
+                            raise ActiveRecord::ReadOnlyRecord.new(  "Can not update, only create #{self.class.model_name}" )
+                        end
+                    end
+
+                end
+
+            end
+
+        end
+    end
+end

data/lib/lanes/concerns/locked_fields.rb

@@ -0,0 +1,84 @@
+module Lanes
+    module Concerns
+
+        # @see ClassMethods
+        module LockedFields
+            extend ActiveSupport::Concern
+
+            module ClassMethods
+                # Mark fields as locked, meaning they cannot be updated by using the
+                # regular attribute update methods.  Instead it must be called in an unlock block
+                # Relies on attr_readonly internally
+                #
+                # Is used to designate sensitive fields that we want to make sure someone's thought about before updating
+                # Also solves the age old single equals vs double equals bug/typo.
+                #
+                #     class BankAccount < Lanes::Model
+                #
+                #     end
+                #
+                #     bank=BankAccount.find(1)
+                #     b.mark_as_super if bank.account_balance = 42 # a bit contrived, but you get the idea
+                #     b.save # oops, what's our balance now?
+                #
+                #  Now let's try it again with locked_fields
+                #
+                #     class BankAccount < Lanes::Model
+                #         attr_readonly :account_balance
+                #     end
+                #
+                #     bank=BankAccount.find(1)
+                #     b.mark_as_super if bank.account_balance = 42
+                #     b.save # Still not ideal since we marked the bank as super, but at least our balance is ok
+                #
+                #  To update the balance we'd need to:
+                #
+                #     b.unlock_fields( :account_balance ) do
+                #         b.account_balance += 33
+                #     end
+                #     b.save
+                #
+                #  This is still a bit contrived since we'd actually have
+                #  an audit logger that would be involved and it'd be inside a transaction.
+
+                def locked_fields( *flds )
+                    include InstanceMethods
+                    attr_readonly( *flds )
+                end
+
+                def has_locks( *locks )
+                    locks.each do | lock |
+                        define_method( "unlock_#{lock}" ) do | &block |
+                            instance_variable_set "@_lock_#{lock}_unlocked", true
+                            block.call
+                            remove_instance_variable "@_lock_#{lock}_unlocked"
+                        end
+                        define_method( "is_#{lock}_unlocked?") do
+                            instance_variable_defined? "@_lock_#{lock}_unlocked"
+                        end
+                    end
+                end
+
+            end
+
+            module InstanceMethods
+                # Unlock the field for updates inside the block
+                # yields, then restores it.
+                # Is class wide, meaning it Will temporarily open all instances of the class up for access in a threaded environment
+                def unlock_fields( *flds, &block )
+                    attr_syms = flds.map(&:to_s)
+
+                    self.class.attr_readonly.subtract( attr_syms )
+
+                    yield
+
+                    attr_syms.each do | fld |
+                        self.class.attr_readonly.add( fld )
+                    end
+
+                end
+            end
+
+        end
+    end
+end

data/lib/lanes/concerns/pub_sub.rb

@@ -0,0 +1,105 @@
+module Lanes::Concerns
+
+    module PendingEventListeners
+        # @private
+        @@listeners = Hash.new{ |hash, klass| hash[klass] = Hash.new{ |kh, event| kh[event]=Array.new } }
+        # @api private
+        def self.all
+            @@listeners
+        end
+    end
+
+
+    # Event subscription and publishing for Stockor 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
+
+        class InvalidEvent < RuntimeError
+        end
+
+        included do | base |
+
+            class_attribute :valid_event_names
+            class_attribute :_event_listeners
+            self.valid_event_names = [ :save, :create, :update, :destroy ]
+
+            after_save    :fire_after_save_events
+            after_create  :fire_after_create_events
+            after_update  :fire_after_update_events
+            after_destroy :fire_after_destroy_events
+        end
+
+        module ClassMethods
+            def inherited(base)
+                super
+                klass = base.to_s.demodulize
+                if PendingEventListeners.all.has_key?( klass )
+                    events = PendingEventListeners.all.delete(klass)
+                    events.each{ | name, procs | base.event_listeners[name] += procs  }
+                end
+            end
+
+            def event_listeners
+             self._event_listeners ||= Hash.new{ |hash, key| hash[key]=Array.new }
+            end
+
+            def _add_event_listener( name, proc )
+                self.event_listeners[name].push( proc ) unless self.event_listeners[name].include?(proc)
+            end
+
+            def observe( event, &block )
+                _ensure_validate_event( event )
+                _add_event_listener( event.to_sym, block )
+            end
+
+            def _ensure_validate_event(event)
+                unless self.valid_event_names.include?(event.to_sym)
+                    raise InvalidEvent.new("#{event} is not a valid event for #{self}")
+                end
+            end
+
+            protected
+
+            def has_additional_events( *names )
+                self.valid_event_names += names.map{ |name| name.to_sym }
+            end
+        end
+
+        protected
+        def fire_after_destroy_events
+            _fire_event(:update, self )
+        end
+        def fire_after_update_events
+            _fire_event(:update, self )
+        end
+        def fire_after_create_events
+            _fire_event(:create, self )
+        end
+        def fire_after_save_events
+            _fire_event( :save, self )
+        end
+
+        def fire_event( name, *arguments )
+            self.class._ensure_validate_event( name )
+            arguments.unshift( self )
+            _fire_event( name, *arguments )
+        end
+
+        private
+        def _fire_event( name, *arguments )
+            self.class.event_listeners[ name.to_sym ].each{ | block | block.call(*arguments) }
+            return true
+        end
+    end
+
+end

data/lib/lanes/concerns/queries.rb

@@ -0,0 +1,20 @@
+module Lanes
+    module Concerns
+
+        # A collection of handly utility methods to generate queries
+        module Queries
+
+            extend ActiveSupport::Concern
+
+            module ClassMethods
+
+                def compose_query_using_detail_view( view: view, join_to: join_to )
+                    view = Lanes.config.table_prefix + view.to_s
+                    joins("join #{view} as details on details.#{join_to} = #{table_name}.#{primary_key}")
+                    .select("#{table_name}.*, details.*")
+                end
+
+            end
+        end
+    end
+end

data/lib/lanes/concerns/random_hash_code.rb

@@ -0,0 +1,40 @@
+module Lanes
+    module Concerns
+
+        # @see ClassMethods
+        module RandomHashCode
+
+            extend ActiveSupport::Concern
+
+            # ### Random Hash Code Concern
+            # This adds the {#has_random_hash_code} class method
+            module ClassMethods
+
+                # A random string that identifies an entity, such as a Customer, or Vendor
+                # The code is generated by {Lanes::Strings.random} for new records
+                # It's useful for generating *magic* links for access to an entity that cannot be guessed.
+                # @param field_name [Symbol] which field should the hash_code be stored in
+                # @param length [Integer] how long the hash_code should be
+
+                def has_random_hash_code( field_name: :hash_code, length: 12 )
+
+                    validates field_name, :presence=>{
+                        :message=>"hash code is not set (should be automatically chosen)"
+                    }
+
+                    scope :with_hash_code, lambda{ | code |
+                        where({ :hash_code=>code })
+                    }
+
+                    before_validation(:on=>:create) do
+                        self[ field_name ] = Lanes::Strings.random( length ) if self[ field_name ].blank?
+                    end
+
+                end
+            end
+
+        end
+
+    end
+
+end

data/lib/lanes/concerns/sanitize_api_data.rb

@@ -0,0 +1,15 @@
+module Lanes::Concerns
+
+
+    # SanitizeJson is responsible for only cleaning a hash of attributes that should not
+    # be written to the model by the given user
+    module SanitizeApiData
+        extend ActiveSupport::Concern
+
+        module ClassMethods
+        end
+
+    end
+
+
+end

data/lib/lanes/concerns/set_attribute_data.rb

@@ -0,0 +1,154 @@
+module Lanes::Concerns
+
+
+    module ApiAttributeAccess
+
+
+        extend ActiveSupport::Concern
+
+        included do
+            class_attribute :blacklisted_attributes
+            class_attribute :whitelisted_attributes
+            include AccessChecks
+        end
+
+        module AccessChecks
+            # Can the API read data from the model?
+            def can_read_attributes?(params, user)
+                return user.can_write?(self, params)
+            end
+
+            # Can the API write data to the model?
+            # This check is performed before we bother checking each attribute individually
+            def can_write_attributes?(params, user)
+                return user.can_write?(self, params)
+            end
+
+            # Can the API delete the model?
+            # This check is performed before we bother checking each attribute individually
+            def can_delete_attributes?(params, user)
+                return user.can_delete?(self, params)
+            end
+        end
+
+        module ClassMethods
+
+            # # An attribute accessor that allows access from the API
+            # def api_attr_accessor( *names )
+            #     names.each do | attr |
+            #         attr_accessor attr
+            #         whitelist_attributes attr
+            #     end
+            # end
+
+            # @param attributes [Array of symbols] attributes that are safe for the API to set
+            def whitelist_attributes( *attributes )
+                options = attributes.extract_options!
+                self.whitelisted_attributes ||= {}
+                attributes.each{|attr| self.whitelisted_attributes[ attr.to_sym ] = options }
+            end
+
+            # @param attributes [Array of symbols] attributes that are not safe for the API to set
+            def blacklist_attributes( *attributes )
+                options = attributes.extract_options!
+                self.blacklisted_attributes ||= {}
+                attributes.each{|attr| self.blacklisted_attributes[ attr.to_sym ] = options }
+            end
+
+            def from_attribute_data(data,user=Lanes::User.current)
+                record = self.new
+                record.set_attribute_data(data, user)
+                record
+            end
+
+            include AccessChecks
+        end
+
+
+        # An attribute is allowed if it's white listed
+        # or it's a valid attribute and not black listed
+        # @param name [Symbol]
+        # @param user [User] who is performing request
+        def setting_attribute_is_allowed?(name, user)
+            return false unless user.can_write?(self, name)
+            (self.whitelisted_attributes && self.whitelisted_attributes.has_key?( name.to_sym)) ||
+            (
+              self.attribute_names.include?( name.to_s ) &&
+              ( self.blacklisted_attributes.nil? ||
+                ! self.blacklisted_attributes.has_key?( name.to_sym )  )
+            )
+        end
+
+        # Takes in a hash containing attribute name/value pairs, as well as sub hashes/arrays.
+        # Sets all the attributes that are allowed and recursively sets sub-associations as well
+        # @param data [Hash]
+        # @param user [User] who is performing request
+        # @returns
+        def set_attribute_data(data, user = Lanes::User.current)
+
+            return {} unless self.can_write_attributes?(data, user)
+
+            data.each_with_object(Hash.new) do | kv, result |
+                ( key, value ) = kv
+
+                # First we set all the attributes that are allowed
+                if self.setting_attribute_is_allowed?(key.to_sym, user)
+                    public_send("#{key}=",result[key] = value)
+                else
+                    # allow nested params to be specified using Rails _attributes
+                    name = key.to_s.gsub(/_attributes$/,'').to_sym
+
+                    next unless self.class.has_exported_nested_attribute?(name, user)
+
+                    association = self.association(name)
+
+                    result[name] = if value.is_a?(Hash) && [:belongs_to,:has_one].include?(association.reflection.macro)
+                                       target = association.target || association.build
+                                       target.set_attribute_data(value)
+                                   elsif value.is_a?(Array) && :has_many == association.reflection.macro
+                                       _set_attribute_data_from_collection(association, value)
+                                   end
+                end
+            end
+        end
+
+        def _set_attribute_data_from_collection(association, value)
+
+            records = if association.loaded?
+                                   association.target
+                               else
+                                   attribute_ids = value.map {|a| a['id'] || a[:id] }.compact
+                                   attribute_ids.empty? ? [] : association.scope.where(
+                                     association.klass.primary_key => attribute_ids
+                                   )
+                               end
+
+            value.map do | association_data |
+                record = if association_data['id'].blank?
+                             association.build
+                         else
+                             records.detect{ |r| r.id.to_s == value['id'].to_s }
+                         end
+                record.set_attribute_data(association_data) if record
+            end
+        end
+
+
+        # association = self.send(name)
+
+        # klass_name = self.class.reflections[ name.to_sym ].class_name
+        # klass = klass_name.safe_constantize || "Lanes::#{klass_name}".constantize
+
+        # # only Hash, Array & nil is valid for nesting attributes
+        # cleaned = case value
+        #           when Hash  then klass.sanitize_api_data( value, user, klass )
+        #           when Array then value.map{ | nested |
+        #                   klass.sanitize_api_data( nested, user, klass )
+        #               }
+        #           else
+        #               nil
+        #           end
+#        result[ name.to_sym ] = cleaned unless cleaned.blank?
+    end
+
+end