Constructor
NewHttpClient
Creates a new HTTP client with the specified logger and configuration options.
func NewHttpClient(logger Logger, options ...HttpClientOption) (HttpClient, error)
Logger instance for debugging and diagnostics. Pass nil to use a no-op logger, or use NewLogger() for default logging.
Variable number of configuration options. See Client options for available options. The configured HTTP client instance.
Error if client creation fails (e.g., invalid configuration).
client, err := tls_client.NewHttpClient(tls_client.NewLogger(),
tls_client.WithClientProfile(profiles.Chrome_133),
tls_client.WithTimeoutSeconds(30),
tls_client.WithProxy("http://proxy.example.com:8080"),
)
if err != nil {
log.Fatal(err)
}
ProvideDefaultClient
Creates a new HTTP client with default options and an automatically configured cookie jar.
func ProvideDefaultClient(logger Logger) (HttpClient, error)
Logger instance for debugging and diagnostics.
The configured HTTP client with default settings.
Error if client creation fails.
- Timeout: 30 seconds
- Client profile: DefaultClientProfile
- Random TLS extension order: enabled
- Follow redirects: disabled
- Cookie jar: enabled
Example:
client, err := tls_client.ProvideDefaultClient(nil)
if err != nil {
log.Fatal(err)
}
Request methods
Issues an HTTP request and returns the corresponding response.
func (c *httpClient) Do(req *http.Request) (*http.Response, error)
The HTTP request to execute. Use http.NewRequest() or http.NewRequestWithContext() to create requests.
The HTTP response. Contains a non-nil body that must be closed by the caller.
Error if the request fails. If error is nil, the response will have a non-nil body.
req, err := http.NewRequest(http.MethodGet, "https://api.example.com/data", nil)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer token123")
req.Header.Set("User-Agent", "MyApp/1.0")
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
Get
Issues a GET request to the specified URL.
func (c *httpClient) Get(url string) (resp *http.Response, err error)
The HTTP response with a non-nil body that must be closed.
Error if the request fails.
resp, err := client.Get("https://api.example.com/users")
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
if resp.StatusCode == 200 {
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Head
Issues a HEAD request to the specified URL.
func (c *httpClient) Head(url string) (resp *http.Response, err error)
The HTTP response. HEAD responses have no body.
Error if the request fails.
resp, err := client.Head("https://api.example.com/status")
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
fmt.Println("Content-Length:", resp.Header.Get("Content-Length"))
fmt.Println("Last-Modified:", resp.Header.Get("Last-Modified"))
Post
Issues a POST request to the specified URL with the given content type and body.
func (c *httpClient) Post(url, contentType string, body io.Reader) (resp *http.Response, err error)
The Content-Type header value (e.g., "application/json", "application/x-www-form-urlencoded").
The HTTP response with a non-nil body that must be closed.
Error if the request fails.
// JSON POST
jsonData := []byte(`{"username":"john","email":"[email protected]"}`)
resp, err := client.Post(
"https://api.example.com/users",
"application/json",
bytes.NewBuffer(jsonData),
)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
// Form POST
formData := url.Values{}
formData.Set("username", "john")
formData.Set("email", "[email protected]")
resp, err = client.Post(
"https://api.example.com/users",
"application/x-www-form-urlencoded",
strings.NewReader(formData.Encode()),
)
Cookie management
GetCookies
Returns the cookies stored in the client’s cookie jar for a given URL.
func (c *httpClient) GetCookies(u *url.URL) []*http.Cookie
The URL to retrieve cookies for. Only cookies that match the URL’s domain and path are returned.
Array of cookies for the specified URL. Returns nil if no cookie jar is configured.
u, _ := url.Parse("https://example.com")
cookies := client.GetCookies(u)
for _, cookie := range cookies {
fmt.Printf("%s = %s\n", cookie.Name, cookie.Value)
}
SetCookies
Sets cookies in the client’s cookie jar for a given URL.
func (c *httpClient) SetCookies(u *url.URL, cookies []*http.Cookie)
The URL to associate cookies with.
u, _ := url.Parse("https://example.com")
cookies := []*http.Cookie{
{Name: "session_id", Value: "abc123", Path: "/", Domain: "example.com"},
{Name: "user_pref", Value: "dark_mode", Path: "/", Domain: "example.com"},
}
client.SetCookies(u, cookies)
SetCookieJar
Replaces the client’s cookie jar with a new one. This is the recommended way to clear all cookies.
func (c *httpClient) SetCookieJar(jar http.CookieJar)
The new cookie jar to use. Use tls_client.NewCookieJar() to create a new empty jar.
// Clear all cookies by setting a new jar
client.SetCookieJar(tls_client.NewCookieJar())
GetCookieJar
Returns the client’s current cookie jar.
func (c *httpClient) GetCookieJar() http.CookieJar
The current cookie jar instance.
jar := client.GetCookieJar()
if jar != nil {
// Save jar to disk, transfer to another client, etc.
}
Proxy management
SetProxy
Configures the client to use the specified proxy URL. The proxy can be changed at runtime.
func (c *httpClient) SetProxy(proxyUrl string) error
Proxy URL in the format "http://user:pass@host:port". Pass an empty string to disable proxy.
Error if the proxy configuration is invalid. On error, the previous proxy configuration is restored.
// Set proxy with authentication
err := client.SetProxy("http://username:[email protected]:8080")
if err != nil {
log.Fatal(err)
}
// Disable proxy
err = client.SetProxy("")
GetProxy
Returns the current proxy URL used by the client.
func (c *httpClient) GetProxy() string
The current proxy URL, or empty string if no proxy is configured.
proxyUrl := client.GetProxy()
if proxyUrl != "" {
fmt.Println("Using proxy:", proxyUrl)
}
Redirect control
SetFollowRedirect
Configures whether the client automatically follows HTTP redirects.
func (c *httpClient) SetFollowRedirect(followRedirect bool)
true to automatically follow redirects, false to return redirect responses directly.
// Disable automatic redirect following
client.SetFollowRedirect(false)
resp, _ := client.Get("https://example.com/redirect")
if resp.StatusCode == 302 {
location := resp.Header.Get("Location")
fmt.Println("Redirects to:", location)
}
// Enable automatic redirect following
client.SetFollowRedirect(true)
GetFollowRedirect
Returns the client’s current redirect following policy.
func (c *httpClient) GetFollowRedirect() bool
true if the client follows redirects automatically, false otherwise.
if client.GetFollowRedirect() {
fmt.Println("Client follows redirects")
}
Connection management
CloseIdleConnections
Closes all idle (keep-alive) connections that are not currently in use.
func (c *httpClient) CloseIdleConnections()
// Close idle connections to free resources
client.CloseIdleConnections()
Advanced features
GetBandwidthTracker
Returns the bandwidth tracker for monitoring network usage. Only available if configured with WithBandwidthTracker().
func (c *httpClient) GetBandwidthTracker() bandwidth.BandwidthTracker
tracker
bandwidth.BandwidthTracker
The bandwidth tracker instance, or a no-op tracker if not enabled.
tracker := client.GetBandwidthTracker()
stats := tracker.GetStats()
fmt.Printf("Sent: %d bytes, Received: %d bytes\n", stats.Sent, stats.Received)
GetDialer
Returns the underlying network dialer used by the client.
func (c *httpClient) GetDialer() proxy.ContextDialer
The context dialer instance used for establishing connections.
dialer := client.GetDialer()
// Use dialer for custom connection logic
GetTLSDialer
Returns a TLS dialer function that uses the same TLS fingerprinting as regular HTTP requests. Essential for WebSocket connections.
func (c *httpClient) GetTLSDialer() TLSDialerFunc
A function that dials TLS connections with consistent fingerprinting.
type TLSDialerFunc func(ctx context.Context, network, addr string) (net.Conn, error)
tlsDialer := client.GetTLSDialer()
// Used internally by WebSocket connections
conn, err := tlsDialer(context.Background(), "tcp", "example.com:443")
Request/response hooks
AddPreRequestHook
Adds a hook that is called before each request is sent. Multiple hooks can be added and execute in order.
func (c *httpClient) AddPreRequestHook(hook PreRequestHookFunc)
Function to execute before each request. Return an error to abort the request.
type PreRequestHookFunc func(req *http.Request) error
// Add custom header to all requests
client.AddPreRequestHook(func(req *http.Request) error {
req.Header.Set("X-Custom-Header", "value")
return nil
})
// Log all requests
client.AddPreRequestHook(func(req *http.Request) error {
log.Printf("Requesting: %s %s", req.Method, req.URL)
return nil
})
// Abort requests to specific domains
client.AddPreRequestHook(func(req *http.Request) error {
if req.URL.Host == "blocked.example.com" {
return fmt.Errorf("domain is blocked")
}
return nil
})
AddPostResponseHook
Adds a hook that is called after each request completes. Multiple hooks can be added and execute in order.
func (c *httpClient) AddPostResponseHook(hook PostResponseHookFunc)
Function to execute after each request completes. Always called even if the request failed.
type PostResponseHookFunc func(ctx *PostResponseContext) error
type PostResponseContext struct {
Request *http.Request
Response *http.Response
Error error // Non-nil if request failed
}
// Log all responses
client.AddPostResponseHook(func(ctx *PostResponseContext) error {
if ctx.Error != nil {
log.Printf("Request failed: %v", ctx.Error)
} else {
log.Printf("Response: %d from %s", ctx.Response.StatusCode, ctx.Request.URL)
}
return nil
})
// Track rate limits
client.AddPostResponseHook(func(ctx *PostResponseContext) error {
if ctx.Response != nil {
remaining := ctx.Response.Header.Get("X-RateLimit-Remaining")
if remaining == "0" {
log.Println("Rate limit exhausted!")
}
}
return nil
})
ResetPreHooks
Removes all pre-request hooks.
func (c *httpClient) ResetPreHooks()
ResetPostHooks
Removes all post-response hooks.
func (c *httpClient) ResetPostHooks()
Constants
DefaultTimeoutSeconds
The default timeout value in seconds.
var DefaultTimeoutSeconds = 30
ErrContinueHooks
Special error that can be returned from hooks to log the error but continue execution.
var ErrContinueHooks = errors.New("continue hooks")
client.AddPreRequestHook(func(req *http.Request) error {
if err := validateRequest(req); err != nil {
// Log error but don't abort request
return fmt.Errorf("%w: validation failed: %v", tls_client.ErrContinueHooks, err)
}
return nil
})