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.



76
77
78
79
80
81
82
83
 
# File 'lib/patron/session.rb', line 76

def initialize
  ext_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:



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

def auth_type
  @auth_type
end

#base_url ⇒ Object

Prepended to the URL in all requests.



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

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



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

def buffer_size
  @buffer_size
end

#connect_timeout ⇒ Object

HTTP connection timeout in seconds. Defaults to 1 second.



38
39
40
 
# File 'lib/patron/session.rb', line 38

def connect_timeout
  @connect_timeout
end

#headers ⇒ Object (readonly)

Standard set of headers that are used in all requests.



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

def headers
  @headers
end

#insecure ⇒ Object

Does this session stricly verify SSL certificates?



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

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.



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

def max_redirects
  @max_redirects
end

#password ⇒ Object

Username and password for http authentication



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

def password
  @password
end

#proxy ⇒ Object

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



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

def proxy
  @proxy
end

#proxy_type ⇒ Object

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



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

def proxy_type
  @proxy_type
end

#timeout ⇒ Object

HTTP transaction timeout in seconds. Defaults to 5 seconds.



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

def timeout
  @timeout
end

#username ⇒ Object

Username and password for http authentication



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

def username
  @username
end

Instance Method Details

#copy(url, dest, headers = {}) ⇒ Object

Sends a WebDAV COPY request to the specified url.



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

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.



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

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

#enable_cookie_session(file) ⇒ Object 



461
462
463
464
465
466
467
468
469
470
471
 
# File 'ext/patron/session_ext.c', line 461

VALUE enable_cookie_session(VALUE self, VALUE file) {
  struct curl_state *state;
  Data_Get_Struct(self, struct curl_state, state);
  CURL* curl = state->handle;
  char* 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 Qnil;
}

#enable_debug(file = nil) ⇒ Object

Enable debug output to stderr or to specified file.



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

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

#escape(value) ⇒ Object

URL escapes the provided string.



125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'ext/patron/session_ext.c', line 125

VALUE session_escape(VALUE self, VALUE value) {
  struct curl_state *state;
  Data_Get_Struct(self, struct curl_state, state);

  VALUE string = StringValue(value);
  char* escaped = curl_easy_escape(state->handle,
                                   RSTRING_PTR(string),
                                   RSTRING_LEN(string));

  VALUE retval = rb_str_new2(escaped);
  curl_free(escaped);

  return retval;
}

#ext_initialize ⇒ Object

NOTE: This must be called from Session#initialize.



113
114
115
116
117
118
119
120
121
122
 
# File 'ext/patron/session_ext.c', line 113

VALUE session_ext_initialize(VALUE self) {
  struct curl_state *state;
  Data_Get_Struct(self, struct curl_state, state);

  state->handle = curl_easy_init();
  state->post   = NULL;
  state->last   = NULL;

  return self;
}

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



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

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.



122
123
124
 
# File 'lib/patron/session.rb', line 122

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.



88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/patron/session.rb', line 88

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 



456
457
458
459
 
# File 'ext/patron/session_ext.c', line 456

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.



127
128
129
 
# File 'lib/patron/session.rb', line 127

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

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

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



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

def post(url, data, headers = {})
  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.



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

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.



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

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.



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

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.



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

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.

Raises:

  • (ArgumentError) 


178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/patron/session.rb', line 178

def request(action, url, headers, options = {})
  # If the Expect header isn't set uploads are really slow
  headers['Expect'] ||= ''

  req = Request.new
  req.action = action
  req.timeout = self.timeout
  req.connect_timeout = self.connect_timeout
  req.max_redirects = self.max_redirects
  req.headers = self.headers.merge(headers)
  req.username = self.username
  req.password = self.password
  req.multipart = options[:multipart]
  req.upload_data = options[:data]
  req.file_name = options[:file]
  req.proxy = proxy
  req.proxy_type = proxy_type
  req.auth_type = auth_type
  req.insecure = insecure
  req.buffer_size = buffer_size

  req.url = self.base_url.to_s + url.to_s
  raise ArgumentError, "Empty URL" if req.url.empty?

  handle_request(req)
end

#set_debug_file(file) ⇒ Object 



473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
 
# File 'ext/patron/session_ext.c', line 473

VALUE set_debug_file(VALUE self, VALUE file) {
  struct curl_state *state;
  Data_Get_Struct(self, struct curl_state, state);
  char* file_path = RSTRING_PTR(file);

  if(state->debug_file){
    fclose(state->debug_file);
    state->debug_file = NULL;
  }

  if(file_path != NULL && strlen(file_path) != 0) {
    state->debug_file = open_file(file, "w");
  } else {
    state->debug_file = stderr;
  }

  return Qnil;
}

#unescape(value) ⇒ Object

Unescapes the provided string.



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'ext/patron/session_ext.c', line 141

VALUE session_unescape(VALUE self, VALUE value) {
  struct curl_state *state;
  Data_Get_Struct(self, struct curl_state, state);

  VALUE string = StringValue(value);
  char* unescaped = curl_easy_unescape(state->handle,
                                       RSTRING_PTR(string),
                                       RSTRING_LEN(string),
                                       NULL);

  VALUE retval = rb_str_new2(unescaped);
  curl_free(unescaped);

  return retval;
}