noiseless 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3568cdfb6fe26188f2ccb0287265f3adfd128b8a056f06636496c8644a87cad3
-  data.tar.gz: f0b29fa15d18a083950553337b9295e480c3966204dc614df5b9b4999b073742
+  metadata.gz: f66be9c1d81e3b887f0c0d4485381c4535f087f8365e2581c4c41d89cdba0934
+  data.tar.gz: 1565bffbcfb554d2b6afcc78ebb1ded79c5c58a8f157b1e25ccd9a449cd2abe2
 SHA512:
-  metadata.gz: cda0f5f8ebdfa6d4f35f6caa9d8c49d179d0fd0d1bdbe928ac9605d3da67e91635b0a15827fcc74c5b2196b4381050a11051a97c1f6a8b75890a20f88d32be60
-  data.tar.gz: f379b20348f2c293255aa56815e458a0668ad77aa0fe01026ed21239a751a815264bbccd87bee54dbad6b55496940f543c186f008621eaa5e767e455a6f9d156
+  metadata.gz: 4a7e23f4eb136bc6c0dc457dcb6f267e000269aceddd6450264ac489429dda2e20c7b382b32c2ab2a91271faeccee419a5c72530e3781087a9f630e8bd16a15d
+  data.tar.gz: 605cf0980142cbe65692b9ef8d2a543969578620fa17b35e069a0344ac1a5ca5947781c6d9cf617203408a73e11cd08626c000d046e4a7a9839508919de8d463

data/lib/noiseless/adapter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "async"
+require "json"
 require_relative "introspection"
 
 module Noiseless
@@ -8,6 +9,17 @@ module Noiseless
     include Instrumentation
     include Introspection
 
+    GEO_FILTER_KEYS = %i[geo_distance geo_bounding_box geo_polygon geo_shape].freeze
+    RANGE_OPERATORS = %i[gte lte gt lt].freeze
+
+    # Aggregation types that require a field (or script) to execute.
+    FIELD_BASED_AGG_TYPES = %i[
+      terms rare_terms significant_terms missing
+      avg sum min max cardinality value_count stats extended_stats
+      percentiles percentile_ranks histogram date_histogram
+      geohash_grid geotile_grid geo_distance
+    ].freeze
+
     def initialize(hosts: [], **connection_params)
       @hosts = hosts
       @connection_params = connection_params.dup
@@ -60,6 +72,14 @@ module Noiseless
       end
     end
 
+    def refresh_index(index_name)
+      Async do
+        instrument(:refresh_index, index: index_name) do
+          execute_refresh_index(index_name)
+        end
+      end
+    end
+
     def index_exists?(index_name)
       Async do
         execute_index_exists?(index_name)
@@ -188,11 +208,32 @@ module Noiseless
       {
         bool: {
           must: must_queries,
-          filter: bool_node.filter.map { |f| { term: { f.field => f.value } } }
+          filter: bool_node.filter.map { |f| build_filter_clause(f) }
         }.reject { |_, v| v.empty? }
       }
     end
 
+    def build_filter_clause(node)
+      value = node.value
+      case value
+      when Hash
+        keys = value.keys.map(&:to_sym)
+        if keys.intersect?(GEO_FILTER_KEYS)
+          # Geo filters are already complete query clauses, e.g.
+          # { geo_distance: { distance: "100km", location: { lat:, lon: } } }
+          value
+        elsif (keys - RANGE_OPERATORS).empty?
+          { range: { node.field => value } }
+        else
+          { term: { node.field => value } }
+        end
+      when Array
+        { terms: { node.field => value } }
+      else
+        { term: { node.field => value } }
+      end
+    end
+
     def build_sort_hash(sort_nodes)
       return [] if sort_nodes.empty?
 
@@ -208,6 +249,31 @@ module Noiseless
       }
     end
 
+    # Parses a backend HTTP response, raising when the backend reported an error.
+    # Success responses return the parsed JSON payload; error responses raise
+    # `error_class` with the backend's error type/reason so failures are never
+    # silently converted into empty results.
+    def parse_json_response!(response, error_class: Noiseless::RequestError, context: nil)
+      body = response.read
+      return JSON.parse(body) if response.success?
+
+      payload = begin
+        JSON.parse(body)
+      rescue JSON::ParserError, TypeError
+        nil
+      end
+      error = payload.is_a?(Hash) ? payload["error"] : nil
+      reason = if error.is_a?(Hash)
+                 [error["type"], error["reason"]].compact.join(": ")
+               elsif error
+                 error.to_s
+               else
+                 "HTTP #{response.status}"
+               end
+      message = context ? "#{context}: #{reason}" : reason
+      raise error_class.new(message, status: response.status, error_type: error.is_a?(Hash) ? error["type"] : nil)
+    end
+
     # Override in subclasses
     def execute_search(_query_hash, **_opts)
       {
@@ -233,6 +299,10 @@ module Noiseless
       { acknowledged: true }
     end
 
+    def execute_refresh_index(_index_name)
+      { "acknowledged" => true }
+    end
+
     def execute_index_exists?(_index_name)
       true
     end
@@ -302,6 +372,10 @@ module Noiseless
       agg_body[:field] = agg.field if agg.field
       agg_body.merge!(agg.options)
 
+      # Convention: an unqualified field-based aggregation targets the field
+      # named after the aggregation itself.
+      agg_body[:field] = agg.name if !agg_body.key?(:field) && !agg_body.key?(:script) && FIELD_BASED_AGG_TYPES.include?(agg.type.to_sym)
+
       result[agg.type] = agg_body
 
       # Add sub-aggregations if any

data/lib/noiseless/adapters/cluster_api.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module Adapters
+    # Cluster health API - needed for Rails healthcheck
+    class ClusterAPI
+      def initialize(adapter)
+        @adapter = adapter
+      end
+
+      def health(**)
+        Sync do
+          @adapter.send(:execute_cluster_health, **)
+        end
+      end
+    end
+  end
+end

data/lib/noiseless/adapters/elasticsearch.rb

@@ -7,22 +7,8 @@ module Noiseless
     class Elasticsearch < Adapter
       include ExecutionModules::ElasticsearchExecution
 
-      def initialize(hosts: [], **connection_params)
-        # Ensure we always have at least one host
-        hosts_array = Array(hosts)
-        default_port = ENV["ELASTICSEARCH_PORT"] || 9200
-        @hosts = hosts_array.empty? ? ["http://localhost:#{default_port}"] : hosts_array
-        @connection_params = connection_params
-
-        # Initialize HTTP clients for each host
-        @clients = {}
-        @hosts.each do |host|
-          endpoint = Async::HTTP::Endpoint.parse(host)
-          @clients[host] = Async::HTTP::Client.new(endpoint)
-        end
-
-        super(hosts: @hosts, **connection_params)
-      end
+      ClusterAPI = Adapters::ClusterAPI
+      IndicesAPI = Adapters::IndicesAPI
 
       # Cluster health API - needed for Rails healthcheck
       def cluster
@@ -34,36 +20,10 @@ module Noiseless
         @indices ||= IndicesAPI.new(self)
       end
 
-      class ClusterAPI
-        def initialize(adapter)
-          @adapter = adapter
-        end
-
-        def health(**)
-          Sync do
-            @adapter.send(:execute_cluster_health, **)
-          end
-        end
-      end
-
-      class IndicesAPI
-        def initialize(adapter)
-          @adapter = adapter
-        end
-
-        def get(index:)
-          @adapter.execute_index_exists?(index) ? { index => {} } : raise("Index not found")
-        end
-
-        def stats(index:)
-          # Return basic stats structure
-          { "indices" => { index => {} } }
-        end
+      private
 
-        def refresh(index:)
-          # Refresh the index to make documents immediately searchable
-          @adapter.send(:execute_refresh_index, index)
-        end
+      def default_port
+        ENV["ELASTICSEARCH_PORT"] || 9200
       end
     end
   end

data/lib/noiseless/adapters/execution_modules/elasticsearch_execution.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "es_compatible_execution"
 
 module Noiseless
   module Adapters
     module ExecutionModules
       module ElasticsearchExecution
-        def close
-          @clients&.each_value(&:close)
-        end
+        include EsCompatibleExecution
 
         private
 
@@ -17,16 +16,7 @@ module Noiseless
           body = JSON.generate(query_hash)
 
           response = post_request(path, body)
-          JSON.parse(response.read)
-        ensure
-          response&.close
-        end
-
-        def execute_bulk(actions, **_opts)
-          body = "#{actions.map { |action| JSON.generate(action) }.join("\n")}\n"
-
-          response = post_request("/_bulk", body, content_type: "application/x-ndjson")
-          JSON.parse(response.read)
+          parse_json_response!(response, error_class: Noiseless::SearchError, context: "search")
         ensure
           response&.close
         end
@@ -37,42 +27,7 @@ module Noiseless
           body[:settings] = settings if settings
 
           response = put_request("/#{index_name}", body.any? ? JSON.generate(body) : nil)
-          JSON.parse(response.read)
-        ensure
-          response&.close
-        end
-
-        def execute_delete_index(index_name, **_opts)
-          response = delete_request("/#{index_name}")
-          JSON.parse(response.read)
-        ensure
-          response&.close
-        end
-
-        def execute_refresh_index(index_name)
-          response = post_request("/#{index_name}/_refresh", nil)
-          JSON.parse(response.read)
-        rescue StandardError => e
-          {
-            "_shards" => {
-              "total" => 0,
-              "successful" => 0,
-              "failed" => 0
-            },
-            "error" => {
-              "type" => e.class.name,
-              "reason" => e.message
-            }
-          }
-        ensure
-          response&.close
-        end
-
-        def execute_index_exists?(index_name)
-          response = head_request("/#{index_name}")
-          response.success?
-        rescue StandardError
-          false
+          parse_json_response!(response, context: "create index #{index_name}")
         ensure
           response&.close
         end
@@ -82,32 +37,7 @@ module Noiseless
           body = JSON.generate(document)
 
           response = id ? put_request(path, body) : post_request(path, body)
-          JSON.parse(response.read)
-        ensure
-          response&.close
-        end
-
-        def execute_update_document(index, id, changes, **_opts)
-          body = JSON.generate(doc: changes)
-
-          response = post_request("/#{index}/_update/#{id}", body)
-          JSON.parse(response.read)
-        ensure
-          response&.close
-        end
-
-        def execute_delete_document(index, id, **_opts)
-          response = delete_request("/#{index}/_doc/#{id}")
-          JSON.parse(response.read)
-        ensure
-          response&.close
-        end
-
-        def execute_document_exists?(index, id)
-          response = head_request("/#{index}/_doc/#{id}")
-          response.success?
-        rescue StandardError
-          false
+          parse_json_response!(response, context: "index document #{index}/#{id}")
         ensure
           response&.close
         end
@@ -132,56 +62,6 @@ module Noiseless
         ensure
           response&.close
         end
-
-        # HTTP helpers using Async::HTTP with connection pooling
-        def get_request(path)
-          with_client do |client|
-            client.get(path, default_headers)
-          end
-        end
-
-        def post_request(path, body, content_type: "application/json")
-          headers = body ? default_headers + [["content-type", content_type]] : default_headers
-
-          with_client do |client|
-            client.post(path, headers, body)
-          end
-        end
-
-        def put_request(path, body, content_type: "application/json")
-          headers = body ? default_headers + [["content-type", content_type]] : default_headers
-
-          with_client do |client|
-            client.put(path, headers, body)
-          end
-        end
-
-        def delete_request(path)
-          with_client do |client|
-            client.delete(path, default_headers)
-          end
-        end
-
-        def head_request(path)
-          with_client do |client|
-            client.head(path, default_headers)
-          end
-        end
-
-        def with_client
-          # Select a random host for load balancing
-          host = @hosts.sample
-          client = @clients[host]
-
-          yield(client)
-        end
-
-        def default_headers
-          [
-            ["accept", "application/json"],
-            ["user-agent", "Noiseless/#{Noiseless::VERSION} (Ruby/#{RUBY_VERSION})"]
-          ]
-        end
       end
     end
   end

data/lib/noiseless/adapters/execution_modules/es_compatible_execution.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "http_transport"
+
+module Noiseless
+  module Adapters
+    module ExecutionModules
+      # Document and index operations shared by the wire-compatible
+      # Elasticsearch and OpenSearch HTTP APIs.
+      module EsCompatibleExecution
+        include HttpTransport
+
+        private
+
+        def execute_bulk(actions, **_opts)
+          body = actions.map do |action|
+            if action[:index]
+              action_line = { index: { _index: action[:index][:_index], _id: action[:index][:_id] } }
+              data_line = action[:index][:data]
+              "#{JSON.generate(action_line)}\n#{JSON.generate(data_line)}\n"
+            else
+              "#{JSON.generate(action)}\n"
+            end
+          end.join
+
+          response = post_request("/_bulk", body, content_type: "application/x-ndjson")
+          parse_json_response!(response, context: "bulk")
+        ensure
+          response&.close
+        end
+
+        def execute_delete_index(index_name, **_opts)
+          response = delete_request("/#{index_name}")
+          # Deleting an absent index is idempotent, matching official ES/OS
+          # clients' ignore-404 behaviour.
+          return { "acknowledged" => true, "result" => "not_found" } if response.status == 404
+
+          parse_json_response!(response, context: "delete index #{index_name}")
+        ensure
+          response&.close
+        end
+
+        def execute_refresh_index(index_name)
+          response = post_request("/#{index_name}/_refresh", nil)
+          parse_json_response!(response, context: "refresh index #{index_name}")
+        ensure
+          response&.close
+        end
+
+        def execute_index_exists?(index_name)
+          response = head_request("/#{index_name}")
+          response.success?
+        rescue StandardError
+          false
+        ensure
+          response&.close
+        end
+
+        def execute_update_document(index, id, changes, **_opts)
+          body = JSON.generate(doc: changes)
+
+          response = post_request("/#{index}/_update/#{id}", body)
+          parse_json_response!(response, context: "update document #{index}/#{id}")
+        ensure
+          response&.close
+        end
+
+        def execute_delete_document(index, id, **_opts)
+          response = delete_request("/#{index}/_doc/#{id}")
+          # 404 covers both a missing document and a missing index; either way
+          # the delete is idempotent.
+          return { "_index" => index, "_id" => id, "result" => "not_found" } if response.status == 404
+
+          parse_json_response!(response, context: "delete document #{index}/#{id}")
+        ensure
+          response&.close
+        end
+
+        def execute_document_exists?(index, id)
+          response = head_request("/#{index}/_doc/#{id}")
+          response.success?
+        rescue StandardError
+          false
+        ensure
+          response&.close
+        end
+      end
+    end
+  end
+end

data/lib/noiseless/adapters/execution_modules/http_transport.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module Adapters
+    module ExecutionModules
+      # Shared Async::HTTP connection handling for HTTP-based adapters.
+      # Host classes must provide a private +default_port+ method.
+      module HttpTransport
+        def initialize(hosts: [], **connection_params)
+          # Ensure we always have at least one host
+          hosts_array = Array(hosts)
+          @hosts = hosts_array.empty? ? ["http://localhost:#{default_port}"] : hosts_array
+          @connection_params = connection_params
+
+          # Initialize HTTP clients for each host
+          @clients = {}
+          @hosts.each do |host|
+            endpoint = Async::HTTP::Endpoint.parse(host)
+            @clients[host] = Async::HTTP::Client.new(endpoint)
+          end
+
+          super(hosts: @hosts, **connection_params)
+        end
+
+        def close
+          @clients&.each_value(&:close)
+        end
+
+        private
+
+        # HTTP helpers using Async::HTTP with connection pooling
+        def get_request(path)
+          with_client do |client|
+            client.get(path, default_headers)
+          end
+        end
+
+        def post_request(path, body, content_type: "application/json")
+          headers = body ? default_headers + [["content-type", content_type]] : default_headers
+
+          with_client do |client|
+            client.post(path, headers, body)
+          end
+        end
+
+        def put_request(path, body, content_type: "application/json")
+          headers = body ? default_headers + [["content-type", content_type]] : default_headers
+
+          with_client do |client|
+            client.put(path, headers, body)
+          end
+        end
+
+        def delete_request(path)
+          with_client do |client|
+            client.delete(path, default_headers)
+          end
+        end
+
+        def head_request(path)
+          with_client do |client|
+            client.head(path, default_headers)
+          end
+        end
+
+        def with_client
+          # Select a random host for load balancing
+          host = @hosts.sample
+          client = @clients[host]
+
+          yield(client)
+        end
+
+        def default_headers
+          [
+            ["accept", "application/json"],
+            ["user-agent", "Noiseless/#{Noiseless::VERSION} (Ruby/#{RUBY_VERSION})"]
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/noiseless/adapters/execution_modules/opensearch_execution.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "es_compatible_execution"
 
 module Noiseless
   module Adapters
     module ExecutionModules
       module OpensearchExecution
-        def close
-          @clients&.each_value(&:close)
-        end
+        include EsCompatibleExecution
 
         private
 
@@ -18,43 +17,7 @@ module Noiseless
           body = JSON.generate(query_hash)
 
           response = post_request(path, body)
-          JSON.parse(response.read)
-        rescue StandardError => e
-          # Return empty response on error to maintain compatibility
-          {
-            took: 0,
-            timed_out: false,
-            _shards: { total: 0, successful: 0, skipped: 0, failed: 0 },
-            hits: {
-              total: { value: 0, relation: "eq" },
-              max_score: nil,
-              hits: []
-            },
-            error: {
-              type: e.class.name,
-              reason: e.message
-            }
-          }
-        ensure
-          response&.close
-        end
-
-        def execute_bulk(actions, **_opts)
-          # Build bulk request body
-          bulk_body = actions.map do |action|
-            if action[:index]
-              action_line = { index: { _index: action[:index][:_index], _id: action[:index][:_id] } }
-              data_line = action[:index][:data]
-              "#{JSON.generate(action_line)}\n#{JSON.generate(data_line)}\n"
-            else
-              "#{JSON.generate(action)}\n"
-            end
-          end.join
-
-          response = post_request("/_bulk", bulk_body, content_type: "application/x-ndjson")
-          JSON.parse(response.read)
-        rescue StandardError => e
-          { items: [], errors: true, error: { type: e.class.name, reason: e.message } }
+          parse_json_response!(response, error_class: Noiseless::SearchError, context: "search #{index_path}")
         ensure
           response&.close
         end
@@ -65,46 +28,7 @@ module Noiseless
           body[:settings] = settings if settings
 
           response = put_request("/#{index_name}", body.any? ? JSON.generate(body) : nil)
-          JSON.parse(response.read)
-        rescue StandardError => e
-          { acknowledged: false, error: { type: e.class.name, reason: e.message } }
-        ensure
-          response&.close
-        end
-
-        def execute_delete_index(index_name, **_opts)
-          response = delete_request("/#{index_name}")
-          JSON.parse(response.read)
-        rescue StandardError => e
-          { acknowledged: false, error: { type: e.class.name, reason: e.message } }
-        ensure
-          response&.close
-        end
-
-        def execute_refresh_index(index_name)
-          response = post_request("/#{index_name}/_refresh", nil)
-          JSON.parse(response.read)
-        rescue StandardError => e
-          {
-            "_shards" => {
-              "total" => 0,
-              "successful" => 0,
-              "failed" => 0
-            },
-            "error" => {
-              "type" => e.class.name,
-              "reason" => e.message
-            }
-          }
-        ensure
-          response&.close
-        end
-
-        def execute_index_exists?(index_name)
-          response = head_request("/#{index_name}")
-          response.success?
-        rescue StandardError
-          false
+          parse_json_response!(response, context: "create index #{index_name}")
         ensure
           response&.close
         end
@@ -114,38 +38,7 @@ module Noiseless
           body = JSON.generate(document)
 
           response = put_request(path, body)
-          JSON.parse(response.read)
-        rescue StandardError => e
-          { _index: index, _id: id, result: "error", error: { type: e.class.name, reason: e.message } }
-        ensure
-          response&.close
-        end
-
-        def execute_update_document(index, id, changes, **_opts)
-          body = JSON.generate(doc: changes)
-
-          response = post_request("/#{index}/_update/#{id}", body)
-          JSON.parse(response.read)
-        rescue StandardError => e
-          { _index: index, _id: id, result: "error", error: { type: e.class.name, reason: e.message } }
-        ensure
-          response&.close
-        end
-
-        def execute_delete_document(index, id, **_opts)
-          response = delete_request("/#{index}/_doc/#{id}")
-          JSON.parse(response.read)
-        rescue StandardError => e
-          { _index: index, _id: id, result: "error", error: { type: e.class.name, reason: e.message } }
-        ensure
-          response&.close
-        end
-
-        def execute_document_exists?(index, id)
-          response = head_request("/#{index}/_doc/#{id}")
-          response.success?
-        rescue StandardError
-          false
+          parse_json_response!(response, context: "index document #{index}/#{id}")
         ensure
           response&.close
         end
@@ -178,13 +71,7 @@ module Noiseless
           body = JSON.generate(enhanced_query)
 
           response = post_request("/_search", body)
-          JSON.parse(response.read)
-        rescue StandardError => e
-          {
-            pit_id: pit_id,
-            error: { type: e.class.name, reason: e.message },
-            hits: { total: { value: 0 }, hits: [] }
-          }
+          parse_json_response!(response, error_class: Noiseless::SearchError, context: "point-in-time search")
         ensure
           response&.close
         end
@@ -198,12 +85,7 @@ module Noiseless
           body = JSON.generate(template_query)
 
           response = post_request("/_search/template", body)
-          JSON.parse(response.read)
-        rescue StandardError => e
-          {
-            error: { type: e.class.name, reason: e.message },
-            hits: { total: { value: 0 }, hits: [] }
-          }
+          parse_json_response!(response, error_class: Noiseless::SearchError, context: "search template #{template_id}")
         ensure
           response&.close
         end
@@ -321,56 +203,6 @@ module Noiseless
         ensure
           response&.close
         end
-
-        # HTTP helpers using Async::HTTP with connection pooling
-        def get_request(path)
-          with_client do |client|
-            client.get(path, default_headers)
-          end
-        end
-
-        def post_request(path, body, content_type: "application/json")
-          headers = body ? default_headers + [["content-type", content_type]] : default_headers
-
-          with_client do |client|
-            client.post(path, headers, body)
-          end
-        end
-
-        def put_request(path, body, content_type: "application/json")
-          headers = body ? default_headers + [["content-type", content_type]] : default_headers
-
-          with_client do |client|
-            client.put(path, headers, body)
-          end
-        end
-
-        def delete_request(path)
-          with_client do |client|
-            client.delete(path, default_headers)
-          end
-        end
-
-        def head_request(path)
-          with_client do |client|
-            client.head(path, default_headers)
-          end
-        end
-
-        def with_client
-          # Select a random host for load balancing
-          host = @hosts.sample
-          client = @clients[host]
-
-          yield(client)
-        end
-
-        def default_headers
-          [
-            ["accept", "application/json"],
-            ["user-agent", "Noiseless/#{Noiseless::VERSION} (Ruby/#{RUBY_VERSION})"]
-          ]
-        end
       end
     end
   end

data/lib/noiseless/adapters/execution_modules/typesense_execution.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "http_transport"
 
 module Noiseless
   module Adapters
     module ExecutionModules
       module TypesenseExecution
-        def close
-          @clients&.each_value(&:close)
-        end
+        include HttpTransport
 
         private
 
@@ -391,54 +390,8 @@ module Noiseless
           response&.close
         end
 
-        # HTTP helpers using Async::HTTP with connection pooling
-        def get_request(path)
-          with_client do |client|
-            client.get(path, default_headers)
-          end
-        end
-
-        def post_request(path, body, content_type: "application/json")
-          headers = body ? default_headers + [["content-type", content_type]] : default_headers
-
-          with_client do |client|
-            client.post(path, headers, body)
-          end
-        end
-
-        def put_request(path, body, content_type: "application/json")
-          headers = body ? default_headers + [["content-type", content_type]] : default_headers
-
-          with_client do |client|
-            client.put(path, headers, body)
-          end
-        end
-
-        def delete_request(path)
-          with_client do |client|
-            client.delete(path, default_headers)
-          end
-        end
-
-        def head_request(path)
-          with_client do |client|
-            client.head(path, default_headers)
-          end
-        end
-
-        def with_client
-          # Select a random host for load balancing
-          host = @hosts.sample
-          client = @clients[host]
-
-          yield(client)
-        end
-
         def default_headers
-          headers = [
-            ["accept", "application/json"],
-            ["user-agent", "Noiseless/#{Noiseless::VERSION} (Ruby/#{RUBY_VERSION})"]
-          ]
+          headers = super
 
           # Add Typesense API key if configured
           if @connection_params && @connection_params[:api_key]

data/lib/noiseless/adapters/indices_api.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module Adapters
+    # Indices API - needed for index management operations
+    class IndicesAPI
+      def initialize(adapter)
+        @adapter = adapter
+      end
+
+      def get(index:)
+        @adapter.execute_index_exists?(index) ? { index => {} } : raise("Index not found")
+      end
+
+      def stats(index:)
+        # Return basic stats structure
+        { "indices" => { index => {} } }
+      end
+
+      def refresh(index:)
+        # Refresh the index to make documents immediately searchable
+        @adapter.refresh_index(index).wait
+      end
+    end
+  end
+end

data/lib/noiseless/adapters/open_search.rb

@@ -7,22 +7,8 @@ module Noiseless
     class OpenSearch < Adapter
       include ExecutionModules::OpensearchExecution
 
-      def initialize(hosts: [], **connection_params)
-        # Ensure we always have at least one host
-        hosts_array = Array(hosts)
-        default_port = ENV["OPENSEARCH_PORT"] || 9200
-        @hosts = hosts_array.empty? ? ["http://localhost:#{default_port}"] : hosts_array
-        @connection_params = connection_params
-
-        # Initialize HTTP clients for each host
-        @clients = {}
-        @hosts.each do |host|
-          endpoint = Async::HTTP::Endpoint.parse(host)
-          @clients[host] = Async::HTTP::Client.new(endpoint)
-        end
-
-        super(hosts: @hosts, **connection_params)
-      end
+      ClusterAPI = Adapters::ClusterAPI
+      IndicesAPI = Adapters::IndicesAPI
 
       # OpenSearch-specific features
       def point_in_time_search(ast_node, pit_id:, **)
@@ -65,38 +51,6 @@ module Noiseless
         end
       end
 
-      class ClusterAPI
-        def initialize(adapter)
-          @adapter = adapter
-        end
-
-        def health(**)
-          Sync do
-            @adapter.send(:execute_cluster_health, **)
-          end
-        end
-      end
-
-      class IndicesAPI
-        def initialize(adapter)
-          @adapter = adapter
-        end
-
-        def get(index:)
-          @adapter.execute_index_exists?(index) ? { index => {} } : raise("Index not found")
-        end
-
-        def stats(index:)
-          # Return basic stats structure
-          { "indices" => { index => {} } }
-        end
-
-        def refresh(index:)
-          # Refresh the index to make documents immediately searchable
-          @adapter.send(:execute_refresh_index, index)
-        end
-      end
-
       # Search Pipelines API for OpenSearch 3.x
       # Pipelines can include request and response processors for neural search, reranking, etc.
       class PipelinesAPI
@@ -203,6 +157,12 @@ module Noiseless
           end
         end
       end
+
+      private
+
+      def default_port
+        ENV["OPENSEARCH_PORT"] || 9200
+      end
     end
   end
 end

data/lib/noiseless/adapters/typesense.rb

@@ -7,22 +7,7 @@ module Noiseless
     class Typesense < Adapter
       include ExecutionModules::TypesenseExecution
 
-      def initialize(hosts: [], **connection_params)
-        # Ensure we always have at least one host
-        hosts_array = Array(hosts)
-        default_port = ENV["TYPESENSE_PORT"] || 8108
-        @hosts = hosts_array.empty? ? ["http://localhost:#{default_port}"] : hosts_array
-        @connection_params = connection_params
-
-        # Initialize HTTP clients for each host
-        @clients = {}
-        @hosts.each do |host|
-          endpoint = Async::HTTP::Endpoint.parse(host)
-          @clients[host] = Async::HTTP::Client.new(endpoint)
-        end
-
-        super(hosts: @hosts, **connection_params)
-      end
+      ClusterAPI = Adapters::ClusterAPI
 
       # Cluster health API - needed for Rails healthcheck
       def cluster
@@ -34,37 +19,18 @@ module Noiseless
         @indices ||= IndicesAPI.new(self)
       end
 
-      class ClusterAPI
-        def initialize(adapter)
-          @adapter = adapter
-        end
-
-        def health(**)
-          Sync do
-            @adapter.send(:execute_cluster_health, **)
-          end
-        end
-      end
-
-      class IndicesAPI
-        def initialize(adapter)
-          @adapter = adapter
-        end
-
-        def get(index:)
-          @adapter.execute_index_exists?(index) ? { index => {} } : raise("Index not found")
-        end
-
-        def stats(index:)
-          # Return basic stats structure
-          { "indices" => { index => {} } }
-        end
-
+      class IndicesAPI < Adapters::IndicesAPI
         def refresh(index: nil) # rubocop:disable Lint/UnusedMethodArgument
           # Typesense doesn't require explicit refresh - documents are immediately available
           { "_shards" => { "total" => 1, "successful" => 1, "failed" => 0 } }
         end
       end
+
+      private
+
+      def default_port
+        ENV["TYPESENSE_PORT"] || 8108
+      end
     end
   end
 end

data/lib/noiseless/ast/field_value_node.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    # Base for leaf nodes that pair a single field with a value.
+    class FieldValueNode < Node
+      attr_reader :field, :value
+
+      def initialize(field, value)
+        super()
+        @field = field
+        @value = value
+      end
+    end
+  end
+end

data/lib/noiseless/ast/filter.rb

@@ -2,14 +2,7 @@
 
 module Noiseless
   module AST
-    class Filter < Node
-      attr_reader :field, :value
-
-      def initialize(field, value)
-        super()
-        @field = field
-        @value = value
-      end
+    class Filter < FieldValueNode
     end
   end
 end

data/lib/noiseless/ast/match.rb

@@ -2,14 +2,7 @@
 
 module Noiseless
   module AST
-    class Match < Node
-      attr_reader :field, :value
-
-      def initialize(field, value)
-        super()
-        @field = field
-        @value = value
-      end
+    class Match < FieldValueNode
     end
   end
 end

data/lib/noiseless/ast/prefix.rb

@@ -2,14 +2,7 @@
 
 module Noiseless
   module AST
-    class Prefix < Node
-      attr_reader :field, :value
-
-      def initialize(field, value)
-        super()
-        @field = field
-        @value = value
-      end
+    class Prefix < FieldValueNode
     end
   end
 end

data/lib/noiseless/ast/wildcard.rb

@@ -2,14 +2,7 @@
 
 module Noiseless
   module AST
-    class Wildcard < Node
-      attr_reader :field, :value
-
-      def initialize(field, value)
-        super()
-        @field = field
-        @value = value
-      end
+    class Wildcard < FieldValueNode
     end
   end
 end

data/lib/noiseless/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Noiseless
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/noiseless.rb

@@ -17,6 +17,21 @@ require_relative "noiseless/version"
 module Noiseless
   class Error < StandardError; end
 
+  # HTTP-level failure from the search backend (non-2xx response).
+  class RequestError < Error
+    attr_reader :status, :error_type
+
+    def initialize(message, status: nil, error_type: nil)
+      super(message)
+      @status = status
+      @error_type = error_type
+    end
+  end
+
+  # Raised when a search query is rejected by the backend
+  # (malformed query, missing index, shard failures).
+  class SearchError < RequestError; end
+
   class Configuration
     attr_accessor :connections_config, :default_connection, :default_adapter, :config_path
 
@@ -85,7 +100,8 @@ module Noiseless
 
   # Setup Zeitwerk autoloader
   loader = Zeitwerk::Loader.for_gem
-  loader.inflector.inflect("ast" => "AST", "dsl" => "DSL", "open_search" => "OpenSearch")
+  loader.inflector.inflect("ast" => "AST", "dsl" => "DSL", "open_search" => "OpenSearch",
+                           "cluster_api" => "ClusterAPI", "indices_api" => "IndicesAPI")
   loader.ignore("#{__dir__}/application_search.rb")
   loader.ignore("#{__dir__}/noiseless/test_helper.rb")
   loader.ignore("#{__dir__}/noiseless/test_case.rb")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: noiseless
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -206,12 +206,16 @@ files:
 - lib/noiseless.rb
 - lib/noiseless/adapter.rb
 - lib/noiseless/adapters.rb
+- lib/noiseless/adapters/cluster_api.rb
 - lib/noiseless/adapters/elasticsearch.rb
 - lib/noiseless/adapters/execution_modules/elasticsearch_execution.rb
+- lib/noiseless/adapters/execution_modules/es_compatible_execution.rb
+- lib/noiseless/adapters/execution_modules/http_transport.rb
 - lib/noiseless/adapters/execution_modules/opensearch_execution.rb
 - lib/noiseless/adapters/execution_modules/pgvector_support.rb
 - lib/noiseless/adapters/execution_modules/postgresql_execution.rb
 - lib/noiseless/adapters/execution_modules/typesense_execution.rb
+- lib/noiseless/adapters/indices_api.rb
 - lib/noiseless/adapters/open_search.rb
 - lib/noiseless/adapters/postgresql.rb
 - lib/noiseless/adapters/typesense.rb
@@ -222,6 +226,7 @@ files:
 - lib/noiseless/ast/collapse.rb
 - lib/noiseless/ast/combined_fields.rb
 - lib/noiseless/ast/conversation.rb
+- lib/noiseless/ast/field_value_node.rb
 - lib/noiseless/ast/filter.rb
 - lib/noiseless/ast/hybrid.rb
 - lib/noiseless/ast/image_query.rb