patron-new 0.4.19

data/lib/patron.rb

@@ -0,0 +1,38 @@
+## -------------------------------------------------------------------
+##
+## 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 'pathname'
+
+cwd = Pathname(__FILE__).dirname
+$:.unshift(cwd.to_s) unless $:.include?(cwd.to_s) || $:.include?(cwd.expand_path.to_s)
+
+require 'patron/session'
+require 'patron/version'
+
+module Patron #:nodoc:
+  # Returns the version number of the Patron library as a string
+  def self.version
+    VERSION
+  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/proxy_type.rb

@@ -0,0 +1,10 @@
+module Patron
+  module ProxyType
+    HTTP
+    HTTP_1_0
+    SOCKS4
+    SOCKS5
+    SOCKS4A
+    SOCKS5_HOSTNAME
+  end
+end

data/lib/patron/request.rb

@@ -0,0 +1,168 @@
+## -------------------------------------------------------------------
+##
+## 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.
+##
+## -------------------------------------------------------------------
+
+require 'patron/util'
+
+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 = %w[GET PUT POST DELETE HEAD COPY]
+
+    def initialize
+      @action = 'GET'
+      @headers = {}
+      @timeout = 0
+      @connect_timeout = 0
+      @max_redirects = -1
+    end
+
+    READER_VARS = [
+      :url, :username, :password, :file_name, :proxy, :proxy_type, :insecure,
+      :ignore_content_length, :multipart, :action, :timeout, :connect_timeout,
+      :max_redirects, :headers, :auth_type, :upload_data, :buffer_size, :cacert
+    ]
+
+    WRITER_VARS = [
+      :url, :username, :password, :file_name, :proxy, :proxy_type, :insecure,
+      :ignore_content_length, :multipart, :cacert
+    ]
+
+    attr_reader *READER_VARS
+    attr_writer *WRITER_VARS
+
+    # 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
+        self.multipart ? data : Util.build_query_string_from_hash(data, action == 'POST')
+      else
+        data
+      end
+    end
+
+    def action=(new_action)
+      action = new_action.to_s.upcase
+
+      if !VALID_ACTIONS.include?(action)
+        raise ArgumentError, "Action must be one of #{VALID_ACTIONS.join(', ')}"
+      end
+
+      @action = 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 buffer_size=(buffer_size)
+      if buffer_size != nil && buffer_size.to_i < 1
+        raise ArgumentError, "Buffer size must be a positive integer greater than 0 or nil"
+      end
+
+      @buffer_size = buffer_size != nil ? buffer_size.to_i : nil
+    end
+
+    def credentials
+      return nil if username.nil? || password.nil?
+      "#{username}:#{password}"
+    end
+
+    def eql?(request)
+      return false unless Request === request
+
+      READER_VARS.inject(true) do |memo, name|
+        memo && (self.send(name) == request.send(name))
+      end
+    end
+
+    alias_method :==, :eql?
+
+    def marshal_dump
+      [ @url, @username, @password, @file_name, @proxy, @proxy_type, @insecure,
+        @ignore_content_length, @multipart, @action, @timeout, @connect_timeout,
+        @max_redirects, @headers, @auth_type, @upload_data, @buffer_size, @cacert ]
+    end
+
+    def marshal_load(data)
+      @url, @username, @password, @file_name, @proxy, @proxy_type, @insecure,
+      @ignore_content_length, @multipart, @action, @timeout, @connect_timeout,
+      @max_redirects, @headers, @auth_type, @upload_data, @buffer_size, @cacert = data
+    end
+
+  end
+end

data/lib/patron/response.rb

@@ -0,0 +1,107 @@
+## -------------------------------------------------------------------
+##
+## 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(url, status, redirect_count, header_data, body, default_charset = nil)
+      # Don't let a response clear out the default charset, which would cause encoding to fail
+      default_charset = "ASCII-8BIT" unless default_charset
+      @url            = url
+      @status         = status
+      @redirect_count = redirect_count
+      @body           = body
+
+      @charset        = determine_charset(header_data, body) || default_charset
+
+      [url, header_data].each do |attr|
+        convert_to_default_encoding!(attr)
+      end
+
+      parse_headers(header_data)
+      if @headers["Content-Type"] && @headers["Content-Type"][0, 5] == "text/"
+        convert_to_default_encoding!(@body)
+      end
+    end
+
+    attr_reader :url, :status, :status_line, :redirect_count, :body, :headers, :charset
+
+    def inspect
+      # Avoid spamming the console with the header and body data
+      "#<Patron::Response @status_line='#{@status_line}'>"
+    end
+
+    def marshal_dump
+      [@url, @status, @status_line, @redirect_count, @body, @headers, @charset]
+    end
+
+    def marshal_load(data)
+      @url, @status, @status_line, @redirect_count, @body, @headers, @charset = data
+    end
+
+  private
+
+    def determine_charset(header_data, body)
+      header_data.match(charset_regex) || (body && body.match(charset_regex))
+
+      $1
+    end
+
+    def charset_regex
+      /(?:charset|encoding)="?([a-z0-9-]+)"?/i
+    end
+
+    def convert_to_default_encoding!(str)
+      if str.respond_to?(:encode) && Encoding.default_internal
+        str.force_encoding(charset).encode!(Encoding.default_internal)
+      end
+    end
+
+    # Called by the C code to parse and set the headers
+    def parse_headers(header_data)
+      @headers = {}
+
+      header_data.split(/\r\n/).each do |header|
+        if header =~ %r|^HTTP/1.[01]|
+          @status_line = header.strip
+        else
+          parts = header.split(':', 2)
+          unless parts.empty?
+            parts[1].strip! unless parts[1].nil?
+            if @headers.has_key?(parts[0])
+              @headers[parts[0]] = [@headers[parts[0]]] unless @headers[parts[0]].kind_of? Array
+              @headers[parts[0]] << parts[1]
+            else
+              @headers[parts[0]] = parts[1]
+            end
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/patron/session.rb

@@ -0,0 +1,234 @@
+## -------------------------------------------------------------------
+##
+## 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 'uri'
+require 'patron/error'
+require 'patron/request'
+require 'patron/response'
+require 'patron/session_ext'
+require 'patron/util'
+
+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 seconds. Defaults to 1 second.
+    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. Defaults to 5.
+    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
+
+    # Proxy URL in cURL format ('hostname:8080')
+    attr_accessor :proxy
+
+    # Proxy type (default is HTTP), see constants under ProxyType for supported types.
+    attr_accessor :proxy_type
+
+    # Standard set of headers that are used in all requests.
+    attr_accessor :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
+
+    # What cacert file should this session use to verify SSL certificates?
+    attr_accessor :cacert
+
+    # Does this session ignore Content-Size headers?
+    attr_accessor :ignore_content_length
+
+    # Set the buffer size for this request. This option will
+    # only be set if buffer_size is non-nil
+    attr_accessor :buffer_size
+
+    # Default encoding of responses. Used if no charset is provided by the host.
+    attr_accessor :default_response_charset
+
+    private :handle_request, :enable_cookie_session, :set_debug_file
+
+    # Create a new Session object.
+    def initialize
+      @headers = {}
+      @timeout = 5
+      @connect_timeout = 1
+      @max_redirects = 5
+      @auth_type = :basic
+    end
+
+    # Turn on cookie handling for this session, storing them in memory by
+    # default or in +file+ if specified. 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, "Can't read or write file #{path} (permission error)"
+        end
+      end
+      enable_cookie_session(path.to_s)
+      self
+    end
+
+    # Enable debug output to stderr or to specified +file+.
+    def enable_debug(file = nil)
+      set_debug_file(file.to_s)
+    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.
+    # Notice: this method doesn't accept any +data+ argument: if you need to send data with
+    # a get request, please, use the #request method.
+    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.
+    # Notice: this method doesn't accept any +data+ argument: if you need to send data with
+    # a delete request, please, use the #request method.
+    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+
+    # can be a string or a hash.
+    def post(url, data, headers = {})
+      if data.is_a?(Hash)
+        data = data.map {|k,v| urlencode(k.to_s) + '=' + urlencode(v.to_s) }.join('&')
+        headers['Content-Type'] = 'application/x-www-form-urlencoded'
+      end
+      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
+
+    # Uploads the contents of a file and data to the specified +url+ using HTTP POST.
+    def post_multipart(url, data, filename, headers = {})
+      request(:post, url, headers, {:data => data, :file => filename, :multipart => true})
+    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 = {})
+      # If the Expect header isn't set uploads are really slow
+      headers['Expect'] ||= ''
+
+      req = Request.new
+      req.action                 = action
+      req.headers                = self.headers.merge headers
+      req.timeout                = options.fetch :timeout,               self.timeout
+      req.connect_timeout        = options.fetch :connect_timeout,       self.connect_timeout
+      req.max_redirects          = options.fetch :max_redirects,         self.max_redirects
+      req.username               = options.fetch :username,              self.username
+      req.password               = options.fetch :password,              self.password
+      req.proxy                  = options.fetch :proxy,                 self.proxy
+      req.proxy_type             = options.fetch :proxy_type,            self.proxy_type
+      req.auth_type              = options.fetch :auth_type,             self.auth_type
+      req.insecure               = options.fetch :insecure,              self.insecure
+      req.cacert                 = options.fetch :cacert,                self.cacert
+      req.ignore_content_length  = options.fetch :ignore_content_length, self.ignore_content_length
+      req.buffer_size            = options.fetch :buffer_size,           self.buffer_size
+      req.multipart              = options[:multipart]
+      req.upload_data            = options[:data]
+      req.file_name              = options[:file]
+
+      base_url = self.base_url.to_s
+      url = url.to_s
+      raise ArgumentError, "Empty URL" if base_url.empty? && url.empty?
+      uri = URI.join(base_url, url)
+      query = uri.query.to_s.split('&')
+      query += options[:query].is_a?(Hash) ? Util.build_query_pairs_from_hash(options[:query]) : options[:query].to_s.split('&')
+      uri.query = query.join('&')
+      uri.query = nil if uri.query.empty?
+      url = uri.to_s
+      req.url = url
+
+      handle_request(req)
+    end
+
+  end
+end