class Patron::Session
This class represents multiple request/response transactions with an HTTP server. This is the primary API for Patron.
Attributes
Set the authentication type for the request. @see Patron::Request#auth_type
Prepended to the URL in all requests.
Set the buffer size for this request. This option will only be set if #buffer_size is non-nil
What cacert file should this session use to verify SSL certificates?
HTTP connection timeout in seconds. Defaults to 1 second.
Default encoding of responses. Used if no charset is provided by the host.
Force curl to use IPv4
Standard set of headers that are used in all requests.
Does this session ignore Content-Size headers?
Does this session stricly verify SSL certificates?
Maximum number of times to follow redirects. Set to 0 to disable and -1 to follow all redirects. Defaults to 5.
Username and password for http authentication
Proxy URL in cURL format ('hostname:8080')
Proxy type (default is HTTP), see constants under ProxyType for supported types.
Specifies the ssl version
HTTP transaction timeout in seconds. Defaults to 5 seconds.
Username and password for http authentication
Public Class Methods
Create a new Session object.
# File lib/patron/session.rb, line 93 def initialize(args = {}, &block) # Allows accessors to be set via constructor hash. Ex: {:base_url => 'www.home.com'} args.each do |attribute, value| send("#{attribute}=", value) end # Allows accessors to be set via block. if block_given? yield self end @headers ||= {} @timeout ||= 5 @connect_timeout ||= 1 @max_redirects ||= 5 @auth_type ||= :basic @force_ipv4 ||= false end
Public Instance Methods
Build a request object that can be used in handle_request
# File lib/patron/session.rb, line 220 def build_request(action, url, headers, options = {}) # If the Expect header isn't set uploads are really slow headers['Expect'] ||= '' Request.new.tap do |req| 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.force_ipv4 = options.fetch :force_ipv4, self.force_ipv4 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.ssl_version = options.fetch :ssl_version, self.ssl_version 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.parse(base_url.empty? ? url : File.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 end end
Sends a WebDAV COPY request to the specified url
.
# File lib/patron/session.rb, line 204 def copy(url, dest, headers = {}) headers['Destination'] = dest request(:copy, url, headers) end
Enable debug output to stderr or to specified file
.
# File lib/patron/session.rb, line 131 def enable_debug(file = nil) set_debug_file(file.to_s) end
URL escapes the provided string.
static VALUE session_escape(VALUE self, VALUE value) { struct curl_state *state = get_curl_state(self); VALUE string = StringValue(value); char* escaped = NULL; VALUE retval = Qnil; escaped = curl_easy_escape(state->handle, RSTRING_PTR(string), (int) RSTRING_LEN(string)); retval = rb_str_new2(escaped); curl_free(escaped); return retval; }
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.
# File lib/patron/session.rb, line 146 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.
# File lib/patron/session.rb, line 152 def get_file(url, filename, headers = {}) request(:get, url, headers, :file => filename) end
As get but sends an HTTP HEAD request.
# File lib/patron/session.rb, line 157 def head(url, headers = {}) request(:head, url, headers) end
Interrupt any currently executing request. This will cause the current request to error and raise an exception.
static VALUE session_interrupt(VALUE self) { struct curl_state *state = get_curl_state(self); state->interrupt = 1; return self; }
Uploads the passed data
to the specified url
using HTTP POST. data
can be a string or a hash.
# File lib/patron/session.rb, line 181 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.
# File lib/patron/session.rb, line 190 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.
# File lib/patron/session.rb, line 195 def post_multipart(url, data, filename, headers = {}) request(:post, url, headers, {:data => data, :file => filename, :multipart => true}) end
Uploads the passed data
to the specified url
using HTTP PUT. data
must be a string.
# File lib/patron/session.rb, line 170 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.
# File lib/patron/session.rb, line 175 def put_file(url, filename, headers = {}) request(:put, url, headers, :file => filename) end
Send an HTTP request to the specified url
.
# File lib/patron/session.rb, line 214 def request(action, url, headers, options = {}) req = build_request(action, url, headers, options) handle_request(req) end
Reset the underlying cURL session. This effectively closes all open connections and disables debug output.
static VALUE session_reset(VALUE self) { struct curl_state *state; Data_Get_Struct(self, struct curl_state, state); if (NULL != state->handle) { cleanup(self); curl_easy_cleanup(state->handle); state->handle = NULL; session_close_debug_file(state); } return self; }
Unescapes the provided string.
static VALUE session_unescape(VALUE self, VALUE value) { struct curl_state *state = get_curl_state(self); VALUE string = StringValue(value); char* unescaped = NULL; VALUE retval = Qnil; unescaped = curl_easy_unescape(state->handle, RSTRING_PTR(string), (int) RSTRING_LEN(string), NULL); retval = rb_str_new2(unescaped); curl_free(unescaped); return retval; }
Private Instance Methods
Peform the actual HTTP request by calling libcurl. Each filed in the
request
object will be used to set the appropriate option on
the libcurl library. After the request completes, a Response object will be created and returned.
In the event of an error in the libcurl library, a Ruby exception will be created and raised. The exception will return the libcurl error code and error message.
static VALUE session_handle_request(VALUE self, VALUE request) { set_options_from_request(self, request); return rb_ensure(&perform_request, self, &cleanup, self); }
Enable debug output to stderr or to specified file
.
static VALUE set_debug_file(VALUE self, VALUE file) { struct curl_state *state = get_curl_state(self); char* file_path = RSTRING_PTR(file); session_close_debug_file(state); if(file_path != NULL && strlen(file_path) != 0) { state->debug_file = open_file(file, "wb"); } else { state->debug_file = stderr; } return self; }