patron 0.13.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f900014f4c841d87c4db54f3db3f33d9b624d5a6dde0eb9352b7a70cc6f330b7
-  data.tar.gz: 31b35805166302cb5527734b70c3607f9dbb951e2c1e3aafd465f7f8d5dbbb75
+  metadata.gz: 8f1026343c941740b978f220122296a7accd4de8770b18b317cdb6310e86dd5e
+  data.tar.gz: 0b90aed0ce0f16d4ae6b66ad0f44131b69e65b06d9e0e5e516d18c209b464160
 SHA512:
-  metadata.gz: 1989abb0ba1be73ed08df186d05349c6519a90663a7263799a1e97e024e5183ff6de9f49ab329ebf4e3b49c4c571d0e3ca7efed3bc5f803ad8edbe96a6554ff6
-  data.tar.gz: dc03c98c0f363d7d7bf273b72a62954dadb590c1236baf06739f6fdebd6ae5007afc243dc526c97359165c19244868779fc4168cc9f972c32cbf8fef81a56521
+  metadata.gz: cce780fab9bb4444992709dc18e2222bcb6e25fa03987b903270347e0a651080fe9024fa848da519b70a1511f429a4199f7e62425f554e4fb12b3bce198e31e7
+  data.tar.gz: d49a557d56dc10e57bc362f1af616eb779333da820c2899c4bb958347317d3bcc6eb171f8090ca03c2aae9ed94c5a53039e5c455206bb1372d743f6d029b97c3

data/CHANGELOG.md

@@ -1,3 +1,100 @@
+### Unreleased
+
+### 1.0.0
+
+Patron 1.0 is a rewrite of the C extension for modern Ruby and modern libcurl. It follows Ivo Anjo's
+guide ["Tips for updating Ruby C extensions for efficiently using Ruby 4 VM APIs"](https://github.com/ruby/ruby/blob/master/doc/efficient_extensions.md),
+which has since been merged into the Ruby documentation, and his post
+["Updating a C extension for a modern VM"](https://ivoanjo.me/blog/2026/09/23/updating-a-c-extension-for-a-modern-vm/).
+It requires **Ruby 3.3+** and **libcurl 7.81+**.
+
+**Transfers**
+
+* A `Session` used inside a Fiber scheduler (`Async { }`, Falcon) yields to the scheduler while libcurl
+  waits for the network instead of blocking the thread, so requests from several fibers overlap and
+  `Async::Task#stop` / `with_timeout` interrupt a request cleanly. No API change, nothing to configure
+
+* Requests are driven through libcurl's multi interface: every `Session` owns a multi handle with its own
+  connection cache (connection pooling, #138), `curl_multi_perform` runs with the GVL held and only
+  `curl_multi_poll` releases it, and `curl_multi_wakeup` is the unblocking function. `Thread#kill`,
+  `Thread#raise`, `Timeout.timeout`, signals and interpreter exit now interrupt a request immediately
+  in any phase of the transfer, including DNS resolution and connect, instead of at the next progress tick
+* `Session#interrupt` aborts the request in flight from another thread immediately and raises `Patron::Aborted`
+* Using one `Session` from two threads at once raises `Patron::Error` instead of corrupting memory
+* Response headers and bodies are accumulated directly into Ruby Strings, no more intermediate C buffer and copy
+* Multipart requests use libcurl's `curl_mime` API: field values are binary-safe, names and values are copied,
+  and multipart `PUT`/`PATCH` work too
+* `download_byte_limit` raises `Patron::DownloadLimitExceeded` (a subclass of `Patron::Aborted`)
+* Exceptions raised inside a `progress_callback` propagate out of the request after the transfer is cleaned up;
+  previously they unwound through libcurl's frames. Returning `false` from the callback aborts the request
+* Every `Patron::Error` raised for a transfer carries the libcurl code as `#curl_code`
+* A forked child no longer reuses the parent's libcurl handles and connections
+* Cookies collected with `handle_cookies` (and TLS sessions) are kept across requests on the same
+  `Session`, not only across the redirects of one request
+* `enable_debug` accepts an `IO` as well as a path, writes libcurl's verbose output through Ruby, and
+  never clobbers the process' stderr
+
+**Memory and VM**
+
+* The `Session` TypedData is write-barrier protected and compaction-aware; the request body is pinned
+  only while libcurl reads it; memory size is reported to `ObjectSpace`
+* The extension declares itself Ractor-safe: Patron can be used from non-main Ractors. A `Session`
+  belongs to the Ractor that created it (Ruby refuses to copy, move or share one); `Response` and
+  `Request` objects can be made shareable, and a frozen `Response` still decodes its body. The 0.x
+  compatibility warnings are tracked per Ractor. Covered by specs on Ruby 4.0+
+* Statically held exception classes are registered with the GC (they could dangle under compaction before)
+* The global list of live sessions, the `at_exit` hook and the bundled `sglib.h` are gone
+
+**Ruby API**
+
+* `Patron::Request` keeps its setters (build one, change the URL, send it again) and also takes keyword
+  arguments; any HTTP token is accepted as a verb (#180), verbs libcurl does not know natively are sent as
+  custom requests, and `Marshal` now covers every attribute instead of 22 of 31
+* `Session.new` takes keyword arguments
+* `Response.new` takes keyword arguments (`url:`, `status:`, `redirect_count:`, `header_data:`, `body:`,
+  `default_charset:`, `timings:`); a custom `response_class` must accept the same
+* `default_response_charset` is now honoured as the fallback for `Response#charset`
+* `Response#body` is no longer mutated by `decoded_body`/`inspectable_body`
+* `Patron.libcurl_features` reports the runtime libcurl version, TLS backend and feature flags
+* `Patron::Request::SSL_VERSIONS` and `HTTP_VERSIONS` list the accepted version names; `"HTTPv3"` is accepted
+* `Patron::ProxyType::HTTPS` added
+* `base_url` and the request path are joined as URLs, not with `File.join`
+* The 0.x positional forms of `Response.new`, `Session.new` and `Session#request` still work in 1.0 with a
+  deprecation warning (see `lib/patron/compat.rb` and #209); they go away in 1.1
+
+**Removed**
+
+* `Session#reset` (it was an alias of `interrupt`)
+* `ssl_version` values `"SSLv2"` and `"SSLv3"` (refused by every supported libcurl anyway)
+* Positional arguments to `Response.new`; `Request::READER_VARS`, `WRITER_VARS` and `VALID_ACTIONS` (see `Request::ATTRIBUTES`)
+* Ruby < 3.3, libcurl < 7.81, and the `#if LIBCURL_VERSION_NUM` compatibility branches for libcurl 7.19 through 7.6x
+
+**Build, packaging and tests**
+
+* Require Ruby 3.3 or newer and libcurl 7.81.0 or newer
+* Build with pkg-config when available; `--with-curl-dir` now takes precedence over a `curl-config` found on `PATH`
+* Remove the dead `patron/proxy_type.rb` file; the `Patron::ProxyType` constants were always defined by the extension
+* Stop shipping test fixtures and CI configuration inside the gem
+* Test suite: Puma 6 and Rack 3, JSON request readback, configurable ports (`PATRON_TEST_HTTP_PORT` and friends), `PATRON_GC_STRESS=1` for GC and compaction stress runs
+
+### 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

data/README.md

@@ -1,6 +1,6 @@
 # Patron
 
-[![Build Status](https://travis-ci.org/toland/patron.svg?branch=master)](https://travis-ci.org/toland/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
@@ -22,9 +22,9 @@ sess.headers['User-Agent'] = 'myapp/1.0'
 You can set options with a hash in the constructor:
 
 ```ruby
-sess = Patron::Session.new({ :timeout => 10,
-                             :base_url => 'http://myserver.com:9900',
-                             :headers => {'User-Agent' => 'myapp/1.0'} } )
+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:
@@ -37,10 +37,11 @@ sess = Patron::Session.new do |patron|
 end
 ```
 
-Output debug log:
+Output libcurl's verbose log to a file, to any IO, or to `$stderr` when called without arguments:
 
 ```ruby
 sess.enable_debug "/tmp/patron.debug"
+sess.enable_debug $stdout
 ```
 
 The Session is used to make HTTP requests.
@@ -57,26 +58,60 @@ if resp.status < 400
 end
 ```
 
-The GET, HEAD, PUT, POST and DELETE operations are all supported.
+The GET, HEAD, PUT, PATCH, POST and DELETE operations have their own methods, and any other
+HTTP verb can be sent through `request`:
 
 ```ruby
 sess.put("/foo/baz", "some data")
 sess.delete("/foo/baz")
+sess.request(:propfind, "/foo", {"Depth" => "1"})
 ```
 
+A failed transfer raises a subclass of `Patron::Error` (`Patron::TimeoutError`, `Patron::ConnectionFailed`,
+`Patron::HostResolutionError` and so on). Every such error carries the libcurl error code as `curl_code`.
+
 You can ship custom headers with a single request:
 
 ```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
 
-By itself, the `Patron::Session` objects are not thread safe (each `Session` holds a single `curl_state` pointer
-from initialization to garbage collection). At this time, Patron has no support for `curl_multi_*` family of functions 
-for doing concurrent requests. However, the actual code that interacts with libCURL does unlock the RVM GIL,
-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.
+A `Patron::Session` performs one request at a time and must not be shared between threads: each `Session`
+owns its own libcurl handles and buffers, and using it from two threads at once raises `Patron::Error`.
+Patron releases the GVL (the global VM lock) whenever it waits for the network, so using one `Session`
+per thread gives you real parallelism.
+For sharing a pool of sessions between threads we recommend the excellent [connection_pool](https://rubygems.org/gems/connection_pool) gem by Mike Perham.
 
 ```ruby
 patron_pool = ConnectionPool.new(size: 5, timeout: 5) { Patron::Session.new }
@@ -89,62 +124,90 @@ Sharing Session objects between requests will also allow you to benefit from per
 
 ## Persistent connections
 
-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.
+Every `Session` owns a libcurl multi handle with its own connection cache, plus a share handle for
+cookies, DNS entries and TLS sessions. If you create the Session once and use it for multiple requests
+to the same hostname/port/protocol, the connection gets reused, following libcurl's rules on
+[connection reuse.](https://everything.curl.dev/libcurl/connectionreuse.html)
 
-## Performance with parallel requests
+## Interrupting requests
 
-When performing the libCURL request, Patron goes out of it's way to unlock the GVL (global VM lock) to allow other threads to be scheduled
-in parallel. The GVL is going to be released when the libCURL request starts, and will then be shortly re-acquired to provide the progress
-callback - if the callback has been configured, and then released again until the libCURL request has been performed and the response has
-been read in full. This allows one to execute multiple libCURL requests in parallel, as well as perform other activities on other MRI threads
-that are currently active in the process.
+A request in flight can be aborted from another thread with `Session#interrupt`, after which the
+request raises `Patron::Aborted`. `Thread#kill`, `Thread#raise`, `Timeout.timeout` and signals interrupt
+a request the same way, immediately and in any phase of the transfer, including DNS resolution and
+connecting. A `progress_callback` that returns `false` aborts the request as well, and an exception
+raised inside the callback propagates out of the request once libcurl is done with it.
 
-## Requirements
+## Fibers and the async gem
 
-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.
+When a Fiber scheduler is installed for the current thread (as inside `Async { }`), Patron hands the
+wait for the network to the scheduler instead of blocking the thread, so requests from several fibers
+overlap and other fibers keep running while one waits:
 
-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. 
+```ruby
+Async do |task|
+  pages = urls.map { |url| task.async { Patron::Session.new(timeout: 10).get(url) } }.map(&:wait)
+end
+```
 
-On OSX the provided libcurl is sufficient if you are not using fork+SSL combination (see below).
-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.
+Each fiber needs its own `Session`, just like each thread does. `Async::Task#stop` and
+`Task#with_timeout` interrupt a request in flight the same way `Thread#kill` and `Timeout` do.
 
-## Forking webservers on macOS and SSL
+## Ractors
 
-Currently, [an issue is at play](https://github.com/curl/curl/issues/788) with OSX builds of `curl` which use
-Apple's SecureTransport. Such builds (which Patron is linking to), are causing segfaults when performing HTTPS
-requests in forked subprocesses. If you need to check whether your system is affected,
-run the Patron test suite by performing
+Patron works from non-main Ractors, so Ractors give you parallelism for the Ruby side of your
+requests as well, not just for the waits. A `Session` belongs to the Ractor that created it: Ruby refuses
+to copy, move or share one (`Ractor::Error`), so create the `Session` inside the Ractor and ship
+`Response` objects out. A worker pool looks like this on Ruby 4.0:
 
-    $ bundle install && bundle exec rspec
+```ruby
+results = Ractor::Port.new
+workers = 4.times.map do
+  Ractor.new(results) do |results|
+    session = Patron::Session.new(timeout: 10)
+    while (url = Ractor.receive)
+      results << Ractor.make_shareable(session.get(url))
+    end
+  end
+end
+urls.each_with_index { |url, i| workers[i % workers.size].send(url) }
+responses = urls.size.times.map { results.receive }
+```
+
+`Ractor.make_shareable` on the `Response` is optional: it saves copying the body when the Response crosses
+over, and a shareable (frozen) `Response` still decodes its body. A `Patron::Error` raised inside the
+Ractor comes out of `Ractor#value` as the `cause` of a `Ractor::RemoteError`, `curl_code` and all.
+`Patron::Request` objects can be made shareable and used from any Ractor too.
+
+## How the GVL is handled
+
+Patron drives libcurl through its multi interface. The part of libcurl that moves bytes
+(`curl_multi_perform`) runs with the GVL held, which is what makes it safe to run your progress callback
+and to write straight into Ruby Strings from inside libcurl. Whenever libcurl has nothing to do but wait
+for the network, Patron releases the GVL (`curl_multi_poll`), so other Ruby threads run in parallel with
+the transfer, and that wait is what Ruby interrupts when it needs the thread back.
+
+## Requirements
 
-in the Patron install directory. Most default curl configurations on OSX (both
-the Apple-shipped version and the version available via Homebrew) are linked to
-SecureTransport and are likely to be affected. This issue may also manifest in
-forking webserver implementations (such as Unicorn or Passenger) and in forking
-job execution engines (such as resque), so even though you may not be using
-`fork()` directly your server engine might be doing it for you.
+Patron 1.0 and up requires Ruby 3.3 or newer and libcurl 7.81.0 or newer (Ubuntu 22.04 and up,
+Debian 12 and up, any current macOS). The 0.x versions support older Rubies and stay on the `v0.x` branch.
 
-To circumvent the issue, you need to build `curl` with OpenSSL via homebrew.
-When doing so, `curl` will use openssl as it's SSL driver. You also need to
-change the Patron compile flag:
+You will have to install the libcurl development package on Debian or Ubuntu (`libcurl4-openssl-dev`),
+Alpine (`curl-dev`) and the like. The build looks libcurl up through `pkg-config`, then `curl-config`,
+then the default include and library paths. To build against a specific libcurl, for example
+Homebrew's OpenSSL-backed one instead of the SecureTransport-backed one macOS ships:
 
+    $ gem install patron -- --with-curl-dir=$(brew --prefix curl)
 
-    $ brew install curl-openssl && \
-        gem install patron -- --with-curl-config=/usr/local/opt/curl-openssl/bin/curl-config
+or, for every Bundler-driven install:
 
-You can also save this parameter for all future Bundler-driven gem installs by
-setting this flag in Bundler proper:
+    $ bundle config build.patron --with-curl-dir=$(brew --prefix curl)
 
-    $ bundle config build.patron --with-curl-config=/usr/local/opt/curl-openssl/bin/curl-config
+The SecureTransport backend of the macOS system libcurl cannot load PEM client certificates,
+and [older versions of it crash](https://github.com/curl/curl/issues/788) when doing HTTPS in a forked
+subprocess, so the Homebrew libcurl is the better choice on macOS.
 
 ## Installation
 
-    sudo gem install patron
+    gem install patron
 
 Copyright (c) 2008 The Hive

data/ext/patron/extconf.rb

@@ -1,26 +1,61 @@
-require 'mkmf'
-require 'rbconfig'
-
-dir_config('curl')
-curl_config_path = with_config('curl-config') || find_executable('curl-config')
-if curl_config_path
-  $CFLAGS << " " << `#{curl_config_path} --cflags`.strip
-  $LIBS << " " << `#{curl_config_path} --libs`.strip
-elsif !have_library('curl') or !have_header('curl/curl.h')
-  fail <<-EOM
-  Can't find libcurl or curl/curl.h
-
-  Try passing --with-curl-config, --with-curl-dir, or --with-curl-lib and --with-curl-include
-  options to extconf.
-  EOM
+# frozen_string_literal: true
+
+require "mkmf"
+
+MIN_LIBCURL = "7.81.0"
+MIN_LIBCURL_NUM = 0x075100
+
+# An explicit --with-curl-dir (or -include/-lib) wins over anything on PATH, otherwise
+# the SDK's curl-config on macOS silently overrides the Homebrew one the user asked for
+explicit_dir = dir_config("curl").any?
+unless explicit_dir
+  pkg_config("libcurl") ||
+    begin
+      curl_config = with_config("curl-config") || find_executable("curl-config")
+      if curl_config
+        $CFLAGS << " " << `#{curl_config} --cflags`.strip
+        $LIBS << " " << `#{curl_config} --libs`.strip
+      end
+    end
 end
 
-if CONFIG['CC'] =~ /gcc/
-  $CFLAGS << ' -pedantic -Wall'
+# pkg-config and curl-config put -lcurl in $LIBS already, so only fall back to have_library
+# when linking does not work as-is - otherwise we get -lcurl twice and a linker warning
+linked = have_header("curl/curl.h") &&
+  (have_func("curl_easy_init", "curl/curl.h") || have_library("curl", "curl_easy_init"))
+unless linked
+  abort <<~MSG
+    Can't find libcurl or curl/curl.h.
+
+    Install the libcurl development package (libcurl4-openssl-dev, curl-dev, ...) or pass
+    --with-curl-dir=/path/to/curl (also --with-curl-include / --with-curl-lib,
+    or --with-curl-config=/path/to/curl-config) to extconf.
+  MSG
 end
 
-if CONFIG['CC'] =~ /clang/
-  $CFLAGS << ' -pedantic -Wall -Wno-void-pointer-to-enum-cast'
+found_num = try_constant("LIBCURL_VERSION_NUM", "curl/curlver.h")
+if found_num.nil? || found_num < MIN_LIBCURL_NUM
+  found = found_num ? "%d.%d.%d" % [found_num >> 16, (found_num >> 8) & 0xff, found_num & 0xff] : "an unknown version"
+  abort "Patron needs libcurl #{MIN_LIBCURL} or newer, found #{found}."
 end
 
-create_makefile 'patron/session_ext'
+%w[
+  CURLOPT_PROTOCOLS_STR
+  CURL_HTTP_VERSION_3
+  CURLOPT_CA_CACHE_TIMEOUT
+  CURL_VERSION_THREADSAFE
+  CURLINFO_QUEUE_TIME_T
+  CURLINFO_POSTTRANSFER_TIME_T
+].each { |const| have_const(const, "curl/curl.h") }
+have_func("curl_easy_header", "curl/curl.h")
+
+# Ruby's own warnflags already bring -Wall -Wextra; these two turn the warnings
+# that hide real ABI mistakes into errors
+append_cflags(%w[-Werror=implicit-function-declaration -Werror=incompatible-pointer-types])
+append_cflags("-Werror") if enable_config("werror")
+
+# For sanitizer builds in CI: plain CFLAGS gets clobbered by RbConfig, so use our own names
+$CFLAGS << " " << ENV["PATRON_CFLAGS"] if ENV["PATRON_CFLAGS"]
+$LDFLAGS << " " << ENV["PATRON_LDFLAGS"] if ENV["PATRON_LDFLAGS"]
+
+create_makefile "patron/session_ext"