requests

package module
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 21, 2026 License: MIT Imports: 32 Imported by: 1

README

requests

Go Version License

A fluent HTTP client library for Go with middleware, retries, proxy and redirect controls, streaming callbacks, and JSON/XML/YAML helpers

Features

  • Fluent request builder: Chain path params, query params, headers, cookies, auth, body encoding, and per-request retry settings.
  • Multiple client entry points: Start with New(...), URL(...), or Create(&Config{...}) depending on how much control you need.
  • Retry-aware delivery: Combine retry counts, backoff strategies, and Retry-After handling without wrapping net/http yourself.
  • Transport controls: Configure TLS, mTLS, HTTP/2, redirect policies, proxies, bypass rules, and connection pooling.
  • Response helpers: Decode JSON, XML, or YAML, iterate line streams, inspect status helpers, or save to disk.
  • Composable middleware: Attach header, cookie, or cache middleware at the client or request level.

Installation

go get github.com/kaptinlin/requests

Requires Go 1.26+.

Quick Start

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/kaptinlin/requests"
)

type Post struct {
	ID    int    `json:"id"`
	Title string `json:"title"`
}

func main() {
	client := requests.New(
		requests.WithBaseURL("https://jsonplaceholder.typicode.com"),
		requests.WithTimeout(10*time.Second),
	)

	resp, err := client.Get("/posts/{id}").PathParam("id", "1").Send(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Close()

	var post Post
	if err := resp.ScanJSON(&post); err != nil {
		log.Fatal(err)
	}

	fmt.Println(post.ID, post.Title)
}

Client Construction

Functional options
client := requests.New(
	requests.WithBaseURL("https://api.example.com"),
	requests.WithTimeout(30*time.Second),
	requests.WithBearerAuth("token"),
	requests.WithMaxRetries(3),
)
URL shortcut
client := requests.URL("https://api.example.com")
Full config
cfg := &requests.Config{
	BaseURL:               "https://api.example.com",
	Timeout:               30 * time.Second,
	HTTP2:                 true,
	TLSServerName:         "api.example.com",
	DialTimeout:           5 * time.Second,
	TLSHandshakeTimeout:   5 * time.Second,
	ResponseHeaderTimeout: 10 * time.Second,
	MaxIdleConnsPerHost:   10,
}
if err := cfg.Validate(); err != nil {
	log.Fatal(err)
}

client := requests.Create(cfg)

Making Requests

JSON request body
resp, err := client.Post("/articles").
	Header("X-Trace-ID", "trace-123").
	JSONBody(map[string]any{"title": "hello"}).
	Send(context.Background())
Path and query parameters
resp, err := client.Get("/articles/{id}").
	PathParam("id", "42").
	Query("include", "comments").
	Send(context.Background())
Forms and files
file, err := os.Open("avatar.png")
if err != nil {
	log.Fatal(err)
}
defer file.Close()

resp, err := client.Post("/upload").
	FormField("user", "alice").
	File("avatar", "avatar.png", file).
	Send(context.Background())

Retries and Delivery

Client-level retries
client := requests.New(
	requests.WithBaseURL("https://api.example.com"),
	requests.WithMaxRetries(3),
	requests.WithRetryStrategy(
		requests.JitterBackoffStrategy(
			requests.ExponentialBackoffStrategy(250*time.Millisecond, 2, 5*time.Second),
			0.2,
		),
	),
)
Request-level overrides
resp, err := client.Get("/jobs/{id}").
	PathParam("id", "job-1").
	MaxRetries(5).
	RetryStrategy(requests.LinearBackoffStrategy(500 * time.Millisecond)).
	Send(context.Background())

The retry logic automatically honors Retry-After on 429 and 503 responses.

Proxies and Redirects

Proxy configuration
if err := client.SetProxyWithBypass("http://proxy.internal:8080", "localhost,.svc.cluster.local,10.0.0.0/8"); err != nil {
	log.Fatal(err)
}

if err := client.SetProxies("http://proxy1:8080", "http://proxy2:8080"); err != nil {
	log.Fatal(err)
}
Redirect policies
client.SetRedirectPolicy(requests.NewSmartRedirectPolicy(10))

Use NewAllowRedirectPolicy, NewProhibitRedirectPolicy, or NewRedirectSpecifiedDomainPolicy when you need a different redirect strategy.

Responses

Decode structured payloads
var out struct {
	Message string `json:"message"`
}
if err := resp.ScanJSON(&out); err != nil {
	log.Fatal(err)
}
Save to disk
if err := resp.Save("downloads/report.json"); err != nil {
	log.Fatal(err)
}
Iterate line-oriented responses
for line := range resp.Lines() {
	fmt.Printf("%s\n", line)
}
Classify failures
_, err := client.Get("/health").Send(context.Background())
if requests.IsTimeout(err) {
	log.Println("request timed out")
}
if requests.IsConnectionError(err) {
	log.Println("connection failed")
}

Streaming

_, err := client.Get("/events").
	Stream(func(line []byte) error {
		fmt.Printf("event: %s\n", line)
		return nil
	}).
	StreamErr(func(err error) {
		log.Printf("stream error: %v", err)
	}).
	StreamDone(func() {
		log.Println("stream closed")
	}).
	Send(context.Background())

Middleware

headers := http.Header{}
headers.Set("X-Client", "requests")

client.AddMiddleware(
	middlewares.HeaderMiddleware(headers),
	middlewares.CookieMiddleware([]*http.Cookie{{Name: "session", Value: "abc"}}),
)

For response caching, use middlewares.CacheMiddleware with a middlewares.Cacher implementation such as middlewares.NewMemoryCache().

Documentation

Development

task test      # Run all tests with race detection
task lint      # Run golangci-lint and tidy checks
task verify    # Run deps, fmt, vet, lint, test, and vuln checks

Contributing

Contributions are welcome. Open an issue or pull request with a focused change, and run task test plus task lint before submitting.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Overview

Package requests provides a fluent HTTP client library for Go.

Runtime failures are returned as errors rather than panics, and the package does not expose Must-style APIs.

Index

Examples

Constants

View Source 
const DirPermissions = 0o750

DirPermissions is the permission mode used when Save creates parent directories.

View Source 
const MaxStreamBufferSize = 512 * 1024

MaxStreamBufferSize is the maximum size of the buffer used for streaming.

Variables

View Source 
var (
	// ErrUnsupportedContentType is returned when the content type is unsupported.
	ErrUnsupportedContentType = errors.New("unsupported content type")

	// ErrUnsupportedDataType is returned when the data type is unsupported.
	ErrUnsupportedDataType = errors.New("unsupported data type")

	// ErrEncodingFailed is returned when the encoding fails.
	ErrEncodingFailed = errors.New("encoding failed")

	// ErrRequestCreationFailed is returned when the request cannot be created.
	ErrRequestCreationFailed = errors.New("failed to create request")

	// ErrResponseReadFailed is returned when the response cannot be read.
	ErrResponseReadFailed = errors.New("failed to read response")

	// ErrUnsupportedScheme is returned when the proxy scheme is unsupported.
	ErrUnsupportedScheme = errors.New("unsupported proxy scheme")

	// ErrNoProxies is returned when no proxy URLs are provided to a rotation function.
	ErrNoProxies = errors.New("no proxy URLs provided")

	// ErrUnsupportedFormFieldsType is returned when the form fields type is unsupported.
	ErrUnsupportedFormFieldsType = errors.New("unsupported form fields type")

	// ErrNotSupportSaveMethod is returned when the provided type for saving is not supported.
	ErrNotSupportSaveMethod = errors.New("unsupported save type")

	// ErrInvalidTransportType is returned when the transport type is invalid.
	ErrInvalidTransportType = errors.New("invalid transport type")

	// ErrResponseNil is returned when the response is nil.
	ErrResponseNil = errors.New("response is nil")

	// ErrAutoRedirectDisabled is returned when the auto redirect is disabled.
	ErrAutoRedirectDisabled = errors.New("auto redirect disabled")

	// ErrTooManyRedirects is returned when the number of redirects is too many.
	ErrTooManyRedirects = errors.New("too many redirects")

	// ErrRedirectNotAllowed is returned when the redirect is not allowed.
	ErrRedirectNotAllowed = errors.New("redirect not allowed")

	// ErrTestTimeout is returned when a test request times out (used in tests).
	ErrTestTimeout = errors.New("test timeout: request took too long")

	// ErrInvalidConfigValue is returned when a config field has an invalid value.
	ErrInvalidConfigValue = errors.New("invalid config value")

	// ErrInvalidTLSClientCertificateConfig is returned when TLS client cert and key paths are inconsistently configured.
	ErrInvalidTLSClientCertificateConfig = errors.New("TLSClientCertFile and TLSClientKeyFile must both be set or both be empty")
)
View Source 
var DefaultFormEncoder = &FormEncoder{}

DefaultFormEncoder is the default FormEncoder instance.

View Source 
var DefaultJSONDecoder = &JSONDecoder{
	UnmarshalFunc: jsonUnmarshal,
}

DefaultJSONDecoder is the default JSONDecoder instance using the JSON v2 unmarshal function.

View Source 
var DefaultJSONEncoder = &JSONEncoder{
	MarshalFunc: jsonMarshal,
}

DefaultJSONEncoder is the default JSONEncoder instance using the JSON v2 marshal function.

View Source 
var DefaultXMLDecoder = &XMLDecoder{
	UnmarshalFunc: xml.Unmarshal,
}

DefaultXMLDecoder is the default XMLDecoder instance using the standard xml.Unmarshal function.

View Source 
var DefaultXMLEncoder = &XMLEncoder{
	MarshalFunc: xml.Marshal,
}

DefaultXMLEncoder is the default XMLEncoder instance using the standard xml.Marshal function.

View Source 
var DefaultYAMLDecoder = &YAMLDecoder{
	UnmarshalFunc: yaml.Unmarshal,
}

DefaultYAMLDecoder is the default YAMLDecoder instance using the goccy/go-yaml Unmarshal function.

View Source 
var DefaultYAMLEncoder = &YAMLEncoder{
	MarshalFunc: yaml.Marshal,
}

DefaultYAMLEncoder is the default YAMLEncoder instance using the goccy/go-yaml Marshal function.

Functions

func DefaultBackoffStrategy 

func DefaultBackoffStrategy(delay time.Duration) func(int) time.Duration

DefaultBackoffStrategy provides a simple constant delay between retries.

func DefaultRetryIf 

func DefaultRetryIf(req *http.Request, resp *http.Response, err error) bool

DefaultRetryIf is a simple retry condition that retries on transport errors, request timeouts, rate limiting, and 5xx status codes.

func ExponentialBackoffStrategy 

func ExponentialBackoffStrategy(initialInterval time.Duration, multiplier float64, maxBackoffTime time.Duration) func(int) time.Duration

ExponentialBackoffStrategy increases the delay exponentially with each retry attempt.

func GetBuffer 

func GetBuffer() *bytebufferpool.ByteBuffer

GetBuffer retrieves a buffer from the pool.

func IsConnectionError added in v0.3.13 

func IsConnectionError(err error) bool

IsConnectionError reports whether err is a connection-level failure (DNS resolution, TCP connect, TLS handshake).

func IsTimeout added in v0.3.13 

func IsTimeout(err error) bool

IsTimeout reports whether err is or wraps a timeout error. It checks for context.DeadlineExceeded and net.Error timeout errors.

func LinearBackoffStrategy 

func LinearBackoffStrategy(initialInterval time.Duration) func(int) time.Duration

LinearBackoffStrategy increases the delay linearly with each retry attempt. The delay increments by `initialInterval` with each attempt.

func PutBuffer 

func PutBuffer(b *bytebufferpool.ByteBuffer)

PutBuffer returns a buffer to the pool.

func RandomProxies added in v0.3.13 

func RandomProxies(proxyURLs ...string) (func(*http.Request) (*url.URL, error), error)

RandomProxies returns a proxy function that selects a random proxy for each request. Safe for concurrent use.

func RoundRobinProxies added in v0.3.13 

func RoundRobinProxies(proxyURLs ...string) (func(*http.Request) (*url.URL, error), error)

RoundRobinProxies returns a proxy function that cycles through proxies in order. Safe for concurrent use.

Types

type AllowRedirectPolicy added in v0.2.3 

type AllowRedirectPolicy struct {
	// contains filtered or unexported fields
}

AllowRedirectPolicy is a redirect policy that allows a flexible number of redirects.

func NewAllowRedirectPolicy added in v0.2.3 

func NewAllowRedirectPolicy(numberRedirects int) *AllowRedirectPolicy

NewAllowRedirectPolicy creates a new AllowRedirectPolicy that allows up to the specified number of redirects.

func (*AllowRedirectPolicy) Apply added in v0.2.3 

func (a *AllowRedirectPolicy) Apply(req *http.Request, via []*http.Request) error

Apply allows redirects up to the configured limit, returning ErrTooManyRedirects if exceeded.

type AuthMethod 

type AuthMethod interface {
	// Apply applies the authentication strategy to req.
	Apply(req *http.Request)
	// Valid reports whether the authentication strategy is configured.
	Valid() bool
}

AuthMethod defines the interface for applying authentication strategies to requests.

type BackoffStrategy 

type BackoffStrategy func(attempt int) time.Duration

BackoffStrategy defines a function that returns the delay before the next retry.

func JitterBackoffStrategy added in v0.3.13 

func JitterBackoffStrategy(base BackoffStrategy, fraction float64) BackoffStrategy

JitterBackoffStrategy wraps a base backoff strategy and applies random jitter. The fraction parameter controls the jitter range: the delay is adjusted by plus or minus the fraction of the base delay. For example, a fraction of 0.25 means plus or minus 25% jitter.

type BasicAuth 

type BasicAuth struct {
	Username string // Username is the HTTP Basic Authentication username.
	Password string // Password is the HTTP Basic Authentication password.
}

BasicAuth represents HTTP Basic Authentication credentials.

func (BasicAuth) Apply 

func (b BasicAuth) Apply(req *http.Request)

Apply adds the Basic Auth credentials to the request.

func (BasicAuth) Valid 

func (b BasicAuth) Valid() bool

Valid checks if the Basic Auth credentials are present.

type BearerAuth 

type BearerAuth struct {
	Token string // Token is the bearer token value.
}

BearerAuth represents an OAuth 2.0 Bearer token.

func (BearerAuth) Apply 

func (b BearerAuth) Apply(req *http.Request)

Apply adds the Bearer token to the request's Authorization header.

func (BearerAuth) Valid 

func (b BearerAuth) Valid() bool

Valid checks if the Bearer token is present.

type Client 

type Client struct {
	BaseURL       string          // BaseURL is prepended to relative request paths.
	Headers       *http.Header    // Headers contains the default headers sent with each request.
	Cookies       []*http.Cookie  // Cookies contains the default cookies sent with each request.
	Middlewares   []Middleware    // Middlewares contains the client-level middleware chain.
	TLSConfig     *tls.Config     // TLSConfig configures TLS settings for the underlying transport.
	MaxRetries    int             // MaxRetries is the maximum number of retry attempts.
	RetryStrategy BackoffStrategy // RetryStrategy computes the delay before the next retry.
	RetryIf       RetryIfFunc     // RetryIf decides whether a request should be retried.
	HTTPClient    *http.Client    // HTTPClient is the underlying HTTP client used to send requests.
	JSONEncoder   Encoder         // JSONEncoder encodes JSON request bodies.
	JSONDecoder   Decoder         // JSONDecoder decodes JSON response bodies.
	XMLEncoder    Encoder         // XMLEncoder encodes XML request bodies.
	XMLDecoder    Decoder         // XMLDecoder decodes XML response bodies.
	YAMLEncoder   Encoder         // YAMLEncoder encodes YAML request bodies.
	YAMLDecoder   Decoder         // YAMLDecoder decodes YAML response bodies.
	Logger        Logger          // Logger receives client log output when configured.
	// contains filtered or unexported fields
}

Client represents an HTTP client.

func Create 

func Create(config *Config) *Client

Create initializes a new HTTP client with the given configuration.

func New added in v0.3.14 

func New(opts ...ClientOption) *Client

New creates a Client with functional options applied. It calls Create(nil) to initialize a client with default settings, then applies each option in order.

func URL 

func URL(baseURL string) *Client

URL creates a new HTTP client with the given base URL.

func (*Client) AddDefaultHeader 

func (c *Client) AddDefaultHeader(key, value string)

AddDefaultHeader adds a default header.

func (*Client) AddMiddleware 

func (c *Client) AddMiddleware(middlewares ...Middleware)

AddMiddleware adds a middleware to the client.

func (*Client) Connect added in v0.3.12 

func (c *Client) Connect(path string) *RequestBuilder

Connect initiates a CONNECT request.

func (*Client) Custom 

func (c *Client) Custom(path, method string) *RequestBuilder

Custom initiates a custom request.

func (*Client) DelDefaultCookie 

func (c *Client) DelDefaultCookie(name string)

DelDefaultCookie removes a default cookie from the client.

func (*Client) DelDefaultHeader 

func (c *Client) DelDefaultHeader(key string)

DelDefaultHeader removes a default header.

func (*Client) Delete 

func (c *Client) Delete(path string) *RequestBuilder

Delete initiates a DELETE request.

func (*Client) Get 

func (c *Client) Get(path string) *RequestBuilder

Get initiates a GET request.

Example 
package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"
	"time"

	"github.com/kaptinlin/requests"
)

func main() {
	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		_, _ = fmt.Fprint(w, `{"id":1,"title":"delectus aut autem"}`)
	}))
	defer server.Close()

	type post struct {
		ID    int    `json:"id"`
		Title string `json:"title"`
	}

	client := requests.New(
		requests.WithBaseURL(server.URL),
		requests.WithTimeout(5*time.Second),
	)

	resp, err := client.Get("/posts/{id}").PathParam("id", "1").Send(context.Background())
	if err != nil {
		fmt.Println("request error:", err)
		return
	}
	defer func() { _ = resp.Close() }()

	var p post
	if err := resp.ScanJSON(&p); err != nil {
		fmt.Println("decode error:", err)
		return
	}

	fmt.Println(p.ID, p.Title)
}

Output:
1 delectus aut autem

func (*Client) GetBaseURL added in v0.4.0 

func (c *Client) GetBaseURL() string

GetBaseURL returns the configured base URL in a thread-safe way.

func (*Client) GetHTTPClient added in v0.4.0 

func (c *Client) GetHTTPClient() *http.Client

GetHTTPClient returns the underlying HTTP client in a thread-safe way.

func (*Client) Head 

func (c *Client) Head(path string) *RequestBuilder

Head initiates a HEAD request.

func (*Client) InsecureSkipVerify 

func (c *Client) InsecureSkipVerify() *Client

InsecureSkipVerify sets the TLS configuration to skip certificate verification.

func (*Client) NewRequestBuilder 

func (c *Client) NewRequestBuilder(method, path string) *RequestBuilder

NewRequestBuilder creates a new RequestBuilder with default settings.

func (*Client) Options 

func (c *Client) Options(path string) *RequestBuilder

Options initiates an OPTIONS request.

func (*Client) Patch 

func (c *Client) Patch(path string) *RequestBuilder

Patch initiates a PATCH request.

func (*Client) Post 

func (c *Client) Post(path string) *RequestBuilder

Post initiates a POST request.

func (*Client) Put 

func (c *Client) Put(path string) *RequestBuilder

Put initiates a PUT request.

func (*Client) RemoveProxy 

func (c *Client) RemoveProxy()

RemoveProxy clears any configured proxy, allowing direct connections.

func (*Client) SetAuth 

func (c *Client) SetAuth(auth AuthMethod)

SetAuth configures an authentication method for the client.

func (*Client) SetBaseURL 

func (c *Client) SetBaseURL(baseURL string)

SetBaseURL sets the base URL for the client.

func (*Client) SetCertificates added in v0.2.3 

func (c *Client) SetCertificates(certs ...tls.Certificate) *Client

SetCertificates sets the TLS certificates for the client.

func (*Client) SetClientCertificate added in v0.4.0 

func (c *Client) SetClientCertificate(certFile, keyFile string) *Client

SetClientCertificate loads and sets a client certificate and private key from files.

func (*Client) SetClientRootCertificate added in v0.2.3 

func (c *Client) SetClientRootCertificate(pemFilePath string) *Client

SetClientRootCertificate sets the client root certificate for the client.

func (*Client) SetClientRootCertificateFromString added in v0.2.3 

func (c *Client) SetClientRootCertificateFromString(pemCerts string) *Client

SetClientRootCertificateFromString sets the client root certificate for the client from a string.

func (*Client) SetDefaultAccept 

func (c *Client) SetDefaultAccept(accept string)

SetDefaultAccept sets the default accept header for the client.

func (*Client) SetDefaultContentType 

func (c *Client) SetDefaultContentType(contentType string)

SetDefaultContentType sets the default content type for the client.

func (*Client) SetDefaultCookie 

func (c *Client) SetDefaultCookie(name, value string)

SetDefaultCookie sets a default cookie for the client.

func (*Client) SetDefaultCookieJar 

func (c *Client) SetDefaultCookieJar(jar *cookiejar.Jar)

SetDefaultCookieJar sets the default cookie jar for the client.

func (*Client) SetDefaultCookies 

func (c *Client) SetDefaultCookies(cookies map[string]string)

SetDefaultCookies sets the default cookies for the client.

func (*Client) SetDefaultHeader 

func (c *Client) SetDefaultHeader(key, value string)

SetDefaultHeader adds or updates a default header.

func (*Client) SetDefaultHeaders 

func (c *Client) SetDefaultHeaders(headers *http.Header)

SetDefaultHeaders sets the default headers for the client.

func (*Client) SetDefaultReferer 

func (c *Client) SetDefaultReferer(referer string)

SetDefaultReferer sets the default referer for the client.

func (*Client) SetDefaultTimeout 

func (c *Client) SetDefaultTimeout(timeout time.Duration)

SetDefaultTimeout sets the default timeout for the client.

func (*Client) SetDefaultTransport 

func (c *Client) SetDefaultTransport(transport http.RoundTripper)

SetDefaultTransport sets the default transport for the client.

func (*Client) SetDefaultUserAgent 

func (c *Client) SetDefaultUserAgent(userAgent string)

SetDefaultUserAgent sets the default user agent for the client.

func (*Client) SetDialTimeout added in v0.3.13 

func (c *Client) SetDialTimeout(d time.Duration) *Client

SetDialTimeout sets the TCP connection timeout on the underlying transport.

func (*Client) SetHTTPClient 

func (c *Client) SetHTTPClient(httpClient *http.Client)

SetHTTPClient sets the HTTP client for the client.

func (*Client) SetIdleConnTimeout added in v0.3.13 

func (c *Client) SetIdleConnTimeout(d time.Duration) *Client

SetIdleConnTimeout sets how long idle connections remain in the pool before being closed.

func (*Client) SetJSONMarshal 

func (c *Client) SetJSONMarshal(marshalFunc func(v any) ([]byte, error))

SetJSONMarshal sets the JSON marshal function for the client's JSONEncoder.

func (*Client) SetJSONUnmarshal 

func (c *Client) SetJSONUnmarshal(unmarshalFunc func(data []byte, v any) error)

SetJSONUnmarshal sets the JSON unmarshal function for the client's JSONDecoder.

func (*Client) SetLogger 

func (c *Client) SetLogger(logger Logger) *Client

SetLogger sets logger instance in client.

func (*Client) SetMaxConnsPerHost added in v0.3.13 

func (c *Client) SetMaxConnsPerHost(n int) *Client

SetMaxConnsPerHost sets the maximum total number of connections per host.

func (*Client) SetMaxIdleConns added in v0.3.13 

func (c *Client) SetMaxIdleConns(n int) *Client

SetMaxIdleConns sets the maximum number of idle connections across all hosts.

func (*Client) SetMaxIdleConnsPerHost added in v0.3.13 

func (c *Client) SetMaxIdleConnsPerHost(n int) *Client

SetMaxIdleConnsPerHost sets the maximum number of idle connections per host.

func (*Client) SetMaxRetries 

func (c *Client) SetMaxRetries(maxRetries int) *Client

SetMaxRetries sets the maximum number of retry attempts.

func (*Client) SetProxies added in v0.3.13 

func (c *Client) SetProxies(proxyURLs ...string) error

SetProxies configures multiple proxies with round-robin rotation. Each outgoing request (including retries) picks the next proxy in order.

func (*Client) SetProxy 

func (c *Client) SetProxy(proxyURL string) error

SetProxy configures the client to use a proxy. Supports http, https, and socks5 proxies.

func (*Client) SetProxyFromEnv added in v0.3.13 

func (c *Client) SetProxyFromEnv() error

SetProxyFromEnv configures the client to use proxy settings from environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY).

func (*Client) SetProxySelector added in v0.3.13 

func (c *Client) SetProxySelector(selector func(*http.Request) (*url.URL, error)) error

SetProxySelector sets a custom proxy selection function matching the http.Transport.Proxy signature. Return nil *url.URL for direct connection.

func (*Client) SetProxyWithBypass added in v0.3.13 

func (c *Client) SetProxyWithBypass(proxyURL, bypass string) error

SetProxyWithBypass configures the client to use a proxy with a NO_PROXY bypass list. The bypass parameter is a comma-separated string of hosts that should not use the proxy. Supported formats: domain names, IPs, CIDR subnets, and "*" for wildcard.

func (*Client) SetRedirectPolicy added in v0.2.3 

func (c *Client) SetRedirectPolicy(policies ...RedirectPolicy) *Client

SetRedirectPolicy sets the redirect policy for the client.

func (*Client) SetResponseHeaderTimeout added in v0.3.13 

func (c *Client) SetResponseHeaderTimeout(d time.Duration) *Client

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 (*Client) SetRetryIf 

func (c *Client) SetRetryIf(retryIf RetryIfFunc) *Client

SetRetryIf sets the custom retry condition function.

func (*Client) SetRetryStrategy 

func (c *Client) SetRetryStrategy(strategy BackoffStrategy) *Client

SetRetryStrategy sets the backoff strategy for retries.

func (*Client) SetRootCertificate added in v0.2.3 

func (c *Client) SetRootCertificate(pemFilePath string) *Client

SetRootCertificate sets the root certificate for the client.

func (*Client) SetRootCertificateFromString added in v0.2.3 

func (c *Client) SetRootCertificateFromString(pemCerts string) *Client

SetRootCertificateFromString sets the root certificate for the client from a string.

func (*Client) SetTLSConfig 

func (c *Client) SetTLSConfig(config *tls.Config) *Client

SetTLSConfig sets the TLS configuration for the client.

func (*Client) SetTLSHandshakeTimeout added in v0.3.13 

func (c *Client) SetTLSHandshakeTimeout(d time.Duration) *Client

SetTLSHandshakeTimeout sets the TLS handshake timeout on the underlying transport.

func (*Client) SetTLSServerName added in v0.4.0 

func (c *Client) SetTLSServerName(serverName string) *Client

SetTLSServerName sets the TLS server name (SNI) for the client.

func (*Client) SetXMLMarshal 

func (c *Client) SetXMLMarshal(marshalFunc func(v any) ([]byte, error))

SetXMLMarshal sets the XML marshal function for the client's XMLEncoder.

func (*Client) SetXMLUnmarshal 

func (c *Client) SetXMLUnmarshal(unmarshalFunc func(data []byte, v any) error)

SetXMLUnmarshal sets the XML unmarshal function for the client's XMLDecoder.

func (*Client) SetYAMLMarshal 

func (c *Client) SetYAMLMarshal(marshalFunc func(v any) ([]byte, error))

SetYAMLMarshal sets the YAML marshal function for the client's YAMLEncoder.

func (*Client) SetYAMLUnmarshal 

func (c *Client) SetYAMLUnmarshal(unmarshalFunc func(data []byte, v any) error)

SetYAMLUnmarshal sets the YAML unmarshal function for the client's YAMLDecoder.

func (*Client) Trace added in v0.3.12 

func (c *Client) Trace(path string) *RequestBuilder

Trace initiates a TRACE request.

type ClientOption added in v0.3.14 

type ClientOption func(*Client)

ClientOption configures a Client. Use with New().

func WithAccept added in v0.3.14 

func WithAccept(accept string) ClientOption

WithAccept sets the default Accept header.

func WithAuth added in v0.3.14 

func WithAuth(auth AuthMethod) ClientOption

WithAuth sets the authentication method for the client.

func WithBaseURL added in v0.3.14 

func WithBaseURL(baseURL string) ClientOption

WithBaseURL sets the base URL for the client.

func WithBasicAuth added in v0.3.14 

func WithBasicAuth(username, password string) ClientOption

WithBasicAuth sets HTTP Basic Authentication credentials.

func WithBearerAuth added in v0.3.14 

func WithBearerAuth(token string) ClientOption

WithBearerAuth sets a Bearer token for authentication.

func WithCertificates added in v0.3.14 

func WithCertificates(certs ...tls.Certificate) ClientOption

WithCertificates sets TLS client certificates.

func WithClientCertificate added in v0.4.0 

func WithClientCertificate(certFile, keyFile string) ClientOption

WithClientCertificate loads and sets a client certificate and key from file paths.

func WithContentType added in v0.3.14 

func WithContentType(contentType string) ClientOption

WithContentType sets the default Content-Type header.

func WithCookieJar added in v0.3.14 

func WithCookieJar(jar *cookiejar.Jar) ClientOption

WithCookieJar sets the cookie jar for the client.

func WithCookies added in v0.3.14 

func WithCookies(cookies map[string]string) ClientOption

WithCookies sets default cookies on the client.

func WithDialTimeout added in v0.3.14 

func WithDialTimeout(d time.Duration) ClientOption

WithDialTimeout sets the TCP connection timeout on the underlying transport.

func WithHTTPClient added in v0.3.14 

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets the underlying http.Client. When combined with transport-modifying options (WithProxy, WithDialTimeout, etc.), place WithHTTPClient first since it replaces the entire http.Client.

func WithHeader added in v0.3.14 

func WithHeader(key, value string) ClientOption

WithHeader sets a default header on the client.

func WithHeaders added in v0.3.14 

func WithHeaders(headers *http.Header) ClientOption

WithHeaders sets all default headers on the client.

func WithIdleConnTimeout added in v0.3.14 

func WithIdleConnTimeout(d time.Duration) ClientOption

WithIdleConnTimeout sets how long idle connections remain in the pool.

func WithInsecureSkipVerify added in v0.3.14 

func WithInsecureSkipVerify() ClientOption

WithInsecureSkipVerify configures the client to skip TLS certificate verification.

func WithJSONMarshal added in v0.3.14 

func WithJSONMarshal(marshalFunc func(v any) ([]byte, error)) ClientOption

WithJSONMarshal sets a custom JSON marshal function.

func WithJSONUnmarshal added in v0.3.14 

func WithJSONUnmarshal(unmarshalFunc func(data []byte, v any) error) ClientOption

WithJSONUnmarshal sets a custom JSON unmarshal function.

func WithLogger added in v0.3.14 

func WithLogger(logger Logger) ClientOption

WithLogger sets the logger for the client.

func WithMaxConnsPerHost added in v0.3.14 

func WithMaxConnsPerHost(n int) ClientOption

WithMaxConnsPerHost sets the maximum total number of connections per host.

func WithMaxIdleConns added in v0.3.14 

func WithMaxIdleConns(n int) ClientOption

WithMaxIdleConns sets the maximum number of idle connections across all hosts.

func WithMaxIdleConnsPerHost added in v0.3.14 

func WithMaxIdleConnsPerHost(n int) ClientOption

WithMaxIdleConnsPerHost sets the maximum number of idle connections per host.

func WithMaxRetries added in v0.3.14 

func WithMaxRetries(maxRetries int) ClientOption

WithMaxRetries sets the maximum number of retry attempts.

func WithMiddleware added in v0.3.14 

func WithMiddleware(middlewares ...Middleware) ClientOption

WithMiddleware adds middleware to the client.

func WithProxy added in v0.3.14 

func WithProxy(proxyURL string) ClientOption

WithProxy sets the proxy URL for the client. Parse errors are silently ignored to maintain the fluent pattern; use Client.SetProxy() directly for error handling.

func WithRedirectPolicy added in v0.3.14 

func WithRedirectPolicy(policies ...RedirectPolicy) ClientOption

WithRedirectPolicy sets the redirect policy for the client.

func WithReferer added in v0.3.14 

func WithReferer(referer string) ClientOption

WithReferer sets the default Referer header.

func WithResponseHeaderTimeout added in v0.3.14 

func WithResponseHeaderTimeout(d time.Duration) ClientOption

WithResponseHeaderTimeout sets the time to wait for response headers.

func WithRetryIf added in v0.3.14 

func WithRetryIf(retryIf RetryIfFunc) ClientOption

WithRetryIf sets the custom retry condition function.

func WithRetryStrategy added in v0.3.14 

func WithRetryStrategy(strategy BackoffStrategy) ClientOption

WithRetryStrategy sets the backoff strategy for retries.

func WithRootCertificate added in v0.3.14 

func WithRootCertificate(pemFilePath string) ClientOption

WithRootCertificate sets the root certificate from a PEM file path.

func WithRootCertificateFromString added in v0.3.14 

func WithRootCertificateFromString(pemCerts string) ClientOption

WithRootCertificateFromString sets the root certificate from a PEM string.

func WithTLSConfig added in v0.3.14 

func WithTLSConfig(config *tls.Config) ClientOption

WithTLSConfig sets the TLS configuration for the client.

func WithTLSHandshakeTimeout added in v0.3.14 

func WithTLSHandshakeTimeout(d time.Duration) ClientOption

WithTLSHandshakeTimeout sets the TLS handshake timeout on the underlying transport.

func WithTLSServerName added in v0.4.0 

func WithTLSServerName(serverName string) ClientOption

WithTLSServerName sets the TLS server name (SNI).

func WithTimeout added in v0.3.14 

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout sets the default timeout for the client.

func WithTransport added in v0.3.14 

func WithTransport(transport http.RoundTripper) ClientOption

WithTransport sets the HTTP transport for the client.

func WithUserAgent added in v0.3.14 

func WithUserAgent(userAgent string) ClientOption

WithUserAgent sets the default User-Agent header.

func WithXMLMarshal added in v0.3.14 

func WithXMLMarshal(marshalFunc func(v any) ([]byte, error)) ClientOption

WithXMLMarshal sets a custom XML marshal function.

func WithXMLUnmarshal added in v0.3.14 

func WithXMLUnmarshal(unmarshalFunc func(data []byte, v any) error) ClientOption

WithXMLUnmarshal sets a custom XML unmarshal function.

func WithYAMLMarshal added in v0.3.14 

func WithYAMLMarshal(marshalFunc func(v any) ([]byte, error)) ClientOption

WithYAMLMarshal sets a custom YAML marshal function.

func WithYAMLUnmarshal added in v0.3.14 

func WithYAMLUnmarshal(unmarshalFunc func(data []byte, v any) error) ClientOption

WithYAMLUnmarshal sets a custom YAML unmarshal function.

type Config 

type Config struct {
	BaseURL           string            // BaseURL is the base URL for requests made by this client.
	Headers           *http.Header      // Headers contains the default headers sent with each request.
	Cookies           map[string]string // Cookies contains the default cookies sent with each request.
	Timeout           time.Duration     // Timeout is the default request timeout.
	CookieJar         *cookiejar.Jar    // CookieJar stores and sends cookies for the client.
	Middlewares       []Middleware      // Middlewares contains the middleware stack for request and response handling.
	TLSConfig         *tls.Config       // TLSConfig configures TLS settings for the client.
	TLSClientCertFile string            // TLSClientCertFile is the path to the client certificate file.
	TLSClientKeyFile  string            // TLSClientKeyFile is the path to the client private key file.
	TLSServerName     string            // TLSServerName is the TLS server name used for SNI.
	Transport         http.RoundTripper // Transport is the custom transport used by the client.
	MaxRetries        int               // MaxRetries is the maximum number of retry attempts.
	RetryStrategy     BackoffStrategy   // RetryStrategy computes the delay before the next retry.
	RetryIf           RetryIfFunc       // RetryIf decides whether a request should be retried.
	Logger            Logger            // Logger receives client log output when configured.
	HTTP2             bool              // HTTP2 enables HTTP/2 when Transport is not provided.

	// Transport-level timeouts.
	DialTimeout           time.Duration // DialTimeout is the TCP connection timeout.
	TLSHandshakeTimeout   time.Duration // TLSHandshakeTimeout is the TLS handshake timeout.
	ResponseHeaderTimeout time.Duration // ResponseHeaderTimeout is the time to the first response byte.

	// Connection pool settings.
	MaxIdleConns        int           // MaxIdleConns is the maximum number of idle connections across all hosts.
	MaxIdleConnsPerHost int           // MaxIdleConnsPerHost is the maximum number of idle connections per host.
	MaxConnsPerHost     int           // MaxConnsPerHost is the maximum number of connections per host.
	IdleConnTimeout     time.Duration // IdleConnTimeout is how long idle connections remain open.
}

Config sets up the initial configuration for the HTTP client.

func (*Config) Validate added in v0.4.0 

func (cfg *Config) Validate() error

Validate checks whether the config contains deterministic invalid values.

type CustomAuth 

type CustomAuth struct {
	Header string // Header is the Authorization header value.
}

CustomAuth allows for custom Authorization header values.

func (CustomAuth) Apply 

func (c CustomAuth) Apply(req *http.Request)

Apply sets a custom Authorization header value.

func (CustomAuth) Valid 

func (c CustomAuth) Valid() bool

Valid checks if the custom Authorization header value is present.

type Decoder 

type Decoder interface {
	// Decode decodes data from r into v.
	Decode(r io.Reader, v any) error
}

Decoder decodes data from an io.Reader into a value.

type DefaultLogger 

type DefaultLogger struct {
	// contains filtered or unexported fields
}

DefaultLogger is a default logger that uses `slog` as the underlying logger.

func (*DefaultLogger) Debugf added in v0.1.1 

func (l *DefaultLogger) Debugf(format string, v ...any)

Debugf logs a message at the Debug level.

func (*DefaultLogger) Errorf added in v0.1.1 

func (l *DefaultLogger) Errorf(format string, v ...any)

Errorf logs a message at the Error level.

func (*DefaultLogger) Infof added in v0.1.1 

func (l *DefaultLogger) Infof(format string, v ...any)

Infof logs a message at the Info level.

func (*DefaultLogger) SetLevel added in v0.1.1 

func (l *DefaultLogger) SetLevel(level Level)

SetLevel sets the log level of the logger.

func (*DefaultLogger) Warnf added in v0.1.1 

func (l *DefaultLogger) Warnf(format string, v ...any)

Warnf logs a message at the Warn level.

type Encoder 

type Encoder interface {
	// Encode encodes v and returns a reader for the encoded payload.
	Encode(v any) (io.Reader, error)
	// ContentType returns the payload content type.
	ContentType() string
}

Encoder encodes values into an io.Reader with an associated content type.

type File 

type File struct {
	Name     string        // Name is the form field name.
	FileName string        // FileName is the uploaded file name.
	Content  io.ReadCloser // Content is the uploaded file content.
}

File represents a form file.

func (*File) SetContent 

func (f *File) SetContent(content io.ReadCloser)

SetContent sets the content of the file.

func (*File) SetFileName 

func (f *File) SetFileName(fileName string)

SetFileName sets the file name.

func (*File) SetName 

func (f *File) SetName(name string)

SetName sets the form field name.

type FormEncoder 

type FormEncoder struct{}

FormEncoder handles encoding of form data.

func (*FormEncoder) Encode 

func (e *FormEncoder) Encode(v any) (io.Reader, error)

Encode encodes the given value into URL-encoded form data.

type JSONDecoder 

type JSONDecoder struct {
	UnmarshalFunc func(data []byte, v any) error // UnmarshalFunc unmarshals JSON data into a value.
}

JSONDecoder handles decoding of JSON data.

func (*JSONDecoder) Decode 

func (d *JSONDecoder) Decode(r io.Reader, v any) error

Decode reads the data from the reader and unmarshals it into the provided value.

type JSONEncoder 

type JSONEncoder struct {
	MarshalFunc func(v any) ([]byte, error) // MarshalFunc marshals a value into JSON.
}

JSONEncoder handles encoding of JSON data.

func (*JSONEncoder) ContentType 

func (e *JSONEncoder) ContentType() string

ContentType returns the content type for JSON data.

func (*JSONEncoder) Encode 

func (e *JSONEncoder) Encode(v any) (io.Reader, error)

Encode marshals the provided value into JSON format.

type Level 

type Level int

Level represents a log level. 

const (
	// LevelDebug enables debug logging.
	LevelDebug Level = iota
	// LevelInfo enables info logging.
	LevelInfo
	// LevelWarn enables warning logging.
	LevelWarn
	// LevelError enables error logging.
	LevelError
)

type Logger 

type Logger interface {
	// Debugf logs a message at the Debug level.
	Debugf(format string, v ...any)
	// Infof logs a message at the Info level.
	Infof(format string, v ...any)
	// Warnf logs a message at the Warn level.
	Warnf(format string, v ...any)
	// Errorf logs a message at the Error level.
	Errorf(format string, v ...any)
	// SetLevel sets the log level of the logger.
	SetLevel(level Level)
}

Logger is a logger interface that outputs logs with a format.

func NewDefaultLogger added in v0.1.1 

func NewDefaultLogger(output io.Writer, level Level) Logger

NewDefaultLogger creates a new `DefaultLogger` with the given output and log level.

type Middleware 

type Middleware func(next MiddlewareHandlerFunc) MiddlewareHandlerFunc

Middleware wraps a MiddlewareHandlerFunc with additional behavior.

type MiddlewareHandlerFunc 

type MiddlewareHandlerFunc func(req *http.Request) (*http.Response, error)

MiddlewareHandlerFunc handles an HTTP request and returns an HTTP response.

type NoProxy added in v0.3.13 

type NoProxy struct {
	// contains filtered or unexported fields
}

NoProxy holds parsed bypass rules for proxy exclusion.

type ProhibitRedirectPolicy added in v0.2.3 

type ProhibitRedirectPolicy struct {
}

ProhibitRedirectPolicy is a redirect policy that does not allow any redirects.

func NewProhibitRedirectPolicy added in v0.2.3 

func NewProhibitRedirectPolicy() *ProhibitRedirectPolicy

NewProhibitRedirectPolicy creates a new ProhibitRedirectPolicy that prevents any redirects.

func (*ProhibitRedirectPolicy) Apply added in v0.2.3 

func (p *ProhibitRedirectPolicy) Apply(req *http.Request, via []*http.Request) error

Apply rejects all redirects by returning ErrAutoRedirectDisabled.

type RedirectPolicy added in v0.2.3 

type RedirectPolicy interface {
	// Apply applies the redirect policy to req based on the prior requests in via.
	Apply(req *http.Request, via []*http.Request) error
}

RedirectPolicy applies redirect behavior to outgoing requests.

type RedirectSpecifiedDomainPolicy added in v0.2.3 

type RedirectSpecifiedDomainPolicy struct {
	// contains filtered or unexported fields
}

RedirectSpecifiedDomainPolicy is a redirect policy that checks if the redirect is allowed based on the hostnames.

func NewRedirectSpecifiedDomainPolicy added in v0.2.3 

func NewRedirectSpecifiedDomainPolicy(domains ...string) *RedirectSpecifiedDomainPolicy

NewRedirectSpecifiedDomainPolicy creates a new RedirectSpecifiedDomainPolicy that only allows redirects to the specified domains.

func (*RedirectSpecifiedDomainPolicy) Apply added in v0.2.3 

func (s *RedirectSpecifiedDomainPolicy) Apply(req *http.Request, _ []*http.Request) error

Apply checks if the redirect target domain is in the allowed domains list.

type RequestBuilder 

type RequestBuilder struct {
	// contains filtered or unexported fields
}

RequestBuilder facilitates building and executing HTTP requests.

func (*RequestBuilder) Accept 

func (b *RequestBuilder) Accept(accept string) *RequestBuilder

Accept sets the Accept header for the request.

func (*RequestBuilder) AddHeader 

func (b *RequestBuilder) AddHeader(key, value string) *RequestBuilder

AddHeader adds a header to the request.

func (*RequestBuilder) AddMiddleware 

func (b *RequestBuilder) AddMiddleware(middlewares ...Middleware)

AddMiddleware adds a middleware to the request.

func (*RequestBuilder) Auth 

func (b *RequestBuilder) Auth(auth AuthMethod) *RequestBuilder

Auth applies an authentication method to the request.

func (*RequestBuilder) Body 

func (b *RequestBuilder) Body(body any) *RequestBuilder

Body sets the request body.

func (*RequestBuilder) Clone added in v0.3.13 

func (b *RequestBuilder) Clone() *RequestBuilder

Clone creates a deep copy of the RequestBuilder. The clone shares the same client reference (shallow copy) but has independent copies of headers, cookies, queries, pathParams, and formFields (deep copy). This means configuration changes to the client will affect both the original and clone.

Body data, form files, stream callbacks, middlewares, and retry config are not copied as they are not safe to share or clone. Set these on the cloned builder if needed.

func (*RequestBuilder) ContentType 

func (b *RequestBuilder) ContentType(contentType string) *RequestBuilder

ContentType sets the Content-Type header for the request.

func (*RequestBuilder) Cookie 

func (b *RequestBuilder) Cookie(key, value string) *RequestBuilder

Cookie adds a cookie to the request.

func (*RequestBuilder) Cookies 

func (b *RequestBuilder) Cookies(cookies map[string]string) *RequestBuilder

Cookies method for map.

func (*RequestBuilder) DelCookie 

func (b *RequestBuilder) DelCookie(key ...string) *RequestBuilder

DelCookie removes one or more cookies from the request.

func (*RequestBuilder) DelFile 

func (b *RequestBuilder) DelFile(key ...string) *RequestBuilder

DelFile removes one or more files from the request.

func (*RequestBuilder) DelFormField 

func (b *RequestBuilder) DelFormField(key ...string) *RequestBuilder

DelFormField removes one or more form fields.

func (*RequestBuilder) DelHeader 

func (b *RequestBuilder) DelHeader(key ...string) *RequestBuilder

DelHeader removes one or more headers from the request.

func (*RequestBuilder) DelPathParam 

func (b *RequestBuilder) DelPathParam(key ...string) *RequestBuilder

DelPathParam removes one or more path params fields from the RequestBuilder instance.

func (*RequestBuilder) DelQuery 

func (b *RequestBuilder) DelQuery(key ...string) *RequestBuilder

DelQuery removes one or more query parameters from the request.

func (*RequestBuilder) File 

func (b *RequestBuilder) File(key, filename string, content io.ReadCloser) *RequestBuilder

File adds a file to the request.

func (*RequestBuilder) Files 

func (b *RequestBuilder) Files(files ...*File) *RequestBuilder

Files sets multiple files at once.

func (*RequestBuilder) Form 

func (b *RequestBuilder) Form(v any) *RequestBuilder

Form sets form fields and files for the request.

func (*RequestBuilder) FormField 

func (b *RequestBuilder) FormField(key, val string) *RequestBuilder

FormField adds or updates a form field.

func (*RequestBuilder) FormFields 

func (b *RequestBuilder) FormFields(fields any) *RequestBuilder

FormFields sets multiple form fields at once.

func (*RequestBuilder) Header 

func (b *RequestBuilder) Header(key, value string) *RequestBuilder

Header sets (or replaces) a header in the request.

func (*RequestBuilder) Headers 

func (b *RequestBuilder) Headers(headers http.Header) *RequestBuilder

Headers set headers to the request.

func (*RequestBuilder) JSONBody added in v0.2.2 

func (b *RequestBuilder) JSONBody(v any) *RequestBuilder

JSONBody sets the request body as JSON.

func (*RequestBuilder) MaxRetries 

func (b *RequestBuilder) MaxRetries(maxRetries int) *RequestBuilder

MaxRetries sets the maximum number of retry attempts.

func (*RequestBuilder) Method 

func (b *RequestBuilder) Method(method string) *RequestBuilder

Method sets the HTTP method for the request.

func (*RequestBuilder) Path 

func (b *RequestBuilder) Path(path string) *RequestBuilder

Path sets the URL path for the request.

func (*RequestBuilder) PathParam 

func (b *RequestBuilder) PathParam(key, value string) *RequestBuilder

PathParam sets a single path param field and its value in the RequestBuilder instance.

func (*RequestBuilder) PathParams 

func (b *RequestBuilder) PathParams(params map[string]string) *RequestBuilder

PathParams sets multiple path params fields and their values at one go in the RequestBuilder instance.

func (*RequestBuilder) Queries 

func (b *RequestBuilder) Queries(params url.Values) *RequestBuilder

Queries adds query parameters to the request.

func (*RequestBuilder) QueriesStruct 

func (b *RequestBuilder) QueriesStruct(queryStruct any) *RequestBuilder

QueriesStruct adds query parameters to the request based on a struct tagged with url tags.

func (*RequestBuilder) Query 

func (b *RequestBuilder) Query(key, value string) *RequestBuilder

Query adds a single query parameter to the request.

func (*RequestBuilder) RawBody 

func (b *RequestBuilder) RawBody(v []byte) *RequestBuilder

RawBody sets the request body as raw bytes.

func (*RequestBuilder) Referer 

func (b *RequestBuilder) Referer(referer string) *RequestBuilder

Referer sets the Referer header for the request.

func (*RequestBuilder) RetryIf 

func (b *RequestBuilder) RetryIf(retryIf RetryIfFunc) *RequestBuilder

RetryIf sets the custom retry condition function.

func (*RequestBuilder) RetryStrategy 

func (b *RequestBuilder) RetryStrategy(strategy BackoffStrategy) *RequestBuilder

RetryStrategy sets the backoff strategy for retries.

func (*RequestBuilder) Send 

func (b *RequestBuilder) Send(ctx context.Context) (*Response, error)

Send executes the HTTP request.

func (*RequestBuilder) Stream added in v0.2.0 

func (b *RequestBuilder) Stream(callback StreamCallback) *RequestBuilder

Stream sets the stream callback for the request.

func (*RequestBuilder) StreamDone added in v0.2.1 

func (b *RequestBuilder) StreamDone(callback StreamDoneCallback) *RequestBuilder

StreamDone sets the done callback for the request.

func (*RequestBuilder) StreamErr added in v0.2.1 

func (b *RequestBuilder) StreamErr(callback StreamErrCallback) *RequestBuilder

StreamErr sets the error callback for the request.

func (*RequestBuilder) TextBody 

func (b *RequestBuilder) TextBody(v string) *RequestBuilder

TextBody sets the request body as plain text.

func (*RequestBuilder) Timeout 

func (b *RequestBuilder) Timeout(timeout time.Duration) *RequestBuilder

Timeout sets the request timeout.

func (*RequestBuilder) UserAgent 

func (b *RequestBuilder) UserAgent(userAgent string) *RequestBuilder

UserAgent sets the User-Agent header for the request.

func (*RequestBuilder) XMLBody 

func (b *RequestBuilder) XMLBody(v any) *RequestBuilder

XMLBody sets the request body as XML.

func (*RequestBuilder) YAMLBody 

func (b *RequestBuilder) YAMLBody(v any) *RequestBuilder

YAMLBody sets the request body as YAML.

type Response 

type Response struct {
	RawResponse *http.Response  // RawResponse is the underlying HTTP response.
	BodyBytes   []byte          // BodyBytes contains the buffered response body for non-streaming responses.
	Context     context.Context // Context is the request context associated with the response.
	Client      *Client         // Client is the client that created the response.
	// contains filtered or unexported fields
}

Response represents an HTTP response.

func NewResponse 

func NewResponse(
	ctx context.Context,
	resp *http.Response,
	client *Client,
	stream StreamCallback,
	streamErr StreamErrCallback,
	streamDone StreamDoneCallback,
) (*Response, error)

NewResponse creates a new wrapped response object, leveraging the buffer pool for efficient memory usage.

func (*Response) Body 

func (r *Response) Body() []byte

Body returns the response body as a byte slice.

func (*Response) Close 

func (r *Response) Close() error

Close closes the response body.

func (*Response) ContentLength 

func (r *Response) ContentLength() int

ContentLength returns the length of the response body.

func (*Response) ContentType 

func (r *Response) ContentType() string

ContentType returns the value of the "Content-Type" header.

func (*Response) Cookies 

func (r *Response) Cookies() []*http.Cookie

Cookies parses and returns the cookies set in the response.

func (*Response) Header 

func (r *Response) Header() http.Header

Header returns the response headers.

func (*Response) IsClientError added in v0.3.13 

func (r *Response) IsClientError() bool

IsClientError checks if the response status code indicates a client error (400 - 499).

func (*Response) IsContentType 

func (r *Response) IsContentType(contentType string) bool

IsContentType checks if the response Content-Type header matches a given content type.

func (*Response) IsEmpty 

func (r *Response) IsEmpty() bool

IsEmpty checks if the response body is empty.

func (*Response) IsError added in v0.3.13 

func (r *Response) IsError() bool

IsError checks if the response status code indicates an error (>= 400).

func (*Response) IsJSON 

func (r *Response) IsJSON() bool

IsJSON checks if the response Content-Type indicates JSON.

func (*Response) IsRedirect added in v0.3.13 

func (r *Response) IsRedirect() bool

IsRedirect checks if the response status code indicates a redirect (300 - 399).

func (*Response) IsServerError added in v0.3.13 

func (r *Response) IsServerError() bool

IsServerError checks if the response status code indicates a server error (>= 500).

func (*Response) IsSuccess 

func (r *Response) IsSuccess() bool

IsSuccess checks if the response status code indicates success (200 - 299).

func (*Response) IsXML 

func (r *Response) IsXML() bool

IsXML checks if the response Content-Type indicates XML.

func (*Response) IsYAML 

func (r *Response) IsYAML() bool

IsYAML checks if the response Content-Type indicates YAML.

func (*Response) Lines added in v0.2.4 

func (r *Response) Lines() iter.Seq[[]byte]

Lines returns an iterator that yields each line of the response body as []byte. This method is available in Go 1.23+ and provides a convenient way to iterate over response lines without loading the entire body into memory. The iterator will automatically handle the scanning and yield each line. Note: This method is designed for non-streaming responses and will return an empty iterator for streaming responses.

func (*Response) Location 

func (r *Response) Location() (*url.URL, error)

Location returns the URL redirected address.

func (*Response) Save 

func (r *Response) Save(v any) error

Save saves the response body to a file or io.Writer.

func (*Response) Scan 

func (r *Response) Scan(v any) error

Scan attempts to unmarshal the response body based on its content type.

func (*Response) ScanJSON 

func (r *Response) ScanJSON(v any) error

ScanJSON unmarshals the response body into a struct via JSON decoding.

func (*Response) ScanXML 

func (r *Response) ScanXML(v any) error

ScanXML unmarshals the response body into a struct via XML decoding.

func (*Response) ScanYAML 

func (r *Response) ScanYAML(v any) error

ScanYAML unmarshals the response body into a struct via YAML decoding.

func (*Response) Status 

func (r *Response) Status() string

Status returns the status string of the response (e.g., "200 OK").

func (*Response) StatusCode 

func (r *Response) StatusCode() int

StatusCode returns the HTTP status code of the response.

func (*Response) String 

func (r *Response) String() string

String returns the response body as a string.

func (*Response) URL 

func (r *Response) URL() *url.URL

URL returns the request URL that elicited the response.

type RetryConfig 

type RetryConfig struct {
	MaxRetries int             // MaxRetries is the maximum number of retry attempts.
	Strategy   BackoffStrategy // Strategy computes the delay before the next retry.
	RetryIf    RetryIfFunc     // RetryIf decides whether a request should be retried.
}

RetryConfig defines the configuration for retrying requests.

type RetryIfFunc 

type RetryIfFunc func(req *http.Request, resp *http.Response, err error) bool

RetryIfFunc defines the function signature for retry conditions.

type SmartRedirectPolicy added in v0.3.13 

type SmartRedirectPolicy struct {
	// contains filtered or unexported fields
}

SmartRedirectPolicy is a redirect policy that downgrades POST to GET on 301/302/303 redirects and strips sensitive headers on cross-host or scheme-downgrade redirects.

func NewSmartRedirectPolicy added in v0.3.13 

func NewSmartRedirectPolicy(maxRedirects int) *SmartRedirectPolicy

NewSmartRedirectPolicy creates a new SmartRedirectPolicy with the given redirect limit.

func (*SmartRedirectPolicy) Apply added in v0.3.13 

func (s *SmartRedirectPolicy) Apply(req *http.Request, via []*http.Request) error

Apply enforces the redirect limit, performs method downgrade for 301/302/303, and strips sensitive headers on cross-host or HTTPS-to-HTTP redirects.

type StreamCallback added in v0.2.0 

type StreamCallback func([]byte) error

StreamCallback is a callback function that is called when data is received.

type StreamDoneCallback added in v0.2.0 

type StreamDoneCallback func()

StreamDoneCallback is a callback function that is called when the stream is done.

type StreamErrCallback added in v0.2.0 

type StreamErrCallback func(error)

StreamErrCallback is a callback function that is called when an error occurs.

type XMLDecoder 

type XMLDecoder struct {
	UnmarshalFunc func(data []byte, v any) error // UnmarshalFunc unmarshals XML data into a value.
}

XMLDecoder handles decoding of XML data.

func (*XMLDecoder) Decode 

func (d *XMLDecoder) Decode(r io.Reader, v any) error

Decode reads the data from the reader and unmarshals it into the provided value.

type XMLEncoder 

type XMLEncoder struct {
	MarshalFunc func(v any) ([]byte, error) // MarshalFunc marshals a value into XML.
}

XMLEncoder handles encoding of XML data.

func (*XMLEncoder) ContentType 

func (e *XMLEncoder) ContentType() string

ContentType returns the content type for XML data.

func (*XMLEncoder) Encode 

func (e *XMLEncoder) Encode(v any) (io.Reader, error)

Encode marshals the provided value into XML format.

type YAMLDecoder 

type YAMLDecoder struct {
	UnmarshalFunc func(data []byte, v any) error // UnmarshalFunc unmarshals YAML data into a value.
}

YAMLDecoder handles decoding of YAML data.

func (*YAMLDecoder) Decode 

func (d *YAMLDecoder) Decode(r io.Reader, v any) error

Decode reads the data from the reader and unmarshals it into the provided value.

type YAMLEncoder 

type YAMLEncoder struct {
	MarshalFunc func(v any) ([]byte, error) // MarshalFunc marshals a value into YAML.
}

YAMLEncoder handles encoding of YAML data.

func (*YAMLEncoder) ContentType 

func (e *YAMLEncoder) ContentType() string

ContentType returns the content type for YAML data.

func (*YAMLEncoder) Encode 

func (e *YAMLEncoder) Encode(v any) (io.Reader, error)

Encode marshals the provided value into YAML format.

Source Files

View all Source files

Directories

Path Synopsis
browser module
The examples command demonstrates basic usage of the requests package.
 The examples command demonstrates basic usage of the requests package.
fingerprint module
http3 module
Package middlewares provides reusable middleware components for the requests HTTP client, including caching, cookie management, and header injection.
 Package middlewares provides reusable middleware components for the requests HTTP client, including caching, cookie management, and header injection.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.