esse 0.0.5 → 0.1.3

data/lib/esse/config.rb

@@ -3,6 +3,31 @@
 require 'pathname'
 
 module Esse
+  # Block configurations
+  #   Esse.configure do |conf|
+  #     conf.indices_directory = 'app/indices/directory'
+  #     conf.cluster(:v1) do |cluster|
+  #       cluster.index_prefix = 'backend'
+  #       cluster.client = Elasticsearch::Client.new
+  #       cluster.index_settings = {
+  #         number_of_shards: 2,
+  #         number_of_replicas: 0
+  #       }
+  #     end
+  #   end
+  #
+  # Inline configurations
+  #   Esse.config.indices_directory = 'app/indices/directory'
+  #   Esse.config.cluster(:v1).client = Elasticsearch::Client.new
+  class << self
+    def config
+      @config ||= Config.new
+      yield(@config) if block_given?
+      @config
+    end
+    alias_method :configure, :config
+  end
+
   # Provides all configurations
   #
   # Example
@@ -19,14 +44,14 @@ module Esse
     def initialize
       self.indices_directory = 'app/indices'
       @clusters = {}
-      clusters(DEFAULT_CLUSTER_ID) # initialize the :default client
+      cluster(DEFAULT_CLUSTER_ID) # initialize the :default client
     end
 
     def cluster_ids
       @clusters.keys
     end
 
-    def clusters(key = DEFAULT_CLUSTER_ID, **options)
+    def cluster(key = DEFAULT_CLUSTER_ID, **options)
       return unless key
 
       id = key.to_sym
@@ -35,6 +60,7 @@ module Esse
         yield c if block_given?
       end
     end
+    alias_method :clusters, :cluster
 
     def indices_directory=(value)
       @indices_directory = value.is_a?(Pathname) ? value : Pathname.new(value)
@@ -45,14 +71,22 @@ module Esse
       when Hash
         assign(arg)
       when File, Pathname
-        # @TODO Load JSON or YAML
+        assign(YAML.load_file(arg))
       when String
-        # @TODO Load JSON or YAML if File.exist?(arg)
+        return load(Pathname.new(arg)) if File.exist?(arg)
+
+        assign(YAML.safe_load(arg))
       else
         raise ArgumentError, printf('could not load configuration using: %p', val)
       end
     end
 
+    # :nodoc:
+    # This is only used by rspec to disable the CLI print out.
+    def cli_event_listeners?
+      true
+    end
+
     private
 
     def assign(hash)
@@ -64,7 +98,7 @@ module Esse
       end
       if (connections = hash['clusters'] || hash[:clusters]).is_a?(Hash)
         connections.each do |key, value|
-          clusters(key).assign(value) if value.is_a?(Hash)
+          cluster(key).assign(value) if value.is_a?(Hash)
         end
       end
       true

data/lib/esse/core.rb

@@ -1,35 +1,28 @@
 # frozen_string_literal: true
 
+
 require 'multi_json'
 require 'elasticsearch'
 
 module Esse
+  require_relative 'config'
+  require_relative 'cluster'
+  require_relative 'primitives'
+  require_relative 'index_type'
+  require_relative 'index_setting'
+  require_relative 'index_mapping'
+  require_relative 'template_loader'
+  require_relative 'backend/index'
+  require_relative 'backend/index_type'
+  require_relative 'version'
+  require_relative 'logging'
+  require_relative 'events'
+  include Logging
+
   @single_threaded = false
   # Mutex used to protect mutable data structures
   @data_mutex = Mutex.new
 
-  # Block configurations
-  #   Esse.config do |conf|
-  #     conf.indices_directory = 'app/indices/directory'
-  #     conf.clusters(:v1) do |cluster|
-  #       cluster.index_prefix = 'backend'
-  #       cluster.client = Elasticsearch::Client.new
-  #       cluster.index_settings = {
-  #         number_of_shards: 2,
-  #         number_of_replicas: 0
-  #       }
-  #     end
-  #   end
-  #
-  # Inline configurations
-  #   Esse.config.indices_directory = 'app/indices/directory'
-  #   Esse.config.clusters(:v1).client = Elasticsearch::Client.new
-  def self.config
-    @config ||= Config.new
-    yield(@config) if block_given?
-    @config
-  end
-
   # Unless in single threaded mode, protects access to any mutable
   # global data structure in Esse.
   # Uses a non-reentrant mutex, so calling code should be careful.
@@ -75,15 +68,4 @@ module Esse
     end
     [id, modified]
   end
-
-  require_relative 'config'
-  require_relative 'cluster'
-  require_relative 'primitives'
-  require_relative 'index_type'
-  require_relative 'index_setting'
-  require_relative 'index_mapping'
-  require_relative 'template_loader'
-  require_relative 'backend/index'
-  require_relative 'backend/index_type'
-  require_relative 'version'
 end

data/lib/esse/document.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Esse
+  # @abstract
+  #
+  # A document is a class that represents a single JSON document to be indexed
+  class Document
+    def initialize(entry, **context)
+      @source = item
+      @context = context
+    end
+
+    # Returns the Elasticsearch `_id` for the document.
+    #
+    # @return [String, Number] The Elasticsearch `_id` for the document
+    # @abstract
+    def id
+      raise NotImplementedError
+    end
+
+    # Returns the Elasticsearch `_routing` for the item. Elasticsearch
+    # default if this value is not provided is to use the `_id`.
+    # Setting this value to `false` or `nil` will omit sending the
+    # meta-field with your requests and use default routing behaviour.
+    #
+    # @return [String, NilClass, Boolean] The Elasticsearch `_routing` for the document
+    # @abstract
+    def routing
+    end
+
+    def attributes
+      {}
+    end
+
+    def to_h
+      {
+        _id: id,
+      }.tap do |hash|
+        hash[:_routing] = routing if routing
+      end
+    end
+  end
+end

data/lib/esse/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Esse
+  class Error < StandardError
+  end
+
+  module Events
+    class UnregisteredEventError < ::Esse::Error
+      def initialize(object_or_event_id)
+        case object_or_event_id
+        when String, Symbol
+          super("You are trying to publish an unregistered event: `#{object_or_event_id}`")
+        else
+          super('You are trying to publish an unregistered event')
+        end
+      end
+    end
+
+    class InvalidSubscriberError < ::Esse::Error
+      # @api private
+      def initialize(object_or_event_id)
+        case object_or_event_id
+        when String, Symbol
+          super("you are trying to subscribe to an event: `#{object_or_event_id}` that has not been registered")
+        else
+          super('you try use subscriber object that will never be executed')
+        end
+      end
+    end
+  end
+
+  module CLI
+    class Error < ::Esse::Error
+      def initialize(msg = nil, **message_attributes)
+        if message_attributes.any?
+          msg = format(msg, **message_attributes)
+        end
+        super(msg)
+      end
+    end
+
+    class InvalidOption < Error
+    end
+  end
+
+  # Elasticsearch::Transport::Transport::Errors::NotFound
+end

data/lib/esse/events/bus.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Esse
+  module Events
+    # Event bus
+    #
+    # An event bus stores listeners (callbacks) and events
+    #
+    # @api private
+    class Bus
+      # @return [Hash] A hash with events registered within a bus
+      attr_reader :events
+
+      # @return [Hash] A hash with event listeners registered within a bus
+      attr_reader :listeners
+
+      # Initialize a new event bus
+      #
+      # @param [Hash] events A hash with events
+      # @param [Hash] listeners A hash with listeners
+      #
+      # @api private
+      # @idea
+      #   Hash is thread-safe in practice because CRuby runs
+      #   threads one at a time and does not do context
+      #   switching during the execution of C functions
+      #   However, in case of jRuby or other ruby interpreters,
+      #   this assumption may not be true. In that case, we should
+      #   use a different data structure. I think we should use
+      #   a Concurrent::Hash or Concurrent::Map object from
+      #   concurrent-ruby
+      # @see https://github.com/ruby-concurrency/concurrent-ruby
+      def initialize(events: {}, listeners: Hash.new { |h, k| h[k] = [] })
+        @listeners = listeners
+        @events = events
+      end
+
+      # @api private
+      def publish(event_id, payload)
+        process(event_id, payload) do |event, listener|
+          listener.call(event)
+        end
+      end
+
+      # @api private
+      def attach(listener)
+        events.each do |id, event|
+          method_name = event.listener_method
+          next unless listener.respond_to?(method_name)
+
+          listeners[id] << listener.method(method_name)
+        end
+      end
+
+      # @api private
+      def detach(listener)
+        listeners.each do |id, arr|
+          arr.each do |func|
+            listeners[id].delete(func) if func.receiver == listener
+          end
+        end
+      end
+
+      # @api private
+      def subscribe(event_id, &block)
+        listeners[event_id] << block
+        self
+      end
+
+      # @api private
+      def subscribed?(listener)
+        listeners.values.any? { |value| value.any? { |func| func == listener } } || (
+          methods = events.values.map(&:listener_method).select(&listener.method(:respond_to?)).map(&listener.method(:method))
+          methods && listeners.values.any? { |value| (methods & value).size > 0 }
+        )
+      end
+
+      # @api private
+      def can_handle?(object_or_event_id)
+        case object_or_event_id
+        when String, Symbol
+          events.key?(object_or_event_id)
+        else
+          events
+            .values
+            .map(&:listener_method)
+            .any?(&object_or_event_id.method(:respond_to?))
+        end
+      end
+
+      protected
+
+      # @api private
+      def process(event_id, payload)
+        listeners[event_id].each do |listener|
+          event = events[event_id].payload(payload)
+
+          yield(event, listener)
+        end
+      end
+    end
+  end
+end

data/lib/esse/events/event.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Esse
+  module Events
+    class Event
+      attr_reader :id
+
+      # Initialize a new event
+      #
+      # @param [Symbol, String] id The event identifier
+      # @param [Hash] payload
+      #
+      # @return [Event]
+      #
+      # @api private
+      def initialize(id, payload = {})
+        @id = id
+        @payload = payload
+      end
+
+      # Get data from the payload
+      #
+      # @param [String,Symbol] name
+      #
+      # @api public
+      def [](name)
+        @payload.fetch(name)
+      end
+
+      # Coerce an event to a hash
+      #
+      # @return [Hash]
+      #
+      # @api public
+      def to_h
+        @payload
+      end
+      alias_method :to_hash, :to_h
+
+      # Get or set a payload
+      #
+      # @overload
+      #   @return [Hash] payload
+      #
+      # @overload payload(data)
+      #   @param [Hash] data A new payload
+      #   @return [Event] A copy of the event with the provided payload
+      #
+      # @api public
+      def payload(data = nil)
+        if data
+          self.class.new(id, @payload.merge(data))
+        else
+          @payload
+        end
+      end
+
+      # @api private
+      def listener_method
+        @listener_method ||= Hstring.new("on_#{id}").underscore.to_sym
+      end
+    end
+  end
+end

data/lib/esse/events/publisher.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative 'event'
+require_relative 'bus'
+
+module Esse
+  module Events
+    module Publisher
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      # Class interface for publishers
+      #
+      # @api public
+      module ClassMethods
+        # Register a new event type
+        #
+        # @param [Symbol,String] event_id The event identifier
+        # @param [Hash] payload Optional default payload
+        #
+        # @return [self]
+        #
+        # @api public
+        def register_event(event_id, payload = {})
+          __bus__.events[event_id] = Event.new(event_id, payload)
+          self
+        end
+
+        # Publish an event
+        #
+        # @param [String] event_id The event identifier
+        # @param [Hash] payload An optional payload
+        # @raise [Esse::Events::UnregisteredEventError] if the event is not registered
+        #
+        # @api public
+        def publish(event_id, payload = {})
+          if __bus__.can_handle?(event_id)
+            __bus__.publish(event_id, payload)
+            self
+          else
+            raise UnregisteredEventError, event_id
+          end
+        end
+
+        # Publish an event with extra runtime information to the payload
+        #
+        # @param [String] event_id The event identifier
+        # @param [Hash] payload An optional payload
+        # @raise [Esse::Events::UnregisteredEventError] if the event is not registered
+        #
+        # @api public
+        def instrument(event_id, payload = {}, &block)
+          publish_event = false # ensure block is also called on error
+          raise(UnregisteredEventError, event_id) unless __bus__.can_handle?(event_id)
+
+          payload[:__started_at__] = Time.now
+          block.call(payload).tap { publish_event = true }
+        ensure
+          if publish_event
+            payload[:runtime] ||= Time.now - payload.delete(:__started_at__) if payload[:__started_at__]
+            __bus__.publish(event_id, payload)
+          end
+        end
+
+        # Subscribe to events.
+        #
+        # @param [Symbol,String,Object] object_or_event_id The event identifier or a listener object
+        # @param [Hash] filter_hash An optional event filter
+        #
+        # @raise [Esse::Events::InvalidSubscriberError] if the subscriber is not registered
+        # @return [Object] self
+        #
+        #
+        # @api public
+        def subscribe(object_or_event_id, &block)
+          if __bus__.can_handle?(object_or_event_id)
+            if block
+              __bus__.subscribe(object_or_event_id, &block)
+            else
+              __bus__.attach(object_or_event_id)
+            end
+
+            self
+          else
+            raise InvalidSubscriberError, object_or_event_id
+          end
+        end
+
+        # Unsubscribe a listener
+        #
+        # @param [Object] listener The listener object
+        #
+        # @return [self]
+        #
+        # @api public
+        def unsubscribe(listener)
+          __bus__.detach(listener)
+        end
+
+        # Return true if a given listener has been subscribed to any event
+        #
+        # @api public
+        def subscribed?(listener)
+          __bus__.subscribed?(listener)
+        end
+
+        # Internal event bus
+        #
+        # @return [Bus]
+        #
+        # @api private
+        def __bus__
+          @__bus__ ||= Bus.new
+        end
+      end
+    end
+  end
+end

data/lib/esse/events.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'events/publisher'
+
+module Esse
+  # Extension used for classes that can pub/sub events
+  #
+  # Examples:
+  #
+  #   # Publish an event
+  #   Esse::Events.publish('elasticsearch.create_index', { definition: {index_name: 'my_index'} })
+  #   # Subscribe to an event
+  #   Esse::Events.subscribe('elasticsearch.create_index') do |event|
+  #     puts event.payload
+  #   end
+  #
+  #   # Publish an event using instrumentation
+  #   Esse::Events.instrument('elasticsearch.create_index') do |payload|
+  #     payload[:definition] = {index_name: 'my_index'}
+  #     # Some slow action
+  #   end
+  #   Esse::Events.subscribe('elasticsearch.create_index') do |event|
+  #     puts event.payload[:runtime] # Extra information about the amount of time the action took
+  #   end
+  #
+  #   # Attach a listener to the event bus
+  #   class MyEventListener
+  #     def on_elasticsearch_create_index(event)
+  #       puts event.payload
+  #     end
+  #   end
+  #   listener = MyEventListener.new
+  #   Esse::Events.attach(listener)
+  #   # Dettash the listener
+  #   Esse::Events.detach(listener)
+  #
+  #
+  module Events
+    include Publisher
+
+    register_event 'elasticsearch.close'
+    register_event 'elasticsearch.open'
+    register_event 'elasticsearch.create_index'
+    register_event 'elasticsearch.delete_index'
+    register_event 'elasticsearch.update_mapping'
+    register_event 'elasticsearch.update_settings'
+    register_event 'elasticsearch.update_aliases'
+  end
+end

data/lib/esse/index/backend.rb

@@ -3,9 +3,10 @@
 module Esse
   class Index
     module ClassMethods
-      def backend
+      def elasticsearch
         Esse::Backend::Index.new(self)
       end
+      alias_method :backend, :elasticsearch
     end
 
     extend ClassMethods

data/lib/esse/index/base.rb

@@ -3,12 +3,10 @@
 module Esse
   class Index
     module ClassMethods
-      attr_reader :cluster_id
-
       # Define a Index method on the given module that calls the Index
       # method on the receiver. This is how the Esse::Index() method is
       # defined, and allows you to define Index() methods on other modules,
-      # making it easier to have custom index settings for all indexes under
+      # making it easier to have custom index settings for all indices under
       # a namespace.  Example:
       #
       #   module V1
@@ -35,7 +33,7 @@ module Esse
       #
       # Example:
       #   # Using a custom cluster
-      #   Esse.config.clusters(:v1).client = Elasticsearch::Client.new
+      #   Esse.config.cluster(:v1).client = Elasticsearch::Client.new
       #   class UsersIndex < Esse::Index(:v1)
       #   end
       #
@@ -92,12 +90,12 @@ module Esse
       def cluster
         unless Esse.config.cluster_ids.include?(cluster_id)
           raise NotImplementedError, <<~MSG
-            There is no cluster configured for this index. Use `Esse.config.clusters(cluster_id) { ... }' define the elasticsearch
+            There is no cluster configured for this index. Use `Esse.config.cluster(cluster_id) { ... }' define the elasticsearch
             client connection.
           MSG
         end
 
-        Esse.synchronize { Esse.config.clusters(cluster_id) }
+        Esse.synchronize { Esse.config.cluster(cluster_id) }
       end
 
       def inspect

data/lib/esse/index/mappings.rb

@@ -7,7 +7,6 @@
 module Esse
   class Index
     module ClassMethods
-
       # This is the actually content that will be passed through the ES api
       def mappings_hash
         { Esse::MAPPING_ROOT_KEY => (index_mapping || type_mapping) }
@@ -16,9 +15,9 @@ module Esse
       # This method is only used to define mapping
       def mappings(hash = {}, &block)
         @mapping = Esse::IndexMapping.new(body: hash, paths: template_dirs)
-        return unless block_given?
+        return unless block
 
-        @mapping.define_singleton_method(:as_json, &block)
+        @mapping.define_singleton_method(:to_h, &block)
       end
 
       private

data/lib/esse/index/settings.rb

@@ -4,16 +4,15 @@ module Esse
   # https://github.com/elastic/elasticsearch-ruby/blob/master/elasticsearch-api/lib/elasticsearch/api/actions/indices/put_settings.rb
   class Index
     module ClassMethods
-
-      def settings_hash(cluster_settings: true)
-        hash = cluster_settings ? cluster.index_settings.merge(setting.body) : setting.body
+      def settings_hash
+        hash = setting.body
         { Esse::SETTING_ROOT_KEY => (hash.key?(Esse::SETTING_ROOT_KEY) ? hash[Esse::SETTING_ROOT_KEY] : hash) }
       end
 
       # Define /_settings definition by each index.
       #
       # +hash+: The body of the request includes the updated settings.
-      # +block+: Overwrite default :as_json from IndexSetting instance
+      # +block+: Overwrite default :to_h from IndexSetting instance
       #
       # Example:
       #
@@ -29,16 +28,16 @@ module Esse
       #     end
       #   end
       def settings(hash = {}, &block)
-        @setting = Esse::IndexSetting.new(body: hash, paths: template_dirs, globals: cluster.index_settings)
-        return unless block_given?
+        @setting = Esse::IndexSetting.new(body: hash, paths: template_dirs, globals: -> { cluster.index_settings })
+        return unless block
 
-        @setting.define_singleton_method(:as_json, &block)
+        @setting.define_singleton_method(:to_h, &block)
       end
 
       private
 
       def setting
-        @setting ||= Esse::IndexSetting.new(paths: template_dirs, globals: cluster.index_settings)
+        @setting ||= Esse::IndexSetting.new(paths: template_dirs, globals: -> { cluster.index_settings })
       end
     end