Documentation
¶
Overview ¶
Package websockify implements a Caddy HTTP handler which proxies WebSocket connections to TCP or Unix sockets.
Index ¶
- Variables
- func IsWebSocket(r *http.Request) bool
- type Config
- type Module
- func (Module) CaddyModule() caddy.ModuleInfo
- func (m *Module) Cleanup() error
- func (m *Module) Provision(ctx caddy.Context) error
- func (m *Module) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
- func (m *Module) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
- func (m *Module) Validate() error
- type Stats
Constants ¶
This section is empty.
Variables ¶
var ( ErrIdleTimeout = errors.New("idle timeout") ErrPingTimeout = errors.New("ping timeout") )
Functions ¶
func IsWebSocket ¶
IsWebSocket returns true if r is a WebSocket upgrade request.
Types ¶
type Config ¶
type Config struct {
// PingInterval is the frequency to ping the client at, or zero to disable.
PingInterval time.Duration
// PingTimeout is how long to wait for a pong from the client. If zero,
// [Config.PingInterval] is used. A ping only times out if nothing was
// received from the client and no data was waiting to be written to the
// upstream for the entire duration (since the pong may otherwise be queued
// behind unread data).
PingTimeout time.Duration
// IdleTimeout closes the connection if no data is transferred in either
// direction for this long, excluding pings, or zero to disable.
IdleTimeout time.Duration
// BufferSize is the copy buffer size for each direction, which is also the
// largest chunk sent to the client in a single message at a time. If zero,
// a reasonable default is used.
BufferSize int
}
Config controls Proxy.
type Module ¶
type Module struct {
// Upstream addresses in Caddy format, like "localhost:5900",
// "tcp6/[::1]:5900", or "unix//run/vnc.sock". Placeholders are expanded for
// each request. Multiple addresses are used round-robin across all
// connections, trying each one once sequentially until one connects or all
// fail.
Upstreams []string `json:"upstreams,omitempty"`
// Timeout for connecting to each upstream. If not specified, a default
// timeout is used.
DialTimeout caddy.Duration `json:"dial_timeout,omitempty"`
// TCP keepalive interval for the upstream connection, or negative to
// disable it. If not specified, a default interval is used.
KeepAlive caddy.Duration `json:"keepalive,omitempty"`
// How often to send WebSocket pings to the downstream client, or negative
// to disable it. If not specified, a default interval is used.
PingInterval caddy.Duration `json:"ping_interval,omitempty"`
// How long to wait for a pong from the downstream client before closing the
// connection. Defaults to the ping interval. Time spent receiving data from
// the client or waiting to write it to a slow upstream doesn't count.
PingTimeout caddy.Duration `json:"ping_timeout,omitempty"`
// Close the connection if no data is transferred in either direction for
// the specified duration, excluding pings. If not specified, the idle
// timeout is disabled.
IdleTimeout caddy.Duration `json:"idle_timeout,omitempty"`
// Copy buffer size, for each direction, which is also the largest chunk
// sent to the client in a single message at a time. If not specified, a
// default size is used.
BufferSize int `json:"buffer_size,omitempty"`
// Allowed Origin header host patterns (path.Match syntax, or
// "scheme://host" to match the scheme too) for cross-origin connections.
// Same-origin connections and ones without an Origin header are always
// allowed. Use "*" to allow any origin.
Origins []string `json:"origins,omitempty"`
// Subprotocols to negotiate. If not specified, "binary" is used.
Subprotocols []string `json:"subprotocols,omitempty"`
// Grace period to keep connections open after the config is unloaded (e.g.,
// on reload). If not specified, they're closed immediately.
StreamCloseDelay caddy.Duration `json:"stream_close_delay,omitempty"`
// If set, TLS is used for the upstream connections. See
// [reverseproxy.TLSConfig].
//
// - [reverseproxy.TLSConfig.ServerName] is set to the host of the upstream address by default, and must be configured explicitly for unix sockets and addresses without a host unless [reverseproxy.TLSConfig.InsecureSkipVerify] is set. Placeholders are supported.
// - [reverseproxy.TLSConfig.HandshakeTimeout] is set to [Module.DialTimeout] if not specified.
TLS *reverseproxy.TLSConfig `json:"tls,omitempty"`
// contains filtered or unexported fields
}
Module proxies binary WebSocket connections to an upstream TCP or unix socket (optionally using TLS), passing non-WebSocket requests to the next handler.
WebSocket requests using an HTTP/2 or HTTP/3 Extended CONNECT are supported in addition to HTTP/1.1 upgrades (but clients currently won't use it in practice).
func (Module) CaddyModule ¶
func (Module) CaddyModule() caddy.ModuleInfo
func (*Module) UnmarshalCaddyfile ¶
type Stats ¶
Stats contains the number of bytes transferred in each direction.
func Proxy ¶
Proxy copies binary messages to and from ws and upstream until either side closes, ctx is cancelled, the client stops responding to pings within the ping timeout (if pings are enabled), or no data is transferred and the idle timeout is reached.
Both connections are closed before returning. Errors from Close on ws and upstream are ignored.
The returned error is nil if either side ended the connection normally, otherwise ErrIdleTimeout, ErrPingTimeout, context.Cause, or the error which caused the connection to end.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
caddy-websockify
command
Command caddy-websockify is a Caddy build which runs the websockify command directly.
|
Command caddy-websockify is a Caddy build which runs the websockify command directly. |