httpclient

type Config struct {
	Pooling  PoolingConfig
	Timeouts TimeoutsConfig
	TLS      TLSConfig
	Proxy    ProxyConfig
	SSRF     SSRFConfig
}

type Option func(*buildState)

type PoolingConfig struct {
	// MaxIdleConns, MaxIdleConnsPerHost, and MaxConnsPerHost mirror the
	// identically-named http.Transport fields.
	MaxIdleConns        int
	MaxIdleConnsPerHost int
	MaxConnsPerHost     int
	// IdleConnTimeout mirrors http.Transport.IdleConnTimeout.
	IdleConnTimeout time.Duration
	// KeepAlive mirrors net.Dialer.KeepAlive for the underlying TCP dialer.
	KeepAlive time.Duration
	// DisableKeepAlives mirrors http.Transport.DisableKeepAlives. Reusing
	// pooled connections carries no SSRF/DNS-rebinding risk (see the
	// netguard package doc), so this defaults to false even when the SSRF
	// guard is enabled.
	DisableKeepAlives bool
	// EnableHTTP2 opts into HTTP/2. It defaults to false: this package
	// always sets a custom DialContext and/or TLSClientConfig, which makes
	// Go's own Transport conservatively disable HTTP/2 unless explicitly
	// re-enabled — and HTTP/2 connection coalescing (RFC 7540 §9.1.1) can
	// reuse an established connection for a different, SAN-covered hostname
	// without a fresh DialContext validation. Only enable this if that
	// tradeoff has been considered for the caller's use case.
	EnableHTTP2 bool
}

type ProxyConfig struct {
	// Mode selects how the proxy is determined: "none" (default, no proxy),
	// "environment" (use HTTP_PROXY/HTTPS_PROXY/NO_PROXY via Go's own
	// http.ProxyFromEnvironment), or "url" (use URL below, with NoProxy as
	// an explicit bypass list).
	Mode string
	// URL is the proxy URL, used when Mode == "url".
	URL string
	// Username and Password set basic auth credentials for the proxy
	// connection (Proxy-Authorization), used when Mode == "url".
	Username, Password string
	// NoProxy lists hosts to bypass the proxy for, used when Mode == "url".
	// Each entry is an exact host, a ".suffix" domain match, or a CIDR.
	NoProxy []string

	// ProxyTLS configures a SEPARATE, distinct TLS handshake to an
	// https:// proxy itself (e.g. the proxy requires its own client
	// certificate, different from TLS.ClientCertFile/Key used for the
	// origin). Leave nil for the common case where either the proxy is
	// plain (http://) or the proxy's own TLS needs no client cert.
	ProxyTLS *ProxyTLSConfig

	// ConnectHeader, if set, supplies additional headers on the CONNECT
	// request to the proxy (e.g. a bearer-token proxy-auth scheme) —
	// passed through to http.Transport.GetProxyConnectHeader.
	ConnectHeader func(ctx context.Context, proxyURL *url.URL, target string) (http.Header, error)

	// Egress must be set explicitly whenever Mode != "none" AND
	// SSRF.Enabled — see the package doc for why a dial-time IP guard
	// cannot protect the proxied origin.
	Egress ProxyEgressPolicy
}

type ProxyEgressPolicy int

type ProxyTLSConfig struct {
	// RootCAFile loads a PEM-encoded CA bundle from disk. RootCAs, if set,
	// takes precedence. Both empty uses Go's system root pool.
	RootCAFile string
	RootCAs    *x509.CertPool

	// ClientCertFile/ClientKeyFile load a PEM client certificate/key pair
	// for mTLS to the proxy. GetClientCertificate, if set, is used instead
	// and the two file fields are ignored.
	ClientCertFile, ClientKeyFile string
	GetClientCertificate          func(*tls.CertificateRequestInfo) (*tls.Certificate, error)

	InsecureSkipVerify             bool
	InsecureSkipVerifyAcknowledged bool
}

type SSRFConfig struct {
	// Enabled turns the guard on. When true, Policy must be a non-zero
	// netguard.Policy — New returns an error otherwise, rather than
	// silently falling back to one preset over another.
	Enabled bool
	Policy  netguard.Policy
	// MaxRedirects bounds redirect hops. 0 uses netguard's own default (5);
	// a negative value is not distinguished from zero.
	MaxRedirects int
}

type TLSConfig struct {
	// MinVersion and MaxVersion use the tlsconfig.ParseVersion vocabulary
	// ("TLS1_0".."TLS1_3"). Both empty uses Go's own defaults.
	MinVersion, MaxVersion string
	// CipherSuites is a comma-separated list of Go crypto/tls cipher suite
	// names. Empty uses Go's own default secure set. Only affects TLS 1.2
	// and below.
	CipherSuites string
	// CurvePreferences is a comma-separated, order-significant list of
	// curve/group names, e.g. "X25519MLKEM768,X25519,P-256" to prefer the
	// FIPS 203 ML-KEM-768 hybrid group while retaining classical fallbacks
	// for a peer that doesn't support it yet. Empty uses Go's own defaults
	// (no PQC) — enabling a hybrid group is always an explicit opt-in here,
	// never this package's unconditional default.
	CurvePreferences string

	// RootCAFile loads a PEM-encoded CA bundle from disk. RootCAs, if set,
	// takes precedence and is used as-is (e.g. for a caller that already
	// manages certificate rotation itself). Both empty uses Go's system
	// root pool.
	RootCAFile string
	RootCAs    *x509.CertPool

	// ClientCertFile/ClientKeyFile load a PEM client certificate/key pair
	// for mTLS to the origin. GetClientCertificate, if set, is used instead
	// (e.g. for rotation) and the two file fields are ignored.
	ClientCertFile, ClientKeyFile string
	GetClientCertificate          func(*tls.CertificateRequestInfo) (*tls.Certificate, error)

	// InsecureSkipVerify disables certificate chain and hostname
	// verification entirely. It is a narrow, explicitly-named, off-by-
	// default escape hatch: New returns an error unless
	// InsecureSkipVerifyAcknowledged is also true, and it can never be
	// combined with VerifyPeerCertificate/VerifyConnection (see below).
	InsecureSkipVerify             bool
	InsecureSkipVerifyAcknowledged bool

	// VerifyPeerCertificate and VerifyConnection are run IN ADDITION TO,
	// never instead of, Go's own default verification — New rejects either
	// one being set alongside InsecureSkipVerify == true, since a custom
	// callback would then silently become the only check performed (its
	// verifiedChains argument is empty when default verification didn't
	// run). Use these only to add an extra check (e.g. certificate
	// pinning) on top of a chain Go has already verified.
	VerifyPeerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
	VerifyConnection      func(tls.ConnectionState) error
}

type TimeoutsConfig struct {
	// Overall mirrors http.Client.Timeout — the end-to-end budget for a
	// single request including any redirects.
	Overall time.Duration
	// Dial bounds the TCP connect phase.
	Dial time.Duration
	// TLSHandshake mirrors http.Transport.TLSHandshakeTimeout.
	TLSHandshake time.Duration
	// ResponseHeader mirrors http.Transport.ResponseHeaderTimeout.
	ResponseHeader time.Duration
	// ExpectContinue mirrors http.Transport.ExpectContinueTimeout.
	ExpectContinue time.Duration
	// MaxResponseBytes bounds how much of a response body the returned
	// client will read before erroring, so an oversized or hostile response
	// cannot exhaust memory. 0 uses the package default
	// (defaultMaxResponseBytes); a negative value disables the bound
	// entirely (opt-in, for callers that stream large trusted payloads).
	MaxResponseBytes int64
}