Documentation
¶
Overview ¶
Package ws is the WebSocket transport for mqttv5. It is a sibling submodule with its own go.mod so the core mqttv5 module stays stdlib-only. Wire it up via DialFunc:
cli, _ := mqttv5.New(
mqttv5.WithBroker("wss://broker.example/mqtt"),
mqttv5.WithDialFunc(ws.DialFunc(ws.DialOpts{
TLSConfig: tlsCfg,
})),
)
Both ws:// and wss:// are first-class. Like mqtts://, wss:// without a DialOpts.TLSConfig verifies the broker against the system roots with the URL's host as the server name.
External dependency: github.com/gobwas/ws — chosen for its low per-frame allocation profile, in line with mqttv5's allocation-free decoder.
Index ¶
- Constants
- Variables
- func Dial(ctx context.Context, brokerURL *url.URL, opts DialOpts) (transport.Conn, error)
- func DialFunc(opts DialOpts) transport.DialFunc
- type Conn
- func (c *Conn) Close() error
- func (c *Conn) LocalAddr() net.Addr
- func (c *Conn) Read(p []byte) (int, error)
- func (c *Conn) RemoteAddr() net.Addr
- func (c *Conn) SetDeadline(t time.Time) error
- func (c *Conn) SetReadDeadline(t time.Time) error
- func (c *Conn) SetWriteDeadline(t time.Time) error
- func (c *Conn) Write(p []byte) (int, error)
- type DialOpts
Constants ¶
const DefaultCloseFrameTimeout = time.Second
DefaultCloseFrameTimeout bounds the Close frame Conn.Close sends, when DialOpts.CloseFrameTimeout is zero.
const DefaultHandshakeTimeout = 10 * time.Second
DefaultHandshakeTimeout is the WebSocket upgrade-handshake budget used when DialOpts.HandshakeTimeout is zero.
Variables ¶
var ErrTextFrame = errors.New("mqttv5/transport/ws: text frame from the broker")
ErrTextFrame reports a WebSocket text frame from the broker. MQTT travels only in binary frames; any other data frame must close the connection [MQTT-6.0.0-1].
Functions ¶
func Dial ¶
Dial performs the WebSocket upgrade against brokerURL and returns a transport.Conn that frames every Read/Write as a single MQTT control packet (per MQTT-over-WS §6 — "single WebSocket data frame"). Prefer DialFunc when wiring into mqttv5.WithDialFunc; call Dial directly when you need a one-shot upgrade outside the client.
func DialFunc ¶
DialFunc binds opts and returns a transport.DialFunc that's directly compatible with mqttv5.WithDialFunc — typical usage:
mqttv5.WithDialFunc(ws.DialFunc(ws.DialOpts{TLSConfig: tlsCfg}))
Equivalent to writing the closure by hand around Dial; provided because the closure form reads poorly when several broker options are stacked together.
Types ¶
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn wraps a websocket connection so every Write is one WebSocket frame holding one MQTT control packet. It is created by Dial; callers should treat the returned transport.Conn as opaque.
func (*Conn) Close ¶
Close closes the underlying connection, first sending a Close frame when no write is in progress, within DialOpts.CloseFrameTimeout. A write in progress is not waited for: it may be stalled behind a peer that stopped reading, and closing the connection is what ends it.
func (*Conn) Read ¶
Read returns the next available bytes from the MQTT byte stream. Each underlying WebSocket binary frame is one MQTT control packet, but the MQTT decoder reads field-at-a-time — so Read may be called many times per frame. Between frames it answers Ping with Pong and Close with Close (then reports io.EOF); a text frame is an error.
func (*Conn) RemoteAddr ¶
RemoteAddr forwards to the underlying connection.
func (*Conn) SetDeadline ¶
SetDeadline forwards to the underlying connection.
func (*Conn) SetReadDeadline ¶
SetReadDeadline forwards to the underlying connection.
func (*Conn) SetWriteDeadline ¶
SetWriteDeadline forwards to the underlying connection.
type DialOpts ¶
type DialOpts struct {
// TLSConfig configures TLS for wss:// URLs and is ignored for
// ws://. Nil verifies against the system roots; an empty ServerName
// is filled in from the URL's host.
TLSConfig *tls.Config
// HTTPHeaders are added to the HTTP upgrade request — useful for
// auth tokens, custom routing headers, etc.
HTTPHeaders http.Header
// Subprotocols sent in Sec-WebSocket-Protocol. Defaults to
// []string{"mqtt"} per MQTT v5 §6.
Subprotocols []string
// HandshakeTimeout bounds the upgrade handshake. Defaults to
// DefaultHandshakeTimeout.
HandshakeTimeout time.Duration
// CloseFrameTimeout bounds the Close frame sent when the connection
// is closed. Defaults to DefaultCloseFrameTimeout.
CloseFrameTimeout time.Duration
// NetDial overrides the underlying TCP dial. Use this to inject a
// SOCKS / HTTP CONNECT proxy or a custom net.Dialer.
NetDial func(ctx context.Context, network, addr string) (net.Conn, error)
}
DialOpts customises a Dial call. Zero value is valid.