patron 0.13.3 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e766e45bfa71015943701e1340503df7f915d499cd001475649613175df4006d
-  data.tar.gz: 8b3a7d7fcb6d555dfff1705685c8685b925c900dfec95200816580028ffa9d53
+  metadata.gz: 355b38921e6368ee1ad7815cd78ad9135630b10c82d60365978747e4189be390
+  data.tar.gz: efbebf2f2e6393e93411d5583c9062b3170e0bf4e30ae370d1e998110b19c3c3
 SHA512:
-  metadata.gz: 986e1bb343ea53368a6acb8f7d7ef84a48674408d4a08f7eabe1d2e2c6ff5c90f2afe0683d1e66ab751c72241a25c9f46c8e16c955c97b87c71a0bc2bd7db723
-  data.tar.gz: c285b097c1fc4022fce3484184ac44d471340a496bc246142233e655bfdf0a28653484490ce5b1802fac4d5b396bea8ca03cfd1c803867f7c07ff3d8a789335c
+  metadata.gz: 760418bb81862c742f9873caa2513a6ed60093a084145b77e9f21996f041b0e848a0a6914e0248c0dca806bc5313c59eed68afd2546c828218a2e0aa52734ecf
+  data.tar.gz: 77510952d581ea162ef55e93260fc8188e58b5f919dd97912c6d7b40863c94e2c517027c6de5fe2b5041431fb9645c85ad674b08f37ce7e2fcdb37b4f16f2da2

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

data/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    continue-on-error: ${{ matrix.allow-failure || false }}
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["2.4", "3.0", "3.4.1", "4.0.5"]
+        include:
+          - ruby-version: "head"
+            allow-failure: true
+
+    name: Specs - Ruby ${{ matrix.ruby-version }}
+    steps:
+    - uses: actions/checkout@v7
+    - name: Install libcurl
+      run: |
+        sudo apt-get update
+        sudo apt-get -y install libcurl4 libcurl4-openssl-dev 
+    - name: Set up Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # 'bundle install' and cache
+    - name: Run tests
+      run: bundle exec rake
+
+  valgrind:
+    runs-on: ubuntu-latest
+    name: Specs under valgrind memcheck
+    steps:
+    - uses: actions/checkout@v7
+    - name: Install libcurl and valgrind
+      run: |
+        sudo apt-get update
+        sudo apt-get -y install libcurl4-openssl-dev valgrind
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: "3.4"
+        bundler-cache: true
+    - name: Compile the extension with debug info
+      run: bundle exec rake clobber compile
+      env:
+        PATRON_EXTRA_CFLAGS: "-g -O1"
+    - name: Run the specs under memcheck
+      # The ruby process itself is under valgrind (bundle exec only sets up the environment).
+      # Specs tagged :timing assert on wall-clock windows that valgrind's slowdown breaks.
+      run: |
+        bundle exec valgrind --error-exitcode=99 --leak-check=no --undef-value-errors=no \
+          --child-silent-after-fork=yes --num-callers=30 \
+          --suppressions=spec/support/valgrind.supp \
+          ruby -S rspec --tag ~timing
+
+  malloc-check:
+    runs-on: ubuntu-latest
+    name: Specs with glibc malloc checking
+    steps:
+    - uses: actions/checkout@v7
+    - name: Install libcurl
+      run: |
+        sudo apt-get update
+        sudo apt-get -y install libcurl4-openssl-dev
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: "3.4"
+        bundler-cache: true
+    - name: Run tests
+      # glibc aborts on heap corruption and fills freed memory with 0xA5, so a use-after-free
+      # shows up as garbage data rather than passing by luck
+      run: bundle exec rake
+      env:
+        MALLOC_CHECK_: "3"
+        MALLOC_PERTURB_: "165"

data/.travis.yml

@@ -1,10 +1,13 @@
 rvm:
-- 1.9.3
-- 2.1.5
-- 2.2.2
-- 2.3.4
-- 2.4.1
-- 2.5.0
-sudo: false
+- 2.3.8
+- 2.4.5
+- 2.5.3
+- 2.6.1
+- ruby-head
+
 dist: trusty
 cache: bundler
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head

data/CHANGELOG.md

@@ -1,6 +1,37 @@
+### Unreleased
+
+### 0.14.0
+
+* Expose libcurl's transfer timings (name lookup, connect, TLS, first byte, total) as `Response#timings`
+* Add `ssl_cert`, `ssl_cert_type`, `ssl_key` and `ssl_key_password` for presenting a client certificate (mutual TLS). Thanks @lenage for the original contribution in #165
+* Raise `Patron::ClientCertificateError` when the client certificate or its key can't be used
+* Accept a `Pathname` for `cacert`
+* Fix a request whose options fail to apply (for example an option of the wrong type) leaking its headers and open files into the next request on the same `Session`
+* Fix the request body being read from freed memory when `upload_data` is not a String (its `#to_s` result was not kept alive during the transfer)
+* Fix multipart field names and values pointing at temporary Strings, and binary multipart values being cut at the first NUL byte
+* Fix an exception raised inside `progress_callback` (including `Timeout.timeout` and `Thread#raise`) unwinding through libcurl; it is now re-raised after the transfer is aborted
+* Raise `Patron::Error` when a second thread uses a `Session` that is already performing a request, instead of corrupting both requests
+* Fix the progress callback being declared with `size_t` arguments where libcurl passes `curl_off_t`
+* Accept `download_byte_limit` above 2 GiB, and Floats for `dns_cache_timeout`, `low_speed_time` and `low_speed_limit`
+* Fix `Session#unescape` cutting the result at a `%00`, and raise instead of crashing when libcurl fails to escape or unescape
+* Reject file paths containing NUL bytes for cookie files, debug output and uploads
+* Raise `NoMemoryError` instead of crashing later when libcurl cannot allocate a Session's handles
+* Register the exception classes the extension looks up at load time with the GC, so heap compaction (`GC.compact`, `GC.auto_compact`) cannot move them out from under `rb_raise`
+
+### 0.13.4
+
+* Format README a bit better using code fences
+* Depend explicitly on base64 for running tests
+* Remove C code used for Ruby support below < 2.4 (GVL unlock etc.) and drop support for these versions
+* In tests, close Tempfiles before allowing libcurl to use them (cookie jar)
+* Fix incorrect ptr type in uses of `curl_easy_escape` / `_unescape`
+* Define methods on `Session` as private instance methods from C instead of privatising them from Ruby
+* Speed up the /slow endpoint test
+* Remove use of `curl_easy_reset`. This should fix the bug with sessions resetting each other's state during `session_free`
+
 ### 0.13.3
 
-* Fix a number of specs that were failing due to use of threads
+* Run Puma test servers in separate processes instead of threads
 
 ### 0.13.2
 

data/Gemfile

@@ -1,4 +1,18 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in patron.gemspec
+# Runtime dependencies are in the gemspec
 gemspec
+
+# Gems below are only needed for Patron development
+# and tests
+gem "rake", ">= 12.3.3"
+gem "rspec", ">= 2.3.0"
+gem "simplecov", "~> 0.10"
+gem "yard", "~> 0.9.20"
+rack_version = RUBY_VERSION >= "3.3" ? "~> 2.2" : "~> 2.1.4"
+gem "rack", rack_version
+gem "puma", '~> 5.6'
+gem "rake-compiler"
+gem "webrick", "~> 1.8"
+gem "base64"
+gem "ostruct"

data/README.md

@@ -1,3 +1,7 @@
+# Patron
+
+[![Tests](https://github.com/toland/patron/actions/workflows/ci.yml/badge.svg)](https://github.com/toland/patron/actions/workflows/ci.yml)
+
 Patron is a Ruby HTTP client library based on libcurl. It does not try to expose
 the full "power" (read complexity) of libcurl but instead tries to provide a
 sane API while taking advantage of libcurl under the hood.
@@ -8,47 +12,92 @@ First, you instantiate a Session object. You can set a few
 default options on the Session instance that will be used by all subsequent
 requests:
 
-    sess = Patron::Session.new
-    sess.timeout = 10
-    sess.base_url = "http://myserver.com:9900"
-    sess.headers['User-Agent'] = 'myapp/1.0'
+```ruby
+sess = Patron::Session.new
+sess.timeout = 10
+sess.base_url = "http://myserver.com:9900"
+sess.headers['User-Agent'] = 'myapp/1.0'
+```
 
 You can set options with a hash in the constructor:
 
-    sess = Patron::Session.new({ :timeout => 10,
-                                 :base_url => 'http://myserver.com:9900',
-                                 :headers => {'User-Agent' => 'myapp/1.0'} } )
+```ruby
+sess = Patron::Session.new({ :timeout => 10,
+                             :base_url => 'http://myserver.com:9900',
+                             :headers => {'User-Agent' => 'myapp/1.0'} } )
+```
 
 Or the set options in a block:
 
-    sess = Patron::Session.new do |patron|
-        patron.timeout = 10
-        patron.base_url = 'http://myserver.com:9900'
-        patron.headers = {'User-Agent' => 'myapp/1.0'}
-    end
+```ruby
+sess = Patron::Session.new do |patron|
+    patron.timeout = 10
+    patron.base_url = 'http://myserver.com:9900'
+    patron.headers = {'User-Agent' => 'myapp/1.0'}
+end
+```
 
 Output debug log:
 
-    sess.enable_debug "/tmp/patron.debug"
+```ruby
+sess.enable_debug "/tmp/patron.debug"
+```
 
 The Session is used to make HTTP requests.
 
-    resp = sess.get("/foo/bar")
+```ruby
+resp = sess.get("/foo/bar")
+```
 
 Requests return a Response object:
 
-    if resp.status < 400
-      puts resp.body
-    end
+```ruby
+if resp.status < 400
+  puts resp.body
+end
+```
 
 The GET, HEAD, PUT, POST and DELETE operations are all supported.
 
-    sess.put("/foo/baz", "some data")
-    sess.delete("/foo/baz")
+```ruby
+sess.put("/foo/baz", "some data")
+sess.delete("/foo/baz")
+```
 
 You can ship custom headers with a single request:
 
-    sess.post("/foo/stuff", "some data", {"Content-Type" => "text/plain"})
+```ruby
+sess.post("/foo/stuff", "some data", {"Content-Type" => "text/plain"})
+```
+
+libcurl's transfer timings are available on the response, in seconds since the request started:
+
+```ruby
+resp = sess.get("/foo/bar")
+resp.timings # => {namelookup: 0.001, connect: 0.012, appconnect: 0.045, pretransfer: 0.045,
+             #     starttransfer: 0.210, redirect: 0.0, total: 0.214}
+```
+
+To authenticate with a client certificate (mutual TLS), point Patron at a PKCS#12 bundle:
+
+```ruby
+sess.ssl_cert = "/path/to/client.p12"
+sess.ssl_cert_type = "P12"
+sess.ssl_key_password = "secret"
+```
+
+or at a PEM certificate with a separate private key:
+
+```ruby
+sess.ssl_cert = "/path/to/client.pem"
+sess.ssl_key = "/path/to/client_key.pem"
+sess.ssl_key_password = "secret" # if the key is encrypted
+```
+
+If the certificate or key can't be loaded (wrong password, missing file) the request raises `Patron::ClientCertificateError`.
+This depends on the TLS library libcurl is built against: with GnuTLS these surface as a plain `Patron::Error`.
+Client certificates are tested with the OpenSSL and LibreSSL backends - libcurl's Secure Transport backend
+can't load a PEM certificate from a file at all.
 
 ## Threading
 
@@ -58,16 +107,18 @@ for doing concurrent requests. However, the actual code that interacts with libC
 so using multiple `Session` objects in different threads actually enables a high degree of parallelism.
 For sharing a resource of sessions between threads we recommend using the excellent [connection_pool](https://rubygems.org/gems/connection_pool) gem by Mike Perham.
 
-    patron_pool = ConnectionPool.new(size: 5, timeout: 5) { Patron::Session.new }
-    patron_pool.with do |session|
-      session.get(...)
-    end
+```ruby
+patron_pool = ConnectionPool.new(size: 5, timeout: 5) { Patron::Session.new }
+patron_pool.with do |session|
+  session.get(...)
+end
+```
 
 Sharing Session objects between requests will also allow you to benefit from persistent connections (connection reuse), see below.
 
 ## Persistent connections
 
-Patron follows the libCURL guidelines on [connection reuse.](https://ec.haxx.se/libcurl-connectionreuse.html) If you create the Session
+Patron follows the libCURL guidelines on [connection reuse.](https://everything.curl.dev/libcurl/connectionreuse.html) If you create the Session
 object once and use it for multiple requests, the same libCURL handle is going to be used across these requests and if requests go to
 the same hostname/port/protocol the connection should get reused.
 
@@ -81,8 +132,10 @@ that are currently active in the process.
 
 ## Requirements
 
-Patron uses encoding features of Ruby, so you need at least Ruby 1.9. Also, a
-recent version of libCURL is required. We recommend at least 7.19.4 because
+Patron 1.0 and up requires MRI Ruby 2.3 or newer. The 0.x versions support
+Ruby 1.9.3 and these versions get tagged and developed on the `v0.x` branch.
+
+A recent version of libCURL is required. We recommend at least 7.19.4 because
 it [supports limiting the protocols](https://curl.haxx.se/libcurl/c/CURLOPT_PROTOCOLS.html),
 and that is very important for security - especially if you follow redirects. 
 
@@ -90,9 +143,6 @@ On OSX the provided libcurl is sufficient if you are not using fork+SSL combinat
 You will have to install the libcurl development packages on Debian or Ubuntu. Other Linux systems are probably
 similar. For Windows we do not have an established build instruction at the moment, unfortunately.
 
-Versions of Patron below 1.0 will maintain compatibility down to Ruby 1.9.3,
-versions below 2.0 will maintain compatibility down to Ruby 2.3
-
 ## Forking webservers on macOS and SSL
 
 Currently, [an issue is at play](https://github.com/curl/curl/issues/788) with OSX builds of `curl` which use

data/ext/patron/extconf.rb

@@ -19,9 +19,12 @@ if CONFIG['CC'] =~ /gcc/
   $CFLAGS << ' -pedantic -Wall'
 end
 
-$defs.push("-DUSE_TBR")
-$defs.push("-DHAVE_THREAD_H") if have_header('ruby/thread.h')
-$defs.push("-DHAVE_TBR") if have_func('rb_thread_blocking_region', 'ruby.h')
-$defs.push("-DHAVE_TCWOGVL") if have_header('ruby/thread.h') && have_func('rb_thread_call_without_gvl', 'ruby/thread.h')
+if CONFIG['CC'] =~ /clang/
+  $CFLAGS << ' -pedantic -Wall -Wno-void-pointer-to-enum-cast'
+end
+
+# Lets CI build with debug info for valgrind without editing this file, like so:
+# PATRON_EXTRA_CFLAGS="-g -O1" rake compile
+$CFLAGS << ' ' << ENV['PATRON_EXTRA_CFLAGS'] if ENV['PATRON_EXTRA_CFLAGS']
 
 create_makefile 'patron/session_ext'