Documentation ¶
Overview ¶
Package forwarder provides a simple forward proxy server. The proxy can be protected with HTTP basic authentication. It can also forward connections to a parent proxy, and authorize connections against that. Both local, and parent credentials can be set via environment variables.
Index ¶
- Constants
- Variables
- func NewHTTPProxyHandler(cfg *HTTPProxyConfig, pr PACResolver, cm *CredentialsMatcher, ...) (http.Handler, error)
- func NewHTTPTransport(cfg *HTTPTransportConfig) (*http.Transport, error)
- func OpenFileParser(flag int, perm, dirPerm os.FileMode) func(val string) (*os.File, error)
- func ParseDNSAddress(val string) (netip.AddrPort, error)
- func ParsePrometheusNamespace(val string) (string, error)
- func ParseProxyURL(val string) (*url.URL, error)
- func ParseUserinfo(val string) (*url.Userinfo, error)
- func ReadFileOrBase64(name string) ([]byte, error)
- func ReadURL(u *url.URL, rt http.RoundTripper) ([]byte, error)
- func ReadURLString(u *url.URL, rt http.RoundTripper) (string, error)
- func RedactHostPortUser(hpu *HostPortUser) string
- func UnmarshalJSONFlag(in []byte, x interface{ ... }, setInt func(int64) error) error
- func WithDialConnTrack(ctx context.Context, track DialConnTrack) context.Context
- type APIEndpoint
- type APIHandler
- type ConnectFunc
- type CredentialsMatcher
- type DNSConfig
- type DialConfig
- type DialConnTrack
- type DialRedirectFunc
- type DialRetryConfig
- type Dialer
- type HTTPProxy
- type HTTPProxyConfig
- type HTTPServer
- type HTTPServerConfig
- type HTTPTransportConfig
- type HostPort
- type HostPortPair
- type HostPortUser
- type Listener
- type ListenerConfig
- type LoggingPACResolver
- type MITMConfig
- type MatchFunc
- type Matcher
- type MultiListener
- type NamedListenerConfig
- type PACResolver
- type PromConfig
- type ProxyFunc
- type ProxyLocalhostMode
- type ProxyProtocolConfig
- type RequestModifier
- type RequestModifierFunc
- type RequestResponseModifier
- type ResponseModifier
- type ResponseModifierFunc
- type Scheme
- type SizeSuffix
- func (x SizeSuffix) BitRateUnit() string
- func (x SizeSuffix) BitUnit() string
- func (x SizeSuffix) ByteRateUnit() string
- func (x SizeSuffix) ByteUnit() string
- func (x *SizeSuffix) Scan(s fmt.ScanState, ch rune) error
- func (x *SizeSuffix) Set(s string) error
- func (x SizeSuffix) String() string
- func (x *SizeSuffix) Type() string
- func (x *SizeSuffix) UnmarshalJSON(in []byte) error
- type SizeSuffixList
- type TLSClientConfig
- type TLSServerConfig
Constants ¶
const ( // SizeSuffixMax is the largest SizeSuffix multiplier SizeSuffixMax = Exbi // SizeSuffixMaxValue is the largest value that can be used to create SizeSuffix SizeSuffixMaxValue = math.MaxInt64 // SizeSuffixMinValue is the smallest value that can be used to create SizeSuffix SizeSuffixMinValue = math.MinInt64 )
const APIUnixSocket = "/tmp/forwarder.sock"
APIUnixSocket is the path to the Unix socket for the API server. It is currently only used in containerized environments.
const ErrorHeader = "X-Forwarder-Error"
ErrorHeader is the header that is set on error responses with the error message.
Variables ¶
var ( ErrProxyAuthentication = errors.New("proxy authentication required") ErrProxyLocalhost = denyError{errors.New("localhost proxying is disabled")} ErrProxyDenied = denyError{errors.New("proxying denied")} )
var ErrConnectFallback = martian.ErrConnectFallback
ErrConnectFallback is returned by a ConnectFunc to indicate that the CONNECT request should be handled by martian.
Functions ¶
func NewHTTPProxyHandler ¶ added in v1.1.0
func NewHTTPProxyHandler(cfg *HTTPProxyConfig, pr PACResolver, cm *CredentialsMatcher, rt http.RoundTripper, log log.Logger) (http.Handler, error)
NewHTTPProxyHandler is like NewHTTPProxy but returns http.Handler instead of *HTTPProxy.
func NewHTTPTransport ¶
func NewHTTPTransport(cfg *HTTPTransportConfig) (*http.Transport, error)
func OpenFileParser ¶
OpenFileParser returns a parser that calls os.OpenFile. If dirPerm is set it will create the directory if it does not exist. For empty path the parser returns nil file and nil error.
func ParsePrometheusNamespace ¶ added in v1.1.0
func ParseUserinfo ¶ added in v1.1.0
ParseUserinfo parses a user:password string into *url.Userinfo.
func ReadFileOrBase64 ¶ added in v1.0.3
func ReadURLString ¶ added in v1.0.3
ReadURLString can read base64 encoded data, local file, http or https URL or stdin and return it as a string.
func RedactHostPortUser ¶
func RedactHostPortUser(hpu *HostPortUser) string
func UnmarshalJSONFlag ¶ added in v1.1.0
UnmarshalJSONFlag unmarshals a JSON input for a flag. If the input is a string then it calls the Set method on the flag otherwise it calls the setInt function with a parsed int64.
func WithDialConnTrack ¶ added in v1.4.0
func WithDialConnTrack(ctx context.Context, track DialConnTrack) context.Context
WithDialConnTrack sets the connection tracking mode for connections dialed by Dialer.
Types ¶
type APIEndpoint ¶ added in v1.1.0
type APIHandler ¶
type APIHandler struct {
// contains filtered or unexported fields
}
APIHandler serves API endpoints. It provides health and readiness endpoints prometheus metrics, and pprof debug endpoints.
func NewAPIHandler ¶
func NewAPIHandler(title string, r prometheus.Gatherer, ready func(ctx context.Context) bool, extraEndpoints ...APIEndpoint) *APIHandler
func (*APIHandler) ServeHTTP ¶
func (h *APIHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
type ConnectFunc ¶ added in v1.1.0
type ConnectFunc = martian.ConnectFunc
Alias all martian types to avoid exposing them.
type CredentialsMatcher ¶
type CredentialsMatcher struct {
// contains filtered or unexported fields
}
func NewCredentialsMatcher ¶
func NewCredentialsMatcher(credentials []*HostPortUser, log log.Logger) (*CredentialsMatcher, error)
type DNSConfig ¶
func DefaultDNSConfig ¶
func DefaultDNSConfig() *DNSConfig
type DialConfig ¶ added in v1.0.3
type DialConfig struct { // DialTimeout is the maximum amount of time a dial will wait for // connect to complete. // // With or without a timeout, the operating system may impose // its own earlier timeout. For instance, TCP timeouts are // often around 3 minutes. DialTimeout time.Duration // KeepAliveConfig contains TCP keep-alive options. KeepAliveConfig net.KeepAliveConfig // RedirectFunc can be optionally set to redirect the connection to a different address. RedirectFunc DialRedirectFunc // Retry specifies the number of attempts and backoff duration between them. Retry DialRetryConfig PromConfig }
func DefaultDialConfig ¶ added in v1.0.3
func DefaultDialConfig() *DialConfig
type DialConnTrack ¶ added in v1.4.0
type DialConnTrack uint8
DialConnTrack specifies the connection tracking mode for connections dialed by Dialer.
const ( DialConnTrackDefault DialConnTrack = iota DialConnTrackDisabled DialConnTrackTraffic )
type DialRedirectFunc ¶ added in v1.4.0
func DialRedirectFromHostPortPairs ¶ added in v1.4.0
func DialRedirectFromHostPortPairs(subs []HostPortPair) DialRedirectFunc
type DialRetryConfig ¶ added in v1.4.0
type Dialer ¶ added in v1.0.3
type Dialer struct {
// contains filtered or unexported fields
}
func NewDialer ¶ added in v1.0.3
func NewDialer(cfg *DialConfig) *Dialer
func (*Dialer) DialContext ¶ added in v1.0.3
DialContext dials the provided network and address and configures OS-specific keep-alive parameters. It tracks dialed and closed connections by default, the behavior can be changed with WithDialConnTrack.
type HTTPProxy ¶
type HTTPProxy struct {
// contains filtered or unexported fields
}
func NewHTTPProxy ¶
func NewHTTPProxy(cfg *HTTPProxyConfig, pr PACResolver, cm *CredentialsMatcher, rt http.RoundTripper, log log.Logger) (*HTTPProxy, error)
NewHTTPProxy creates a new HTTP proxy. It is the caller's responsibility to call Close on the returned server.
func (*HTTPProxy) MITMCACert ¶ added in v1.1.0
func (hp *HTTPProxy) MITMCACert() *x509.Certificate
type HTTPProxyConfig ¶
type HTTPProxyConfig struct { HTTPServerConfig ExtraListeners []NamedListenerConfig Name string MITM *MITMConfig MITMDomains Matcher ProxyLocalhost ProxyLocalhostMode UpstreamProxy *url.URL UpstreamProxyFunc ProxyFunc DenyDomains Matcher DirectDomains Matcher RequestIDHeader string RequestModifiers []RequestModifier ResponseModifiers []ResponseModifier ConnectFunc ConnectFunc ConnectTimeout time.Duration PromHTTPOpts []middleware.PrometheusOpt // TestingHTTPHandler uses Martian's [http.Handler] implementation // over [http.Server] instead of the default TCP server. TestingHTTPHandler bool }
func DefaultHTTPProxyConfig ¶
func DefaultHTTPProxyConfig() *HTTPProxyConfig
func (*HTTPProxyConfig) Validate ¶
func (c *HTTPProxyConfig) Validate() error
type HTTPServer ¶
type HTTPServer struct {
// contains filtered or unexported fields
}
func NewHTTPServer ¶
func NewHTTPServer(cfg *HTTPServerConfig, h http.Handler, log log.Logger) (*HTTPServer, error)
NewHTTPServer creates a new HTTP server. It is the caller's responsibility to call Close on the returned server.
func (*HTTPServer) Addr ¶
func (hs *HTTPServer) Addr() string
Addr returns the address the server is listening on.
func (*HTTPServer) Close ¶ added in v1.1.0
func (hs *HTTPServer) Close() error
type HTTPServerConfig ¶
type HTTPServerConfig struct { ListenerConfig Protocol Scheme TLSServerConfig IdleTimeout time.Duration ReadTimeout time.Duration ReadHeaderTimeout time.Duration WriteTimeout time.Duration LogHTTPMode httplog.Mode BasicAuth *url.Userinfo PromConfig // contains filtered or unexported fields }
func DefaultHTTPServerConfig ¶
func DefaultHTTPServerConfig() *HTTPServerConfig
func (*HTTPServerConfig) Validate ¶
func (c *HTTPServerConfig) Validate() error
type HTTPTransportConfig ¶
type HTTPTransportConfig struct { DialConfig TLSClientConfig // MaxIdleConns controls the maximum number of idle (keep-alive) // connections across all hosts. Zero means no limit. MaxIdleConns int // MaxIdleConnsPerHost, if non-zero, controls the maximum idle // (keep-alive) connections to keep per-host. If zero, // DefaultMaxIdleConnsPerHost is used. MaxIdleConnsPerHost int // MaxConnsPerHost optionally limits the total number of // connections per host, including connections in the dialing, // active, and idle states. On limit violation, dials will block. // // Zero means no limit. MaxConnsPerHost int // IdleConnTimeout is the maximum amount of time an idle // (keep-alive) connection will remain idle before closing // itself. // Zero means no limit. IdleConnTimeout time.Duration // ResponseHeaderTimeout, if non-zero, specifies the amount of // time to wait for a server's response headers after fully // writing the request (including its body, if any). This // time does not include the time to read the response body. ResponseHeaderTimeout time.Duration // ExpectContinueTimeout, if non-zero, specifies the amount of // time to wait for a server's first response headers after fully // writing the request headers if the request has an // "Expect: 100-continue" header. Zero means no timeout and // causes the body to be sent immediately, without // waiting for the server to approve. // This time does not include the time to send the request header. ExpectContinueTimeout time.Duration }
func DefaultHTTPTransportConfig ¶
func DefaultHTTPTransportConfig() *HTTPTransportConfig
type HostPortPair ¶ added in v1.4.0
type HostPortPair struct {
Src, Dst HostPort
}
func ParseHostPortPair ¶ added in v1.4.0
func ParseHostPortPair(val string) (HostPortPair, error)
ParseHostPortPair parses HOST1:PORT1:HOST2:PORT2 string into HostPortPair. HOST1:PORT1 is the source, HOST2:PORT2 is the destination.
func (HostPortPair) String ¶ added in v1.4.0
func (p HostPortPair) String() string
func (HostPortPair) Validate ¶ added in v1.4.0
func (p HostPortPair) Validate() error
type HostPortUser ¶
func ParseHostPortUser ¶
func ParseHostPortUser(val string) (*HostPortUser, error)
ParseHostPortUser parses a user:password@host:port string into HostUser.
func (*HostPortUser) String ¶ added in v1.1.0
func (hpu *HostPortUser) String() string
func (*HostPortUser) Validate ¶
func (hpu *HostPortUser) Validate() error
type Listener ¶ added in v1.2.0
type Listener struct { ListenerConfig TLSConfig *tls.Config PromConfig // contains filtered or unexported fields }
type ListenerConfig ¶ added in v1.4.0
type ListenerConfig struct { Address string KeepAliveConfig net.KeepAliveConfig ProxyProtocolConfig *ProxyProtocolConfig ReadLimit SizeSuffix WriteLimit SizeSuffix TrackTraffic bool }
func DefaultListenerConfig ¶ added in v1.4.0
func DefaultListenerConfig(addr string) *ListenerConfig
type LoggingPACResolver ¶
type LoggingPACResolver struct { Resolver PACResolver Logger log.Logger }
func (*LoggingPACResolver) FindProxyForURL ¶
type MITMConfig ¶ added in v1.0.3
type MITMConfig struct { CACertFile string CAKeyFile string Organization string Validity time.Duration CacheSize uint32 CacheTTL time.Duration }
func DefaultMITMConfig ¶ added in v1.0.3
func DefaultMITMConfig() *MITMConfig
type MultiListener ¶ added in v1.4.0
type MultiListener struct { ListenerConfigs []NamedListenerConfig TLSConfig func(NamedListenerConfig) *tls.Config PromConfig }
MultiListener is a builder for multiple listeners sharing the same prometheus configuration. The listener name is added as a label to the metrics.
type NamedListenerConfig ¶ added in v1.4.0
type NamedListenerConfig struct { Name string ListenerConfig }
type PACResolver ¶
type PromConfig ¶ added in v1.2.0
type PromConfig struct { PromNamespace string PromRegistry prometheus.Registerer }
PromConfig is a configuration for Prometheus metrics.
type ProxyLocalhostMode ¶
type ProxyLocalhostMode string
const ( DenyProxyLocalhost ProxyLocalhostMode = "deny" AllowProxyLocalhost ProxyLocalhostMode = "allow" DirectProxyLocalhost ProxyLocalhostMode = "direct" )
func (ProxyLocalhostMode) String ¶
func (m ProxyLocalhostMode) String() string
func (*ProxyLocalhostMode) UnmarshalText ¶
func (m *ProxyLocalhostMode) UnmarshalText(text []byte) error
type ProxyProtocolConfig ¶ added in v1.4.0
func DefaultProxyProtocolConfig ¶ added in v1.4.0
func DefaultProxyProtocolConfig() *ProxyProtocolConfig
type RequestModifier ¶ added in v1.1.0
type RequestModifier = martian.RequestModifier
Alias all martian types to avoid exposing them.
type RequestModifierFunc ¶ added in v1.1.0
type RequestModifierFunc = martian.RequestModifierFunc
Alias all martian types to avoid exposing them.
type RequestResponseModifier ¶ added in v1.1.0
type RequestResponseModifier = martian.RequestResponseModifier
Alias all martian types to avoid exposing them.
type ResponseModifier ¶ added in v1.1.0
type ResponseModifier = martian.ResponseModifier
Alias all martian types to avoid exposing them.
type ResponseModifierFunc ¶ added in v1.1.0
type ResponseModifierFunc = martian.ResponseModifierFunc
Alias all martian types to avoid exposing them.
type SizeSuffix ¶ added in v1.1.0
type SizeSuffix int64
SizeSuffix is an int64 with a friendly way of printing setting
const ( SizeSuffixBase SizeSuffix = 1 << (iota * 10) Kibi Mebi Gibi Tebi Pebi Exbi )
Common multipliers for SizeSuffix
func (SizeSuffix) BitRateUnit ¶ added in v1.1.0
func (x SizeSuffix) BitRateUnit() string
BitRateUnit turns SizeSuffix into a string with bit rate unit
func (SizeSuffix) BitUnit ¶ added in v1.1.0
func (x SizeSuffix) BitUnit() string
BitUnit turns SizeSuffix into a string with bit unit
func (SizeSuffix) ByteRateUnit ¶ added in v1.1.0
func (x SizeSuffix) ByteRateUnit() string
ByteRateUnit turns SizeSuffix into a string with byte rate unit
func (SizeSuffix) ByteUnit ¶ added in v1.1.0
func (x SizeSuffix) ByteUnit() string
ByteUnit turns SizeSuffix into a string with byte unit
func (*SizeSuffix) Scan ¶ added in v1.1.0
func (x *SizeSuffix) Scan(s fmt.ScanState, ch rune) error
Scan implements the fmt.Scanner interface
func (SizeSuffix) String ¶ added in v1.1.0
func (x SizeSuffix) String() string
String turns SizeSuffix into a string
func (*SizeSuffix) UnmarshalJSON ¶ added in v1.1.0
func (x *SizeSuffix) UnmarshalJSON(in []byte) error
UnmarshalJSON makes sure the value can be parsed as a string or integer in JSON
type SizeSuffixList ¶ added in v1.1.0
type SizeSuffixList []SizeSuffix
SizeSuffixList is a slice SizeSuffix values
func (SizeSuffixList) Len ¶ added in v1.1.0
func (l SizeSuffixList) Len() int
func (SizeSuffixList) Less ¶ added in v1.1.0
func (l SizeSuffixList) Less(i, j int) bool
func (SizeSuffixList) Swap ¶ added in v1.1.0
func (l SizeSuffixList) Swap(i, j int)
type TLSClientConfig ¶ added in v1.0.3
type TLSClientConfig struct { // HandshakeTimeout specifies the maximum amount of time waiting to // wait for a TLS handshake. Zero means no timeout. HandshakeTimeout time.Duration // Insecure controls whether a client verifies the server's // certificate chain and host name. If Insecure is true, crypto/tls // accepts any certificate presented by the server and any host name in that // certificate. In this mode, TLS is susceptible to machine-in-the-middle // attacks unless custom verification is used. This should be used only for // testing or in combination with VerifyConnection or VerifyPeerCertificate. Insecure bool // CACertFiles is a list of paths to CA certificate files. // If this is set, the system root CA pool will be supplemented with certificates from these files. CACertFiles []string // KeyLogFile optionally specifies a destination for TLS master secrets // in NSS key log format that can be used to allow external programs // such as Wireshark to decrypt TLS connections. KeyLogFile string }
func DefaultTLSClientConfig ¶ added in v1.2.0
func DefaultTLSClientConfig() *TLSClientConfig
func (*TLSClientConfig) ConfigureTLSConfig ¶ added in v1.0.3
func (c *TLSClientConfig) ConfigureTLSConfig(tlsCfg *tls.Config) error
type TLSServerConfig ¶ added in v1.0.3
type TLSServerConfig struct { // HandshakeTimeout specifies the maximum amount of time waiting to // wait for a TLS handshake. Zero means no timeout. HandshakeTimeout time.Duration // CertFile is the path to the TLS certificate. CertFile string // KeyFile is the path to the TLS private key of the certificate. KeyFile string }
func (*TLSServerConfig) ConfigureTLSConfig ¶ added in v1.0.3
func (c *TLSServerConfig) ConfigureTLSConfig(tlsCfg *tls.Config) error
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
command
|
|
internal
|
|
martian
Package martian provides an HTTP/1.1 proxy with an API for configurable request and response modifiers.
|
Package martian provides an HTTP/1.1 proxy with an API for configurable request and response modifiers. |
martian/fifo
Package fifo provides Group, which is a list of modifiers that are executed consecutively.
|
Package fifo provides Group, which is a list of modifiers that are executed consecutively. |
martian/h2
Package h2 contains basic HTTP/2 handling for Martian.
|
Package h2 contains basic HTTP/2 handling for Martian. |
martian/h2/grpc
Package grpc contains gRPC functionality for Martian proxy.
|
Package grpc contains gRPC functionality for Martian proxy. |
martian/h2/testing
Package testing contains a test fixture for working with gRPC over HTTP/2.
|
Package testing contains a test fixture for working with gRPC over HTTP/2. |
martian/httpspec
Package httpspec provides a modifier stack that has been preconfigured to provide spec-compliant HTTP proxy behavior.
|
Package httpspec provides a modifier stack that has been preconfigured to provide spec-compliant HTTP proxy behavior. |
martian/martiantest
Package martiantest provides helper utilities for testing modifiers.
|
Package martiantest provides helper utilities for testing modifiers. |
martian/messageview
Package messageview provides no-op snapshots for HTTP requests and responses.
|
Package messageview provides no-op snapshots for HTTP requests and responses. |
martian/mitm
Package mitm provides tooling for MITMing TLS connections.
|
Package mitm provides tooling for MITMing TLS connections. |
martian/proxyutil
Package proxyutil provides functionality for building proxies.
|
Package proxyutil provides functionality for building proxies. |
Package pac provides a PAC file parser and evaluator.
|
Package pac provides a PAC file parser and evaluator. |
utils
|
|