relay

type AdaptiveTimeoutConfig struct {
	// Percentile is the latency percentile to use as the base (e.g. 0.95 for p95).
	// Default: 0.95.
	Percentile float64
	// Multiplier scales the percentile latency to get the timeout (e.g. 2.0 = 2x p95).
	// Default: 2.0.
	Multiplier float64
	// WindowSize is the number of recent observations to keep.
	// Default: 100.
	WindowSize int
	// MinTimeout is the minimum timeout regardless of observed latency.
	// Default: 100ms.
	MinTimeout time.Duration
	// MaxTimeout is the maximum timeout cap.
	// Default: 30s.
	MaxTimeout time.Duration
	// InitialTimeout is used until enough observations accumulate.
	// Default: 5s.
	InitialTimeout time.Duration
}

type AsyncResult struct {
	Response *Response
	Err      error
}

type BasicAuthCreds struct {
	Username string
	Password string
}

type BatchResult struct {
	// Index is the position of this result in the original request slice,
	// allowing callers to correlate results with their requests.
	Index int
	// Response is the HTTP response, or nil if Err is non-nil.
	Response *Response
	// Err is the error returned by Execute, or nil on success.
	Err error
}

type BeforeRedirectHookFunc func(req *http.Request, via []*http.Request) error

type BeforeRetryHookFunc func(ctx context.Context, attempt int, req *Request, httpResp *http.Response, err error)

type CacheStore interface {
	// Get returns the cached entry for key and true if found, or nil and false
	// if the key is absent or the entry has expired.
	Get(key string) (*CachedResponse, bool)

	// Set stores or replaces the entry for key.
	Set(key string, entry *CachedResponse)

	// Delete removes the entry for key. It is a no-op if the key is absent.
	Delete(key string)

	// Clear removes all entries from the store.
	Clear()
}

type CachedResponse struct {
	// StatusCode is the HTTP status code of the original response.
	StatusCode int

	// Status is the human-readable status line (e.g. "200 OK").
	Status string

	// Headers is a clone of the original response headers.
	Headers http.Header

	// Body is the full response body bytes.
	Body []byte

	// ExpiresAt is the absolute time after which this entry must not be served.
	// A zero value means the entry has no expiry derived from the response.
	ExpiresAt time.Time

	// ETag is the value of the ETag response header, used for conditional
	// revalidation via If-None-Match on subsequent requests.
	ETag string

	// LastModified is the value of the Last-Modified response header, used for
	// conditional revalidation via If-Modified-Since when ETag is absent.
	LastModified string
}

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

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

type CircuitBreakerConfig struct {
	// MaxFailures is the number of consecutive failures in StateClosed that
	// trips the breaker to StateOpen. Must be > 0.
	MaxFailures int

	// ResetTimeout is how long the breaker stays in StateOpen before
	// automatically transitioning to StateHalfOpen to probe recovery.
	ResetTimeout time.Duration

	// HalfOpenRequests is the maximum number of probe requests allowed while
	// in StateHalfOpen. Additional requests are rejected until the breaker
	// decides to close or re-open.
	HalfOpenRequests int

	// SuccessThreshold is the number of consecutive successes required while
	// in StateHalfOpen to transition back to StateClosed.
	SuccessThreshold int

	// OnStateChange is an optional callback invoked on every state transition.
	// It receives the previous and new states. The callback is invoked OUTSIDE
	// the breaker's internal mutex - it is safe to call breaker methods from
	// within it.
	OnStateChange func(from, to CircuitBreakerState)
}

type CircuitBreakerState int

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

type CompressionAlgorithm int

type Config struct {
	// BaseURL is prepended to every request path that does not start with
	// "http://" or "https://". Trailing slashes are normalised automatically.
	BaseURL string

	// Timeout is the end-to-end deadline for a complete request/response cycle,
	// including all retry attempts. Set per-request timeouts via
	// [Request.WithTimeout] for finer-grained control.
	Timeout time.Duration

	// MaxIdleConns is the maximum total number of idle (keep-alive) connections
	// across all hosts in the pool.
	MaxIdleConns int

	// MaxIdleConnsPerHost is the maximum number of idle connections kept per
	// individual host.
	MaxIdleConnsPerHost int

	// MaxConnsPerHost limits the total number of connections (active + idle) per
	// host. 0 means unlimited.
	MaxConnsPerHost int

	// IdleConnTimeout is how long an idle keep-alive connection remains open
	// before being evicted from the pool.
	IdleConnTimeout time.Duration

	// TLSHandshakeTimeout is the deadline for completing the TLS handshake.
	TLSHandshakeTimeout time.Duration

	// ResponseHeaderTimeout is the deadline to read the response headers after
	// the request body has been sent. 0 disables the timeout.
	ResponseHeaderTimeout time.Duration

	// DialTimeout is the maximum time allowed for a TCP connection to be
	// established.
	DialTimeout time.Duration

	// DialKeepAlive is the interval between TCP keep-alive probes sent on an
	// active connection.
	DialKeepAlive time.Duration

	// ExpectContinueTimeout is the maximum time to wait for a server's first
	// response headers after fully writing the request headers if the request
	// has an Expect: 100-continue header. Zero means no specific timeout.
	ExpectContinueTimeout time.Duration

	// TLSConfig replaces the default TLS configuration. When nil, a config
	// enforcing TLS 1.2 as the minimum version is used.
	TLSConfig *tls.Config

	// ProxyURL is the URL of the HTTP/HTTPS proxy to use for all requests.
	// When empty, the proxy is sourced from the HTTP_PROXY / HTTPS_PROXY
	// environment variables.
	ProxyURL string

	// CookieJar manages cookie storage across requests. Set to nil to disable
	// automatic cookie handling.
	CookieJar http.CookieJar

	// CacheStore is the backend used to cache HTTP responses. When nil, caching
	// is disabled. Use [NewInMemoryCacheStore] or implement [CacheStore] for
	// custom backends such as Redis.
	CacheStore CacheStore

	// CustomDialer replaces the default net.Dialer. When set, DialTimeout and
	// DialKeepAlive are ignored in favour of the dialer's own settings.
	CustomDialer *net.Dialer

	// DNSOverrides maps hostnames to fixed IP addresses, bypassing DNS
	// resolution for those hosts. Example: {"api.internal": "10.0.0.42"}.
	DNSOverrides map[string]string

	// RetryConfig controls retry behaviour. When nil, a sensible default
	// (3 attempts, exponential backoff) is used.
	RetryConfig *RetryConfig

	// RetryBudget limits the fraction of requests that may be retried within a
	// sliding window to prevent retry storms. When nil, no budget is enforced.
	RetryBudget *RetryBudget

	// CircuitBreakerConfig controls the circuit breaker. When nil, a default
	// (5 failures → Open, 60 s reset) is used. Set explicitly to nil with
	// [WithDisableCircuitBreaker] to disable it entirely.
	CircuitBreakerConfig *CircuitBreakerConfig

	// RateLimitConfig enables the client-side token-bucket rate limiter.
	// When nil, rate limiting is disabled.
	RateLimitConfig *RateLimitConfig

	// LoadBalancerConfig distributes requests across multiple backend URLs.
	// When set, BaseURL is ignored and a backend is selected per request.
	// When nil, load balancing is disabled.
	LoadBalancerConfig *LoadBalancerConfig

	// DefaultHeaders are merged into every outgoing request. Per-request headers
	// always take precedence over these defaults.
	DefaultHeaders map[string]string

	// DisableCompression disables automatic Accept-Encoding negotiation and
	// transparent response decompression.
	DisableCompression bool

	// RequestCompression enables transparent gzip compression of request bodies.
	// Requests with no body are not affected. Content-Encoding is set automatically.
	// Set via [WithRequestCompression] or [WithRequestCompressionLevel].
	RequestCompression bool

	// RequestCompressionLevel is the gzip compression level (0-9).
	// A value of 0 means gzip.DefaultCompression is used.
	// Only meaningful when RequestCompression is true.
	RequestCompressionLevel int

	// DisableTiming skips per-request timing instrumentation (httptrace).
	// When true, [Response.Timing] fields are all zero and roughly 10
	// allocations per request are avoided. Useful for high-throughput
	// scenarios where timing metrics are not needed.
	DisableTiming bool

	// MaxRedirects is the maximum number of redirects to follow automatically.
	// Set to 0 to disable redirect following.
	MaxRedirects int

	// MaxResponseBodyBytes is the maximum number of body bytes buffered by
	// [Execute]. Responses exceeding this limit are truncated and
	// [Response.IsTruncated] returns true. Set to 0 for no limit (default 10 MB).
	MaxResponseBodyBytes int64

	// TransportMiddlewares is a chain of [http.RoundTripper] wrappers applied
	// around the core transport. Middleware is applied outermost-last - the last
	// appended middleware is the first to intercept a request.
	TransportMiddlewares []func(http.RoundTripper) http.RoundTripper

	// OnBeforeRequest is a list of hooks called before each request attempt
	// (including retries). A hook that returns a non-nil error cancels the
	// request immediately.
	OnBeforeRequest []func(context.Context, *Request) error

	// OnAfterResponse is a list of hooks called after a successful response is
	// received (after all retries, before returning to the caller). A hook that
	// returns a non-nil error propagates as the [Client.Execute] return value.
	OnAfterResponse []func(context.Context, *Response) error

	// ErrorDecoder is called by [Client.Execute] whenever the HTTP response
	// status code is >= 400. It receives the numeric status code and the full,
	// already-buffered response body. When the function returns a non-nil error,
	// [Client.Execute] releases the response and returns that error directly to
	// the caller. When it returns nil the response is returned normally,
	// preserving the default behaviour where HTTP error codes are not
	// automatically treated as errors.
	//
	// ErrorDecoder is invoked after all [OnAfterResponse] hooks have run.
	// Use [WithErrorDecoder] to set it.
	ErrorDecoder func(statusCode int, body []byte) error

	// ResponseDecoder is used by [Response.Decode] and [ExecuteAs] to
	// deserialise response bodies into Go values. When set, it replaces the
	// default encoding/json and encoding/xml decoders. The contentType
	// parameter receives the response Content-Type header (e.g.
	// "application/json", "application/protobuf") so the decoder can pick
	// the right format.
	//
	// Returning a non-nil error from ResponseDecoder propagates as the error
	// from [Response.Decode] or [ExecuteAs].
	//
	// Use [WithResponseDecoder] to set it.
	ResponseDecoder func(contentType string, body []byte, v any) error

	// ResponseValidator is applied after each successful (2xx) response body
	// is read. The body is decoded into an interface{} and passed to Validate.
	// If validation fails, Execute returns a [ValidationError].
	//
	// Use [WithResponseValidator] to set it.
	ResponseValidator SchemaValidator

	// Signer is called for each outgoing HTTP request, after all headers and
	// the idempotency key have been applied, and before the request is sent.
	// Use it to implement request authentication that must inspect and/or
	// mutate the final *http.Request (e.g. HMAC-SHA256, OAuth 1.0a, JWS).
	//
	// Returning a non-nil error from Sign aborts the request attempt and
	// propagates as the [Client.Execute] error.
	//
	// Use [WithSigner] to set it.
	Signer RequestSigner

	// CredentialProvider is called before each outgoing request (including
	// retries) to supply fresh credentials. It runs before [Signer], allowing
	// dynamic tokens (e.g. OAuth, Vault) without rebuilding the client.
	//
	// Use [WithCredentialProvider] to set it.
	CredentialProvider CredentialProvider

	// Logger is used for internal structured logging (retries, circuit-breaker
	// transitions, rate-limit events, shutdown). Defaults to NoopLogger.
	Logger Logger

	// TLSPins is a list of SHA-256 certificate fingerprints in the format
	// "sha256/BASE64==". When non-empty, TLS connections whose certificate chain
	// does not match any pin are rejected with ErrCertificatePinMismatch.
	TLSPins []string

	// EnableCoalescing activates request deduplication for concurrent identical
	// GET/HEAD requests. Only one real request is made; all waiters share a copy.
	EnableCoalescing bool

	// Deduplication configures opt-in singleflight request deduplication.
	// When Enabled, concurrent GET/HEAD requests with the same URL are
	// collapsed into a single real HTTP call. All callers receive their own
	// copy of the response body. Disabled by default.
	Deduplication DeduplicationConfig

	// DigestUsername and DigestPassword enable HTTP Digest Authentication.
	DigestUsername string
	DigestPassword string

	// HARRecorder captures all request/response pairs when non-nil.
	HARRecorder *HARRecorder

	// HTTP2PushHandler is called for each HTTP/2 push-promised response.
	// See [WithHTTP2PushHandler] for details and current limitations.
	HTTP2PushHandler PushPromiseHandler

	// AutoIdempotencyKey automatically injects an X-Idempotency-Key header on
	// every request. The same key is reused across retry attempts.
	AutoIdempotencyKey bool

	// AutoIdempotencyOnSafeRetries is like AutoIdempotencyKey but restricts
	// key injection to HTTP methods that are semantically idempotent or safe:
	// GET, HEAD, PUT, OPTIONS, and TRACE. POST, PATCH, and DELETE are skipped
	// unless the caller sets the key explicitly. The same key is reused across
	// all retry attempts for the request.
	AutoIdempotencyOnSafeRetries bool

	// BeforeRetryHooks are called before each retry sleep, in order.
	// attempt is 1-based. httpResp and err reflect the result that triggered
	// the retry; either may be nil. Use [WithBeforeRetryHook] to append hooks.
	BeforeRetryHooks []BeforeRetryHookFunc

	// BeforeRedirectHooks are called before each redirect is followed.
	// Returning a non-nil error stops the redirect chain; the error propagates
	// as the [Client.Execute] return value. Use [WithBeforeRedirectHook].
	BeforeRedirectHooks []BeforeRedirectHookFunc

	// OnErrorHooks are called when [Client.Execute] returns a non-nil error.
	// They run after all internal error handling and are intended for logging
	// and metrics; the return value is discarded. Use [WithOnErrorHook].
	OnErrorHooks []OnErrorHookFunc

	// HealthCheck enables a background goroutine that proactively probes a
	// health endpoint while the circuit breaker is open and resets it on
	// success. Nil disables the feature.
	HealthCheck *HealthCheckConfig

	// DNSCache enables client-side DNS caching with a configurable TTL.
	// Nil disables the feature (default: OS resolver on every dial).
	DNSCache *DNSCacheConfig

	// URLNormalisationMode controls how [BaseURL] is resolved against request
	// paths. Default is NormalisationAuto, which intelligently detects API URLs
	// and applies the best strategy. Can be overridden with [WithURLNormalisation].
	URLNormalisationMode URLNormalisationMode

	// AutoNormaliseBaseURL automatically adds a trailing slash to BaseURL if
	// missing. Enabled by default for API convenience; can be disabled with
	// [WithAutoNormaliseURL](false).
	AutoNormaliseBaseURL bool

	// MaxConcurrentRequests is the maximum number of in-flight requests
	// allowed simultaneously. Zero or negative means no limit.
	MaxConcurrentRequests int

	// EnablePriorityQueue activates priority-aware dequeuing when the bulkhead
	// is at capacity. When enabled, higher-priority requests are dequeued before
	// lower-priority ones. Requests within the same priority level maintain FIFO
	// order. Disabled by default (all requests use PriorityNormal).
	// Only has an effect when MaxConcurrentRequests > 0.
	EnablePriorityQueue bool

	// DefaultAccept is the value sent in the Accept header when no explicit
	// Accept header has been set on the request. Empty string means no default
	// Accept header is added.
	DefaultAccept string

	// UnixSocketPath is the filesystem path of a Unix domain socket to use for
	// all outgoing connections. When set, the TCP dialler is replaced with a
	// Unix socket dialler so that the client communicates with a local server
	// (e.g. the Docker daemon at /var/run/docker.sock) instead of opening a
	// TCP connection. The host in the request URL is still sent as the HTTP
	// Host header; only the transport layer is changed.
	//
	// HTTP/2 is disabled for Unix socket connections because it is not
	// typically negotiated over local sockets.
	//
	// Set via [WithUnixSocket].
	UnixSocketPath string

	// HedgeAfter is the delay before sending a duplicate (hedge) request.
	// Zero disables hedging. When set, a second request is sent after this
	// duration if the first has not completed. The first response wins.
	HedgeAfter time.Duration

	// HedgeMaxAttempts is the maximum number of concurrent hedge requests
	// (including the original). Defaults to 2 when HedgeAfter > 0.
	HedgeMaxAttempts int

	// CertWatcher holds the active dynamic TLS certificate watcher created by
	// [WithDynamicTLSCert] or [WithCertWatcher]. Callers can call Stop() to
	// halt the background reload goroutine.
	CertWatcher *CertWatcher

	// WebSocketDialTimeout is the handshake timeout for [Client.ExecuteWebSocket].
	// Zero uses the client Timeout.
	WebSocketDialTimeout time.Duration

	// SchemeAdapters maps URL schemes to custom [http.RoundTripper] instances.
	// Requests whose scheme matches a key are dispatched to the corresponding
	// transport instead of the default HTTP/HTTPS transport. Set via
	// [WithTransportAdapter].
	SchemeAdapters map[string]http.RoundTripper

	// AdaptiveTimeoutConfig enables adaptive timeout adjustment based on
	// observed response latencies. When set, per-request timeouts are
	// dynamically computed from the percentile of recent latencies.
	// When nil, adaptive timeout is disabled.
	AdaptiveTimeoutConfig *AdaptiveTimeoutConfig
	// contains filtered or unexported fields
}

type CredentialProvider interface {
	Credentials(ctx context.Context) (Credentials, error)
}

type Credentials struct {
	BearerToken string            // sets Authorization: Bearer <token>
	BasicAuth   *BasicAuthCreds   // sets HTTP basic auth
	Headers     map[string]string // arbitrary headers (e.g. X-API-Key)
}

type DNSCacheConfig struct {
	// TTL is how long a resolved address set is considered valid.
	// After expiry the next dial for that hostname triggers a fresh resolution.
	// A typical value is 30 s–5 min depending on how often your upstreams
	// rotate IPs and how quickly you need to detect changes.
	TTL time.Duration
}

type DeduplicationConfig struct {
	// Enabled activates singleflight deduplication for safe methods (GET, HEAD).
	// Default: false.
	Enabled bool
}

type ErrorClass int

type HAR struct {
	Log HARLog `json:"log"`
}

type HARContent struct {
	Size     int    `json:"size"`
	MimeType string `json:"mimeType"`
	Text     string `json:"text,omitempty"`
}

type HARCreator struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type HAREntry struct {
	StartedDateTime string      `json:"startedDateTime"`
	Time            float64     `json:"time"`
	Request         HARRequest  `json:"request"`
	Response        HARResponse `json:"response"`
	Timings         HARTimings  `json:"timings"`
}

type HARLog struct {
	Version string     `json:"version"`
	Creator HARCreator `json:"creator"`
	Entries []HAREntry `json:"entries"`
}

type HARNameVal struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type HARPostData struct {
	MimeType string `json:"mimeType"`
	Text     string `json:"text"`
}

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

type HARRequest struct {
	Method      string       `json:"method"`
	URL         string       `json:"url"`
	HTTPVersion string       `json:"httpVersion"`
	Headers     []HARNameVal `json:"headers"`
	QueryString []HARNameVal `json:"queryString"`
	PostData    *HARPostData `json:"postData,omitempty"`
	BodySize    int          `json:"bodySize"`
	HeadersSize int          `json:"headersSize"`
}

type HARResponse struct {
	Status      int          `json:"status"`
	StatusText  string       `json:"statusText"`
	HTTPVersion string       `json:"httpVersion"`
	Headers     []HARNameVal `json:"headers"`
	Content     HARContent   `json:"content"`
	RedirectURL string       `json:"redirectURL"`
	BodySize    int          `json:"bodySize"`
	HeadersSize int          `json:"headersSize"`
}

type HARTimings struct {
	Send    float64 `json:"send"`
	Wait    float64 `json:"wait"`
	Receive float64 `json:"receive"`
}

type HMACRequestSigner struct {
	// Key is the HMAC-SHA256 signing key. Must not be empty.
	Key []byte
	// Header is the name of the signature header.
	// Defaults to "X-Signature" when empty.
	Header string
}

type HTTPError struct {
	StatusCode int
	Status     string
	Body       []byte
}

type HealthCheckConfig struct {
	// URL is the HTTP endpoint to probe. It must be a fully-qualified URL
	// (e.g. "https://api.example.com/health"). The client issues a plain GET
	// using the standard library - not through the relay pipeline - so the
	// probe is not subject to the main circuit breaker, retries, or rate limiter.
	URL string

	// Interval is how often to send a probe while the circuit is Open.
	// Smaller values recover faster at the cost of more background traffic.
	// A reasonable default is 10–30 seconds.
	Interval time.Duration

	// Timeout is the per-probe HTTP deadline. It should be shorter than
	// Interval so a slow probe does not delay the next one.
	Timeout time.Duration

	// ExpectedStatus is the HTTP status code that signals a healthy upstream.
	// Any 2xx status is accepted when ExpectedStatus is 0.
	ExpectedStatus int
}

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

type LoadBalancerConfig struct {
	// Backends is the list of base URLs to balance across.
	// Must not be empty when used.
	Backends []string

	// Strategy selects the load balancing algorithm.
	// Defaults to RoundRobin if empty.
	Strategy LoadBalancerStrategy
}

type LoadBalancerStrategy string

type Logger interface {
	Debug(msg string, args ...any)
	Info(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
}

type LongPollResult struct {
	// Modified is true when the server returned a new response (not 304).
	Modified bool
	// Response is the full response when Modified is true. Nil on 304.
	Response *Response
	// ETag is the ETag from the response (for the next poll).
	ETag string
}

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

type MultipartField struct {
	// FieldName is the form field name (the name attribute in HTML).
	FieldName string

	// FileName is the filename reported to the server. A non-empty value
	// creates a file part; an empty value creates a plain form field.
	FileName string

	// ContentType is an optional MIME type for file parts.
	// When empty, multipart.Writer uses application/octet-stream.
	ContentType string

	// Content holds in-memory file or field data. Use Reader instead for
	// streaming sources such as os.File to avoid loading the whole file.
	Content []byte

	// Reader is a streaming data source. Takes precedence over Content when
	// both are non-nil. The caller is responsible for closing it after Execute.
	Reader io.Reader
}

type NextPageFunc func(resp *Response) string

type OnErrorHookFunc func(ctx context.Context, req *Request, err error)

type Option func(*Config)

type PageFunc func(resp *Response) (more bool, err error)

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

type Priority int

type ProgressFunc func(transferred, total int64)

type PushPromiseHandler func(pushedURL string, pushedResp *http.Response)

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

type RateLimitConfig struct {
	// RequestsPerSecond is the sustained token replenishment rate, i.e. the
	// long-term maximum number of requests per second.
	RequestsPerSecond float64

	// Burst is the maximum number of tokens that can accumulate above the
	// sustained rate. A burst of N allows N requests to be dispatched
	// immediately before throttling begins.
	Burst int
}

type RedirectInfo struct {
	// From is the URL of the request that received the redirect response.
	From string
	// To is the URL the client was redirected to.
	To string
	// StatusCode is the HTTP status of the redirect response (e.g. 302).
	// Zero if the status could not be determined.
	StatusCode int
}

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

type RequestSigner interface {
	Sign(req *http.Request) error
}

type RequestSignerFunc func(req *http.Request) error

type RequestTiming struct {
	// DNSLookup is the time spent resolving the hostname.
	DNSLookup time.Duration

	// TCPConnect is the time to establish the TCP connection.
	TCPConnect time.Duration

	// TLSHandshake is the time to complete the TLS handshake (0 for plain HTTP).
	TLSHandshake time.Duration

	// TimeToFirstByte (TTFB) is the time from sending the request until the
	// first byte of the response was received.
	TimeToFirstByte time.Duration

	// ContentTransfer is the time from first byte to the full body being read.
	ContentTransfer time.Duration

	// Total is the end-to-end wall-clock duration of the request.
	Total time.Duration
}

type ResolutionResult struct {
	// URL is the final resolved URL as a string
	URL string

	// ParsedURL is the resolved URL parsed into a *url.URL structure
	ParsedURL *url.URL

	// Strategy indicates which normalisation strategy was used:
	// - "Auto" for automatic detection
	// - "RFC3986" for RFC 3986 resolution
	// - "API" for safe string normalisation
	Strategy string

	// IsAPI indicates whether the base URL was detected as an API endpoint
	IsAPI bool
}

type Response struct {
	StatusCode    int
	Status        string
	Headers       http.Header
	Truncated     bool          // true when body was cut at MaxResponseBodyBytes
	RedirectCount int           // number of redirects followed to reach this response
	Timing        RequestTiming // per-phase timing breakdown (DNS, TCP, TLS, TTFB, ...)
	// contains filtered or unexported fields
}

type RetryBudget struct {
	// Ratio is the maximum fraction of requests that can be retried.
	// E.g., 0.1 means at most 10% of requests in the window can be retried.
	Ratio float64
	// Window is the sliding window duration.
	Window time.Duration
	// MinRetry is the minimum number of retries always allowed regardless of ratio.
	// Default 10.
	MinRetry int
}

type RetryConfig struct {
	// MaxAttempts is the total number of tries, including the initial one.
	// Set to 1 to disable retries.
	MaxAttempts int

	// InitialInterval is the base delay before the first retry.
	InitialInterval time.Duration

	// MaxInterval caps the computed backoff delay regardless of how many
	// attempts have been made.
	MaxInterval time.Duration

	// Multiplier grows the interval on each successive attempt.
	// 2.0 produces classic exponential backoff.
	Multiplier float64

	// RandomFactor adds ±jitter proportional to the computed interval.
	// 0 disables jitter entirely; 0.5 adds up to ±50 % random jitter.
	RandomFactor float64

	// RetryableStatus is the set of HTTP status codes that trigger a retry.
	// Defaults to [429, 500, 502, 503, 504].
	RetryableStatus []int

	// RetryIf is an optional predicate called when the built-in logic would
	// retry. Returning false prevents the retry even when the status or error
	// is normally retryable. Either argument may be nil depending on whether
	// the trigger was an HTTP status code or a transport error.
	//
	//	RetryIf: func(resp *http.Response, err error) bool {
	//	    if resp != nil { return resp.StatusCode == 503 }
	//	    return true
	//	}
	RetryIf func(resp *http.Response, err error) bool

	// OnRetry is an optional callback invoked before each retry sleep.
	// attempt is 1-based (first retry = 1). Useful for structured logging.
	// Either resp or err may be nil depending on the failure mode.
	OnRetry func(attempt int, resp *http.Response, err error)
}

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

type SRVBalancer int

type SRVOption func(*SRVResolver)

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

type SSEClientConfig struct {
	// MaxReconnects is the maximum number of reconnect attempts.
	// 0 means unlimited. Default: 0.
	MaxReconnects int
	// ReconnectDelay is the base delay between reconnects.
	// If the server sends a "retry" field, that takes precedence.
	// Default: 3s.
	ReconnectDelay time.Duration
	// EventTypes filters which event types to deliver to the handler.
	// Empty slice means deliver all events (default behaviour).
	EventTypes []string
}

type SSEEvent struct {
	// ID is the event identifier set by the "id" field.
	ID string

	// Event is the event type set by the "event" field.
	// Defaults to "message" when the field is absent, per the SSE spec.
	Event string

	// Data is the concatenated content of all "data" fields in the event,
	// with a newline between each line.
	Data string

	// Retry is the reconnection time in milliseconds from the "retry" field.
	// Zero means no retry directive was received.
	Retry int
}

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

type SSEHandler func(event SSEEvent) bool

type SchemaValidator interface {
	// Validate checks the decoded value and returns an error if validation fails.
	// The value is the result of json.Unmarshal into an interface{}.
	Validate(v interface{}) error
}

type StreamResponse struct {
	// StatusCode is the HTTP status code (e.g. 200).
	StatusCode int

	// Status is the human-readable status line (e.g. "200 OK").
	Status string

	// Headers contains all response headers as received from the server.
	Headers http.Header

	// Body is the live, unbuffered response body. The caller must read from it
	// and eventually close it to release the underlying connection.
	Body io.ReadCloser
}

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

type URLNormalisationMode int

type ValidationError struct {
	Field   string
	Message string
}

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