client

func WithDialControl ¶ added in v0.30.1

func WithDialControl(control func(network, address string, c syscall.RawConn) error) Option

WithDialControl installs a per-connection Control hook on the dialer used to reach every backend. The hook fires after DNS resolution and before the TCP handshake, receiving the resolved peer IP in address — which is why it defeats DNS-rebinding attacks that a host-name–based allow/deny check cannot: a hostname can legitimately resolve to a blocked IP after the name-based check passes.

The hook composes with per-backend CA-bundle handling: it augments the internally built *http.Transport rather than replacing it. Supplying it implies the standard dial timeouts (30 s Timeout, 30 s KeepAlive) used throughout this package.

The signature matches net.Dialer.Control exactly.

Security limitations embedders must understand:

• Per-TCP-dial, not per-request: the hook fires once per TCP connection. A pooled connection is reused without re-invoking the hook until it is recycled. Because each backend gets its own isolated transport and connection pool, a reused connection is always one this hook already approved on its first dial — reuse cannot reach an unclassified peer. This client does not offer per-request re-classification.

• Proxy transparency: when http.ProxyFromEnvironment selects a proxy (HTTP_PROXY/HTTPS_PROXY set), the dial target is the proxy server, so the hook receives the proxy's IP, not the backend's. Embedders relying on this hook for SSRF or IP allow-listing must either unset the proxy env vars or additionally validate the request URL's host before dialing.

• Both IP families: the address argument may be an IPv4 or IPv6 literal (host:port form); embedders must handle both families — including IPv4-mapped IPv6 such as ::ffff:127.0.0.1 — in their check. See the OWASP SSRF Prevention Cheat Sheet for the full set of ranges to deny (loopback, RFC 1918, link-local 169.254/16, CGNAT 100.64/10, IPv6 ULA).

denyNonPublic := func(_, address string, _ syscall.RawConn) error {
	host, _, err := net.SplitHostPort(address)
	if err != nil {
		return err
	}
	ip := net.ParseIP(host)
	if ip == nil {
		return fmt.Errorf("unresolved dial address %q", address)
	}
	if ip.IsLoopback() || ip.IsPrivate() || ip.IsLinkLocalUnicast() {
		return fmt.Errorf("blocked connection to non-public IP %s", ip)
	}
	return nil
}

registry := auth.NewDefaultOutgoingAuthRegistry()
if err := registry.RegisterStrategy(
	authtypes.StrategyTypeUnauthenticated, &strategies.UnauthenticatedStrategy{},
); err != nil {
	panic(err)
}

backendClient, err := NewHTTPBackendClient(registry, WithDialControl(denyNonPublic))
if err != nil {
	panic(err)
}
_ = backendClient

func WithRefutationTTL ¶ added in v0.42.0

func WithRefutationTTL(d time.Duration) Option

WithRefutationTTL overrides how long a refuted Modern-handshake hint suppresses the confirming server/discover probe in legacyInit. Zero or negative restores the default. Production callers should not set this; it exists so tests can shrink the window.

func WithRequestTimeoutResolver ¶ added in v0.45.0

func WithRequestTimeoutResolver(resolver func(workloadID string) time.Duration) Option

WithRequestTimeoutResolver configures the timeout used for each backend operation. The resolver receives the backend workload ID and may return a workload-specific duration. A nil resolver, or a non-positive result, uses the 30-second default.

The resolver may be called concurrently and must therefore be safe for concurrent use. SSE connection lifetimes remain unbounded, but individual operations on those connections are bounded through request contexts.