network

type AllowedURLEntry struct {
	// URL is the prefix to allow. Must include scheme and host. The
	// path component is treated as a literal prefix — entry URL
	// "https://api.example.com/v1/" matches request URLs whose path
	// starts with "/v1/" on that origin. %2f / %5c in the path are
	// rejected at compile time because they create ambiguity with
	// real / and \ characters.
	URL string

	// Transform is the list of header rewrites applied when this entry
	// matches the outgoing request. Multiple entries with overlapping
	// origins all contribute their headers, last-write-wins per header
	// name.
	Transform []RequestTransform
}

type Config struct {
	// AllowedURLPrefixes whitelists specific origins (scheme+host[+port])
	// and optionally a path prefix and per-entry header transforms. An
	// incoming URL matches when its origin equals the entry's origin
	// AND its path begins with the entry's path. Each entry is
	// re-validated on every redirect hop.
	AllowedURLPrefixes []AllowedURLEntry

	// AllowedMethods restricts which HTTP methods the Doer will issue.
	// Nil means DefaultAllowedMethods (GET, HEAD). An explicitly empty
	// slice denies every method (unless DangerouslyAllowFullAccess is set).
	// Method names are case-insensitive.
	AllowedMethods []string

	// DangerouslyAllowFullAccess turns SecureFetch into a pass-through.
	// All URLs and methods are permitted. DenyPrivateRanges is still
	// honored. Intended for development sandboxes — do not enable in
	// production hosts.
	DangerouslyAllowFullAccess bool

	// MaxRedirects caps the redirect chain. The initial request is hop
	// zero; the limit is the number of additional Location hops the
	// client will follow. Zero means DefaultMaxRedirects (20). A
	// negative value disables redirect following entirely (the first
	// 3xx returns to the caller).
	MaxRedirects int

	// Timeout is the per-request deadline (initial + redirects). Zero
	// means DefaultTimeout (30s). A negative value disables the
	// per-request timeout (caller's ctx is still honored).
	Timeout time.Duration

	// MaxResponseSize caps the response body in bytes. Zero means
	// DefaultMaxResponseSize (10 MiB). A negative value disables the
	// cap; SecureFetch will still read the whole body into memory.
	MaxResponseSize int64

	// DenyPrivateRanges resolves every connection target via DNSResolve
	// (or net.DefaultResolver if nil) and rejects any address in a
	// private, loopback, link-local, or multicast range. Combine with
	// DangerouslyAllowFullAccess to permit arbitrary public hosts
	// while still blocking SSRF into the host's local network.
	DenyPrivateRanges bool

	// DNSResolve is an injection point for tests and custom resolvers.
	// When nil, SecureFetch falls back to net.DefaultResolver.LookupIP.
	// When non-nil, it is the sole source of address records used for
	// the DenyPrivateRanges check.
	DNSResolve func(ctx context.Context, host string) ([]DNSLookupResult, error)
}

type DNSLookupResult struct {
	// Address is the textual representation (192.0.2.1 or 2001:db8::1).
	Address string

	// Family is 4 (AF_INET) or 6 (AF_INET6). Unknown families cause
	// the address to be skipped during private-range checks.
	Family int
}

type Doer interface {
	Do(ctx context.Context, req *http.Request) (*Response, error)
}

type MethodNotAllowedError struct {
	Method string
	URL    string
}

type NetworkAccessDeniedError struct {
	URL    string
	Reason string
}

type RedirectNotAllowedError struct {
	From string
	To   string
}

type RequestTransform struct {
	// Headers is the name → value overlay. Header names are
	// canonicalized via http.CanonicalHeaderKey before application.
	Headers map[string]string
}

type Response struct {
	// Status is the numeric HTTP status code (200, 404, etc.).
	Status int

	// StatusText is the HTTP status line text ("OK", "Not Found", ...).
	StatusText string

	// Headers is the response header set. Multi-value headers retain
	// every value. Callers MUST NOT mutate this map.
	Headers http.Header

	// Body is the response body bytes, capped at Config.MaxResponseSize.
	// If the server attempted to send more, Doer.Do returns
	// *ResponseTooLargeError and Response is nil.
	Body []byte

	// URL is the final URL after any redirect chain. For a non-redirected
	// response it equals the request URL string.
	URL string
}

type ResponseTooLargeError struct {
	Max int64
}

type TooManyRedirectsError struct {
	Max int
}