Class: Patron::Session

Inherits:
Object
  • Object
show all
Defined in:
lib/patron/session.rb,
ext/patron/session_ext.c

Overview

This class represents multiple request/response transactions with an HTTP server. This is the primary API for Patron.

Instance Attribute Summary collapse

WebDAV methods collapse

Basic API methods collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) { ... } ⇒ Session

Create a new Session object.

Parameters:

  • args (Hash) (defaults to: {}) —

    options for the Session (same names as the writable attributes of the Session)

Yields:

  • self



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/patron/session.rb', line 114

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

Instance Attribute Details

#auth_type ⇒ Symbol

Returns the authentication type for the request (‘:basic`, `:digest` or `:token`).

Returns:

  • (Symbol) —

    the authentication type for the request (‘:basic`, `:digest` or `:token`).

See Also:

  • Request#auth_type


74
75
76
 
# File 'lib/patron/session.rb', line 74

def auth_type
  @auth_type
end

#automatic_content_encoding ⇒ Boolean

Returns Support automatic Content-Encoding decompression and set liberal Accept-Encoding headers.

Returns:

  • (Boolean) —

    Support automatic Content-Encoding decompression and set liberal Accept-Encoding headers



106
107
108
 
# File 'lib/patron/session.rb', line 106

def automatic_content_encoding
  @automatic_content_encoding
end

#base_url ⇒ String

Returns The URL to prepend to all requests.

Returns:

  • (String) —

    The URL to prepend to all requests.



52
53
54
 
# File 'lib/patron/session.rb', line 52

def base_url
  @base_url
end

#buffer_size ⇒ Integer?

Set the buffer size for this request. This option will only be set if buffer_size is non-nil

Returns:

  • (Integer, nil) 


93
94
95
 
# File 'lib/patron/session.rb', line 93

def buffer_size
  @buffer_size
end

#cacert ⇒ String

Returns path to the CA file used for certificate verification, or ‘nil` if CURL default is used.

Returns:

  • (String) —

    path to the CA file used for certificate verification, or ‘nil` if CURL default is used



85
86
87
 
# File 'lib/patron/session.rb', line 85

def cacert
  @cacert
end

#connect_timeout ⇒ Integer

Returns HTTP connection timeout in seconds. Defaults to 1 second.

Returns:

  • (Integer) —

    HTTP connection timeout in seconds. Defaults to 1 second.



41
42
43
 
# File 'lib/patron/session.rb', line 41

def connect_timeout
  @connect_timeout
end

#default_response_charset ⇒ String?

Sets the name of the charset to assume for the response. The argument should be a String that is an acceptable argument for ‘Encoding.find()` in Ruby. The variable will only be used if the response does not specify a charset in it’s ‘Content-Type` header already, if it does that charset will take precedence.

Returns:

  • (String, nil) 


100
101
102
 
# File 'lib/patron/session.rb', line 100

def default_response_charset
  @default_response_charset
end

#force_ipv4 ⇒ Boolean

Returns Force curl to use IPv4.

Returns:

  • (Boolean) —

    Force curl to use IPv4



103
104
105
 
# File 'lib/patron/session.rb', line 103

def force_ipv4
  @force_ipv4
end

#headers ⇒ Hash

Returns headers used in all requests.

Returns:

  • (Hash) —

    headers used in all requests.



70
71
72
 
# File 'lib/patron/session.rb', line 70

def headers
  @headers
end

#ignore_content_length ⇒ Boolean

Returns whether Content-Range and Content-Length headers should be ignored.

Returns:

  • (Boolean) —

    whether Content-Range and Content-Length headers should be ignored



88
89
90
 
# File 'lib/patron/session.rb', line 88

def ignore_content_length
  @ignore_content_length
end

#insecure ⇒ Boolean

Please consider twice before using this option..

Returns:

  • (Boolean) —

    ‘true` if SSL certificate verification is disabled.



78
79
80
 
# File 'lib/patron/session.rb', line 78

def insecure
  @insecure
end

#max_redirects ⇒ Integer

Maximum number of redirects to follow Set to 0 to disable and -1 to follow all redirects. Defaults to 5.

Returns:

  • (Integer) 


49
50
51
 
# File 'lib/patron/session.rb', line 49

def max_redirects
  @max_redirects
end

#password ⇒ String?

Password for http authentication

Returns:

  • (String, nil) —

    the HTTP basic auth password



60
61
62
 
# File 'lib/patron/session.rb', line 60

def password
  @password
end

#proxy ⇒ String

Returns Proxy URL in cURL format (‘hostname:8080’).

Returns:

  • (String) —

    Proxy URL in cURL format (‘hostname:8080’)



63
64
65
 
# File 'lib/patron/session.rb', line 63

def proxy
  @proxy
end

#proxy_type ⇒ Integer

Returns Proxy type (default is HTTP).

Returns:

  • (Integer) —

    Proxy type (default is HTTP)

See Also:



67
68
69
 
# File 'lib/patron/session.rb', line 67

def proxy_type
  @proxy_type
end

#ssl_version ⇒ String

The supported values are nil, “SSLv2”, “SSLv3”, and “TLSv1”.

Returns:

  • (String) —

    the SSL version for the requests, or nil if all versions are permitted



82
83
84
 
# File 'lib/patron/session.rb', line 82

def ssl_version
  @ssl_version
end

#timeout ⇒ Integer

Returns HTTP transaction timeout in seconds. Defaults to 5 seconds.

Returns:

  • (Integer) —

    HTTP transaction timeout in seconds. Defaults to 5 seconds.



44
45
46
 
# File 'lib/patron/session.rb', line 44

def timeout
  @timeout
end

#username ⇒ String?

Username for http authentication

Returns:

  • (String, nil) —

    the HTTP basic auth username



56
57
58
 
# File 'lib/patron/session.rb', line 56

def username
  @username
end

Class Method Details

.escape(value) ⇒ Object

Escapes the provided string using libCURL URL escaping functions.

Parameters:

  • value (String) —

    plain string to URL-escape @return [String] the escaped string



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'ext/patron/session_ext.c', line 214

static VALUE session_escape(VALUE self, VALUE value) {
  
  VALUE string = StringValue(value);
  char* escaped = NULL;
  VALUE retval = Qnil;

  struct curl_state* state = curl_easy_init();
  escaped = curl_easy_escape(state->handle,
                             RSTRING_PTR(string),
                             (int) RSTRING_LEN(string));

  retval = rb_str_new2(escaped);
  curl_easy_cleanup(state);
  curl_free(escaped);

  return retval;
}

.unescape(value) ⇒ Object

Unescapes the provided string using libCURL URL escaping functions.

Parameters:

  • value (String) —

    URL-encoded String to unescape @return [String] unescaped (decoded) string



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'ext/patron/session_ext.c', line 238

static VALUE session_unescape(VALUE self, VALUE value) {
  VALUE string = StringValue(value);
  char* unescaped = NULL;
  VALUE retval = Qnil;

  struct curl_state* state = curl_easy_init();
  unescaped = curl_easy_unescape(state->handle,
                                 RSTRING_PTR(string),
                                 (int) RSTRING_LEN(string),
                                 NULL);

  retval = rb_str_new2(unescaped);
  curl_free(unescaped);
  curl_easy_cleanup(state);

  return retval;
}

Instance Method Details

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. FIXME: what does the empty string actually do here?

Parameters:

  • file (String) —

    path to the existing cookie file, or nil to store in memory. @return self



742
743
744
745
746
747
748
749
750
751
752
753
754
755
 
# File 'ext/patron/session_ext.c', line 742

static VALUE add_cookie_file(VALUE self, VALUE file) {
  struct curl_state *state = get_curl_state(self);
  CURL* curl = state->handle;
  char* file_path = NULL;

  // FIXME: http://websystemsengineering.blogspot.nl/2013/03/curloptcookiefile-vs-curloptcookiejar.html
  file_path = RSTRING_PTR(file);
  if (file_path != NULL && strlen(file_path) != 0) {
    curl_easy_setopt(curl, CURLOPT_COOKIEJAR, file_path);
  }
  curl_easy_setopt(curl, CURLOPT_COOKIEFILE, file_path);

  return self;
}

#build_request(action, url, headers, options = {}) ⇒ Patron::Request

Builds a request object that can be used by handle_request Note that internally, handle_request uses instance variables of the Request object, and not it’s public methods.

Parameters:

  • action (String) —

    the HTTP verb

Returns:



347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
 
# File 'lib/patron/session.rb', line 347

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.automatic_content_encoding = options.fetch :automatic_content_encoding, self.automatic_content_encoding
    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

#copy(url, dest, headers = {}) ⇒ Patron::Response

Sends a WebDAV COPY request to the specified url.

Parameters:

  • url (String) —

    the URL to copy

  • dest (String) —

    the URL of the COPY destination

  • headers (Hash) (defaults to: {}) —

    the hash of header keys to values

Returns:



303
304
305
306
 
# File 'lib/patron/session.rb', line 303

def copy(url, dest, headers = {})
  headers['Destination'] = dest
  request(:copy, url, headers)
end

#delete(url, headers = {}) ⇒ Patron::Response

Same as #get but performs a DELETE request.

Notice: this method doesn’t accept any ‘data` argument: if you need to send data with a delete request (as might be needed for ElasticSearch), please, use the #request method.

Parameters:

  • url (String) —

    the URL to fetch

  • headers (Hash) (defaults to: {}) —

    the hash of header keys to values

Returns:



219
220
221
 
# File 'lib/patron/session.rb', line 219

def delete(url, headers = {})
  request(:delete, url, headers)
end

#enable_debug(file = nil) ⇒ Object

TODO:

Change to an assignment of an IO object

Enable debug output to stderr or to specified ‘file`.

Parameters:

  • file (String, nil) (defaults to: nil) —

    path to the file to write debug data to, or ‘nil` to print to `STDERR`

Returns:

  • self



167
168
169
170
 
# File 'lib/patron/session.rb', line 167

def enable_debug(file = nil)
  set_debug_file(file.to_s)
  self
end

#escape(value) ⇒ Object Also known as: urlencode

Escapes the provided string using libCURL URL escaping functions.

Parameters:

  • value (String) —

    plain string to URL-escape @return [String] the escaped string



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'ext/patron/session_ext.c', line 214

static VALUE session_escape(VALUE self, VALUE value) {
  
  VALUE string = StringValue(value);
  char* escaped = NULL;
  VALUE retval = Qnil;

  struct curl_state* state = curl_easy_init();
  escaped = curl_easy_escape(state->handle,
                             RSTRING_PTR(string),
                             (int) RSTRING_LEN(string));

  retval = rb_str_new2(escaped);
  curl_easy_cleanup(state);
  curl_free(escaped);

  return retval;
}

#get(url, headers = {}) ⇒ Patron::Response

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 a request body with a GET request, when using ElasticSearch for example, please, use the #request method.

Parameters:

  • url (String) —

    the URL to fetch

  • headers (Hash) (defaults to: {}) —

    the hash of header keys to values

Returns:



183
184
185
 
# File 'lib/patron/session.rb', line 183

def get(url, headers = {})
  request(:get, url, headers)
end

#get_file(url, filename, headers = {}) ⇒ Patron::Response

Retrieve the contents of the specified url as with #get, but the content at the URL is downloaded directly into the specified file. The file will be accessed by libCURL bypassing the Ruby runtime entirely.

Note that when using this option, the Response object will have nil as the body, and you will need to read your target file for access to the body string).

Parameters:

  • url (String) —

    the URL to fetch

  • filename (String) —

    path to the file to save the response body in

Returns:



197
198
199
 
# File 'lib/patron/session.rb', line 197

def get_file(url, filename, headers = {})
  request(:get, url, headers, :file => filename)
end

#handle_cookies(file_path = nil) ⇒ Object

TODO:

the cookie jar and cookie file path options should be split

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.

Parameters:

  • file_path (String) (defaults to: nil) —

    path to an existing cookie jar file, or nil to store cookies in memory

Returns:

  • self



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/patron/session.rb', line 141

def handle_cookies(file_path = nil)
  if file_path
    path = Pathname(file_path).expand_path
    
    if !File.exists?(file_path) && !File.writable?(path.dirname)
      raise ArgumentError, "Can't create file #{path} (permission error)"
    elsif File.exists?(file_path) && !File.writable?(file_path)
      raise ArgumentError, "Can't read or write file #{path} (permission error)"
    end
  else
    path = nil
  end
  
  # Apparently calling this with an empty string sets the cookie file,
  # but calling it with a path to a writable file sets that file to be
  # the cookie jar (new cookies are written there)
  add_cookie_file(path.to_s)
  
  self
end

#handle_request(request) ⇒ Patron::Response

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.

Parameters:

  • request (Patron::Request) —

    the request to use when filling the CURL options

Returns:

  • (Patron::Response) —

    the result of calling ‘response_class` on the Session



692
693
694
695
 
# File 'ext/patron/session_ext.c', line 692

static VALUE session_handle_request(VALUE self, VALUE request) {
  set_options_from_request(self, request);
  return rb_ensure(&perform_request, self, &cleanup, self);
}

#head(url, headers = {}) ⇒ Patron::Response

Same as #get but performs a HEAD request.

Parameters:

  • url (String) —

    the URL to fetch

  • headers (Hash) (defaults to: {}) —

    the hash of header keys to values

Returns:

See Also:



207
208
209
 
# File 'lib/patron/session.rb', line 207

def head(url, headers = {})
  request(:head, url, headers)
end

#interrupt ⇒ void

This method returns an undefined value.

Interrupt any currently executing request. This will cause the current request to error and raise an exception.



727
728
729
730
731
 
# File 'ext/patron/session_ext.c', line 727

static VALUE session_interrupt(VALUE self) {
  struct curl_state *state = get_curl_state(self);
  state->interrupt = 1;
  return self;
}

#patch(url, data, headers = {}) ⇒ Patron::Response

TODO:

inconsistency with “post” - Hash not accepted

Uploads the passed ‘data` to the specified `url` using an HTTP PATCH. Note that unline post, a Hash is not accepted as the data argument.

Parameters:

  • url (String) —

    the URL to fetch

  • data (#to_s) —

    an object that can be converted to a String to create the request body

  • headers (Hash) (defaults to: {}) —

    the hash of header keys to values

Returns:



243
244
245
 
# File 'lib/patron/session.rb', line 243

def patch(url, data, headers = {})
  request(:patch, url, headers, :data => data)
end

#post(url, data, headers = {}) ⇒ Patron::Response

Uploads the passed ‘data` to the specified `url` using an HTTP POST.

Parameters:

  • url (String) —

    the URL to fetch

  • data (Hash, #to_s) —

    a Hash of form fields/values, or an object that can be converted to a String to create the request body

  • headers (Hash) (defaults to: {}) —

    the hash of header keys to values

Returns:



264
265
266
267
268
269
270
 
# File 'lib/patron/session.rb', line 264

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

#post_file(url, filename, headers = {}) ⇒ Patron::Response

Uploads the contents of ‘file` to the specified `url` using an HTTP POST. The file will be sent “as-is” without any multipart encoding.

Parameters:

  • url (String) —

    the URL to fetch

  • filename (String) —

    path to the file to be uploaded

  • headers (Hash) (defaults to: {}) —

    the hash of header keys to values

Returns:



279
280
281
 
# File 'lib/patron/session.rb', line 279

def post_file(url, filename, headers = {})
  request(:post, url, headers, :file => filename)
end

#post_multipart(url, data, filename, headers = {}) ⇒ Patron::Response

Uploads the contents of ‘filename` to the specified `url` using an HTTP POST, in combination with given form fields passed in `data`.

Parameters:

  • url (String) —

    the URL to fetch

  • data (Hash) —

    hash of the form fields

  • filename (String) —

    path to the file to be uploaded

  • headers (Hash) (defaults to: {}) —

    the hash of header keys to values

Returns:



291
292
293
 
# File 'lib/patron/session.rb', line 291

def post_multipart(url, data, filename, headers = {})
  request(:post, url, headers, {:data => data, :file => filename, :multipart => true})
end

#put(url, data, headers = {}) ⇒ Patron::Response

TODO:

inconsistency with “post” - Hash not accepted

Uploads the passed ‘data` to the specified `url` using an HTTP PUT. Note that unline post, a Hash is not accepted as the data argument.

Parameters:

  • url (String) —

    the URL to fetch

  • data (#to_s) —

    an object that can be converted to a String to create the request body

  • headers (Hash) (defaults to: {}) —

    the hash of header keys to values

Returns:



231
232
233
 
# File 'lib/patron/session.rb', line 231

def put(url, data, headers = {})
  request(:put, url, headers, :data => data)
end

#put_file(url, filename, headers = {}) ⇒ Patron::Response

Uploads the contents of ‘file` to the specified `url` using an HTTP PUT. The file will be sent “as-is” without any multipart encoding.

Parameters:

  • url (String) —

    the URL to fetch

  • filename (String) —

    path to the file to be uploaded

  • headers (Hash) (defaults to: {}) —

    the hash of header keys to values

Returns:



254
255
256
 
# File 'lib/patron/session.rb', line 254

def put_file(url, filename, headers = {})
  request(:put, url, headers, :file => filename)
end

#request(action, url, headers, options = {}) ⇒ Patron::Response

Send an HTTP request to the specified ‘url`.

Parameters:

  • action (#to_s) —

    the HTTP verb

  • url (String) —

    the URL for the request

  • headers (Hash) —

    headers to send along with the request

  • options (Hash) (defaults to: {}) —

    any additonal setters to call on the Request

Returns:

See Also:



318
319
320
321
 
# File 'lib/patron/session.rb', line 318

def request(action, url, headers, options = {})
  req = build_request(action, url, headers, options)
  handle_request(req)
end

#reset ⇒ Object

FIXME: figure out how this method should be used at all given Session is not multithreaded. FIXME: also: what is the difference with ‘interrupt()` and also relationship with `cleanup()`? Reset the underlying cURL session. This effectively closes all open connections and disables debug output. There is no need to call this method manually after performing a request, since cleanup is performed automatically but the method can be used from another thread to abort a request currently in progress.

Returns:

  • self



708
709
710
711
712
713
714
715
716
717
718
719
720
 
# File 'ext/patron/session_ext.c', line 708

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;
}

#response_class ⇒ #new

Returns the class that will be used to build a Response from a Curl call.

Primarily useful if you need a very lightweight Response object that does not have to perform all the parsing of various headers/status codes. The method must return a module that supports the same interface for new as Patron::Response

Returns:

  • (#new) —

    Returns any object that responds to ‘.new` with 6 arguments

See Also:



334
335
336
 
# File 'lib/patron/session.rb', line 334

def response_class
  ::Patron::Response
end

#set_debug_file(file) ⇒ Object

Enable debug output to stderr or to specified file.

Parameters:

  • file (String, nil) —

    path to the debug file, or nil to write to STDERR @return self



763
764
765
766
767
768
769
770
771
772
773
774
775
776
 
# File 'ext/patron/session_ext.c', line 763

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;
}

#unescape(value) ⇒ Object Also known as: urldecode

Unescapes the provided string using libCURL URL escaping functions.

Parameters:

  • value (String) —

    URL-encoded String to unescape @return [String] unescaped (decoded) string



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'ext/patron/session_ext.c', line 238

static VALUE session_unescape(VALUE self, VALUE value) {
  VALUE string = StringValue(value);
  char* unescaped = NULL;
  VALUE retval = Qnil;

  struct curl_state* state = curl_easy_init();
  unescaped = curl_easy_unescape(state->handle,
                                 RSTRING_PTR(string),
                                 (int) RSTRING_LEN(string),
                                 NULL);

  retval = rb_str_new2(unescaped);
  curl_free(unescaped);
  curl_easy_cleanup(state);

  return retval;
}