noiseless 0.0.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b80fb21fd8ce9ead0c11e07f58073c6e2d6ffeb725c12b942900232a869562a
-  data.tar.gz: dd05691108e09285328159ec96892fd1564bfbe17461ea3665d947aedfe81b0e
+  metadata.gz: 7fb5d9afa49be27d359d92a2fdf24999d488f8a7d865547452ea10b7aae67850
+  data.tar.gz: da2fb4b847d7c1b53bb17b7b0a588d2a1660006cbe9413af0b657282087ad681
 SHA512:
-  metadata.gz: 4babc5689c8e21b325c3cf6bc595f8b92f91c8ce364bb102ffa779ce5332e9fe4e221d613e805e1bfcd782f9e3f8dd2d7caa39a11de5df89703feb16086c20f7
-  data.tar.gz: a62dd755a2bf87f96ac17c920e9e350cabad4bfb8384bba4a96a5db90c71fcb8510ed1c2467717087824e6d0981c0e6670ff4ada99ea95101b3e61dec192d637
+  metadata.gz: 32b345fcc0ac56e25765f628c1ab8dd7dd03740e9a1a12bbcf5e13e9ce5078ef9ad57581f2b0a0f445f4d4b543559e01ceb50dd1a0dae86e7db5d35440b8e3c8
+  data.tar.gz: da9518b7381e61a16d7efef22e2d8d585b895b2e644820099403781c86ee9c7b541cf2ee00bad6cac7c40830764fd30aa841dd685dd9c63cb4ed227a1ed7ce8a

data/LICENSE.txt

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Abdelkader Boudih
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,214 @@
+# Noiseless
+
+Async-first search abstraction for Rails with multi-backend support (OpenSearch, Elasticsearch, Typesense, PostgreSQL).
+
+## Features
+
+- **Chainable DSL** — fluent query builder with runtime validation
+- **Multi-backend** — OpenSearch, Elasticsearch, Typesense, PostgreSQL adapters
+- **Async-first** — built on Ruby 3.4+ fiber scheduler with non-blocking I/O
+- **HTTP/2 connection pooling** — persistent connections via `Async::Pool`
+- **Rails integration** — Railtie with log subscriber and controller runtime tracking
+- **Lazy loading** — adapters loaded on-demand, test files excluded from production
+
+## Installation
+
+```ruby
+gem "noiseless"
+```
+
+`noiseless` is a Rails gem. It requires Ruby >= 3.4 and Rails >= 8.1.
+
+## Configuration
+
+Create `config/noiseless.yml`:
+
+```yaml
+development:
+  default: primary
+  connections:
+    primary:
+      adapter: elasticsearch
+      hosts:
+        - http://localhost:9201
+    opensearch:
+      adapter: open_search
+      hosts:
+        - http://localhost:9202
+    typesense:
+      adapter: typesense
+      hosts:
+        - http://localhost:8109
+    postgresql:
+      adapter: postgresql
+
+production:
+  default: primary
+  connections:
+    primary:
+      adapter: opensearch
+      hosts:
+        - <%= ENV['OPENSEARCH_URL'] %>
+    typesense:
+      adapter: typesense
+      hosts:
+        - <%= ENV['TYPESENSE_URL'] %>
+    postgresql:
+      adapter: postgresql
+```
+
+## Usage
+
+### Defining a Search
+
+```ruby
+class Company::Search < Noiseless::Model
+  index_name 'companies'
+
+  def by_name(name)
+    multi_match(name, [:name, :name_aliases])
+  end
+
+  def suppliers_only
+    filter(:company_type, 'supplier')
+  end
+end
+```
+
+### Executing Searches
+
+All `.execute` calls return `Async::Task` objects. Use `Sync` to wait for results, or use the `_sync` convenience methods:
+
+```ruby
+# Convenience method (recommended for simple cases)
+results = Company::Search.new.by_name('tech').execute_sync
+
+# Class-level convenience
+results = Company::Search.search_sync do |s|
+  s.match(:name, 'tech')
+  s.limit(10)
+end
+
+# Explicit Sync block
+results = Sync do
+  Company::Search.new
+    .by_name('technology')
+    .suppliers_only
+    .limit(20)
+    .execute
+    .wait
+end
+```
+
+### Concurrent Searches
+
+```ruby
+Async do |task|
+  companies_task = Company::Search.new.match(:name, 'tech').execute
+  products_task  = Product::Search.new.match(:name, 'tech').execute
+
+  companies = companies_task.wait
+  products  = products_task.wait
+end
+```
+
+For best performance, run independent searches concurrently within a single `Async` block rather than creating separate `Sync` blocks per search.
+
+### Advanced Queries
+
+```ruby
+results = Company::Search.new
+  .match(:name, 'electronics')
+  .filter(:status, 'active')
+  .geo_distance(:location, lat: 40.7128, lon: -74.0060, distance: '50km')
+  .sort(:created_at, :desc)
+  .paginate(page: 1, per_page: 10)
+  .execute_sync
+```
+
+### Rails Integration
+
+```ruby
+class CompaniesController < ApplicationController
+  def search
+    @results = Company::Search.new
+      .by_name(params[:q])
+      .limit(20)
+      .execute_sync
+
+    render json: @results
+  end
+end
+```
+
+## Testing
+
+Add to `test/test_helper.rb`:
+
+```ruby
+require 'noiseless/test_helper'
+require 'noiseless/test_case'
+```
+
+### With Noiseless::TestCase (automatic VCR cassettes)
+
+```ruby
+class CompanySearchTest < Noiseless::TestCase
+  def test_search_by_name
+    # Cassette auto-named: company_search/search_by_name
+    search = Company::Search.new.by_name('test')
+    assert_search_results(search)
+  end
+end
+```
+
+### With manual VCR control
+
+```ruby
+class CompanySearchTest < ActiveSupport::TestCase
+  include Noiseless::TestHelper
+
+  def test_custom_search
+    noiseless_cassette(record: :new_episodes) do
+      results = Company::Search.new.by_name('test').execute_sync
+      assert results.any?
+    end
+  end
+end
+```
+
+### Running Tests Locally
+
+```bash
+docker compose up -d postgres elasticsearch opensearch typesense
+bin/test
+```
+
+`bin/test` expects all four local services from `docker-compose.yml`, including PostgreSQL on `:5432`.
+Default ports match `docker-compose.yml`: PostgreSQL `:5432`, Elasticsearch `:9201`, OpenSearch `:9202`, Typesense `:8109`. Override via env vars:
+
+```bash
+ELASTICSEARCH_PORT=9200 OPENSEARCH_PORT=9201 TYPESENSE_PORT=8108 bin/test
+```
+
+For a release smoke test that does not require the dummy app or local services:
+
+```bash
+bundle exec rake release:check
+```
+
+## Debug Mode
+
+```ruby
+ENV['NOISELESS_VERBOSE'] = 'true'
+```
+
+## Contributing
+
+1. Follow Rails conventions for code organization
+2. Test helpers must remain separate from core functionality
+3. Add tests for new features using the provided test utilities
+
+## License
+
+BSD 3-Clause License — See [LICENSE.txt](LICENSE.txt)

data/lib/application_search.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Abstract base class for all search models
+class ApplicationSearch < Noiseless::Model
+  # Mark as abstract - concrete search models like Product::Search inherit from this
+  def self.abstract!
+    @abstract = true
+  end
+
+  def self.abstract?
+    @abstract == true
+  end
+
+  abstract!
+end

data/lib/noiseless/adapter.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require "async"
+require "json"
+require_relative "introspection"
+
+module Noiseless
+  class Adapter
+    include Instrumentation
+    include Introspection
+
+    def initialize(hosts: [], **connection_params)
+      @hosts = hosts
+      @connection_params = connection_params.dup
+      @connection_params.delete(:async)
+    end
+
+    def async_context?
+      true
+    end
+
+    # Convert AST to Hash/JSON before execution
+    def search(ast_node, model_class: nil, response_type: nil, **)
+      query_hash = ast_to_hash(ast_node)
+
+      Async do
+        raw_response = instrument(:search, indexes: ast_node.indexes, query: query_hash) do
+          execute_search(query_hash, indexes: ast_node.indexes, **)
+        end
+
+        ResponseFactory.create(
+          raw_response,
+          model_class: model_class,
+          response_type: response_type,
+          query_hash: query_hash
+        )
+      end
+    end
+
+    def bulk(actions, **)
+      Async do
+        instrument(:bulk, actions_count: actions.size) do
+          execute_bulk(actions, **)
+        end
+      end
+    end
+
+    def create_index(index_name, **)
+      Async do
+        instrument(:create_index, index: index_name) do
+          execute_create_index(index_name, **)
+        end
+      end
+    end
+
+    def delete_index(index_name, **)
+      Async do
+        instrument(:delete_index, index: index_name) do
+          execute_delete_index(index_name, **)
+        end
+      end
+    end
+
+    def index_exists?(index_name)
+      Async do
+        execute_index_exists?(index_name)
+      end
+    end
+
+    def index_document(index:, id:, document:, **)
+      Async do
+        instrument(:index_document, index: index, id: id) do
+          execute_index_document(index, id, document, **)
+        end
+      end
+    end
+
+    def update_document(index:, id:, changes:, **)
+      Async do
+        instrument(:update_document, index: index, id: id, changes_count: changes.size) do
+          execute_update_document(index, id, changes, **)
+        end
+      end
+    end
+
+    def delete_document(index:, id:, **)
+      Async do
+        instrument(:delete_document, index: index, id: id) do
+          execute_delete_document(index, id, **)
+        end
+      end
+    end
+
+    def document_exists?(index:, id:)
+      Async do
+        execute_document_exists?(index, id)
+      end
+    end
+
+    # Raw search method for backward compatibility
+    def search_raw(query_body, indexes: [], **)
+      Async do
+        instrument(:search, indexes: indexes, query: query_body) do
+          execute_search(query_body, indexes: indexes, **)
+        end
+      end
+    end
+
+    private
+
+    # Convert AST to Hash - override in subclasses for adapter-specific format
+    def ast_to_hash(ast_node)
+      result = {}
+
+      query_hash = build_query_hash(ast_node.bool)
+      result[:query] = query_hash unless query_hash.empty?
+
+      sort_hash = build_sort_hash(ast_node.sort)
+      result[:sort] = sort_hash unless sort_hash.empty?
+
+      # Handle search_after (cursor pagination) vs offset pagination
+      if ast_node.search_after
+        result[:search_after] = ast_node.search_after.values
+        result[:size] = ast_node.paginate&.per_page || 20
+      else
+        pagination = build_pagination_hash(ast_node.paginate)
+        result[:from] = pagination[:from]
+        result[:size] = pagination[:size]
+      end
+
+      # Field collapsing
+      result[:collapse] = build_collapse_hash(ast_node.collapse) if ast_node.collapse
+
+      # Aggregations
+      result[:aggs] = build_aggregations_hash(ast_node.aggregations) if ast_node.aggregations.any?
+
+      # Vector/kNN search (OpenSearch/Elasticsearch compatible)
+      result[:knn] = build_knn_query(ast_node.vector) if ast_node.vector_search?
+
+      # Hybrid search (combines text + vector with RRF or weighted scoring)
+      if ast_node.hybrid_search?
+        hybrid_config = build_hybrid_query(ast_node.hybrid)
+        result.merge!(hybrid_config)
+      end
+
+      # Search pipeline (OpenSearch only)
+      result[:search_pipeline] = ast_node.pipeline if ast_node.has_pipeline?
+
+      result
+    end
+
+    def build_knn_query(vector_node)
+      {
+        field: vector_node.field.to_s,
+        query_vector: vector_node.embedding,
+        k: vector_node.k,
+        num_candidates: vector_node.k * 10
+      }
+    end
+
+    # Build hybrid query using RRF (Reciprocal Rank Fusion) for OpenSearch/Elasticsearch
+    def build_hybrid_query(hybrid_node)
+      {
+        query: {
+          bool: {
+            should: [
+              {
+                match: {
+                  _all: hybrid_node.text_query
+                }
+              }
+            ]
+          }
+        },
+        knn: build_knn_query(hybrid_node.vector),
+        rank: {
+          rrf: {
+            window_size: hybrid_node.vector.k * 2
+          }
+        }
+      }
+    end
+
+    def build_query_hash(bool_node)
+      return {} if bool_node.must.empty? && bool_node.filter.empty?
+
+      must_queries = bool_node.must.filter_map { |node| build_must_clause(node) }
+
+      {
+        bool: {
+          must: must_queries,
+          filter: bool_node.filter.map { |f| { term: { f.field => f.value } } }
+        }.reject { |_, v| v.empty? }
+      }
+    end
+
+    def build_sort_hash(sort_nodes)
+      return [] if sort_nodes.empty?
+
+      sort_nodes.map { |s| { s.field => { order: s.direction } } }
+    end
+
+    def build_pagination_hash(paginate_node)
+      return { from: 0, size: 20 } unless paginate_node
+
+      {
+        from: (paginate_node.page - 1) * paginate_node.per_page,
+        size: paginate_node.per_page
+      }
+    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)
+      {
+        took: 1,
+        hits: {
+          total: { value: 0 },
+          hits: []
+        }
+      }
+    end
+
+    def execute_bulk(actions, **_opts)
+      {
+        items: actions.map { |_action| { index: { status: 201 } } }
+      }
+    end
+
+    def execute_create_index(_index_name, **_opts)
+      { acknowledged: true }
+    end
+
+    def execute_delete_index(_index_name, **_opts)
+      { acknowledged: true }
+    end
+
+    def execute_index_exists?(_index_name)
+      true
+    end
+
+    def execute_index_document(index, id, _document, **_opts)
+      { _index: index, _id: id, result: "created" }
+    end
+
+    def execute_update_document(index, id, _changes, **_opts)
+      { _index: index, _id: id, result: "updated" }
+    end
+
+    def execute_delete_document(index, id, **_opts)
+      { _index: index, _id: id, result: "deleted" }
+    end
+
+    def execute_document_exists?(_index, _id)
+      true
+    end
+
+    def build_must_clause(node)
+      case node
+      when AST::Match
+        { match: { node.field => node.value } }
+      when AST::MultiMatch
+        { multi_match: { query: node.query, fields: node.fields }.merge(node.options) }
+      when AST::CombinedFields
+        { combined_fields: { query: node.query, fields: node.fields }.merge(node.options) }
+      when AST::Wildcard
+        { wildcard: { node.field => node.value } }
+      when AST::Range
+        range_options = {
+          gte: node.gte,
+          lte: node.lte,
+          gt: node.gt,
+          lt: node.lt
+        }.compact
+        { range: { node.field => range_options } }
+      when AST::Prefix
+        { prefix: { node.field => node.value } }
+      else
+        node.to_hash
+      end
+    end
+
+    def build_collapse_hash(collapse_node)
+      result = { field: collapse_node.field }
+      result[:inner_hits] = collapse_node.inner_hits if collapse_node.inner_hits
+      if collapse_node.max_concurrent_group_searches
+        result[:max_concurrent_group_searches] =
+          collapse_node.max_concurrent_group_searches
+      end
+      result
+    end
+
+    def build_aggregations_hash(aggregations)
+      aggregations.each_with_object({}) do |agg, hash|
+        hash[agg.name] = build_single_aggregation(agg)
+      end
+    end
+
+    def build_single_aggregation(agg)
+      result = {}
+
+      # Build the aggregation type hash
+      agg_body = {}
+      agg_body[:field] = agg.field if agg.field
+      agg_body.merge!(agg.options)
+
+      result[agg.type] = agg_body
+
+      # Add sub-aggregations if any
+      result[:aggs] = build_aggregations_hash(agg.sub_aggregations) if agg.sub_aggregations.any?
+
+      result
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "execution_modules/elasticsearch_execution"
+
+module Noiseless
+  module Adapters
+    class Elasticsearch < Adapter
+      include ExecutionModules::ElasticsearchExecution
+
+      ClusterAPI = Adapters::ClusterAPI
+      IndicesAPI = Adapters::IndicesAPI
+
+      # Cluster health API - needed for Rails healthcheck
+      def cluster
+        @cluster ||= ClusterAPI.new(self)
+      end
+
+      # Indices API - needed for index management operations
+      def indices
+        @indices ||= IndicesAPI.new(self)
+      end
+
+      private
+
+      def default_port
+        ENV["ELASTICSEARCH_PORT"] || 9200
+      end
+    end
+  end
+end