requests

package module
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: May 1, 2026 License: MIT Imports: 35 Imported by: 1

README

requests

Go Version License

A fluent HTTP client library for Go with middleware, retries, proxy and redirect controls, streaming callbacks, ordered-header intent, optional client profiles, 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, resolver/dialer hooks, and connection pooling.
  • Ordered headers: Express header order as request intent with orderedobject, while preserving net/http header semantics.
  • Optional profiles: Apply browser-like headers, TLS ClientHello fingerprints, or HTTP/3 through separate extension modules.
  • net/http adapters: Use configured requests clients as *http.Client or http.RoundTripper in other SDKs.
  • Response helpers: Decode JSON, XML, or YAML, inspect diagnostics, 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+.

Optional extension modules:

go get github.com/kaptinlin/requests/browser
go get github.com/kaptinlin/requests/fingerprint
go get github.com/kaptinlin/requests/http3

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")
Optional profiles

Browser-like defaults:

import (
	"github.com/kaptinlin/requests"
	"github.com/kaptinlin/requests/browser"
)

client := requests.New(
	requests.WithProfile(browser.Chrome()),
)

Profiles apply client-level defaults. Request-local headers still override profile headers.

TLS fingerprint profile:

import (
	"github.com/kaptinlin/requests"
	"github.com/kaptinlin/requests/fingerprint"
)

client := requests.New(
	requests.WithProfile(fingerprint.Chrome()),
)

HTTP/3 profile:

import (
	"crypto/tls"

	"github.com/kaptinlin/requests"
	"github.com/kaptinlin/requests/http3"
)

client := requests.New(
	requests.WithProfile(http3.Profile(http3.WithTLSConfig(&tls.Config{
		MinVersion: tls.VersionTLS13,
	}))),
)

Optional profile packages keep heavier dependencies out of the core module:

  • github.com/kaptinlin/requests/browser applies browser-like headers, ordered header metadata, and HTTP/2 preference.
  • github.com/kaptinlin/requests/fingerprint applies uTLS ClientHello fingerprints.
  • github.com/kaptinlin/requests/http3 applies a QUIC HTTP/3 transport.
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

Ordered headers
import "github.com/kaptinlin/orderedobject"

headers := orderedobject.NewObject[[]string]().
	Set("Accept", []string{"application/json"}).
	Set("User-Agent", []string{"requests-example/1.0"})

resp, err := client.Get("/articles").
	OrderedHeaders(headers).
	Send(context.Background())

Default net/http transports preserve header semantics. Transports that explicitly read requests.OrderedHeaders(req) can use the metadata for wire-order delivery.

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())

For larger multipart bodies, use the streaming multipart builder:

body := requests.NewMultipart().
	Field("user", "alice").
	File("avatar", "avatar.png", file)

resp, err := client.Post("/upload").
	Multipart(body).
	Send(context.Background())

Use Replayable(maxBytes) when a multipart request must be replayable for retries:

body := requests.NewMultipart().
	Field("user", "alice").
	FileString("note", "note.txt", "hello").
	Replayable(1 << 20)

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())

Use MaxRetries(0) on a request to disable a positive client default. Replayable request bodies are restored before retry attempts; non-replayable streaming bodies are attempted once.

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

net/http Integration

Use AsHTTPClient() when another SDK accepts *http.Client:

httpClient := client.AsHTTPClient()
resp, err := httpClient.Get("https://api.example.com/resource")

Use AsTransport() when the caller owns the http.Client:

httpClient := &http.Client{
	Transport: client.AsTransport(),
}

The adapter applies client headers, cookies, auth, and client middleware. It does not run request-builder retries, response buffering, streaming callbacks, or decoding helpers.

Session and Dialing

client := requests.New(
	requests.WithSession(),
	requests.WithHTTP2(),
	requests.WithResolver(net.DefaultResolver),
)

WithSession() creates a cookie jar and TLS session cache when missing. WithDialContext and WithLocalAddr are available for custom gateway and network binding setups.

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")
}
Inspect diagnostics
fmt.Println(resp.Elapsed())
fmt.Println(resp.Attempts())
fmt.Println(resp.Protocol())
fmt.Println(resp.TLS() != nil)

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 root tests with race detection
task test:all   # Run root and extension tests with race detection
task lint       # Run root golangci-lint and tidy checks
task lint:all   # Run root and extension linters
task tidy:all   # Tidy root and extension modules
task verify     # Run deps, fmt, vet, lint, test, and vuln checks for root

Contributing

Contributions are welcome. Open an issue or pull request with a focused change, and run task test:all plus task lint:all before submitting changes that touch extension modules.

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")

	// ErrRequestBodyNotReplayable is returned when a retry needs a request body that cannot be replayed.
	ErrRequestBodyNotReplayable = errors.New("request body is not replayable")

	// ErrRequestBodyReadIncomplete is returned when a replayable request body cannot be fully read.
	ErrRequestBodyReadIncomplete = errors.New("request body read incomplete")

	// 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 OrderedHeaders added in v0.5.0 

func OrderedHeaders(req *http.Request) (*orderedobject.Object[[]string], bool)

OrderedHeaders returns the ordered header metadata attached to req, when present.

Default net/http transports do not guarantee wire-order delivery. This metadata is intended for transports that explicitly support ordered headers.

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.
	OrderedHeaders *orderedobject.Object[[]string] // OrderedHeaders contains ordered default headers.
	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) ApplyProfile added in v0.5.0 

func (c *Client) ApplyProfile(profile Profile) error

ApplyProfile applies profile to the client.

func (*Client) AsHTTPClient added in v0.5.0 

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

AsHTTPClient returns a net/http client that applies this client's defaults.

The returned client preserves the underlying timeout, cookie jar, redirect policy, and transport at the time AsHTTPClient is called. Its transport applies client headers, cookies, auth, and client-level middleware. RequestBuilder-only behavior such as retries, response buffering, streaming callbacks, and decoding helpers is not part of the returned client.

func (*Client) AsTransport added in v0.5.0 

func (c *Client) AsTransport() http.RoundTripper

AsTransport returns a RoundTripper that applies this client's defaults.

Use it when another library owns the *http.Client and only lets callers replace http.Client.Transport. The returned transport snapshots client headers, cookies, auth, middleware, and the underlying transport at call time.

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) EnableHTTP2 added in v0.5.0 

func (c *Client) EnableHTTP2() *Client

EnableHTTP2 enables HTTP/2 on the underlying HTTP transport.

func (*Client) EnableSession added in v0.5.0 

func (c *Client) EnableSession() *Client

EnableSession enables cookie and TLS session reuse without replacing existing session stores.

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) SetDefaultOrderedHeaders added in v0.5.0 

func (c *Client) SetDefaultOrderedHeaders(headers *orderedobject.Object[[]string])

SetDefaultOrderedHeaders sets ordered 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) SetDialContext added in v0.5.0 

func (c *Client) SetDialContext(dial func(context.Context, string, string) (net.Conn, error)) *Client

SetDialContext sets the dial function on the underlying transport.

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) SetLocalAddr added in v0.5.0 

func (c *Client) SetLocalAddr(addr net.Addr) *Client

SetLocalAddr sets the local address used by the default transport dialer.

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) SetResolver added in v0.5.0 

func (c *Client) SetResolver(resolver *net.Resolver) *Client

SetResolver sets the resolver used by the default transport dialer.

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 WithDialContext added in v0.5.0 

func WithDialContext(dial func(context.Context, string, string) (net.Conn, error)) ClientOption

WithDialContext sets the dial function on the underlying transport.

func WithDialTimeout added in v0.3.14 

func WithDialTimeout(d time.Duration) ClientOption

WithDialTimeout sets the TCP connection timeout on the underlying transport.

func WithHTTP2 added in v0.5.0 

func WithHTTP2() ClientOption

WithHTTP2 enables HTTP/2 transport support.

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 WithLocalAddr added in v0.5.0 

func WithLocalAddr(addr net.Addr) ClientOption

WithLocalAddr sets the local address used by the default transport dialer.

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 WithOrderedHeaders added in v0.5.0 

func WithOrderedHeaders(headers *orderedobject.Object[[]string]) ClientOption

WithOrderedHeaders sets ordered default headers on the client.

func WithProfile added in v0.5.0 

func WithProfile(profile Profile) ClientOption

WithProfile applies a coherent client identity profile.

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 WithResolver added in v0.5.0 

func WithResolver(resolver *net.Resolver) ClientOption

WithResolver sets the resolver used by the default transport dialer.

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 WithSession added in v0.5.0 

func WithSession() ClientOption

WithSession enables cookie and TLS session reuse.

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.
	OrderedHeaders    *orderedobject.Object[[]string] // OrderedHeaders contains ordered default headers.
	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 on the default HTTP transport.
	Resolver          *net.Resolver                   // Resolver customizes name resolution for the default transport dialer.
	// DialContext is the dial function used by the default transport.
	DialContext func(context.Context, string, string) (net.Conn, error)
	LocalAddr   net.Addr // LocalAddr is the local address used by the default transport dialer.

	// 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 FilePart added in v0.5.0 

type FilePart struct {
	Field       string
	Filename    string
	ContentType string
	Body        io.Reader
}

FilePart describes one multipart file part.

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 Multipart added in v0.5.0 

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

Multipart builds a multipart/form-data request body.

func NewMultipart added in v0.5.0 

func NewMultipart() *Multipart

NewMultipart creates an empty multipart builder.

func (*Multipart) Boundary added in v0.5.0 

func (m *Multipart) Boundary(boundary string) *Multipart

Boundary sets the multipart boundary.

func (*Multipart) Field added in v0.5.0 

func (m *Multipart) Field(name, value string) *Multipart

Field adds a form field.

func (*Multipart) File added in v0.5.0 

func (m *Multipart) File(field, filename string, r io.Reader) *Multipart

File adds a file part.

func (*Multipart) FileBytes added in v0.5.0 

func (m *Multipart) FileBytes(field, filename string, data []byte) *Multipart

FileBytes adds a file part backed by bytes.

func (*Multipart) FileString added in v0.5.0 

func (m *Multipart) FileString(field, filename, data string) *Multipart

FileString adds a file part backed by a string.

func (*Multipart) Part added in v0.5.0 

func (m *Multipart) Part(part FilePart) *Multipart

Part adds a file part with explicit metadata.

func (*Multipart) Replayable added in v0.5.0 

func (m *Multipart) Replayable(maxBytes int64) *Multipart

Replayable buffers the multipart body up to maxBytes so it can be replayed for retries.

type NoProxy added in v0.3.13 

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

NoProxy holds parsed bypass rules for proxy exclusion.

type Profile added in v0.5.0 

type Profile interface {
	Name() string
	Apply(*Client) error
}

Profile applies a coherent client identity to a Client.

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, multipart bodies, 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 adds cookies from a 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) Multipart added in v0.5.0 

func (b *RequestBuilder) Multipart(m *Multipart) *RequestBuilder

Multipart sets a multipart/form-data body built by Multipart.

func (*RequestBuilder) OrderedHeaders added in v0.5.0 

func (b *RequestBuilder) OrderedHeaders(headers *orderedobject.Object[[]string]) *RequestBuilder

OrderedHeaders sets ordered headers 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) Attempts added in v0.5.0 

func (r *Response) Attempts() int

Attempts returns the total number of transport attempts, including the first request.

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) Elapsed added in v0.5.0 

func (r *Response) Elapsed() time.Duration

Elapsed returns the duration from request dispatch through response setup.

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 over the buffered response body lines.

func (*Response) Location 

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

Location returns the URL redirected address.

func (*Response) Protocol added in v0.5.0 

func (r *Response) Protocol() string

Protocol returns the response protocol, such as "HTTP/1.1" or "HTTP/2.0".

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) TLS added in v0.5.0 

func (r *Response) TLS() *tls.ConnectionState

TLS returns a copy of the response TLS connection state, if any.

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 handles a streamed response chunk.

type StreamDoneCallback added in v0.2.0 

type StreamDoneCallback func()

StreamDoneCallback runs after streaming finishes.

type StreamErrCallback added in v0.2.0 

type StreamErrCallback func(error)

StreamErrCallback handles a streaming read error.

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.