shamu 0.0.1 → 0.0.2

data/lib/shamu/attributes.rb

@@ -0,0 +1,255 @@
+require "active_support/concern"
+
+module Shamu
+
+  # Provide  attributes that project data from another source (such as an
+  # external API, ActiveRecord model, cached data, etc.) providing simple
+  # transformations.
+  #
+  # To add additional attribute functionality see
+  #
+  # - {Attributes::Assignment}
+  # - {Attributes::FluidAssignment}
+  # - {Attributes::Validation}
+  # - {Attributes::Equality}
+  #
+  # @example
+  #
+  #   class Person
+  #     include Shamu::Attributes
+  #
+  #     attribute :name
+  #   end
+  module Attributes
+    extend ActiveSupport::Concern
+
+    require "shamu/attributes/assignment"
+    require "shamu/attributes/fluid_assignment"
+    require "shamu/attributes/validation"
+    require "shamu/attributes/equality"
+
+    def initialize( *attributes )
+      assign_attributes( attributes.last )
+    end
+
+    # Project the current state of the object to a hash of attributes that can
+    # be used to restore the attribute object at a later time.
+    #
+    # @param [Array, Regex] only include matching attributes
+    # @param [Array, Regex] except matching attributes
+    # @return [Hash] of attributes
+    def to_attributes( only: nil, except: nil )
+      self.class.attributes.each_with_object({}) do |(name, options), attrs|
+        next if ( only && !match_attribute?( only, name ) ) || ( except && match_attribute?( except, name ) )
+        next unless serialize_attribute?( name, options )
+        attrs[name] = send( name )
+      end
+    end
+
+    # Indicates if the object has an attribute with the given name. Aliased to
+    # {#key?} to make the object look like a Hash.
+    def attribute?( name )
+      self.class.attributes.key?( name.to_sym )
+    end
+    alias_method :key?, :attribute?
+
+    # Access an attribute using a Hash like index.
+    # @param [Symbol] name of the attribute.
+    # @return [Object]
+    def []( name )
+      send name if attribute?( name )
+    end
+
+    # @param [Symbol] attribute name.
+    # @return [Boolean] true if the attribute has been set.
+    def set?( attribute )
+      instance_variable_defined? :"@#{ attribute }"
+    end
+
+    private
+
+      def match_attribute?( pattern, name )
+        Array( pattern ).any? do |matcher|
+          matcher === name
+        end
+      end
+
+      # Hook for derived objects to explicitly filter attributes included in
+      # {#to_attributes}
+      def serialize_attribute?( _name, options )
+        options[:serialize]
+      end
+
+      # @!visibility public
+      #
+      # Assign a hash of values to the matching instance variables.
+      #
+      # @param [Hash] attributes to assign.
+      #
+      # @return [self]
+      def assign_attributes( attributes )
+        attributes = resolve_attributes( attributes )
+
+        self.class.attributes.each do |key, options|
+          as = options[ :as ] # Alias support
+          next unless attributes.key?( key ) || ( as && attributes.key?( as ) )
+          value = attributes[ key ]
+          value ||= attributes[ as ] if as
+
+          if build = options[:build]
+            value = build_value( build, value )
+          end
+
+          send :"assign_#{ key }", value
+        end
+      end
+
+      def build_value( build, value )
+        if build.is_a?( Class )
+          klass = build
+          build = ->(v) { klass.new( v ) }
+        end
+
+        build.call( value )
+      end
+
+      def resolve_attributes( attributes )
+        if attributes.respond_to?( :to_attributes )
+          attributes.to_attributes
+        # Allow protected attributes to be used without explicitly being set.
+        # All 'Attributes' classes are them selves the explicit set of permitted
+        # attributes.
+        elsif attributes.respond_to?( :to_hash )
+          attributes.to_hash.symbolize_keys
+        elsif attributes.respond_to?( :to_h )
+          attributes.to_h.symbolize_keys
+        else
+          attributes
+        end
+      end
+
+    class_methods do
+
+      # @return [Hash] of attributes and their options defined on the class.
+      def attributes
+        @attributes ||= {}
+      end
+
+      def inherited( subclass )
+        # Clone the base class's attributes into the subclass
+        subclass.instance_variable_set :@attributes, attributes.dup
+        super
+      end
+
+      # Define a new attribute for the class.
+      #
+      # @overload attribute(name, on:, default:, build: )
+      # @overload attribute(name, build, on:, default:)
+      #
+      # @param [Symbol] name of the attribute.
+      # @param [Symbol] as an alias of the attribute.
+      # @param [Symbol] on another method on the class to delegate the attribute
+      #     to.
+      # @param [Object,#call] default value if not set.
+      # @param [Class,#call] build method used to build a nested object on
+      #     assignement of a hash with nested keys.
+      # @param [Boolean] serialize true if the attribute should be included in
+      #   {#to_attributes}. Default true.
+      # @yieldreturn the value of the attribute. The result is memoized so the
+      #     block is only invoked once.
+      # @return [self]
+      def attribute( name, *args, **options, &block )
+        name    = name.to_sym
+        options = create_attribute( name, *args, **options )
+
+        define_attribute_reader( name, **options )
+        define_attribute_assignment( name, **options )
+
+        if options.key?( :on )
+          define_delegate_fetcher( name, options[:on], options[:build] )
+        else
+          define_virtual_fetcher( name, options[:default], &block )
+        end
+
+        private :"fetch_#{ name }"
+        private :"assign_#{ name }"
+
+
+        self
+      end
+
+      private
+
+        # @return [Array<Symbol>] keys used by the {.attribute} method options
+        #   argument. Used by {Attributes::Validation} to filter option keys.
+        def attribute_option_keys
+          [ :on, :build, :default, :serialize ]
+        end
+
+        def create_attribute( name, *args, **options )
+          options = options.dup
+          options[:build]     = args[0] unless args.blank?
+          options[:serialize] = options.fetch( :serialize, true )
+          attributes[name]    = options
+        end
+
+        def define_attribute_reader( name, as: nil, ** )
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{ name }                                           # def attribute
+              return @#{ name } if defined? @#{ name }              #   return @attribute if defined? @attribute
+              @#{ name } = fetch_#{ name }                          #   @attribute = fetch_attribute
+            end                                                     # end
+          RUBY
+
+          alias_method as, name if as
+        end
+
+        def define_virtual_fetcher( name, default, &block )
+          method_name = :"fetch_#{ name }"
+
+          if block_given?
+            define_method method_name, &block
+          elsif default.respond_to?( :call ) && !default.is_a?( Symbol )
+            define_method method_name, &default
+          elsif default
+            define_method method_name do
+              default
+            end
+          else
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def fetch_#{ name }; @#{ name } end                   # def fetch_attribute; @attribute end
+            RUBY
+          end
+        end
+
+        def define_delegate_fetcher( name, on, builder )
+          if builder
+            define_method :"build_#{ name }" do |value|
+              build_value( builder, value )
+            end
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def fetch_#{ name }                                   # fetch_attribute
+                #{ on } && build_#{ name }( #{ on }.#{ name } )     #   target && build_attribute( target.attribute )
+              end                                                   # end
+            RUBY
+          else
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def fetch_#{ name }                                   # fetch_attribute
+                #{ on } && #{ on }.#{ name }                        #   target && target.attribute
+              end                                                   # end
+            RUBY
+          end
+        end
+
+        def define_attribute_assignment( name, ** )
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def assign_#{ name }( value )                           # assign_attribute( value )
+              @#{ name } = value                                    #   @attribute = value
+            end                                                     # end
+          RUBY
+        end
+
+    end
+
+  end
+end

data/lib/shamu/auditing/audit_record.rb

@@ -0,0 +1,32 @@
+module Shamu
+  module Auditing
+    class AuditRecord < Entities::Entity
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      model :record
+
+      # @!attribute
+      # @return [Integer]
+      attribute :id, on: :record
+
+      # @!attribute
+      # @return [String] an {EntityPath} from the root to the target entity.
+      attribute :entity_path, on: :record
+
+      # @!attribute
+      # @return [Time] when the transaction occured.
+      attribute :timestamp, on: :record
+
+      # @!attribute
+      # @return [Hash] the changes requested.
+      attribute :changes, on: :record
+
+      #
+      # @!endgroup Attributes
+
+    end
+  end
+end

data/lib/shamu/auditing/auditing_service.rb

@@ -0,0 +1,32 @@
+module Shamu
+  module Auditing
+
+    # Records audit {Transaction transactions} to record change requests made to
+    # a {Services::Service} that includes auditing {Support}.
+    #
+    # > **Security Note** the audit service does not enforce any security policies
+    # > for reading or writing. It is expected that audit transactions should be
+    # > recordable by any service and that reading those audits will be limited by
+    # > some admin only accessible resource. To expose the audit records via a web
+    # > interface, create a proxy AuditingService that has it's own
+    # > {Security::Policy} but delegates the actual reading and writing.
+    class AuditingService < Services::Service
+
+      def self.create( scorpion, *args )
+        if defined? ActiveRecord
+          scorpion.fetch Shamu::Auditing::ActiveRecord::Service, *args
+        else
+          fail "No available auditing service available."
+        end
+      end
+
+      # Records an auditable event in persistent storage.
+      # @param [Transaction] transaction
+      # @return [AuditRecord] the persisted record.
+      def commit( transaction )
+        fail NotImplementedError
+      end
+
+    end
+  end
+end

data/lib/shamu/auditing/list_scope.rb

@@ -0,0 +1,22 @@
+module Shamu
+  module Auditing
+    class ListScope < Entities::ListScope
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [String] entity_path
+      attribute :entity_path
+
+      # @!attribute
+      # @return [Object] user_id
+      attribute :user_id
+
+      #
+      # @!endgroup Attributes
+
+    end
+  end
+end

data/lib/shamu/auditing/logging_auditing_service.rb

@@ -0,0 +1,16 @@
+module Shamu
+  module Auditing
+
+    # Writes audit logs to the {Shamu::Logger}.
+    class LoggingAuditingService < Services::Service
+
+      # Records an auditable event in persistent storage.
+      # @param [Transaction] transaction
+      # @return [AuditRecord] the persisted record.
+      def commit( transaction )
+        logger.unknown "AUDIT TRANSACTION action: #{ transaction.action } entity: #{ transaction.entity_path } by user: #{ transaction.user_id_chain } changes: #{ transaction.changes }" # rubocop:disable Metrics/LineLength
+      end
+
+    end
+  end
+end

data/lib/shamu/auditing/support.rb

@@ -0,0 +1,75 @@
+module Shamu
+  module Auditing
+
+    # Add auditing support to a {Services::Servie}.
+    module Support
+      extend ActiveSupport::Concern
+
+      included do
+        include Shamu::Services::RequestSupport
+
+        # ============================================================================
+        # @!group Dependencies
+        #
+
+        # @!attribute
+        # @return [Shamu::Auditing::AuditingService] the service to report audit
+        #     transactions to.
+        attr_dependency :auditing_service, Shamu::Auditing::AuditingService
+
+        #
+        # @!endgroup Dependencies
+
+      end
+
+      private
+
+        # @!visibility public
+        #
+        # Audit the requested changes and report the request to the
+        # {#auditing_service}.
+        #
+        # See {Shamu::Services::RequestSupport#with_request}
+        #
+        # @param (see Shamu::Services::RequestSupport#with_request)
+        # @return (see Shamu::Services::RequestSupport#with_request)
+        # @yield (request, transaction)
+        # @yieldparam [Services::Request] request coerced from `params`.
+        # @yieldparam [Transaction] transaction the audit transaction. Most fields
+        #     will be populated automatically from the request but the block
+        #     should call {Transaction#append_entity} to include any parent
+        #     entities in the entity path.
+        def audit_request( params, request_class, action: :smart, &block )
+          transaction = Transaction.new \
+            user_id_chain: auditing_security_principal.user_id_chain
+
+          result = with_request params, request_class do |request|
+            transaction.action  = audit_request_action( request, action )
+            transaction.changes = request.to_attributes
+
+            yield request, transaction
+          end
+
+          if result.valid?
+            transaction.append_entity result.entity if result.entity
+            auditing_service.commit( transaction )
+          end
+
+          result
+        end
+
+        def auditing_security_principal
+          return @auditing_security_principal if defined? @auditing_security_principal
+
+          @auditing_security_principal = security_principal if defined? security_principal
+          @auditing_security_principal ||= scorpion.fetch Security::Principal
+        end
+
+        def audit_request_action( request, type )
+          return type unless type == :smart
+
+          request.class.name.demodulize.sub( "Request", "" ).underscore
+        end
+    end
+  end
+end

data/lib/shamu/auditing/transaction.rb

@@ -0,0 +1,58 @@
+module Shamu
+  module Auditing
+
+    # An audit record of a discrete change transaction.
+    class Transaction < Services::Request
+      include Shamu::Attributes
+      include Entities::EntityPath
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [Array<Object>] the chain of user ids making the request.
+      attribute :user_id_chain, presence: true
+
+      # @!attribute
+      # @return [String] the primitive action that was requested, such as `add`,
+      #     `remove`, or `change`.
+      attribute :action, presence: true
+
+      # @!attribute
+      # @return [Hash] the changes by attribute requested in the transaction.
+      attribute :changes
+
+      # The {EntityPath} describing how to reach the leaf entity {#append_entity
+      # appended} from the root entity.
+      attribute :entity_path, presence: true do
+        compose_entity_path( entities )
+      end
+
+      #
+      # @!endgroup Attributes
+
+      # Appends a child node to the {#entity_path}.
+      # @overload append_entity( entity )
+      #   @param [Entities::Entity] an entity
+      # @overload append_entity( pair )
+      #   @param [Array<String,Object>] pair consisting of entity class and id.
+      def append_entity( entity )
+        @entities ||= []
+        entities << entity
+      end
+
+      # (see Services::Request#apply_to)
+      def apply_to( model )
+        super.tap do
+          model.changes_json = changes.to_json if changes.present?
+        end
+      end
+
+      private
+
+        attr_reader :entities
+
+    end
+  end
+end

data/lib/shamu/auditing.rb

@@ -0,0 +1,12 @@
+module Shamu
+
+  # {include:file:lib/shamu/auditing/README.md}
+  module Auditing
+    require "shamu/auditing/audit_record"
+    require "shamu/auditing/auditing_service"
+    require "shamu/auditing/logging_auditing_service"
+    require "shamu/auditing/list_scope"
+    require "shamu/auditing/support"
+    require "shamu/auditing/transaction"
+  end
+end

data/lib/shamu/entities/README.md

@@ -0,0 +1 @@
+Entities Rock!

data/lib/shamu/entities/active_record.rb

@@ -0,0 +1,123 @@
+module Shamu
+  module Entities
+
+    # Mixins for working with ActiveRecord resources as {Entity entities}.
+    #
+    # ```
+    # module Domain
+    #   module Models
+    #     class Account < ActiveRecord::Base
+    #       extend Shamu::Entities::ActiveRecord
+    #     end
+    #   end
+    #
+    #   class AccountListScope < Shamu::Entities::ListScope
+    #     attribute :name
+    #   end
+    # end
+    #
+    # list_scope = Domain::AccountListScope.new( name: "Flipper" )
+    # records = Domain::Models::Account.all.by_list_scope( list_scope )
+    # ```
+    module ActiveRecord
+
+      # Apply the filters defined in a {ListScope} to an ActiveRecord::Relation.
+      #
+      # @param [ListScope] scope to apply
+      # @return [ActiveRecord::Relation]
+      def by_list_scope( scope )
+        criteria = all
+        criteria = apply_custom_list_scope( criteria, scope )
+        criteria = apply_paging_scope( criteria, scope )        if scope.respond_to?( :paged? )
+        criteria = apply_scoped_paging_scope( criteria, scope ) if scope.respond_to?( :scoped_page? )
+        criteria = apply_dates_scope( criteria, scope )         if scope.respond_to?( :dated? )
+        criteria = apply_sorting_scope( criteria, scope )       if scope.respond_to?( :sorted? )
+        criteria
+      end
+
+      #
+      # @!endgroup Scopes
+
+
+      private
+
+        # @!visibility public
+        #
+        # Apply sorting to the criteria for the given field and the given
+        # direction.
+        #
+        # @param [ActiveRecord::Relation] criteria to sort.
+        # @param [Symbol] field to sort by.
+        # @param [Symbol] direction to sort.
+        # @return [ActiveRecord::Relation] the sorted criteria.
+        def apply_sort( criteria, field, direction )
+          if attribute_method?( field )
+            criteria.order( arel_table[ field ].send( direction ) )
+          else
+            criteria
+          end
+        end
+
+        def apply_sorting_scope( criteria, scope )
+          if scope.sort_by
+            criteria = scope.sort_by.reduce( criteria ) do |crit, ( field, direction )|
+              apply_sort( crit, field, direction )
+            end
+          end
+
+          criteria
+        end
+
+        def apply_paging_scope( criteria, scope )
+          if scope.paged?
+            criteria = criteria.page( scope.page || 1 )
+            criteria = criteria.per( scope.per_page ) if scope.per_page
+          end
+          criteria
+        end
+
+        def apply_scoped_paging_scope( criteria, scope )
+          if scope.scoped_page?
+            criteria = criteria.page( scope.page.number || 1 )
+            criteria = criteria.per( scope.page.size ) if scope.page.size
+          end
+          criteria
+        end
+
+        def apply_dates_scope( criteria, scope )
+          criteria = criteria.where( criteria.arel_table[:since].gteq( scope.since ) ) if scope.since
+          criteria = criteria.where( criteria.arel_table[:until].lteq( scope.until ) ) if scope.until
+          criteria
+        end
+
+        def apply_custom_list_scope( criteria, scope )
+          custom_list_scope_attributes( scope ).each do |name|
+            scope_name = :"by_#{ name }"
+            if criteria.respond_to?( scope_name )
+              value    = scope.send( name )
+              criteria = criteria.send scope_name, value if value.present?
+            else
+              # rubocop:disable Metrics/LineLength
+              fail ArgumentError, "Cannot apply '#{ name }' filter from #{ scope.class.name }. Add 'scope :#{ scope_name }, ->( #{ name } ) { ... }' to #{ criteria.class.name }"
+            end
+          end
+
+          criteria
+        end
+
+        def custom_list_scope_attributes( scope )
+          scope.class.attributes.keys - StandardListScopeTemplate.attributes.keys
+        end
+
+        # @!visibility private
+        # @api internal
+        class StandardListScopeTemplate < ListScope
+          include ListScope::Paging
+          include ListScope::ScopedPaging
+          include ListScope::Dates
+          include ListScope::Sorting
+        end
+
+    end
+  end
+end