swiftype-enterprise 1.0.0

data/lib/swiftype-enterprise.rb

@@ -0,0 +1,6 @@
+require 'swiftype-enterprise/client'
+
+module SwiftypeEnterprise
+  extend SwiftypeEnterprise::Configuration
+end
+

data/lib/swiftype-enterprise/client.rb

@@ -0,0 +1,140 @@
+require 'set'
+require 'swiftype-enterprise/configuration'
+require 'swiftype-enterprise/request'
+require 'swiftype-enterprise/utils'
+
+module SwiftypeEnterprise
+  # API client for the {Swiftype Enterprise API}[https://swiftype.com/enterprise-search].
+  class Client
+    DEFAULT_TIMEOUT = 15
+
+    include SwiftypeEnterprise::Request
+
+    def self.configure(&block)
+      SwiftypeEnterprise.configure &block
+    end
+
+    # Create a new SwiftypeEnterprise::Client client
+    #
+    # @param options [Hash] a hash of configuration options that will override what is set on the SwiftypeEnterprise class.
+    # @option options [String] :access_token an Access Token to use for this client
+    # @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={})
+      @options = options
+    end
+
+    def access_token
+      @options[:access_token] || SwiftypeEnterprise.access_token
+    end
+
+    def open_timeout
+      @options[:open_timeout] || DEFAULT_TIMEOUT
+    end
+
+    def overall_timeout
+      (@options[:overall_timeout] || DEFAULT_TIMEOUT).to_f
+    end
+
+    # Documents have fields that can be searched or filtered.
+    #
+    # For more information on indexing documents, see the {Content Source documentation}[https://app.swiftype.com/ent/docs/custom_sources].
+    module ContentSourceDocuments
+      REQUIRED_TOP_LEVEL_KEYS = [
+        'external_id',
+        'url',
+        'title',
+        'body'
+      ].map!(&:freeze).to_set.freeze
+      OPTIONAL_TOP_LEVEL_KEYS = [
+        'created_at',
+        'updated_at',
+        'type',
+      ].map!(&:freeze).to_set.freeze
+      CORE_TOP_LEVEL_KEYS = (REQUIRED_TOP_LEVEL_KEYS + OPTIONAL_TOP_LEVEL_KEYS).freeze
+
+      # Retrieve Document Receipts from the API by ID for the {asynchronous API}[https://app.swiftype.com/ent/docs/custom_sources]
+      #
+      # @param [Array<String>] receipt_ids an Array of Document Receipt IDs
+      #
+      # @return [Array<Hash>] an Array of Document Receipt hashes
+      def document_receipts(receipt_ids)
+        get('ent/document_receipts/bulk_show.json', :ids => receipt_ids.join(','))
+      end
+
+      # Index a batch of documents synchronously using the {Content Source API}[https://app.swiftype.com/ent/docs/custom_sources].
+      #
+      # @param [String] content_source_key the unique Content Source key as found in your Content Sources dashboard
+      # @param [Array] documents an Array of Document Hashes
+      # @option options [Numeric] :timeout (10) Number of seconds to wait before raising an exception
+      #
+      # @return [Array<Hash>] an Array of processed Document Receipt hashes
+      #
+      # @raise [Timeout::Error] when timeout expires waiting for receipts
+      def index_documents(content_source_key, documents, options = {})
+        documents = Array(documents).map! { |document| validate_and_normalize_document(document) }
+
+        res = async_create_or_update_documents(content_source_key, documents)
+        receipt_ids = res['document_receipts'].map { |a| a['id'] }
+
+        poll(options) do
+          receipts = document_receipts(receipt_ids)
+          flag = receipts.all? { |a| a['status'] != 'pending' }
+          flag ? receipts : false
+        end
+      end
+
+      # Index a batch of documents asynchronously using the {Content Source API}[https://app.swiftype.com/ent/docs/custom_sources].
+      #
+      # @param [String] content_source_key the unique Content Source key as found in your Content Sources dashboard
+      # @param [Array] documents an Array of Document Hashes
+      # @param [Hash] options additional options
+      #
+      # @return [Array<String>] an Array of Document Receipt IDs pending completion
+      def async_index_documents(content_source_key, documents, options = {})
+        documents = Array(documents).map! { |document| validate_and_normalize_document(document) }
+
+        res = async_create_or_update_documents(content_source_key, documents)
+        res['document_receipts'].map { |a| a['id'] }
+      end
+
+      # Destroy a batch of documents given a list of external IDs
+      #
+      # @param [Array<String>] document_ids an Array of Document External IDs
+      #
+      # @return [Array<Hash>] an Array of Document destroy result hashes
+      def destroy_documents(content_source_key, document_ids)
+        document_ids = Array(document_ids)
+        post("ent/sources/#{content_source_key}/documents/bulk_destroy.json", document_ids)
+      end
+
+      private
+      def async_create_or_update_documents(content_source_key, documents)
+        post("ent/sources/#{content_source_key}/documents/bulk_create.json", documents)
+      end
+
+      def validate_and_normalize_document(document)
+        document = Utils.stringify_keys(document)
+        missing_keys = REQUIRED_TOP_LEVEL_KEYS - document.keys
+        raise SwiftypeEnterprise::InvalidDocument.new("missing required fields (#{missing_keys.to_a.join(', ')})") if missing_keys.any?
+
+        normalized_document = {}
+
+        body_content = [document.delete('body')]
+        document.each do |key, value|
+          if CORE_TOP_LEVEL_KEYS.include?(key)
+            normalized_document[key] = value
+          else
+            body_content << "#{key}: #{value}"
+          end
+        end
+        normalized_document['body'] = body_content.join("\n")
+
+        normalized_document
+      end
+    end
+
+    include SwiftypeEnterprise::Client::ContentSourceDocuments
+  end
+end

data/lib/swiftype-enterprise/configuration.rb

@@ -0,0 +1,53 @@
+require 'uri'
+require 'swiftype-enterprise/version'
+
+module SwiftypeEnterprise
+  module Configuration
+    DEFAULT_ENDPOINT = "https://api.swiftype.com/api/v1/"
+    DEFAULT_USER_AGENT = "SwiftypeEnterprise-Ruby/#{SwiftypeEnterprise::VERSION}"
+
+    VALID_OPTIONS_KEYS = [
+      :access_token,
+      :user_agent,
+      :endpoint
+    ].freeze
+
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    def self.extended(base)
+      base.reset
+    end
+
+    # Reset configuration to default values.
+    def reset
+      self.access_token = nil
+      self.endpoint = DEFAULT_ENDPOINT
+      self.user_agent = DEFAULT_USER_AGENT
+      self
+    end
+
+    # Yields the SwiftypeEnterprise::Configuration module which can be used to set configuration options.
+    #
+    # @return self
+    def configure
+      yield self
+      self
+    end
+
+    # Return a hash of the configured options.
+    def options
+      options = {}
+      VALID_OPTIONS_KEYS.each{ |k| options[k] = send(k) }
+      options
+    end
+
+    # setter for endpoint that ensures it always ends in '/'
+    def endpoint=(endpoint)
+      if endpoint.end_with?('/')
+        @endpoint = endpoint
+      else
+        @endpoint = "#{endpoint}/"
+      end
+    end
+  end
+end

data/lib/swiftype-enterprise/exceptions.rb

@@ -0,0 +1,9 @@
+module SwiftypeEnterprise
+  class ClientException < StandardError; end
+  class NonExistentRecord < ClientException; end
+  class InvalidCredentials < ClientException; end
+  class BadRequest < ClientException; end
+  class Forbidden < ClientException; end
+  class UnexpectedHTTPException < ClientException; end
+  class InvalidDocument < ClientException; end
+end

data/lib/swiftype-enterprise/request.rb

@@ -0,0 +1,118 @@
+require 'net/https'
+require 'json'
+require 'swiftype-enterprise/exceptions'
+require 'openssl'
+
+module SwiftypeEnterprise
+  module 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 delete(path, params={})
+      request(:delete, path, params)
+    end
+
+    # Poll a block with backoff until a timeout is reached.
+    #
+    # @param [Hash] options optional arguments
+    # @option options [Numeric] :timeout (10) Number of seconds to wait before timing out
+    #
+    # @yieldreturn a truthy value to return from poll
+    # @yieldreturn [false] to continue polling.
+    #
+    # @return the truthy value returned from the block.
+    #
+    # @raise [Timeout::Error] when the timeout expires
+    def poll(options={})
+      timeout = options[:timeout] || 10
+      delay = 0.05
+      Timeout.timeout(timeout) do
+        while true
+          res = yield
+          return res if res
+          sleep delay *= 2
+        end
+      end
+    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("#{SwiftypeEnterprise.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
+
+        if uri.scheme == 'https'
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.ca_file = File.join(File.dirname(__FILE__), '..', 'data', 'ca-bundle.crt')
+          http.ssl_timeout = open_timeout
+        end
+
+        response = http.request(request)
+        handle_errors(response)
+        JSON.parse(response.body) if response.body && response.body.strip != ''
+      end
+    end
+
+    private
+    def handle_errors(response)
+      case response
+      when Net::HTTPSuccess
+        response
+      when Net::HTTPUnauthorized
+        raise SwiftypeEnterprise::InvalidCredentials
+      when Net::HTTPNotFound
+        raise SwiftypeEnterprise::NonExistentRecord
+      when Net::HTTPBadRequest
+        raise SwiftypeEnterprise::BadRequest
+      when Net::HTTPForbidden
+        raise SwiftypeEnterprise::Forbidden
+      else
+        raise SwiftypeEnterprise::UnexpectedHTTPException, "#{response.code} #{response.body}"
+      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 :delete
+                Net::HTTP::Delete
+              end
+
+      case method
+      when :get, :delete
+        uri.query = URI.encode_www_form(params) if params && !params.empty?
+        req = klass.new(uri.request_uri)
+      when :post, :put
+        req = klass.new(uri.request_uri)
+        req.body = JSON.generate(params) unless params.length == 0
+      end
+
+      req['User-Agent'] = SwiftypeEnterprise.user_agent
+      req['Content-Type'] = 'application/json'
+      req['Authorization'] = "Bearer #{access_token}"
+
+      req
+    end
+  end
+end

data/lib/swiftype-enterprise/utils.rb

@@ -0,0 +1,13 @@
+module SwiftypeEnterprise
+  module Utils
+    extend self
+
+    def stringify_keys(hash)
+      output = {}
+      hash.each do |key, value|
+        output[key.to_s] = value
+      end
+      output
+    end
+  end
+end

data/lib/swiftype-enterprise/version.rb

@@ -0,0 +1,3 @@
+module SwiftypeEnterprise
+  VERSION = '1.0.0'
+end

data/spec/client_spec.rb

@@ -0,0 +1,119 @@
+require 'spec_helper'
+
+describe SwiftypeEnterprise::Client do
+  let(:engine_slug) { 'swiftype-api-example' }
+  let(:client) { SwiftypeEnterprise::Client.new }
+
+  before :each do
+    SwiftypeEnterprise.access_token = 'cGUN-vBokevBhhzyA669'
+  end
+
+  context 'ContentSourceDocuments' do
+    def check_receipt_response_format(response, options = {})
+      expect(response.keys).to match_array(["document_receipts", "batch_link"])
+      expect(response["document_receipts"]).to be_a_kind_of(Array)
+      expect(response["document_receipts"].first.keys).to match_array(["id", "external_id", "links", "status", "errors"])
+      expect(response["document_receipts"].first["external_id"]).to eq(options[:external_id]) if options[:external_id]
+      expect(response["document_receipts"].first["status"]).to eq(options[:status]) if options[:status]
+      expect(response["document_receipts"].first["errors"]).to eq(options[:errors]) if options[:errors]
+    end
+
+    let(:content_source_key) { '59542d332139de0acacc7dd4' }
+    let(:documents) do
+      [{'external_id'=>'INscMGmhmX4',
+        'url' => 'http://www.youtube.com/watch?v=v1uyQZNg2vE',
+        'title' => 'The Original Grumpy Cat',
+        'body' => 'this is a test'},
+       {'external_id'=>'JNDFojsd02',
+               'url' => 'http://www.youtube.com/watch?v=tsdfhk2j',
+               'title' => 'Another Grumpy Cat',
+               'body' => 'this is also a test'}]
+    end
+
+    context '#document_receipts' do
+      before :each do
+        def get_receipt_ids
+          receipt_ids = nil
+          VCR.use_cassette(:async_create_or_update_document_success) do
+            receipt_ids = client.async_index_documents(content_source_key, documents)
+          end
+          receipt_ids
+        end
+      end
+
+      it 'returns array of hashes one for each receipt' do
+        VCR.use_cassette(:document_receipts_multiple) do
+          receipt_ids = get_receipt_ids
+          response = client.document_receipts(receipt_ids)
+          expect(response.size).to eq(2)
+          expect(response.first.keys).to match_array(["id", "external_id", "links", "status", "errors"])
+        end
+      end
+    end
+
+    context '#index_documents' do
+      it 'returns document_receipts when successful' do
+        VCR.use_cassette(:async_create_or_update_document_success) do
+          VCR.use_cassette(:document_receipts_multiple_complete) do
+            response = client.index_documents(content_source_key, documents)
+            expect(response.map(&:keys).map(&:sort)).to eq([["errors", "external_id", "id", "links", "status"], ["errors", "external_id", "id", "links", "status"]])
+            expect(response.map { |a| a["status"] }).to eq(["complete", "complete"])
+          end
+        end
+      end
+
+      it 'should timeout if the process takes longer than the timeout option passed' do
+        allow(client).to receive(:document_receipts) { sleep 0.05 }
+
+        VCR.use_cassette(:async_create_or_update_document_success) do
+          expect do
+            client.index_documents(content_source_key, documents, :timeout => 0.01)
+          end.to raise_error(Timeout::Error)
+        end
+      end
+
+      it 'should validate required document fields' do
+        documents = [{'external_id'=>'INscMGmhmX4', 'url' => 'http://www.youtube.com/watch?v=v1uyQZNg2vE'}]
+        expect do
+          client.index_documents(content_source_key, documents)
+        end.to raise_error(SwiftypeEnterprise::InvalidDocument)
+      end
+
+      it 'should accept non-core document fields' do
+        documents.first['a_new_field'] = 'some value'
+        VCR.use_cassette(:async_create_or_update_document_success) do
+          VCR.use_cassette(:document_receipts_multiple_complete) do
+            response = client.index_documents(content_source_key, documents)
+            expect(response.map { |a| a["status"] }).to eq(["complete", "complete"])
+          end
+        end
+      end
+    end
+
+    context '#async_index_documents' do
+      it 'returns receipt IDs when successful' do
+        VCR.use_cassette(:async_create_or_update_document_success) do
+          VCR.use_cassette(:document_receipts_multiple_complete) do
+            response = client.async_index_documents(content_source_key, documents)
+            expect(response.size).to eq(2)
+          end
+        end
+      end
+    end
+
+    context '#destroy_documents' do
+      it 'returns #async_create_or_update_documents format return when async has been passed as true' do
+        VCR.use_cassette(:async_create_or_update_document_success) do
+          VCR.use_cassette(:document_receipts_multiple_complete) do
+            client.index_documents(content_source_key, documents)
+            VCR.use_cassette(:destroy_documents_success) do
+              response = client.destroy_documents(content_source_key, [documents.first['external_id']])
+              expect(response.size).to eq(1)
+              expect(response.first['success']).to eq(true)
+            end
+          end
+        end
+      end
+    end
+  end
+end