shamu 0.0.1 → 0.0.2

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

@@ -0,0 +1,76 @@
+module Shamu
+  module Entities
+    class ListScope
+
+      # Include sorting parameters and parsing.
+      #
+      # ```
+      # class UsersListScope < Shamu::Entities::ListScope
+      #   include Shamu::Entities::ListScope::Sorting
+      # end
+      #
+      # scope = UserListScope.coerce!( sort_by: { first_name: :desc } )
+      # scope.sort_by   #=> { first_name: :desc }
+      #
+      # scope = UserListScope.coerce!( sort_by: :first_name )
+      # scope.sort_by   #=> { first_name: :asc }
+      #
+      # scope = UserListScope.coerce!( sort_by: [ :first_name, :last_name ] )
+      # scope.sort_by   #=> { first_name: :asc, last_name: :asc }
+      # ```
+      module Sorting
+
+        # ============================================================================
+        # @!group Attributes
+        #
+
+        # @!attribute sort_by
+        # @return [Hash] the attributes and directions to sort by.
+        #
+        # The sort attribute is coerced by converting arrays to a hash with a
+        # default direction of :asc for each attribute.
+        #
+        # ```
+        # scope.sort_by :name                   # => { name: :asc }
+        # scope.sort_by :name, :created_at      # => { name: :asc, created_at: :asc }
+        # scope.sort_by :count, rating: :desc   # => { count: :asc, rating: :desc }
+        # ```
+
+        #
+        # @!endgroup Attributes
+
+        def self.included( base )
+          super
+
+          base.attribute :sort_by, coerce: ->( *values ) { parse_sort_by( values ) }
+        end
+
+        # @return [Boolean] true if the scope is paged.
+        def sorted?
+          !!sort_by
+        end
+
+        private
+
+          def parse_sort_by( arguments )
+            Array( arguments ).each_with_object( {} ) do |arg, sorted|
+              case arg
+              when Array          then sorted.merge!( parse_sort_by( arg ) )
+              when Hash           then
+                arg.each do |attr, direction|
+                  case direction
+                  when :asc, :desc, "asc", "desc" then sorted[attr] = direction.to_sym
+                  when Array, Hash                then sorted[attr] = parse_sort_by( direction )
+                  else                                 fail ArgumentError
+                  end
+                end
+              when String, Symbol then sorted[arg.to_sym] = :asc
+              else                     fail ArgumentError
+              end
+            end
+          end
+
+      end
+    end
+  end
+end

data/lib/shamu/entities/list_scope.rb

@@ -0,0 +1,105 @@
+module Shamu
+  module Entities
+
+    # The desired scope of entities offered {Services::Service} to prepare a
+    # list of {Entity entities}.
+    #
+    # ### Standard scopes
+    #
+    # - {Paging}
+    # - {ScopedPaging}
+    # - {Dates}
+    # - {Sorting}
+    #
+    # @example
+    #   class UsersListScope < Shamu::Entities::ListScope
+    #
+    #     # Include standard paging options (page, per_page) from ListScopes::Paging
+    #     include Shamu::Entities::ListScope::Paging
+    #
+    #     # Allow client to request that users be limited to those in one of the
+    #     # given roles.
+    #     attribute :roles, array: true, coerce: :to_s
+    #   end
+    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/dates"
+      require "shamu/entities/list_scope/sorting"
+
+
+      # Clone the params but exclude the given parameters.
+      # @param [Array<Symbol>] param_names to exclude.
+      # @return [ListScope]
+      def except( *param_names )
+        self.class.new( to_attributes( except: param_names ) )
+      end
+
+      # @return [Hash] the hash of attributes that can be used to generate a url.
+      def params
+        params = to_attributes
+        params.each do |key, value|
+          params[key] = value.params if value.respond_to?( :params )
+        end
+        params
+      end
+
+      class << self
+        # Coerces a hash or params object to a proper ListScope object.
+        # @param [Object] params to be coerced.
+        # @return [ListScope] the coerced scope
+        def coerce( params )
+          if params.is_a?( self )
+            params
+          elsif params.respond_to?( :to_h ) || params.respond_to?( :to_attributes )
+            new( params )
+          elsif params.nil?
+            new
+          else
+            raise ArgumentError
+          end
+        end
+
+        # Coerces the given params object and raises an ArgumentError if any of
+        # the parameters are invalid.
+        # @param (see .coerce)
+        # @return (see .coerce)
+        def coerce!( params )
+          coerced = coerce( params )
+          raise ArgumentError unless coerced.valid?
+          coerced
+        end
+
+        # Finds the natural {ListScope} class for the given entity class.
+        #
+        # Users::UserEntity -> Users::UserListScope or Users::ListScope
+        #
+        # @param [Class] entity_class the {Entity} class to find a scope for.
+        # @return [ListScope] the custom list scope if found, otherwise
+        #     {ListScope}.
+        def for( entity_class )
+          base_name = entity_class.name || "Entity"
+          name = base_name.sub /(Entity)?$/, "ListScope"
+          begin
+            return name.constantize
+          rescue NameError # rubocop:disable Lint/HandleExceptions
+          end
+
+          name = base_name.sub /::[A-Za-z0-9]+(Entity)?$/, "::ListScope"
+
+          begin
+            return name.constantize
+          rescue NameError # rubocop:disable Lint/HandleExceptions
+          end
+
+          self
+        end
+      end
+    end
+  end
+end

data/lib/shamu/entities/null_entity.rb

@@ -0,0 +1,88 @@
+module Shamu
+  module Entities
+
+    # Null entities look at feel just like their natural counterparts but are
+    # not backed by any real data. Rather than returning null from a service
+    # lookup function, services will return a null entity so that clients do not
+    # need to constantly check for nil before formatting output.
+    #
+    # ```
+    # class UserEntity < Entity
+    #   attribute :name
+    #   attribute :id
+    #   attribute :email
+    # end
+    #
+    # class NullUserEntity < UserEntity
+    #   include NullEntity
+    # end
+    #
+    # user = user_service.lookup( real_user_id )
+    # user       # => UserEntity
+    # user.name  # => "Shamu"
+    # user.email # => "start@seaworld.com"
+    # user.id    # => 5
+    #
+    # user = user_service.lookup( unknown_user_id )
+    # user       # => NullUserEntity
+    # user.name  # => "Unknown User"
+    # user.email # => nil
+    # user.id    # => nil
+    # ```
+    module NullEntity
+
+      # Attributes to automatically format as "Unknown {Entity Class Name}"
+      AUTO_FORMATTED_ATTRIBUTES = %i( name title label ).freeze
+
+      # @return [nil]
+      # Prevent rails url helpers from generating URLs for the entity.
+      def to_param
+      end
+
+      # @return [true]
+      #
+      # Allow clients to adjust behavior if needed for missing entities.
+      def empty?
+        true
+      end
+
+      def self.included( base )
+        AUTO_FORMATTED_ATTRIBUTES.each do |attr|
+          next unless base.attributes.key?( attr )
+
+          base_name ||= begin
+            name = base.name || "Resource"
+            name.split( "::" )
+                .last
+                .sub( /Entity/, "" )
+                .gsub( /(.)([[:upper:]])/, '\1 \2' )
+          end
+          base.attribute attr, default: "Unknown #{ base_name }"
+        end
+      end
+
+      # Dynamically generate a new null entity class.
+      # @param [Class] entity_class {Entity} class
+      # @return [Class] a null entity class derived from `entity_class`.
+      def self.for( entity_class )
+        if null_klass = ( entity_class.const_defined?( :NullEntity, false ) &&
+                          entity_class.const_get( :NullEntity, false ) )
+          # If the base class is reloaded a-la rails dev, then regenerate the
+          # null class as well.
+          null_klass = nil if null_klass.superclass != entity_class
+        end
+
+        unless null_klass
+          null_klass = Class.new( entity_class ) do
+            include ::Shamu::Entities::NullEntity
+          end
+
+          entity_class.const_set :NullEntity, null_klass
+        end
+
+        null_klass
+      end
+
+    end
+  end
+end

data/lib/shamu/entities.rb

@@ -0,0 +1,11 @@
+module Shamu
+  # {include:file:lib/shamu/entities/README.md}
+  module Entities
+    require "shamu/entities/entity"
+    require "shamu/entities/null_entity"
+    require "shamu/entities/list"
+    require "shamu/entities/list_scope"
+    require "shamu/entities/identity_cache"
+    require "shamu/entities/entity_path"
+  end
+end

data/lib/shamu/error.rb

@@ -1,13 +1,31 @@
-require 'i18n'
+require "i18n"
 
-module Schamu
-  class Error < StandardError
+module Shamu
 
+  # A generic error class for problems in the shamu library.
+  class Error < StandardError
     private
-      def translate( key, args = {} )
-        I18n.translate key, args.merge( scope: [:shamu,:errors,:messages] )
+
+      def translation_scope
+        [ :shamu, :errors ]
+      end
+
+      def translate( key, **args )
+        I18n.translate key, args.merge( scope: translation_scope )
       end
   end
 
+  # The resource was not found.
+  class NotFoundError < Error
+    def initialize( message = :not_found )
+      super translate( message )
+    end
+  end
 
+  # The method is not implemented.
+  class NotImplementedError < Error
+    def initialize( message = :not_implemented )
+      super translate( message )
+    end
+  end
 end

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

@@ -0,0 +1,36 @@
+module Shamu
+  module Events
+    module ActiveRecord
+
+      # Registry of event channels.
+      class Channel < ::ActiveRecord::Base
+
+        self.table_name = "shamu_event_channels"
+
+        # ============================================================================
+        # @!group Attributes
+        #
+
+        # @!attribute
+        # @return [String] name of the channel.
+
+        #
+        # @!endgroup Attributes
+
+        # ============================================================================
+        # @!group Scope
+        #
+
+        # @!attribute
+        # @return [ActiveRecord::Relation] messages posted to the given channel.
+        scope :by_name, ->( name ) {
+          where( name: name )
+        }
+
+        #
+        # @!endgroup Scope
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+module Shamu
+  module Events
+    module ActiveRecord
+
+      # The model used to store the event messages in the database.
+      class Message < ::ActiveRecord::Base
+
+        self.table_name = "shamu_event_messages"
+        self.primary_key = "id"
+
+        # ============================================================================
+        # @!group Attributes
+        #
+
+        # @!attribute
+        # @return [String] id of the message a UUID.
+
+        # @!attribute
+        # @return [Integer] channel_id
+
+        # @!attribute
+        # @return [String] message the serialized message.
+
+        # @!attribute
+        # @return [DateTime] timestamp when the event was submitted.
+
+        #
+        # @!endgroup Attributes
+
+        # ============================================================================
+        # @!group Scope
+        #
+
+        # @!attribute
+        # @return [ActiveRecord::Relation] messages posted to the given channel.
+        scope :by_channel, ->( name ) {
+          where( channel: name )
+        }
+
+        # @!attribute
+        # @return [ActiveRecord::Relation] messages posted after the given created_at.
+        scope :since, ->( created_at ) {
+          where( arel_table[:created_at].gt( created_at ) )
+        }
+
+        #
+        # @!endgroup Scope
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+module Shamu
+  module Events
+    module ActiveRecord
+
+      # Prepare the database for storing event messages.
+      class Migration < ::ActiveRecord::Migration
+
+        self.verbose = false
+
+        # rubocop:disable Metrics/MethodLength
+
+        def up
+          return if table_exists? Message.table_name
+
+          # TODO: Need to provide a means for using 64-bit primary keys in
+          # databases that support it. Otherwise limited to 4B events.
+          create_table Message.table_name do |t|
+            t.integer :channel_id, null: false
+            t.string  :message, null: false
+
+            t.index :id
+            t.index :channel_id
+          end
+
+          create_table Channel.table_name do |t|
+            t.string :name, null: false, unique: true
+
+            t.index :name
+          end
+
+          create_table Runner.table_name, id: false do |t|
+            t.timestamp :last_processed_at
+            t.integer   :last_processed_id
+            t.string    :id, null: false
+
+            t.index :id, unique: true
+          end
+        end
+
+        def down
+          drop_table Message.table_name if table_exists? Message.table_name
+          drop_table Channel.table_name if table_exists? Channel.table_name
+          drop_table Runner.table_name  if table_exists? Runner.table_name
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+module Shamu
+  module Events
+    module ActiveRecord
+
+      # Keep track of the last time message processed by a channel dispatch
+      # runner.
+      class Runner < ::ActiveRecord::Base
+
+        self.table_name = "shamu_event_runners"
+        self.primary_key = "id"
+
+        # ============================================================================
+        # @!group Attributes
+        #
+
+        # @!attribute id
+        # @return [String] the runner's UUID.
+
+        # @!attribute last_processed_timestamp
+        # @return [Datetime] timestamp of the last message processed.
+
+        #
+        # @!endgroup Attributes
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,174 @@
+require "thread"
+
+module Shamu
+  module Events
+    module ActiveRecord
+
+      # Store events in a database using ActiveRecord persistence layer.
+      #
+      # ## Runner IDS
+      #
+      # A globally unique id (may be UUID or a well- defined internal
+      # convention that guarantees uniqueness.) The runner id is used by the
+      # system to track which messages have been delivered to the subscribers
+      # hosted by that runner process. This allows dispatching to resume should
+      # the host or process die.
+      class Service < EventsService
+        include ChannelStats
+
+        # Ensure that the tables are present in the database and have been
+        # initialized.
+        #
+        # @return [void]
+        def self.ensure_records!
+          return if @ensure_records
+
+          @ensure_records = true
+          Migration.new.migrate( :up )
+        end
+
+        initialize do
+          self.class.ensure_records!
+          @channels ||= {}
+          @mutex    ||= Mutex.new
+        end
+
+        # (see EventsService#publish)
+        def publish( channel, message )
+          channel_id = fetch_channel( channel )[:id]
+          Message.create! channel_id: channel_id, message: serialize( message )
+        end
+
+        # (see EventsService#subscribe)
+        def subscribe( channel, &callback )
+          state = fetch_channel( channel )
+          mutex.synchronize do
+            state[:subscribers] << callback
+          end
+        end
+
+        # Dispatch queued messages up to the given `limit`. Once all the
+        # messages are dispatched, the method returns. A long running process
+        # might periodically call dispatch in a loop trapping SIGINT to
+        # shutdown.
+        #
+        # @param [String] runner_id that identifies the host and process
+        #     responding to events.
+        # @param [Array<String>] names of the channels to dispatch. If empty,
+        #     dispatches to all subscribed channels.
+        # @param [Integer] limit the maximum number of messages to dispatch. If
+        #     not given, defaults to 100.
+        #
+        # @return [Hash<String,Integer>] the number of messages actually
+        #     dispatched on each channel.
+        def dispatch( runner_id, *names, limit: nil )
+          fail UnknownRunnerError unless runner_id.present?
+          names = channels.keys unless channels.present?
+
+          names.each_with_object( {} ) do |name, dispatched|
+            state = fetch_channel( name )
+            dispatched[name] = dispatch_channel( state, "#{ runner_id }::#{ name }", limit )
+          end
+        end
+
+        # (see ChannelStats#channel_stats)
+        # @param [String] runner_id if provided, only show stats for the given runner.
+        def channel_stats( name, runner_id: nil )
+          channel = fetch_channel( name )
+          queue   = Message.where( channel_id: channel[:id] )
+
+          if runner_id && ( runner = create_runner( runner_id ) )
+            if runner.last_processed_id
+              queue = queue.where( Message.arel_table[ :id ].gt( runner.last_processed_id ) )
+            end
+          end
+
+          {
+            name: name,
+            subscribers_count: channel[:subscribers].size,
+            dispatching: channel[:dispatching],
+            queue_size: queue.count
+          }
+        end
+
+        private
+
+          attr_reader :channels
+          attr_reader :mutex
+
+          def create_channel( name )
+            {
+              id: create_named_channel( name ).id,
+              subscribers: []
+            }
+          end
+
+          def dispatch_channel( state, runner_id, limit )
+            mutex.synchronize do
+              return if state[:dispatching]
+              state[ :dispatching ] = true
+            end
+
+            dispatch_messages( state, runner_id, limit )
+
+          ensure
+            mutex.synchronize do
+              state[ :dispatching ] = false
+            end
+          end
+
+          def dispatch_messages( state, runner_id, limit )
+            last_message = nil
+            count = 0
+
+            pending_messages( state, runner_id, limit ).each do |record|
+              last_message = record
+              message      = deserialize( record.message )
+
+              count += 1
+
+              state[ :subscribers ].each do |subscriber|
+                subscriber.call( message )
+              end
+            end
+
+            bookmark_runner( runner_id, last_message )
+
+            count
+          end
+
+          def bookmark_runner( runner_id, last_message )
+            return unless last_message
+
+            runner = create_runner( runner_id )
+            runner.update_attributes last_processed_id: last_message.id, last_processed_at: Time.now.utc
+          end
+
+          def pending_messages( state, runner_id, limit )
+            messages = Message.where( channel_id: state[:id] )
+                              .limit( limit )
+            runner   = create_runner( runner_id )
+
+            if runner.last_processed_id
+              messages = messages.where( Message.arel_table[:id].gt( runner.last_processed_id ) )
+            end
+
+            messages
+          end
+
+          def create_runner( runner_id )
+            Runner.transaction( requires_new: true ) do
+              Runner.first_or_create!( id: runner_id )
+            end
+          end
+
+          def create_named_channel( name )
+            Channel.transaction( requires_new: true ) do
+              Channel.first_or_create!( name: name )
+            end
+          end
+
+      end
+    end
+  end
+end

data/lib/shamu/events/active_record.rb

@@ -0,0 +1,13 @@
+module Shamu
+  module Events
+
+    # See {ActiveRecord::Service}
+    module ActiveRecord
+      require "shamu/events/active_record/service"
+      require "shamu/events/active_record/message"
+      require "shamu/events/active_record/channel"
+      require "shamu/events/active_record/runner"
+      require "shamu/events/active_record/migration"
+    end
+  end
+end

data/lib/shamu/events/channel_stats.rb

@@ -0,0 +1,23 @@
+module Shamu
+  module Events
+
+    # Indicates that an {EventsService} supports reporting channel activity states.
+    module ChannelStats
+
+      # Gets stats for the given `channel`.
+      #
+      # #### Stats Included in the results.
+      #
+      # - **name** name of the channel.
+      # - **subscribers_count** the number of subscribers.
+      # - **queue_size** the size of the message queue.
+      # - **dispatching** true if the channel is currently dispatching messages.
+      #
+      # @param [String] name  of the channel
+      # @return [Hash] stats.
+      def channel_stats( name )
+        fail NotImplementedError
+      end
+    end
+  end
+end