Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Proxy ¶
func Proxy(w http.ResponseWriter, r *http.Request, upstreamURL string, opts ProxyOptions)
Proxy accepts a client WebSocket upgrade, dials the upstream URL, and pumps messages bidirectionally until either side closes. ProxyOptions fields are optional and use defaults when omitted.
func Pump ¶
func Pump(ctx context.Context, client, upstream Conn, onClose func(cause PumpExitCause), logger *slog.Logger, transform MessageTransform, observe Observer)
Pump bidirectionally copies messages between client and upstream until either side errors or ctx is cancelled, then calls onClose with the cause. If transform is non-nil it is called for every message; the returned bytes are forwarded to the other side. If observe is non-nil it is called for every message that was forwarded successfully, so a message whose write failed is never observed.
Types ¶
type Conn ¶
type Conn interface {
Read(ctx context.Context) (websocket.MessageType, []byte, error)
Write(ctx context.Context, typ websocket.MessageType, p []byte) error
Close(statusCode websocket.StatusCode, reason string) error
}
Conn abstracts a WebSocket connection for testing and flexibility.
type MessageTransform ¶
type MessageTransform func(direction string, mt websocket.MessageType, msg []byte) []byte
MessageTransform is called for every message flowing through the proxy. direction is "->" for client-to-upstream and "<-" for upstream-to-client. It returns the (possibly modified) message bytes to forward.
type Observer ¶
type Observer func(direction string, mt websocket.MessageType, msg []byte, ts int64)
Observer is called after a message has been successfully written to the other side, with ts set to the time that write completed (Unix microseconds). It runs on the pump goroutine, so anything it does delays the next message: hand work to a worker rather than doing it here. msg is not retained by the pump after the call, so an observer may take ownership.
type ProxyOptions ¶
type ProxyOptions struct {
AcceptOptions *websocket.AcceptOptions
DialOptions *websocket.DialOptions
Logger *slog.Logger
Transform MessageTransform
Observe Observer
// Registry, when set, tracks the accepted client connection so it is
// closed with a Going Away frame on server shutdown.
Registry *wsdrain.Registry
}
ProxyOptions configures the proxy accept/dial behavior and optional message transformation. Zero values are valid and use sensible defaults.
type PumpExitCause ¶
type PumpExitCause string
PumpExitCause names which side caused Pump to return. Callers use this to distinguish a clean client close from an upstream failure or context cancellation when deciding telemetry attribution and reconnect policy.
const ( // PumpExitClient indicates the client-side read or upstream-side write // returned an error first (typically: client closed the WS). PumpExitClient PumpExitCause = "client" // PumpExitUpstream indicates the upstream-side read or client-side write // returned an error first (typically: upstream died or restarted). PumpExitUpstream PumpExitCause = "upstream" // PumpExitContext indicates the pump's context was cancelled before // either side errored (typically: server shutdown). PumpExitContext PumpExitCause = "context" )
Source Files