excon 1.10.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8f339eac15303582618d7c092e0c31facc11e717477d11676ddf1cece1f4df8
-  data.tar.gz: f1225a0e544fb64eed9411d5f0c5028103a853e07acfa5df5b9c8d1057101297
+  metadata.gz: a5b23fd4372baad22a291604ac1177dede89a9e4a8b9caa1aa86019f4893b98d
+  data.tar.gz: 54bb6046bf8e2359a75e6720b9d8d0ffbdb41dbeeea3a483b78d0e58a2653119
 SHA512:
-  metadata.gz: 37951c154ffa841570e55ec4bd9bd6894ccd4617cbf51f03e2606d341defde41e114d85b78af7cb67ffc9f46ba4fb8ca59398dcd219f4aeb0267ee79f5a20649
-  data.tar.gz: bf5f8bb104fcdcc6fe87d8f9a221775214af61b81df535f603ff1c1c47b44b5bfd441aef1bb35ede8761cdb2badd5ff52be93ecd2a3639a4809cf0fc3371f383
+  metadata.gz: 6032a35accee4a3c447c61b2a1d8bac83352b6fd3c2eb18171f59942614983d5b17bcc18f55e051e4280008ff326acc65f93134f2cfb88d6ce18f604dd51b5ac
+  data.tar.gz: 8dfd5595f225591adf29b9d4cba4740825e75b575d894c4a5ebdb3cad468fadefa9b980ca68e7a443a23cb6e04ef72cf457855c760e93b6894f74327674c6b17

data/README.md

@@ -403,6 +403,37 @@ end
 
 By default stubs are shared globally, to make stubs unique to each thread, use `Excon.defaults[:stubs] = :local`.
 
+### Checking that stubs were called
+
+Excon counts the requests each stub answers, so a test can check that the stubs it set up were actually used, instead of passing silently when the request is never made.
+
+```ruby
+stub = Excon.stub({ :method => :get, :path => '/users' }, { :body => '[]', :status => 200 })
+
+Excon.stub_call_count(stub) # => 0
+Excon.get('http://example.com/users', :mock => true)
+Excon.stub_call_count(stub) # => 1
+```
+
+`Excon.verify_stubs` raises `Excon::Error::StubNotCalled`, listing the request params of each stub that answered no requests. With no arguments it checks every stub in `Excon.stubs`; pass stubs to check only those, for instance to leave out a catch-all fallback stub that some tests never use.
+
+```ruby
+Excon.verify_stubs       # check every stub
+Excon.verify_stubs(stub) # check only this stub
+```
+
+For example, with RSpec:
+
+```ruby
+config.after(:each) do
+  Excon.verify_stubs
+ensure
+  Excon.stubs.clear
+end
+```
+
+A stub's count is kept with the stub object `Excon.stub` returns (or `Excon.stub_for` finds), so two identical stubs are counted separately. Counts are only kept for stubs still in `Excon.stubs`, so don't rely on the count of a stub after removing it. Counts follow `Excon.defaults[:stubs]`, so `:local` stubs are counted per thread.
+
 ## Instrumentation
 
 Excon calls can be timed using the [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) API.

data/data/cacert.pem

@@ -1,7 +1,7 @@
 ##
 ## Bundle of CA Root Certificates
 ##
-## Certificate data from Mozilla as of: Tue Oct 20 13:32:40 2026 GMT
+## Certificate data from Mozilla as of: Thu Nov  5 04:12:01 2026 GMT
 ##
 ## Find updated versions here: https://curl.se/docs/caextract.html
 ##
@@ -16,7 +16,7 @@
 ## Configure this file as the SSLCACertificateFile.
 ##
 ## Conversion done with mk-ca-bundle.pl version 1.35.
-## SHA256: beb7e6dfe6499926e52c075c27bcfbe4c957f8609c575b3860273ae2806f63eb
+## SHA256: 3ec2b4d240dc12c747eaf450061db84af757c483bbda302f9e29ceb5d70be510
 ##
 
 

data/lib/excon/connection.rb

@@ -547,7 +547,11 @@ module Excon
     end
 
     def raise_socket_error(error)
-      if error.message.include?('certificate verify failed')
+      # already a Socket error (e.g. from a proxy handshake): wrapping it
+      # again would add nothing but its class name to the message
+      if error.is_a?(Excon::Error::Socket)
+        raise(error)
+      elsif error.message.include?('certificate verify failed')
         raise(Excon::Errors::CertificateError.new(error))
       else
         raise(Excon::Errors::SocketError.new(error))
@@ -617,7 +621,12 @@ module Excon
       when Hash
         # no processing needed
       when String, URI
-        uri = @data[:proxy].is_a?(String) ? URI.parse(@data[:proxy]) : @data[:proxy]
+        uri = if @data[:proxy].is_a?(String)
+          uri_parser = @data[:uri_parser] || Excon.defaults[:uri_parser]
+          uri_parser.parse(@data[:proxy])
+        else
+          @data[:proxy]
+        end
         @data[:proxy] = {
           :host       => uri.host,
           :hostname   => uri.hostname,

data/lib/excon/error.rb

@@ -5,6 +5,7 @@ module Excon
     @default_status_error = :HTTPStatus
 
     class StubNotFound < Error; end
+    class StubNotCalled < Error; end
     class InvalidStub < Error; end
     class Warning < Error; end
 
@@ -12,9 +13,14 @@ module Excon
     class Socket < Error
       attr_reader :socket_error
 
+      # socket_error is the error to wrap, or a message for an error that
+      # wraps none (whose socket_error is then itself)
       def initialize(socket_error = Excon::Error.new)
         if is_a?(Certificate) || is_a?(Excon::Errors::CertificateError)
           super
+        elsif socket_error.is_a?(String)
+          super
+          @socket_error = self
         else
           super("#{socket_error.message} (#{socket_error.class})")
           set_backtrace(socket_error.backtrace)
@@ -52,7 +58,9 @@ or:
     class Timeout < Error; end
     class ResponseParse < Error; end
 
-    class ProxyConnectionError < Error
+    # Raised when a proxy refuses to open a CONNECT tunnel. A Socket error, so
+    # it is retried and rescued as one; socket_error returns the error itself.
+    class ProxyConnectionError < Socket
       attr_reader :request, :response
 
       def initialize(msg, request = nil, response = nil)
@@ -62,6 +70,10 @@ or:
       end
     end
 
+    # Raised when a SOCKS5 proxy handshake fails. A Socket error, so it is
+    # retried and rescued as one; socket_error returns the error itself.
+    class SOCKS5Error < Socket; end
+
     class ProxyParse < Error; end
     class TooManyRedirects < Error; end
 

data/lib/excon/middlewares/mock.rb

@@ -26,6 +26,8 @@ module Excon
           end
 
           if (stub = Excon.stub_for(datum))
+            # count before calling a block stub, so one that raises still counts
+            Excon.record_stub_call(stub)
             datum[:remote_ip] ||= '127.0.0.1'
             datum[:response] = {
               :body       => '',

data/lib/excon/response.rb

@@ -126,32 +126,20 @@ module Excon
           end
         end
 
+        # without a :response_block (or when :expects would fail), buffer the body
+        response_block ||= lambda { |chunk, _remaining, _total| datum[:response][:body] << chunk }
+
         if transfer_encoding_chunked
-          if response_block
-            while (chunk_size = socket.readline.chomp!.to_i(16)) > 0
-              while chunk_size > 0
-                chunk = socket.read(chunk_size) || raise(EOFError)
-                chunk_size -= chunk.bytesize
-                response_block.call(chunk, nil, nil)
-              end
-              new_line_size = 2 # 2 == "\r\n".length
-              while new_line_size > 0
-                chunk = socket.read(new_line_size) || raise(EOFError)
-                new_line_size -= chunk.length
-              end
+          while (chunk_size = socket.readline.chomp!.to_i(16)) > 0
+            while chunk_size > 0
+              chunk = socket.read(chunk_size) || raise(EOFError)
+              chunk_size -= chunk.bytesize
+              response_block.call(chunk, nil, nil)
             end
-          else
-            while (chunk_size = socket.readline.chomp!.to_i(16)) > 0
-              while chunk_size > 0
-                chunk = socket.read(chunk_size) || raise(EOFError)
-                chunk_size -= chunk.bytesize
-                datum[:response][:body] << chunk
-              end
-              new_line_size = 2 # 2 == "\r\n".length
-              while new_line_size > 0
-                chunk = socket.read(new_line_size) || raise(EOFError)
-                new_line_size -= chunk.length
-              end
+            new_line_size = 2 # 2 == "\r\n".length
+            while new_line_size > 0
+              chunk = socket.read(new_line_size) || raise(EOFError)
+              new_line_size -= chunk.length
             end
           end
           parse_headers(socket, datum) # merge trailers into headers
@@ -161,28 +149,14 @@ module Excon
           end
 
           if (remaining = content_length)
-            if response_block
-              while remaining > 0
-                chunk = socket.read([datum[:chunk_size], remaining].min) || raise(EOFError)
-                response_block.call(chunk, [remaining - chunk.bytesize, 0].max, content_length)
-                remaining -= chunk.bytesize
-              end
-            else
-              while remaining > 0
-                chunk = socket.read([datum[:chunk_size], remaining].min) || raise(EOFError)
-                datum[:response][:body] << chunk
-                remaining -= chunk.bytesize
-              end
+            while remaining > 0
+              chunk = socket.read([datum[:chunk_size], remaining].min) || raise(EOFError)
+              response_block.call(chunk, [remaining - chunk.bytesize, 0].max, content_length)
+              remaining -= chunk.bytesize
             end
           else
-            if response_block
-              while (chunk = socket.read(datum[:chunk_size]))
-                response_block.call(chunk, nil, nil)
-              end
-            else
-              while (chunk = socket.read(datum[:chunk_size]))
-                datum[:response][:body] << chunk
-              end
+            while (chunk = socket.read(datum[:chunk_size]))
+              response_block.call(chunk, nil, nil)
             end
           end
         end

data/lib/excon/socks5.rb

@@ -80,7 +80,7 @@ module Excon
       version, chosen_method = response.unpack('CC')
 
       if version != SOCKS5_VERSION
-        raise Excon::Error::Socket.new(Exception.new("SOCKS5 proxy returned invalid version: #{version}"))
+        raise Excon::Error::SOCKS5Error, "SOCKS5 proxy returned invalid version: #{version}"
       end
 
       case chosen_method
@@ -88,13 +88,13 @@ module Excon
         # No authentication required
       when SOCKS5_AUTH_USERNAME_PASSWORD
         unless @proxy_user && @proxy_pass
-          raise Excon::Error::Socket.new(Exception.new('SOCKS5 proxy requires authentication but no credentials provided'))
+          raise Excon::Error::SOCKS5Error, 'SOCKS5 proxy requires authentication but no credentials provided'
         end
         socks5_username_password_auth
       when SOCKS5_NO_ACCEPTABLE_AUTH
-        raise Excon::Error::Socket.new(Exception.new('SOCKS5 proxy: no acceptable authentication methods'))
+        raise Excon::Error::SOCKS5Error, 'SOCKS5 proxy: no acceptable authentication methods'
       else
-        raise Excon::Error::Socket.new(Exception.new("SOCKS5 proxy: unsupported authentication method #{chosen_method}"))
+        raise Excon::Error::SOCKS5Error, "SOCKS5 proxy: unsupported authentication method #{chosen_method}"
       end
     end
 
@@ -114,14 +114,14 @@ module Excon
       _, status = response.unpack('CC')
 
       unless status == 0x00
-        raise Excon::Error::Socket.new(Exception.new('SOCKS5 proxy authentication failed'))
+        raise Excon::Error::SOCKS5Error, 'SOCKS5 proxy authentication failed'
       end
     end
 
     # Request connection to target through SOCKS5 proxy
     def socks5_connect(host, port)
       if host.bytesize > MAX_HOSTNAME_LENGTH
-        raise Excon::Error::Socket.new(Exception.new("SOCKS5: hostname exceeds maximum length of #{MAX_HOSTNAME_LENGTH} bytes"))
+        raise Excon::Error::SOCKS5Error, "SOCKS5: hostname exceeds maximum length of #{MAX_HOSTNAME_LENGTH} bytes"
       end
 
       # Build CONNECT request with domain name (let proxy resolve DNS)
@@ -135,12 +135,12 @@ module Excon
       version, reply, _, atyp = response.unpack('CCCC')
 
       if version != SOCKS5_VERSION
-        raise Excon::Error::Socket.new(Exception.new("SOCKS5 proxy returned invalid version: #{version}"))
+        raise Excon::Error::SOCKS5Error, "SOCKS5 proxy returned invalid version: #{version}"
       end
 
       unless reply == SOCKS5_SUCCESS
         error_msg = SOCKS5_ERRORS[reply] || "Unknown error (#{reply})"
-        raise Excon::Error::Socket.new(Exception.new("SOCKS5 proxy connect failed: #{error_msg}"))
+        raise Excon::Error::SOCKS5Error, "SOCKS5 proxy connect failed: #{error_msg}"
       end
 
       # Read and discard bound address (not needed for CONNECT)
@@ -157,7 +157,7 @@ module Excon
       when SOCKS5_ATYP_IPV6
         socks5_read_exactly(16 + 2) # 16 bytes IP + 2 bytes port
       else
-        raise Excon::Error::Socket.new(Exception.new("SOCKS5 proxy returned unknown address type: #{atyp}"))
+        raise Excon::Error::SOCKS5Error, "SOCKS5 proxy returned unknown address type: #{atyp}"
       end
     end
 
@@ -183,7 +183,7 @@ module Excon
         when :wait_readable
           IO.select([@socket], nil, nil, deadline ? [deadline - Time.now, 0].max : nil)
         when nil, ''
-          raise Excon::Error::Socket.new(Exception.new('SOCKS5 proxy connection closed unexpectedly'))
+          raise Excon::Error::SOCKS5Error, 'SOCKS5 proxy connection closed unexpectedly'
         else
           data << chunk
         end

data/lib/excon/ssl_socket.rb

@@ -86,11 +86,8 @@ module Excon
 
       if client_cert_data && client_key_data
         ssl_context.cert = OpenSSL::X509::Certificate.new client_cert_data
-        if OpenSSL::PKey.respond_to? :read
-          ssl_context.key = OpenSSL::PKey.read(client_key_data, client_key_pass)
-        else
-          ssl_context.key = OpenSSL::PKey::RSA.new(client_key_data, client_key_pass)
-        end
+        ssl_context.key = OpenSSL::PKey.read(client_key_data, client_key_pass)
+        # jruby-openssl 0.16.x (bundled with JRuby 10.0) lacks Certificate.load
         if client_chain_data && OpenSSL::X509::Certificate.respond_to?(:load)
           ssl_context.extra_chain_cert = OpenSSL::X509::Certificate.load(client_chain_data)
         elsif client_chain_data
@@ -101,11 +98,7 @@ module Excon
         end
       elsif @data.key?(:certificate) && @data.key?(:private_key)
         ssl_context.cert = OpenSSL::X509::Certificate.new(@data[:certificate])
-        if OpenSSL::PKey.respond_to? :read
-          ssl_context.key = OpenSSL::PKey.read(@data[:private_key], client_key_pass)
-        else
-          ssl_context.key = OpenSSL::PKey::RSA.new(@data[:private_key], client_key_pass)
-        end
+        ssl_context.key = OpenSSL::PKey.read(@data[:private_key], client_key_pass)
       end
 
       if @data[:proxy]
@@ -129,10 +122,15 @@ module Excon
         # write out the proxy setup request
         @socket.write(request)
 
-        # eat the proxy's connection response
-        response = Excon::Response.parse(self,  :expects => 200, :method => 'CONNECT')
-        if response[:response][:status] != 200
-          raise(Excon::Errors::ProxyConnectionError.new("proxy connection could not be established", request, response))
+        # eat the proxy's connection response; any 2xx means the tunnel is
+        # open (RFC 9110, section 9.3.6)
+        response = Excon::Response.parse(self, method: 'CONNECT')
+        unless (200..299).cover?(response[:response][:status])
+          # the error keeps the request, which may be logged, so leave out
+          # the proxy credentials (which :ssl_proxy_headers may also carry)
+          redacted_request = request.gsub(/^(Proxy-Authorization:)[^\r\n]*/i, "\\1 #{Excon::REDACTED}")
+          raise(Excon::Errors::ProxyConnectionError.new('proxy connection could not be established',
+                                                        redacted_request, response))
         end
       end
 

data/lib/excon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Excon
-  VERSION = "1.10.0"
+  VERSION = "1.11.0"
 end

data/lib/excon.rb

@@ -48,6 +48,9 @@ require 'excon/unix_socket'
 
 # Define defaults first so they will be available to other files
 module Excon
+  # guards the stub call counts, which threads share when stubs are :global
+  STUB_CALL_COUNTS_MUTEX = Mutex.new
+
   class << self
     # @return [Hash] defaults for Excon connections
     def defaults
@@ -178,19 +181,21 @@ module Excon
       else
         raise(ArgumentError, 'stub requires either response_params OR a block')
       end
+      prune_stub_call_counts
       stubs.unshift(stub)
       stub
     end
 
     # get a stub matching params or nil
     # @param request_params [Hash<Symbol, >] request params to match against, omitted params match all
-    # @return [Hash<Symbol, >] response params to return from matched request or block to call with params
+    # @return [Array] the matching stub from Excon.stubs, a [request_params, response_params] pair
     def stub_for(request_params={})
       if (method = request_params.delete(:method))
         request_params[:method] = method.to_s.downcase.to_sym
       end
       request_params[:query] = Utils.query_string(request_params)[1...] if request_params.key?(:query)
-      Excon.stubs.each do |stub, response_params|
+      Excon.stubs.each do |entry|
+        stub, = entry
         captures = { headers: {} }
         headers_match = !stub.key?(:headers) || stub[:headers].keys.all? do |key|
           case value = stub[:headers][key]
@@ -226,7 +231,7 @@ module Excon
         end
         if headers_match && non_headers_match
           request_params[:captures] = captures
-          return [stub, response_params]
+          return entry
         end
       end
       nil
@@ -248,7 +253,44 @@ module Excon
     def unstub(request_params = {})
       return unless (stub = stub_for(request_params))
 
-      Excon.stubs.delete_at(Excon.stubs.index(stub))
+      STUB_CALL_COUNTS_MUTEX.synchronize { stub_call_counts.delete(stub) }
+      Excon.stubs.delete_at(Excon.stubs.index { |entry| entry.equal?(stub) })
+    end
+
+    # number of requests a stub has answered
+    # counts are only kept for stubs still in Excon.stubs; don't rely on the
+    # count of a stub after removing it
+    # @param stub [Array] a stub, as returned by Excon.stub or Excon.stub_for
+    # @return [Integer] how many times the stub has answered a request
+    def stub_call_count(stub)
+      STUB_CALL_COUNTS_MUTEX.synchronize { stub_call_counts.fetch(stub, 0) }
+    end
+
+    # raise if any of the given stubs, or of all stubs, has not answered a request
+    # @param stubs [Array<Array>] stubs to check, as returned by Excon.stub; omit to check every stub in Excon.stubs
+    # @raise [Excon::Error::StubNotCalled] listing the request params of each stub that was never called
+    # @return [true] if every stub checked has been called
+    def verify_stubs(*stubs)
+      stubs = Excon.stubs.dup if stubs.empty?
+      uncalled = stubs.select { |stub| stub_call_count(stub).zero? }
+      return true if uncalled.empty?
+
+      message = StringIO.new
+      message.puts("#{uncalled.length} of #{stubs.length} stubs not called")
+      uncalled.each do |request_params, _|
+        message.puts('{')
+        Excon::PrettyPrinter.pp(message, request_params)
+        message.puts('}')
+      end
+      raise(Excon::Error::StubNotCalled.new(message.string))
+    end
+
+    # record that a stub answered a request, used by Excon::Middleware::Mock
+    # @param stub [Array] the stub, as returned by Excon.stub_for
+    def record_stub_call(stub)
+      STUB_CALL_COUNTS_MUTEX.synchronize do
+        stub_call_counts[stub] = stub_call_counts.fetch(stub, 0) + 1
+      end
     end
 
     # Generic non-persistent HTTP methods
@@ -259,5 +301,30 @@ module Excon
         end
       DEF
     end
+
+    private
+
+    # call counts for stubs, keyed by the stub object itself (not by equality,
+    # so two identical stubs are counted apart); kept alongside Excon.stubs
+    def stub_call_counts
+      case Excon.defaults[:stubs]
+      when :global
+        @stub_call_counts ||= {}.compare_by_identity
+      when :local
+        Thread.current[:_excon_stub_call_counts] ||= {}.compare_by_identity
+      end
+    end
+
+    # drop counts for stubs no longer in Excon.stubs (e.g. after Excon.stubs.clear),
+    # so they don't hold on to removed stubs
+    def prune_stub_call_counts
+      STUB_CALL_COUNTS_MUTEX.synchronize do
+        counts = stub_call_counts
+        next if counts.empty?
+
+        live = Excon.stubs.each_with_object({}.compare_by_identity) { |stub, set| set[stub] = true }
+        counts.delete_if { |stub, _| !live.key?(stub) }
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: excon
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.0
 platform: ruby
 authors:
 - dpiddy (Dan Peterson)