shamu 0.0.13 → 0.0.14

data/lib/shamu/entities/entity_lookup_service.rb

@@ -0,0 +1,137 @@
+require "shamu/services"
+
+module Shamu
+  module Entities
+
+    # Looks up entities from compiled {EntityPath} strings allowing references
+    # to be stored as opaque values in an external service and later looked up
+    # without knowing which services are required to look up the entities.
+    #
+    # Useful for implementing a `node` field in a Relay GraphQL endpoint or
+    # resolving entities in an {Auditing::AuditingService audit log}.
+    #
+    # {#lookup} maps entity types to the service class used to look up entities
+    # of that type. The services must implement the well known `#lookup` method
+    # that takes an array of ids as an argument.
+    #
+    # If there is no entry mapping in the `entity_map` provided to the
+    # constructor then EntityLookupService will attempt to locate a service
+    # named {Entities}Service in the same namespace as the entity type.
+    #
+    # The EntityLookupService should be configured as a per-request singleton
+    # in Scorpion with all custom entity mappings set.
+    #
+    # ```
+    # Scorpion.prepare do
+    #   capture Shamu::Entities::EntityLookupService do |scorpion|
+    #     scorpion.new( Shamu::Entities::EntityLookupService, { "User" => Users::ExternalUsersService }, {} )
+    #   end
+    # end
+    # ```
+    class EntityLookupService < Shamu::Services::Service
+
+      def initialize( entity_map = nil )
+        entity_map ||= {}
+        @entity_map_cache = Hash.new do |hash, entity_type|
+          hash[ entity_type ] = entity_map[ entity_type ] \
+                                || entity_map[ entity_type.to_s ] \
+                                || find_implicit_service_class( entity_type.to_s )
+        end
+        super()
+      end
+
+      # Gets the class of the service used to look up entities of the given
+      # type. Use a scorpion to get an instance of the service class.
+      #
+      # @return [Shamu::Services::Service] a service that implements `#lookup`.
+      def service_class_for( entity_type )
+        entity_map_cache[ entity_type.to_sym ]
+      end
+
+      # Map the given entities to their {EntityPath} that can later be used to
+      # {#lookup} the given entity.
+      def ids( entities )
+        Array.wrap( entities ).map do |entity|
+          EntityPath.compose_entity_path( [ entity ] )
+        end
+      end
+
+      # Map the encoded ids back to their raw record IDs discarding any type
+      # information.
+      #
+      # @param [Array<String>] ids an array of ids encoded with {#ids}.
+      def record_ids( ids )
+        Array.wrap( ids ).map do |id|
+          EntityPath.decompose_entity_path( id ).first.last.to_model_id
+        end
+      end
+
+      # Look up all the entities from their composed {EntityPath}.
+      #
+      # @param [Array<String>] ids an array of {EntityPath} strings.
+      # @return [EntityList<Entity>] the entities in the same order as the
+      # given ids.
+      def lookup( *ids ) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        types = {}
+
+        # Decompose entity paths and group by entity type
+        ids.each do |composed|
+          path = EntityPath.decompose_entity_path( composed )
+          fail "Only root entities can be restored" unless path.size == 1
+          type, id = path.first
+
+          types[ type ] ||= { paths: [], ids: [] }
+
+          types[ type ][ :paths ] << composed
+          types[ type ][ :ids ]   << id
+        end
+
+        # Short-circuit if we only have one entity type
+        if types.size == 1
+          service_class = service_class_for( types.first.first )
+          service = scorpion.fetch service_class
+
+          return service.lookup( *types.first.last[ :ids ] )
+        end
+
+        # Lookup all entities in batches
+        hydrated = types.map do |type, map|
+          service_class = service_class_for( type )
+          service = scorpion.fetch service_class
+
+          entities = service.lookup( *map[ :ids ] )
+
+          Hash[ map[ :paths ].zip( entities ) ]
+        end
+
+        # Map found entities back to their original input order
+        mapped = ids.map do |id|
+          found = nil
+          hydrated.each do |map|
+            break if found = map[ id ]
+          end
+
+          found
+        end
+
+        Entities::List.new mapped
+      end
+
+      private
+
+        attr_reader :entity_map_cache
+
+        def find_implicit_service_class( entity_type )
+          namespace = entity_type.deconstantize
+          type      = entity_type.demodulize
+
+          service_name = [
+                           namespace,
+                           "#{ type.pluralize }Service"
+                         ].join( "::" )
+
+          service_name.constantize
+        end
+    end
+  end
+end

data/lib/shamu/entities/entity_path.rb

@@ -1,14 +1,13 @@
 module Shamu
   module Entities
 
-    # An entity path descrives one or more levels of parent/child relationships
+    # An entity path describes one or more levels of parent/child relationships
     # that can be used to navigate from the root entity to a target entity.
     #
     # Entity paths can be used to identify polymorphic relationships between
     # entities managed by difference services.
     module EntityPath
-      module_function
-
+      extend self # rubocop:disable Style/ModuleFunction
 
       # Composes an array of entities describing the path from the root entity
       # to the leaf into a string.
@@ -29,13 +28,11 @@ module Shamu
       def compose_entity_path( entities )
         return unless entities.present?
 
-        entities.each_with_object( "" ) do |entity, path|
-          path << "/" if path.present?
-          path << compose_single_entity( entity )
-        end
+        entities.map do |entity|
+          compose_single_entity( entity )
+        end.join( "/" )
       end
 
-
       # Decompose an entity path into an array of arrays of entity classes with
       # their ids.
       #
@@ -84,4 +81,4 @@ module Shamu
 
     end
   end
-end
+end

data/lib/shamu/entities/list.rb

@@ -16,11 +16,17 @@ module Shamu
         entities.each( &block )
       end
 
-      delegate :first, :count, :empty?, to: :raw_entities
+      delegate :first, :last, :count, :empty?, :index, to: :raw_entities
 
       alias_method :size, :count
       alias_method :length, :count
 
+      # @return [Boolean] true if the list represents a slice of a larger set.
+      # See {PagedList} for paged implementation.
+      def paged?
+        false
+      end
+
       # Get an entity by it's primary key.
       # @param [Object] key the primary key to look for.
       # @param [Symbol] field to use as the primary key. Default :id.
@@ -51,4 +57,4 @@ module Shamu
         end
     end
   end
-end
+end

data/lib/shamu/entities/list_scope/paging.rb

@@ -37,15 +37,15 @@ module Shamu
 
           base.attribute :page, coerce: :to_i
           base.attribute :per_page, coerce: :to_i, default: ->() { default_per_page }
-          base.attribute :default_per_page, coerce: :to_i, default: 25, serialize: false
+          base.attribute :default_per_page, coerce: :to_i, serialize: false
         end
 
         # @return [Boolean] true if the scope is paged.
         def paged?
-          !!page
+          !!page || !!per_page
         end
 
       end
     end
   end
-end
+end

data/lib/shamu/entities/list_scope/sorting.rb

@@ -42,7 +42,7 @@ module Shamu
         def self.included( base )
           super
 
-          base.attribute :sort_by, coerce: ->( *values ) { parse_sort_by( values ) }
+          base.attribute :sort_by, as: :order, coerce: ->( *values ) { parse_sort_by( values ) }
         end
 
         # @return [Boolean] true if the scope is paged.
@@ -50,8 +50,27 @@ module Shamu
           !!sort_by
         end
 
+        # @return [Hash] gets a normalized hash of attribute to direction with
+        # all transforms applied.
+        def sort_by_resolved
+          return sort_by unless reverse_sort?
+
+          sort_by.each_with_object( {} ) do |( attribute, direction ), resolved|
+            resolved[ attribute ] = direction == :asc ? :desc : :asc
+          end
+        end
+
         private
 
+          def reverse_sort?
+            @reverse_sort
+          end
+
+          def reverse_sort!
+            @reverse_sort = true
+            self.sort_by = { id: :asc } unless sort_by_set?
+          end
+
           def parse_sort_by( arguments )
             Array( arguments ).each_with_object( {} ) do |arg, sorted|
               case arg
@@ -73,4 +92,4 @@ module Shamu
       end
     end
   end
-end
+end

data/lib/shamu/entities/list_scope/window_paging.rb

@@ -0,0 +1,96 @@
+module Shamu
+  module Entities
+    class ListScope
+
+      # Limit/offset style paging using first/after naming conventions typical
+      # in GraphQL implementations.
+      #
+      # ```
+      # class UsersListScope < Shamu::Entities::ListScope
+      #   include Shamu::Entities::ListScope::WindowPaging
+      # end
+      #
+      # scope = UsersListScope.coerce!( params )
+      # scope.first    # => 25
+      # scope.after    # => 75
+      # ```
+      module WindowPaging
+
+        # ============================================================================
+        # @!group Attributes
+        #
+
+        # @!attribute first
+        # @return [Integer] get the first n records.
+
+        # @!attribute after
+        # @return [Integer] the number of records to skip from the beginning.
+
+        # @!attribute last
+        # @return [Integer] get the last n records.
+
+        # @!attribute before
+        # @return [Integer] the number of records to skip from the end.
+
+        #
+        # @!endgroup Attributes
+
+        def self.included( base ) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          super
+
+          base.attribute :first, coerce: :to_i, default: ->() { default_first }
+          base.attribute :default_first, coerce: :to_i, serialize: false
+
+          base.attribute :after, coerce: :to_i
+
+          base.attribute :last, default: ->() { default_last }, coerce: ->( value ) do
+            ensure_includes_sorting!
+            reverse_sort!
+
+            value.to_i if value
+          end
+
+          base.attribute :default_last, serialize: false, coerce: ->( value ) do
+            ensure_includes_sorting!
+            reverse_sort!
+
+            value.to_i if value
+          end
+
+          base.attribute :before, coerce: ->( value ) do
+            ensure_includes_sorting!
+            reverse_sort!
+
+            value.to_i if value
+          end
+
+          base.validate :only_first_or_last
+        end
+
+        # @return [Boolean] true if the scope is paged.
+        def window_paged?
+          first? || last?
+        end
+
+        private
+
+          def first?
+            !!first || !!after
+          end
+
+          def last?
+            !!last || !!before
+          end
+
+          def only_first_or_last
+            errors.add :base, :only_first_or_last if first? && last?
+          end
+
+          def ensure_includes_sorting!
+            raise "Must include Shamu::Entities::ListScope::Sorting to use last/before" unless respond_to?( :reverse_sort!, true ) # rubocop:disable Metrics/LineLength
+          end
+
+      end
+    end
+  end
+end

data/lib/shamu/entities/list_scope.rb

@@ -24,11 +24,11 @@ module Shamu
     class ListScope
       include Attributes
       include Attributes::Assignment
-      include Attributes::FluidAssignment
       include Attributes::Validation
 
       require "shamu/entities/list_scope/paging"
       require "shamu/entities/list_scope/scoped_paging"
+      require "shamu/entities/list_scope/window_paging"
       require "shamu/entities/list_scope/dates"
       require "shamu/entities/list_scope/sorting"
 
@@ -102,4 +102,4 @@ module Shamu
       end
     end
   end
-end
+end

data/lib/shamu/entities/opaque_entity_lookup_service.rb

@@ -0,0 +1,59 @@
+require "shamu/services"
+
+module Shamu
+  module Entities
+
+    # Implements an {EntityLookupService} that works with {OpaqueId} encoded
+    # values to obfuscate the contents and type of record identified by the id.
+    # Useful for implementing guidelines for globally unique IDs in a GraphQL
+    # system.
+    #
+    # ```
+    # Scorpion.prepare do
+    #   capture Shamu::Entities::EntityLookupService do |scorpion|
+    #     scorpion.new( Shamu::Entities::OpaqueEntityLookupService, { "User" => Users::ExternalUsersService }, {} )
+    #   end
+    # end
+    # ```
+    class OpaqueEntityLookupService < EntityLookupService
+
+      # ============================================================================
+      # @!group Dependencies
+      #
+
+      # @!attribute
+      # @return [EntityLookupService] the underlying lookup service to use.
+      attr_dependency :lookup_service, EntityLookupService do |scorpion|
+        scorpion.new( EntityLookupService, { entity_map: entity_map }, {} )
+      end
+
+
+      #
+      # @!endgroup Dependencies
+
+      # (see {EntityLookupService#ids)
+      def ids( entities )
+        super.map do |id|
+          OpaqueId.opaque_id( id )
+        end
+      end
+
+      # (see {EntityLookupService#record_ids)
+      def record_ids( ids )
+        super( ids_to_entity_paths( ids ) )
+      end
+
+      # (see {EntityLookupService#lookup)
+      def lookup( *ids )
+        super( *ids_to_entity_paths( ids ) )
+      end
+
+      private
+
+        def ids_to_entity_paths( ids )
+          Array.wrap( ids ).map { |id| OpaqueId.to_entity_path( id ) }
+        end
+
+    end
+  end
+end

data/lib/shamu/entities/opaque_id.rb

@@ -0,0 +1,54 @@
+module Shamu
+  module Entities
+
+    # A collection of helper methods for building and reconstructing opaque
+    # entity ids. These ids can be used to uniquely reference a resource within
+    # the system without knowing the type or service.
+    #
+    # See {EntityLookupService} for lookup up resources by opaque ID.
+    module OpaqueId
+      module_function
+
+      PREFIX  = "::".freeze
+      PATTERN = %r{\A#{ PREFIX }[a-zA-Z0-9+/]+={0,3}\z}
+
+      # @return [String] an opaque value that uniquely identifies the
+      # entity.
+      def opaque_id( entity )
+        path = if entity.is_a?( String )
+                 entity
+               else
+                 Entity.compose_entity_path( [ entity ] )
+               end
+
+        "#{ PREFIX }#{ Base64.strict_encode64( path ) }"
+      end
+
+      # @return [String,Integer] the encoded raw record id.
+      def to_model_id( opaque_id )
+        if path = to_entity_path( opaque_id )
+          path = EntityPath.decompose_entity_path( path )
+          path.first.last.to_model_id
+        else
+          opaque_id.to_model_id
+        end
+      end
+
+      # @return [Array<[String, String]>] decodes the id to it's {EntityPath}.
+      def to_entity_path( opaque_id )
+        return nil unless opaque_id && opaque_id.start_with?( PREFIX )
+
+        id = opaque_id[ PREFIX.length..-1 ]
+        id = Base64.strict_decode64( id )
+        id
+      end
+
+      # @param [String] value candidate value
+      # @return [Boolean] true if the given value is an opaque id.
+      def opaque_id?( value )
+        return unless value
+        PATTERN =~ value
+      end
+    end
+  end
+end

data/lib/shamu/entities/paged_list.rb

@@ -0,0 +1,137 @@
+module Shamu
+  module Entities
+
+    # A list of {Entities::Entity} records.
+    class PagedList < List
+      include Enumerable
+
+      # @param [Enumerable] entities the raw list of entities.
+      # @param [Integer, #call] total_count the number (or a proc that resolves
+      # to a number) of records in the entire set.
+      # @param [Integer, #call] limit the maximum number (or a proc that resolves to a
+      # number) of records in the page represented by the list.
+      # @param [Integer, #call] offset the number (or a proc that resolves to a
+      # number) offset from the start of the set that this list represents.
+      # @param [Boolean,#call] has_next true if there is another page
+      # available or a proc that returns a bool.
+      # @param [Boolean,#call] has_previous true if there is a previous page
+      # available or a proc that returns a bool.
+      def initialize( entities,
+                      total_count: :not_set,
+                      limit: :not_set,
+                      offset: :not_set,
+                      has_next: :not_set,
+                      has_previous: :not_set )
+        super( entities )
+
+        @total_count  = total_count
+        @limit        = limit
+        @offset       = offset
+        @has_next     = has_next
+        @has_previous = has_previous
+      end
+
+      # (see List#paged?)
+      def paged?
+        true
+      end
+
+      # @return [Integer] the total number of records in the set.
+      def total_count
+        if @total_count == :not_set
+          raw_entities.total_count
+        elsif @total_count.respond_to?( :call )
+          @total_count = @total_count.call
+        else
+          @total_count
+        end
+      end
+
+      # @return [Integer] the maximum number of records to return in each page.
+      def limit
+        if @limit == :not_set
+          if raw_entities.respond_to?( :limit_value )
+            raw_entities.limit_value
+          elsif raw_entities.respond_to?( :limit )
+            raw_entities.limit
+          end
+        elsif @limit.respond_to?( :call )
+          @limit = @limit.call
+        else
+          @limit
+        end
+      end
+      alias_method :per_page, :limit
+
+      # @return [Integer] the absolute offset into the set for the window of
+      # data that that this list contains.
+      def offset
+        if @offset == :not_set
+          if raw_entities.respond_to?( :offset_value )
+            raw_entities.offset_value
+          elsif raw_entities.respond_to?( :offset )
+            raw_entities.offset
+          end
+        elsif @offset.respond_to?( :call )
+          @offset = @offset.call
+        else
+          @offset
+        end
+      end
+
+      # @return [Integer] the current page number.
+      def current_page
+        if limit > 0
+          ( offset / limit ).to_i + 1
+        else
+          1
+        end
+      end
+
+      # @return [Boolean] true if there is another page of data available.
+      def next?
+        if @has_next == :not_set
+          if raw_entities.respond_to?( :has_next? )
+            raw_entities.has_next?
+          elsif raw_entities.respond_to?( :last_page? )
+            !raw_entities.last_page?
+          end
+        elsif @has_next.respond_to?( :call )
+          @has_next = @has_next.call
+        else
+          @has_next
+        end
+      end
+      alias_method :has_next?, :next?
+
+      # @return [Boolean] true if this list represents the last page in the
+      # set.
+      def last?
+        !next?
+      end
+
+      # @return [Boolean] true if there is another page of data available.
+      def previous?
+        if @has_previous == :not_set
+          if raw_entities.respond_to?( :has_previous? )
+            raw_entities.has_previous?
+          elsif raw_entities.respond_to?( :first_page? )
+            !raw_entities.first_page?
+          end
+        elsif @has_previous.respond_to?( :call )
+          @has_previous = @has_previous.call
+        else
+          @has_previous
+        end
+      end
+      alias_method :has_prev?, :previous?
+      alias_method :has_previous, :previous?
+
+      # @return [Boolean] true if this list represents the first page in the
+      # set.
+      def first?
+        !previous?
+      end
+    end
+  end
+end

data/lib/shamu/entities.rb

@@ -4,9 +4,13 @@ module Shamu
     require "shamu/entities/entity"
     require "shamu/entities/null_entity"
     require "shamu/entities/list"
+    require "shamu/entities/paged_list"
     require "shamu/entities/list_scope"
     require "shamu/entities/identity_cache"
     require "shamu/entities/entity_path"
     require "shamu/entities/html_sanitation"
+    require "shamu/entities/entity_lookup_service"
+    require "shamu/entities/opaque_id"
+    require "shamu/entities/opaque_entity_lookup_service"
   end
-end
+end

data/lib/shamu/events/active_record/service.rb

@@ -110,7 +110,6 @@ module Shamu
             end
 
             dispatch_messages( state, runner_id, limit )
-
           ensure
             mutex.synchronize do
               state[ :dispatching ] = false
@@ -171,4 +170,4 @@ module Shamu
       end
     end
   end
-end
+end

data/lib/shamu/events/in_memory/service.rb

@@ -75,7 +75,6 @@ module Shamu
             end
 
             dispatch_messages( state )
-
           ensure
             mutex.synchronize do
               state[ :dispatching ] = false
@@ -94,4 +93,4 @@ module Shamu
       end
     end
   end
-end
+end

data/lib/shamu/features/conditions/percentage.rb

@@ -25,9 +25,9 @@ module Shamu
 
           def user_id_hash( user_id )
             if user_id.is_a?( Numeric )
-              return user_id
+              user_id
             else
-              return user_id.sub( "-", "" ).to_i( 16 )
+              user_id.sub( "-", "" ).to_i( 16 )
             end
           end
 
@@ -41,4 +41,4 @@ module Shamu
 
     end
   end
-end
+end