carbon 0.1.2 → 0.1.3

data/README.rdoc

@@ -47,6 +47,30 @@ When you want to calculate emissions, simply call <tt>RentalCar</tt>#<tt>emissio
 
 Read the {carbon gem RDoc}[http://rdoc.info/projects/brighterplanet/carbon] for more!
 
+== Exceptions to watch out for
+
+Since this gem connects to a web service, you need to be ready for network problems and latency. For example:
+
+    begin
+      my_emission = my_car.emission
+    rescue ::SocketError, ::Timeout::Error, ::Errno::ETIMEDOUT, ::Errno::ENETUNREACH, ::Errno::ECONNRESET, ::Errno::ECONNREFUSED
+      # These are general network errors raised by Net::HTTP.
+      # Your internet connection might be down, or our servers might be down.
+    rescue ::Carbon::RateLimited
+      # Realtime mode only.
+      # In order to prevent denial-of-service attacks, our servers rate limit requests.
+      # The gem will try up to three times to get an answer back from the server, waiting slightly longer each time.
+      # If you still get this exception, please contact us at staff@brighterplanet.com and we'll lift your rate.
+    rescue ::Carbon::RealtimeEstimateFailed
+      # Realtime mode only.
+      # Our server returned a 4XX or 5XX error.
+      # Please contact us at staff@brighterplanet.com if you get these more than a couple times.
+    rescue ::Carbon::QueueingFailed
+      # Async mode only.
+      # The gem connects directly to Amazon SQS in order to provide maximum throughput. If that service returns anything other than success, you get this exception.
+      # Please contact us at staff@brighterplanet.com if you see too many of these.
+    end
+
 == A note on API keys
 
 You should get an API key from http://keys.brighterplanet.com and set it globally:

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.3

data/carbon.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{carbon}
-  s.version = "0.1.2"
+  s.version = "0.1.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Derek Kastner", "Seamus Abshere"]
-  s.date = %q{2010-07-19}
+  s.date = %q{2010-07-20}
   s.description = %q{Carbon allows you to easily calculate the carbon footprint of various activities. This is an API for the Brighter Planet Carbon Middleware service.}
   s.email = %q{derek.kastner@brighterplanet.com}
   s.extra_rdoc_files = [

data/lib/carbon.rb

@@ -170,7 +170,19 @@ module Carbon
   end
 
   def _realtime_emission(options = {}) # :nodoc:
-    response = _carbon_response options
+    attempts = 0
+    begin
+      response = _carbon_response options
+      raise ::Carbon::RateLimited if response.status_code == 403 and response.body =~ /Rate Limit/i
+    rescue ::Carbon::RateLimited
+      if attempts < 4
+        attempts += 1
+        sleep 0.2 * attempts
+        retry
+      else
+        raise $!, "Rate limited #{attempts} time(s) in a row"
+      end
+    end
     raise ::Carbon::RealtimeEstimateFailed unless response.success?
     ::Carbon::EmissionEstimate.new ::ActiveSupport::JSON.decode(response.body)
   end
@@ -206,6 +218,8 @@ module Carbon
   # Returns an emission estimate.
   #
   # Note: <b>You need to take care of storing the return value to a local variable!</b> Every call to <tt>emission</tt> runs a query.
+  #
+  # Note also: please see the README about exceptions that you should watch out for.
   # 
   # You can use it like a number...
   #   > my_car.emission + 5.1

data/spec/lib/carbon_spec.rb

@@ -94,7 +94,7 @@ describe Carbon do
     it 'should post a message to SQS' do
       c = RentalCar.new
       c._carbon_request_url.should =~ /queue.amazonaws.com/
-      c.emission :timeframe => Timeframe.new(:year => 2009), :callback => 'http://www.postbin.org/1dj0145'
+      c.emission :timeframe => Timeframe.new(:year => 2009), :callback => 'http://www.postbin.org/1dj0146'
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: carbon
 version: !ruby/object:Gem::Version 
-  hash: 31
+  hash: 29
   prerelease: false
   segments: 
   - 0
   - 1
-  - 2
-  version: 0.1.2
+  - 3
+  version: 0.1.3
 platform: ruby
 authors: 
 - Derek Kastner
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-19 00:00:00 -05:00
+date: 2010-07-20 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency