excon 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8124592e1f6c3ea37d99a51f28930c5adfbd4a6f125c82b1dfd412e96d0398f9
-  data.tar.gz: 2b94bf542e90fee28b76fd70aedcabfad6b96610922e5300fa437c550eec89fc
+  metadata.gz: 3df399d0b27add472158c8762cd3287e085e8f081705ac1fe48d88f54bd86346
+  data.tar.gz: 9021bb3bec4b54c8ef6c9a7d651ca474b55804b8f9509a826cd3ad699d23424f
 SHA512:
-  metadata.gz: d8565b4788beb8dd5b1a0aaeea8cf4ba665447e27e2f6fe871a738a22bc0d54794a1b29c67de16b274b0d0e801034127afb9410c66460ea588187b8da0a42c96
-  data.tar.gz: e54e47995333604a5cd33b803b9060e1ba51cbad20e472a7160444549397518a7feceb4d7ea548a715bf1503ae427f7fae96da02c2441965cf8f2bdaadebc2df
+  metadata.gz: 240cc0b39f52ce4ad87dac7805038f05b27d8ba6ca61c05e7713dfe2a231eb259e8bc48d5a500e6040d9565fea70a0b6c1e7939b3b2da2c86a11e59b200678b3
+  data.tar.gz: 3960311628a4f2be6c43957de1e68d4e29f0b2ab290943eb1efd3ff21301d526780b4dd10fa16d5f0761510ba696f36f7f802653ba9f6468f845c6bcb4fb23d4

data/README.md

@@ -213,6 +213,19 @@ dns_resolver = Resolv::DNS.new(nameserver: ['127.0.0.1'])
 dns_resolver.timeouts = 3
 resolver = Resolv.new([Resolv::Hosts.new, dns_resolver])
 connection = Excon.new('http://geemus.com', :resolv_resolver => resolver)
+
+# As an global alternative for Excon, you can configure a custom resolver
+# factory which produces new resolver instances, configured to your likings.
+# This even works with Ruby Ractors!
+class CustomResolverFactory
+  # @return [Resolv] the new resolver instance
+  def self.create_resolver
+    dns_resolver = Resolv::DNS.new(nameserver: ['127.0.0.1'])
+    dns_resolver.timeouts = 3
+    Resolv.new([Resolv::Hosts.new, dns_resolver])
+  end
+end
+Excon.defaults[:resolver_factory] = CustomResolverFactory
 ```
 
 ## Chunked Requests
@@ -311,10 +324,10 @@ s.close
 The Unix socket will work for one-off requests and multiuse connections. A Unix socket path must be provided separate from the resource path.
 
 ```ruby
-connection = Excon.new('unix:///', :socket => '/tmp/unicorn.sock')
+connection = Excon.new('unix:///', :socket => '/tmp/puma.sock')
 connection.request(:method => :get, :path => '/ping')
 
-Excon.get('unix:///ping', :socket => '/tmp/unicorn.sock')
+Excon.get('unix:///ping', :socket => '/tmp/puma.sock')
 ```
 
 NOTE: Proxies will be ignored when using a Unix socket, since a Unix socket has to be local.

data/data/cacert.pem

@@ -1,7 +1,7 @@
 ##
 ## Bundle of CA Root Certificates
 ##
-## Certificate data from Mozilla as of: Tue Nov  4 04:12:02 2025 GMT
+## Certificate data from Mozilla as of: Tue Dec  2 04:12:02 2025 GMT
 ##
 ## Find updated versions here: https://curl.se/docs/caextract.html
 ##
@@ -15,8 +15,8 @@
 ## an Apache+mod_ssl webserver for SSL client authentication.
 ## Just configure this file as the SSLCACertificateFile.
 ##
-## Conversion done with mk-ca-bundle.pl version 1.29.
-## SHA256: 039132bff5179ce57cec5803ba59fe37abe6d0297aeb538c5af27847f0702517
+## Conversion done with mk-ca-bundle.pl version 1.30.
+## SHA256: a903b3cd05231e39332515ef7ebe37e697262f39515a52015c23c62805b73cd0
 ##
 
 
@@ -3167,96 +3167,6 @@ bbd+NvBNEU/zy4k6LHiRUKNbwMp1JvK/kF0LgoxgKJ/GcJpo5PECMFxYDlZ2z1jD1xCMuo6u47xk
 dUfFVZDj/bpV6wfEU6s3qe4hsiFbYI89MvHVI5TWWA==
 -----END CERTIFICATE-----
 
-CommScope Public Trust ECC Root-01
-==================================
------BEGIN CERTIFICATE-----
-MIICHTCCAaOgAwIBAgIUQ3CCd89NXTTxyq4yLzf39H91oJ4wCgYIKoZIzj0EAwMwTjELMAkGA1UE
-BhMCVVMxEjAQBgNVBAoMCUNvbW1TY29wZTErMCkGA1UEAwwiQ29tbVNjb3BlIFB1YmxpYyBUcnVz
-dCBFQ0MgUm9vdC0wMTAeFw0yMTA0MjgxNzM1NDNaFw00NjA0MjgxNzM1NDJaME4xCzAJBgNVBAYT
-AlVTMRIwEAYDVQQKDAlDb21tU2NvcGUxKzApBgNVBAMMIkNvbW1TY29wZSBQdWJsaWMgVHJ1c3Qg
-RUNDIFJvb3QtMDEwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAARLNumuV16ocNfQj3Rid8NeeqrltqLx
-eP0CflfdkXmcbLlSiFS8LwS+uM32ENEp7LXQoMPwiXAZu1FlxUOcw5tjnSCDPgYLpkJEhRGnSjot
-6dZoL0hOUysHP029uax3OVejQjBAMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMB0G
-A1UdDgQWBBSOB2LAUN3GGQYARnQE9/OufXVNMDAKBggqhkjOPQQDAwNoADBlAjEAnDPfQeMjqEI2
-Jpc1XHvr20v4qotzVRVcrHgpD7oh2MSg2NED3W3ROT3Ek2DS43KyAjB8xX6I01D1HiXo+k515liW
-pDVfG2XqYZpwI7UNo5uSUm9poIyNStDuiw7LR47QjRE=
------END CERTIFICATE-----
-
-CommScope Public Trust ECC Root-02
-==================================
------BEGIN CERTIFICATE-----
-MIICHDCCAaOgAwIBAgIUKP2ZYEFHpgE6yhR7H+/5aAiDXX0wCgYIKoZIzj0EAwMwTjELMAkGA1UE
-BhMCVVMxEjAQBgNVBAoMCUNvbW1TY29wZTErMCkGA1UEAwwiQ29tbVNjb3BlIFB1YmxpYyBUcnVz
-dCBFQ0MgUm9vdC0wMjAeFw0yMTA0MjgxNzQ0NTRaFw00NjA0MjgxNzQ0NTNaME4xCzAJBgNVBAYT
-AlVTMRIwEAYDVQQKDAlDb21tU2NvcGUxKzApBgNVBAMMIkNvbW1TY29wZSBQdWJsaWMgVHJ1c3Qg
-RUNDIFJvb3QtMDIwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAR4MIHoYx7l63FRD/cHB8o5mXxO1Q/M
-MDALj2aTPs+9xYa9+bG3tD60B8jzljHz7aRP+KNOjSkVWLjVb3/ubCK1sK9IRQq9qEmUv4RDsNuE
-SgMjGWdqb8FuvAY5N9GIIvejQjBAMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMB0G
-A1UdDgQWBBTmGHX/72DehKT1RsfeSlXjMjZ59TAKBggqhkjOPQQDAwNnADBkAjAmc0l6tqvmSfR9
-Uj/UQQSugEODZXW5hYA4O9Zv5JOGq4/nich/m35rChJVYaoR4HkCMHfoMXGsPHED1oQmHhS48zs7
-3u1Z/GtMMH9ZzkXpc2AVmkzw5l4lIhVtwodZ0LKOag==
------END CERTIFICATE-----
-
-CommScope Public Trust RSA Root-01
-==================================
------BEGIN CERTIFICATE-----
-MIIFbDCCA1SgAwIBAgIUPgNJgXUWdDGOTKvVxZAplsU5EN0wDQYJKoZIhvcNAQELBQAwTjELMAkG
-A1UEBhMCVVMxEjAQBgNVBAoMCUNvbW1TY29wZTErMCkGA1UEAwwiQ29tbVNjb3BlIFB1YmxpYyBU
-cnVzdCBSU0EgUm9vdC0wMTAeFw0yMTA0MjgxNjQ1NTRaFw00NjA0MjgxNjQ1NTNaME4xCzAJBgNV
-BAYTAlVTMRIwEAYDVQQKDAlDb21tU2NvcGUxKzApBgNVBAMMIkNvbW1TY29wZSBQdWJsaWMgVHJ1
-c3QgUlNBIFJvb3QtMDEwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQCwSGWjDR1C45Ft
-nYSkYZYSwu3D2iM0GXb26v1VWvZVAVMP8syMl0+5UMuzAURWlv2bKOx7dAvnQmtVzslhsuitQDy6
-uUEKBU8bJoWPQ7VAtYXR1HHcg0Hz9kXHgKKEUJdGzqAMxGBWBB0HW0alDrJLpA6lfO741GIDuZNq
-ihS4cPgugkY4Iw50x2tBt9Apo52AsH53k2NC+zSDO3OjWiE260f6GBfZumbCk6SP/F2krfxQapWs
-vCQz0b2If4b19bJzKo98rwjyGpg/qYFlP8GMicWWMJoKz/TUyDTtnS+8jTiGU+6Xn6myY5QXjQ/c
-Zip8UlF1y5mO6D1cv547KI2DAg+pn3LiLCuz3GaXAEDQpFSOm117RTYm1nJD68/A6g3czhLmfTif
-BSeolz7pUcZsBSjBAg/pGG3svZwG1KdJ9FQFa2ww8esD1eo9anbCyxooSU1/ZOD6K9pzg4H/kQO9
-lLvkuI6cMmPNn7togbGEW682v3fuHX/3SZtS7NJ3Wn2RnU3COS3kuoL4b/JOHg9O5j9ZpSPcPYeo
-KFgo0fEbNttPxP/hjFtyjMcmAyejOQoBqsCyMWCDIqFPEgkBEa801M/XrmLTBQe0MXXgDW1XT2mH
-+VepuhX2yFJtocucH+X8eKg1mp9BFM6ltM6UCBwJrVbl2rZJmkrqYxhTnCwuwwIDAQABo0IwQDAP
-BgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBBjAdBgNVHQ4EFgQUN12mmnQywsL5x6YVEFm4
-5P3luG0wDQYJKoZIhvcNAQELBQADggIBAK+nz97/4L1CjU3lIpbfaOp9TSp90K09FlxD533Ahuh6
-NWPxzIHIxgvoLlI1pKZJkGNRrDSsBTtXAOnTYtPZKdVUvhwQkZyybf5Z/Xn36lbQnmhUQo8mUuJM
-3y+Xpi/SB5io82BdS5pYV4jvguX6r2yBS5KPQJqTRlnLX3gWsWc+QgvfKNmwrZggvkN80V4aCRck
-jXtdlemrwWCrWxhkgPut4AZ9HcpZuPN4KWfGVh2vtrV0KnahP/t1MJ+UXjulYPPLXAziDslg+Mkf
-Foom3ecnf+slpoq9uC02EJqxWE2aaE9gVOX2RhOOiKy8IUISrcZKiX2bwdgt6ZYD9KJ0DLwAHb/W
-NyVntHKLr4W96ioDj8z7PEQkguIBpQtZtjSNMgsSDesnwv1B10A8ckYpwIzqug/xBpMu95yo9GA+
-o/E4Xo4TwbM6l4c/ksp4qRyv0LAbJh6+cOx69TOY6lz/KwsETkPdY34Op054A5U+1C0wlREQKC6/
-oAI+/15Z0wUOlV9TRe9rh9VIzRamloPh37MG88EU26fsHItdkJANclHnYfkUyq+Dj7+vsQpZXdxc
-1+SWrVtgHdqul7I52Qb1dgAT+GhMIbA1xNxVssnBQVocicCMb3SgazNNtQEo/a2tiRc7ppqEvOuM
-6sRxJKi6KfkIsidWNTJf6jn7MZrVGczw
------END CERTIFICATE-----
-
-CommScope Public Trust RSA Root-02
-==================================
------BEGIN CERTIFICATE-----
-MIIFbDCCA1SgAwIBAgIUVBa/O345lXGN0aoApYYNK496BU4wDQYJKoZIhvcNAQELBQAwTjELMAkG
-A1UEBhMCVVMxEjAQBgNVBAoMCUNvbW1TY29wZTErMCkGA1UEAwwiQ29tbVNjb3BlIFB1YmxpYyBU
-cnVzdCBSU0EgUm9vdC0wMjAeFw0yMTA0MjgxNzE2NDNaFw00NjA0MjgxNzE2NDJaME4xCzAJBgNV
-BAYTAlVTMRIwEAYDVQQKDAlDb21tU2NvcGUxKzApBgNVBAMMIkNvbW1TY29wZSBQdWJsaWMgVHJ1
-c3QgUlNBIFJvb3QtMDIwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDh+g77aAASyE3V
-rCLENQE7xVTlWXZjpX/rwcRqmL0yjReA61260WI9JSMZNRTpf4mnG2I81lDnNJUDMrG0kyI9p+Kx
-7eZ7Ti6Hmw0zdQreqjXnfuU2mKKuJZ6VszKWpCtYHu8//mI0SFHRtI1CrWDaSWqVcN3SAOLMV2MC
-e5bdSZdbkk6V0/nLKR8YSvgBKtJjCW4k6YnS5cciTNxzhkcAqg2Ijq6FfUrpuzNPDlJwnZXjfG2W
-Wy09X6GDRl224yW4fKcZgBzqZUPckXk2LHR88mcGyYnJ27/aaL8j7dxrrSiDeS/sOKUNNwFnJ5rp
-M9kzXzehxfCrPfp4sOcsn/Y+n2Dg70jpkEUeBVF4GiwSLFworA2iI540jwXmojPOEXcT1A6kHkIf
-hs1w/tkuFT0du7jyU1fbzMZ0KZwYszZ1OC4PVKH4kh+Jlk+71O6d6Ts2QrUKOyrUZHk2EOH5kQMr
-eyBUzQ0ZGshBMjTRsJnhkB4BQDa1t/qp5Xd1pCKBXbCL5CcSD1SIxtuFdOa3wNemKfrb3vOTlycE
-VS8KbzfFPROvCgCpLIscgSjX74Yxqa7ybrjKaixUR9gqiC6vwQcQeKwRoi9C8DfF8rhW3Q5iLc4t
-Vn5V8qdE9isy9COoR+jUKgF4z2rDN6ieZdIs5fq6M8EGRPbmz6UNp2YINIos8wIDAQABo0IwQDAP
-BgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBBjAdBgNVHQ4EFgQUR9DnsSL/nSz12Vdgs7Gx
-cJXvYXowDQYJKoZIhvcNAQELBQADggIBAIZpsU0v6Z9PIpNojuQhmaPORVMbc0RTAIFhzTHjCLqB
-KCh6krm2qMhDnscTJk3C2OVVnJJdUNjCK9v+5qiXz1I6JMNlZFxHMaNlNRPDk7n3+VGXu6TwYofF
-1gbTl4MgqX67tiHCpQ2EAOHyJxCDut0DgdXdaMNmEMjRdrSzbymeAPnCKfWxkxlSaRosTKCL4BWa
-MS/TiJVZbuXEs1DIFAhKm4sTg7GkcrI7djNB3NyqpgdvHSQSn8h2vS/ZjvQs7rfSOBAkNlEv41xd
-gSGn2rtO/+YHqP65DSdsu3BaVXoT6fEqSWnHX4dXTEN5bTpl6TBcQe7rd6VzEojov32u5cSoHw2O
-HG1QAk8mGEPej1WFsQs3BWDJVTkSBKEqz3EWnzZRSb9wO55nnPt7eck5HHisd5FUmrh1CoFSl+Nm
-YWvtPjgelmFV4ZFUjO2MJB+ByRCac5krFk5yAD9UG/iNuovnFNa2RU9g7Jauwy8CTl2dlklyALKr
-dVwPaFsdZcJfMw8eD/A7hvWwTruc9+olBdytoptLFwG+Qt81IR2tq670v64fG9PiO/yzcnMcmyiQ
-iRM9HcEARwmWmjgb3bHPDcK0RPOWlc4yOo80nOAXx17Org3bhzjlP1v9mxnhMUF6cKojawHhRUzN
-lM47ni3niAIi9G7oyOzWPPO5std3eqx7
------END CERTIFICATE-----
-
 Telekom Security TLS ECC Root 2020
 ==================================
 -----BEGIN CERTIFICATE-----

data/lib/excon/connection.rb

@@ -60,6 +60,8 @@ module Excon
     # @option params [Fixnum] :retry_interval Set how long to wait between retries. (Default 0)
     # @option params [Class] :instrumentor Responds to #instrument as in ActiveSupport::Notifications
     # @option params [String] :instrumentor_name Name prefix for #instrument events.  Defaults to 'excon'
+    # @option params [Resolv, nil] :resolv_resolver A ready to use +Resolv+ resolver instance.
+    # @option params [Class] :resolver_factory Const of the resolver factory.  Defaults to 'Excon::ResolverFactory'
     def initialize(params = {})
       @pid = Process.pid
       @data = Excon.defaults.dup
@@ -483,6 +485,13 @@ module Excon
       unix_proxy = datum[:proxy] ? datum[:proxy][:scheme] == UNIX : false
       sockets[@socket_key] ||= if datum[:scheme] == UNIX || unix_proxy
         Excon::UnixSocket.new(datum)
+      elsif datum[:socks5_proxy]
+        # SOCKS5 proxy - use appropriate socket based on target scheme
+        if datum[:ssl_uri_schemes].include?(datum[:scheme])
+          Excon::SOCKS5SSLSocket.new(datum)
+        else
+          Excon::SOCKS5Socket.new(datum)
+        end
       elsif datum[:ssl_uri_schemes].include?(datum[:scheme])
         Excon::SSLSocket.new(datum)
       else

data/lib/excon/constants.rb

@@ -60,6 +60,7 @@ module Excon
     read_timeout
     request_block
     resolv_resolver
+    resolver_factory
     response_block
     stubs
     timeout
@@ -97,6 +98,7 @@ module Excon
     proxy
     scheme
     socket
+    socks5_proxy
     ssl_ca_file
     ssl_ca_path
     ssl_cert_store
@@ -170,6 +172,7 @@ module Excon
     persistent: false,
     read_timeout: 60,
     resolv_resolver: nil,
+    resolver_factory: Excon::ResolverFactory,
     retry_errors: DEFAULT_RETRY_ERRORS,
     retry_limit: DEFAULT_RETRY_LIMIT,
     ssl_verify_peer: true,

data/lib/excon/resolver_factory.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+module Excon
+  # This factory produces new +resolv+ gem resolver instances. Users who wants
+  # to configure a custom resolver (varying settings for varying resolvers) can
+  # provide a custom resolver factory class and configure it globally on the
+  # Excon defaults:
+  #
+  #   Excon.defaults[:resolver_factory] = MyCustomResolverFactory
+  #
+  # Then you just need to provide a static method called +.create_resolver+
+  # which returns a new +Resolv+ instance. This allows the customization.
+  class ResolverFactory
+    # @return [Resolv] the new resolver instance
+    def self.create_resolver
+      Resolv.new
+    end
+  end
+end

data/lib/excon/socket.rb

@@ -132,7 +132,7 @@ module Excon
         family = @data[:proxy][:family]
       end
 
-      resolver = @data[:resolv_resolver] || Resolv.new
+      resolver = @data[:resolv_resolver] || @data[:resolver_factory].create_resolver
 
       # Deprecated
       if @data[:dns_timeouts]
@@ -252,15 +252,11 @@ module Excon
             end
           end
         end
-      rescue OpenSSL::SSL::SSLError => error
-        if error.message == 'read would block'
-          if @read_buffer.empty?
-            select_with_timeout(@socket, :read) && retry
-          end
-        else
-          raise(error)
-        end
-      rescue *READ_RETRY_EXCEPTION_CLASSES
+      rescue OpenSSL::SSL::SSLError => e
+        raise(e) unless e.message == 'read would block'
+
+        select_with_timeout(@socket, :read) && retry if @read_buffer.empty?
+      rescue *READ_RETRY_EXCEPTION_CLASSES => e
         if @read_buffer.empty?
           # if we didn't read anything, try again...
           select_with_timeout(@socket, :read) && retry
@@ -299,12 +295,10 @@ module Excon
 
     def read_block(max_length)
       @socket.read(max_length)
-    rescue OpenSSL::SSL::SSLError => error
-      if error.message == 'read would block'
-        select_with_timeout(@socket, :read) && retry
-      else
-        raise(error)
-      end
+    rescue OpenSSL::SSL::SSLError => e
+      select_with_timeout(@socket, :read) && retry if e.message == 'read would block'
+
+      raise(error)
     rescue *READ_RETRY_EXCEPTION_CLASSES
       select_with_timeout(@socket, :read) && retry
     rescue EOFError
@@ -327,12 +321,10 @@ module Excon
           else
             raise error
           end
-        rescue OpenSSL::SSL::SSLError, *WRITE_RETRY_EXCEPTION_CLASSES => error
-          if error.is_a?(OpenSSL::SSL::SSLError) && error.message != 'write would block'
-            raise error
-          else
-            select_with_timeout(@socket, :write) && retry
-          end
+        rescue OpenSSL::SSL::SSLError, *WRITE_RETRY_EXCEPTION_CLASSES => e
+          raise e if error.is_a?(OpenSSL::SSL::SSLError) && e.message != 'write would block'
+
+          select_with_timeout(@socket, :write) && retry
         end
 
         # Fast, common case.
@@ -348,12 +340,10 @@ module Excon
 
     def write_block(data)
       @socket.write(data)
-    rescue OpenSSL::SSL::SSLError, *WRITE_RETRY_EXCEPTION_CLASSES => error
-      if error.is_a?(OpenSSL::SSL::SSLError) && error.message != 'write would block'
-        raise error
-      else
-        select_with_timeout(@socket, :write) && retry
-      end
+    rescue OpenSSL::SSL::SSLError, *WRITE_RETRY_EXCEPTION_CLASSES => e
+      raise e if e.is_a?(OpenSSL::SSL::SSLError) && e.message != 'write would block'
+
+      select_with_timeout(@socket, :write) && retry
     end
 
     def select_with_timeout(socket, type)
@@ -373,25 +363,19 @@ module Excon
       end
 
       select = case type
-      when :connect_read
-        IO.select([socket], nil, nil, timeout)
-      when :connect_write
-        IO.select(nil, [socket], nil, timeout)
-      when :read
-        IO.select([socket], nil, nil, timeout)
-      when :write
-        IO.select(nil, [socket], nil, timeout)
-      end
+               when :connect_read, :read
+                 IO.select([socket], nil, nil, timeout)
+               when :connect_write, :write
+                 IO.select(nil, [socket], nil, timeout)
+               end
 
-      select || raise(Excon::Errors::Timeout.new("#{timeout_kind} timeout reached"))
+      select || raise(Excon::Errors::Timeout.new, "#{timeout_kind} timeout reached")
     end
 
     def unpacked_sockaddr
       @unpacked_sockaddr ||= ::Socket.unpack_sockaddr_in(@socket.to_io.getsockname)
     rescue ArgumentError => e
-      unless e.message == 'not an AF_INET/AF_INET6 sockaddr'
-        raise
-      end
+      raise unless e.message == 'not an AF_INET/AF_INET6 sockaddr'
     end
 
     # Returns the remaining time in seconds until we reach the deadline for the request timeout.

data/lib/excon/socks5.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Excon
+  # SOCKS5 protocol implementation (RFC 1928, RFC 1929)
+  # Shared module for SOCKS5Socket and SOCKS5SSLSocket
+  module SOCKS5
+    SOCKS5_VERSION = 0x05
+    SOCKS5_RESERVED = 0x00
+
+    # Authentication methods
+    SOCKS5_NO_AUTH = 0x00
+    SOCKS5_AUTH_USERNAME_PASSWORD = 0x02
+    SOCKS5_NO_ACCEPTABLE_AUTH = 0xFF
+
+    # Commands
+    SOCKS5_CMD_CONNECT = 0x01
+
+    # Address types
+    SOCKS5_ATYP_IPV4 = 0x01
+    SOCKS5_ATYP_DOMAIN = 0x03
+    SOCKS5_ATYP_IPV6 = 0x04
+
+    # Reply codes
+    SOCKS5_SUCCESS = 0x00
+    SOCKS5_ERRORS = {
+      0x01 => 'General SOCKS server failure',
+      0x02 => 'Connection not allowed by ruleset',
+      0x03 => 'Network unreachable',
+      0x04 => 'Host unreachable',
+      0x05 => 'Connection refused',
+      0x06 => 'TTL expired',
+      0x07 => 'Command not supported',
+      0x08 => 'Address type not supported'
+    }.freeze
+
+    # Maximum hostname length per RFC 1928
+    MAX_HOSTNAME_LENGTH = 255
+
+    private
+
+    # Parse SOCKS5 proxy string into components
+    # @param proxy_string [String] Proxy specification in various formats
+    # @return [Array<String, String, String, String>] host, port, user, pass
+    def parse_socks5_proxy(proxy_string)
+      # Support formats:
+      #   host:port
+      #   user:pass@host:port
+      #   socks5://host:port
+      #   socks5://user:pass@host:port
+      proxy_string = proxy_string.to_s.sub(%r{^socks5://}, '')
+
+      user = nil
+      pass = nil
+
+      if proxy_string.include?('@')
+        auth, host_port = proxy_string.split('@', 2)
+        user, pass = auth.split(':', 2)
+      else
+        host_port = proxy_string
+      end
+
+      host, port = host_port.split(':', 2)
+      port ||= '1080'
+
+      [host, port, user, pass]
+    end
+
+    # Perform SOCKS5 authentication handshake
+    def socks5_authenticate
+      auth_methods = if @proxy_user && @proxy_pass
+        [SOCKS5_NO_AUTH, SOCKS5_AUTH_USERNAME_PASSWORD]
+      else
+        [SOCKS5_NO_AUTH]
+      end
+
+      greeting = [SOCKS5_VERSION, auth_methods.length, *auth_methods].pack('C*')
+      @socket.write(greeting)
+
+      response = socks5_read_exactly(2)
+      version, chosen_method = response.unpack('CC')
+
+      if version != SOCKS5_VERSION
+        raise Excon::Error::Socket.new(Exception.new("SOCKS5 proxy returned invalid version: #{version}"))
+      end
+
+      case chosen_method
+      when SOCKS5_NO_AUTH
+        # 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'))
+        end
+        socks5_username_password_auth
+      when SOCKS5_NO_ACCEPTABLE_AUTH
+        raise Excon::Error::Socket.new(Exception.new('SOCKS5 proxy: no acceptable authentication methods'))
+      else
+        raise Excon::Error::Socket.new(Exception.new("SOCKS5 proxy: unsupported authentication method #{chosen_method}"))
+      end
+    end
+
+    # RFC 1929: Username/Password Authentication
+    def socks5_username_password_auth
+      auth_request = [
+        0x01, # auth protocol version
+        @proxy_user.bytesize,
+        @proxy_user,
+        @proxy_pass.bytesize,
+        @proxy_pass
+      ].pack('CCA*CA*')
+
+      @socket.write(auth_request)
+
+      response = socks5_read_exactly(2)
+      _, status = response.unpack('CC')
+
+      unless status == 0x00
+        raise Excon::Error::Socket.new(Exception.new('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"))
+      end
+
+      # Build CONNECT request with domain name (let proxy resolve DNS)
+      request = [SOCKS5_VERSION, SOCKS5_CMD_CONNECT, SOCKS5_RESERVED].pack('CCC')
+      request += [SOCKS5_ATYP_DOMAIN, host.bytesize, host].pack('CCA*')
+      request += [port.to_i].pack('n')
+
+      @socket.write(request)
+
+      response = socks5_read_exactly(4)
+      version, reply, _, atyp = response.unpack('CCCC')
+
+      if version != SOCKS5_VERSION
+        raise Excon::Error::Socket.new(Exception.new("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}"))
+      end
+
+      # Read and discard bound address (not needed for CONNECT)
+      socks5_read_bound_address(atyp)
+    end
+
+    def socks5_read_bound_address(atyp)
+      case atyp
+      when SOCKS5_ATYP_IPV4
+        socks5_read_exactly(4 + 2) # 4 bytes IP + 2 bytes port
+      when SOCKS5_ATYP_DOMAIN
+        domain_len = socks5_read_exactly(1).unpack1('C')
+        socks5_read_exactly(domain_len + 2)
+      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}"))
+      end
+    end
+
+    # Read exact number of bytes with timeout support
+    def socks5_read_exactly(nbytes)
+      data = ''.dup
+      deadline = @data[:read_timeout] ? Time.now + @data[:read_timeout] : nil
+
+      while data.bytesize < nbytes
+        if deadline
+          remaining = deadline - Time.now
+          if remaining <= 0
+            raise Excon::Error::Timeout.new('SOCKS5 read timeout')
+          end
+          ready = IO.select([@socket], nil, nil, remaining)
+          unless ready
+            raise Excon::Error::Timeout.new('SOCKS5 read timeout')
+          end
+        end
+
+        chunk = @socket.read_nonblock(nbytes - data.bytesize, exception: false)
+        case chunk
+        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'))
+        else
+          data << chunk
+        end
+      end
+      data
+    end
+  end
+end

data/lib/excon/socks5_socket.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Excon
+  class SOCKS5Socket < Socket
+    include SOCKS5
+
+    def initialize(data = {})
+      @socks5_proxy = data[:socks5_proxy]
+      @proxy_host, @proxy_port, @proxy_user, @proxy_pass = parse_socks5_proxy(@socks5_proxy)
+      super(data)
+    end
+
+    private
+
+    # Proxy-swap pattern: temporarily set @data[:proxy] to the SOCKS5 proxy
+    # so that Socket#connect routes the TCP connection there (inheriting DNS
+    # resolution, nonblock, retry, keepalive, reuseaddr, remote_ip tracking).
+    # After TCP is up, clear :proxy and run the SOCKS5 handshake.
+    def connect
+      @data[:proxy] = {
+        host:     @proxy_host,
+        hostname: @proxy_host,
+        port:     @proxy_port.to_i
+      }
+
+      begin
+        super
+      ensure
+        @data.delete(:proxy)
+      end
+
+      socks5_authenticate
+      socks5_connect(@data[:host], @data[:port])
+    end
+  end
+end

data/lib/excon/socks5_ssl_socket.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Excon
+  class SOCKS5SSLSocket < SSLSocket
+    include SOCKS5
+
+    def initialize(data = {})
+      @socks5_proxy = data[:socks5_proxy]
+      @proxy_host, @proxy_port, @proxy_user, @proxy_pass = parse_socks5_proxy(@socks5_proxy)
+      super(data)
+    end
+
+    private
+
+    # Proxy-swap pattern (same as SOCKS5Socket#connect).
+    #
+    # Call chain:
+    #   SOCKS5SSLSocket#initialize -> super (SSLSocket#initialize)
+    #     -> super (Socket#initialize) -> connect
+    #       -> SOCKS5SSLSocket#connect (this method)
+    #         -> super -> SSLSocket#connect -> Socket#connect (TCP to proxy)
+    #       -> SOCKS5 handshake on raw TCP socket
+    #     <- returns to SSLSocket#initialize
+    #     -> @data[:proxy] is nil, so HTTP CONNECT is skipped (line 111)
+    #     -> SSL wrapping on the SOCKS5-tunneled socket
+    def connect
+      @data[:proxy] = {
+        host:     @proxy_host,
+        hostname: @proxy_host,
+        port:     @proxy_port.to_i
+      }
+
+      begin
+        super
+      ensure
+        # Clear :proxy so SSLSocket#initialize skips HTTP CONNECT (line 111)
+        @data.delete(:proxy)
+      end
+
+      socks5_authenticate
+      socks5_connect(@data[:host], @data[:port])
+    end
+  end
+end

data/lib/excon/test/plugin/server/webrick.rb

@@ -10,7 +10,7 @@ module Excon
             open_process(RbConfig.ruby, '-S', 'rackup', '-s', 'webrick', '--host', host, '--port', port, app_str)
             process_stderr = ""
             line = ''
-            until line.include?('HTTPServer#start')
+            until line.include?('Server#start')
               line = error.gets
               raise process_stderr if line.nil?
               process_stderr << line

data/lib/excon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Excon
-  VERSION = '1.3.1'
+  VERSION = '1.4.0'
 end

data/lib/excon.rb

@@ -27,6 +27,7 @@ require 'excon/middlewares/mock'
 require 'excon/middlewares/response_parser'
 
 require 'excon/error'
+require 'excon/resolver_factory'
 require 'excon/constants'
 require 'excon/utils'
 
@@ -39,6 +40,9 @@ require 'excon/middlewares/capture_cookies'
 require 'excon/pretty_printer'
 require 'excon/socket'
 require 'excon/ssl_socket'
+require 'excon/socks5'
+require 'excon/socks5_socket'
+require 'excon/socks5_ssl_socket'
 require 'excon/instrumentors/standard_instrumentor'
 require 'excon/instrumentors/logging_instrumentor'
 require 'excon/unix_socket'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: excon
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - dpiddy (Dan Peterson)
@@ -241,8 +241,12 @@ files:
 - lib/excon/middlewares/redirect_follower.rb
 - lib/excon/middlewares/response_parser.rb
 - lib/excon/pretty_printer.rb
+- lib/excon/resolver_factory.rb
 - lib/excon/response.rb
 - lib/excon/socket.rb
+- lib/excon/socks5.rb
+- lib/excon/socks5_socket.rb
+- lib/excon/socks5_ssl_socket.rb
 - lib/excon/ssl_socket.rb
 - lib/excon/test/plugin/server/exec.rb
 - lib/excon/test/plugin/server/puma.rb
@@ -278,7 +282,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: speed, persistence, http(s)
 test_files: []