class Patron::Request

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.

Constants

AuthAny
AuthBasic
AuthDigest
READER_VARS
VALID_ACTIONS

Contains the valid HTTP verbs that can be used to perform requests

WRITER_VARS

Public Class Methods

new() click to toggle source

Initializes a new Request, which defaults to the GET HTTP verb and has it’s timeouts set to 0

# File lib/patron/request.rb, line 15
def initialize
  @action = :get
  @headers = {}
  @timeout = 0
  @connect_timeout = 0
  @max_redirects = -1
end

Public Instance Methods

==(request)
Alias for: eql?
action=(action) click to toggle source

Sets the HTTP verb for the request

@param action the name of the HTTP verb

# File lib/patron/request.rb, line 84
def action=(action)
  if !VALID_ACTIONS.include?(action.to_s.upcase)
    raise ArgumentError, "Action must be one of #{VALID_ACTIONS.join(', ')}"
  end
  @action = action.downcase.to_sym
end
action_name() click to toggle source

Returns the set HTTP verb

@return [String] the HTTP verb

# File lib/patron/request.rb, line 163
def action_name
  @action.to_s.upcase
end
auth_type=(type=:basic) click to toggle source

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
# File lib/patron/request.rb, line 49
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
buffer_size=(buffer_size) click to toggle source

Sets the receive buffer size. This is a recommendedation value, as CURL is not guaranteed to honor this value internally (see curl.haxx.se/libcurl/c/CURLOPT_BUFFERSIZE.html). By default, CURL uses the maximum possible buffer size, which will be the best especially for smaller and quickly-executing requests.

@param buffer_size the desired buffer size, or ‘nil` for automatic buffer size

# File lib/patron/request.rb, line 144
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
connect_timeout=(new_timeout) click to toggle source

Sets the connect timeout for the CURL request, in seconds. Can be set to less than a second using a floating-point value.

@param new_timeout the number of seconds to wait before raising a timeout error

# File lib/patron/request.rb, line 107
def connect_timeout=(new_timeout)
  if new_timeout && new_timeout.to_f < 0
    raise ArgumentError, "Timeout must be a positive number"
  end

  @connect_timeout = new_timeout.to_f
end
credentials() click to toggle source

Returns the set HTTP authentication string for basic authentication.

@return [String, NilClass] the authentication string or nil if no authentication is used

# File lib/patron/request.rb, line 155
def credentials
  return nil if username.nil? || password.nil?
  "#{username}:#{password}"
end
eql?(request) click to toggle source

Tells whether this Request is configured the same as the other request @return [TrueClass, FalseClass]

# File lib/patron/request.rb, line 169
def eql?(request)
  return false unless Request === request

  READER_VARS.inject(true) do |memo, name|
    memo && (self.send(name) == request.send(name))
  end
end
Also aliased as: ==
headers=(new_headers) click to toggle source

Sets the headers for the request. Headers muse be set with the right capitalization. The previously set headers will be replaced.

@param new_headers the hash of headers to set.

# File lib/patron/request.rb, line 130
def headers=(new_headers)
  if !new_headers.kind_of?(Hash)
    raise ArgumentError, "Headers must be a hash"
  end

  @headers = new_headers
end
marshal_dump() click to toggle source

Returns a Marshalable representation of the Request @return [Array]

# File lib/patron/request.rb, line 181
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
marshal_load(data) click to toggle source

Reinstates instance variables from a marshaled representation @param data @return [void]

# File lib/patron/request.rb, line 190
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
max_redirects=(new_max_redirects) click to toggle source

Sets the maximum number of redirects that are going to be followed.

@param new_max_redirects The number of redirects to follow, or ‘-1` for unlimited redirects.

# File lib/patron/request.rb, line 118
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
timeout=(new_timeout) click to toggle source

Sets the read timeout for the CURL request, in seconds. Can be set to less than a second using a floating-point value. Setting the value to 0 will disable the timeout.

@param new_timeout the number of seconds to wait before raising a timeout error

# File lib/patron/request.rb, line 96
def timeout=(new_timeout)
  if new_timeout && new_timeout.to_f < 0
    raise ArgumentError, "Timeout must be a positive number"
  end
  @timeout = new_timeout.to_f
end
upload_data=(data) click to toggle source

Sets the upload data (request body) for the request. If the given argument is a Hash, the contents of the hash will be handled as form fields and will be form-encoded. The somposition of the request body is then going to be handled by Curl.

If the given ‘data` is any other object, it is going to be treated as a stringable request body (JSON or other verbatim type) and will have it’s ‘to_s` method called before sending out the request.

@param data[Hash, to_s] a Hash of form fields to values, or an object that responds to ‘to_s`

# File lib/patron/request.rb, line 72
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