shamu 0.0.1 → 0.0.2

data/lib/shamu/services/active_record.rb

@@ -0,0 +1,58 @@
+module Shamu
+  module Services
+
+    # Helper methods useful for services that interact with {ActiveRecord::Base}
+    # models.
+    module ActiveRecord
+
+      private
+
+        # @!visibility public
+        #
+        # Watch for ActiveRecord::RecordNotFound errors and rethrow as a
+        # {Shamu::NotFoundError}.
+        def wrap_not_found( &block )
+          yield
+        rescue ::ActiveRecord::RecordNotFound
+          raise Shamu::NotFoundError
+        end
+
+        # @!visibility public
+        #
+        # Wrap all the changes to any ActiveRecord resource in a transaction.
+        # @param [Hash] options to pass to
+        #     ActiveRecord::Transactions.transaction.
+        # @yieldreturn [Result] the validation sources for the transaction. See
+        #     {Service#with_result}.
+        # @return [Result]
+        def with_transaction( options = {}, &block )
+          result = nil
+
+          ::ActiveRecord::Base.transaction options do
+            result = yield
+            raise ::ActiveRecord::Rollback if result && !result.valid?
+          end
+
+          result
+        end
+
+        # @!visibility public
+        #
+        # Apply the filters specified in `list_scope` to the `relation`.
+        #
+        # @param [ActiveRecord::Relation] relation to filter.
+        # @param [Entities::ListScope] list_scope to apply.
+        # @return [ActiveRecord::Relation] the scoped relation.
+        def scope_relation( relation, list_scope )
+          return unless relation
+
+          if relation.respond_to?( :by_list_scope )
+            relation.by_list_scope( list_scope )
+          else
+            fail "Can't scope a #{ relation.klass }. Add `scope :by_list_scope, ->(list_scope) { ... }` or include Shamu::Entities::ActiveRecord." # rubocop:disable Metrics/LineLength
+          end
+        end
+
+    end
+  end
+end

data/lib/shamu/services/active_record_crud.rb

@@ -0,0 +1,378 @@
+module Shamu
+  module Services
+
+    # Adds standard CRUD builders to an {ActiveRecordService} to reduce
+    # boilerplate for common methods.
+    #
+    # @example
+    #
+    #   class UsersService < Shamu::Services::Service
+    #     include Shamu::Services::Crud
+    #
+    #     # Define the resource that the service will manage
+    #     resource UserEntity, Models::User
+    #
+    #     # Define finder methods #find, #list and #lookup using the given
+    #     # default scope.
+    #     finders Models::User.active
+    #
+    #     # Define change methods
+    #     create
+    #     update
+    #
+    #     # Common update/change behavior for #create and #update
+    #     change do |request, model|
+    #       model.last_updated_at = Time.now
+    #     end
+    #
+    #     # Standard destroy method
+    #     destroy
+    #
+    #     # Build the entity class from the given record.
+    #     build_entity do |record, records = nil|
+    #       parent = lookup_association( record.parent_id, self ) do
+    #                  records.pluck( :parent_id ) if records
+    #                end
+    #
+    #       scorpion.fetch UserEntity, { parent: parent }, {}
+    #     end
+    #   end
+    module ActiveRecordCrud
+      extend ActiveSupport::Concern
+
+      # Known DSL methods defined by {ActiveRecordCrud}.
+      DSL_METHODS = %i( create update change destroy find list lookup finders ).freeze
+
+      included do |base|
+        base.include Shamu::Services::RequestSupport
+        base.include Shamu::Services::ActiveRecord
+      end
+
+      private
+
+        def model_class
+          self.class.model_class
+        end
+
+        def entity_class
+          self.class.model_class
+        end
+
+        # @!visibility public
+        #
+        # Hook to allow a security module to authorize actions taken by the
+        # standard CRUD methods. If authorization is not granted, then an
+        # exception should be raised. Default behavior is a no-op.
+        #
+        # @param [Symbol] method on the service that was invoked.
+        # @param [Entities::Entity, Class, Symbol] resource the entity, class or
+        #     arbitrary symbol describing the resource that the service method
+        #     applies to.
+        # @param [Object] additional_context that the security module might
+        #     consider when authorizing the transaction.
+        # @return [resource] the resource given to authorize.
+        def authorize!( method, resource, additional_context = nil )
+          resource
+        end
+
+        # @!visibility public
+        #
+        # Hook to allow a security module to pre-filter ActiveRecord queries
+        # for the standard crud methods. Default behavior is a no-op.
+        #
+        # @param [Symbol] method on the service that was invoked.
+        # @param [ActiveRecord::Relation] relation to filter
+        # @param [Object] additional_context that the security module might
+        #     consider when authorizing the transaction.
+        #
+        # @return [relation] the filtered relation.
+        def authorize_relation( method, relation, additional_context = nil )
+          relation
+        end
+
+      class_methods do
+
+        # Declare the entity and resource classes used by the service.
+        #
+        # Creates instance and class level methods `entity_class` and
+        # `model_class`.
+        #
+        # See {.build_entity} for build_entity block details.
+        #
+        # @param [Class] entity_class the {Entities::Entity} class that will be
+        #   returned by finders and mutator methods.
+        # @param [Class] model_class the {ActiveRecord::Base} model
+        # @param [Array<Symbol>] methods the {DSL_METHODS DSL methods} to
+        #     include (eg :create, :update, :find, etc.)
+        # @yield (record, records = nil )
+        # @yieldparam [ActiveRecord::Base] record to build an {Entities::Entity}
+        #     for.
+        # @yieldparam [ActiveRecord::Relation] records that are all being built
+        # @yieldreturn [Entities::Entity] the entity projection for the given
+        #     record.
+        # @return [void]
+        def resource( entity_class, model_class, methods: nil, &block )
+          private define_method( :entity_class )   { entity_class }
+          define_singleton_method( :entity_class ) { entity_class }
+
+          private define_method( :model_class )    { model_class }
+          define_singleton_method( :model_class )  { model_class }
+
+          ( Array( methods ) & DSL_METHODS ).each do |method|
+            send method
+          end
+
+          build_entity( &block )
+        end
+
+        # @return [Class] the {Entities::Entity} class that the service will
+        #     return from it's methods.
+        def entity_class
+          resource_not_configured
+        end
+
+        # @return [Class] the {ActiveRecord::Base} class used to store the data
+        #     managed by the service.
+        def model_class
+          resource_not_configured
+        end
+
+        # Define a `#create` method on the service that takes a single {Request}
+        # parameter.
+        #
+        # See {.apply_changes} for details.
+        # @yield (see .apply_changes)
+        # @yieldparam (see .apply_changes)
+        # @return [void]
+        def create( &block )
+          define_method :create do |params = nil|
+            with_request params, request_class( :create ) do |request|
+              authorize! :create, entity_class, request
+
+              record = request.apply_to( model_class.new )
+              if block
+                yield( request, record )
+              elsif respond_to? :apply_changes
+                apply_changes( request, record )
+              end
+
+              next record unless record.save
+              build_entity record
+            end
+          end
+        end
+
+        # Define an change `method` on the service that takes the id of the
+        # resource to modify and a corresponding {Request} parameter.
+        #
+        # See {.apply_changes} for details.
+        # @yield (see .apply_changes)
+        # @yieldparam (see .apply_changes)
+        # @return [Result] the result of the request.
+        # @return [void]
+        def change( method = :update, &block )
+          define_method method do |id, params = nil|
+            with_request params, request_class( method ) do |request|
+              record = model_class.find( id.to_model_id )
+              authorize! method, build_entity( record ), request
+
+              request.apply_to( record )
+
+              if block
+                yield( request, record )
+              elsif respond_to? :apply_changes
+                apply_changes( request, record )
+              end
+
+              next record unless record.save
+              build_entity record
+            end
+          end
+        end
+
+        # Define an `update` method on the service that takes the id of the
+        # resource to update and a {Request} parameter. After applying the
+        # changes the record is persisted and the updated entity result is
+        # returned.
+        #
+        # See {.apply_changes} for details.
+        # @yield (see .apply_changes)
+        # @yieldparam (see .apply_changes)
+        # @return [void]
+        def update( &block )
+          change :update, &block
+        end
+
+        # Define a private method `apply_changes` on the service used by the
+        # {.create} and {.change} defined methods to apply changes in a
+        # {Request} to the model.
+        #
+        # @yield ( request, record ) a block that applies changes in the
+        #     `request` to the `record`.
+        # @yieldparam [Request] request the {Request} containing all the changes
+        #     that should be applied to the `record`.
+        # @yieldparam [ActiveRecord::Base] record the record to be updated.
+        # @yieldreturn [void]
+        # @return [void]
+        def apply_changes( &block )
+          define_method :apply_changes, &block
+          private :apply_changes
+        end
+
+        # Define the standard finder methods {.find}, {.lookup} and {.list}.
+        #
+        # @param [ActiveRecord::Relation] default_scope to use when finding
+        #     records.
+        # @return [void]
+        def finders( default_scope = model_class.all, only: nil, except: nil )
+          methods = Array( only || [ :find, :lookup, :list ] )
+          methods -= Array( except ) if except
+
+          methods.each do |method|
+            send method, default_scope
+          end
+        end
+
+        # Define a `find( id )` method on the service that returns the entity
+        # with the given id if found or raises a {Shamu::NotFoundError} if the
+        # entity does not exist.
+        #
+        # @param [ActiveRecord::Relation] default_scope to use when finding
+        #     records.
+        # @yield (id)
+        # @yieldreturn (ActiveRecord::Base) the found record.
+        # @return [void]
+        def find( default_scope = model_class.all, &block )
+          if block_given?
+            define_method :find do |id|
+              wrap_not_found do
+                record = yield( id )
+                authorize! :read, build_entity( record )
+              end
+            end
+          else
+            define_method :find do |id|
+              authorize! :read, find_by_lookup( id )
+            end
+          end
+        end
+
+        # Define a `lookup( *ids )` method that takes a list of entity ids to
+        # find. Calls {#build_entity} for each found record, or constructs a
+        # {Entities::NullEntity} for ids that were not found.
+        #
+        # @param [ActiveRecord::Relation] default_scope to use when finding
+        #     records.
+        # @yield (uncached_ids)
+        # @yieldparam [Array<Object>] ids that need to be fetched from the
+        #     underlying resource.
+        # @yieldreturn [ActiveRecord::Relation] records for ids found in the
+        #     underlying resource.
+        # @return [void]
+        def lookup( default_scope = model_class.all, &block )
+          define_method :lookup do |*ids|
+            cached_lookup( ids ) do |uncached_ids|
+              records = block_given? ? yield( uncached_ids ) : default_scope.where( id: uncached_ids )
+              records = authorize_relation :read, records
+              entity_lookup_list records, uncached_ids, entity_class.null_entity
+            end
+          end
+        end
+
+        # Define a `list( params = nil )` method that takes a
+        # {Entities::ListScope} and returns all the entities selected by that
+        # scope.
+        #
+        # @param [ActiveRecord::Relation] default_scope to use when finding
+        #     records.
+        # @yield (scope)
+        # @yieldparam [ListScope] scope to apply.
+        # @yieldreturn [ActiveRecord::Relation] records matching the given scope.
+        # @return [void]
+        def list( default_scope = model_class.all, &block )
+          define_method :list do |params = nil|
+            list_scope = Entities::ListScope.for( entity_class ).coerce( params )
+            authorize! :list, entity_class, list_scope
+
+            records    = block_given? ? yield( scope ) : scope_relation( default_scope, list_scope )
+            records    = authorize_relation( :read, records, list_scope )
+
+            entity_list records
+          end
+        end
+
+        # Define a `destroy( id )` method that takes an {Entities::Entity} {Entities::Entity#id}
+        # and destroys the resource.
+        #
+        # @param [ActiveRecord::Relation] default_scope to use when finding
+        #     records.
+        # @return [void]
+        def destroy( default_scope = model_class.all )
+          define_method :destroy do |id|
+            wrap_not_found do
+              record = default_scope.find( id.to_model_id )
+              authorize! :destroy, build_entity( record )
+              record.destroy
+            end
+          end
+        end
+
+        # Define a private `build_entity( record, records = nil )` method that
+        # constructs an {Entities::Entity} from the given `record`. The optional
+        # `records` argument is used when constructing a list of entities so
+        # that associations can all be fetched once and cached while building
+        # the list of entities.
+        #
+        # If no block is given, creates a simple builder that simply constructs
+        # an instance of the {.entity_class} passing `record: record` to the
+        # initializer.
+        #
+        # See {Service#lookup_association} for details on association caching.
+        #
+        # @yield (record, records = nil )
+        # @yieldparam [ActiveRecord::Base] record to build an {Entities::Entity}
+        #     for.
+        # @yieldparam [ActiveRecord::Relation] records that are all being built.
+        # @yieldreturn [Entities::Entity] the entity projection for the given
+        #     record.
+        # @return [void]
+        def build_entity( &block )
+          if block_given?
+            define_method :build_entity_instance, &block
+          else
+            define_method :build_entity_instance do |record, _ = nil|
+              scorpion.fetch( entity_class, { record: record }, {} )
+            end
+          end
+
+          define_method :build_entity do |record, records = nil|
+            authorize! :read, build_entity_instance( record, records )
+          end
+
+          private :build_entity
+          private :build_entity_instance
+        end
+
+        private
+
+          def resource_not_configured
+            raise IncompleteSetupError, "Resource has not been defined. Add `resource #{ inferred_namespace }#{ inferred_resource_name }Entity, #{ inferred_namespace }Models::#{ inferred_resource_name }` to #{ name }." # rubocop:disable Metrics/LineLength
+          end
+
+          def inferred_resource_name
+            inferred = name || "Resource"
+            inferred.split( "::" ).last.sub /Service/, ""
+          end
+
+          def inferred_namespace
+            parts = ( name || "Resource" ).split( "::" )
+            parts.pop
+            return "" if parts.empty?
+            parts.join( "::" ) << "::"
+          end
+
+      end
+
+    end
+  end
+end

data/lib/shamu/services/error.rb

@@ -0,0 +1,24 @@
+require "i18n"
+
+module Shamu
+
+  module Services
+    # A generic error class for problems with shamu services.
+    class Error < Shamu::Error
+      private
+
+        def translation_scope
+          super.dup.insert( 1, :services )
+        end
+
+    end
+
+    # The service has included a module that requires some setup or
+    # configuration but it hasn't been setup properly.
+    class IncompleteSetupError < Error
+      def initialize( message = :incomplete_setup )
+        super
+      end
+    end
+  end
+end

data/lib/shamu/services/lazy_association.rb

@@ -0,0 +1,31 @@
+module Shamu
+  module Services
+
+    # Lazily look up an associated resource
+    class LazyAssociation < Delegator
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!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
+
+      #
+      # @!endgroup Attributes
+
+      def initialize( id, &block )
+        @id = id
+        @block = block
+      end
+
+      def __getobj__
+        return @association if defined? @association
+
+        @association = @block.call
+      end
+    end
+  end
+end

data/lib/shamu/services/lazy_transform.rb

@@ -0,0 +1,97 @@
+module Shamu
+  module Services
+
+    # Lazily transform one enumerable to another with shortcuts for common
+    # collection methods such as first, count, etc.
+    class LazyTransform
+      include Enumerable
+
+      # @param [Enumerable] source enumerable to transform.
+      # @yieldparam [Object] object the original value.
+      # @yieldreturn the transformed value.
+      # @yield (object)
+      def initialize( source, &transformer )
+        @transformer = transformer
+        @source      = source
+      end
+
+      # Yields each transformed value from the original source to the block.
+      #
+      # @yield (object)
+      # @yieldparam [Object] object
+      # @return [self]
+      def each( &block )
+        transformed.each( &block )
+        self
+      end
+
+      # (see Enumerable#count)
+      # @return [Integer]
+      def count( *args )
+        if args.any? || block_given?
+          super
+        else
+          source.count
+        end
+      end
+      alias_method :size, :count
+      alias_method :length, :count
+
+      # Get the first transformed value without transforming the entire list.
+      # @overload first(n)
+      # @overload first
+      # @return [Object]
+      def first( *args )
+        if args.any?
+          super
+        else
+          return @first if defined? @first
+          @first = begin
+            value = source.first
+            transformer.call( value ) unless value.nil?
+          end
+        end
+      end
+
+      # @return [Boolean] true if there are no source values.
+      def empty?
+        source.empty?
+      end
+
+      # @param [Integer] n number of source entries to take.
+      # @return [LazyTransform] a new {LazyTransform} taking only `n` source
+      #     entries.
+      def take( n )
+        if transformed?
+          super
+        else
+          self.class.new( source.take( n ), &transformer )
+        end
+      end
+
+      # @param [Integer] n number of source entries to skip.
+      # @return [LazyTransform] a new {LazyTransform} skipping `n` source
+      #     entries.
+      def drop( n )
+        if transformed?
+          super
+        else
+          self.class.new( source.drop( n ), &transformer )
+        end
+      end
+
+      private
+
+        attr_reader :source
+        attr_reader :transformer
+
+        def transformed
+          @transformed ||= source.map( &transformer )
+        end
+
+        def transformed?
+          !!@transformed
+        end
+    end
+  end
+end