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.



69
70
71
72
73
74
75
76
 
# File 'lib/patron/session.rb', line 69

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:



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

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

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



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

def headers
  @headers
end

#insecure ⇒ Object

Does this session stricly verify SSL certificates?



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

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

HTTP proxy URL



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

def proxy
  @proxy
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.



151
152
153
154
 
# File 'lib/patron/session.rb', line 151

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.



120
121
122
 
# File 'lib/patron/session.rb', line 120

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

#enable_cookie_session(file) ⇒ Object 



396
397
398
399
400
401
402
403
404
405
406
 
# File 'ext/patron/session_ext.c', line 396

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

#escape(value) ⇒ Object

URL escapes the provided string.



114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'ext/patron/session_ext.c', line 114

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.



104
105
106
107
108
109
110
111
 
# File 'ext/patron/session_ext.c', line 104

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

  state->handle = curl_easy_init();

  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.



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

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.



110
111
112
 
# File 'lib/patron/session.rb', line 110

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

#handle_cookies(file = nil) ⇒ Object

Makes this session handle cookies and store them in in file. If file is nil they will be stored in memory. Otherwise the file must be readable and writable. Calling multiple times will add more files.



81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/patron/session.rb', line 81

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, "Cant read or write file #{path} (permission error)"
    end
  end
  enable_cookie_session(path.to_s)
  self
end

#handle_request(request) ⇒ Object 



391
392
393
394
 
# File 'ext/patron/session_ext.c', line 391

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.



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

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.



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

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.



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

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

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

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



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

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.



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

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) 


161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/patron/session.rb', line 161

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.upload_data = options[:data]
  req.file_name = options[:file]
  req.proxy = proxy
  req.auth_type = auth_type
  req.insecure = insecure

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

  handle_request(req)
end

#unescape(value) ⇒ Object

Unescapes the provided string.



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'ext/patron/session_ext.c', line 130

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