client.rb in algoliasearch-1.21.0

- old
+ new

@@ -7,23 +7,25 @@
 require 'base64'
 
 module Algolia
   WAIT_TASK_DEFAULT_TIME_BEFORE_RETRY = 100
 
+  #
   # A class which encapsulates the HTTPS communication with the Algolia
   # API server. Uses the HTTPClient library for low-level HTTP communication.
+  #
   class Client
     attr_reader :ssl, :ssl_version, :hosts, :search_hosts, :application_id, :api_key, :headers, :connect_timeout, :send_timeout, :receive_timeout, :search_timeout, :batch_timeout
 
     DEFAULT_CONNECT_TIMEOUT = 2
     DEFAULT_RECEIVE_TIMEOUT = 30
     DEFAULT_SEND_TIMEOUT    = 30
     DEFAULT_BATCH_TIMEOUT   = 120
     DEFAULT_SEARCH_TIMEOUT  = 5
 
     def initialize(data = {})
-      raise ArgumentError.new("No APPLICATION_ID provided, please set :application_id") if data[:application_id].nil?
+      raise ArgumentError.new('No APPLICATION_ID provided, please set :application_id') if data[:application_id].nil?
 
       @ssl             = data[:ssl].nil? ? true : data[:ssl]
       @ssl_version     = data[:ssl_version].nil? ? nil : data[:ssl_version]
       @gzip            = data[:gzip].nil? ? true : data[:gzip]
       @application_id  = data[:application_id]
@@ -65,10 +67,11 @@
     end
 
     #
     # Allow to use IP rate limit when you have a proxy between end-user and Algolia.
     # This option will set the X-Forwarded-For HTTP header with the client IP and the X-Forwarded-API-Key with the API Key having rate limits.
+    #
     # @param admin_api_key the admin API Key you can find in your dashboard
     # @param end_user_ip the end user IP (you can use both IPV4 or IPV6 syntax)
     # @param rate_limit_api_key the API key on which you have a rate limit
     #
     def enable_rate_limit_forward(admin_api_key, end_user_ip, rate_limit_api_key)
@@ -121,14 +124,14 @@
       request_options ||= {}
 
       requests = {
         :requests => queries.map do |query|
           query = query.dup
-          indexName = query.delete(index_name_key) || query.delete(index_name_key.to_s)
-          raise ArgumentError.new("Missing '#{index_name_key}' option") if indexName.nil?
-          encoded_params = Hash[query.map { |k,v| [k.to_s, v.is_a?(Array) ? v.to_json : v] }]
-          { :indexName => indexName, :params => Protocol.to_query(encoded_params) }
+          index_name = query.delete(index_name_key) || query.delete(index_name_key.to_s)
+          raise ArgumentError.new("Missing '#{index_name_key}' option") if index_name.nil?
+          encoded_params = Hash[query.map { |k, v| [k.to_s, v.is_a?(Array) ? v.to_json : v] }]
+          { :indexName => index_name, :params => Protocol.to_query(encoded_params) }
         end
       }
       post(Protocol.multiple_queries_uri(strategy), requests.to_json, :search, request_options)
     end
 
@@ -144,21 +147,23 @@
       get(Protocol.indexes_uri, :read, request_options)
     end
 
     #
     # Move an existing index.
+    #
     # @param src_index the name of index to copy.
     # @param dst_index the new index name that will contains a copy of srcIndexName (destination will be overriten if it already exist).
     # @param request_options contains extra parameters to send with your query
     #
     def move_index(src_index, dst_index, request_options = {})
-      request = {"operation" => "move", "destination" => dst_index};
+      request = { 'operation' => 'move', 'destination' => dst_index };
       post(Protocol.index_operation_uri(src_index), request.to_json, :write, request_options)
     end
 
     #
     # Move an existing index and wait until the move has been processed
+    #
     # @param src_index the name of index to copy.
     # @param dst_index the new index name that will contains a copy of srcIndexName (destination will be overriten if it already exist).
     # @param request_options contains extra parameters to send with your query
     #
     def move_index!(src_index, dst_index, request_options = {})
@@ -167,23 +172,25 @@
       res
     end
 
     #
     # Copy an existing index.
+    #
     # @param src_index the name of index to copy.
     # @param dst_index the new index name that will contains a copy of srcIndexName (destination will be overriten if it already exist).
     # @param scope the optional list of scopes to copy (all if not specified).
     # @param request_options contains extra parameters to send with your query
     #
     def copy_index(src_index, dst_index, scope = nil, request_options = {})
-      request = {"operation" => "copy", "destination" => dst_index};
-      request["scope"] = scope unless scope.nil?
+      request = { 'operation' => 'copy', 'destination' => dst_index };
+      request['scope'] = scope unless scope.nil?
       post(Protocol.index_operation_uri(src_index), request.to_json, :write, request_options)
     end
 
     #
     # Copy an existing index and wait until the copy has been processed.
+    #
     # @param src_index the name of index to copy.
     # @param dst_index the new index name that will contains a copy of srcIndexName (destination will be overriten if it already exist).
     # @param scope the optional list of scopes to copy (all if not specified).
     # @param request_options contains extra parameters to send with your query
     #
@@ -191,18 +198,20 @@
       res = copy_index(src_index, dst_index, scope, request_options)
       init_index(dst_index).wait_task(res['taskID'], WAIT_TASK_DEFAULT_TIME_BEFORE_RETRY, request_options)
       res
     end
 
+    #
     # Delete an index
     # @param name the name of the index to delete
     # @param request_options contains extra parameters to send with your query
     #
     def delete_index(name, request_options = {})
       init_index(name).delete(request_options)
     end
 
+    #
     # Delete an index and wait until the deletion has been processed.
     # @param name the name of the index to delete
     # @param request_options contains extra parameters to send with your query
     #
     def delete_index!(name, request_options = {})
@@ -234,20 +243,24 @@
       request_options ||= {}
 
       get(Protocol.logs(offset, length, type), :write, request_options)
     end
 
+    #
     # List all existing user keys with their associated ACLs
     #
     # @param request_options contains extra parameters to send with your query
+    #
     def list_api_keys(request_options = {})
       get(Protocol.keys_uri, :read, request_options)
     end
 
+    #
     # Get ACL of a user key
     #
     # @param request_options contains extra parameters to send with your query
+    #
     def get_api_key(key, request_options = {})
       get(Protocol.key_uri(key), :read, request_options)
     end
 
     #
@@ -261,11 +274,11 @@
     #    - deleteObject : allows to delete an existing object (https only)
     #    - deleteIndex : allows to delete index content (https only)
     #    - settings : allows to get index settings (https only)
     #    - editSettings : allows to change index settings (https only)
     #
-    #  @param obj The list of parameters for this key.
+    #  @param object The list of parameters for this key.
     #         Defined by a Hash that can contain the following values:
     #          - acl: array of string
     #          - indexes: array of string
     #          - validity: int
     #          - referers: array of string
@@ -273,53 +286,46 @@
     #          - maxHitsPerQuery: integer
     #          - queryParameters: string
     #          - maxQueriesPerIPPerHour: integer
     #  @param request_options contains extra parameters to send with your query - Default = {}
     #
-    def add_api_key(obj, request_options = {}, maxQueriesPerIPPerHour = 0, maxHitsPerQuery = 0, indexes = nil)
-      if obj.instance_of? Array
-        params = {
-          :acl => obj
-        }
+    def add_api_key(object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil)
+      if object.instance_of?(Array)
+        params = { :acl => object }
       else
-        params = obj
+        params = object
       end
 
       validity = 0
       unless request_options.is_a?(Hash)
         validity = request_options
         request_options = {}
       end
 
-      if validity != 0
-        params['validity'] = validity.to_i
-      end
-      if maxQueriesPerIPPerHour != 0
-        params['maxQueriesPerIPPerHour'] = maxQueriesPerIPPerHour.to_i
-      end
-      if maxHitsPerQuery != 0
-        params['maxHitsPerQuery'] = maxHitsPerQuery.to_i
-      end
       params[:indexes] = indexes if indexes
+      params['validity'] = validity.to_i if validity != 0
+      params['maxHitsPerQuery'] = max_hits_per_query.to_i if max_hits_per_query != 0
+      params['maxQueriesPerIPPerHour'] = max_queries_per_IP_per_hour.to_i if max_queries_per_IP_per_hour != 0
+
       post(Protocol.keys_uri, params.to_json, :write, request_options)
     end
 
     #
     #  Update a user key
     #
-    #  Deprecated call was update_api_key(key, acl, validity, maxQueriesPerIPPerHour, maxHitsPerQuery, indexes)
+    #  Deprecated call was update_api_key(key, acl, validity, max_queries_per_IP_per_hour, max_hits_per_query, indexes)
     #
     #  ACL can contain an array with those strings:
     #    - search: allow to search (https and http)
     #    - addObject: allows to add/update an object in the index (https only)
     #    - deleteObject : allows to delete an existing object (https only)
     #    - deleteIndex : allows to delete index content (https only)
     #    - settings : allows to get index settings (https only)
     #    - editSettings : allows to change index settings (https only)
     #
     #  @param key API Key to update
-    #  @param obj The list of parameters for this key.
+    #  @param object The list of parameters for this key.
     #         Defined by a Hash that can contain the following values:
     #          - acl: array of string
     #          - indexes: array of string
     #          - validity: int
     #          - referers: array of string
@@ -327,63 +333,61 @@
     #          - maxHitsPerQuery: integer
     #          - queryParameters: string
     #          - maxQueriesPerIPPerHour: integer
     #  @param request_options contains extra parameters to send with your query - Default = {}
     #
-    def update_api_key(key, obj, request_options = {}, maxQueriesPerIPPerHour = 0, maxHitsPerQuery = 0, indexes = nil)
-      if obj.instance_of? Array
-        params = {
-          :acl => obj
-        }
+    def update_api_key(key, object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil)
+      if object.instance_of?(Array)
+        params = { :acl => object }
       else
-        params = obj
+        params = object
       end
 
       validity = 0
       unless request_options.is_a?(Hash)
         validity = request_options
         request_options = {}
       end
 
-      if validity != 0
-        params['validity'] = validity.to_i
-      end
-      if maxQueriesPerIPPerHour != 0
-        params['maxQueriesPerIPPerHour'] = maxQueriesPerIPPerHour.to_i
-      end
-      if maxHitsPerQuery != 0
-        params['maxHitsPerQuery'] = maxHitsPerQuery.to_i
-      end
       params[:indexes] = indexes if indexes
+      params['validity'] = validity.to_i if validity != 0
+      params['maxQueriesPerIPPerHour'] = max_queries_per_IP_per_hour.to_i if max_queries_per_IP_per_hour != 0
+      params['maxHitsPerQuery'] = max_hits_per_query.to_i if max_hits_per_query != 0
+
       put(Protocol.key_uri(key), params.to_json, :write, request_options)
     end
 
+    #
     # Delete an existing user key
     #
     def delete_api_key(key, request_options = {})
       delete(Protocol.key_uri(key), :write, request_options)
     end
 
+    #
     # Send a batch request targeting multiple indices
     #
-    def batch(requests, request_options = {})
-      post(Protocol.batch_uri, {"requests" => requests}.to_json, :batch, request_options)
+    def batch(operations, request_options = {})
+      post(Protocol.batch_uri, { 'requests' => operations }.to_json, :batch, request_options)
     end
 
+    #
     # Send a batch request targeting multiple indices and wait the end of the indexing
     #
-    def batch!(requests, request_options = {})
-      res = batch(requests, request_options)
+    def batch!(operations, request_options = {})
+      res = batch(operations, request_options)
       res['taskID'].each do |index, taskID|
         init_index(index).wait_task(taskID, WAIT_TASK_DEFAULT_TIME_BEFORE_RETRY, request_options)
       end
     end
 
+    #
     # Perform an HTTP request for the given uri and method
     # with common basic response handling. Will raise a
     # AlgoliaProtocolError if the response has an error status code,
     # and will return the parsed JSON body on success, if there is one.
+    #
     def request(uri, method, data = nil, type = :write, request_options = {})
       exceptions = []
 
       connect_timeout = @connect_timeout
       send_timeout = if type == :search
@@ -437,11 +441,13 @@
       request(uri, :DELETE, nil, type, request_options)
     end
 
     private
 
+    #
     # This method returns a thread-local array of sessions
+    #
     def thread_local_hosts(read)
       thread_hosts_key = read ? "algolia_search_hosts_#{application_id}" : "algolia_hosts_#{application_id}"
       Thread.current[thread_hosts_key] ||= (read ? search_hosts : hosts).each_with_index.map do |host, i|
         client = HTTPClient.new
         client.ssl_config.ssl_version = @ssl_version if @ssl && @ssl_version
@@ -525,11 +531,13 @@
     Algolia.client.set_extra_header(key, value)
   end
 
   #
   # Allow to use IP rate limit when you have a proxy between end-user and Algolia.
-  # This option will set the X-Forwarded-For HTTP header with the client IP and the X-Forwarded-API-Key with the API Key having rate limits.
+  # This option will set the X-Forwarded-For HTTP header with the client IP and the
+  # X-Forwarded-API-Key with the API Key having rate limits.
+  #
   # @param admin_api_key the admin API Key you can find in your dashboard
   # @param end_user_ip the end user IP (you can use both IPV4 or IPV6 syntax)
   # @param rate_limit_api_key the API key on which you have a rate limit
   #
   def Algolia.enable_rate_limit_forward(admin_api_key, end_user_ip, rate_limit_api_key)
@@ -558,11 +566,11 @@
   # @param tag_filters the list of tags applied to the query (used as security)
   # @param user_token an optional token identifying the current user
   #
   def Algolia.generate_secured_api_key(private_api_key, tag_filters_or_params, user_token = nil)
     if tag_filters_or_params.is_a?(Hash) && user_token.nil?
-      encoded_params = Hash[tag_filters_or_params.map { |k,v| [k.to_s, v.is_a?(Array) ? v.to_json : v] }]
+      encoded_params = Hash[tag_filters_or_params.map { |k, v| [k.to_s, v.is_a?(Array) ? v.to_json : v] }]
       query_str = Protocol.to_query(encoded_params)
       hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), private_api_key, query_str)
       Base64.encode64("#{hmac}#{query_str}").gsub("\n", '')
     else
       tag_filters = if tag_filters_or_params.is_a?(Array)
@@ -594,56 +602,62 @@
     Algolia.client.list_indexes(request_options)
   end
 
   #
   # Move an existing index.
+  #
   # @param src_index the name of index to copy.
-  # @param dst_index the new index name that will contains a copy of srcIndexName (destination will be overriten if it already exist).
+  # @param dst_index the new index name that will contains a copy of src_index_name (destination will be overriten if it already exist).
   # @param request_options contains extra parameters to send with your query
   #
   def Algolia.move_index(src_index, dst_index, request_options = {})
     Algolia.client.move_index(src_index, dst_index, request_options)
   end
 
   #
   # Move an existing index and wait until the move has been processed
+  #
   # @param src_index the name of index to copy.
-  # @param dst_index the new index name that will contains a copy of srcIndexName (destination will be overriten if it already exist).
+  # @param dst_index the new index name that will contains a copy of src_index_name (destination will be overriten if it already exist).
   # @param request_options contains extra parameters to send with your query
   #
   def Algolia.move_index!(src_index, dst_index, request_options = {})
     Algolia.client.move_index!(src_index, dst_index, request_options)
   end
 
   #
   # Copy an existing index.
+  #
   # @param src_index the name of index to copy.
-  # @param dst_index the new index name that will contains a copy of srcIndexName (destination will be overriten if it already exist).
+  # @param dst_index the new index name that will contains a copy of src_index_name (destination will be overriten if it already exist).
   # @param scope the optional list of scopes to copy (all if not specified).
   # @param request_options contains extra parameters to send with your query
   #
   def Algolia.copy_index(src_index, dst_index, scope = nil, request_options = {})
     Algolia.client.copy_index(src_index, dst_index, scope, request_options)
   end
 
   #
   # Copy an existing index and wait until the copy has been processed.
+  #
   # @param src_index the name of index to copy.
-  # @param dst_index the new index name that will contains a copy of srcIndexName (destination will be overriten if it already exist).
+  # @param dst_index the new index name that will contains a copy of src_index_name (destination will be overriten if it already exist).
   # @param scope the optional list of scopes to copy (all if not specified).
   # @param request_options contains extra parameters to send with your query
   #
   def Algolia.copy_index!(src_index, dst_index, scope = nil, request_options = {})
     Algolia.client.copy_index!(src_index, dst_index, scope, request_options)
   end
 
+  #
   # Delete an index
   #
   def Algolia.delete_index(name, request_options = {})
     Algolia.client.delete_index(name, request_options)
   end
 
+  #
   # Delete an index and wait until the deletion has been processed.
   #
   def Algolia.delete_index!(name, request_options = {})
     Algolia.client.delete_index!(name, request_options)
   end
@@ -658,133 +672,155 @@
   #
   def Algolia.get_logs(options = nil, length = nil, type = nil)
     Algolia.client.get_logs(options, length, type)
   end
 
+  #
   # List all existing user keys with their associated ACLs
   #
   # @param request_options contains extra parameters to send with your query
+  #
   def Algolia.list_api_keys(request_options = {})
     Algolia.client.list_api_keys(request_options)
   end
 
+  #
   # Deprecated
+  #
   def Algolia.list_user_keys(request_options = {})
     Algolia.client.list_api_keys(request_options)
   end
 
+  #
   # Get ACL of a user key
   #
   # @param request_options contains extra parameters to send with your query
+  #
   def Algolia.get_api_key(key, request_options = {})
     Algolia.client.get_api_key(key, request_options)
   end
 
+  #
   # Deprecated
+  #
   def Algolia.get_user_key(key, request_options = {})
     Algolia.client.get_user_key(key, request_options)
   end
 
   #
   #  Create a new user key
   #
-  #  Deprecated call was add_api_key(acl, validity, maxQueriesPerIPPerHour, maxHitsPerQuery, indexes)
+  #  Deprecated call was add_api_key(acl, validity, max_queries_per_IP_per_hour, max_hits_per_query, indexes)
   #
   #  ACL can contain an array with those strings:
   #    - search: allow to search (https and http)
   #    - addObject: allows to add/update an object in the index (https only)
   #    - deleteObject : allows to delete an existing object (https only)
   #    - deleteIndex : allows to delete index content (https only)
   #    - settings : allows to get index settings (https only)
   #    - editSettings : allows to change index settings (https only)
   #
-  #  @param obj can be two different parameters:
+  #  @param object can be two different parameters:
   #        The list of parameters for this key. Defined by a NSDictionary that
   #        can contains the following values:
   #          - acl: array of string
   #          - indexes: array of string
   #          - validity: int
   #          - referers: array of string
   #          - description: string
-  #          - maxHitsPerQuery: integer
+  #          - max_hits_per_query: integer
   #          - queryParameters: string
-  #          - maxQueriesPerIPPerHour: integer
+  #          - max_queries_per_IP_per_hour: integer
   #  @param request_options contains extra parameters to send with your query - Default = {}
   #
-  def Algolia.add_api_key(obj, request_options = {}, maxQueriesPerIPPerHour = 0, maxHitsPerQuery = 0, indexes = nil)
-    Algolia.client.add_api_key(obj, request_options, maxQueriesPerIPPerHour, maxHitsPerQuery, indexes)
+  def Algolia.add_api_key(object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil)
+    Algolia.client.add_api_key(object, request_options, max_queries_per_IP_per_hour, max_hits_per_query, indexes)
   end
 
+  #
   # Deprecated
-  def Algolia.add_user_key(obj, request_options = {}, maxQueriesPerIPPerHour = 0, maxHitsPerQuery = 0, indexes = nil)
-    Algolia.client.add_api_key(obj, request_options, maxQueriesPerIPPerHour, maxHitsPerQuery, indexes)
+  #
+  def Algolia.add_user_key(object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil)
+    Algolia.client.add_api_key(object, request_options, max_queries_per_IP_per_hour, max_hits_per_query, indexes)
   end
 
   #
   #  Update a user key
   #
-  #  Deprecated call was update_api_key(key, acl, validity, maxQueriesPerIPPerHour, maxHitsPerQuery, indexes)
+  #  Deprecated call was update_api_key(key, acl, validity, maxQueriesPerIPPerHour, max_hits_per_query, indexes)
   #
   #  ACL can contain an array with those strings:
   #    - search: allow to search (https and http)
   #    - addObject: allows to add/update an object in the index (https only)
   #    - deleteObject : allows to delete an existing object (https only)
   #    - deleteIndex : allows to delete index content (https only)
   #    - settings : allows to get index settings (https only)
   #    - editSettings : allows to change index settings (https only)
   #
   #  @param key API Key to update
-  #  @param obj The list of parameters for this key.
+  #  @param object The list of parameters for this key.
   #         Defined by a Hash that can contain the following values:
   #          - acl: array of string
   #          - indexes: array of string
   #          - validity: int
   #          - referers: array of string
   #          - description: string
-  #          - maxHitsPerQuery: integer
+  #          - max_hits_per_query: integer
   #          - queryParameters: string
-  #          - maxQueriesPerIPPerHour: integer
+  #          - max_queries_per_IP_per_hour: integer
   #  @param request_options contains extra parameters to send with your query - Default = {}
   #
-  def Algolia.update_api_key(key, obj, request_options = {}, maxQueriesPerIPPerHour = 0, maxHitsPerQuery = 0, indexes = nil)
-    Algolia.client.update_api_key(key, obj, request_options, maxQueriesPerIPPerHour, maxHitsPerQuery, indexes)
+  def Algolia.update_api_key(key, object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil)
+    Algolia.client.update_api_key(key, object, request_options, max_queries_per_IP_per_hour, max_hits_per_query, indexes)
   end
 
+  #
   # Deprecated
-  def Algolia.update_user_key(key, obj, request_options = {}, maxQueriesPerIPPerHour = 0, maxHitsPerQuery = 0, indexes = nil)
-    Algolia.client.update_api_key(key, obj, request_options, maxQueriesPerIPPerHour, maxHitsPerQuery, indexes)
+  #
+  def Algolia.update_user_key(key, object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil)
+    Algolia.client.update_api_key(key, object, request_options, max_queries_per_IP_per_hour, max_hits_per_query, indexes)
   end
 
+  #
   # Delete an existing user key
+  #
   def Algolia.delete_api_key(key, request_options = {})
     Algolia.client.delete_api_key(key, request_options)
   end
 
+  #
   # Deprecated
+  #
   def Algolia.delete_user_key(key, request_options = {})
     Algolia.client.delete_api_key(key, request_options)
   end
 
+  #
   # Send a batch request targeting multiple indices
+  #
   def Algolia.batch(requests, request_options = {})
     Algolia.client.batch(requests, request_options)
   end
 
+  #
   # Send a batch request targeting multiple indices and wait the end of the indexing
+  #
   def Algolia.batch!(requests, request_options = {})
     Algolia.client.batch!(requests, request_options)
   end
 
+  #
   # Used mostly for testing. Lets you delete the api key global vars.
+  #
   def Algolia.destroy
     @@client.destroy unless @@client.nil?
     @@client = nil
     self
   end
 
   def Algolia.client
     if !@@client
-      raise AlgoliaError, "API not initialized"
+      raise AlgoliaError, 'API not initialized'
     end
     @@client
   end
 
 end