proxy

Documentation

Overview

Package proxy provides HTTP and SOCKS5 proxy servers with domain filtering.

Index

• func CheckURL(rawURL string, cfg *config.Config) error
• func GetHostFromRequest(r *http.Request) string
• func ParseUpstreamProxyURL(cfg *config.Config) *url.URL
• type FilterFunc
  • func CreateDomainFilter(cfg *config.Config, debug bool) FilterFunc
• type HTTPProxy
  • func NewHTTPProxy(route RouteFunc, upstreamURL *url.URL, debug, monitor bool) *HTTPProxy
  • func (p *HTTPProxy) Port() int
  • func (p *HTTPProxy) Start() (int, error)
  • func (p *HTTPProxy) Stop() error
• type RouteDecision
• type RouteFunc
  • func CreateRouteFunc(cfg *config.Config, debug bool) RouteFunc
• type SOCKSProxy
  • func NewSOCKSProxy(filter FilterFunc, debug, monitor bool) *SOCKSProxy
  • func (p *SOCKSProxy) Port() int
  • func (p *SOCKSProxy) Start() (int, error)
  • func (p *SOCKSProxy) Stop() error
• type URLBlockedError
  • func (e *URLBlockedError) Error() string

Functions

func CheckURL

func CheckURL(rawURL string, cfg *config.Config) error

CheckURL is the hook-time predicate paralleling CreateDomainFilter's wrap-mode traffic gate. Both consume cfg.Network.* identically: a URL is allowed iff the host matches AllowedDomains and not DeniedDomains; an empty AllowedDomains denies everything.

Caveat: hook-time enforcement is deny-by-intent, not deny-by-traffic. The agent could embed an allowed host in a path (`?next=https://blocked.example/`) and the actual HTTP fetch would not be intercepted — wrap mode (with the proxy in the network path) is the answer for that. Hook mode catches the agent's declared intent only.

Adapters that want hook-mode to be permissive when network policy is unconfigured should ship a template (see internal/templates/hermes.json for a worked example) rather than relaxing this predicate.

func GetHostFromRequest

func GetHostFromRequest(r *http.Request) string

GetHostFromRequest extracts the hostname from a request.

func ParseUpstreamProxyURL

func ParseUpstreamProxyURL(cfg *config.Config) *url.URL

ParseUpstreamProxyURL parses the upstream proxy URL from the config. Returns nil when no upstream is configured or the URL is invalid.

Types

type FilterFunc

type FilterFunc func(host string, port int) bool

FilterFunc determines if a connection to host:port should be allowed. Used by SOCKSProxy and legacy callers; HTTPProxy uses RouteFunc instead.

func CreateDomainFilter

func CreateDomainFilter(cfg *config.Config, debug bool) FilterFunc

CreateDomainFilter creates a boolean FilterFunc from a config. Used by SOCKSProxy and hook-mode evaluator; HTTP proxy uses CreateRouteFunc. When debug is true, logs filter rule matches to stderr.

type HTTPProxy

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

HTTPProxy is an HTTP/HTTPS proxy server with domain filtering.

func NewHTTPProxy

func NewHTTPProxy(route RouteFunc, upstreamURL *url.URL, debug, monitor bool) *HTTPProxy

NewHTTPProxy creates a new HTTP proxy with the given route function. upstreamURL may be nil when no upstream proxy is configured. If monitor is true, only blocked requests are logged. If debug is true, all requests and filter rules are logged.

func (*HTTPProxy) Port

func (p *HTTPProxy) Port() int

Port returns the port the proxy is listening on.

func (*HTTPProxy) Start

func (p *HTTPProxy) Start() (int, error)

Start starts the HTTP proxy on a random available port.

func (*HTTPProxy) Stop

func (p *HTTPProxy) Stop() error

Stop stops the HTTP proxy.

type RouteDecision

type RouteDecision int

RouteDecision is the tri-state routing outcome for an HTTP proxy request.

const (
	// RouteDecisionDeny rejects the request with 403. Applied to deniedDomains
	// and to unmatched traffic when no upstream proxy is configured.
	RouteDecisionDeny RouteDecision = iota

	// RouteDecisionDirect connects to the target host directly.
	// Applied to hosts matching allowedDomains.
	RouteDecisionDirect

	// RouteDecisionUpstream forwards the request to the configured upstream
	// proxy. Applied to unmatched (grey-zone) traffic when upstreamProxy is set.
	RouteDecisionUpstream
)

type RouteFunc

type RouteFunc func(host string, port int) RouteDecision

RouteFunc maps a host:port to a RouteDecision.

func CreateRouteFunc

func CreateRouteFunc(cfg *config.Config, debug bool) RouteFunc

CreateRouteFunc creates a RouteFunc from a config for use by HTTPProxy.

Decision logic:

• deniedDomains → RouteDecisionDeny (hard block, never forwarded upstream)
• allowedDomains → RouteDecisionDirect (connect directly to target)
• otherwise → RouteDecisionUpstream (if upstreamProxy configured)
• otherwise → RouteDecisionDeny (no upstream configured)

type SOCKSProxy

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

SOCKSProxy is a SOCKS5 proxy server with domain filtering.

func NewSOCKSProxy

func NewSOCKSProxy(filter FilterFunc, debug, monitor bool) *SOCKSProxy

NewSOCKSProxy creates a new SOCKS5 proxy with the given filter. If monitor is true, only blocked connections are logged. If debug is true, all connections are logged.

func (*SOCKSProxy) Port

func (p *SOCKSProxy) Port() int

Port returns the port the proxy is listening on.

func (*SOCKSProxy) Start

func (p *SOCKSProxy) Start() (int, error)

Start starts the SOCKS5 proxy on a random available port.

func (*SOCKSProxy) Stop

func (p *SOCKSProxy) Stop() error

Stop stops the SOCKS5 proxy.

type URLBlockedError

type URLBlockedError struct {
	URL         string
	Host        string
	MatchedRule string
	Reason      string
}

URLBlockedError is returned when a URL is blocked by network policy at the hook layer. Wrap-mode equivalent is the in-line filter result inside CreateDomainFilter; this exists so callers can `errors.As` and surface the matched rule.

func (*URLBlockedError) Error

func (e *URLBlockedError) Error() string