martian

Documentation

Overview

Package martian provides an HTTP/1.1 proxy with an API for configurable request and response modifiers.

Index

• Variables
• func ContextDuration(ctx context.Context) time.Duration
• func ContextTraceID(ctx context.Context) string
• func OnProxyConnectResponse(_ context.Context, _ *url.URL, req *http.Request, connectRes *http.Response) error
• type ConnectFunc
• type ErrorStatus
  • func (e ErrorStatus) Error() string
  • func (e ErrorStatus) Unwrap() error
• type Proxy
  • func (p *Proxy) Close() error
  • func (p *Proxy) Connect(ctx context.Context, req *http.Request, terminateTLS bool) (res *http.Response, crw io.ReadWriteCloser, cerr error)
  • func (p *Proxy) Handler() http.Handler
  • func (p *Proxy) Serve(l net.Listener) error
  • func (p *Proxy) Shutdown(ctx context.Context) error
• type ProxyTrace
• type ReadRequestInfo
• type RequestModifier
• type RequestModifierFunc
  • func (f RequestModifierFunc) ModifyRequest(req *http.Request) error
• type RequestResponseModifier
• type ResponseModifier
• type ResponseModifierFunc
  • func (f ResponseModifierFunc) ModifyResponse(res *http.Response) error
• type TraceIDPrependingLogger
  • func (l TraceIDPrependingLogger) Debugf(ctx context.Context, format string, args ...any)
  • func (l TraceIDPrependingLogger) Errorf(ctx context.Context, format string, args ...any)
  • func (l TraceIDPrependingLogger) Infof(ctx context.Context, format string, args ...any)
• type WroteResponseInfo

Variables

var ErrConnectFallback = errors.New("martian: connect fallback")

ErrConnectFallback is returned by a ConnectFunc to indicate that the CONNECT request should be handled by martian.

Functions

func ContextDuration

func ContextDuration(ctx context.Context) time.Duration

func ContextTraceID

func ContextTraceID(ctx context.Context) string

func OnProxyConnectResponse

func OnProxyConnectResponse(_ context.Context, _ *url.URL, req *http.Request, connectRes *http.Response) error

Types

type ConnectFunc

type ConnectFunc func(req *http.Request) (*http.Response, io.ReadWriteCloser, error)

ConnectFunc dials a network connection for a CONNECT request. If the returned net.Conn is not nil, the response must be not nil.

type ErrorStatus

type ErrorStatus struct {
	Err    error
	Status int
}

func (ErrorStatus) Error

func (e ErrorStatus) Error() string

func (ErrorStatus) Unwrap

func (e ErrorStatus) Unwrap() error

type Proxy

type Proxy struct {
	RequestModifier
	ResponseModifier
	Trace *ProxyTrace

	// RoundTripper specifies the round tripper to use for requests.
	RoundTripper http.RoundTripper

	// DialContext specifies the dial function for creating unencrypted TCP connections.
	// If not set and the RoundTripper is an *http.Transport, the Transport's DialContext is used.
	DialContext func(context.Context, string, string) (net.Conn, error)

	// ProxyURL specifies the upstream proxy to use for requests.
	// If not set and the RoundTripper is an *http.Transport, the Transport's ProxyURL is used.
	ProxyURL func(*http.Request) (*url.URL, error)

	// AllowHTTP disables automatic HTTP to HTTPS upgrades when the listener is TLS.
	AllowHTTP bool

	// RequestIDHeader specifies a special header name that the proxy will use to identify requests.
	// If the header is present in the request, the proxy will associate the value with the request in the logs.
	// If empty, no action is taken, and the proxy will generate a new request ID.
	RequestIDHeader string

	// ConnectFunc specifies a function to dial network connections for CONNECT requests.
	// Implementations can return ErrConnectFallback to indicate that the CONNECT request should be handled by martian.
	ConnectFunc ConnectFunc

	// ConnectTimeout specifies the maximum amount of time to connect to upstream before cancelling request.
	ConnectTimeout time.Duration

	// MITMConfig is config to use for MITMing of CONNECT requests.
	MITMConfig *mitm.Config

	// MITMFilter specifies a function to determine whether a CONNECT request should be MITMed.
	MITMFilter func(*http.Request) bool

	// MITMTLSHandshakeTimeout specifies the maximum amount of time to wait for a TLS handshake for a MITMed connection.
	// Zero means no timeout.
	MITMTLSHandshakeTimeout time.Duration

	// WithoutWarning disables the warning header added to requests and responses when modifier errors occur.
	WithoutWarning bool

	// ErrorResponse specifies a custom error HTTP response to send when a proxying error occurs.
	ErrorResponse func(req *http.Request, err error) *http.Response

	// IdleTimeout is the maximum amount of time to wait for the
	// next request. If IdleTimeout is zero, the value of ReadTimeout is used.
	// If both are zero, there is no timeout.
	IdleTimeout time.Duration

	// TLSHandshakeTimeout is the maximum amount of time to wait for a TLS handshake.
	// The proxy will try to cast accepted connections to tls.Conn and perform a handshake.
	// If TLSHandshakeTimeout is zero, no timeout is set.
	TLSHandshakeTimeout time.Duration

	// ReadTimeout is the maximum duration for reading the entire
	// request, including the body. A zero or negative value means
	// there will be no timeout.
	//
	// Because ReadTimeout does not let Handlers make per-request
	// decisions on each request body's acceptable deadline or
	// upload rate, most users will prefer to use
	// ReadHeaderTimeout. It is valid to use them both.
	ReadTimeout time.Duration

	// ReadHeaderTimeout is the amount of time allowed to read
	// request headers. The connection's read deadline is reset
	// after reading the headers and the Handler can decide what
	// is considered too slow for the body. If ReadHeaderTimeout
	// is zero, the value of ReadTimeout is used. If both are
	// zero, there is no timeout.
	ReadHeaderTimeout time.Duration

	// WriteTimeout is the maximum duration before timing out
	// writes of the response. It is reset whenever a new
	// request's header is read. Like ReadTimeout, it does not
	// let Handlers make decisions on a per-request basis.
	// A zero or negative value means there will be no timeout.
	WriteTimeout time.Duration

	// BaseContext is the base context for all requests.
	BaseContext context.Context //nolint:containedctx // It's intended to be used as a base context.

	// TestingSkipRoundTrip skips the round trip for requests and returns a 200 OK response.
	TestingSkipRoundTrip bool
	// contains filtered or unexported fields
}

Proxy is an HTTP proxy with support for TLS MITM and customizable behavior.

func (*Proxy) Close

func (p *Proxy) Close() error

Close closes the proxy and all connections it has accepted.

func (*Proxy) Connect

func (p *Proxy) Connect(ctx context.Context, req *http.Request, terminateTLS bool) (res *http.Response, crw io.ReadWriteCloser, cerr error)

func (*Proxy) Handler

func (p *Proxy) Handler() http.Handler

Handler returns proxy as http.Handler, see [proxyHandler] for details.

func (*Proxy) Serve

func (p *Proxy) Serve(l net.Listener) error

Serve accepts connections from the listener and handles the requests.

func (*Proxy) Shutdown

func (p *Proxy) Shutdown(ctx context.Context) error

Shutdown sets the proxy to the closing state so it stops receiving new connections, finishes processing any inflight requests, and closes existing connections without reading anymore requests from them.

type ProxyTrace

type ProxyTrace struct {
	// ReadRequest is called with the result of reading the request.
	// It is called after the request has been read.
	ReadRequest func(ReadRequestInfo)

	// WroteResponse is called with the result of writing the response.
	// It is called after the response has been written.
	WroteResponse func(WroteResponseInfo)
}

ProxyTrace is a set of hooks to run at various stages of a request. Any particular hook may be nil. Functions may be called concurrently from different goroutines and some may be called after the request has completed or failed.

type ReadRequestInfo

type ReadRequestInfo struct {
	// Req is the request that was read.
	Req *http.Request
	// Err is any error encountered while reading the Request.
	Err error
}

type RequestModifier

type RequestModifier interface {
	// ModifyRequest modifies the request.
	ModifyRequest(req *http.Request) error
}

RequestModifier is an interface that defines a request modifier that can be used by a proxy.

type RequestModifierFunc

type RequestModifierFunc func(req *http.Request) error

RequestModifierFunc is an adapter for using a function with the given signature as a RequestModifier.

func (RequestModifierFunc) ModifyRequest

func (f RequestModifierFunc) ModifyRequest(req *http.Request) error

ModifyRequest modifies the request using the given function.

type RequestResponseModifier

type RequestResponseModifier interface {
	RequestModifier
	ResponseModifier
}

RequestResponseModifier is an interface that is both a ResponseModifier and a RequestModifier.

type ResponseModifier

type ResponseModifier interface {
	// ModifyResponse modifies the response.
	ModifyResponse(res *http.Response) error
}

ResponseModifier is an interface that defines a response modifier that can be used by a proxy.

type ResponseModifierFunc

type ResponseModifierFunc func(res *http.Response) error

ResponseModifierFunc is an adapter for using a function with the given signature as a ResponseModifier.

func (ResponseModifierFunc) ModifyResponse

func (f ResponseModifierFunc) ModifyResponse(res *http.Response) error

ModifyResponse modifies the response using the given function.

type TraceIDPrependingLogger

type TraceIDPrependingLogger struct {
	log.Logger
}

func (TraceIDPrependingLogger) Debugf

func (l TraceIDPrependingLogger) Debugf(ctx context.Context, format string, args ...any)

func (TraceIDPrependingLogger) Errorf

func (l TraceIDPrependingLogger) Errorf(ctx context.Context, format string, args ...any)

func (TraceIDPrependingLogger) Infof

func (l TraceIDPrependingLogger) Infof(ctx context.Context, format string, args ...any)

type WroteResponseInfo

type WroteResponseInfo struct {
	// Res is the response that was written.
	Res *http.Response
	// Err is any error encountered while writing the Request.
	Err error
}