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

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Session

Create a new Session object.



90
91
92
93
94
95
96
 
# File 'lib/patron/session.rb', line 90

def initialize
  @headers = {}
  @timeout = 5
  @connect_timeout = 1
  @max_redirects = 5
  @auth_type = :basic
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

#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

#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

Instance Method Details

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

Build a request object that can be used in handle_request



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/patron/session.rb', line 205

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.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.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.



189
190
191
192
 
# File 'lib/patron/session.rb', line 189

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.



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

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.



699
700
701
702
703
704
705
706
707
708
709
710
711
 
# File 'ext/patron/session_ext.c', line 699

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.



116
117
118
 
# File 'lib/patron/session.rb', line 116

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

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

URL escapes the provided string.



222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'ext/patron/session_ext.c', line 222

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

#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.



131
132
133
 
# File 'lib/patron/session.rb', line 131

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.



137
138
139
 
# File 'lib/patron/session.rb', line 137

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.



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

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.



655
656
657
658
 
# File 'ext/patron/session_ext.c', line 655

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.



142
143
144
 
# File 'lib/patron/session.rb', line 142

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.



686
687
688
689
690
 
# File 'ext/patron/session_ext.c', line 686

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.



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

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.



175
176
177
 
# File 'lib/patron/session.rb', line 175

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.



180
181
182
 
# File 'lib/patron/session.rb', line 180

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.



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

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.



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

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.



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

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.



666
667
668
669
670
671
672
673
674
675
676
677
678
 
# File 'ext/patron/session_ext.c', line 666

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

#set_debug_file(file) ⇒ Object

Enable debug output to stderr or to specified file.



718
719
720
721
722
723
724
725
726
727
728
729
730
731
 
# File 'ext/patron/session_ext.c', line 718

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.



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'ext/patron/session_ext.c', line 243

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