search-engine-for-typesense 1.0.0

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

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  class Client
+    module Services
+      # Collection-related operations (schema lifecycle, alias management, listings).
+      class Collections < Base
+        # @param logical_name [String]
+        # @return [String, nil]
+        def resolve_alias(logical_name, timeout_ms: nil)
+          name = logical_name.to_s
+          start = current_monotonic_ms
+          path = [Client::RequestBuilder::ALIASES_PREFIX, name].join
+
+          ts = if timeout_ms&.to_i&.positive?
+                 build_typesense_client_with_read_timeout(timeout_ms.to_i / 1000.0)
+               else
+                 typesense
+               end
+
+          result = with_exception_mapping(:get, path, {}, start) do
+            ts.aliases[name].retrieve
+          end
+
+          (result && (result['collection_name'] || result[:collection_name])).to_s
+        rescue Errors::Api => error
+          return nil if error.status.to_i == 404
+
+          raise
+        ensure
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+        end
+
+        # @param collection_name [String]
+        # @return [Hash, nil]
+        def retrieve_schema(collection_name, timeout_ms: nil)
+          name = collection_name.to_s
+          start = current_monotonic_ms
+          path = [Client::RequestBuilder::COLLECTIONS_PREFIX, name].join
+
+          ts = if timeout_ms&.to_i&.positive?
+                 build_typesense_client_with_read_timeout(timeout_ms.to_i / 1000.0)
+               else
+                 typesense
+               end
+
+          result = with_exception_mapping(:get, path, {}, start) do
+            ts.collections[name].retrieve
+          end
+
+          symbolize_keys_deep(result)
+        rescue Errors::Api => error
+          return nil if error.status.to_i == 404
+
+          raise
+        ensure
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+        end
+
+        # @param alias_name [String]
+        # @param physical_name [String]
+        # @return [Hash]
+        def upsert_alias(alias_name, physical_name)
+          a = alias_name.to_s
+          p = physical_name.to_s
+          start = current_monotonic_ms
+          path = [Client::RequestBuilder::ALIASES_PREFIX, a].join
+
+          result = with_exception_mapping(:put, path, {}, start) do
+            typesense.aliases.upsert(a, collection_name: p)
+          end
+
+          symbolize_keys_deep(result)
+        ensure
+          instrument(:put, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+        end
+
+        # @param schema [Hash]
+        # @return [Hash]
+        def create(schema)
+          start = current_monotonic_ms
+          path = Client::RequestBuilder::COLLECTIONS_ROOT
+          body = schema.dup
+
+          result = with_exception_mapping(:post, path, {}, start) do
+            typesense.collections.create(body)
+          end
+
+          symbolize_keys_deep(result)
+        ensure
+          instrument(:post, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+        end
+
+        # @param name [String]
+        # @param schema [Hash]
+        # @return [Hash]
+        def update(name, schema)
+          n = name.to_s
+          start = current_monotonic_ms
+          path = Client::RequestBuilder::COLLECTIONS_PREFIX + n
+          body = schema.dup
+
+          result = with_exception_mapping(:patch, path, {}, start) do
+            typesense.collections[n].update(body)
+          end
+
+          symbolize_keys_deep(result)
+        ensure
+          instrument(:patch, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+        end
+
+        # @param name [String]
+        # @param timeout_ms [Integer, nil]
+        # @return [Hash]
+        def delete(name, timeout_ms: nil)
+          n = name.to_s
+          start = current_monotonic_ms
+          path = Client::RequestBuilder::COLLECTIONS_PREFIX + n
+
+          ts = if timeout_ms&.to_i&.positive?
+                 build_typesense_client_with_read_timeout(timeout_ms.to_i / 1000.0)
+               else
+                 typesense
+               end
+
+          result = with_exception_mapping(:delete, path, {}, start) do
+            ts.collections[n].delete
+          end
+
+          symbolize_keys_deep(result)
+        rescue Errors::Api => error
+          return { status: 404 } if error.status.to_i == 404
+
+          raise
+        ensure
+          instrument(:delete, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+        end
+
+        # @return [Array<Hash>]
+        def list(timeout_ms: nil)
+          start = current_monotonic_ms
+          path = Client::RequestBuilder::COLLECTIONS_ROOT
+
+          ts = if timeout_ms&.to_i&.positive?
+                 build_typesense_client_with_read_timeout(timeout_ms.to_i / 1000.0)
+               else
+                 typesense
+               end
+
+          result = with_exception_mapping(:get, path, {}, start) do
+            ts.collections.retrieve
+          end
+
+          symbolize_keys_deep(result)
+        ensure
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  class Client
+    module Services
+      # Document-level operations (import, CRUD, bulk updates).
+      class Documents < Base
+        # @param collection [String]
+        # @param jsonl [String]
+        # @param action [Symbol, String]
+        # @return [Object]
+        def import(collection:, jsonl:, action: :upsert)
+          unless collection.is_a?(String) && !collection.strip.empty?
+            raise Errors::InvalidParams, 'collection must be a non-empty String'
+          end
+          raise Errors::InvalidParams, 'jsonl must be a String' unless jsonl.is_a?(String)
+
+          ts = typesense_for_import
+          start = current_monotonic_ms
+          path = documents_path(collection)
+
+          result = with_exception_mapping(:post, path, {}, start) do
+            ts.collections[collection].documents.import(jsonl, action: action.to_s)
+          end
+
+          instrument(:post, path, current_monotonic_ms - start, {})
+          result
+        end
+
+        # @param collection [String]
+        # @param filter_by [String]
+        # @param timeout_ms [Integer, nil]
+        # @return [Hash]
+        def delete_by_filter(collection:, filter_by:, timeout_ms: nil)
+          unless collection.is_a?(String) && !collection.strip.empty?
+            raise Errors::InvalidParams, 'collection must be a non-empty String'
+          end
+          unless filter_by.is_a?(String) && !filter_by.strip.empty?
+            raise Errors::InvalidParams, 'filter_by must be a non-empty String'
+          end
+
+          ts = if timeout_ms&.to_i&.positive?
+                 build_typesense_client_with_read_timeout(timeout_ms.to_i / 1000.0)
+               else
+                 typesense
+               end
+          start = current_monotonic_ms
+          path = documents_path(collection)
+
+          result = with_exception_mapping(:delete, path, {}, start) do
+            ts.collections[collection].documents.delete(filter_by: filter_by)
+          end
+
+          instrument(:delete, path, current_monotonic_ms - start, {})
+          symbolize_keys_deep(result)
+        end
+
+        # @param collection [String]
+        # @param id [String, #to_s]
+        # @param timeout_ms [Integer, nil]
+        # @return [Hash, nil]
+        def delete(collection:, id:, timeout_ms: nil)
+          unless collection.is_a?(String) && !collection.strip.empty?
+            raise Errors::InvalidParams, 'collection must be a non-empty String'
+          end
+
+          s = id.to_s
+          raise Errors::InvalidParams, 'id must be a non-empty String' if s.strip.empty?
+
+          ts = if timeout_ms&.to_i&.positive?
+                 build_typesense_client_with_read_timeout(timeout_ms.to_i / 1000.0)
+               else
+                 typesense
+               end
+          start = current_monotonic_ms
+          path = document_member_path(collection, s)
+
+          result = with_exception_mapping(:delete, path, {}, start) do
+            ts.collections[collection].documents[s].delete
+          end
+          symbolize_keys_deep(result)
+        rescue Errors::Api => error
+          return nil if error.status.to_i == 404
+
+          raise
+        ensure
+          instrument(:delete, path, current_monotonic_ms - start, {}) if defined?(start)
+        end
+
+        # @param collection [String]
+        # @param id [String, #to_s]
+        # @param fields [Hash]
+        # @param timeout_ms [Integer, nil]
+        # @return [Hash]
+        def update(collection:, id:, fields:, timeout_ms: nil)
+          unless collection.is_a?(String) && !collection.strip.empty?
+            raise Errors::InvalidParams, 'collection must be a non-empty String'
+          end
+
+          s = id.to_s
+          raise Errors::InvalidParams, 'id must be a non-empty String' if s.strip.empty?
+          raise Errors::InvalidParams, 'fields must be a Hash' unless fields.is_a?(Hash)
+
+          ts = if timeout_ms&.to_i&.positive?
+                 build_typesense_client_with_read_timeout(timeout_ms.to_i / 1000.0)
+               else
+                 typesense
+               end
+          start = current_monotonic_ms
+          path = document_member_path(collection, s)
+
+          result = with_exception_mapping(:patch, path, {}, start) do
+            ts.collections[collection].documents[s].update(fields)
+          end
+          instrument(:patch, path, current_monotonic_ms - start, {})
+          symbolize_keys_deep(result)
+        end
+
+        # @param collection [String]
+        # @param filter_by [String]
+        # @param fields [Hash]
+        # @param timeout_ms [Integer, nil]
+        # @return [Hash]
+        def update_by_filter(collection:, filter_by:, fields:, timeout_ms: nil)
+          unless collection.is_a?(String) && !collection.strip.empty?
+            raise Errors::InvalidParams, 'collection must be a non-empty String'
+          end
+          unless filter_by.is_a?(String) && !filter_by.strip.empty?
+            raise Errors::InvalidParams, 'filter_by must be a non-empty String'
+          end
+          raise Errors::InvalidParams, 'fields must be a Hash' unless fields.is_a?(Hash)
+
+          ts = if timeout_ms&.to_i&.positive?
+                 build_typesense_client_with_read_timeout(timeout_ms.to_i / 1000.0)
+               else
+                 typesense
+               end
+          start = current_monotonic_ms
+          path = documents_path(collection)
+
+          result = with_exception_mapping(:patch, path, {}, start) do
+            ts.collections[collection].documents.update(fields, filter_by: filter_by)
+          end
+
+          instrument(:patch, path, current_monotonic_ms - start, {})
+          symbolize_keys_deep(result)
+        end
+
+        # @param collection [String]
+        # @param document [Hash]
+        # @return [Hash]
+        def create(collection:, document:)
+          unless collection.is_a?(String) && !collection.strip.empty?
+            raise Errors::InvalidParams, 'collection must be a non-empty String'
+          end
+          raise Errors::InvalidParams, 'document must be a Hash' unless document.is_a?(Hash)
+
+          start = current_monotonic_ms
+          path = documents_path(collection)
+
+          result = with_exception_mapping(:post, path, {}, start) do
+            typesense.collections[collection].documents.create(document)
+          end
+
+          instrument(:post, path, current_monotonic_ms - start, {})
+          symbolize_keys_deep(result)
+        end
+
+        # Retrieve a single document by id.
+        # @param collection [String]
+        # @param id [String, #to_s]
+        # @param timeout_ms [Integer, nil]
+        # @return [Hash, nil] document hash or nil when 404
+        def retrieve(collection:, id:, timeout_ms: nil)
+          unless collection.is_a?(String) && !collection.strip.empty?
+            raise Errors::InvalidParams, 'collection must be a non-empty String'
+          end
+
+          s = id.to_s
+          raise Errors::InvalidParams, 'id must be a non-empty String' if s.strip.empty?
+
+          ts = if timeout_ms&.to_i&.positive?
+                 build_typesense_client_with_read_timeout(timeout_ms.to_i / 1000.0)
+               else
+                 typesense
+               end
+          start = current_monotonic_ms
+          path = document_member_path(collection, s)
+
+          result = with_exception_mapping(:get, path, {}, start) do
+            ts.collections[collection].documents[s].retrieve
+          end
+          symbolize_keys_deep(result)
+        rescue Errors::Api => error
+          return nil if error.status.to_i == 404
+
+          raise
+        ensure
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {}) if defined?(start)
+        end
+
+        private
+
+        def documents_path(collection)
+          Client::RequestBuilder::COLLECTIONS_PREFIX + collection.to_s + Client::RequestBuilder::DOCUMENTS_SUFFIX
+        end
+
+        def document_member_path(collection, id)
+          documents_path(collection) + "/#{id}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  class Client
+    module Services
+      # Operational endpoints (health checks, cache management, API keys).
+      class Operations < Base
+        def health
+          start = current_monotonic_ms
+          path = Client::RequestBuilder::HEALTH_PATH
+
+          result = with_exception_mapping(:get, path, {}, start) do
+            typesense.health.retrieve
+          end
+
+          symbolize_keys_deep(result)
+        ensure
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+        end
+
+        def list_api_keys
+          start = current_monotonic_ms
+          path = '/keys'
+
+          result = with_exception_mapping(:get, path, {}, start) do
+            res = begin
+              typesense.keys.retrieve
+            rescue NoMethodError
+              typesense.keys.list
+            end
+            if res.is_a?(Hash)
+              Array(res[:keys] || res['keys'])
+            else
+              Array(res)
+            end
+          end
+
+          symbolize_keys_deep(result)
+        ensure
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+        end
+
+        def clear_cache
+          start = current_monotonic_ms
+          path = '/operations/cache/clear'
+
+          result = with_exception_mapping(:post, path, {}, start) do
+            typesense.operations.perform('cache/clear')
+          end
+
+          instrument(:post, path, current_monotonic_ms - start, {})
+          symbolize_keys_deep(result)
+        end
+
+        # Return raw cluster metrics from Typesense.
+        #
+        # Exposes the `/metrics.json` endpoint without symbolizing or coercing keys.
+        # When the upstream client does not expose a dedicated endpoint, falls back
+        # to a direct HTTP GET using the configured host/port/protocol and API key.
+        #
+        # @return [Hash] raw JSON object returned by Typesense `/metrics.json`
+        # @see `https://typesense.org/docs/latest/api/cluster-operations.html#metrics`
+        def metrics
+          start = current_monotonic_ms
+          path = '/metrics.json'
+
+          with_exception_mapping(:get, path, {}, start) do
+            ts = typesense
+            if ts.respond_to?(:metrics) && ts.metrics.respond_to?(:retrieve)
+              ts.metrics.retrieve
+            elsif ts.respond_to?(:operations) && ts.operations.respond_to?(:perform)
+              ts.operations.perform('metrics.json')
+            else
+              http_get_json(path)
+            end
+          end
+        ensure
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+        end
+
+        # Return raw server statistics from Typesense.
+        #
+        # Exposes the `/stats.json` endpoint without symbolizing or coercing keys.
+        # When the upstream client does not expose a dedicated endpoint, falls back
+        # to a direct HTTP GET using the configured host/port/protocol and API key.
+        #
+        # @return [Hash] raw JSON object returned by Typesense `/stats.json`
+        # @see `https://typesense.org/docs/latest/api/cluster-operations.html#stats`
+        def stats
+          start = current_monotonic_ms
+          path = '/stats.json'
+
+          with_exception_mapping(:get, path, {}, start) do
+            ts = typesense
+            if ts.respond_to?(:stats) && ts.stats.respond_to?(:retrieve)
+              ts.stats.retrieve
+            elsif ts.respond_to?(:operations) && ts.operations.respond_to?(:perform)
+              ts.operations.perform('stats.json')
+            else
+              http_get_json(path)
+            end
+          end
+        ensure
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+        end
+
+        private
+
+        def http_get_json(path)
+          require 'net/http'
+          require 'uri'
+          require 'json'
+
+          proto = begin
+            config.protocol.to_s.strip
+          rescue StandardError
+            'http'
+          end
+          proto = proto.nil? || proto.empty? ? 'http' : proto
+
+          host = config.host
+          port = config.port
+          uri = URI.parse("#{proto}://#{host}:#{port}#{path}")
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = (uri.scheme == 'https')
+
+          timeout_s = begin
+            t = config.timeout_ms.to_i
+            t.positive? ? (t / 1000.0) : 2.0
+          rescue StandardError
+            2.0
+          end
+          http.open_timeout = timeout_s
+          http.read_timeout = timeout_s
+
+          req = Net::HTTP::Get.new(uri.request_uri)
+          req['X-TYPESENSE-API-KEY'] = config.api_key
+
+          res = http.request(req)
+          code = res.code.to_i
+          body = res.body.to_s
+          unless code >= 200 && code < 300
+            raise SearchEngine::Errors::Api.new("typesense api error: #{code}", status: code, body: body)
+          end
+
+          JSON.parse(body)
+        end
+      end
+    end
+  end
+end