wreq 1.2.11-aarch64-linux → 1.2.12-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8141b1cfd59a1268c9532940b86a4ae41edfde917bd568fed589e6f4baee785d
-  data.tar.gz: dad9f6d56c1437927c96b5f13f0e0bf30e2dda5a5d912deaf58bb1c194f688ae
+  metadata.gz: 77c664031054cda90dc0a51bb1eb1489bd140ece7acf2016be6d316faca11798
+  data.tar.gz: 41669054ee2c4d3abd8ec8fbcc162a8b10d94261b8db26ca0d43352891a60fda
 SHA512:
-  metadata.gz: f5b842f60b928099b18bcc57be0a2ca847dbb9b4567ee1634fcaa888e0a87e98c52c7e9e01d54101ef20897abc80ed8e22a14e01d4e8ad5101059a6f7425073e
-  data.tar.gz: 7c9f7da692dbd6cae90720b436b9918d7bb48f924aa8791c7bdf00e5751364e8f2b7393fcc3f168af468aa1d7e674e03bb6dc6fb0914c87c6fff5e994559bdfd
+  metadata.gz: 9c1a1bed05c48b912a4221c16bcf095bf4ed21e064d00a8add61c67fa23376f5217cefb3c47b7546810f85082d8e60e60293aa6b115c29a4e0c1adcc15b03b70
+  data.tar.gz: 80deb6d3d1e748165bf0277aa92b568ac55dc02d8355ef25dd6c793a8610c6c298dc98c8e241628f240126cb8aa2a7360c3ebbbb0a79013e4241024a550eb9ee

data/docs/fork-safety.md

@@ -0,0 +1,34 @@
+# Fork safety
+
+## Why inherited clients are rejected
+
+wreq-ruby uses a process-wide Tokio runtime and connection pool. `fork` copies
+the parent's memory, but only the thread that called `fork` continues in the
+child. Tokio's worker threads are gone, and its inherited tasks, locks, and
+connections are not safe to reuse.
+
+If the parent has already loaded wreq-ruby, native HTTP operations in the child
+raise `Wreq::ForkError`. This applies to new and existing clients, module
+request methods, streaming request bodies, and response methods backed by native
+state. Retrying the operation in the same child raises the same error. Read-only
+response metadata such as status, headers, and captured TLS information remains
+available.
+
+The parent can continue using its clients. When inherited Ruby objects are
+collected in the child, their native runtime state is left for the operating
+system to reclaim when the process exits.
+
+## HTTP work in forked children is unsupported
+
+A process created with `fork` must not start or continue HTTP work through
+wreq-ruby, even when it first loads the extension after the fork. If the parent
+loaded wreq-ruby, native HTTP operations in the child raise `Wreq::ForkError`.
+
+When the extension was not present in the parent, no wreq-ruby state or fork
+marker reaches the child. The extension cannot reliably distinguish that child
+from a newly started process, so this unsupported path cannot guarantee a Ruby
+error and may fail inside platform libraries.
+
+Prefork servers should use an `exec`- or spawn-based worker model when workers
+need wreq-ruby. Requiring the extension again does not reset inherited runtime
+state, and there is no `after_fork!` hook.

data/docs/interrupt-handling.md

@@ -0,0 +1,133 @@
+# 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 this conversion centralized in `rt::try_block_on`. Request, response, and
+body operations may call `try_block_on`, but they must not construct their own
+Ruby cancellation exception.
+
+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,6 +12,7 @@ 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"
@@ -28,6 +29,9 @@ unless defined?(Wreq)
     # raise ArgumentError. Known values retain the error class from their Ruby
     # or native conversion, such as TypeError or Wreq::BuilderError. Validation
     # finishes before network I/O.
+    #
+    # If a child process inherits wreq-ruby from its parent, requests raise
+    # Wreq::ForkError. Require wreq after the worker has been forked.
 
     # Send an HTTP request.
     #
@@ -60,6 +64,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 wreq-ruby from its parent
     def self.request(method, url, **options)
     end
 
@@ -93,6 +98,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 wreq-ruby from its parent
     def self.get(url, **options)
     end
 
@@ -126,6 +132,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 wreq-ruby from its parent
     def self.head(url, **options)
     end
 
@@ -159,6 +166,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 wreq-ruby from its parent
     def self.post(url, **options)
     end
 
@@ -192,6 +200,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 wreq-ruby from its parent
     def self.put(url, **options)
     end
 
@@ -225,6 +234,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 wreq-ruby from its parent
     def self.delete(url, **options)
     end
 
@@ -258,6 +268,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 wreq-ruby from its parent
     def self.options(url, **options)
     end
 
@@ -291,6 +302,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 wreq-ruby from its parent
     def self.trace(url, **options)
     end
 
@@ -324,6 +336,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 wreq-ruby from its parent
     def self.patch(url, **options)
     end
   end

data/lib/wreq_ruby/body.rb

@@ -17,6 +17,8 @@ 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 or using a sender raises Wreq::ForkError if the child inherited
+    # wreq-ruby from its parent.
     class BodySender
       # Create a bounded request-body sender.
       #
@@ -25,6 +27,7 @@ unless defined?(Wreq)
       # @return [Wreq::BodySender] A streaming request body sender
       # @raise [ArgumentError] if capacity is zero, negative, or too large
       # @raise [TypeError] if capacity is not an Integer
+      # @raise [Wreq::ForkError] if the child inherited wreq-ruby from its parent
       def self.new(capacity = 8)
       end
 
@@ -33,6 +36,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 child inherited wreq-ruby from its parent
       def push(data)
       end
 
@@ -41,6 +45,7 @@ unless defined?(Wreq)
       # This operation is idempotent.
       #
       # @return [nil]
+      # @raise [Wreq::ForkError] if the child inherited wreq-ruby from its parent
       def close
       end
 
@@ -50,6 +55,7 @@ unless defined?(Wreq)
       # the receiving side.
       #
       # @return [Boolean]
+      # @raise [Wreq::ForkError] if the child inherited wreq-ruby from its parent
       def closed?
       end
     end

data/lib/wreq_ruby/client.rb

@@ -17,6 +17,10 @@ unless defined?(Wreq)
     # native conversion, such as TypeError or Wreq::BuilderError. Request
     # validation finishes before network I/O.
     #
+    # A child process cannot create or use a client if it inherited wreq-ruby
+    # from its parent. These calls raise Wreq::ForkError before accessing the
+    # native runtime. Require wreq after the worker has been forked.
+    #
     # @example Basic usage
     #   client = Wreq::Client.new
     #   # Use client for HTTP requests
@@ -130,6 +134,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,6 +174,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 the child inherited wreq-ruby from its parent
       #
       # @example Minimal client
       #   client = Wreq::Client.new
@@ -280,6 +290,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 child inherited wreq-ruby from its parent
       def request(method, url, **options)
       end
 
@@ -313,6 +324,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 wreq-ruby from its parent
       def get(url, **options)
       end
 
@@ -346,6 +358,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 wreq-ruby from its parent
       def head(url, **options)
       end
 
@@ -379,6 +392,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 wreq-ruby from its parent
       def post(url, **options)
       end
 
@@ -412,6 +426,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 wreq-ruby from its parent
       def put(url, **options)
       end
 
@@ -445,6 +460,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 wreq-ruby from its parent
       def delete(url, **options)
       end
 
@@ -478,6 +494,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 wreq-ruby from its parent
       def options(url, **options)
       end
 
@@ -511,6 +528,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 wreq-ruby from its parent
       def trace(url, **options)
       end
 
@@ -544,6 +562,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 wreq-ruby from its parent
       def patch(url, **options)
       end
     end

data/lib/wreq_ruby/error.rb

@@ -11,6 +11,19 @@ unless defined?(Wreq)
     # Memory allocation failed.
     class MemoryError < StandardError; end
 
+    # The child process inherited wreq-ruby from its parent.
+    #
+    # Tokio worker threads do not survive fork, and inherited pooled
+    # connections are not safe to reuse. This error is raised before a child
+    # can access that state.
+    #
+    # @example
+    #   Process.fork do
+    #     Wreq::Client.new # Raises if the parent loaded wreq-ruby.
+    #   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.

data/lib/wreq_ruby/response.rb

@@ -8,6 +8,9 @@ unless defined?(Wreq)
     # access to HTTP response data including status codes, headers, body
     # content, and streaming capabilities.
     #
+    # Body methods raise Wreq::ForkError if the child inherited wreq-ruby from
+    # its parent.
+    #
     # @example Basic response handling
     #   response = client.get("https://api.example.com")
     #   puts response.status.as_int  # => 200
@@ -107,6 +110,7 @@ unless defined?(Wreq)
 
       # Get the response bytes as a binary string.
       # @return [String] Response body as binary data
+      # @raise [Wreq::ForkError] if the child inherited wreq-ruby from its parent
       # @example
       #   binary_data = response.bytes
       #   puts binary_data.size  # => 1024
@@ -122,6 +126,7 @@ unless defined?(Wreq)
       #   html = response.text("ISO-8859-1")
       #   puts html
       # @raise [Wreq::DecodingError] if body cannot be decoded with the specified encoding
+      # @raise [Wreq::ForkError] if the child inherited wreq-ruby from its parent
       def text(default_encoding = "UTF-8")
       end
 
@@ -132,6 +137,7 @@ unless defined?(Wreq)
       #
       # @return [Object] Parsed JSON (Hash, Array, String, Integer, Float, Boolean, nil)
       # @raise [Wreq::DecodingError] if body is not valid JSON
+      # @raise [Wreq::ForkError] if the child inherited wreq-ruby from its parent
       # @example
       #   data = response.json
       #   puts data["key"]
@@ -149,6 +155,7 @@ unless defined?(Wreq)
       # @raise [LocalJumpError] if called without a block
       # @raise [Wreq::TimeoutError, Wreq::BodyError, Wreq::ConnectionResetError, Wreq::RequestError]
       #   if streaming fails while reading the response body
+      # @raise [Wreq::ForkError] if the child inherited wreq-ruby from its parent
       # @example Save response to file
       #   File.open("output.bin", "wb") do |f|
       #     response.chunks { |chunk| f.write(chunk) }
@@ -165,10 +172,31 @@ unless defined?(Wreq)
       # Close the response and free associated resources.
       #
       # @return [void]
+      # @raise [Wreq::ForkError] if the child inherited wreq-ruby from its parent
       # @example
       #   response.close
       def close
       end
+
+      # Return TLS information captured for this response.
+      #
+      # Returns +nil+ when +tls_info: true+ was not enabled, the response used
+      # plain HTTP, or the transport supplied no TLS information. Reading or
+      # closing the response body does not discard captured TLS data.
+      #
+      # @return [Wreq::TlsInfo, nil] TLS information for this response, or +nil+
+      #   when unavailable
+      # @example
+      #   client = Wreq::Client.new(tls_info: true)
+      #   response = client.get("https://example.com")
+      #   tls = response.tls_info
+      #
+      #   if tls
+      #     tls.peer_certificate       # => DER-encoded binary String
+      #     tls.peer_certificate_chain # => frozen Array of DER binary Strings
+      #   end
+      def tls_info
+      end
     end
   end
 end

data/lib/wreq_ruby/tls.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+unless defined?(Wreq)
+  module Wreq
+    # Peer certificate data captured for one HTTPS response.
+    #
+    # Instances are returned by {Wreq::Response#tls_info}. Certificate bytes
+    # remain available after the response body is read or closed, even if the
+    # connection is later reused.
+    #
+    # The returned certificate Strings are Ruby-owned copies. Changing one does
+    # not alter the stored TLS data or values returned by later calls. The chain
+    # Array is frozen, but its String elements remain mutable.
+    #
+    # Certificates use the DER encoding described by the X.509 profile in
+    # RFC 5280.
+    #
+    # @example Parse the peer certificate with OpenSSL
+    #   require "openssl"
+    #
+    #   client = Wreq::Client.new(tls_info: true)
+    #   response = client.get("https://example.com")
+    #   der = response.tls_info&.peer_certificate
+    #
+    #   if der
+    #     certificate = OpenSSL::X509::Certificate.new(der)
+    #     puts certificate.subject
+    #   end
+    # @see https://www.rfc-editor.org/rfc/rfc5280#section-4.1 X.509 certificate format
+    class TlsInfo
+      # Return the peer's leaf certificate.
+      #
+      # @return [String, nil] a new DER-encoded String with
+      #   +Encoding::BINARY+, or +nil+ when the transport did not provide one
+      def peer_certificate
+      end
+
+      # Return the peer certificate chain.
+      #
+      # The Array is frozen. Each element is a new DER-encoded binary String.
+      # The chain includes the leaf certificate when the transport supplies it.
+      #
+      # @return [Array<String>, nil] a frozen Array of certificate copies, or
+      #   +nil+ when the transport did not provide a chain
+      def peer_certificate_chain
+      end
+    end
+  end
+end
+
+# ======================== Ruby API Extensions ========================
+
+module Wreq
+  class TlsInfo
+    # Return a compact summary for debugging.
+    #
+    # The summary reports the leaf certificate size and the number of
+    # certificates in the chain without printing the DER data.
+    #
+    # @return [String] TLS certificate metadata
+    # @example
+    #   tls_info.inspect
+    #   # => "#<Wreq::TlsInfo peer_certificate=781B peer_certificate_chain=1>"
+    def inspect
+      certificate = peer_certificate
+      chain = peer_certificate_chain
+      certificate_size = certificate ? "#{certificate.bytesize}B" : "nil"
+      chain_size = chain ? chain.length : "nil"
+
+      "#<#{self.class} peer_certificate=#{certificate_size} peer_certificate_chain=#{chain_size}>"
+    end
+  end
+end

data/test/fork_test.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "rbconfig"
+require "tempfile"
+require "timeout"
+
+class ForkTest < Minitest::Test
+  FORK_ERROR_LABELS = %w[
+    before_runtime
+    invalid_client
+    invalid_request
+    fresh_body_sender
+    inherited_body_sender_push
+    inherited_body_sender_close
+    inherited_body_sender_closed
+    fresh_client
+    inherited_client
+    inherited_response
+    inherited_response_text
+    inherited_response_chunks
+    inherited_response_close
+  ].freeze
+
+  def test_fork_error_is_a_runtime_error
+    assert_operator Wreq::ForkError, :<, RuntimeError
+  end
+
+  def test_loaded_extension_is_rejected_after_fork
+    skip "fork is not supported on this platform" unless Process.respond_to?(:fork)
+
+    stdout, stderr, status = run_fork_script("fork_safety.rb")
+
+    assert status.success?, "subprocess failed with #{status.inspect}: #{stderr}"
+    assert_equal "ok\n", stdout
+    FORK_ERROR_LABELS.each do |label|
+      assert_match(/#{label}=Wreq::ForkError:.*cannot be used after fork/, stderr)
+      assert_match(/#{label}_retry=Wreq::ForkError:.*cannot be used after fork/, stderr)
+    end
+    assert_match(/inherited_gc=ok/, stderr)
+    refute_match(/\[BUG\]|segmentation fault|panicked/i, stderr)
+  end
+
+  private
+
+  def run_fork_script(name)
+    lib_dir = File.expand_path("../lib", __dir__)
+    script = File.expand_path("scripts/#{name}", __dir__)
+
+    Tempfile.create("wreq-fork-stdout") do |stdout|
+      Tempfile.create("wreq-fork-stderr") do |stderr|
+        pid = Process.spawn(
+          RbConfig.ruby,
+          "-I",
+          lib_dir,
+          script,
+          out: stdout,
+          err: stderr,
+          pgroup: true
+        )
+        status = Timeout.timeout(30) { Process.wait2(pid).last }
+        stdout.rewind
+        stderr.rewind
+        return [stdout.read, stderr.read, status]
+      rescue Timeout::Error
+        begin
+          Process.kill("KILL", -pid)
+        rescue Errno::ESRCH
+          nil
+        end
+
+        begin
+          Process.wait(pid)
+        rescue Errno::ECHILD
+          nil
+        end
+
+        flunk "#{name} timed out"
+      end
+    end
+  end
+end

data/test/scripts/fork_safety.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "socket"
+require "timeout"
+require "weakref"
+require "wreq"
+
+$stdout.sync = true
+$stderr.sync = true
+
+def expect_fork_error(label)
+  child_pid = fork do
+    2.times do |attempt|
+      attempt_label = attempt.zero? ? label : "#{label}_retry"
+
+      begin
+        Timeout.timeout(5) { yield }
+      rescue Wreq::ForkError => error
+        warn "#{attempt_label}=#{error.class}: #{error.message}"
+        next
+      rescue => error
+        warn "#{attempt_label}=unexpected #{error.class}: #{error.message}"
+        exit! 2
+      end
+
+      warn "#{attempt_label}=missing Wreq::ForkError"
+      exit! 3
+    end
+
+    exit! 0
+  end
+
+  _, status = Process.wait2(child_pid)
+  abort "#{label} child failed with #{status.inspect}" unless status.success?
+end
+
+expect_fork_error("before_runtime") { Wreq::Client.new }
+expect_fork_error("invalid_client") { Wreq::Client.new(unknown: true) }
+expect_fork_error("invalid_request") { Wreq.get(1) }
+expect_fork_error("fresh_body_sender") { Wreq::BodySender.new(0) }
+
+server = TCPServer.new("127.0.0.1", 0)
+port = server.addr[1]
+server_pid = fork do
+  3.times do
+    ready = IO.select([server], nil, nil, 10)
+    exit! 4 unless ready
+
+    socket = server.accept
+    begin
+      while (line = socket.gets)
+        break if line == "\r\n"
+      end
+      socket.write("HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok")
+    ensure
+      socket.close
+    end
+  end
+  exit! 0
+ensure
+  server.close
+end
+server.close
+
+url = "http://127.0.0.1:#{port}/"
+client = Wreq::Client.new
+abort "parent warm-up failed" unless client.get(url).bytes == "ok"
+
+def build_inherited_objects(client, url)
+  [Wreq::Client.new, Wreq::BodySender.new, client.get(url)]
+end
+
+inherited_objects = build_inherited_objects(client, url)
+inherited_weak_refs = inherited_objects.map { |object| WeakRef.new(object) }
+
+expect_fork_error("inherited_body_sender_push") do
+  inherited_objects[1].push("chunk")
+end
+expect_fork_error("inherited_body_sender_close") { inherited_objects[1].close }
+expect_fork_error("inherited_body_sender_closed") { inherited_objects[1].closed? }
+expect_fork_error("fresh_client") { Wreq::Client.new }
+expect_fork_error("inherited_client") { client.get(url) }
+expect_fork_error("inherited_response") { inherited_objects[2].bytes }
+expect_fork_error("inherited_response_text") { inherited_objects[2].text(1) }
+expect_fork_error("inherited_response_chunks") { inherited_objects[2].chunks }
+expect_fork_error("inherited_response_close") { inherited_objects[2].close }
+
+# Release the earlier test blocks so this array is the only strong reference.
+GC.start(full_mark: true, immediate_sweep: true)
+gc_pid = fork do
+  inherited_objects = nil
+  3.times { GC.start(full_mark: true, immediate_sweep: true) }
+  alive = inherited_weak_refs.each_index.select do |index|
+    inherited_weak_refs[index].weakref_alive?
+  end
+  abort "inherited objects were not collected: #{alive.join(", ")}" unless alive.empty?
+  warn "inherited_gc=ok"
+  exit! 0
+rescue => error
+  warn "inherited_gc=unexpected #{error.class}: #{error.message}"
+  exit! 5
+end
+_, gc_status = Process.wait2(gc_pid)
+abort "inherited GC child failed with #{gc_status.inspect}" unless gc_status.success?
+
+abort "parent request after fork failed" unless client.get(url).bytes == "ok"
+_, server_status = Process.wait2(server_pid)
+abort "server failed with #{server_status.inspect}" unless server_status.success?
+
+puts "ok"

data/test/support/tls_server.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "socket"
+require "timeout"
+
+# A small HTTPS server that serves every expected request on one TLS connection.
+module TlsTestServer
+  RESPONSE_BODY = "ok"
+
+  module_function
+
+  def with_connection(request_count:)
+    tcp_server = TCPServer.new("127.0.0.1", 0)
+    context, certificate_der = server_context
+    ssl_server = OpenSSL::SSL::SSLServer.new(tcp_server, context)
+    outcome = Queue.new
+    server_thread = Thread.new do
+      socket = ssl_server.accept
+      request_lines = []
+
+      request_count.times do |index|
+        request_lines << read_request(socket)
+        connection = (index == request_count - 1) ? "close" : "keep-alive"
+        socket.write(response(connection))
+        socket.flush
+      end
+
+      outcome << {connections: 1, requests: request_lines}
+    rescue => error
+      outcome << error
+    ensure
+      socket&.close
+    end
+    server_thread.report_on_exception = false
+
+    yield "https://127.0.0.1:#{tcp_server.addr[1]}/", certificate_der
+
+    result = Timeout.timeout(5) { outcome.pop }
+    raise result if result.is_a?(StandardError)
+
+    result
+  ensure
+    tcp_server&.close
+    server_thread&.join(5)
+    if server_thread&.alive?
+      server_thread.kill
+      server_thread.join
+    end
+  end
+
+  def read_request(socket)
+    request_line = socket.gets
+    raise EOFError, "client closed before sending a request" unless request_line
+
+    loop do
+      line = socket.gets
+      raise EOFError, "client closed while sending headers" unless line
+      break if line == "\r\n"
+    end
+
+    request_line
+  end
+  private_class_method :read_request
+
+  def response(connection)
+    [
+      "HTTP/1.1 200 OK",
+      "Content-Length: #{RESPONSE_BODY.bytesize}",
+      "Connection: #{connection}",
+      "",
+      RESPONSE_BODY
+    ].join("\r\n")
+  end
+  private_class_method :response
+
+  def server_context
+    key = OpenSSL::PKey::RSA.new(2048)
+    certificate = OpenSSL::X509::Certificate.new
+    certificate.version = 2
+    certificate.serial = 1
+    certificate.subject = certificate.issuer = OpenSSL::X509::Name.parse("/CN=127.0.0.1")
+    certificate.public_key = key.public_key
+    certificate.not_before = Time.now - 60
+    certificate.not_after = Time.now + 3600
+    certificate.sign(key, OpenSSL::Digest.new("SHA256"))
+
+    context = OpenSSL::SSL::SSLContext.new.tap do |ssl_context|
+      ssl_context.cert = certificate
+      ssl_context.key = key
+    end
+    [context, certificate.to_der]
+  end
+  private_class_method :server_context
+end

data/test/tls_info_test.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require_relative "support/tls_server"
+
+class TlsInfoTest < Minitest::Test
+  HTTPBIN_HTTP_URL = ENV.fetch("HTTPBIN_HTTP_URL", HTTPBIN_URL.sub(/\Ahttps:/, "http:"))
+
+  def test_tls_info_is_nil_when_disabled_or_request_is_plain_http
+    default_response = Wreq::Client.new.get("#{HTTPBIN_URL}/get")
+    plain_response = Wreq::Client.new(tls_info: true).get("#{HTTPBIN_HTTP_URL}/get")
+
+    assert_nil default_response.tls_info
+    assert_nil plain_response.tls_info
+  end
+
+  def test_certificate_data_survives_body_lifecycle_on_a_reused_connection
+    fixture = TlsTestServer.with_connection(request_count: 2) do |base_url, certificate_der|
+      client = Wreq::Client.new(
+        tls_info: true,
+        verify: false,
+        http1_only: true,
+        no_proxy: true,
+        timeout: 5
+      )
+
+      read_response = client.get("#{base_url}read")
+      assert_equal "ok", read_response.text
+      read_tls = read_response.tls_info
+
+      closed_response = client.get("#{base_url}close")
+      closed_response.close
+      closed_tls = closed_response.tls_info
+
+      assert_instance_of Wreq::TlsInfo, read_tls
+      certificate = read_tls.peer_certificate
+      chain = read_tls.peer_certificate_chain
+      assert_equal certificate_der, certificate
+      assert_equal Encoding::BINARY, certificate.encoding
+      assert_equal [certificate_der], chain
+      assert_equal Encoding::BINARY, chain.first.encoding
+      assert_predicate chain, :frozen?
+      assert_equal(
+        "#<Wreq::TlsInfo peer_certificate=#{certificate_der.bytesize}B peer_certificate_chain=1>",
+        read_tls.inspect
+      )
+      assert_empty Wreq::TlsInfo.instance_methods(false) & %i[to_h to_s]
+
+      certificate.clear
+      assert_equal certificate_der, read_tls.peer_certificate
+      assert_equal certificate_der, closed_tls.peer_certificate
+    end
+
+    assert_equal(
+      {connections: 1, requests: ["GET /read HTTP/1.1\r\n", "GET /close HTTP/1.1\r\n"]},
+      fixture
+    )
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wreq
 version: !ruby/object:Gem::Version
-  version: 1.2.11
+  version: 1.2.12
 platform: aarch64-linux
 authors:
 - SearchApi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-05 00:00:00.000000000 Z
+date: 2026-08-15 00:00:00.000000000 Z
 dependencies: []
 description: An easy and powerful Ruby HTTP client with advanced browser fingerprinting
   that accurately emulates Chrome, Edge, Firefox, Safari, Opera, and OkHttp with precise
@@ -38,6 +38,8 @@ files:
 - crates/wreq-util/README.md
 - crates/wreq-util/release-plz.toml
 - crates/wreq-util/rustfmt.toml
+- docs/fork-safety.md
+- docs/interrupt-handling.md
 - docs/windows-gnu-tokio-crash.md
 - examples/body.rb
 - examples/client.rb
@@ -48,6 +50,7 @@ files:
 - examples/send_stream.rb
 - examples/stream.rb
 - examples/thread_interrupt.rb
+- examples/tls_info.rb
 - lib/wreq.rb
 - lib/wreq_ruby/3.3/wreq_ruby.so
 - lib/wreq_ruby/3.4/wreq_ruby.so
@@ -60,6 +63,7 @@ files:
 - lib/wreq_ruby/header.rb
 - lib/wreq_ruby/http.rb
 - lib/wreq_ruby/response.rb
+- lib/wreq_ruby/tls.rb
 - script/build_platform_gem.rb
 - script/rust_env.rb
 - test/body_sender_test.rb
@@ -68,6 +72,7 @@ files:
 - test/cookie_test.rb
 - test/emulation_test.rb
 - test/error_handling_test.rb
+- test/fork_test.rb
 - test/header_test.rb
 - test/inspect_test.rb
 - test/json_precision_test.rb
@@ -77,8 +82,11 @@ files:
 - test/request_parameters_test.rb
 - test/request_test.rb
 - test/response_test.rb
+- test/scripts/fork_safety.rb
 - test/stream_test.rb
+- test/support/tls_server.rb
 - test/test_helper.rb
+- test/tls_info_test.rb
 - test/value_semantics_test.rb
 - wreq.gemspec
 homepage: https://github.com/SearchApi/wreq-ruby