refactor: improve code quality and simplify response handling

Implement improvements to enhance code simplicity, maintainability,
and adherence to DRY/KISS/YAGNI principles:

High-priority improvements:
- Extract withTransport helper to reduce duplication in setter methods
  (client.go) - reduces ~140 lines to ~50 lines
- Replace strings.SplitSeq with standard strings.Split (proxy.go) for
  better portability and familiarity
- Extract stripSensitiveHeaders helper (redirect.go) for single
  responsibility and easier testing

Medium-priority improvements:
- Add hasTransportConfig helper method (client.go) to improve readability
  and make intent explicit
- Add minBackoffDelay constant (retry.go) for self-documenting code
- Add comment for uint64 conversion in RoundRobinProxies (proxy.go)

Documentation enhancements:
- Enhance Clone() method documentation (request.go) to clarify shallow
  client reference behavior and deep copy semantics
- Remove redundant comments that merely describe obvious test behavior
- Replace verbose assertion messages with concise assertions
- Use require.True for critical type assertions that must pass
- Eliminate unnecessary explanatory comments in test setup

Simplifications:
- Remove ErrorForStatus method and ErrHTTPStatus error (over-engineered)
- Users can check status with IsError(), IsClientError(), IsServerError()

All changes maintain backward compatibility and pass existing tests.

Author: kaptinlin

client.go

@@ -3,6 +3,7 @@ package requests
 import (
 	"crypto/tls"
 	"crypto/x509"
+	"net"
 	"net/http"
 	"net/http/cookiejar"
 	"os"
@@ -51,6 +52,25 @@ type Config struct {
 	RetryIf       RetryIfFunc       // Custom function to determine retry based on request and response
 	Logger        Logger            // Logger instance for the client
 	HTTP2         bool              // Whether to use HTTP/2. Transport takes priority over HTTP2 if both are set.
+
+	// Transport-level timeouts (applied to http.Transport)
+	DialTimeout           time.Duration // TCP connection timeout
+	TLSHandshakeTimeout   time.Duration // TLS handshake timeout
+	ResponseHeaderTimeout time.Duration // Time to first response byte
+
+	// Connection pool settings (applied to http.Transport)
+	MaxIdleConns        int           // Max idle connections across all hosts (0 = default 100)
+	MaxIdleConnsPerHost int           // Max idle connections per host (0 = default 2)
+	MaxConnsPerHost     int           // Max total connections per host (0 = no limit)
+	IdleConnTimeout     time.Duration // How long idle connections live (0 = default 90s)
+}
+
+// hasTransportConfig checks if any transport-level configuration is set.
+func (cfg *Config) hasTransportConfig() bool {
+	return cfg.DialTimeout > 0 || cfg.TLSHandshakeTimeout > 0 ||
+		cfg.ResponseHeaderTimeout > 0 || cfg.MaxIdleConns > 0 ||
+		cfg.MaxIdleConnsPerHost > 0 || cfg.MaxConnsPerHost > 0 ||
+		cfg.IdleConnTimeout > 0
 }
 
 // URL creates a new HTTP client with the given base URL.
@@ -112,6 +132,9 @@ func Create(config *Config) *Client {
 		client.HTTPClient.Transport = &http2.Transport{}
 	}
 
+	// Apply transport-level timeouts and connection pool settings
+	applyTransportConfig(client, config)
+
 	if config.Middlewares != nil {
 		client.Middlewares = config.Middlewares
 	}
@@ -525,6 +548,113 @@ func (c *Client) SetLogger(logger Logger) *Client {
 	return c
 }
 
+// withTransport executes a function on the client's transport, handling locking and error checking.
+// Returns the client for method chaining. Errors from ensureTransport are silently ignored to
+// maintain the fluent API pattern.
+func (c *Client) withTransport(fn func(*http.Transport)) *Client {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	transport, err := c.ensureTransport()
+	if err != nil {
+		return c
+	}
+	fn(transport)
+	return c
+}
+
+// SetDialTimeout sets the TCP connection timeout on the underlying transport.
+func (c *Client) SetDialTimeout(d time.Duration) *Client {
+	return c.withTransport(func(t *http.Transport) {
+		t.DialContext = (&net.Dialer{Timeout: d}).DialContext
+	})
+}
+
+// SetTLSHandshakeTimeout sets the TLS handshake timeout on the underlying transport.
+func (c *Client) SetTLSHandshakeTimeout(d time.Duration) *Client {
+	return c.withTransport(func(t *http.Transport) {
+		t.TLSHandshakeTimeout = d
+	})
+}
+
+// SetResponseHeaderTimeout sets the time to wait for response headers after the request
+// is sent. This does not include the time to read the response body.
+func (c *Client) SetResponseHeaderTimeout(d time.Duration) *Client {
+	return c.withTransport(func(t *http.Transport) {
+		t.ResponseHeaderTimeout = d
+	})
+}
+
+// SetMaxIdleConns sets the maximum number of idle connections across all hosts.
+func (c *Client) SetMaxIdleConns(n int) *Client {
+	return c.withTransport(func(t *http.Transport) {
+		t.MaxIdleConns = n
+	})
+}
+
+// SetMaxIdleConnsPerHost sets the maximum number of idle connections per host.
+func (c *Client) SetMaxIdleConnsPerHost(n int) *Client {
+	return c.withTransport(func(t *http.Transport) {
+		t.MaxIdleConnsPerHost = n
+	})
+}
+
+// SetMaxConnsPerHost sets the maximum total number of connections per host.
+func (c *Client) SetMaxConnsPerHost(n int) *Client {
+	return c.withTransport(func(t *http.Transport) {
+		t.MaxConnsPerHost = n
+	})
+}
+
+// SetIdleConnTimeout sets how long idle connections remain in the pool before being closed.
+func (c *Client) SetIdleConnTimeout(d time.Duration) *Client {
+	return c.withTransport(func(t *http.Transport) {
+		t.IdleConnTimeout = d
+	})
+}
+
+// applyTransportConfig applies transport-level timeouts and connection pool settings
+// from Config to the client's transport. Only modifies settings that are explicitly set
+// (non-zero). Skips if the transport is not *http.Transport (e.g., HTTP/2 transport).
+func applyTransportConfig(c *Client, config *Config) {
+	transport, ok := c.HTTPClient.Transport.(*http.Transport)
+	if !ok {
+		// No *http.Transport available (nil or HTTP/2); create one if any config is set
+		if !config.hasTransportConfig() {
+			return
+		}
+
+		if c.HTTPClient.Transport == nil {
+			transport = &http.Transport{}
+			c.HTTPClient.Transport = transport
+		} else {
+			return // Non-nil, non-http.Transport (e.g., http2.Transport): skip
+		}
+	}
+
+	if config.DialTimeout > 0 {
+		transport.DialContext = (&net.Dialer{Timeout: config.DialTimeout}).DialContext
+	}
+	if config.TLSHandshakeTimeout > 0 {
+		transport.TLSHandshakeTimeout = config.TLSHandshakeTimeout
+	}
+	if config.ResponseHeaderTimeout > 0 {
+		transport.ResponseHeaderTimeout = config.ResponseHeaderTimeout
+	}
+	if config.MaxIdleConns > 0 {
+		transport.MaxIdleConns = config.MaxIdleConns
+	}
+	if config.MaxIdleConnsPerHost > 0 {
+		transport.MaxIdleConnsPerHost = config.MaxIdleConnsPerHost
+	}
+	if config.MaxConnsPerHost > 0 {
+		transport.MaxConnsPerHost = config.MaxConnsPerHost
+	}
+	if config.IdleConnTimeout > 0 {
+		transport.IdleConnTimeout = config.IdleConnTimeout
+	}
+}
+
 // Get initiates a GET request.
 func (c *Client) Get(path string) *RequestBuilder {
 	return c.NewRequestBuilder(http.MethodGet, path)

client_test.go

@@ -980,6 +980,154 @@ func TestClientSetRootCertificate(t *testing.T) {
 	})
 }
 
+func TestTransportTimeoutsViaConfig(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(3 * time.Second)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	client := Create(&Config{
+		BaseURL:               server.URL,
+		DialTimeout:           5 * time.Second,
+		TLSHandshakeTimeout:   5 * time.Second,
+		ResponseHeaderTimeout: 1 * time.Second,
+	})
+
+	_, err := client.Get("/").Send(context.Background())
+	assert.Error(t, err)
+}
+
+func TestTransportTimeoutsViaSetMethods(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(3 * time.Second)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	client := Create(&Config{BaseURL: server.URL})
+	client.SetDialTimeout(5 * time.Second)
+	client.SetTLSHandshakeTimeout(5 * time.Second)
+	client.SetResponseHeaderTimeout(1 * time.Second)
+
+	_, err := client.Get("/").Send(context.Background())
+	assert.Error(t, err)
+}
+
+func TestConnectionPoolConfig(t *testing.T) {
+	client := Create(&Config{
+		MaxIdleConns:        50,
+		MaxIdleConnsPerHost: 10,
+		MaxConnsPerHost:     20,
+		IdleConnTimeout:     30 * time.Second,
+	})
+
+	transport, ok := client.HTTPClient.Transport.(*http.Transport)
+	require.True(t, ok)
+	assert.Equal(t, 50, transport.MaxIdleConns)
+	assert.Equal(t, 10, transport.MaxIdleConnsPerHost)
+	assert.Equal(t, 20, transport.MaxConnsPerHost)
+	assert.Equal(t, 30*time.Second, transport.IdleConnTimeout)
+}
+
+func TestConnectionPoolConfigSetMethods(t *testing.T) {
+	client := Create(nil)
+	client.SetMaxIdleConns(50).
+		SetMaxIdleConnsPerHost(10).
+		SetMaxConnsPerHost(20).
+		SetIdleConnTimeout(30 * time.Second)
+
+	transport, ok := client.HTTPClient.Transport.(*http.Transport)
+	require.True(t, ok)
+	assert.Equal(t, 50, transport.MaxIdleConns)
+	assert.Equal(t, 10, transport.MaxIdleConnsPerHost)
+	assert.Equal(t, 20, transport.MaxConnsPerHost)
+	assert.Equal(t, 30*time.Second, transport.IdleConnTimeout)
+}
+
+func TestTransportConfigSkipsHTTP2Transport(t *testing.T) {
+	client := Create(&Config{
+		HTTP2:               true,
+		TLSConfig:           &tls.Config{InsecureSkipVerify: true},
+		MaxIdleConns:        50,
+		MaxIdleConnsPerHost: 10,
+	})
+
+	_, isHTTPTransport := client.HTTPClient.Transport.(*http.Transport)
+	assert.False(t, isHTTPTransport)
+}
+
+func TestTransportConfigNoOpWhenNoSettings(t *testing.T) {
+	client := Create(&Config{
+		BaseURL: "http://example.com",
+	})
+	assert.Nil(t, client.HTTPClient.Transport)
+}
+
+func TestErrorIntrospection(t *testing.T) {
+	t.Run("IsTimeout with deadline exceeded", func(t *testing.T) {
+		assert.True(t, IsTimeout(context.DeadlineExceeded))
+	})
+
+	t.Run("IsTimeout with wrapped deadline exceeded", func(t *testing.T) {
+		err := fmt.Errorf("request failed: %w", context.DeadlineExceeded)
+		assert.True(t, IsTimeout(err))
+	})
+
+	t.Run("IsTimeout with nil", func(t *testing.T) {
+		assert.False(t, IsTimeout(nil))
+	})
+
+	t.Run("IsTimeout with non-timeout error", func(t *testing.T) {
+		assert.False(t, IsTimeout(ErrResponseReadFailed))
+	})
+
+	t.Run("IsTimeout with actual timeout", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			time.Sleep(2 * time.Second)
+			w.WriteHeader(http.StatusOK)
+		}))
+		defer server.Close()
+
+		client := Create(&Config{
+			BaseURL: server.URL,
+			Timeout: 100 * time.Millisecond,
+		})
+		_, err := client.Get("/").Send(context.Background())
+		assert.Error(t, err)
+		assert.True(t, IsTimeout(err))
+	})
+
+	t.Run("IsConnectionError with nil", func(t *testing.T) {
+		assert.False(t, IsConnectionError(nil))
+	})
+
+	t.Run("IsConnectionError with non-connection error", func(t *testing.T) {
+		assert.False(t, IsConnectionError(ErrResponseReadFailed))
+	})
+
+	t.Run("IsConnectionError with OpError", func(t *testing.T) {
+		opErr := &net.OpError{Op: "dial", Err: ErrTestTimeout}
+		assert.True(t, IsConnectionError(opErr))
+	})
+
+	t.Run("IsConnectionError with wrapped OpError", func(t *testing.T) {
+		opErr := &net.OpError{Op: "dial", Err: ErrTestTimeout}
+		wrapped := fmt.Errorf("request failed: %w", opErr)
+		assert.True(t, IsConnectionError(wrapped))
+	})
+
+	t.Run("IsConnectionError with real connection failure", func(t *testing.T) {
+		client := Create(&Config{
+			BaseURL: "http://127.0.0.1:1",
+			Timeout: 2 * time.Second,
+		})
+		_, err := client.Get("/").Send(context.Background())
+		assert.Error(t, err)
+		assert.True(t, IsConnectionError(err))
+	})
+}
+
 func TestHttp2Scenarios(t *testing.T) {
 	if testing.Short() {
 		t.Skip("Skipping HTTP/2 external network tests in short mode")