Documentation
¶
Overview ¶
Package proxy provides a configurable reverse proxy handler. It wraps httputil.NewSingleHostReverseProxy, starting with sensible defaults, integrating a reusable buffer pool, structured logging, and robust error handling via a functional options API.
Index ¶
- Constants
- type Director
- type DirectorFactory
- type ErrorHandler
- type ErrorHandlerFactory
- type Handler
- type HandlerOption
- func WithDirector(f DirectorFactory) HandlerOption
- func WithErrorHandler(f ErrorHandlerFactory) HandlerOption
- func WithFlushInterval(d time.Duration) HandlerOption
- func WithLogger(log *slog.Logger) HandlerOption
- func WithMaxBufferSize(n int) HandlerOption
- func WithMinBufferSize(n int) HandlerOption
- func WithTransport(t *http.Transport) HandlerOption
Constants ¶
const ( // DefaultMinBufferSize is the default minimum size of pooled buffers. DefaultMinBufferSize = 32 << 10 // 32 KiB // DefaultMaxBufferSize is the default maximum size of pooled buffers. DefaultMaxBufferSize = 256 << 10 // 256 KiB )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Director ¶
Director defines a function to modify the request before it is sent to the upstream target.
The signature matches httputil.ReverseProxy.Director.
func NewDirector ¶
NewDirector is the default DirectorFactory for the proxy. It returns the original Director unmodified.
type DirectorFactory ¶
DirectorFactory creates a Director using the provided original Director. The returned Director may call original to retain its behavior.
type ErrorHandler ¶
type ErrorHandler = func(http.ResponseWriter, *http.Request, error)
ErrorHandler defines a function for handling errors that occur during the reverse proxy's operation.
The signature matches httputil.ReverseProxy.ErrorHandler.
func NewErrorHandler ¶
func NewErrorHandler(logger *slog.Logger) ErrorHandler
NewErrorHandler is the default ErrorHandlerFactory for the proxy. It creates an error handler that logs upstream errors using the provided logger and maps them to appropriate HTTP status codes.
type ErrorHandlerFactory ¶
type ErrorHandlerFactory = func(*slog.Logger) ErrorHandler
ErrorHandlerFactory creates an ErrorHandler using the provided logger. It receives the configured logger to be used for error reporting.
type Handler ¶
Handler is an alias of http.Handler representing a reverse proxy.
func NewHandler ¶
func NewHandler(target *url.URL, opts ...HandlerOption) Handler
NewHandler creates a new reverse proxy handler that routes to the target URL. The behavior of the proxy can be customized through the given options.
type HandlerOption ¶
type HandlerOption func(*handlerConfig)
HandlerOption defines a function for setting reverse proxy options.
func WithDirector ¶
func WithDirector(f DirectorFactory) HandlerOption
WithDirector provides a custom DirectorFactory for the proxy.
If nil is given, this option is ignored. By default, NewDirector is used.
func WithErrorHandler ¶
func WithErrorHandler(f ErrorHandlerFactory) HandlerOption
WithErrorHandler provides a custom ErrorHandlerFactory for the proxy.
If nil is given, this option is ignored. By default, NewErrorHandler is used.
func WithFlushInterval ¶
func WithFlushInterval(d time.Duration) HandlerOption
WithFlushInterval specifies the periodic flush interval for copying the response body to the client.
A zero value (default) disables periodic flushing. A negative value tells the proxy to flush immediately after each write to the client. The proxy is smart enough to recognize streaming responses, ignoring the flush interval in such cases.
Adjust this setting if you observe high latencies for responses that are fully buffered by the proxy before being sent to the client. A lower value reduces latency at the cost of increased CPU usage.
func WithLogger ¶
func WithLogger(log *slog.Logger) HandlerOption
WithLogger sets the logger to be used by the proxy's ErrorHandler.
If nil is given, this option is ignored. By default, slog.Default() is used. The default error handler (NewErrorHandler) uses this logger for capturing upstream errors.
func WithMaxBufferSize ¶
func WithMaxBufferSize(n int) HandlerOption
WithMaxBufferSize specifies the maximum size of buffers to be returned to the buffer pool. Buffers that grow larger than this size will be discarded after use to prevent memory bloat.
Non-positive values are ignored, and DefaultMaxBufferSize is used.
This is a critical tuning parameter. If your typical (e.g., P95) response size is larger than this value, the pool will be ineffective, as most buffers will be discarded instead of being reused.
func WithMinBufferSize ¶
func WithMinBufferSize(n int) HandlerOption
WithMinBufferSize specifies the minimum size of buffers allocated by the buffer pool. This helps to reduce allocations for large response bodies.
Non-positive values are ignored, and DefaultMinBufferSize is used. The value will be capped at MaxBufferSize.
The pool will automatically adjust itself for larger, common responses and the MaxBufferSize will protect from memory bloat. You only need to adapt this setting if you know from profiling that 99% of your responses are, for example, larger than 100 KB.
func WithTransport ¶
func WithTransport(t *http.Transport) HandlerOption
WithTransport sets the http.Transport for upstream requests.
Use this option to tune connection pooling, timeouts (e.g., Dial, TLSHandshake), and keep-alives. If nil is given, this option is ignored.
Source Files