nap 0.7.0 → 0.8.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 55ffcab5a8b5cdab1783bed5bd25c770557fd0a6
-  data.tar.gz: 1261b212ae72939d3fa6ed746c3316eca3197108
+  metadata.gz: 3b399814b5fbc094bb5c2a5d620034ac4476ff58
+  data.tar.gz: 78e178d833e8229ed7171ca4fd67c27723b3372e
 SHA512:
-  metadata.gz: fcd3842a4c5009bbee634839e2555c4366218d86013251824e1235838251bb349de8fc89daeb76ebe2512616c629ddc67cda26c24a66a10d63170021f8789aaa
-  data.tar.gz: a6651461595d44851bb36f5659a005ec3249800d70244672fb3e535c28c295763ba7b8e9a9fb7bebbada9299c2a52974340eab73b32bff47d58afaf2f8a2b933
+  metadata.gz: 3186e5ea15c41e9d5300b7fe30f9e9cdda734672a6266a8ccb31b9277f1720126627eb0961da2b3d2257c0f1df69703ffd7c39d73e42fea362cabf32191ae7e0
+  data.tar.gz: 15f7fbd148fbf9e294cae5b75e7af2532e4830ea93576c01468d580bff3b4e7b26d5c8cffe8aea12dd82cf36510fe079658b1dfdb8109c741cb65d13bf1ea2ec

data/README.md

@@ -26,8 +26,7 @@ fire off HTTP requests without having to research net/http internals.
 
 ## Advanced request configuration
 
-If you need more control over the Net::HTTP request you can pass a block to
-all of the request methods. 
+If you need more control over the Net::HTTP request you can pass a block to all of the request methods. 
 
     response = REST.get('http://google.com') do |http_request|
       http_request.open_timeout = 15
@@ -40,6 +39,23 @@ To enable the proxy settings in Nap, you can either use the HTTP\_PROXY or http\
 
     $ env HTTP_PROXY=http://rob:secret@192.167.1.254:665 ruby app.rb
 
+## Exceptions
+
+Nap defines one top-level and three main error types which allow you to catch a whole range of exceptions thrown by underlying protocol implementations.
+
+* *REST::Error*: Any type of error
+* *REST::Timeout*: Read timeouts of various sorts
+* *REST::Connection*: Connection errors caused by dropped sockets
+* *REST::Protocol*: Request failed because of a problem when handling the HTTP request or response
+
+In the most basic case you can rescue from the top-level type to warn about fetching problems.
+
+	begin
+	  REST.get('http://example.com/pigeons/12')
+	rescue REST::Error
+	  puts "[!] Failed to fetch Pigeon number 12."
+	end
+
 ## Contributions
 
 Nap couldn't be the shining beacon in the eternal darkness without help from:

data/lib/rest.rb

@@ -1,10 +1,13 @@
 require 'uri'
 
-# REST is basically a convenience wrapper around Net::HTTP. It defines a simple and consistant API for doing REST-style
-# HTTP calls.
+# REST is basically a convenience wrapper around Net::HTTP. It defines a simple and consistant API
+# for doing REST-style HTTP calls.
+#
+# In addition it provides wrappers for the many error classes that can be raised while making
+# requests. See REST::Error for a complete discussion of options.
 module REST
   # Library version
-  VERSION = '0.7.0'
+  VERSION = '0.8.0.pre'
   
   # Raised when the remote server disconnects when reading the response
   class DisconnectedError < StandardError; end
@@ -101,5 +104,6 @@ module REST
   end
 end
 
+require File.expand_path('../rest/error', __FILE__)
 require File.expand_path('../rest/request', __FILE__)
 require File.expand_path('../rest/response', __FILE__)

data/lib/rest/error.rb

@@ -0,0 +1,91 @@
+require 'net/http'
+
+module REST
+  # This constant can be used to rescue any of the known `Timeout`, `Connection`, and `Protocol`
+  # error classes.
+  #
+  # For instance, to rescue _any_ type of error that could be raise while making a request:
+  #
+  #   begin
+  #     REST.get('http://example.com/pigeons/12')
+  #   rescue REST::Error => e
+  #     p e # => Timeout::Error
+  #   end
+  #
+  # If you want to rescue only `Timeout` related error classes, however, you can limit the scope:
+  #
+  #   begin
+  #     REST.get('http://example.com/pigeons/12')
+  #   rescue REST::Error::Timeout => e
+  #     p e # => Timeout::Error
+  #   end
+  module Error
+    # This constant can be used to rescue only the known `Timeout` error classes.
+    module Timeout
+      def self.class_names
+        %w(
+          Errno::ETIMEDOUT
+          Timeout::Error
+          Net::OpenTimeout
+          Net::ReadTimeout
+        )
+      end
+    end
+
+    # This constant can be used to rescue only the known `Connection` error classes.
+    module Connection
+      def self.class_names
+        %w(
+          EOFError
+          Errno::ECONNABORTED
+          Errno::ECONNREFUSED
+          Errno::ECONNRESET
+          Errno::EHOSTUNREACH
+          Errno::EINVAL
+          Errno::ENETUNREACH
+          SocketError
+          OpenSSL::SSL::SSLError
+        )
+      end
+    end
+
+    # This constant can be used to rescue only the known `Protocol` error classes.
+    module Protocol
+      def self.class_names
+        %w(
+          Net::HTTPBadResponse
+          Net::HTTPHeaderSyntaxError
+          Net::ProtocolError
+          Zlib::GzipFile::Error
+        )
+      end
+    end
+
+    private
+
+    [Timeout, Connection, Protocol].each do |mod|
+      mod.send(:include, Error)
+
+      # Collect all the error classes that exist at runtime.
+      def mod.classes
+        class_names.map do |name|
+          begin
+            # MRI < 2 does not support full constant paths for `Object.const_get`.
+            name.split('::').inject(Object) do |current, const|
+              current.const_get(const)
+            end
+          rescue NameError
+            nil
+          end
+        end.compact
+      end
+
+      # Include the `mod` into the classes.
+      def mod.extend_classes!
+        classes.each { |klass| klass.send(:include, self) }
+      end
+
+      mod.extend_classes!
+    end
+  end
+end

data/lib/rest/request.rb

@@ -111,6 +111,7 @@ module REST
       if url.scheme == 'https'
         require 'net/https'
         require 'openssl'
+        Error::Connection.extend_classes!
         
         http_request.use_ssl = true
         

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nap
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0.pre
 platform: ruby
 authors:
 - Manfred Stienstra
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-05 00:00:00.000000000 Z
+date: 2014-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -51,6 +51,7 @@ files:
 - LICENSE
 - README.md
 - lib/rest.rb
+- lib/rest/error.rb
 - lib/rest/request.rb
 - lib/rest/response.rb
 - support/cacert.pem
@@ -70,9 +71,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.2.0