dusty-patron 0.4.3

data/lib/patron.rb

@@ -0,0 +1,39 @@
+## -------------------------------------------------------------------
+##
+## 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'
+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
+    patch = (yaml['patch'] || yaml[:patch]).to_i
+    "#{major}.#{minor}.#{patch}"
+  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,147 @@
+## -------------------------------------------------------------------
+##
+## 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
+
+    VALID_ACTIONS = [:get, :put, :post, :delete, :head, :copy]
+
+    def initialize
+      @action = :get
+      @headers = {}
+      @timeout = 0
+      @connect_timeout = 0
+      @max_redirects = -1
+    end
+
+    attr_accessor :url, :username, :password, :file_name, :proxy, :auth_type, :insecure
+    attr_reader :action, :timeout, :connect_timeout, :max_redirects, :headers
+    attr_reader :auth_type
+    
+      # Set the type of authentication to use for this request. 
+      # 
+      # @param [String, Symbol] type - The type of authentication to use for this request, can be one of
+      #   :basic, :digest, or :any
+      #
+      # @example
+      #   sess.username = "foo"
+      #   sess.password = "sekrit"
+      #   sess.auth_type = :digest
+      def auth_type=(type=:basic)
+        @auth_type = case type
+        when :basic, "basic"
+          Request::AuthBasic
+        when :digest, "digest"
+          Request::AuthDigest
+        when :any, "any"
+          Request::AuthAny
+        else
+          raise "#{type.inspect} is an unknown authentication type"
+        end
+      end
+
+    def upload_data=(data)
+      @upload_data = case data
+      when Hash
+        hash_to_string(data)
+      else
+        data
+      end
+    end
+    
+    def upload_data
+      @upload_data
+    end
+
+    def action=(new_action)
+      if !VALID_ACTIONS.include?(new_action)
+        raise ArgumentError, "Action must be one of #{VALID_ACTIONS.join(', ')}"
+      end
+
+      @action = new_action
+    end
+
+    def timeout=(new_timeout)
+      if new_timeout && 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 && 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 action_name
+      @action.to_s.upcase
+    end
+
+    def credentials
+      return nil if username.nil? || password.nil?
+      "#{username}:#{password}"
+    end
+
+    private
+    
+    # serialize hash for Rails-style params
+    def hash_to_string(hash)
+      pairs = []
+      recursive = Proc.new do |h, prefix| 
+        h.each_pair do |k,v|
+          key = prefix == '' ? k : "#{prefix}[#{k}]"
+          v.is_a?(Hash) ? recursive.call(v, key) : pairs << "#{key}=#{v}"
+        end
+      end
+      recursive.call(hash, '')
+      return pairs.join('&')
+    end
+    
+  end
+end

data/lib/patron/response.rb

@@ -0,0 +1,58 @@
+## -------------------------------------------------------------------
+##
+## 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)
+          parts[1].strip! unless parts[1].nil?
+          @headers[parts[0]] = parts[1]
+        end
+      end
+    end
+
+  end
+end

data/lib/patron/session.rb

@@ -0,0 +1,183 @@
+## -------------------------------------------------------------------
+##
+## 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
+
+    # HTTP proxy URL
+    attr_accessor :proxy
+
+    # Standard set of headers that are used in all requests.
+    attr_reader :headers
+    
+    # Set the authentication type for the request.
+    # @see Patron::Request#auth_type
+    attr_accessor :auth_type
+
+    # Does this session stricly verify SSL certificates?
+    attr_accessor :insecure
+
+    private :ext_initialize, :handle_request, :enable_cookie_session
+
+    # Create a new Session object.
+    def initialize
+      ext_initialize
+      @headers = {}
+      @timeout = 5
+      @connect_timeout = 1000
+      @max_redirects = -1
+      @auth_type = :basic
+    end
+
+    # Makes this session handle cookies and store them in in +file+.
+    # If file is nil they will be stored in memory. Otherwise the +file+
+    # must be readable and writable. Calling multiple times will add more files.
+    def handle_cookies(file = nil)
+      if file
+        path = Pathname(file).expand_path
+        unless File.exists?(file) and File.writable?(path.dirname)
+          raise ArgumentError, "Can't create file #{path} (permission error)"
+        end
+        unless File.readable?(file) or File.writable?(path)
+          raise ArgumentError, "Cant read or write file #{path} (permission error)"
+        end
+      end
+      enable_cookie_session(path.to_s)
+      self
+    end
+
+    ###################################################################
+    ### Standard HTTP methods
+    ###
+
+    # 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 = {})
+      request(:get, url, headers)
+    end
+
+    # Retrieve the contents of the specified +url+ as with #get, but the
+    # content at the URL is downloaded directly into the specified file.
+    def get_file(url, filename, headers = {})
+      request(:get, url, headers, :file => filename)
+    end
+
+    # As #get but sends an HTTP HEAD request.
+    def head(url, headers = {})
+      request(:head, url, headers)
+    end
+
+    # As #get but sends an HTTP DELETE request.
+    def delete(url, headers = {})
+      request(:delete, url, headers)
+    end
+
+    # Uploads the passed +data+ to the specified +url+ using HTTP PUT. +data+
+    # must be a string.
+    def put(url, data, headers = {})
+      request(:put, url, headers, :data => data)
+    end
+
+    # Uploads the contents of a file to the specified +url+ using HTTP PUT.
+    def put_file(url, filename, headers = {})
+      request(:put, url, headers, :file => filename)
+    end
+
+    # Uploads the passed +data+ to the specified +url+ using HTTP POST. +data+
+    # must be a string.
+    def post(url, data, headers = {})
+      request(:post, url, headers, :data => data)
+    end
+
+    # Uploads the contents of a file to the specified +url+ using HTTP POST.
+    def post_file(url, filename, headers = {})
+      request(:post, url, headers, :file => filename)
+    end     
+
+    ###################################################################
+    ### WebDAV methods
+    ###
+
+    # Sends a WebDAV COPY request to the specified +url+.
+    def copy(url, dest, headers = {})
+      headers['Destination'] = dest
+      request(:copy, url, headers)
+    end
+
+    ###################################################################
+    ### Basic API methods
+    ###
+
+    # Send an HTTP request to the specified +url+.
+    def request(action, url, headers, options = {})
+      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 = options[:data]
+      req.file_name = options[:file]
+      req.proxy = proxy
+      req.auth_type = auth_type
+      req.insecure = insecure
+
+      req.url = self.base_url.to_s + url.to_s
+      raise ArgumentError, "Empty URL" if req.url.empty?
+
+      handle_request(req)
+    end
+
+  end
+end