carbon 0.2.4 → 0.2.5

data/lib/carbon.rb

@@ -1,7 +1,10 @@
 require 'uri'
 require 'blockenspiel'
-require 'rest' # provided by nap gem
 require 'timeframe'
+require 'digest/sha1'
+require 'rest'    # provided by nap gem
+gem 'SystemTimer' # >=1.2, so as not to be confused with system_timer 1.0
+require 'system_timer'
 require 'active_support/version'
 %w{
   active_support/core_ext/module/attribute_accessors
@@ -44,6 +47,7 @@ module Carbon
   
   REALTIME_URL = 'http://carbon.brighterplanet.com'
   ASYNC_URL = 'https://queue.amazonaws.com/121562143717/cm1_production_incoming'
+  STORAGE_URL = 'http://storage.carbon.brighterplanet.com'
   
   class RealtimeEstimateFailed < RuntimeError # :nodoc:
   end

data/lib/carbon/emission_estimate.rb

@@ -1,5 +1,6 @@
 require 'carbon/emission_estimate/response'
 require 'carbon/emission_estimate/request'
+require 'carbon/emission_estimate/storage'
 
 module Carbon
   # Let's start off by saying that realtime <tt>EmissionEstimate</tt> objects quack like numbers.
@@ -10,11 +11,18 @@ module Carbon
   #
   # At the same time, they contain all the data you get back from the emission estimate web service. For example, you could say <tt>puts my_donut_factor.emission_estimate.oven_count</tt> (see the tests) and you'd get back the oven count used in the calculation, if any.
   class EmissionEstimate
+    def self.parse(str)
+      data = ::ActiveSupport::JSON.decode str
+      data['active_subtimeframe'] = ::Timeframe.interval(data['active_subtimeframe']) if data.has_key? 'active_subtimeframe'
+      data['updated_at'] = ::Time.parse(data['updated_at']) if data.has_key? 'updated_at'
+      data
+    end
+    
     def initialize(emitter)
       @emitter = emitter
     end
     
-    VALID_OPTIONS = [:callback_content_type, :key, :callback, :timeframe]
+    VALID_OPTIONS = [:callback_content_type, :key, :callback, :timeframe, :guid, :timeout, :defer]
     def take_options(options)
       return if options.blank?
       options.slice(*VALID_OPTIONS).each do |k, v|
@@ -25,7 +33,7 @@ module Carbon
     # I can be compared directly to a number, unless I'm an async request.
     def ==(other)
       if other.is_a? ::Numeric and mode == :realtime
-        other == response.number
+        other == number
       else
         super
       end
@@ -38,23 +46,35 @@ module Carbon
     #   > my_car.emission_estimate.model
     #   => 'Ford Taurus'
     def method_missing(method_id, *args, &blk)
-      if !block_given? and args.empty? and response.data.has_key? method_id.to_s
-        response.data[method_id.to_s]
+      if !block_given? and args.empty? and data.has_key? method_id.to_s
+        data[method_id.to_s]
       elsif ::Float.method_defined? method_id
         raise TriedToUseAsyncResponseAsNumber if mode == :async
-        response.number.send method_id, *args, &blk
+        number.send method_id, *args, &blk
       else
         super
       end
     end
-
     attr_writer :callback_content_type
     attr_writer :key
-
+    attr_writer :timeout
+    attr_writer :defer
     attr_accessor :callback
     attr_accessor :timeframe
-    
+    attr_accessor :guid
     attr_reader :emitter
+    def data
+      if storage.present?
+        storage.data
+      else
+        response.data
+      end
+    end
+    def storage
+      @storage ||= {}
+      return @storage[guid] if @storage.has_key? guid
+      @storage[guid] = Storage.new self
+    end
     def request
       @request ||= Request.new self
     end
@@ -65,8 +85,18 @@ module Carbon
       return @response[current_params] if @response.has_key? current_params
       @response[current_params] = Response.new self
     end
+    def defer?
+      @defer == true
+    end
+    def async?
+      callback or defer?
+    end
     def mode
-      callback ? :async : :realtime
+      async? ? :async : :realtime
+    end
+    # Timeout on realtime requests in seconds, if desired.
+    def timeout
+      @timeout
     end
     def callback_content_type
       @callback_content_type || 'application/json'
@@ -76,27 +106,27 @@ module Carbon
     end
     # The timeframe being looked at in the emission calculation.
     def active_subtimeframe
-      response.data['active_subtimeframe']
+      data['active_subtimeframe']
     end
     # Another way to access the emission value.
     # Useful if you don't like treating <tt>EmissionEstimate</tt> objects like <tt>Numeric</tt> objects (even though they do quack like numbers...)
-    def emission_value
-      response.number
+    def number
+      async? ? nil : data['emission'].to_f.freeze
     end
     # The units of the emission.
     def emission_units
-      response.data['emission_units']
+      data['emission_units']
     end
     # Errors (and warnings) as reported in the response.
     # Note: may contain HTML tags like KBD or A
     def errors
-      response.data['errors']
+      data['errors']
     end
     # The URL of the methodology report indicating how this estimate was calculated.
     #   > my_car.emission_estimate.methodology
     #   => 'http://carbon.brighterplanet.com/automobiles.html?[...]'
     def methodology
-      response.data['methodology']
+      data['methodology']
     end
   end
 end

data/lib/carbon/emission_estimate/request.rb

@@ -12,10 +12,13 @@ module Carbon
         send "#{parent.mode}_params"
       end
       def async_params # :nodoc:
+        raise ::ArgumentError, "When using :callback you cannot specify :defer" if parent.defer? and parent.callback
+        raise ::ArgumentError, "When using :defer => true you must specify :guid" if parent.defer? and parent.guid.blank?
         hash = _params
         hash[:emitter] = parent.emitter.class.carbon_base.emitter_common_name
-        hash[:callback] = parent.callback
-        hash[:callback_content_type] = parent.callback_content_type
+        hash[:callback] = parent.callback if parent.callback
+        hash[:callback_content_type] = parent.callback_content_type if parent.callback
+        hash[:guid] = parent.guid if parent.defer?
         {
           :Action => 'SendMessage',
           :Version => '2009-02-01',

data/lib/carbon/emission_estimate/response.rb

@@ -3,7 +3,6 @@ module Carbon
     class Response
       attr_reader :parent
       attr_reader :data
-      attr_reader :number
       attr_reader :raw_request
       attr_reader :raw_response
       def initialize(parent)
@@ -12,6 +11,7 @@ module Carbon
       end
       def load_realtime_data # :nodoc:
         attempts = 0
+        response = nil
         begin
           response = perform
           raise ::Carbon::RateLimited if response.status_code == 403 and response.body =~ /Rate Limit/i
@@ -21,26 +21,31 @@ module Carbon
             sleep 0.2 * attempts
             retry
           else
-            raise $!, "Rate limited #{attempts} time(s) in a row"
+            raise $!
           end
         end
         raise ::Carbon::RealtimeEstimateFailed unless response.success?
-        @data = ::ActiveSupport::JSON.decode response.body
-        instantiate_known_response_objects
-        @number = data['emission'].to_f.freeze
-      end
-      def instantiate_known_response_objects # :nodoc:
-        data['active_subtimeframe'] = ::Timeframe.interval(data['active_subtimeframe']) if data.has_key? 'active_subtimeframe'
+        @data = ::Carbon::EmissionEstimate.parse response.body
       end
       def load_async_data # :nodoc:
         response = perform
         raise ::Carbon::QueueingFailed unless response.success?
         @data = {}
-        @number = nil
       end
       def perform # :nodoc:
+        response = nil
+        if parent.timeout
+          ::SystemTimer.timeout_after(parent.timeout) do
+            response = _perform
+          end
+        else
+          response = _perform
+        end
+        response
+      end
+      def _perform # :nodoc:
         @raw_request = ::REST::Request.new :post, ::URI.parse(parent.request.url), parent.request.body, {'Content-Type' => 'application/x-www-form-urlencoded; charset=utf-8'}
-        @raw_response = @raw_request.perform
+        @raw_response = raw_request.perform
       end
     end
   end

data/lib/carbon/emission_estimate/storage.rb

@@ -0,0 +1,29 @@
+module Carbon
+  class EmissionEstimate
+    class Storage
+      attr_accessor :parent
+      attr_reader :raw_request
+      attr_reader :raw_response
+      def initialize(parent)
+        @parent = parent
+      end
+      def url
+        "#{::Carbon::STORAGE_URL}/#{::Digest::SHA1.hexdigest(parent.key+parent.guid)}"
+      end
+      def present?
+        parent.guid.present? and data.present?
+      end
+      def data
+        return @data[0] if @data.is_a? ::Array
+        @raw_request = ::REST::Request.new :get, ::URI.parse(url)
+        @raw_response = raw_request.perform
+        if raw_response.success?
+          @data = [::Carbon::EmissionEstimate.parse(raw_response.body)]
+        else
+          @data = []
+        end
+        @data[0]
+      end
+    end
+  end
+end

data/spec/lib/carbon_spec.rb

@@ -1,6 +1,85 @@
 require 'spec_helper'
+require 'active_support/json/encoding'
+require 'fakeweb'
 
 CALLBACK_URL = 'http://www.postbin.org/1dj0146'
+KEY = 'valid'
+EXISTING_UNIQUE_ID = 'oisjoaioijodijaosijdoias'
+MISSING_UNIQUE_ID = 'd09joijdoijaloijdoais'
+OTHER_UNIQUE_ID = '1092fjoid;oijsao;ga'
+
+FakeWeb.register_uri  :post,
+                      /carbon.brighterplanet.com.automobiles/,
+                      :status => ["200", "OK"],
+                      :body => {
+                        'emission' => '134.599',
+                        'emission_units' => 'kilograms',
+                        'methodology' => 'http://carbon.brighterplanet.com/something',
+                        'active_subtimeframe' => Timeframe.new(:year => 2008)
+                      }.to_json
+#
+FakeWeb.register_uri  :post,
+                      /carbon.brighterplanet.com.factories/,
+                      :status => ["200", "OK"],
+                      :body => {
+                        'emission' => 1000.0,
+                        'emission_units' => 'kilograms',
+                        'methodology' => 'http://carbon.brighterplanet.com/something',
+                        'active_subtimeframe' => Timeframe.new(:year => 2008)
+                      }.to_json
+#
+FakeWeb.register_uri  :post,
+                      /queue.amazonaws.com/,
+                      :status => ["200", "OK"],
+                      :body => 'You would see an amazon aws response'
+# yep, it's stored!
+FakeWeb.register_uri  :get,
+                      "http://storage.carbon.brighterplanet.com/#{Digest::SHA1.hexdigest(KEY+EXISTING_UNIQUE_ID)}",
+                      :status => ["200", "OK"],
+                      :body => {
+                        'emission' => 1234,
+                        'emission_units' => 'kilograms',
+                        'methodology' => 'http://carbon.brighterplanet.com/something',
+                        'updated_at' => Time.now.as_json
+                      }.to_json
+#
+FakeWeb.register_uri  :get,
+                      "http://storage.carbon.brighterplanet.com/#{Digest::SHA1.hexdigest(KEY+OTHER_UNIQUE_ID)}",
+                      :status => ["200", "OK"],
+                      :body => {
+                        'emission' => 99982,
+                        'emission_units' => 'kilograms',
+                        'methodology' => 'http://carbon.brighterplanet.com/something',
+                        'updated_at' => Time.now.as_json
+                      }.to_json
+#
+FakeWeb.register_uri  :get,
+                      "http://storage.carbon.brighterplanet.com/#{Digest::SHA1.hexdigest(KEY+MISSING_UNIQUE_ID)}",
+                      [
+                        {
+                          :status => ["404", "Not Found"],
+                          :body => "It's not here, you better ask carbon for it!"
+                        },
+                        {
+                          :status => ["200", "OK"],
+                          :body => {
+                            'emission' => 9876,
+                            'emission_units' => 'kilograms',
+                            'methodology' => 'http://carbon.brighterplanet.com/something',
+                            'updated_at' => Time.now.as_json
+                          }.to_json
+                        }
+                      ]
+#
+# FakeWeb.register_uri  :post,
+#                       /carbon.brighterplanet.com.*#{MISSING_UNIQUE_ID}/,
+#                       :status => ["302", "Moved Permanently"],
+#                       :body => {
+#                         'emission' => 9876,
+#                         'emission_units' => 'kilograms',
+#                         'methodology' => 'http://carbon.brighterplanet.com/something'
+#                       }.to_json,
+#                       :headers => { 'Location' => "http://storage.carbon.brighterplanet.com/#{Digest::SHA1.hexdigest(KEY+MISSING_UNIQUE_ID)}" }
 
 class RentalCar
   include Carbon
@@ -45,9 +124,24 @@ class DonutFactory
   end
 end
 
+# set up timeouts
+module Carbon
+  class EmissionEstimate
+    attr_accessor :sleep_before_performing
+    VALID_OPTIONS.push :sleep_before_performing
+    class Response
+      def _perform_with_delay
+        sleep parent.sleep_before_performing if parent.sleep_before_performing
+        _perform_without_delay
+      end
+      alias_method_chain :_perform, :delay
+    end
+  end
+end
+
 describe Carbon do
   before(:each) do
-    Carbon.key = 'valid'
+    Carbon.key = KEY
   end
   
   it 'should be simple to use' do
@@ -104,6 +198,52 @@ describe Carbon do
     end
   end
   
+  describe 'requests that can be stored (cached) by guid' do
+    it 'should find existing unique ids on S3' do
+      d = DonutFactory.new
+      d.emission_estimate(:guid => EXISTING_UNIQUE_ID).should == 1234
+      d.emission_estimate(:guid => EXISTING_UNIQUE_ID).updated_at.should be_instance_of(Time)
+    end
+    it "should pass through to realtime if unique id isn't found on S3" do
+      d = DonutFactory.new
+      d.emission_estimate(:guid => MISSING_UNIQUE_ID).should == 1000
+      d.emission_estimate(:guid => MISSING_UNIQUE_ID).response.data.keys.should_not include('updated_at')
+      d1 = DonutFactory.new
+      d1.emission_estimate(:guid => MISSING_UNIQUE_ID).should == 9876
+      d1.emission_estimate(:guid => MISSING_UNIQUE_ID).updated_at.should be_instance_of(Time)
+    end
+    it "should depend on the user to update the guid if they want a new estimate" do
+      d = DonutFactory.new
+      d.oven_count = 12_000
+      str1 = d.emission_estimate(:guid => EXISTING_UNIQUE_ID).methodology
+      str1.should equal(d.emission_estimate(:guid => EXISTING_UNIQUE_ID).methodology)
+      d.oven_count = 13_000
+      str1.should equal(d.emission_estimate(:guid => EXISTING_UNIQUE_ID).methodology)
+      str1.should_not equal(d.emission_estimate(:guid => OTHER_UNIQUE_ID).methodology)
+    end
+    it 'should be deferrable for use in 2-pass reporting systems' do
+      d = DonutFactory.new
+      d.emission_estimate(:guid => EXISTING_UNIQUE_ID, :defer => true).number.should be_nil
+      d.emission_estimate(:guid => EXISTING_UNIQUE_ID, :defer => true).request.url.should =~ /amazonaws/
+    end
+    it 'should complain if you provide defer but not guid' do
+      d = DonutFactory.new
+      lambda {
+        d.emission_estimate(:defer => true).request.params
+      }.should raise_error(ArgumentError, /defer.*guid/i)
+    end
+    it 'should complain if you provide guid and callback' do
+      d = DonutFactory.new
+      lambda {
+        d.emission_estimate(:defer => true, :callback => 'foobar').request.params
+      }.should raise_error(ArgumentError, /callback.*defer/i)
+    end
+    it 'should send guid along with other parameters when queueing up deferred request' do
+      d = DonutFactory.new
+      d.emission_estimate(:guid => EXISTING_UNIQUE_ID, :defer => true).request.params[:MessageBody].should =~ /#{EXISTING_UNIQUE_ID.to_query(:guid)}/
+    end
+  end
+  
   describe 'synchronous (realtime) requests' do
     it 'should send simple params' do
       d = DonutFactory.new
@@ -138,10 +278,17 @@ describe Carbon do
     it 'should override defaults' do
       d = DonutFactory.new
       key = 'ADifferentOne'
-      d.emission_estimate.key.should == 'valid'
+      d.emission_estimate.key.should == KEY
       d.emission_estimate.key = key
       d.emission_estimate.key.should == key
     end
+    
+    it 'should accept timeouts' do
+      d = DonutFactory.new
+      lambda {
+        d.emission_estimate(:sleep_before_performing => 2, :timeout => 1).to_f
+      }.should raise_error(::Timeout::Error)
+    end
   
     it 'should accept timeframes' do
       c = RentalCar.new
@@ -180,7 +327,7 @@ describe Carbon do
     it 'should have nil data in its response' do
       c = RentalCar.new
       c.emission_estimate.callback = CALLBACK_URL
-      c.emission_estimate.emission_value.should be_nil
+      c.emission_estimate.number.should be_nil
       c.emission_estimate.emission_units.should be_nil
       c.emission_estimate.methodology.should be_nil
     end