algoliasearch 1.1.16 → 1.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9a5b805f07b381464702a5730df66afaf269deab
-  data.tar.gz: 20ec0ac8649ed6260de80004ffc71bda15f04f3c
+  metadata.gz: 14d536f146b031e91b22b0fa8fd6ae490d5313ca
+  data.tar.gz: 6363a928bb6e679e51b55e73fffdc5b8fdea4b6a
 SHA512:
-  metadata.gz: ca22ebe2ea6f5bf41069c668119981da77bb2f36b982b1f4b12a8097bf0fcce98944664fd4f8d9ced69211eaca2f6ed56c6a171fc2544e6b05c873de1896363f
-  data.tar.gz: 0502436b3c8f7ba247595b97aa7ac3d47ba172631dfd2267e8804544524ccbcac2161c76eee07473f407d3dc3b0b40109b62be5a91a643214da4b9b7ed69922f
+  metadata.gz: d618bbb9d33e9af749ba5a0b5a61bb7c94f3c3af1680d28969eb080df1ebc3abb9ccc48f5bb7e0c455eca13ba4080a8af18ea82c955c0ac00f58644253be1fba
+  data.tar.gz: 4492f1024fe3bdaeacc0523ea0d3e99cc63db2d03cbbc8c8ab5a19cc58b8bcad18f790a23708744e91b9db14d9ba5fe69badfc06bb41c2ccc434d27c31d3777e

data/ChangeLog

@@ -1,5 +1,10 @@
 CHANGELOG
 
+2014-01-02  1.1.17
+
+      * Ability to use IP rate limit behind a proxy forwarding the end-user's IP
+      * Add documentation for the new 'attributeForDistinct' setting and 'distinct' search parameter
+
 2013-12-16  1.1.16
 
       * Add arguments type-checking

data/README.md

@@ -148,6 +148,9 @@ You can use the following optional arguments:
  * **facetFilters**: filter the query by a list of facets. Facets are separated by commas and each facet is encoded as `attributeName:value`. For example: `facetFilters=category:Book,author:John%20Doe`. You can also use a string array encoding (for example `["category:Book","author:John%20Doe"]`).
  * **facets**: List of object attributes that you want to use for faceting. <br/>Attributes are separated with a comma (for example `"category,author"` ). You can also use a JSON string array encoding (for example `["category","author"]` ). Only attributes that have been added in **attributesForFaceting** index setting can be used in this parameter. You can also use `*` to perform faceting on all attributes specified in **attributesForFaceting**.
 
+#### Distinct parameter
+ * **distinct**: If set to 1, enable the distinct feature (disabled by default) if the `attributeForDistinct` index setting is set. This feature is similar to the SQL "distinct" keyword: when enabled in a query with the `distinct=1` parameter, all hits containing a duplicate value for the attributeForDistinct attribute are removed from results. For example, if the chosen attribute is `show_name` and several hits have the same value for `show_name`, then only the best one is kept and others are removed.
+
 ```ruby
 index = Algolia::Index.new("contacts")
 res = index.search("query string")
@@ -273,6 +276,7 @@ You can retrieve all settings using the `getSettings` function. The result will
   * *Limit the attributes to index*.<br/>For example if you store a binary image in base64, you want to store it and be able to retrieve it but you don't want to search in the base64 string.
   * *Control part of the ranking*.<br/>(see the ranking parameter for full explanation) Matches in attributes at the beginning of the list will be considered more important than matches in attributes further down the list. In one attribute, matching text at the beginning of the attribute will be considered more important than text after, you can disable this behavior if you add your attribute inside `unordered(AttributeName)`, for example `attributesToIndex: ["title", "unordered(text)"]`.
  * **attributesForFaceting**: (array of strings) The list of fields you want to use for faceting. All strings in the attribute selected for faceting are extracted and added as a facet. If set to null, no attribute is used for faceting.
+ * **attributeForDistinct**: The attribute name used for the `Distinct` feature. This feature is similar to the SQL "distinct" keyword: when enabled in query with the `distinct=1` parameter, all hits containing a duplicate value for this attribute are removed from results. For example, if the chosen attribute is `show_name` and several hits have the same value for `show_name, then only the best one is kept and others are removed.
  * **ranking**: (array of strings) controls the way results are sorted.<br/>We have six available criteria: 
   * **typo**: sort according to number of typos,
   * **geo**: sort according to decreassing distance when performing a geo-location based search,
@@ -422,6 +426,8 @@ You can also create an API Key with advanced restrictions:
 
  * Add a validity period: the key will be valid only for a specific period of time (in seconds),
  * Specify the maximum number of API calls allowed from an IP address per hour. Each time an API call is performed with this key, a check is performed. If the IP at the origin of the call did more than this number of calls in the last hour, a 403 code is returned. Defaults to 0 (no rate limit). This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
+
+  Note: If you are sending the query through your servers, you must use the `Algolia.enable_rate_limit_forward("TheAdminAPIKey", "EndUserIP", "APIKeyWithRateLimit")` function to enable rate-limit.
  * Specify the maximum number of hits this API key can retrieve in one call. Defaults to 0 (unlimited). This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
 
 ```ruby

data/algoliasearch.gemspec

@@ -2,15 +2,15 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: algoliasearch 1.1.16 ruby lib
+# stub: algoliasearch 1.1.17 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "algoliasearch"
-  s.version = "1.1.16"
+  s.version = "1.1.17"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Algolia"]
-  s.date = "2013-12-20"
+  s.date = "2014-01-02"
   s.description = "A simple Ruby client for the algolia.com REST API"
   s.email = "contact@algolia.com"
   s.extra_rdoc_files = [
@@ -39,7 +39,8 @@ Gem::Specification.new do |s|
     "resources/ca-bundle.crt",
     "spec/client_spec.rb",
     "spec/mock_spec.rb",
-    "spec/spec_helper.rb"
+    "spec/spec_helper.rb",
+    "spec/stub_spec.rb"
   ]
   s.homepage = "http://github.com/algolia/algoliasearch-client-ruby"
   s.licenses = ["MIT"]

data/lib/algolia/client.rb

@@ -72,8 +72,6 @@ module Algolia
       request(uri, :DELETE)
     end
 
-    private
-
     # this method returns a thread-local array of sessions
     def thread_local_hosts
       if Thread.current[:algolia_hosts].nil?
@@ -108,12 +106,55 @@ module Algolia
   # Initialize the singleton instance of Client which is used
   # by all API methods.
   def Algolia.init(options = {})
-    defaulted = { :api_id => ENV["ALGOLIA_API_ID"], :api_key => ENV["ALGOLIA_REST_API_KEY"] }
+    application_id = ENV["ALGOLIA_API_ID"] || ENV["ALGOLIA_APPLICATION_ID"]
+    api_key = ENV["ALGOLIA_REST_API_KEY"] || ENV['ALGOLIA_API_KEY']
+
+    defaulted = { :application_id => application_id, :api_key => api_key }
     defaulted.merge!(options)
 
     @@client = Client.new(defaulted)
   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 Algolia.enable_rate_limit_forward(admin_api_key, end_user_ip, rate_limit_api_key)
+    Algolia.client.thread_local_hosts.each do |host|
+      session = host["session"]
+      session.headers[Protocol::HEADER_API_KEY] = admin_api_key
+      session.headers[Protocol::HEADER_FORWARDED_IP] = end_user_ip
+      session.headers[Protocol::HEADER_FORWARDED_API_KEY] = rate_limit_api_key
+    end
+  end
+
+  #
+  # Disable IP rate limit enabled with enableRateLimitForward() function
+  #
+  def Algolia.disable_rate_limit_forward
+    Algolia.client.thread_local_hosts.each do |host|
+      session = host["session"]
+      session.headers[Protocol::HEADER_API_KEY] = Algolia.client.api_key
+      session.headers.delete(Protocol::HEADER_FORWARDED_IP)
+      session.headers.delete(Protocol::HEADER_FORWARDED_API_KEY)
+    end
+  end
+
+  #
+  # Convenience method thats wraps enable_rate_limit_forward/disable_rate_limit_forward
+  #
+  def Algolia.with_rate_limits(end_user_ip, rate_limit_api_key, &block)
+    Algolia.enable_rate_limit_forward(Algolia.client.api_key, end_user_ip, rate_limit_api_key)
+    begin
+      yield
+    ensure
+      Algolia.disable_rate_limit_forward
+    end
+  end
+
   #
   # List all existing indexes
   # return an Answer object with answer in the form 
@@ -126,8 +167,8 @@ module Algolia
 
   #
   # Move an existing index.
-  # @param srcIndexName the name of index to copy.
-  # @param dstIndexName the new index name that will contains a copy of srcIndexName (destination will be overriten if it already exist).
+  # @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).
   #
   def Algolia.move_index(src_index, dst_index)
       request = {"operation" => "move", "destination" => dst_index};
@@ -136,8 +177,8 @@ module Algolia
 
   #
   # Copy an existing index.
-  # @param srcIndexName the name of index to copy.
-  # @param dstIndexName the new index name that will contains a copy of srcIndexName (destination will be overriten if it already exist).
+  # @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).
   #
   def Algolia.copy_index(src_index, dst_index)
       request = {"operation" => "copy", "destination" => dst_index};

data/lib/algolia/index.rb

@@ -124,7 +124,12 @@ module Algolia
     #    - prefixLast: only the last word is interpreted as a prefix (default behavior),
     #    - prefixNone: no query word is interpreted as a prefix. This option is not recommended.
     # - optionalWords: a string that contains the list of words that should be considered as optional when found in the query. 
-    #   The list of words is comma separated.    #
+    #   The list of words is comma separated.
+    # - distinct: If set to 1, enable the distinct feature (disabled by default) if the attributeForDistinct index setting is set. 
+    #   This feature is similar to the SQL "distinct" keyword: when enabled in a query with the distinct=1 parameter, 
+    #   all hits containing a duplicate value for the attributeForDistinct attribute are removed from results. 
+    #   For example, if the chosen attribute is show_name and several hits have the same value for show_name, then only the best 
+    #   one is kept and others are removed.
     def search(query, params = {})
       encoded_params = Hash[params.map { |k,v| [k.to_s, v.is_a?(Array) ? v.to_json : v] }]
       Algolia.client.get(Protocol.search_uri(name, query, encoded_params))
@@ -336,13 +341,20 @@ module Algolia
     #       this behavior if you add your attribute inside `unordered(AttributeName)`, for example attributesToIndex: ["title", "unordered(text)"].
     # - attributesForFaceting: (array of strings) The list of fields you want to use for faceting. 
     #   All strings in the attribute selected for faceting are extracted and added as a facet. If set to null, no attribute is used for faceting.
+    # - attributeForDistinct: (string) The attribute name used for the Distinct feature. This feature is similar to the SQL "distinct" keyword: when enabled 
+    #   in query with the distinct=1 parameter, all hits containing a duplicate value for this attribute are removed from results. 
+    #   For example, if the chosen attribute is show_name and several hits have the same value for show_name, then only the best one is kept and others are removed.
     # - ranking: (array of strings) controls the way results are sorted.
     #   We have six available criteria: 
     #    - typo: sort according to number of typos,
     #    - geo: sort according to decreassing distance when performing a geo-location based search,
     #    - proximity: sort according to the proximity of query words in hits,
     #    - attribute: sort according to the order of attributes defined by attributesToIndex,
-    #    - exact: sort according to the number of words that are matched identical to query word (and not as a prefix),
+    #    - exact: 
+    #        - if the user query contains one word: sort objects having an attribute that is exactly the query word before others. 
+    #          For example if you search for the "V" TV show, you want to find it with the "V" query and avoid to have all popular TV 
+    #          show starting by the v letter before it.
+    #        - if the user query contains multiple words: sort according to the number of words that matched exactly (and not as a prefix).
     #    - custom: sort according to a user defined formula set in **customRanking** attribute.
     #   The standard order is ["typo", "geo", "proximity", "attribute", "exact", "custom"]
     # - customRanking: (array of strings) lets you specify part of the ranking.

data/lib/algolia/protocol.rb

@@ -20,6 +20,10 @@ module Algolia
     # Algolia API.
     HEADER_API_KEY  = "X-Algolia-API-Key"
     
+    HEADER_FORWARDED_IP = "X-Forwarded-For"
+
+    HEADER_FORWARDED_API_KEY = "X-Forwarded-API-Key"
+    
     # HTTP ERROR CODES
     # ----------------------------------------
 

data/lib/algolia/version.rb

@@ -1,3 +1,3 @@
 module Algolia
-  VERSION = "1.1.16"
+  VERSION = "1.1.17"
 end

data/spec/stub_spec.rb

@@ -0,0 +1,46 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'spec_helper'))
+
+require 'webmock'
+
+describe 'With a rate limited client' do
+
+  before(:each) do
+    WebMock.enable!
+    Thread.current[:algolia_hosts] = nil
+  end
+
+  it "should pass the right headers" do
+    WebMock.stub_request(:get, %r{https://.*\.algolia\.io/1/indexes/friends\?query=.*}).
+      with(:headers => {'Content-Type'=>'application/json; charset=utf-8', 'User-Agent'=>"Algolia for Ruby #{Algolia::VERSION}", 'X-Algolia-Api-Key'=>ENV['ALGOLIA_API_KEY'], 'X-Algolia-Application-Id'=>ENV['ALGOLIA_APPLICATION_ID'], 'X-Forwarded-Api-Key'=>'ratelimitapikey', 'X-Forwarded-For'=>'1.2.3.4'}).
+      to_return(:status => 200, :body => "{ \"hits\": [], \"fakeAttribute\": 1 }", :headers => {})
+    Algolia.enable_rate_limit_forward ENV['ALGOLIA_API_KEY'], "1.2.3.4", "ratelimitapikey"
+    index = Algolia::Index.new("friends")
+    index.search('foo')['fakeAttribute'].should == 1
+    index.search('bar')['fakeAttribute'].should == 1
+  end
+
+  it "should use original headers" do
+    WebMock.stub_request(:get, %r{https://.*\.algolia\.io/1/indexes/friends\?query=.*}).
+      with(:headers => {'Content-Type'=>'application/json; charset=utf-8', 'User-Agent'=>"Algolia for Ruby #{Algolia::VERSION}", 'X-Algolia-Api-Key'=>ENV['ALGOLIA_API_KEY'], 'X-Algolia-Application-Id'=>ENV['ALGOLIA_APPLICATION_ID'] }).
+      to_return(:status => 200, :body => "{ \"hits\": [], \"fakeAttribute\": 2 }", :headers => {})    
+    Algolia.disable_rate_limit_forward
+    index = Algolia::Index.new("friends")
+    index.search('bar')['fakeAttribute'].should == 2
+  end
+
+  it "should pass the right headers in the scope" do
+    WebMock.stub_request(:get, %r{https://.*\.algolia\.io/1/indexes/friends\?query=.*}).
+      with(:headers => {'Content-Type'=>'application/json; charset=utf-8', 'User-Agent'=>"Algolia for Ruby #{Algolia::VERSION}", 'X-Algolia-Api-Key'=>ENV['ALGOLIA_API_KEY'], 'X-Algolia-Application-Id'=>ENV['ALGOLIA_APPLICATION_ID'], 'X-Forwarded-Api-Key'=>'ratelimitapikey', 'X-Forwarded-For'=>'1.2.3.4'}).
+      to_return(:status => 200, :body => "{ \"hits\": [], \"fakeAttribute\": 1 }", :headers => {})
+    Algolia.with_rate_limits "1.2.3.4", "ratelimitapikey" do
+      index = Algolia::Index.new("friends")
+      index.search('foo')['fakeAttribute'].should == 1
+      index.search('bar')['fakeAttribute'].should == 1
+    end
+  end
+
+  after(:each) do
+    WebMock.disable!
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: algoliasearch
 version: !ruby/object:Gem::Version
-  version: 1.1.16
+  version: 1.1.17
 platform: ruby
 authors:
 - Algolia
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-20 00:00:00.000000000 Z
+date: 2014-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: curb
@@ -96,6 +96,7 @@ files:
 - spec/client_spec.rb
 - spec/mock_spec.rb
 - spec/spec_helper.rb
+- spec/stub_spec.rb
 homepage: http://github.com/algolia/algoliasearch-client-ruby
 licenses:
 - MIT