outbound

package
v2.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package outbound provides a standard-library-only HTTP client for destinations supplied by users, such as webhook URLs. It validates every request and the addresses actually dialed, including requests that reuse an existing connection.

The default policy allows public HTTPS destinations. Exact host and CIDR allowlists may additionally trust private or plaintext HTTP destinations, but never enable metadata endpoints, link-local, multicast, unspecified, or selected address-translation ranges. An allowlist is an exception to the public-only default, not a restriction that disables other public HTTPS destinations.

Clients returned by Policy.Client disable environment proxies and all redirects. Use that client for the actual request: Validate alone is a check-then-use and cannot prevent DNS rebinding. Keep the client's transport and redirect policy intact. This package does not retry requests, authenticate destinations, limit response bodies, or redact net/http's URL-bearing errors.

The policy originated in OwlCron. Its MIT license and attribution are retained in LICENSE-OWLCRON and NOTICE at the module root.

Index

Constants

This section is empty.

Variables

View Source
var ErrBlocked = errors.New("outbound destination is prohibited by security policy")

ErrBlocked reports an invalid or prohibited destination. It never includes the URL, hostname, or address. Use errors.Is to classify wrapped client errors.

View Source
var ErrDNSResolution = errors.New("outbound DNS resolution failed")

ErrDNSResolution reports a failed DNS lookup without exposing resolver details.

View Source
var ErrInvalidOptions = errors.New("invalid outbound policy options")

ErrInvalidOptions reports malformed configuration without repeating its input.

View Source
var ErrNoAddresses = errors.New("outbound DNS returned no addresses")

ErrNoAddresses reports a successful lookup that returned no addresses.

Functions

This section is empty.

Types

type Options

type Options struct {
	AllowedHosts []string
	AllowedCIDRs []string
}

Options configures exceptions to the default public-HTTPS policy. Entries do not restrict access to other public HTTPS destinations. Wildcards, URL schemes, ports, trailing dots, scoped IPv6 addresses and IPv4-mapped CIDRs are rejected. Use exact DNS hostnames, bare IP literals, or CIDRs respectively. Metadata and other always-prohibited addresses remain blocked by any exception. NewPolicy copies and normalizes these slices; later caller mutations have no effect.

type Policy

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

Policy is an immutable destination policy, safe for concurrent requests. Its zero value permits public HTTPS and no other destinations.

func NewPolicy

func NewPolicy(options Options) (*Policy, error)

NewPolicy validates the options and returns an independent policy. An invalid entry rejects the entire configuration; errors never contain the supplied entry.

func (*Policy) Client

func (p *Policy) Client() *http.Client

Client returns a fresh client with its own connection pool. Reuse the returned client across requests and call CloseIdleConnections when it is no longer used. The timeout is ten seconds. Proxies and redirects are disabled, and TLS uses the standard library's certificate verification and protocol defaults.

Every request is checked even when a connection is reused. New connections additionally resolve and check the destination immediately before dialing a numeric address. Plaintext HTTP requires explicit trust at both stages.

Changing Transport or CheckRedirect can bypass these protections. The client does not impose response-size limits; callers must bound the bodies they read.

func (*Policy) Validate

func (p *Policy) Validate(ctx context.Context, target string) error

Validate checks a URL and all addresses it currently resolves to. DNS changes after this call are possible: use Client for the actual request as well. A nil Policy fails closed. A canceled context returns its context error.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL