ruby-aaws 0.5.1 → 0.6.0

data/NEWS

@@ -1,4 +1,113 @@
-$Id: NEWS,v 1.17 2009/03/28 23:04:22 ianmacd Exp $
+$Id: NEWS,v 1.18 2009/05/26 15:25:19 ianmacd Exp $
+
+
+0.6.0 - 2009-05-26
+------------------
+
+1. Requests to AWS can now be signed in order to authenticate them. Amazon
+   plans to make the signing of requests mandatory as of 15th August 2009, so
+   it is recommended to start doing so now.
+
+   To have your requests automatically signed by Ruby/AWS, simply add the
+   'secret_key_id' parameter to your ~/.amazonrc configuration file. Its value
+   should, rather predictably, be your secret access key, which can be
+   retrieved here:
+
+   https://aws-portal.amazon.com/gp/aws/developer/account/index.html?ie=UTF8&action=access-key
+
+   You needn't be concerned about Amazon's warnings not to show your secret
+   key to anyone else, because it will be used only for signing requests,
+   prior to sending them. The key itself will not be sent over the network to
+   Amazon, even in encrypted form.
+
+   In order to incorporate the new functionality, minor changes had to be made
+   to the way the AWS request URLs are encoded. This change means that
+   previous requests cached by earlier versions of Ruby/AWS will not be found
+   in the cache. This is a minor, one-time inconvenience, and it just means
+   that the requests will be performed and cached again.
+
+2. When Amazon's AWS servers check whether the correct signature has been
+   applied to a request, they recalculate the signature based on the data in
+   the request and check for a match with the signature supplied by Ruby/AWS.
+
+   This introduces a complicating factor, namely the treatment of non-ASCII
+   characters in the request, such as accented letters. When recalculating the
+   signature, Amazon will use the UTF-8 representation of any such characters.
+   This will cause a signature mismatch if you used a different encoding, such
+   as ISO-8859-1 (a.k.a. Latin-1), when you supplied values for your request
+   parameters.
+
+   Ruby/AWS can't (reliably) dynamically determine which character encoding
+   your strings use, so this information can now be supplied via the
+   ~/.amazonrc configuration file, using the 'encoding' parameter. This should
+   be set to whichever encoding you use. If left unset, it defaults to UTF-8.
+   An exception will be raised if you attempt to use an invalid (i.e. unknown)
+   encoding.
+
+   Currently, the encoding you use makes no difference unless your requests
+   are being signed, but because signing will soon be mandatory, I recommend
+   you explicitly state which encoding you intend to use.
+
+   You may also change the encoding in use at any time by assigning to the
+   @encoding instance variable of your Request object.
+
+3. The robustness of the software has been improved by handling the following
+   additional exceptions while communicating with the AWS servers:
+   Errno::ECONNREFUSED, Errno::ECONNABORTED, Errno::ETIMEDOUT and
+   Timeout::Error. Users have reported that all of these occur from time to
+   time, although only Windows platforms seem to suffer from
+   Errno::ECONNABORTED.
+
+4. The version of the AWS API used is now 2009-03-31, the latest at the time
+   of writing.
+
+5. <RANT>
+   Amazon must have appointed a new interim Senior Vice-President of
+   Outward-Facing Moniker Reconciliation or something, because earlier this
+   month, on 8th May, I received an e-mail from Amazon, informing me that the
+   Web service formerly known as Amazon Web Services, latterly the E-Commerce
+   Service, and then, until this month, the Amazon Associates Web Service, is
+   to undergo yet another name change.
+
+   Once again, the reason for the new moniker is that it ostensibly "more
+   accurately reflects the purpose of the API". The new sobriquet is the
+   highly reflective 'Product Advertising API'.
+
+   It never ceases to amaze me that the collective intellectual might of a
+   company as large and resourceful as Amazon cannot, over a period of five
+   years, converge to decisively name an API.
+
+   How long until the reins of responsibility for this offering change hands
+   once again and the next in a growing line of misguided middle managers
+   decides that he can best raise his profile with his superiors by changing
+   the name of the API to "better reflect its purpose"?
+
+   Well, I'm resistant to change, especially stupid, time-wasting changes, so
+   I'll be continuing to refer to AWS as AWS for the foreseeable future. When
+   I say AWS, you'll know I mean the product whose name is woefully subject to
+   Amazon's whimsy.
+
+   The same e-mail informed me that Amazon would soon be introducing mandatory
+   authentication of AWS requests.
+
+   I downloaded the latest developer guide, wrote some code to implement
+   request signatures, and then spent a good couple of hours trying to make my
+   code produce the sample results shown in the developer guide.
+
+   Ultimately, I realised that the sample requests in the developer guide
+   could not have produced the output claimed by the documentation.
+
+   Not only that, but 3 of the 10 steps in the developer guide, in the section
+   detailing how to sign AWS requests, contain critical errors. This means
+   that Amazon didn't once follow their own documentation to verify its
+   correctness.
+
+   Most of the mistakes have since been silently rectified by Amazon, without
+   any mention on the AWS forum or revising the document version. Who knows
+   how often the developer guide changes on a day to day basis. I had thought
+   each dated version to be a static, completed work, but this is apparently
+   not the case.
+   </RANT>
 
 
 0.5.1 - 2009-03-29

data/README

@@ -1,4 +1,4 @@
-$Id: README,v 1.20 2009/03/28 23:04:23 ianmacd Exp $
+$Id: README,v 1.21 2009/05/25 23:38:24 ianmacd Exp $
 
 
 Introduction
@@ -56,9 +56,10 @@ good news is that, in most cases, this isn't as much work as it might sound.
 
 Another bit of good news is that the /etc/amazonrc and ~/.amazonrc files used
 by Ruby/Amazon _are_ compatible with Ruby/AWS. The only change required for
-Ruby/AWS is the addition of a 'key_id' parameter, which should contain your
-AWS Access Key ID. That fact notwithstanding, as of version 0.5.0, Ruby/AWS
-also supports a more flexible, locale-specific configuration syntax.
+Ruby/AWS is the addition of the 'key_id' and 'secret_key_id' parameters, which
+should contain your AWS Access Key ID and its secret counterpart. That fact
+notwithstanding, as of version 0.5.0, Ruby/AWS also supports a more flexible,
+locale-specific configuration syntax.
 
 Amazon finally decomissioned v3 of the AWS API on 2008-03-31. As a result, the
 original Ruby/Amazon library no longer functions and is therefore obsolete.
@@ -79,10 +80,10 @@ Please obtain and use an AWS Access Key ID instead.
 API version
 -----------
 
-Ruby/AWS currently requests the 2009-02-01 revision of the AWS API when
+Ruby/AWS currently requests the 2009-03-31 revision of the AWS API when
 performing its operations:
 
-  http://docs.amazonwebservices.com/AWSECommerceService/2009-02-01/DG/
+  http://docs.amazonwebservices.com/AWSECommerceService/2009-03-31/DG/
 
 However, a different version can be requested via the 'api' parameter in the
 user configuration file.
@@ -91,19 +92,20 @@ user configuration file.
 Status and functionality
 ------------------------
 
-Ruby/AWS is currently beta code. Amongst other things, this means:
+Ruby/AWS is currently beta software. Amongst other things, this means:
 
-- You will encounter bugs, but hopefully not too many and none too serious. If
-  you tell me about them, I will endeavour to fix them.
+- You will encounter bugs, but hopefully not too many and none too serious.
+  Tell me about them and I will endeavour to fix them.
 
-- The documentation is incomplete, but steadily getting better. Version 0.0.1
-  had virtually none, so consider yourself lucky.
+- The documentation isn't what it could be, but it's hopefully enough to get
+  you up and running.
 
-- Not all features are currently implemented. Others may not be _fully_
-  implemented. Yet others may not be _properly_ implemented.
+- Not all features are currently implemented. Others may not yet be _fully_
+  implemented. Some, I probably haven't even thought of yet. Again, if
+  something's missing, tell me, and if it makes sense, I'll add it.
 
-  Nevertheless, the AWS v4 API is now more or less fully supported, with only
-  small gaps in the functionality of some operations.
+  In spite of this shortcomings, the AWS v4 API is more or less fully
+  supported, with only small gaps in the functionality of some operations.
 
   Currently implemented operations are:
   
@@ -130,19 +132,21 @@ Ruby/AWS is currently beta code. Amongst other things, this means:
     CartModify
     CartClear
 
-  Version 0.4.0 also adds:
+  Version 0.4.0 adds the remaining shopping-cart operation, which I had first
+  thought superfluous:
 
     CartGet
 
-  Multiple operations are supported, but not well tested.
+  Multiple operations are supported, but not well tested (by me, anyway).
 
   As of version 0.5.0, batch operations are fully supported, using the
   Operation#batch method.
   
-  Beware of bugs in this area. There appear to also be (undocumented)
-  Amazon-imposed restrictions on the use of multiple operations and batch
-  requests, so some experimentation on your part will probably be required to
-  determine what works and what doesn't.
+  Beware of bugs in this area. Quite apart from any mistakes I've made in the
+  implementation, there appear to also be (undocumented) Amazon-imposed
+  restrictions on the use of multiple operations and batch requests, so some
+  experimentation will be required on your part to determine what works and
+  what doesn't.
 
   The 2008-08-19 version of the AWS API added the following operations:
 
@@ -150,21 +154,21 @@ Ruby/AWS is currently beta code. Amongst other things, this means:
     VehiclePartSearch
     VehicleSearch
 
-  These are supported by Ruby/AWS as of version 0.5.0
+  These are supported by Ruby/AWS from version 0.5.0 onwards.
   
 - Classes, methods, constants and instance variables may change name in the
-  future. These various objects may appear from nowhere, change shape, grow,
-  shrink or disappear entirely. Such fundamental changes will almost certainly
-  break existing code, so I will endeavour to keep them to a minimum.
+  future. New ones may appear from nowhere and existing ones may change shape,
+  grow, shrink or disappear without trace. Such fundamental changes will break
+  existing code, so I will endeavour to keep them to a minimum.
 
 In short, code written to work with this release of Ruby/AWS may stop working
 when you upgrade to the next. In fact, it may even stop working _during_ this
-release, because it's possible there are circumstances that would cause an
-exception to be raised, that I haven't come across in my limited testing of
-the code. It's also possible that future changes made by Amazon will affect
-Ruby/AWS in unexpected ways.
+release cycle, because it's possible there are fatal conditions that I didn't
+encounter in my limited testing of the code. It's also possible that future
+(possibly unannounced) changes made by Amazon will affect Ruby/AWS in
+ways I can't anticipate.
 
-That said, the Ruby/AWS's API is pretty stable at this point in time. I won't
+That said, the Ruby/AWS API is pretty stable at this point in time. I won't
 break any of the method interfaces without seriously considering the merits of
 doing so.
 
@@ -179,22 +183,43 @@ choose between an installation script and a RubyGems installation.
 Usage
 -----
 
-First of all, create either /etc/amazonrc or ~/.amazonrc. Its contents should
-look something like this:
+First of all, create either /etc/amazonrc or ~/.amazonrc as a plain text file.
+Its contents should look something like this:
 
   # Any line that starts with a hash character is a comment.
   key_id = '0Y44V8G41KCQPGF6XYZ2'
+  secret_key_id = 'k+kuddeoQJzUnImC0Hyy21J4xLWQc1hbvfQ+7F1G
   associate = 'fuzbarorg-21'
   cache = false
   locale = 'uk'
+  encoding = 'iso-8859-15'
+
+Including your secret key is a new feature in version 0.6.0 of Ruby/AWS. If
+you choose to do so, your requests to AWS will be signed for authentication by
+the Amazon's servers.
+
+Amazon plans to make this practice obligatory as of 15th August 2009, so I
+recommend that you adopt it well ahead of time.
+
+When Amazon checks for a valid signature, it does so by comparing its
+computation of the signature with the one supplied by the user. In doing this,
+Amazon uses the UTF-8 representation of parameter values that you supply, even
+if you use a different encoding.
+
+In order to have Ruby/AWS properly reencode your strings as UTF-8, you need
+to tell it which encoding you are using. The 'encoding' parameter can be used
+for this, but you can omit it if your strings are already UTF-8, because this
+is the default.
 
 As of version 0.5.0 of Ruby/AWS, the following locale-specific configuration
 syntax is also supported:
 
   [global]
   key_id = '0Y44V8G41KCQPGF6XYZ2'
-  locale = 'uk'
+  secret_key_id = 'k+kuddeoQJzUnImC0Hyy21J4xLWQc1hbvfQ+7F1G
   cache = false
+  locale = 'uk'
+  encoding = 'iso-8859-15'
   # Request a specific version of the API.
   # api = '2008-03-03'
 
@@ -204,16 +229,20 @@ syntax is also supported:
   [us]
   associate = 'fuzbarorg-20'
 
-Because you're embedding your key ID in the file, you should protect it (on
-UNIX and equivalent systems) by making it mode 0600:
+This enables the use of a different associate tag for each locale, although,
+oddly enough, no-one has ever requested this feature.
+
+Because you're embedding your personal keys in the file, you should protect it
+(on UNIX and equivalent systems) by making it mode 0600:
 
 $ chmod 600 ~/.amazonrc
 
-If you define 'cache' to be 'true', you may also define 'cache_dir' to point
-to somewhere other the default, /tmp/amazon.
+If you define 'cache' to be 'true', you may want to also define 'cache_dir' to
+point to somewhere other the default cache directory, /tmp/amazon.
 
 If you want to place .amazonrc somewhere other than $HOME, you may set
-$AMAZONRCDIR in the environment, as this location is checked prior to $HOME.
+the $AMAZONRCDIR environment variable, as this location is checked prior to
+$HOME.
 
 If you're using Windows, $HOME is usually undefined, so a number of additional
 locations are checked for .amazonrc.
@@ -230,13 +259,13 @@ $AMAZONRCDIR and $HOME are defined, but only the path specified by $HOME
 contains a file called .amazonrc, it will not be found.
 
 If you want the user configuration file to be called something other than
-.amazonrc, you may define $AMAZONRCFILE in the environment.
+.amazonrc, you may define the $AMAZONRCFILE environment variable.
 
-Once you have your configuration file, you can get started on your code.
+Once you have your configuration file, you can get started writing your code.
  
-Here's some basic code, indicating how to perform an ItemSearch, probably the
+Here's a basic example, showing how to perform an ItemSearch, probably the
 most common type of AWS operation. Please see the ./examples subdirectory for
-more examples of working code.
+more examples of contrived, but working code.
 
 --
 
@@ -288,11 +317,13 @@ XML to Ruby mapping
 -------------------
 
 Here, I will discuss the mapping of the XML returned from AWS to native Ruby
-objects and data.
+objects and data. Note that the XML shown below was that returned at the time
+of writing and may look different to what you would see today if you were to
+execute the same request.
 
-When the following code:
+When this code:
 
-resp = req.search( is, rg )
+  resp = req.search( is, rg )
 
 was called in the previous section, the following URL was composed and sent to
 AWS as an HTTP GET operation:
@@ -370,7 +401,7 @@ the following statements would all be true:
 - ItemAttributes, Author, Manufacturer, ProductGroup and Title would all be
   dynamically defined subclasses of AWSObject.
 
-- An instance of the ItemAttributes class would be instantiated, with instance
+- An instance of the ItemAttributes class would be created, with instance
   variables @author, @manufacturer, @product_group and @title.
 
 - To each of these instance variables would respectively be assigned an array
@@ -379,13 +410,15 @@ the following statements would all be true:
   would all be single element arrays, because there's only one instance of
   each kind of tag in the XML.
 
-- These lowest level objects would have no instance variables, because the
-  corresponding XML elements contain no children, just a value. These objects
-  are therefore directly assigned the value of the corresponding XML element.
+- The Author, Manufacturer, ProductGroup and Title objects would have no
+  instance variables of their own, because the corresponding XML elements
+  have no children, just a value. These objects are therefore directly
+  assigned the value in question.
 
-So, if resp is the top level AWSObject created and returned by calling
-Amazon::AWS::Search::Request#search on the Request object, and we'd like to
-know the ASIN of the first item found, we can refer to this as follows:
+So, if resp is the top level AWSObject created and returned by calling the
+Amazon::AWS::Search::Request#search method of the Request object, and we'd
+like to know the ASIN of the first item found, we can refer to this as
+follows:
 
   resp.item_search_response[0].items[0].item[0].asin
 
@@ -393,101 +426,105 @@ Looking at each component of this chain in turn:
 
 - resp is an AWSObject with a single instance variable, @item_search_response.
   This is because the entire XML response is contained within a single
-  <ItemSearchResponse> tag pair, so there's nothing else at the top level.
+  <ItemSearchResponse> element, so there's nothing else at the top level.
 
 - resp.item_search_response is assigned an array of ItemSearchResponse
-  objects. Because there's only a single <ItemSearchResponse> tag pair in the
+  objects. Because there's only a single <ItemSearchResponse> element in the
   whole document (containing the rest of the XML), the array contains only a
   single element.
 
 - resp.item_search_response[0] has an instance variable, @items, which is
   assigned an array of Items objects. Here again, only a single element is
-  created, because there's only one <Items> tag pair in the XML.
+  created, because there's only one corresponding <Items> element in the XML.
 
 - resp.item_search_response[0].items[0] has an instance variable, @item, which
-  is an array containing the item(s) returned by the search. It is a
+  is an array containing the actual item(s) located by the search. It is a
   multi-element array, however, because more than one item was found, as
   represented by the multiple <Item> elements in the XML.
 
 The creation of so many single element arrays is unfortunate. It makes user
 code verboser, uglier and consequently harder to read.
 
-Some such arrays do, in fact, have the potential to be multi-element, because
-the corresponding XML tag _can_ appear multiple times in the AWS response. A
-book, for example, _may_ have more than one <Author>. Many other types of
-array, however, are necessarily single element arrays. The same book, for
-example, is unlikely to have more than one <Title>.
+You might wonder why Ruby/AWS doesn't just assign the single element itself,
+rather than the array that contains it.
+
+The answer is that most of these single-element arrays actually do have the
+potential to be multi-element, because the corresponding XML tag _can_ appear
+multiple times in an AWS response. A book, for example, _may_ have more than
+one <Author>. Many other types of array, however, are necessarily single
+element arrays. That same book, for example, is unlikely to have more than one
+<Title>. This is context-dependent and difficult to define programatically.
 
-As another concrete example, an ItemSearch will probably return many <Item>
+As another concrete example, an ItemSearch will probably yield many <Item>
 elements in the <ItemSearchResponse>, but these will invariably be nested in a
-single <Items> tag. The @items instance variable of the ItemSearchResponse
-object will therefore always have a size of 1.
+single <Items> element. The @items instance variable of the ItemSearchResponse
+object will therefore always be a single-element array.
 
-In other words, the following statements are always true when an ItemSearch
-successfully finds items:
+In other words, the following statements are both invariably true when an
+ItemSearch successfully locates items:
 
 - resp.item_search_response[0].items.size == 1
 
 - resp.item_search_response[0].items[0].item.size >= 1
 
 The awkwardness of using such single element arrays is alleviated in Ruby/AWS
-by the use of the AWSArray subclass. This ever-so-slightly magic class of
-array allows element 0 of single-element arrays to be dereferenced using the
-base array name, i.e. without a subscript.
+by the use of the AWSArray subclass. An instance of this class differs from a
+standard array by allowing element 0 of a single-element array to be
+dereferenced using just the array name, i.e. without a subscript.
 
-In other words, a reference to foo.bar will actually return foo[0].bar, so
-long as foo.size == 1. Note that this only works because the array instance
-itself, foo, has no bar method, so the intention is unambiguous and foo can
-pass the call of bar down to foo[0]. foo.size, on the other hand, will
-_always_ refer to foo and never to foo[0], because Array#size _is_ an existing
-method.
+In other words, a reference to foo.bar will actually return foo[0].bar when
+foo.size == 1. Note that this can only work because the array itself, foo, has
+no bar method, so the intention is unambiguous and foo can delegate the
+invocation of the method to foo[0]. foo.size, on the other hand, will _always_
+invoke foo's bar method, never delegating to foo[0], because of the existence
+of the Array#size method.
 
 This allows the ASIN of the first item returned in the above XML to be
 referred to using the following shorthand:
 
   resp.item_search_response.items.item[0].asin
 
-It's worth reiterating that it's still necessary to refer to item[0] using a
-subscript in this example, because the <Items> tag in the XML contains
-multiple <Item> tags, making item.size > 1.
+It's worth reiterating that it's still necessary in this example to refer to
+item[0] using a subscript, because the <Items> element in the XML contains
+multiple <Item> elements, making item.size > 1.
 
 Use this syntactic shorthand to your advantage, but understand when you're
-likely to be dealing with a single element array and when a multiple. This
-will become apparent as you gain familiarity with AWS v4.
+likely to be dealing with a single element array vs. a multiple. This will
+become apparent as you gain familiarity with AWS v4.
 
-An exception will be thrown if an unknown method is called on a multi-element
-array, as it can't be known which element the method invocation should be
-passed to. This will almost certainly be the result of an incorrect assumption
-that an array contains only a single element when it actually contains
-multiple.
+An exception will be raised if an unknown method is called on a multi-element
+array, as it can't be known to which array element the method invocation
+should be delegated. This will almost certainly stem from an incorrect
+assumption that an array contains only a single element when, in actual fact,
+it contains multiple elements.
 
-A further important detail to note is that not all AWS operations in the same
+A further important detail to note is that not all AWS operations of the same
 class return the same data. For example, an ItemSearch using the Books search
-index will return items that, amongst other things, create an ItemAttributes
+index will return items that, amongst other things, have an ItemAttributes
 object containing further objects of class Author, ISBN, etc. An ItemSearch
-using the DVD search index, however, will have no Author or ISBN, but _will_
-have a Director and probably one or more Actor objects.
+using the DVD search index, by contrast, will have no Author or ISBN, but
+will likely have a Director and probably one or more Actor objects.
 
 Because of the disparity in same-class object attributes, Ruby/AWS returns
 *nil* when an attempt is made to dereference a non-existent instance variable.
-This approach was chosen, because it often cannot be known in advance
-precisely which data will be returned by a given search. Returning *nil* for
-non-existent attributes means that the user does not have to pepper their code
-with exception-handling clauses.
+This approach was chosen because, more often than not, it cannot be known in
+advance precisely which data will be returned by a given search operation.
+Returning *nil* for non-existent attributes saves the user from having to
+pepper their code with exception-handling clauses.
 
 For example:
 
-resp.item_search_response[0].items[0].item[0].item_attributes.director
+  resp.item_search_response[0].items[0].item[0].item_attributes.director
 
 will return *nil* for a book, because there was no corresponding Director
 element in the XML returned by AWS.
 
 Similarly:
 
-resp.item_search_response[0].items[0].item[0].item_attributes.foo_bar
+  resp.item_search_response[0].items[0].item[0].item_attributes.foo_bar
 
-will _always_ return *nil* for any item, because no kind of ItemSearch will
-ever yield an item with a FooBar attribute.
+will _always_ return *nil* for _any_ item, because no kind of ItemSearch will
+ever yield an item with a FooBar element.
 
 
 Parameter checking
@@ -498,18 +535,19 @@ particular type of search. For example, an ItemSearch can use a Sort parameter
 with a value of 'titlerank' if the SearchIndex is 'Books'. However, this value
 wouldn't make much sense in the 'Automotive' SearchIndex.
 
-The very presence of a certain parameter can be illegal in a certain contexts.
-For example, specifying the parameter 'Author' with any value would be
+The very presence of a certain parameter can be illegal in certain contexts.
+For example, specifying the parameter 'Author' with _any_ value would be
 nonsensical in the 'PetSupplies' SearchIndex.
 
 To complicate things further, the validity of parameters and their values
 differs not only by search type, but also by Amazon locale (amazon.com,
-amazon.co.uk, amazon.de, etc.) and is prone to change with each minor revision
-of the Amazon AWS API.
+amazon.co.uk, amazon.de, etc.) and is prone to change with minor revisions of
+the Amazon AWS API.
 
 Even worse, the operations themselves can be illegal in certain locales.
-TransactionLookup operations, for example, don't currently work in the UK
-locale, but do work in the US locale.
+TransactionLookup operations, for example, don't work in the UK locale at the
+time of writing, but do work in the US locale. As a rule of thumb, we can say
+that almost everything works in the US locale and _may_ work in others.
 
 Ruby/Amazon attempted to track these complex and dynamic relationships to
 prevent illegal or ineffective operations from being attempted. It was a
@@ -517,24 +555,25 @@ time-consuming and tedious task to track the evolving API (which often changed
 in subtle ways without prior [or even belated] notice from Amazon), find all
 of the corner cases and handle undocumented quirks.
 
-With the highly dynamic nature of the Amazon environment, plus the sheer
-number of operations, parameters, possible legal values and locales in the AWS
-v4 API, this strict approach would be completely impractical. Ruby/AWS
-therefore doesn't even try.
+With the highly dynamic nature of the Amazon environment and its many locales,
+plus the sheer number of operations, parameters and their possibly legal
+values in the AWS v4 API, this strict approach would be completely
+impractical for Ruby/AWS. It therefore doesn't even try.
 
 Instead, it's now up to you to ensure that you perform legal operations and
-pass in sensible parameters and values for the locale in which you're working.
+pass sensible parameters and values for the locale in which you're working.
+The context is now your responsibility.
 
 The one exception to this rule is search index checking for ItemSearch
 operations. Code that attempts to use an invalid SearchIndex will raise an
-exception. The list of allowable search indices can be found in
-Amazon::AWS::Operation::ItemSearch::SEARCH_INDICES.
+exception. The list of allowable search indices can be found in the
+Amazon::AWS::Operation::ItemSearch::SEARCH_INDICES array.
 
 Of course, even this check exposes the user to the risk that Amazon may later
 add new search indices, which would continue to be unrecognised and ruled
-invalid by Ruby/AWS until a future update. Whilst I have chosen to implement
-this very basic level of checking, it may be removed in the future if it
-becomes impractical to keep it current.
+invalid by Ruby/AWS until an update was issued. Whilst I have chosen to
+implement this very basic level of checking, it may be removed in the future
+if it becomes impractical to keep it current.
 
 In short, the validity of what goes into a search operation is your own
 responsibility: garbage in, garbage out.
@@ -542,34 +581,35 @@ responsibility: garbage in, garbage out.
 Thankfully, with the AWS Developer Guide at your side, it's largely common
 sense which parameters and values can be used with each type of search. It's
 less obvious when these differ by locale. For example, the 'Beauty'
-SearchIndex was valid in the 'us', but not in the 'uk' until the 2009-01-06
-revision of the AWS API.
+SearchIndex was valid in the 'us' locale, but not in the 'uk' locale until the
+2009-01-06 revision of the AWS API.
 
 Unfortunately, AWS abounds with such inconsistencies and they are prone to
-change at any time.
+change at any time. Amazon, themselves, seem to struggle to document all of
+these quirks, a situation probably aggravated by the US focus of the AWS
+staff.
 
-The only way to apprise yourself of such quirks is to read Amazon's latest
-developer documentation (and closely follow the release notes of each minor
-API revision to make sure things haven't changed). If you don't want to be
-exposed to such API changes, use the 'api' parameter in the user configuration
-file to request a particular version of the API.
+The only way to apprise yourself of such peculiarities is to read Amazon's
+latest developer documentation (and closely follow the release notes of each
+minor API revision to make sure things haven't changed). If you don't want to
+be exposed to such API changes, use the 'api' parameter in the user
+configuration file to request a particular version of the API.
 
 The AWS Developer Connection pages may also be of use to you. In particular,
 the forum for discussing AWS has proved useful to me over the years:
 
   http://developer.amazonwebservices.com/connect/forum.jspa?forumID=9
 
-For those illegal operations that make it through and are passed to the Amazon
-servers, the good news is that Amazon carries out extensive request-time
-parameter checking in AWS v4 (much better than in v3) and will generate an
-error when an illegal set of parameters and values is given. Ruby/AWS will
-dynamically generate an exception class for the reported type of error and
-raise an exception of that class.
+For those illegal operations that make it through to the Amazon servers, the
+good news is that Amazon carries out extensive run-time parameter checking in
+AWS v4 (much better than in v3) and will generate an error when an illegal set
+of parameters and/or values is given. Ruby/AWS will dynamically generate a
+class for the type of error reported and raise an exception of that class.
 
 Using this approach, Ruby/AWS doesn't have to perform checks that Amazon will
-perform later anyway. This helps keep the code base leaner, the library
-faster, and reduces the chances of Ruby/AWS disallowing operations that will
-one day be allowed in a minor revision of AWS.
+perform, anyway. This helps keep the code base leaner, the library faster, and
+reduces the chance that Ruby/AWS will disallow an operation that becomes valid
+following a minor revision of AWS.
 
 
 Documentation
@@ -580,14 +620,14 @@ command, executed from the directory created when you unpacked the archive:
 
   rdoc -SUx CVS lib
 
-The documentation on how to use this library is currently incomplete, but that
-is steadily being remedied.
+The documentation on how to use this library is currently incomplete, but it
+should be enough to get you started.
 
 You can also use the Ruby/AWS mailing-list:
 
   http://www.caliban.org/mailman/listinfo/ruby-aws
 
-to discuss all Ruby/AWS-related subjects and issues.
+to discuss any Ruby/AWS-related subjects and issues.
 
 
 Examples

data/README.rdoc

@@ -1,5 +1,5 @@
 #--
-# $Id: README.rdoc,v 1.22 2009/03/28 23:04:23 ianmacd Exp $
+# $Id: README.rdoc,v 1.23 2009/05/26 15:25:19 ianmacd Exp $
 #++
 #
 #
@@ -53,19 +53,22 @@
 #  CartClear
 #  CartGet
 # 
-# In addition, multiple operations and batch requests are also supported.
+# Finally, multiple operations and batch requests are also supported.
 #
-# Ruby/AWS also offers advanced features not directly available in the AWS
-# API, such as the ability to retrieve *all* results pages for a particular
-# search, rather than having to manually deal with AWS responses of 10 results
-# per page.
+# Ruby/AWS supports request authentication, using your secret key to sign your
+# requests to AWS.
+#
+# Beyond wrapping features readily available in the AWS API, Ruby/AWS also
+# offers advanced features not directly supported by the AWS API, such as the
+# ability to retrieve *all* results pages for a particular search, rather than
+# having to manually deal with multiple AWS responses of 10 results per page.
 #
 # You can also retrieve product images and optionally overlay them with
 # percentage discount icons.
 #
 # Another advanced feature is the ability to cache responses returned by AWS.
 # If the cache is used (as it is by default), the results of each unique
-# query will be cached and used for 24 hours. The cache can be manually
+# search will be cached and used for 24 hours. The cache can be manually
 # flushed of all or just the expired entries.
 #
 # One other useful advanced feature is the ability to determine the
@@ -82,9 +85,9 @@
 # to install Ruby/AWS. You can choose between an installation script and a
 # RubyGems[http://www.rubygems.org/] installation.
 #
-# Note, however, if choosing the gem installation, that whilst Ruby/AWS's
-# RubyForge UNIX name is now ruby-aaws. The ruby-aws name was taken by
-# {another project}[http://rubyforge.org/projects/ruby-aws/] and this clash
+# Note, however, if opting for the gem installation, that Ruby/AWS's RubyForge
+# UNIX name is now ruby-aaws. The ruby-aws name was taken by {another
+# project}[http://rubyforge.org/projects/ruby-aws/] and this namespace clash
 # prevented remote installation of the Ruby/AWS gem.
 #
 #
@@ -95,17 +98,17 @@
 # ID}[https://aws-portal.amazon.com/gp/aws/developer/registration/index.html].
 #
 # You should also apply for an {Associates
-# account}[http://docs.amazonwebservices.com/AWSECommerceService/2009-01-06/GSG/BecominganAssociate.html],
+# account}[http://docs.amazonwebservices.com/AWSECommerceService/2009-03-31/GSG/BecominganAssociate.html],
 # although this isn't strictly necessary. If you do not explicitly provide an
-# Associates tag in your calls through Ruby/AWS, the tag of the Ruby/AWS
-# author will be used by default.
+# Associates tag in the operations you conduct via Ruby/AWS, the tag of the
+# Ruby/AWS author will be used by default.
 #
 # 
 # == See Also
 # 
-# Ultimately, the way to get the most from this library is to read the AWS
+# Ultimately, the way to get the most from Ruby/AWS is to read the AWS
 # documentation to get a feel for what is possible, and then experiment with
-# this library to see how the AWS calls are mapped into the Ruby world. You
+# the library to see how the calls to AWS are mapped to the Ruby world. You
 # should also review this library's
 # RDoc[http://www.ruby-doc.org/core/classes/RDoc.html]
 # documentation[http://www.caliban.org/ruby/ruby-aws/] as well as the
@@ -113,26 +116,28 @@
 #
 # Additionally, there's a
 # {mailing-list}[http://www.caliban.org/mailman/listinfo/ruby-aws] available,
-# where you can discuss all Ruby/AWS-related subjects and issues.
+# where you can discuss any Ruby/AWS-related subjects and issues.
 #
-# Please see the Amazon Web Services
-# documentation[http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=5]
+# Please see the Amazon Web Services API
+# documentation[http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=5],
+# not forgetting the {release
+# notes}[http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=17]
 # for definitive information on the capabilities and inner workings of the AWS
 # API.
 #
 #
 # == Download
 #
-# Version 0.5.1
-# === {gzip'ed tar archive}[http://www.caliban.org/files/ruby/ruby-aws-0.5.1.tar.gz]
-# === {Ruby Gem}[http://www.caliban.org/files/ruby/ruby-aaws-0.5.1.gem]
-# === {Fedora 9 RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-0.5.1-1.fc9.noarch.rpm]
-# === {Fedora 9 doc RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-doc-0.5.1-1.fc9.noarch.rpm]
-# === {Fedora 9 source RPM}[http://www.caliban.org/files/redhat/SRPMS/ruby-aws-0.5.1-1.fc9.src.rpm]
+# Version 0.6.0
+# === {gzip'ed tar archive}[http://www.caliban.org/files/ruby/ruby-aws-0.6.0.tar.gz]
+# === {Ruby Gem}[http://www.caliban.org/files/ruby/ruby-aaws-0.6.0.gem]
+# === {Fedora 9 RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-0.6.0-1.fc9.noarch.rpm]
+# === {Fedora 9 doc RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-doc-0.6.0-1.fc9.noarch.rpm]
+# === {Fedora 9 source RPM}[http://www.caliban.org/files/redhat/SRPMS/ruby-aws-0.6.0-1.fc9.src.rpm]
 # 
 # 
 # ---
 # Author::   Ian Macdonald <mailto:ian@caliban.org>
-# Version::  0.5.1
+# Version::  0.6.0
 # Copyright:: (C) 2008-2009 Ian Macdonald
 # Licence::  GPL[http://www.gnu.org/copyleft/gpl.html]

data/lib/amazon.rb

@@ -1,4 +1,4 @@
-# $Id: amazon.rb,v 1.26 2009/01/19 16:45:11 ianmacd Exp $
+# $Id: amazon.rb,v 1.28 2009/05/26 15:25:20 ianmacd Exp $
 #
 
 module Amazon
@@ -8,6 +8,7 @@ module Amazon
   class AmazonError < StandardError; end
 
   NAME = 'Ruby/Amazon'
+
   @@config = {}
 
   # Prints debugging messages and works like printf, except that it prints
@@ -22,11 +23,12 @@ module Amazon
   #
   def Amazon.url_encode(string)
 
-    # Shamelessly plagiarised from Wakou Aoyama's cgi.rb.
+    # Shamelessly plagiarised from Wakou Aoyama's cgi.rb, but then altered
+    # slightly to please AWS.
     #
-    string.gsub( /([^ a-zA-Z0-9_.-]+)/n ) do
+    string.gsub( /([^a-zA-Z0-9_.~-]+)/n ) do
       '%' + $1.unpack( 'H2' * $1.size ).join( '%' ).upcase
-    end.tr( ' ', '+' )
+    end
   end
 
 

data/lib/amazon/aws.rb

@@ -1,4 +1,4 @@
-# $Id: aws.rb,v 1.89 2009/03/28 23:04:23 ianmacd Exp $
+# $Id: aws.rb,v 1.97 2009/05/26 15:24:31 ianmacd Exp $
 #
 #:include: ../../README.rdoc
 
@@ -6,13 +6,14 @@ module Amazon
 
   module AWS
 
-    require 'uri'
     require 'amazon'
     require 'amazon/aws/cache'
+    require 'iconv'
     require 'rexml/document'
+    require 'uri'
 
     NAME = '%s/%s' % [ Amazon::NAME, 'AWS' ]
-    VERSION = '0.5.1'
+    VERSION = '0.6.0'
     USER_AGENT = '%s %s' % [ NAME, VERSION ]
 
     # Default Associate tags to use per locale.
@@ -30,7 +31,7 @@ module Amazon
     # changed via the user configuration file.
     #
     SERVICE = { 'Service' => 'AWSECommerceService',
-		'Version' => '2009-02-01'
+		'Version' => '2009-03-31'
     }
 
     # Maximum number of 301 and 302 HTTP responses to follow, should Amazon
@@ -66,6 +67,11 @@ module Amazon
     # ReviewPage       20
   
 
+    # A hash to store character encoding converters.
+    #
+    @@encodings = {}
+
+
     # Exception class for HTTP errors.
     #
     class HTTPError < AmazonError; end
@@ -96,11 +102,12 @@ module Amazon
       'us' => Endpoint.new( 'http://ecs.amazonaws.com/onca/xml' )
     }
 
+
     # Fetch a page, either from the cache or by HTTP. This is used internally.
     #
-    def AWS.get_page(request, query)  # :nodoc:
+    def AWS.get_page(request)  # :nodoc:
 
-      url = ENDPOINT[request.locale].path + query
+      url = ENDPOINT[request.locale].path + request.query
       cache_url = ENDPOINT[request.locale].host + url
 
       # Check for cached page and return that if it's there.
@@ -110,6 +117,14 @@ module Amazon
 	return body if body
       end
 
+      # Check whether we have a secret key available for signing the request.
+      # If so, sign the request for authentication.
+      #
+      if request.config['secret_key_id']
+	request.sign
+	url = ENDPOINT[request.locale].path + request.query
+      end
+
       # Get the existing connection. If there isn't one, force a new one.
       #
       conn = request.conn || request.reconnect.conn
@@ -124,7 +139,9 @@ module Amazon
       # just not passed by here recently), the HTTP connection to the server
       # will probably have timed out.
       #
-      rescue Errno::ECONNRESET, Errno::EPIPE => error
+      rescue EOFError,		Errno::ECONNABORTED, Errno::ECONNREFUSED,
+	     Errno::ECONNRESET, Errno::EPIPE,	     Errno::ETIMEDOUT,
+	     Timeout::Error	=> error
 	Amazon.dprintf( 'Connection to server lost: %s. Retrying...', error )
 	conn = request.reconnect.conn
 	retry
@@ -159,16 +176,23 @@ module Amazon
     end
 
 
-    def AWS.assemble_query(items)  # :nodoc:
+    def AWS.assemble_query(items, encoding=nil)  # :nodoc:
+
       query = ''
+      @@encodings[encoding] ||= Iconv.new( 'utf-8', encoding ) if encoding
 
       # We must sort the items into an array to get reproducible ordering
       # of the query parameters. Otherwise, URL caching would not work. We
-      # must also convert the keys to strings, in case Symbols have been used
-      # as the keys.
+      # must also convert the parameter values to strings, in case Symbols
+      # have been used as the values.
       #
       items.sort { |a,b| a.to_s <=> b.to_s }.each do |k, v|
-	query << '&%s=%s' % [ k, Amazon.url_encode( v.to_s ) ]
+	if encoding
+	  query << '&%s=%s' %
+	    [ k, Amazon.url_encode( @@encodings[encoding].iconv( v.to_s ) ) ]
+	else
+	  query << '&%s=%s' % [ k, Amazon.url_encode( v.to_s ) ]
+	end
       end
 
       # Replace initial ampersand with question-mark.
@@ -819,13 +843,6 @@ module Amazon
       #   indices.
       # - *Video* combines the DVD and VHS search indices.
       #
-      # Note that {page
-      # 53}[http://docs.amazonwebservices.com/AWSECommerceService/2009-01-06/DG/SearchIndices.html]
-      # of the PDF of the AWS Developer Guide (revision 2009-01-06) contains
-      # an outdated description of *Blended* with too few subindices. {Page
-      # 95}[http://docs.amazonwebservices.com/AWSECommerceService/2009-01-06/DG/CommonItemSearchParameters.html]
-      # of the PDF contains the correct list.
-      #
       SEARCH_INDICES = %w[
 	All
 	Apparel

data/lib/amazon/aws/search.rb

@@ -1,4 +1,4 @@
-# $Id: search.rb,v 1.30 2009/02/19 16:19:47 ianmacd Exp $
+# $Id: search.rb,v 1.35 2009/05/26 16:27:12 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,8 +28,14 @@ module Amazon
 	#
 	class LocaleError < Amazon::AWS::Error::AWSError; end
 
-	attr_reader :conn, :locale, :user_agent
+	# Requests can be authenticated using the SHA-256 Secure Hash
+	# Algorithm.
+	#
+	DIGEST = OpenSSL::Digest::Digest.new( 'sha256' )
+
+	attr_reader :conn, :config, :locale, :query, :user_agent
 	attr_writer :cache
+	attr_accessor :encoding
 
 	# This method is used to generate an AWS search request object.
 	#
@@ -82,7 +89,13 @@ module Amazon
 			else
 			  nil
 			end
-	  @api	      = @config['api'] || nil
+
+	  # 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
 
@@ -178,6 +191,43 @@ module Amazon
 	private :error_check
 
 
+	# Add a timestamp to a request object's query string.
+	#
+	def timestamp
+	  @query << '&Timestamp=%s' %
+	    [ Amazon.url_encode( Time.now.utc.strftime( '%FT%TZ' ) ) ]
+	end
+	private :timestamp
+
+
+	# Add a signature to a request object's query string. This implicitly
+	# also adds a timestamp.
+	#
+	def sign
+	  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
+	end
+
+
 	# 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.
@@ -204,19 +254,19 @@ module Amazon
 	# 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 )
+	  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.
 	  #
-	  q_params.merge!( { 'Version' => @api } ) if @api
+	  parameters.merge!( { 'Version' => @api } ) if @api
 
-	  query = Amazon::AWS.assemble_query( q_params )
-	  page = Amazon::AWS.get_page( self, query )
+	  @query = Amazon::AWS.assemble_query( parameters, @encoding )
+	  page = Amazon::AWS.get_page( self )
 	  doc = Document.new( page )
 
 	  # Some errors occur at the very top level of the XML. For example,
@@ -315,9 +365,10 @@ 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 )
 	    doc = Document.new( page )
 
 	    # Check for errors.
@@ -327,7 +378,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/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.4 2009/05/25 23:35:54 ianmacd Exp $
 #
 
 # Attempt to load Ruby/AWS using RubyGems.
@@ -24,6 +24,7 @@ class AWSTest < Test::Unit::TestCase
     @req = Request.new
     @req.locale = 'uk'
     @req.cache = false
+    @req.encoding = 'utf-8'
   end
 
   undef_method :default_test

data/test/tc_item_search.rb

@@ -1,4 +1,4 @@
-# $Id: tc_item_search.rb,v 1.1 2008/05/19 10:17:26 ianmacd Exp $
+# $Id: tc_item_search.rb,v 1.3 2009/05/26 16:18:14 ianmacd Exp $
 #
 
 require 'test/unit'
@@ -6,8 +6,13 @@ require './setup'
 
 class TestItemSearch < AWSTest
 
-  def test_item_search
-    is = ItemSearch.new( 'Books', { 'Title' => 'Ruby' } )
+  def test_item_search_iso_8859_15
+
+    # Ensure that character set encoding works properly by manually trying
+    # ISO-8859-15, a.k.a. Latin-15.
+    #
+    @req.encoding = 'iso-8859-15'
+    is = ItemSearch.new( 'Books', { 'Title' => 'Caf�' } )
     response = @req.search( is, @rg )
 
     results = response.kernel
@@ -18,4 +23,36 @@ class TestItemSearch < AWSTest
 
   end
 
+  def test_item_search_utf8
+
+    # Manually set UTF-8 encoding.
+    #
+    @req.encoding = 'utf-8'
+    is = ItemSearch.new( 'Books', { 'Title' => 'Café' } )
+    response = @req.search( is, @rg )
+
+    results = response.kernel
+
+    # Ensure we got some actual results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_item_search_multiple_pages
+
+    is = ItemSearch.new( 'Books', { 'Title' => 'programming' } )
+    responses = @req.search( is, @rg, 5 )
+
+    results = []
+    responses.each do |response|
+      results += response.kernel
+    end
+
+    # Ensure we got more than 10 results back.
+    #
+    assert( results.size > 10 )
+
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ruby-aaws
 version: !ruby/object:Gem::Version 
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors: 
 - Ian Macdonald
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-29 00:00:00 +01:00
+date: 2009-05-26 00:00:00 +02:00
 default_executable: 
 dependencies: []