thumbnail 0.2.0

data/History.txt

@@ -0,0 +1,8 @@
+== 0.2.0 2007-06-08
+
+* Initial release:
+  * fully wraps the AWS-AST REST API
+  * tested on Mac OS X 10.4.9 (PowerPC architecture) with Ruby 1.8.5
+  * complete spec suite
+  * basic rdoc and website
+  * rad logo

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Greg Borenstein
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,28 @@
+client_spec.txt
+response_spec.txt
+History.txt
+License.txt
+lib/thumbnail.rb
+lib/thumbnail/version.rb
+lib/thumbnail/client.rb
+lib/thumbnail/response.rb
+Manifest.txt
+Rakefile
+README.txt
+setup.rb
+spec/client_spec.rb
+spec/response_spec.rb
+spec/spec.opts
+spec/fixtures/batch.xml
+spec/fixtures/single.xml
+spec/fixtures/unexists.xml
+spec/fixtures/invalid_credentials.xml
+website/index.html
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/amzn.jpg
+website/craphound.jpg
+website/logo.png
+website/small_crap.jpg
+website/soon.jpg
+

data/README.txt

@@ -0,0 +1,88 @@
+= THUMBNAIL 
+
+A Ruby wrapper for the Amazon Web Services Alexa Site Thumbnail Service REST API, which provides website thumbnail images on demand for a small fee ($0.20/1000).
+
+    by Greg Borenstein
+    thumbnail.rubyforge.org
+    
+== Installing
+    
+    $ sudo gem install thumbnail
+    
+Thumbnail depends on the terrific Hpricot (http://code.whytheluckystiff.net/hpricot) XHTML parsing and manipulation library by why the lucky stiff; version 0.5 or better has the necessary powers.
+
+== Registering with Amazon
+
+In order to use the AWS-AST api, you must first complete the following series of bureaucratic tasks:
+
+1. Signup for an Amazon Web Services account (if you don't yet have one) by visiting http://aws.amazon.com . You can use your existing Amazon user account for this or create a new one.
+
+2. Signup for the Alexa Site Thumbnail Service (http://www.amazon.com/b/ref=sc_fe_c_0_239513011_4/102-1130464-8229719?ie=UTF8&node=236156011&no=239513011&me=A36L942TSJ2AJA)
+
+3. Find and note your AWS Access Key Id and your Secret Access Key. You'll need to tell Thumbnail about these for authentication's sake; you should be given them at the end of the signup process.
+
+Registering for both of these accounts is free, payment for the Site Thumbnail Service is based entirely on usage, with no charges for requests for unavailable thumbnails.
+
+== Some Usage Examples
+
+Download a small thumbnail of http://www.craphound.com as a local file called small_crap.jpg:
+
+    require 'thumbnail'
+    require 'open-uri'
+    
+    t = Thumbnail::Client.new :access_key_id => YOUR_ACCESS_KEY_ID, :secret_access_key => YOUR_SECRET_ACCESS_KEY, :size => :small
+    url = t.get("www.craphound.com")[:thumbnail][:url]
+    File.open("small_crap.jpg", "w") { |f| f.write open(url).read }
+    
+Write a view helper for use in a Rails application to generate image tags with Amazon redirect urls in your templates. In app/helpers/my_helper.rb:
+
+    module MyHelper
+      def thumbnail_image(url, size=:large)_
+        t = Thumbnail::Client.new :access_key_id => AWS_ACCESS_KEY_ID, :secret_access_key => AWS_SECRET_ACCESS_KEY, 
+                                  :action => :redirect, :size => size
+        "<img src=\"#{t.get(url)}\">"
+      end
+    end
+  
+which, assuming you'd defined AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in your environment.rb file and required thumbnail somewhere along the line, you'd use in your view like so:
+
+    <%= thumbnail_image("www.craphound.com") %>
+
+(Work is underway on a plugin that would make this helper universally available within your app.)
+    
+Download large thumbnails for a bunch of sites in one batch with error handling:  
+  
+    require 'thumbnail'
+    require 'open-uri'
+    
+    t = Thumbnail::Client.new :access_key_id => YOUR_ACCESS_KEY_ID, :secret_access_key => YOUR_SECRET_ACCESS_KEY
+    result = t.get(["www.craphound.com", "www.urbanhonking.com", "www.twitter.com"])
+    if result.is_a? Thumbnail::Response::Success
+      result.parsed.each do |r|
+        url = r[:thumbnail][:url]
+        filename = "#{r[:thumbnail][:request_url].split(".")[1]}.jpg"
+        File.open(filename, "w") { |f| f.write open(url).read }
+      end
+    else
+      puts "Request failed! #{result}"
+    end
+    
+For a more verbose walkthrough (and an idea of what the thumbnails look like), visit Thumbnail's rubyforge homepage: http://thumbnail.rubyforge.org. For more details on the library's operation, see the spec output in client_spec.txt and response_spec.txt.
+
+== Other Facts of Note
+
+-If a site thumbnail is not available, AWS-AST will return the "not available" image and will not charge for the api call. The actual site thumbnail will be created within 24 hours. The parsed results hash of a Thumbnail::Response::Success object offers programatic access to this via the <code>:exists</code> key.
+
+-Thumbnail urls generated by calls to the api are good for 15 seconds, so run your code that downloads and saves them right away.
+
+== AWS-AST API Docs
+
+http://docs.amazonwebservices.com/AlexaSiteThumbnail/2007-01-01/
+
+== License
+
+Copyright 2007 Greg Borenstein. This code is free to use under the terms of the MIT license.
+
+== Feedback
+
+Got questions? Got Kudos? Email me: greg@mfdz.com.

data/Rakefile

@@ -0,0 +1,140 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  puts 'To use rspec for testing you must install rspec gem:'
+  puts '$ sudo gem install rspec'
+  exit
+end
+
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'thumbnail', 'version')
+
+AUTHOR = 'Greg Borenstein'  # can also be an array of Authors
+EMAIL = "greg@mfdz.com"
+DESCRIPTION = "Wrapper for the Amazon Web Services Alexa Thumbnail Service REST API, which provides website thumbnail images on demand for a small fee ($0.20/1000)"
+GEM_NAME = 'thumbnail' # what ppl will type to install your gem
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}"
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  @rubyforge_username ||= @config["username"]
+end
+
+RUBYFORGE_PROJECT = 'thumbnail' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+NAME = "thumbnail"
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = Thumbnail::VERSION::STRING + (REV ? ".#{REV}" : "")
+CLEAN.include ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']
+RDOC_OPTS = ['--quiet', '--title', 'thumbnail documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= CLEAN  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.extra_deps = []     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\n\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.spec.files << "client_spec.txt"
+hoe.spec.files << "response_spec.txt"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+
+desc 'Generate website files'
+task :website_generate do
+  Dir['website/**/*.txt'].each do |txt|
+    sh %{ ruby scripts/txt2html #{txt} > #{txt.gsub(/txt$/,'html')} }
+  end
+end
+
+desc 'Upload website files to rubyforge'
+task :website_upload do
+  host = "#{rubyforge_username}@rubyforge.org"
+  remote_dir = "/var/www/gforge-projects/#{PATH}/"
+  local_dir = 'website'
+  sh %{rsync -aCv #{local_dir}/ #{host}:#{remote_dir}}
+end
+
+desc 'Generate and upload website files'
+task :website => [:website_generate, :website_upload, :publish_docs]
+
+desc 'Release the website and new gem version'
+task :deploy => [:check_version, :website, :release] do
+  puts "Remember to create SVN tag:"
+  puts "svn copy svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/trunk " +
+    "svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/tags/REL-#{VERS} "
+  puts "Suggested comment:"
+  puts "Tagging release #{CHANGES}"
+end
+
+desc 'Runs tasks website_generate and install_gem as a local deployment of the gem'
+task :local_deploy => [:website_generate, :install_gem]
+
+task :check_version do
+  unless ENV['VERSION']
+    puts 'Must pass a VERSION=x.y.z release version'
+    exit
+  end
+  unless ENV['VERSION'] == VERS
+    puts "Please update your version.rb to match the release version, currently #{VERS}"
+    exit
+  end
+end
+
+desc "Run the specs under spec/models"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_files = FileList['spec/*_spec.rb']
+end
+
+desc "Default task is to run specs"
+task :default => :spec
+

data/client_spec.txt

@@ -0,0 +1,58 @@
+
+Thumbnail::Client#new
+- should default to the thumbnail action
+- should set the action as redirect if specified
+- should raise an error if the action is neither redirect nor thumbnail
+- should raise an error if the access_key_id is not specified
+- should raise an error if the secret_access_key is not specified
+- should default the size to large
+- should set the size to small if specified
+- should raise an error if the size is neither large nor small
+- should raise an error if a default_image is specified for a Thumbnail action
+
+Thumbnail::Client#new for a redirect
+- should set the default_image if specified
+
+Thumbnail#query
+- should calculate the signature and timestamp
+
+Thumbnail#calculate_signature_and_timestamp
+- should calculate the signature
+- should set the (correctly formatted) timestamp
+
+Thumbnail#query with thumbnail action and a single url
+- should compose a thumbnail single query
+
+Thumbnail::Client#query with thumbnail action and an array of urls
+- should compose a thumbnail batch query
+
+Thumbnail::Client#query with redirect action
+- should compose a redirect query
+
+Thumbnail::Client#thumbnail_query_single
+- should compose the query url correctly
+
+Thumbnail::Client#thumbnail_query_batch
+- should compose the query url correctly
+
+Thumbnail::Client#redirect_query with a default_image
+- should compose the query url correctly
+
+Thumbnail::Client#redirect_query without a default_image
+- should compose the query url correctly
+
+Thumbnail::Client#get with a thumbnail action
+- should set the url string if given a single url
+- should set the url array if given an array of urls
+- should parse the url before conducting the query
+- should use net/https to conduct the query
+- should build a response object from the xml
+
+Thumbnail::Client#get with one or more invalid urls
+- should raise an error with one url that is invalid
+- should raise an error if any of the urls in its give array are invalid
+
+Thumbnail::Client#get with a redirect action
+- should raise an error if given an array of urls
+- should calculate the query url
+- should return the redirect query

data/lib/thumbnail.rb

@@ -0,0 +1 @@
+Dir['thumbnail/**/*.rb'].sort.each { |lib| require lib }

data/lib/thumbnail/client.rb

@@ -0,0 +1,106 @@
+require "base64"
+require "net/https"
+require "uri"
+require 'cgi'
+
+module Thumbnail
+  
+  class Client
+    attr_accessor :size, :action
+    
+    # <code>:access_key_id</code> and <code>:secret_access_key</code> are required.
+    # Optionally, you can indicate <code>:action => :redirect</code> (default is :thumbnail),
+    # <code>:size => :small</code> (default is :large), and <code>:default_image => '<image_url>'</code> (only available in
+    # conjunction with <code>:action => :redirect</code>)
+    def initialize(opts={})
+      if opts[:action] && ![:thumbnail, :redirect].include?(opts[:action])
+        raise ArgumentError, "Bad action. Must be thumbnail or redirect. Defaults to thumbnail." 
+      end
+      
+      if opts[:size] && ![:large, :small].include?(opts[:size])
+        raise ArgumentError, "Size must be large or small. Defaults to large"
+      end
+      
+      unless opts[:access_key_id] && opts[:secret_access_key]
+        raise ArgumentError, "Must include your access_key_id and your secret_access_key."
+      end 
+      
+      @size = opts[:size] || :large
+      @action = opts[:action] || :thumbnail 
+      @access_key_id = opts[:access_key_id]
+      @secret_access_key = opts[:secret_access_key]
+          
+      if opts[:default_image] && (@action == :thumbnail)
+        raise ArgumentError, "Can only specify a default_image on the redirect action."
+      end
+          
+      @default_image = opts[:default_image]
+    end
+    
+    # The main method for using this library.
+    # get() can take a single url, or an array of them (only available for the thumbnail action).
+    # For a request with <code>:action => :redirect</code>
+    # it will return the composed query url; for a thumbnail action
+    # it will build your query, send it to Amazon, and build
+    # and return the Thumbnail::Response object.
+    def get(url)
+      if (@action == :redirect) 
+        if url.is_a?(Array)
+          raise ArgumentError, "Can only get a single url on a redirect action"
+        else
+          @url = url
+          return query
+        end
+      end
+      
+      url.each{|u| URI.parse(u)}
+      
+      @url = url
+      xml = Net::HTTP.get(URI.parse(query))
+      Response.build(xml)
+    end
+    
+    private
+
+    # (adapted from amzn's topsites example:  http://developer.amazonwebservices.com/connect/entry!default.jspa?categoryID=32&externalID=408&fromSearchPage=true    )
+    def calculate_signature_and_timestamp
+      @timestamp = ( Time.now ).utc.strftime("%Y-%m-%dT%H:%M:%S.000Z")
+      
+      @signature = CGI.escape(Base64.encode64( OpenSSL::HMAC.digest( OpenSSL::Digest::Digest.new( "SHA1" ), @secret_access_key, @action.to_s.capitalize + @timestamp)).strip)
+    end
+  
+    def query
+      calculate_signature_and_timestamp
+
+      if @action == :thumbnail
+        if @url.is_a? Array
+          thumbnail_query_batch
+        else
+          thumbnail_query_single
+        end
+      else
+        redirect_query
+      end
+    end
+    
+    
+    def thumbnail_query_single
+      "http://ast.amazonaws.com/?Action=Thumbnail&AWSAccessKeyId=#{@access_key_id}&Signature=#{@signature}&Timestamp=#{@timestamp}&Url=#{@url}&Size=#{@size.to_s.capitalize}"
+    end
+    
+    def thumbnail_query_batch
+      url_params = ""
+      @url.each_with_index do |a,i|
+        url_params << "Thumbnail.#{i+1}.Url=#{a}"
+        url_params << "&" unless (i+1)==@url.length
+      end
+      "http://ast.amazonaws.com/?Action=Thumbnail&AWSAccessKeyId=#{@access_key_id}&Signature=#{@signature}&Timestamp=#{@timestamp}&Shared.Size=#{@size.to_s.capitalize}&#{url_params}"
+    end
+    
+    def redirect_query
+      default_param = @default_image ? "&DefaultImage=#{@default_image}" : ""
+      "http://ast.amazonaws.com/?Action=Redirect&AWSAccessKeyId=#{@access_key_id}&Signature=#{@signature}&Timestamp=#{@timestamp}&Url=#{@url}&Size=#{@size.to_s.capitalize}#{default_param}"
+    end
+  end
+  
+end