shamu 0.0.21 → 0.0.24

data/lib/shamu/services/lazy_association.rb

@@ -2,30 +2,62 @@ module Shamu
   module Services
 
     # Lazily look up an associated resource
-    class LazyAssociation < Delegator
+    module LazyAssociation
+      EXCLUDE_PATTERN = /\A(block_given\?|id|send|public_send|iterator|object_id|to_model_id|binding|class|kind_of\?|is_a\?|instance_of\?|respond_to\?|p.+_methods|__.+__)\z/ # rubocop:disable Metrics/LineLength
+      MUTEX = Mutex.new
 
-      # ============================================================================
-      # @!group Attributes
-      #
+      def self.class_for( klass ) # rubocop:disable Metrics/MethodLength, Metrics/PerceivedComplexity
+        return klass.const_get( :Lazy_ ) if klass.const_defined?( :Lazy_ )
 
-      # @!attribute
-      # @return [Object] the primary key id of the association. Not delegated so
-      #     it is safe to use and will not trigger an unnecessary fetch.
-      attr_reader :id
+        MUTEX.synchronize do
 
-      #
-      # @!endgroup Attributes
+          # Check again in case another thread defined it while waiting for the
+          # mutex
+          return klass.const_get( :Lazy_ ) if klass.const_defined?( :Lazy_ )
 
-      def initialize( id, &block )
-        @id = id
-        @block = block
-      end
+          lazy_class = Class.new( klass ) do
+            # Remove all existing public methods so that they can be delegated
+            # with #method_missing.
+            klass.public_instance_methods.each do |method|
+              next if EXCLUDE_PATTERN =~ method
+              undef_method method
+            end
+
+            def initialize( id, &block )
+              @id = id
+              @block = block
+            end
+
+            # @!attribute
+            # @return [Object] the primary key id of the association. Not delegated so
+            #     it is safe to use and will not trigger an unnecessary fetch.
+            attr_reader :id
+
+            def __getobj__
+              return @association if defined? @association
 
-      def __getobj__
-        return @association if defined? @association
+              @association = @block.call( @id ) if @block
+            end
 
-        @association = @block.call
+            def method_missing( method, *args, &block )
+              if respond_to_missing?( method )
+                __getobj__.public_send( method, *args, &block )
+              else
+                super
+              end
+            end
+
+            def respond_to_missing?( method, include_private = false )
+              __getobj__.respond_to?( method, include_private ) || super
+            end
+
+          end
+
+          klass.const_set( :Lazy_, lazy_class )
+          lazy_class
+        end
       end
+
     end
   end
-end
+end

data/lib/shamu/services/observable_support.rb

@@ -0,0 +1,73 @@
+module Shamu
+  module Services
+
+    # Adds the ability for other services to observe requests on the service.
+    #
+    # In contrast to {Events} that are async and independent, observers are
+    # called immediately when a request is performed and may influence the
+    # behavior of the request.
+    #
+    # See {#ObserverSupport} for details on observing other services.
+    module ObservableSupport
+
+      # Ask to be notified of important actions as they are executed on the
+      # service.
+      #
+      # @yield (observed_request)
+      # @yieldparam [ObservedRequest] action
+      def observe( &block )
+        @observers ||= []
+        @observers << block
+      end
+
+      private
+
+        # @!visibility public
+        #
+        # Invoke a block notifying observers before the action is performed
+        # allowing them to modify inputs or request the action be canceled.
+        #
+        # @param [Request] request the service request
+        # @return [Result]
+        # @yield [Request]
+        def with_observers( request, &block )
+          observed = ObservedRequest.new( request: request )
+          notify_observers( observed )
+
+          returned =
+            if observed.cancel_requested?
+              request.error :base, :canceled
+            else
+              yield( request )
+            end
+
+          result = Result.coerce( returned, request: request )
+
+          observed.complete( result, false )
+        end
+
+        # @!visibility public
+        #
+        # Notify all registered observers about the pending request.
+        # @param [ObservedAction] observed_action
+        def notify_observers( observed_action )
+          return unless defined? @observers
+
+          @observers.each do |observer|
+            observer.call( observed_action )
+          end
+        end
+
+        # Override {Shamu::Services::RequestSupport#with_partial_request} to make all requests observable.
+        # {#audit_request audit the request}.
+        def with_partial_request( *args, &block )
+          super( *args ) do |request|
+            with_observers request do |wrapped_request|
+              yield wrapped_request
+            end
+          end
+        end
+
+    end
+  end
+end

data/lib/shamu/services/observed_request.rb

@@ -0,0 +1,76 @@
+module Shamu
+  module Services
+
+    # Describes request that will be/has been performed by a service and the
+    # associated data properties.
+    class ObservedRequest
+      include Shamu::Attributes
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [Request] the original request submitted to the service. The
+      # request may be modified by the observers.
+      attribute :request
+
+      # @return [Result] the result of a dependency that asked for the request
+      # to be canceled.
+      attr_reader :cancel_reason
+
+      #
+      # @!endgroup Attributes
+
+      # Ask that the service cancel the request.
+      #
+      # @return [Result] a nested result that should be reported for why the
+      # request was canceled.
+      def request_cancel( result = Result.new )
+        @cancel_reason = result
+      end
+
+      # @return [Boolean] true if an observer has asked the request to be
+      # canceled.
+      def cancel_requested?
+        !!cancel_reason
+      end
+
+      # Execute block if the action was canceled by another observer.
+      # @yield(result)
+      # @yieldresult [Result]
+      def on_canceled( &block )
+        @on_cancel_blocks ||= []
+        @on_cancel_blocks << block
+      end
+
+      # Mark the action as complete and run any {#on_success} or #{on_fail}
+      # callbacks.
+      #
+      # @param [Result] result the result of the action. If valid success callbacks are invoked.
+      # @param [Boolean] canceled true if the action was canceled and not
+      # processed.
+      #
+      # @return [Result] the result of all the observed callbacks.
+      def complete( result, canceled )
+        invoke_callbacks( result, @on_cancel_blocks ) if canceled
+
+        result
+      end
+
+      private
+
+        def invoke_callbacks( result, callbacks )
+          return unless callbacks.present?
+
+          callbacks.each do |callback|
+            nested = callback.call( result )
+            result.join( nested ) if nested
+          end
+
+          result
+        end
+
+    end
+  end
+end

data/lib/shamu/services/request.rb

@@ -85,6 +85,18 @@ module Shamu
         @on_complete_blocks && @on_complete_blocks.each( &:call )
       end
 
+      # Adds an error to {#errors} and returns self. Used when performing an
+      # early return in a service method
+      #
+      # @example
+      #   next request.error( :title, "should be clever" ) unless title_is_clever?
+      #
+      # @return [self]
+      def error( *args )
+        errors.add( *args )
+        self
+      end
+
       class << self
         # Coerces a hash or params object to a proper {Request} object.
         # @param [Object] params to be coerced.

data/lib/shamu/services/request_support.rb

@@ -58,7 +58,7 @@ module Shamu
         #       order = Models::Order.find( request.id )
         #
         #       # Custom validation
-        #       next error( :base, "can't do that" ) if order.state == 'processed'
+        #       next request.error( :base, "can't do that" ) if order.state == 'processed'
         #
         #       request.apply_to( order )
         #
@@ -66,7 +66,7 @@ module Shamu
         #       next order unless order.save
         #
         #       # All good, return an entity for the order
-        #       scorpion.fetch OrderEntity, { order: order }, {}
+        #       scorpion.fetch OrderEntity, { order: order }
         #     end
         #   end
         def with_request( params, request_class, &block )
@@ -92,10 +92,32 @@ module Shamu
 
           result = Result.coerce( sources, request: request )
           request.complete( result.valid? )
+          recache_entity( result.entity ) if result.valid? && result.entity
 
           result
         end
 
+        # Support convenient calling convention on update/delete style methods
+        # that might pass an id and params or a single params hash with
+        # associated id.
+        #
+        # @example
+        #   users.update user, name: "Changed"  # Backend service
+        #   users.update id: 1, name: "Changed" # HTTP request params
+        #
+        def extract_params( id, params )
+          if !params && !id.respond_to?( :to_model_id )
+            params, id = id, id[ :id ] || id[ "id" ]
+          end
+
+          if params
+            params = params.symbolize_keys if params.respond_to?( :symbolize_keys )
+            params[ :id ] ||= id
+          end
+
+          [ id, params ]
+        end
+
       # Static methods added to {RequestSupport}
       class_methods do
 

data/lib/shamu/services/result.rb

@@ -38,6 +38,12 @@ module Shamu
         value
       end
 
+      # @return [Array<Result>] results from calling dependent assemblies that
+      # may have caused the request to fail.
+      def nested_results
+        @nested_results ||= []
+      end
+
       #
       # @!endgroup Attributes
 
@@ -48,7 +54,7 @@ module Shamu
       #   the first {Request} object found in the `values`.
       # @param [Entities::Entity] entity submitted to the service. If :not_set,
       #   uses the first {Entity} object found in the `values`.
-      def initialize( *values, request: :not_set, entity: :not_set ) # rubocop:disable Metrics/LineLength, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def initialize( *values, request: :not_set, entity: :not_set ) # rubocop:disable Metrics/LineLength, Metrics/PerceivedComplexity
         @values = values
         @value  = values.first
 
@@ -97,6 +103,12 @@ module Shamu
         self
       end
 
+      # Joins a dependency's result to the result of the request.
+      def join( result )
+        nested_results << result
+        append_error_source result
+      end
+
       # @return [Result] the value coerced to a {Result}.
       def self.coerce( value, **args )
         if value.is_a?( Result )
@@ -106,6 +118,55 @@ module Shamu
         end
       end
 
+      # @return [String] debug friendly string
+      def inspect # rubocop:disable Metrics/AbcSize
+        result = "#<#{ self.class } valid: #{ valid? }"
+        result << ", errors: #{ errors.inspect }" if errors.any?
+        result << ", entity: #{ entity.inspect }" if entity
+        result << ", value: #{ value.inspect }"   if value && value != entity
+        result << ", values: #{ values.inspect }" if values.length > 1
+        result << ">"
+        result
+      end
+
+      # @return [String] even friendlier debug string.
+      def pretty_print( pp ) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        pp.object_address_group( self ) do
+          pp.breakable " "
+          pp.text "valid: "
+          pp.pp valid?
+
+          if errors.any?
+            pp.comma_breakable
+            pp.text "errors:"
+            pp.breakable " "
+            pp.pp errors
+          end
+
+          if entity
+            pp.comma_breakable
+            pp.text "entity:"
+            pp.breakable " "
+            pp.pp entity
+          end
+
+          if !value.nil? && value != entity
+            pp.comma_breakable
+            pp.text "value:"
+            pp.breakable " "
+            pp.pp value
+          end
+
+          if values.length > 1
+            pp.comma_breakable
+            pp.text "values:"
+            pp.breakable " "
+            pp.pp values - [ value ]
+          end
+        end
+      end
+
+
       private
 
         def append_error_source( source )

data/lib/shamu/services/service.rb

@@ -53,7 +53,7 @@ module Shamu
     #     ```
     #     def report( report_scope = nil )
     #       report_scope = UserReportScope.coerce! report_scope
-    #       scorpion.fetch UserReport, report_scope, {}
+    #       scorpion.fetch UserReport, report_scope
     #     end
     #     ```
     class Service
@@ -61,9 +61,6 @@ module Shamu
       # Support dependency injection for related services.
       include Scorpion::Object
 
-      initialize do
-      end
-
       private
 
         # Maps a single record to an entity. Requires a `build_entities` method
@@ -133,7 +130,7 @@ module Shamu
         #   def lookup( *ids )
         #     records = Models::Favorite.all.where( id: ids )
         #     entity_lookup_list records, ids, NullEntity.for( FavoriteEntity ) do |record|
-        #       scorpion.fetch FavoriteEntity, { record: record }, {}
+        #       scorpion.fetch FavoriteEntity, { record: record }
         #     end
         #   end
         #
@@ -141,7 +138,7 @@ module Shamu
         #     records = Models::Favorite.all.where( :name.in( names ) )
         #
         #     entity_lookup_list records, names, NullEntity.for( FavoriteEntity ), match: :name do |record|
-        #       scorpion.fetch FavoriteEntity, { record: record }, {}
+        #       scorpion.fetch FavoriteEntity, { record: record }
         #     end
         #   end
         #
@@ -150,7 +147,7 @@ module Shamu
         #     matcher = ->( record ) { record.name.downcase }
         #
         #     entity_lookup_list records, names, NullEntity.for( FavoriteEntity ), match: matcher do |record|
-        #       scorpion.fetch FavoriteEntity, { record: record }, {}
+        #       scorpion.fetch FavoriteEntity, { record: record }
         #     end
         #   end
         #
@@ -162,19 +159,25 @@ module Shamu
 
           list = entity_list records, &transformer
           matched = ids.map do |id|
-            list.find { |e| matcher.call( e ) == id } || scorpion.fetch( null_class, { id: id }, {} )
+            list.find { |e| matcher.call( e ) == id } || scorpion.fetch( null_class, id: id )
           end
 
           Entities::List.new( matched )
         end
 
+          ID_MATCHER = ->( record ) { record && record.id }
+
           def entity_lookup_list_matcher( match )
             if !match.is_a?( Symbol ) && match.respond_to?( :call )
               match
             elsif match == :id
-              ->( record ) { record && record.id }
+              ID_MATCHER
             else
-              ->( record ) { record && record.send( match ) }
+              @@matcher_proc_cache ||= Hash.new do |hash, key| # rubocop:disable Style/ClassVars
+                hash[ key ] = ->( record ) { record && record.send( key ) }
+              end
+
+              @@matcher_proc_cache[ match ]
             end
           end
 
@@ -208,10 +211,15 @@ module Shamu
         #   end
         def find_by_lookup( id )
           entity = lookup( id ).first
-          raise Shamu::NotFoundError unless entity.present?
+          not_found!( id ) unless entity.present?
           entity
         end
 
+        # @exception [Shamu::NotFoundError]
+        def not_found!( id = :not_set )
+          raise Shamu::NotFoundError, id: id
+        end
+
         # @!visibility public
         #
         # Find an associated entity from a dependent service. Attempts to
@@ -221,22 +229,23 @@ module Shamu
         #
         # @param [Object] id of the associated {Entities::Entity} to find.
         # @param [Service] service used to locate the associated resource.
+        # @param [IdentityCache] cache to store found associations.
         # @return [Entity] the found entity or a {Entities::NullEntity} if the
         #     association doesn't exist.
         #
         # @example
         #
-        #   def build_entity( record, records = nil )
-        #     owner = lookup_association record.owner_id, users_service do
+        #   def build_entities( records )
+        #     cache = cache_for( entity: users_service )
+        #     owner = lookup_association record.owner_id, users_service, cache do
         #               records.pluck( :owner_id ) if records
         #             end
         #
-        #     scorpion.fetch UserEntity, { record: record, owner: owner }, {}
+        #     scorpion.fetch UserEntity, { record: record, owner: owner }
         #   end
-        def lookup_association( id, service, &block )
+        def lookup_association( id, service, cache, &block )
           return unless id
 
-          cache = cache_for( entity: service )
           cache.fetch( id ) || begin
             if block_given? && ( ids = yield )
               service.lookup( *ids ).map do |entity|
@@ -253,20 +262,33 @@ module Shamu
 
         # @!visibility public
         #
-        # Perform a lazy {#lookup_association} and only load the entity if its
-        # actually dereferenced by the caller.
+        # Build a proxy object that delays yielding to the block until a method
+        # on the association is invoked.
+        #
+        # @example
+        #   user = lazy_association 10, Users::UserEntity do
+        #            expensive_lookup_user.find( 10 )
+        #          end
+        #
+        #   user.id   # => 10 expensive lookup not performed
+        #   user.name # => "Trump" expensive lookup executed, cached, then
+        #             #    method invoked on real object
         #
-        # @param (see #lookup_association)
+        # @param [Integer] id of the resource.
+        # @param [Class] entity_class of the resource.
         # @return [LazyAssociation<Entity>]
-        def lazy_association( id, service, &block )
-          LazyAssociation.new( id ) do
-            lookup_association id, service, &block
-          end
+        def lazy_association( id, entity_class, &block )
+          return nil if id.nil?
+
+          LazyAssociation.class_for( entity_class ).new( id, &block )
         end
 
         # @!visibility public
         #
         # Get the {Entities::IdentityCache} for the given {Entities::Entity} class.
+        # @param [Service#entity_class] dependency_service the dependent
+        #   {Service} to cache results from. Must respond to `#entity_class` that
+        #   returns the {Entities::Entity} class to cache.
         # @param [Class] entity the type of entity that will be cached. Only
         #     required if the service manages multiple entities.
         # @param [Symbol,#call] key the attribute on the entity, or a custom
@@ -275,8 +297,10 @@ module Shamu
         #     to the same type (eg :to_i). If not set, automatically uses :to_i
         #     if key is an 'id' attribute.
         # @return [Entities::IdentityCache]
-        def cache_for( key: :id, entity: nil, coerce: :not_set )
+        def cache_for( dependency_service = nil, key: :id, entity: nil, coerce: :not_set )
           coerce = coerce_method( coerce, key )
+          entity ||= dependency_service
+          entity = entity.entity_class if entity.respond_to?( :entity_class )
 
           cache_key        = [ entity, key, coerce ]
           @entity_caches ||= {}
@@ -328,16 +352,17 @@ module Shamu
             end
           end
 
-        # @!visibility public
+        # @!visbility public
         #
-        # Return an error {#result} from a service request.
-        # @overload error( attribute, message )
-        # @param (see ErrorResult#initialize)
-        # @return [ErrorResult]
-        def error( *args )
-          Result.new.tap do |r|
-            r.errors.add( *args )
-          end
+        # After a mutation method call to make sure the cache for the entity
+        # is updated to reflect the new entity state.
+        #
+        # @param [Entity] entity in the new modified state.
+        def recache_entity( entity, match: :id )
+          matcher = entity_lookup_list_matcher( match )
+          cache = cache_for( key: match )
+
+          cache.add( matcher.call( entity ), entity )
         end
 
     end