kernow-ruby-aaws 0.5.4 → 0.7.1

data/lib/amazon/aws/search.rb

@@ -1,4 +1,4 @@
-# $Id: search.rb,v 1.26 2008/09/21 22:17:32 ianmacd Exp $
+# $Id: search.rb,v 1.43 2009/06/14 22:28:27 ianmacd Exp $
 #
 
 module Amazon
@@ -8,6 +8,7 @@ module Amazon
     require 'amazon/aws'
     require 'net/http'
     require 'rexml/document'
+    require 'openssl'
 
     # Load this library with:
     #
@@ -27,15 +28,31 @@ module Amazon
 	#
 	class LocaleError < Amazon::AWS::Error::AWSError; end
 
-	attr_reader :conn, :locale, :user_agent
+	# Do we have support for the SHA-256 Secure Hash Algorithm?
+	#
+	# Note that Module#constants returns Strings in Ruby 1.8 and Symbols
+	# in 1.9.
+	#
+	DIGEST_SUPPORT = OpenSSL::Digest.constants.include?( 'SHA256' ) ||
+			 OpenSSL::Digest.constants.include?( :SHA256 )
+
+	# Requests are authenticated using the SHA-256 Secure Hash Algorithm.
+	#
+	DIGEST = OpenSSL::Digest::Digest.new( 'sha256' ) if DIGEST_SUPPORT
+
+	attr_reader :conn, :config, :locale, :query, :user_agent
 	attr_writer :cache
+	attr_accessor :encoding, :cache_dir
 
 	# This method is used to generate an AWS search request object.
 	#
 	# _key_id_ is your AWS {access key
-	# ID}[https://aws-portal.amazon.com/gp/aws/developer/registration/index.html],
+	# ID}[https://aws-portal.amazon.com/gp/aws/developer/registration/index.html].
+	# Note that your secret key, used for signing requests, can be
+	# specified only in your <tt>~/.amazonrc</tt> configuration file.
+	#
 	# _associate_ is your
-	# Associates[http://docs.amazonwebservices.com/AWSECommerceService/2008-04-07/GSG/BecominganAssociate.html]
+	# Associates[http://docs.amazonwebservices.com/AWSECommerceService/2009-03-31/GSG/BecominganAssociate.html]
 	# tag (if any), _locale_ is the locale in which you which to work
 	# (*us* for amazon.com[http://www.amazon.com/], *uk* for
 	# amazon.co.uk[http://www.amazon.co.uk], etc.), _cache_ is whether or
@@ -62,7 +79,7 @@ module Amazon
 
 	  key_id ||= @config['key_id']
 	  cache = @config['cache'] if cache.nil?
-	  cache_dir ||= @config['cache_dir']
+	  @cache_dir = cache_dir.nil? ? @config['cache_dir'] : cache_dir
 
 	  # Take locale from config file if no locale was passed to method.
 	  #
@@ -79,10 +96,17 @@ module Amazon
 	  @tag	      = associate || @config['associate'] || DEF_ASSOC[locale]
 	  @user_agent = user_agent
 	  @cache      = unless cache == 'false' || cache == false
-			  Amazon::AWS::Cache.new( cache_dir )
+			  Amazon::AWS::Cache.new( @cache_dir )
 			else
 			  nil
 			end
+
+	  # Set the following two variables from the config file. Will be
+	  # *nil* if not present in config file.
+	  #
+	  @api	      = @config['api']
+	  @encoding   = @config['encoding']
+
 	  self.locale = locale
 	end
 
@@ -102,6 +126,10 @@ module Amazon
 	    @tag = Amazon::AWS::DEF_ASSOC[@locale]
 	  end
 
+	  if @config.key?( @locale ) && @config[@locale].key?( 'associate' )
+	    @tag = @config[@locale]['associate']
+	  end
+
 	  # We must now set up a new HTTP connection to the correct server for
 	  # this locale, unless the same server is used for both.
 	  #
@@ -119,7 +147,7 @@ module Amazon
 	#
 	def cache  # :nodoc:
 	  if @cache == true
-	    @cache = Amazon::AWS::Cache.new( @config['cache_dir'] )
+	    @cache = Amazon::AWS::Cache.new( @cache_dir )
 	  else
 	    @cache
 	  end
@@ -167,19 +195,76 @@ module Amazon
 	# _xml_ is the XML node below which to search.
 	#
 	def error_check(xml)
-	  if xml = xml.elements['Errors/Error']
+	  if ! xml.nil? && xml = xml.elements['Errors/Error']
 	    raise Amazon::AWS::Error.exception( xml )
 	  end
 	end
 	private :error_check
 
 
-	# Perform a search of the AWS database. _operation_ is one of the
-	# objects subclassed from _Operation_, such as _ItemSearch_,
-	# _ItemLookup_, etc. It may also be a _MultipleOperation_ object.
+	# Add a timestamp to a request object's query string.
 	#
-	# _response_group_ will apply to all both operations contained in
-	# _operation_, if _operation_ is a _MultipleOperation_ object.
+	def timestamp
+	  @query << '&Timestamp=%s' %
+	    [ Amazon.url_encode(
+		Time.now.utc.strftime( '%Y-%m-%dT%H:%M:%SZ' ) ) ]
+	end
+	private :timestamp
+
+
+	# Add a signature to a request object's query string. This implicitly
+	# also adds a timestamp.
+	#
+	def sign
+	  return false unless DIGEST_SUPPORT
+
+	  timestamp
+	  params = @query[1..-1].split( '&' ).sort.join( '&' )
+  
+	  sign_str = "GET\n%s\n%s\n%s" % [ ENDPOINT[@locale].host,
+					   ENDPOINT[@locale].path,
+					   params ]
+
+	  Amazon.dprintf( 'Calculating SHA256 HMAC of "%s"...', sign_str )
+
+	  hmac = OpenSSL::HMAC.digest( DIGEST,
+				       @config['secret_key_id'],
+				       sign_str )
+	  Amazon.dprintf( 'SHA256 HMAC is "%s"', hmac.inspect )
+
+	  base64_hmac = [ hmac ].pack( 'm' ).chomp
+	  Amazon.dprintf( 'Base64-encoded HMAC is "%s".', base64_hmac )
+
+	  signature = Amazon.url_encode( base64_hmac )
+
+	  params << '&Signature=%s' % [ signature ]
+	  @query = '?' + params
+
+	  true
+	end
+
+
+	# Perform a search of the AWS database, returning an AWSObject.
+	#
+	# _operation_ is an object of a subclass of _Operation_, such as
+	# _ItemSearch_, _ItemLookup_, etc. It may also be a _MultipleOperation_
+	# object.
+	#
+	# _response_group_, if supplied, is a set of one or more response
+	# groups to use in combination with _operation_ for the purpose of
+	# determining which data sets AWS should return.
+	#
+	# If _response_group_ is *nil*, Ruby/AWS will instead use the response
+	# groups specified by the _@response_group_ attribute of _operation_.
+	# That is now the preferred way of specifying response groups to use
+	# with a given operation. The _response_group_ parameter may later be
+	# removed from this method altogether.
+	#
+	# If _response_group_ is given, it will apply to all sub-operations of
+	# _operation_, if _operation_ is of class MultipleOperation. To use a
+	# different set of response groups for each sub-operation, you should
+	# assign to the _@response_group_ attribute of each of them before
+	# instantiating a MultipleOperation to combine them.
 	#
 	# _nr_pages_ is the number of results pages to return. It defaults to
 	# <b>1</b>. If a higher number is given, pages 1 to _nr_pages_ will be
@@ -189,25 +274,41 @@ module Amazon
 	# The maximum page number that can be returned for each type of
 	# operation is documented in the AWS Developer's Guide:
 	#
-	# http://docs.amazonwebservices.com/AWSECommerceService/2008-08-19/DG/index.html?CHAP_MakingRequestsandUnderstandingResponses.html#PagingThroughResults
+	# http://docs.amazonwebservices.com/AWSECommerceService/2009-03-31/DG/index.html?MaximumNumberofPages.html
 	#
 	# Note that _ItemLookup_ operations can use three separate pagination
 	# parameters. Ruby/AWS, however, uses _OfferPage_ for the purposes of
 	# returning multiple pages.
 	#
 	# If operation is of class _MultipleOperation_, the operations
-	# combined within will return only the first page, regardless of
+	# specified within will return only the first page, regardless of
 	# whether a higher number of pages is requested.
 	#
-	def search(operation, response_group, nr_pages=1)
-	  q_params = Amazon::AWS::SERVICE.
-		       merge( { 'AWSAccessKeyId' => @key_id,
-				'AssociateTag'   => @tag } ).
-		       merge( operation.params ).
-		       merge( response_group.params )
-
-	  query = Amazon::AWS.assemble_query( q_params )
-	  page = Amazon::AWS.get_page( self, query )
+	# If a block is passed to this method, each successive page of results
+	# will be yielded to the block.
+	#
+	def search(operation, response_group=nil, nr_pages=1)
+	  response_group ||=
+	    operation.response_group || ResponseGroup.new( :Large )
+
+	  parameters = Amazon::AWS::SERVICE.
+			 merge( { 'AWSAccessKeyId' => @key_id,
+				  'AssociateTag'   => @tag } ).
+			 merge( operation.params ).
+			 merge( response_group.params )
+
+	  # Check to see whether a particular version of the API has been
+	  # requested. If so, overwrite Version with the new value.
+	  #
+	  parameters.merge!( { 'Version' => @api } ) if @api
+
+	  @query = Amazon::AWS.assemble_query( parameters, @encoding )
+	  page = Amazon::AWS.get_page( self )
+
+	  # Ruby 1.9 needs to know that the page is UTF-8, not ASCII-8BIT.
+	  #
+	  page.force_encoding( 'utf-8' ) if RUBY_VERSION >= '1.9.0'
+
 	  doc = Document.new( page )
 
 	  # Some errors occur at the very top level of the XML. For example,
@@ -216,6 +317,19 @@ module Amazon
 	  #
 	  error_check( doc )
 
+	  # Another possible error results in a document containing nothing
+	  # but <Result>Internal Error</Result>. This occurs when a specific
+	  # version of the AWS API is requested, in combination with an
+	  # operation that did not yet exist in that version of the API.
+	  #
+	  # For example:
+	  #
+	  # http://ecs.amazonaws.com/onca/xml?AWSAccessKeyId=foo&Operation=VehicleSearch&Year=2008&ResponseGroup=VehicleMakes&Service=AWSECommerceService&Version=2008-03-03
+	  #
+	  if xml = doc.elements['Result']
+	    raise Amazon::AWS::Error::AWSError, xml.text
+	  end
+
 	  # Fundamental errors happen at the OperationRequest level. For
 	  # example, if an invalid AWSAccessKeyId is used.
 	  #
@@ -293,9 +407,15 @@ module Amazon
 	  # Iterate over pages 2 and higher, but go no higher than MAX_PAGES.
 	  #
 	  2.upto( nr_pages < max_pages ? nr_pages : max_pages ) do |page_nr|
-	    query = Amazon::AWS.assemble_query(
-		      q_params.merge( { page_parameter => page_nr } ) )
-	    page = Amazon::AWS.get_page( self, query )
+	    @query = Amazon::AWS.assemble_query(
+		      parameters.merge( { page_parameter => page_nr } ),
+		      @encoding)
+	    page = Amazon::AWS.get_page( self )
+
+	    # Ruby 1.9 needs to know that the page is UTF-8, not ASCII-8BIT.
+	    #
+	    page.force_encoding( 'utf-8' ) if RUBY_VERSION >= '1.9.0'
+
 	    doc = Document.new( page )
 
 	    # Check for errors.
@@ -305,7 +425,7 @@ module Amazon
 
 	    # Create a new AWS object and walk the XML response tree.
 	    #
-	    aws = AWS::AWSObject.new
+	    aws = AWS::AWSObject.new( operation )
 	    aws.walk( doc )
 
 	    # When dealing with multiple pages, we return not just an

data/ruby-aaws.gemspec

@@ -0,0 +1,117 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{ruby-aaws}
+  s.version = "0.7.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Ian Macdonald", "Jamie Dyer"]
+  s.date = %q{2009-08-17}
+  s.description = %q{Ruby interface to Amazon Associates Web Services}
+  s.email = %q{ian@caliban.org}
+  s.extra_rdoc_files = [
+    "README",
+     "README.rdoc"
+  ]
+  s.files = [
+    "COPYING",
+     "INSTALL",
+     "NEWS",
+     "README",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "example/batch_operation",
+     "example/browse_node_lookup1",
+     "example/customer_content_lookup1",
+     "example/customer_content_search1",
+     "example/example1",
+     "example/help1",
+     "example/item_lookup1",
+     "example/item_lookup2",
+     "example/item_search1",
+     "example/item_search2",
+     "example/item_search3",
+     "example/list_lookup1",
+     "example/list_search1",
+     "example/multiple_operation1",
+     "example/seller_listing_lookup1",
+     "example/seller_listing_search1",
+     "example/seller_lookup1",
+     "example/shopping_cart1",
+     "example/similarity_lookup1",
+     "example/tag_lookup1",
+     "example/transaction_lookup1",
+     "example/vehicle_search",
+     "lib/amazon.rb",
+     "lib/amazon/aws.rb",
+     "lib/amazon/aws/cache.rb",
+     "lib/amazon/aws/search.rb",
+     "lib/amazon/aws/shoppingcart.rb",
+     "lib/amazon/locale.rb",
+     "ruby-aaws.gemspec",
+     "setup.rb",
+     "test/setup.rb",
+     "test/tc_amazon.rb",
+     "test/tc_aws.rb",
+     "test/tc_browse_node_lookup.rb",
+     "test/tc_customer_content_lookup.rb",
+     "test/tc_help.rb",
+     "test/tc_item_lookup.rb",
+     "test/tc_item_search.rb",
+     "test/tc_list_lookup.rb",
+     "test/tc_list_search.rb",
+     "test/tc_multiple_operation.rb",
+     "test/tc_operation_request.rb",
+     "test/tc_seller_listing_lookup.rb",
+     "test/tc_seller_listing_search.rb",
+     "test/tc_seller_lookup.rb",
+     "test/tc_serialisation.rb",
+     "test/tc_shopping_cart.rb",
+     "test/tc_similarity_lookup.rb",
+     "test/tc_tag_lookup.rb",
+     "test/tc_transaction_lookup.rb",
+     "test/tc_vehicle_operations.rb",
+     "test/ts_aws.rb"
+  ]
+  s.has_rdoc = true
+  s.homepage = %q{http://www.caliban.org/ruby/ruby-aws/}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Ruby interface to Amazon Associates Web Services}
+  s.test_files = [
+    "test/setup.rb",
+     "test/tc_amazon.rb",
+     "test/tc_aws.rb",
+     "test/tc_browse_node_lookup.rb",
+     "test/tc_customer_content_lookup.rb",
+     "test/tc_help.rb",
+     "test/tc_item_lookup.rb",
+     "test/tc_item_search.rb",
+     "test/tc_list_lookup.rb",
+     "test/tc_list_search.rb",
+     "test/tc_multiple_operation.rb",
+     "test/tc_operation_request.rb",
+     "test/tc_seller_listing_lookup.rb",
+     "test/tc_seller_listing_search.rb",
+     "test/tc_seller_lookup.rb",
+     "test/tc_serialisation.rb",
+     "test/tc_shopping_cart.rb",
+     "test/tc_similarity_lookup.rb",
+     "test/tc_tag_lookup.rb",
+     "test/tc_transaction_lookup.rb",
+     "test/tc_vehicle_operations.rb",
+     "test/ts_aws.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/test/setup.rb

@@ -1,4 +1,4 @@
-# $Id: setup.rb,v 1.3 2008/06/22 11:50:23 ianmacd Exp $
+# $Id: setup.rb,v 1.5 2009/06/14 00:28:48 ianmacd Exp $
 #
 
 # Attempt to load Ruby/AWS using RubyGems.
@@ -24,8 +24,11 @@ class AWSTest < Test::Unit::TestCase
     @req = Request.new
     @req.locale = 'uk'
     @req.cache = false
+    @req.encoding = 'utf-8'
   end
 
-  undef_method :default_test
+  # The default_test method needs to be removed before Ruby 1.9.0.
+  #
+  undef_method :default_test if method_defined? :default_test
  
 end

data/test/tc_aws.rb

@@ -1,4 +1,4 @@
-# $Id: tc_aws.rb,v 1.11 2008/10/02 21:33:58 ianmacd Exp $
+# $Id: tc_aws.rb,v 1.12 2009/06/14 00:29:28 ianmacd Exp $
 #
 
 require 'test/unit'
@@ -13,7 +13,7 @@ class TestAWSBasics < AWSTest
   CACHE_PATH = File.join( Dir.tmpdir, 'aws_cache' )
 
   def test_version
-    v = '1.8.6'
+    v = '1.8.7'
     assert( RUBY_VERSION >= v, "Ruby version is lower than #{v}." )
   end
 

data/test/tc_browse_node_lookup.rb

@@ -0,0 +1,62 @@
+# $Id: tc_browse_node_lookup.rb,v 1.2 2009/06/02 00:39:43 ianmacd Exp $
+#
+
+require 'test/unit'
+require './setup'
+
+class TestBrowseNodeLookup < AWSTest
+
+  def test_browse_node_lookup
+
+    bnl = BrowseNodeLookup.new( 694212 )
+    rg = ResponseGroup.new( :BrowseNodeInfo )
+
+    response = @req.search( bnl, rg )
+
+    results = response.kernel
+
+    # Ensure we got some actual results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_browse_node_lookup_no_response_group
+
+    bnl = BrowseNodeLookup.new( 694212 )
+    bnl.response_group = ResponseGroup.new( :BrowseNodeInfo )
+    response = @req.search( bnl, nil )
+
+    results = response.kernel
+
+    # Ensure we got more than 10 results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_browse_node_lookup_class_method
+
+    response = Amazon::AWS.browse_node_lookup( 694212 )
+
+    results = response.kernel
+
+    # Ensure we got some actual results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_browse_node_lookup_class_method_block
+
+    Amazon::AWS.browse_node_lookup( '694212' ) do |r|
+
+      results = r.kernel
+
+      # Ensure we got some actual results back.
+      #
+      assert( results.size > 0 )
+    end
+  end
+
+end