wreq 1.2.11 → 1.2.13

data/lib/wreq_ruby/response.rb

@@ -8,6 +8,13 @@ unless defined?(Wreq)
     # access to HTTP response data including status codes, headers, body
     # content, and streaming capabilities.
     #
+    # A response belongs to the process that received it. Accessing its metadata
+    # or body after inheriting it from a parent raises Wreq::ForkError.
+    #
+    # @note Fork safety Keep each response in the process that received it.
+    #   Issue a new request in the worker instead of carrying a response through
+    #   `fork`.
+    #
     # @example Basic response handling
     #   response = client.get("https://api.example.com")
     #   puts response.status.as_int  # => 200
@@ -26,6 +33,7 @@ unless defined?(Wreq)
       # Get the HTTP status code as an integer.
       #
       # @return [Integer] Status code (e.g., 200, 404, 500)
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
       # @example
       #   response.code  # => 200
       def code
@@ -34,6 +42,7 @@ unless defined?(Wreq)
       # Get the HTTP status code object.
       #
       # @return [Wreq::StatusCode] Status code wrapper with helper methods
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
       # @example
       #   status = response.status
       #   status.success?  # => true
@@ -43,6 +52,7 @@ unless defined?(Wreq)
       # Get the HTTP protocol version used.
       #
       # @return [Wreq::Version] HTTP version (HTTP/1.1, HTTP/2, etc.)
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
       # @example
       #   response.version  # => Wreq::Version::HTTP_11
       def version
@@ -51,6 +61,7 @@ unless defined?(Wreq)
       # Get the final URL after redirects.
       #
       # @return [String] The final URL
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
       # @example
       #   response.url  # => "https://example.com/final-page"
       def url
@@ -59,6 +70,7 @@ unless defined?(Wreq)
       # Get the content length if known.
       #
       # @return [Integer, nil] Content length in bytes, or nil if unknown
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
       # @example
       #   response.content_length  # => 1024
       def content_length
@@ -72,6 +84,7 @@ unless defined?(Wreq)
       # response or a later snapshot, and object identity is not guaranteed.
       #
       # @return [Wreq::Headers] Response headers
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
       # @example
       #   response.headers.get("content-type")  # => "application/json"
       def headers
@@ -80,6 +93,7 @@ unless defined?(Wreq)
       # Get the local socket address.
       #
       # @return [String, nil] Local address (e.g., "127.0.0.1:54321"), or nil
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
       # @example
       #   response.local_addr  # => "192.168.1.100:54321"
       def local_addr
@@ -88,6 +102,7 @@ unless defined?(Wreq)
       # Get the remote socket address.
       #
       # @return [String, nil] Remote address (e.g., "93.184.216.34:443"), or nil
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
       # @example
       #   response.remote_addr  # => "93.184.216.34:443"
       def remote_addr
@@ -98,6 +113,7 @@ unless defined?(Wreq)
       # Invalid `Set-Cookie` values are skipped.
       #
       # @return [Array<Wreq::Cookie>] Parsed response cookies
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
       # @example
       #   response.cookies.each do |cookie|
       #     puts "#{cookie.name}=#{cookie.value}"
@@ -107,6 +123,7 @@ unless defined?(Wreq)
 
       # Get the response bytes as a binary string.
       # @return [String] Response body as binary data
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
       # @example
       #   binary_data = response.bytes
       #   puts binary_data.size  # => 1024
@@ -122,6 +139,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 response belongs to the parent process
       def text(default_encoding = "UTF-8")
       end
 
@@ -132,6 +150,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 response belongs to the parent process
       # @example
       #   data = response.json
       #   puts data["key"]
@@ -149,6 +168,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 response belongs to the parent process
       # @example Save response to file
       #   File.open("output.bin", "wb") do |f|
       #     response.chunks { |chunk| f.write(chunk) }
@@ -165,10 +185,32 @@ unless defined?(Wreq)
       # Close the response and free associated resources.
       #
       # @return [void]
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
       # @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
+      # @raise [Wreq::ForkError] if the response belongs to the parent process
+      # @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
@@ -180,6 +222,7 @@ module Wreq
     # Returns the response body as a string.
     #
     # @return [String] Response body text
+    # @raise [Wreq::ForkError] if the response belongs to the parent process
     # @example
     #   puts response.to_s
     #   puts response
@@ -193,6 +236,7 @@ module Wreq
     # Format: #<Wreq::Response STATUS content-type="..." body=SIZE>
     #
     # @return [String] Compact formatted response information
+    # @raise [Wreq::ForkError] if the response belongs to the parent process
     # @example
     #   p response
     #   # => #<Wreq::Response 200 content-type="application/json" body=456B>

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/src/arch.rs

@@ -6,6 +6,77 @@
 //! do not leak into the rest of the binding.
 #![allow(unsafe_code)]
 
+use std::mem::ManuallyDrop;
+
+use magnus::Ruby;
+
+#[cfg(unix)]
+use crate::error::fork_error;
+
+/// Native state that belongs to the process where it was created.
+///
+/// A forked child must not destroy inherited clients, channels, or response
+/// bodies because their synchronization state may belong to threads that no
+/// longer exist. The child intentionally leaks the value and lets the operating
+/// system reclaim it when the process exits.
+///
+/// `Send` and `Sync` only describe access between threads in one process. They
+/// do not make a runtime, lock, channel, or connection pool safe after `fork`.
+///
+/// [`ProcessLocal::get`] is the only access path and checks the object's own
+/// process generation before exposing its value.
+pub(crate) struct ProcessLocal<T> {
+    value: ManuallyDrop<T>,
+    #[cfg(unix)]
+    owner: unix::ProcessToken,
+}
+
+impl<T> ProcessLocal<T> {
+    /// Wrap native state created by the current process.
+    pub(crate) fn new(value: T) -> Self {
+        Self {
+            value: ManuallyDrop::new(value),
+            #[cfg(unix)]
+            owner: unix::ProcessToken::current(),
+        }
+    }
+
+    /// Borrow native state only from the process that created it.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Wreq::ForkError` when the value was inherited from a parent
+    /// process.
+    #[inline]
+    pub(crate) fn get(&self, ruby: &Ruby) -> Result<&T, magnus::Error> {
+        #[cfg(unix)]
+        if let Some((owner_pid, current_pid)) = self.owner.forked_process_ids() {
+            return Err(fork_error(ruby, owner_pid, current_pid));
+        }
+
+        #[cfg(not(unix))]
+        let _ = ruby;
+
+        Ok(&self.value)
+    }
+}
+
+impl<T> Drop for ProcessLocal<T> {
+    fn drop(&mut self) {
+        #[cfg(unix)]
+        if self.owner.forked_process_ids().is_some() {
+            return;
+        }
+
+        // SAFETY: `new` initializes the value exactly once, `ManuallyDrop`
+        // prevents an automatic second drop, and this wrapper's `Drop`
+        // implementation runs at most once.
+        unsafe {
+            ManuallyDrop::drop(&mut self.value);
+        }
+    }
+}
+
 /// Whether the native client exposes TCP user-timeout configuration.
 pub(crate) const SUPPORTS_TCP_USER_TIMEOUT: bool = cfg!(any(
     target_os = "android",
@@ -27,6 +98,82 @@ pub(crate) const SUPPORTS_INTERFACE: bool = cfg!(any(
     target_os = "watchos",
 ));
 
+#[cfg(unix)]
+mod unix {
+    use std::{io, process, sync::OnceLock};
+
+    /// Identity of the process generation that created native state.
+    ///
+    /// Forkguard's child callback only advances an atomic generation counter.
+    /// The PID is retained for diagnostics and as a fallback if registering
+    /// the callback fails.
+    /// https://pubs.opengroup.org/onlinepubs/9799919799/functions/pthread_atfork.html
+    pub(super) struct ProcessToken {
+        detector: Option<forkguard::Guard>,
+        owner_pid: u32,
+    }
+
+    impl ProcessToken {
+        /// Capture the current process and fork generation.
+        pub(super) fn current() -> Self {
+            Self::try_current().unwrap_or_else(|_| Self {
+                detector: None,
+                owner_pid: process::id(),
+            })
+        }
+
+        /// Capture the current process after registering fork detection.
+        fn try_current() -> io::Result<Self> {
+            forkguard::Guard::try_new()
+                .map(|detector| Self {
+                    detector: Some(detector),
+                    owner_pid: process::id(),
+                })
+                .map_err(|error| io::Error::from_raw_os_error(error.code().get()))
+        }
+
+        /// Return process IDs when this token was inherited through a fork.
+        pub(super) fn forked_process_ids(&self) -> Option<(u32, u32)> {
+            if let Some(detector) = &self.detector {
+                // Keep the stored generation unchanged so repeated accesses
+                // continue to reject the same inherited object. Cloning the
+                // detector copies one usize.
+                return detector
+                    .clone()
+                    .detected_fork()
+                    .then(|| (self.owner_pid, process::id()));
+            }
+
+            let current_pid = process::id();
+            (self.owner_pid != current_pid).then_some((self.owner_pid, current_pid))
+        }
+    }
+
+    /// Runtime owner captured when Tokio first initializes.
+    static RUNTIME_OWNER: OnceLock<ProcessToken> = OnceLock::new();
+
+    /// Register process fork tracking before the Tokio runtime is initialized.
+    pub(crate) fn initialize_fork_tracking() -> io::Result<()> {
+        if RUNTIME_OWNER.get().is_some() {
+            return Ok(());
+        }
+
+        let owner = ProcessToken::try_current()?;
+        let _ = RUNTIME_OWNER.set(owner);
+        Ok(())
+    }
+
+    /// Return process IDs when this process inherited an initialized runtime.
+    pub(crate) fn forked_process_ids() -> Option<(u32, u32)> {
+        RUNTIME_OWNER
+            .get()
+            .and_then(ProcessToken::forked_process_ids)
+    }
+}
+
+#[cfg(unix)]
+pub(crate) use unix::{forked_process_ids, initialize_fork_tracking};
+
 #[cfg(all(target_os = "windows", target_env = "gnu"))]
 mod windows_gnu {
     //! Windows GNU support.
@@ -53,3 +200,30 @@ mod windows_gnu {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use std::cell::Cell;
+
+    use super::ProcessLocal;
+
+    struct DropCounter<'a>(&'a Cell<usize>);
+
+    impl Drop for DropCounter<'_> {
+        fn drop(&mut self) {
+            self.0.set(self.0.get() + 1);
+        }
+    }
+
+    #[test]
+    fn process_local_drops_in_its_owner_process() {
+        let drops = Cell::new(0);
+
+        {
+            let value = ProcessLocal::new(DropCounter(&drops));
+            assert_eq!(value.value.0.get(), 0);
+        }
+
+        assert_eq!(drops.get(), 1);
+    }
+}

data/src/client/body/stream.rs

@@ -13,6 +13,7 @@ use magnus::{Error, Integer, RString, Ruby, Value, scan_args::scan_args};
 use tokio::sync::{Mutex, Semaphore, mpsc};
 
 use crate::{
+    arch::ProcessLocal,
     error::{
         argument_error, body_sender_borrow_error, body_sender_borrow_mut_error,
         body_sender_send_error, closed_body_sender_error, memory_error, type_error, wreq_error,
@@ -33,7 +34,7 @@ pub struct BodyReceiver(Mutex<Pin<Box<dyn Stream<Item = wreq::Result<Bytes>> + S
 /// receiver. Ruby's GVL protects state access; no [`RefCell`] borrow is kept
 /// while request backpressure waits without the GVL.
 #[magnus::wrap(class = "Wreq::BodySender", free_immediately, size)]
-pub struct BodySender(RefCell<InnerBodySender>);
+pub struct BodySender(ProcessLocal<RefCell<InnerBodySender>>);
 
 /// Mutable ownership state for both halves of the body channel.
 struct InnerBodySender {
@@ -64,17 +65,14 @@ impl BodyReceiver {
 
     /// Read the next body chunk, converting stream errors into Ruby errors.
     pub fn next(&self, ruby: &Ruby) -> Result<Option<Bytes>, Error> {
-        rt::try_block_on(
-            ruby,
-            async {
-                match self.0.lock().await.as_mut().next().await {
-                    Some(Ok(data)) => Ok(Some(data)),
-                    Some(Err(err)) => Err(err),
-                    None => Ok(None),
-                }
-            },
-            wreq_error,
-        )
+        rt::block_on(ruby, async {
+            match self.0.lock().await.as_mut().next().await {
+                Some(Ok(data)) => Ok(Some(data)),
+                Some(Err(err)) => Err(err),
+                None => Ok(None),
+            }
+        })?
+        .map_err(|err| wreq_error(ruby, err))
     }
 }
 
@@ -100,10 +98,12 @@ impl BodySender {
         let (tx, rx) =
             catch_unwind(|| mpsc::channel(capacity)).map_err(|_| invalid_capacity_error(ruby))?;
 
-        Ok(BodySender(RefCell::new(InnerBodySender {
-            tx: Some(tx),
-            rx: Some(rx),
-        })))
+        Ok(BodySender(ProcessLocal::new(RefCell::new(
+            InnerBodySender {
+                tx: Some(tx),
+                rx: Some(rx),
+            },
+        ))))
     }
 
     /// Push a binary chunk, waiting for capacity when the channel is full.
@@ -113,7 +113,8 @@ impl BodySender {
     /// # Errors
     ///
     /// Returns `IOError` after either channel side has closed. An interrupted
-    /// wait raises `Wreq::InterruptError`.
+    /// wait raises `Wreq::InterruptError`. Returns `Wreq::ForkError` before
+    /// reading an inherited channel.
     pub fn push(ruby: &Ruby, rb_self: &Self, data: RString) -> Result<(), Error> {
         // Clone during the shared borrow, then release it before waiting
         // for capacity. Request attachment needs a mutable borrow.
@@ -122,7 +123,8 @@ impl BodySender {
             _ => return Err(closed_body_sender_error(ruby)),
         };
 
-        rt::try_block_on(ruby, tx.send(data.to_bytes()), body_sender_send_error)
+        rt::block_on(ruby, tx.send(data.to_bytes()))?
+            .map_err(|err| body_sender_send_error(ruby, err))
     }
 
     /// Close the producing side while retaining the receiver and queued chunks.
@@ -131,7 +133,8 @@ impl BodySender {
     ///
     /// # Errors
     ///
-    /// Returns `Wreq::BodyError` if the internal state is already borrowed.
+    /// Returns `Wreq::ForkError` before reading an inherited channel, or
+    /// `Wreq::BodyError` if the internal state is already borrowed.
     pub fn close(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
         let mut inner = rb_self.write_inner(ruby)?;
         inner.tx.take();
@@ -142,21 +145,24 @@ impl BodySender {
     ///
     /// # Errors
     ///
-    /// Returns `Wreq::BodyError` if the internal state is already borrowed.
+    /// Returns `Wreq::ForkError` before reading an inherited channel, or
+    /// `Wreq::BodyError` if the internal state is already borrowed.
     pub fn is_closed(ruby: &Ruby, rb_self: &Self) -> Result<bool, Error> {
         rb_self.read_inner(ruby).map(|r| r.is_closed())
     }
 
-    /// Borrow the channel state without panicking on accidental re-entry.
+    /// Borrow channel state only in the process that created this sender.
     fn read_inner(&self, ruby: &Ruby) -> Result<Ref<'_, InnerBodySender>, Error> {
         self.0
+            .get(ruby)?
             .try_borrow()
             .map_err(|err| body_sender_borrow_error(ruby, err))
     }
 
-    /// Mutably borrow the channel state without panicking on accidental re-entry.
+    /// Mutably borrow channel state only in the process that created this sender.
     fn write_inner(&self, ruby: &Ruby) -> Result<RefMut<'_, InnerBodySender>, Error> {
         self.0
+            .get(ruby)?
             .try_borrow_mut()
             .map_err(|err| body_sender_borrow_mut_error(ruby, err))
     }