wreq 1.2.11 → 1.2.13

data/docs/fork-safety.md

@@ -0,0 +1,51 @@
+# Fork safety
+
+## Prefork checklist
+
+- `require "wreq"` may run in the parent before workers fork.
+- Create each `Wreq::Client`, `Wreq::Jar`, and `Wreq::BodySender` in the worker
+  that will use it.
+- Keep each `Wreq::Response` in the process that received it.
+- Do not start requests or push streaming body data in the parent before workers
+  fork.
+- If the parent must use wreq-ruby first, start workers with `spawn` or `exec`
+  instead of `fork`.
+
+wreq-ruby checks process ownership whenever it exposes guarded native state. It
+does not copy, reset, or rebuild inherited objects.
+
+## Loading before fork
+
+wreq-ruby creates its process-wide Tokio runtime on the first operation that
+needs it. Requiring the gem does not initialize the runtime, so a prefork server
+may load wreq-ruby during boot. Each worker can then create its own runtime on
+its first request without an `after_fork!` hook.
+
+Create clients and other native-backed objects inside the worker. Each client,
+response, body sender, and cookie jar belongs to the process that created it.
+Using an inherited object raises `Wreq::ForkError`, even when the parent never
+started the runtime. wreq-ruby does not rebuild these objects.
+
+## Forking after runtime initialization
+
+Once the parent starts an HTTP operation or otherwise uses the Tokio runtime, a
+forked child must not reuse it. Tokio's worker threads do not survive `fork`, and
+the inherited connection pool may refer to those missing threads.
+
+Operations that need the inherited runtime raise `Wreq::ForkError`. This
+includes requests through new or existing clients, module request methods, and
+streaming request writes. Constructing a new client, body sender, or cookie jar
+does not use the runtime, but runtime-backed operations remain unavailable in
+that child. Retrying them raises the same error.
+
+An inherited `Wreq::Response` cannot be used at all. This includes status,
+headers, socket addresses, TLS information, and body methods. Values copied out
+before the fork, such as a `Wreq::StatusCode` or `Wreq::TlsInfo`, are separate
+objects and do not retain access to the response.
+
+The parent remains usable. Native objects collected in the child do not destroy
+state owned by the parent process.
+
+Use a spawn- or exec-based worker when the parent must perform HTTP work before
+workers start. Requiring the extension again cannot replace an inherited
+runtime.

data/docs/interrupt-handling.md

@@ -0,0 +1,134 @@
+# Interrupt handling policy
+
+wreq-ruby must not construct or raise Ruby's built-in `Interrupt` to report a
+request cancellation. This rule applies to the Rust extension and to Ruby
+wrappers in this repository. A pull request that turns a wreq-owned
+cancellation into the built-in class must not be merged.
+
+Represent native cancellation as a Rust value until the Ruby-owned calling
+thread has reacquired the GVL. Then map a wreq-owned request cancellation to
+`Wreq::InterruptError`:
+
+```ruby
+Wreq::InterruptError < Interrupt
+```
+
+Keep this class outside `StandardError`. A broad transport rescue such as
+`rescue StandardError` must not swallow an interruption.
+
+## Why `Interrupt` is reserved
+
+Ruby documents `Interrupt` as the exception raised for an interrupt signal,
+usually when the user presses Control-C. Its hierarchy is:
+
+```text
+Exception
+└── SignalException
+    └── Interrupt
+```
+
+`Interrupt` is not a `StandardError`. Ruby's default `rescue` catches
+`StandardError`, so it does not catch `Interrupt` or `Wreq::InterruptError`.
+Code that explicitly uses `rescue Interrupt` catches both because
+`Wreq::InterruptError` is a subclass.
+
+The exact built-in class therefore carries Ruby-level control-flow meaning. If
+wreq creates that class for its own cancellation, callers cannot tell whether
+Ruby delivered an interrupt or the HTTP library cancelled a request. A
+library-specific subclass preserves that distinction while keeping the
+interruption outside ordinary transport errors.
+
+## Required behavior
+
+| Event | wreq-ruby behavior |
+| --- | --- |
+| Ruby raises its built-in `Interrupt`, including an exception supplied through `Thread#raise` | Propagate the original exception. Do not replace or wrap it. |
+| `Thread#kill`, `Thread#terminate`, or `Thread#exit` stops a thread | Let Ruby perform the fatal thread termination. The native unblock callback may request cancellation, but wreq must not translate the event into `Interrupt`. |
+| wreq's native cancellation path finishes without a pending Ruby exception | Raise `Wreq::InterruptError`. |
+| A connection, timeout, protocol, or other transport operation fails | Raise the matching wreq transport error under `StandardError`. |
+
+Ruby's implementation also makes an important distinction here.
+`Thread#raise` queues the exception chosen by the caller. `Thread#kill` queues
+Ruby's internal fatal thread-kill event instead of an `Interrupt` object, and
+its termination is asynchronous. Once a no-GVL callback returns, Ruby handles
+that fatal event after reacquiring the GVL and before the native call can return
+normally to wreq's error mapper.
+
+## Native no-GVL boundary
+
+There are two separate rules at this boundary:
+
+1. A Tokio worker, other Rust background thread, no-GVL callback, or UBF must
+   not construct or raise any Ruby exception.
+2. Rust code running on the Ruby-owned calling thread with the GVL may construct
+   Ruby exceptions, but it must not turn a wreq-owned cancellation into Ruby's
+   built-in `Interrupt`.
+
+Requests run through `rb_thread_call_without_gvl`. Ruby's C API documents this
+sequence:
+
+1. Handle pending interrupts.
+2. Release the GVL.
+3. Run the native callback.
+4. Reacquire the GVL.
+5. Handle interrupts received while the callback was running.
+
+Ruby may call the unblock function, or UBF, when another thread interacts with
+the blocked thread. The UBF is a request to stop the native operation. It does
+not identify which Ruby exception, if any, is pending.
+
+The UBF in [`src/gvl.rs`](../src/gvl.rs) must only signal cancellation. It must
+not call Ruby APIs or raise an exception while the GVL is released. The request
+future returns its result as a Rust value. Only after the no-GVL call returns
+to the Ruby-owned thread with the GVL may [`src/rt.rs`](../src/rt.rs) map a
+wreq-owned cancellation to the `Wreq::InterruptError` defined in
+[`src/error.rs`](../src/error.rs).
+
+Keep cancellation conversion centralized in `rt::block_on`. Request, response,
+and body operations may call `block_on`, but they must not construct their own
+Ruby cancellation exception. `block_on` returns a future's native error
+unchanged so the caller can convert it after the GVL has been reacquired.
+
+These forms are forbidden for wreq-owned cancellation:
+
+```rust
+MagnusError::new(ruby.exception_interrupt(), "request interrupted")
+```
+
+```ruby
+raise Interrupt, "request interrupted"
+```
+
+Using `exception_interrupt` as the parent when defining
+`Wreq::InterruptError` is still required. Using it as the class passed to
+`MagnusError::new` is not.
+
+## Review checklist
+
+- Reject direct construction or raising of Ruby's built-in `Interrupt` for a
+  wreq-owned cancellation.
+- Keep `Wreq::InterruptError` as a direct subclass of `Interrupt`.
+- Keep Ruby API calls and exception construction out of the no-GVL callback
+  and UBF.
+- Preserve an exception supplied by Ruby through `Thread#raise`.
+- Do not turn `Thread#kill`, `Thread#terminate`, or `Thread#exit` into a new
+  exception.
+- Test the real cancellation path, the exception hierarchy, and the
+  `StandardError` boundary when changing this code.
+
+## Ruby references
+
+- [Ruby `Interrupt`](https://docs.ruby-lang.org/en/3.4/Interrupt.html) explains
+  that the class represents an interrupt signal, usually Control-C, and
+  inherits from `SignalException`.
+- [Ruby's built-in exception hierarchy](https://docs.ruby-lang.org/en/4.0/Exception.html#class-Exception-label-Built-In+Exception+Class+Hierarchy)
+  shows that `SignalException` and `StandardError` are separate branches.
+- [`Thread#raise`](https://docs.ruby-lang.org/en/4.0/Thread.html#method-i-raise)
+  raises the caller-supplied exception in another thread.
+- [`Thread#kill`](https://docs.ruby-lang.org/en/4.0/Thread.html#method-i-kill)
+  documents asynchronous termination and its `terminate` and `exit` aliases.
+- [`rb_thread_call_without_gvl`](https://docs.ruby-lang.org/capi/en/master/d6/dfb/include_2ruby_2thread_8h.html)
+  documents interrupt checks, GVL reacquisition, UBF cancellation, and the
+  restriction on Ruby API calls from no-GVL callbacks.
+- [Issue #111](https://github.com/SearchApi/wreq-ruby/issues/111) contains the
+  original error-hierarchy discussion.

data/examples/tls_info.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "openssl"
+require_relative "../lib/wreq"
+
+url = ARGV.fetch(0, "https://example.com")
+client = Wreq::Client.new(tls_info: true)
+response = client.get(url)
+tls_info = response.tls_info
+response.close
+
+abort "TLS information is unavailable for #{url}" unless tls_info
+
+p tls_info
+
+if (der = tls_info.peer_certificate)
+  certificate = OpenSSL::X509::Certificate.new(der)
+  puts "Subject: #{certificate.subject}"
+  puts "Issuer: #{certificate.issuer}"
+  puts "Valid from: #{certificate.not_before}"
+  puts "Valid until: #{certificate.not_after}"
+end
+
+chain = tls_info.peer_certificate_chain
+chain_size = chain ? chain.length : "unavailable"
+puts "Certificate chain: #{chain_size}"

data/lib/wreq.rb

@@ -12,12 +12,40 @@ require_relative "wreq_ruby/http"
 require_relative "wreq_ruby/emulate"
 require_relative "wreq_ruby/client"
 require_relative "wreq_ruby/response"
+require_relative "wreq_ruby/tls"
 require_relative "wreq_ruby/body"
 require_relative "wreq_ruby/header"
 require_relative "wreq_ruby/error"
 require_relative "wreq_ruby/cookie"
 
 unless defined?(Wreq)
+  # An HTTP client backed by a lazily initialized, process-wide Tokio runtime.
+  #
+  # Loading wreq-ruby before `fork` is supported. The parent must not send a
+  # request or perform another operation that starts the runtime before workers
+  # are forked. Create clients and begin HTTP work inside each worker so it gets
+  # its own runtime and connection pool. Clients, responses, body senders, and
+  # cookie jars belong to the process that created them and must be recreated
+  # in the worker. wreq-ruby does not rebuild inherited objects.
+  #
+  # Accessing an inherited native-backed object raises Wreq::ForkError even if
+  # the parent did not start the runtime. If the parent did start it, the child
+  # also cannot perform new runtime-backed operations. Retrying does not replace
+  # either kind of inherited state. Use `spawn` or `exec`, or move the parent's
+  # HTTP work until after the workers have been forked.
+  #
+  # @example Preload the extension, then start HTTP work in the worker
+  #   require "wreq"
+  #
+  #   Process.fork do
+  #     client = Wreq::Client.new
+  #     response = client.get("https://example.com")
+  #     puts response.status
+  #   end
+  #
+  # @note Fork safety Create clients, cookie jars, and body senders inside the
+  #   worker that uses them. Do not carry responses across `fork`.
+  # @see https://github.com/SearchApi/wreq-ruby/blob/main/docs/fork-safety.md
   module Wreq
     # Current wreq gem version.
     # @return [String]
@@ -60,6 +88,7 @@ unless defined?(Wreq)
     # @return [Wreq::Response] HTTP response
     # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
     #   value cannot be converted, validated, or built
+    # @raise [Wreq::ForkError] if the child inherited an initialized wreq-ruby runtime
     def self.request(method, url, **options)
     end
 
@@ -93,6 +122,7 @@ unless defined?(Wreq)
     # @return [Wreq::Response] HTTP response
     # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
     #   value cannot be converted, validated, or built
+    # @raise [Wreq::ForkError] if the child inherited an initialized wreq-ruby runtime
     def self.get(url, **options)
     end
 
@@ -126,6 +156,7 @@ unless defined?(Wreq)
     # @return [Wreq::Response] HTTP response
     # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
     #   value cannot be converted, validated, or built
+    # @raise [Wreq::ForkError] if the child inherited an initialized wreq-ruby runtime
     def self.head(url, **options)
     end
 
@@ -159,6 +190,7 @@ unless defined?(Wreq)
     # @return [Wreq::Response] HTTP response
     # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
     #   value cannot be converted, validated, or built
+    # @raise [Wreq::ForkError] if the child inherited an initialized wreq-ruby runtime
     def self.post(url, **options)
     end
 
@@ -192,6 +224,7 @@ unless defined?(Wreq)
     # @return [Wreq::Response] HTTP response
     # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
     #   value cannot be converted, validated, or built
+    # @raise [Wreq::ForkError] if the child inherited an initialized wreq-ruby runtime
     def self.put(url, **options)
     end
 
@@ -225,6 +258,7 @@ unless defined?(Wreq)
     # @return [Wreq::Response] HTTP response
     # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
     #   value cannot be converted, validated, or built
+    # @raise [Wreq::ForkError] if the child inherited an initialized wreq-ruby runtime
     def self.delete(url, **options)
     end
 
@@ -258,6 +292,7 @@ unless defined?(Wreq)
     # @return [Wreq::Response] HTTP response
     # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
     #   value cannot be converted, validated, or built
+    # @raise [Wreq::ForkError] if the child inherited an initialized wreq-ruby runtime
     def self.options(url, **options)
     end
 
@@ -291,6 +326,7 @@ unless defined?(Wreq)
     # @return [Wreq::Response] HTTP response
     # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
     #   value cannot be converted, validated, or built
+    # @raise [Wreq::ForkError] if the child inherited an initialized wreq-ruby runtime
     def self.trace(url, **options)
     end
 
@@ -324,6 +360,7 @@ unless defined?(Wreq)
     # @return [Wreq::Response] HTTP response
     # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
     #   value cannot be converted, validated, or built
+    # @raise [Wreq::ForkError] if the child inherited an initialized wreq-ruby runtime
     def self.patch(url, **options)
     end
   end

data/lib/wreq_ruby/body.rb

@@ -17,6 +17,12 @@ unless defined?(Wreq)
     #
     # A sender can be attached to one request. Closing it prevents further writes but
     # retains queued chunks so a request attached afterward can still drain them.
+    # Creating a sender does not initialize Tokio. An inherited sender raises
+    # Wreq::ForkError before its channel is accessed. A new sender can be
+    # created in a child, but pushing data also requires a usable runtime.
+    #
+    # @note Fork safety Create each sender in the worker that writes to it.
+    #   Do not pass a sender through `fork`.
     class BodySender
       # Create a bounded request-body sender.
       #
@@ -33,6 +39,7 @@ unless defined?(Wreq)
       # @param data [String] binary chunk
       # @return [nil]
       # @raise [IOError] if the sender or receiving side is closed
+      # @raise [Wreq::ForkError] if the sender or runtime belongs to the parent process
       def push(data)
       end
 
@@ -41,6 +48,7 @@ unless defined?(Wreq)
       # This operation is idempotent.
       #
       # @return [nil]
+      # @raise [Wreq::ForkError] if the sender belongs to the parent process
       def close
       end
 
@@ -50,6 +58,7 @@ unless defined?(Wreq)
       # the receiving side.
       #
       # @return [Boolean]
+      # @raise [Wreq::ForkError] if the sender belongs to the parent process
       def closed?
       end
     end

data/lib/wreq_ruby/client.rb

@@ -17,6 +17,15 @@ unless defined?(Wreq)
     # native conversion, such as TypeError or Wreq::BuilderError. Request
     # validation finishes before network I/O.
     #
+    # A client belongs to the process that created it. An inherited client
+    # raises Wreq::ForkError before its connection pool is accessed. Loading
+    # the gem before fork is supported, but clients must be created inside the
+    # worker. If the parent already started the runtime, new clients can be
+    # constructed in the child but cannot send requests.
+    #
+    # @note Fork safety Create each client in the worker that uses it. An
+    #   inherited client is never rebuilt automatically.
+    #
     # @example Basic usage
     #   client = Wreq::Client.new
     #   # Use client for HTTP requests
@@ -130,6 +139,11 @@ unless defined?(Wreq)
       #   including self-signed or expired ones. Should only be disabled
       #   for testing purposes.
       #
+      # @param tls_info [Boolean, nil] Retain peer certificate data for HTTPS
+      #   responses. When true, {Wreq::Response#tls_info} may return a
+      #   {Wreq::TlsInfo} object. Disabled by default because retaining
+      #   certificate data uses additional memory.
+      #
       # @param no_proxy [Boolean, nil] Disable use of any configured proxy
       #   for this client, even if proxy settings are detected from the
       #   environment.
@@ -165,7 +179,7 @@ unless defined?(Wreq)
       #   value cannot be converted or validated.
       # @raise [Wreq::BuilderError, Wreq::TlsError] if the native client cannot
       #   be initialized.
-      #
+      # @raise [Wreq::ForkError] if :cookie_provider belongs to a parent process.
       # @example Minimal client
       #   client = Wreq::Client.new
       #
@@ -280,6 +294,7 @@ unless defined?(Wreq)
       #   or unavailable on the current platform
       # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
       #   value cannot be converted, validated, or built
+      # @raise [Wreq::ForkError] if the client or runtime belongs to the parent process
       def request(method, url, **options)
       end
 
@@ -313,6 +328,7 @@ unless defined?(Wreq)
       # @return [Wreq::Response] HTTP response
       # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
       #   value cannot be converted, validated, or built
+      # @raise [Wreq::ForkError] if the client or runtime belongs to the parent process
       def get(url, **options)
       end
 
@@ -346,6 +362,7 @@ unless defined?(Wreq)
       # @return [Wreq::Response] HTTP response
       # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
       #   value cannot be converted, validated, or built
+      # @raise [Wreq::ForkError] if the client or runtime belongs to the parent process
       def head(url, **options)
       end
 
@@ -379,6 +396,7 @@ unless defined?(Wreq)
       # @return [Wreq::Response] HTTP response
       # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
       #   value cannot be converted, validated, or built
+      # @raise [Wreq::ForkError] if the client or runtime belongs to the parent process
       def post(url, **options)
       end
 
@@ -412,6 +430,7 @@ unless defined?(Wreq)
       # @return [Wreq::Response] HTTP response
       # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
       #   value cannot be converted, validated, or built
+      # @raise [Wreq::ForkError] if the client or runtime belongs to the parent process
       def put(url, **options)
       end
 
@@ -445,6 +464,7 @@ unless defined?(Wreq)
       # @return [Wreq::Response] HTTP response
       # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
       #   value cannot be converted, validated, or built
+      # @raise [Wreq::ForkError] if the client or runtime belongs to the parent process
       def delete(url, **options)
       end
 
@@ -478,6 +498,7 @@ unless defined?(Wreq)
       # @return [Wreq::Response] HTTP response
       # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
       #   value cannot be converted, validated, or built
+      # @raise [Wreq::ForkError] if the client or runtime belongs to the parent process
       def options(url, **options)
       end
 
@@ -511,6 +532,7 @@ unless defined?(Wreq)
       # @return [Wreq::Response] HTTP response
       # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
       #   value cannot be converted, validated, or built
+      # @raise [Wreq::ForkError] if the client or runtime belongs to the parent process
       def trace(url, **options)
       end
 
@@ -544,6 +566,7 @@ unless defined?(Wreq)
       # @return [Wreq::Response] HTTP response
       # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
       #   value cannot be converted, validated, or built
+      # @raise [Wreq::ForkError] if the client or runtime belongs to the parent process
       def patch(url, **options)
       end
     end

data/lib/wreq_ruby/cookie.rb

@@ -158,6 +158,11 @@ unless defined?(Wreq)
     # Stores cookies for reuse across requests.
     #
     # Pass a Jar to Wreq::Client as `cookie_provider` to share its cookies.
+    # A jar belongs to the process that created it and cannot be inherited
+    # across `fork`.
+    #
+    # @note Fork safety Create a new jar in each worker. wreq-ruby does not
+    #   copy cookies from an inherited jar.
     class Jar
       # Creates an empty cookie jar.
       # @return [Wreq::Jar]
@@ -166,6 +171,7 @@ unless defined?(Wreq)
 
       # Returns all stored cookies.
       # @return [Array<Wreq::Cookie>]
+      # @raise [Wreq::ForkError] if the jar belongs to the parent process
       def get_all
       end
 
@@ -174,6 +180,7 @@ unless defined?(Wreq)
       # @param url [String] URL that scopes the cookie
       # @return [void]
       # @raise [TypeError] if cookie is neither a String nor Wreq::Cookie
+      # @raise [Wreq::ForkError] if the jar belongs to the parent process
       def add(cookie, url)
       end
 
@@ -181,11 +188,13 @@ unless defined?(Wreq)
       # @param name [String]
       # @param url [String]
       # @return [void]
+      # @raise [Wreq::ForkError] if the jar belongs to the parent process
       def remove(name, url)
       end
 
       # Clear all cookies from the jar.
       # @return [void]
+      # @raise [Wreq::ForkError] if the jar belongs to the parent process
       def clear
       end
     end

data/lib/wreq_ruby/error.rb

@@ -11,6 +11,21 @@ unless defined?(Wreq)
     # Memory allocation failed.
     class MemoryError < StandardError; end
 
+    # The child process tried to use native state created by its parent.
+    #
+    # Tokio worker threads do not survive fork. Inherited connection pools,
+    # locks, channels, and response state are also unsafe to use. wreq-ruby
+    # raises this error before exposing them. Loading the gem before fork is
+    # supported, but native-backed objects must be created in each worker.
+    #
+    # @example
+    #   client = Wreq::Client.new
+    #   Process.fork do
+    #     client.get("https://example.com") # Raises in the child.
+    #   end
+    # @see https://github.com/SearchApi/wreq-ruby/blob/main/docs/fork-safety.md
+    class ForkError < RuntimeError; end
+
     # Network connection errors
 
     # Connection to the server failed.