patron 0.3.2

data/lib/patron.rb

@@ -0,0 +1,42 @@
+## -------------------------------------------------------------------
+##
+## Patron HTTP Client: Bootstrap script
+## Copyright (c) 2008 The Hive http://www.thehive.com/
+##
+## 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.
+##
+## -------------------------------------------------------------------
+require 'yaml'
+require 'pathname'
+
+cwd = Pathname(__FILE__).dirname
+$:.unshift(cwd) unless $:.include?(cwd) || $:.include?(cwd.expand_path)
+
+require 'patron/session'
+
+module Patron #:nodoc:
+  # Returns the version number of the Patron library as a string
+  def self.version
+    cwd = Pathname(__FILE__).dirname
+    yaml = YAML.load_file(cwd.expand_path / '../VERSION.yml')
+    major = (yaml['major'] || yaml[:major]).to_i
+    minor = (yaml['minor'] || yaml[:minor]).to_i
+    "#{major}.#{minor}"
+  end
+end

data/lib/patron/error.rb

@@ -0,0 +1,55 @@
+## -------------------------------------------------------------------
+##
+## Patron HTTP Client: Error definitions
+## Copyright (c) 2008 The Hive http://www.thehive.com/
+##
+## 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.
+##
+## -------------------------------------------------------------------
+
+module Patron
+
+  # Base class for Patron exceptions.
+  class Error < StandardError; end
+
+  # The URL you passed to Patron used a protocol that it does not support.
+  # This most likely the result of a misspelled protocol string.
+  class UnsupportedProtocol   < Error; end
+
+  # The URL was not properly formatted.
+  class URLFormatError        < Error; end
+
+  # Could not resolve the remote host name.
+  class HostResolutionError   < Error; end
+
+  # Failed to connect to the remote host.
+  class ConnectionFailed      < Error; end
+
+  # A file transfer was shorter or larger than expected.
+  # This happens when the server first reports an expected transfer size,
+  # and then delivers data that doesn't match the previously given size.
+  class PartialFileError      < Error; end
+
+  # Operation timeout. The specified time-out period was reached.
+  class TimeoutError          < Error; end
+
+  # Too many redirects. When following redirects, Patron hit the maximum amount.
+  class TooManyRedirects      < Error; end
+
+end

data/lib/patron/request.rb

@@ -0,0 +1,90 @@
+## -------------------------------------------------------------------
+##
+## Patron HTTP Client: Request class
+## Copyright (c) 2008 The Hive http://www.thehive.com/
+##
+## 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.
+##
+## -------------------------------------------------------------------
+
+module Patron
+
+  # Represents the information necessary for an HTTP request.
+  # This is basically a data object with validation. Not all fields will be
+  # used in every request.
+  class Request
+
+    def initialize
+      @action = :get
+      @headers = {}
+      @timeout = 0
+      @connect_timeout = 0
+      @max_redirects = -1
+    end
+
+    attr_accessor :url, :username, :password, :upload_data
+    attr_reader :action, :timeout, :connect_timeout, :max_redirects, :headers
+
+    def action=(new_action)
+      if ![:get, :put, :post, :delete, :head].include?(new_action)
+        raise ArgumentError, "Action must be one of :get, :put, :post, :delete or :head"
+      end
+
+      @action = new_action
+    end
+
+    def timeout=(new_timeout)
+      if new_timeout.to_i < 1
+        raise ArgumentError, "Timeout must be a positive integer greater than 0"
+      end
+
+      @timeout = new_timeout.to_i
+    end
+
+    def connect_timeout=(new_timeout)
+      if new_timeout.to_i < 1
+        raise ArgumentError, "Timeout must be a positive integer greater than 0"
+      end
+
+      @connect_timeout = new_timeout.to_i
+    end
+
+    def max_redirects=(new_max_redirects)
+      if new_max_redirects.to_i < -1
+        raise ArgumentError, "Max redirects must be a positive integer, 0 or -1"
+      end
+
+      @max_redirects = new_max_redirects.to_i
+    end
+
+    def headers=(new_headers)
+      if !new_headers.kind_of?(Hash)
+        raise ArgumentError, "Headers must be a hash"
+      end
+
+      @headers = new_headers
+    end
+
+    def credentials
+      return nil if username.nil? || password.nil?
+      "#{username}:#{password}"
+    end
+
+  end
+end

data/lib/patron/response.rb

@@ -0,0 +1,57 @@
+## -------------------------------------------------------------------
+##
+## Patron HTTP Client: Response class
+## Copyright (c) 2008 The Hive http://www.thehive.com/
+##
+## 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.
+##
+## -------------------------------------------------------------------
+
+module Patron
+
+  # Represents the response from the HTTP server.
+  class Response
+
+    def initialize
+      @headers = {}
+    end
+
+    attr_reader :url, :status, :status_line, :redirect_count, :body, :headers
+
+    def inspect
+      # Avoid spamming the console with the header and body data
+      "#<Patron::Response @status_line='#{@status_line}'>"
+    end
+
+  private
+
+    # Called by the C code to parse and set the headers
+    def parse_headers(header_data)
+      header_data.split(/\r\n/).each do |header|
+        if header =~ %r|^HTTP/1.[01]|
+          @status_line = header.strip
+        else
+          parts = header.split(':', 2)
+          @headers[parts[0]] = parts[1]
+        end
+      end
+    end
+
+  end
+end

data/lib/patron/session.rb

@@ -0,0 +1,114 @@
+## -------------------------------------------------------------------
+##
+## Patron HTTP Client: Session class
+## Copyright (c) 2008 The Hive http://www.thehive.com/
+##
+## 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.
+##
+## -------------------------------------------------------------------
+require 'patron/error'
+require 'patron/request'
+require 'patron/response'
+require 'patron/session_ext'
+
+
+module Patron
+
+  # This class represents multiple request/response transactions with an HTTP
+  # server. This is the primary API for Patron.
+  class Session
+
+    # HTTP connection timeout in milliseconds. Defaults to 1 second (1000 ms).
+    attr_accessor :connect_timeout
+
+    # HTTP transaction timeout in seconds. Defaults to 5 seconds.
+    attr_accessor :timeout
+
+    # Maximum number of times to follow redirects.
+    # Set to 0 to disable and -1 to follow all redirects (the default).
+    attr_accessor :max_redirects
+
+    # Prepended to the URL in all requests.
+    attr_accessor :base_url
+
+    # Username and password for http authentication
+    attr_accessor :username, :password
+
+    # Standard set of headers that are used in all requests.
+    attr_reader :headers
+
+    private :ext_initialize, :handle_request
+
+    # Create an instance of the Session class.
+    def initialize
+      ext_initialize
+      @headers = {}
+      @timeout = 5
+      @connect_timeout = 1000
+      @max_redirects = -1
+    end
+
+    # Retrieve the contents of the specified +url+ optionally sending the
+    # specified headers. If the +base_url+ varaible is set then it is prepended
+    # to the +url+ parameter. Any custom headers are merged with the contents
+    # of the +headers+ instance variable. The results are returned in a
+    # Response object.
+    def get(url, headers = {})
+      do_request(:get, url, headers)
+    end
+
+    # As #get but sends an HTTP HEAD request.
+    def head(url, headers = {})
+      do_request(:head, url, headers)
+    end
+
+    def delete(url, headers = {})
+      do_request(:delete, url, headers)
+    end
+
+    def put(url, data, headers = {})
+      do_request(:put, url, headers, data)
+    end
+
+    def post(url, data, headers = {})
+      do_request(:post, url, headers, data)
+    end
+
+  private
+
+    # Creates a new Request object from the parameters and instance variables.
+    def do_request(action, url, headers, data = nil)
+      req = Request.new
+      req.action = action
+      req.timeout = self.timeout
+      req.connect_timeout = self.connect_timeout
+      req.max_redirects = self.max_redirects
+      req.headers = self.headers.merge(headers)
+      req.username = self.username
+      req.password = self.password
+      req.upload_data = data
+
+      req.url = self.base_url.to_s + url.to_s
+      raise ArgumentError, "Empty URL" if req.url.empty?
+
+      handle_request(req)
+    end
+
+  end
+end

data/spec/patron_spec.rb

@@ -0,0 +1,38 @@
+## -------------------------------------------------------------------
+##
+## Copyright (c) 2008 The Hive http://www.thehive.com/
+##
+## 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.
+##
+## -------------------------------------------------------------------
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe Patron do
+
+  it "should return the version number of the Patron library" do
+    version = Patron.version
+    version.should match(%r|^\d+.\d+.\d+$|)
+  end
+
+  it "should return the version number of the libcurl library" do
+    version = Patron.libcurl_version
+    version.should match(%r|^libcurl/\d+.\d+.\d+|)
+  end
+
+end

data/spec/request_spec.rb

@@ -0,0 +1,75 @@
+## -------------------------------------------------------------------
+##
+## Copyright (c) 2008 The Hive http://www.thehive.com/
+##
+## 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.
+##
+## -------------------------------------------------------------------
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+
+describe Patron::Request do
+
+  before(:each) do
+    @request = Patron::Request.new
+  end
+
+  describe :action do
+
+    it "should accept :get, :put, :post, :delete and :head" do
+      [:get, :put, :post, :delete, :head].each do |action|
+        lambda {@request.action = action}.should_not raise_error
+      end
+    end
+
+    it "should raise an exception when assigned a bad value" do
+      lambda {@request.action = :foo}.should raise_error(ArgumentError)
+    end
+
+  end
+
+  describe :timeout do
+
+    it "should raise an exception when assigned a negative number" do
+      lambda {@request.timeout = -1}.should raise_error(ArgumentError)
+    end
+
+    it "should raise an exception when assigned 0" do
+      lambda {@request.timeout = -1}.should raise_error(ArgumentError)
+    end
+
+  end
+
+  describe :max_redirects do
+
+    it "should raise an error when assigned an integer smaller than -1" do
+      lambda {@request.max_redirects = -2}.should raise_error(ArgumentError)
+    end
+
+  end
+
+  describe :headers do
+
+    it "should raise an error when assigned something other than a hash" do
+      lambda {@request.headers = :foo}.should raise_error(ArgumentError)
+    end
+
+  end
+
+end