Documentation
¶
Overview ¶
Package proxy provides a configurable reverse proxy handler. It constructs an httputil.ReverseProxy, starting with sensible defaults, integrating a reusable buffer pool, structured logging, and robust error handling via a functional options API.
Index ¶
- Constants
- type ErrorHandler
- type ErrorHandlerFactory
- type Handler
- type 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 WithRewrite(f RewriteFactory) HandlerOption
- func WithTransport(t *http.Transport) HandlerOption
- type RewriteFactory
- type RewriteFunc
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 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 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 WithRewrite ¶ added in v1.1.11
func WithRewrite(f RewriteFactory) HandlerOption
WithRewrite provides a custom RewriteFactory for the proxy.
If nil is given, this option is ignored. By default, NewRewrite is used.
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.
type RewriteFactory ¶ added in v1.1.11
type RewriteFactory = func(original RewriteFunc) RewriteFunc
RewriteFactory creates a RewriteFunc using the provided original RewriteFunc. The returned RewriteFunc may call original to retain its behavior.
type RewriteFunc ¶ added in v1.1.11
type RewriteFunc func(*httputil.ProxyRequest)
RewriteFunc defines a function to modify the proxy request before it is sent to the upstream target.
The signature matches httputil.ReverseProxy.Rewrite.
func NewRewrite ¶ added in v1.1.11
func NewRewrite(original RewriteFunc) RewriteFunc
NewRewrite is the default RewriteFactory for the proxy. It returns the original RewriteFunc unmodified.
Source Files