rwebthumb 0.1

data/README

@@ -0,0 +1,54 @@
+== rwebthumb
+
+= what is it
+A Ruby wrapper for the webthumb API from http://webthumb.bluga.net and a generator
+for the easythumb API
+
+= Installation
+sudo gem update --system (in case you are not yet on version 1.2.0 or higher)
+sudo gem sources -a http://gems.github.com (only once)
+sudo gem install filippocamillo-rwebthumb
+
+
+= Usage
+# require the libs
+require 'rubygems'
+require 'rwebthumb'
+include Simplificator::Webthumb
+
+# Creating a Webthumb Object. This is used as your main access point.
+wt = Webthumb.new('YOUR API KEY')
+
+# Create a new thumbnail job
+job = wt.thumbnail(:url => 'http://www.filippocamillo.com')
+
+# fetch the thumbnail. this might throw an exception from server side
+# if thumb is not ready yet
+job.fetch(:large)
+
+# you can check the status of a job by request id
+job.check_status
+
+# you can also now check the status of a job by url
+job.check_status_by_url
+
+# or fetch the thumbnail when it is complete
+job.fetch_when_complete(:large)
+
+# once thumbnails are fetched they are cached within the job. so a new fetch will not go to the server again
+
+# there is a helper method to write the images to disk
+job.write_file(job.fetch(:custom), '/tmp/test.jpg')
+
+# if you have a job ID then you can use this to get a Job object and then use the fetch_xyz methods
+wt.job_status(JOB_ID)
+
+# check the status of your account
+wt.status
+
+
+# generate a Easythumb URL
+et = Easythumb.new('YOUR_API_KEY', 'YOUR_USER_ID')
+# This returns an URL which you can directly use in your webpage
+et.build_url(:url => 'http://simplificator.com', :size => :large, :cache => 1)
+

data/init.rb

@@ -0,0 +1 @@
+require 'rwebthumb'

data/lib/rwebthumb.rb

@@ -0,0 +1,5 @@
+require 'time'
+require 'rwebthumb/base'
+require 'rwebthumb/job'
+require 'rwebthumb/webthumb'
+require 'rwebthumb/easythumb'

data/lib/rwebthumb/base.rb

@@ -0,0 +1,78 @@
+module Simplificator
+  module Webthumb
+    #
+    #
+    #
+    #
+    class Base
+      # Valid output_types for thumbnail requests
+      VALID_OUTPUT_TYPES = [:jpg, :png]
+      # Valid values for size element in fetch requests
+      VALID_SIZES = [:small, :medium, :medium2, :large, :full, :excerpt, :effect, :custom, :zip]
+
+      attr_reader :api_key
+      # Constructor
+      #  api_key: the Webthumb api key, not nil and not blank
+      #
+      def initialize(api_key, api_endpoint = 'http://webthumb.bluga.net/api.php')
+        raise WebthumbException.new('Need an not nil and not blank api_key') if api_key == nil || api_key == ''
+        @api_key = api_key
+        @api_endpoint = api_endpoint
+        @api_uri = URI.parse(@api_endpoint)
+      end
+
+      # Parse the datetime string and returns a DateTime object in UTC time
+      # Webthumb returns the time in MST (Mountain Standard Time) which is some 7 hours
+      # behind UTC
+      def self.parse_webthumb_datetime(s)
+        Time.parse("#{s} MST").getutc
+      end
+
+      def do_request(xml)
+        request = Net::HTTP::Post.new(@api_uri.path)
+        request.body = xml.to_s
+        response = Net::HTTP.new(@api_uri.host, @api_uri.port).start {|p| p.request(request) }
+        case response
+        when Net::HTTPOK :
+          case response.content_type.downcase
+          when 'text/xml' : REXML::Document.new(response.body)
+          when 'image/jpg', 'image/jpeg', 'image/png'
+            raise WebthumbException.new("No data returned though content type is #{response.content_type}") if response.body.length == 0
+            response.body
+          else
+            raise WebthumbException.new("usupported content type #{response.content_type}. Body was: \n#{response.body}")
+          end
+        else
+          raise CommunicationException('Response code was not HTTP OK')
+        end
+      end
+
+      # builds the root node for webthumb requtes
+      def  build_root_node()
+        root = REXML::Element.new('webthumb')
+        api = root.add_element('apikey')
+        api.text = @api_key
+        root
+      end
+
+      protected
+      #
+      # add a XML element if value is present.
+      # can be used to create XML for webthumb requests from ruby options hash.
+      #
+      # root: the root XML element where element is added to
+      # options: the hash where value is taken from
+      # key: the key to lookup the value in options
+      # name: the name of the XML element. defaults to key
+      #
+      def add_element(root, options, key, name = key.to_s)
+        root.add_element(name).add_text(options[key].to_s) if options.has_key?(key)
+      end
+
+    end
+    class WebthumbException < RuntimeError
+    end
+    class CommunicationException < RuntimeError
+    end
+  end
+end

data/lib/rwebthumb/easythumb.rb

@@ -0,0 +1,27 @@
+require 'cgi'
+require 'digest/md5'
+module Simplificator
+  module Webthumb
+    class Easythumb
+      VALID_SIZES = [:small, :medium, :medium2, :large]
+      def initialize(api_key, user_id, api_endpoint = 'http://webthumb.bluga.net/easythumb.php')
+        @api_key = api_key
+        @user_id = user_id
+        @api_endpoint = api_endpoint
+      end
+      
+      # Build an Easythumb URL
+      # options are
+      #  url: the url to take a snapshot from. required.
+      #  size: the size of the thumbnail to take (VALID_SIZES). Defaults to :medium
+      #  cache: the maximum allowed age in the cache (1-30). Defaults to 15
+      def build_url(options = {})
+        raise WebthumbException.new(':url is required') if (options[:url] == nil || options[:url] == '')
+        options[:size] ||= :medium
+        options[:cache] ||= 15
+        hash_out = Digest::MD5.hexdigest("#{Time.now.strftime('%Y%m%d')}#{options[:url]}#{@api_key}")
+        "#{@api_endpoint}?user=#{@user_id}&cache=#{options[:cache]}&size=#{options[:size]}&url=#{CGI.escape(options[:url])}&hash=#{hash_out}"
+      end
+    end
+  end
+end

data/lib/rwebthumb/job.rb

@@ -0,0 +1,140 @@
+module Simplificator
+  module Webthumb
+    class Job < Base
+
+      attr_reader :duration_estimate, :submission_datetime, :cost, :job_id, :url
+
+      # Constant for the status attribute when job is beeing processed
+      STATUS_PROCESSING = 100
+      # Constant for the status attribute when job is done
+      STATUS_PICKUP = 200
+
+      # Factory method to build a Job object from a REXML xml element
+      def self.from_thumbnail_xml(api_key, xml)
+        job_element = REXML::XPath.first(xml, '/webthumb/jobs/job')
+        return nil if job_element.nil?
+
+        submission_datetime = self.parse_webthumb_datetime(job_element.attributes['time'])
+        Job.new(api_key, job_element.text, job_element.attributes['url'], submission_datetime, job_element.attributes['estimate'].to_i, job_element.attributes['cost'].to_i)
+      end
+      # Factory method to create a Job object from a status XML.
+      # this does not set all attributes of the Job (url, duration_estimate, cost) since the API of webthumb does not
+      # return the same information on job creation and status requests.
+      def self.from_status_xml(api_key, xml)
+        status_element = REXML::XPath.first(xml, '/webthumb/jobStatus/status')
+        submission_datetime = self.parse_webthumb_datetime(status_element.attributes['submissionTime'])
+        job = Job.new(api_key, status_element.attributes['id'], nil, submission_datetime, 5, nil,
+          status_element.text == 'Complete' ? STATUS_PICKUP : STATUS_PROCESSING)
+      end
+      # Constructor.
+      # *api_key: webthumb API key. Required by all the operations which query the server
+      # *job_id: id of the job. Required.
+      # *url: the url of the site to snapshot. Optional
+      # *submission_datetime: UTC Datetime of job submission
+      # *duration_estimate: integer value indicating estimated job duration in seconds
+      # *cost: integer value indicating how many credit this request costet. Optional
+      # *status: one of the STATUS_XXX constants defined in Base. Defaults to STATUS_PROCESSING
+      def initialize(api_key, job_id, url, submission_datetime, duration_estimate, cost, status = STATUS_PROCESSING)
+        super(api_key)
+        @job_id = job_id
+        @url = url
+        @submission_datetime = submission_datetime
+        @duration_estimate = duration_estimate
+        @cost = cost
+        @status = status
+        @cache = {}
+      end
+
+      # Checks the status of the job on webthumb server.
+      # Returns one of the STATUS_XXX constants from Base.
+      # A call to this method updates the @status attribute.
+      def check_status
+        response = do_request(build_status_xml())
+        @status = REXML::XPath.first(response, '/webthumb/jobStatus/status').text == 'Complete' ? STATUS_PICKUP : STATUS_PROCESSING
+        if pickup?
+          @completion_time = response.attributes['completionTime']
+        end
+        @status
+      end
+
+      def check_status_by_url
+        response = do_request(build_status_by_url())
+        @status = REXML::XPath.first(response, '/webthumb/jobStatus/status').text == 'Complete' ? STATUS_PICKUP : STATUS_PROCESSING
+        if pickup?
+          @completion_time = response.attributes['completionTime']
+        end
+        @status
+      end
+
+      def fetch_when_complete(size = :small)
+        while not pickup?
+          sleep @duration_estimate
+          check_status
+        end
+        fetch(size)
+      end
+
+      # Fetch an image from the webthumb server.
+      # If the job has not yet finished then the server will return an error so check status first or use fetch_when_complete()
+      # Images are cached in the context of this Job so consequent calls are not requested from server again.
+      # Cache is experimental, dont know if it is a good idea.
+      def fetch(size = :small)
+        unless @cache.has_key?(size)
+          response = do_request(build_fetch_xml(size))
+          @cache[size] = response
+        end
+        @cache[size]
+      end
+
+      # Write the data to disk.
+      # *data: the bytes of the image as returned by fetch/fetch_when_complete
+      # *name: a filename
+      # Will return a File object
+      def write_file(data, name)
+        raise WebthumbException.new('NO data given') if data == nil || data.size == 0
+        File.open(name, 'wb+') do |file|
+          file.write(data)
+          file.close
+          file
+        end
+      end
+
+      # Is the status attribute set to STATUS_PICKUP ?
+      def pickup?
+        @status == STATUS_PICKUP
+      end
+      # Is the status attribute set to STATUS_PROCESSING ?
+      def processing?
+        @status == STATUS_PROCESSING
+      end
+
+      private
+      def build_fetch_xml(size = :small)
+        raise WebthumbException.new("size parameter must be one of #{VALID_SIZES.join(', ')} but was #{size}") unless Base::VALID_SIZES.include?(size)
+        root = build_root_node()
+        fetch = root.add_element('fetch')
+        fetch.add_element('job').add_text(@job_id)
+        fetch.add_element('size').add_text(size.to_s)
+        root
+      end
+      def build_status_xml()
+        root = build_root_node()
+        status = root.add_element('status')
+        status.add_element('job').add_text(@job_id)
+        root
+      end
+
+      def build_status_by_url()
+        root = build_root_node()
+        status = root.add_element('status')
+        status.add_element('url').add_text(@url)
+        root
+      end
+
+
+      def to_s
+        "Job: #{@job_id} / Status: #{@status} / Submission Time #{@submission_time} / Duration Estimate #{@duration_estimate}"
+      end
+    end
+  end
+end

data/lib/rwebthumb/webthumb.rb

@@ -0,0 +1,121 @@
+require 'net/http'
+require 'rexml/document'
+require 'date'
+module Simplificator
+  module Webthumb
+
+    #
+    # Main access point for the webthumb API.
+    # All methods calling the Server need the api key beeing set.
+    #
+    class Webthumb < Base
+      # Request thumbnail creation from webthumb server. A Job object holding 
+      # request information is returned (most important the job_id)
+      # Some keys have been ruby-ized (i.e. outputType -> :output_type). All keys are
+      # Symbols. Check out the webthumb API description for detailed explanation of the options
+      # http://webthumb.bluga.net/apidoc
+      # Options:
+      # * url: the url to take the snapshot from
+      # * output_type: chose output format (jpg or png)
+      # * width: width of the browser
+      # * height: height of the browser
+      # * fullthumb: full sized snapshot (true or false)
+      # * custom_thumbnail: create a custom sized thumbnail. A hash with width and height entries
+      # * effect: specify a visual effect (mirror, dropshadow or border)
+      # * delay: wait until the snapshot is taken
+      # * notify: callback url which is called after snapshot is taken
+      # * excerpt: taking an excerpt snapshot. A hash with for entries. width, height, x, y
+      # * videothumb: experimental option, check Joshs blog (http://blog.joshuaeichorn.com/archives/2008/07/08/videothumb-addon-to-webthumb-is-alpha/)
+      #   (true or false)
+      # Only the url option is required. Check webthumb API for default values. Check also the different constants 
+      # defined in Base.rb for valid values
+      #
+      def thumbnail(options = {})
+        Job.from_thumbnail_xml(@api_key, do_request(build_thumbnail_xml(options)))
+      end
+      
+      # Request the job status from server.
+      # This can be used to look up job status from server when you just have the job ID, e.g. when you want to retrieve
+      # the thumbs later or when you use callbacks.
+      # The Job object returned from this method does not have all attributes set since. Webthumbs API does not return
+      # the requested URL, the duration estimation and the cost values when checking the status. I hope this will change someday.
+      def job_status(job_id)
+        raise WebthumbException.new('Job id is required') if job_id == nil || job_id == ''
+        Job.from_status_xml(@api_key, do_request(build_job_status_xml(job_id)))
+      end
+      
+      # Check your credit status on the webthumbs server
+      # Returns a hash with two keys. See webthumb API for detailed information.
+      # * reserve: an integer
+      # * subscription: an integer
+      def credits()
+        response = do_request(build_credits_xml())
+        credit_element = REXML::XPath.first(response, '/webthumb/credits')
+        {:reserve => credit_element['reserve'].text.to_i, :subscription => credit_element['subscription'].text.to_i}
+      end
+      
+      # This method doesn't work
+      # <webthumb>
+      #   <credits>
+      #     <used-this-month>1642.5</used-this-month>
+      #     <easythumb-cached-this-month>15765</easythumb-cached-this-month>
+      #     <subscription>1000</subscription>
+      #     <reserve>45587.1</reserve>
+      #   </credits>
+      # </webthumb>
+      
+      private 
+      def build_thumbnail_xml(options)
+        validate_thumbnail_options(options)
+        
+        
+        root = build_root_node()
+        request = root.add_element('request')
+        request.add_element('url').add_text(options[:url])
+        add_element(request, options, :output_type, 'outputType')
+        # these elements have the same name as the key in options hash
+        [:width, :height, :effect, :delay, :notify].each {|item| add_element(request, options, item)}
+        # these options need conversion from true/false to 0/1
+        if options[:fullthumb] == true
+          request.add_element('fullthumb').add_text('1')
+        end
+        if options[:videothumb] == true
+          request.add_element('videothumb').add_text('1')
+        end
+        if options.has_key?(:custom_thumbnail)
+          request.add_element('customThumbnail', 
+            'width' => options[:custom_thumbnail][:width].to_s, 
+            'height' => options[:custom_thumbnail][:height].to_s)
+				
+        end
+        if options.has_key?(:excerpt)
+          excerpt = request.add_element('excerpt')
+          [:x, :y, :width, :height].each {|item| add_element(excerpt, options[:excerpt], item)}
+        end
+        root
+      end
+      
+      def build_job_status_xml(job_id)
+        root = build_root_node()
+        root.add_element('status').add_element('job').add_text(job_id)
+        root
+      end
+      
+      def build_credits_xml()
+        root = build_root_node()
+        root.add_element('credits')
+        root
+      end
+      
+      def validate_thumbnail_options(options)
+        raise WebthumbException.new('Need an URL') if options[:url] == nil || options[:url] == ''
+        #raise WebthumbException.new("output_type is invalid: #{options[:output_type]}") if options.has_key?(:output_type) and (not Base::VALID_OUTPUT_TYPES.include?(options[:output_type]))
+      end
+    end
+
+  end
+end
+
+
+
+

data/test/base_test.rb

@@ -0,0 +1,23 @@
+require File.join(File.dirname(__FILE__), 'helper')
+class BaseTest < Test::Unit::TestCase
+  def test_api_key_required
+    assert_raises(WebthumbException) { Base.new('') }
+    assert_raises(WebthumbException) { Base.new(nil) }
+  end
+
+  def test_parse_webthumb_date
+    [['2000-1-1 14:00:00', '2000-1-1 07:00:00'], ['2000-1-1 07:00:00', '2000-1-1 00:00:00'], ['2000-8-1 07:44:2', '2000-8-1 00:44:02']].each do |item|
+      utc = Time.parse("#{item[0]} UTC")
+      mst = Base.parse_webthumb_datetime(item[1])
+      assert_equal(utc, mst)
+    end
+  end
+
+  def test_build_root_node()
+    root = Base.new('1234').build_root_node()
+    assert_not_nil(root)
+    assert_not_nil(REXML::XPath.first(root, '/'))
+    assert_not_nil(REXML::XPath.first(root, '/apikey'))
+    assert_equal('1234', REXML::XPath.first(root, '/apikey').text)
+  end
+end

data/test/helper.rb

@@ -0,0 +1,4 @@
+require 'test/unit'
+require 'rubygems'
+require 'rwebthumb'
+include Simplificator::Webthumb

data/test/job_test.rb

@@ -0,0 +1,48 @@
+require File.join(File.dirname(__FILE__), 'helper')
+class JobTest < Test::Unit::TestCase
+  JOB_XML = <<-EOF
+    <webthumb>
+      <jobs>
+        <job estimate='20' time='2008-02-27 12:49:48' url='http://blog.joshuaeichorn.com' cost='1'>wt47c5f71c37c3a</job>
+      </jobs>
+    </webthumb>
+  EOF
+
+  JOBLESS_XML = <<-EOF
+    <webthumb>
+    </webthumb>
+  EOF
+
+  def setup_job_from_xml(xml)
+    job_xml = REXML::Document.new(xml)
+    @job = Job.from_thumbnail_xml('1234', job_xml)
+  end
+
+  def test_from_thumbnail_xml
+    setup_job_from_xml(JOB_XML)
+    assert_equal('1234', @job.api_key)
+    assert_equal(20, @job.duration_estimate)
+    assert_equal(Time.parse('2008-02-27 19:49:48 UTC'), @job.submission_datetime)
+    assert_equal('http://blog.joshuaeichorn.com', @job.url)
+    assert_equal(1, @job.cost)
+    assert_equal('wt47c5f71c37c3a', @job.job_id)
+  end
+
+  def test_build_fetch()
+    setup_job_from_xml(JOB_XML)
+    xml = @job.send(:build_fetch_xml)
+    assert_equal('small', REXML::XPath.first(xml, 'fetch/size').text)
+    assert_equal('wt47c5f71c37c3a', REXML::XPath.first(xml, 'fetch/job').text)
+  end
+
+  def test_build_status_xml()
+    setup_job_from_xml(JOB_XML)
+    xml = @job.send(:build_status_xml)
+    assert_equal('wt47c5f71c37c3a', REXML::XPath.first(xml, 'status/job').text)
+  end
+
+  def test_from_thumbnail_xml_without_any_jobs()
+    setup_job_from_xml(JOBLESS_XML)
+    assert_nil @job
+  end
+end

data/test/webthumb_test.rb

@@ -0,0 +1,35 @@
+require File.join(File.dirname(__FILE__), 'helper')
+class WebthumbTest < Test::Unit::TestCase
+  
+  
+  
+  def test_build_fetch()
+    xml = Webthumb.new('1234').send(:build_thumbnail_xml, 
+      :url => 'http://simplificator.com', 
+      :videothumb => true, :fullthumb => true, :effect => 'dropshadow', :output_type => :jpg, 
+      :width => 1024, :height => 2048, :custom_thumbnail => {:width => 300, :height => 400},
+      :excerpt => {:x => 30, :y => 40, :width => 600, :height => 345}, :delay => 20, :notify => 'http://foo.bar.com')
+    assert_equal('http://simplificator.com', REXML::XPath.first(xml, 'request/url').text)
+    assert_equal('1', REXML::XPath.first(xml, 'request/videothumb').text)
+    assert_equal('1', REXML::XPath.first(xml, 'request/fullthumb').text)
+    assert_equal('dropshadow', REXML::XPath.first(xml, 'request/effect').text)
+    assert_equal('jpg', REXML::XPath.first(xml, 'request/outputType').text)
+    assert_equal('1024', REXML::XPath.first(xml, 'request/width').text)
+    assert_equal('2048', REXML::XPath.first(xml, 'request/height').text)
+    assert_equal('300', REXML::XPath.first(xml, 'request/customThumbnail').attributes['width'])
+    assert_equal('400', REXML::XPath.first(xml, 'request/customThumbnail').attributes['height'])
+    assert_equal('30', REXML::XPath.first(xml, 'request/excerpt/x').text)
+    assert_equal('40', REXML::XPath.first(xml, 'request/excerpt/y').text)
+    assert_equal('600', REXML::XPath.first(xml, 'request/excerpt/width').text)
+    assert_equal('345', REXML::XPath.first(xml, 'request/excerpt/height').text)
+    assert_equal('20', REXML::XPath.first(xml, 'request/delay').text)
+    assert_equal('http://foo.bar.com', REXML::XPath.first(xml, 'request/notify').text)
+    
+    
+  end
+
+  def test_build_job_status_xml()
+    xml = Webthumb.new('1234').send(:build_job_status_xml, 'abcd')
+    assert_equal('abcd', REXML::XPath.first(xml, 'status/job').text)
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: rwebthumb
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+platform: ruby
+authors: 
+- Filippo Camillo
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-29 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: rwebthumb provides a ruby interface for the webthumb.bluga.net
+email: info@xnovo.it
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/rwebthumb.rb
+- lib/rwebthumb/base.rb
+- lib/rwebthumb/job.rb
+- lib/rwebthumb/webthumb.rb
+- test/base_test.rb
+- test/helper.rb
+- test/job_test.rb
+- test/webthumb_test.rb
+- lib/rwebthumb/easythumb.rb
+- README
+- init.rb
+has_rdoc: true
+homepage: http://www.filippocamillo.com/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: rwebthumb provides a ruby interface for the webthumb.bluga.net
+test_files: []
+