elastic-app-search 0.7.0

data/lib/elastic/app-search.rb

@@ -0,0 +1,6 @@
+require 'elastic/app-search/client'
+
+module Elastic
+  module AppSearch
+  end
+end

data/lib/elastic/app-search/client.rb

@@ -0,0 +1,67 @@
+require 'set'
+require 'elastic/app-search/request'
+require 'elastic/app-search/utils'
+require 'jwt'
+
+module Elastic
+  module AppSearch
+    # API client for the {Elastic App Search API}[https://www.elastic.co/cloud/app-search-service].
+    class Client
+      autoload :Documents, 'elastic/app-search/client/documents'
+      autoload :Engines, 'elastic/app-search/client/engines'
+      autoload :Search, 'elastic/app-search/client/search'
+      autoload :QuerySuggestion, 'elastic/app-search/client/query_suggestion'
+      autoload :SearchSettings, 'elastic/app-search/client/search_settings'
+
+      DEFAULT_TIMEOUT = 15
+
+      include Elastic::AppSearch::Request
+
+      attr_reader :api_key, :open_timeout, :overall_timeout, :api_endpoint
+
+      # Create a new Elastic::AppSearch::Client client
+      #
+      # @param options [Hash] a hash of configuration options that will override what is set on the Elastic::AppSearch class.
+      # @option options [String] :account_host_key or :host_identifier is your Host Identifier to use with this client.
+      # @option options [String] :api_key can be any of your API Keys. Each has a different scope, so ensure you are using the correct key.
+      # @option options [Numeric] :overall_timeout overall timeout for requests in seconds (default: 15s)
+      # @option options [Numeric] :open_timeout the number of seconds Net::HTTP (default: 15s)
+      #   will wait while opening a connection before raising a Timeout::Error
+      def initialize(options = {})
+        @api_endpoint = options.fetch(:api_endpoint) { "https://#{options.fetch(:account_host_key) { options.fetch(:host_identifier) }}.api.swiftype.com/api/as/v1/" }
+        @api_key = options.fetch(:api_key)
+        @open_timeout = options.fetch(:open_timeout, DEFAULT_TIMEOUT).to_f
+        @overall_timeout = options.fetch(:overall_timeout, DEFAULT_TIMEOUT).to_f
+      end
+
+      module SignedSearchOptions
+        ALGORITHM = 'HS256'.freeze
+
+        module ClassMethods
+          # Build a JWT for authentication
+          #
+          # @param [String] api_key the API Key to sign the request with
+          # @param [String] api_key_name the unique name for the API Key
+          # @option options see the {App Search API}[https://swiftype.com/documentation/app-search/] for supported search options.
+          #
+          # @return [String] the JWT to use for authentication
+          def create_signed_search_key(api_key, api_key_name, options = {})
+            payload = Utils.symbolize_keys(options).merge(:api_key_name => api_key_name)
+            JWT.encode(payload, api_key, ALGORITHM)
+          end
+        end
+
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+      end
+
+      include Elastic::AppSearch::Client::Documents
+      include Elastic::AppSearch::Client::Engines
+      include Elastic::AppSearch::Client::Search
+      include Elastic::AppSearch::Client::SignedSearchOptions
+      include Elastic::AppSearch::Client::QuerySuggestion
+      include Elastic::AppSearch::Client::SearchSettings
+    end
+  end
+end

data/lib/elastic/app-search/client/documents.rb

@@ -0,0 +1,91 @@
+# Documents have fields that can be searched or filtered.
+#
+# For more information on indexing documents, see the {App Search documentation}[https://swiftype.com/documentation/app-search/].
+module Elastic
+  module AppSearch
+    class Client
+      module Documents
+
+        # Retrieve all Documents from the API for the {App Search API}[https://swiftype.com/documentation/app-search/]
+        #
+        # @param [String] engine_name the unique Engine name
+        # @option options see the {App Search API}[https://swiftype.com/documentation/app-search/] for supported options.
+        #
+        # @return [Array<Hash>] an Array of Documents
+        def list_documents(engine_name, options = {})
+          params = Utils.symbolize_keys(options)
+          request(:get, "engines/#{engine_name}/documents/list", params)
+        end
+
+        # Retrieve Documents from the API by IDs for the {App Search API}[https://swiftype.com/documentation/app-search/]
+        #
+        # @param [String] engine_name the unique Engine name
+        # @param [Array<String>] ids an Array of Document IDs
+        #
+        # @return [Hash] list results
+        def get_documents(engine_name, ids)
+          get("engines/#{engine_name}/documents", ids)
+        end
+
+        # Index a document using the {App Search API}[https://swiftype.com/documentation/app-search/].
+        #
+        # @param [String] engine_name the unique Engine name
+        # @param [Array] document a Document Hash
+        #
+        # @return [Hash] processed Document Status hash
+        #
+        # @raise [Elastic::AppSearch::InvalidDocument] when the document has processing errors returned from the api
+        # @raise [Timeout::Error] when timeout expires waiting for statuses
+        def index_document(engine_name, document)
+          response = index_documents(engine_name, [document])
+          errors = response.first['errors']
+          raise InvalidDocument.new(errors.join('; ')) if errors.any?
+          response.first.tap { |h| h.delete('errors') }
+        end
+
+        # Index a batch of documents using the {App Search API}[https://swiftype.com/documentation/app-search/].
+        #
+        # @param [String] engine_name the unique Engine name
+        # @param [Array] documents an Array of Document Hashes
+        #
+        # @return [Array<Hash>] an Array of processed Document Status hashes
+        #
+        # @raise [Elastic::AppSearch::InvalidDocument] when any documents have processing errors returned from the api
+        # @raise [Timeout::Error] when timeout expires waiting for statuses
+        def index_documents(engine_name, documents)
+          documents.map! { |document| normalize_document(document) }
+          post("engines/#{engine_name}/documents", documents)
+        end
+
+        # Update a batch of documents using the {App Search API}[https://swiftype.com/documentation/app-search/].
+        #
+        # @param [String] engine_name the unique Engine name
+        # @param [Array] documents an Array of Document Hashes including valid ids
+        #
+        # @return [Array<Hash>] an Array of processed Document Status hashes
+        #
+        # @raise [Elastic::AppSearch::InvalidDocument] when any documents have processing errors returned from the api
+        # @raise [Timeout::Error] when timeout expires waiting for statuses
+        def update_documents(engine_name, documents)
+          documents.map! { |document| normalize_document(document) }
+          patch("engines/#{engine_name}/documents", documents)
+        end
+
+        # Destroy a batch of documents given a list of IDs
+        #
+        # @param [Array<String>] ids an Array of Document IDs
+        #
+        # @return [Array<Hash>] an Array of Document destroy result hashes
+        def destroy_documents(engine_name, ids)
+          delete("engines/#{engine_name}/documents", ids)
+        end
+
+        private
+
+        def normalize_document(document)
+          Utils.stringify_keys(document)
+        end
+      end
+    end
+  end
+end

data/lib/elastic/app-search/client/engines.rb

@@ -0,0 +1,27 @@
+# Engines are the core concept representing indexes in App Search.
+#
+module Elastic
+  module AppSearch
+    class Client
+      module Engines
+        def list_engines(current: 1, size: 20)
+          get("engines", :page => { :current => current, :size => size })
+        end
+
+        def get_engine(engine_name)
+          get("engines/#{engine_name}")
+        end
+
+        def create_engine(engine_name, language = nil)
+          params = { :name => engine_name }
+          params[:language] = language if language
+          post("engines", params)
+        end
+
+        def destroy_engine(engine_name)
+          delete("engines/#{engine_name}")
+        end
+      end
+    end
+  end
+end

data/lib/elastic/app-search/client/query_suggestion.rb

@@ -0,0 +1,19 @@
+module Elastic
+  module AppSearch
+    class Client
+      module QuerySuggestion
+        # Request Query Suggestions
+        #
+        # @param [String] engine_name the unique Engine name
+        # @param [String] query the search query to suggest for
+        # @options options see the {App Search API}[https://swiftype.com/documentation/app-search/] for supported search options.
+        #
+        # @return [Hash] search results
+        def query_suggestion(engine_name, query, options = {})
+          params = Utils.symbolize_keys(options).merge(:query => query)
+          request(:post, "engines/#{engine_name}/query_suggestion", params)
+        end
+      end
+    end
+  end
+end

data/lib/elastic/app-search/client/search.rb

@@ -0,0 +1,38 @@
+module Elastic
+  module AppSearch
+    class Client
+      module Search
+        # Search for documents
+        #
+        # @param [String] engine_name the unique Engine name
+        # @param [String] query the search query
+        # @option options see the {App Search API}[https://swiftype.com/documentation/app-search/] for supported search options.
+        #
+        # @return [Hash] search results
+        def search(engine_name, query, options = {})
+          params = Utils.symbolize_keys(options).merge(:query => query)
+          request(:post, "engines/#{engine_name}/search", params)
+        end
+
+        # Run multiple searches for documents on a single request
+        #
+        # @param [String] engine_name the unique Engine name
+        # @param [{query: String, options: Hash}] searches to execute
+        # see the {App Search API}[https://swiftype.com/documentation/app-search/] for supported search options.
+        #
+        # @return [Array<Hash>] an Array of searh sesults
+        def multi_search(engine_name, searches)
+          params = searches.map do |search|
+            search = Utils.symbolize_keys(search)
+            query = search[:query]
+            options = search[:options] || {}
+            Utils.symbolize_keys(options).merge(:query => query)
+          end
+          request(:post, "engines/#{engine_name}/multi_search", {
+            queries: params
+          })
+        end
+      end
+    end
+  end
+end

data/lib/elastic/app-search/client/search_settings.rb

@@ -0,0 +1,37 @@
+# Search Settings is used to adjust weights and boosts
+module Elastic
+  module AppSearch
+    class Client
+      module SearchSettings
+
+        # Show all Weights and Boosts applied to the search fields of an Engine.
+        #
+        # @param [String] engine_name the unique Engine name
+        #
+        # @return [Hash] current Search Settings
+        def show_settings(engine_name)
+          get("engines/#{engine_name}/search_settings")
+        end
+
+        # Update Weights or Boosts for search fields of an Engine.
+        #
+        # @param [String] engine_name the unique Engine name
+        # @param [Hash] settings new Search Settings Hash
+        #
+        # @return [Hash] new Search Settings
+        def update_settings(engine_name, settings)
+          put("engines/#{engine_name}/search_settings", settings)
+        end
+
+        # Reset Engine's Search Settings to default values.
+        #
+        # @param [String] engine_name the unique Engine name
+        #
+        # @return [Hash] default Search Settings
+        def reset_settings(engine_name)
+          post("engines/#{engine_name}/search_settings/reset")
+        end
+      end
+    end
+  end
+end

data/lib/elastic/app-search/exceptions.rb

@@ -0,0 +1,31 @@
+module Elastic
+  module AppSearch
+    class ClientException < StandardError
+      attr_reader :errors
+
+      def initialize(response)
+        @errors = if response.is_a?(Array)
+          response.flat_map { |r| r['errors'] }
+        else
+          response['errors'] || [response]
+        end
+        message = (errors.count == 1) ? "Error: #{errors.first}" : "Errors: #{errors.inspect}"
+        super(message)
+      end
+    end
+
+    class NonExistentRecord < ClientException; end
+    class InvalidCredentials < ClientException; end
+    class BadRequest < ClientException; end
+    class Forbidden < ClientException; end
+    class InvalidDocument < ClientException; end
+    class RequestEntityTooLarge < ClientException; end
+
+    class UnexpectedHTTPException < ClientException
+      def initialize(response, response_json)
+        errors = (response_json['errors'] || [response.message]).map { |e| "(#{response.code}) #{e}" }
+        super({ 'errors' => errors })
+      end
+    end
+  end
+end

data/lib/elastic/app-search/request.rb

@@ -0,0 +1,147 @@
+require 'net/https'
+require 'json'
+require 'time'
+require 'elastic/app-search/exceptions'
+require 'elastic/app-search/version'
+require 'openssl'
+
+module Elastic
+  module AppSearch
+    CLIENT_NAME = 'elastic-app-search-ruby'
+    CLIENT_VERSION = Elastic::AppSearch::VERSION
+
+    module Request
+      attr_accessor :last_request
+
+      def get(path, params={})
+        request(:get, path, params)
+      end
+
+      def post(path, params={})
+        request(:post, path, params)
+      end
+
+      def put(path, params={})
+        request(:put, path, params)
+      end
+
+      def patch(path, params={})
+        request(:patch, path, params)
+      end
+
+      def delete(path, params={})
+        request(:delete, path, params)
+      end
+
+      # Construct and send a request to the API.
+      #
+      # @raise [Timeout::Error] when the timeout expires
+      def request(method, path, params = {})
+        Timeout.timeout(overall_timeout) do
+          uri = URI.parse("#{api_endpoint}#{path}")
+
+          request = build_request(method, uri, params)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.open_timeout = open_timeout
+          http.read_timeout = overall_timeout
+
+          http.set_debug_output(STDERR) if debug?
+
+          if uri.scheme == 'https'
+            http.use_ssl = true
+            # st_ssl_verify_none provides a means to disable SSL verification for debugging purposes. An example
+            # is Charles, which uses a self-signed certificate in order to inspect https traffic. This will
+            # not be part of this client's public API, this is more of a development enablement option
+            http.verify_mode = ENV['st_ssl_verify_none'] == 'true' ? OpenSSL::SSL::VERIFY_NONE : OpenSSL::SSL::VERIFY_PEER
+            http.ca_file = File.join(File.dirname(__FILE__), '../..', 'data', 'ca-bundle.crt')
+            http.ssl_timeout = open_timeout
+          end
+
+          @last_request = request
+
+          response = http.request(request)
+          response_json = parse_response(response)
+
+          case response
+          when Net::HTTPSuccess
+            return response_json
+          when Net::HTTPBadRequest
+            raise Elastic::AppSearch::BadRequest, response_json
+          when Net::HTTPUnauthorized
+            raise Elastic::AppSearch::InvalidCredentials, response_json
+          when Net::HTTPNotFound
+            raise Elastic::AppSearch::NonExistentRecord, response_json
+          when Net::HTTPForbidden
+            raise Elastic::AppSearch::Forbidden, response_json
+          when Net::HTTPRequestEntityTooLarge
+            raise Elastic::AppSearch::RequestEntityTooLarge, response_json
+          else
+            raise Elastic::AppSearch::UnexpectedHTTPException.new(response, response_json)
+          end
+        end
+      end
+
+      private
+
+      def parse_response(response)
+        body = response.body.to_s.strip
+        body == '' ? {} : JSON.parse(body)
+      end
+
+      def debug?
+        @debug ||= (ENV['AS_DEBUG'] == 'true')
+      end
+
+      def serialize_json(object)
+        JSON.generate(clean_json(object))
+      end
+
+      def clean_json(object)
+        case object
+        when Hash
+          object.inject({}) do |builder, (key, value)|
+            builder[key] = clean_json(value)
+            builder
+          end
+        when Enumerable
+          object.map { |value| clean_json(value) }
+        else
+          clean_atom(object)
+        end
+      end
+
+      def clean_atom(atom)
+        if atom.is_a?(Time)
+          atom.to_datetime
+        else
+          atom
+        end
+      end
+
+      def build_request(method, uri, params)
+        klass = case method
+                when :get
+                  Net::HTTP::Get
+                when :post
+                  Net::HTTP::Post
+                when :put
+                  Net::HTTP::Put
+                when :patch
+                  Net::HTTP::Patch
+                when :delete
+                  Net::HTTP::Delete
+                end
+
+        req = klass.new(uri.request_uri)
+        req.body = serialize_json(params) unless params.length == 0
+
+        req['X-Swiftype-Client'] = CLIENT_NAME
+        req['X-Swiftype-Client-Version'] = CLIENT_VERSION
+        req['Content-Type'] = 'application/json'
+        req['Authorization'] = "Bearer #{api_key}"
+
+        req
+      end
+    end
+  end
+end