search-engine-for-typesense 1.0.0

data/lib/search_engine/cli/support.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'tmpdir'
+require 'pathname'
+
+module SearchEngine
+  module Cli
+    # Small, pure helpers shared by CLI tasks/commands.
+    #
+    # Side‑effect free and safe to require in task context.
+    # All helpers return strings/values; callers are responsible for printing.
+    module Support
+      # Common UI constants (kept minimal to avoid behavior drift)
+      DOCS_ROOT = 'docs/'
+      SEP       = ' - '
+      BULLET    = '-'
+      CHECK     = '✓'
+      WARN      = '⚠'
+      CROSS     = '✖'
+
+      module_function
+
+      # --- JSON helpers ------------------------------------------------------
+      # @param str [Object]
+      # @return [Boolean]
+      def json_string?(str)
+        s = str.to_s.strip
+        return false if s.empty?
+
+        JSON.parse(s)
+        true
+      rescue StandardError
+        false
+      end
+
+      # Parse JSON safely.
+      # @param str [Object]
+      # @return [Object, nil] parsed JSON or nil when invalid
+      def parse_json_safe(str)
+        s = str.to_s
+        return nil if s.strip.empty?
+
+        JSON.parse(s)
+      rescue StandardError
+        nil
+      end
+
+      # Parse JSON or return original string, without raising.
+      # @param str [Object]
+      # @return [Object] parsed value or the original string
+      def parse_json_or_string(str)
+        parsed = parse_json_safe(str)
+        return parsed unless parsed.nil?
+
+        str.to_s
+      end
+
+      # Whether JSON output is requested via FORMAT=json.
+      # @return [Boolean]
+      def json_output?
+        (ENV['FORMAT'] || '').to_s.strip.downcase == 'json'
+      end
+
+      # Returns true when ENV[name] is a truthy flag (1/true/yes/on).
+      # @param name [String]
+      # @return [Boolean]
+      def boolean_env?(name)
+        truthy_env?(ENV[name])
+      end
+
+      # --- Console formatting ------------------------------------------------
+      # Respect NO_COLOR and TTY.
+      # @return [Boolean]
+      def color?
+        no_color = ENV['NO_COLOR']
+        return false if truthy_env?(no_color)
+
+        $stdout.respond_to?(:tty?) ? $stdout.tty? : false
+      end
+
+      # Whether emoji are enabled (disabled via NO_EMOJI=1).
+      # @return [Boolean]
+      def emoji?
+        return false if truthy_env?(ENV['NO_EMOJI'])
+
+        true
+      end
+
+      # Heading formatter (no decoration by default to preserve existing output).
+      # @param text [String]
+      # @return [String]
+      def fmt_heading(text)
+        text.to_s
+      end
+
+      # Bullet line formatter.
+      # @param text [String]
+      # @return [String]
+      def fmt_bullet(text)
+        "#{BULLET} #{text}"
+      end
+
+      # Key/Value formatter (key: value)
+      # @param key [String]
+      # @param value [Object]
+      # @return [String]
+      def fmt_kv(key, value)
+        "#{key}: #{value}"
+      end
+
+      # Green success line.
+      # @param text [String]
+      # @return [String]
+      def fmt_ok(text)
+        base = emoji? ? "#{CHECK} #{text}" : "OK #{text}"
+        color? ? colorize(base, 32) : base
+      end
+
+      # Yellow warning line.
+      # @param text [String]
+      # @return [String]
+      def fmt_warn(text)
+        base = emoji? ? "#{WARN} #{text}" : "WARN #{text}"
+        color? ? colorize(base, 33) : base
+      end
+
+      # Red error line.
+      # @param text [String]
+      # @return [String]
+      def fmt_err(text)
+        base = emoji? ? "#{CROSS} #{text}" : "ERROR #{text}"
+        color? ? colorize(base, 31) : base
+      end
+
+      # Simple text wrap (hard break by width).
+      # @param text [String]
+      # @param width [Integer]
+      # @return [String]
+      def wrap(text, width: 80)
+        s = text.to_s
+        return s if width.to_i <= 0
+
+        lines = []
+        s.split(/\r?\n/).each do |line|
+          lines << line.slice!(0, width) while line.length > width
+          lines << line
+        end
+        lines.join("\n")
+      end
+
+      # Indent text by level (2 spaces per level by default).
+      # @param text [String]
+      # @param level [Integer]
+      # @param spaces [Integer]
+      # @return [String]
+      def indent(text, level: 1, spaces: 2)
+        pad = ' ' * (level.to_i * spaces.to_i)
+        text.to_s.split(/\r?\n/).map { |l| pad + l }.join("\n")
+      end
+
+      # --- Path helpers ------------------------------------------------------
+      # Expand a path (supporting ~).
+      # @param path [String]
+      # @return [String]
+      def expand(path)
+        File.expand_path(path.to_s)
+      end
+
+      # Render a relative path from base (defaults to Dir.pwd).
+      # @param path [String]
+      # @param base [String]
+      # @return [String]
+      def rel(path, base: Dir.pwd)
+        p = Pathname.new(File.expand_path(path.to_s))
+        b = Pathname.new(File.expand_path(base.to_s))
+        p.relative_path_from(b).to_s
+      rescue ArgumentError
+        p.to_s
+      end
+
+      # Safe read file contents; returns nil if missing/unreadable.
+      # @param path [String]
+      # @return [String, nil]
+      def safe_read(path)
+        p = path.to_s
+        return nil unless File.file?(p)
+
+        File.read(p)
+      rescue StandardError
+        nil
+      end
+
+      # Generate a tmp file path (not created).
+      # @param prefix [String]
+      # @return [String]
+      def tmp_path(prefix: 'se')
+        t = Time.now.utc.strftime('%Y%m%d%H%M%S')
+        rand_s = rand(36 ** 6).to_s(36)
+        File.join(Dir.tmpdir, "search_engine-#{prefix}-#{t}-#{rand_s}")
+      end
+
+      # --- Internals ---------------------------------------------------------
+      def colorize(text, code)
+        "\e[#{code}m#{text}\e[0m"
+      end
+      private_class_method :colorize
+
+      def truthy_env?(val)
+        return false if val.nil?
+
+        %w[1 true yes on].include?(val.to_s.strip.downcase)
+      end
+      private_class_method :truthy_env?
+    end
+  end
+end

data/lib/search_engine/cli.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'search_engine/cli/support'
+
+module SearchEngine
+  # Internal helpers for operator-facing CLI/Rake tasks.
+  #
+  # This module is intentionally minimal and only used by task definitions
+  # located under `lib/tasks/search_engine.rake`. It avoids changing the
+  # library require graph by being required from the Rake file.
+  module Cli
+    class << self
+      # Resolve a collection argument into a model class.
+      #
+      # Attempts to constantize when the input looks like a class name; falls back
+      # to the registry via {SearchEngine.collection_for} for logical identifiers.
+      #
+      # @param arg [#to_s] collection argument (e.g., "SearchEngine::Product" or "products")
+      # @return [Class] subclass of {SearchEngine::Base}
+      # @raise [ArgumentError] when resolution fails
+      def resolve_collection!(arg)
+        input = arg.to_s
+        raise ArgumentError, 'collection argument required' if input.strip.empty?
+
+        klass = try_constantize(input)
+        klass ||= safe_collection_for(input)
+
+        unless klass.ancestors.include?(SearchEngine::Base)
+          raise ArgumentError, "#{klass.name} must inherit from SearchEngine::Base"
+        end
+
+        klass
+      end
+
+      # Parse a partition argument into a typed value.
+      #
+      # Numeric strings are converted to Integer; blank values return nil.
+      # Any other value is returned as-is (String).
+      #
+      # @param arg [Object]
+      # @return [Integer, String, nil]
+      def parse_partition(arg)
+        return nil if arg.nil?
+
+        str = arg.to_s
+        return nil if str.strip.empty? || str.strip.casecmp('nil').zero?
+
+        return Integer(str) if str.match?(/\A-?\d+\z/)
+
+        str
+      rescue ArgumentError
+        str
+      end
+
+      # Run a task with small, structured instrumentation.
+      #
+      # Emits three events when ActiveSupport::Notifications is available:
+      # - `search_engine.cli.started`
+      # - `search_engine.cli.finished`
+      # - `search_engine.cli.error`
+      #
+      # @param task [String] task name (e.g., "schema:diff")
+      # @param payload [Hash] small JSON-safe payload (e.g., { collection: "products" })
+      # @yield executes the task body
+      # @return [Object] the block's return value
+      def with_task_instrumentation(task, payload = {})
+        started = monotonic_ms
+        instrument('search_engine.cli.started', payload.merge(task: task))
+        result = yield
+        duration = (monotonic_ms - started).round(1)
+        instrument('search_engine.cli.finished', payload.merge(task: task, duration_ms: duration, status: 'ok'))
+        result
+      rescue StandardError => error
+        duration = (monotonic_ms - started).round(1)
+        instrument(
+          'search_engine.cli.error',
+          payload.merge(task: task, duration_ms: duration, status: 'error', error_class: error.class.name,
+                        message_truncated: error.message.to_s[0, 200]
+          )
+        )
+        raise
+      end
+
+      # Resolve the effective dispatch mode from ENV override or config.
+      # @param env_value [String, Symbol, nil]
+      # @return [Symbol] :inline or :active_job (falls back to :inline if AJ unavailable)
+      def resolve_dispatch_mode(env_value)
+        val = (env_value || ENV['DISPATCH'] || SearchEngine.config.indexer.dispatch || :inline).to_s.downcase
+        case val
+        when 'active_job', 'activejob', 'aj'
+          return :active_job if defined?(::ActiveJob::Base)
+        end
+        :inline
+      end
+
+      # Return true when ENV[name] is a truthy flag (1/true/yes/on).
+      # @param name [String]
+      # @return [Boolean]
+      def boolean_env?(name)
+        SearchEngine::Cli::Support.boolean_env?(name)
+      end
+
+      # Whether JSON output is requested via FORMAT=json.
+      # @return [Boolean]
+      def json_output?
+        SearchEngine::Cli::Support.json_output?
+      end
+
+      # Build an Enumerator that yields a single mapped documents batch for dry-run preview.
+      #
+      # @param klass [Class]
+      # @param partition [Object, nil]
+      # @return [Enumerable<Array<Hash>>>]
+      # @raise [ArgumentError] when mapper/source is missing
+      def docs_enum_for_first_batch(klass, partition)
+        mapper = SearchEngine::Mapper.for(klass)
+        raise ArgumentError, "mapper is not defined for #{klass.name}" unless mapper
+
+        rows_enum = rows_enumerator_for(klass, partition)
+        first_rows = next_from_enum(rows_enum)
+        first_rows ||= []
+
+        docs, _report = mapper.map_batch!(first_rows, batch_index: 0)
+        [docs]
+      end
+
+      # Resolve the physical collection name to import into, mirroring Indexer semantics.
+      #
+      # @param klass [Class]
+      # @param partition [Object, nil]
+      # @param into [String, nil]
+      # @return [String]
+      def resolve_into!(klass, partition: nil, into: nil)
+        return into if into && !into.to_s.strip.empty?
+
+        resolver = SearchEngine.config.partitioning&.default_into_resolver
+        if resolver.respond_to?(:arity)
+          case resolver.arity
+          when 1
+            val = resolver.call(klass)
+            return val if val && !val.to_s.strip.empty?
+          when 2, -1
+            val = resolver.call(klass, partition)
+            return val if val && !val.to_s.strip.empty?
+          end
+        elsif resolver
+          val = resolver.call(klass)
+          return val if val && !val.to_s.strip.empty?
+        end
+
+        # Fallback to logical name (alias)
+        if klass.respond_to?(:collection)
+          klass.collection.to_s
+        else
+          klass.name.to_s
+        end
+      end
+
+      # Enumerate partitions if DSL is present; otherwise a single nil partition.
+      # @param klass [Class]
+      # @return [Enumerable]
+      def partitions_for(klass)
+        compiled = SearchEngine::Partitioner.for(klass)
+        return [nil] unless compiled
+
+        compiled.partitions
+      end
+
+      private
+
+      def try_constantize(input)
+        return nil unless looks_like_constant?(input)
+
+        Object.const_get(input)
+      rescue NameError
+        nil
+      end
+
+      def looks_like_constant?(str)
+        str.include?('::') || str[0] =~ /[A-Z]/
+      end
+
+      def safe_collection_for(name)
+        SearchEngine.collection_for(name)
+      rescue ArgumentError
+        raise ArgumentError,
+              "Unknown collection '#{name}'. Provide a fully qualified class name or a registered collection."
+      end
+
+      def rows_enumerator_for(klass, partition)
+        compiled_partitioner = SearchEngine::Partitioner.for(klass)
+        return compiled_partitioner.partition_fetch_enum(partition) if compiled_partitioner
+
+        dsl = klass.instance_variable_get(:@__mapper_dsl__) if klass.instance_variable_defined?(:@__mapper_dsl__)
+        source_def = dsl && dsl[:source]
+        unless source_def
+          raise ArgumentError, 'No partition_fetch defined and no source adapter provided. Define one in the DSL.'
+        end
+
+        adapter = SearchEngine::Sources.build(source_def[:type], **(source_def[:options] || {}), &source_def[:block])
+        adapter.each_batch(partition: partition)
+      end
+
+      def next_from_enum(enum)
+        return enum.first if enum.respond_to?(:first)
+
+        e = enum.to_enum
+        e.next
+      rescue StopIteration
+        nil
+      end
+
+      def instrument(event, payload)
+        SearchEngine::Instrumentation.instrument(event, payload) {}
+      end
+
+      def monotonic_ms
+        SearchEngine::Instrumentation.monotonic_ms
+      end
+    end
+  end
+end

data/lib/search_engine/client/http_adapter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  class Client
+    # HttpAdapter is a minimal transport wrapper around the injected Typesense::Client.
+    #
+    # Provides a very small surface to execute normalized requests produced by
+    # {SearchEngine::Client::RequestBuilder}, delegating to the official Typesense
+    # client without re-implementing low-level HTTP. It stays transport-only and
+    # does not parse or coerce responses beyond returning a simple Response struct.
+    #
+    # @see SearchEngine::Client::RequestBuilder
+    # @see `https://typesense.org/docs/latest/api/`
+    class HttpAdapter
+      Response = Struct.new(:status, :headers, :body, keyword_init: true)
+
+      TYPESENSE_API_KEY_HEADER = 'X-TYPESENSE-API-KEY'
+
+      # Initialize with an injected Typesense client instance.
+      # @param typesense_client [Object] an instance compatible with Typesense::Client
+      # @return [void]
+      def initialize(typesense_client)
+        @typesense = typesense_client
+      end
+
+      # Execute a normalized request produced by {SearchEngine::Client::RequestBuilder}.
+      #
+      # Delegates to the upstream Typesense client where possible, returning a
+      # transport-level {Response}. This adapter does not perform parsing or
+      # symbolization and intentionally exposes the raw upstream value in
+      # {Response#body}.
+      #
+      # Supported forms (current usage):
+      # - POST `/collections/:collection/documents/search` (with `common_params`)
+      #
+      # @param request [SearchEngine::Client::RequestBuilder::Request] normalized request
+      # @return [Response] response wrapper with status, headers and raw body
+      # @raise [ArgumentError] when the request path is not supported by this adapter
+      # @see `https://typesense.org/docs/latest/api/documents.html#search-document`
+      def perform(request)
+        method = request.http_method.to_sym
+        path = request.path.to_s
+        if method == :post && path.match?(%r{\A/collections/[^/]+/documents/search\z})
+          collection = path.split('/')[2]
+          docs = @typesense.collections[collection].documents
+          begin
+            params = docs.method(:search).parameters
+            supports_common = params.any? { |(kind, _)| %i[key keyreq keyrest].include?(kind) }
+          rescue StandardError
+            supports_common = false
+          end
+          raw = supports_common ? docs.search(request.body, common_params: request.params) : docs.search(request.body)
+          # The official client returns parsed JSON (Hash). No headers/status exposed here.
+          return Response.new(status: 200, headers: {}, body: raw)
+        end
+
+        # Fallback: attempt a generic call via low-level typesense endpoint access if available.
+        # This keeps adapter permissive for future endpoints without adding Faraday here.
+        raise ArgumentError, "Unsupported request path for adapter: #{request.method} #{request.path}"
+      end
+    end
+  end
+end

data/lib/search_engine/client/request_builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  class Client
+    # RequestBuilder maps compiled params to concrete Typesense requests.
+    # It has no network concerns; it only assembles the request object.
+    #
+    # Produces a normalized {Request} that can be executed by
+    # {SearchEngine::Client::HttpAdapter} or directly by the client methods.
+    # Sanitizes internal-only keys before encoding to ensure the payload is
+    # compatible with the Typesense API.
+    #
+    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/client`
+    # @see `https://typesense.org/docs/latest/api/`
+    class RequestBuilder
+      # Normalized request container used by the transport adapter.
+      # @!attribute http_method [Symbol] one of :get, :post, :put, :delete
+      # @!attribute path [String] absolute path (no host), e.g. "/collections/products/documents/search"
+      # @!attribute params [Hash] URL/common params (e.g., { use_cache:, cache_ttl: })
+      # @!attribute headers [Hash] per-request headers (adapter may add global ones)
+      # @!attribute body [Hash, nil] JSON body as a Ruby Hash
+      # @!attribute body_json [String, nil] Deterministic JSON representation of body
+      Request = Struct.new(:http_method, :path, :params, :headers, :body, :body_json, keyword_init: true)
+
+      COLLECTIONS_PREFIX = '/collections/'
+      DOCUMENTS_SEARCH_SUFFIX = '/documents/search'
+      # Additional endpoint fragments for internal reuse
+      COLLECTIONS_ROOT = '/collections'
+      DOCUMENTS_SUFFIX = '/documents'
+      DOCUMENTS_IMPORT_SUFFIX = '/documents/import'
+      ALIASES_PREFIX = '/aliases/'
+      SYNONYMS_SUFFIX = '/synonyms'
+      SYNONYMS_PREFIX = '/synonyms/'
+      STOPWORDS_SUFFIX = '/stopwords'
+      STOPWORDS_PREFIX = '/stopwords/'
+      HEALTH_PATH = '/health'
+
+      CONTENT_TYPE_JSON = 'application/json'
+      DEFAULT_HEADERS_JSON = { 'Content-Type' => CONTENT_TYPE_JSON }.freeze
+
+      # Centralized doc links used by client error mapping
+      DOC_CLIENT_ERRORS = 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/client#errors'
+
+      INTERNAL_ONLY_KEYS = %i[
+        _join
+        _selection
+        _preset_mode
+        _preset_pruned_keys
+        _preset_conflicts
+        _curation_conflict_type
+        _curation_conflict_count
+        _runtime_flags
+        _hits
+        _curation
+      ].freeze
+
+      # Build a single-search request for a collection.
+      #
+      # @param collection [String] logical collection name (alias)
+      # @param compiled_params [SearchEngine::CompiledParams] sanitized, deterministic params
+      # @param url_opts [Hash] URL/common params such as cache controls
+      # @return [Request] normalized request ready for transport
+      # @see `https://typesense.org/docs/latest/api/documents.html#search-document`
+      def self.build_search(collection:, compiled_params:, url_opts: {})
+        name = collection.to_s
+        body_hash = sanitize_body_params(compiled_params.to_h)
+        # Ensure deterministic ordering even after sanitization
+        body_json = SearchEngine::CompiledParams.from(body_hash).to_json
+
+        Request.new(
+          http_method: :post,
+          path: COLLECTIONS_PREFIX + name + DOCUMENTS_SEARCH_SUFFIX,
+          params: url_opts || {},
+          headers: DEFAULT_HEADERS_JSON,
+          body: body_hash,
+          body_json: body_json
+        )
+      end
+
+      # Remove internal-only keys from the HTTP payload (copied from previous client behavior).
+      #
+      # @param params [Hash] possibly containing internal keys
+      # @return [Hash] new Hash without internal-only keys
+      def self.sanitize_body_params(params)
+        payload = params.dup
+        INTERNAL_ONLY_KEYS.each { |k| payload.delete(k) }
+        payload
+      end
+      private_class_method :sanitize_body_params
+    end
+  end
+end

data/lib/search_engine/client/services/base.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  class Client
+    module Services
+      # Shared helpers for service objects that delegate to {SearchEngine::Client}.
+      #
+      # Provides convenient access to the parent client and its private helpers
+      # without widening the public API surface of the client itself.
+      class Base
+        # @param client [SearchEngine::Client]
+        def initialize(client)
+          @client = client
+        end
+
+        private
+
+        attr_reader :client
+
+        def config
+          client.__send__(:config)
+        end
+
+        def typesense
+          client.__send__(:typesense)
+        end
+
+        def typesense_for_import
+          client.__send__(:typesense_for_import)
+        end
+
+        def build_typesense_client_with_read_timeout(seconds)
+          client.__send__(:build_typesense_client_with_read_timeout, seconds)
+        end
+
+        def build_typesense_client
+          client.__send__(:build_typesense_client)
+        end
+
+        def with_exception_mapping(*args, &block)
+          client.__send__(:with_exception_mapping, *args, &block)
+        end
+
+        def instrument(*args)
+          client.__send__(:instrument, *args)
+        end
+
+        def log_success(*args)
+          client.__send__(:log_success, *args)
+        end
+
+        def current_monotonic_ms
+          client.__send__(:current_monotonic_ms)
+        end
+
+        def derive_cache_opts(url_opts)
+          client.__send__(:derive_cache_opts, url_opts)
+        end
+
+        def symbolize_keys_deep(payload)
+          client.__send__(:symbolize_keys_deep, payload)
+        end
+
+        def validate_single!(*args)
+          client.__send__(:validate_single!, *args)
+        end
+
+        def validate_multi!(*args)
+          client.__send__(:validate_multi!, *args)
+        end
+      end
+    end
+  end
+end