search-engine-for-typesense 1.0.0

data/lib/search_engine/stale_rules.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Compile partition-aware stale cleanup rules into Typesense filter strings.
+  #
+  # Evaluates entries declared via the indexing DSL `stale ...` and returns a
+  # list of filter fragments or a merged OR expression suitable for delete-by
+  # or Relation.where. Resilient to errors in individual entries.
+  module StaleRules
+    module_function
+
+    # Check whether any stale configuration is defined for this model.
+    #
+    # @param klass [Class]
+    # @return [Boolean]
+    def defined_for?(klass)
+      entries = begin
+        klass.respond_to?(:stale_entries) ? Array(klass.stale_entries) : []
+      rescue StandardError
+        []
+      end
+      return true if entries.any?
+
+      false
+    rescue StandardError
+      false
+    end
+
+    # Build an Array of Typesense filter fragments from stale rules.
+    #
+    # @param klass [Class]
+    # @param partition [Object, nil]
+    # @return [Array<String>]
+    def compile_filters(klass, partition: nil)
+      entries = begin
+        klass.respond_to?(:stale_entries) ? Array(klass.stale_entries) : []
+      rescue StandardError
+        []
+      end
+
+      filters = []
+      filters.concat(build_scope_filters(klass, entries, partition: partition))
+      filters.concat(build_attribute_filters(klass, entries))
+      filters.concat(build_hash_filters(klass, entries))
+      filters.concat(build_raw_filters(klass, entries, partition: partition))
+
+      filters.compact!
+      filters.reject { |f| f.to_s.strip.empty? }
+    rescue StandardError
+      []
+    end
+
+    # Merge multiple filter fragments with OR semantics.
+    #
+    # @param filters [Array<String>]
+    # @return [String, nil]
+    def merge_filters(filters)
+      list = Array(filters).compact.reject { |f| f.to_s.strip.empty? }
+      return nil if list.empty?
+      return list.first if list.size == 1
+
+      list.map { |f| "(#{f})" }.join(' || ')
+    end
+
+    # --- helpers ------------------------------------------------------------
+
+    def build_scope_filters(klass, entries, partition: nil)
+      entries
+        .select { |entry| entry[:type] == :scope }
+        .map do |entry|
+          scope = entry[:name]
+          next unless klass.respond_to?(scope)
+
+          rel = invoke_scope(klass, scope, partition)
+          next unless defined?(SearchEngine::Relation) && rel.is_a?(SearchEngine::Relation)
+
+          rel.filter_params
+        end
+        .compact
+    rescue StandardError
+      []
+    end
+
+    def build_attribute_filters(klass, entries)
+      entries
+        .select { |entry| entry[:type] == :attribute }
+        .map do |entry|
+          attr = entry[:name]
+          val = entry[:value]
+          relation_for(klass, { attr => val })&.filter_params
+        end
+        .compact
+    rescue StandardError
+      []
+    end
+
+    def build_hash_filters(klass, entries)
+      entries
+        .select { |entry| entry[:type] == :hash }
+        .map { |entry| relation_for(klass, entry[:hash])&.filter_params }
+        .compact
+    rescue StandardError
+      []
+    end
+
+    def build_raw_filters(klass, entries, partition: nil)
+      raw = entries.select { |entry| %i[filter relation block].include?(entry[:type]) }
+      Array(
+        raw.flat_map do |entry|
+          case entry[:type]
+          when :filter then entry[:value]
+          when :relation then entry[:relation]&.filter_params
+          when :block then evaluate_block_entry(klass, entry[:block], partition: partition)
+          end
+        end
+      ).compact
+    rescue StandardError
+      []
+    end
+
+    def relation_for(klass, hash)
+      SearchEngine::Relation.new(klass).where(hash)
+    end
+
+    def evaluate_block_entry(klass, block, partition: nil)
+      params = block.parameters
+      result = if params.any? { |(kind, name)| %i[key keyreq].include?(kind) && name == :partition }
+                 klass.instance_exec(partition: partition, &block)
+               elsif block.arity.positive?
+                 klass.instance_exec(partition, &block)
+               else
+                 klass.instance_exec(&block)
+               end
+
+      case result
+      when String then result
+      when Hash then relation_for(klass, result)&.filter_params
+      when SearchEngine::Relation then result.filter_params
+      end
+    rescue StandardError
+      nil
+    end
+
+    def invoke_scope(klass, scope, partition)
+      method_obj = klass.method(scope)
+      params = method_obj.parameters
+      if params.empty?
+        klass.public_send(scope)
+      elsif params.any? { |(kind, name)| %i[key keyreq].include?(kind) && %i[partition _partition].include?(name) }
+        klass.public_send(scope, partition: partition)
+      elsif params.first && %i[req opt].include?(params.first.first)
+        klass.public_send(scope, partition)
+      else
+        klass.public_send(scope)
+      end
+    rescue ArgumentError
+      klass.public_send(scope)
+    end
+  end
+end

data/lib/search_engine/test/minitest_assertions.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  module Test
+    # Minitest assertion helpers for SearchEngine event testing.
+    #
+    # Include this module in your test case to use `assert_emits` and `capture_events`.
+    module MinitestAssertions
+      # Assert that a named event is emitted within the provided block.
+      # Optional payload matcher may be a Hash, Proc, or object responding to :matches?.
+      # @param name [String, Regexp]
+      # @param payload [Object, nil]
+      # @yield block to execute
+      def assert_emits(name, payload: nil, &block)
+        captured = SearchEngine::Test.capture_events(/^search_engine\./, &block)
+        matches = filter_by_name(captured, name)
+        refute_empty(matches, "expected block to emit #{name.inspect}, but none matched")
+        if payload
+          ok = matches.any? { |ev| payload_matches?(ev[:payload], payload) }
+          detail = matches.map { |e| e[:payload] }.inspect
+          assert(ok, "expected an event payload matching #{payload.inspect}, got: #{detail}")
+        end
+        true
+      end
+
+      # Capture events emitted within the block and return the Array.
+      # @yield block to execute
+      # @return [Array<Hash>]
+      def capture_events(&block)
+        SearchEngine::Test.capture_events(/^search_engine\./, &block)
+      end
+
+      private
+
+      def filter_by_name(events, name)
+        case name
+        when Regexp
+          events.select { |ev| ev[:name] =~ name }
+        else
+          events.select { |ev| ev[:name].to_s == name.to_s }
+        end
+      end
+
+      def payload_matches?(payload, matcher)
+        if matcher.respond_to?(:matches?)
+          matcher.matches?(payload)
+        elsif matcher.is_a?(Proc)
+          matcher.call(payload)
+        else
+          payload == matcher
+        end
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/search_engine/test/offline_client.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# rubocop:disable Lint/UnusedMethodArgument
+
+require 'search_engine/result'
+
+module SearchEngine
+  module Test
+    # No-op client that mirrors SearchEngine::Client without network I/O.
+    # Returns safe empty/ok responses for all operations.
+    class OfflineClient
+      SUCCESS_JSONL = "{\"success\":true}\n"
+      EMPTY_SEARCH = { 'hits' => [], 'found' => 0, 'out_of' => 0 }.freeze
+
+      def search(collection:, params:, url_opts: {})
+        SearchEngine::Result.new(EMPTY_SEARCH, klass: nil)
+      end
+
+      def multi_search(searches:, url_opts: {})
+        { 'results' => [] }
+      end
+
+      def import_documents(collection:, jsonl:, action: :upsert)
+        SUCCESS_JSONL
+      end
+
+      def delete_documents_by_filter(collection:, filter_by:, timeout_ms: nil)
+        { 'num_deleted' => 0 }
+      end
+
+      def delete_document(collection:, id:, timeout_ms: nil)
+        {}
+      end
+
+      def retrieve_document(collection:, id:, timeout_ms: nil)
+        nil
+      end
+
+      def update_document(collection:, id:, fields:, timeout_ms: nil)
+        fields.merge('id' => id.to_s)
+      end
+
+      def update_documents_by_filter(collection:, filter_by:, fields:, timeout_ms: nil)
+        { 'num_updated' => 0 }
+      end
+
+      def create_document(collection:, document:)
+        document
+      end
+
+      def resolve_alias(logical_name, timeout_ms: nil)
+        nil
+      end
+
+      def retrieve_collection_schema(collection_name, timeout_ms: nil)
+        nil
+      end
+
+      def upsert_alias(alias_name, physical_name)
+        {}
+      end
+
+      def create_collection(schema)
+        schema
+      end
+
+      def update_collection(name, schema)
+        schema
+      end
+
+      def delete_collection(name, timeout_ms: nil)
+        {}
+      end
+
+      def list_collections(timeout_ms: nil)
+        []
+      end
+
+      def health
+        { 'ok' => true }
+      end
+
+      def metrics
+        {}
+      end
+
+      def stats
+        {}
+      end
+
+      def list_api_keys
+        []
+      end
+
+      def synonyms_upsert(collection:, id:, terms:)
+        {}
+      end
+
+      def synonyms_list(collection:)
+        []
+      end
+
+      def synonyms_get(collection:, id:)
+        nil
+      end
+
+      def synonyms_delete(collection:, id:)
+        {}
+      end
+
+      def stopwords_upsert(collection:, id:, terms:)
+        {}
+      end
+
+      def stopwords_list(collection:)
+        []
+      end
+
+      def stopwords_get(collection:, id:)
+        nil
+      end
+
+      def stopwords_delete(collection:, id:)
+        {}
+      end
+
+      def clear_cache
+        { 'success' => true }
+      end
+    end
+  end
+end
+
+# rubocop:enable Lint/UnusedMethodArgument

data/lib/search_engine/test/rspec_matchers.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+begin
+  require 'rspec/expectations'
+rescue LoadError
+  # RSpec not available; file remains loadable but inert in non-RSpec contexts
+end
+
+if defined?(RSpec)
+  module SearchEngine
+    # Test utilities namespace. Contains RSpec matchers for event assertions.
+    module Test
+      # Internal helpers to keep matcher block concise
+      def self.emit_event_filter_by_name(events, name)
+        case name
+        when Regexp then events.select { |ev| ev[:name] =~ name }
+        else events.select { |ev| ev[:name].to_s == name.to_s }
+        end
+      end
+
+      def self.emit_event_payload_matches?(payload, matcher)
+        if matcher.respond_to?(:matches?)
+          matcher.matches?(payload)
+        elsif matcher.is_a?(Proc)
+          matcher.call(payload)
+        else
+          payload == matcher
+        end
+      rescue StandardError
+        false
+      end
+
+      def self.emit_event_redact_for_message(payload)
+        SearchEngine::Observability.redact(payload)
+      rescue StandardError
+        payload
+      end
+
+      def self.emit_event_failure_message(expected_name, payload_matcher, events)
+        lines = []
+        lines << "expected block to emit #{expected_name.inspect}"
+        lines << "with payload matching: #{payload_matcher.inspect}" if payload_matcher
+        if events && !events.empty?
+          samples = events.take(3).map { |ev| emit_event_redact_for_message(ev[:payload]) }
+          lines << "but got events: #{samples.inspect}"
+        else
+          lines << 'but no matching events were emitted'
+        end
+        lines.join("\n")
+      end
+
+      # RSpec matcher to assert that an event is emitted during a block.
+      # Usage:
+      #   expect { rel.to_a }.to emit_event('search_engine.search').with(hash_including(collection: 'products'))
+      RSpec::Matchers.define :emit_event do |expected_name|
+        supports_block_expectations
+
+        chain :with do |payload_matcher|
+          @payload_matcher = payload_matcher
+        end
+
+        match do |probe|
+          captured = SearchEngine::Test.capture_events(/^search_engine\./) { probe.call }
+          @events = SearchEngine::Test.emit_event_filter_by_name(captured, expected_name)
+          return false if @events.empty?
+          return true unless @payload_matcher
+
+          @events.any? { |ev| SearchEngine::Test.emit_event_payload_matches?(ev[:payload], @payload_matcher) }
+        end
+
+        failure_message do
+          SearchEngine::Test.emit_event_failure_message(expected_name, @payload_matcher, @events)
+        end
+      end
+    end
+  end
+end

data/lib/search_engine/test/stub_client.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'monitor'
+require 'json'
+
+module SearchEngine
+  module Test
+    # Test-only programmable stub client that mimics the public surface of
+    # SearchEngine::Client for search and multi_search. It never performs I/O.
+    #
+    # Thread-safe: queues and captures are guarded by a Monitor.
+    # Redaction: bodies and captured payloads are redacted for safe inspection.
+    #
+    # Usage:
+    #   stub = SearchEngine::Test::StubClient.new
+    #   stub.enqueue_response(:search, { 'hits' => [], 'found' => 0, 'out_of' => 0 })
+    #   SearchEngine.configure { |c| c.client = stub }
+    #
+    # Queued responses are FIFO. You may enqueue Exceptions to simulate errors
+    # or Procs that receive the captured request and return a response.
+    #
+    # @since M8
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/testing
+    class StubClient
+      Call = Struct.new(
+        :timestamp,
+        :correlation_id,
+        :verb,
+        :url,
+        :body,
+        :url_opts,
+        :redacted_body,
+        :redacted?,
+        keyword_init: true
+      )
+
+      def initialize
+        @lock = Monitor.new
+        @queues = { search: [], multi_search: [] }
+        @calls = { search: [], multi_search: [] }
+      end
+
+      # Enqueue a response for a given method. Accepts a Hash, Exception, or Proc.
+      # @param method [Symbol] :search or :multi_search
+      # @param value [Hash, Exception, Proc]
+      # @return [void]
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/testing#quick-start
+      def enqueue_response(method, value)
+        @lock.synchronize do
+          queue_for(method) << value
+        end
+      end
+
+      # Reset all internal state (queues and captures).
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/testing#parallel-test-safety
+      def reset!
+        @lock.synchronize do
+          @queues.each_value(&:clear)
+          @calls.each_value(&:clear)
+        end
+      end
+
+      # Return captured calls for search.
+      # @return [Array<Call>]
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/testing
+      def search_calls
+        @lock.synchronize { @calls[:search].dup }
+      end
+
+      # Return captured calls for multi_search.
+      # @return [Array<Call>]
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/testing
+      def multi_search_calls
+        @lock.synchronize { @calls[:multi_search].dup }
+      end
+
+      # All calls in chronological order.
+      # @return [Array<Call>]
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/testing
+      def all_calls
+        @lock.synchronize { (@calls[:search] + @calls[:multi_search]).sort_by(&:timestamp) }
+      end
+
+      # Public API: single search. Mirrors Client#search arity. Returns Result-like object.
+      # @param collection [String]
+      # @param params [Hash]
+      # @param url_opts [Hash]
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/testing
+      def search(collection:, params:, url_opts: {})
+        unless collection.is_a?(String) && !collection.strip.empty?
+          raise ArgumentError, 'collection must be a non-empty String'
+        end
+
+        params_obj = SearchEngine::CompiledParams.from(params)
+        params_hash = params_obj.to_h
+
+        entry = capture(:search, url: compiled_url(collection), params: params_hash, url_opts: url_opts)
+        payload = dequeue_or_default(:search, entry)
+        wrap_single(payload)
+      end
+
+      # Public API: multi search. Mirrors top-level helper client usage: returns raw Hash from Typesense.
+      # @param searches [Array<Hash>]
+      # @param url_opts [Hash]
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/testing
+      def multi_search(searches:, url_opts: {})
+        unless searches.is_a?(Array) && searches.all? { |h| h.is_a?(Hash) }
+          raise ArgumentError, 'searches must be an Array of Hashes'
+        end
+
+        # Record a synthetic URL for multi endpoint; individual bodies are not posted here
+        entry = capture(:multi_search, url: compiled_multi_url, params: searches, url_opts: url_opts)
+        dequeue_or_default(:multi_search, entry).tap do |raw|
+          return raw
+        end
+      end
+
+      private
+
+      def dequeue_or_default(method, entry)
+        val = @lock.synchronize { queue_for(method).shift }
+        case val
+        when nil
+          default_payload(method)
+        when Proc
+          val.call(entry)
+        when Exception
+          raise val
+        else
+          val
+        end
+      end
+
+      def default_payload(method)
+        if method == :search
+          { 'hits' => [], 'found' => 0, 'out_of' => 0 }
+        else
+          { 'results' => [] }
+        end
+      end
+
+      def queue_for(method)
+        q = @queues[method]
+        raise ArgumentError, "unknown method: #{method.inspect}" unless q
+
+        q
+      end
+
+      def compiled_url(collection)
+        cfg = SearchEngine.config
+        proto = cfg.protocol.to_s.strip.presence
+        base = [proto, "#{cfg.host}:#{cfg.port}"].compact.join('://')
+        "#{base}/collections/#{collection}/documents/search"
+      end
+
+      def compiled_multi_url
+        cfg = SearchEngine.config
+        proto = cfg.protocol.to_s.strip.presence
+        base = [proto, "#{cfg.host}:#{cfg.port}"].compact.join('://')
+        "#{base}/multi_search"
+      end
+
+      def capture(method, url:, params:, url_opts: {})
+        redacted = begin
+          SearchEngine::Observability.redact(params)
+        rescue StandardError
+          params
+        end
+        corr = begin
+          SearchEngine::Instrumentation.current_correlation_id
+        rescue StandardError
+          nil
+        end
+        entry = Call.new(
+          timestamp: SearchEngine::Instrumentation.monotonic_ms,
+          correlation_id: corr,
+          verb: method,
+          url: url,
+          body: params,
+          url_opts: SearchEngine::Observability.filtered_url_opts(url_opts),
+          redacted_body: redacted,
+          redacted?: true
+        )
+        @lock.synchronize { @calls[method] << entry }
+        entry
+      end
+
+      def wrap_single(payload)
+        # Mirror Client#search returning SearchEngine::Result
+        SearchEngine::Result.new(payload, klass: nil)
+      end
+    end
+  end
+end

data/lib/search_engine/test.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Test-only utilities for offline execution and assertions.
+  #
+  # Provides:
+  # - SearchEngine::Test::StubClient — a programmable stub client that captures requests
+  # - SearchEngine::Test::OfflineClient — a no-op client for test/offline mode
+  # - Event capture helpers (SearchEngine::Test.capture_events)
+  # - Framework adapters (RSpec matcher `emit_event`, Minitest assertions)
+  #
+  # These helpers are allocation-light, thread-safe, and never perform network I/O.
+  #
+  # @since M8
+  # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/testing
+  module Test
+    class << self
+      # Subscribe to `search_engine.*` for the duration of the block and return captured events.
+      # Each event is a Hash: { name:, payload:, time:, duration: }
+      # Payloads are redacted for safety.
+      # @param name [String, Regexp, nil]
+      # @yield block within which events are captured
+      # @return [Array<Hash>]
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/testing#event-assertions
+      def capture_events(name = nil)
+        require 'active_support/notifications'
+        pattern = name.is_a?(Regexp) ? name : /^search_engine\./
+        captured = []
+        handle = ActiveSupport::Notifications.subscribe(pattern) do |*args|
+          ev = ActiveSupport::Notifications::Event.new(*args)
+          payload = safe_payload(ev.payload)
+          captured << { name: ev.name, payload: payload, time: ev.time, duration: ev.duration }
+        end
+        yield
+        captured
+      ensure
+        ActiveSupport::Notifications.unsubscribe(handle) if defined?(handle)
+      end
+
+      # Internal: apply redaction once more to be safe
+      def safe_payload(payload)
+        p = payload.dup
+        p[:params] = SearchEngine::Observability.redact(p[:params]) if p.key?(:params)
+        p[:params_preview] = SearchEngine::Observability.redact(p[:params_preview]) if p.key?(:params_preview)
+        p
+      rescue StandardError
+        payload
+      end
+    end
+  end
+end
+
+require 'search_engine/test/stub_client'
+require 'search_engine/test/offline_client'
+# Framework adapters are optional; require only when present
+begin
+  require 'search_engine/test/rspec_matchers'
+rescue LoadError
+  # no-op
+end
+begin
+  require 'search_engine/test/minitest_assertions'
+rescue LoadError
+  # no-op
+end

data/lib/search_engine/test_autoload.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Trivial module used to assert lib/ autoload works as expected.
+  module TestAutoload
+    NAME = 'SearchEngine::TestAutoload'
+  end
+end