esse 0.2.2 → 0.2.3

data/lib/esse/{client_proxy → transport}/search.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 module Esse
-  class ClientProxy
+  class Transport
     module InstanceMethods
       # Returns results matching a query.
+      # @param [Hash] options
+      # @option [String] :index The comma-separated list of index names to search; use `_all` to perform the operation on all indices
       def search(index:, **options)
         definition = options.merge(
           index: index,
@@ -17,9 +19,10 @@ module Esse
 
       # Allows to retrieve a large numbers of results from a single search request.
       #
-      # @param [Time] :scroll Specify how long a consistent view of the index should be maintained for scrolled search
-      # @param [Boolean] :rest_total_hits_as_int Indicates whether hits.total should be rendered as an integer or an object in the rest search response
-      # @param [Hash] :body The scroll ID
+      # @param [Hash] options
+      # @option [Time] :scroll Specify how long a consistent view of the index should be maintained for scrolled search
+      # @option [Boolean] :rest_total_hits_as_int Indicates whether hits.total should be rendered as an integer or an object in the rest search response
+      # @option [Hash] :body The scroll ID
       def scroll(scroll:, **definition)
         unless definition[:body]
           raise ArgumentError, 'scroll search must have a :body with the :scroll_id'
@@ -32,7 +35,8 @@ module Esse
 
       # Explicitly clears the search context for a scroll.
       #
-      # @param [Hash] :body Body with the "scroll_id" (string or array of strings) Scroll IDs to clear.
+      # @param [Hash] options
+      # @option [Hash] :body Body with the "scroll_id" (string or array of strings) Scroll IDs to clear.
       #   To clear all scroll IDs, use _all.
       def clear_scroll(body:, **options)
         coerce_exception { client.clear_scroll(body: body, **options) }

data/lib/esse/transport.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Esse
+  class Transport
+    require_relative './transport/aliases'
+    require_relative './transport/health'
+    require_relative './transport/indices'
+    require_relative './transport/search'
+    require_relative './transport/documents'
+
+    extend Forwardable
+
+    def_delegators :@cluster, :client, :throw_error_when_readonly!
+
+    attr_reader :cluster
+
+    def initialize(cluster)
+      @cluster = cluster
+    end
+
+    # Elasticsearch::Transport was renamed to Elastic::Transport in 8.0
+    # This lib should support both versions that's why we are wrapping up the transport
+    # errors to local errors.
+    #
+    # We are not only coercing exceptions but also the response body. Elasticsearch-ruby >= 8.0 returns
+    # the response wrapped in a Elasticsearch::API::Response::Response object. We are unwrapping it
+    # to keep the same interface. But we may want to coerce it to some internal object in the future.
+    def coerce_exception
+      resp = yield
+      if resp.class.name.start_with?('Elasticsearch::API::Response')
+        resp = resp.body
+      end
+      resp
+    rescue => exception
+      name = Hstring.new(exception.class.name)
+      if /^(Elasticsearch|Elastic|OpenSearch)?::Transport::Transport::Errors/.match?(name.value) && \
+          (exception_class = Esse::Transport::ERRORS[name.demodulize.value])
+        raise exception_class.new(exception.message)
+      else
+        raise exception
+      end
+    end
+  end
+end

data/lib/esse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Esse
-  VERSION = '0.2.2'
+  VERSION = '0.2.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: esse
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Marcos G. Zimmermann
 autorequire:
 bindir: exec
 cert_chain: []
-date: 2023-02-14 00:00:00.000000000 Z
+date: 2023-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.12'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -198,9 +198,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.4'
-description: All the elegance of ruby with the elasticsearch flexibility. This gem
-  is a pretty simple but excential helpers to deal with mapping, indexing, serialization
-  and search.
+description: With all elegance of Ruby and ElasticSearch flexibility this gem brings
+  to you the best of both worlds. Provides a solid architecture allowing to easily
+  Extract, Transform, Enrich and Load data from any data source into ElasticSearch/OpenSearch
+  and also to search it. It is framework-agnostic, which means you can use it with
+  any Ruby framework or even without any framework at all.
 email:
 - mgzmaster@gmail.com
 executables:
@@ -210,18 +212,6 @@ extra_rdoc_files: []
 files:
 - exec/esse
 - lib/esse.rb
-- lib/esse/backend/index.rb
-- lib/esse/backend/index/aliases.rb
-- lib/esse/backend/index/close.rb
-- lib/esse/backend/index/create.rb
-- lib/esse/backend/index/delete.rb
-- lib/esse/backend/index/documents.rb
-- lib/esse/backend/index/existance.rb
-- lib/esse/backend/index/open.rb
-- lib/esse/backend/index/refresh.rb
-- lib/esse/backend/index/reset.rb
-- lib/esse/backend/index/update.rb
-- lib/esse/backend/repository_backend.rb
 - lib/esse/cli.rb
 - lib/esse/cli/base.rb
 - lib/esse/cli/event_listener.rb
@@ -239,12 +229,10 @@ files:
 - lib/esse/cli/index/update_settings.rb
 - lib/esse/cli/templates/collection.rb.erb
 - lib/esse/cli/templates/config.rb.erb
+- lib/esse/cli/templates/document.rb.erb
 - lib/esse/cli/templates/index.rb.erb
 - lib/esse/cli/templates/mappings.json
-- lib/esse/cli/templates/serializer.rb.erb
 - lib/esse/cli/templates/settings.json
-- lib/esse/client_proxy.rb
-- lib/esse/client_proxy/search.rb
 - lib/esse/cluster.rb
 - lib/esse/cluster_engine.rb
 - lib/esse/collection.rb
@@ -252,8 +240,13 @@ files:
 - lib/esse/core.rb
 - lib/esse/deprecations.rb
 - lib/esse/deprecations/cluster.rb
+- lib/esse/deprecations/deprecate.rb
 - lib/esse/deprecations/index.rb
+- lib/esse/deprecations/index_backend_delegator.rb
 - lib/esse/deprecations/repository.rb
+- lib/esse/deprecations/repository_backend_delegator.rb
+- lib/esse/deprecations/serializer.rb
+- lib/esse/document.rb
 - lib/esse/dynamic_template.rb
 - lib/esse/errors.rb
 - lib/esse/events.rb
@@ -265,10 +258,12 @@ files:
 - lib/esse/import/request_body.rb
 - lib/esse/index.rb
 - lib/esse/index/actions.rb
+- lib/esse/index/aliases.rb
 - lib/esse/index/attributes.rb
-- lib/esse/index/backend.rb
 - lib/esse/index/base.rb
 - lib/esse/index/descendants.rb
+- lib/esse/index/documents.rb
+- lib/esse/index/indices.rb
 - lib/esse/index/inheritance.rb
 - lib/esse/index/mappings.rb
 - lib/esse/index/object_document_mapper.rb
@@ -287,12 +282,17 @@ files:
 - lib/esse/primitives/output.rb
 - lib/esse/repository.rb
 - lib/esse/repository/actions.rb
-- lib/esse/repository/backend.rb
+- lib/esse/repository/documents.rb
 - lib/esse/repository/object_document_mapper.rb
 - lib/esse/search/query.rb
 - lib/esse/search/response.rb
-- lib/esse/serializer.rb
 - lib/esse/template_loader.rb
+- lib/esse/transport.rb
+- lib/esse/transport/aliases.rb
+- lib/esse/transport/documents.rb
+- lib/esse/transport/health.rb
+- lib/esse/transport/indices.rb
+- lib/esse/transport/search.rb
 - lib/esse/version.rb
 homepage: https://github.com/marcosgz/esse
 licenses:
@@ -316,9 +316,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
+rubygems_version: 3.2.32
 signing_key:
 specification_version: 4
-summary: Pure Ruby toolkit based on official elasticsearch-ruby library. (No! It isn't
-  a new DSL)
+summary: Pure Ruby and framework-agnostic ElasticSearch/OpenSearch toolkit for building
+  indexers and searchers
 test_files: []

data/lib/esse/backend/index/aliases.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-module Esse
-  module Backend
-    class Index
-      module InstanceMethods
-        # Return a list of index aliases.
-        #
-        # @param options [Hash] Hash of paramenters that will be passed along to elasticsearch request
-        # @param options [Array] :index list of serialized documents to be indexed(Optional)
-        #
-        # @see https://www.elastic.co/guide/en/elasticsearch/reference/7.5/indices-aliases.html
-        def aliases(**options)
-          response = coerce_exception { client.indices.get_alias({ index: index_name, name: '*' }.merge(options)) }
-          idx_name = response.keys.find { |idx| idx.start_with?(index_name) }
-          return [] unless idx_name
-
-          response.dig(idx_name, 'aliases')&.keys || []
-        rescue NotFoundError
-          []
-        end
-
-        # Returns a list of indices.
-        #
-        # @param options [Hash] Hash of paramenters that will be passed along to elasticsearch request
-        # @return [Array] list of indices that match with `index_name`.
-        def indices(**options)
-          coerce_exception { client.indices.get_alias({ name: index_name }.merge(options)).keys }
-        rescue NotFoundError
-          []
-        end
-
-        # Replaces all existing aliases by the respective suffixed index from argument.
-        #
-        # @param options [Hash] Hash of paramenters that will be passed along to elasticsearch request
-        # @option [String] :suffix The suffix of the index used for versioning.
-        # @raise [Esse::Backend::NotFoundError] in case of failure
-        # @return [Hash] the elasticsearch response
-        def update_aliases!(suffix:, **options)
-          raise(ArgumentError, 'index suffix cannot be nil') if suffix.nil?
-
-          options[:body] = {
-            actions: [
-              *indices.map do |index|
-                { remove: { index: index, alias: index_name } }
-              end,
-              { add: {index: build_real_index_name(suffix), alias: index_name } }
-            ],
-          }
-
-          Esse::Events.instrument('elasticsearch.update_aliases') do |payload|
-            payload[:request] = options
-            payload[:response] = coerce_exception { client.indices.update_aliases(options)}
-          end
-        end
-
-        # Replaces all existing aliases by the respective suffixed index from argument.
-        #
-        # @param options [Hash] Hash of paramenters that will be passed along to elasticsearch request
-        # @option [String] :suffix The suffix of the index used for versioning.
-        # @raise [Esse::Backend::NotFoundError] in case of failure
-        # @return [Hash] the elasticsearch response, or an hash with 'errors' as true in case of failure
-        def update_aliases(suffix:, **options)
-          update_aliases!(suffix: suffix, **options)
-        rescue NotFoundError
-          { 'errors' => true }
-        end
-      end
-
-      include InstanceMethods
-    end
-  end
-end

data/lib/esse/backend/index/close.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-module Esse
-  module Backend
-    class Index
-      module InstanceMethods
-        # Close an index (keep the data on disk, but deny operations with the index).
-        #
-        # @option options [String, nil] :suffix The index suffix. Defaults to the index_version.
-        #   Use nil if you want to check existence of the `index_name` index or alias.
-        # @option options [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that
-        #   are open, closed or both. (options: open, closed)
-        # @option options [String] :ignore_indices When performed on multiple indices, allows to ignore
-        #   `missing` ones (options: none, missing) @until 1.0
-        # @option options [Boolean] :ignore_unavailable Whether specified concrete indices should be ignored when
-        #   unavailable (missing, closed, etc)
-        # @option options [Time] :timeout Explicit operation timeout
-        # @raise [Esse::Backend::ServerError]
-        #   in case of failure
-        # @return [Hash] the elasticsearch response
-        #
-        # @see https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-open-close.html
-        def close!(suffix: index_version, **options)
-          Esse::Events.instrument('elasticsearch.close') do |payload|
-            payload[:request] = attributes = options.merge(index: index_name(suffix: suffix))
-            payload[:response] = coerce_exception { client.indices.close(**attributes) }
-          end
-        end
-
-        # Close an index (keep the data on disk, but deny operations with the index).
-        #
-        # @option options [String, nil] :suffix The index suffix. Defaults to the index_version.
-        #   Use nil if you want to check existence of the `index_name` index or alias.
-        # @option options [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that
-        #   are open, closed or both. (options: open, closed)
-        # @option options [String] :ignore_indices When performed on multiple indices, allows to ignore
-        #   `missing` ones (options: none, missing) @until 1.0
-        # @option options [Boolean] :ignore_unavailable Whether specified concrete indices should be ignored when
-        #   unavailable (missing, closed, etc)
-        # @option options [Time] :timeout Explicit operation timeout
-        # @return [Hash] the elasticsearch response, or an hash with 'errors' as true in case of failure
-        #
-        # @see https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-open-close.html
-        def close(suffix: index_version, **options)
-          close!(suffix: suffix, **options)
-        rescue ServerError
-          { 'errors' => true }
-        end
-      end
-
-      include InstanceMethods
-    end
-  end
-end

data/lib/esse/backend/index/create.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-module Esse
-  module Backend
-    class Index
-      module InstanceMethods
-        DEFAULT_OPTIONS = {
-          alias: true,
-        }.freeze
-
-        # Creates index and applies mappings and settings.
-        #
-        #   UsersIndex.elasticsearch.create_index # creates index named `<prefix_>users_<suffix|index_version|timestamp>`
-        #
-        # @param options [Hash] Options hash
-        # @option options [Boolean] :alias Update `index_name` alias along with the new index
-        # @option options [String] :suffix The index suffix. Defaults to the `IndexClass#index_version` or
-        #   `Esse.timestamp`. Suffixed index names might be used for zero-downtime mapping change.
-        # @return [Hash] the elasticsearch response, or an hash with 'errors' as true in case of failure
-        #
-        # @see http://www.elasticsearch.org/blog/changing-mapping-with-zero-downtime/
-        def create_index(suffix: index_version, **options)
-          create_index!(suffix: suffix, **options)
-        rescue ServerError
-          { 'errors' => true }
-        end
-
-        # Creates index and applies mappings and settings.
-        #
-        #   UsersIndex.elasticsearch.create_index! # creates index named `<prefix_>users_<suffix|index_version|timestamp>`
-        #
-        # @param options [Hash] Options hash
-        # @option options [Boolean] :alias Update `index_name` alias along with the new index
-        # @option options [String] :suffix The index suffix. Defaults to the `IndexClass#index_version` or
-        #   `Esse.timestamp`. Suffixed index names might be used for zero-downtime mapping change.
-        # @option arguments [String] :wait_for_active_shards Set the number of active shards
-        #    to wait for before the operation returns.
-        # @option arguments [Time] :timeout Explicit operation timeout
-        # @option arguments [Time] :master_timeout Specify timeout for connection to master
-        # @option arguments [Hash] :headers Custom HTTP headers
-        # @option arguments [Hash] :body The configuration for the index (`settings` and `mappings`)
-        # @raise [Esse::Backend::NotFoundError] when index already exists
-        # @return [Hash] the elasticsearch response
-        #
-        # @see http://www.elasticsearch.org/blog/changing-mapping-with-zero-downtime/
-        def create_index!(suffix: index_version, **options)
-          options = DEFAULT_OPTIONS.merge(options)
-          name = build_real_index_name(suffix)
-          definition = [settings_hash, mappings_hash].reduce(&:merge)
-
-          if options.delete(:alias) && name != index_name
-            definition[:aliases] = { index_name => {} }
-          end
-
-          Esse::Events.instrument('elasticsearch.create_index') do |payload|
-            payload[:request] = opts = options.merge(index: name, body: definition)
-            payload[:response] = response = coerce_exception { client.indices.create(**opts) }
-            coerce_exception { cluster.wait_for_status! } if response
-            response
-          end
-        end
-      end
-
-      include InstanceMethods
-    end
-  end
-end

data/lib/esse/backend/index/delete.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Esse
-  module Backend
-    class Index
-      module InstanceMethods
-        # Deletes ES index
-        #
-        #   UsersIndex.elasticsearch.delete_index! # deletes `<prefix_>users<_suffix|_index_version|_timestamp>` index
-        #
-        # @param suffix [String, nil] The index suffix Use nil if you want to delete the current index.
-        # @raise [Esse::Backend::NotFoundError] when index does not exists
-        # @return [Hash] elasticsearch response
-        def delete_index!(suffix: index_version, **options)
-          Esse::Events.instrument('elasticsearch.delete_index') do |payload|
-            payload[:request] = opts = options.merge(index: index_name(suffix: suffix))
-            payload[:response] = response = coerce_exception { client.indices.delete(**opts) }
-            coerce_exception { cluster.wait_for_status! } if response
-            response
-          end
-        end
-
-        # Deletes ES index
-        #
-        #   UsersIndex.elasticsearch.delete_index # deletes `<prefix_>users<_suffix|_index_version|_timestamp>` index
-        #
-        # @param suffix [String, nil] The index suffix Use nil if you want to delete the current index.
-        # @return [Hash] the elasticsearch response, or an hash with 'errors' as true in case of failure
-        def delete_index(suffix: index_version, **options)
-          delete_index!(suffix: suffix, **options)
-        rescue ServerError
-          { 'errors' => true }
-        end
-      end
-
-      include InstanceMethods
-    end
-  end
-end