curb 0.8.5 → 0.8.6

data/README.markdown

@@ -0,0 +1,230 @@
+# Curb - Libcurl bindings for Ruby
+
+* [rubyforge rdoc](http://curb.rubyforge.org/)
+* [rubyforge project](http://rubyforge.org/projects/curb)
+* [github project](http://github.com/taf2/curb/tree/master)
+
+Curb (probably CUrl-RuBy or something) provides Ruby-language bindings for the
+libcurl(3), a fully-featured client-side URL transfer library.
+cURL and libcurl live at [http://curl.haxx.se/](http://curl.haxx.se/) .
+
+Curb is a work-in-progress, and currently only supports libcurl's 'easy' and 'multi' modes.
+
+## License
+
+Curb is copyright (c)2006 Ross Bamford, and released under the terms of the 
+Ruby license. See the LICENSE file for the gory details. 
+
+## You will need
+
+* A working Ruby installation (1.8+, tested with 1.8.6, 1.8.7, 1.9.1, and 1.9.2)
+* A working (lib)curl installation, with development stuff (7.5+, tested with 7.19.x)
+* A sane build environment (e.g. gcc, make)
+
+## Installation...
+
+... will usually be as simple as:
+
+    $ gem install curb
+  
+Or, if you downloaded the archive:  
+
+    $ rake install 
+
+If you have a weird setup, you might need extconf options. In this case, pass
+them like so:
+
+    $ rake install EXTCONF_OPTS='--with-curl-dir=/path/to/libcurl --prefix=/what/ever'
+  
+Curb is tested only on GNU/Linux x86 and Mac OSX - YMMV on other platforms.
+If you do use another platform and experience problems, or if you can 
+expand on the above instructions, please report the issue at http://github.com/taf2/curb/issues
+
+On Ubuntu, the dependencies can be satisfied by installing the following packages:
+
+    $ sudo apt-get install libcurl3 libcurl3-gnutls libcurl4-openssl-dev
+
+Curb has fairly extensive RDoc comments in the source. You can build the
+documentation with:
+
+    $ rake doc
+
+## Usage & examples
+
+Curb provides two classes:
+
+* `Curl::Easy` - simple API, for day-to-day tasks.
+* `Curl::Multi` - more advanced API, for operating on multiple URLs simultaneously.
+
+### Super simple API (less typing)
+
+```ruby
+http = Curl.get("http://www.google.com/")
+puts http.body_str
+
+http = Curl.post("http://www.google.com/", {:foo => "bar"})
+puts http.body_str
+
+http = Curl.get("http://www.google.com/") do|http|
+  http.headers['Cookie'] = 'foo=1;bar=2'
+end
+puts http.body_str
+```
+
+### Simple fetch via HTTP:
+
+```ruby
+c = Curl::Easy.perform("http://www.google.co.uk")
+puts c.body_str
+```
+
+Same thing, more manual:
+
+```ruby
+c = Curl::Easy.new("http://www.google.co.uk")
+c.perform
+puts c.body_str
+```
+
+### Additional config:
+
+```ruby
+Curl::Easy.perform("http://www.google.co.uk") do |curl| 
+  curl.headers["User-Agent"] = "myapp-0.0"
+  curl.verbose = true
+end
+```
+
+Same thing, more manual:
+
+```ruby
+c = Curl::Easy.new("http://www.google.co.uk") do |curl| 
+  curl.headers["User-Agent"] = "myapp-0.0"
+  curl.verbose = true
+end
+
+c.perform
+```
+
+### HTTP basic authentication:
+
+```ruby
+c = Curl::Easy.new("http://github.com/")
+c.http_auth_types = :basic
+c.username = 'foo'
+c.password = 'bar'
+c.perform
+```
+
+### HTTP "insecure" SSL connections (like curl -k, --insecure) to avoid Curl::Err::SSLCACertificateError:
+
+```ruby
+    c = Curl::Easy.new("http://github.com/")
+    c.ssl_verify_peer = false
+    c.perform
+```
+
+### Supplying custom handlers:
+
+```ruby
+c = Curl::Easy.new("http://www.google.co.uk")
+
+c.on_body { |data| print(data) }
+c.on_header { |data| print(data) }
+
+c.perform
+```
+
+### Reusing Curls:
+
+```ruby
+c = Curl::Easy.new
+
+["http://www.google.co.uk", "http://www.ruby-lang.org/"].map do |url|
+  c.url = url
+  c.perform
+  c.body_str
+end
+```
+
+### HTTP POST form:
+
+```ruby
+c = Curl::Easy.http_post("http://my.rails.box/thing/create",
+                         Curl::PostField.content('thing[name]', 'box'),
+                         Curl::PostField.content('thing[type]', 'storage'))
+```
+
+### HTTP POST file upload:
+
+```ruby
+c = Curl::Easy.new("http://my.rails.box/files/upload")
+c.multipart_form_post = true
+c.http_post(Curl::PostField.file('thing[file]', 'myfile.rb'))
+```
+
+### Multi Interface (Basic HTTP GET):
+
+```ruby
+# make multiple GET requests
+easy_options = {:follow_location => true}
+multi_options = {:pipeline => true}
+
+Curl::Multi.get('url1','url2','url3','url4','url5', easy_options, multi_options) do|easy|
+  # do something interesting with the easy response
+  puts easy.last_effective_url
+end
+```
+
+### Multi Interface (Basic HTTP POST):
+
+```ruby
+# make multiple POST requests
+easy_options = {:follow_location => true, :multipart_form_post => true}
+multi_options = {:pipeline => true}
+
+url_fields = [
+  { :url => 'url1', :post_fields => {'f1' => 'v1'} },
+  { :url => 'url2', :post_fields => {'f1' => 'v1'} },
+  { :url => 'url3', :post_fields => {'f1' => 'v1'} }
+]
+
+Curl::Multi.post(url_fields, easy_options, multi_options) do|easy|
+  # do something interesting with the easy response
+  puts easy.last_effective_url
+end
+```
+
+### Multi Interface (Advanced):
+
+```ruby
+responses = {}
+requests = ["http://www.google.co.uk/", "http://www.ruby-lang.org/"]
+m = Curl::Multi.new
+# add a few easy handles
+requests.each do |url|
+  responses[url] = ""
+  c = Curl::Easy.new(url) do|curl|
+    curl.follow_location = true
+    curl.on_body{|data| responses[url] << data; data.size }
+    curl.on_success {|easy| puts "success, add more easy handles" }
+  end
+  m.add(c)
+end
+
+m.perform do
+  puts "idling... can do some work here"
+end
+
+requests.each do|url|
+  puts responses[url]
+end
+```
+
+### Easy Callbacks
+
+* `on_success`  is called when the response code is 2xx
+* `on_redirect` is called when the response code is 3xx
+* `on_missing` is called when the response code is 4xx
+* `on_failure` is called when the response code is 5xx
+* `on_complete` is called in all cases.

data/ext/curb.c

@@ -304,6 +304,13 @@ void Init_curb_core() {
   rb_define_const(mCurl, "CURLPROXY_SOCKS4", INT2FIX(-2));
 #endif
 
+  /* When passed to Curl::Easy#proxy_type , indicates that the proxy is a SOCKS4A proxy. (libcurl >= 7.18.0) */
+#ifdef HAVE_CURLPROXY_SOCKS4A
+  rb_define_const(mCurl, "CURLPROXY_SOCKS4A", INT2FIX(CURLPROXY_SOCKS4A));
+#else
+  rb_define_const(mCurl, "CURLPROXY_SOCKS4A", INT2FIX(-2));
+#endif
+
   /* When passed to Curl::Easy#proxy_type , indicates that the proxy is a SOCKS5 proxy. (libcurl >= 7.10) */
 #ifdef HAVE_CURLPROXY_SOCKS5
   rb_define_const(mCurl, "CURLPROXY_SOCKS5", INT2FIX(CURLPROXY_SOCKS5));

data/ext/curb.h

@@ -20,11 +20,11 @@
 #include "curb_macros.h"
 
 // These should be managed from the Rake 'release' task.
-#define CURB_VERSION   "0.8.5"
-#define CURB_VER_NUM   805
+#define CURB_VERSION   "0.8.6"
+#define CURB_VER_NUM   806
 #define CURB_VER_MAJ   0
 #define CURB_VER_MIN   8
-#define CURB_VER_MIC   5
+#define CURB_VER_MIC   6
 #define CURB_VER_PATCH 0
 
 
@@ -37,12 +37,8 @@
   #define RSTRING_PTR(x) RSTRING(x)->ptr
 #endif
 
-#ifndef RHASH_LEN
-#ifdef HAVE_RUBY19_HASH
-  #define RHASH_LEN(hash) RHASH(hash)->ntbl->num_entries
-#else
-  #define RHASH_LEN(hash) RHASH(hash)->tbl->num_entries
-#endif
+#ifndef RHASH_SIZE
+  #define RHASH_SIZE(hash) RHASH(hash)->tbl->num_entries
 #endif
 
 extern VALUE mCurl;

data/ext/curb_easy.c

@@ -96,6 +96,25 @@ static size_t read_data_handler(void *ptr,
   }
 }
 
+int seek_data_handler(ruby_curl_easy *rbce,
+                      curl_off_t offset,
+                      int origin) {
+
+  VALUE upload = rb_easy_get("upload");
+  VALUE stream = ruby_curl_upload_stream_get(upload);
+
+  if (rb_respond_to(stream, rb_intern("seek"))) {
+    rb_funcall(stream, rb_intern("seek"), 2, SEEK_SET, offset);
+  } else {
+    ruby_curl_upload *rbcu;
+    Data_Get_Struct(upload, ruby_curl_upload, rbcu);
+    // This OK because curl only uses SEEK_SET as per the documentation
+    rbcu->offset = offset;
+  }
+
+  return 0;
+}
+
 static size_t proc_data_handler(char *stream,
                                 size_t size,
                                 size_t nmemb,
@@ -772,7 +791,9 @@ static VALUE ruby_curl_easy_put_data_set(VALUE self, VALUE data) {
   curl_easy_setopt(curl, CURLOPT_NOBODY, 0);
   curl_easy_setopt(curl, CURLOPT_UPLOAD, 1);
   curl_easy_setopt(curl, CURLOPT_READFUNCTION, (curl_read_callback)read_data_handler);
+  curl_easy_setopt(curl, CURLOPT_SEEKFUNCTION, (curl_seek_callback)seek_data_handler);
   curl_easy_setopt(curl, CURLOPT_READDATA, rbce);
+  curl_easy_setopt(curl, CURLOPT_SEEKDATA, rbce);
 
   /* 
    * we need to set specific headers for the PUT to work... so
@@ -1637,9 +1658,10 @@ static VALUE ruby_curl_easy_ignore_content_length_q(VALUE self) {
  */
 static VALUE ruby_curl_easy_resolve_mode(VALUE self) {
   ruby_curl_easy *rbce;
+  unsigned short rm;
   Data_Get_Struct(self, ruby_curl_easy, rbce);
 
-  unsigned short rm = rbce->resolve_mode;
+  rm = rbce->resolve_mode;
 
   switch(rm) {
     case CURL_IPRESOLVE_V4:
@@ -1668,9 +1690,10 @@ static VALUE ruby_curl_easy_resolve_mode_set(VALUE self, VALUE resolve_mode) {
     return Qnil;
   } else {
     ruby_curl_easy *rbce;
+    ID resolve_mode_id;
     Data_Get_Struct(self, ruby_curl_easy, rbce);
 
-    ID resolve_mode_id = rb_to_id(resolve_mode);
+    resolve_mode_id = rb_to_id(resolve_mode);
 
     if (resolve_mode_id == rb_intern("auto")) {
       rbce->resolve_mode = CURL_IPRESOLVE_WHATEVER;
@@ -1850,10 +1873,10 @@ static VALUE ruby_curl_easy_on_debug_set(int argc, VALUE *argv, VALUE self) {
  */
 static VALUE cb_each_http_header(VALUE header, VALUE wrap) {
   struct curl_slist **list;
-  Data_Get_Struct(wrap, struct curl_slist *, list);
-
   VALUE header_str = Qnil;
 
+  Data_Get_Struct(wrap, struct curl_slist *, list);
+
   //rb_p(header);
 
   if (rb_type(header) == T_ARRAY) {
@@ -1882,9 +1905,10 @@ static VALUE cb_each_http_header(VALUE header, VALUE wrap) {
  */
 static VALUE cb_each_ftp_command(VALUE ftp_command, VALUE wrap) {
   struct curl_slist **list;
+  VALUE ftp_command_string;
   Data_Get_Struct(wrap, struct curl_slist *, list);
 
-  VALUE ftp_command_string = rb_obj_as_string(ftp_command);
+  ftp_command_string = rb_obj_as_string(ftp_command);
   *list = curl_slist_append(*list, StringValuePtr(ftp_command));
 
   return ftp_command_string;
@@ -3129,6 +3153,9 @@ static VALUE ruby_curl_easy_set_opt(VALUE self, VALUE opt, VALUE val) {
     VALUE cookiejar = val;
     CURB_OBJECT_HSETTER(ruby_curl_easy, cookiejar);
     } break;
+  case CURLOPT_TCP_NODELAY: {
+    curl_easy_setopt(rbce->curl, CURLOPT_TCP_NODELAY, FIX2LONG(val));
+    } break;
   case CURLOPT_RESUME_FROM: {
     curl_easy_setopt(rbce->curl, CURLOPT_RESUME_FROM, FIX2LONG(val));
     } break;
@@ -3141,7 +3168,7 @@ static VALUE ruby_curl_easy_set_opt(VALUE self, VALUE opt, VALUE val) {
     } break;
 #endif
   default:
-    break;
+    rb_raise(rb_eTypeError, "Curb unsupported option");
   }
 
   return val;
@@ -3247,7 +3274,7 @@ static VALUE ruby_curl_easy_unescape(VALUE self, VALUE str) {
 
 /*
  * call-seq:
- *   Curl::Easy.error(code)    => String
+ *   Curl::Easy.error(code)    => [ErrCode, String]
  *
  * translate an internal libcurl error to ruby error class
  */

data/ext/curb_errors.c

@@ -32,13 +32,13 @@ VALUE eCurlErrNotBuiltIn;
 VALUE eCurlErrProxyResolution;
 VALUE eCurlErrHostResolution;
 VALUE eCurlErrConnectFailed;
-VALUE eCurlErrFTPWierdReply;
+VALUE eCurlErrFTPWeirdReply;
 VALUE eCurlErrFTPAccessDenied;
 VALUE eCurlErrFTPBadPassword;
-VALUE eCurlErrFTPWierdPassReply;
-VALUE eCurlErrFTPWierdUserReply;
-VALUE eCurlErrFTPWierdPasvReply;
-VALUE eCurlErrFTPWierd227Format;
+VALUE eCurlErrFTPWeirdPassReply;
+VALUE eCurlErrFTPWeirdUserReply;
+VALUE eCurlErrFTPWeirdPasvReply;
+VALUE eCurlErrFTPWeird227Format;
 VALUE eCurlErrFTPCantGetHost;
 VALUE eCurlErrFTPCantReconnect;
 VALUE eCurlErrFTPCouldntSetBinary;
@@ -118,6 +118,9 @@ VALUE mCurlErrBadEasyHandle;
 VALUE mCurlErrOutOfMemory;
 VALUE mCurlErrInternalError;
 VALUE mCurlErrBadSocket;
+#if HAVE_CURLM_ADDED_ALREADY
+VALUE mCurlErrAddedAlready;
+#endif
 VALUE mCurlErrUnknownOption;
 
 /* binding errors */
@@ -161,7 +164,7 @@ VALUE rb_curl_easy_error(CURLcode code) {
       exclz = eCurlErrConnectFailed;
       break;
     case CURLE_FTP_WEIRD_SERVER_REPLY:  /* 8 */
-      exclz = eCurlErrFTPWierdReply;
+      exclz = eCurlErrFTPWeirdReply;
       break;
     case CURLE_FTP_ACCESS_DENIED:       /* 9 denied due to lack of access. */
       exclz = eCurlErrFTPAccessDenied;
@@ -170,16 +173,16 @@ VALUE rb_curl_easy_error(CURLcode code) {
       exclz = eCurlErrFTPBadPassword;
       break;
     case CURLE_FTP_WEIRD_PASS_REPLY:    /* 11 */
-      exclz = eCurlErrFTPWierdPassReply;
+      exclz = eCurlErrFTPWeirdPassReply;
       break;
     case CURLE_FTP_WEIRD_USER_REPLY:    /* 12 */
-      exclz = eCurlErrFTPWierdUserReply;
+      exclz = eCurlErrFTPWeirdUserReply;
       break;
     case CURLE_FTP_WEIRD_PASV_REPLY:    /* 13 */
-      exclz = eCurlErrFTPWierdPasvReply;
+      exclz = eCurlErrFTPWeirdPasvReply;
       break;
     case CURLE_FTP_WEIRD_227_FORMAT:    /* 14 */
-      exclz = eCurlErrFTPWierd227Format;
+      exclz = eCurlErrFTPWeird227Format;
       break;
     case CURLE_FTP_CANT_GET_HOST:       /* 15 */
       exclz = eCurlErrFTPCantGetHost;
@@ -492,6 +495,11 @@ VALUE rb_curl_multi_error(CURLMcode code) {
     case CURLM_UNKNOWN_OPTION: /* 6 */
       exclz = mCurlErrUnknownOption;
       break;
+#endif
+#if HAVE_CURLM_ADDED_ALREADY
+    case CURLM_ADDED_ALREADY: /* 7 */
+      exclz = mCurlErrAddedAlready;
+      break;
 #endif
     default:
       exclz = eCurlErrError;
@@ -535,13 +543,13 @@ void init_curb_errors() {
   eCurlErrHostResolution = rb_define_class_under(mCurlErr, "HostResolutionError", eCurlErrError);
   eCurlErrConnectFailed = rb_define_class_under(mCurlErr, "ConnectionFailedError", eCurlErrError);
 
-  eCurlErrFTPWierdReply = rb_define_class_under(mCurlErr, "WierdReplyError", eCurlErrFTPError);
+  eCurlErrFTPWeirdReply = rb_define_class_under(mCurlErr, "WeirdReplyError", eCurlErrFTPError);
   eCurlErrFTPAccessDenied = rb_define_class_under(mCurlErr, "AccessDeniedError", eCurlErrFTPError);
-  eCurlErrFTPBadPassword = rb_define_class_under(mCurlErr, "BadBasswordError", eCurlErrFTPError);
-  eCurlErrFTPWierdPassReply = rb_define_class_under(mCurlErr, "WierdPassReplyError", eCurlErrFTPError);
-  eCurlErrFTPWierdUserReply = rb_define_class_under(mCurlErr, "WierdUserReplyError", eCurlErrFTPError);
-  eCurlErrFTPWierdPasvReply = rb_define_class_under(mCurlErr, "WierdPasvReplyError", eCurlErrFTPError);
-  eCurlErrFTPWierd227Format = rb_define_class_under(mCurlErr, "Wierd227FormatError", eCurlErrFTPError);
+  eCurlErrFTPBadPassword = rb_define_class_under(mCurlErr, "BadPasswordError", eCurlErrFTPError);
+  eCurlErrFTPWeirdPassReply = rb_define_class_under(mCurlErr, "WeirdPassReplyError", eCurlErrFTPError);
+  eCurlErrFTPWeirdUserReply = rb_define_class_under(mCurlErr, "WeirdUserReplyError", eCurlErrFTPError);
+  eCurlErrFTPWeirdPasvReply = rb_define_class_under(mCurlErr, "WeirdPasvReplyError", eCurlErrFTPError);
+  eCurlErrFTPWeird227Format = rb_define_class_under(mCurlErr, "Weird227FormatError", eCurlErrFTPError);
   eCurlErrFTPCantGetHost = rb_define_class_under(mCurlErr, "CantGetHostError", eCurlErrFTPError);
   eCurlErrFTPCantReconnect = rb_define_class_under(mCurlErr, "CantReconnectError", eCurlErrFTPError);
   eCurlErrFTPCouldntSetBinary = rb_define_class_under(mCurlErr, "CouldntSetBinaryError", eCurlErrFTPError);
@@ -625,6 +633,9 @@ void init_curb_errors() {
   mCurlErrOutOfMemory        = rb_define_class_under(mCurlErr, "MultiOutOfMemory", eCurlErrError);
   mCurlErrInternalError      = rb_define_class_under(mCurlErr, "MultiInternalError", eCurlErrError);
   mCurlErrBadSocket          = rb_define_class_under(mCurlErr, "MultiBadSocket", eCurlErrError);
+#if HAVE_CURLM_ADDED_ALREADY
+  mCurlErrAddedAlready       = rb_define_class_under(mCurlErr, "MultiAddedAlready", eCurlErrError);
+#endif
   mCurlErrUnknownOption      = rb_define_class_under(mCurlErr, "MultiUnknownOption", eCurlErrError);
 
   eCurlErrLDAPInvalidURL = rb_define_class_under(mCurlErr, "InvalidLDAPURLError", eCurlErrLDAPError);