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

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}, &block) ⇒ Session

Create a new Session object.



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/patron/session.rb', line 96

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 ⇒ Object

Set the authentication type for the request.

See Also:

  • Request#auth_type


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

def auth_type
  @auth_type
end

#automatic_content_encoding ⇒ Object

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



91
92
93
 
# File 'lib/patron/session.rb', line 91

def automatic_content_encoding
  @automatic_content_encoding
end

#base_url ⇒ Object

Prepended to the URL in all requests.



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

def base_url
  @base_url
end

#buffer_size ⇒ Object

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



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

def buffer_size
  @buffer_size
end

#cacert ⇒ Object

What cacert file should this session use to verify SSL certificates?



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

def cacert
  @cacert
end

#connect_timeout ⇒ Object

HTTP connection timeout in seconds. Defaults to 1 second.



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

def connect_timeout
  @connect_timeout
end

#default_response_charset ⇒ Object

Default encoding of responses. Used if no charset is provided by the host.



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

def default_response_charset
  @default_response_charset
end

#force_ipv4 ⇒ Object

Force curl to use IPv4



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

def force_ipv4
  @force_ipv4
end

#headers ⇒ Object

Standard set of headers that are used in all requests.



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

def headers
  @headers
end

#ignore_content_length ⇒ Object

Does this session ignore Content-Size headers?



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

def ignore_content_length
  @ignore_content_length
end

#insecure ⇒ Object

Does this session stricly verify SSL certificates?



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

def insecure
  @insecure
end

#max_redirects ⇒ Object

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



47
48
49
 
# File 'lib/patron/session.rb', line 47

def max_redirects
  @max_redirects
end

#password ⇒ Object

Username and password for http authentication



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

def password
  @password
end

#proxy ⇒ Object

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



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

def proxy
  @proxy
end

#proxy_type ⇒ Object

Proxy type (default is HTTP), see constants under ProxyType for supported types.



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

def proxy_type
  @proxy_type
end

#ssl_version ⇒ Object

Specifies the ssl version



72
73
74
 
# File 'lib/patron/session.rb', line 72

def ssl_version
  @ssl_version
end

#timeout ⇒ Object

HTTP transaction timeout in seconds. Defaults to 5 seconds.



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

def timeout
  @timeout
end

#username ⇒ Object

Username and password for http authentication



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

def username
  @username
end

Class Method Details

.escape(string) ⇒ Object

URL escapes the provided string.



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'ext/patron/session_ext.c', line 225

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(string) ⇒ Object

Unescapes the provided string.



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'ext/patron/session_ext.c', line 248

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

#build_request(action, url, headers, options = {}) ⇒ Object

Build a request object that can be used in handle_request



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/patron/session.rb', line 235

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 = {}) ⇒ Object

Sends a WebDAV COPY request to the specified url.



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

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

#delete(url, headers = {}) ⇒ Object

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.



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

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

#enable_cookie_session(file) ⇒ Object

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.



728
729
730
731
732
733
734
735
736
737
738
739
740
 
# File 'ext/patron/session_ext.c', line 728

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

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

#enable_debug(file = nil) ⇒ Object

Enable debug output to stderr or to specified file.



134
135
136
 
# File 'lib/patron/session.rb', line 134

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

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

URL escapes the provided string.



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'ext/patron/session_ext.c', line 225

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 = {}) ⇒ Object

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.



149
150
151
 
# File 'lib/patron/session.rb', line 149

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

#get_file(url, filename, headers = {}) ⇒ Object

Retrieve the contents of the specified url as with #get, but the content at the URL is downloaded directly into the specified file.



155
156
157
 
# File 'lib/patron/session.rb', line 155

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

#handle_cookies(file = nil) ⇒ Object

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.



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

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

#handle_request(request) ⇒ Object

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.



684
685
686
687
 
# File 'ext/patron/session_ext.c', line 684

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 = {}) ⇒ Object

As #get but sends an HTTP HEAD request.



160
161
162
 
# File 'lib/patron/session.rb', line 160

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

#interrupt ⇒ Object

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



715
716
717
718
719
 
# File 'ext/patron/session_ext.c', line 715

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

#post(url, data, headers = {}) ⇒ Object

Uploads the passed data to the specified url using HTTP POST. data can be a string or a hash.



184
185
186
187
188
189
190
 
# File 'lib/patron/session.rb', line 184

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 = {}) ⇒ Object

Uploads the contents of a file to the specified url using HTTP POST.



193
194
195
 
# File 'lib/patron/session.rb', line 193

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

#post_multipart(url, data, filename, headers = {}) ⇒ Object

Uploads the contents of a file and data to the specified url using HTTP POST.



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

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

#put(url, data, headers = {}) ⇒ Object

Uploads the passed data to the specified url using HTTP PUT. data must be a string.



173
174
175
 
# File 'lib/patron/session.rb', line 173

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

#put_file(url, filename, headers = {}) ⇒ Object

Uploads the contents of a file to the specified url using HTTP PUT.



178
179
180
 
# File 'lib/patron/session.rb', line 178

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

#request(action, url, headers, options = {}) ⇒ Object

Send an HTTP request to the specified url.



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

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

#reset ⇒ Object

Reset the underlying cURL session. This effectively closes all open connections and disables debug output.



695
696
697
698
699
700
701
702
703
704
705
706
707
 
# File 'ext/patron/session_ext.c', line 695

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 ⇒ Object

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



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

def response_class
  ::Patron::Response
end

#set_debug_file(file) ⇒ Object

Enable debug output to stderr or to specified file.



747
748
749
750
751
752
753
754
755
756
757
758
759
760
 
# File 'ext/patron/session_ext.c', line 747

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(string) ⇒ Object Also known as: urldecode

Unescapes the provided string.



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'ext/patron/session_ext.c', line 248

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