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 https://curl.se/libcurl/ .
Curb is a work-in-progress, and currently only supports libcurl's easy
and multi
modes.
Curb is copyright (c) 2006 Ross Bamford, and released under the terms of the Ruby license. See the LICENSE file for the gory details.
GET request
res = Curl.get("https://www.google.com/") {|http|
http.timeout = 10 # raise exception if request/response not handled within 10 seconds
}
puts res.code
puts res.head
puts res.body
POST request
res = Curl.post("https://your-server.com/endpoint", {post: "this"}.to_json) {|http|
http.headers["Content-Type"] = "application/json"
}
puts res.code
puts res.head
puts res.body
- A working Ruby installation (
2.0.0+
will work but2.1+
preferred) (it's possible it still works with 1.8.7 but you'd have to tell me if not...) - A working libcurl development installation
(Ideally one of the versions listed in the compatibility chart below that maps to your
curb
version) - A sane build environment (e.g. gcc, make)
A non-exhaustive set of compatibility versions of the libcurl library with this gem are as follows. (Note that these are only the ones that have been tested and reported to work across a variety of platforms / rubies)
Gem Version | Release Date | libcurl versions |
---|---|---|
1.0.5 | Jan 2023 | 7.58 - 7.87 |
1.0.4 | Jan 2023 | 7.58 - 7.87 |
1.0.3* | Dec 2022 | 7.58 - 7.87 |
1.0.2* | Dec 2022 | 7.58 - 7.87 |
1.0.1 | Apr 2022 | 7.58 - 7.87 |
1.0.0 | Jan 2022 | 7.58 - 7.87 |
0.9.8 | Jan 2019 | 7.58 - 7.81 |
0.9.7 | Nov 2018 | 7.56 - 7.60 |
0.9.6 | May 2018 | 7.51 - 7.59 |
0.9.5 | May 2018 | 7.51 - 7.59 |
0.9.4 | Aug 2017 | 7.41 - 7.58 |
0.9.3 | Apr 2016 | 7.26 - 7.58 |
*avoid using these version are known to have issues with segmentation faults
... will usually be as simple as:
$ gem install curb
On Windows, make sure you're using the DevKit and the development version of libcurl. Unzip, then run this in your command line (alter paths to your curl location, but remember to use forward slashes):
gem install curb --platform=ruby -- --with-curl-lib=C:/curl-7.39.0-devel-mingw32/lib --with-curl-include=C:/curl-7.39.0-devel-mingw32/include
Note that with Windows moving from one method of compiling to another as of Ruby 2.4
(DevKit -> MYSYS2),
the usage of Ruby 2.4+
with this gem on windows is unlikely to work. It is advised to use the
latest version of Ruby 2.3 available HERE
Or, if you downloaded the archive:
$ rake compile && rake install
If you have a weird setup, you might need extconf options. In this case, pass them like so:
$ rake compile EXTCONF_OPTS='--with-curl-dir=/path/to/libcurl --prefix=/what/ever' && rake install
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:
18.04 and onwards
$ sudo apt-get install libcurl4 libcurl3-gnutls libcurl4-openssl-dev
< 18.04
$ sudo apt-get install libcurl3 libcurl3-gnutls libcurl4-openssl-dev
On RedHat:
$ sudo yum install ruby-devel libcurl-devel openssl-devel
Curb has fairly extensive RDoc comments in the source. You can build the documentation with:
$ rake doc
Curb provides two classes:
Curl::Easy
- simple API, for day-to-day tasks.Curl::Multi
- more advanced API, for operating on multiple URLs simultaneously.
To use either, you will need to require the curb gem:
require 'curb'
http = Curl.get("http://www.google.com/")
puts http.body
http = Curl.post("http://www.google.com/", {:foo => "bar"})
puts http.body
http = Curl.get("http://www.google.com/") do |http|
http.headers['Cookie'] = 'foo=1;bar=2'
end
puts http.body
c = Curl::Easy.perform("http://www.google.co.uk")
puts c.body
Same thing, more manual:
c = Curl::Easy.new("http://www.google.co.uk")
c.perform
puts c.body
http = 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:
c = Curl::Easy.new("http://www.google.co.uk") do |curl|
curl.headers["User-Agent"] = "myapp-0.0"
curl.verbose = true
end
c.perform
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:
c = Curl::Easy.new("https://github.com/")
c.ssl_verify_peer = false
c.perform
c = Curl::Easy.new("http://www.google.co.uk")
c.on_body { |data| print(data) }
c.on_header { |data| print(data) }
c.perform
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
c = Curl::Easy.http_post("http://my.rails.box/thing/create",
Curl::PostField.content('thing[name]', 'box'),
Curl::PostField.content('thing[type]', 'storage'))
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'))
c = Curl::Easy.new("https://http2.akamai.com")
c.set(:HTTP_VERSION, Curl::HTTP_2_0)
c.perform
puts (c.body_str.include? "You are using HTTP/2 right now!") ? "HTTP/2" : "HTTP/1.x"
# make multiple GET requests
easy_options = {:follow_location => true}
# Use Curl::CURLPIPE_MULTIPLEX for HTTP/2 multiplexing
multi_options = {:pipeline => Curl::CURLPIPE_HTTP1}
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
# make multiple POST requests
easy_options = {:follow_location => true, :multipart_form_post => true}
multi_options = {:pipeline => Curl::CURLPIPE_HTTP1}
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
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
on_success
is called when the response code is 2xxon_redirect
is called when the response code is 3xxon_missing
is called when the response code is 4xxon_failure
is called when the response code is 5xxon_complete
is called in all cases.