Documentation
¶
Overview ¶
Package http provides an enhanced HTTP client with built-in support for authentication, retries, tracing, and middleware.
The client supports multiple authentication methods (Basic, Digest, NTLM, OAuth), automatic retries with exponential backoff, request/response tracing, and a flexible middleware system.
Basic Usage:
client := http.NewClient()
resp, err := client.R(context.Background()).GET("https://api.example.com/data")
With Authentication:
client := http.NewClient().
Auth("username", "password").
Digest(true)
With Retries and Timeout:
client := http.NewClient(). Retry(3, time.Second, 2.0). Timeout(30 * time.Second)
With Request Tracing:
client := http.NewClient(). Trace(http.TraceAll) // Log full request/response details
The client can also be used as a standard http.RoundTripper:
httpClient := &http.Client{
Transport: http.NewClient().Auth("user", "pass").RoundTripper(),
}
Index ¶
- Variables
- func Error(span trace.Span, err error) bool
- type AuthConfig
- type Client
- func (c *Client) Auth(username, password string) *Client
- func (c *Client) BaseURL(url string) *Client
- func (c *Client) CacheDNS(val bool) *Client
- func (c *Client) ConnectTo(host string) *Client
- func (c *Client) Digest(val bool) *Client
- func (c *Client) DisableKeepAlive(val bool) *Client
- func (c *Client) Header(key, val string) *Client
- func (c *Client) InsecureSkipVerify(val bool) *Client
- func (c *Client) NTLM(val bool) *Client
- func (c *Client) NTLMV2(val bool) *Client
- func (c *Client) OAuth(config middlewares.OauthConfig) *Client
- func (c *Client) Proxy(url string) *Client
- func (c *Client) R(ctx context.Context) *Request
- func (c *Client) Retry(maxRetries uint, baseDuration time.Duration, exponent float64) *Client
- func (c *Client) RoundTrip(r *http.Request) (*http.Response, error)
- func (c *Client) RoundTripper() http.RoundTripper
- func (c *Client) TLSConfig(conf TLSConfig) (*Client, error)
- func (c *Client) Timeout(d time.Duration) *Client
- func (c *Client) Trace(config TraceConfig) *Client
- func (c *Client) TraceToStdout(config TraceConfig) *Client
- func (c *Client) Use(middlewares ...middlewares.Middleware) *Client
- func (c *Client) UserAgent(agent string) *Client
- func (c *Client) WithHttpLogging(headerLevel, bodyLevel logger.LogLevel) *Client
- type OauthConfig
- type Request
- func (r *Request) Body(v any) error
- func (r *Request) Debug() string
- func (r *Request) Delete(url string) (*Response, error)
- func (r *Request) Do(method, reqURL string) (resp *Response, err error)
- func (r *Request) Get(url string) (*Response, error)
- func (r *Request) GetHeader(key string) string
- func (r *Request) GetHeaders() map[string]string
- func (r *Request) Header(key, value string) *Request
- func (r *Request) HeaderMap() map[string]string
- func (r *Request) Patch(url string, body any) (*Response, error)
- func (r *Request) Post(url string, body any) (*Response, error)
- func (r *Request) Put(url string, body any) (*Response, error)
- func (r *Request) QueryParam(key, value string) *Request
- func (r *Request) QueryParamAdd(key, value string) *Request
- func (r *Request) Retry(maxRetries uint, baseDuration time.Duration, exponent float64) *Request
- type Response
- func (h *Response) AsJSON() (map[string]any, error)
- func (h *Response) AsMap() (map[string]any, error)
- func (r *Response) AsString() (string, error)
- func (h *Response) Debug() string
- func (r *Response) GetHeaders() map[string]string
- func (h *Response) GetSSLAge() *time.Duration
- func (h *Response) HeaderMap() map[string]string
- func (r *Response) Into(dest any) error
- func (h *Response) IsJSON() bool
- func (r *Response) IsOK(responseCodes ...int) bool
- type RetryConfig
- type TLSConfig
- type TraceConfig
Constants ¶
This section is empty.
Variables ¶
var AuthStyleAutoDetect = middlewares.AuthStyleAutoDetect
var AuthStyleInHeader = middlewares.AuthStyleInHeader
var AuthStyleInParams = middlewares.AuthStyleInParams
var TraceAll = TraceConfig{ MaxBodyLength: 4096, Body: true, Response: true, QueryParam: true, Headers: true, ResponseHeaders: true, TLS: true, }
var TraceHeaders = TraceConfig{ Body: false, Response: false, QueryParam: true, Headers: true, ResponseHeaders: true, TLS: false, }
Functions ¶
Types ¶
type AuthConfig ¶ added in v1.13.0
type AuthConfig struct {
// Username for basic Auth
Username string
// Password for basic Auth
Password string
// Use digest access authentication
Digest bool
// Ntlm controls whether to use NTLM
Ntlm bool
// Ntlmv2 controls whether to use NTLMv2
Ntlmv2 bool
}
func (*AuthConfig) IsEmpty ¶ added in v1.16.0
func (a *AuthConfig) IsEmpty() bool
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is an enhanced HTTP client with built-in support for authentication, retries, tracing, and middleware. It provides a fluent API for configuring requests and can be used as a drop-in replacement for http.Client.
Example:
client := http.NewClient().
Auth("user", "pass").
Retry(3, time.Second, 2.0).
Trace(http.TraceHeaders).
Timeout(30 * time.Second)
resp, err := client.R(ctx).
GET("https://api.example.com/data")
func NewClient ¶
func NewClient() *Client
NewClient creates a new HTTP client with default settings. The client has a default timeout of 2 minutes and can be customized using the fluent API methods.
Example:
client := http.NewClient().
BaseURL("https://api.example.com").
Header("X-API-Key", "secret").
InsecureSkipVerify(true)
func (*Client) Auth ¶ added in v1.13.0
Auth configures authentication credentials for the client. By default, this sets up HTTP Basic Authentication. Use Digest(), NTLM(), or NTLMV2() to switch authentication methods.
Example:
// Basic auth
client.Auth("username", "password")
// Digest auth
client.Auth("username", "password").Digest(true)
// NTLM auth with domain
client.Auth("DOMAIN\\username", "password").NTLM(true)
func (*Client) ConnectTo ¶ added in v1.13.0
ConnectTo overrides the target host:port for requests. This is useful for testing against specific IPs or when dealing with DNS issues. The original hostname is preserved in the Host header.
Example:
// Connect to a specific IP instead of using DNS
client.ConnectTo("192.168.1.100:8080")
// Test against localhost while preserving the original Host header
client.ConnectTo("localhost:3000")
func (*Client) DisableKeepAlive ¶ added in v1.13.0
DisableKeepAlives prevents reuse of TCP connections
func (*Client) InsecureSkipVerify ¶ added in v1.13.0
InsecureSkipVerify disables TLS certificate verification. WARNING: This makes the client vulnerable to man-in-the-middle attacks. Only use in development or when connecting to services with self-signed certificates.
Example:
// Accept any certificate (dangerous!) client.InsecureSkipVerify(true)
func (*Client) OAuth ¶ added in v1.15.0
func (c *Client) OAuth(config middlewares.OauthConfig) *Client
OAuth configures OAuth 2.0 authentication for the client. Supports various OAuth flows including client credentials and authorization code.
Example:
client.OAuth(middlewares.OauthConfig{
ClientID: "client-id",
ClientSecret: "client-secret",
TokenURL: "https://auth.example.com/token",
Scopes: []string{"read", "write"},
})
func (*Client) R ¶ added in v1.13.0
R creates a new request with the given context. The request inherits all settings from the client (headers, auth, etc.) and can be further customized before execution.
Example:
resp, err := client.R(ctx).
Header("X-Request-ID", "123").
QueryParam("page", "1").
GET("/users")
func (*Client) Retry ¶ added in v1.13.0
Retry configures automatic retry behavior with exponential backoff. Failed requests will be retried up to maxRetries times, with delays calculated as baseDuration * (exponent ^ attemptNumber).
Parameters:
- maxRetries: Maximum number of retry attempts (0 disables retries)
- baseDuration: Initial delay between retries
- exponent: Multiplier for exponential backoff (typically 2.0)
Example:
// Retry up to 3 times with delays of 1s, 2s, 4s client.Retry(3, time.Second, 2.0)
func (*Client) RoundTripper ¶ added in v1.40.2
func (c *Client) RoundTripper() http.RoundTripper
func (*Client) TLSConfig ¶ added in v1.22.2
TLSConfig configures advanced TLS settings including custom CAs, client certificates, and handshake timeout.
Example:
client.TLSConfig(TLSConfig{
CA: caPEM, // Custom CA certificate
Cert: clientCert, // Client certificate for mTLS
Key: clientKey, // Client private key
InsecureSkipVerify: false, // Verify server certificate
HandshakeTimeout: 10 * time.Second,
})
func (*Client) Timeout ¶ added in v1.13.0
Timeout specifies a time limit for requests made by this Client.
Default: 2 minutes
func (*Client) Trace ¶ added in v1.15.0
func (c *Client) Trace(config TraceConfig) *Client
Trace enables request/response tracing with customizable detail levels. Traced information is added to the context and can be retrieved by middleware.
Use predefined configs for common scenarios:
- TraceAll: Full details including headers, body, and TLS
- TraceHeaders: Headers and query params only (no body)
Example:
client.Trace(http.TraceConfig{
Headers: true,
ResponseHeaders: true,
Body: true,
Response: true,
MaxBodyLength: 1024, // Limit body size in traces
})
func (*Client) TraceToStdout ¶ added in v1.16.0
func (c *Client) TraceToStdout(config TraceConfig) *Client
func (*Client) Use ¶ added in v1.13.0
func (c *Client) Use(middlewares ...middlewares.Middleware) *Client
Use adds middleware to the client's transport chain. Middleware functions wrap the underlying RoundTripper and can modify requests/responses, add logging, implement caching, etc.
Middleware is applied in the order it was added.
Example:
client.Use(func(rt http.RoundTripper) http.RoundTripper {
return middlewares.RoundTripperFunc(func(req *http.Request) (*http.Response, error) {
req.Header.Set("X-Custom", "value")
return rt.RoundTrip(req)
})
})
func (*Client) WithHttpLogging ¶ added in v1.40.2
WithHttpLogging enables HTTP request/response logging based on the provided log levels.
Parameters:
- headerLevel: The minimum log level required to log HTTP headers (e.g., logger.Debug)
- bodyLevel: The minimum log level required to log request/response bodies (e.g., logger.Trace)
Example:
client.WithHttpLogging(logger.Debug, logger.Trace)
This will log headers when debug logging is enabled (-v or -v 1) and bodies when trace logging is enabled (-vv or -v 2 or higher).
Note: When using with cobra commands, ensure UseCobraFlags is called in PersistentPreRun to properly parse -v N syntax.
type OauthConfig ¶ added in v1.17.0
type OauthConfig = middlewares.OauthConfig
type Request ¶
type Request struct {
// contains filtered or unexported fields
}
Request represents an HTTP request that can be customized and executed. It provides a fluent API for setting headers, query parameters, body, and other options. Request instances should be created using Client.R(ctx).
func (*Request) Body ¶ added in v1.13.0
Body sets the request body. Accepts multiple types:
- io.Reader: Used directly as the body
- []byte: Wrapped in a bytes.Reader
- string: Converted to []byte and wrapped
- Any other type: JSON marshaled
Example:
// JSON body
req.Body(map[string]string{"key": "value"})
// String body
req.Body("raw text data")
// Reader body
req.Body(bytes.NewReader(data))
func (*Request) Do ¶ added in v1.13.0
Do performs an HTTP request with the specified method and URL.
func (*Request) Get ¶ added in v1.13.0
Get performs an HTTP GET request to the specified URL.
Example:
resp, err := client.R(ctx).Get("https://api.example.com/users")
if err != nil {
return err
}
defer resp.Body.Close()
func (*Request) GetHeaders ¶ added in v1.16.0
func (*Request) Header ¶ added in v1.13.0
Header sets a header for the request. Multiple calls with the same key will overwrite previous values.
Example:
resp, err := client.R(ctx).
Header("Authorization", "Bearer token").
Header("Content-Type", "application/json").
GET("/api/data")
func (*Request) Post ¶ added in v1.13.0
Post performs an HTTP POST request with the given body. The body can be a string, []byte, io.Reader, or any type that can be JSON marshaled.
Example:
user := map[string]string{"name": "John", "email": "john@example.com"}
resp, err := client.R(ctx).
Header("Content-Type", "application/json").
Post("https://api.example.com/users", user)
func (*Request) QueryParam ¶ added in v1.13.0
QueryParam sets a query parameter for the request. Multiple calls with the same key will overwrite previous values.
Example:
resp, err := client.R(ctx).
QueryParam("page", "1").
QueryParam("limit", "10").
GET("/api/users")
func (*Request) QueryParamAdd ¶ added in v1.31.24
QueryParamAdd adds a value to a query parameter. Unlike QueryParam, this allows multiple values for the same key.
Example:
// Results in: /api/search?tag=go&tag=http
resp, err := client.R(ctx).
QueryParamAdd("tag", "go").
QueryParamAdd("tag", "http").
GET("/api/search")
func (*Request) Retry ¶ added in v1.13.0
Retry configures retry behavior for this specific request, overriding the client's default retry configuration.
Parameters:
- maxRetries: Maximum number of retry attempts
- baseDuration: Initial delay between retries
- exponent: Multiplier for exponential backoff
Example:
// Retry this request up to 5 times
resp, err := client.R(ctx).
Retry(5, 500*time.Millisecond, 2.0).
GET("/flaky-endpoint")
type Response ¶
type Response struct {
// The underlying http.Response is embed into Response.
*http.Response
// Request is the Response's related Request.
Request *Request
RawRequest *http.Request
}
Response extends the stdlib http.Response type and extends its functionality
func (*Response) GetHeaders ¶ added in v1.16.0
type RetryConfig ¶ added in v1.13.0
type TLSConfig ¶ added in v1.22.2
type TLSConfig struct {
// InsecureSkipVerify controls whether a client verifies the server's
// certificate chain and host name
InsecureSkipVerify bool
// HandshakeTimeout defaults to 10 seconds
HandshakeTimeout time.Duration
// PEM encoded certificate of the CA to verify the server certificate
CA string
// PEM encoded client certificate
Cert string
// PEM encoded client private key
Key string
}
type TraceConfig ¶ added in v1.15.0
type TraceConfig = middlewares.TraceConfig
Source Files
Directories